@spacefast/auth 0.0.23

package/README.md

@@ -0,0 +1,102 @@
+# @spacefast/auth
+
+Auth primitives for apps running on Spacefast. Two entry points, one contract:
+
+- `@spacefast/auth/server` — verify a visitor token offline and get back the
+  identity contract every Spacefast surface shares.
+- `@spacefast/auth/tokens` — keep any short-lived credential fresh without
+  writing refresh code again.
+
+The library verifies and manages. It never mints — identity always comes from
+the platform.
+
+## Verify on the server
+
+```ts
+import { createVerifier } from "@spacefast/auth/server";
+
+// The full relying-party profile is mandatory. A signing key alone only says
+// who signed a token — issuer, audience, host, purpose, and claim version are
+// what make it *yours*. The JWKS is data you already have, never a URL: no
+// network round-trip hides in your request path.
+const verify = createVerifier({
+  jwks, // { keys: [...] } — Ed25519 public keys
+  issuer: "spacefast-api",
+  audience: "spc_1234", // your Space
+  host: "docs.example.com", // the host this token must be bound to
+  purpose: "handoff", // tokens minted for any other lane never pass
+  claimVersion: 1,
+});
+
+const auth = await verify(request); // AuthContext | null
+
+// AuthContext — the shared contract:
+// { principal: "account:usr_8m2p" | "person:per_…" | "guest:local",
+//   authorities: ["member:usr_8m2p"],
+//   capabilities: ["page.view", "comments.write"],
+//   isGuest, isAuthenticated, displayName, email?, emailVerified?, picture? }
+```
+
+`verify` accepts a `Request` (it reads `Authorization: Bearer` or
+`X-SF-Authorization`) or a raw token string.
+
+### The four states
+
+`null` is fine for the main path — anything that isn't a verified identity is
+a guest. When you need to know _why_, ask for the outcome:
+
+```ts
+import { guestContext } from "@spacefast/auth/server";
+
+const outcome = await verify.outcome(request);
+// { state: "verified", auth }        the token proves an identity
+// { state: "no-token" }              nothing to verify
+// { state: "invalid-token", reason } provably not acceptable here
+// { state: "verifier-unavailable", reason }
+//                                    this process can't render a verdict —
+//                                    e.g. a key id your JWKS doesn't know yet
+
+const auth = outcome.state === "verified" ? outcome.auth : guestContext();
+```
+
+Fail open to guest: every non-verified state serves the guest experience. The
+states exist so your logs can tell a forged token from a stale key deployment.
+An unknown `kid` is deliberately _unavailable_, not _invalid_ — during key
+rotation the honest answer is "I can't know", never "forged".
+
+Defaults worth knowing: 5 seconds of clock skew on `exp`/`nbf`; `azp` is
+checked only when you pass `authorizedParties`; a malformed claim — even an
+optional one — makes the whole token invalid. Bad data fails loud, not soft.
+
+## Keep a credential fresh
+
+```ts
+import { createTokenManager, TokenRefusedError } from "@spacefast/auth/tokens";
+
+const tickets = createTokenManager({
+  mint: async () => {
+    const response = await fetch("/__spacefast/collab/ticket", { method: "POST" });
+    if (response.status === 403) throw new TokenRefusedError("forbidden");
+    if (!response.ok) throw new Error(`ticket ${response.status}`); // transient
+    const { data } = await response.json();
+    return { token: data.token, expiresAt: data.expiresAt };
+  },
+});
+
+await tickets.current(); // mints once, then stays warm
+tickets.onToken((token) => reconnect(token));
+tickets.onRefusal((code) => teardown(code)); // "no" is terminal, not a retry
+tickets.stop(); // cancels everything, leaks nothing
+```
+
+What the manager does for you:
+
+- **Proactive refresh** at 80% of each token's lifetime — callers never pay
+  the mint latency on the hot path.
+- **Jittered exponential backoff** when minting fails transiently, while any
+  unexpired token keeps being served.
+- **Offline ≠ signed out.** A caller with no live token during an outage gets
+  a `TokenOfflineError`, never a `null` that reads as "no access". Refusals
+  throw `TokenRefusedError` with the code the minter gave.
+- **One mint at a time.** Concurrent `current()` calls share the in-flight
+  request — bursts don't stampede your token endpoint.

package/dist/server.d.ts

@@ -0,0 +1,76 @@
+/** The one identity contract every Spacefast surface shares. */
+export type AuthContext = {
+    /**
+     * Who this session is: `account:…` (a Spacefast user), `person:…` (an
+     * email-invited collaborator), `external:…` (vouched for by an identity
+     * connection), or `guest:…` (nobody in particular).
+     */
+    principal: string;
+    /** The credentials this session arrived with, e.g. `member:usr_8m2p`. */
+    authorities: string[];
+    /** What the session may do, e.g. `page.view`, `comments.write`. */
+    capabilities: string[];
+    isGuest: boolean;
+    isAuthenticated: boolean;
+    displayName: string;
+    email?: string;
+    emailVerified?: boolean;
+    picture?: string;
+};
+export type Jwk = {
+    kty?: string;
+    crv?: string;
+    alg?: string;
+    kid?: string;
+    x?: string;
+    [member: string]: unknown;
+};
+/** Key material as data. Never a URL — the verifier does not fetch. */
+export type Jwks = {
+    keys: Jwk[];
+};
+export type VerifierConfig = {
+    /** Ed25519 public keys (OKP/EdDSA), passed as data. */
+    jwks: Jwks;
+    /** Exact `iss` the token must carry. */
+    issuer: string;
+    /** Exact `aud` the token must carry — for visitor tokens, the Space id. */
+    audience: string;
+    /** The serving host the token must be bound to (`host` claim, case-insensitive). */
+    host: string;
+    /** Exact `purpose` the token must carry. A token minted for another lane never verifies. */
+    purpose: string;
+    /** Exact claim-schema version (`v` claim) this verifier understands. */
+    claimVersion: number;
+    /** When set, a token carrying `azp` must name one of these parties. */
+    authorizedParties?: readonly string[];
+    /** exp/nbf leeway in seconds. Default 5. */
+    clockSkewSeconds?: number;
+    /** Unix-seconds clock override for tests. */
+    now?: () => number;
+};
+export type VerifyInput = Request | string | null | undefined;
+export type VerifyOutcome = {
+    state: "verified";
+    auth: AuthContext;
+} | {
+    state: "no-token";
+} | {
+    state: "invalid-token";
+    reason: string;
+} | {
+    state: "verifier-unavailable";
+    reason: string;
+};
+export type Verifier = {
+    /** Sugar over `outcome`: the AuthContext, or null for every other state. */
+    (input: VerifyInput): Promise<AuthContext | null>;
+    outcome(input: VerifyInput): Promise<VerifyOutcome>;
+};
+/**
+ * The guest AuthContext — what a caller serves when verification returns
+ * anything but `verified`. `guestContext("jane doe")` names the guest;
+ * with no name the guest is simply a Guest.
+ */
+export declare function guestContext(name?: string): AuthContext;
+export declare function createVerifier(config: VerifierConfig): Verifier;

package/dist/server.js

@@ -0,0 +1,371 @@
+// Server-side verification of Spacefast visitor tokens (access-unification
+// plan §07). The whole design is 0-hop: the JWKS arrives as data, the token is
+// checked offline with WebCrypto, and no request ever leaves the process. The
+// relying-party profile — issuer, audience, host, purpose, claim version — is
+// mandatory in full. A JWKS alone only says who signed a token; with a shared
+// cross-tenant signer that is not a tenant boundary. The profile is.
+//
+// Verification is four-state (Lakebed's contract):
+//   verified             the token proves an AuthContext
+//   no-token             the request carried nothing to verify
+//   invalid-token        the token is provably not acceptable here
+//   verifier-unavailable this process cannot render a verdict (missing
+//                        WebCrypto, or a `kid` the supplied JWKS doesn't know)
+//
+// The documented failure posture is fail-open-to-guest: anything but
+// `verified` serves the guest experience. The four states exist so callers
+// that care (logging, strict mode) can tell an attack from a stale deploy.
+// jose v6 reports the fully-specified "Ed25519" for OKP keys while older
+// signers stamp the umbrella "EdDSA" — both name the same signature scheme.
+const TOKEN_ALGS = ["EdDSA", "Ed25519"];
+const ED25519_PUBLIC_KEY_BYTES = 32;
+const DEFAULT_CLOCK_SKEW_SECONDS = 5;
+/**
+ * The guest AuthContext — what a caller serves when verification returns
+ * anything but `verified`. `guestContext("jane doe")` names the guest;
+ * with no name the guest is simply a Guest.
+ */
+export function guestContext(name) {
+    const slug = name === undefined ? "local" : guestSlug(name);
+    return {
+        principal: `guest:${slug}`,
+        authorities: [],
+        capabilities: [],
+        isGuest: true,
+        isAuthenticated: false,
+        displayName: name === undefined ? "Guest" : guestDisplayName(slug),
+    };
+}
+export function createVerifier(config) {
+    requireText(config.issuer, "issuer");
+    requireText(config.audience, "audience");
+    requireText(config.host, "host");
+    requireText(config.purpose, "purpose");
+    if (!Number.isInteger(config.claimVersion)) {
+        throw new TypeError("createVerifier: claimVersion must be an integer");
+    }
+    const keys = usableKeys(config.jwks);
+    if (keys.length === 0) {
+        throw new TypeError("createVerifier: jwks carries no usable Ed25519 key (need kty OKP, crv Ed25519, base64url x of 32 bytes)");
+    }
+    const expectedHost = config.host.trim().toLowerCase();
+    const skew = config.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+    const outcome = async (input) => {
+        const token = tokenFrom(input);
+        if (!token) {
+            return { state: "no-token" };
+        }
+        const parts = token.split(".");
+        const headerPart = parts[0];
+        const payloadPart = parts[1];
+        const signaturePart = parts[2];
+        if (parts.length !== 3 || !headerPart || !payloadPart || !signaturePart) {
+            return invalid("malformed");
+        }
+        let header;
+        let payload;
+        let signature;
+        try {
+            header = jsonObject(decodeText(headerPart));
+            payload = jsonObject(decodeText(payloadPart));
+            signature = base64UrlDecode(signaturePart);
+        }
+        catch {
+            return invalid("malformed");
+        }
+        if (!header || !payload) {
+            return invalid("malformed");
+        }
+        if (!TOKEN_ALGS.includes(header.alg)) {
+            return invalid("alg");
+        }
+        // Key selection: a token `kid` narrows to keys claiming that id (keys
+        // published without a kid stay candidates). A kid nobody claims is
+        // indistinguishable from key material this deploy hasn't received yet —
+        // that is unavailability, not proof of forgery.
+        const kid = typeof header.kid === "string" ? header.kid : null;
+        const candidates = kid ? keys.filter((key) => key.kid === undefined || key.kid === kid) : keys;
+        if (candidates.length === 0) {
+            return { state: "verifier-unavailable", reason: "unknown-kid" };
+        }
+        const subtle = webCrypto();
+        if (!subtle) {
+            return { state: "verifier-unavailable", reason: "no-webcrypto" };
+        }
+        const signed = new TextEncoder().encode(`${headerPart}.${payloadPart}`);
+        const verified = (await Promise.all(candidates.map((key) => ed25519Verify(subtle, key.bytes, signed, signature)))).some(Boolean);
+        if (!verified) {
+            return invalid("signature");
+        }
+        const claims = readClaims(payload);
+        if (typeof claims === "string") {
+            return invalid(claims);
+        }
+        if (claims.iss !== config.issuer)
+            return invalid("claim:iss");
+        if (claims.aud !== config.audience)
+            return invalid("claim:aud");
+        if (claims.host.trim().toLowerCase() !== expectedHost)
+            return invalid("claim:host");
+        if (claims.purpose !== config.purpose)
+            return invalid("claim:purpose");
+        if (claims.v !== config.claimVersion)
+            return invalid("claim:v");
+        if (config.authorizedParties !== undefined &&
+            claims.azp !== undefined &&
+            !config.authorizedParties.includes(claims.azp)) {
+            return invalid("claim:azp");
+        }
+        const now = config.now ? config.now() : Math.floor(Date.now() / 1000);
+        if (now > claims.exp + skew)
+            return invalid("expired");
+        if (claims.nbf !== undefined && now < claims.nbf - skew)
+            return invalid("not-yet-valid");
+        return { state: "verified", auth: authFromClaims(claims) };
+    };
+    const verify = async (input) => {
+        const result = await outcome(input);
+        return result.state === "verified" ? result.auth : null;
+    };
+    return Object.assign(verify, { outcome });
+}
+function invalid(reason) {
+    return { state: "invalid-token", reason };
+}
+// Identity comes from the `principal` claim alone — set at mint by whichever
+// lane actually authenticated somebody, never inferred from authorities. A
+// verified token without it is a real session (a share link, a password) that
+// belongs to nobody: it keeps its authorities and capabilities as a guest.
+function authFromClaims(claims) {
+    const identified = claims.principal !== undefined;
+    const displayName = claims.profile?.name ??
+        claims.profile?.username ??
+        (identified && claims.principal
+            ? claims.principal.slice(claims.principal.indexOf(":") + 1)
+            : "Guest");
+    return {
+        principal: claims.principal ?? "guest:local",
+        authorities: claims.authorities,
+        capabilities: claims.capabilities,
+        isGuest: !identified,
+        isAuthenticated: identified,
+        displayName,
+        ...(claims.email !== undefined ? { email: claims.email } : {}),
+        ...(claims.emailVerified !== undefined ? { emailVerified: claims.emailVerified } : {}),
+        ...(claims.profile?.avatar_url !== undefined ? { picture: claims.profile.avatar_url } : {}),
+    };
+}
+// Strict claim reading: a malformed claim — even an optional one — makes the
+// token invalid. A signer emitting out-of-contract values is a bug we want
+// loud, not a value we quietly drop. Returns the reason string on failure.
+function readClaims(payload) {
+    const sub = text(payload.sub);
+    if (sub === null)
+        return "claim:sub";
+    const authorities = stringArray(payload.authorities);
+    if (authorities === null || authorities.length === 0)
+        return "claim:authorities";
+    const capabilities = payload.capabilities === undefined ? [] : stringArray(payload.capabilities);
+    if (capabilities === null)
+        return "claim:capabilities";
+    const exp = seconds(payload.exp);
+    if (exp === null)
+        return "claim:exp";
+    const iss = text(payload.iss);
+    if (iss === null)
+        return "claim:iss";
+    const aud = text(payload.aud);
+    if (aud === null)
+        return "claim:aud";
+    const host = text(payload.host);
+    if (host === null)
+        return "claim:host";
+    const purpose = text(payload.purpose);
+    if (purpose === null)
+        return "claim:purpose";
+    if (typeof payload.v !== "number" || !Number.isInteger(payload.v))
+        return "claim:v";
+    const claims = {
+        sub,
+        authorities,
+        capabilities,
+        exp,
+        iss,
+        aud,
+        host,
+        purpose,
+        v: payload.v,
+    };
+    if (payload.principal !== undefined) {
+        const principal = text(payload.principal);
+        if (principal === null || !/^(?:account|person|external):[A-Za-z0-9_.-]+$/.test(principal)) {
+            return "claim:principal";
+        }
+        claims.principal = principal;
+    }
+    if (payload.nbf !== undefined) {
+        const nbf = seconds(payload.nbf);
+        if (nbf === null)
+            return "claim:nbf";
+        claims.nbf = nbf;
+    }
+    if (payload.azp !== undefined) {
+        const azp = text(payload.azp);
+        if (azp === null)
+            return "claim:azp";
+        claims.azp = azp;
+    }
+    if (payload.email !== undefined) {
+        const email = text(payload.email);
+        if (email === null || !email.includes("@"))
+            return "claim:email";
+        claims.email = email;
+    }
+    if (payload.emailVerified !== undefined) {
+        if (typeof payload.emailVerified !== "boolean")
+            return "claim:emailVerified";
+        claims.emailVerified = payload.emailVerified;
+    }
+    if (payload.profile !== undefined) {
+        const raw = payload.profile;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return "claim:profile";
+        const record = raw;
+        const profile = {};
+        for (const field of ["name", "username", "avatar_url"]) {
+            if (record[field] === undefined)
+                continue;
+            const value = text(record[field]);
+            if (value === null)
+                return "claim:profile";
+            profile[field] = value;
+        }
+        claims.profile = profile;
+    }
+    return claims;
+}
+// ---------------------------------------------------------------------------
+// Token extraction
+// ---------------------------------------------------------------------------
+// `Authorization: Bearer …` wins; `X-SF-Authorization` is the integration
+// header for clients whose Authorization is already spoken for.
+function tokenFrom(input) {
+    if (input === null || input === undefined)
+        return null;
+    if (typeof input === "string") {
+        return input.trim() || null;
+    }
+    const authorization = input.headers.get("authorization");
+    if (authorization) {
+        const match = /^Bearer\s+(.+)$/i.exec(authorization.trim());
+        if (match?.[1])
+            return match[1].trim();
+    }
+    const dedicated = input.headers.get("x-sf-authorization");
+    return dedicated?.trim() || null;
+}
+function usableKeys(jwks) {
+    const keys = [];
+    for (const jwk of jwks.keys ?? []) {
+        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string")
+            continue;
+        if (jwk.alg !== undefined && !TOKEN_ALGS.includes(jwk.alg))
+            continue;
+        let bytes;
+        try {
+            bytes = base64UrlDecode(jwk.x);
+        }
+        catch {
+            continue;
+        }
+        if (bytes.length !== ED25519_PUBLIC_KEY_BYTES)
+            continue;
+        keys.push(typeof jwk.kid === "string" ? { kid: jwk.kid, bytes } : { bytes });
+    }
+    return keys;
+}
+function webCrypto() {
+    return globalThis.crypto?.subtle ?? null;
+}
+async function ed25519Verify(subtle, publicKey, data, signature) {
+    try {
+        const key = await subtle.importKey("raw", copyBytes(publicKey), { name: "Ed25519" }, false, [
+            "verify",
+        ]);
+        return await subtle.verify({ name: "Ed25519" }, key, copyBytes(signature), copyBytes(data));
+    }
+    catch {
+        return false;
+    }
+}
+// Copies onto a fresh ArrayBuffer so BufferSource-typed WebCrypto inputs never
+// see a SharedArrayBuffer-backed or offset view.
+function copyBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+// ---------------------------------------------------------------------------
+// Small strict parsers
+// ---------------------------------------------------------------------------
+function requireText(value, name) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError(`createVerifier: ${name} is required`);
+    }
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function seconds(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    const items = [];
+    for (const item of value) {
+        if (typeof item !== "string" || item.length === 0)
+            return null;
+        items.push(item);
+    }
+    return items;
+}
+function jsonObject(value) {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+function decodeText(part) {
+    return new TextDecoder().decode(base64UrlDecode(part));
+}
+// Strict base64url: reject out-of-alphabet input instead of skipping it, so a
+// tampered segment fails as malformed rather than decoding to something else.
+function base64UrlDecode(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value)) {
+        throw new TypeError("invalid base64url");
+    }
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function guestSlug(name) {
+    return (name
+        .replace(/^guest:/, "")
+        .trim()
+        .replace(/[^a-zA-Z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase() || "local");
+}
+function guestDisplayName(slug) {
+    const pretty = slug
+        .split(/[-_.]+/)
+        .filter(Boolean)
+        .map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`)
+        .join(" ");
+    return pretty || "Guest";
+}

package/dist/tokens.d.ts

@@ -0,0 +1,43 @@
+/** What a supplier returns: the credential and when it dies. */
+export type MintedToken = {
+    token: string;
+    /** ISO-8601 string, epoch milliseconds, or a Date. */
+    expiresAt: string | number | Date;
+};
+/** The minter refused — a policy decision, not an outage. Throw this from `mint`. */
+export declare class TokenRefusedError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/** Minting is failing for transient reasons. The session is not over. */
+export declare class TokenOfflineError extends Error {
+    constructor(cause?: unknown);
+}
+/** Scheduling seam — inject a fake clock in tests, omit everywhere else. */
+export type TokenManagerClock = {
+    now(): number;
+    random(): number;
+    setTimer(callback: () => void, delayMs: number): unknown;
+    clearTimer(timer: unknown): void;
+};
+export type TokenManagerOptions = {
+    mint: () => Promise<MintedToken>;
+    clock?: TokenManagerClock;
+};
+export type TokenManager = {
+    /**
+     * The live token, minting one first if needed. Concurrent callers share one
+     * in-flight mint. Rejects with `TokenRefusedError` (terminal),
+     * `TokenOfflineError` (transient), or a plain Error after `stop()`.
+     */
+    current(): Promise<string>;
+    /** Force a fresh mint now — the "identity changed" seam. */
+    refresh(): Promise<string>;
+    /** Fires with each new token, and with null when access lapses. */
+    onToken(listener: (token: string | null) => void): () => void;
+    /** Fires once, with the refusal code, when the minter terminally says no. */
+    onRefusal(listener: (code: string) => void): () => void;
+    /** Cancels all timers, settles all waiters, ends the manager for good. */
+    stop(): void;
+};
+export declare function createTokenManager(options: TokenManagerOptions): TokenManager;

package/dist/tokens.js

@@ -0,0 +1,195 @@
+// One TokenManager for every short-lived credential (access-unification plan
+// §07): realtime tickets, machine-exchange tokens, anything a supplier can
+// mint. The manager owns the lifecycle — proactive refresh at 80% of the
+// token's lifetime, jittered exponential backoff when minting fails, and an
+// honest vocabulary for the two ways minting stops working:
+//
+//   refused   the minter said no. Terminal. `onRefusal` fires with the code,
+//             and every later `current()` rejects with the same error.
+//   offline   the minter was unreachable. NOT signed out: an unexpired token
+//             keeps being served, retries continue in the background, and a
+//             caller with no token gets a distinct `TokenOfflineError` —
+//             never a null that reads as "no access".
+//
+// `stop()` cancels every timer and settles every waiter. Nothing leaks.
+/** The minter refused — a policy decision, not an outage. Throw this from `mint`. */
+export class TokenRefusedError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? `token refused: ${code}`);
+        this.name = "TokenRefusedError";
+        this.code = code;
+    }
+}
+/** Minting is failing for transient reasons. The session is not over. */
+export class TokenOfflineError extends Error {
+    constructor(cause) {
+        super("token minting is unreachable", cause === undefined ? undefined : { cause });
+        this.name = "TokenOfflineError";
+    }
+}
+const REFRESH_AT_LIFETIME_FRACTION = 0.8;
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_MS = 30_000;
+function stoppedError() {
+    return new Error("token manager stopped");
+}
+function expiryOf(minted) {
+    const raw = minted.expiresAt;
+    const expiresAt = raw instanceof Date ? raw.getTime() : typeof raw === "number" ? raw : Date.parse(raw);
+    if (!Number.isFinite(expiresAt)) {
+        // A supplier handing back an unreadable expiry is a bug, not weather.
+        throw new TypeError(`mint returned an unreadable expiresAt: ${String(raw)}`);
+    }
+    return expiresAt;
+}
+function systemClock() {
+    return {
+        now: () => Date.now(),
+        random: () => Math.random(),
+        setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+        clearTimer: (timer) => clearTimeout(timer),
+    };
+}
+export function createTokenManager(options) {
+    const clock = options.clock ?? systemClock();
+    const tokenListeners = new Set();
+    const refusalListeners = new Set();
+    let live = null;
+    let terminal = null;
+    let inFlight = null;
+    let timer = null;
+    let retryAttempt = 0;
+    let generation = 0;
+    let emitted = null;
+    function clearTimer() {
+        if (timer !== null)
+            clock.clearTimer(timer);
+        timer = null;
+    }
+    function emit(token) {
+        if (token === emitted)
+            return;
+        emitted = token;
+        for (const listener of tokenListeners)
+            listener(token);
+    }
+    function unexpired() {
+        return live && live.expiresAt > clock.now() ? live.token : null;
+    }
+    function fail(error, refusalCode) {
+        clearTimer();
+        terminal = error;
+        live = null;
+        inFlight = null;
+        if (refusalCode !== null) {
+            for (const listener of refusalListeners)
+                listener(refusalCode);
+        }
+        emit(null);
+        return error;
+    }
+    function scheduleMint(delayMs) {
+        clearTimer();
+        timer = clock.setTimer(() => {
+            timer = null;
+            void mintOnce().catch(() => {
+                // A background mint failure is handled inside mintOnce (backoff or
+                // terminal state); the rejection here has no waiter.
+            });
+        }, Math.max(1, delayMs));
+    }
+    function scheduleRefresh(expiresAt) {
+        scheduleMint((expiresAt - clock.now()) * REFRESH_AT_LIFETIME_FRACTION);
+    }
+    function scheduleRetry() {
+        const exponential = Math.min(RETRY_BASE_MS * 2 ** Math.max(0, retryAttempt - 1), RETRY_MAX_MS);
+        const jitter = 0.8 + Math.min(1, Math.max(0, clock.random())) * 0.4;
+        scheduleMint(exponential * jitter);
+    }
+    function mintOnce() {
+        if (inFlight)
+            return inFlight;
+        clearTimer();
+        const request = generation;
+        const attempt = (async () => {
+            let minted;
+            try {
+                minted = await options.mint();
+            }
+            catch (error) {
+                if (generation !== request)
+                    throw stoppedError();
+                inFlight = null;
+                if (error instanceof TokenRefusedError) {
+                    throw fail(error, error.code);
+                }
+                // Transient: keep any unexpired token in play, back off, and tell the
+                // waiter the truth — offline, not signed out.
+                retryAttempt += 1;
+                if (live && live.expiresAt <= clock.now())
+                    emit(null);
+                scheduleRetry();
+                throw new TokenOfflineError(error);
+            }
+            if (generation !== request)
+                throw stoppedError();
+            inFlight = null;
+            const expiresAt = expiryOf(minted); // throws on contract breakage
+            if (expiresAt <= clock.now()) {
+                // A token born dead is indistinguishable from clock trouble; treat it
+                // as an outage and retry rather than hot-looping on the 80% timer.
+                retryAttempt += 1;
+                scheduleRetry();
+                throw new TokenOfflineError(new Error("minted token was already expired"));
+            }
+            retryAttempt = 0;
+            live = { token: minted.token, expiresAt };
+            scheduleRefresh(expiresAt);
+            emit(minted.token);
+            return minted.token;
+        })();
+        // Contract failures from expiryOf land here as terminal state.
+        inFlight = attempt;
+        attempt.catch((error) => {
+            if (generation === request && error instanceof TypeError) {
+                fail(error, null);
+            }
+        });
+        return attempt;
+    }
+    return {
+        current() {
+            if (terminal)
+                return Promise.reject(terminal);
+            const token = unexpired();
+            if (token)
+                return Promise.resolve(token);
+            return mintOnce();
+        },
+        refresh() {
+            if (terminal)
+                return Promise.reject(terminal);
+            return mintOnce();
+        },
+        onToken(listener) {
+            tokenListeners.add(listener);
+            return () => tokenListeners.delete(listener);
+        },
+        onRefusal(listener) {
+            refusalListeners.add(listener);
+            return () => refusalListeners.delete(listener);
+        },
+        stop() {
+            if (terminal)
+                return;
+            generation += 1;
+            terminal = stoppedError();
+            clearTimer();
+            live = null;
+            inFlight = null;
+            tokenListeners.clear();
+            refusalListeners.clear();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@spacefast/auth",
+  "version": "0.0.23",
+  "license": "MIT",
+  "description": "Verify Spacefast visitor tokens offline and keep short-lived credentials fresh.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spacefast/monorepo.git",
+    "directory": "packages/spacefast-auth"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": "^1.3.11",
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./tokens": {
+      "types": "./dist/tokens.d.ts",
+      "import": "./dist/tokens.js",
+      "default": "./dist/tokens.js"
+    }
+  }
+}