@mccaskie-labs/workbench-supabase 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mccaskie-labs/workbench-supabase
 
+## 0.3.0
+
+- `createSessions({ url, publishableKey, secret })`: app sign-in by typed emailed code with the session held by the server (authentication standard §4, §6, §10). `sendCode`, `verifyCode`, `read`, `signOut`, and a pending-sign-in cookie that grants nothing. The session is one AES-GCM sealed `__Host-session` cookie (Secure, HttpOnly, SameSite=Lax) with four dials: idle on a private device (14 days), on a shared one (30 minutes), an absolute cap (30 days, never moved by a refresh) and a freshness window (15 minutes). The access token is refreshed by the server and never reaches page script. Sign-out clears the cookie first, with every attribute, then ends this session only at Supabase.
+- `limitKey(kind, value)`: a keyed hash for rate-limit keys, so a counter never holds an address or an IP.
+- `safeReturnPath(next)`, `sameOrigin(request)`, `normaliseEmail`, `normaliseCode`, `readCookie`.
+
+## 0.2.0
+
+- `plainError(error, { appName })`: raw Postgres and PostgREST wording (permission denied, row-level security, missing relation, PGRST codes and so on) becomes one plain line naming the app, and the full message is logged. The app's own words pass unchanged. From Imprint's `plain-error.ts` (sign-in kit, 11 November 2026).
+- `plainAuthError(error, { appName })`: a plain line for each common Supabase Auth error code. None says whether an account exists for an address.
+
 ## 0.1.0
 
 - First version (step 4.11): `supabaseConfig`, `createBrowserClient`, `createServerClient`, `createUserClient`, `createServiceClient` (logs its reason once per isolate), `WorkbenchSupabaseError`, and the CLI's `check:migrations`, `check:prod-schema` and `prod-schema-sql` (`docs/spec.md` §3).

package/README.md

@@ -22,10 +22,39 @@ const admin = createServiceClient({ url: cfg.url, secretKey: workerSecret(env, '
 | `createServerClient({ ...cfg, cookies })` | On the server, as the signed-in user from the request's cookies. `cookies` is `{ getAll, setAll }` |
 | `createUserClient({ ...cfg, accessToken })` | As the caller, with the token they sent (audit F7). No session is stored or refreshed |
 | `createServiceClient({ url, secretKey, reason })` | The `sb_secret_` key: **bypasses RLS**. `reason` (one line) is logged once per isolate: `[workbench-supabase] service client (bypasses RLS): <reason>`. Refused in a browser and for a publishable key |
+| `plainError(error, { appName, log? })` | The message to show a person: the app's own words unchanged, or for raw Postgres or PostgREST wording ("permission denied for function …", RLS, missing relation, `PGRST116`) one plain line, "Something went wrong on <app>'s side …". The full message is logged |
+| `plainAuthError(error, { appName, log? })` | A plain line for a Supabase Auth error by its `code` (`otp_expired`, `invalid_credentials`, rate limits, `weak_password` …). None says whether an account exists; an unknown code gets the plain line and is logged |
 | `WorkbenchSupabaseError` | A client built wrongly: `code` is `invalid_config` or `forbidden`. Never holds a key, URL or token |
 
 Every client takes an optional `fetch`, for tests against a fake Supabase.
 
+## Sign-in and sessions
+
+App sign-in by a typed emailed code (no link, no password reset), with the session held by the Worker. The browser never talks to Supabase Auth and never sees the access token (Robert's authentication standard §4).
+
+```ts
+import { createSessions, safeReturnPath, sameOrigin } from '@mccaskie-labs/workbench-supabase'
+
+const sessions = createSessions({ url, publishableKey, secret: env.SESSION_SECRET }) // once per isolate
+await sessions.sendCode(email)                                   // same answer whether or not the account exists
+const r = await sessions.verifyCode(email, code, { keep: true }) // { ok, user, cookie } or { ok: false, code } for plainAuthError
+const s = await sessions.read(request)                           // none | signed_in | ended | unavailable
+if (s.state === 'signed_in') createUserClient({ url, publishableKey, accessToken: s.accessToken })
+```
+
+| Export | What it does |
+| --- | --- |
+| `createSessions(cfg)` | `sendCode`, `verifyCode`, `read`, `signOut`, `rememberSignIn` / `pendingSignIn` / `clearSignIn`, `clearSession`, `limitKey`. `secret` is `SESSION_SECRET` (Control: `cf_worker_secret_put source=generate:32`) |
+| `SESSION_DEFAULTS` | Idle 14 days (private device), 30 minutes (shared: "keep me signed in" unticked), absolute cap 30 days, fresh 15 minutes. Change with `timers`; the shared idle can only be shorter |
+| `safeReturnPath(next, fallback)` | `next` when it is a path on this site, else `fallback` |
+| `sameOrigin(request)` | The request's Origin (or Referer) is its own origin. Check it on every write |
+
+Cookies: `__Host-session` holds the sealed tokens and timers; `__Host-signin` holds which address has a code outstanding, for an hour, and grants nothing. Both are `Secure; HttpOnly; SameSite=Lax; Path=/`, sealed with AES-GCM under a key derived from `SESSION_SECRET` with the cookie's name bound in, so one can't stand in for the other. Replacing `SESSION_SECRET` signs everybody out.
+
+`read` refreshes the access token a minute before it expires; a refresh never moves the absolute cap or the freshness window. When `read` or `verifyCode` returns a `cookie`, set it on the response. When Supabase can't be reached, a still-valid token keeps working and an expired one reads as `unavailable`: say so, and keep everything that doesn't need an account working.
+
+What it doesn't do, so the app must: rate limiting. Supabase sees every call coming from Cloudflare, not from the person, so its own per-IP limits don't protect a six-digit code. Limit `sendCode` and `verifyCode` per IP and per address with `limitKey` (the project template uses Workers rate limiting). Accepted, recorded: the cookie is the session, so a copy taken before sign-out keeps working until its access token expires (at most an hour) or its refresh token is used after sign-out; and replacing `SESSION_SECRET` signs everybody out (no key rotation yet).
+
 ## Worker secrets
 
 Control writes them with `cf_worker_secret_put`, from the Worker's own database (`<id>-staging` Worker: `<id>-staging`; `<id>` Worker: `<id>-production`). Nobody types a value.

package/dist/index.d.ts

@@ -5,3 +5,5 @@ export { migrationProblems, type MigrationProblem } from "./migrations.ts";
 export { PRODUCTION_SCHEMA_SQL, createdBy, missingOnProduction, findUses, unusedAllows, parseProductionSchema, parseAllow, type ProductionSchema, type AllowEntry, type MissingName, type Use, } from "./prod-schema.ts";
 export { stringPieces, type StringPiece } from "./strings.ts";
 export type { SupabaseClient } from "@supabase/supabase-js";
+export { plainError, plainAuthError, plainServerError, isRawDbError, type PlainErrorOptions } from "./plain-error.ts";
+export { createSessions, normaliseEmail, normaliseCode, safeReturnPath, sameOrigin, readCookie, SESSION_COOKIE, SIGN_IN_COOKIE, SESSION_DEFAULTS, type Sessions, type SessionsConfig, type SessionTimers, type SessionRead, type SessionUser, type AuthFailure, } from "./sessions.ts";

package/dist/index.js

@@ -4,3 +4,5 @@ export { WorkbenchSupabaseError } from "./errors.js";
 export { migrationProblems } from "./migrations.js";
 export { PRODUCTION_SCHEMA_SQL, createdBy, missingOnProduction, findUses, unusedAllows, parseProductionSchema, parseAllow, } from "./prod-schema.js";
 export { stringPieces } from "./strings.js";
+export { plainError, plainAuthError, plainServerError, isRawDbError } from "./plain-error.js";
+export { createSessions, normaliseEmail, normaliseCode, safeReturnPath, sameOrigin, readCookie, SESSION_COOKIE, SIGN_IN_COOKIE, SESSION_DEFAULTS, } from "./sessions.js";

package/dist/plain-error.d.ts

@@ -0,0 +1,21 @@
+export interface PlainErrorOptions {
+    /** The app's name as people see it (brand.json `name`). */
+    appName: string;
+    /** Where the full message is logged. Defaults to console.error. */
+    log?: (line: string) => void;
+}
+/** True for wording from Postgres or PostgREST that a person shouldn't see. */
+export declare function isRawDbError(message: string): boolean;
+/** The line shown in place of a raw error. */
+export declare function plainServerError(appName: string): string;
+/**
+ * The message to show: as it is, or the plain line for a raw database error
+ * (logged in full). Takes a string, an Error or a Supabase/PostgREST error
+ * object; anything without a message is treated as raw.
+ */
+export declare function plainError(error: unknown, opts: PlainErrorOptions): string;
+/**
+ * A plain line for a Supabase Auth error, by its code. An unknown code (or
+ * none) gets the app's plain server line, and the error is logged in full.
+ */
+export declare function plainAuthError(error: unknown, opts: PlainErrorOptions): string;

package/dist/plain-error.js

@@ -0,0 +1,76 @@
+// Raw database and Auth errors never reach a person's screen. Carried across
+// from Imprint's apps/admin/lib/plain-error.ts (sign-in kit, agreed
+// 11 November 2026): a technical message is logged in full for us and
+// replaced with one plain line naming the app. The app's own refusals,
+// including its database functions' own words, pass unchanged.
+/** Postgres and PostgREST wording that only makes sense to a developer. */
+const RAW_DB = /permission denied for|violates (row-level security|foreign key|check|not-null|unique|exclusion)|duplicate key value|(relation|column|function|schema|type) "?[\w.]+(\([^)]*\))?"? does not exist|invalid input (syntax|value) for|syntax error at or near|could not serialize access|deadlock detected|null value in column|value too long for type|\bPGRST\d{3}\b|\bJWT\b|42501|23505|23503|42883|42P01/i;
+/** True for wording from Postgres or PostgREST that a person shouldn't see. */
+export function isRawDbError(message) {
+    return RAW_DB.test(message);
+}
+/** The line shown in place of a raw error. */
+export function plainServerError(appName) {
+    return `Something went wrong on ${appName}’s side. Try again, and if it happens again, tell ${appName} support.`;
+}
+function messageOf(error) {
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object" && typeof error.message === "string") {
+        return error.message;
+    }
+    return "";
+}
+/**
+ * The message to show: as it is, or the plain line for a raw database error
+ * (logged in full). Takes a string, an Error or a Supabase/PostgREST error
+ * object; anything without a message is treated as raw.
+ */
+export function plainError(error, opts) {
+    const message = messageOf(error);
+    if (message !== "" && !isRawDbError(message))
+        return message;
+    (opts.log ?? console.error)(`[error shown as plain] ${message || String(error)}`);
+    return plainServerError(opts.appName);
+}
+/**
+ * Supabase Auth error codes (`AuthError.code`) and the plain line for each.
+ * None says whether an account exists for an address, so a sign-in form
+ * can't be used to find out who has an account.
+ */
+const AUTH_LINES = {
+    invalid_credentials: "That email address and password don't match. Check them and try again.",
+    otp_expired: "That code has expired or was already used. Ask for a new one.",
+    otp_disabled: "Signing in with a code isn't turned on.",
+    over_email_send_rate_limit: "Too many emails were sent to this address. Wait a few minutes, then try again.",
+    over_request_rate_limit: "Too many tries. Wait a few minutes, then try again.",
+    over_sms_send_rate_limit: "Too many messages were sent. Wait a few minutes, then try again.",
+    weak_password: "Choose a longer password that's harder to guess.",
+    same_password: "Choose a password different from your current one.",
+    reauthentication_needed: "For your safety, confirm it's you first. We'll send you a code.",
+    reauthentication_not_valid: "That code isn't right or has expired. Ask for a new one.",
+    mfa_verification_failed: "That code isn't right. Check your authenticator app and try again.",
+    mfa_challenge_expired: "That took too long. Start signing in again.",
+    session_expired: "You've been signed out. Sign in again.",
+    session_not_found: "You've been signed out. Sign in again.",
+    refresh_token_not_found: "You've been signed out. Sign in again.",
+    user_banned: "This login can't be used. Contact support.",
+    signup_disabled: "New accounts can't be made here. Ask the person who runs it for an invite.",
+    // These would say an account exists: the same neutral line as a new sign-up.
+    email_exists: "Check your email for a code to carry on.",
+    user_already_exists: "Check your email for a code to carry on.",
+    // An address Supabase won't take, said without saying why.
+    email_address_invalid: "Check the email address and try again.",
+    email_address_not_authorized: "Check the email address and try again.",
+};
+/**
+ * A plain line for a Supabase Auth error, by its code. An unknown code (or
+ * none) gets the app's plain server line, and the error is logged in full.
+ */
+export function plainAuthError(error, opts) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    if (typeof code === "string" && Object.hasOwn(AUTH_LINES, code))
+        return AUTH_LINES[code];
+    (opts.log ?? console.error)(`[auth error shown as plain] ${typeof code === "string" ? `${code}: ` : ""}${messageOf(error) || String(error)}`);
+    return plainServerError(opts.appName);
+}

package/dist/sessions.d.ts

@@ -0,0 +1,120 @@
+type Fetch = typeof fetch;
+export declare const SESSION_COOKIE = "__Host-session";
+export declare const SIGN_IN_COOKIE = "__Host-signin";
+/** The four dials, in seconds. */
+export interface SessionTimers {
+    /** Signed out after this long without a request, on a private device. */
+    idlePrivate: number;
+    /** The same, when "keep me signed in" was left unticked. Shorter than idlePrivate. */
+    idleShared: number;
+    /** Signed out this long after the code was typed, however active. */
+    absolute: number;
+    /** `fresh` is true for this long after the code was typed. */
+    fresh: number;
+}
+/** Weeks with an absolute cap (§10): the defaults a project starts with. */
+export declare const SESSION_DEFAULTS: Readonly<SessionTimers>;
+export interface SessionUser {
+    id: string;
+    email: string;
+}
+/** A Supabase Auth refusal: its `code` is what plainAuthError reads. Never holds a token. */
+export interface AuthFailure {
+    ok: false;
+    /** Supabase's error_code, or ours: invalid_email, invalid_code, auth_unavailable, session_too_large. */
+    code: string;
+    status: number;
+}
+export type SessionRead = 
+/** No session cookie. */
+{
+    state: "none";
+}
+/** Signed in. `cookie` is set when the session changed (a refresh, or "last seen" moved): put it on the response. */
+ | {
+    state: "signed_in";
+    user: SessionUser;
+    accessToken: string;
+    fresh: boolean;
+    cookie?: string;
+}
+/** The session was there and has ended (idle, cap, refresh refused, or tampered): put `cookie` on the response to clear it. */
+ | {
+    state: "ended";
+    reason: "idle" | "absolute" | "refused" | "invalid";
+    cookie: string;
+}
+/** Supabase couldn't be reached to refresh it. Say so plainly; the cookie is kept. */
+ | {
+    state: "unavailable";
+};
+export interface SessionsConfig {
+    /** SUPABASE_URL */
+    url: string;
+    /** SUPABASE_PUBLISHABLE_KEY */
+    publishableKey: string;
+    /** SESSION_SECRET: at least 32 characters (Control writes 32 random bytes, base64url). */
+    secret: string;
+    /** Change a dial; each must stay positive, and idleShared no longer than idlePrivate. */
+    timers?: Partial<SessionTimers>;
+    /** For tests: a fake Supabase. */
+    fetch?: Fetch;
+    /** For tests: the clock, in seconds. */
+    now?: () => number;
+}
+/** The address as Supabase stores it (trimmed, lower case), or null when it isn't one. */
+export declare function normaliseEmail(input: unknown): string | null;
+/** Six to ten digits, as Supabase's Email OTP Length allows; spaces and dashes typed between them are dropped. */
+export declare function normaliseCode(input: unknown): string | null;
+/**
+ * Where to go after signing in: `next` when it is a path on this site, else
+ * `fallback` (§7: an unchecked return target is an open redirect). Refuses
+ * other hosts, scheme-relative `//host`, backslashes and control characters.
+ */
+export declare function safeReturnPath(next: unknown, fallback?: string): string;
+/**
+ * True when a state-changing request came from this site's own pages: its
+ * Origin (or, without one, its Referer) is the request's own origin. A
+ * cross-site form post never passes, whatever cookies it carries.
+ */
+export declare function sameOrigin(request: Request): boolean;
+/** The value of one cookie on a request, or null. */
+export declare function readCookie(request: Request, name: string): string | null;
+export interface Sessions {
+    /** Ask Supabase to email a sign-in code. Answers the same whether or not the address has an account (§8.1). */
+    sendCode(email: string, opts?: {
+        createUser?: boolean;
+    }): Promise<{
+        ok: true;
+    } | AuthFailure>;
+    /** Check a typed code; on success, the session cookie to set. `keep` false marks a shared device (§10.2). */
+    verifyCode(email: string, code: string, opts: {
+        keep: boolean;
+    }): Promise<{
+        ok: true;
+        user: SessionUser;
+        cookie: string;
+    } | AuthFailure>;
+    /** The request's session, refreshed if its access token is near expiry. */
+    read(request: Request): Promise<SessionRead>;
+    /** Clear our cookie first and unconditionally, then tell Supabase (§10.3). Returns the clearing cookie. */
+    signOut(request: Request): Promise<string>;
+    /** The clearing cookie for the session. */
+    clearSession(): string;
+    /** Remember which address has a code outstanding (grants nothing). */
+    rememberSignIn(email: string): Promise<string>;
+    /** The outstanding sign-in, or null. */
+    pendingSignIn(request: Request): Promise<{
+        email: string;
+        sent: number;
+    } | null>;
+    /** The clearing cookie for the pending sign-in. */
+    clearSignIn(): string;
+    /** A keyed hash for a rate-limit key, so the counter store never holds an address or an IP (§9). */
+    limitKey(kind: string, value: string): Promise<string>;
+    /** The dials in force. */
+    timers: Readonly<SessionTimers>;
+}
+/** Sign-in and sessions for one Worker env. Make it once per isolate. */
+export declare function createSessions(cfg: SessionsConfig): Sessions;
+export {};

package/dist/sessions.js

@@ -0,0 +1,399 @@
+// App sign-in for Workbench apps: typed emailed codes and a server-held
+// session (authentication standard §4, §6, §10, §12; sign-in thread,
+// 11 November 2026).
+//
+// The browser never talks to Supabase Auth. The app's own endpoints call
+// these functions, which call Supabase Auth's REST API with the publishable
+// key, and the session lives in one sealed cookie:
+//
+//   __Host-session   AES-GCM sealed: Supabase's access and refresh tokens,
+//                    the user's id and email, and four timestamps (session
+//                    start, last seen, last proof, access-token expiry)
+//   __Host-signin    AES-GCM sealed: which address has a code outstanding and
+//                    when it was sent. It grants nothing (§5.4): forging it
+//                    earns a pre-filled address of your own choosing.
+//
+// Both are host-prefixed, Secure, HttpOnly and SameSite=Lax, and each is
+// sealed with the cookie's own name as associated data, so one can't stand in
+// for the other. The access token never reaches page script.
+//
+// Four dials (§10.1): idle on a private device, a much shorter idle on a
+// shared one, an absolute cap counted from the code that started the session
+// (a token refresh never moves it), and a freshness window that says whether
+// the session proved itself recently (for disclosure, not access).
+//
+// The key comes from one Worker secret (SESSION_SECRET, Control writes it with
+// cf_worker_secret_put source=generate:32). Two keys are derived from it: one
+// seals cookies, the other hashes rate-limit keys so no address is ever stored.
+import { WorkbenchSupabaseError } from "./errors.js";
+export const SESSION_COOKIE = "__Host-session";
+export const SIGN_IN_COOKIE = "__Host-signin";
+/** Weeks with an absolute cap (§10): the defaults a project starts with. */
+export const SESSION_DEFAULTS = Object.freeze({
+    idlePrivate: 14 * 86_400,
+    idleShared: 30 * 60,
+    absolute: 30 * 86_400,
+    fresh: 15 * 60,
+});
+/** How long a pending sign-in (an address with a code outstanding) is remembered. */
+const PENDING_SECONDS = 60 * 60;
+/** The access token is refreshed this close to its expiry. */
+const REFRESH_EARLY = 60;
+/** "Last seen" is rewritten at most this often, so most requests set no cookie. */
+const SEEN_STEP = 5 * 60;
+/** How long one call to Supabase Auth may take: nothing, sign-out above all, waits on a hung Supabase. */
+const AUTH_TIMEOUT_MS = 5_000;
+/** Browsers drop a cookie over 4096 bytes without a word. */
+const COOKIE_LIMIT = 4000;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** The address as Supabase stores it (trimmed, lower case), or null when it isn't one. */
+export function normaliseEmail(input) {
+    if (typeof input !== "string")
+        return null;
+    const e = input.trim().toLowerCase();
+    if (e.length < 3 || e.length > 254 || !EMAIL.test(e))
+        return null;
+    return e;
+}
+/** Six to ten digits, as Supabase's Email OTP Length allows; spaces and dashes typed between them are dropped. */
+export function normaliseCode(input) {
+    if (typeof input !== "string")
+        return null;
+    const c = input.replace(/[\s-]/g, "");
+    return /^\d{6,10}$/.test(c) ? c : null;
+}
+/**
+ * Where to go after signing in: `next` when it is a path on this site, else
+ * `fallback` (§7: an unchecked return target is an open redirect). Refuses
+ * other hosts, scheme-relative `//host`, backslashes and control characters.
+ */
+export function safeReturnPath(next, fallback = "/") {
+    if (typeof next !== "string" || next.length === 0 || next.length > 2000)
+        return fallback;
+    if (!next.startsWith("/") || next.startsWith("//") || /[\\\u0000-\u001f\u007f]/.test(next))
+        return fallback;
+    try {
+        const u = new URL(next, "https://same.invalid");
+        if (u.origin !== "https://same.invalid")
+            return fallback;
+        const out = `${u.pathname}${u.search}${u.hash}`;
+        // Dot segments can normalise to a leading "//" (/.//evil.example), which a browser reads as another host.
+        if (out.startsWith("//") || out.includes("\\"))
+            return fallback;
+        return out;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * True when a state-changing request came from this site's own pages: its
+ * Origin (or, without one, its Referer) is the request's own origin. A
+ * cross-site form post never passes, whatever cookies it carries.
+ */
+export function sameOrigin(request) {
+    const own = new URL(request.url).origin;
+    const origin = request.headers.get("origin");
+    if (origin !== null)
+        return origin === own;
+    const referer = request.headers.get("referer");
+    if (referer === null)
+        return false;
+    try {
+        return new URL(referer).origin === own;
+    }
+    catch {
+        return false;
+    }
+}
+function checkTimers(t) {
+    for (const [k, v] of Object.entries(t)) {
+        if (!Number.isInteger(v) || v <= 0)
+            throw new WorkbenchSupabaseError("invalid_config", `Session timer ${k} must be a whole number of seconds above 0.`);
+    }
+    if (t.idleShared > t.idlePrivate)
+        throw new WorkbenchSupabaseError("invalid_config", "idleShared can only be shorter than idlePrivate (§10.2: the shared-device control only shortens).");
+    if (t.idleShared < 2 * SEEN_STEP)
+        throw new WorkbenchSupabaseError("invalid_config", `idleShared must be at least ${2 * SEEN_STEP} seconds: "last seen" moves every ${SEEN_STEP}.`);
+    if (t.idlePrivate > t.absolute)
+        throw new WorkbenchSupabaseError("invalid_config", "idlePrivate can't be longer than the absolute cap.");
+    return t;
+}
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+function b64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        return null;
+    try {
+        const b64 = s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "=");
+        return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+/** The value of one cookie on a request, or null. */
+export function readCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return null;
+    for (const part of header.split(";")) {
+        const i = part.indexOf("=");
+        if (i < 0)
+            continue;
+        if (part.slice(0, i).trim() === name)
+            return part.slice(i + 1).trim();
+    }
+    return null;
+}
+/** A host-prefixed cookie with every attribute, setting or clearing (§10.3: the clear needs them too). */
+function cookie(name, value, maxAge) {
+    return `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=${Math.max(0, Math.floor(maxAge))}`;
+}
+/** Sign-in and sessions for one Worker env. Make it once per isolate. */
+export function createSessions(cfg) {
+    if (typeof cfg.secret !== "string" || cfg.secret.length < 32) {
+        throw new WorkbenchSupabaseError("invalid_config", "SESSION_SECRET must be at least 32 characters (cf_worker_secret_put source=generate:32).");
+    }
+    if (typeof cfg.url !== "string" || !/^https?:\/\//.test(cfg.url))
+        throw new WorkbenchSupabaseError("invalid_config", "The Supabase URL is missing or invalid.");
+    if (typeof cfg.publishableKey !== "string" || !cfg.publishableKey.startsWith("sb_publishable_")) {
+        throw new WorkbenchSupabaseError("invalid_config", "Sign-in needs the sb_publishable_ key: never the secret key.");
+    }
+    const timers = checkTimers({ ...SESSION_DEFAULTS, ...(cfg.timers ?? {}) });
+    const base = cfg.url.replace(/\/+$/, "");
+    const doFetch = cfg.fetch ?? ((input, init) => fetch(input, init));
+    const now = cfg.now ?? (() => Math.floor(Date.now() / 1000));
+    let keysP = null;
+    const keys = () => (keysP ??= (async () => {
+        const raw = await crypto.subtle.importKey("raw", enc.encode(cfg.secret), "HKDF", false, ["deriveKey"]);
+        const hkdf = (info) => ({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: enc.encode(info) });
+        return {
+            seal: await crypto.subtle.deriveKey(hkdf("workbench-session-seal-v1"), raw, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]),
+            hash: await crypto.subtle.deriveKey(hkdf("workbench-session-limit-v1"), raw, { name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign"]),
+        };
+    })().catch((e) => {
+        keysP = null; // don't cache a failure for the isolate's life
+        throw e;
+    }));
+    async function seal(name, data) {
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: enc.encode(name) }, (await keys()).seal, enc.encode(JSON.stringify(data))));
+        const out = new Uint8Array(iv.length + ct.length);
+        out.set(iv);
+        out.set(ct, iv.length);
+        return b64url(out);
+    }
+    async function open(name, value) {
+        if (!value || value.length > COOKIE_LIMIT)
+            return null;
+        const bytes = unb64url(value);
+        if (!bytes || bytes.length < 12 + 16)
+            return null;
+        try {
+            const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: bytes.slice(0, 12), additionalData: enc.encode(name) }, (await keys()).seal, bytes.slice(12));
+            return JSON.parse(dec.decode(pt));
+        }
+        catch {
+            return null;
+        }
+    }
+    async function auth(path, body, bearer) {
+        let res;
+        try {
+            res = await doFetch(`${base}/auth/v1/${path}`, {
+                method: "POST",
+                headers: { apikey: cfg.publishableKey, "content-type": "application/json", ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) },
+                body: JSON.stringify(body ?? {}),
+                signal: AbortSignal.timeout(AUTH_TIMEOUT_MS),
+            });
+        }
+        catch {
+            return { ok: false, code: "auth_unavailable", status: 503 };
+        }
+        let json = null;
+        let text = "";
+        try {
+            text = await res.text();
+        }
+        catch {
+            return { ok: false, code: "auth_unavailable", status: 503 };
+        }
+        if (text) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = null;
+            }
+        }
+        if (res.ok)
+            return { ok: true, status: res.status, json };
+        const j = (json ?? {});
+        const code = typeof j.error_code === "string" ? j.error_code : typeof j.code === "string" ? j.code : res.status >= 500 ? "auth_unavailable" : "unknown";
+        return { ok: false, code, status: res.status };
+    }
+    function sessionCookie(s, value) {
+        const idle = s.shared ? timers.idleShared : timers.idlePrivate;
+        return cookie(SESSION_COOKIE, value, Math.min(idle, s.iat + timers.absolute - now()));
+    }
+    async function issue(s) {
+        const value = await seal(SESSION_COOKIE, s);
+        if (value.length > COOKIE_LIMIT) {
+            // A Supabase access token that has grown (large user_metadata) would be dropped by the browser without a word.
+            console.error(`[workbench-supabase] session cookie is ${value.length} bytes, over ${COOKIE_LIMIT}: keep user_metadata small`);
+            return { ok: false, code: "session_too_large", status: 500 };
+        }
+        return sessionCookie(s, value);
+    }
+    function tokens(json) {
+        const t = (json ?? {});
+        if (typeof t.access_token !== "string" || typeof t.refresh_token !== "string")
+            return null;
+        const id = t.user?.id;
+        const email = t.user?.email;
+        if (typeof id !== "string" || typeof email !== "string")
+            return null;
+        const exp = typeof t.expires_at === "number" ? t.expires_at : now() + (typeof t.expires_in === "number" ? t.expires_in : 3600);
+        return { at: t.access_token, rt: t.refresh_token, exp, user: { id, email } };
+    }
+    const clearSession = () => cookie(SESSION_COOKIE, "", 0);
+    const clearSignIn = () => cookie(SIGN_IN_COOKIE, "", 0);
+    return {
+        timers,
+        clearSession,
+        clearSignIn,
+        async sendCode(email, opts = {}) {
+            const e = normaliseEmail(email);
+            if (!e)
+                return { ok: false, code: "invalid_email", status: 400 };
+            const r = await auth("otp", { email: e, create_user: opts.createUser ?? true });
+            if (!r.ok) {
+                // With sign-ups off, Supabase refuses an unknown address: answer as if a code went out (§8.1).
+                // A real account's resend cooldown would then tell the two apart, so it reads the same too.
+                // (Timing still differs with sign-ups off, since only a real account gets an email: §8.2's residual.)
+                const hidden = ["otp_disabled", "signup_disabled", "user_not_found", ...(opts.createUser === false ? ["over_email_send_rate_limit"] : [])];
+                if (hidden.includes(r.code)) {
+                    console.info(JSON.stringify({ event: "sign_in_code_not_sent", reason: r.code }));
+                    return { ok: true };
+                }
+                return r;
+            }
+            return { ok: true };
+        },
+        async verifyCode(email, code, { keep }) {
+            const e = normaliseEmail(email);
+            if (!e)
+                return { ok: false, code: "invalid_email", status: 400 };
+            const c = normaliseCode(code);
+            if (!c)
+                return { ok: false, code: "invalid_code", status: 400 };
+            const r = await auth("verify", { type: "email", email: e, token: c });
+            if (!r.ok)
+                return r;
+            const t = tokens(r.json);
+            if (!t)
+                return { ok: false, code: "auth_unavailable", status: 502 };
+            const at = now();
+            const s = { v: 1, uid: t.user.id, email: t.user.email, at: t.at, rt: t.rt, exp: t.exp, iat: at, seen: at, auth: at, shared: !keep };
+            const set = await issue(s);
+            if (typeof set !== "string")
+                return set;
+            return { ok: true, user: t.user, cookie: set };
+        },
+        async read(request) {
+            const raw = readCookie(request, SESSION_COOKIE);
+            if (raw === null || raw === "")
+                return { state: "none" };
+            const s = await open(SESSION_COOKIE, raw);
+            if (!s || s.v !== 1 || typeof s.at !== "string" || typeof s.iat !== "number" || typeof s.seen !== "number") {
+                return { state: "ended", reason: "invalid", cookie: clearSession() };
+            }
+            const t = now();
+            if (t - s.iat >= timers.absolute)
+                return { state: "ended", reason: "absolute", cookie: clearSession() };
+            if (t - s.seen >= (s.shared ? timers.idleShared : timers.idlePrivate))
+                return { state: "ended", reason: "idle", cookie: clearSession() };
+            let changed = false;
+            if (s.exp - t <= REFRESH_EARLY) {
+                const r = await auth("token?grant_type=refresh_token", { refresh_token: s.rt });
+                if (!r.ok) {
+                    if (r.code === "auth_unavailable" || r.status >= 500 || r.status === 429) {
+                        // Supabase is down or busy: a token that is still valid keeps working; an expired one can't.
+                        if (s.exp > t)
+                            return { state: "signed_in", user: { id: s.uid, email: s.email }, accessToken: s.at, fresh: t - s.auth < timers.fresh };
+                        return { state: "unavailable" };
+                    }
+                    return { state: "ended", reason: "refused", cookie: clearSession() };
+                }
+                const n = tokens(r.json);
+                if (!n)
+                    return { state: "unavailable" };
+                // A refresh never moves iat or auth: that is what keeps the cap a cap (§10.1).
+                Object.assign(s, { at: n.at, rt: n.rt, exp: n.exp, uid: n.user.id, email: n.user.email });
+                changed = true;
+            }
+            if (t - s.seen >= SEEN_STEP) {
+                s.seen = t;
+                changed = true;
+            }
+            const base = { state: "signed_in", user: { id: s.uid, email: s.email }, accessToken: s.at, fresh: t - s.auth < timers.fresh };
+            if (!changed)
+                return base;
+            const set = await issue(s);
+            if (typeof set !== "string")
+                return { state: "ended", reason: "invalid", cookie: clearSession() };
+            return { ...base, cookie: set };
+        },
+        async signOut(request) {
+            const clear = clearSession();
+            try {
+                const s = await open(SESSION_COOKIE, readCookie(request, SESSION_COOKIE));
+                // Ends this session only (scope=local), never the person's other devices.
+                if (s && typeof s.at === "string" && typeof s.rt === "string") {
+                    let token = s.at;
+                    // An expired access token can't log out, and the refresh token would stay live: swap it first.
+                    if (typeof s.exp !== "number" || s.exp - now() <= REFRESH_EARLY) {
+                        const r = await auth("token?grant_type=refresh_token", { refresh_token: s.rt });
+                        const n = r.ok ? tokens(r.json) : null;
+                        if (!n)
+                            return clear; // refused: the refresh token is already dead
+                        token = n.at;
+                    }
+                    await auth("logout?scope=local", {}, token);
+                }
+            }
+            catch {
+                // Nothing may block somebody signing out (§10.3): the cookie is cleared whatever Supabase says.
+            }
+            return clear;
+        },
+        async rememberSignIn(email) {
+            const e = normaliseEmail(email);
+            if (!e)
+                return clearSignIn();
+            const p = { v: 1, email: e, sent: now() };
+            return cookie(SIGN_IN_COOKIE, await seal(SIGN_IN_COOKIE, p), PENDING_SECONDS);
+        },
+        async pendingSignIn(request) {
+            const p = await open(SIGN_IN_COOKIE, readCookie(request, SIGN_IN_COOKIE));
+            if (!p || p.v !== 1 || typeof p.email !== "string" || typeof p.sent !== "number")
+                return null;
+            if (now() - p.sent > PENDING_SECONDS)
+                return null;
+            return { email: p.email, sent: p.sent };
+        },
+        async limitKey(kind, value) {
+            if (kind === "email")
+                value = value.trim().toLowerCase();
+            const mac = await crypto.subtle.sign("HMAC", (await keys()).hash, enc.encode(`${kind}\u0000${value}`));
+            return `${kind}:${b64url(new Uint8Array(mac)).slice(0, 32)}`;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-supabase",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Supabase clients for Workbench apps (browser, server, the caller's own token, and a service client that logs its reason), plus check:migrations and check:prod-schema.",
   "license": "UNLICENSED",
   "type": "module",