@starci/auth 0.0.0-stage → 0.1.0

package/dist/server/sessions.d.ts

@@ -0,0 +1,45 @@
+import type { JwksDocument } from "../contracts/index.js";
+import type { AuthOptions } from "./options.js";
+import type { AuthClock, AuthIds, AuthLogger, AuthSubject, DeviceMeta, SessionTokens } from "./ports.js";
+import type { AuthTokens } from "./tokens.js";
+/** A rotated token presented again this soon after its rotation is a racing tab, not a theft. */
+export declare const DEFAULT_REUSE_GRACE_MS = 30000;
+/** The log event of a replayed refresh token. */
+export declare const REFRESH_REUSE_EVENT = "auth.refresh-reuse-detected";
+/** What the sessions need from the module. */
+export interface SessionsDeps {
+    readonly options: Pick<AuthOptions, "refreshTtlSeconds" | "reuseGraceMs" | "sessions" | "accounts">;
+    readonly tokens: AuthTokens;
+    readonly clock: AuthClock;
+    readonly ids: AuthIds;
+    readonly logger?: AuthLogger | undefined;
+}
+/**
+ * Device sessions: opens one at sign-in, rotates its refresh token on every refresh (a replayed token ends the session) and ends it
+ * at sign-out. A token rotated within the grace window is a racing request: it is answered with an access token only, the cookie
+ * is left as the winner wrote it.
+ */
+export declare class AuthSessions {
+    #private;
+    constructor(deps: SessionsDeps);
+    /** Opens a device session for a person who just proved who they are, and answers its first tokens. */
+    start(subject: AuthSubject, device: DeviceMeta): Promise<SessionTokens>;
+    /**
+     * Exchanges a refresh token for a new pair; the presented token is spent. Throws when it is unknown, expired, or rotated long
+     * ago (reuse ends the session). A token a sibling request rotated within the grace window answers an access token marked
+     * `cookieKept`, so the caller leaves the cookie alone: the sibling already wrote the successor.
+     */
+    refresh(presented: string): Promise<SessionTokens>;
+    /**
+     * Answers a fresh access token for the session of a refresh token WITHOUT rotating it, so parallel gated requests of one browser
+     * can ask at once. A token rotated within the grace window still counts (a sibling request just rotated it); an older replay
+     * ends the session.
+     */
+    access(presented: string): Promise<SessionTokens>;
+    /** The public key document access tokens verify against. */
+    jwks(): Promise<JwksDocument>;
+    /** Signs the person out of every other device; the session of the caller stays. */
+    endOthers(userId: string, keepSessionId: string | undefined): Promise<void>;
+    /** Ends the session a refresh token belongs to (an empty or unknown token changes nothing). */
+    end(presented: string): Promise<void>;
+}

package/dist/server/sessions.js

@@ -0,0 +1,153 @@
+import { AUTH_ERROR_CODES } from "../contracts/index.js";
+import { AuthError } from "./errors.js";
+import { digestOf } from "./primitives.js";
+/** A rotated token presented again this soon after its rotation is a racing tab, not a theft. */
+export const DEFAULT_REUSE_GRACE_MS = 30_000;
+/** The log event of a replayed refresh token. */
+export const REFRESH_REUSE_EVENT = "auth.refresh-reuse-detected";
+const MILLISECONDS = 1000;
+/**
+ * Device sessions: opens one at sign-in, rotates its refresh token on every refresh (a replayed token ends the session) and ends it
+ * at sign-out. A token rotated within the grace window is a racing request: it is answered with an access token only, the cookie
+ * is left as the winner wrote it.
+ */
+export class AuthSessions {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    get #store() {
+        return this.#deps.options.sessions;
+    }
+    get #graceMs() {
+        return this.#deps.options.reuseGraceMs ?? DEFAULT_REUSE_GRACE_MS;
+    }
+    /** Opens a device session for a person who just proved who they are, and answers its first tokens. */
+    async start(subject, device) {
+        const now = this.#deps.clock.now();
+        const sessionId = this.#deps.ids.next();
+        const refreshToken = this.#mintToken();
+        await this.#store.transaction(async (tx) => {
+            await tx.openSession({ id: sessionId, userId: subject.userId, now, userAgent: device.userAgent, ip: device.ip });
+            await tx.insertToken({
+                id: this.#deps.ids.next(),
+                sessionId,
+                userId: subject.userId,
+                tokenHash: digestOf(refreshToken),
+                expiresAt: this.#refreshExpiry(now),
+            });
+        });
+        return this.#tokensFor(subject, sessionId, refreshToken, now);
+    }
+    /**
+     * Exchanges a refresh token for a new pair; the presented token is spent. Throws when it is unknown, expired, or rotated long
+     * ago (reuse ends the session). A token a sibling request rotated within the grace window answers an access token marked
+     * `cookieKept`, so the caller leaves the cookie alone: the sibling already wrote the successor.
+     */
+    async refresh(presented) {
+        if (presented === "")
+            throw new AuthError(AUTH_ERROR_CODES.RefreshInvalid);
+        const now = this.#deps.clock.now();
+        const nextToken = this.#mintToken();
+        const rotation = await this.#store.transaction(async (tx) => {
+            const row = await tx.findTokenForUpdate(digestOf(presented));
+            if (row === null || row.expiresAt <= now)
+                return { kind: "invalid" };
+            if (row.usedAt !== null) {
+                return now.getTime() - row.usedAt.getTime() <= this.#graceMs
+                    ? { kind: "raced", row }
+                    : { kind: "reused", sessionId: row.sessionId };
+            }
+            await tx.markTokenUsed(row.id, now);
+            await tx.insertToken({
+                id: this.#deps.ids.next(),
+                sessionId: row.sessionId,
+                userId: row.userId,
+                tokenHash: digestOf(nextToken),
+                expiresAt: this.#refreshExpiry(now),
+            });
+            await tx.deleteExpiredTokens(row.userId, now);
+            return { kind: "rotated", row, next: nextToken };
+        });
+        if (rotation.kind === "reused") {
+            await this.#store.closeSession(rotation.sessionId);
+            this.#deps.logger?.warn(REFRESH_REUSE_EVENT, { sessionId: rotation.sessionId });
+            throw new AuthError(AUTH_ERROR_CODES.RefreshReused);
+        }
+        if (rotation.kind === "invalid")
+            throw new AuthError(AUTH_ERROR_CODES.RefreshInvalid);
+        if (rotation.kind === "raced")
+            return this.#accessOf(rotation.row, presented, now);
+        const user = await this.#deps.options.accounts.find(rotation.row.userId);
+        if (user === undefined || user.disabled || user.email === null) {
+            await this.#store.closeSession(rotation.row.sessionId);
+            throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
+        }
+        await this.#store.touchSession(rotation.row.sessionId, now);
+        return this.#tokensFor({ userId: user.id, email: user.email }, rotation.row.sessionId, rotation.next, now);
+    }
+    /**
+     * Answers a fresh access token for the session of a refresh token WITHOUT rotating it, so parallel gated requests of one browser
+     * can ask at once. A token rotated within the grace window still counts (a sibling request just rotated it); an older replay
+     * ends the session.
+     */
+    async access(presented) {
+        if (presented === "")
+            throw new AuthError(AUTH_ERROR_CODES.RefreshInvalid);
+        const now = this.#deps.clock.now();
+        const row = await this.#store.findToken(digestOf(presented));
+        if (row === null || row.expiresAt <= now)
+            throw new AuthError(AUTH_ERROR_CODES.RefreshInvalid);
+        if (row.usedAt !== null && now.getTime() - row.usedAt.getTime() > this.#graceMs) {
+            await this.#store.closeSession(row.sessionId);
+            this.#deps.logger?.warn(REFRESH_REUSE_EVENT, { sessionId: row.sessionId });
+            throw new AuthError(AUTH_ERROR_CODES.RefreshReused);
+        }
+        return this.#accessOf(row, presented, now);
+    }
+    /** The public key document access tokens verify against. */
+    jwks() {
+        return this.#deps.tokens.jwks();
+    }
+    /** Signs the person out of every other device; the session of the caller stays. */
+    async endOthers(userId, keepSessionId) {
+        if (keepSessionId === undefined)
+            throw new AuthError(AUTH_ERROR_CODES.Unauthenticated);
+        await this.#store.closeOtherSessions(userId, keepSessionId);
+    }
+    /** Ends the session a refresh token belongs to (an empty or unknown token changes nothing). */
+    async end(presented) {
+        if (presented === "")
+            return;
+        const row = await this.#store.findToken(digestOf(presented));
+        if (row !== null)
+            await this.#store.closeSession(row.sessionId);
+    }
+    /** An access token for the session of a token row, without rotating; an account that is gone or disabled ends the session. */
+    async #accessOf(row, presented, now) {
+        const user = await this.#deps.options.accounts.find(row.userId);
+        if (user === undefined || user.disabled || user.email === null) {
+            await this.#store.closeSession(row.sessionId);
+            throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
+        }
+        const tokens = await this.#tokensFor({ userId: user.id, email: user.email }, row.sessionId, presented, now);
+        return { ...tokens, cookieKept: true };
+    }
+    async #tokensFor(subject, sessionId, refreshToken, now) {
+        const access = await this.#deps.tokens.sign({ sub: subject.userId, email: subject.email, sessionId }, now);
+        return {
+            accessToken: access.token,
+            accessExpiresAt: access.expiresAt.toISOString(),
+            accessExpiresIn: Math.round((access.expiresAt.getTime() - now.getTime()) / MILLISECONDS),
+            cookieToken: refreshToken,
+            refreshMaxAgeSeconds: this.#deps.options.refreshTtlSeconds,
+            user: { id: subject.userId, email: subject.email },
+        };
+    }
+    #refreshExpiry(now) {
+        return new Date(now.getTime() + this.#deps.options.refreshTtlSeconds * MILLISECONDS);
+    }
+    #mintToken() {
+        return `${this.#deps.ids.next()}${this.#deps.ids.next()}`.replaceAll("-", "");
+    }
+}

package/dist/server/strategies.d.ts

@@ -0,0 +1,29 @@
+import { Strategy as GoogleStrategy } from "passport-google-oauth20";
+import type { Profile } from "passport-google-oauth20";
+import { Strategy as LocalStrategy } from "passport-local";
+import type { GoogleStateClient } from "./google-state.js";
+import type { GoogleOptions } from "./options.js";
+import type { AuthAuthenticator, AuthSubject, GoogleProfile } from "./ports.js";
+/** The facts the app needs from a Google profile; an account without a subject is refused. */
+export declare const googleProfileOf: (profile: Profile) => GoogleProfile;
+declare const PassportLocalStrategy_base: new (...args: [] | [options: import("passport-local").IStrategyOptionsWithRequest] | [options: import("passport-local").IStrategyOptions]) => LocalStrategy & {
+    validate(...args: any[]): unknown;
+};
+/** The email and password strategy; the app decides whether the pair is right. */
+export declare class PassportLocalStrategy extends PassportLocalStrategy_base {
+    #private;
+    constructor(authenticator: AuthAuthenticator);
+    /** Called by passport with the posted pair; answers the person or throws the app's refusal. */
+    validate(email: string, password: string): Promise<AuthSubject>;
+}
+declare const PassportGoogleStrategy_base: new (...args: [options: import("passport-google-oauth20").StrategyOptionsWithRequest] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptionsWithRequest]) => GoogleStrategy & {
+    validate(...args: any[]): unknown;
+};
+/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export declare class PassportGoogleStrategy extends PassportGoogleStrategy_base {
+    #private;
+    constructor(google: GoogleOptions, authenticator: AuthAuthenticator, state: GoogleStateClient);
+    /** Called by passport with Google's profile; answers the person the app stands it for. */
+    validate(_accessToken: string, _refreshToken: string, profile: Profile): Promise<AuthSubject>;
+}
+export {};

package/dist/server/strategies.js

@@ -0,0 +1,55 @@
+import { PassportStrategy } from "@nestjs/passport";
+import { Strategy as GoogleStrategy } from "passport-google-oauth20";
+import { Strategy as LocalStrategy } from "passport-local";
+import { AUTH_ERROR_CODES } from "../contracts/index.js";
+import { AuthError } from "./errors.js";
+import { revealed } from "./primitives.js";
+const verifiedOf = (profile) => {
+    const claim = profile._json.email_verified;
+    return claim === true || claim === "true";
+};
+/** The facts the app needs from a Google profile; an account without a subject is refused. */
+export const googleProfileOf = (profile) => {
+    if (profile.id === "")
+        throw new AuthError(AUTH_ERROR_CODES.GoogleRejected);
+    return {
+        subject: profile.id,
+        email: profile.emails?.[0]?.value ?? null,
+        emailVerified: verifiedOf(profile),
+        name: profile.displayName === "" ? null : profile.displayName,
+        picture: profile.photos?.[0]?.value ?? null,
+    };
+};
+/** The email and password strategy; the app decides whether the pair is right. */
+export class PassportLocalStrategy extends PassportStrategy(LocalStrategy, "local") {
+    #authenticator;
+    constructor(authenticator) {
+        super({ usernameField: "email", passwordField: "password", session: false });
+        this.#authenticator = authenticator;
+    }
+    /** Called by passport with the posted pair; answers the person or throws the app's refusal. */
+    validate(email, password) {
+        return this.#authenticator.verifyPassword(email, password);
+    }
+}
+/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export class PassportGoogleStrategy extends PassportStrategy(GoogleStrategy, "google") {
+    #authenticator;
+    constructor(google, authenticator, state) {
+        super({
+            clientID: google.clientId,
+            clientSecret: revealed(google.clientSecret),
+            callbackURL: google.callbackUrl,
+            scope: ["openid", "email", "profile"],
+            state: true,
+            pkce: true,
+        });
+        this.#authenticator = authenticator;
+        // passport-oauth2 types describe only its session stores; the stateless PKCE store replaces the one it built.
+        Object.assign(this, { _stateStore: state });
+    }
+    /** Called by passport with Google's profile; answers the person the app stands it for. */
+    validate(_accessToken, _refreshToken, profile) {
+        return this.#authenticator.signInWithGoogle(googleProfileOf(profile));
+    }
+}

package/dist/server/tokens.d.ts

@@ -0,0 +1,26 @@
+import type { JwksDocument } from "../contracts/index.js";
+import type { Outcome } from "./errors.js";
+import type { AuthOptions } from "./options.js";
+import type { AccessClaims, IssuedAccessToken } from "./ports.js";
+import type { SignedState } from "./primitives.js";
+/** The options this signer needs. */
+export type TokenOptions = Pick<AuthOptions, "issuer" | "audience" | "keys" | "accessTtlSeconds">;
+/**
+ * The one signer and verifier of our access tokens (Ed25519 JWTs, the algorithm pinned) and of the short-lived Google state.
+ * The key set holds one signing key and any number of retired keys: all of them verify and are published as the JWKS, so a key
+ * rotates without signing anybody out (add the new key first, make it the signer, drop the old one when its tokens have expired).
+ */
+export declare class AuthTokens {
+    #private;
+    constructor(options: TokenOptions);
+    /** Signs an access token for one device session. */
+    sign(claims: AccessClaims, now: Date): Promise<IssuedAccessToken>;
+    /** The claims of a token that passed signature (against any key of the set), issuer, audience and expiry, or a refusal. */
+    verify(token: string, now: Date): Promise<Outcome<AccessClaims>>;
+    /** The public key document: every key of the set. */
+    jwks(): Promise<JwksDocument>;
+    /** Signs the state of a Google round trip (an HMAC under a key derived from the signing key). */
+    signState(state: SignedState): string;
+    /** The state when the value is ours, unexpired and untampered; otherwise null. */
+    verifyState(value: string, now: Date): SignedState | null;
+}

package/dist/server/tokens.js

@@ -0,0 +1,130 @@
+import { createHash, createHmac, createPrivateKey, createPublicKey } from "node:crypto";
+import { SignJWT, calculateJwkThumbprint, createLocalJWKSet, exportJWK, importPKCS8, importSPKI, jwtVerify } from "jose";
+import { AUTH_ALGORITHM, AUTH_AUDIENCE, AUTH_CLAIMS, AUTH_ERROR_CODES, AUTH_ROLE } from "../contracts/index.js";
+import { AuthError, ok, refused } from "./errors.js";
+import { revealed, signStateToken, verifyStateToken } from "./primitives.js";
+const STATE_LABEL = "passport.google-state";
+const pemOf = (value) => value.replaceAll(String.raw `\n`, "\n");
+/**
+ * The one signer and verifier of our access tokens (Ed25519 JWTs, the algorithm pinned) and of the short-lived Google state.
+ * The key set holds one signing key and any number of retired keys: all of them verify and are published as the JWKS, so a key
+ * rotates without signing anybody out (add the new key first, make it the signer, drop the old one when its tokens have expired).
+ */
+export class AuthTokens {
+    #options;
+    #ring;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Signs an access token for one device session. */
+    async sign(claims, now) {
+        const { signer } = await this.#keys();
+        const issuedAt = Math.floor(now.getTime() / 1000);
+        const expiresAt = issuedAt + this.#options.accessTtlSeconds;
+        const token = await new SignJWT({
+            [AUTH_CLAIMS.role]: AUTH_ROLE,
+            [AUTH_CLAIMS.sessionId]: claims.sessionId,
+            ...(claims.email === undefined ? {} : { [AUTH_CLAIMS.email]: claims.email }),
+        })
+            .setProtectedHeader({ alg: AUTH_ALGORITHM, kid: signer.keyId, typ: "JWT" })
+            .setSubject(claims.sub)
+            .setIssuer(this.#options.issuer)
+            .setAudience(this.#options.audience ?? AUTH_AUDIENCE)
+            .setIssuedAt(issuedAt)
+            .setExpirationTime(expiresAt)
+            .sign(signer.privateKey);
+        return { token, expiresAt: new Date(expiresAt * 1000) };
+    }
+    /** The claims of a token that passed signature (against any key of the set), issuer, audience and expiry, or a refusal. */
+    async verify(token, now) {
+        const { verifyingSet } = await this.#keys();
+        try {
+            const { payload } = await jwtVerify(token, verifyingSet, {
+                algorithms: [AUTH_ALGORITHM],
+                issuer: this.#options.issuer,
+                audience: this.#options.audience ?? AUTH_AUDIENCE,
+                currentDate: now,
+            });
+            const sessionId = payload[AUTH_CLAIMS.sessionId];
+            if (payload[AUTH_CLAIMS.role] !== AUTH_ROLE || typeof payload.sub !== "string" || typeof sessionId !== "string") {
+                return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
+            }
+            const email = payload[AUTH_CLAIMS.email];
+            return ok({ sub: payload.sub, sessionId, ...(typeof email === "string" ? { email } : {}) });
+        }
+        catch (cause) {
+            return refused(AUTH_ERROR_CODES.AccessTokenInvalid, { cause: String(cause) });
+        }
+    }
+    /** The public key document: every key of the set. */
+    async jwks() {
+        return (await this.#keys()).document;
+    }
+    /** Signs the state of a Google round trip (an HMAC under a key derived from the signing key). */
+    signState(state) {
+        return signStateToken(this.#stateKey(), state);
+    }
+    /** The state when the value is ours, unexpired and untampered; otherwise null. */
+    verifyState(value, now) {
+        return verifyStateToken(this.#stateKey(), value, now.getTime());
+    }
+    #stateKey() {
+        const signer = this.#options.keys.find((key) => key.privateKey !== undefined);
+        if (signer?.privateKey === undefined)
+            throw new AuthError(AUTH_ERROR_CODES.KeyInvalid, { context: { reason: "no signing key" } });
+        const pem = pemOf(revealed(signer.privateKey));
+        const material = createHash("sha256").update(pem, "utf8").digest();
+        return createHmac("sha256", material).update(STATE_LABEL).digest();
+    }
+    #keys() {
+        this.#ring ??= this.#load();
+        return this.#ring;
+    }
+    async #load() {
+        const loaded = await Promise.all(this.#options.keys.map((key) => loadKey(key)));
+        const signers = loaded.filter((key) => key.privateKey !== undefined);
+        const [signer] = signers;
+        if (signers.length !== 1 || signer?.privateKey === undefined) {
+            throw new AuthError(AUTH_ERROR_CODES.KeyInvalid, { context: { reason: "the key set needs exactly one signing key", signers: signers.length } });
+        }
+        const ids = new Set(loaded.map((key) => key.keyId));
+        if (ids.size !== loaded.length)
+            throw new AuthError(AUTH_ERROR_CODES.KeyInvalid, { context: { reason: "two keys share a kid" } });
+        const keys = loaded.map((key) => ({ ...key.jwk }));
+        return {
+            signer: { ...signer, privateKey: signer.privateKey },
+            verifyingSet: createLocalJWKSet({ keys }),
+            document: { keys: loaded.map((key) => key.jwk) },
+        };
+    }
+}
+const publicPemOf = (key) => {
+    if (key.publicKey !== undefined)
+        return pemOf(key.publicKey);
+    if (key.privateKey === undefined)
+        throw new Error("a key needs a public key or a private key");
+    return createPublicKey(createPrivateKey(pemOf(revealed(key.privateKey)))).export({ type: "spki", format: "pem" }).toString();
+};
+const publicJwkOf = async (publicKey, keyId) => {
+    const key = await importSPKI(publicKey, AUTH_ALGORITHM, { extractable: true });
+    const exported = await exportJWK(key);
+    const kid = keyId ?? (await calculateJwkThumbprint(exported));
+    const jwk = {};
+    for (const [name, value] of Object.entries({ ...exported, kid, alg: AUTH_ALGORITHM, use: "sig" })) {
+        if (typeof value === "string")
+            jwk[name] = value;
+    }
+    return { jwk, keyId: kid };
+};
+const loadKey = async (key) => {
+    try {
+        const [privateKey, published] = await Promise.all([
+            key.privateKey === undefined ? Promise.resolve(undefined) : importPKCS8(pemOf(revealed(key.privateKey)), AUTH_ALGORITHM),
+            publicJwkOf(publicPemOf(key), key.keyId),
+        ]);
+        return { keyId: published.keyId, jwk: published.jwk, privateKey };
+    }
+    catch (cause) {
+        throw new AuthError(AUTH_ERROR_CODES.KeyInvalid, { cause });
+    }
+};

package/dist/server/verifier.d.ts

@@ -0,0 +1,20 @@
+import type { Outcome } from "./errors.js";
+import type { AuthClock, AuthPrincipal } from "./ports.js";
+import type { AuthTokens } from "./tokens.js";
+/**
+ * What `domain/identity` asks of an identity source: the principal of a bearer token, or a refusal. The lite edition's source is
+ * `AuthPrincipalVerifier`; the full edition's is the OIDC verifier of `@starci/auth-oidc` behind this same interface, so guards,
+ * `@Public` and `@Credential` do not change between editions.
+ */
+export interface PrincipalVerifier {
+    /** Verifies one token at one instant. */
+    verify(token: string, now?: Date): Promise<Outcome<AuthPrincipal>>;
+}
+/** The verifier of the app that signs people in: our own access token, checked against our key set, issuer, audience and expiry. */
+export declare class AuthPrincipalVerifier implements PrincipalVerifier {
+    #private;
+    constructor(tokens: AuthTokens, clock?: AuthClock);
+    verify(token: string, now?: Date): Promise<Outcome<AuthPrincipal>>;
+}
+/** The verifier of an app that serves no user session: every access token is refused, so the default-deny guard admits only its public and credential doors. */
+export declare const refuseSessions: PrincipalVerifier;

package/dist/server/verifier.js

@@ -0,0 +1,23 @@
+import { AUTH_ERROR_CODES, AUTH_ROLE } from "../contracts/index.js";
+import { ok, refused } from "./errors.js";
+import { systemClock } from "./runtime.js";
+/** The verifier of the app that signs people in: our own access token, checked against our key set, issuer, audience and expiry. */
+export class AuthPrincipalVerifier {
+    #tokens;
+    #clock;
+    constructor(tokens, clock = systemClock) {
+        this.#tokens = tokens;
+        this.#clock = clock;
+    }
+    async verify(token, now = this.#clock.now()) {
+        const verified = await this.#tokens.verify(token, now);
+        if (verified.kind === "refused")
+            return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
+        const { sub, email, sessionId } = verified.value;
+        return ok({ id: sub, role: AUTH_ROLE, sessionId, ...(email === undefined ? {} : { email }) });
+    }
+}
+/** The verifier of an app that serves no user session: every access token is refused, so the default-deny guard admits only its public and credential doors. */
+export const refuseSessions = {
+    verify: () => Promise.resolve(refused(AUTH_ERROR_CODES.AccessTokenInvalid)),
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,52 @@
+import type { AuthOptions, SigningKeyOptions } from "../server/options.js";
+import type { AccountDirectory, AccountStanding, AuthClock, AuthIds, NewSession, RateCounter, RefreshTokenRecord, SessionStore, SessionTransaction } from "../server/ports.js";
+/** A generated Ed25519 key pair as the PEM texts the options take. */
+export interface TestKeyPair {
+    readonly privateKey: string;
+    readonly publicKey: string;
+}
+/** Generates an Ed25519 key pair (PKCS#8 private PEM, SPKI public PEM). */
+export declare const generateTestKeyPair: () => TestKeyPair;
+/** A signing key for the options; `signer: false` makes it a verify-only (retired) key. */
+export declare const testSigningKey: (pair?: TestKeyPair, keyId?: string, signer?: boolean) => SigningKeyOptions;
+/** A clock the test moves by hand. */
+export declare class FakeClock implements AuthClock {
+    #private;
+    constructor(start?: Date | number);
+    now(): Date;
+    /** Moves time forward. */
+    advance(milliseconds: number): void;
+}
+/** Ids that count up, so a spec reads them. */
+export declare const sequentialIds: (prefix?: string) => AuthIds;
+/** An in-memory `SessionStore` with the same rotation semantics the SQL tables give (a transaction applies all or none of its writes). */
+export declare class MemorySessionStore implements SessionStore {
+    #private;
+    readonly sessions: Map<string, NewSession>;
+    readonly tokens: Map<string, RefreshTokenRecord>;
+    transaction<T>(work: (tx: SessionTransaction) => Promise<T>): Promise<T>;
+    findToken(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    touchSession(): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    closeOtherSessions(userId: string, keepSessionId: string): Promise<void>;
+}
+/** An in-memory account directory. */
+export declare class MemoryAccounts implements AccountDirectory {
+    readonly accounts: Map<string, AccountStanding>;
+    /** Adds or replaces an account. */
+    set(account: AccountStanding): this;
+    find(userId: string): Promise<AccountStanding | undefined>;
+}
+/** An in-memory rate counter with fixed windows that the clock moves. */
+export declare class MemoryRateCounter implements RateCounter {
+    #private;
+    constructor(clock: AuthClock);
+    consume(key: string, windowMs: number, limit: number): Promise<boolean>;
+    clear(key: string): Promise<void>;
+}
+/** Options for a spec: one fresh signing key, in-memory stores and a fake clock. Override any field. */
+export declare const testAuthOptions: (overrides?: Partial<Omit<AuthOptions, "clock" | "sessions" | "accounts">>) => AuthOptions & {
+    readonly clock: FakeClock;
+    readonly sessions: MemorySessionStore;
+    readonly accounts: MemoryAccounts;
+};