handoff-app 2.0.0-2 → 2.0.0-3

package/src/registry/checkout/index.ts

@@ -16,12 +16,13 @@
 import * as p from '@clack/prompts';
 import fs from 'fs-extra';
 import path from 'path';
-import { resolveComponentDeclaration } from '../../config/runtime';
+import { type EntryKind, isEntryCovered, writeEntries } from '../../config/entries';
+import { isComponentDirectory, resolveComponentDeclaration } from '../../config/runtime';
 import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
-import { resolveRegistryConnection } from '../connection';
+import { resolveAuthenticatedRegistryConnection } from '../connection';
 import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
 
@@ -51,7 +52,7 @@ const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
  * host has no local workspace to write into) and a resolved registry URL + access token. Throws an
  * actionable {@link CheckoutError} naming the exact misconfiguration.
  */
-export const resolveConnectionOrThrow = (handoff: Handoff) => {
+export const resolveConnectionOrThrow = async (handoff: Handoff) => {
   const mode = handoff.config?.runtime?.mode ?? 'workspace';
   if (mode !== 'workspace') {
     throw new CheckoutError(
@@ -60,17 +61,17 @@ export const resolveConnectionOrThrow = (handoff: Handoff) => {
     );
   }
 
-  const connection = resolveRegistryConnection(handoff.config);
+  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath);
   if (!connection.url) {
     throw new CheckoutError(
-      `No registry URL is configured. Set runtime.registryConnection.url, or the "${connection.urlEnv}" environment variable, ` +
-        'to the base URL of the registry to checkout from.'
+      `No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
+        `or set the "${connection.urlEnv}" environment variable to the base URL of the registry to checkout from.`
     );
   }
   if (!connection.accessToken) {
     throw new CheckoutError(
-      `No registry access token is configured. Set the "${connection.accessTokenEnv}" environment variable to the ` +
-        "registry's bearer token to authorize checkout."
+      `No registry access token is configured. Run \`handoff-app login --url ${connection.url}\`, or set the ` +
+        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.`
     );
   }
   return connection;
@@ -84,16 +85,68 @@ const describeFetchFailure = (error: RegistryClientError, kind: TransferEntityKi
     case 'runtime_mode_conflict':
       return `The registry at ${registryUrl} is not running in registry mode, so it cannot serve a checkout: ${error.message}`;
     case 'unauthorized':
-      return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+      return `The registry rejected the access token (401). Run \`handoff-app login --url ${registryUrl}\` again, or replace the user-issued CI token.`;
+    case 'forbidden':
+      return `The registry token does not have permission to checkout this content (403). Authorize a token with registry:read access.`;
     default:
       return error.message;
   }
 };
 
 /**
- * Resolve the local directory the entity is written into: an already-checked-out / locally-declared
- * entity keeps its existing source directory (matched by stable `id`); otherwise it lands under the
- * first configured `entries.{components|patterns}` root (falling back to `components`/`patterns`).
+ * Ask the user which collection directory a new entity should land in when the config is ambiguous.
+ * Under `--force` (or any non-interactive run) there's no one to ask, so we fail with an actionable
+ * message rather than guessing a root.
+ */
+const promptForCollectionRoot = async (handoff: Handoff, kind: TransferEntityKind, roots: string[]): Promise<string> => {
+  const relative = (root: string) => path.relative(handoff.workingPath, root) || '.';
+  if (handoff.force) {
+    throw new CheckoutError(
+      `Cannot determine where to checkout the ${kind}: entries.${kind}s declares individual ${kind}s under different ` +
+        `directories (${roots.map(relative).join(', ')}). Declare a single collection directory in handoff.config, ` +
+        `or run checkout without --force to choose interactively.`
+    );
+  }
+  const choice = await p.select({
+    message: `Where should the new ${kind} be checked out?`,
+    options: roots.map((root) => ({ value: root, label: relative(root) })),
+    initialValue: roots[0],
+  });
+  if (p.isCancel(choice)) {
+    throw new CheckoutError('Checkout cancelled; no target directory chosen.');
+  }
+  return choice as string;
+};
+
+/**
+ * Resolve the collection directory a new entity is cloned into from the configured
+ * `entries.{components|patterns}`. Each entry is either a collection directory (used as-is) or a
+ * single declared entity directory, in which case its parent is the collection root so the new
+ * entity lands as a sibling rather than nested inside. Different parents mean the config is
+ * ambiguous, so we ask the user; with nothing configured we fall back to the default subdir.
+ */
+const resolveCollectionRoot = async (handoff: Handoff, kind: TransferEntityKind): Promise<string> => {
+  const configuredRoots = kind === 'component' ? handoff.config?.entries?.components : handoff.config?.entries?.patterns;
+  if (!configuredRoots?.length) {
+    return path.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
+  }
+
+  const roots = [
+    ...new Set(
+      configuredRoots.map((entry) => {
+        const resolved = path.resolve(handoff.workingPath, entry);
+        return isComponentDirectory(resolved) ? path.dirname(resolved) : resolved;
+      })
+    ),
+  ];
+
+  return roots.length === 1 ? roots[0] : promptForCollectionRoot(handoff, kind, roots);
+};
+
+/**
+ * Resolve the local directory the entity is written into. An already-checked-out or locally-declared
+ * entity keeps its existing source directory (matched by stable `id`); otherwise it lands as a
+ * sibling under its configured collection root (see {@link resolveCollectionRoot}).
  */
 const resolveTargetDir = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<string> => {
   const store = kind === 'component' ? handoff.store.components : handoff.store.patterns;
@@ -103,10 +156,7 @@ const resolveTargetDir = async (handoff: Handoff, kind: TransferEntityKind, id:
     return existingDir;
   }
 
-  const configuredRoots = kind === 'component' ? handoff.config?.entries?.components : handoff.config?.entries?.patterns;
-  const root = configuredRoots?.length
-    ? path.resolve(handoff.workingPath, configuredRoots[0])
-    : path.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
+  const root = await resolveCollectionRoot(handoff, kind);
   const targetDir = resolvePathWithin(root, id);
   if (!targetDir) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
@@ -542,7 +592,7 @@ const checkoutSingle = async (
   id: string,
   client: RegistryClient,
   registryUrl: string
-): Promise<void> => {
+): Promise<string | null> => {
   const validId = kind === 'page' ? isSafeRelativePath(id) : isSafePathSegment(id);
   if (!validId) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
@@ -559,10 +609,11 @@ const checkoutSingle = async (
     throw error;
   }
 
-  // Pages round-trip as a single verbatim `.md` with no declaration synthesis.
+  // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
+  // declared in `entries`, so there's nothing to register.
   if (kind === 'page') {
     await checkoutPage(handoff, id, payload);
-    return;
+    return null;
   }
 
   const targetDir = await resolveTargetDir(handoff, kind, id);
@@ -581,7 +632,7 @@ const checkoutSingle = async (
   const conflicts = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath].filter((file) => fs.existsSync(file));
   if (!(await confirmOverwrite(handoff, conflicts))) {
     Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
-    return;
+    return null;
   }
 
   await fs.ensureDir(targetDir);
@@ -598,6 +649,35 @@ const checkoutSingle = async (
     `Checked out ${kind} "${id}" into ${path.relative(handoff.workingPath, targetDir) || '.'} ` +
       `(${payload.files.length} source file(s) + ${declarationFileName}).`
   );
+  return targetDir;
+};
+
+/**
+ * Declare freshly checked-out entities in `entries.{components|patterns}` so the workspace build
+ * picks them up. Ones already covered by a collection directory load on their own and are left
+ * alone; the rest are added to the config automatically. If the config can't be edited (a computed
+ * or unusual `entries` array), we print the paths for the user to add so nothing is silently orphaned.
+ */
+const registerCheckedOut = async (handoff: Handoff, kind: TransferEntityKind, targetDirs: string[]): Promise<void> => {
+  if (kind === 'page') {
+    return;
+  }
+  const entryKind: EntryKind = kind === 'component' ? 'components' : 'patterns';
+  const uncovered = targetDirs.filter((dir) => !isEntryCovered(handoff, entryKind, dir));
+  if (uncovered.length === 0) {
+    return;
+  }
+
+  const result = await writeEntries(handoff, entryKind, uncovered);
+  if (result.status === 'added') {
+    const where = result.configPath ? path.relative(handoff.workingPath, result.configPath) || path.basename(result.configPath) : 'handoff.config';
+    Logger.success(`Updated ${where} with ${result.added.length} ${entryKind} path(s).`);
+    return;
+  }
+
+  const where = result.configPath ? path.relative(handoff.workingPath, result.configPath) : 'handoff.config';
+  Logger.warn(`Could not update ${where} automatically. Add these to entries.${entryKind} manually:`);
+  result.pending.forEach((rel) => Logger.warn(`  - ${rel}`));
 };
 
 /**
@@ -605,9 +685,12 @@ const checkoutSingle = async (
  * Overwriting existing local files requires `--force` or an interactive confirmation.
  */
 export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
   const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
-  await checkoutSingle(handoff, kind, id, client, connection.url);
+  const targetDir = await checkoutSingle(handoff, kind, id, client, connection.url);
+  if (targetDir) {
+    await registerCheckedOut(handoff, kind, [targetDir]);
+  }
 };
 
 /**
@@ -617,7 +700,7 @@ export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind,
  * prompting is per entity (skipped under `--force`).
  */
 export const checkoutEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
   const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
 
   let summaries;
@@ -637,15 +720,22 @@ export const checkoutEntities = async (handoff: Handoff, kind: TransferEntityKin
 
   let checkedOut = 0;
   const failed: { id: string; message: string }[] = [];
+  const targetDirs: string[] = [];
   for (const { id } of summaries) {
     try {
-      await checkoutSingle(handoff, kind, id, client, connection.url);
+      const targetDir = await checkoutSingle(handoff, kind, id, client, connection.url);
+      if (targetDir) {
+        targetDirs.push(targetDir);
+      }
       checkedOut += 1;
     } catch (error) {
       failed.push({ id, message: error instanceof Error ? error.message : String(error) });
     }
   }
 
+  // Register everything checked out in one pass, so the config is edited (and confirmed) once.
+  await registerCheckedOut(handoff, kind, targetDirs);
+
   Logger.success(
     `${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} checked out${failed.length ? `, ${failed.length} failed` : ''}.`
   );

package/src/registry/checkout/tokens.ts

@@ -28,7 +28,9 @@ const describeFetchFailure = (error: RegistryClientError, target: string, regist
     case 'runtime_mode_conflict':
       return `The registry at ${registryUrl} is not running in registry mode, so it cannot serve a checkout: ${error.message}`;
     case 'unauthorized':
-      return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+      return `The registry rejected the access token (401). Run \`handoff-app login --url ${registryUrl}\` again, or replace the user-issued CI token.`;
+    case 'forbidden':
+      return `The registry token does not have permission to checkout design tokens (403). Authorize a token with registry:read access.`;
     default:
       return error.message;
   }
@@ -73,7 +75,7 @@ export const checkoutTokens = async (handoff: Handoff, setId?: string): Promise<
   if (setId && !isTokenSetId(setId)) {
     throw new CheckoutError(`Unknown or unsafe token set id "${setId}".`);
   }
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
   const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
 
   let ids: string[];

package/src/registry/connection.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Config } from '../types/config';
+import { cliAuthMatchesRegistry, cliAuthTokenIsValid, readCliAuth } from '../cli/auth/store';
 
 /** Default env-var name holding the remote registry base URL. */
 export const DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
@@ -48,3 +49,25 @@ export const resolveRegistryConnection = (config: Config | null | undefined): Re
     accessTokenEnv,
   };
 };
+
+/**
+ * Resolve the same connection for an authenticated CLI operation, letting a saved device login fill
+ * in what the environment does not provide. A valid login supplies both the registry URL and the
+ * access token, so `handoff-app login` alone is enough to publish and checkout. Environment values
+ * keep precedence for deterministic CI: `HANDOFF_REGISTRY_URL` (or inline config) wins over the
+ * saved URL, and `HANDOFF_REGISTRY_ACCESS_TOKEN` wins over the saved token. The saved token only
+ * applies to the URL it was issued for.
+ */
+export const resolveAuthenticatedRegistryConnection = async (
+  config: Config | null | undefined,
+  workingPath = process.cwd()
+): Promise<ResolvedRegistryConnection> => {
+  const connection = resolveRegistryConnection(config);
+
+  const auth = await readCliAuth(workingPath);
+  if (!cliAuthTokenIsValid(auth)) return connection;
+
+  const url = connection.url || auth!.remoteUrl;
+  const accessToken = connection.accessToken || (cliAuthMatchesRegistry(auth, url) ? auth!.accessToken : '');
+  return { ...connection, url, accessToken };
+};

package/src/registry/db/driver.ts

@@ -18,7 +18,7 @@ export type RegistryDatabaseDriver = 'pg' | 'neon';
 /** Default env-var name holding the database connection string. */
 export const DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
 
-/** Default env-var name holding the registry management API bearer token. */
+/** @deprecated Fixed registry server secrets are no longer authorized. */
 export const DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
 
 /** Default registry database driver when none is configured. */
@@ -41,9 +41,10 @@ export const resolveDatabaseUrlEnv = (config: Config | null | undefined): string
 };
 
 /**
- * Resolve the env-var *name* holding the registry management API bearer token (defaults to
- * `HANDOFF_REGISTRY_API_TOKEN`). Like the database URL, only the name is ever persisted — the token
- * value is resolved from the environment at request time and never written to config.
+ * Resolve the legacy fixed-token env-var name for configuration compatibility.
+ *
+ * @deprecated The returned env var is intentionally ignored by registry authorization. Use a
+ * user-issued access token or `handoff-app login`.
  */
 export const resolveApiTokenEnv = (config: Config | null | undefined): string => {
   const configured = config?.runtime?.registry?.apiTokenEnv?.trim();

package/src/registry/db/index.ts

@@ -5,10 +5,22 @@ export {
   docsArtifacts,
   patternFiles,
   patterns,
+  registryAccessTokens,
+  registryAuthActionTokens,
+  registryAuthRateLimits,
+  registryDeviceAuthorizations,
+  registryInstallations,
   registrySchema,
+  registryUsers,
   type BuildMetadataEntityKind,
   type DocsArtifactEntityKind,
+  type RegistryAccessScope,
+  type RegistryAuthActionPurpose,
+  type RegistryDeviceAuthorizationStatus,
+  type RegistryRateLimitBucket,
   type RegistryReviewMetadata,
+  type RegistryUserRole,
+  type RegistryUserStatus,
 } from './schema';
 
 export type { ArtifactBuildStatus as RegistryBuildStatus } from '../../artifacts/types';

package/src/registry/db/schema.ts

@@ -23,7 +23,7 @@
  */
 
 import { sql } from 'drizzle-orm';
-import { check, customType, index, integer, jsonb, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';
+import { check, customType, index, integer, jsonb, pgTable, primaryKey, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
 import type { ArtifactBuildStatus, ArtifactKind, ArtifactOwnerKind, ArtifactReference } from '../../artifacts/types';
 import type { RegistryTextFileKind } from '../../store/types';
 import type { TokenSetKind } from '../tokens/sets';
@@ -43,6 +43,24 @@ const bytea = customType<{ data: Buffer; driverData: Buffer }>({
 export type AssetStorageProvider = 'database' | 'vercel-blob' | (string & {});
 import type { ComponentListObject, PageListObject, PatternComponentEntry, PatternListObject } from '../../transformers/preview/types';
 
+/** Registry account role. Administrators may issue write-scoped credentials. */
+export type RegistryUserRole = 'admin' | 'member';
+
+/** Registry account lifecycle. Invited and deactivated accounts cannot authenticate. */
+export type RegistryUserStatus = 'invited' | 'active' | 'deactivated';
+
+/** One-time account action represented by a hashed secret. */
+export type RegistryAuthActionPurpose = 'invite' | 'password_reset';
+
+/** Capability granted to a registry access token. */
+export type RegistryAccessScope = 'registry:read' | 'registry:write';
+
+/** State machine for an RFC 8628-style CLI device authorization. */
+export type RegistryDeviceAuthorizationStatus = 'pending' | 'approved' | 'denied' | 'consumed';
+
+/** Public endpoint family protected by a database-backed throttling counter. */
+export type RegistryRateLimitBucket = 'login' | 'password_reset' | 'device';
+
 /**
  * Entity a docs read-model artifact is associated with. `page` is included only for type-compat with
  * the generic management delete path (which filters `docs_artifacts.entityKind` by kind); pages emit
@@ -426,6 +444,155 @@ export const assetBlobs = pgTable('asset_blobs', {
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
 });
 
+/**
+ * Registry users. Browser sessions carry the id and auth version, while protected requests re-read
+ * this row so role/status changes take effect without waiting for a cookie to expire.
+ */
+export const registryUsers = pgTable(
+  'registry_users',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    email: text('email').notNull(),
+    name: text('name'),
+    image: text('image'),
+    role: text('role').$type<RegistryUserRole>().notNull().default('member'),
+    status: text('status').$type<RegistryUserStatus>().notNull().default('invited'),
+    passwordHash: text('password_hash'),
+    emailVerifiedAt: timestamp('email_verified_at', { withTimezone: true }),
+    authVersion: integer('auth_version').notNull().default(1),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('registry_users_normalized_email_idx').on(sql`lower(btrim(${table.email}))`),
+    index('registry_users_status_role_idx').on(table.status, table.role),
+    check('registry_users_email_normalized', sql`${table.email} = lower(btrim(${table.email}))`),
+    check('registry_users_role_valid', sql`${table.role} in ('admin', 'member')`),
+    check('registry_users_status_valid', sql`${table.status} in ('invited', 'active', 'deactivated')`),
+    check('registry_users_auth_version_positive', sql`${table.authVersion} > 0`),
+  ]
+);
+
+/**
+ * Permanent one-row installation marker. There is deliberately no reset path: deleting or
+ * deactivating users must never reopen the public first-visitor installer.
+ */
+export const registryInstallations = pgTable(
+  'registry_installations',
+  {
+    id: text('id').primaryKey().default('default'),
+    status: text('status').notNull().default('installed'),
+    schemaVersion: integer('schema_version').notNull(),
+    initialAdminUserId: text('initial_admin_user_id')
+      .notNull()
+      .references(() => registryUsers.id, { onDelete: 'restrict' }),
+    installedAt: timestamp('installed_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    check('registry_installations_singleton', sql`${table.id} = 'default'`),
+    check('registry_installations_status_valid', sql`${table.status} = 'installed'`),
+    check('registry_installations_schema_version_positive', sql`${table.schemaVersion} > 0`),
+  ]
+);
+
+/** Hash-only invitation and password-reset secrets. */
+export const registryAuthActionTokens = pgTable(
+  'registry_auth_action_tokens',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    userId: text('user_id')
+      .notNull()
+      .references(() => registryUsers.id, { onDelete: 'cascade' }),
+    purpose: text('purpose').$type<RegistryAuthActionPurpose>().notNull(),
+    tokenHash: text('token_hash').notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    usedAt: timestamp('used_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('registry_auth_action_tokens_hash_idx').on(table.tokenHash),
+    index('registry_auth_action_tokens_user_purpose_idx').on(table.userId, table.purpose),
+    check('registry_auth_action_tokens_purpose_valid', sql`${table.purpose} in ('invite', 'password_reset')`),
+  ]
+);
+
+/** Revocable, hash-only registry API credentials owned by one user. */
+export const registryAccessTokens = pgTable(
+  'registry_access_tokens',
+  {
+    /** Public lookup id embedded in the opaque token; not itself a credential. */
+    id: text('id').primaryKey(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => registryUsers.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    secretHash: text('secret_hash').notNull(),
+    scopes: jsonb('scopes').$type<RegistryAccessScope[]>().notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index('registry_access_tokens_user_idx').on(table.userId),
+    index('registry_access_tokens_expires_idx').on(table.expiresAt),
+    check('registry_access_tokens_name_not_blank', sql`length(btrim(${table.name})) > 0`),
+    check('registry_access_tokens_scopes_array', sql`jsonb_typeof(${table.scopes}) = 'array'`),
+  ]
+);
+
+/** Short-lived authorization used by `handoff-app login`. Plaintext device codes are never stored. */
+export const registryDeviceAuthorizations = pgTable(
+  'registry_device_authorizations',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    deviceCodeHash: text('device_code_hash').notNull(),
+    userCode: text('user_code').notNull(),
+    status: text('status').$type<RegistryDeviceAuthorizationStatus>().notNull().default('pending'),
+    userId: text('user_id').references(() => registryUsers.id, { onDelete: 'set null' }),
+    scopes: jsonb('scopes').$type<RegistryAccessScope[]>().notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    approvedAt: timestamp('approved_at', { withTimezone: true }),
+    consumedAt: timestamp('consumed_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('registry_device_authorizations_device_hash_idx').on(table.deviceCodeHash),
+    uniqueIndex('registry_device_authorizations_user_code_idx').on(table.userCode),
+    index('registry_device_authorizations_expires_idx').on(table.expiresAt),
+    check('registry_device_authorizations_status_valid', sql`${table.status} in ('pending', 'approved', 'denied', 'consumed')`),
+    check('registry_device_authorizations_scopes_array', sql`jsonb_typeof(${table.scopes}) = 'array'`),
+  ]
+);
+
+/**
+ * Fixed-window throttling counters. Callers pass a hash of the identifying value so raw emails and
+ * IP addresses are not retained.
+ */
+export const registryAuthRateLimits = pgTable(
+  'registry_auth_rate_limits',
+  {
+    bucket: text('bucket').$type<RegistryRateLimitBucket>().notNull(),
+    identifierHash: text('identifier_hash').notNull(),
+    windowStartedAt: timestamp('window_started_at', { withTimezone: true }).notNull(),
+    attempts: integer('attempts').notNull().default(1),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.bucket, table.identifierHash, table.windowStartedAt] }),
+    index('registry_auth_rate_limits_expires_idx').on(table.expiresAt),
+    check('registry_auth_rate_limits_bucket_valid', sql`${table.bucket} in ('login', 'password_reset', 'device')`),
+    check('registry_auth_rate_limits_attempts_positive', sql`${table.attempts} > 0`),
+  ]
+);
+
 /** All registry tables, for typed Drizzle clients and migration tooling. */
 export const registrySchema = {
   components,
@@ -441,4 +608,10 @@ export const registrySchema = {
   assetCollections,
   assets,
   assetBlobs,
+  registryUsers,
+  registryInstallations,
+  registryAuthActionTokens,
+  registryAccessTokens,
+  registryDeviceAuthorizations,
+  registryAuthRateLimits,
 };

package/src/registry/publish/assets.ts

@@ -42,7 +42,7 @@ const toManifestEntry = (asset: AssetMetadata): AssetManifestEntry => ({
  * throws at the end if any collection failed.
  */
 export const publishAssets = async (handoff: Handoff, collection?: string): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
   if (collection && !isAssetCollection(collection)) {
     throw new PublishError(`Unknown asset collection "${collection}". Supported collections: ${ASSET_COLLECTIONS.join(', ')}.`);
   }

package/src/registry/publish/errors.ts

@@ -11,10 +11,10 @@ export const describeUploadFailure = (
   switch (error.code) {
     case 'runtime_mode_conflict':
       return `The registry at ${registryUrl} is not running in registry mode, so it cannot accept publishes: ${error.message}`;
-    case 'token_not_configured':
-      return `The registry at ${registryUrl} has no management token configured, so it is rejecting mutations: ${error.message}`;
     case 'unauthorized':
-      return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+      return `The registry rejected the access token (401). Run \`handoff-app login --url ${registryUrl}\` again, or replace the user-issued CI token.`;
+    case 'forbidden':
+      return `The registry token does not have permission to publish (403). Sign in as an administrator and authorize a token with registry:write access.`;
     case 'bad_request':
       return `The registry rejected the ${rejectedPayload} (400): ${error.message}`;
     default:

package/src/registry/publish/index.ts

@@ -16,7 +16,7 @@ import processComponents from '../../transformers/preview/component/builder';
 import { processPatterns } from '../../transformers/preview/pattern/builder';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, RegistryClientError } from '../client';
-import { resolveRegistryConnection } from '../connection';
+import { resolveAuthenticatedRegistryConnection } from '../connection';
 import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { describeUploadFailure } from './errors';
 import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
@@ -34,7 +34,7 @@ export class PublishError extends Error {
  * hosts do not publish) and a resolved registry URL + access token. Throws an actionable
  * {@link PublishError} naming the exact misconfiguration.
  */
-export const resolveConnectionOrThrow = (handoff: Handoff) => {
+export const resolveConnectionOrThrow = async (handoff: Handoff) => {
   const mode = handoff.config?.runtime?.mode ?? 'workspace';
   if (mode !== 'workspace') {
     throw new PublishError(
@@ -43,17 +43,17 @@ export const resolveConnectionOrThrow = (handoff: Handoff) => {
     );
   }
 
-  const connection = resolveRegistryConnection(handoff.config);
+  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath);
   if (!connection.url) {
     throw new PublishError(
-      `No registry URL is configured. Set runtime.registryConnection.url, or the "${connection.urlEnv}" environment variable, ` +
-        'to the base URL of the registry to publish to.'
+      `No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
+        `or set the "${connection.urlEnv}" environment variable to the base URL of the registry to publish to.`
     );
   }
   if (!connection.accessToken) {
     throw new PublishError(
-      `No registry access token is configured. Set the "${connection.accessTokenEnv}" environment variable to the ` +
-        "registry's bearer token to authorize publishing."
+      `No registry access token is configured. Run \`handoff-app login --url ${connection.url}\`, or set the ` +
+        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.`
     );
   }
   return connection;
@@ -103,7 +103,7 @@ const runTargetedBuild = async (handoff: Handoff, kind: TransferEntityKind, id:
  * receive a targeted build, while pages are packaged directly from their source.
  */
 export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
 
   Logger.info(kind === 'page' ? `Preparing page "${id}" for publish…` : `Building ${kind} "${id}" for publish…`);
   await runTargetedBuild(handoff, kind, id);
@@ -160,7 +160,7 @@ const listWorkspaceEntityIds = async (handoff: Handoff, kind: TransferEntityKind
  * collected and never aborts the rest; the run throws at the end if any entity failed.
  */
 export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
 
   Logger.info(`Building ${kind}s for publish…`);
   await runBulkBuild(handoff, kind);

package/src/registry/publish/tokens.ts

@@ -58,7 +58,7 @@ const buildTokenSetPackage = async (handoff: Handoff, set: TokenSetRecord): Prom
  * committed atomically server-side); the run throws at the end if any set failed.
  */
 export const publishTokens = async (handoff: Handoff, setId?: string): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
 
   Logger.info(setId ? `Building tokens to publish "${setId}"…` : 'Building tokens for publish…');
   await handoff.fetch();

package/src/types/config.ts

@@ -135,7 +135,10 @@ export interface HandoffRuntimeConfig {
   registry?: {
     /** Name of the env var holding the database URL. @default "DATABASE_URL" */
     databaseUrlEnv?: string;
-    /** Name of the env var holding the registry API token. @default "HANDOFF_REGISTRY_API_TOKEN" */
+    /**
+     * @deprecated Fixed registry secrets are no longer authorized. This option remains parseable
+     * only so existing configuration files do not break.
+     */
     apiTokenEnv?: string;
     database?: {
       /**