handoff-app 2.0.0-4 → 2.0.0-5

package/dist/index.js

@@ -45,11 +45,68 @@ const eject_1 = require("./cli/eject");
 const make_1 = require("./cli/make");
 const config_1 = require("./config");
 const pipeline_1 = __importStar(require("./pipeline"));
+const content_kinds_1 = require("./registry/content-kinds");
 const store_1 = require("./store");
 const builder_1 = __importStar(require("./transformers/preview/component/builder"));
 const logger_1 = require("./utils/logger");
 const path_2 = require("./utils/path");
 const path_3 = require("./utils/path");
+/**
+ * Reject a kind we do not know. Plural kinds arrive from CLI arguments and HTTP payloads, so an
+ * unrecognized one has to stop here: the entity paths below pick their store by elimination, and an
+ * unchecked value would quietly resolve to pages.
+ */
+const assertContentKind = (kind) => {
+    if (!(0, content_kinds_1.isRegistryEntityKind)(kind)) {
+        throw new Error(`Unknown content kind "${kind}". Supported kinds: ${content_kinds_1.REGISTRY_ENTITY_KINDS.join(', ')}.`);
+    }
+};
+const normalizeTarget = (target) => typeof target === 'string' ? { kind: target } : target;
+/**
+ * Normalize an optional single-or-list selection to a list, or `undefined` for "everything". An empty
+ * list means "everything" too: yargs defaults an omitted variadic positional to `[]`, and that has to
+ * read as "no narrowing", not "no targets".
+ */
+const toSelection = (value) => {
+    if (value === undefined)
+        return undefined;
+    const selection = Array.isArray(value) ? value : [value];
+    return selection.length > 0 ? selection : undefined;
+};
+/**
+ * The one id a selection names, if it names exactly one. Lets a single-target request keep the
+ * cheaper targeted-build path whether it arrived as a string or a one-element list.
+ */
+const onlyId = (value) => {
+    const selection = toSelection(value);
+    return (selection === null || selection === void 0 ? void 0 : selection.length) === 1 ? selection[0] : undefined;
+};
+/**
+ * Run one operation across several targets in order, reporting each failure as it happens and throwing
+ * once at the end. Shared by {@link Handoff.publishAll} and {@link Handoff.checkoutAll} so a
+ * multi-kind run behaves the same in both directions.
+ */
+const runKinds = (targets, verb, dryRun, run) => __awaiter(void 0, void 0, void 0, function* () {
+    const kinds = targets.map(normalizeTarget);
+    const failed = [];
+    for (const { kind, ids } of kinds) {
+        try {
+            yield run(kind, ids);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            failed.push({ kind, message });
+            logger_1.Logger.error(`Failed to ${verb} ${kind}: ${message}`);
+        }
+    }
+    const succeeded = kinds.length - failed.length;
+    const outcome = verb === 'publish' ? 'published' : 'checked out';
+    logger_1.Logger.success(`${dryRun ? 'Dry run' : `${verb[0].toUpperCase()}${verb.slice(1)} complete`} — ${succeeded}/${kinds.length} kind(s) ` +
+        `${dryRun ? `would be ${outcome}` : outcome}${failed.length ? `, ${failed.length} failed` : ''}.`);
+    if (failed.length > 0) {
+        throw new Error(`${failed.length} kind(s) failed to ${verb}: ${failed.map((entry) => entry.kind).join(', ')}.`);
+    }
+});
 class Handoff {
     /**
      * Normalized store over the current workspace runtime for components, patterns, pages, tokens,
@@ -61,30 +118,38 @@ class Handoff {
         }
         return this._store;
     }
-    constructor(debug, force, config) {
+    constructor(options = {}) {
         this.debug = false;
         this.force = false;
+        this.dryRun = false;
+        this.skipBuild = false;
         this.modulePath = path_1.default.resolve(__filename, '../..');
-        this.workingPath = process.cwd();
+        this.workingPath = (0, path_2.resolveWorkingPath)();
         this.exportsDirectory = 'exported';
         this.sitesDirectory = 'out';
-        this._initialArgs = {};
+        this._options = {};
         this._configFilePaths = [];
         this._configFileIndex = new Map();
-        this._initialArgs = { debug, force, config };
-        this.construct(debug, force, config);
+        this._options = options;
+        this.construct(options);
     }
-    construct(debug, force, config) {
+    construct(options) {
+        var _a, _b, _c, _d;
         this.config = null;
-        this.debug = debug !== null && debug !== void 0 ? debug : false;
-        this.force = force !== null && force !== void 0 ? force : false;
+        this.debug = (_a = options.debug) !== null && _a !== void 0 ? _a : false;
+        this.force = (_b = options.force) !== null && _b !== void 0 ? _b : false;
+        this.dryRun = (_c = options.dryRun) !== null && _c !== void 0 ? _c : false;
+        this.skipBuild = (_d = options.skipBuild) !== null && _d !== void 0 ? _d : false;
         logger_1.Logger.init({ debug: this.debug });
-        this.init(config);
+        this.init(options.config);
         global.handoff = this;
     }
     init(configOverride) {
         var _a, _b, _c;
-        const configResult = (0, config_1.initConfigWithMetadata)(configOverride !== null && configOverride !== void 0 ? configOverride : {});
+        const configResult = (0, config_1.initConfigWithMetadata)(configOverride !== null && configOverride !== void 0 ? configOverride : {}, {
+            workingPath: this.workingPath,
+            configPath: this._options.configPath,
+        });
         const config = configResult.config;
         this.config = config;
         this._mainConfigFilePath = configResult.configPath;
@@ -97,7 +162,7 @@ class Handoff {
         return this;
     }
     reload() {
-        this.construct(this._initialArgs.debug, this._initialArgs.force, this._initialArgs.config);
+        this.construct(this._options);
         return this;
     }
     preRunner(validate) {
@@ -160,42 +225,45 @@ class Handoff {
     }
     /**
      * Publish components, patterns, or pages from this connected workspace to the configured remote
-     * registry. With `id` it publishes that one entity after a targeted build; without `id` it builds
-     * the kind once and publishes every declared entity, skipping ones whose content is unchanged on
-     * the registry (`--force` re-uploads all). Pages upload their record and markdown source because
-     * they render at runtime. The publish module is loaded lazily so the registry client and build code
-     * never enter the docs app bundle.
+     * registry. With a single `id` it publishes that one entity after a targeted build; with a list of
+     * ids, or none, it builds the kind once and publishes the selected (or every declared) entity,
+     * skipping ones whose content is unchanged on the registry (`--force` re-uploads all). Pages upload
+     * their record and markdown source because they render at runtime. The publish module is loaded
+     * lazily so the registry client and build code never enter the docs app bundle.
      */
     publish(kind, id) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            if (id) {
+            const single = onlyId(id);
+            if (single) {
                 const { publishEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
-                yield publishEntity(this, kind, id);
+                yield publishEntity(this, kind, single);
             }
             else {
                 const { publishEntities } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
-                yield publishEntities(this, kind);
+                yield publishEntities(this, kind, toSelection(id));
             }
             return this;
         });
     }
     /**
      * Checkout components, patterns, or pages from the connected remote registry into this workspace.
-     * With `id` it checks out that one entity; without `id` it checks out every published entity of the
-     * kind. Overwriting existing local files requires `--force` or an interactive confirmation. The
-     * checkout module is loaded lazily so the registry client never enters the docs app bundle.
+     * With a single `id` it checks out that one entity; with a list of ids, or none, it checks out the
+     * selected (or every published) entity of the kind. Overwriting existing local files requires
+     * `--force` or an interactive confirmation. The checkout module is loaded lazily so the registry
+     * client never enters the docs app bundle.
      */
     checkout(kind, id) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            if (id) {
+            const single = onlyId(id);
+            if (single) {
                 const { checkoutEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
-                yield checkoutEntity(this, kind, id);
+                yield checkoutEntity(this, kind, single);
             }
             else {
                 const { checkoutEntities } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
-                yield checkoutEntities(this, kind);
+                yield checkoutEntities(this, kind, toSelection(id));
             }
             return this;
         });
@@ -204,28 +272,28 @@ class Handoff {
      * Publish design token sets from this connected workspace to the configured remote registry. Runs a
      * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads
      * each changed set (its extracted record + generated artifacts). Publishes every set when `setId` is
-     * omitted, or only the named set (`foundation/colors`, `component/<id>`). Loaded lazily so the
+     * omitted, or only the named set(s) (`foundation/colors`, `component/<id>`). Loaded lazily so the
      * registry client/build code never enters the docs app bundle.
      */
     publishTokens(setId) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
             const { publishTokens } = yield Promise.resolve().then(() => __importStar(require('./registry/publish/tokens')));
-            yield publishTokens(this, setId);
+            yield publishTokens(this, toSelection(setId));
             return this;
         });
     }
     /**
      * Checkout design token sets from the connected remote registry into this workspace: reconstruct
      * the canonical local `tokens.json` and restore the generated token files to their configured output
-     * paths. Checks out every published set when `setId` is omitted, or only the named set. Loaded lazily
-     * so the registry client never enters the docs app bundle.
+     * paths. Checks out every published set when `setId` is omitted, or only the named set(s). Loaded
+     * lazily so the registry client never enters the docs app bundle.
      */
     checkoutTokens(setId) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
             const { checkoutTokens } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout/tokens')));
-            yield checkoutTokens(this, setId);
+            yield checkoutTokens(this, toSelection(setId));
             return this;
         });
     }
@@ -233,28 +301,73 @@ class Handoff {
      * Publish asset collections (icons/logos/fonts) from this connected workspace to the configured
      * remote registry. Runs a fresh build (Figma extract + asset generation), discovers the collections,
      * uploads only content hashes the registry lacks, and finalizes each collection manifest atomically.
-     * Publishes every collection when `collection` is omitted, or only the named one. Loaded lazily so
+     * Publishes every collection when `collection` is omitted, or only the named one(s). Loaded lazily so
      * the registry client/build code never enters the docs app bundle.
      */
     publishAssets(collection) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
             const { publishAssets } = yield Promise.resolve().then(() => __importStar(require('./registry/publish/assets')));
-            yield publishAssets(this, collection);
+            yield publishAssets(this, toSelection(collection));
             return this;
         });
     }
     /**
      * Checkout asset collections from the connected remote registry into this workspace: recreate the
      * standard workspace asset files, collection JSON, icon sprite/manifest, and downloadable archives.
-     * Checks out every published collection when `collection` is omitted, or only the named one. Loaded
-     * lazily so the registry client never enters the docs app bundle.
+     * Checks out every published collection when `collection` is omitted, or only the named one(s).
+     * Loaded lazily so the registry client never enters the docs app bundle.
      */
     checkoutAssets(collection) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
             const { checkoutAssets } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout/assets')));
-            yield checkoutAssets(this, collection);
+            yield checkoutAssets(this, toSelection(collection));
+            return this;
+        });
+    }
+    /**
+     * Publish one content kind named by its plural form (`components`, `tokens`, …). The entry point for
+     * callers working in the plural vocabulary, so the plural-to-transfer-path mapping lives in one
+     * place.
+     */
+    publishKind(kind, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            assertContentKind(kind);
+            if (kind === 'tokens')
+                return this.publishTokens(id);
+            if (kind === 'assets')
+                return this.publishAssets(id);
+            return this.publish(content_kinds_1.ENTITY_WIRE_KIND[kind], id);
+        });
+    }
+    /** Checkout one content kind named by its plural form. Mirrors {@link publishKind}. */
+    checkoutKind(kind, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            assertContentKind(kind);
+            if (kind === 'tokens')
+                return this.checkoutTokens(id);
+            if (kind === 'assets')
+                return this.checkoutAssets(id);
+            return this.checkout(content_kinds_1.ENTITY_WIRE_KIND[kind], id);
+        });
+    }
+    /**
+     * Publish every content kind, or the given subset of kinds and ids, in dependency order: tokens and
+     * assets first (rendered component artifacts reference the CSS variables and asset URLs they
+     * produce), then components, patterns and pages. A failing kind is reported and never aborts the
+     * rest; the run throws at the end if any kind failed.
+     */
+    publishAll() {
+        return __awaiter(this, arguments, void 0, function* (targets = content_kinds_1.ALL_KIND_ORDER) {
+            yield runKinds(targets, 'publish', this.dryRun, (kind, ids) => this.publishKind(kind, ids));
+            return this;
+        });
+    }
+    /** Checkout every content kind, or the given subset, in the same order. Mirrors {@link publishAll}. */
+    checkoutAll() {
+        return __awaiter(this, arguments, void 0, function* (targets = content_kinds_1.ALL_KIND_ORDER) {
+            yield runKinds(targets, 'checkout', this.dryRun, (kind, ids) => this.checkoutKind(kind, ids));
             return this;
         });
     }

package/dist/nav/resolver.js

@@ -13,6 +13,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNavData = void 0;
 const lodash_1 = require("lodash");
+const content_kinds_1 = require("../registry/content-kinds");
 const normalizeBasePath = (basePath) => {
     if (!basePath)
         return '';
@@ -142,7 +143,8 @@ const buildChildPageItems = (parentId, pages) => {
 const buildPageSections = (sources, keepEmpty) => {
     const pages = sources.pages.filter((page) => page.enabled !== false);
     return pages
-        .filter((page) => !page.id.includes('/'))
+        // The home page is reachable through the header logo and must not become a duplicate nav section.
+        .filter((page) => page.id !== content_kinds_1.HOME_PAGE_ID && !page.id.includes('/'))
         .map((page) => {
         var _a, _b;
         const declared = page.menu

package/dist/nav/workspace.js

@@ -37,8 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWorkspaceNavData = void 0;
 const fs = __importStar(require("fs"));
-const gray_matter_1 = __importDefault(require("gray-matter"));
 const path_1 = __importDefault(require("path"));
+const markdown_1 = require("../utils/markdown");
 const menu_shell_1 = require("../utils/menu-shell");
 const resolver_1 = require("./resolver");
 const safeLoad = (load) => __awaiter(void 0, void 0, void 0, function* () {
@@ -58,7 +58,7 @@ const markdownTitle = (id, docRoot, workingPagesDir) => {
     for (const candidate of candidates) {
         if (!candidate || !fs.existsSync(candidate))
             continue;
-        const title = (0, gray_matter_1.default)(fs.readFileSync(candidate, 'utf8')).data.title;
+        const title = (0, markdown_1.parseMarkdown)(fs.readFileSync(candidate, 'utf8')).data.title;
         if (typeof title === 'string' && title.trim())
             return title;
     }

package/dist/registry/auth/access-tokens.d.ts

@@ -1,6 +1,6 @@
 import type { RegistryDatabase } from '../db/client';
 import { type RegistryAccessScope } from '../db/schema';
-import { type RegistryPrincipal, type RegistryUserRole } from './types';
+import { type RegistryTokenPrincipal, type RegistryUserRole } from './types';
 export interface RegistryAccessTokenSummary {
     id: string;
     name: string;
@@ -18,7 +18,15 @@ export type CreateRegistryAccessTokenResult = {
     ok: false;
     reason: 'user_not_found' | 'user_inactive' | 'scope_forbidden' | 'invalid_name' | 'invalid_expiry';
 };
-export declare const normalizeRegistryScopes: (scopes: readonly RegistryAccessScope[]) => RegistryAccessScope[];
+/** Resolve one canonical scope or documented alias; anything else is not a scope we grant. */
+export declare const resolveRegistryScope: (value: unknown) => RegistryAccessScope | null;
+/** Resolve, dedupe and canonically order a scope list, dropping anything unrecognized. */
+export declare const normalizeRegistryScopes: (scopes: readonly unknown[]) => RegistryAccessScope[];
+/**
+ * Normalize a requested scope list into what a token is issued with: write implies read (a write-only
+ * token would be rejected by every read endpoint), and an empty request means read.
+ */
+export declare const expandRegistryScopes: (scopes: readonly unknown[]) => RegistryAccessScope[];
 export declare const registryRoleAllowsScopes: (role: RegistryUserRole, scopes: readonly RegistryAccessScope[]) => boolean;
 export declare const formatRegistryAccessToken: (id: string, secret: string) => string;
 export declare const parseRegistryAccessToken: (token: string) => {
@@ -43,4 +51,4 @@ export declare const revokeAllRegistryAccessTokens: (db: RegistryDatabase, userI
  * Resolve an opaque bearer credential into a live principal. User state is joined on every call,
  * making deactivation effective even if a defensive token-revocation write was interrupted.
  */
-export declare const authenticateRegistryAccessToken: (db: RegistryDatabase, token: string, now?: Date) => Promise<RegistryPrincipal | null>;
+export declare const authenticateRegistryAccessToken: (db: RegistryDatabase, token: string, now?: Date) => Promise<RegistryTokenPrincipal | null>;

package/dist/registry/auth/access-tokens.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.registryRoleAllowsScopes = exports.normalizeRegistryScopes = void 0;
+exports.authenticateRegistryAccessToken = exports.revokeAllRegistryAccessTokens = exports.revokeRegistryAccessToken = exports.listRegistryAccessTokens = exports.createRegistryAccessToken = exports.parseRegistryAccessToken = exports.formatRegistryAccessToken = exports.registryRoleAllowsScopes = exports.expandRegistryScopes = exports.normalizeRegistryScopes = exports.resolveRegistryScope = void 0;
 const drizzle_orm_1 = require("drizzle-orm");
 const schema_1 = require("../db/schema");
 const crypto_1 = require("./crypto");
@@ -17,12 +17,37 @@ const database_1 = require("./database");
 const types_1 = require("./types");
 const ACCESS_TOKEN_PREFIX = 'hnd';
 const DEFAULT_ACCESS_TOKEN_LIFETIME_MS = 365 * 24 * 60 * 60 * 1000;
-const isRegistryScope = (value) => value === types_1.REGISTRY_READ_SCOPE || value === types_1.REGISTRY_WRITE_SCOPE;
+/**
+ * Documented scope names that mean the same as ours. The published API vocabulary calls these
+ * `sync:*`; they are resolved on the way in and never stored, so rows and responses stay canonical.
+ */
+const SCOPE_ALIASES = {
+    'sync:read': types_1.REGISTRY_READ_SCOPE,
+    'sync:write': types_1.REGISTRY_WRITE_SCOPE,
+};
+/** Resolve one canonical scope or documented alias; anything else is not a scope we grant. */
+const resolveRegistryScope = (value) => {
+    var _a;
+    if (value === types_1.REGISTRY_READ_SCOPE || value === types_1.REGISTRY_WRITE_SCOPE)
+        return value;
+    return typeof value === 'string' ? ((_a = SCOPE_ALIASES[value]) !== null && _a !== void 0 ? _a : null) : null;
+};
+exports.resolveRegistryScope = resolveRegistryScope;
+/** Resolve, dedupe and canonically order a scope list, dropping anything unrecognized. */
 const normalizeRegistryScopes = (scopes) => {
-    const unique = new Set(scopes.filter(isRegistryScope));
+    const unique = new Set(scopes.map(exports.resolveRegistryScope).filter((scope) => scope !== null));
     return [types_1.REGISTRY_READ_SCOPE, types_1.REGISTRY_WRITE_SCOPE].filter((scope) => unique.has(scope));
 };
 exports.normalizeRegistryScopes = normalizeRegistryScopes;
+/**
+ * Normalize a requested scope list into what a token is issued with: write implies read (a write-only
+ * token would be rejected by every read endpoint), and an empty request means read.
+ */
+const expandRegistryScopes = (scopes) => {
+    const normalized = (0, exports.normalizeRegistryScopes)(scopes);
+    return normalized.includes(types_1.REGISTRY_WRITE_SCOPE) ? [types_1.REGISTRY_READ_SCOPE, types_1.REGISTRY_WRITE_SCOPE] : [types_1.REGISTRY_READ_SCOPE];
+};
+exports.expandRegistryScopes = expandRegistryScopes;
 const registryRoleAllowsScopes = (role, scopes) => role === 'admin' || !scopes.includes(types_1.REGISTRY_WRITE_SCOPE);
 exports.registryRoleAllowsScopes = registryRoleAllowsScopes;
 const formatRegistryAccessToken = (id, secret) => `${ACCESS_TOKEN_PREFIX}_${id}_${secret}`;
@@ -154,6 +179,7 @@ const authenticateRegistryAccessToken = (db_1, token_1, ...args_1) => __awaiter(
     if (!updated.length)
         return null;
     return {
+        kind: 'access_token',
         tokenId: row.tokenId,
         userId: row.userId,
         email: row.email,

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

@@ -1,11 +1,12 @@
-export { createRegistryAccessToken, listRegistryAccessTokens, revokeRegistryAccessToken, revokeAllRegistryAccessTokens, authenticateRegistryAccessToken, formatRegistryAccessToken, parseRegistryAccessToken, normalizeRegistryScopes, registryRoleAllowsScopes, type RegistryAccessTokenSummary, type CreateRegistryAccessTokenResult, } from './access-tokens';
+export { createRegistryAccessToken, listRegistryAccessTokens, revokeRegistryAccessToken, revokeAllRegistryAccessTokens, authenticateRegistryAccessToken, formatRegistryAccessToken, parseRegistryAccessToken, normalizeRegistryScopes, expandRegistryScopes, resolveRegistryScope, 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 { authenticateRegistrySyncSecret, resolveRegistrySyncSecret, SYNC_SECRET_ENV } from './sync-secret';
 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';
+export { REGISTRY_READ_SCOPE, REGISTRY_WRITE_SCOPE, scopesForRegistryRole, registryPrincipalHasScope, isRegistryTokenPrincipal, type RegistryAccessScope, type RegistryPrincipal, type RegistryTokenPrincipal, type RegistrySyncSecretPrincipal, type RegistryUser, type RegistryUserRole, type RegistryUserStatus, } from './types';
+export { isTransmittableCredential, validateRegistryDisplayName, validateRegistryEmail, validateRegistryImageUrl } from './validation';

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