handoff-app 2.0.0-9 → 2.0.0

package/dist/registry/asset-storage/resolve.d.ts

@@ -2,44 +2,34 @@
  * Asset storage settings resolution.
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
- * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
- * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
+ * `database` inline default or a `custom` module. The build bakes the provider, the module location,
+ * and the options. An option literal is baked as it is. An environment reference stays `{ $env }`
+ * and is resolved at request time, before the custom provider factory runs.
  */
 import type { ResolvedConfig } from '../../types/config';
 import type { AssetStorageProvider } from '../db/schema';
-/** Which adapter implementation is active. */
-export type AssetStorageAdapterKind = 'database' | 'vercel-blob' | 'custom';
 /** The raw, authored settings block (a structural copy of the config type, resolvable from bake). */
 export interface AssetStorageSettings {
-    adapter?: AssetStorageAdapterKind;
+    provider?: AssetStorageProvider;
     module?: string;
-    tokenEnv?: string;
     maxInlineBytes?: number;
     options?: Record<string, unknown>;
 }
-/** Default adapter when none is configured. */
-export declare const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind;
-/** Default env-var name holding the Vercel Blob read/write token. */
-export declare const DEFAULT_BLOB_TOKEN_ENV = "BLOB_READ_WRITE_TOKEN";
+export declare const DEFAULT_ASSET_STORAGE_PROVIDER: AssetStorageProvider;
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 export declare const DEFAULT_MAX_INLINE_BYTES: number;
 /** Fully resolved asset storage settings. */
 export interface ResolvedAssetStorage {
-    /** The active adapter implementation. */
-    adapterKind: AssetStorageAdapterKind;
-    /** Provider id recorded on blob rows written by the active adapter (drives read resolution). */
+    /** Recorded on each new blob row as its storage provider. */
     provider: AssetStorageProvider;
-    /** For `custom`: the server-only adapter module path. */
+    /** For `custom`: the server-only provider module path. */
     module?: string;
-    /** For `vercel-blob`: the env-var name holding the token. */
-    tokenEnv: string;
     /** For `database`: the inline-content size ceiling. */
     maxInlineBytes: number;
-    /** Non-secret adapter options. */
+    /** Provider options: literals and `{ $env }` references, never secret values. */
     options: Record<string, unknown>;
 }
 /** Resolve raw asset storage settings into a fully-defaulted shape. */
 export declare const resolveAssetStorageSettings: (settings: AssetStorageSettings | null | undefined) => ResolvedAssetStorage;
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
 export declare const resolveAssetStorageFromConfig: (config: ResolvedConfig | null | undefined) => ResolvedAssetStorage;

package/dist/registry/asset-storage/resolve.js

@@ -3,37 +3,49 @@
  * Asset storage settings resolution.
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
- * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
- * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
+ * `database` inline default or a `custom` module. The build bakes the provider, the module location,
+ * and the options. An option literal is baked as it is. An environment reference stays `{ $env }`
+ * and is resolved at request time, before the custom provider factory runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveAssetStorageFromConfig = exports.resolveAssetStorageSettings = exports.DEFAULT_MAX_INLINE_BYTES = exports.DEFAULT_BLOB_TOKEN_ENV = exports.DEFAULT_ASSET_STORAGE_ADAPTER = void 0;
-/** Default adapter when none is configured. */
-exports.DEFAULT_ASSET_STORAGE_ADAPTER = 'database';
-/** Default env-var name holding the Vercel Blob read/write token. */
-exports.DEFAULT_BLOB_TOKEN_ENV = 'BLOB_READ_WRITE_TOKEN';
+exports.resolveAssetStorageFromConfig = exports.resolveAssetStorageSettings = exports.DEFAULT_MAX_INLINE_BYTES = exports.DEFAULT_ASSET_STORAGE_PROVIDER = void 0;
+const errors_1 = require("../../config/errors");
+const PROVIDERS = ['database', 'custom'];
+exports.DEFAULT_ASSET_STORAGE_PROVIDER = 'database';
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 exports.DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
-/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
-const customProviderId = (options) => {
-    const id = typeof options.providerId === 'string' && options.providerId.trim() ? options.providerId.trim() : 'custom';
-    return id;
-};
 /** Resolve raw asset storage settings into a fully-defaulted shape. */
 const resolveAssetStorageSettings = (settings) => {
-    var _a, _b, _c, _d;
-    const adapterKind = (_a = settings === null || settings === void 0 ? void 0 : settings.adapter) !== null && _a !== void 0 ? _a : exports.DEFAULT_ASSET_STORAGE_ADAPTER;
+    var _a, _b, _c;
+    const provider = (_a = settings === null || settings === void 0 ? void 0 : settings.provider) !== null && _a !== void 0 ? _a : exports.DEFAULT_ASSET_STORAGE_PROVIDER;
     const options = (_b = settings === null || settings === void 0 ? void 0 : settings.options) !== null && _b !== void 0 ? _b : {};
-    const tokenEnv = ((_c = settings === null || settings === void 0 ? void 0 : settings.tokenEnv) === null || _c === void 0 ? void 0 : _c.trim()) || exports.DEFAULT_BLOB_TOKEN_ENV;
     const maxInlineBytes = typeof (settings === null || settings === void 0 ? void 0 : settings.maxInlineBytes) === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : exports.DEFAULT_MAX_INLINE_BYTES;
-    const provider = adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
-    return { adapterKind, provider, module: ((_d = settings === null || settings === void 0 ? void 0 : settings.module) === null || _d === void 0 ? void 0 : _d.trim()) || undefined, tokenEnv, maxInlineBytes, options };
+    return { provider, module: ((_c = settings === null || settings === void 0 ? void 0 : settings.module) === null || _c === void 0 ? void 0 : _c.trim()) || undefined, maxInlineBytes, options };
 };
 exports.resolveAssetStorageSettings = resolveAssetStorageSettings;
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
 const resolveAssetStorageFromConfig = (config) => {
-    var _a, _b, _c, _d, _e, _f;
-    return (0, exports.resolveAssetStorageSettings)(Object.assign(Object.assign({}, (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.assetStorage), { tokenEnv: (_f = (_e = (_d = (_c = config === null || config === void 0 ? void 0 : config.runtime) === null || _c === void 0 ? void 0 : _c.registry) === null || _d === void 0 ? void 0 : _d.assetStorage) === null || _e === void 0 ? void 0 : _e.token) === null || _f === void 0 ? void 0 : _f.$env }));
+    var _a, _b, _c;
+    const settings = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.assetStorage;
+    const fail = (problem) => {
+        throw new errors_1.HandoffConfigError(`Config "runtime.registry.assetStorage": ${problem}`);
+    };
+    const provider = (_c = settings === null || settings === void 0 ? void 0 : settings.provider) !== null && _c !== void 0 ? _c : exports.DEFAULT_ASSET_STORAGE_PROVIDER;
+    if (!PROVIDERS.includes(provider)) {
+        fail(`unknown provider ${JSON.stringify(provider)}. Use "database" or "custom".`);
+    }
+    const options = settings === null || settings === void 0 ? void 0 : settings.options;
+    if (options !== undefined && (options === null || typeof options !== 'object' || Array.isArray(options))) {
+        fail('"options" must be an object.');
+    }
+    const module = settings === null || settings === void 0 ? void 0 : settings.module;
+    if (provider === 'custom' && (typeof module !== 'string' || !module.trim())) {
+        fail('provider "custom" needs a "module" that default-exports a defineStorageProvider() result.');
+    }
+    const maxInlineBytes = settings === null || settings === void 0 ? void 0 : settings.maxInlineBytes;
+    if (maxInlineBytes !== undefined && (typeof maxInlineBytes !== 'number' || !Number.isInteger(maxInlineBytes) || maxInlineBytes <= 0)) {
+        fail('"maxInlineBytes" must be a positive whole number.');
+    }
+    return (0, exports.resolveAssetStorageSettings)(settings);
 };
 exports.resolveAssetStorageFromConfig = resolveAssetStorageFromConfig;

package/dist/registry/asset-storage/types.d.ts

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

package/dist/registry/asset-storage/types.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * Server-only asset storage contract for object-backed providers (Vercel Blob + custom
- * {@link defineAssetStorage} modules), so callers need no provider-specific logic. The built-in
- * `database` provider is the inline default: bytes live in the `asset_blobs.content` bytea column,
- * read/written directly by the registry, so it needs no adapter. Object providers record a
- * `storageRef` + provider id so reads resolve back through whichever provider stored the blob.
+ * Server-only asset storage contract for custom {@link defineStorageProvider} object storage modules.
+ * The built-in `database` provider is the inline default: bytes live in the `asset_blobs.content`
+ * bytea column, read/written directly by the registry, so it needs no module. Object providers
+ * record a `storageRef` + provider id so reads resolve back through whichever provider stored the
+ * blob.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/auth/ai-keys.d.ts

@@ -0,0 +1,32 @@
+import type { RegistryDatabase } from '../db/client';
+/**
+ * Reader-supplied keys for connections the config declares with `credential: 'user'`.
+ *
+ * The key is write-only across the API boundary: once saved, a read reports only that a key exists.
+ * Only the chat route ever decrypts one, and only to send it to the connection's own endpoint.
+ */
+/**
+ * Ids of the connections this reader has a *usable* key for. A row that no longer decrypts — written
+ * under a rotated `HANDOFF_AI_KEY_SECRET` — is left out, so the account page and the assistant agree
+ * that no key is in place instead of offering a key the provider would never receive.
+ */
+export declare const listRegistryAiKeyConnections: (db: RegistryDatabase, userId: string) => Promise<string[]>;
+/** Save or replace this reader's key for one connection. */
+export declare const saveRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+    key: string;
+}) => Promise<void>;
+/** Remove this reader's key for one connection. Returns whether a row was there to remove. */
+export declare const deleteRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+}) => Promise<boolean>;
+/**
+ * Read back one reader's key. A row that no longer decrypts reads as absent, so the reader is told
+ * to add a key rather than shown a provider error.
+ */
+export declare const readRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+}) => Promise<string | null>;

package/dist/registry/auth/ai-keys.js

@@ -0,0 +1,69 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRegistryAiKey = exports.deleteRegistryAiKey = exports.saveRegistryAiKey = exports.listRegistryAiKeyConnections = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const schema_1 = require("../db/schema");
+const crypto_1 = require("./crypto");
+/**
+ * Reader-supplied keys for connections the config declares with `credential: 'user'`.
+ *
+ * The key is write-only across the API boundary: once saved, a read reports only that a key exists.
+ * Only the chat route ever decrypts one, and only to send it to the connection's own endpoint.
+ */
+/**
+ * Ids of the connections this reader has a *usable* key for. A row that no longer decrypts — written
+ * under a rotated `HANDOFF_AI_KEY_SECRET` — is left out, so the account page and the assistant agree
+ * that no key is in place instead of offering a key the provider would never receive.
+ */
+const listRegistryAiKeyConnections = (db, userId) => __awaiter(void 0, void 0, void 0, function* () {
+    const rows = yield db
+        .select({ connectionId: schema_1.registryAiKeys.connectionId, encryptedKey: schema_1.registryAiKeys.encryptedKey })
+        .from(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, userId))
+        .orderBy(schema_1.registryAiKeys.connectionId);
+    return rows.filter((row) => (0, crypto_1.decryptSecret)(row.encryptedKey) !== null).map((row) => row.connectionId);
+});
+exports.listRegistryAiKeyConnections = listRegistryAiKeyConnections;
+/** Save or replace this reader's key for one connection. */
+const saveRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const encryptedKey = (0, crypto_1.encryptSecret)(input.key);
+    yield db
+        .insert(schema_1.registryAiKeys)
+        .values({ userId: input.userId, connectionId: input.connectionId, encryptedKey })
+        .onConflictDoUpdate({
+        target: [schema_1.registryAiKeys.userId, schema_1.registryAiKeys.connectionId],
+        set: { encryptedKey, updatedAt: new Date() },
+    });
+});
+exports.saveRegistryAiKey = saveRegistryAiKey;
+/** Remove this reader's key for one connection. Returns whether a row was there to remove. */
+const deleteRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const rows = yield db
+        .delete(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, input.userId), (0, drizzle_orm_1.eq)(schema_1.registryAiKeys.connectionId, input.connectionId)))
+        .returning({ connectionId: schema_1.registryAiKeys.connectionId });
+    return rows.length > 0;
+});
+exports.deleteRegistryAiKey = deleteRegistryAiKey;
+/**
+ * Read back one reader's key. A row that no longer decrypts reads as absent, so the reader is told
+ * to add a key rather than shown a provider error.
+ */
+const readRegistryAiKey = (db, input) => __awaiter(void 0, void 0, void 0, function* () {
+    const [row] = yield db
+        .select({ encryptedKey: schema_1.registryAiKeys.encryptedKey })
+        .from(schema_1.registryAiKeys)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.registryAiKeys.userId, input.userId), (0, drizzle_orm_1.eq)(schema_1.registryAiKeys.connectionId, input.connectionId)))
+        .limit(1);
+    return row ? (0, crypto_1.decryptSecret)(row.encryptedKey) : null;
+});
+exports.readRegistryAiKey = readRegistryAiKey;

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

@@ -2,3 +2,20 @@ export declare const hashSecret: (secret: string) => string;
 export declare const createOpaqueSecret: (byteLength?: number) => string;
 export declare const secretHashMatches: (secret: string, expectedHash: string) => boolean;
 export declare const normalizeEmail: (email: string) => string;
+/** Env var holding the deployment secret that reader-supplied AI keys are encrypted with. */
+export declare const AI_KEY_SECRET_ENV = "HANDOFF_AI_KEY_SECRET";
+/** Thrown when a key must be encrypted but the deployment secret is missing or too short. */
+export declare class MissingEncryptionSecretError extends Error {
+    constructor();
+}
+/**
+ * Encrypt a value that has to be read back, such as a reader's provider key. AES-256-GCM, with the
+ * salt, nonce and authentication tag carried in the payload so a row is self-describing.
+ */
+export declare const encryptSecret: (plaintext: string) => string;
+/**
+ * Decrypt a value written by {@link encryptSecret}. Returns `null` for anything that does not
+ * authenticate — a payload in another format, or one written under a secret that has since been
+ * rotated — so a stale row reads as "no key saved" instead of failing the request.
+ */
+export declare const decryptSecret: (payload: string) => string | null;

package/dist/registry/auth/crypto.js

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

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

@@ -1,6 +1,7 @@
 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 { AI_KEY_SECRET_ENV, MissingEncryptionSecretError, createOpaqueSecret, decryptSecret, encryptSecret, hashSecret, normalizeEmail, secretHashMatches, } from './crypto';
+export { deleteRegistryAiKey, listRegistryAiKeyConnections, readRegistryAiKey, saveRegistryAiKey } from './ai-keys';
 export { buildGravatarUrl } from './gravatar';
 export { authenticateRegistrySyncSecret, resolveRegistrySyncSecret, SYNC_SECRET_ENV } from './sync-secret';
 export { 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';

package/dist/registry/auth/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+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.saveRegistryAiKey = exports.readRegistryAiKey = exports.listRegistryAiKeyConnections = exports.deleteRegistryAiKey = exports.secretHashMatches = exports.normalizeEmail = exports.hashSecret = exports.encryptSecret = exports.decryptSecret = exports.createOpaqueSecret = exports.MissingEncryptionSecretError = exports.AI_KEY_SECRET_ENV = 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 = exports.getRegistryUserById = exports.hashRateLimitIdentifier = exports.purgeExpiredAuthRateLimits = exports.clearAuthRateLimit = exports.consumeAuthRateLimit = exports.MAXIMUM_PASSWORD_LENGTH = exports.MINIMUM_PASSWORD_LENGTH = exports.validatePassword = 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; } });
@@ -23,10 +23,19 @@ Object.defineProperty(exports, "resetPassword", { enumerable: true, get: functio
 Object.defineProperty(exports, "INVITATION_LIFETIME_MS", { enumerable: true, get: function () { return action_tokens_1.INVITATION_LIFETIME_MS; } });
 Object.defineProperty(exports, "PASSWORD_RESET_LIFETIME_MS", { enumerable: true, get: function () { return action_tokens_1.PASSWORD_RESET_LIFETIME_MS; } });
 var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "AI_KEY_SECRET_ENV", { enumerable: true, get: function () { return crypto_1.AI_KEY_SECRET_ENV; } });
+Object.defineProperty(exports, "MissingEncryptionSecretError", { enumerable: true, get: function () { return crypto_1.MissingEncryptionSecretError; } });
 Object.defineProperty(exports, "createOpaqueSecret", { enumerable: true, get: function () { return crypto_1.createOpaqueSecret; } });
+Object.defineProperty(exports, "decryptSecret", { enumerable: true, get: function () { return crypto_1.decryptSecret; } });
+Object.defineProperty(exports, "encryptSecret", { enumerable: true, get: function () { return crypto_1.encryptSecret; } });
 Object.defineProperty(exports, "hashSecret", { enumerable: true, get: function () { return crypto_1.hashSecret; } });
 Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: function () { return crypto_1.normalizeEmail; } });
 Object.defineProperty(exports, "secretHashMatches", { enumerable: true, get: function () { return crypto_1.secretHashMatches; } });
+var ai_keys_1 = require("./ai-keys");
+Object.defineProperty(exports, "deleteRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.deleteRegistryAiKey; } });
+Object.defineProperty(exports, "listRegistryAiKeyConnections", { enumerable: true, get: function () { return ai_keys_1.listRegistryAiKeyConnections; } });
+Object.defineProperty(exports, "readRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.readRegistryAiKey; } });
+Object.defineProperty(exports, "saveRegistryAiKey", { enumerable: true, get: function () { return ai_keys_1.saveRegistryAiKey; } });
 var gravatar_1 = require("./gravatar");
 Object.defineProperty(exports, "buildGravatarUrl", { enumerable: true, get: function () { return gravatar_1.buildGravatarUrl; } });
 var sync_secret_1 = require("./sync-secret");

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

@@ -6,7 +6,8 @@
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
  * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
- * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published. A
+ * new entity goes to the directory it was published from (`sourceDir`).
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an