@rexezuge/identity 0.0.0-stage → 1.0.1

package/dist/UserIdentityService.js

@@ -0,0 +1,151 @@
+import { BadRequestError } from '@rexezuge/errors';
+import { isValidEmailFormat } from '@rexezuge/shared';
+import { TimestampUtil } from '@rexezuge/shared';
+import { registerAccount, resolveAccount } from './accountLookup';
+import { newAnchor, summarize } from './ResolvedAccount';
+import { UserDAO } from './UserDAO';
+import { UserEmailDAO } from './UserEmailDAO';
+/**
+ * The account behind an address, plus the address-change operations.
+ *
+ * Converged from `backend-services/src/identity/UserIdentityService.ts`
+ * (identical in Durable-DAV, Durable-DAV-Router, Edge-Git, Mail-Otter; AWS and
+ * Mail-Meow keep the resolve core). Canonical names merge the two spellings the
+ * repos used — `resolveUserById` (Durable-DAV family) and
+ * `resolveAccountById` (AWS) are one method, `resolveAccountById`.
+ *
+ * The instance is one per request scope: the ownership and permission paths
+ * resolve the same caller several times each, and a per-instance address memo
+ * costs one query per request rather than one per comparison. Bind it once in
+ * the composition root and share it — constructing per consumer is the bug the
+ * memo exists to prevent.
+ *
+ * Resolution itself lives in `accountLookup` (free functions, shared with any
+ * account bootstrap); this class adds memoization and the change operations.
+ */
+export class UserIdentityService {
+    deps;
+    byEmail = new Map();
+    constructor(env, deps = {}) {
+        this.deps = {
+            userDAO: () => Promise.resolve(new UserDAO(env.DB)),
+            userEmailDAO: () => Promise.resolve(new UserEmailDAO(env.DB)),
+            ...deps,
+        };
+    }
+    /**
+     * Resolve a sign-in address to its account, or null when unknown.
+     *
+     * Only a verified address resolves. A revoked address (changed away from) is
+     * retained so pre-change rows stay attributable, but it must never
+     * authenticate, otherwise a reassigned address would inherit the previous
+     * holder's account.
+     */
+    async resolveAccount(email) {
+        const key = email.trim().toLowerCase();
+        if (!isValidEmailFormat(key))
+            return null;
+        if (this.byEmail.has(key))
+            return this.byEmail.get(key) ?? null;
+        const resolved = await resolveAccount(this.deps, key);
+        this.byEmail.set(key, resolved);
+        return resolved;
+    }
+    /** Account id for a sign-in address, or null when unknown. */
+    async resolveAccountId(email) {
+        const account = await this.resolveAccount(email);
+        return account?.id ?? null;
+    }
+    /**
+     * Account behind a stable key. The inverse direction, for a caller that
+     * already holds one (a resource owner) and needs the current address.
+     */
+    async resolveAccountById(userId) {
+        const userDAO = await this.deps.userDAO();
+        const row = await userDAO.getById(userId);
+        return summarize(row);
+    }
+    /**
+     * Resolve-or-create, for a login path that may see a first-time user.
+     *
+     * Returns null when the address exists but cannot be resolved (a revoked
+     * address) — a caller that needs "guaranteed account" must distinguish that
+     * from "created now" through its own route, because silently registering on a
+     * revoked address would hand the previous holder's history to the new one.
+     */
+    async resolveOrRegister(email, now = TimestampUtil.getCurrentUnixTimestampInSeconds()) {
+        const existing = await this.resolveAccount(email);
+        if (existing)
+            return existing;
+        const key = email.trim().toLowerCase();
+        // The anchor is the address itself whenever it is free. When it is already
+        // held as another account's anchor — its previous holder moved off it — the
+        // opaque-anchor retry is what lets a released address be used again.
+        const account = (await registerAccount(this.deps, key, key, now)) ?? (await registerAccount(this.deps, key, newAnchor(), now));
+        this.byEmail.set(key, account);
+        return account;
+    }
+    /**
+     * Every address known for an account, verified ones first.
+     */
+    async listAddresses(userId) {
+        const emailDAO = await this.deps.userEmailDAO();
+        const rows = await emailDAO.listByUserId(userId);
+        return rows.map((row) => ({ email: row.email, isVerified: row.is_verified === 1 }));
+    }
+    /**
+     * Point an account at a new sign-in address.
+     *
+     * The account id, the frozen anchor, and every id-keyed row are untouched:
+     * only which address authenticates the account moves. The previous address is
+     * revoked rather than deleted, so rows written before the change still resolve
+     * to this account, and it is released for a later legitimate holder.
+     *
+     * Rejects an address already verified for another account. That check is the
+     * whole reason this is not simply an `UPDATE`: an unverified change would let
+     * anyone claim an address and inherit its history.
+     *
+     * Order is load-bearing, and it is the one the ops CLI (`change-email.ts`)
+     * already gets right: claim first, move `current_email` second, revoke third.
+     * Inverting it opens a window in which nothing authenticates if a later step
+     * fails.
+     */
+    async setPrimaryEmail(userId, newEmail, now = TimestampUtil.getCurrentUnixTimestampInSeconds()) {
+        const email = newEmail.trim().toLowerCase();
+        if (!isValidEmailFormat(email))
+            throw new BadRequestError('Invalid email address');
+        const userDAO = await this.deps.userDAO();
+        const emailDAO = await this.deps.userEmailDAO();
+        const row = await userDAO.getById(userId);
+        if (!row?.id)
+            throw new BadRequestError('User not found');
+        const current = (row.current_email ?? row.email).toLowerCase();
+        if (current === email) {
+            return { id: row.id, email, anchorEmail: row.email, username: row.username ?? null };
+        }
+        const holder = await emailDAO.resolveVerified(email);
+        if (holder && holder.user_id !== row.id)
+            throw new BadRequestError('Email is already in use');
+        await emailDAO.register({ email, userId: row.id, isVerified: true, now });
+        await userDAO.setCurrentEmail(row.id, email, now);
+        // Revoke every other verified address, so only the new one authenticates.
+        await emailDAO.revokeAllVerified(row.id, email);
+        this.byEmail.delete(current);
+        this.byEmail.set(email, { id: row.id, email, anchorEmail: row.email, username: row.username ?? null });
+        return { id: row.id, email, anchorEmail: row.email, username: row.username ?? null };
+    }
+    /**
+     * Ops/migration path: attach an address that has already been proven, without
+     * making it the sign-in address.
+     */
+    async linkVerifiedEmail(userId, email, now = TimestampUtil.getCurrentUnixTimestampInSeconds()) {
+        const address = email.trim().toLowerCase();
+        if (!isValidEmailFormat(address))
+            throw new BadRequestError('Invalid email address');
+        const emailDAO = await this.deps.userEmailDAO();
+        const outcome = await emailDAO.register({ email: address, userId, isVerified: true, now });
+        if (outcome === 'already-claimed')
+            throw new BadRequestError('Email is already in use');
+    }
+}
+//# sourceMappingURL=UserIdentityService.js.map

package/dist/UserIdentityService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserIdentityService.js","sourceRoot":"","sources":["../src/UserIdentityService.ts"],"names":[],"mappings":"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"}

package/dist/accountLookup.d.ts

@@ -0,0 +1,45 @@
+import type { ResolvedAccount } from './ResolvedAccount';
+import { UserDAO } from './UserDAO';
+import { UserEmailDAO } from './UserEmailDAO';
+/**
+ * Injected DAO factories. All optional: each defaults to a real DAO over the
+ * same D1 binding, so tests override only what they need.
+ */
+export interface AccountLookupDeps {
+    userDAO: () => Promise<UserDAO>;
+    userEmailDAO: () => Promise<UserEmailDAO>;
+}
+/**
+ * Address -> account resolution, as free functions so the service and any
+ * higher-level account bootstrap share one implementation instead of
+ * re-deriving the query.
+ *
+ * Converged from `backend-services/src/user/accountLookup.ts` (identical in
+ * Durable-DAV, Durable-DAV-Router, Edge-Git, Mail-Otter).
+ */
+export declare function resolveAccount(deps: AccountLookupDeps, email: string): Promise<ResolvedAccount | null>;
+/** Account id for a sign-in address, or null when unknown. */
+export declare function resolveUserId(deps: AccountLookupDeps, email: string): Promise<string | null>;
+/**
+ * Insert an account and claim its sign-in address.
+ *
+ * The anchor is the address itself whenever it is free, which keeps new rows
+ * shaped like the pre-identity ones. It falls back to an opaque anchor only when
+ * the address is already held as another account's anchor — i.e. its previous
+ * holder moved off it — so a released address is never permanently unusable.
+ *
+ * Returns null when the insert could not produce a *new* account holding this
+ * address, which is the caller's signal to retry with a different anchor.
+ *
+ * The read-back is load-bearing, not defensive. `createUser` is
+ * `ON CONFLICT(email) DO NOTHING`, so when the anchor is already taken the
+ * insert is silently a no-op and the generated `id` belongs to nobody. Trusting
+ * it would (a) re-point the address registry at a phantom account that resolves
+ * to nothing, permanently stranding the address, and (b) on the opaque-anchor
+ * retry, hand the caller an account whose address the registry refuses to
+ * re-point because the phantom row already marked it verified. Re-reading the
+ * anchor row and requiring *our* id to be the one there makes the no-op
+ * detectable, so the retry gets a genuinely new account.
+ */
+export declare function registerAccount(deps: AccountLookupDeps, loginEmail: string, anchor: string, now: number): Promise<ResolvedAccount | null>;
+//# sourceMappingURL=accountLookup.d.ts.map

package/dist/accountLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountLookup.d.ts","sourceRoot":"","sources":["../src/accountLookup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA0C5G;AAED,8DAA8D;AAC9D,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGlG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,iBAAiB,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC"}

package/dist/accountLookup.js

@@ -0,0 +1,107 @@
+import { isMissingSchemaError } from '@rexezuge/d1';
+import { summarize } from './ResolvedAccount';
+/**
+ * Address -> account resolution, as free functions so the service and any
+ * higher-level account bootstrap share one implementation instead of
+ * re-deriving the query.
+ *
+ * Converged from `backend-services/src/user/accountLookup.ts` (identical in
+ * Durable-DAV, Durable-DAV-Router, Edge-Git, Mail-Otter).
+ */
+export async function resolveAccount(deps, email) {
+    const normalized = email.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    const userDAO = await deps.userDAO();
+    // A known address is authoritative: the registry says which account it belongs
+    // to, and a *revoked* row (the account moved off this address) must not
+    // resolve at all. Falling through to the legacy lookups in that case would let
+    // a reassigned address keep authenticating the previous holder's account.
+    //
+    // Only a *missing registry* falls through, and "missing" means one specific
+    // thing: the identity migration has not run. The previous
+    // `.catch(() => null)` answered that question for **every** failure, so a
+    // transient D1 error on this one statement made the code proceed to the anchor
+    // lookup below — `getByEmail`, which is an attribution lookup whose key is a
+    // re-registrable string, not an identity. An address whose account had moved
+    // off it (so its `user_emails` row is revoked, and correctly refuses to
+    // resolve) would then be resolved against the *previous holder's* anchor, and
+    // that account's id was installed as the caller's identity: full access to
+    // someone else's rows from one failed `SELECT`.
+    //
+    // So the degradation is narrowed to `isMissingSchemaError`, and everything
+    // else rethrows.
+    const registered = await deps
+        .userEmailDAO()
+        .then((dao) => dao.get(normalized))
+        .catch((error) => {
+        if (isMissingSchemaError(error))
+            return null;
+        throw error;
+    });
+    if (registered) {
+        return registered.is_verified === 1 ? summarize(await userDAO.getById(registered.user_id)) : null;
+    }
+    // No registry row at all. Safe to fall through: the identity migration
+    // backfilled a verified row for every anchor, so a row-less address is either
+    // new or on a pre-identity database, where the address *is* the anchor.
+    //
+    // No `.catch` on either: a failed `users` read is an outage, and reporting it
+    // as "no such account" would turn a D1 blip into a 404 and a spurious
+    // re-registration attempt.
+    const byCurrent = await userDAO.getByCurrentEmail(normalized);
+    const legacy = byCurrent ?? (await userDAO.getByEmail(normalized));
+    return summarize(legacy);
+}
+/** Account id for a sign-in address, or null when unknown. */
+export async function resolveUserId(deps, email) {
+    const account = await resolveAccount(deps, email);
+    return account?.id ?? null;
+}
+/**
+ * Insert an account and claim its sign-in address.
+ *
+ * The anchor is the address itself whenever it is free, which keeps new rows
+ * shaped like the pre-identity ones. It falls back to an opaque anchor only when
+ * the address is already held as another account's anchor — i.e. its previous
+ * holder moved off it — so a released address is never permanently unusable.
+ *
+ * Returns null when the insert could not produce a *new* account holding this
+ * address, which is the caller's signal to retry with a different anchor.
+ *
+ * The read-back is load-bearing, not defensive. `createUser` is
+ * `ON CONFLICT(email) DO NOTHING`, so when the anchor is already taken the
+ * insert is silently a no-op and the generated `id` belongs to nobody. Trusting
+ * it would (a) re-point the address registry at a phantom account that resolves
+ * to nothing, permanently stranding the address, and (b) on the opaque-anchor
+ * retry, hand the caller an account whose address the registry refuses to
+ * re-point because the phantom row already marked it verified. Re-reading the
+ * anchor row and requiring *our* id to be the one there makes the no-op
+ * detectable, so the retry gets a genuinely new account.
+ */
+export async function registerAccount(deps, loginEmail, anchor, now) {
+    const userDAO = await deps.userDAO();
+    const created = await userDAO.createUser({ anchor, loginEmail, now });
+    // `null` is the detected no-op: the anchor was already held. The caller's
+    // signal to retry with an opaque anchor — see `newAnchor`.
+    if (created === null)
+        return null;
+    // Claim the sign-in address *before* resolving, otherwise the fresh account is
+    // invisible to the registry and registration looks like a failure. An address
+    // already verified for another account is left alone by `register`, and the
+    // resolve below then reports that account instead.
+    await deps
+        .userEmailDAO()
+        .then((dao) => dao.register({ email: loginEmail, userId: created, isVerified: true, now }))
+        .catch((error) => {
+        // Pre-identity registry only, per the same rule `resolveAccount` follows: a
+        // missing table is tolerated, a failed write is not. Swallowing the second
+        // would return an account the address registry has never heard of, which
+        // resolves to nothing on the next login.
+        if (isMissingSchemaError(error))
+            return;
+        throw error;
+    });
+    return resolveAccount(deps, loginEmail);
+}
+//# sourceMappingURL=accountLookup.js.map

package/dist/accountLookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountLookup.js","sourceRoot":"","sources":["../src/accountLookup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAc9C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAuB,EAAE,KAAa;IACzE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACrC,+EAA+E;IAC/E,wEAAwE;IACxE,+EAA+E;IAC/E,0EAA0E;IAC1E,EAAE;IACF,4EAA4E;IAC5E,0DAA0D;IAC1D,0EAA0E;IAC1E,+EAA+E;IAC/E,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,8EAA8E;IAC9E,2EAA2E;IAC3E,gDAAgD;IAChD,EAAE;IACF,2EAA2E;IAC3E,iBAAiB;IACjB,MAAM,UAAU,GAAG,MAAM,IAAI;SAC1B,YAAY,EAAE;SACd,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;SAClC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,IAAI,oBAAoB,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACL,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpG,CAAC;IACD,uEAAuE;IACvE,8EAA8E;IAC9E,wEAAwE;IACxE,EAAE;IACF,8EAA8E;IAC9E,sEAAsE;IACtE,2BAA2B;IAC3B,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACnE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAuB,EAAE,KAAa;IACxE,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAClD,OAAO,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAuB,EACvB,UAAkB,EAClB,MAAc,EACd,GAAW;IAEX,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACtE,0EAA0E;IAC1E,2DAA2D;IAC3D,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,+EAA+E;IAC/E,8EAA8E;IAC9E,4EAA4E;IAC5E,mDAAmD;IACnD,MAAM,IAAI;SACP,YAAY,EAAE;SACd,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;SAC1F,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,4EAA4E;QAC5E,2EAA2E;QAC3E,yEAAyE;QACzE,yCAAyC;QACzC,IAAI,oBAAoB,CAAC,KAAK,CAAC;YAAE,OAAO;QACxC,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACL,OAAO,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAC1C,CAAC"}

package/dist/applyMigrations.d.ts

@@ -0,0 +1,33 @@
+import type { D1Queryable } from '@rexezuge/d1';
+/**
+ * The identity migrations this package ships, by filename. `IDENTITY_MIGRATIONS`
+ * in `migrations.ts` carries the same pair with the reasoning; this map is the
+ * executable form.
+ */
+declare const IDENTITY_MIGRATION_SQL: {
+    readonly 'users.sql': "\n-- The account. The anchor (email) is immutable; current_email is the login.\nCREATE TABLE IF NOT EXISTS users (\n  id TEXT NOT NULL PRIMARY KEY,\n  email TEXT NOT NULL UNIQUE,\n  current_email TEXT NOT NULL UNIQUE,\n  username TEXT,\n  created_at INTEGER NOT NULL,\n  updated_at INTEGER\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_id ON users(id);\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_current_email ON users(current_email);\n\n-- The address registry: which account an address authenticates.\nCREATE TABLE IF NOT EXISTS user_emails (\n  email TEXT PRIMARY KEY,\n  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\n  is_verified INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_user_emails_user ON user_emails(user_id);\n";
+    readonly 'upgrade-user-identity.sql': "\n-- Phase 1: stable account key.\n-- SQLite cannot add a PRIMARY KEY column, so the id is a plain column with a\n-- unique index. A unique index is a valid foreign key parent, which is all the\n-- user_id references need.\nALTER TABLE users ADD COLUMN id TEXT;\n\nUPDATE users SET id = 'usr_' || lower(hex(randomblob(16))) WHERE id IS NULL;\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_id ON users(id);\n\n-- Phase 2: mutable sign-in address.\n-- 'email' stays as the frozen anchor; 'current_email' is what the account signs\n-- in with and what the API reports. Uniqueness is enforced here, so an address\n-- can never be claimed by two accounts.\nALTER TABLE users ADD COLUMN current_email TEXT;\n\nUPDATE users SET current_email = lower(email) WHERE current_email IS NULL;\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_current_email ON users(current_email);\n\n-- Phase 3: address registry.\n-- Login resolution consults is_verified = 1 only. Backfilled from the frozen\n-- anchor address of every existing account, lowercased so a legacy mixed-case\n-- row still yields exactly one login identity.\nCREATE TABLE IF NOT EXISTS user_emails (\n  email TEXT PRIMARY KEY,\n  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\n  is_verified INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_user_emails_user ON user_emails(user_id);\n\nINSERT OR IGNORE INTO user_emails (email, user_id, is_verified, created_at)\nSELECT lower(email), id, 1, created_at FROM users;\n";
+};
+type IdentityMigrationName = keyof typeof IDENTITY_MIGRATION_SQL;
+/** The full fresh-install order. */
+declare const FRESH_MIGRATIONS: readonly IdentityMigrationName[];
+/** A legacy database applies the upgrade after the fresh schema is in place. */
+declare const UPGRADE_MIGRATIONS: readonly IdentityMigrationName[];
+/**
+ * Apply the identity migrations to a D1 binding.
+ *
+ * Split and executed through `@rexezuge/d1` — the same statement splitter the
+ * test helpers use — so a kit migration and an integration suite can never
+ * disagree about where one statement ends. One `batch()` per file, matching
+ * D1's own per-file apply, so a failure names its file.
+ *
+ * `upgrade: false` (the default) applies only the fresh-install schema. Pass
+ * `upgrade: true` for a database whose `users` table predates the identity
+ * columns; the upgrade file is rerunnable, so applying both is safe.
+ */
+declare function applyIdentityMigrations(db: D1Queryable, options?: {
+    upgrade?: boolean;
+}): Promise<void>;
+export { applyIdentityMigrations, IDENTITY_MIGRATION_SQL, FRESH_MIGRATIONS, UPGRADE_MIGRATIONS };
+export type { IdentityMigrationName };
+//# sourceMappingURL=applyMigrations.d.ts.map

package/dist/applyMigrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyMigrations.d.ts","sourceRoot":"","sources":["../src/applyMigrations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;GAIG;AACH,QAAA,MAAM,sBAAsB;;;CAGlB,CAAC;AAEX,KAAK,qBAAqB,GAAG,MAAM,OAAO,sBAAsB,CAAC;AAEjE,oCAAoC;AACpC,QAAA,MAAM,gBAAgB,EAAE,SAAS,qBAAqB,EAAkB,CAAC;AAEzE,gFAAgF;AAChF,QAAA,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAA+C,CAAC;AAExG;;;;;;;;;;;GAWG;AACH,iBAAe,uBAAuB,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1G;AAED,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;AACjG,YAAY,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/applyMigrations.js

@@ -0,0 +1,44 @@
+import { executableStatements } from '@rexezuge/d1';
+import { UPGRADE_USER_IDENTITY, USERS_SCHEMA } from './migrations';
+/**
+ * The identity migrations this package ships, by filename. `IDENTITY_MIGRATIONS`
+ * in `migrations.ts` carries the same pair with the reasoning; this map is the
+ * executable form.
+ */
+const IDENTITY_MIGRATION_SQL = {
+    'users.sql': USERS_SCHEMA,
+    'upgrade-user-identity.sql': UPGRADE_USER_IDENTITY,
+};
+/** The full fresh-install order. */
+const FRESH_MIGRATIONS = ['users.sql'];
+/** A legacy database applies the upgrade after the fresh schema is in place. */
+const UPGRADE_MIGRATIONS = ['users.sql', 'upgrade-user-identity.sql'];
+/**
+ * Apply the identity migrations to a D1 binding.
+ *
+ * Split and executed through `@rexezuge/d1` — the same statement splitter the
+ * test helpers use — so a kit migration and an integration suite can never
+ * disagree about where one statement ends. One `batch()` per file, matching
+ * D1's own per-file apply, so a failure names its file.
+ *
+ * `upgrade: false` (the default) applies only the fresh-install schema. Pass
+ * `upgrade: true` for a database whose `users` table predates the identity
+ * columns; the upgrade file is rerunnable, so applying both is safe.
+ */
+async function applyIdentityMigrations(db, options = {}) {
+    const names = options.upgrade === true ? UPGRADE_MIGRATIONS : FRESH_MIGRATIONS;
+    for (const name of names) {
+        const statements = executableStatements(IDENTITY_MIGRATION_SQL[name]);
+        if (statements.length === 0)
+            continue;
+        if (db.batch) {
+            await db.batch(statements.map((sql) => db.prepare(sql)));
+            continue;
+        }
+        for (const sql of statements) {
+            await db.prepare(sql).run();
+        }
+    }
+}
+export { applyIdentityMigrations, IDENTITY_MIGRATION_SQL, FRESH_MIGRATIONS, UPGRADE_MIGRATIONS };
+//# sourceMappingURL=applyMigrations.js.map

package/dist/applyMigrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyMigrations.js","sourceRoot":"","sources":["../src/applyMigrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE;;;;GAIG;AACH,MAAM,sBAAsB,GAAG;IAC7B,WAAW,EAAE,YAAY;IACzB,2BAA2B,EAAE,qBAAqB;CAC1C,CAAC;AAIX,oCAAoC;AACpC,MAAM,gBAAgB,GAAqC,CAAC,WAAW,CAAC,CAAC;AAEzE,gFAAgF;AAChF,MAAM,kBAAkB,GAAqC,CAAC,WAAW,EAAE,2BAA2B,CAAC,CAAC;AAExG;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,uBAAuB,CAAC,EAAe,EAAE,UAAiC,EAAE;IACzF,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC/E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACtC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACzD,SAAS;QACX,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC;AAED,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@rexezuge/identity` — the account layer: the address is not the account.
+ *
+ * Converged from the seven repos that authenticate users (all but
+ * ChordDHT-Tracker, whose callers are certificates). Durable-DAV's invariants
+ * are the canonical ones because they are the strictest: the frozen anchor,
+ * the verified-only registry, and the fail-closed resolution order.
+ */
+export { registerAccount, resolveAccount, resolveUserId } from './accountLookup';
+export type { AccountLookupDeps } from './accountLookup';
+export { applyIdentityMigrations, IDENTITY_MIGRATION_SQL, FRESH_MIGRATIONS, UPGRADE_MIGRATIONS } from './applyMigrations';
+export type { IdentityMigrationName } from './applyMigrations';
+export { IDENTITY_MIGRATIONS, UPGRADE_USER_IDENTITY, USERS_SCHEMA } from './migrations';
+export { newAccountId, newAnchor, summarize } from './ResolvedAccount';
+export type { AccountSummary, ResolvedAccount, UserRow, UserRowLike } from './ResolvedAccount';
+export { UserDAO } from './UserDAO';
+export { UserEmailDAO } from './UserEmailDAO';
+export type { EmailClaim, UserEmailRow } from './UserEmailDAO';
+export { UserIdentityService } from './UserIdentityService';
+export type { UserIdentityDeps, UserIdentityEnv } from './UserIdentityService';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1H,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@rexezuge/identity` — the account layer: the address is not the account.
+ *
+ * Converged from the seven repos that authenticate users (all but
+ * ChordDHT-Tracker, whose callers are certificates). Durable-DAV's invariants
+ * are the canonical ones because they are the strictest: the frozen anchor,
+ * the verified-only registry, and the fail-closed resolution order.
+ */
+export { registerAccount, resolveAccount, resolveUserId } from './accountLookup';
+export { applyIdentityMigrations, IDENTITY_MIGRATION_SQL, FRESH_MIGRATIONS, UPGRADE_MIGRATIONS } from './applyMigrations';
+export { IDENTITY_MIGRATIONS, UPGRADE_USER_IDENTITY, USERS_SCHEMA } from './migrations';
+export { newAccountId, newAnchor, summarize } from './ResolvedAccount';
+export { UserDAO } from './UserDAO';
+export { UserEmailDAO } from './UserEmailDAO';
+export { UserIdentityService } from './UserIdentityService';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE1H,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/migrations.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The canonical `users` / `user_emails` schema.
+ *
+ * Converged from migration `0001_init.sql` + `0004_user_identity.sql` across the
+ * identity-carrying repos, expressed as the *final* shape so a fresh database
+ * never has to be upgraded: `users.id` is the account key from the start, and
+ * `user_emails` exists from the start.
+ *
+ * The invariants that make an address change safe (Durable-DAV's design, which
+ * is the strictest in the family and the one every other repo's upgrade is
+ * migrating toward):
+ *
+ * - `users.id` is an opaque, unique account key — never an address.
+ * - `users.email` is the **frozen anchor**: immutable, the foreign-key target
+ *   every legacy `*_email` value resolves against, so history survives a change.
+ * - `users.current_email` is the mutable sign-in address; unique, so an address
+ *   can never be claimed by two accounts.
+ * - `users.username` is a separately-mutable public handle, not the identity.
+ * - `user_emails` is the address registry: `is_verified = 1` may authenticate;
+ *   a changed-from address stays at `0` (attributable, non-authenticating) and
+ *   is re-pointable by a later claimant.
+ *
+ * The anchor design is forced on D1: it honours neither
+ * `PRAGMA foreign_keys = off` nor `legacy_alter_table`, and `defer_foreign_keys`
+ * does not suppress `ON DELETE CASCADE`, so a live reference cannot be repointed
+ * without losing rows. A fresh install just starts with the anchor in place.
+ *
+ * A repo with legacy tables that reference `users(email)` applies this file's
+ * statements and then adds its own additive backfill (the converged pattern is
+ * in `upgrade-user-identity.sql`), repointing each legacy column through
+ * `user_emails` rather than through the anchor.
+ */
+declare const USERS_SCHEMA = "\n-- The account. The anchor (email) is immutable; current_email is the login.\nCREATE TABLE IF NOT EXISTS users (\n  id TEXT NOT NULL PRIMARY KEY,\n  email TEXT NOT NULL UNIQUE,\n  current_email TEXT NOT NULL UNIQUE,\n  username TEXT,\n  created_at INTEGER NOT NULL,\n  updated_at INTEGER\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_id ON users(id);\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_current_email ON users(current_email);\n\n-- The address registry: which account an address authenticates.\nCREATE TABLE IF NOT EXISTS user_emails (\n  email TEXT PRIMARY KEY,\n  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\n  is_verified INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_user_emails_user ON user_emails(user_id);\n";
+/**
+ * The additive upgrade for a database whose `users` predates the identity
+ * columns — converged from `0004_user_identity.sql` (Durable-DAV) with the
+ * table-specific phases (dav_volumes, namespaces) generalized into a
+ * documented extension point, because every repo's legacy tables differ.
+ *
+ * Run order per phase matches Durable-DAV's, and each backfill is guarded so
+ * the file is rerunnable: `users.id` is only filled where still missing, and
+ * every registry insert is `INSERT OR IGNORE`.
+ *
+ * Why the address stays in `users` at all (the anchor question, answered once):
+ * SQLite rewrites a child's foreign key clause when the parent is renamed and
+ * drops the parent by cascading, so the reference from a legacy
+ * `owner_email`-style column cannot be repointed at `users.id` without losing
+ * rows. Keeping `email` as a frozen anchor sidesteps the rebuild entirely:
+ * this migration is purely additive.
+ *
+ * A consumer with its own legacy tables appends one additive phase per table:
+ * add the `*_user_id` column with `REFERENCES users(id) ON DELETE CASCADE`
+ * (`NO ACTION` would *restrict* where the existing `owner_email` cascade
+ * removed rows — the two references must cascade together), backfill it by
+ * resolving the stored address through `user_emails`, and index it.
+ */
+declare const UPGRADE_USER_IDENTITY = "\n-- Phase 1: stable account key.\n-- SQLite cannot add a PRIMARY KEY column, so the id is a plain column with a\n-- unique index. A unique index is a valid foreign key parent, which is all the\n-- user_id references need.\nALTER TABLE users ADD COLUMN id TEXT;\n\nUPDATE users SET id = 'usr_' || lower(hex(randomblob(16))) WHERE id IS NULL;\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_id ON users(id);\n\n-- Phase 2: mutable sign-in address.\n-- 'email' stays as the frozen anchor; 'current_email' is what the account signs\n-- in with and what the API reports. Uniqueness is enforced here, so an address\n-- can never be claimed by two accounts.\nALTER TABLE users ADD COLUMN current_email TEXT;\n\nUPDATE users SET current_email = lower(email) WHERE current_email IS NULL;\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_users_current_email ON users(current_email);\n\n-- Phase 3: address registry.\n-- Login resolution consults is_verified = 1 only. Backfilled from the frozen\n-- anchor address of every existing account, lowercased so a legacy mixed-case\n-- row still yields exactly one login identity.\nCREATE TABLE IF NOT EXISTS user_emails (\n  email TEXT PRIMARY KEY,\n  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,\n  is_verified INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_user_emails_user ON user_emails(user_id);\n\nINSERT OR IGNORE INTO user_emails (email, user_id, is_verified, created_at)\nSELECT lower(email), id, 1, created_at FROM users;\n";
+/**
+ * Every migration this package ships, in apply order.
+ *
+ * `upgrade-user-identity.sql` is *not* applied on a fresh database — the
+ * fresh-install path is `users.sql` alone, and the upgrade exists only for a
+ * legacy one.
+ */
+declare const IDENTITY_MIGRATIONS: ReadonlyArray<{
+    name: string;
+    sql: string;
+}>;
+export { IDENTITY_MIGRATIONS, UPGRADE_USER_IDENTITY, USERS_SCHEMA };
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,QAAA,MAAM,YAAY,oyBAuBjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,QAAA,MAAM,qBAAqB,2/CAoC1B,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,mBAAmB,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAGrE,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,CAAC"}