@starci/auth 0.0.0-stage → 0.2.0

package/dist/server/primitives.d.ts

@@ -0,0 +1,36 @@
+/** A value read out of a secret holder (the app's `Secret` class has this shape). */
+export interface Revealable {
+    reveal(): string;
+}
+/** A secret given as text or as a holder the app already keeps. */
+export type SecretInput = string | Revealable;
+/** The text of a secret input. */
+export declare const revealed: (secret: SecretInput) => string;
+/** The signed state of one short round trip: the handle, the PKCE verifier, the landing path, the expiry and the purpose. */
+export interface SignedState {
+    readonly w: string;
+    readonly u: string;
+    readonly r: string;
+    readonly e: number;
+    readonly p?: string;
+}
+/** A record: a non-null object that is not an array. */
+export declare const isRecord: (value: unknown) => value is Readonly<Record<string, unknown>>;
+/** A same-site path (one leading slash, no line break), else the fallback path. */
+export declare const sameSitePath: (value: unknown, fallback: string) => string;
+/** Signs a state: base64url(JSON).base64url(HMAC-SHA256). */
+export declare const signStateToken: (key: Buffer, state: SignedState) => string;
+/** The state when the signature is valid, the body is a state and it has not expired at `now`; otherwise null. */
+export declare const verifyStateToken: (key: Buffer, value: string, now: number) => SignedState | null;
+/** The SHA-256 hex of an opaque token or an address; only this form is stored or used as a counter key. */
+export declare const digestOf: (value: string) => string;
+/** The lower-cased, trimmed sign-in address. */
+export declare const normalizeEmail: (email: string) => string;
+/** True when a new password fits the policy: at least 8 characters, at most the 72 bytes bcrypt reads. */
+export declare const isAcceptablePassword: (password: string) => boolean;
+/** True when a presented password can possibly match (bcrypt reads 72 bytes at most); longer input is refused before hashing. */
+export declare const isPresentablePassword: (password: string) => boolean;
+/** True when two texts are equal, compared in constant time over equal-length buffers. */
+export declare const sameValue: (given: string, expected: string) => boolean;
+/** The value of one cookie in a `Cookie` request header (empty text when the header lacks it); the values we write are URL-safe and need no decoding. */
+export declare const cookieValue: (header: string, name: string) => string;

package/dist/server/primitives.js

@@ -0,0 +1,67 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { PASSWORD_BOUNDS } from "../contracts/index.js";
+/** The text of a secret input. */
+export const revealed = (secret) => (typeof secret === "string" ? secret : secret.reveal());
+/** A record: a non-null object that is not an array. */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const SAME_SITE_PATH = /^\/(?![/\\])/u;
+const LINE_BREAK = /[\r\n]/u;
+/** A same-site path (one leading slash, no line break), else the fallback path. */
+export const sameSitePath = (value, fallback) => typeof value === "string" && SAME_SITE_PATH.test(value) && !LINE_BREAK.test(value) ? value : fallback;
+const encode = (buffer) => buffer.toString("base64url");
+const isSignedState = (value) => isRecord(value) &&
+    typeof value.w === "string" &&
+    typeof value.u === "string" &&
+    typeof value.r === "string" &&
+    typeof value.e === "number" &&
+    (value.p === undefined || typeof value.p === "string");
+/** Signs a state: base64url(JSON).base64url(HMAC-SHA256). */
+export const signStateToken = (key, state) => {
+    const body = encode(Buffer.from(JSON.stringify(state)));
+    return `${body}.${encode(createHmac("sha256", key).update(body).digest())}`;
+};
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The state when the signature is valid, the body is a state and it has not expired at `now`; otherwise null. */
+export const verifyStateToken = (key, value, now) => {
+    if (value === "")
+        return null;
+    const [body, signature, extra] = value.split(".");
+    if (body === undefined || body === "" || signature === undefined || signature === "" || extra !== undefined)
+        return null;
+    const expected = createHmac("sha256", key).update(body).digest();
+    const given = Buffer.from(signature, "base64url");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        return null;
+    const state = parseJson(Buffer.from(body, "base64url").toString("utf8"));
+    return isSignedState(state) && state.e >= now ? state : null;
+};
+/** The SHA-256 hex of an opaque token or an address; only this form is stored or used as a counter key. */
+export const digestOf = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+/** The lower-cased, trimmed sign-in address. */
+export const normalizeEmail = (email) => email.trim().toLowerCase();
+/** True when a new password fits the policy: at least 8 characters, at most the 72 bytes bcrypt reads. */
+export const isAcceptablePassword = (password) => Array.from(password).length >= PASSWORD_BOUNDS.min && Buffer.byteLength(password, "utf8") <= PASSWORD_BOUNDS.bcryptMaxBytes;
+/** True when a presented password can possibly match (bcrypt reads 72 bytes at most); longer input is refused before hashing. */
+export const isPresentablePassword = (password) => password.length > 0 && Buffer.byteLength(password, "utf8") <= PASSWORD_BOUNDS.bcryptMaxBytes;
+/** True when two texts are equal, compared in constant time over equal-length buffers. */
+export const sameValue = (given, expected) => {
+    const left = Buffer.from(given);
+    const right = Buffer.from(expected);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+/** The value of one cookie in a `Cookie` request header (empty text when the header lacks it); the values we write are URL-safe and need no decoding. */
+export const cookieValue = (header, name) => {
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator > 0 && part.slice(0, separator).trim() === name)
+            return part.slice(separator + 1).trim();
+    }
+    return "";
+};

package/dist/server/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { AuthClock, AuthIds } from "./ports.js";
+/** The default id source: random UUIDs. */
+export declare const randomIds: AuthIds;
+/** The system clock. */
+export declare const systemClock: AuthClock;

package/dist/server/runtime.js

@@ -0,0 +1,5 @@
+import { randomUUID } from "node:crypto";
+/** The default id source: random UUIDs. */
+export const randomIds = { next: () => randomUUID() };
+/** The system clock. */
+export const systemClock = { now: () => new Date() };

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)),
+};