handoff-app 2.0.0-9 → 2.0.0

package/src/registry/asset-storage/types.ts

@@ -1,13 +1,13 @@
 /**
- * Server-only asset storage contract for object-backed providers (Vercel Blob + custom
- * {@link defineAssetStorage} modules), so callers need no provider-specific logic. The built-in
- * `database` provider is the inline default: bytes live in the `asset_blobs.content` bytea column,
- * read/written directly by the registry, so it needs no adapter. Object providers record a
- * `storageRef` + provider id so reads resolve back through whichever provider stored the blob.
+ * Server-only asset storage contract for custom {@link defineStorageProvider} object storage modules.
+ * The built-in `database` provider is the inline default: bytes live in the `asset_blobs.content`
+ * bytea column, read/written directly by the registry, so it needs no module. Object providers
+ * record a `storageRef` + provider id so reads resolve back through whichever provider stored the
+ * blob.
  */
 
 /** Input for storing one content-addressed blob. */
-export interface AssetStorageInput {
+export interface StorageInput {
   /** SHA-256 of the bytes (hex), the content identity, usable as a stable object key. */
   hash: string;
   bytes: Buffer;
@@ -19,28 +19,50 @@ export interface AssetStorageInput {
  * How a provider returns stored content: raw bytes, a readable stream, or a signed/redirect URL the
  * client can fetch directly (used to avoid routing large payloads through the serverless function).
  */
-export type AssetStorageReadResult =
+export type StorageReadResult =
   | { kind: 'bytes'; bytes: Buffer; contentType?: string }
   | { kind: 'stream'; stream: NodeJS.ReadableStream; contentType?: string }
   | { kind: 'redirect'; url: string };
 
-/** The pluggable storage adapter contract for object-backed asset providers. */
-export interface AssetStorage {
+/** Input for a direct upload of one blob from the CLI to storage. */
+export interface AssetUploadInput {
+  /** SHA-256 of the bytes (hex). */
+  hash: string;
+  size: number;
+  contentType: string;
+}
+
+/** A signed URL the CLI sends the blob to with `PUT` and the given headers. */
+export interface AssetUpload {
+  url: string;
+  headers?: Record<string, string>;
+  /** The reference to persist on the blob's `asset_blobs` row after the upload. */
+  storageRef: string;
+}
+
+/** The pluggable storage contract for object-backed asset providers. */
+export interface StorageProvider {
   /** Store one blob and return the reference to persist on its `asset_blobs` row. */
-  put(input: AssetStorageInput): Promise<{ storageRef: string }>;
+  put(input: StorageInput): Promise<{ storageRef: string }>;
+  /**
+   * Return a signed URL so the CLI uploads the blob directly to storage instead of through the
+   * registry, which avoids serverless request size limits. The URL must make storage reject bytes
+   * that do not match `hash`, for example with a signed SHA-256 checksum header.
+   */
+  createUpload?(input: AssetUploadInput): Promise<AssetUpload>;
   /** Resolve stored content by its `storageRef`. */
-  get(storageRef: string): Promise<AssetStorageReadResult>;
+  get(storageRef: string): Promise<StorageReadResult>;
   /** Delete stored content by its `storageRef`. Should be retryable/idempotent. */
   delete(storageRef: string): Promise<void>;
 }
 
-/** Context passed to a custom adapter factory: its non-secret config options + the process env. */
-export interface AssetStorageContext {
-  /** Non-secret options from `runtime.registry.assetStorage.options` (bucket env-var names, region, …). */
+/** Context passed to a custom provider factory: its config options and the process env. */
+export interface StorageProviderContext {
+  /** `runtime.registry.assetStorage.options`, with each `fromEnv()` reference replaced by its value. */
   options: Record<string, unknown>;
-  /** The process environment. Read secret *values* here by the env-var *names* carried in options. */
+  /** The process environment. */
   env: NodeJS.ProcessEnv;
 }
 
-/** A custom adapter may export the adapter directly or a factory that builds it from its context. */
-export type AssetStorageFactory = (context: AssetStorageContext) => AssetStorage | Promise<AssetStorage>;
+/** A custom provider module may export the provider directly or a factory that builds it from its context. */
+export type StorageProviderFactory = (context: StorageProviderContext) => StorageProvider | Promise<StorageProvider>;

package/src/registry/auth/ai-keys.ts

@@ -0,0 +1,62 @@
+import { and, eq } from 'drizzle-orm';
+import type { RegistryDatabase } from '../db/client';
+import { registryAiKeys } from '../db/schema';
+import { decryptSecret, encryptSecret } from './crypto';
+
+/**
+ * Reader-supplied keys for connections the config declares with `credential: 'user'`.
+ *
+ * The key is write-only across the API boundary: once saved, a read reports only that a key exists.
+ * Only the chat route ever decrypts one, and only to send it to the connection's own endpoint.
+ */
+
+/**
+ * Ids of the connections this reader has a *usable* key for. A row that no longer decrypts — written
+ * under a rotated `HANDOFF_AI_KEY_SECRET` — is left out, so the account page and the assistant agree
+ * that no key is in place instead of offering a key the provider would never receive.
+ */
+export const listRegistryAiKeyConnections = async (db: RegistryDatabase, userId: string): Promise<string[]> => {
+  const rows = await db
+    .select({ connectionId: registryAiKeys.connectionId, encryptedKey: registryAiKeys.encryptedKey })
+    .from(registryAiKeys)
+    .where(eq(registryAiKeys.userId, userId))
+    .orderBy(registryAiKeys.connectionId);
+  return rows.filter((row) => decryptSecret(row.encryptedKey) !== null).map((row) => row.connectionId);
+};
+
+/** Save or replace this reader's key for one connection. */
+export const saveRegistryAiKey = async (
+  db: RegistryDatabase,
+  input: { userId: string; connectionId: string; key: string }
+): Promise<void> => {
+  const encryptedKey = encryptSecret(input.key);
+  await db
+    .insert(registryAiKeys)
+    .values({ userId: input.userId, connectionId: input.connectionId, encryptedKey })
+    .onConflictDoUpdate({
+      target: [registryAiKeys.userId, registryAiKeys.connectionId],
+      set: { encryptedKey, updatedAt: new Date() },
+    });
+};
+
+/** Remove this reader's key for one connection. Returns whether a row was there to remove. */
+export const deleteRegistryAiKey = async (db: RegistryDatabase, input: { userId: string; connectionId: string }): Promise<boolean> => {
+  const rows = await db
+    .delete(registryAiKeys)
+    .where(and(eq(registryAiKeys.userId, input.userId), eq(registryAiKeys.connectionId, input.connectionId)))
+    .returning({ connectionId: registryAiKeys.connectionId });
+  return rows.length > 0;
+};
+
+/**
+ * Read back one reader's key. A row that no longer decrypts reads as absent, so the reader is told
+ * to add a key rather than shown a provider error.
+ */
+export const readRegistryAiKey = async (db: RegistryDatabase, input: { userId: string; connectionId: string }): Promise<string | null> => {
+  const [row] = await db
+    .select({ encryptedKey: registryAiKeys.encryptedKey })
+    .from(registryAiKeys)
+    .where(and(eq(registryAiKeys.userId, input.userId), eq(registryAiKeys.connectionId, input.connectionId)))
+    .limit(1);
+  return row ? decryptSecret(row.encryptedKey) : null;
+};

package/src/registry/auth/crypto.ts

@@ -1,4 +1,4 @@
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, timingSafeEqual } from 'node:crypto';
 
 export const hashSecret = (secret: string): string => createHash('sha256').update(secret, 'utf8').digest('hex');
 
@@ -11,3 +11,65 @@ export const secretHashMatches = (secret: string, expectedHash: string): boolean
 };
 
 export const normalizeEmail = (email: string): string => email.trim().toLowerCase();
+
+/** Env var holding the deployment secret that reader-supplied AI keys are encrypted with. */
+export const AI_KEY_SECRET_ENV = 'HANDOFF_AI_KEY_SECRET';
+
+/** Shortest secret worth accepting. Matches the guidance the installer gives for `AUTH_SECRET`. */
+const MIN_KEY_SECRET_LENGTH = 32;
+
+/** Format marker, so a later algorithm is distinguishable from this one rather than guessed at. */
+const ENCRYPTED_SECRET_VERSION = 'v1';
+
+/** Thrown when a key must be encrypted but the deployment secret is missing or too short. */
+export class MissingEncryptionSecretError extends Error {
+  constructor() {
+    super(
+      `Reader-supplied AI keys cannot be stored because ${AI_KEY_SECRET_ENV} is not set. Set it to a ` +
+        `random value of at least ${MIN_KEY_SECRET_LENGTH} characters, or declare no connection with ` +
+        `"credential: 'user'".`
+    );
+    this.name = 'MissingEncryptionSecretError';
+  }
+}
+
+/**
+ * Derive the record key. A per-record salt means two rows holding the same provider key produce
+ * different ciphertexts, and the fixed `info` label keeps this key distinct from anything else the
+ * same secret is ever used for.
+ */
+const deriveKey = (salt: Buffer): Buffer => {
+  const secret = process.env[AI_KEY_SECRET_ENV]?.trim();
+  if (!secret || secret.length < MIN_KEY_SECRET_LENGTH) throw new MissingEncryptionSecretError();
+  return Buffer.from(hkdfSync('sha256', Buffer.from(secret, 'utf8'), salt, 'handoff-ai-key', 32));
+};
+
+/**
+ * Encrypt a value that has to be read back, such as a reader's provider key. AES-256-GCM, with the
+ * salt, nonce and authentication tag carried in the payload so a row is self-describing.
+ */
+export const encryptSecret = (plaintext: string): string => {
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', deriveKey(salt), iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const parts = [salt, iv, cipher.getAuthTag(), encrypted].map((part) => part.toString('base64url'));
+  return [ENCRYPTED_SECRET_VERSION, ...parts].join('.');
+};
+
+/**
+ * Decrypt a value written by {@link encryptSecret}. Returns `null` for anything that does not
+ * authenticate — a payload in another format, or one written under a secret that has since been
+ * rotated — so a stale row reads as "no key saved" instead of failing the request.
+ */
+export const decryptSecret = (payload: string): string | null => {
+  const [version, salt, iv, tag, encrypted] = payload.split('.');
+  if (version !== ENCRYPTED_SECRET_VERSION || !salt || !iv || !tag || !encrypted) return null;
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', deriveKey(Buffer.from(salt, 'base64url')), Buffer.from(iv, 'base64url'));
+    decipher.setAuthTag(Buffer.from(tag, 'base64url'));
+    return Buffer.concat([decipher.update(Buffer.from(encrypted, 'base64url')), decipher.final()]).toString('utf8');
+  } catch {
+    return null;
+  }
+};

package/src/registry/auth/index.ts

@@ -25,7 +25,17 @@ export {
   type ResendUserInvitationResult,
   type ConsumeAuthActionResult,
 } from './action-tokens';
-export { createOpaqueSecret, hashSecret, normalizeEmail, secretHashMatches } from './crypto';
+export {
+  AI_KEY_SECRET_ENV,
+  MissingEncryptionSecretError,
+  createOpaqueSecret,
+  decryptSecret,
+  encryptSecret,
+  hashSecret,
+  normalizeEmail,
+  secretHashMatches,
+} from './crypto';
+export { deleteRegistryAiKey, listRegistryAiKeyConnections, readRegistryAiKey, saveRegistryAiKey } from './ai-keys';
 export { buildGravatarUrl } from './gravatar';
 export { authenticateRegistrySyncSecret, resolveRegistrySyncSecret, SYNC_SECRET_ENV } from './sync-secret';
 export {

package/src/registry/checkout/index.ts

@@ -6,7 +6,8 @@
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
  * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
- * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published. A
+ * new entity goes to the directory it was published from (`sourceDir`).
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an
@@ -30,14 +31,14 @@ import {
   type RendererKind,
   type SourceFormat,
 } from '../../catalog/renderers';
-import { addToCatalog, isIncluded } from '../../config/catalog-include';
 import { isComponentDirectory, resolveComponentDeclaration } from '../../config/runtime';
 import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
+import { arePathsEqual } from '../../utils/path';
 import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
 import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNote } from '../connection';
-import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
+import { isSafePathSegment, isSafeRelativePath, isWorkspaceRelativePath, resolvePathWithin } from '../path';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
 
@@ -52,12 +53,7 @@ export class CheckoutError extends Error {
 /** Default authoring format synthesized when no existing file or configured preference applies. */
 const DEFAULT_DECLARATION_FORMAT: DeclarationFormat = 'ts';
 
-/** Default workspace subdirectory an entity is written into when none is configured. */
-const DEFAULT_ENTITY_DIR: Record<TransferEntityKind, string> = {
-  component: 'components',
-  pattern: 'patterns',
-  page: 'pages',
-};
+const PAGES_DIR = 'pages';
 
 /** Source-file extensions stripped to form a module specifier for a React component import. */
 const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
@@ -108,88 +104,48 @@ const describeFetchFailure = (error: RegistryClientError, kind: TransferEntityKi
   }
 };
 
-/**
- * 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}: catalog.include declares directories under different ` +
-        `parents (${roots.map(relative).join(', ')}), and none is named "${DEFAULT_ENTITY_DIR[kind]}". 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],
+/** `dir` is a `catalog.include` entry, or a direct child of a collection entry. */
+const isInCatalog = (handoff: Handoff, dir: string): boolean =>
+  (handoff.config?.catalog?.include ?? []).some((entry) => {
+    const included = path.resolve(handoff.workingPath, entry);
+    return arePathsEqual(included, dir) || (!isComponentDirectory(included) && arePathsEqual(included, path.dirname(dir)));
   });
-  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
- * `catalog.include`. 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 are settled by the
- * conventional directory name for the kind, and only then by asking the user. With nothing
- * configured we fall back to the default subdir.
- */
-const resolveCollectionRoot = async (handoff: Handoff, kind: TransferEntityKind): Promise<string> => {
-  const configuredRoots = handoff.config?.catalog?.include;
-  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;
-      })
-    ),
-  ];
-
-  if (roots.length === 1) {
-    return roots[0];
-  }
 
-  // `catalog.include` is one list for both lanes, so a project that registers `components` and
-  // `patterns` offers two roots for every checkout. Without this, every such project prompts, and a
-  // non-interactive `--force` run fails.
-  const conventional = roots.filter((root) => path.basename(root) === DEFAULT_ENTITY_DIR[kind]);
-  if (conventional.length === 1) {
-    return conventional[0];
-  }
-
-  return 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> => {
+/** A locally declared entity keeps its directory. A new one goes to the directory it was published from. */
+const resolveTargetDir = async (
+  handoff: Handoff,
+  kind: TransferEntityKind,
+  id: string,
+  sourceDir: string | undefined
+): Promise<{ dir: string; isInCatalog: boolean }> => {
   const store = kind === 'component' ? handoff.store.components : handoff.store.patterns;
   const existing = await store.get(id);
   const existingDir = (existing as { path?: string } | null)?.path;
   if (existingDir) {
-    return existingDir;
+    return { dir: existingDir, isInCatalog: true };
   }
 
-  const root = await resolveCollectionRoot(handoff, kind);
-  const targetDir = resolvePathWithin(root, id);
-  if (!targetDir) {
-    throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
+  if (!isWorkspaceRelativePath(sourceDir)) {
+    throw new CheckoutError(`The registry has no valid source directory for ${kind} "${id}". Republish it, then checkout again.`);
+  }
+  const dir = path.resolve(handoff.workingPath, sourceDir);
+  return { dir, isInCatalog: isInCatalog(handoff, dir) };
+};
+
+/** `--force` fails here: it skips overwrite prompts, not approval of a location the registry chose. */
+const confirmLocation = async (handoff: Handoff, kind: TransferEntityKind, id: string, dir: string): Promise<boolean> => {
+  const relative = path.relative(handoff.workingPath, dir) || '.';
+  if (handoff.force) {
+    throw new CheckoutError(
+      `The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. ` +
+        `Add "${relative}" or its parent directory to catalog.include, or run checkout without --force to accept the location.`
+    );
   }
-  return targetDir;
+  const proceed = await p.confirm({
+    message: `The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. Write it there?`,
+    initialValue: false,
+  });
+  return !p.isCancel(proceed) && proceed === true;
 };
 
 /** Read the extension of an existing local declaration in `dir`, if any maps to a known format. */
@@ -761,7 +717,7 @@ export const reportPlannedWrites = (handoff: Handoff, label: string, targets: st
  * markdown file is itself the authored source — so the page round-trips byte-for-byte.
  */
 const checkoutPage = async (handoff: Handoff, id: string, payload: CheckoutPayload): Promise<void> => {
-  const pagesRoot = path.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR.page);
+  const pagesRoot = path.resolve(handoff.workingPath, PAGES_DIR);
   const targets = payload.files.map((file) => {
     const target = resolvePathWithin(pagesRoot, file.path);
     if (!target) {
@@ -799,7 +755,7 @@ const checkoutSingle = async (
   id: string,
   client: RegistryClient,
   registryUrl: string
-): Promise<string | null> => {
+): Promise<void> => {
   const validId = kind === 'page' ? isSafeRelativePath(id) : isSafePathSegment(id);
   if (!validId) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
@@ -816,14 +772,15 @@ const checkoutSingle = async (
     throw error;
   }
 
-  // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
-  // listed in `catalog.include`, so there's nothing to register.
   if (kind === 'page') {
     await checkoutPage(handoff, id, payload);
-    return null;
+    return;
   }
 
-  const targetDir = await resolveTargetDir(handoff, kind, id);
+  const target = await resolveTargetDir(handoff, kind, id, payload.sourceDir);
+  const targetDir = target.dir;
+  const relativeDir = path.relative(handoff.workingPath, targetDir) || '.';
+  const outsideCatalogWarning = `Add "${relativeDir}" to catalog.include, or the build will not load ${kind} "${id}".`;
   const format = resolveDeclarationFormat(handoff, targetDir);
   const declarationFileName = resolveDeclarationFileName(targetDir, id, format);
   const declarationPath = path.join(targetDir, declarationFileName);
@@ -840,13 +797,19 @@ const checkoutSingle = async (
   const plannedWrites = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath];
   const conflicts = plannedWrites.filter((file) => fs.existsSync(file));
   if (handoff.dryRun) {
-    // Returning null also skips `registerCheckedOut`, so a dry run never edits handoff.config either.
     reportPlannedWrites(handoff, `${kind} "${id}"`, plannedWrites, conflicts);
-    return null;
+    if (!target.isInCatalog) {
+      Logger.warn(`${relativeDir} is outside catalog.include. ${outsideCatalogWarning}`);
+    }
+    return;
+  }
+  if (!target.isInCatalog && !(await confirmLocation(handoff, kind, id, targetDir))) {
+    Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
+    return;
   }
   if (!(await confirmOverwrite(handoff, conflicts))) {
     Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
-    return null;
+    return;
   }
 
   await fs.ensureDir(targetDir);
@@ -858,41 +821,10 @@ const checkoutSingle = async (
   await fs.writeFile(declarationPath, declaration, 'utf8');
   written.push(declarationPath);
 
-  Logger.success(
-    `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 `catalog.include` 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 `include` 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 kindLabel = kind === 'component' ? 'components' : 'patterns';
-  const unlisted = targetDirs.filter((dir) => !isIncluded(handoff, dir));
-  if (unlisted.length === 0) {
-    return;
-  }
-
-  const result = await addToCatalog(handoff, unlisted);
-  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} ${kindLabel} path(s).`);
-    return;
+  Logger.success(`Checked out ${kind} "${id}" into ${relativeDir} (${payload.files.length} source file(s) + ${declarationFileName}).`);
+  if (!target.isInCatalog) {
+    Logger.warn(outsideCatalogWarning);
   }
-
-  const where = result.configPath ? path.relative(handoff.workingPath, result.configPath) : 'handoff.config';
-  Logger.warn(`Could not update ${where} automatically. Add these to catalog.include manually:`);
-  result.pending.forEach((rel) => Logger.warn(`  - ${rel}`));
 };
 
 /**
@@ -902,10 +834,7 @@ const registerCheckedOut = async (handoff: Handoff, kind: TransferEntityKind, ta
 export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
   const connection = await resolveConnectionOrThrow(handoff);
   const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
-  const targetDir = await checkoutSingle(handoff, kind, id, client, connection.url);
-  if (targetDir) {
-    await registerCheckedOut(handoff, kind, [targetDir]);
-  }
+  await checkoutSingle(handoff, kind, id, client, connection.url);
 };
 
 /** List the ids the registry publishes for one kind, naming the registry in a listing failure. */
@@ -922,7 +851,7 @@ const listPublishedIds = async (kind: TransferEntityKind, client: RegistryClient
 };
 
 /**
- * Check out the given ids of one kind and register what landed. The caller selects the ids, because a
+ * Check out the given ids of one kind. The caller selects the ids, because a
  * catalog run resolves them across both entity lanes before any of them is written.
  *
  * A per-entity failure is collected and never aborts the rest. Failures are reported here, and the
@@ -937,22 +866,15 @@ const checkoutSelected = async (
 ): Promise<number> => {
   let checkedOut = 0;
   const failed: { id: string; message: string }[] = [];
-  const targetDirs: string[] = [];
   for (const id of targets) {
     try {
-      const targetDir = await checkoutSingle(handoff, kind, id, client, registryUrl);
-      if (targetDir) {
-        targetDirs.push(targetDir);
-      }
+      await checkoutSingle(handoff, kind, id, client, registryUrl);
       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} ${handoff.dryRun ? 'would be checked out' : 'checked out'}` +
       `${failed.length ? `, ${failed.length} failed` : ''}.`

package/src/registry/client.ts

@@ -11,6 +11,7 @@
 import type { CheckoutPayload, EntitySummary, TransferEntityKind, TransferPackage } from './transfer';
 import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
 import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
+import type { AssetUpload } from './asset-storage/types';
 
 /** Encode a token set id for the catch-all transfer route, preserving `/` between segments. */
 const encodeSetIdPath = (id: string): string =>
@@ -139,6 +140,30 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
     return envelope;
   };
 
+  const uploadAssetBlobThroughRegistry = async (blobPath: string, contentType: string, bytes: Buffer): Promise<void> => {
+    const url = `${root}${blobPath}`;
+    // Send a Blob, not a Buffer/Uint8Array: under Next `trailingSlash: true` this PUT is
+    // 308-redirected and undici must re-send the body; a typed-array body's ArrayBuffer is detached
+    // after the first send ("slice on a detached ArrayBuffer"), but a Blob is re-readable.
+    const body = new Blob([new Uint8Array(bytes)] as unknown as BlobPart[]);
+    const response = await fetchRegistry(url, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': contentType || 'application/octet-stream',
+        ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
+      },
+      body,
+    });
+    if (!response.ok) {
+      let code: string | undefined;
+      let message = `Blob upload failed (${response.status} ${response.statusText}).`;
+      const envelope = await readErrorEnvelope(response);
+      code = envelope?.error?.code;
+      message = envelope?.error?.message || message;
+      throw new RegistryClientError(message, { status: response.status, code });
+    }
+  };
+
   return {
     /** Publish (`PUT`) an entity's package to the registry transfer endpoint. */
     publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope> {
@@ -187,29 +212,44 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
       const envelope = await request<{ missing: string[] }>('POST', '/api/registry/transfer/assets/blobs/have', { hashes });
       return envelope.data?.missing ?? [];
     },
-    /** Upload one content-addressed blob (binary-safe body). Idempotent: re-uploading an existing hash no-ops. */
+    /**
+     * Upload one content-addressed blob. Sends it directly to storage when the registry returns a
+     * signed URL, otherwise through the registry. Idempotent: re-uploading an existing hash no-ops.
+     */
     async uploadAssetBlob(hash: string, contentType: string, bytes: Buffer): Promise<void> {
-      const url = `${root}/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
-      // Send a Blob, not a Buffer/Uint8Array: under Next `trailingSlash: true` this PUT is
-      // 308-redirected and undici must re-send the body; a typed-array body's ArrayBuffer is detached
-      // after the first send ("slice on a detached ArrayBuffer"), but a Blob is re-readable.
-      const body = new Blob([new Uint8Array(bytes)] as unknown as BlobPart[]);
-      const response = await fetchRegistry(url, {
-        method: 'PUT',
-        headers: {
-          'Content-Type': contentType || 'application/octet-stream',
-          ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
-        },
-        body,
-      });
+      const blobPath = `/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+      const size = bytes.length;
+      const envelope = await request<{ upload: AssetUpload | null; stored?: boolean }>('POST', `${blobPath}/upload`, { size, contentType });
+      if (envelope.data?.stored) {
+        return;
+      }
+      const upload = envelope.data?.upload;
+      if (!upload) {
+        await uploadAssetBlobThroughRegistry(blobPath, contentType, bytes);
+        return;
+      }
+
+      // Name only the origin in errors: the signed query string must not reach logs.
+      const storage = new URL(upload.url).origin;
+      let response: Response;
+      try {
+        response = await fetch(upload.url, {
+          method: 'PUT',
+          headers: upload.headers,
+          body: new Blob([new Uint8Array(bytes)] as unknown as BlobPart[]),
+        });
+      } catch (error) {
+        const cause = (error as { cause?: { code?: string; message?: string } } | undefined)?.cause;
+        throw new RegistryClientError(`Could not reach asset storage at ${storage}: ${cause?.code || cause?.message || 'network error'}.`);
+      }
       if (!response.ok) {
-        let code: string | undefined;
-        let message = `Blob upload failed (${response.status} ${response.statusText}).`;
-        const envelope = await readErrorEnvelope(response);
-        code = envelope?.error?.code;
-        message = envelope?.error?.message || message;
-        throw new RegistryClientError(message, { status: response.status, code });
+        const detail = (await response.text().catch(() => '')).slice(0, 300);
+        throw new RegistryClientError(
+          `Asset storage at ${storage} rejected the upload of blob "${hash}" (${response.status} ${response.statusText})${detail ? `: ${detail}` : ''}.`,
+          { status: response.status }
+        );
       }
+      await request('POST', `${blobPath}/complete`, { storageRef: upload.storageRef, size, contentType });
     },
     /** Download one blob's raw bytes by hash (follows any provider redirect). */
     async downloadAssetBlob(hash: string): Promise<Buffer> {