handoff-app 2.0.0-8 → 2.0.0

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

@@ -2,74 +2,75 @@
  * 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 { HandoffConfigError } from '../../config/errors';
 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 const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind = 'database';
+const PROVIDERS: readonly AssetStorageProvider[] = ['database', 'custom'];
 
-/** Default env-var name holding the Vercel Blob read/write token. */
-export const DEFAULT_BLOB_TOKEN_ENV = 'BLOB_READ_WRITE_TOKEN';
+export const DEFAULT_ASSET_STORAGE_PROVIDER: AssetStorageProvider = 'database';
 
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 export const DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
 
 /** 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>;
 }
 
-/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
-const customProviderId = (options: Record<string, unknown>): AssetStorageProvider => {
-  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. */
 export const resolveAssetStorageSettings = (settings: AssetStorageSettings | null | undefined): ResolvedAssetStorage => {
-  const adapterKind = settings?.adapter ?? DEFAULT_ASSET_STORAGE_ADAPTER;
+  const provider = settings?.provider ?? DEFAULT_ASSET_STORAGE_PROVIDER;
   const options = settings?.options ?? {};
-  const tokenEnv = settings?.tokenEnv?.trim() || DEFAULT_BLOB_TOKEN_ENV;
   const maxInlineBytes =
     typeof settings?.maxInlineBytes === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : DEFAULT_MAX_INLINE_BYTES;
 
-  const provider: AssetStorageProvider =
-    adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
-
-  return { adapterKind, provider, module: settings?.module?.trim() || undefined, tokenEnv, maxInlineBytes, options };
+  return { provider, module: settings?.module?.trim() || undefined, maxInlineBytes, options };
 };
 
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
-export const resolveAssetStorageFromConfig = (config: ResolvedConfig | null | undefined): ResolvedAssetStorage =>
-  resolveAssetStorageSettings({
-    ...config?.runtime?.registry?.assetStorage,
-    tokenEnv: config?.runtime?.registry?.assetStorage?.token?.$env,
-  });
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
+export const resolveAssetStorageFromConfig = (config: ResolvedConfig | null | undefined): ResolvedAssetStorage => {
+  const settings = config?.runtime?.registry?.assetStorage as Record<string, unknown> | undefined;
+  const fail = (problem: string): never => {
+    throw new HandoffConfigError(`Config "runtime.registry.assetStorage": ${problem}`);
+  };
+
+  const provider = settings?.provider ?? DEFAULT_ASSET_STORAGE_PROVIDER;
+  if (!PROVIDERS.includes(provider as AssetStorageProvider)) {
+    fail(`unknown provider ${JSON.stringify(provider)}. Use "database" or "custom".`);
+  }
+  const options = settings?.options;
+  if (options !== undefined && (options === null || typeof options !== 'object' || Array.isArray(options))) {
+    fail('"options" must be an object.');
+  }
+  const module = 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?.maxInlineBytes;
+  if (maxInlineBytes !== undefined && (typeof maxInlineBytes !== 'number' || !Number.isInteger(maxInlineBytes) || maxInlineBytes <= 0)) {
+    fail('"maxInlineBytes" must be a positive whole number.');
+  }
+
+  return resolveAssetStorageSettings(settings as AssetStorageSettings | undefined);
+};

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

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

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

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

package/src/registry/auth/crypto.ts

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

package/src/registry/auth/index.ts

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