@starci/auth 0.0.0-stage → 0.2.0

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

package/dist/server/flows.js

@@ -0,0 +1,66 @@
+import passport from "passport";
+import { AUTH_ERROR_CODES } from "../contracts/index.js";
+import { AuthError } from "./errors.js";
+import { isRecord, sameSitePath } from "./primitives.js";
+const isSubject = (value) => isRecord(value) && typeof value.userId === "string" && typeof value.email === "string";
+const isHandler = (value) => typeof value === "function";
+/** The middleware passport built; passport types it as any, so it is checked once here. */
+const handlerOf = (built) => {
+    if (!isHandler(built))
+        throw new AuthError(AUTH_ERROR_CODES.GoogleUnavailable);
+    return built;
+};
+const errorOf = (error) => (error instanceof Error ? error : new Error("passport"));
+/** Runs the passport strategies for one request without sessions; the only caller of `passport.authenticate`. */
+export class AuthFlows {
+    #google;
+    constructor(options) {
+        this.#google = options.google;
+    }
+    /** Runs the local strategy over the posted body; answers the person, or throws the app's refusal. */
+    authenticateLocal(exchange) {
+        return new Promise((resolve, reject) => {
+            const settled = (error, user) => {
+                if (error !== null && error !== undefined)
+                    reject(errorOf(error));
+                else if (isSubject(user))
+                    resolve(user);
+                else
+                    reject(new AuthError(AUTH_ERROR_CODES.MissingCredentials));
+            };
+            handlerOf(passport.authenticate("local", { session: false }, settled))(exchange.req, exchange.res, reject);
+        });
+    }
+    /** 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) {
+        if (this.#google === null)
+            return Promise.reject(new AuthError(AUTH_ERROR_CODES.GoogleUnavailable));
+        return new Promise((resolve, reject) => {
+            exchange.res.once("finish", resolve);
+            const built = passport.authenticate("google", { session: false, prompt: "select_account" }, (error) => {
+                reject(errorOf(error));
+            });
+            handlerOf(built)(exchange.req, exchange.res, reject);
+        });
+    }
+    /** Finishes the Google round trip: the state cookie, the PKCE verifier and the profile must all check out. */
+    completeGoogle(exchange) {
+        if (this.#google === null)
+            return Promise.reject(new AuthError(AUTH_ERROR_CODES.GoogleUnavailable));
+        return new Promise((resolve, reject) => {
+            const settled = (error, user, info) => {
+                if (error !== null && error !== undefined) {
+                    reject(errorOf(error));
+                    return;
+                }
+                if (!isSubject(user)) {
+                    reject(new AuthError(AUTH_ERROR_CODES.GoogleStateInvalid));
+                    return;
+                }
+                const state = isRecord(info) && isRecord(info.state) ? info.state.next : undefined;
+                resolve({ subject: user, next: sameSitePath(state, "/") });
+            };
+            handlerOf(passport.authenticate("google", { session: false }, settled))(exchange.req, exchange.res, reject);
+        });
+    }
+}

package/dist/server/google-state.d.ts

@@ -0,0 +1,33 @@
+import type { HttpRequest } from "./http.js";
+import type { AuthOptions } from "./options.js";
+import type { AuthClock, AuthIds } from "./ports.js";
+import type { AuthTokens } from "./tokens.js";
+/** The cookie that carries one Google round trip, when the options name none. */
+export declare const DEFAULT_GOOGLE_STATE_COOKIE = "auth_google_state";
+/** The only path the state cookie is sent to. */
+export declare const GOOGLE_STATE_PATH: "/auth/google";
+/** How long a Google round trip may take, in milliseconds. */
+export declare const GOOGLE_STATE_TTL_MS = 600000;
+type StoreDone = (error: Error | null, handle?: string) => void;
+type VerifyDone = (error: Error | null, verifier?: unknown, context?: unknown) => void;
+/**
+ * The state store passport-oauth2 calls for `state` and PKCE without a server session: the handle (echoed as `state`), the code
+ * verifier and the landing path travel in a signed, httpOnly cookie that only the callback path receives, and the handle is
+ * compared on return. The landing path is a same-site path only, so the callback can never redirect off the web origin.
+ */
+export declare class GoogleStateClient {
+    #private;
+    constructor(deps: {
+        readonly tokens: AuthTokens;
+        readonly clock: AuthClock;
+        readonly ids: AuthIds;
+        readonly options: Pick<AuthOptions, "returnOrigin" | "google">;
+    });
+    /** The name of the state cookie. */
+    get cookieName(): string;
+    /** Called by passport-oauth2 on the outbound leg (the five-argument PKCE form). */
+    store(req: HttpRequest, verifier: string, _state: unknown, _meta: unknown, done: StoreDone): void;
+    /** Called by passport-oauth2 on the return leg (the meta form, since this method takes four arguments): the cookie must be ours, unexpired and carry the same handle as `state`. */
+    verify(req: HttpRequest, providedState: string, _meta: unknown, done: VerifyDone): void;
+}
+export {};

package/dist/server/google-state.js

@@ -0,0 +1,73 @@
+import { AUTH_DOORS } from "../contracts/index.js";
+import { cookieValue, sameSitePath, sameValue } from "./primitives.js";
+/** The cookie that carries one Google round trip, when the options name none. */
+export const DEFAULT_GOOGLE_STATE_COOKIE = "auth_google_state";
+/** The only path the state cookie is sent to. */
+export const GOOGLE_STATE_PATH = AUTH_DOORS.google;
+/** How long a Google round trip may take, in milliseconds. */
+export const GOOGLE_STATE_TTL_MS = 600_000;
+/**
+ * The state store passport-oauth2 calls for `state` and PKCE without a server session: the handle (echoed as `state`), the code
+ * verifier and the landing path travel in a signed, httpOnly cookie that only the callback path receives, and the handle is
+ * compared on return. The landing path is a same-site path only, so the callback can never redirect off the web origin.
+ */
+export class GoogleStateClient {
+    #tokens;
+    #clock;
+    #ids;
+    #returnOrigin;
+    #cookie;
+    constructor(deps) {
+        this.#tokens = deps.tokens;
+        this.#clock = deps.clock;
+        this.#ids = deps.ids;
+        this.#returnOrigin = deps.options.returnOrigin;
+        this.#cookie = deps.options.google?.stateCookie ?? DEFAULT_GOOGLE_STATE_COOKIE;
+    }
+    /** The name of the state cookie. */
+    get cookieName() {
+        return this.#cookie;
+    }
+    /** Called by passport-oauth2 on the outbound leg (the five-argument PKCE form). */
+    store(req, verifier, _state, _meta, done) {
+        const handle = this.#ids.next();
+        const signed = this.#tokens.signState({
+            w: handle,
+            u: verifier,
+            r: this.#landingOf(req),
+            e: this.#clock.now().getTime() + GOOGLE_STATE_TTL_MS,
+            p: "google",
+        });
+        req.res?.cookie(this.#cookie, signed, {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: GOOGLE_STATE_PATH,
+            maxAge: GOOGLE_STATE_TTL_MS,
+        });
+        done(null, handle);
+    }
+    /** The same-site path to land on: the requested return address when it is a path, or an absolute address on the web origin; else the root. */
+    #landingOf(req) {
+        const { returnTo, next } = req.query ?? {};
+        const wanted = typeof returnTo === "string" ? returnTo : next;
+        if (typeof wanted !== "string")
+            return "/";
+        if (!URL.canParse(wanted))
+            return sameSitePath(wanted, "/");
+        const url = new URL(wanted);
+        return url.origin === this.#returnOrigin ? sameSitePath(`${url.pathname}${url.search}`, "/") : "/";
+    }
+    /** Called by passport-oauth2 on the return leg (the meta form, since this method takes four arguments): the cookie must be ours, unexpired and carry the same handle as `state`. */
+    verify(req, providedState, _meta, done) {
+        const header = req.headers.cookie;
+        const raw = cookieValue(Array.isArray(header) ? header.join("; ") : (header ?? ""), this.#cookie);
+        req.res?.clearCookie(this.#cookie, { httpOnly: true, secure: true, sameSite: "lax", path: GOOGLE_STATE_PATH });
+        const state = raw === "" ? null : this.#tokens.verifyState(raw, this.#clock.now());
+        if (state?.p !== "google" || typeof providedState !== "string" || !sameValue(state.w, providedState)) {
+            done(null, false, { message: "state" });
+            return;
+        }
+        done(null, state.u, { next: sameSitePath(state.r, "/") });
+    }
+}

package/dist/server/http.d.ts

@@ -0,0 +1,27 @@
+/** The cookie attributes a response writes. */
+export interface CookieWrite {
+    readonly httpOnly: boolean;
+    readonly secure: boolean;
+    readonly sameSite: "lax" | "strict";
+    readonly path: string;
+    readonly maxAge?: number;
+    readonly domain?: string;
+}
+/** The part of a request the package reads. */
+export interface HttpRequest {
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly ip?: string | undefined;
+    readonly query?: Readonly<Record<string, unknown>> | undefined;
+    readonly res?: HttpResponse | undefined;
+}
+/** The part of a response the package writes. */
+export interface HttpResponse {
+    cookie(name: string, value: string, options: CookieWrite): unknown;
+    clearCookie(name: string, options: Omit<CookieWrite, "maxAge">): unknown;
+    once(event: "finish", listener: () => void): unknown;
+}
+/** The two halves of an HTTP exchange the flows work on (an Express request and response satisfy it). */
+export interface HttpExchange {
+    readonly req: HttpRequest;
+    readonly res: HttpResponse;
+}

package/dist/server/http.js

@@ -0,0 +1 @@
+export {};

package/dist/server/index.d.ts

@@ -0,0 +1,24 @@
+export { 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 { AuthModule, MODULE_OPTIONS_TOKEN as AUTH_OPTIONS } from "./auth.module.js";
+export type { AuthModuleExtras, AuthRegisterAsyncOptions, AuthRegisterOptions } from "./auth.module.js";
+export { SignInBudget } from "./budget.js";
+export { RefreshCookie } from "./cookie.js";
+export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf } from "./doors.js";
+export type { DoorsDeps } from "./doors.js";
+export { AuthError, ok, refused } from "./errors.js";
+export type { Outcome } from "./errors.js";
+export { AuthFlows } from "./flows.js";
+export type { GoogleCompletion } from "./flows.js";
+export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient } from "./google-state.js";
+export type { CookieWrite, HttpExchange, HttpRequest, HttpResponse } from "./http.js";
+export type { AuthOptions, BudgetOptions, GoogleOptions, RefreshCookieOptions, SigningKeyOptions } from "./options.js";
+export { AuthPasswords } from "./passwords.js";
+export type { AccessClaims, AccountDirectory, AccountStanding, AuthAuthenticator, AuthClock, AuthIds, AuthLogger, AuthPrincipal, AuthSubject, DeviceMeta, GoogleProfile, IssuedAccessToken, NewSession, RateCounter, RefreshTokenRecord, SessionStore, SessionTokens, SessionTransaction, } from "./ports.js";
+export { cookieValue, digestOf, isAcceptablePassword, isPresentablePassword, normalizeEmail, sameSitePath } from "./primitives.js";
+export type { Revealable, SecretInput } from "./primitives.js";
+export { randomIds, systemClock } from "./runtime.js";
+export { AuthSessions, DEFAULT_REUSE_GRACE_MS, REFRESH_REUSE_EVENT } from "./sessions.js";
+export { googleProfileOf } from "./strategies.js";
+export { AuthTokens } from "./tokens.js";
+export { AuthPrincipalVerifier, refuseSessions } from "./verifier.js";
+export type { PrincipalVerifier } from "./verifier.js";

package/dist/server/index.js

@@ -0,0 +1,15 @@
+export { 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 { AuthModule, MODULE_OPTIONS_TOKEN as AUTH_OPTIONS } from "./auth.module.js";
+export { SignInBudget } from "./budget.js";
+export { RefreshCookie } from "./cookie.js";
+export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf } from "./doors.js";
+export { AuthError, ok, refused } from "./errors.js";
+export { AuthFlows } from "./flows.js";
+export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient } from "./google-state.js";
+export { AuthPasswords } from "./passwords.js";
+export { cookieValue, digestOf, isAcceptablePassword, isPresentablePassword, normalizeEmail, sameSitePath } from "./primitives.js";
+export { randomIds, systemClock } from "./runtime.js";
+export { AuthSessions, DEFAULT_REUSE_GRACE_MS, REFRESH_REUSE_EVENT } from "./sessions.js";
+export { googleProfileOf } from "./strategies.js";
+export { AuthTokens } from "./tokens.js";
+export { AuthPrincipalVerifier, refuseSessions } from "./verifier.js";

package/dist/server/options.d.ts

@@ -0,0 +1,81 @@
+import type { SecretInput } from "./primitives.js";
+import type { AccountDirectory, AuthClock, AuthIds, AuthLogger, RateCounter, SessionStore } from "./ports.js";
+/** One signing key of the key set. */
+export interface SigningKeyOptions {
+    /** The public key (SPKI PEM) published at the JWKS door. Derived from the private key when absent; a verify-only key needs it. */
+    readonly publicKey?: string | undefined;
+    /** The Ed25519 private key (PKCS#8 PEM). Exactly one key of the set carries it: the active signer. A key without it only verifies. */
+    readonly privateKey?: SecretInput | undefined;
+    /** The `kid` of the key; the RFC 7638 thumbprint of the public key when absent. */
+    readonly keyId?: string | undefined;
+}
+/** The Google OAuth client and where Google sends the browser back. */
+export interface GoogleOptions {
+    /** The public client id. */
+    readonly clientId: string;
+    /** The client secret. */
+    readonly clientSecret: SecretInput;
+    /** The registered callback address (`<api>/auth/google/callback`). */
+    readonly callbackUrl: string;
+    /** The name of the cookie that carries one Google round trip. */
+    readonly stateCookie?: string | undefined;
+}
+/** The refresh cookie. */
+export interface RefreshCookieOptions {
+    /** The cookie name. */
+    readonly name: string;
+    /** The `Domain` of the cookie; undefined keeps it host-only. */
+    readonly domain?: string | undefined;
+    /** The path the cookie is sent on (the web app's server reads it on its own pages and forwards it to the api). */
+    readonly path?: string | undefined;
+    /** The paths older sessions wrote the cookie under; each is cleared so a stale copy never shadows the live one. */
+    readonly legacyPaths?: readonly string[] | undefined;
+    /** `lax` (default) or `strict`. */
+    readonly sameSite?: "lax" | "strict" | undefined;
+}
+/** The budget of sign-in failures. */
+export interface BudgetOptions {
+    /** Sign-in failures per address in one window. */
+    readonly loginAttempts: number;
+    /** Reset and signup requests per address in one window. */
+    readonly resetAttempts: number;
+    /** The window, in milliseconds. */
+    readonly windowMs: number;
+}
+/** Everything the package needs, typed and parsed by the app (the package reads no environment). */
+export interface AuthOptions {
+    /** The `iss` claim. */
+    readonly issuer: string;
+    /** The `aud` claim; `authenticated` when absent. */
+    readonly audience?: string | undefined;
+    /** The signing keys: the first with a private key signs, every key verifies and is published, so a retired key stays valid until its tokens expire. */
+    readonly keys: readonly SigningKeyOptions[];
+    /** How long an access token lives, in seconds. */
+    readonly accessTtlSeconds: number;
+    /** How long a refresh token lives, in seconds. */
+    readonly refreshTtlSeconds: number;
+    /** A rotated refresh token presented again within this many milliseconds is a racing tab, not a theft (30 seconds when absent). */
+    readonly reuseGraceMs?: number | undefined;
+    /** The bcrypt cost of a new password hash. */
+    readonly bcryptCost: number;
+    /** The origin of the web app: a return address is accepted only on this origin, and the Google callback lands there. */
+    readonly returnOrigin: string;
+    /** The Google client; null when the deployment has none (the Google door is then unavailable). */
+    readonly google: GoogleOptions | null;
+    /** The refresh cookie. */
+    readonly cookie: RefreshCookieOptions;
+    /** The sign-in budget. */
+    readonly budget: BudgetOptions;
+    /** The session tables behind the app's ORM. */
+    readonly sessions: SessionStore;
+    /** The app's user table, as far as sessions need it. */
+    readonly accounts: AccountDirectory;
+    /** The counter the budget uses. */
+    readonly rate: RateCounter;
+    /** The clock (system time when absent). */
+    readonly clock?: AuthClock | undefined;
+    /** The id source (random UUIDs when absent). */
+    readonly ids?: AuthIds | undefined;
+    /** The security-event log (silent when absent). */
+    readonly logger?: AuthLogger | undefined;
+}

package/dist/server/options.js

@@ -0,0 +1 @@
+export {};

package/dist/server/passwords.d.ts

@@ -0,0 +1,11 @@
+/** The one owner of bcrypt: hashes new passwords and verifies hashes, including any written by another bcrypt implementation. */
+export declare class AuthPasswords {
+    #private;
+    constructor(options: {
+        readonly bcryptCost: number;
+    });
+    /** A bcrypt hash of a new password. */
+    hash(plain: string): Promise<string>;
+    /** True when the password matches the stored hash (constant time); an empty stored hash is compared against a decoy and never matches. */
+    verify(plain: string, stored: string): Promise<boolean>;
+}

package/dist/server/passwords.js

@@ -0,0 +1,22 @@
+import bcrypt from "bcryptjs";
+/** A valid bcrypt hash nobody can match, compared when no account exists so a missing account costs the same time as a wrong password. */
+const DECOY_HASH = "$2b$10$6RdlN0g82RrrsKDj5Hb7pu4B48ZqLbJd7F245q9CktC/LrHJyag9.";
+/** The one owner of bcrypt: hashes new passwords and verifies hashes, including any written by another bcrypt implementation. */
+export class AuthPasswords {
+    #cost;
+    constructor(options) {
+        this.#cost = options.bcryptCost;
+    }
+    /** A bcrypt hash of a new password. */
+    hash(plain) {
+        return bcrypt.hash(plain, this.#cost);
+    }
+    /** True when the password matches the stored hash (constant time); an empty stored hash is compared against a decoy and never matches. */
+    async verify(plain, stored) {
+        if (stored === "") {
+            await bcrypt.compare(plain, DECOY_HASH);
+            return false;
+        }
+        return bcrypt.compare(plain, stored);
+    }
+}

package/dist/server/ports.d.ts

@@ -0,0 +1,145 @@
+import type { AttemptKind, SessionUser } from "../contracts/index.js";
+/** The person a sign-in method established; the session is opened for them. */
+export interface AuthSubject {
+    /** The account id. */
+    readonly userId: string;
+    /** The account email. */
+    readonly email: string;
+}
+/** What Google told us about the person who consented. */
+export interface GoogleProfile {
+    /** Google's stable account id (`sub`). */
+    readonly subject: string;
+    /** The Google email, when released. */
+    readonly email: string | null;
+    /** True when Google verified that mailbox. */
+    readonly emailVerified: boolean;
+    /** The display name, when released. */
+    readonly name: string | null;
+    /** The picture address, when released. */
+    readonly picture: string | null;
+}
+/** The sign-in decisions the app makes for the two strategies; each throws the app's error when it refuses. */
+export interface AuthAuthenticator {
+    /** Verifies an email and password; answers the person or throws. */
+    verifyPassword(email: string, password: string): Promise<AuthSubject>;
+    /** Finds, links or creates the person a verified Google profile stands for; answers the person or throws. */
+    signInWithGoogle(profile: GoogleProfile): Promise<AuthSubject>;
+}
+/** The account facts a refresh needs to decide that a session may go on. */
+export interface AccountStanding {
+    /** The account id. */
+    readonly id: string;
+    /** The address, or null. */
+    readonly email: string | null;
+    /** Whether the account is disabled or gone. */
+    readonly disabled: boolean;
+}
+/** The app's user table, seen only as far as sessions need it. */
+export interface AccountDirectory {
+    /** The standing of one account, or undefined when it does not exist. */
+    find(userId: string): Promise<AccountStanding | undefined>;
+}
+/** One refresh token as the store keeps it: only its digest, and a spent token is kept for replay detection. */
+export interface RefreshTokenRecord {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly userId: string;
+    readonly tokenHash: string;
+    readonly expiresAt: Date;
+    /** When the token was rotated away, or null while it is the live one. */
+    readonly usedAt: Date | null;
+}
+/** A device session to open. */
+export interface NewSession {
+    readonly id: string;
+    readonly userId: string;
+    readonly now: Date;
+    readonly userAgent: string | null;
+    readonly ip: string | null;
+}
+/** The writes of one rotation, applied atomically by the store. */
+export interface SessionTransaction {
+    /** Opens a device session. */
+    openSession(session: NewSession): Promise<void>;
+    /** Stores a live refresh token. */
+    insertToken(token: Omit<RefreshTokenRecord, "usedAt">): Promise<void>;
+    /** The token with this digest, locked for update (a pessimistic write lock), or null. */
+    findTokenForUpdate(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    /** Marks a token as rotated away at `at`. */
+    markTokenUsed(tokenId: string, at: Date): Promise<void>;
+    /** Deletes the tokens of an account that expired before `before`. */
+    deleteExpiredTokens(userId: string, before: Date): Promise<void>;
+}
+/** The tables the package owns (`identity_sessions`, `identity_refresh_tokens`), behind the app's ORM. */
+export interface SessionStore {
+    /** Runs `work` in one database transaction. */
+    transaction<T>(work: (tx: SessionTransaction) => Promise<T>): Promise<T>;
+    /** The token with this digest, or null. */
+    findToken(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    /** Marks a session refreshed. */
+    touchSession(sessionId: string, now: Date): Promise<void>;
+    /** Ends one session (and with it every token of it). */
+    closeSession(sessionId: string): Promise<void>;
+    /** Ends every session of an account but one. */
+    closeOtherSessions(userId: string, keepSessionId: string): Promise<void>;
+}
+/** A counter every replica shares (the app's rate-limit store). */
+export interface RateCounter {
+    /** Counts one hit in the window; false when the key is over `limit`. */
+    consume(key: string, windowMs: number, limit: number): Promise<boolean>;
+    /** Forgets a key. */
+    clear(key: string): Promise<void>;
+}
+/** The clock the package reads. */
+export interface AuthClock {
+    now(): Date;
+}
+/** The source of ids the package mints. */
+export interface AuthIds {
+    next(): string;
+}
+/** Where the package reports a security event (a replayed refresh token). */
+export interface AuthLogger {
+    warn(event: string, context?: Readonly<Record<string, unknown>>): void;
+}
+/** The device a request comes from. */
+export interface DeviceMeta {
+    readonly userAgent: string | null;
+    readonly ip: string | null;
+}
+/** The tokens one sign-in or refresh produces; the refresh token only ever leaves in the cookie. */
+export interface SessionTokens {
+    readonly accessToken: string;
+    readonly accessExpiresAt: string;
+    readonly accessExpiresIn: number;
+    /** The opaque token the refresh cookie carries. */
+    readonly cookieToken: string;
+    /** True when the answer did not rotate the token (a racing request, or the non-rotating session door): the caller leaves the cookie as it is. */
+    readonly cookieKept?: true;
+    readonly refreshMaxAgeSeconds: number;
+    readonly user: SessionUser;
+}
+/** The claims of one of our access tokens after verification. */
+export interface AccessClaims {
+    /** The user id. */
+    readonly sub: string;
+    /** The email at issue time, when the account has one. */
+    readonly email?: string | undefined;
+    /** The device session the token belongs to. */
+    readonly sessionId: string;
+}
+/** The principal domain code builds from a verified access token. */
+export interface AuthPrincipal {
+    readonly id: string;
+    readonly role: "authenticated";
+    readonly sessionId: string;
+    readonly email?: string;
+}
+/** A freshly signed access token. */
+export interface IssuedAccessToken {
+    readonly token: string;
+    readonly expiresAt: Date;
+}
+/** The kinds of attempt a budget counts. */
+export type { AttemptKind };

package/dist/server/ports.js

@@ -0,0 +1 @@
+export {};