toddstack-accounts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Todd Everett Griffin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# toddstack-accounts (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![JSR](https://jsr.io/badges/@todd/toddstack-accounts)](https://jsr.io/@todd/toddstack-accounts)
+[![npm](https://img.shields.io/npm/v/toddstack-accounts)](https://www.npmjs.com/package/toddstack-accounts)
+
+Client for Todd Griffin's Projects accounts (`accounts.toddgriffin.me`): what a project's backend needs to sign people
+in, check tokens, verify webhooks, and use friends. The TypeScript half of `toddstack-accounts`, with the same features
+as the [Rust crate](../../rust/toddstack_accounts/README.md). Part of
+[toddstack](https://github.com/goddtriffin/toddstack).
+
+Web Platform APIs only (`fetch`, WebCrypto): Node 20+, Deno, Bun. No dependencies.
+
+```sh
+npx jsr add @todd/toddstack-accounts   # or: deno add jsr:@todd/toddstack-accounts
+npm install toddstack-accounts
+```
+
+Web apps use the **backend-for-frontend** pattern: your server is the OIDC client and keeps the tokens; the browser only
+ever holds your own session cookie. Native apps sign in through the system browser as public clients and send their
+access token to your server, which checks it with `accounts.verifyAccessToken`.
+
+## Sign in (two routes)
+
+```ts
+import { Accounts, toddgriffin } from "toddstack-accounts"; // or "@todd/toddstack-accounts"
+
+const accounts = new Accounts(toddgriffin(
+  "boggledygook",
+  process.env.ACCOUNTS_CLIENT_SECRET!, // from your env (1Password)
+  "https://www.boggledygook.com/auth/callback", // registered exactly
+));
+
+// GET /auth/login?return=/play
+const { url, pending } = await accounts.startLogin({
+  scopes: ["profile", "offline_access", "friends"],
+  returnTo: "/play",
+});
+// Keep `pending` server-side or in an encrypted HttpOnly cookie, then redirect to `url`.
+
+// GET /auth/callback?code=..&state=..&iss=..
+const signedIn = await accounts.finishLogin(pending, new URL(request.url).search);
+// signedIn.claims.sub is the person's permanent id: key everything on it.
+// Keep signedIn.tokens (refreshToken rotates: always store the new one).
+// Redirect to signedIn.returnTo (already checked to be a path on your site).
+```
+
+`finishLogin` checks `state` and `iss`, exchanges the code with PKCE, and verifies the ID token (ES256 signature against
+the published keys, issuer, audience, expiry, nonce).
+
+| Call                                        | What                                                                                         |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `startLogin({ prompt, loginHint, maxAge })` | `prompt: "login"` forces a fresh sign-in, `"none"` checks silently, `"create"` opens sign-up |
+| `accounts.refresh(token)`                   | New tokens; an `AccountsError` with `kind: "token_refused"` means sign in again              |
+| `accounts.revoke(token)`                    | On sign-out                                                                                  |
+| `accounts.verifyAccessToken(token)`         | For your API: checks `typ`, issuer, audience = your client id, expiry                        |
+| `accounts.verifyIdToken(token, nonce?)`     | ID token checks on their own                                                                 |
+| `accounts.userinfo(token)`                  | The profile JSON                                                                             |
+| `safeReturnTo(path)`                        | Keeps redirects on your site                                                                 |
+
+Errors are `AccountsError` with a `kind`: `state_mismatch`, `authorization` (the person cancelled, or `login_required`
+after `prompt: "none"`), `missing_code`, `token_refused`, `invalid_token`, `invalid_webhook`, `api` (with `status`),
+`http`, `config`.
+
+## Webhooks
+
+```ts
+import { verifyWebhook, WEBHOOK_HEADER } from "toddstack-accounts";
+
+const event = await verifyWebhook(webhookSecret, request.headers.get(WEBHOOK_HEADER), await request.text());
+switch (event.type) {
+  case "user.deleted": /* delete or anonymize event.data.sub's rows */
+    break;
+  case "user.updated": /* refresh cached username / picture */
+    break;
+  case "user.signed_out":
+  case "user.suspended":
+  case "grant.revoked": /* end event.data.sub's sessions */
+    break;
+}
+```
+
+Your sessions are your own: accounts can't end them. On `user.signed_out`, `user.suspended` and `grant.revoked`, delete
+every session you hold for `event.data.sub`. Their refresh tokens are already revoked.
+
+Verify the raw body before parsing. Signatures older than 5 minutes are refused. Deliveries retry, so ignore repeated
+`event.id`s.
+
+## Friends and events
+
+```ts
+const friends = accounts.friends(accessToken);
+const list = await friends.list(); // only friends who also use your app
+await friends.requestByUsername("alex");
+await friends.postEvent({
+  kind: "beat_your_score",
+  title: "Alex beat your high score",
+  body: "4,200 points in today's daily",
+  collapseKey: "daily-2026-11-14",
+}); // needs scope friends:events
+```
+
+Also `requests`, `requestByCode`, `accept`, `decline`, `cancel`, `remove`, `block`, `unblock`, `inbox(limit)`,
+`markRead`, `mutes`, `mute(kind)` (`ALL_KINDS` mutes everything), `unmute`.
+
+## Tests
+
+`new Accounts(config, { keys, fetch })` pins the signing keys and swaps `fetch`, so tests run with no network.
+
+## Publishing
+
+`deno.jsonc` (JSR) and `package.json` (npm) carry the same version as `version.ts`; a test checks. The npm package is
+the `tsc` build of the same sources (`tsconfig.npm.json`, output in `dist/`, not committed).

package/dist/encoding.d.ts

@@ -0,0 +1,12 @@
+/** UTF-8 bytes of `text`. */
+export declare function utf8(text: string): Uint8Array<ArrayBuffer>;
+/** Text of UTF-8 `bytes`. */
+export declare function fromUtf8(bytes: Uint8Array): string;
+/** Unpadded base64url of `bytes`. */
+export declare function base64url(bytes: Uint8Array): string;
+/** Bytes of base64url (padded or not) or standard base64 `text`. Throws on malformed input. */
+export declare function fromBase64(text: string): Uint8Array<ArrayBuffer>;
+/** `n` cryptographically random bytes. */
+export declare function randomBytes(n: number): Uint8Array<ArrayBuffer>;
+/** A random base64url token with `n` bytes of entropy. */
+export declare function randomToken(n?: number): string;

package/dist/encoding.js

@@ -0,0 +1,36 @@
+// Base64url, UTF-8 and random helpers on Web Platform APIs only (Node 20+, Deno, Bun, browsers).
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** UTF-8 bytes of `text`. */
+export function utf8(text) {
+    return encoder.encode(text);
+}
+/** Text of UTF-8 `bytes`. */
+export function fromUtf8(bytes) {
+    return decoder.decode(bytes);
+}
+/** Unpadded base64url of `bytes`. */
+export function base64url(bytes) {
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** Bytes of base64url (padded or not) or standard base64 `text`. Throws on malformed input. */
+export function fromBase64(text) {
+    const standard = text.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = standard + "=".repeat((4 - (standard.length % 4)) % 4);
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** `n` cryptographically random bytes. */
+export function randomBytes(n) {
+    return crypto.getRandomValues(new Uint8Array(n));
+}
+/** A random base64url token with `n` bytes of entropy. */
+export function randomToken(n = 32) {
+    return base64url(randomBytes(n));
+}

package/dist/error.d.ts

@@ -0,0 +1,38 @@
+/** What went wrong. */
+export type AccountsErrorKind = 
+/** The callback's `state` (or `iss`) doesn't match the pending sign-in: forged or stale. Start over. */
+"state_mismatch"
+/** The service sent the person back with an OAuth error (`access_denied`, `login_required` for `prompt=none`). */
+ | "authorization"
+/** The callback had no `code`. */
+ | "missing_code"
+/** The token endpoint refused (`invalid_grant`: expired, reused or revoked). Sign in again. */
+ | "token_refused"
+/** A token failed verification (signature, issuer, audience, expiry, nonce). */
+ | "invalid_token"
+/** A webhook failed verification. */
+ | "invalid_webhook"
+/** The API refused a call; `status` and the API's message are set. */
+ | "api"
+/** The request itself failed (network, timeout). */
+ | "http"
+/** Bad configuration. */
+ | "config";
+/** An error from this library. Switch on `kind`. */
+export declare class AccountsError extends Error {
+    /** What went wrong. */
+    readonly kind: AccountsErrorKind;
+    /** The OAuth error code, for `authorization` and `token_refused`. */
+    readonly error?: string;
+    /** The OAuth `error_description`, when the service sent one. */
+    readonly description?: string;
+    /** The HTTP status, for `api`. */
+    readonly status?: number;
+    /** Builds an error; `details` carries the OAuth code, description, HTTP status or cause. */
+    constructor(kind: AccountsErrorKind, message: string, details?: {
+        error?: string;
+        description?: string;
+        status?: number;
+        cause?: unknown;
+    });
+}

package/dist/error.js

@@ -0,0 +1,22 @@
+// Everything that can go wrong talking to the accounts service. One error class with a `kind`, the
+// TypeScript shape of the Rust crate's `Error` enum.
+/** An error from this library. Switch on `kind`. */
+export class AccountsError extends Error {
+    /** What went wrong. */
+    kind;
+    /** The OAuth error code, for `authorization` and `token_refused`. */
+    error;
+    /** The OAuth `error_description`, when the service sent one. */
+    description;
+    /** The HTTP status, for `api`. */
+    status;
+    /** Builds an error; `details` carries the OAuth code, description, HTTP status or cause. */
+    constructor(kind, message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = "AccountsError";
+        this.kind = kind;
+        this.error = details.error;
+        this.description = details.description;
+        this.status = details.status;
+    }
+}

package/dist/friends.d.ts

@@ -0,0 +1,99 @@
+import type { Accounts } from "./tokens.ts";
+/** A friend, request or blocked person as your app sees them. */
+export interface Person {
+    /** Their permanent id. */
+    sub: string;
+    /** Their unique username. */
+    username: string;
+    /** Display name, if set. */
+    name: string | null;
+    /** Profile picture URL, if set. */
+    picture: string | null;
+    /** When the friendship, request or block started (RFC 3339). */
+    since: string;
+}
+/** Pending friend requests. */
+export interface Requests {
+    /** Requests sent to the person. */
+    incoming: Person[];
+    /** Requests the person sent. */
+    outgoing: Person[];
+}
+/** What sending a request did: `accepted` means they had already asked, so you're friends now. */
+export type Sent = "requested" | "accepted" | "already_friends";
+/** An event for friends' inboxes ("Alex beat your high score"). */
+export interface FriendEvent {
+    /** 1-40 of `a-z`, `0-9`, `_`. People can mute a kind. */
+    kind: string;
+    /** 1-80 characters. */
+    title: string;
+    /** Up to 280 characters. */
+    body?: string;
+    /** An `https` link into your app. */
+    url?: string;
+    /** A newer event with the same key replaces an unread older one. */
+    collapseKey?: string;
+    /** Only these friends (`sub`s); all friends who use your app if omitted. */
+    recipients?: string[];
+}
+/** One item in the person's inbox from your app. */
+export interface InboxItem {
+    /** Item id (for `markRead`). */
+    id: string;
+    /** The friend it came from (`sub`), null for system items. */
+    from: string | null;
+    /** That friend's username. */
+    fromUsername: string | null;
+    /** The event kind. */
+    kind: string;
+    /** The headline. */
+    title: string;
+    /** The text (may be empty). */
+    body: string;
+    /** An `https` link into your app. */
+    url: string | null;
+    /** When it was posted (RFC 3339). */
+    createdAt: string;
+    /** When the person read it (RFC 3339), null if unread. */
+    readAt: string | null;
+}
+/** Mutes every event kind from your app. */
+export declare const ALL_KINDS = "*";
+/** The API for one person (their access token). Get one from `accounts.friends(token)`. */
+export declare class Friends {
+    #private;
+    /** The API for the person whose access token this is. */
+    constructor(accounts: Accounts, accessToken: string);
+    /** Friends who also use your app. */
+    list(): Promise<Person[]>;
+    /** Incoming and outgoing requests. */
+    requests(): Promise<Requests>;
+    /** Sends a request by exact username. Not found also covers blocks and privacy settings. */
+    requestByUsername(username: string): Promise<Sent>;
+    /** Sends a request by friend code (works even when the person only takes requests from people with their code). */
+    requestByCode(friendCode: string): Promise<Sent>;
+    /** Accepts `sub`'s request. */
+    accept(sub: string): Promise<void>;
+    /** Declines `sub`'s request. */
+    decline(sub: string): Promise<void>;
+    /** Cancels a request you sent. */
+    cancel(sub: string): Promise<void>;
+    /** Ends a friendship. */
+    remove(sub: string): Promise<void>;
+    /** Blocks: ends the friendship and requests, and stops events both ways. */
+    block(sub: string): Promise<void>;
+    /** Undoes `block`. */
+    unblock(sub: string): Promise<void>;
+    /** Posts an event; returns how many friends' inboxes it reached. Rate limit: 60 per person per hour per app. */
+    postEvent(event: FriendEvent): Promise<number>;
+    /** The person's inbox items from your app, newest first. */
+    inbox(limit: number): Promise<InboxItem[]>;
+    /** Marks an inbox item read. */
+    markRead(id: string): Promise<void>;
+    /** The event kinds from your app the person has muted (`ALL_KINDS` means all of them). */
+    mutes(): Promise<string[]>;
+    /** Stops friends' events of `kind` from your app reaching the person (`ALL_KINDS` for every kind). */
+    mute(kind: string): Promise<void>;
+    /** Undoes `mute`. */
+    unmute(kind: string): Promise<void>;
+}

package/dist/friends.js

@@ -0,0 +1,110 @@
+// The friends, events and inbox API, called with a person's access token (scopes `friends`, and
+// `friends:events` to post events). Your app only ever sees friends who also use your app.
+import { AccountsError } from "./error.js";
+/** Mutes every event kind from your app. */
+export const ALL_KINDS = "*";
+function field(value, name) {
+    const out = value?.[name];
+    if (out === undefined) {
+        throw new AccountsError("api", `accounts API returned 200: missing field \`${name}\``, { status: 200 });
+    }
+    return out;
+}
+/** The API for one person (their access token). Get one from `accounts.friends(token)`. */
+export class Friends {
+    #accounts;
+    #token;
+    #base;
+    /** The API for the person whose access token this is. */
+    constructor(accounts, accessToken) {
+        this.#accounts = accounts;
+        this.#token = accessToken;
+        this.#base = `${accounts.config.issuer.replace(/\/oidc$/, "")}/api/v1`;
+    }
+    #call(method, path, body) {
+        return this.#accounts.call(this.#token, method, `${this.#base}${path}`, body);
+    }
+    /** Friends who also use your app. */
+    async list() {
+        return field(await this.#call("GET", "/friends"), "friends");
+    }
+    /** Incoming and outgoing requests. */
+    async requests() {
+        const value = await this.#call("GET", "/friends/requests");
+        return { incoming: field(value, "incoming"), outgoing: field(value, "outgoing") };
+    }
+    /** Sends a request by exact username. Not found also covers blocks and privacy settings. */
+    async requestByUsername(username) {
+        return field(await this.#call("POST", "/friends/requests", { username }), "result");
+    }
+    /** Sends a request by friend code (works even when the person only takes requests from people with their code). */
+    async requestByCode(friendCode) {
+        return field(await this.#call("POST", "/friends/requests", { friend_code: friendCode }), "result");
+    }
+    /** Accepts `sub`'s request. */
+    async accept(sub) {
+        await this.#call("POST", `/friends/requests/${encodeURIComponent(sub)}/accept`);
+    }
+    /** Declines `sub`'s request. */
+    async decline(sub) {
+        await this.#call("POST", `/friends/requests/${encodeURIComponent(sub)}/decline`);
+    }
+    /** Cancels a request you sent. */
+    async cancel(sub) {
+        await this.#call("DELETE", `/friends/requests/${encodeURIComponent(sub)}`);
+    }
+    /** Ends a friendship. */
+    async remove(sub) {
+        await this.#call("DELETE", `/friends/${encodeURIComponent(sub)}`);
+    }
+    /** Blocks: ends the friendship and requests, and stops events both ways. */
+    async block(sub) {
+        await this.#call("POST", "/blocks", { sub });
+    }
+    /** Undoes `block`. */
+    async unblock(sub) {
+        await this.#call("DELETE", `/blocks/${encodeURIComponent(sub)}`);
+    }
+    /** Posts an event; returns how many friends' inboxes it reached. Rate limit: 60 per person per hour per app. */
+    async postEvent(event) {
+        const wire = { kind: event.kind, title: event.title, body: event.body ?? "" };
+        if (event.url !== undefined)
+            wire.url = event.url;
+        if (event.collapseKey !== undefined)
+            wire.collapse_key = event.collapseKey;
+        if (event.recipients !== undefined)
+            wire.recipients = event.recipients;
+        return field(await this.#call("POST", "/events", wire), "delivered");
+    }
+    /** The person's inbox items from your app, newest first. */
+    async inbox(limit) {
+        const items = field(await this.#call("GET", `/inbox?limit=${Math.floor(limit)}`), "items");
+        return items.map((i) => ({
+            id: i.id,
+            from: i.from,
+            fromUsername: i.from_username,
+            kind: i.kind,
+            title: i.title,
+            body: i.body,
+            url: i.url,
+            createdAt: i.created_at,
+            readAt: i.read_at,
+        }));
+    }
+    /** Marks an inbox item read. */
+    async markRead(id) {
+        await this.#call("POST", `/inbox/${encodeURIComponent(id)}/read`);
+    }
+    /** The event kinds from your app the person has muted (`ALL_KINDS` means all of them). */
+    async mutes() {
+        return field(await this.#call("GET", "/mutes"), "mutes");
+    }
+    /** Stops friends' events of `kind` from your app reaching the person (`ALL_KINDS` for every kind). */
+    async mute(kind) {
+        await this.#call("PUT", `/mutes/${encodeURIComponent(kind)}`);
+    }
+    /** Undoes `mute`. */
+    async unmute(kind) {
+        await this.#call("DELETE", `/mutes/${encodeURIComponent(kind)}`);
+    }
+}

package/dist/jwks.d.ts

@@ -0,0 +1,21 @@
+/** One key from a JWKS document. */
+export interface Jwk extends JsonWebKey {
+    /** Key id (the JWT header's `kid`). */
+    kid?: string;
+}
+/** A JWKS document. */
+export interface JwkSet {
+    /** The keys. */
+    keys: Jwk[];
+}
+/** A key cache: remote (fetched from the issuer) or pinned (tests, offline use; never refetched). */
+export declare class Keys {
+    #private;
+    private constructor();
+    /** Keys fetched from `url`. */
+    static remote(url: string, fetcher: typeof fetch): Keys;
+    /** Fixed keys, never fetched. */
+    static pinned(set: JwkSet): Keys;
+    /** The key for `kid`, fetching the key set if it's missing or stale. */
+    get(kid: string): Promise<CryptoKey>;
+}

package/dist/jwks.js

@@ -0,0 +1,68 @@
+// The accounts service's published signing keys, cached. An unknown `kid` triggers one refetch (keys rotate),
+// at most once a minute.
+import { AccountsError } from "./error.js";
+const REFRESH_EVERY_MS = 3600_000;
+const MIN_REFETCH_MS = 60_000;
+/** A key cache: remote (fetched from the issuer) or pinned (tests, offline use; never refetched). */
+export class Keys {
+    #url;
+    #fetch;
+    #cache;
+    #imported = new Map();
+    constructor(url, set, fetcher) {
+        this.#url = url;
+        this.#fetch = fetcher;
+        this.#cache = set ? { at: Date.now(), set } : null;
+    }
+    /** Keys fetched from `url`. */
+    static remote(url, fetcher) {
+        return new Keys(url, null, fetcher);
+    }
+    /** Fixed keys, never fetched. */
+    static pinned(set) {
+        return new Keys(null, set, fetch);
+    }
+    #lookup(kid) {
+        const jwk = this.#cache?.set.keys.find((k) => k.kid === kid && k.kty === "EC" && k.crv === "P-256");
+        if (!jwk)
+            return null;
+        const id = JSON.stringify([jwk.kid, jwk.x, jwk.y]);
+        let key = this.#imported.get(id);
+        if (!key) {
+            const { kid: _kid, alg: _alg, use: _use, key_ops: _ops, ...material } = jwk;
+            key = crypto.subtle.importKey("jwk", material, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+            this.#imported.set(id, key);
+        }
+        return key;
+    }
+    /** The key for `kid`, fetching the key set if it's missing or stale. */
+    async get(kid) {
+        const age = this.#cache ? Date.now() - this.#cache.at : null;
+        const stale = age === null || age > REFRESH_EVERY_MS;
+        if (!stale || this.#url === null) {
+            const key = this.#lookup(kid);
+            if (key)
+                return await key;
+            if (this.#url === null)
+                throw new AccountsError("invalid_token", "token rejected: unknown signing key");
+        }
+        // Unknown kid on a fresh cache: refetch, but not more than once a minute.
+        if (stale || (age !== null && age > MIN_REFETCH_MS)) {
+            let response;
+            try {
+                response = await this.#fetch(this.#url, { signal: AbortSignal.timeout(10_000) });
+            }
+            catch (cause) {
+                throw new AccountsError("http", `http: ${cause}`, { cause });
+            }
+            if (!response.ok) {
+                throw new AccountsError("http", `http: JWKS fetch returned ${response.status}`, { status: response.status });
+            }
+            this.#cache = { at: Date.now(), set: (await response.json()) };
+        }
+        const key = this.#lookup(kid);
+        if (!key)
+            throw new AccountsError("invalid_token", "token rejected: unknown signing key");
+        return await key;
+    }
+}

package/dist/login.d.ts

@@ -0,0 +1,51 @@
+import type { Config } from "./tokens.ts";
+/** What to remember between `startLogin` and the callback. Plain JSON: safe to serialize. */
+export interface PendingLogin {
+    /** Echoed back in the callback; must match. */
+    state: string;
+    /** Must come back inside the ID token. */
+    nonce: string;
+    /** The PKCE verifier. Never send it to the browser. */
+    verifier: string;
+    /** Where to go after sign-in: a path on your site, already checked. */
+    returnTo: string | null;
+}
+/** Options beyond the defaults. */
+export interface LoginOptions {
+    /** Scopes to ask for; `openid` is always added. */
+    scopes?: string[];
+    /** A path on your site to return to; anything off-site is dropped. */
+    returnTo?: string | null;
+    /** `login` forces a fresh sign-in; `none` checks silently (no page shown); `create` opens the sign-up page. */
+    prompt?: "login" | "none" | "create";
+    /** Prefills the email field. */
+    loginHint?: string;
+    /** Require a sign-in within this many seconds. */
+    maxAge?: number;
+}
+/** A started sign-in: redirect to `url`, keep `pending`. */
+export interface StartedLogin {
+    /** Where to send the person. */
+    url: string;
+    /** What to keep until the callback. */
+    pending: PendingLogin;
+}
+/** The PKCE S256 challenge for `verifier`. */
+export declare function pkceChallenge(verifier: string): Promise<string>;
+/** Starts a sign-in. */
+export declare function startLogin(config: Config, options?: LoginOptions): Promise<StartedLogin>;
+/** What the callback query says. */
+export interface Callback {
+    /** The authorization code. */
+    code: string | null;
+    /** The `state` to match against the pending sign-in. */
+    state: string | null;
+    /** The issuer (RFC 9207), when sent. */
+    iss: string | null;
+    /** An OAuth error code, when the sign-in failed. */
+    error: string | null;
+    /** The error's description. */
+    errorDescription: string | null;
+}
+/** Reads a callback query string (with or without `?`) or `URLSearchParams`. */
+export declare function parseCallback(query: string | URLSearchParams): Callback;

package/dist/login.js

@@ -0,0 +1,53 @@
+// The sign-in round trip, as two steps around a redirect.
+//
+// 1. `startLogin` builds the URL to send the person to and a `PendingLogin`. Keep the pending login
+//    server-side (or in an encrypted, HttpOnly cookie): it holds the PKCE verifier, which must never reach the
+//    browser's JS.
+// 2. When the person comes back to your redirect URI, pass the pending login and the callback query to
+//    `Accounts.finishLogin`.
+import { base64url, randomToken, utf8 } from "./encoding.js";
+import { safeReturnTo } from "./return-to.js";
+/** The PKCE S256 challenge for `verifier`. */
+export async function pkceChallenge(verifier) {
+    return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", utf8(verifier))));
+}
+/** Starts a sign-in. */
+export async function startLogin(config, options = {}) {
+    const pending = {
+        state: randomToken(),
+        nonce: randomToken(),
+        verifier: randomToken(),
+        returnTo: options.returnTo ? safeReturnTo(options.returnTo) : null,
+    };
+    const scopes = [...(options.scopes ?? [])];
+    if (!scopes.includes("openid"))
+        scopes.unshift("openid");
+    const url = new URL(`${config.issuer}/auth`);
+    const q = url.searchParams;
+    q.append("client_id", config.clientId);
+    q.append("redirect_uri", config.redirectUri);
+    q.append("response_type", "code");
+    q.append("scope", scopes.join(" "));
+    q.append("state", pending.state);
+    q.append("nonce", pending.nonce);
+    q.append("code_challenge", await pkceChallenge(pending.verifier));
+    q.append("code_challenge_method", "S256");
+    if (options.prompt)
+        q.append("prompt", options.prompt);
+    if (options.loginHint)
+        q.append("login_hint", options.loginHint);
+    if (options.maxAge !== undefined)
+        q.append("max_age", String(options.maxAge));
+    return { url: url.toString(), pending };
+}
+/** Reads a callback query string (with or without `?`) or `URLSearchParams`. */
+export function parseCallback(query) {
+    const q = typeof query === "string" ? new URLSearchParams(query.replace(/^\?/, "")) : query;
+    return {
+        code: q.get("code"),
+        state: q.get("state"),
+        iss: q.get("iss"),
+        error: q.get("error"),
+        errorDescription: q.get("error_description"),
+    };
+}

package/dist/mod.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Client for Todd Griffin's Projects accounts (`accounts.toddgriffin.me`): what a project's backend needs to
+ * sign people in, check tokens, verify webhooks, and use friends. The TypeScript half of `toddstack-accounts`
+ * (same features as the Rust crate). Web Platform APIs only: runs on Node 20+, Deno and Bun.
+ *
+ * ```ts
+ * import { Accounts, toddgriffin } from "@todd/toddstack-accounts";
+ *
+ * const accounts = new Accounts(toddgriffin("boggledygook", clientSecret, "https://www.boggledygook.com/auth/callback"));
+ *
+ * // GET /auth/login: redirect to `url`; keep `pending` server-side or in an encrypted HttpOnly cookie.
+ * const { url, pending } = await accounts.startLogin({ scopes: ["profile", "offline_access"], returnTo: "/play" });
+ *
+ * // GET /auth/callback?code=..&state=..
+ * const signedIn = await accounts.finishLogin(pending, new URL(request.url).search);
+ * console.log(signedIn.claims.sub);
+ * ```
+ *
+ * @module
+ */
+export { AccountsError, type AccountsErrorKind } from "./error.ts";
+export { ALL_KINDS, type FriendEvent, Friends, type InboxItem, type Person, type Requests, type Sent, } from "./friends.ts";
+export type { Jwk, JwkSet } from "./jwks.ts";
+export { type Callback, type LoginOptions, parseCallback, type PendingLogin, pkceChallenge, type StartedLogin, startLogin, } from "./login.ts";
+export { safeReturnTo } from "./return-to.ts";
+export { type AccessClaims, Accounts, type AccountsOptions, type Config, hasScope, type IdClaims, ISSUER, type SignedIn, toddgriffin, type TokenSet, } from "./tokens.ts";
+export { VERSION } from "./version.ts";
+export { verifyWebhook, WEBHOOK_HEADER, WEBHOOK_TOLERANCE_SECONDS, type WebhookEvent } from "./webhook.ts";

package/dist/mod.js

@@ -0,0 +1,27 @@
+/**
+ * Client for Todd Griffin's Projects accounts (`accounts.toddgriffin.me`): what a project's backend needs to
+ * sign people in, check tokens, verify webhooks, and use friends. The TypeScript half of `toddstack-accounts`
+ * (same features as the Rust crate). Web Platform APIs only: runs on Node 20+, Deno and Bun.
+ *
+ * ```ts
+ * import { Accounts, toddgriffin } from "@todd/toddstack-accounts";
+ *
+ * const accounts = new Accounts(toddgriffin("boggledygook", clientSecret, "https://www.boggledygook.com/auth/callback"));
+ *
+ * // GET /auth/login: redirect to `url`; keep `pending` server-side or in an encrypted HttpOnly cookie.
+ * const { url, pending } = await accounts.startLogin({ scopes: ["profile", "offline_access"], returnTo: "/play" });
+ *
+ * // GET /auth/callback?code=..&state=..
+ * const signedIn = await accounts.finishLogin(pending, new URL(request.url).search);
+ * console.log(signedIn.claims.sub);
+ * ```
+ *
+ * @module
+ */
+export { AccountsError } from "./error.js";
+export { ALL_KINDS, Friends, } from "./friends.js";
+export { parseCallback, pkceChallenge, startLogin, } from "./login.js";
+export { safeReturnTo } from "./return-to.js";
+export { Accounts, hasScope, ISSUER, toddgriffin, } from "./tokens.js";
+export { VERSION } from "./version.js";
+export { verifyWebhook, WEBHOOK_HEADER, WEBHOOK_TOLERANCE_SECONDS } from "./webhook.js";

package/dist/return-to.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `target` if it is a path on this site, else null. Refuses `//host`, `/\host`, absolute URLs, control
+ * characters and anything over 1000 bytes: the shapes open-redirect attacks use.
+ */
+export declare function safeReturnTo(target: string): string | null;

package/dist/return-to.js

@@ -0,0 +1,14 @@
+// Post-sign-in redirects that can't leave your site.
+/**
+ * `target` if it is a path on this site, else null. Refuses `//host`, `/\host`, absolute URLs, control
+ * characters and anything over 1000 bytes: the shapes open-redirect attacks use.
+ */
+export function safeReturnTo(target) {
+    const ok = target.startsWith("/") &&
+        !target.startsWith("//") &&
+        !target.startsWith("/\\") &&
+        // deno-lint-ignore no-control-regex
+        !/[\u0000-\u001f\u007f-\u009f\\]/.test(target) &&
+        new TextEncoder().encode(target).length < 1000;
+    return ok ? target : null;
+}

package/dist/tokens.d.ts

@@ -0,0 +1,123 @@
+import { Friends } from "./friends.ts";
+import { type JwkSet } from "./jwks.ts";
+import { type LoginOptions, type PendingLogin, type StartedLogin } from "./login.ts";
+/** The production issuer. */
+export declare const ISSUER = "https://accounts.toddgriffin.me/oidc";
+/** Your app's registration with the accounts service. */
+export interface Config {
+    /** `https://accounts.toddgriffin.me/oidc` in production. */
+    issuer: string;
+    /** Your client id, as registered. */
+    clientId: string;
+    /** Null for public clients (native and desktop apps). */
+    clientSecret: string | null;
+    /** Exactly as registered. */
+    redirectUri: string;
+}
+/** A config for the production accounts service. */
+export declare function toddgriffin(clientId: string, clientSecret: string | null, redirectUri: string): Config;
+/** The token endpoint's answer. */
+export interface TokenSet {
+    /** For calls to the accounts API (10 minutes). */
+    accessToken: string;
+    /** The signed ID token. */
+    idToken: string;
+    /**
+     * Present when `offline_access` was granted. Rotates on every refresh: always store the new one, and never
+     * reuse an old one (that revokes the whole family).
+     */
+    refreshToken: string | null;
+    /** Access token lifetime, seconds. */
+    expiresIn: number;
+    /** The scopes granted, space-separated. */
+    scope: string;
+}
+/** Verified ID token claims (standard claim names). */
+export interface IdClaims {
+    /** The person's permanent id. Key everything on this. */
+    sub: string;
+    /** Their username (scope `profile`). */
+    username?: string;
+    /** Display name (scope `profile`). */
+    name?: string;
+    /** Picture URL (scope `profile`). */
+    picture?: string;
+    /** Email (scope `email`). */
+    email?: string;
+    /** Whether the email was verified. */
+    email_verified?: boolean;
+    /** When they last proved who they are (Unix seconds). */
+    auth_time?: number;
+    /** How: `pwd`, `otp`, `hwk` (passkey), `fed` (social), `mfa`, ... */
+    amr: string[];
+    /** The nonce from the sign-in request. */
+    nonce?: string;
+    /** Any other claim. */
+    [claim: string]: unknown;
+}
+/** Verified access token claims (RFC 9068). */
+export interface AccessClaims {
+    /** The person's permanent id. */
+    sub: string;
+    /** The app the token was issued to (always your client id once verified). */
+    client_id: string;
+    /** The scopes granted, space-separated; see `hasScope`. */
+    scope: string;
+    /** Expiry, Unix seconds. */
+    exp: number;
+    /** Any other claim. */
+    [claim: string]: unknown;
+}
+/** Whether `claims` grant `scope`. */
+export declare function hasScope(claims: AccessClaims, scope: string): boolean;
+/** A finished sign-in. */
+export interface SignedIn {
+    /** Verified ID token claims. */
+    claims: IdClaims;
+    /** The tokens; store the refresh token if you need it. */
+    tokens: TokenSet;
+    /** The checked path from `startLogin`, if any. */
+    returnTo: string | null;
+}
+/** Construction options. */
+export interface AccountsOptions {
+    /** Verify tokens against these keys and never fetch them: for tests, or a service that pins keys. */
+    keys?: JwkSet;
+    /** The `fetch` to use (defaults to the global one). */
+    fetch?: typeof fetch;
+}
+/** The client. Create one per process and share it; it caches the signing keys. */
+export declare class Accounts {
+    #private;
+    /** This client's registration. */
+    readonly config: Config;
+    /** A client for `config`. Throws `config` if the client id is empty. */
+    constructor(config: Config, options?: AccountsOptions);
+    /** Starts a sign-in: redirect the person to `url` and keep `pending` (see `startLogin`). */
+    startLogin(options?: LoginOptions): Promise<StartedLogin>;
+    /**
+     * Completes a sign-in from the callback's query: checks `state` and `iss`, exchanges the code, and verifies
+     * the ID token (including the nonce).
+     */
+    finishLogin(pending: PendingLogin, callbackQuery: string | URLSearchParams): Promise<SignedIn>;
+    /**
+     * Swaps a refresh token for new tokens. Store the new refresh token. A `token_refused` error
+     * (`invalid_grant`) means it's expired, reused or the person removed your app: sign them in again.
+     */
+    refresh(refreshToken: string): Promise<TokenSet>;
+    /** Revokes a refresh token (and its whole family), e.g. on sign-out. */
+    revoke(refreshToken: string): Promise<void>;
+    /** Verifies an ID token: signature, ES256, issuer, audience (your client id), expiry, and the nonce if given. */
+    verifyIdToken(token: string, nonce?: string): Promise<IdClaims>;
+    /**
+     * Verifies an access token sent to *your* API (for example by your native app): signature, `typ: at+jwt`,
+     * issuer, audience = your client id, expiry. Tokens issued to other apps are refused.
+     */
+    verifyAccessToken(token: string): Promise<AccessClaims>;
+    /** The person's profile from `/me`. */
+    userinfo(accessToken: string): Promise<Record<string, unknown>>;
+    /** The friends, events and inbox API for one person. */
+    friends(accessToken: string): Friends;
+    /** One authenticated JSON call; errors carry the API's message. Used by `Friends`. */
+    call(token: string, method: string, url: string, body?: unknown): Promise<unknown>;
+}

package/dist/tokens.js

@@ -0,0 +1,232 @@
+// Tokens: exchanging codes, refreshing, revoking, and verifying ID and access tokens.
+import { fromBase64, fromUtf8, utf8 } from "./encoding.js";
+import { AccountsError } from "./error.js";
+import { Friends } from "./friends.js";
+import { Keys } from "./jwks.js";
+import { parseCallback, startLogin } from "./login.js";
+import { VERSION } from "./version.js";
+/** The production issuer. */
+export const ISSUER = "https://accounts.toddgriffin.me/oidc";
+/** A config for the production accounts service. */
+export function toddgriffin(clientId, clientSecret, redirectUri) {
+    return { issuer: ISSUER, clientId, clientSecret, redirectUri };
+}
+/** Whether `claims` grant `scope`. */
+export function hasScope(claims, scope) {
+    return claims.scope.split(" ").includes(scope);
+}
+/** Allowed clock skew for `exp`, seconds. */
+const LEEWAY_SECONDS = 30;
+/** The client. Create one per process and share it; it caches the signing keys. */
+export class Accounts {
+    /** This client's registration. */
+    config;
+    #fetch;
+    #keys;
+    /** A client for `config`. Throws `config` if the client id is empty. */
+    constructor(config, options = {}) {
+        if (!config.clientId)
+            throw new AccountsError("config", "configuration: clientId is required");
+        this.config = { ...config, issuer: config.issuer.replace(/\/+$/, "") };
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#keys = options.keys ? Keys.pinned(options.keys) : Keys.remote(`${this.config.issuer}/jwks`, this.#fetch);
+    }
+    /** Starts a sign-in: redirect the person to `url` and keep `pending` (see `startLogin`). */
+    startLogin(options = {}) {
+        return startLogin(this.config, options);
+    }
+    /**
+     * Completes a sign-in from the callback's query: checks `state` and `iss`, exchanges the code, and verifies
+     * the ID token (including the nonce).
+     */
+    async finishLogin(pending, callbackQuery) {
+        const callback = parseCallback(callbackQuery);
+        const mismatch = "the sign-in callback doesn't match this browser's pending sign-in";
+        if (callback.state !== pending.state)
+            throw new AccountsError("state_mismatch", mismatch);
+        if (callback.iss !== null && callback.iss !== this.config.issuer) {
+            throw new AccountsError("state_mismatch", mismatch);
+        }
+        if (callback.error !== null) {
+            throw new AccountsError("authorization", `sign-in failed: ${callback.error}`, {
+                error: callback.error,
+                description: callback.errorDescription ?? undefined,
+            });
+        }
+        if (callback.code === null)
+            throw new AccountsError("missing_code", "the callback has no code");
+        const tokens = await this.#tokenRequest({
+            grant_type: "authorization_code",
+            code: callback.code,
+            redirect_uri: this.config.redirectUri,
+            code_verifier: pending.verifier,
+        });
+        const claims = await this.verifyIdToken(tokens.idToken, pending.nonce);
+        return { claims, tokens, returnTo: pending.returnTo };
+    }
+    /**
+     * Swaps a refresh token for new tokens. Store the new refresh token. A `token_refused` error
+     * (`invalid_grant`) means it's expired, reused or the person removed your app: sign them in again.
+     */
+    refresh(refreshToken) {
+        return this.#tokenRequest({ grant_type: "refresh_token", refresh_token: refreshToken });
+    }
+    /** Revokes a refresh token (and its whole family), e.g. on sign-out. */
+    async revoke(refreshToken) {
+        const response = await this.#post(`${this.config.issuer}/token/revocation`, {
+            token: refreshToken,
+            token_type_hint: "refresh_token",
+        });
+        if (!response.ok) {
+            throw new AccountsError("api", `accounts API returned ${response.status}`, { status: response.status });
+        }
+    }
+    /** Verifies an ID token: signature, ES256, issuer, audience (your client id), expiry, and the nonce if given. */
+    async verifyIdToken(token, nonce) {
+        const claims = await this.#decode(token, null);
+        if (nonce !== undefined && claims.nonce !== nonce) {
+            throw new AccountsError("invalid_token", "token rejected: nonce mismatch");
+        }
+        return { ...claims, amr: Array.isArray(claims.amr) ? claims.amr : [] };
+    }
+    /**
+     * Verifies an access token sent to *your* API (for example by your native app): signature, `typ: at+jwt`,
+     * issuer, audience = your client id, expiry. Tokens issued to other apps are refused.
+     */
+    async verifyAccessToken(token) {
+        return (await this.#decode(token, "at+jwt"));
+    }
+    /** The person's profile from `/me`. */
+    userinfo(accessToken) {
+        return this.call(accessToken, "GET", `${this.config.issuer}/me`);
+    }
+    /** The friends, events and inbox API for one person. */
+    friends(accessToken) {
+        return new Friends(this, accessToken);
+    }
+    /** One authenticated JSON call; errors carry the API's message. Used by `Friends`. */
+    async call(token, method, url, body) {
+        const headers = {
+            authorization: `Bearer ${token}`,
+            "user-agent": `toddstack-accounts/${VERSION}`,
+        };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const response = await this.#send(url, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            let message = text;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed?.error === "string")
+                    message = parsed.error;
+            }
+            catch { /* not JSON: keep the text */ }
+            throw new AccountsError("api", `accounts API returned ${response.status}: ${message}`, {
+                status: response.status,
+            });
+        }
+        if (text === "")
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new AccountsError("api", `accounts API returned ${response.status}: ${cause}`, {
+                status: response.status,
+                cause,
+            });
+        }
+    }
+    async #send(url, init) {
+        try {
+            return await this.#fetch(url, { ...init, signal: AbortSignal.timeout(10_000) });
+        }
+        catch (cause) {
+            throw new AccountsError("http", `http: ${cause}`, { cause });
+        }
+    }
+    /** A form POST with client authentication (Basic for confidential clients, `client_id` for public ones). */
+    #post(url, params) {
+        const form = new URLSearchParams(params);
+        const headers = {
+            "content-type": "application/x-www-form-urlencoded",
+            "user-agent": `toddstack-accounts/${VERSION}`,
+        };
+        if (this.config.clientSecret !== null) {
+            // RFC 6749 2.3.1: form-encode both parts before Basic.
+            const enc = (s) => new URLSearchParams({ v: s }).toString().slice(2);
+            headers.authorization = `Basic ${btoa(`${enc(this.config.clientId)}:${enc(this.config.clientSecret)}`)}`;
+        }
+        else {
+            form.append("client_id", this.config.clientId);
+        }
+        return this.#send(url, { method: "POST", headers, body: form.toString() });
+    }
+    async #tokenRequest(params) {
+        const response = await this.#post(`${this.config.issuer}/token`, params);
+        if (!response.ok) {
+            let error = `http_${response.status}`;
+            let description;
+            try {
+                const body = await response.json();
+                if (typeof body?.error === "string") {
+                    error = body.error;
+                    description = typeof body.error_description === "string" ? body.error_description : undefined;
+                }
+            }
+            catch { /* not JSON */ }
+            throw new AccountsError("token_refused", `token request refused: ${error}`, { error, description });
+        }
+        const raw = (await response.json());
+        return {
+            accessToken: raw.access_token,
+            idToken: raw.id_token,
+            refreshToken: raw.refresh_token ?? null,
+            expiresIn: raw.expires_in,
+            scope: raw.scope,
+        };
+    }
+    async #decode(token, typ) {
+        const reject = (why) => new AccountsError("invalid_token", `token rejected: ${why}`);
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            throw reject("malformed token");
+        let header;
+        let claims;
+        let signature;
+        try {
+            header = JSON.parse(fromUtf8(fromBase64(parts[0])));
+            claims = JSON.parse(fromUtf8(fromBase64(parts[1])));
+            signature = fromBase64(parts[2]);
+        }
+        catch {
+            throw reject("malformed token");
+        }
+        if (header.alg !== "ES256")
+            throw reject("unexpected algorithm");
+        if (typ !== null && header.typ?.toLowerCase() !== typ)
+            throw reject("not an access token");
+        if (!header.kid)
+            throw reject("no kid");
+        const key = await this.#keys.get(header.kid);
+        const ok = await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, signature, utf8(`${parts[0]}.${parts[1]}`));
+        if (!ok)
+            throw reject("InvalidSignature");
+        if (claims.iss !== this.config.issuer)
+            throw reject("InvalidIssuer");
+        const aud = claims.aud;
+        if (!(aud === this.config.clientId || (Array.isArray(aud) && aud.includes(this.config.clientId)))) {
+            throw reject("InvalidAudience");
+        }
+        if (typeof claims.exp !== "number")
+            throw reject("Missing required claim: exp");
+        if (claims.exp < Math.floor(Date.now() / 1000) - LEEWAY_SECONDS)
+            throw reject("ExpiredSignature");
+        return claims;
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version; kept equal to `deno.jsonc` and `package.json` (a test checks). */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This package's version; kept equal to `deno.jsonc` and `package.json` (a test checks). */
+export const VERSION = "0.1.0";

package/dist/webhook.d.ts

@@ -0,0 +1,23 @@
+/** The header name. */
+export declare const WEBHOOK_HEADER = "X-Accounts-Signature";
+/** How old a signature may be, seconds. */
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+/** A verified event. */
+export interface WebhookEvent {
+    /** Unique per event; repeated on retries. */
+    id: string;
+    /** `user.updated`, `user.deleted`, `user.suspended`, `user.reactivated`, `user.signed_out`, or `grant.revoked`. */
+    type: string;
+    /** Unix seconds. */
+    createdAt: number;
+    /** Always has `sub` (the person the event is about); `user.updated` adds the fields that changed. */
+    data: {
+        sub?: string;
+        [field: string]: unknown;
+    };
+}
+/**
+ * Checks the signature and age, then parses the event. `body` is the raw request body (text or bytes);
+ * `now` is the current Unix time in seconds (a parameter so tests can fix it).
+ */
+export declare function verifyWebhook(secret: string | Uint8Array, signatureHeader: string | null | undefined, body: string | Uint8Array, now?: number): Promise<WebhookEvent>;

package/dist/webhook.js

@@ -0,0 +1,63 @@
+// Verifying webhooks from the accounts service.
+//
+// Each delivery is a POST with JSON and `X-Accounts-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of
+// "<t>.<raw body>">` under your app's webhook secret. Verify against the raw body, before parsing. Deliveries
+// can repeat (retries); use the event `id` to ignore duplicates.
+import { utf8 } from "./encoding.js";
+import { AccountsError } from "./error.js";
+/** The header name. */
+export const WEBHOOK_HEADER = "X-Accounts-Signature";
+/** How old a signature may be, seconds. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+function reject(why) {
+    return new AccountsError("invalid_webhook", `webhook rejected: ${why}`);
+}
+function fromHex(hex) {
+    if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex))
+        return null;
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+/**
+ * Checks the signature and age, then parses the event. `body` is the raw request body (text or bytes);
+ * `now` is the current Unix time in seconds (a parameter so tests can fix it).
+ */
+export async function verifyWebhook(secret, signatureHeader, body, now = Math.floor(Date.now() / 1000)) {
+    let t = null;
+    let v1 = null;
+    for (const part of (signatureHeader ?? "").split(",")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        const [k, value] = [part.slice(0, eq).trim(), part.slice(eq + 1).trim()];
+        if (k === "t")
+            t = /^-?\d+$/.test(value) ? Number(value) : null;
+        if (k === "v1")
+            v1 = fromHex(value);
+    }
+    if (t === null || v1 === null)
+        throw reject("malformed signature header");
+    if (Math.abs(now - t) > WEBHOOK_TOLERANCE_SECONDS)
+        throw reject("signature too old (or from the future)");
+    const bodyBytes = typeof body === "string" ? utf8(body) : body;
+    const signed = new Uint8Array([...utf8(`${t}.`), ...bodyBytes]);
+    const keyBytes = typeof secret === "string" ? utf8(secret) : new Uint8Array(secret);
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    // WebCrypto's verify compares in constant time.
+    if (!(await crypto.subtle.verify("HMAC", key, v1, signed)))
+        throw reject("signature mismatch");
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(bodyBytes));
+    }
+    catch {
+        throw reject("body is not an event");
+    }
+    if (typeof raw?.id !== "string" || typeof raw.type !== "string" || typeof raw.created_at !== "number" ||
+        raw.data === undefined) {
+        throw reject("body is not an event");
+    }
+    return { id: raw.id, type: raw.type, createdAt: raw.created_at, data: raw.data };
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "toddstack-accounts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Client for Todd Griffin's Projects accounts: OIDC sign-in, token checks, signed webhooks, friends and events.",
+  "license": "MIT",
+  "author": "Todd Everett Griffin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goddtriffin/toddstack.git",
+    "directory": "typescript/accounts"
+  },
+  "homepage": "https://github.com/goddtriffin/toddstack/tree/main/typescript/accounts",
+  "keywords": ["oidc", "accounts", "friends", "toddstack"],
+  "type": "module",
+  "exports": { ".": { "types": "./dist/mod.d.ts", "default": "./dist/mod.js" } },
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": { "node": ">=20" }
+}