@starci/auth 0.0.0-stage → 0.2.0

package/dist/contracts/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 declare const AUTH_PREFIX = "auth";
+/** The REST doors of sign-in, relative to the API origin. */
+export declare const AUTH_DOORS: {
+    readonly login: "/auth/login";
+    readonly signup: "/auth/signup";
+    readonly resend: "/auth/resend";
+    readonly confirm: "/auth/confirm";
+    readonly refresh: "/auth/refresh";
+    readonly session: "/auth/session";
+    readonly logout: "/auth/logout";
+    readonly forgot: "/auth/forgot";
+    readonly reset: "/auth/reset";
+    readonly google: "/auth/google";
+    readonly googleCallback: "/auth/google/callback";
+    readonly jwks: "/auth/jwks";
+};
+/** The name of one door. */
+export type AuthDoorName = keyof typeof AUTH_DOORS;
+/** The `role` claim every access token carries; any other role is refused. */
+export declare const AUTH_ROLE = "authenticated";
+/** The audience every access token names. */
+export declare const AUTH_AUDIENCE = "authenticated";
+/** The claim names of an access token beyond the registered ones. */
+export declare const AUTH_CLAIMS: {
+    readonly role: "role";
+    readonly sessionId: "session_id";
+    readonly email: "email";
+};
+/** The signature algorithm of every access token: pinned, never negotiated. */
+export declare const AUTH_ALGORITHM = "EdDSA";
+/** The codes the doors answer on the wire; the front end maps them to its sentences. */
+export declare const AUTH_ERROR_CODES: {
+    readonly Unauthenticated: "IDENTITY_UNAUTHENTICATED";
+    readonly AccessTokenInvalid: "PASSPORT_ACCESS_TOKEN_INVALID";
+    readonly KeyInvalid: "PASSPORT_KEY_INVALID";
+    readonly MissingCredentials: "PASSPORT_MISSING_CREDENTIALS";
+    readonly GoogleStateInvalid: "PASSPORT_GOOGLE_STATE_INVALID";
+    readonly GoogleRejected: "PASSPORT_GOOGLE_REJECTED";
+    readonly GoogleUnavailable: "PASSPORT_GOOGLE_UNAVAILABLE";
+    readonly RefreshInvalid: "IDENTITY_REFRESH_INVALID";
+    readonly RefreshReused: "IDENTITY_REFRESH_REUSED";
+    readonly AccountDisabled: "IDENTITY_ACCOUNT_DISABLED";
+    readonly TooManyAttempts: "IDENTITY_TOO_MANY_ATTEMPTS";
+    readonly InvalidCredentials: "IDENTITY_INVALID_CREDENTIALS";
+    readonly EmailNotConfirmed: "IDENTITY_EMAIL_NOT_CONFIRMED";
+    readonly PasswordInvalid: "IDENTITY_PASSWORD_INVALID";
+    readonly ResetTokenInvalid: "IDENTITY_RESET_TOKEN_INVALID";
+};
+/** One wire code of sign-in. */
+export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[keyof typeof AUTH_ERROR_CODES];
+/** How a code travels: the family of status the transport maps it to. */
+export type AuthErrorKind = "unauthenticated" | "forbidden" | "invalid" | "rate-limited" | "internal" | "unavailable";
+/** The kind of every code. */
+export declare const AUTH_ERROR_KINDS: Readonly<Record<AuthErrorCode, AuthErrorKind>>;
+/** The person a session belongs to. */
+export interface SessionUser {
+    /** The user id. */
+    readonly id: string;
+    /** The account email. */
+    readonly email: string;
+}
+/** What a sign-in, refresh or session door answers in the body. */
+export interface AccessGrant {
+    /** The access JWT, to be sent as a Bearer token. */
+    readonly accessToken: string;
+    /** How many seconds the access token lives. */
+    readonly expiresIn: number;
+    /** When the access token stops being accepted, ISO 8601. */
+    readonly expiresAt: string;
+    /** The signed-in person. */
+    readonly user: SessionUser;
+}
+/** The attempts a sign-in budget counts separately. */
+export type AttemptKind = "login" | "reset" | "signup";
+/** One public key of the JWKS document. */
+export type PublicJwk = Readonly<Record<string, string>>;
+/** The public key document served at the JWKS door. */
+export interface JwksDocument {
+    /** The public keys access tokens verify against. */
+    readonly keys: readonly PublicJwk[];
+}
+/** Where the browser goes after the Google round trip. */
+export interface GoogleRedirect {
+    /** The absolute address. */
+    readonly url: string;
+    /** The redirect status. */
+    readonly statusCode: number;
+}
+/** The kinds of failure a front-end call ends with, as the doors' statuses stand for them. */
+export type AuthFailureKind = "refused" | "not-found" | "invalid" | "unavailable";
+/** The outcome of a front-end auth call: a value, or a failure carrying its kind and the wire code. */
+export type AuthOutcome<T> = {
+    readonly success: true;
+    readonly message: "ok";
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly message: AuthFailureKind;
+    readonly error: string;
+};
+/** The facts both sides hold about a password. */
+export declare const PASSWORD_BOUNDS: {
+    readonly min: 8;
+    readonly max: 256;
+    readonly bcryptMaxBytes: 72;
+};

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