handoff-app 2.0.0-4 → 2.0.0-6

package/dist/registry/auth/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setRegistryUserStatus = exports.updateRegistryUserRole = exports.updateRegistryUserProfile = exports.authenticateRegistryCredentials = exports.listRegistryUsers = exports.getRegistryUserById = exports.hashRateLimitIdentifier = exports.purgeExpiredAuthRateLimits = exports.clearAuthRateLimit = exports.consumeAuthRateLimit = exports.MAXIMUM_PASSWORD_LENGTH = exports.MINIMUM_PASSWORD_LENGTH = exports.validatePassword = exports.verifyPassword = exports.hashPassword = exports.REGISTRY_INSTALLATION_ID = exports.REGISTRY_AUTH_SCHEMA_VERSION = exports.installRegistry = exports.getRegistryInstallationState = exports.getRegistryInstallation = exports.DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS = exports.DEVICE_AUTHORIZATION_LIFETIME_SECONDS = exports.normalizeRegistryUserCode = exports.generateRegistryUserCode = exports.purgeExpiredRegistryDeviceAuthorizations = exports.exchangeRegistryDeviceAuthorization = exports.denyRegistryDeviceAuthorization = exports.approveRegistryDeviceAuthorization = exports.createRegistryDeviceAuthorization = exports.buildGravatarUrl = exports.secretHashMatches = exports.normalizeEmail = exports.hashSecret = exports.createOpaqueSecret = exports.PASSWORD_RESET_LIFETIME_MS = exports.INVITATION_LIFETIME_MS = exports.resetPassword = exports.createPasswordReset = exports.acceptUserInvitation = exports.resendUserInvitation = exports.createUserInvitation = exports.registryRoleAllowsScopes = exports.normalizeRegistryScopes = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = void 0;
-exports.validateRegistryImageUrl = exports.validateRegistryEmail = exports.validateRegistryDisplayName = exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = void 0;
+exports.getRegistryUserById = exports.hashRateLimitIdentifier = exports.purgeExpiredAuthRateLimits = exports.clearAuthRateLimit = exports.consumeAuthRateLimit = exports.MAXIMUM_PASSWORD_LENGTH = exports.MINIMUM_PASSWORD_LENGTH = exports.validatePassword = exports.verifyPassword = exports.hashPassword = exports.REGISTRY_INSTALLATION_ID = exports.REGISTRY_AUTH_SCHEMA_VERSION = exports.installRegistry = exports.getRegistryInstallationState = exports.getRegistryInstallation = exports.DEVICE_AUTHORIZATION_POLL_INTERVAL_SECONDS = exports.DEVICE_AUTHORIZATION_LIFETIME_SECONDS = exports.normalizeRegistryUserCode = exports.generateRegistryUserCode = exports.purgeExpiredRegistryDeviceAuthorizations = exports.exchangeRegistryDeviceAuthorization = exports.denyRegistryDeviceAuthorization = exports.approveRegistryDeviceAuthorization = exports.createRegistryDeviceAuthorization = exports.SYNC_SECRET_ENV = exports.resolveRegistrySyncSecret = exports.authenticateRegistrySyncSecret = exports.buildGravatarUrl = exports.secretHashMatches = exports.normalizeEmail = exports.hashSecret = exports.createOpaqueSecret = exports.PASSWORD_RESET_LIFETIME_MS = exports.INVITATION_LIFETIME_MS = exports.resetPassword = exports.createPasswordReset = exports.acceptUserInvitation = exports.resendUserInvitation = exports.createUserInvitation = exports.registryRoleAllowsScopes = exports.resolveRegistryScope = exports.expandRegistryScopes = exports.normalizeRegistryScopes = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = void 0;
+exports.validateRegistryImageUrl = exports.validateRegistryEmail = exports.validateRegistryDisplayName = exports.isTransmittableCredential = exports.isRegistryTokenPrincipal = exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = exports.setRegistryUserStatus = exports.updateRegistryUserRole = exports.updateRegistryUserProfile = exports.authenticateRegistryCredentials = exports.listRegistryUsers = void 0;
 var access_tokens_1 = require("./access-tokens");
 Object.defineProperty(exports, "createRegistryAccessToken", { enumerable: true, get: function () { return access_tokens_1.createRegistryAccessToken; } });
 Object.defineProperty(exports, "listRegistryAccessTokens", { enumerable: true, get: function () { return access_tokens_1.listRegistryAccessTokens; } });
@@ -11,6 +11,8 @@ Object.defineProperty(exports, "authenticateRegistryAccessToken", { enumerable:
 Object.defineProperty(exports, "formatRegistryAccessToken", { enumerable: true, get: function () { return access_tokens_1.formatRegistryAccessToken; } });
 Object.defineProperty(exports, "parseRegistryAccessToken", { enumerable: true, get: function () { return access_tokens_1.parseRegistryAccessToken; } });
 Object.defineProperty(exports, "normalizeRegistryScopes", { enumerable: true, get: function () { return access_tokens_1.normalizeRegistryScopes; } });
+Object.defineProperty(exports, "expandRegistryScopes", { enumerable: true, get: function () { return access_tokens_1.expandRegistryScopes; } });
+Object.defineProperty(exports, "resolveRegistryScope", { enumerable: true, get: function () { return access_tokens_1.resolveRegistryScope; } });
 Object.defineProperty(exports, "registryRoleAllowsScopes", { enumerable: true, get: function () { return access_tokens_1.registryRoleAllowsScopes; } });
 var action_tokens_1 = require("./action-tokens");
 Object.defineProperty(exports, "createUserInvitation", { enumerable: true, get: function () { return action_tokens_1.createUserInvitation; } });
@@ -27,6 +29,10 @@ Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: functi
 Object.defineProperty(exports, "secretHashMatches", { enumerable: true, get: function () { return crypto_1.secretHashMatches; } });
 var gravatar_1 = require("./gravatar");
 Object.defineProperty(exports, "buildGravatarUrl", { enumerable: true, get: function () { return gravatar_1.buildGravatarUrl; } });
+var sync_secret_1 = require("./sync-secret");
+Object.defineProperty(exports, "authenticateRegistrySyncSecret", { enumerable: true, get: function () { return sync_secret_1.authenticateRegistrySyncSecret; } });
+Object.defineProperty(exports, "resolveRegistrySyncSecret", { enumerable: true, get: function () { return sync_secret_1.resolveRegistrySyncSecret; } });
+Object.defineProperty(exports, "SYNC_SECRET_ENV", { enumerable: true, get: function () { return sync_secret_1.SYNC_SECRET_ENV; } });
 var device_authorizations_1 = require("./device-authorizations");
 Object.defineProperty(exports, "createRegistryDeviceAuthorization", { enumerable: true, get: function () { return device_authorizations_1.createRegistryDeviceAuthorization; } });
 Object.defineProperty(exports, "approveRegistryDeviceAuthorization", { enumerable: true, get: function () { return device_authorizations_1.approveRegistryDeviceAuthorization; } });
@@ -66,7 +72,9 @@ Object.defineProperty(exports, "REGISTRY_READ_SCOPE", { enumerable: true, get: f
 Object.defineProperty(exports, "REGISTRY_WRITE_SCOPE", { enumerable: true, get: function () { return types_1.REGISTRY_WRITE_SCOPE; } });
 Object.defineProperty(exports, "scopesForRegistryRole", { enumerable: true, get: function () { return types_1.scopesForRegistryRole; } });
 Object.defineProperty(exports, "registryPrincipalHasScope", { enumerable: true, get: function () { return types_1.registryPrincipalHasScope; } });
+Object.defineProperty(exports, "isRegistryTokenPrincipal", { enumerable: true, get: function () { return types_1.isRegistryTokenPrincipal; } });
 var validation_1 = require("./validation");
+Object.defineProperty(exports, "isTransmittableCredential", { enumerable: true, get: function () { return validation_1.isTransmittableCredential; } });
 Object.defineProperty(exports, "validateRegistryDisplayName", { enumerable: true, get: function () { return validation_1.validateRegistryDisplayName; } });
 Object.defineProperty(exports, "validateRegistryEmail", { enumerable: true, get: function () { return validation_1.validateRegistryEmail; } });
 Object.defineProperty(exports, "validateRegistryImageUrl", { enumerable: true, get: function () { return validation_1.validateRegistryImageUrl; } });

package/dist/registry/auth/sync-secret.d.ts

@@ -0,0 +1,27 @@
+import { type RegistrySyncSecretPrincipal } from './types';
+/**
+ * Deployment-wide sync secret.
+ *
+ * The documented API describes a raw secret carried as a bearer credential for CI-style sync, which is
+ * what this module resolves. It is the credential itself, so presenting it issues no token and creates
+ * no session: no owner, no expiry, no usage trail, and unsetting the variable is the only way to
+ * withdraw it. User-issued `hnd_*` tokens stay the canonical path, and this is off whenever the
+ * variable is absent.
+ */
+/** Env var holding the raw secret. Read per call so unsetting it takes effect on restart alone. */
+export declare const SYNC_SECRET_ENV = "HANDOFF_SYNC_SECRET";
+/**
+ * The configured secret, or `''` when this method is unavailable. Never returns a value that could not
+ * be presented in every accepted header, or one using the access-token prefix: credentials are routed
+ * by shape, so such a secret would be permanently unreachable. Both cases warn instead.
+ */
+export declare const resolveRegistrySyncSecret: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * Resolve a raw credential into a sync-secret principal, granting registry read and write.
+ *
+ * The empty checks have to come first: `hashSecret('')` is a valid digest that matches itself, so
+ * hashing up front would authenticate an empty credential on any deployment that leaves
+ * {@link SYNC_SECRET_ENV} unset. The comparison runs over fixed-length digests, so it is constant time
+ * and leaks no length.
+ */
+export declare const authenticateRegistrySyncSecret: (credential: string, env?: NodeJS.ProcessEnv) => RegistrySyncSecretPrincipal | null;

package/dist/registry/auth/sync-secret.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authenticateRegistrySyncSecret = exports.resolveRegistrySyncSecret = exports.SYNC_SECRET_ENV = void 0;
+const crypto_1 = require("./crypto");
+const types_1 = require("./types");
+const validation_1 = require("./validation");
+/**
+ * Deployment-wide sync secret.
+ *
+ * The documented API describes a raw secret carried as a bearer credential for CI-style sync, which is
+ * what this module resolves. It is the credential itself, so presenting it issues no token and creates
+ * no session: no owner, no expiry, no usage trail, and unsetting the variable is the only way to
+ * withdraw it. User-issued `hnd_*` tokens stay the canonical path, and this is off whenever the
+ * variable is absent.
+ */
+/** Env var holding the raw secret. Read per call so unsetting it takes effect on restart alone. */
+exports.SYNC_SECRET_ENV = 'HANDOFF_SYNC_SECRET';
+/** Prefix reserved for issued access tokens; see `formatRegistryAccessToken`. */
+const RESERVED_TOKEN_PREFIX = 'hnd_';
+/** Reasons already reported, so a misconfigured deployment warns once rather than once per request. */
+const warned = new Set();
+const warnOnce = (reason, detail) => {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`${exports.SYNC_SECRET_ENV} is ignored: ${detail}`);
+};
+/**
+ * The configured secret, or `''` when this method is unavailable. Never returns a value that could not
+ * be presented in every accepted header, or one using the access-token prefix: credentials are routed
+ * by shape, so such a secret would be permanently unreachable. Both cases warn instead.
+ */
+const resolveRegistrySyncSecret = (env = process.env) => {
+    var _a, _b;
+    const configured = (_b = (_a = env[exports.SYNC_SECRET_ENV]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+    if (!configured)
+        return '';
+    if (!(0, validation_1.isTransmittableCredential)(configured)) {
+        warnOnce('untransmittable', 'the value must be printable ASCII with no spaces or commas to be sent in a request header.');
+        return '';
+    }
+    if (configured.startsWith(RESERVED_TOKEN_PREFIX)) {
+        warnOnce('token_shaped', `the value starts with the \`${RESERVED_TOKEN_PREFIX}\` prefix reserved for issued access tokens.`);
+        return '';
+    }
+    return configured;
+};
+exports.resolveRegistrySyncSecret = resolveRegistrySyncSecret;
+/**
+ * Resolve a raw credential into a sync-secret principal, granting registry read and write.
+ *
+ * The empty checks have to come first: `hashSecret('')` is a valid digest that matches itself, so
+ * hashing up front would authenticate an empty credential on any deployment that leaves
+ * {@link SYNC_SECRET_ENV} unset. The comparison runs over fixed-length digests, so it is constant time
+ * and leaks no length.
+ */
+const authenticateRegistrySyncSecret = (credential, env = process.env) => {
+    const configured = (0, exports.resolveRegistrySyncSecret)(env);
+    if (!configured || !credential)
+        return null;
+    if (!(0, crypto_1.secretHashMatches)(credential, (0, crypto_1.hashSecret)(configured)))
+        return null;
+    return { kind: 'sync_secret', scopes: [types_1.REGISTRY_READ_SCOPE, types_1.REGISTRY_WRITE_SCOPE] };
+};
+exports.authenticateRegistrySyncSecret = authenticateRegistrySyncSecret;

package/dist/registry/auth/types.d.ts

@@ -14,7 +14,9 @@ export interface RegistryUser {
     createdAt: Date;
     updatedAt: Date;
 }
-export interface RegistryPrincipal {
+/** A request authenticated by a user-issued, revocable `hnd_*` access token. */
+export interface RegistryTokenPrincipal {
+    kind: 'access_token';
     tokenId: string;
     userId: string;
     email: string;
@@ -22,5 +24,22 @@ export interface RegistryPrincipal {
     role: RegistryUserRole;
     scopes: RegistryAccessScope[];
 }
+/**
+ * A request authenticated by the deployment-wide `HANDOFF_SYNC_SECRET`. The secret is the credential
+ * itself, so there is no token row and no owner, only the scopes it grants. Nothing derived from the
+ * secret lives here — no hash, no label: response bodies are serialized verbatim, so any field added
+ * to this principal reaches a client as written.
+ */
+export interface RegistrySyncSecretPrincipal {
+    kind: 'sync_secret';
+    scopes: RegistryAccessScope[];
+}
+/**
+ * Whoever a registry request is acting as. Discriminated on `kind` because identity fields exist only
+ * for token principals, and both tsconfigs run without `strictNullChecks`: one interface with nullable
+ * fields would let `principal.userId` compile against a secret-authenticated request.
+ */
+export type RegistryPrincipal = RegistryTokenPrincipal | RegistrySyncSecretPrincipal;
+export declare const isRegistryTokenPrincipal: (principal: RegistryPrincipal) => principal is RegistryTokenPrincipal;
 export declare const scopesForRegistryRole: (role: RegistryUserRole) => RegistryAccessScope[];
 export declare const registryPrincipalHasScope: (principal: RegistryPrincipal, scope: RegistryAccessScope) => boolean;

package/dist/registry/auth/types.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = void 0;
+exports.registryPrincipalHasScope = exports.scopesForRegistryRole = exports.isRegistryTokenPrincipal = exports.REGISTRY_WRITE_SCOPE = exports.REGISTRY_READ_SCOPE = void 0;
 exports.REGISTRY_READ_SCOPE = 'registry:read';
 exports.REGISTRY_WRITE_SCOPE = 'registry:write';
+const isRegistryTokenPrincipal = (principal) => principal.kind === 'access_token';
+exports.isRegistryTokenPrincipal = isRegistryTokenPrincipal;
 const scopesForRegistryRole = (role) => role === 'admin' ? [exports.REGISTRY_READ_SCOPE, exports.REGISTRY_WRITE_SCOPE] : [exports.REGISTRY_READ_SCOPE];
 exports.scopesForRegistryRole = scopesForRegistryRole;
 const registryPrincipalHasScope = (principal, scope) => principal.scopes.includes(scope);

package/dist/registry/auth/validation.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whether a credential can be presented unambiguously in a request header. One rule shared by the
+ * authentication headers and by whatever a deployment configures as a secret, so a value is never
+ * accepted through one carrier and rejected by the other.
+ *
+ * Whitespace is out so nothing can be trimmed away or smuggled past a parser, and the comma with it:
+ * repeats of a header Node does not de-duplicate arrive joined with `, `, and no accepted credential
+ * may look like that. Non-ASCII bytes are out too, since their header encoding is ambiguous and a
+ * credential has to reproduce exactly.
+ */
+export declare const isTransmittableCredential: (value: string) => boolean;
 export declare const validateRegistryEmail: (email: string) => string | null;
 export declare const validateRegistryDisplayName: (name: string) => string | null;
 export declare const validateRegistryImageUrl: (image: string | null | undefined) => string | null | false;

package/dist/registry/auth/validation.js

@@ -1,8 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateRegistryImageUrl = exports.validateRegistryDisplayName = exports.validateRegistryEmail = void 0;
+exports.validateRegistryImageUrl = exports.validateRegistryDisplayName = exports.validateRegistryEmail = exports.isTransmittableCredential = void 0;
 const crypto_1 = require("./crypto");
 const SIMPLE_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Printable ASCII (`!` through `~`) except the comma: HTTP's `VCHAR`, minus the character Node joins
+ * duplicate header values with.
+ */
+const TRANSMITTABLE_CREDENTIAL_PATTERN = /^[\x21-\x2B\x2D-\x7E]+$/;
+/**
+ * Whether a credential can be presented unambiguously in a request header. One rule shared by the
+ * authentication headers and by whatever a deployment configures as a secret, so a value is never
+ * accepted through one carrier and rejected by the other.
+ *
+ * Whitespace is out so nothing can be trimmed away or smuggled past a parser, and the comma with it:
+ * repeats of a header Node does not de-duplicate arrive joined with `, `, and no accepted credential
+ * may look like that. Non-ASCII bytes are out too, since their header encoding is ambiguous and a
+ * credential has to reproduce exactly.
+ */
+const isTransmittableCredential = (value) => TRANSMITTABLE_CREDENTIAL_PATTERN.test(value);
+exports.isTransmittableCredential = isTransmittableCredential;
 const validateRegistryEmail = (email) => {
     const normalized = (0, crypto_1.normalizeEmail)(email);
     return normalized.length <= 320 && SIMPLE_EMAIL_PATTERN.test(normalized) ? normalized : null;

package/dist/registry/checkout/assets.d.ts

@@ -13,4 +13,4 @@ import Handoff from '../../index';
  * Checkout all published asset collections, or a single collection when `collection` is given.
  * Recreates workspace asset files; prompts before overwriting changed local files unless `--force`.
  */
-export declare const checkoutAssets: (handoff: Handoff, collection?: string) => Promise<void>;
+export declare const checkoutAssets: (handoff: Handoff, selection?: string[]) => Promise<void>;

package/dist/registry/checkout/assets.js

@@ -84,15 +84,19 @@ const wouldChange = (absolutePath, bytes) => {
  * Checkout all published asset collections, or a single collection when `collection` is given.
  * Recreates workspace asset files; prompts before overwriting changed local files unless `--force`.
  */
-const checkoutAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0, function* () {
+const checkoutAssets = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
-    if (collection && !(0, sets_1.isAssetCollection)(collection)) {
-        throw new index_1.CheckoutError(`Unknown asset collection "${collection}". Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
+    const unsupported = (_a = selection === null || selection === void 0 ? void 0 : selection.filter((name) => !(0, sets_1.isAssetCollection)(name))) !== null && _a !== void 0 ? _a : [];
+    if (unsupported.length > 0) {
+        throw new index_1.CheckoutError(`Unknown asset collection ${unsupported.map((name) => `"${name}"`).join(', ')}. ` +
+            `Supported collections: ${sets_1.ASSET_COLLECTIONS.join(', ')}.`);
     }
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    // A named selection is trusted as-is; only a full checkout has to ask the registry what exists.
     let collections;
-    if (collection) {
-        collections = [collection];
+    if (selection) {
+        collections = selection;
     }
     else {
         const summaries = yield client.listAssetCollections();
@@ -123,16 +127,27 @@ const checkoutAssets = (handoff, collection) => __awaiter(void 0, void 0, void 0
     // Download each referenced blob once (dedup by hash), then resolve every asset to a physical write.
     const blobCache = new Map();
     const writes = [];
+    const plannedPaths = [];
     for (const payload of payloads) {
         for (const asset of payload.assets) {
+            const absolutePath = (0, layout_1.resolveAssetPhysicalPath)(asset.path, roots);
+            plannedPaths.push(absolutePath);
+            // A dry run reports paths only, so there is no reason to pull the bytes down.
+            if (handoff.dryRun) {
+                continue;
+            }
             let bytes = blobCache.get(asset.contentHash);
             if (!bytes) {
                 bytes = yield client.downloadAssetBlob(asset.contentHash);
                 blobCache.set(asset.contentHash, bytes);
             }
-            writes.push({ absolutePath: (0, layout_1.resolveAssetPhysicalPath)(asset.path, roots), bytes });
+            writes.push({ absolutePath, bytes });
         }
     }
+    if (handoff.dryRun) {
+        (0, index_1.reportPlannedWrites)(handoff, 'asset collections', plannedPaths, plannedPaths.filter((target) => fs_extra_1.default.existsSync(target)));
+        return;
+    }
     const existingChanges = writes.filter((write) => fs_extra_1.default.existsSync(write.absolutePath) && wouldChange(write.absolutePath, write.bytes));
     if (existingChanges.length > 0 && !handoff.force) {
         const proceed = yield p.confirm({

package/dist/registry/checkout/index.d.ts

@@ -24,6 +24,13 @@ export declare class CheckoutError extends Error {
  * actionable {@link CheckoutError} naming the exact misconfiguration.
  */
 export declare const resolveConnectionOrThrow: (handoff: Handoff) => Promise<import("../connection").ResolvedRegistryConnection>;
+/**
+ * Report the files a checkout would create or replace, and write nothing. Called once the real
+ * checkout has computed its targets but before it prompts or writes, so a dry run exercises the same
+ * path resolution and conflict detection as the real thing. Shared by the entity, page, token and
+ * asset checkout paths.
+ */
+export declare const reportPlannedWrites: (handoff: Handoff, label: string, targets: string[], conflicts: string[]) => void;
 /**
  * Checkout a single component, pattern, or page from the connected registry into this workspace.
  * Overwriting existing local files requires `--force` or an interactive confirmation.
@@ -35,4 +42,4 @@ export declare const checkoutEntity: (handoff: Handoff, kind: TransferEntityKind
  * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
  * prompting is per entity (skipped under `--force`).
  */
-export declare const checkoutEntities: (handoff: Handoff, kind: TransferEntityKind) => Promise<void>;
+export declare const checkoutEntities: (handoff: Handoff, kind: TransferEntityKind, ids?: string[]) => Promise<void>;

package/dist/registry/checkout/index.js

@@ -60,7 +60,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkoutEntities = exports.checkoutEntity = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
+exports.checkoutEntities = exports.checkoutEntity = exports.reportPlannedWrites = exports.resolveConnectionOrThrow = exports.CheckoutError = void 0;
 const p = __importStar(require("@clack/prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -70,6 +70,7 @@ const logger_1 = require("../../utils/logger");
 const client_1 = require("../client");
 const connection_1 = require("../connection");
 const path_2 = require("../path");
+const selection_1 = require("../selection");
 /** A connected-workspace configuration or precondition failure surfaced to the CLI. */
 class CheckoutError extends Error {
     constructor(message) {
@@ -568,6 +569,21 @@ const writeSourceFile = (targetDir, file) => __awaiter(void 0, void 0, void 0, f
     yield fs_extra_1.default.writeFile(absolutePath, file.content, 'utf8');
     return absolutePath;
 });
+/**
+ * Report the files a checkout would create or replace, and write nothing. Called once the real
+ * checkout has computed its targets but before it prompts or writes, so a dry run exercises the same
+ * path resolution and conflict detection as the real thing. Shared by the entity, page, token and
+ * asset checkout paths.
+ */
+const reportPlannedWrites = (handoff, label, targets, conflicts) => {
+    const conflicting = new Set(conflicts);
+    logger_1.Logger.info(`Would checkout ${label} (${targets.length} file(s)):`);
+    for (const target of targets) {
+        const relative = path_1.default.relative(handoff.workingPath, target) || target;
+        logger_1.Logger.info(`  ${conflicting.has(target) ? 'overwrite' : 'create'}: ${relative}`);
+    }
+};
+exports.reportPlannedWrites = reportPlannedWrites;
 /**
  * Checkout a page: write its single verbatim `.md` (transfer path `<id>.md`) back under
  * `<workingPath>/pages/`. Unlike components/patterns there is no declaration to synthesize — the
@@ -583,6 +599,10 @@ const checkoutPage = (handoff, id, payload) => __awaiter(void 0, void 0, void 0,
         return target;
     });
     const conflicts = targets.filter((file) => fs_extra_1.default.existsSync(file));
+    if (handoff.dryRun) {
+        (0, exports.reportPlannedWrites)(handoff, `page "${id}"`, targets, conflicts);
+        return;
+    }
     if (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of page "${id}" cancelled; no files were written.`);
         return;
@@ -633,7 +653,13 @@ const checkoutSingle = (handoff, kind, id, client, registryUrl) => __awaiter(voi
         }
         return { file, absolutePath };
     });
-    const conflicts = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath].filter((file) => fs_extra_1.default.existsSync(file));
+    const plannedWrites = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath];
+    const conflicts = plannedWrites.filter((file) => fs_extra_1.default.existsSync(file));
+    if (handoff.dryRun) {
+        // Returning null also skips `registerCheckedOut`, so a dry run never edits handoff.config either.
+        (0, exports.reportPlannedWrites)(handoff, `${kind} "${id}"`, plannedWrites, conflicts);
+        return null;
+    }
     if (!(yield confirmOverwrite(handoff, conflicts))) {
         logger_1.Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
         return null;
@@ -694,7 +720,7 @@ exports.checkoutEntity = checkoutEntity;
  * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
  * prompting is per entity (skipped under `--force`).
  */
-const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, function* () {
+const checkoutEntities = (handoff, kind, ids) => __awaiter(void 0, void 0, void 0, function* () {
     const connection = yield (0, exports.resolveConnectionOrThrow)(handoff);
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
     let summaries;
@@ -707,14 +733,20 @@ const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fu
         }
         throw error;
     }
-    if (summaries.length === 0) {
+    const published = summaries.map((summary) => summary.id);
+    const { selected: targets, unknown } = (0, selection_1.selectIds)(published, ids);
+    if (unknown.length > 0) {
+        throw new CheckoutError(`No ${kind} named ${unknown.map((id) => `"${id}"`).join(', ')} is published in the registry. ` +
+            `Published ${kind}s: ${published.join(', ') || '(none)'}.`);
+    }
+    if (targets.length === 0) {
         logger_1.Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
         return;
     }
     let checkedOut = 0;
     const failed = [];
     const targetDirs = [];
-    for (const { id } of summaries) {
+    for (const id of targets) {
         try {
             const targetDir = yield checkoutSingle(handoff, kind, id, client, connection.url);
             if (targetDir) {
@@ -728,7 +760,8 @@ const checkoutEntities = (handoff, kind) => __awaiter(void 0, void 0, void 0, fu
     }
     // Register everything checked out in one pass, so the config is edited (and confirmed) once.
     yield registerCheckedOut(handoff, kind, targetDirs);
-    logger_1.Logger.success(`${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} checked out${failed.length ? `, ${failed.length} failed` : ''}.`);
+    logger_1.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` : ''}.`);
     if (failed.length > 0) {
         for (const failure of failed) {
             logger_1.Logger.error(`  - ${failure.id}: ${failure.message}`);

package/dist/registry/checkout/tokens.d.ts

@@ -12,4 +12,4 @@ import Handoff from '../../index';
  * Checkout all published token sets, or a single set when `setId` is given. Reconstructs `tokens.json`
  * and restores generated files; prompts before overwriting changed local files unless `--force`.
  */
-export declare const checkoutTokens: (handoff: Handoff, setId?: string) => Promise<void>;
+export declare const checkoutTokens: (handoff: Handoff, selection?: string[]) => Promise<void>;

package/dist/registry/checkout/tokens.js

@@ -97,15 +97,18 @@ const wouldChange = (absolutePath, content) => {
  * Checkout all published token sets, or a single set when `setId` is given. Reconstructs `tokens.json`
  * and restores generated files; prompts before overwriting changed local files unless `--force`.
  */
-const checkoutTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, function* () {
-    if (setId && !(0, sets_1.isTokenSetId)(setId)) {
-        throw new index_1.CheckoutError(`Unknown or unsafe token set id "${setId}".`);
+const checkoutTokens = (handoff, selection) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const unsupported = (_a = selection === null || selection === void 0 ? void 0 : selection.filter((id) => !(0, sets_1.isTokenSetId)(id))) !== null && _a !== void 0 ? _a : [];
+    if (unsupported.length > 0) {
+        throw new index_1.CheckoutError(`Unknown or unsafe token set id ${unsupported.map((id) => `"${id}"`).join(', ')}.`);
     }
     const connection = yield (0, index_1.resolveConnectionOrThrow)(handoff);
     const client = (0, client_1.createRegistryClient)({ baseUrl: connection.url, accessToken: connection.accessToken });
+    // A named selection is trusted as-is; only a full checkout has to ask the registry what exists.
     let ids;
-    if (setId) {
-        ids = [setId];
+    if (selection) {
+        ids = selection;
     }
     else {
         const summaries = yield client.listTokenSets();
@@ -153,6 +156,10 @@ const checkoutTokens = (handoff, setId) => __awaiter(void 0, void 0, void 0, fun
         }
     }
     const existingChanges = changed.filter((filePath) => fs_extra_1.default.existsSync(filePath));
+    if (handoff.dryRun) {
+        (0, index_1.reportPlannedWrites)(handoff, 'token sets', changed, existingChanges);
+        return;
+    }
     if (existingChanges.length > 0 && !handoff.force) {
         const proceed = yield p.confirm({
             message: `Checkout will overwrite ${existingChanges.length} changed local token file(s). Continue?`,

package/dist/registry/connection.d.ts

@@ -6,6 +6,9 @@
  * config + environment: the registry URL may be given inline or via an env-var *name*, and the
  * access token is always read from an env-var name (never persisted as a value). This is the single
  * source the publish (and later checkout) client reads its target + credentials from.
+ *
+ * The older `HANDOFF_CLOUD_*` names still work as deprecated fallbacks; see
+ * {@link DEPRECATED_ENV_ALIASES}.
  */
 import type { Config } from '../types/config';
 /** Default env-var name holding the remote registry base URL. */
@@ -26,6 +29,9 @@ export interface ResolvedRegistryConnection {
 /**
  * Resolve the connected-workspace registry connection from config + environment. Never throws —
  * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ *
+ * `urlEnv` and `accessTokenEnv` always report the canonical name, even when an alias supplied the
+ * value, so errors built from them point at the variable to adopt.
  */
 export declare const resolveRegistryConnection: (config: Config | null | undefined) => ResolvedRegistryConnection;
 /**
@@ -35,5 +41,9 @@ export declare const resolveRegistryConnection: (config: Config | null | undefin
  * 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.
+ *
+ * A configured `HANDOFF_SYNC_SECRET` is the last resort. Being deployment-wide rather than personal,
+ * it fills in only where there is no explicit token and no login (CI, in practice), instead of quietly
+ * speaking for a developer who is signed in.
  */
 export declare const resolveAuthenticatedRegistryConnection: (config: Config | null | undefined, workingPath?: string) => Promise<ResolvedRegistryConnection>;

package/dist/registry/connection.js

@@ -7,6 +7,9 @@
  * config + environment: the registry URL may be given inline or via an env-var *name*, and the
  * access token is always read from an env-var name (never persisted as a value). This is the single
  * source the publish (and later checkout) client reads its target + credentials from.
+ *
+ * The older `HANDOFF_CLOUD_*` names still work as deprecated fallbacks; see
+ * {@link DEPRECATED_ENV_ALIASES}.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -20,22 +23,60 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAuthenticatedRegistryConnection = exports.resolveRegistryConnection = exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = exports.DEFAULT_REGISTRY_URL_ENV = void 0;
 const store_1 = require("../cli/auth/store");
+// Imported straight from the module, not the `auth` barrel, to keep the database schema off the CLI
+// startup path; this file is resolved for every command.
+const sync_secret_1 = require("./auth/sync-secret");
+const logger_1 = require("../utils/logger");
 /** Default env-var name holding the remote registry base URL. */
 exports.DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
 /** Default env-var name holding the connected-workspace access token. */
 exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = 'HANDOFF_REGISTRY_ACCESS_TOKEN';
+/**
+ * Old env-var names we still read, keyed by the name that replaced them. Keeps workspaces set up
+ * from the older docs working instead of silently reporting no registry.
+ */
+const DEPRECATED_ENV_ALIASES = {
+    [exports.DEFAULT_REGISTRY_URL_ENV]: 'HANDOFF_CLOUD_URL',
+    [exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV]: 'HANDOFF_CLOUD_TOKEN',
+};
+/** Aliases we've already warned about, so each one warns once per run and not once per lookup. */
+const warnedAliases = new Set();
+/**
+ * Value of the named env var, falling back to its deprecated alias. Only the default names have
+ * aliases: a custom `urlEnv`/`accessTokenEnv` is a deliberate choice, so a stray `HANDOFF_CLOUD_*`
+ * must not stand in for it. The warning goes through {@link Logger.warn}, so
+ * `HANDOFF_LOG_LEVEL=error` silences it in CI.
+ */
+const readConnectionEnv = (name) => {
+    var _a, _b;
+    const configured = (_a = process.env[name]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (configured)
+        return configured;
+    const alias = DEPRECATED_ENV_ALIASES[name];
+    const inherited = alias ? (_b = process.env[alias]) === null || _b === void 0 ? void 0 : _b.trim() : '';
+    if (!inherited)
+        return '';
+    if (!warnedAliases.has(alias)) {
+        warnedAliases.add(alias);
+        logger_1.Logger.warn(`${alias} is deprecated and will be removed in a future release; set ${name} instead.`);
+    }
+    return inherited;
+};
 /**
  * Resolve the connected-workspace registry connection from config + environment. Never throws —
  * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ *
+ * `urlEnv` and `accessTokenEnv` always report the canonical name, even when an alias supplied the
+ * value, so errors built from them point at the variable to adopt.
  */
 const resolveRegistryConnection = (config) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d;
     const connection = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registryConnection;
     const urlEnv = ((_b = connection === null || connection === void 0 ? void 0 : connection.urlEnv) === null || _b === void 0 ? void 0 : _b.trim()) || exports.DEFAULT_REGISTRY_URL_ENV;
     const accessTokenEnv = ((_c = connection === null || connection === void 0 ? void 0 : connection.accessTokenEnv) === null || _c === void 0 ? void 0 : _c.trim()) || exports.DEFAULT_REGISTRY_ACCESS_TOKEN_ENV;
     const inlineUrl = (_d = connection === null || connection === void 0 ? void 0 : connection.url) === null || _d === void 0 ? void 0 : _d.trim();
-    const url = (_f = (inlineUrl || ((_e = process.env[urlEnv]) === null || _e === void 0 ? void 0 : _e.trim()))) !== null && _f !== void 0 ? _f : '';
-    const accessToken = (_h = (_g = process.env[accessTokenEnv]) === null || _g === void 0 ? void 0 : _g.trim()) !== null && _h !== void 0 ? _h : '';
+    const url = inlineUrl || readConnectionEnv(urlEnv);
+    const accessToken = readConnectionEnv(accessTokenEnv);
     return {
         url,
         accessToken,
@@ -51,14 +92,18 @@ exports.resolveRegistryConnection = resolveRegistryConnection;
  * 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.
+ *
+ * A configured `HANDOFF_SYNC_SECRET` is the last resort. Being deployment-wide rather than personal,
+ * it fills in only where there is no explicit token and no login (CI, in practice), instead of quietly
+ * speaking for a developer who is signed in.
  */
 const resolveAuthenticatedRegistryConnection = (config_1, ...args_1) => __awaiter(void 0, [config_1, ...args_1], void 0, function* (config, workingPath = process.cwd()) {
     const connection = (0, exports.resolveRegistryConnection)(config);
     const auth = yield (0, store_1.readCliAuth)(workingPath);
-    if (!(0, store_1.cliAuthTokenIsValid)(auth))
-        return connection;
-    const url = connection.url || auth.remoteUrl;
-    const accessToken = connection.accessToken || ((0, store_1.cliAuthMatchesRegistry)(auth, url) ? auth.accessToken : '');
+    const login = (0, store_1.cliAuthTokenIsValid)(auth) ? auth : null;
+    const url = connection.url || (login === null || login === void 0 ? void 0 : login.remoteUrl) || '';
+    const savedToken = login && (0, store_1.cliAuthMatchesRegistry)(login, url) ? login.accessToken : '';
+    const accessToken = connection.accessToken || savedToken || (0, sync_secret_1.resolveRegistrySyncSecret)();
     return Object.assign(Object.assign({}, connection), { url, accessToken });
 });
 exports.resolveAuthenticatedRegistryConnection = resolveAuthenticatedRegistryConnection;

package/dist/registry/content-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Logical content-kind vocabulary: the dependency-light boundary shared by the CLI, the
+ * publish/checkout orchestration, and the compatibility layer.
+ *
+ * A workspace publishes and checks out five kinds of content. Components, patterns and pages are
+ * entities with a singular wire kind ({@link TransferEntityKind}); tokens and assets travel through
+ * their own transfer endpoints. This module owns only the stable plural vocabulary and its ordering,
+ * so it stays free of fs, DB and React dependencies.
+ */
+import type { TransferEntityKind } from './transfer';
+/** Stable identity used to publish `pages/index.md` while serving it at the root route. */
+export declare const HOME_PAGE_ID = "index";
+export declare const HOME_PAGE_PATH = "/";
+/** Plural content kinds accepted wherever a publish or checkout target is named. */
+export declare const REGISTRY_ENTITY_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets"];
+export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
+/** Map the plural content kind to the singular wire kind used by entity publish/checkout. */
+export declare const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind>;
+/** The entity kinds, in the order a full run visits them: patterns compose components, pages reference both. */
+export declare const ENTITY_KIND_ORDER: readonly ["components", "patterns", "pages"];
+/**
+ * Every kind, in dependency order. Tokens and assets come first because rendered component
+ * artifacts reference the CSS variables and asset URLs they produce.
+ */
+export declare const ALL_KIND_ORDER: readonly RegistryEntityKind[];
+/** Whether a string names a supported content kind. */
+export declare const isRegistryEntityKind: (value: string) => value is RegistryEntityKind;