@starci/auth 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - 2026-11-03
+
+The sign-in of a lite StarCi app in one package, lifted from the product that ran it in production and generalised: no product names, every setting a typed option, no environment read.
+
+- Added: `@starci/auth/server`, the NestJS module `AuthModule.register` / `registerAsync`. `AuthTokens` signs and verifies EdDSA access tokens (the algorithm pinned, issuer, audience, `role` and `session_id` claims, a `kid` from the key or its RFC 7638 thumbprint) over a key set: one signing key and any number of retired keys, all verified and all published by `jwks()`, so a key rotates without signing anybody out. `AuthSessions` opens device sessions and rotates the refresh token on every refresh with reuse detection: a spent token replayed inside the grace window (30 seconds) is a racing tab and is answered with an access token and no rotation (`cookieKept`), an older replay ends the session. `SignInBudget` counts sign-in failures only (a right password clears its address). `RefreshCookie` writes the httpOnly, Secure, SameSite cookie with a configurable name, domain, path and legacy paths. `AuthFlows` runs the passport local and Google strategies (state and PKCE in a signed cookie, a same-site landing path only). `AuthDoors` is what a controller calls. `AuthPasswords` is the one owner of bcrypt. `AuthPrincipalVerifier` implements `PrincipalVerifier`, the interface the identity domain injects.
+- Added: ports the app implements over its own tables: `SessionStore`, `AccountDirectory`, `RateCounter`, `AuthAuthenticator`.
+- Added: `migrations/identity-sessions.sql`, the session tables (`identity_sessions`, `identity_refresh_tokens`) and the sign-in attempt counter (`identity_attempts`) the starter renders.
+- Added: `@starci/auth/contracts`, the door paths, wire codes, claim names and answer shapes both sides read.
+- Added: `@starci/auth/client`, `createAuthClient`: the access token in memory only, one shared refresh for overlapping callers with refresh-ahead, retries of 429, 5xx and a lost connection with backoff, signed out only on 401 or 403, an event listener and a stable snapshot, the server-side `checkSession`. `@starci/auth/client/react` holds `AuthProvider` (a context that draws nothing), `useAuthSession`, `useAuthClient`, `useWhenSignedIn` and `useCooldown`.
+- Added: `@starci/auth/testing`, test keys, a fake clock, in-memory stores and `testAuthOptions`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 starci183
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @starci/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The sign-in of a lite StarCi app: one package, four entries.
+
+| entry | holds |
+|---|---|
+| `@starci/auth/server` | the NestJS module (`AuthModule.register` / `registerAsync`), the token signer and verifier (EdDSA, multi-key JWKS), rotating sessions, the sign-in budget, the refresh cookie, the passport flows and the doors that run them |
+| `@starci/auth/client` | `createAuthClient`: access token in memory, one shared refresh, signed out only on 401 or 403 |
+| `@starci/auth/client/react` | `AuthProvider`, `useAuthSession`, `useAuthClient`, `useWhenSignedIn`, `useCooldown` (context and hooks over the client; no visual) |
+| `@starci/auth/contracts` | door paths, wire codes, claim names and answer shapes both sides read |
+| `@starci/auth/testing` | test keys, a fake clock, in-memory stores, `testAuthOptions` |
+
+An app reaches the package only through `integrations/passport` (back end) and `modules/auth/client.ts` (front end); the lint refuses `passport*`, `jose`, `bcryptjs` and `@nestjs/jwt` in an app.
+
+## Back end
+
+```ts
+AuthModule.registerAsync({
+    isGlobal: true,
+    authenticator: IDENTITY_AUTHENTICATOR, // the token of the app's AuthAuthenticator, resolved from a global module
+    inject: [SESSION_STORE, ACCOUNT_DIRECTORY, RATE_LIMIT_STORE],
+    useFactory: (sessions, accounts, rate) => ({ ...parsedOptions, sessions, accounts, rate }),
+})
+```
+
+The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; secrets are passed as `{ reveal(): string }` holders or text. The app implements `SessionStore` over the tables of `migrations/identity-sessions.sql`, `AccountDirectory` over its user table, `RateCounter` over its shared counter, and `AuthAuthenticator` (the password and Google decisions) using `AuthPasswords` and `SignInBudget.counted` from the module.
+
+Key rotation: list the new key first with its private key, keep the old key with its public key only, deploy, and drop the old key once its access tokens have expired. Every listed key verifies and is published by `AuthSessions.jwks()`.
+
+## Front end
+
+```ts
+// modules/auth/client.ts: the one instance
+export const auth = createAuthClient({ apiOrigin: () => apiOrigin() })
+```
+
+## Tests
+
+`npm test` typechecks, lints and runs the `node:test` specs under 90% line coverage.

package/dist/client/auth-client.d.ts

@@ -0,0 +1,70 @@
+import type { AccessGrant, AuthDoorName, AuthOutcome, SessionUser } from "../contracts/index.js";
+import type { StatusCodes } from "./outcome.js";
+/** What a door answered. A refusal is an answer, not a throw: the status says what happened. */
+export interface AuthDoorAnswer {
+    readonly status: number;
+    readonly body: unknown;
+}
+/** The event a listener hears. */
+export type AuthEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+/** Called on every sign-in, sign-out and token refresh with the id of the person the session belongs to (null when signed out). */
+export type AuthListener = (event: AuthEvent, userId: string | null) => void;
+/** What a view reads: loading until the first answer, then signed in or out. The object changes only when the session does. */
+export interface AuthSnapshot {
+    readonly status: "loading" | "signed-in" | "signed-out";
+    readonly user: SessionUser | null;
+}
+/** The options of the client. */
+export interface AuthClientOptions {
+    /** The API origin the doors live on. */
+    readonly apiOrigin: string | (() => string);
+    /** The fetch to use (the global one when absent). */
+    readonly fetch?: typeof fetch | undefined;
+    /** Refresh this long before the token really expires, so a request never carries a dying one (15 seconds). */
+    readonly refreshAheadMs?: number | undefined;
+    /** Tries a refresh makes before it gives up on a busy or unreachable back end (4). */
+    readonly retryAttempts?: number | undefined;
+    /** The base of the linear backoff between tries, in milliseconds (400). */
+    readonly retryBaseMs?: number | undefined;
+    /** The clock in milliseconds (`Date.now`). */
+    readonly now?: (() => number) | undefined;
+    /** The pause between tries (a timer). */
+    readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+/** The front-end client of the auth doors: the access token lives in this closure's memory only, never in storage or a cookie. */
+export interface AuthClient {
+    /** Calls a door with the credentials of the browser; a transport failure rejects, any answer resolves. `cookie` is the header a server forwards. */
+    door(name: AuthDoorName, body?: object, cookie?: string): Promise<AuthDoorAnswer>;
+    /** Signs in with email and password and keeps the grant; a refusal is an outcome. */
+    signIn(body: object): Promise<AuthOutcome<SessionUser>>;
+    /** Calls a door that returns no grant (signup, resend, confirm, forgot, reset) and maps its answer to an outcome. */
+    send(name: AuthDoorName, body: object, fallbacks?: StatusCodes): Promise<AuthOutcome<unknown>>;
+    /** Ends the session of the cookie and forgets the token; the token is forgotten even when the door cannot be reached. */
+    signOut(): Promise<void>;
+    /** Refreshes through the httpOnly cookie. Overlapping calls share one refresh. `undefined` when it cannot be refreshed. */
+    renew(): Promise<string | undefined>;
+    /** The access token of the current session, refreshed when missing or about to expire; `undefined` when signed out. */
+    accessToken(): Promise<string | undefined>;
+    /** The held access token without any request. */
+    peek(): string | undefined;
+    /** The signed-in person (id and email), or null when signed out. */
+    user(): Promise<SessionUser | null>;
+    /** The `Authorization` header of the current session (an empty object when signed out). */
+    headers(): Promise<Record<string, string>>;
+    /** Keeps a grant a door answered (an OAuth landing, a sign-in the app ran itself) and announces it. */
+    keep(grant: AccessGrant, event?: AuthEvent): void;
+    /** Forgets the token (sign-out, or a refresh the back end refused). */
+    drop(): void;
+    /** Listens to auth events; the first answer comes from a refresh. Answers the function that stops listening. */
+    subscribe(listener: AuthListener): () => void;
+    /** The current snapshot (stable between changes). */
+    getSnapshot: () => AuthSnapshot;
+    /** The snapshot for server rendering: always loading. */
+    getServerSnapshot: () => AuthSnapshot;
+    /** Calls `onChange` when the snapshot changes (the shape `useSyncExternalStore` takes). */
+    watch: (onChange: () => void) => () => void;
+    /** Asks the back end whether the given `Cookie` header holds a live session (server side); the door does not rotate the cookie. */
+    checkSession(cookie: string | null): Promise<AuthOutcome<true>>;
+}
+/** Creates the one auth client of a front end (one instance, like the event stream). */
+export declare const createAuthClient: (options: AuthClientOptions) => AuthClient;

package/dist/client/auth-client.js

@@ -0,0 +1,225 @@
+import { AUTH_DOORS } from "../contracts/index.js";
+import { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientStatus } from "./outcome.js";
+const LOADING = { status: "loading", user: null };
+const isGrant = (value) => typeof value === "object" &&
+    value !== null &&
+    "accessToken" in value &&
+    typeof value.accessToken === "string" &&
+    "expiresIn" in value &&
+    typeof value.expiresIn === "number";
+const fieldOf = (value, key) => typeof value === "object" && value !== null ? Object.entries(value).find(([name]) => name === key)?.[1] : undefined;
+const claimsOf = (token) => {
+    const payload = token.split(".")[1];
+    if (payload === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(atob(payload.replaceAll("-", "+").replaceAll("_", "/")));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+const userOf = (grant) => {
+    if (typeof grant.user === "object" && typeof grant.user.id === "string")
+        return { id: grant.user.id, email: typeof grant.user.email === "string" ? grant.user.email : "" };
+    const { sub, email } = claimsOf(grant.accessToken);
+    return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "" } : null;
+};
+const MILLISECONDS = 1000;
+const timerPause = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(() => {
+        clearTimeout(timer);
+        resolve();
+    }, ms);
+});
+/** Creates the one auth client of a front end (one instance, like the event stream). */
+export const createAuthClient = (options) => {
+    const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+    const refreshAheadMs = options.refreshAheadMs ?? 15_000;
+    const attemptsMax = options.retryAttempts ?? 4;
+    const retryBaseMs = options.retryBaseMs ?? 400;
+    const now = options.now ?? Date.now;
+    const pause = options.sleep ?? timerPause;
+    const originOf = () => (typeof options.apiOrigin === "string" ? options.apiOrigin : options.apiOrigin());
+    let token;
+    let expiresAt = 0;
+    let announced = false;
+    let user = null;
+    let inFlight;
+    let snapshot = LOADING;
+    const listeners = new Set();
+    const watchers = new Set();
+    const setSnapshot = (next) => {
+        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email)
+            return;
+        snapshot = next;
+        for (const watcher of watchers)
+            watcher();
+    };
+    const notify = (event) => {
+        for (const listener of listeners)
+            listener(event, user?.id ?? null);
+    };
+    const keep = (grant, event = "TOKEN_REFRESHED") => {
+        token = grant.accessToken;
+        expiresAt = now() + grant.expiresIn * MILLISECONDS;
+        announced = true;
+        user = userOf(grant);
+        setSnapshot({ status: "signed-in", user });
+        notify(event);
+    };
+    const drop = () => {
+        const had = token !== undefined;
+        token = undefined;
+        expiresAt = 0;
+        announced = true;
+        user = null;
+        setSnapshot({ status: "signed-out", user: null });
+        if (had)
+            notify("SIGNED_OUT");
+    };
+    const door = async (name, body, cookie) => {
+        const get = name === "session" || name === "jwks";
+        const response = await fetcher(`${originOf()}${AUTH_DOORS[name]}`, {
+            method: get ? "GET" : "POST",
+            credentials: "include",
+            headers: {
+                ...(get ? {} : { "content-type": "application/json" }),
+                ...(cookie === undefined ? {} : { cookie }),
+            },
+            ...(get ? {} : { body: JSON.stringify(body ?? {}) }),
+        });
+        const parsed = await response.json().catch(() => undefined);
+        return { status: response.status, body: parsed };
+    };
+    const refreshEvent = () => {
+        if (!announced)
+            return "INITIAL_SESSION";
+        return token === undefined ? "SIGNED_IN" : "TOKEN_REFRESHED";
+    };
+    const requestRefresh = async (attempt = 1) => {
+        const retry = async () => {
+            await pause(retryBaseMs * attempt);
+            return requestRefresh(attempt + 1);
+        };
+        try {
+            const answer = await door("refresh");
+            if (answer.status < 200 || answer.status >= 300) {
+                if (isSignedOutStatus(answer.status))
+                    drop();
+                else if (isTransientStatus(answer.status) && attempt < attemptsMax)
+                    return await retry();
+                return undefined;
+            }
+            if (!isGrant(answer.body))
+                return undefined;
+            keep(answer.body, refreshEvent());
+            return answer.body.accessToken;
+        }
+        catch {
+            return attempt < attemptsMax ? retry() : undefined;
+        }
+    };
+    const renew = () => {
+        inFlight ??= requestRefresh().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const accessToken = async () => token !== undefined && expiresAt - refreshAheadMs > now() ? token : renew();
+    const outcomeOfAnswer = (answer, fallbacks) => {
+        if (answer.status >= 200 && answer.status < 300)
+            return authOk(answer.body);
+        const code = fieldOf(answer.body, "code");
+        return failureOfStatus(answer.status, typeof code === "string" ? code : undefined, fallbacks);
+    };
+    const send = async (name, body, fallbacks) => {
+        try {
+            return outcomeOfAnswer(await door(name, body), fallbacks);
+        }
+        catch {
+            return authFailure("unavailable", "transport");
+        }
+    };
+    const signIn = async (body) => {
+        const outcome = await send("login", body);
+        if (!outcome.success)
+            return outcome;
+        if (!isGrant(outcome.data))
+            return authFailure("unavailable", "grant");
+        keep(outcome.data, "SIGNED_IN");
+        const person = userOf(outcome.data);
+        return person === null ? authFailure("unavailable", "grant") : authOk(person);
+    };
+    const signOut = async () => {
+        try {
+            await door("logout");
+        }
+        catch {
+            // The token is forgotten below even when the door cannot be reached; the cookie then lapses with its session.
+        }
+        drop();
+    };
+    const subscribe = (listener) => {
+        listeners.add(listener);
+        if (announced) {
+            listener("INITIAL_SESSION", user?.id ?? null);
+        }
+        else {
+            void renew().then(() => {
+                if (!announced)
+                    announced = true;
+                if (token === undefined) {
+                    setSnapshot({ status: "signed-out", user: null });
+                    listener("INITIAL_SESSION", null);
+                }
+            });
+        }
+        return () => {
+            listeners.delete(listener);
+        };
+    };
+    const watch = (onChange) => {
+        watchers.add(onChange);
+        if (!announced && inFlight === undefined)
+            void renew().then(() => undefined);
+        return () => {
+            watchers.delete(onChange);
+        };
+    };
+    const checkSession = async (cookie) => {
+        if (cookie === null || cookie === "")
+            return authFailure("refused", "no-session");
+        try {
+            const answer = await door("session", undefined, cookie);
+            if (answer.status >= 200 && answer.status < 300)
+                return authOk(true);
+            return authFailure(isSignedOutStatus(answer.status) ? "refused" : "unavailable", String(answer.status));
+        }
+        catch {
+            return authFailure("unavailable", "transport");
+        }
+    };
+    return {
+        door,
+        signIn,
+        send,
+        signOut,
+        renew,
+        accessToken,
+        peek: () => token,
+        user: async () => ((await accessToken()) === undefined ? null : user),
+        headers: async () => {
+            const held = await accessToken();
+            return held === undefined ? {} : { authorization: `Bearer ${held}` };
+        },
+        keep,
+        drop,
+        subscribe,
+        getSnapshot: () => snapshot,
+        getServerSnapshot: () => LOADING,
+        watch,
+        checkSession,
+    };
+};

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export { createAuthClient } from "./auth-client.js";
+export type { AuthClient, AuthClientOptions, AuthDoorAnswer, AuthEvent, AuthListener, AuthSnapshot } from "./auth-client.js";
+export { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientStatus, kindOfStatus } from "./outcome.js";
+export type { StatusCodes } from "./outcome.js";
+export { EMAIL_PATTERN, NAME_MIN_LENGTH, PASSWORD_MIN_LENGTH, RESEND_COOLDOWN_SECONDS, authErrorKey, isLinkInvalid, passwordStrength, strengthKey, } from "./shared.js";
+export type { AuthErrorKey, Strength } from "./shared.js";

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { createAuthClient } from "./auth-client.js";
+export { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientStatus, kindOfStatus } from "./outcome.js";
+export { EMAIL_PATTERN, NAME_MIN_LENGTH, PASSWORD_MIN_LENGTH, RESEND_COOLDOWN_SECONDS, authErrorKey, isLinkInvalid, passwordStrength, strengthKey, } from "./shared.js";

package/dist/client/outcome.d.ts

@@ -0,0 +1,15 @@
+import type { AuthFailureKind, AuthOutcome } from "../contracts/index.js";
+/** Wraps a value as a successful outcome. */
+export declare const authOk: <T>(value: T) => AuthOutcome<T>;
+/** Builds an expected failure: the kind as the message, the wire code as the error. */
+export declare const authFailure: <T = never>(kind: AuthFailureKind, code: string) => AuthOutcome<T>;
+/** True when a status of a refresh or session door means the person is signed out. Only 401 and 403 do: a 429, a 5xx or a lost connection is a passing failure that never ends a session. */
+export declare const isSignedOutStatus: (status: number) => boolean;
+/** True when a status is a passing failure (too many requests, a server error) that a later attempt can clear. */
+export declare const isTransientStatus: (status: number) => boolean;
+/** The failure kind an HTTP status of the auth doors stands for. */
+export declare const kindOfStatus: (status: number) => AuthFailureKind;
+/** Codes a status falls back to when the body names none, so the friendly copy can pick its sentence. */
+export type StatusCodes = Readonly<Record<number, string>>;
+/** Maps a non-ok answer of an auth door (status plus the optional `code` of its JSON body) into a failed outcome. */
+export declare const failureOfStatus: <T = never>(status: number, code: string | undefined, fallbacks?: StatusCodes) => AuthOutcome<T>;

package/dist/client/outcome.js

@@ -0,0 +1,22 @@
+/** Wraps a value as a successful outcome. */
+export const authOk = (value) => ({ success: true, message: "ok", data: value });
+/** Builds an expected failure: the kind as the message, the wire code as the error. */
+export const authFailure = (kind, code) => ({
+    success: false,
+    message: kind,
+    error: code,
+});
+/** True when a status of a refresh or session door means the person is signed out. Only 401 and 403 do: a 429, a 5xx or a lost connection is a passing failure that never ends a session. */
+export const isSignedOutStatus = (status) => status === 401 || status === 403;
+/** True when a status is a passing failure (too many requests, a server error) that a later attempt can clear. */
+export const isTransientStatus = (status) => status === 429 || status >= 500;
+/** The failure kind an HTTP status of the auth doors stands for. */
+export const kindOfStatus = (status) => {
+    if (isSignedOutStatus(status))
+        return "refused";
+    if (status === 404)
+        return "not-found";
+    return status === 400 || status === 409 || status === 410 || status === 422 ? "invalid" : "unavailable";
+};
+/** Maps a non-ok answer of an auth door (status plus the optional `code` of its JSON body) into a failed outcome. */
+export const failureOfStatus = (status, code, fallbacks = {}) => authFailure(kindOfStatus(status), code ?? fallbacks[status] ?? String(status));

package/dist/client/shared.d.ts

@@ -0,0 +1,20 @@
+/** Shortest display name a sign-up accepts. */
+export declare const NAME_MIN_LENGTH = 2;
+/** Shortest password the forms accept (the doors enforce the same bound). */
+export declare const PASSWORD_MIN_LENGTH: 8;
+/** Seconds before a confirmation or reset mail may be requested again. */
+export declare const RESEND_COOLDOWN_SECONDS = 60;
+/** One address: a local part, one `@`, a domain with a dot. */
+export declare const EMAIL_PATTERN: RegExp;
+/** How strong a password looks. */
+export type Strength = "weak" | "ok" | "strong";
+/** Rough strength hint for the sign-up and reset forms (length plus character variety). */
+export declare const passwordStrength: (value: string) => Strength;
+/** The catalog key of the strength sentence. */
+export declare const strengthKey: (value: Strength) => "strengthWeak" | "strengthOk" | "strengthStrong";
+/** Catalog keys of the friendly error sentences. */
+export type AuthErrorKey = "errInvalidCredentials" | "errEmailNotConfirmed" | "errTooMany" | "errWeakPassword" | "errLinkInvalid" | "errGeneric";
+/** Maps the code of a failed outcome (a wire code, or an HTTP status when the body named none) to its catalog key. */
+export declare const authErrorKey: (code: string) => AuthErrorKey;
+/** Whether a failure code means the recovery link is no longer usable. */
+export declare const isLinkInvalid: (code: string) => boolean;

package/dist/client/shared.js

@@ -0,0 +1,42 @@
+import { AUTH_ERROR_CODES, PASSWORD_BOUNDS } from "../contracts/index.js";
+/** Shortest display name a sign-up accepts. */
+export const NAME_MIN_LENGTH = 2;
+/** Shortest password the forms accept (the doors enforce the same bound). */
+export const PASSWORD_MIN_LENGTH = PASSWORD_BOUNDS.min;
+/** Seconds before a confirmation or reset mail may be requested again. */
+export const RESEND_COOLDOWN_SECONDS = 60;
+/** One address: a local part, one `@`, a domain with a dot. */
+export const EMAIL_PATTERN = /^[^\s@]+@[^\s@][^\s@.]*\.[^\s@]+$/u;
+/** Rough strength hint for the sign-up and reset forms (length plus character variety). */
+export const passwordStrength = (value) => {
+    const variety = [/[a-z]/u, /[A-Z]/u, /\d/u, /[^A-Za-z0-9]/u].filter((pattern) => pattern.test(value)).length;
+    if (value.length < PASSWORD_MIN_LENGTH || variety < 2)
+        return "weak";
+    return value.length >= 10 && variety >= 3 ? "strong" : "ok";
+};
+/** The catalog key of the strength sentence. */
+export const strengthKey = (value) => {
+    if (value === "weak")
+        return "strengthWeak";
+    return value === "ok" ? "strengthOk" : "strengthStrong";
+};
+/** Maps the code of a failed outcome (a wire code, or an HTTP status when the body named none) to its catalog key. */
+export const authErrorKey = (code) => {
+    switch (code) {
+        case AUTH_ERROR_CODES.InvalidCredentials:
+            return "errInvalidCredentials";
+        case AUTH_ERROR_CODES.EmailNotConfirmed:
+            return "errEmailNotConfirmed";
+        case AUTH_ERROR_CODES.TooManyAttempts:
+        case "429":
+            return "errTooMany";
+        case AUTH_ERROR_CODES.PasswordInvalid:
+            return "errWeakPassword";
+        case AUTH_ERROR_CODES.ResetTokenInvalid:
+            return "errLinkInvalid";
+        default:
+            return "errGeneric";
+    }
+};
+/** Whether a failure code means the recovery link is no longer usable. */
+export const isLinkInvalid = (code) => authErrorKey(code) === "errLinkInvalid";

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