handoff-app 2.0.0-2 → 2.0.0-3

package/src/registry/auth/index.ts

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

package/src/registry/auth/installation.ts

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

package/src/registry/auth/password.ts

@@ -0,0 +1,46 @@
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const scryptAsync = promisify(scrypt);
+const PASSWORD_HASH_VERSION = 'scrypt-v1';
+const PASSWORD_KEY_LENGTH = 64;
+export const MINIMUM_PASSWORD_LENGTH = 12;
+export const MAXIMUM_PASSWORD_LENGTH = 1024;
+
+export type PasswordValidationResult = { valid: true } | { valid: false; error: string };
+
+export const validatePassword = (password: string): PasswordValidationResult => {
+  if (password.length < MINIMUM_PASSWORD_LENGTH) {
+    return { valid: false, error: `Password must be at least ${MINIMUM_PASSWORD_LENGTH} characters.` };
+  }
+  if (password.length > MAXIMUM_PASSWORD_LENGTH) {
+    return { valid: false, error: `Password must be at most ${MAXIMUM_PASSWORD_LENGTH} characters.` };
+  }
+  return { valid: true };
+};
+
+/** Versioned scrypt encoding: `scrypt-v1:<base64url salt>:<base64url derived key>`. */
+export const hashPassword = async (password: string): Promise<string> => {
+  const validation = validatePassword(password);
+  if ('error' in validation) throw new Error(validation.error);
+
+  const salt = randomBytes(16);
+  const derived = (await scryptAsync(password, salt, PASSWORD_KEY_LENGTH)) as Buffer;
+  return `${PASSWORD_HASH_VERSION}:${salt.toString('base64url')}:${derived.toString('base64url')}`;
+};
+
+export const verifyPassword = async (password: string, encoded: string | null | undefined): Promise<boolean> => {
+  if (!encoded || password.length > MAXIMUM_PASSWORD_LENGTH) return false;
+  const [version, saltText, hashText, ...rest] = encoded.split(':');
+  if (version !== PASSWORD_HASH_VERSION || !saltText || !hashText || rest.length) return false;
+
+  try {
+    const salt = Buffer.from(saltText, 'base64url');
+    const expected = Buffer.from(hashText, 'base64url');
+    if (salt.length !== 16 || expected.length !== PASSWORD_KEY_LENGTH) return false;
+    const actual = (await scryptAsync(password, salt, PASSWORD_KEY_LENGTH)) as Buffer;
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  } catch {
+    return false;
+  }
+};

package/src/registry/auth/rate-limits.ts

@@ -0,0 +1,84 @@
+import { and, eq, lt, sql } from 'drizzle-orm';
+import type { RegistryDatabase } from '../db/client';
+import { registryAuthRateLimits, type RegistryRateLimitBucket } from '../db/schema';
+import { hashSecret } from './crypto';
+
+export interface ConsumeAuthRateLimitInput {
+  bucket: RegistryRateLimitBucket;
+  identifier: string;
+  limit: number;
+  windowMs: number;
+  now?: Date;
+}
+
+export interface AuthRateLimitResult {
+  allowed: boolean;
+  attempts: number;
+  limit: number;
+  remaining: number;
+  resetsAt: Date;
+  retryAfterSeconds: number;
+}
+
+export const hashRateLimitIdentifier = (bucket: RegistryRateLimitBucket, identifier: string): string =>
+  hashSecret(`${bucket}:${identifier.trim().toLowerCase()}`);
+
+/** Atomic fixed-window counter shared by all registry instances. */
+export const consumeAuthRateLimit = async (db: RegistryDatabase, input: ConsumeAuthRateLimitInput): Promise<AuthRateLimitResult> => {
+  if (!Number.isInteger(input.limit) || input.limit < 1) throw new Error('Rate-limit limit must be a positive integer.');
+  if (!Number.isInteger(input.windowMs) || input.windowMs < 1) {
+    throw new Error('Rate-limit windowMs must be a positive integer.');
+  }
+
+  const now = input.now ?? new Date();
+  const windowStartedAt = new Date(Math.floor(now.getTime() / input.windowMs) * input.windowMs);
+  const resetsAt = new Date(windowStartedAt.getTime() + input.windowMs);
+  const identifierHash = hashRateLimitIdentifier(input.bucket, input.identifier);
+  const [counter] = await db
+    .insert(registryAuthRateLimits)
+    .values({
+      bucket: input.bucket,
+      identifierHash,
+      windowStartedAt,
+      attempts: 1,
+      expiresAt: resetsAt,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [registryAuthRateLimits.bucket, registryAuthRateLimits.identifierHash, registryAuthRateLimits.windowStartedAt],
+      set: {
+        attempts: sql`${registryAuthRateLimits.attempts} + 1`,
+        expiresAt: resetsAt,
+        updatedAt: now,
+      },
+    })
+    .returning({ attempts: registryAuthRateLimits.attempts });
+
+  const attempts = counter.attempts;
+  return {
+    allowed: attempts <= input.limit,
+    attempts,
+    limit: input.limit,
+    remaining: Math.max(0, input.limit - attempts),
+    resetsAt,
+    retryAfterSeconds: attempts > input.limit ? Math.max(1, Math.ceil((resetsAt.getTime() - now.getTime()) / 1000)) : 0,
+  };
+};
+
+export const clearAuthRateLimit = async (db: RegistryDatabase, bucket: RegistryRateLimitBucket, identifier: string): Promise<number> => {
+  const rows = await db
+    .delete(registryAuthRateLimits)
+    .where(
+      and(eq(registryAuthRateLimits.bucket, bucket), eq(registryAuthRateLimits.identifierHash, hashRateLimitIdentifier(bucket, identifier)))
+    )
+    .returning({ identifierHash: registryAuthRateLimits.identifierHash });
+  return rows.length;
+};
+
+export const purgeExpiredAuthRateLimits = async (db: RegistryDatabase, now = new Date()): Promise<number> => {
+  const rows = await db
+    .delete(registryAuthRateLimits)
+    .where(lt(registryAuthRateLimits.expiresAt, now))
+    .returning({ identifierHash: registryAuthRateLimits.identifierHash });
+  return rows.length;
+};

package/src/registry/auth/types.ts

@@ -0,0 +1,34 @@
+import type { RegistryAccessScope, RegistryUserRole, RegistryUserStatus } from '../db/schema';
+
+export type { RegistryAccessScope, RegistryUserRole, RegistryUserStatus };
+
+export const REGISTRY_READ_SCOPE = 'registry:read' as const;
+export const REGISTRY_WRITE_SCOPE = 'registry:write' as const;
+
+export interface RegistryUser {
+  id: string;
+  email: string;
+  name: string | null;
+  image: string | null;
+  role: RegistryUserRole;
+  status: RegistryUserStatus;
+  emailVerifiedAt: Date | null;
+  authVersion: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface RegistryPrincipal {
+  tokenId: string;
+  userId: string;
+  email: string;
+  name: string | null;
+  role: RegistryUserRole;
+  scopes: RegistryAccessScope[];
+}
+
+export const scopesForRegistryRole = (role: RegistryUserRole): RegistryAccessScope[] =>
+  role === 'admin' ? [REGISTRY_READ_SCOPE, REGISTRY_WRITE_SCOPE] : [REGISTRY_READ_SCOPE];
+
+export const registryPrincipalHasScope = (principal: RegistryPrincipal, scope: RegistryAccessScope): boolean =>
+  principal.scopes.includes(scope);

package/src/registry/auth/user-record.ts

@@ -0,0 +1,25 @@
+import type { RegistryUser } from './types';
+
+export const toRegistryUser = (row: {
+  id: string;
+  email: string;
+  name: string | null;
+  image: string | null;
+  role: RegistryUser['role'];
+  status: RegistryUser['status'];
+  emailVerifiedAt: Date | null;
+  authVersion: number;
+  createdAt: Date;
+  updatedAt: Date;
+}): RegistryUser => ({
+  id: row.id,
+  email: row.email,
+  name: row.name,
+  image: row.image,
+  role: row.role,
+  status: row.status,
+  emailVerifiedAt: row.emailVerifiedAt,
+  authVersion: row.authVersion,
+  createdAt: row.createdAt,
+  updatedAt: row.updatedAt,
+});

package/src/registry/auth/users.ts

@@ -0,0 +1,145 @@
+import { and, count, eq, sql } from 'drizzle-orm';
+import type { RegistryDatabase } from '../db/client';
+import { registryUsers, type RegistryUserRole } from '../db/schema';
+import { revokeAllRegistryAccessTokens } from './access-tokens';
+import { acquireRegistryAdvisoryLock, REGISTRY_ADMIN_LOCK_ID, withRegistryTransaction } from './database';
+import { normalizeEmail } from './crypto';
+import { verifyPassword } from './password';
+import type { RegistryUser, RegistryUserStatus } from './types';
+import { toRegistryUser } from './user-record';
+import { validateRegistryDisplayName, validateRegistryImageUrl } from './validation';
+
+const DUMMY_PASSWORD_HASH =
+  'scrypt-v1:AAAAAAAAAAAAAAAAAAAAAA:yK99vlYIaV57oeErq8gHqx18DxRfiUoHwETrTFUjt5JasWeMsu62stPgY-fO0TUeUc6uAu1hge_vuSQY15vvuQ';
+
+export type RegistryUserMutationResult =
+  | { ok: true; user: RegistryUser }
+  | {
+      ok: false;
+      reason: 'not_found' | 'invalid_name' | 'invalid_image' | 'invalid_role' | 'last_admin' | 'self_deactivation' | 'invalid_status';
+    };
+
+export const getRegistryUserById = async (db: RegistryDatabase, userId: string): Promise<RegistryUser | null> => {
+  const [row] = await db.select().from(registryUsers).where(eq(registryUsers.id, userId)).limit(1);
+  return row ? toRegistryUser(row) : null;
+};
+
+export const listRegistryUsers = async (db: RegistryDatabase): Promise<RegistryUser[]> => {
+  const rows = await db.select().from(registryUsers).orderBy(registryUsers.createdAt);
+  return rows.map(toRegistryUser);
+};
+
+/** Credentials authentication is intentionally enumeration-safe: all failures return null. */
+export const authenticateRegistryCredentials = async (
+  db: RegistryDatabase,
+  email: string,
+  password: string
+): Promise<RegistryUser | null> => {
+  const normalizedEmail = normalizeEmail(email);
+  const [row] = await db.select().from(registryUsers).where(eq(registryUsers.email, normalizedEmail)).limit(1);
+  const passwordMatches = await verifyPassword(password, row?.passwordHash ?? DUMMY_PASSWORD_HASH);
+  return row && row.status === 'active' && row.passwordHash && passwordMatches ? toRegistryUser(row) : null;
+};
+
+export const updateRegistryUserProfile = async (
+  db: RegistryDatabase,
+  input: { userId: string; name: string; image?: string | null; now?: Date }
+): Promise<RegistryUserMutationResult> => {
+  const name = validateRegistryDisplayName(input.name);
+  if (!name) return { ok: false, reason: 'invalid_name' };
+  const image = validateRegistryImageUrl(input.image);
+  if (image === false) return { ok: false, reason: 'invalid_image' };
+
+  const [row] = await db
+    .update(registryUsers)
+    .set({ name, image, updatedAt: input.now ?? new Date() })
+    .where(eq(registryUsers.id, input.userId))
+    .returning();
+  return row ? { ok: true, user: toRegistryUser(row) } : { ok: false, reason: 'not_found' };
+};
+
+export const updateRegistryUserRole = async (
+  db: RegistryDatabase,
+  input: { userId: string; role: RegistryUserRole; now?: Date }
+): Promise<RegistryUserMutationResult> => {
+  if (input.role !== 'admin' && input.role !== 'member') return { ok: false, reason: 'invalid_role' };
+  return withRegistryTransaction(db, async (tx) => {
+    await acquireRegistryAdvisoryLock(tx, REGISTRY_ADMIN_LOCK_ID);
+    const [target] = await tx.select().from(registryUsers).where(eq(registryUsers.id, input.userId)).limit(1);
+    if (!target) return { ok: false, reason: 'not_found' };
+    if (target.role === input.role) return { ok: true, user: toRegistryUser(target) };
+
+    if (target.role === 'admin' && target.status === 'active' && input.role === 'member') {
+      const [{ value }] = await tx
+        .select({ value: count() })
+        .from(registryUsers)
+        .where(and(eq(registryUsers.role, 'admin'), eq(registryUsers.status, 'active')));
+      if (Number(value) <= 1) return { ok: false, reason: 'last_admin' };
+    }
+
+    const now = input.now ?? new Date();
+    const [row] = await tx
+      .update(registryUsers)
+      .set({
+        role: input.role,
+        authVersion: sql`${registryUsers.authVersion} + 1`,
+        updatedAt: now,
+      })
+      .where(eq(registryUsers.id, input.userId))
+      .returning();
+    if (target.role === 'admin' && input.role === 'member') {
+      await revokeAllRegistryAccessTokens(tx, input.userId, now);
+    }
+    return { ok: true, user: toRegistryUser(row) };
+  });
+};
+
+export const setRegistryUserStatus = async (
+  db: RegistryDatabase,
+  input: {
+    userId: string;
+    status: Extract<RegistryUserStatus, 'active' | 'deactivated'>;
+    actorUserId?: string;
+    now?: Date;
+  }
+): Promise<RegistryUserMutationResult> => {
+  if (input.status !== 'active' && input.status !== 'deactivated') {
+    return { ok: false, reason: 'invalid_status' };
+  }
+  if (input.status === 'deactivated' && input.actorUserId === input.userId) {
+    return { ok: false, reason: 'self_deactivation' };
+  }
+
+  return withRegistryTransaction(db, async (tx) => {
+    await acquireRegistryAdvisoryLock(tx, REGISTRY_ADMIN_LOCK_ID);
+    const [target] = await tx.select().from(registryUsers).where(eq(registryUsers.id, input.userId)).limit(1);
+    if (!target) return { ok: false, reason: 'not_found' };
+    if (target.status === input.status) return { ok: true, user: toRegistryUser(target) };
+    if (input.status === 'active' && target.status === 'invited') {
+      return { ok: false, reason: 'invalid_status' };
+    }
+
+    if (target.role === 'admin' && target.status === 'active' && input.status === 'deactivated') {
+      const [{ value }] = await tx
+        .select({ value: count() })
+        .from(registryUsers)
+        .where(and(eq(registryUsers.role, 'admin'), eq(registryUsers.status, 'active')));
+      if (Number(value) <= 1) return { ok: false, reason: 'last_admin' };
+    }
+
+    const now = input.now ?? new Date();
+    const [row] = await tx
+      .update(registryUsers)
+      .set({
+        status: input.status,
+        authVersion: sql`${registryUsers.authVersion} + 1`,
+        updatedAt: now,
+      })
+      .where(eq(registryUsers.id, input.userId))
+      .returning();
+    if (input.status === 'deactivated') {
+      await revokeAllRegistryAccessTokens(tx, input.userId, now);
+    }
+    return { ok: true, user: toRegistryUser(row) };
+  });
+};

package/src/registry/auth/validation.ts

@@ -0,0 +1,24 @@
+import { normalizeEmail } from './crypto';
+
+const SIMPLE_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export const validateRegistryEmail = (email: string): string | null => {
+  const normalized = normalizeEmail(email);
+  return normalized.length <= 320 && SIMPLE_EMAIL_PATTERN.test(normalized) ? normalized : null;
+};
+
+export const validateRegistryDisplayName = (name: string): string | null => {
+  const normalized = name.trim();
+  return normalized && normalized.length <= 120 ? normalized : null;
+};
+
+export const validateRegistryImageUrl = (image: string | null | undefined): string | null | false => {
+  const normalized = image?.trim();
+  if (!normalized) return null;
+  try {
+    const parsed = new URL(normalized);
+    return parsed.protocol === 'https:' && normalized.length <= 2048 ? normalized : false;
+  } catch {
+    return false;
+  }
+};

package/src/registry/checkout/assets.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 assets (403). Authorize a token with registry:read access.`;
     default:
       return error.message;
   }
@@ -55,7 +57,7 @@ const wouldChange = (absolutePath: string, bytes: Buffer): boolean => {
  * Recreates workspace asset files; prompts before overwriting changed local files unless `--force`.
  */
 export const checkoutAssets = async (handoff: Handoff, collection?: string): Promise<void> => {
-  const connection = resolveConnectionOrThrow(handoff);
+  const connection = await resolveConnectionOrThrow(handoff);
   if (collection && !isAssetCollection(collection)) {
     throw new CheckoutError(`Unknown asset collection "${collection}". Supported collections: ${ASSET_COLLECTIONS.join(', ')}.`);
   }