handoff-app 2.0.0-2 → 2.0.0-3

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

@@ -0,0 +1,198 @@
+import { and, eq, gt, isNull } from 'drizzle-orm';
+import type { RegistryDatabase } from '../db/client';
+import { registryAccessTokens, registryUsers, type RegistryAccessScope } from '../db/schema';
+import { createOpaqueSecret, hashSecret, secretHashMatches } from './crypto';
+import { withRegistryTransaction } from './database';
+import { REGISTRY_READ_SCOPE, REGISTRY_WRITE_SCOPE, type RegistryPrincipal, type RegistryUserRole } from './types';
+
+const ACCESS_TOKEN_PREFIX = 'hnd';
+const DEFAULT_ACCESS_TOKEN_LIFETIME_MS = 365 * 24 * 60 * 60 * 1000;
+
+export interface RegistryAccessTokenSummary {
+  id: string;
+  name: string;
+  scopes: RegistryAccessScope[];
+  expiresAt: Date;
+  lastUsedAt: Date | null;
+  revokedAt: Date | null;
+  createdAt: Date;
+}
+
+export type CreateRegistryAccessTokenResult =
+  | { ok: true; token: string; record: RegistryAccessTokenSummary }
+  | { ok: false; reason: 'user_not_found' | 'user_inactive' | 'scope_forbidden' | 'invalid_name' | 'invalid_expiry' };
+
+const isRegistryScope = (value: unknown): value is RegistryAccessScope => value === REGISTRY_READ_SCOPE || value === REGISTRY_WRITE_SCOPE;
+
+export const normalizeRegistryScopes = (scopes: readonly RegistryAccessScope[]): RegistryAccessScope[] => {
+  const unique = new Set(scopes.filter(isRegistryScope));
+  return [REGISTRY_READ_SCOPE, REGISTRY_WRITE_SCOPE].filter((scope) => unique.has(scope));
+};
+
+export const registryRoleAllowsScopes = (role: RegistryUserRole, scopes: readonly RegistryAccessScope[]): boolean =>
+  role === 'admin' || !scopes.includes(REGISTRY_WRITE_SCOPE);
+
+export const formatRegistryAccessToken = (id: string, secret: string): string => `${ACCESS_TOKEN_PREFIX}_${id}_${secret}`;
+
+export const parseRegistryAccessToken = (token: string): { id: string; secret: string } | null => {
+  const match = /^hnd_([A-Za-z0-9_-]{16})_([A-Za-z0-9_-]{43})$/.exec(token.trim());
+  return match ? { id: match[1], secret: match[2] } : null;
+};
+
+const createRegistryAccessTokenInTransaction = async (
+  db: RegistryDatabase,
+  input: {
+    userId: string;
+    name: string;
+    scopes: RegistryAccessScope[];
+    expiresAt?: Date;
+    now?: Date;
+  }
+): Promise<CreateRegistryAccessTokenResult> => {
+  const name = input.name.trim();
+  if (!name || name.length > 120) return { ok: false, reason: 'invalid_name' };
+
+  const now = input.now ?? new Date();
+  const expiresAt = input.expiresAt ?? new Date(now.getTime() + DEFAULT_ACCESS_TOKEN_LIFETIME_MS);
+  if (!(expiresAt instanceof Date) || !Number.isFinite(expiresAt.getTime()) || expiresAt <= now) {
+    return { ok: false, reason: 'invalid_expiry' };
+  }
+
+  const [user] = await db
+    .select({ id: registryUsers.id, role: registryUsers.role, status: registryUsers.status })
+    .from(registryUsers)
+    .where(eq(registryUsers.id, input.userId))
+    .limit(1)
+    .for('update');
+  if (!user) return { ok: false, reason: 'user_not_found' };
+  if (user.status !== 'active') return { ok: false, reason: 'user_inactive' };
+
+  const scopes = normalizeRegistryScopes(input.scopes);
+  if (!scopes.length) scopes.push(REGISTRY_READ_SCOPE);
+  if (!registryRoleAllowsScopes(user.role, scopes)) return { ok: false, reason: 'scope_forbidden' };
+
+  const id = createOpaqueSecret(12);
+  const secret = createOpaqueSecret(32);
+  const [record] = await db
+    .insert(registryAccessTokens)
+    .values({
+      id,
+      userId: user.id,
+      name,
+      secretHash: hashSecret(secret),
+      scopes,
+      expiresAt,
+    })
+    .returning({
+      id: registryAccessTokens.id,
+      name: registryAccessTokens.name,
+      scopes: registryAccessTokens.scopes,
+      expiresAt: registryAccessTokens.expiresAt,
+      lastUsedAt: registryAccessTokens.lastUsedAt,
+      revokedAt: registryAccessTokens.revokedAt,
+      createdAt: registryAccessTokens.createdAt,
+    });
+
+  return { ok: true, token: formatRegistryAccessToken(id, secret), record };
+};
+
+export const createRegistryAccessToken = async (
+  db: RegistryDatabase,
+  input: {
+    userId: string;
+    name: string;
+    scopes: RegistryAccessScope[];
+    expiresAt?: Date;
+    now?: Date;
+  }
+): Promise<CreateRegistryAccessTokenResult> => withRegistryTransaction(db, (tx) => createRegistryAccessTokenInTransaction(tx, input));
+
+export const listRegistryAccessTokens = async (db: RegistryDatabase, userId: string): Promise<RegistryAccessTokenSummary[]> =>
+  db
+    .select({
+      id: registryAccessTokens.id,
+      name: registryAccessTokens.name,
+      scopes: registryAccessTokens.scopes,
+      expiresAt: registryAccessTokens.expiresAt,
+      lastUsedAt: registryAccessTokens.lastUsedAt,
+      revokedAt: registryAccessTokens.revokedAt,
+      createdAt: registryAccessTokens.createdAt,
+    })
+    .from(registryAccessTokens)
+    .where(eq(registryAccessTokens.userId, userId))
+    .orderBy(registryAccessTokens.createdAt);
+
+export const revokeRegistryAccessToken = async (
+  db: RegistryDatabase,
+  input: { tokenId: string; userId: string; now?: Date }
+): Promise<boolean> => {
+  const rows = await db
+    .update(registryAccessTokens)
+    .set({ revokedAt: input.now ?? new Date() })
+    .where(
+      and(eq(registryAccessTokens.id, input.tokenId), eq(registryAccessTokens.userId, input.userId), isNull(registryAccessTokens.revokedAt))
+    )
+    .returning({ id: registryAccessTokens.id });
+  return rows.length > 0;
+};
+
+export const revokeAllRegistryAccessTokens = async (db: RegistryDatabase, userId: string, now = new Date()): Promise<number> => {
+  const rows = await db
+    .update(registryAccessTokens)
+    .set({ revokedAt: now })
+    .where(and(eq(registryAccessTokens.userId, userId), isNull(registryAccessTokens.revokedAt)))
+    .returning({ id: registryAccessTokens.id });
+  return rows.length;
+};
+
+/**
+ * Resolve an opaque bearer credential into a live principal. User state is joined on every call,
+ * making deactivation effective even if a defensive token-revocation write was interrupted.
+ */
+export const authenticateRegistryAccessToken = async (
+  db: RegistryDatabase,
+  token: string,
+  now = new Date()
+): Promise<RegistryPrincipal | null> => {
+  const parsed = parseRegistryAccessToken(token);
+  if (!parsed) return null;
+
+  const [row] = await db
+    .select({
+      tokenId: registryAccessTokens.id,
+      secretHash: registryAccessTokens.secretHash,
+      scopes: registryAccessTokens.scopes,
+      expiresAt: registryAccessTokens.expiresAt,
+      revokedAt: registryAccessTokens.revokedAt,
+      userId: registryUsers.id,
+      email: registryUsers.email,
+      name: registryUsers.name,
+      role: registryUsers.role,
+      status: registryUsers.status,
+    })
+    .from(registryAccessTokens)
+    .innerJoin(registryUsers, eq(registryUsers.id, registryAccessTokens.userId))
+    .where(eq(registryAccessTokens.id, parsed.id))
+    .limit(1);
+
+  if (!row || row.status !== 'active' || row.revokedAt || row.expiresAt <= now || !secretHashMatches(parsed.secret, row.secretHash)) {
+    return null;
+  }
+
+  const scopes = normalizeRegistryScopes(Array.isArray(row.scopes) ? row.scopes : []);
+  const updated = await db
+    .update(registryAccessTokens)
+    .set({ lastUsedAt: now })
+    .where(and(eq(registryAccessTokens.id, row.tokenId), isNull(registryAccessTokens.revokedAt), gt(registryAccessTokens.expiresAt, now)))
+    .returning({ id: registryAccessTokens.id });
+  if (!updated.length) return null;
+
+  return {
+    tokenId: row.tokenId,
+    userId: row.userId,
+    email: row.email,
+    name: row.name,
+    role: row.role,
+    scopes,
+  };
+};

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`;