@open-athena/auth

Named share links, Google sign-in, email codes, and an access log for gated dashboards.

Reusable auth layers for apps with the "public site, gate a slice" shape: a backend kernel (HMAC sessions, DB-backed grant tokens, Google/OIDC sign-in, emailed codes), a framework-free client, unstyled React primitives, and Vue useWhoami / AuthGate wrappers.

Mint a link, say who it's for, set how many times and how long it works, and see what they looked at. Google or an emailed code for people the policy admits; request-access for everyone else.

Scope note: this is gating — sessions, sign-in, share links, request-access, audit — not a general-purpose auth framework (no password store, no OAuth server, no RBAC engine).

Try it: auth.oa.dev

Get a throwaway sandbox, mint a named link, open it, watch its access log fill in — then revoke it and watch the session die on its next request. No account needed.

Status

Pre-1.0 and moving: the backend kernel, Google and email-code sign-in, request-access, the HTTP route surface, the React primitives, and the analytics work (beacon, bot filtering, retention rollup) are implemented, tested, and deployed at auth.oa.dev. See specs/adoption.md for who uses it.

• demo/ — the deployed app: mint a link, watch its access log, revoke it and see the session die
• specs/adoption.md — which repos should adopt this, in what order, and what each costs
• specs/overview.md — layer split, packaging
• specs/share-links-and-audit.md — share-link config, request-access, access log, analytics

Layout

core/ is runtime-agnostic — Web Crypto and a SQL-shaped store interface, nothing else. Everything platform-specific is an adapter, kept as a file boundary rather than an abstraction layer (no plugin registry, no DI):

src/core/       sessions, tokens, grants, policy, requests, email codes, audit, routes — no CF, no Node
src/adapters/   d1 (stores, audit sink & queries), oidc (Google + any issuer), resend (mail),
                r2 (avatar bytes), google-directory (group → allowlist sync)
src/client/     typed fetch client, URL/exchange/identity/image helpers — no framework imports
src/react/      useWhoami / AuthGate / SignInPanel / WhoamiChip / Avatar / AvatarField / disclosure — unstyled;
                GrantsPanel / UserMenu — optional ui.css
src/vue/        useWhoami / AuthGate — Vue-only composable and slotted gate, unstyled
src/session-log/  optional, time-boxed user-action logging (routes; D1 store in adapters/,
                logger in client/session-log/, admin UI in react/session-log/)
src/provider/   optional OIDC provider over a gate, for a sign-in broker (D1 store in adapters/)
src/testing/    in-memory stores, so adopters can test a gated route without a DB
migrations/     the schema (one baseline file pre-1.0; see below)
scripts/        provisioning (Google client, Resend domain, group-sync SA) and d1-rebaseline
demo/           a working app on Pages + Functions + D1

Peers of adapters/d1 are any SQLite (Turso, better-sqlite3) or Postgres; every current consumer is on Cloudflare, so D1 is the only store adapter until a non-CF consumer appears.

Framework-Free Client

Vue/Slidev, vanilla JavaScript and React can all call the same HTTP surface without importing React:

import { AuthClientError, createAuthClient, shareUrl } from '@open-athena/auth/client'

const auth = createAuthClient() // defaults to /api/auth; fetch is injectable
const { grant, token } = await auth.grants.mint({ scopes: ['reports'], name: 'Board packet' })
const link = shareUrl(token, 'https://app.example/reports/3?tab=costs#notes')
await auth.grants.update(grant.id, { note: 'Shared with the board' })
await auth.grants.revoke(grant.id)

grants also supports list({ active? }), disable, enable, rotate(id, { endSessions? }) and activity; the client has whoami(), logout() and log({ grant?, limit? }). Successful values retain the route's JSON envelope. Non-2xx responses throw AuthClientError with status and body (JSON when available, otherwise text/null); network and malformed-success-JSON errors stay distinct. Unlike useWhoami, client.whoami() throws on 401 rather than returning null. Allowlist wrappers and migrating the existing React hooks/admin UI onto this client are deferred.

displayName, hasScope, hasKeyParam, exchangeKeyParam and downscaleImage are available from /client, along with the shared wire types. Existing /react helper imports still work. Importing /client is SSR-safe; browser-only helpers need browser APIs when called, and shareUrl needs an explicit absolute target outside the browser. It preserves the target's other query parameters and hash, replacing an existing key. The emitted module graph is checked during pnpm build for external dependencies, including React/Vue.

The backend root import and platform adapters remain separate from /client. React hooks/components live under /react; Vue wrappers live under /vue. Vanilla apps need neither framework.

Share-Link Admin and User Menu

Each has headless logic that owns state and API calls, and reference components built only on it, so an app can use them as they are, restyle them, or replace them.

This is the beginning of the README. Read the rest at the original. Read the full README ↗