handoff-app 2.0.0-1 → 2.0.0-3

package/src/registry/auth/action-tokens.ts

@@ -0,0 +1,225 @@
+import { and, eq, gt, isNull, sql } from 'drizzle-orm';
+import { randomUUID } from 'node:crypto';
+import type { RegistryDatabase } from '../db/client';
+import { registryAuthActionTokens, registryUsers, type RegistryAuthActionPurpose, type RegistryUserRole } from '../db/schema';
+import { revokeAllRegistryAccessTokens } from './access-tokens';
+import { createOpaqueSecret, hashSecret, normalizeEmail } from './crypto';
+import { withRegistryTransaction } from './database';
+import { hashPassword, validatePassword } from './password';
+import type { RegistryUser } from './types';
+import { toRegistryUser } from './user-record';
+import { validateRegistryDisplayName, validateRegistryEmail } from './validation';
+
+export const INVITATION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+export const PASSWORD_RESET_LIFETIME_MS = 60 * 60 * 1000;
+
+export type CreateUserInvitationResult =
+  | { ok: true; user: RegistryUser; token: string; expiresAt: Date }
+  | { ok: false; reason: 'invalid_email' | 'invalid_name' | 'invalid_role' | 'email_exists' };
+
+export type ResendUserInvitationResult =
+  | { ok: true; user: RegistryUser; token: string; expiresAt: Date }
+  | { ok: false; reason: 'not_found' | 'already_accepted' | 'deactivated' };
+
+export type ConsumeAuthActionResult =
+  | { ok: true; user: RegistryUser }
+  | { ok: false; reason: 'invalid_or_expired_token' | 'invalid_password'; error?: string };
+
+const invalidateUnusedActionTokens = async (
+  db: RegistryDatabase,
+  userId: string,
+  purpose: RegistryAuthActionPurpose,
+  now: Date
+): Promise<void> => {
+  await db
+    .update(registryAuthActionTokens)
+    .set({ usedAt: now })
+    .where(
+      and(
+        eq(registryAuthActionTokens.userId, userId),
+        eq(registryAuthActionTokens.purpose, purpose),
+        isNull(registryAuthActionTokens.usedAt)
+      )
+    );
+};
+
+const insertActionToken = async (
+  db: RegistryDatabase,
+  userId: string,
+  purpose: RegistryAuthActionPurpose,
+  expiresAt: Date,
+  now: Date
+): Promise<string> => {
+  const token = createOpaqueSecret(32);
+  await db.insert(registryAuthActionTokens).values({
+    id: randomUUID(),
+    userId,
+    purpose,
+    tokenHash: hashSecret(token),
+    expiresAt,
+    createdAt: now,
+  });
+  return token;
+};
+
+export const createUserInvitation = async (
+  db: RegistryDatabase,
+  input: {
+    email: string;
+    name: string;
+    role: RegistryUserRole;
+    now?: Date;
+    expiresAt?: Date;
+  }
+): Promise<CreateUserInvitationResult> => {
+  const email = validateRegistryEmail(input.email);
+  if (!email) return { ok: false, reason: 'invalid_email' };
+  const name = validateRegistryDisplayName(input.name);
+  if (!name) return { ok: false, reason: 'invalid_name' };
+  if (input.role !== 'admin' && input.role !== 'member') return { ok: false, reason: 'invalid_role' };
+  const now = input.now ?? new Date();
+  const expiresAt = input.expiresAt ?? new Date(now.getTime() + INVITATION_LIFETIME_MS);
+
+  return withRegistryTransaction(db, async (tx) => {
+    const userId = randomUUID();
+    const rows = await tx
+      .insert(registryUsers)
+      .values({
+        id: userId,
+        email,
+        name,
+        role: input.role,
+        status: 'invited',
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .returning();
+    const user = rows[0];
+    if (!user) return { ok: false, reason: 'email_exists' };
+
+    const token = await insertActionToken(tx, userId, 'invite', expiresAt, now);
+    return { ok: true, user: toRegistryUser(user), token, expiresAt };
+  });
+};
+
+export const resendUserInvitation = async (
+  db: RegistryDatabase,
+  input: { userId: string; now?: Date; expiresAt?: Date }
+): Promise<ResendUserInvitationResult> =>
+  withRegistryTransaction(db, async (tx) => {
+    const [user] = await tx.select().from(registryUsers).where(eq(registryUsers.id, input.userId)).limit(1).for('update');
+    if (!user) return { ok: false, reason: 'not_found' };
+    if (user.status === 'active') return { ok: false, reason: 'already_accepted' };
+    if (user.status === 'deactivated') return { ok: false, reason: 'deactivated' };
+
+    const now = input.now ?? new Date();
+    const expiresAt = input.expiresAt ?? new Date(now.getTime() + INVITATION_LIFETIME_MS);
+    await invalidateUnusedActionTokens(tx, user.id, 'invite', now);
+    const token = await insertActionToken(tx, user.id, 'invite', expiresAt, now);
+    return { ok: true, user: toRegistryUser(user), token, expiresAt };
+  });
+
+export const acceptUserInvitation = async (
+  db: RegistryDatabase,
+  input: { token: string; password: string; now?: Date }
+): Promise<ConsumeAuthActionResult> => {
+  const validation = validatePassword(input.password);
+  if ('error' in validation) return { ok: false, reason: 'invalid_password', error: validation.error };
+  const passwordHash = await hashPassword(input.password);
+  const now = input.now ?? new Date();
+
+  return withRegistryTransaction(db, async (tx) => {
+    const [consumed] = await tx
+      .update(registryAuthActionTokens)
+      .set({ usedAt: now })
+      .where(
+        and(
+          eq(registryAuthActionTokens.tokenHash, hashSecret(input.token)),
+          eq(registryAuthActionTokens.purpose, 'invite'),
+          isNull(registryAuthActionTokens.usedAt),
+          gt(registryAuthActionTokens.expiresAt, now)
+        )
+      )
+      .returning({ userId: registryAuthActionTokens.userId });
+    if (!consumed) return { ok: false, reason: 'invalid_or_expired_token' };
+
+    const [user] = await tx
+      .update(registryUsers)
+      .set({
+        passwordHash,
+        status: 'active',
+        emailVerifiedAt: now,
+        updatedAt: now,
+      })
+      .where(and(eq(registryUsers.id, consumed.userId), eq(registryUsers.status, 'invited')))
+      .returning();
+    return user ? { ok: true, user: toRegistryUser(user) } : { ok: false, reason: 'invalid_or_expired_token' };
+  });
+};
+
+/**
+ * Enumeration-safe reset request. The token is returned only to the trusted mail-delivery caller;
+ * unknown/inactive emails return the same successful shape with a null token.
+ */
+export const createPasswordReset = async (
+  db: RegistryDatabase,
+  email: string,
+  options: { now?: Date; expiresAt?: Date } = {}
+): Promise<{ ok: true; user: RegistryUser | null; token: string | null; expiresAt: Date | null }> => {
+  const normalizedEmail = normalizeEmail(email);
+  const now = options.now ?? new Date();
+  const expiresAt = options.expiresAt ?? new Date(now.getTime() + PASSWORD_RESET_LIFETIME_MS);
+  return withRegistryTransaction(db, async (tx) => {
+    const [user] = await tx
+      .select()
+      .from(registryUsers)
+      .where(and(eq(registryUsers.email, normalizedEmail), eq(registryUsers.status, 'active')))
+      .limit(1)
+      .for('update');
+    if (!user) return { ok: true, user: null, token: null, expiresAt: null };
+
+    await invalidateUnusedActionTokens(tx, user.id, 'password_reset', now);
+    const token = await insertActionToken(tx, user.id, 'password_reset', expiresAt, now);
+    return { ok: true, user: toRegistryUser(user), token, expiresAt };
+  });
+};
+
+export const resetPassword = async (
+  db: RegistryDatabase,
+  input: { token: string; password: string; now?: Date }
+): Promise<ConsumeAuthActionResult> => {
+  const validation = validatePassword(input.password);
+  if ('error' in validation) return { ok: false, reason: 'invalid_password', error: validation.error };
+  const passwordHash = await hashPassword(input.password);
+  const now = input.now ?? new Date();
+
+  return withRegistryTransaction(db, async (tx) => {
+    const [consumed] = await tx
+      .update(registryAuthActionTokens)
+      .set({ usedAt: now })
+      .where(
+        and(
+          eq(registryAuthActionTokens.tokenHash, hashSecret(input.token)),
+          eq(registryAuthActionTokens.purpose, 'password_reset'),
+          isNull(registryAuthActionTokens.usedAt),
+          gt(registryAuthActionTokens.expiresAt, now)
+        )
+      )
+      .returning({ userId: registryAuthActionTokens.userId });
+    if (!consumed) return { ok: false, reason: 'invalid_or_expired_token' };
+
+    const [user] = await tx
+      .update(registryUsers)
+      .set({
+        passwordHash,
+        authVersion: sql`${registryUsers.authVersion} + 1`,
+        updatedAt: now,
+      })
+      .where(and(eq(registryUsers.id, consumed.userId), eq(registryUsers.status, 'active')))
+      .returning();
+    if (!user) return { ok: false, reason: 'invalid_or_expired_token' };
+    await revokeAllRegistryAccessTokens(tx, user.id, now);
+    return { ok: true, user: toRegistryUser(user) };
+  });
+};

package/src/registry/auth/crypto.ts

@@ -0,0 +1,13 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+export const hashSecret = (secret: string): string => createHash('sha256').update(secret, 'utf8').digest('hex');
+
+export const createOpaqueSecret = (byteLength = 32): string => randomBytes(byteLength).toString('base64url');
+
+export const secretHashMatches = (secret: string, expectedHash: string): boolean => {
+  const actual = Buffer.from(hashSecret(secret), 'hex');
+  const expected = Buffer.from(expectedHash, 'hex');
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+};
+
+export const normalizeEmail = (email: string): string => email.trim().toLowerCase();

package/src/registry/auth/database.ts

@@ -0,0 +1,15 @@
+import { sql } from 'drizzle-orm';
+import type { RegistryDatabase } from '../db/client';
+
+export type RegistryTransaction = RegistryDatabase;
+
+export const withRegistryTransaction = async <T>(db: RegistryDatabase, callback: (tx: RegistryTransaction) => Promise<T>): Promise<T> =>
+  (db as any).transaction((tx: unknown) => callback(tx as RegistryTransaction));
+
+export const acquireRegistryAdvisoryLock = async (tx: RegistryTransaction, lockId: number): Promise<void> => {
+  await tx.execute(sql`select pg_advisory_xact_lock(${lockId})`);
+};
+
+/** Stable, package-owned Postgres advisory-lock ids. */
+export const REGISTRY_INSTALL_LOCK_ID = 1_841_111_001;
+export const REGISTRY_ADMIN_LOCK_ID = 1_841_111_002;

package/src/registry/auth/device-authorizations.ts

@@ -0,0 +1,223 @@
+import { and, eq, gt, lt } from 'drizzle-orm';
+import { randomBytes, randomUUID } from 'node:crypto';
+import type { RegistryDatabase } from '../db/client';
+import { registryDeviceAuthorizations, registryUsers } from '../db/schema';
+import {
+  createRegistryAccessToken,
+  normalizeRegistryScopes,
+  registryRoleAllowsScopes,
+  type RegistryAccessTokenSummary,
+} from './access-tokens';
+import { hashSecret } from './crypto';
+import { withRegistryTransaction } from './database';
+import { scopesForRegistryRole, type RegistryAccessScope, type RegistryUser } from './types';
+import { toRegistryUser } from './user-record';
+
+const USER_CODE_ALPHABET = 'BCDFGHJKLMNPQRSTVWXYZ23456789';
+export const DEVICE_AUTHORIZATION_LIFETIME_SECONDS = 15 * 60;
+export const DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS = 5;
+
+const randomUserCodeSegment = (length: number): string => {
+  const bytes = randomBytes(length);
+  let result = '';
+  for (let index = 0; index < length; index += 1) {
+    result += USER_CODE_ALPHABET[bytes[index] % USER_CODE_ALPHABET.length];
+  }
+  return result;
+};
+
+export const generateRegistryUserCode = (): string => `${randomUserCodeSegment(4)}-${randomUserCodeSegment(4)}`;
+
+export const normalizeRegistryUserCode = (value: string): string => {
+  const compact = value.toUpperCase().replace(/[^A-Z0-9]/g, '');
+  return compact.length === 8 ? `${compact.slice(0, 4)}-${compact.slice(4)}` : value.trim().toUpperCase();
+};
+
+export interface CreateRegistryDeviceAuthorizationResult {
+  deviceCode: string;
+  userCode: string;
+  expiresIn: number;
+  interval: number;
+  expiresAt: Date;
+}
+
+export const createRegistryDeviceAuthorization = async (
+  db: RegistryDatabase,
+  options: { now?: Date; expiresInSeconds?: number } = {}
+): Promise<CreateRegistryDeviceAuthorizationResult> => {
+  const now = options.now ?? new Date();
+  const expiresIn = options.expiresInSeconds ?? DEVICE_AUTHORIZATION_LIFETIME_SECONDS;
+  const deviceCode = randomBytes(32).toString('base64url');
+  const userCode = generateRegistryUserCode();
+  const expiresAt = new Date(now.getTime() + expiresIn * 1000);
+
+  await db.insert(registryDeviceAuthorizations).values({
+    id: randomUUID(),
+    deviceCodeHash: hashSecret(deviceCode),
+    userCode,
+    status: 'pending',
+    scopes: [],
+    expiresAt,
+    createdAt: now,
+  });
+  return {
+    deviceCode,
+    userCode,
+    expiresIn,
+    interval: DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS,
+    expiresAt,
+  };
+};
+
+export type RegistryDeviceApprovalResult =
+  | { ok: true; user: RegistryUser; scopes: RegistryAccessScope[] }
+  | { ok: false; reason: 'invalid_or_expired_code' | 'user_inactive' };
+
+export const approveRegistryDeviceAuthorization = async (
+  db: RegistryDatabase,
+  input: { userCode: string; userId: string; now?: Date }
+): Promise<RegistryDeviceApprovalResult> => {
+  const now = input.now ?? new Date();
+  const [user] = await db.select().from(registryUsers).where(eq(registryUsers.id, input.userId)).limit(1);
+  if (!user || user.status !== 'active') return { ok: false, reason: 'user_inactive' };
+
+  const scopes = scopesForRegistryRole(user.role);
+  const [authorization] = await db
+    .update(registryDeviceAuthorizations)
+    .set({
+      status: 'approved',
+      userId: user.id,
+      scopes,
+      approvedAt: now,
+    })
+    .where(
+      and(
+        eq(registryDeviceAuthorizations.userCode, normalizeRegistryUserCode(input.userCode)),
+        eq(registryDeviceAuthorizations.status, 'pending'),
+        gt(registryDeviceAuthorizations.expiresAt, now)
+      )
+    )
+    .returning({ id: registryDeviceAuthorizations.id });
+  return authorization ? { ok: true, user: toRegistryUser(user), scopes } : { ok: false, reason: 'invalid_or_expired_code' };
+};
+
+export const denyRegistryDeviceAuthorization = async (db: RegistryDatabase, userCode: string, now = new Date()): Promise<boolean> => {
+  const rows = await db
+    .update(registryDeviceAuthorizations)
+    .set({ status: 'denied' })
+    .where(
+      and(
+        eq(registryDeviceAuthorizations.userCode, normalizeRegistryUserCode(userCode)),
+        eq(registryDeviceAuthorizations.status, 'pending'),
+        gt(registryDeviceAuthorizations.expiresAt, now)
+      )
+    )
+    .returning({ id: registryDeviceAuthorizations.id });
+  return rows.length > 0;
+};
+
+export type ExchangeRegistryDeviceAuthorizationResult =
+  | {
+      ok: true;
+      accessToken: string;
+      tokenType: 'Bearer';
+      expiresIn: number;
+      scopes: RegistryAccessScope[];
+      user: RegistryUser;
+      record: RegistryAccessTokenSummary;
+    }
+  | {
+      ok: false;
+      error: 'invalid_grant' | 'expired_token' | 'authorization_pending' | 'access_denied';
+      errorDescription: string;
+    };
+
+export const exchangeRegistryDeviceAuthorization = async (
+  db: RegistryDatabase,
+  input: { deviceCode: string; tokenName?: string; now?: Date }
+): Promise<ExchangeRegistryDeviceAuthorizationResult> => {
+  const now = input.now ?? new Date();
+  const tokenName = input.tokenName?.trim() || 'Handoff CLI';
+
+  return withRegistryTransaction(db, async (tx) => {
+    const [authorization] = await tx
+      .select()
+      .from(registryDeviceAuthorizations)
+      .where(eq(registryDeviceAuthorizations.deviceCodeHash, hashSecret(input.deviceCode)))
+      .limit(1);
+    if (!authorization) {
+      return { ok: false, error: 'invalid_grant', errorDescription: 'Unknown device code.' };
+    }
+    if (authorization.expiresAt <= now) {
+      return { ok: false, error: 'expired_token', errorDescription: 'Device authorization expired.' };
+    }
+    if (authorization.status === 'pending') {
+      return {
+        ok: false,
+        error: 'authorization_pending',
+        errorDescription: 'The authorization request is still pending.',
+      };
+    }
+    if (authorization.status === 'denied') {
+      return { ok: false, error: 'access_denied', errorDescription: 'The authorization request was denied.' };
+    }
+    if (authorization.status === 'consumed') {
+      return { ok: false, error: 'invalid_grant', errorDescription: 'Device code has already been used.' };
+    }
+    if (!authorization.userId) {
+      return { ok: false, error: 'invalid_grant', errorDescription: 'Device authorization has no user.' };
+    }
+
+    const [consumed] = await tx
+      .update(registryDeviceAuthorizations)
+      .set({ status: 'consumed', consumedAt: now })
+      .where(
+        and(
+          eq(registryDeviceAuthorizations.id, authorization.id),
+          eq(registryDeviceAuthorizations.status, 'approved'),
+          gt(registryDeviceAuthorizations.expiresAt, now)
+        )
+      )
+      .returning({ id: registryDeviceAuthorizations.id });
+    if (!consumed) {
+      return { ok: false, error: 'invalid_grant', errorDescription: 'Device code has already been used.' };
+    }
+
+    const [user] = await tx.select().from(registryUsers).where(eq(registryUsers.id, authorization.userId)).limit(1);
+    if (!user || user.status !== 'active') {
+      return { ok: false, error: 'access_denied', errorDescription: 'The approving account is inactive.' };
+    }
+
+    let scopes = normalizeRegistryScopes(authorization.scopes);
+    if (!registryRoleAllowsScopes(user.role, scopes)) scopes = scopesForRegistryRole(user.role);
+    const expiresAt = new Date(now.getTime() + 365 * 24 * 60 * 60 * 1000);
+    const token = await createRegistryAccessToken(tx, {
+      userId: user.id,
+      name: tokenName,
+      scopes,
+      expiresAt,
+      now,
+    });
+    if (!token.ok) {
+      return { ok: false, error: 'access_denied', errorDescription: 'The account cannot issue this token.' };
+    }
+
+    return {
+      ok: true,
+      accessToken: token.token,
+      tokenType: 'Bearer',
+      expiresIn: Math.floor((expiresAt.getTime() - now.getTime()) / 1000),
+      scopes: token.record.scopes,
+      user: toRegistryUser(user),
+      record: token.record,
+    };
+  });
+};
+
+export const purgeExpiredRegistryDeviceAuthorizations = async (db: RegistryDatabase, now = new Date()): Promise<number> => {
+  const rows = await db
+    .delete(registryDeviceAuthorizations)
+    .where(lt(registryDeviceAuthorizations.expiresAt, now))
+    .returning({ id: registryDeviceAuthorizations.id });
+  return rows.length;
+};

package/src/registry/auth/gravatar.ts

@@ -0,0 +1,6 @@
+import { hashSecret, normalizeEmail } from './crypto';
+
+// Gravatar resolves an avatar from the SHA-256 hash of the trimmed, lowercased email.
+// `d=identicon` guarantees a generated image renders even when the user has no Gravatar.
+export const buildGravatarUrl = (email: string): string =>
+  `https://www.gravatar.com/avatar/${hashSecret(normalizeEmail(email))}?d=identicon`;

package/src/registry/auth/index.ts

@@ -0,0 +1,89 @@
+export {
+  createRegistryAccessToken,
+  listRegistryAccessTokens,
+  revokeRegistryAccessToken,
+  revokeAllRegistryAccessTokens,
+  authenticateRegistryAccessToken,
+  formatRegistryAccessToken,
+  parseRegistryAccessToken,
+  normalizeRegistryScopes,
+  registryRoleAllowsScopes,
+  type RegistryAccessTokenSummary,
+  type CreateRegistryAccessTokenResult,
+} from './access-tokens';
+export {
+  createUserInvitation,
+  resendUserInvitation,
+  acceptUserInvitation,
+  createPasswordReset,
+  resetPassword,
+  INVITATION_LIFETIME_MS,
+  PASSWORD_RESET_LIFETIME_MS,
+  type CreateUserInvitationResult,
+  type ResendUserInvitationResult,
+  type ConsumeAuthActionResult,
+} from './action-tokens';
+export { createOpaqueSecret, hashSecret, normalizeEmail, secretHashMatches } from './crypto';
+export { buildGravatarUrl } from './gravatar';
+export {
+  createRegistryDeviceAuthorization,
+  approveRegistryDeviceAuthorization,
+  denyRegistryDeviceAuthorization,
+  exchangeRegistryDeviceAuthorization,
+  purgeExpiredRegistryDeviceAuthorizations,
+  generateRegistryUserCode,
+  normalizeRegistryUserCode,
+  DEVICE_AUTHORIZATION_LIFETIME_SECONDS,
+  DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS,
+  type CreateRegistryDeviceAuthorizationResult,
+  type RegistryDeviceApprovalResult,
+  type ExchangeRegistryDeviceAuthorizationResult,
+} from './device-authorizations';
+export {
+  getRegistryInstallation,
+  getRegistryInstallationState,
+  installRegistry,
+  REGISTRY_AUTH_SCHEMA_VERSION,
+  REGISTRY_INSTALLATION_ID,
+  type RegistryInstallation,
+  type RegistryInstallationState,
+  type RegistryInstallInput,
+  type RegistryInstallResult,
+} from './installation';
+export {
+  hashPassword,
+  verifyPassword,
+  validatePassword,
+  MINIMUM_PASSWORD_LENGTH,
+  MAXIMUM_PASSWORD_LENGTH,
+  type PasswordValidationResult,
+} from './password';
+export {
+  consumeAuthRateLimit,
+  clearAuthRateLimit,
+  purgeExpiredAuthRateLimits,
+  hashRateLimitIdentifier,
+  type ConsumeAuthRateLimitInput,
+  type AuthRateLimitResult,
+} from './rate-limits';
+export {
+  getRegistryUserById,
+  listRegistryUsers,
+  authenticateRegistryCredentials,
+  updateRegistryUserProfile,
+  updateRegistryUserRole,
+  setRegistryUserStatus,
+  type RegistryUserMutationResult,
+} from './users';
+export {
+  REGISTRY_READ_SCOPE,
+  REGISTRY_WRITE_SCOPE,
+  scopesForRegistryRole,
+  registryPrincipalHasScope,
+  type RegistryAccessScope,
+  type RegistryPrincipal,
+  type RegistryUser,
+  type RegistryUserRole,
+  type RegistryUserStatus,
+} from './types';
+export { validateRegistryDisplayName, validateRegistryEmail, validateRegistryImageUrl } from './validation';

package/src/registry/auth/installation.ts

@@ -0,0 +1,117 @@
+import { count, eq } from 'drizzle-orm';
+import { randomUUID } from 'node:crypto';
+import type { RegistryDatabase } from '../db/client';
+import { registryInstallations, registryUsers } from '../db/schema';
+import { acquireRegistryAdvisoryLock, REGISTRY_INSTALL_LOCK_ID, withRegistryTransaction } from './database';
+import { hashPassword, validatePassword } from './password';
+import type { RegistryUser } from './types';
+import { toRegistryUser } from './user-record';
+import { validateRegistryDisplayName, validateRegistryEmail } from './validation';
+
+/** Migration number that introduced the registry authentication schema. */
+export const REGISTRY_AUTH_SCHEMA_VERSION = 5;
+export const REGISTRY_INSTALLATION_ID = 'default';
+
+export type RegistryInstallation = typeof registryInstallations.$inferSelect;
+export type RegistryInstallationState =
+  | { status: 'ready'; installation: null; userCount: 0 }
+  | { status: 'installed'; installation: RegistryInstallation; userCount: number }
+  | { status: 'inconsistent'; installation: null; userCount: number };
+
+export interface RegistryInstallInput {
+  email: string;
+  name: string;
+  password: string;
+  now?: Date;
+}
+
+export type RegistryInstallResult =
+  | { ok: true; user: RegistryUser; installation: RegistryInstallation }
+  | {
+      ok: false;
+      reason: 'invalid_email' | 'invalid_name' | 'invalid_password' | 'already_installed' | 'users_exist';
+      error?: string;
+    };
+
+export const getRegistryInstallation = async (db: RegistryDatabase): Promise<RegistryInstallation | null> => {
+  const [installation] = await db
+    .select()
+    .from(registryInstallations)
+    .where(eq(registryInstallations.id, REGISTRY_INSTALLATION_ID))
+    .limit(1);
+  return installation ?? null;
+};
+
+export const getRegistryInstallationState = async (db: RegistryDatabase): Promise<RegistryInstallationState> => {
+  const installation = await getRegistryInstallation(db);
+  const [{ value }] = await db.select({ value: count() }).from(registryUsers);
+  const userCount = Number(value);
+  if (installation) return { status: 'installed', installation, userCount };
+  return userCount === 0
+    ? { status: 'ready', installation: null, userCount: 0 }
+    : { status: 'inconsistent', installation: null, userCount };
+};
+
+/**
+ * Complete first-visitor installation under a transaction-scoped advisory lock. Password hashing is
+ * intentionally performed before taking the lock; all state checks are repeated inside it.
+ */
+export const installRegistry = async (db: RegistryDatabase, input: RegistryInstallInput): Promise<RegistryInstallResult> => {
+  const email = validateRegistryEmail(input.email);
+  if (!email) return { ok: false, reason: 'invalid_email' };
+  const name = validateRegistryDisplayName(input.name);
+  if (!name) return { ok: false, reason: 'invalid_name' };
+  const passwordValidation = validatePassword(input.password);
+  if ('error' in passwordValidation) {
+    return { ok: false, reason: 'invalid_password', error: passwordValidation.error };
+  }
+
+  const passwordHash = await hashPassword(input.password);
+  const now = input.now ?? new Date();
+
+  return withRegistryTransaction(db, async (tx) => {
+    await acquireRegistryAdvisoryLock(tx, REGISTRY_INSTALL_LOCK_ID);
+
+    const [installation] = await tx
+      .select()
+      .from(registryInstallations)
+      .where(eq(registryInstallations.id, REGISTRY_INSTALLATION_ID))
+      .limit(1);
+    if (installation) return { ok: false, reason: 'already_installed' };
+
+    const [{ value }] = await tx.select({ value: count() }).from(registryUsers);
+    if (Number(value) > 0) return { ok: false, reason: 'users_exist' };
+
+    const userId = randomUUID();
+    const [userRow] = await tx
+      .insert(registryUsers)
+      .values({
+        id: userId,
+        email,
+        name,
+        role: 'admin',
+        status: 'active',
+        passwordHash,
+        emailVerifiedAt: now,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .returning();
+    const [createdInstallation] = await tx
+      .insert(registryInstallations)
+      .values({
+        id: REGISTRY_INSTALLATION_ID,
+        status: 'installed',
+        schemaVersion: REGISTRY_AUTH_SCHEMA_VERSION,
+        initialAdminUserId: userId,
+        installedAt: now,
+      })
+      .returning();
+
+    return {
+      ok: true,
+      user: toRegistryUser(userRow),
+      installation: createdInstallation,
+    };
+  });
+};