@krizaka/auth 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,133 +1,54 @@
-/**
- * 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);
-}
+import { E as ExternalIdentity, I as IdentityLinkStore, a as IdentityProvider } from './identity-links-C5AG7Fbp.js';
+export { A as AccountDeps, b as AccountError, c as AccountProfile, d as AccountService, C as CompleteOptions, e as EMAIL_CHANGE_TTL_HOURS, F as FEDERATED_PROVIDERS, f as FEDERATION_CODE, g as FederatedProvider, h as FederationCode, i as FederationError, j as IdentityLinkError, M as Mail, k as MailLink, P as PASSWORD_RESET_MAX_MINUTES, l as PASSWORD_RESET_MIN_MINUTES, m as PASSWORD_RESET_TTL_MINUTES, n as ProfilePatch, Q as Query, S as SessionSummary, o as StartOptions, p as StartedSignIn, T as Theme, q as dbAccounts, r as dbIdentityLinks, s as emailChangeMail, t as emailChangeToken, u as identityLinksMigration, v as isEmailChangeToken, w as isFederatedProvider, x as isLinkToken, y as isLocalReturn, z as linkToken, B as memoryIdentityLinks, D as memoryIdentityProvider, G as passwordResetMail, H as pkceChallenge, J as postgresAccounts } from './identity-links-C5AG7Fbp.js';
 
-/** 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;
+/** What federated sign-in needs from the product's accounts: no second user table, just a look-up and, when registration is open, a creation. */
+interface FederatedAccounts {
+    /** The account that holds this address (lower case), and whether the product has verified it; null when none. */
+    findByEmail(email: string): Promise<{
+        id: string;
+        emailVerified: boolean;
+    } | null>;
+    /** Creates an account for a person the provider vouches for (address verified, no password). Absent when registration is closed. */
+    create?(identity: ExternalIdentity & {
+        email: string;
+    }): Promise<string>;
 }
-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>;
+/** Why a sign-in was refused: a stable code the product maps to its words. */
+declare const FEDERATED_REFUSAL: {
+    /** The provider did not verify the address (or gave none): nothing is linked, nothing is created. */
+    readonly emailNotVerified: "EMAIL_NOT_VERIFIED";
+    /** An account holds the address but the product never verified it: linking would let a stranger take it over. */
+    readonly accountEmailUnverified: "ACCOUNT_EMAIL_UNVERIFIED";
+    /** No account, and registration is closed. */
+    readonly noAccount: "NO_ACCOUNT";
+};
+type FederatedRefusal = (typeof FEDERATED_REFUSAL)[keyof typeof FEDERATED_REFUSAL];
+type FederatedSignInResult = 
+/** `via`: `link` already linked, `linked` attached to the account of that address now, `created` a new account. */
+{
+    status: "signed-in";
+    accountId: string;
+    via: "link" | "linked" | "created";
+} | {
+    status: "refused";
+    code: FederatedRefusal;
+};
+interface FederatedSignInDeps {
+    links: IdentityLinkStore;
+    accounts: FederatedAccounts;
+    clock: {
+        now(): Date;
     };
-    /** 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, `postgresAccounts` 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;
+/**
+ * From a verified external identity to an account of the product. The rule that matters: an identity attaches to an EXISTING account
+ * only when the address is verified on both sides — by the provider and by the product. Otherwise a stranger who registers at
+ * Facebook with your address would sign in as you.
+ */
+declare function createFederatedSignIn({ links, accounts, clock }: FederatedSignInDeps): {
+    signIn(identity: ExternalIdentity): Promise<FederatedSignInResult>;
 };
-/** The adapter over the product's own PostgreSQL (`accounts`, `sessions`, `email_changes`, `password_resets`; see `accountsMigration`). */
-declare function postgresAccounts(deps: AccountDeps): AccountService;
+type FederatedSignIn = ReturnType<typeof createFederatedSignIn>;
 
 /**
  * What the account adapter needs from a product's database, safe to run on a database that already has `accounts` and `sessions`:
@@ -250,4 +171,29 @@ declare function createRoles<Role extends string, Permission extends string>(dep
 };
 type Roles<Role extends string = string, Permission extends string = string> = ReturnType<typeof createRoles<Role, Permission>>;
 
-export { type AccountDeps, AccountError, type AccountProfile, type AccountService, EMAIL_CHANGE_TTL_HOURS, type Invitation, type Mail, type Member, PASSWORD_RESET_MAX_MINUTES, PASSWORD_RESET_MIN_MINUTES, PASSWORD_RESET_TTL_MINUTES, type ProfilePatch, type Query, ROLES_CODE, type RoleModel, type Roles, type RolesCode, type RolesDeps, RolesError, type RolesQuery, type SessionSummary, type Theme, accountsMigration, can, createRoles, defineRoles, emailChangeMail, emailChangeToken, isEmailChangeToken, isLinkToken, linkToken, passwordResetMail, postgresAccounts, rolesMigration };
+/** The `fetch` the adapter calls krizaka-users with (injected: no global, no network in tests). */
+type Fetcher = (url: string, init: {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+interface UsersFederationOptions {
+    /** The tenant host of the product: `https://auth.dev.akinaza.com`. */
+    baseUrl: string;
+    /** The product's public address: the start URL sends the person back to it, so `returnTo` is absolute from it. */
+    appUrl: string;
+    fetch: Fetcher;
+}
+/** Reads krizaka-users' answer into an identity; anything that is not a complete identity is refused. */
+declare function parseExternalIdentity(body: unknown): ExternalIdentity;
+/**
+ * The adapter for krizaka-users (`auth.<product>` tenant host, krizaka/krizaka-users#31): `start` builds the tenant's start address,
+ * `complete` exchanges the one-time code (and the PKCE verifier of a native app) for the verified identity.
+ */
+declare function usersIdentityProvider({ baseUrl, appUrl, fetch }: UsersFederationOptions): IdentityProvider;
+
+export { ExternalIdentity, FEDERATED_REFUSAL, type FederatedAccounts, type FederatedRefusal, type FederatedSignIn, type FederatedSignInDeps, type FederatedSignInResult, type Fetcher, IdentityLinkStore, IdentityProvider, type Invitation, type Member, ROLES_CODE, type RoleModel, type Roles, type RolesCode, type RolesDeps, RolesError, type RolesQuery, type UsersFederationOptions, accountsMigration, can, createFederatedSignIn, createRoles, defineRoles, parseExternalIdentity, rolesMigration, usersIdentityProvider };

package/dist/index.js

@@ -1,5 +1,19 @@
+import {
+  FEDERATED_PROVIDERS,
+  FEDERATION_CODE,
+  FederationError,
+  IdentityLinkError,
+  dbIdentityLinks,
+  identityLinksMigration,
+  isFederatedProvider,
+  isLocalReturn,
+  memoryIdentityLinks,
+  memoryIdentityProvider,
+  pkceChallenge
+} from "./chunk-H7AKE2OH.js";
+
 // src/accounts.ts
-import crypto from "crypto";
+import crypto2 from "crypto";
 import { addHours, addMinutes } from "date-fns";
 
 // src/port.ts
@@ -29,7 +43,7 @@ var NAME_MAX = 80;
 var PASSWORD_MIN = 12;
 var PASSWORD_MAX = 256;
 var THEMES = ["light", "dark", "system"];
-var linkToken = (prefix) => `${prefix}1.${crypto.randomBytes(32).toString("base64url")}`;
+var linkToken = (prefix) => `${prefix}1.${crypto2.randomBytes(32).toString("base64url")}`;
 var isLinkToken = (prefix, value) => !!value && new RegExp(`^${prefix}1\\.[A-Za-z0-9_-]{43}$`).test(value);
 var emailChangeToken = linkToken;
 var isEmailChangeToken = isLinkToken;
@@ -77,7 +91,7 @@ var cleanName = (raw) => {
   if (name.length > NAME_MAX) throw new AccountError(400, "BAD_REQUEST", `A name is at most ${NAME_MAX} characters`);
   return name;
 };
-function postgresAccounts(deps) {
+function dbAccounts(deps) {
   const { query } = deps;
   const resetTtlMinutes = checkResetTtl(deps.passwordResetTtlMinutes ?? PASSWORD_RESET_TTL_MINUTES);
   const transaction = deps.transaction ?? ((work) => work(query));
@@ -120,7 +134,7 @@ function postgresAccounts(deps) {
       const token = (deps.token ?? (() => emailChangeToken(deps.tokenPrefix)))();
       await query("INSERT INTO email_changes (account_id, new_email, token_hash, expires_at) VALUES ($1, $2, $3, $4)", [id, address, deps.tokenHash(token), addHours(now, EMAIL_CHANGE_TTL_HOURS)]);
       const url = `${deps.baseUrl.replace(/\/$/, "")}/${profile.locale}/confirm-email?token=${encodeURIComponent(token)}`;
-      await deps.mail({ to: address, locale: profile.locale, ...emailChangeMail(deps.product, profile.locale, url) });
+      await deps.mail({ to: address, locale: profile.locale, ...emailChangeMail(deps.product, profile.locale, url), link: { kind: "emailChange", url, hours: EMAIL_CHANGE_TTL_HOURS } });
     },
     async confirmEmailChange(token, now) {
       if (!isEmailChangeToken(deps.tokenPrefix, token)) return "INVALID";
@@ -154,7 +168,7 @@ function postgresAccounts(deps) {
       });
       if (!issued) return;
       const url = `${deps.baseUrl.replace(/\/$/, "")}/${issued.locale}/reset-password?token=${encodeURIComponent(issued.token)}`;
-      await deps.mail({ to: address, locale: issued.locale, ...passwordResetMail(deps.product, issued.locale, url, resetTtlMinutes) });
+      await deps.mail({ to: address, locale: issued.locale, ...passwordResetMail(deps.product, issued.locale, url, resetTtlMinutes), link: { kind: "passwordReset", url, minutes: resetTtlMinutes } });
     },
     async resetPassword(token, next, now) {
       if (next.length < PASSWORD_MIN) throw new AccountError(400, "PASSWORD_TOO_SHORT", `At least ${PASSWORD_MIN} characters`);
@@ -186,6 +200,37 @@ function postgresAccounts(deps) {
     }
   };
 }
+var postgresAccounts = dbAccounts;
+
+// src/federated-sign-in.ts
+var FEDERATED_REFUSAL = {
+  /** The provider did not verify the address (or gave none): nothing is linked, nothing is created. */
+  emailNotVerified: "EMAIL_NOT_VERIFIED",
+  /** An account holds the address but the product never verified it: linking would let a stranger take it over. */
+  accountEmailUnverified: "ACCOUNT_EMAIL_UNVERIFIED",
+  /** No account, and registration is closed. */
+  noAccount: "NO_ACCOUNT"
+};
+function createFederatedSignIn({ links, accounts, clock }) {
+  return {
+    async signIn(identity) {
+      const known = await links.find(identity.issuer, identity.subject);
+      if (known) return { status: "signed-in", accountId: known, via: "link" };
+      const email = identity.email?.trim().toLowerCase();
+      if (!email || !identity.emailVerified) return { status: "refused", code: FEDERATED_REFUSAL.emailNotVerified };
+      const existing = await accounts.findByEmail(email);
+      if (existing) {
+        if (!existing.emailVerified) return { status: "refused", code: FEDERATED_REFUSAL.accountEmailUnverified };
+        await links.link(existing.id, identity.issuer, identity.subject, clock.now());
+        return { status: "signed-in", accountId: existing.id, via: "linked" };
+      }
+      if (!accounts.create) return { status: "refused", code: FEDERATED_REFUSAL.noAccount };
+      const accountId = await accounts.create({ ...identity, email });
+      await links.link(accountId, identity.issuer, identity.subject, clock.now());
+      return { status: "signed-in", accountId, via: "created" };
+    }
+  };
+}
 
 // src/migration.ts
 function accountsMigration(options = {}) {
@@ -248,7 +293,7 @@ CREATE INDEX IF NOT EXISTS invitations_scope ON invitations(scope_id) WHERE used
 }
 
 // src/roles.ts
-import crypto2 from "crypto";
+import crypto3 from "crypto";
 import { addHours as addHours2 } from "date-fns";
 var defineRoles = (model) => model;
 var can = (model, role, permission) => !!role && model.permissions[role].includes(permission);
@@ -279,7 +324,7 @@ function createRoles(deps) {
     if (!known(role)) throw new RolesError(ROLES_CODE.unknownRole);
     return role;
   };
-  const newToken = deps.token ?? (() => `${deps.tokenPrefix}1.${crypto2.randomBytes(32).toString("base64url")}`);
+  const newToken = deps.token ?? (() => `${deps.tokenPrefix}1.${crypto3.randomBytes(32).toString("base64url")}`);
   const owners = (scopeId) => query("SELECT account_id FROM memberships WHERE scope_id = $1 AND role = $2", [scopeId, ownerRole()]);
   const ownerRole = () => model.roles.find((r) => model.roles.every((x) => model.manages[r].includes(x) || x === r)) ?? model.roles[0];
   async function roleOf(accountId, scopeId) {
@@ -345,7 +390,7 @@ function createRoles(deps) {
       const token = newToken();
       const [row] = await query(
         "INSERT INTO invitations (id, scope_id, email, role, token_hash, invited_by, created_at, expires_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8) RETURNING id, created_at, expires_at",
-        [crypto2.randomUUID(), scopeId, email, role, deps.tokenHash(token), actor.id, now, addHours2(now, deps.inviteTtlHours)]
+        [crypto3.randomUUID(), scopeId, email, role, deps.tokenHash(token), actor.id, now, addHours2(now, deps.inviteTtlHours)]
       );
       return { token, invitation: { id: row.id, email, role, createdAt: row.created_at, expiresAt: row.expires_at } };
     },
@@ -376,9 +421,53 @@ function createRoles(deps) {
     }
   };
 }
+
+// src/users-federation.ts
+var START = (base, provider) => `${base}/api/v1/auth/web/${provider}/start`;
+var EXCHANGE = (base) => `${base}/api/v1/auth/web/exchange`;
+var text = (value) => typeof value === "string" && value.length > 0 ? value : null;
+function parseExternalIdentity(body) {
+  const o = body ?? {};
+  const issuer = text(o.issuer);
+  const subject = text(o.subject);
+  if (!issuer || !subject) throw new FederationError(FEDERATION_CODE.unavailable, "krizaka-users answered without an issuer and a subject");
+  return { issuer, subject, email: text(o.email), emailVerified: o.email_verified === true, name: text(o.name) };
+}
+function usersIdentityProvider({ baseUrl, appUrl, fetch }) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const app = appUrl.replace(/\/+$/, "");
+  return {
+    async start(provider, returnTo, options = {}) {
+      if (!isFederatedProvider(provider)) throw new FederationError(FEDERATION_CODE.unknownProvider, `Unknown provider ${String(provider)}`);
+      if (!isLocalReturn(returnTo)) throw new FederationError(FEDERATION_CODE.badReturn, "That return address is not allowed");
+      const state = crypto.randomUUID();
+      const query = new URLSearchParams({ return_to: `${app}${returnTo}`, state });
+      if (options.codeChallenge) {
+        query.set("code_challenge", options.codeChallenge);
+        query.set("code_challenge_method", "S256");
+      }
+      return { url: `${START(base, provider)}?${query}`, state };
+    },
+    async complete(code, options = {}) {
+      const response = await fetch(EXCHANGE(base), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code, ...options.codeVerifier ? { code_verifier: options.codeVerifier } : {} })
+      });
+      if (response.status === 400 || response.status === 401 || response.status === 404 || response.status === 410) throw new FederationError(FEDERATION_CODE.invalidCode, "That code is not valid");
+      if (!response.ok) throw new FederationError(FEDERATION_CODE.unavailable, `krizaka-users answered ${response.status}`);
+      return parseExternalIdentity(await response.json());
+    }
+  };
+}
 export {
   AccountError,
   EMAIL_CHANGE_TTL_HOURS,
+  FEDERATED_PROVIDERS,
+  FEDERATED_REFUSAL,
+  FEDERATION_CODE,
+  FederationError,
+  IdentityLinkError,
   PASSWORD_RESET_MAX_MINUTES,
   PASSWORD_RESET_MIN_MINUTES,
   PASSWORD_RESET_TTL_MINUTES,
@@ -386,15 +475,26 @@ export {
   RolesError,
   accountsMigration,
   can,
+  createFederatedSignIn,
   createRoles,
+  dbAccounts,
+  dbIdentityLinks,
   defineRoles,
   emailChangeMail,
   emailChangeToken,
+  identityLinksMigration,
   isEmailChangeToken,
+  isFederatedProvider,
   isLinkToken,
+  isLocalReturn,
   linkToken,
+  memoryIdentityLinks,
+  memoryIdentityProvider,
+  parseExternalIdentity,
   passwordResetMail,
+  pkceChallenge,
   postgresAccounts,
-  rolesMigration
+  rolesMigration,
+  usersIdentityProvider
 };
 //# sourceMappingURL=index.js.map