@starci/auth 0.0.0-stage → 0.1.0

package/dist/contracts/index.js

@@ -0,0 +1,71 @@
+/**
+ * The contract both sides of the sign-in share: the door paths, the wire codes, the claim names and the shapes of the answers.
+ * The server controller and the front-end client read these constants, so a door can never drift between them.
+ */
+/** The path prefix of every auth door. */
+export const AUTH_PREFIX = "auth";
+/** The REST doors of sign-in, relative to the API origin. */
+export const AUTH_DOORS = {
+    login: "/auth/login",
+    signup: "/auth/signup",
+    resend: "/auth/resend",
+    confirm: "/auth/confirm",
+    refresh: "/auth/refresh",
+    session: "/auth/session",
+    logout: "/auth/logout",
+    forgot: "/auth/forgot",
+    reset: "/auth/reset",
+    google: "/auth/google",
+    googleCallback: "/auth/google/callback",
+    jwks: "/auth/jwks",
+};
+/** The `role` claim every access token carries; any other role is refused. */
+export const AUTH_ROLE = "authenticated";
+/** The audience every access token names. */
+export const AUTH_AUDIENCE = "authenticated";
+/** The claim names of an access token beyond the registered ones. */
+export const AUTH_CLAIMS = {
+    role: "role",
+    sessionId: "session_id",
+    email: "email",
+};
+/** The signature algorithm of every access token: pinned, never negotiated. */
+export const AUTH_ALGORITHM = "EdDSA";
+/** The codes the doors answer on the wire; the front end maps them to its sentences. */
+export const AUTH_ERROR_CODES = {
+    Unauthenticated: "IDENTITY_UNAUTHENTICATED",
+    AccessTokenInvalid: "PASSPORT_ACCESS_TOKEN_INVALID",
+    KeyInvalid: "PASSPORT_KEY_INVALID",
+    MissingCredentials: "PASSPORT_MISSING_CREDENTIALS",
+    GoogleStateInvalid: "PASSPORT_GOOGLE_STATE_INVALID",
+    GoogleRejected: "PASSPORT_GOOGLE_REJECTED",
+    GoogleUnavailable: "PASSPORT_GOOGLE_UNAVAILABLE",
+    RefreshInvalid: "IDENTITY_REFRESH_INVALID",
+    RefreshReused: "IDENTITY_REFRESH_REUSED",
+    AccountDisabled: "IDENTITY_ACCOUNT_DISABLED",
+    TooManyAttempts: "IDENTITY_TOO_MANY_ATTEMPTS",
+    InvalidCredentials: "IDENTITY_INVALID_CREDENTIALS",
+    EmailNotConfirmed: "IDENTITY_EMAIL_NOT_CONFIRMED",
+    PasswordInvalid: "IDENTITY_PASSWORD_INVALID",
+    ResetTokenInvalid: "IDENTITY_RESET_TOKEN_INVALID",
+};
+/** The kind of every code. */
+export const AUTH_ERROR_KINDS = {
+    [AUTH_ERROR_CODES.Unauthenticated]: "unauthenticated",
+    [AUTH_ERROR_CODES.AccessTokenInvalid]: "unauthenticated",
+    [AUTH_ERROR_CODES.KeyInvalid]: "internal",
+    [AUTH_ERROR_CODES.MissingCredentials]: "invalid",
+    [AUTH_ERROR_CODES.GoogleStateInvalid]: "unauthenticated",
+    [AUTH_ERROR_CODES.GoogleRejected]: "unauthenticated",
+    [AUTH_ERROR_CODES.GoogleUnavailable]: "unavailable",
+    [AUTH_ERROR_CODES.RefreshInvalid]: "unauthenticated",
+    [AUTH_ERROR_CODES.RefreshReused]: "unauthenticated",
+    [AUTH_ERROR_CODES.AccountDisabled]: "forbidden",
+    [AUTH_ERROR_CODES.TooManyAttempts]: "rate-limited",
+    [AUTH_ERROR_CODES.InvalidCredentials]: "unauthenticated",
+    [AUTH_ERROR_CODES.EmailNotConfirmed]: "forbidden",
+    [AUTH_ERROR_CODES.PasswordInvalid]: "invalid",
+    [AUTH_ERROR_CODES.ResetTokenInvalid]: "invalid",
+};
+/** The facts both sides hold about a password. */
+export const PASSWORD_BOUNDS = { min: 8, max: 256, bcryptMaxBytes: 72 };

package/dist/react/index.d.ts

@@ -0,0 +1,21 @@
+import type { ReactElement, ReactNode } from "react";
+import type { AuthClient, AuthSnapshot } from "../client/index.js";
+/** The props of the provider. */
+export interface AuthProviderProps {
+    /** The one client of the front end (`createAuthClient`). */
+    readonly client: AuthClient;
+    readonly children?: ReactNode;
+}
+/** Makes the client reachable to the hooks below. It draws nothing: it is a context, never a visual. */
+export declare const AuthProvider: ({ client, children }: AuthProviderProps) => ReactElement;
+/** The client of the nearest provider. */
+export declare const useAuthClient: () => AuthClient;
+/** The session snapshot: loading until the first answer (the first subscriber starts it), then signed in or out. */
+export declare const useAuthSession: () => AuthSnapshot;
+/** Calls `onSignedIn` once the session is signed in (a public sign-in page sends a visitor who already has a session on). */
+export declare const useWhenSignedIn: (onSignedIn: () => void) => void;
+/** A resend cooldown: `start()` begins a countdown from `seconds`; `left` is 0 when ready. */
+export declare const useCooldown: (seconds: number, startActive?: boolean) => {
+    readonly left: number;
+    readonly start: () => void;
+};

package/dist/react/index.js

@@ -0,0 +1,42 @@
+import { createContext, createElement, useCallback, useContext, useEffect, useState, useSyncExternalStore } from "react";
+const AuthClientContext = createContext(null);
+/** Makes the client reachable to the hooks below. It draws nothing: it is a context, never a visual. */
+export const AuthProvider = ({ client, children }) => createElement(AuthClientContext.Provider, { value: client }, children);
+/** The client of the nearest provider. */
+export const useAuthClient = () => {
+    const client = useContext(AuthClientContext);
+    if (client === null)
+        throw new Error("useAuthClient needs an AuthProvider above it");
+    return client;
+};
+/** The session snapshot: loading until the first answer (the first subscriber starts it), then signed in or out. */
+export const useAuthSession = () => {
+    const client = useAuthClient();
+    return useSyncExternalStore(client.watch, client.getSnapshot, client.getServerSnapshot);
+};
+/** Calls `onSignedIn` once the session is signed in (a public sign-in page sends a visitor who already has a session on). */
+export const useWhenSignedIn = (onSignedIn) => {
+    const { status } = useAuthSession();
+    useEffect(() => {
+        if (status === "signed-in")
+            onSignedIn();
+    }, [status, onSignedIn]);
+};
+/** A resend cooldown: `start()` begins a countdown from `seconds`; `left` is 0 when ready. */
+export const useCooldown = (seconds, startActive = false) => {
+    const [left, setLeft] = useState(startActive ? seconds : 0);
+    useEffect(() => {
+        if (left <= 0)
+            return undefined;
+        const id = setTimeout(() => {
+            setLeft((current) => current - 1);
+        }, 1000);
+        return () => {
+            clearTimeout(id);
+        };
+    }, [left]);
+    const start = useCallback(() => {
+        setLeft(seconds);
+    }, [seconds]);
+    return { left, start };
+};

package/dist/server/auth.module.d.ts

@@ -0,0 +1,29 @@
+import type { DynamicModule, InjectionToken } from "@nestjs/common";
+import type { AuthOptions } from "./options.js";
+/** The extras every registration sets beside the options. */
+export interface AuthModuleExtras {
+    /** Whether the module is global. */
+    readonly isGlobal: boolean;
+    /**
+     * The provider token of the app's `AuthAuthenticator` (its password and Google decisions). The app's authenticator uses
+     * `AuthPasswords` and `SignInBudget` of this module, so it is resolved by token here, never passed as a built instance.
+     */
+    readonly authenticator: InjectionToken | undefined;
+}
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<AuthOptions, "register", "createAuthOptions", AuthModuleExtras>, MODULE_OPTIONS_TOKEN: string | symbol, OPTIONS_TYPE: AuthOptions & Partial<AuthModuleExtras>, ASYNC_OPTIONS_TYPE: import("@nestjs/common").ConfigurableModuleAsyncOptions<AuthOptions, "createAuthOptions"> & Partial<AuthModuleExtras>;
+/** What `AuthModule.register` takes: the options, plus `isGlobal` and the `authenticator` token. */
+export type AuthRegisterOptions = typeof OPTIONS_TYPE;
+/** What `AuthModule.registerAsync` takes: `imports`, `inject` and one of `useFactory`, `useClass`, `useExisting`, plus `isGlobal` and the `authenticator` token. */
+export type AuthRegisterAsyncOptions = typeof ASYNC_OPTIONS_TYPE;
+/**
+ * The sign-in of a lite app as one Nest capability: the token signer and verifier, the passwords, the sign-in budget, the
+ * rotating sessions, the refresh cookie, the passport flows (local and Google with state and PKCE) and the doors that run them.
+ * Registered once at the api root; the app implements the stores (`SessionStore`, `AccountDirectory`, `RateCounter`) and the
+ * `AuthAuthenticator` over its own tables.
+ */
+export declare class AuthModule extends ConfigurableModuleClass {
+    /** Registers the module from options known now. */
+    static register(options: AuthRegisterOptions): DynamicModule;
+    /** Registers the module from options a factory, class or existing provider supplies. */
+    static registerAsync(options: AuthRegisterAsyncOptions): DynamicModule;
+}

package/dist/server/auth.module.js

@@ -0,0 +1,85 @@
+import { ConfigurableModuleBuilder, Module } from "@nestjs/common";
+import { AuthDoors } from "./doors.js";
+import { RefreshCookie } from "./cookie.js";
+import { AuthFlows } from "./flows.js";
+import { GoogleStateClient } from "./google-state.js";
+import { AuthPasswords } from "./passwords.js";
+import { randomIds, systemClock } from "./runtime.js";
+import { AuthSessions } from "./sessions.js";
+import { PassportGoogleStrategy, PassportLocalStrategy } from "./strategies.js";
+import { AuthTokens } from "./tokens.js";
+import { AuthPrincipalVerifier } from "./verifier.js";
+import { SignInBudget } from "./budget.js";
+import { AUTH_AUTHENTICATOR, AUTH_DOORS_SERVICE, AUTH_FLOWS, AUTH_GOOGLE_STATE, AUTH_GOOGLE_STRATEGY, AUTH_LOCAL_STRATEGY, AUTH_PASSWORDS, AUTH_PRINCIPAL_VERIFIER, AUTH_REFRESH_COOKIE, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET, AUTH_TOKENS, } from "./auth.tokens.js";
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({ moduleName: "Auth" })
+    .setClassMethodName("register")
+    .setFactoryMethodName("createAuthOptions")
+    .setExtras({ isGlobal: false, authenticator: undefined }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build();
+/** The token a registration without an authenticator resolves to: no provider answers it, so the boot fails loudly. */
+const AUTH_AUTHENTICATOR_MISSING = Symbol.for("@starci/auth/authenticator-missing");
+const providers = (authenticator) => [
+    { provide: AUTH_AUTHENTICATOR, useExisting: authenticator ?? AUTH_AUTHENTICATOR_MISSING },
+    { provide: AUTH_TOKENS, inject: [MODULE_OPTIONS_TOKEN], useFactory: (options) => new AuthTokens(options) },
+    { provide: AUTH_PASSWORDS, inject: [MODULE_OPTIONS_TOKEN], useFactory: (options) => new AuthPasswords(options) },
+    {
+        provide: AUTH_SIGN_IN_BUDGET,
+        inject: [MODULE_OPTIONS_TOKEN],
+        useFactory: (options) => new SignInBudget(options.budget, options.rate),
+    },
+    {
+        provide: AUTH_SESSIONS,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_TOKENS],
+        useFactory: (options, tokens) => new AuthSessions({ options, tokens, clock: options.clock ?? systemClock, ids: options.ids ?? randomIds, logger: options.logger }),
+    },
+    { provide: AUTH_REFRESH_COOKIE, inject: [MODULE_OPTIONS_TOKEN], useFactory: (options) => new RefreshCookie(options.cookie) },
+    {
+        provide: AUTH_GOOGLE_STATE,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_TOKENS],
+        useFactory: (options, tokens) => new GoogleStateClient({ tokens, clock: options.clock ?? systemClock, ids: options.ids ?? randomIds, options }),
+    },
+    { provide: AUTH_FLOWS, inject: [MODULE_OPTIONS_TOKEN], useFactory: (options) => new AuthFlows(options) },
+    {
+        provide: AUTH_LOCAL_STRATEGY,
+        inject: [AUTH_AUTHENTICATOR],
+        useFactory: (authenticator) => new PassportLocalStrategy(authenticator),
+    },
+    {
+        provide: AUTH_GOOGLE_STRATEGY,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_AUTHENTICATOR, AUTH_GOOGLE_STATE],
+        useFactory: (options, authenticator, state) => options.google === null ? null : new PassportGoogleStrategy(options.google, authenticator, state),
+    },
+    {
+        provide: AUTH_DOORS_SERVICE,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_FLOWS, AUTH_SESSIONS, AUTH_REFRESH_COOKIE],
+        useFactory: (options, flows, sessions, cookie) => new AuthDoors({ flows, sessions, cookie, returnOrigin: options.returnOrigin, logger: options.logger }),
+    },
+    {
+        provide: AUTH_PRINCIPAL_VERIFIER,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_TOKENS],
+        useFactory: (options, tokens) => new AuthPrincipalVerifier(tokens, options.clock ?? systemClock),
+    },
+];
+const EXPORTED = [AUTH_TOKENS, AUTH_PASSWORDS, AUTH_SIGN_IN_BUDGET, AUTH_SESSIONS, AUTH_REFRESH_COOKIE, AUTH_FLOWS, AUTH_DOORS_SERVICE, AUTH_PRINCIPAL_VERIFIER];
+const withProviders = (base, authenticator) => ({
+    ...base,
+    providers: [...(base.providers ?? []), ...providers(authenticator)],
+    exports: [...(base.exports ?? []), ...EXPORTED],
+});
+/**
+ * The sign-in of a lite app as one Nest capability: the token signer and verifier, the passwords, the sign-in budget, the
+ * rotating sessions, the refresh cookie, the passport flows (local and Google with state and PKCE) and the doors that run them.
+ * Registered once at the api root; the app implements the stores (`SessionStore`, `AccountDirectory`, `RateCounter`) and the
+ * `AuthAuthenticator` over its own tables.
+ */
+export class AuthModule extends ConfigurableModuleClass {
+    /** Registers the module from options known now. */
+    static register(options) {
+        return withProviders(super.register(options), options.authenticator);
+    }
+    /** Registers the module from options a factory, class or existing provider supplies. */
+    static registerAsync(options) {
+        return withProviders(super.registerAsync(options), options.authenticator);
+    }
+}
+Module({})(AuthModule);

package/dist/server/auth.tokens.d.ts

@@ -0,0 +1,24 @@
+/** Token of the app's authenticator (resolved from the token the registration names). */
+export declare const AUTH_AUTHENTICATOR: unique symbol;
+/** Token of `AuthTokens`, the access-token signer and verifier. */
+export declare const AUTH_TOKENS: unique symbol;
+/** Token of `AuthPasswords`. */
+export declare const AUTH_PASSWORDS: unique symbol;
+/** Token of `SignInBudget`. */
+export declare const AUTH_SIGN_IN_BUDGET: unique symbol;
+/** Token of `AuthSessions`, the rotating device sessions. */
+export declare const AUTH_SESSIONS: unique symbol;
+/** Token of `RefreshCookie`. */
+export declare const AUTH_REFRESH_COOKIE: unique symbol;
+/** Token of the Google round-trip state store. */
+export declare const AUTH_GOOGLE_STATE: unique symbol;
+/** Token of `AuthFlows`, the passport strategy runs. */
+export declare const AUTH_FLOWS: unique symbol;
+/** Token of the local passport strategy (registered with passport when constructed). */
+export declare const AUTH_LOCAL_STRATEGY: unique symbol;
+/** Token of the Google passport strategy, or null when the deployment has no Google client. */
+export declare const AUTH_GOOGLE_STRATEGY: unique symbol;
+/** Token of `AuthDoors`, what a controller calls. */
+export declare const AUTH_DOORS_SERVICE: unique symbol;
+/** Token of the `PrincipalVerifier` the identity domain injects. */
+export declare const AUTH_PRINCIPAL_VERIFIER: unique symbol;

package/dist/server/auth.tokens.js

@@ -0,0 +1,24 @@
+/** Token of the app's authenticator (resolved from the token the registration names). */
+export const AUTH_AUTHENTICATOR = Symbol.for("@starci/auth/authenticator");
+/** Token of `AuthTokens`, the access-token signer and verifier. */
+export const AUTH_TOKENS = Symbol.for("@starci/auth/tokens");
+/** Token of `AuthPasswords`. */
+export const AUTH_PASSWORDS = Symbol.for("@starci/auth/passwords");
+/** Token of `SignInBudget`. */
+export const AUTH_SIGN_IN_BUDGET = Symbol.for("@starci/auth/sign-in-budget");
+/** Token of `AuthSessions`, the rotating device sessions. */
+export const AUTH_SESSIONS = Symbol.for("@starci/auth/sessions");
+/** Token of `RefreshCookie`. */
+export const AUTH_REFRESH_COOKIE = Symbol.for("@starci/auth/refresh-cookie");
+/** Token of the Google round-trip state store. */
+export const AUTH_GOOGLE_STATE = Symbol.for("@starci/auth/google-state");
+/** Token of `AuthFlows`, the passport strategy runs. */
+export const AUTH_FLOWS = Symbol.for("@starci/auth/flows");
+/** Token of the local passport strategy (registered with passport when constructed). */
+export const AUTH_LOCAL_STRATEGY = Symbol.for("@starci/auth/local-strategy");
+/** Token of the Google passport strategy, or null when the deployment has no Google client. */
+export const AUTH_GOOGLE_STRATEGY = Symbol.for("@starci/auth/google-strategy");
+/** Token of `AuthDoors`, what a controller calls. */
+export const AUTH_DOORS_SERVICE = Symbol.for("@starci/auth/doors");
+/** Token of the `PrincipalVerifier` the identity domain injects. */
+export const AUTH_PRINCIPAL_VERIFIER = Symbol.for("@starci/auth/principal-verifier");

package/dist/server/budget.d.ts

@@ -0,0 +1,21 @@
+import type { AttemptKind } from "../contracts/index.js";
+import type { BudgetOptions } from "./options.js";
+import type { RateCounter } from "./ports.js";
+/**
+ * Counts sign-in, reset and signup attempts per address in a window every replica shares, and refuses an address over its
+ * limit. A sign-in budget is a budget of failures: the password check that succeeds clears the count of its address, so good
+ * sign-ins never lock an account out.
+ */
+export declare class SignInBudget {
+    #private;
+    constructor(options: BudgetOptions, rate: RateCounter);
+    /** Counts one attempt of this kind for an address (hashed in the counter key); throws when the address is over its limit. */
+    admit(kind: AttemptKind, address: string): Promise<void>;
+    /** Forgets the attempts of this kind counted for an address: its password was proved right, so earlier failures no longer weigh on it. */
+    clear(kind: AttemptKind, address: string): Promise<void>;
+    /** Admits one attempt, runs the check, and clears the address when the check passes; only failures stay counted. */
+    counted<T>(kind: AttemptKind, address: string, check: () => Promise<{
+        readonly passed: boolean;
+        readonly value: T;
+    }>): Promise<T>;
+}

package/dist/server/budget.js

@@ -0,0 +1,38 @@
+import { AUTH_ERROR_CODES } from "../contracts/index.js";
+import { AuthError } from "./errors.js";
+import { digestOf } from "./primitives.js";
+/**
+ * Counts sign-in, reset and signup attempts per address in a window every replica shares, and refuses an address over its
+ * limit. A sign-in budget is a budget of failures: the password check that succeeds clears the count of its address, so good
+ * sign-ins never lock an account out.
+ */
+export class SignInBudget {
+    #options;
+    #rate;
+    constructor(options, rate) {
+        this.#options = options;
+        this.#rate = rate;
+    }
+    /** Counts one attempt of this kind for an address (hashed in the counter key); throws when the address is over its limit. */
+    async admit(kind, address) {
+        const limit = kind === "login" ? this.#options.loginAttempts : this.#options.resetAttempts;
+        const allowed = await this.#rate.consume(this.#keyOf(kind, address), this.#options.windowMs, limit);
+        if (!allowed)
+            throw new AuthError(AUTH_ERROR_CODES.TooManyAttempts);
+    }
+    /** Forgets the attempts of this kind counted for an address: its password was proved right, so earlier failures no longer weigh on it. */
+    async clear(kind, address) {
+        await this.#rate.clear(this.#keyOf(kind, address));
+    }
+    /** Admits one attempt, runs the check, and clears the address when the check passes; only failures stay counted. */
+    async counted(kind, address, check) {
+        await this.admit(kind, address);
+        const result = await check();
+        if (result.passed)
+            await this.clear(kind, address);
+        return result.value;
+    }
+    #keyOf(kind, address) {
+        return `${kind}:${digestOf(address)}`;
+    }
+}

package/dist/server/cookie.d.ts

@@ -0,0 +1,19 @@
+import type { HttpRequest, HttpResponse } from "./http.js";
+import type { RefreshCookieOptions } from "./options.js";
+import type { DeviceMeta, SessionTokens } from "./ports.js";
+/**
+ * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the configured domain so the web
+ * app and the API both see it. The token only ever leaves the back end through this cookie, never in a body or a URL.
+ */
+export declare class RefreshCookie {
+    #private;
+    constructor(options: RefreshCookieOptions);
+    /** The refresh token the browser sent (empty text when there is none). */
+    read(request: HttpRequest): string;
+    /** The device a request comes from: its user agent (bounded) and caller address. */
+    deviceOf(request: HttpRequest): DeviceMeta;
+    /** Sets the cookie to the refresh token of a session, clearing the copies older sessions kept under their paths. */
+    issue(response: HttpResponse, tokens: SessionTokens): void;
+    /** Clears the cookie on its path and on the paths older sessions used. */
+    clear(response: HttpResponse): void;
+}

package/dist/server/cookie.js

@@ -0,0 +1,54 @@
+import { cookieValue } from "./primitives.js";
+const MAX_AGENT_LENGTH = 512;
+const MILLISECONDS = 1000;
+/**
+ * The refresh cookie: httpOnly and Secure on every write and clear, SameSite lax (or strict), on the configured domain so the web
+ * app and the API both see it. The token only ever leaves the back end through this cookie, never in a body or a URL.
+ */
+export class RefreshCookie {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The refresh token the browser sent (empty text when there is none). */
+    read(request) {
+        const header = request.headers.cookie;
+        return cookieValue(Array.isArray(header) ? header.join("; ") : (header ?? ""), this.#options.name);
+    }
+    /** The device a request comes from: its user agent (bounded) and caller address. */
+    deviceOf(request) {
+        const agent = request.headers["user-agent"];
+        const text = Array.isArray(agent) ? agent[0] : agent;
+        return { userAgent: text?.slice(0, MAX_AGENT_LENGTH) ?? null, ip: request.ip ?? null };
+    }
+    /** Sets the cookie to the refresh token of a session, clearing the copies older sessions kept under their paths. */
+    issue(response, tokens) {
+        for (const path of this.#legacyPaths())
+            response.clearCookie(this.#options.name, this.#flags(path));
+        response.cookie(this.#options.name, tokens.cookieToken, {
+            ...this.#flags(this.#path()),
+            maxAge: tokens.refreshMaxAgeSeconds * MILLISECONDS,
+        });
+    }
+    /** Clears the cookie on its path and on the paths older sessions used. */
+    clear(response) {
+        for (const path of [this.#path(), ...this.#legacyPaths()])
+            response.clearCookie(this.#options.name, this.#flags(path));
+    }
+    #path() {
+        return this.#options.path ?? "/";
+    }
+    #legacyPaths() {
+        return (this.#options.legacyPaths ?? ["/auth"]).filter((path) => path !== this.#path());
+    }
+    #flags(path) {
+        const domain = this.#options.domain;
+        return {
+            httpOnly: true,
+            secure: true,
+            sameSite: this.#options.sameSite ?? "lax",
+            path,
+            ...(domain === undefined ? {} : { domain }),
+        };
+    }
+}

package/dist/server/doors.d.ts

@@ -0,0 +1,44 @@
+import type { AccessGrant, GoogleRedirect } from "../contracts/index.js";
+import type { RefreshCookie } from "./cookie.js";
+import type { AuthFlows } from "./flows.js";
+import type { HttpExchange } from "./http.js";
+import type { AuthLogger, SessionTokens } from "./ports.js";
+import type { AuthSessions } from "./sessions.js";
+/** The status of the Google callback redirect. */
+export declare const SEE_OTHER = 303;
+/** The log event of a failed Google sign-in. */
+export declare const GOOGLE_SIGN_IN_FAILED_EVENT = "auth.google-sign-in-failed";
+/** The body a sign-in, refresh or session door answers. */
+export declare const accessOf: (tokens: SessionTokens) => AccessGrant;
+/** What the doors need. */
+export interface DoorsDeps {
+    readonly flows: AuthFlows;
+    readonly sessions: AuthSessions;
+    readonly cookie: RefreshCookie;
+    readonly returnOrigin: string;
+    readonly logger?: AuthLogger | undefined;
+}
+/**
+ * The cookie doors of sign-in over the flows, the sessions and the cookie: what a controller calls. The refresh token only goes
+ * into the cookie; a refresh that cannot be used clears it, one a sibling request just rotated leaves it as the sibling wrote it.
+ */
+export declare class AuthDoors {
+    #private;
+    constructor(deps: DoorsDeps);
+    /** Email and password through the local strategy; the refresh token goes into the cookie. */
+    login(exchange: HttpExchange): Promise<AccessGrant>;
+    /** Rotates the cookie token and answers a new access token; a cookie that cannot be used is cleared and the refusal rethrown. */
+    refresh(exchange: HttpExchange): Promise<AccessGrant>;
+    /** Answers a fresh access token for the cookie session without rotating the cookie. */
+    session(exchange: HttpExchange): Promise<AccessGrant>;
+    /** Ends the session of the cookie and clears it. */
+    logout(exchange: HttpExchange): Promise<void>;
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange: HttpExchange): Promise<void>;
+    /**
+     * Finishes the Google round trip: state, PKCE and profile are verified, the account found, linked or created, its session opened
+     * and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a redirect-only door has
+     * nowhere to show an error body.
+     */
+    completeGoogle(exchange: HttpExchange): Promise<GoogleRedirect>;
+}

package/dist/server/doors.js

@@ -0,0 +1,72 @@
+/** The status of the Google callback redirect. */
+export const SEE_OTHER = 303;
+/** The log event of a failed Google sign-in. */
+export const GOOGLE_SIGN_IN_FAILED_EVENT = "auth.google-sign-in-failed";
+/** The body a sign-in, refresh or session door answers. */
+export const accessOf = (tokens) => ({
+    accessToken: tokens.accessToken,
+    expiresIn: tokens.accessExpiresIn,
+    expiresAt: tokens.accessExpiresAt,
+    user: tokens.user,
+});
+/**
+ * The cookie doors of sign-in over the flows, the sessions and the cookie: what a controller calls. The refresh token only goes
+ * into the cookie; a refresh that cannot be used clears it, one a sibling request just rotated leaves it as the sibling wrote it.
+ */
+export class AuthDoors {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /** Email and password through the local strategy; the refresh token goes into the cookie. */
+    async login(exchange) {
+        const subject = await this.#deps.flows.authenticateLocal(exchange);
+        const tokens = await this.#deps.sessions.start(subject, this.#deps.cookie.deviceOf(exchange.req));
+        this.#deps.cookie.issue(exchange.res, tokens);
+        return accessOf(tokens);
+    }
+    /** Rotates the cookie token and answers a new access token; a cookie that cannot be used is cleared and the refusal rethrown. */
+    async refresh(exchange) {
+        try {
+            const tokens = await this.#deps.sessions.refresh(this.#deps.cookie.read(exchange.req));
+            if (tokens.cookieKept !== true)
+                this.#deps.cookie.issue(exchange.res, tokens);
+            return accessOf(tokens);
+        }
+        catch (cause) {
+            this.#deps.cookie.clear(exchange.res);
+            throw cause;
+        }
+    }
+    /** Answers a fresh access token for the cookie session without rotating the cookie. */
+    async session(exchange) {
+        return accessOf(await this.#deps.sessions.access(this.#deps.cookie.read(exchange.req)));
+    }
+    /** Ends the session of the cookie and clears it. */
+    async logout(exchange) {
+        await this.#deps.sessions.end(this.#deps.cookie.read(exchange.req));
+        this.#deps.cookie.clear(exchange.res);
+    }
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange) {
+        return this.#deps.flows.beginGoogle(exchange);
+    }
+    /**
+     * Finishes the Google round trip: state, PKCE and profile are verified, the account found, linked or created, its session opened
+     * and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a redirect-only door has
+     * nowhere to show an error body.
+     */
+    async completeGoogle(exchange) {
+        try {
+            const completion = await this.#deps.flows.completeGoogle(exchange);
+            const tokens = await this.#deps.sessions.start(completion.subject, this.#deps.cookie.deviceOf(exchange.req));
+            this.#deps.cookie.issue(exchange.res, tokens);
+            return { url: `${this.#deps.returnOrigin}${completion.next}`, statusCode: SEE_OTHER };
+        }
+        catch (cause) {
+            this.#deps.cookie.clear(exchange.res);
+            this.#deps.logger?.warn(GOOGLE_SIGN_IN_FAILED_EVENT, { cause: String(cause) });
+            return { url: `${this.#deps.returnOrigin}/sign-in?auth=error`, statusCode: SEE_OTHER };
+        }
+    }
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,24 @@
+import type { AuthErrorCode, AuthErrorKind } from "../contracts/index.js";
+/** The one error class of sign-in: a wire code, the kind it travels as and optional context for the log. */
+export declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly kind: AuthErrorKind;
+    readonly context: Readonly<Record<string, unknown>>;
+    constructor(code: AuthErrorCode, options?: {
+        readonly cause?: unknown;
+        readonly context?: Readonly<Record<string, unknown>>;
+    });
+}
+/** The result of a check that can refuse with a code. */
+export type Outcome<T, E extends string = AuthErrorCode> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "refused";
+    readonly code: E;
+    readonly detail?: Readonly<Record<string, unknown>>;
+};
+/** An accepted outcome. */
+export declare const ok: <T>(value: T) => Outcome<T, never>;
+/** A refused outcome. */
+export declare const refused: <E extends string>(code: E, detail?: Readonly<Record<string, unknown>>) => Outcome<never, E>;

package/dist/server/errors.js

@@ -0,0 +1,18 @@
+import { AUTH_ERROR_KINDS } from "../contracts/index.js";
+/** The one error class of sign-in: a wire code, the kind it travels as and optional context for the log. */
+export class AuthError extends Error {
+    code;
+    kind;
+    context;
+    constructor(code, options = {}) {
+        super(code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "AuthError";
+        this.code = code;
+        this.kind = AUTH_ERROR_KINDS[code];
+        this.context = options.context ?? {};
+    }
+}
+/** An accepted outcome. */
+export const ok = (value) => ({ kind: "ok", value });
+/** A refused outcome. */
+export const refused = (code, detail) => detail === undefined ? { kind: "refused", code } : { kind: "refused", code, detail };

package/dist/server/flows.d.ts

@@ -0,0 +1,21 @@
+import type { HttpExchange } from "./http.js";
+import type { AuthOptions } from "./options.js";
+import type { AuthSubject } from "./ports.js";
+/** The result of the Google callback leg. */
+export interface GoogleCompletion {
+    /** The signed-in person. */
+    readonly subject: AuthSubject;
+    /** The same-site path the browser lands on. */
+    readonly next: string;
+}
+/** Runs the passport strategies for one request without sessions; the only caller of `passport.authenticate`. */
+export declare class AuthFlows {
+    #private;
+    constructor(options: Pick<AuthOptions, "google">);
+    /** Runs the local strategy over the posted body; answers the person, or throws the app's refusal. */
+    authenticateLocal(exchange: HttpExchange): Promise<AuthSubject>;
+    /** Sends the browser to the Google consent screen (the response is the redirect); the optional `next` query value is kept in the state cookie. */
+    beginGoogle(exchange: HttpExchange): Promise<void>;
+    /** Finishes the Google round trip: the state cookie, the PKCE verifier and the profile must all check out. */
+    completeGoogle(exchange: HttpExchange): Promise<GoogleCompletion>;
+}