@krizaka/auth 0.7.0 → 0.8.0

package/dist/identity-links-C5AG7Fbp.d.ts

@@ -1,239 +0,0 @@
-/**
- * The account PORT (ADR-0008 of Yomizaka, now shared). A product's account — name, language, theme, avatar, e-mail change with
- * verification, password (changed when signed in, or reset by a mailed link), sessions, export, deletion — behind one interface. Every product keeps its OWN accounts: no central
- * service, no runtime dependency between products.
- */
-type Theme = "light" | "dark" | "system";
-interface AccountProfile {
-    id: string;
-    email: string;
-    name: string | null;
-    locale: "en" | "fr";
-    /** The theme the person chose; null = follow the device. */
-    theme: Theme | null;
-    /** A seed of the default avatars (the UI draws it); null = derived from the e-mail address. */
-    avatarSeed: string | null;
-    emailVerified: boolean;
-    /** An address awaiting its verification link, if the person asked to change it. */
-    pendingEmail: string | null;
-}
-interface ProfilePatch {
-    name?: string | null;
-    locale?: "en" | "fr";
-    theme?: Theme | null;
-    avatarSeed?: string | null;
-}
-/** A sign-in of the person: where from and when. Never the token. */
-interface SessionSummary {
-    id: string;
-    createdAt: Date;
-    expiresAt: Date;
-    ip: string | null;
-    userAgent: string | null;
-    current: boolean;
-}
-interface AccountService {
-    profile(accountId: string): Promise<AccountProfile>;
-    updateProfile(accountId: string, patch: ProfilePatch): Promise<AccountProfile>;
-    /** Asks to change the address: the password is checked, a link is mailed to the NEW address. Answers the same whether or not it is already taken (no enumeration). */
-    requestEmailChange(accountId: string, input: {
-        newEmail: string;
-        password: string;
-    }, now: Date): Promise<void>;
-    /** Applies the change from the mailed link (single use, expires); the new address is verified by that very act. */
-    confirmEmailChange(token: string, now: Date): Promise<"CHANGED" | "INVALID">;
-    /** Changes the password (the current one is checked) and signs every other session out; `keepSessionId` stays. */
-    changePassword(accountId: string, input: {
-        current: string;
-        next: string;
-    }, keepSessionId?: string): Promise<void>;
-    /** Asks for a reset link, mailed (in the person's language) when an account with a password has this address; answers the same either way (no enumeration). */
-    requestPasswordReset(email: string, now: Date): Promise<void>;
-    /** Sets a new password from the mailed link — single use, expires — and signs every session out. The new password is checked before the link is used up. */
-    resetPassword(token: string, next: string, now: Date): Promise<"CHANGED" | "INVALID">;
-    /** Checks the password. Throws `AccountError(403, "WRONG_PASSWORD")`. */
-    confirmPassword(accountId: string, password: string): Promise<void>;
-    /** The person's live sign-ins, newest first; `currentSessionId` is flagged. */
-    sessions(accountId: string, now: Date, currentSessionId?: string): Promise<SessionSummary[]>;
-    /** Signs every other session out (and returns how many); `keepSessionId` stays. */
-    signOutOthers(accountId: string, keepSessionId: string): Promise<number>;
-    /** What the product keeps about the person, as one JSON-able document: the profile, the live sign-ins, and what `extra` adds. */
-    exportAccount(accountId: string, now: Date, extra?: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
-    /** Deletes the identity: the account, its sessions and everything that hangs on it (the product erases its own data first). */
-    deleteAccount(accountId: string): Promise<void>;
-}
-declare class AccountError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(status: number, code: string, message: string);
-}
-
-/** A SQL executor: the rows of a statement and its parameters (the product's pool). */
-type Query = <T = Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<T[]>;
-interface Mail {
-    to: string;
-    /** The language of the mail (the person's). */
-    locale: "en" | "fr";
-    subject: string;
-    text: string;
-    /**
-     * The link this mail carries, as data: a product that sends branded HTML (`@krizaka/email`: `passwordReset`, `emailChange`)
-     * renders it from this instead of from `text`. Absent on a mail that is not a link.
-     */
-    link?: MailLink;
-}
-/** A mailed link: what it is for, where it goes, and how long it lives. */
-interface MailLink {
-    kind: "passwordReset" | "emailChange";
-    url: string;
-    /** `passwordReset`: the lifetime in minutes. */
-    minutes?: number;
-    /** `emailChange`: the lifetime in hours. */
-    hours?: number;
-}
-interface AccountDeps {
-    query: Query;
-    /**
-     * Runs `work` in one transaction on one connection (BEGIN … COMMIT, rolled back when `work` throws) — the product's pool
-     * knows how. The password reset runs under it: the account row is locked, the links retired and issued, the token claimed,
-     * the password set and the sessions ended as one. Without it, the statements run one by one on `query` (one process, no
-     * concurrent requests): give it in production.
-     */
-    transaction?: <T>(work: (query: Query) => Promise<T>) => Promise<T>;
-    mail: (mail: Mail) => Promise<void>;
-    /** `https://www.akinaza.com`: the e-mail change link is `<baseUrl>/<locale>/confirm-email?token=…`, the reset link `<baseUrl>/<locale>/reset-password?token=…`. */
-    baseUrl: string;
-    /** The product's name, in the words of the mail (« Akinaza »). */
-    product: string;
-    /** The product's token prefix, two or three letters (`ye1.` for Yomizaka: `ye`). The tokens are `<prefix>1.<43 base64url>`. */
-    tokenPrefix: string;
-    passwords: {
-        hash: (password: string) => Promise<string>;
-        verify: (password: string, stored: string) => Promise<boolean>;
-    };
-    /** How a token is kept: the product's own keyed hash, the one its sessions use. */
-    tokenHash: (token: string) => string;
-    /**
-     * How long a password reset link lives, in minutes: a whole number from 5 to 1440 (`PASSWORD_RESET_MIN_MINUTES`–`PASSWORD_RESET_MAX_MINUTES`),
-     * default `PASSWORD_RESET_TTL_MINUTES` (30). The product reads it from its settings; the expiry and the mailed text both use it.
-     * Out of range, `dbAccounts` throws.
-     */
-    passwordResetTtlMinutes?: number;
-    /** Test seam: the token to issue. */
-    token?: () => string;
-}
-declare const EMAIL_CHANGE_TTL_HOURS = 24;
-/** The default lifetime of a password reset link, in minutes (`AccountDeps.passwordResetTtlMinutes` changes it). */
-declare const PASSWORD_RESET_TTL_MINUTES = 30;
-declare const PASSWORD_RESET_MIN_MINUTES = 5;
-declare const PASSWORD_RESET_MAX_MINUTES = 1440;
-/** One format for every mailed link (an e-mail change, a password reset): the product's prefix, a version, 256 random bits. */
-declare const linkToken: (prefix: string) => string;
-declare const isLinkToken: (prefix: string, value: string | undefined | null) => value is string;
-declare const emailChangeToken: (prefix: string) => string;
-declare const isEmailChangeToken: (prefix: string, value: string | undefined | null) => value is string;
-declare function passwordResetMail(product: string, locale: "en" | "fr", url: string, ttlMinutes?: number): {
-    subject: string;
-    text: string;
-};
-declare function emailChangeMail(product: string, locale: "en" | "fr", url: string): {
-    subject: string;
-    text: string;
-};
-/** The adapter over the product's own PostgreSQL (`accounts`, `sessions`, `email_changes`, `password_resets`; see `accountsMigration`). */
-declare function dbAccounts(deps: AccountDeps): AccountService;
-/** @deprecated The old name of `dbAccounts` (a name says what a thing does, not the technology). Removed in the next major. */
-declare const postgresAccounts: typeof dbAccounts;
-
-/**
- * Federated sign-in (Google, Apple, Facebook, a native app's PKCE) delegated to krizaka-users, behind a PORT. The product keeps its
- * own accounts (`postgresAccounts`); this port only answers « who is this person, according to the provider ». An external
- * identity is never a second user table: it is a link to an account the product already has.
- */
-type FederatedProvider = "google" | "apple" | "facebook";
-/** The providers the port knows; anything else is refused before it reaches the adapter. */
-declare const FEDERATED_PROVIDERS: readonly FederatedProvider[];
-declare const isFederatedProvider: (value: unknown) => value is FederatedProvider;
-/** Who the provider says the person is. `issuer` + `subject` identify them for good; the address can change. */
-interface ExternalIdentity {
-    /** The authority that vouches (`https://accounts.google.com`, `https://appleid.apple.com`…). */
-    issuer: string;
-    /** The person's stable id at that authority. */
-    subject: string;
-    email: string | null;
-    /** The provider checked the address (a Facebook address, for one, may not be). */
-    emailVerified: boolean;
-    name: string | null;
-}
-/** What a sign-in is started with: a native app sends the PKCE challenge, a browser flow does not. */
-interface StartOptions {
-    /** The S256 challenge of a PKCE flow (a native app); the matching verifier goes to `complete`. */
-    codeChallenge?: string;
-}
-interface StartedSignIn {
-    /** Where to send the person: the provider's consent page, through krizaka-users. */
-    url: string;
-    /** Echoed back with the code: the product checks it against the one it kept for this browser. */
-    state: string;
-}
-interface CompleteOptions {
-    /** The PKCE verifier of the challenge given to `start`. */
-    codeVerifier?: string;
-}
-interface IdentityProvider {
-    /** Starts a sign-in with `provider`; the person comes back to `returnTo` (a path or an address the adapter allows) with a one-time code. */
-    start(provider: FederatedProvider, returnTo: string, options?: StartOptions): Promise<StartedSignIn>;
-    /** Exchanges the one-time code (single use) for the verified identity. Throws `FederationError("INVALID_CODE")` for a code that is unknown, used or expired. */
-    complete(code: string, options?: CompleteOptions): Promise<ExternalIdentity>;
-}
-declare const FEDERATION_CODE: {
-    readonly invalidCode: "INVALID_CODE";
-    readonly unknownProvider: "UNKNOWN_PROVIDER";
-    readonly badReturn: "BAD_RETURN_TO";
-    readonly unavailable: "UNAVAILABLE";
-};
-type FederationCode = (typeof FEDERATION_CODE)[keyof typeof FEDERATION_CODE];
-declare class FederationError extends Error {
-    readonly code: FederationCode;
-    constructor(code: FederationCode, message: string);
-}
-/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). A native app computes it; the adapter and the in-memory provider check it. */
-declare const pkceChallenge: (verifier: string) => string;
-/** A return address stays on the product: a path (`/fr/account`), never `//host` or a scheme. */
-declare const isLocalReturn: (returnTo: string) => boolean;
-/** An in-memory provider: the tests' adapter, and the reference the contract is written against. */
-declare function memoryIdentityProvider(): IdentityProvider & {
-    /** Test seam: the one-time code the provider would hand back for this identity (with the PKCE challenge it was started with, if any). */
-    issue(identity: ExternalIdentity, challenge?: string): string;
-};
-
-/**
- * Which external identity belongs to which account. Never a second user table: a row is only `(issuer, subject) → account`.
- * The product's `accounts` stays the one place a person lives.
- */
-interface IdentityLinkStore {
-    /** The account this external identity is linked to, or null. */
-    find(issuer: string, subject: string): Promise<string | null>;
-    /** Links it. Idempotent for the same account; throws when the identity is already linked to another one. */
-    link(accountId: string, issuer: string, subject: string, now: Date): Promise<void>;
-    /** Removes the link (the person unlinks Google); true when there was one. */
-    unlink(accountId: string, issuer: string, subject: string): Promise<boolean>;
-    /** The identities linked to an account, oldest first. */
-    list(accountId: string): Promise<{
-        issuer: string;
-        subject: string;
-        linkedAt: Date;
-    }[]>;
-}
-declare class IdentityLinkError extends Error {
-    readonly code = "ALREADY_LINKED";
-    constructor();
-}
-/** An in-memory store: the tests' adapter, and the reference the contract is written against. */
-declare function memoryIdentityLinks(): IdentityLinkStore;
-/** The table of links (idempotent). `accounts` is the product's account table. */
-declare function identityLinksMigration(): string;
-/** The store over the product's own database (`external_identities`; see `identityLinksMigration`). */
-declare function dbIdentityLinks(query: Query): IdentityLinkStore;
-
-export { type AccountDeps as A, memoryIdentityLinks as B, type CompleteOptions as C, memoryIdentityProvider as D, type ExternalIdentity as E, FEDERATED_PROVIDERS as F, passwordResetMail as G, pkceChallenge as H, type IdentityLinkStore as I, postgresAccounts as J, type Mail as M, PASSWORD_RESET_MAX_MINUTES as P, type Query as Q, type SessionSummary as S, type Theme as T, type IdentityProvider as a, AccountError as b, type AccountProfile as c, type AccountService as d, EMAIL_CHANGE_TTL_HOURS as e, FEDERATION_CODE as f, type FederatedProvider as g, type FederationCode as h, FederationError as i, IdentityLinkError as j, type MailLink as k, PASSWORD_RESET_MIN_MINUTES as l, PASSWORD_RESET_TTL_MINUTES as m, type ProfilePatch as n, type StartOptions as o, type StartedSignIn as p, dbAccounts as q, dbIdentityLinks as r, emailChangeMail as s, emailChangeToken as t, identityLinksMigration as u, isEmailChangeToken as v, isFederatedProvider as w, isLinkToken as x, isLocalReturn as y, linkToken as z };