handoff-app 2.0.0-8 → 2.0.0

package/dist/registry/db/driver.js

@@ -20,8 +20,8 @@ exports.DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
 exports.DEFAULT_REGISTRY_DRIVER = 'pg';
 /** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
 const resolveDatabaseUrlEnv = (config) => {
-    var _a, _b, _c, _d;
-    const configured = (_d = (_c = (_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.databaseUrl) === null || _c === void 0 ? void 0 : _c.$env) === null || _d === void 0 ? void 0 : _d.trim();
+    var _a, _b, _c, _d, _e;
+    const configured = (_e = (_d = (_c = (_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.database) === null || _c === void 0 ? void 0 : _c.url) === null || _d === void 0 ? void 0 : _d.$env) === null || _e === void 0 ? void 0 : _e.trim();
     return configured || exports.DEFAULT_DATABASE_URL_ENV;
 };
 exports.resolveDatabaseUrlEnv = resolveDatabaseUrlEnv;
@@ -43,7 +43,7 @@ const resolveRegistryDatabase = (config) => {
     const connectionString = (_a = process.env[databaseUrlEnv]) === null || _a === void 0 ? void 0 : _a.trim();
     if (!connectionString) {
         throw new Error(`Registry database URL is not configured. Set the "${databaseUrlEnv}" environment variable to a ` +
-            `PostgreSQL connection string (or change "runtime.registry.databaseUrl" to point at the env var you use).`);
+            `PostgreSQL connection string (or change "runtime.registry.database.url" to point at the env var you use).`);
     }
     return { driver, databaseUrlEnv, connectionString };
 };

package/dist/registry/db/schema.d.ts

@@ -24,8 +24,8 @@
 import type { ArtifactBuildStatus, ArtifactKind, ArtifactOwnerKind, ArtifactReference } from '../../artifacts/types';
 import type { RegistryTextFileKind } from '../../store/types';
 import type { TokenSetKind } from '../tokens/sets';
-/** Where an asset blob's bytes physically live: the default DB adapter, Vercel Blob, or a custom id. */
-export type AssetStorageProvider = 'database' | 'vercel-blob' | (string & {});
+/** Where an asset blob's bytes live: inline in the database (`database`) or in a custom provider (`custom`). */
+export type AssetStorageProvider = 'database' | 'custom';
 import type { ComponentListObject, PageListObject, PatternComponentEntry, PatternListObject } from '../../transformers/preview/types';
 /** Registry account role. Administrators may issue write-scoped credentials. */
 export type RegistryUserRole = 'admin' | 'member';
@@ -248,6 +248,23 @@ export declare const components: import("drizzle-orm/pg-core").PgTableWithColumn
         }, {}, {
             $type: string[];
         }>;
+        sourceDir: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_dir";
+            tableName: "components";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         record: import("drizzle-orm/pg-core").PgColumn<{
             name: "record";
             tableName: "components";
@@ -603,6 +620,23 @@ export declare const patterns: import("drizzle-orm/pg-core").PgTableWithColumns<
         }, {}, {
             $type: PatternComponentEntry[];
         }>;
+        sourceDir: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_dir";
+            tableName: "patterns";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         record: import("drizzle-orm/pg-core").PgColumn<{
             name: "record";
             tableName: "patterns";
@@ -2405,7 +2439,7 @@ export declare const assets: import("drizzle-orm/pg-core").PgTableWithColumns<{
 /**
  * Content-addressed binary blob store, shared across assets/collections (the `hash` is the blob
  * identity, so an unchanged file re-references the same row). Exactly one location is active per row:
- * inline `content` (bytea, default DB adapter) or an external `storageRef` resolved through the
+ * inline `content` (bytea, default `database` provider) or an external `storageRef` resolved through the
  * recorded `storageProvider`. Both nullable so DB- and object-backed blobs coexist.
  */
 export declare const assetBlobs: import("drizzle-orm/pg-core").PgTableWithColumns<{
@@ -3310,6 +3344,104 @@ export declare const registryDeviceAuthorizations: import("drizzle-orm/pg-core")
     };
     dialect: "pg";
 }>;
+/**
+ * One reader's key for one declared AI connection. Unlike every other credential here the value
+ * must be recoverable, because it is sent to the provider on that reader's behalf, so it is
+ * encrypted rather than hashed (see `../auth/crypto`). A row whose `connectionId` no longer appears
+ * in the config is ignored, not deleted: the connection may come back on the next deploy.
+ */
+export declare const registryAiKeys: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "registry_ai_keys";
+    schema: undefined;
+    columns: {
+        userId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "user_id";
+            tableName: "registry_ai_keys";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        connectionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "connection_id";
+            tableName: "registry_ai_keys";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        encryptedKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "encrypted_key";
+            tableName: "registry_ai_keys";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "registry_ai_keys";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "registry_ai_keys";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 /**
  * Fixed-window throttling counters. Callers pass a hash of the identifying value so raw emails and
  * IP addresses are not retained.
@@ -3605,6 +3737,23 @@ export declare const registrySchema: {
             }, {}, {
                 $type: string[];
             }>;
+            sourceDir: import("drizzle-orm/pg-core").PgColumn<{
+                name: "source_dir";
+                tableName: "components";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             record: import("drizzle-orm/pg-core").PgColumn<{
                 name: "record";
                 tableName: "components";
@@ -3952,6 +4101,23 @@ export declare const registrySchema: {
             }, {}, {
                 $type: PatternComponentEntry[];
             }>;
+            sourceDir: import("drizzle-orm/pg-core").PgColumn<{
+                name: "source_dir";
+                tableName: "patterns";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             record: import("drizzle-orm/pg-core").PgColumn<{
                 name: "record";
                 tableName: "patterns";
@@ -6413,6 +6579,98 @@ export declare const registrySchema: {
         };
         dialect: "pg";
     }>;
+    registryAiKeys: import("drizzle-orm/pg-core").PgTableWithColumns<{
+        name: "registry_ai_keys";
+        schema: undefined;
+        columns: {
+            userId: import("drizzle-orm/pg-core").PgColumn<{
+                name: "user_id";
+                tableName: "registry_ai_keys";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            connectionId: import("drizzle-orm/pg-core").PgColumn<{
+                name: "connection_id";
+                tableName: "registry_ai_keys";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            encryptedKey: import("drizzle-orm/pg-core").PgColumn<{
+                name: "encrypted_key";
+                tableName: "registry_ai_keys";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            createdAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "created_at";
+                tableName: "registry_ai_keys";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "updated_at";
+                tableName: "registry_ai_keys";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+        };
+        dialect: "pg";
+    }>;
     registryDeviceAuthorizations: import("drizzle-orm/pg-core").PgTableWithColumns<{
         name: "registry_device_authorizations";
         schema: undefined;

package/dist/registry/db/schema.js

@@ -23,12 +23,12 @@
  *   storage of large/binary assets (a content-reference field) rather than assuming inline content.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registrySchema = exports.registryAuthRateLimits = exports.registryDeviceAuthorizations = exports.registryAccessTokens = exports.registryAuthActionTokens = exports.registryInstallations = exports.registryUsers = exports.assetBlobs = exports.assets = exports.assetCollections = exports.tokenArtifacts = exports.tokenSets = exports.buildMetadata = exports.docsArtifacts = exports.pageFiles = exports.pages = exports.patternFiles = exports.patterns = exports.componentFiles = exports.components = void 0;
+exports.registrySchema = exports.registryAuthRateLimits = exports.registryAiKeys = exports.registryDeviceAuthorizations = exports.registryAccessTokens = exports.registryAuthActionTokens = exports.registryInstallations = exports.registryUsers = exports.assetBlobs = exports.assets = exports.assetCollections = exports.tokenArtifacts = exports.tokenSets = exports.buildMetadata = exports.docsArtifacts = exports.pageFiles = exports.pages = exports.patternFiles = exports.patterns = exports.componentFiles = exports.components = void 0;
 const drizzle_orm_1 = require("drizzle-orm");
 const pg_core_1 = require("drizzle-orm/pg-core");
 /**
  * PostgreSQL `bytea` column. Drizzle pg-core has no built-in binary type, so declare it once here.
- * Reads/writes are Node `Buffer`s. The default asset storage adapter keeps small/ordinary asset
+ * Reads/writes are Node `Buffer`s. The default asset storage provider keeps small/ordinary asset
  * bytes inline in this column; larger assets are offloaded to an object-storage `storageRef` instead.
  */
 const bytea = (0, pg_core_1.customType)({
@@ -55,6 +55,8 @@ exports.components = (0, pg_core_1.pgTable)('components', {
     sourceFormat: (0, pg_core_1.text)('source_format'),
     tags: (0, pg_core_1.jsonb)('tags').$type(),
     categories: (0, pg_core_1.jsonb)('categories').$type(),
+    /** Workspace-relative directory the component was published from. */
+    sourceDir: (0, pg_core_1.text)('source_dir'),
     /** Full normalized component record. */
     record: (0, pg_core_1.jsonb)('record').$type().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -98,6 +100,8 @@ exports.patterns = (0, pg_core_1.pgTable)('patterns', {
     tags: (0, pg_core_1.jsonb)('tags').$type(),
     /** Pattern component references. */
     components: (0, pg_core_1.jsonb)('components').$type(),
+    /** Workspace-relative directory the pattern was published from. */
+    sourceDir: (0, pg_core_1.text)('source_dir'),
     /** Full normalized pattern record. */
     record: (0, pg_core_1.jsonb)('record').$type().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -317,13 +321,13 @@ exports.assets = (0, pg_core_1.pgTable)('assets', {
 /**
  * Content-addressed binary blob store, shared across assets/collections (the `hash` is the blob
  * identity, so an unchanged file re-references the same row). Exactly one location is active per row:
- * inline `content` (bytea, default DB adapter) or an external `storageRef` resolved through the
+ * inline `content` (bytea, default `database` provider) or an external `storageRef` resolved through the
  * recorded `storageProvider`. Both nullable so DB- and object-backed blobs coexist.
  */
 exports.assetBlobs = (0, pg_core_1.pgTable)('asset_blobs', {
     /** SHA-256 of the blob bytes (hex). */
     hash: (0, pg_core_1.text)('hash').primaryKey(),
-    /** Which storage backed this blob when it was written (`database`|`vercel-blob`|custom id). */
+    /** Which storage backed this blob when it was written (`database`|custom id). */
     storageProvider: (0, pg_core_1.text)('storage_provider').$type().notNull(),
     /** Inline bytes; null when stored externally via `storageRef`. */
     content: bytea('content'),
@@ -435,6 +439,26 @@ exports.registryDeviceAuthorizations = (0, pg_core_1.pgTable)('registry_device_a
     (0, pg_core_1.check)('registry_device_authorizations_status_valid', (0, drizzle_orm_1.sql) `${table.status} in ('pending', 'approved', 'denied', 'consumed')`),
     (0, pg_core_1.check)('registry_device_authorizations_scopes_array', (0, drizzle_orm_1.sql) `jsonb_typeof(${table.scopes}) = 'array'`),
 ]);
+/**
+ * One reader's key for one declared AI connection. Unlike every other credential here the value
+ * must be recoverable, because it is sent to the provider on that reader's behalf, so it is
+ * encrypted rather than hashed (see `../auth/crypto`). A row whose `connectionId` no longer appears
+ * in the config is ignored, not deleted: the connection may come back on the next deploy.
+ */
+exports.registryAiKeys = (0, pg_core_1.pgTable)('registry_ai_keys', {
+    userId: (0, pg_core_1.text)('user_id')
+        .notNull()
+        .references(() => exports.registryUsers.id, { onDelete: 'cascade' }),
+    /** Id of the connection the config declares. Never a reader-supplied endpoint. */
+    connectionId: (0, pg_core_1.text)('connection_id').notNull(),
+    /** Self-describing AES-256-GCM payload; the deployment secret it is keyed from is never stored. */
+    encryptedKey: (0, pg_core_1.text)('encrypted_key').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    (0, pg_core_1.primaryKey)({ columns: [table.userId, table.connectionId] }),
+    (0, pg_core_1.check)('registry_ai_keys_connection_not_blank', (0, drizzle_orm_1.sql) `length(btrim(${table.connectionId})) > 0`),
+]);
 /**
  * Fixed-window throttling counters. Callers pass a hash of the identifying value so raw emails and
  * IP addresses are not retained.
@@ -471,6 +495,7 @@ exports.registrySchema = {
     registryInstallations: exports.registryInstallations,
     registryAuthActionTokens: exports.registryAuthActionTokens,
     registryAccessTokens: exports.registryAccessTokens,
+    registryAiKeys: exports.registryAiKeys,
     registryDeviceAuthorizations: exports.registryDeviceAuthorizations,
     registryAuthRateLimits: exports.registryAuthRateLimits,
 };

package/dist/registry/email/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed identity helper for custom email providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points `runtime.registry.email.module`
+ * at it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => EmailProvider` when it needs its options or env.
+ */
+import type { EmailProvider, EmailProviderFactory } from './types';
+export declare function defineEmailProvider(provider: EmailProvider): EmailProvider;
+export declare function defineEmailProvider(factory: EmailProviderFactory): EmailProviderFactory;

package/dist/registry/email/define.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Typed identity helper for custom email providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points `runtime.registry.email.module`
+ * at it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => EmailProvider` when it needs its options or env.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEmailProvider = defineEmailProvider;
+function defineEmailProvider(input) {
+    return input;
+}

package/dist/registry/email/providers/smtp.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Built-in SMTP provider, selected with `runtime.registry.email.provider: "smtp"`.
+ *
+ * `nodemailer` is loaded lazily so it is only pulled into memory (and traced into the registry
+ * bundle) when this provider is selected. Options may come from environment variables, so numbers
+ * and booleans can arrive as strings.
+ */
+import type { EmailProvider } from '../types';
+/** Build an SMTP provider from options whose references are already resolved. */
+export declare const createSmtpProvider: (options: Record<string, unknown>) => EmailProvider;

package/dist/registry/email/providers/smtp.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Built-in SMTP provider, selected with `runtime.registry.email.provider: "smtp"`.
+ *
+ * `nodemailer` is loaded lazily so it is only pulled into memory (and traced into the registry
+ * bundle) when this provider is selected. Options may come from environment variables, so numbers
+ * and booleans can arrive as strings.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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.createSmtpProvider = void 0;
+const toNumber = (value) => {
+    const number = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+    return Number.isFinite(number) ? number : undefined;
+};
+const toBoolean = (value) => typeof value === 'boolean' ? value : typeof value === 'string' && value.trim() ? value.trim() === 'true' : undefined;
+/** Build an SMTP provider from options whose references are already resolved. */
+const createSmtpProvider = (options) => {
+    var _a;
+    const host = typeof options.host === 'string' ? options.host : '';
+    const configuredPort = toNumber(options.port);
+    const secure = (_a = toBoolean(options.secure)) !== null && _a !== void 0 ? _a : (configuredPort === undefined || configuredPort === 465);
+    const port = configuredPort !== null && configuredPort !== void 0 ? configuredPort : (secure ? 465 : 587);
+    const user = typeof options.user === 'string' ? options.user : undefined;
+    const password = typeof options.password === 'string' ? options.password : undefined;
+    return {
+        send(_a) {
+            return __awaiter(this, arguments, void 0, function* ({ from, to, subject, html, text }) {
+                var _b;
+                if (!host)
+                    throw new Error('The SMTP host is not set.');
+                const { createTransport } = yield Promise.resolve().then(() => __importStar(require('nodemailer')));
+                const transport = createTransport({ host, port, secure, auth: user ? { user, pass: password } : undefined });
+                const info = yield transport.sendMail({ from, to, subject, html, text });
+                if ((_b = info.rejected) === null || _b === void 0 ? void 0 : _b.length) {
+                    throw new Error(`The SMTP server rejected the recipient: ${info.response}`);
+                }
+            });
+        },
+    };
+};
+exports.createSmtpProvider = createSmtpProvider;

package/dist/registry/email/resolve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Registry email settings resolution.
+ *
+ * `runtime.registry.email.provider` selects the built-in `smtp` provider or a `custom` module. Without
+ * an email block, email delivery is off. 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.
+ */
+import type { ResolvedConfig } from '../../types/config';
+export type EmailProviderKind = 'smtp' | 'custom';
+/** Email settings as they are baked: literals and `{ $env }` references, never secret values. */
+export interface EmailSettings {
+    from?: string;
+    /** Unset when the config has no email block. */
+    provider?: EmailProviderKind;
+    /** For `custom`: the server-only provider module path. */
+    module?: string;
+    options: Record<string, unknown>;
+}
+/** Resolve and validate the email block from a loaded config (CLI/build side). An unusable block fails the build. */
+export declare const resolveEmailFromConfig: (config: ResolvedConfig | null | undefined) => EmailSettings;
+/** Read baked settings back leniently (server side): a malformed value must not take the server down. */
+export declare const parseEmailSettings: (raw: {
+    from?: unknown;
+    provider?: unknown;
+    module?: unknown;
+    options?: unknown;
+}) => EmailSettings;

package/dist/registry/email/resolve.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Registry email settings resolution.
+ *
+ * `runtime.registry.email.provider` selects the built-in `smtp` provider or a `custom` module. Without
+ * an email block, email delivery is off. 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEmailSettings = exports.resolveEmailFromConfig = void 0;
+const errors_1 = require("../../config/errors");
+const PROVIDERS = ['smtp', 'custom'];
+/** The options each built-in provider accepts. A custom provider accepts any. */
+const BUILT_IN_OPTIONS = {
+    smtp: ['host', 'port', 'secure', 'user', 'password'],
+};
+const isPlainRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Resolve and validate the email block from a loaded config (CLI/build side). An unusable block fails the build. */
+const resolveEmailFromConfig = (config) => {
+    var _a, _b, _c;
+    const email = (_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.email;
+    const fail = (problem) => {
+        throw new errors_1.HandoffConfigError(`Config "runtime.registry.email": ${problem}`);
+    };
+    if (email === undefined)
+        return { options: {} };
+    const provider = email.provider;
+    if (!PROVIDERS.includes(provider)) {
+        fail(email.provider === undefined
+            ? '"provider" is required. Use "smtp" or "custom".'
+            : `unknown provider ${JSON.stringify(provider)}. Use "smtp" or "custom".`);
+    }
+    if (email.options !== undefined && !isPlainRecord(email.options)) {
+        fail('"options" must be an object.');
+    }
+    const options = Object.assign({}, ((_c = email.options) !== null && _c !== void 0 ? _c : {}));
+    const module = typeof email.module === 'string' ? email.module.trim() : undefined;
+    if (provider === 'custom') {
+        if (!module)
+            fail('provider "custom" needs a "module" that default-exports a defineEmailProvider() result.');
+    }
+    else {
+        if (email.module !== undefined)
+            fail(`"module" is used only by provider "custom", not "${provider}".`);
+        const allowed = BUILT_IN_OPTIONS[provider];
+        const unknown = Object.keys(options).filter((key) => !allowed.includes(key));
+        if (unknown.length > 0) {
+            fail(`provider "${provider}" does not support ${unknown.map((key) => `"options.${key}"`).join(', ')}. ` +
+                `Use ${allowed.map((key) => `"${key}"`).join(', ')}.`);
+        }
+    }
+    if (provider === 'smtp' && options.host === undefined)
+        fail('provider "smtp" needs "options.host".');
+    const from = typeof email.from === 'string' ? email.from.trim() || undefined : undefined;
+    return Object.assign(Object.assign({ from, provider }, (module ? { module } : {})), { options });
+};
+exports.resolveEmailFromConfig = resolveEmailFromConfig;
+/** Read baked settings back leniently (server side): a malformed value must not take the server down. */
+const parseEmailSettings = (raw) => {
+    let options = raw.options;
+    if (typeof options === 'string') {
+        try {
+            options = options.trim() ? JSON.parse(options) : {};
+        }
+        catch (_a) {
+            options = {};
+        }
+    }
+    const provider = PROVIDERS.find((kind) => kind === raw.provider);
+    const module = typeof raw.module === 'string' ? raw.module.trim() : '';
+    return Object.assign(Object.assign(Object.assign({ from: typeof raw.from === 'string' ? raw.from.trim() || undefined : undefined }, (provider ? { provider } : {})), (module ? { module } : {})), { options: isPlainRecord(options) ? options : {} });
+};
+exports.parseEmailSettings = parseEmailSettings;

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

@@ -0,0 +1,24 @@
+/**
+ * Server-only email provider contract. Handoff renders every message, and a provider only delivers it.
+ * SMTP is built in. Anything else is a {@link defineEmailProvider} module.
+ */
+/** One rendered message. */
+export interface EmailMessage {
+    from: string;
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+}
+/** The pluggable provider contract. `send` throws when the message is not accepted for delivery. */
+export interface EmailProvider {
+    send(message: EmailMessage): Promise<void>;
+}
+/** Context passed to a provider factory. */
+export interface EmailProviderContext {
+    /** `runtime.registry.email.options`, with environment references resolved to their values. */
+    options: Record<string, unknown>;
+    env: NodeJS.ProcessEnv;
+}
+/** A custom provider may export the provider directly or a factory that builds it from its context. */
+export type EmailProviderFactory = (context: EmailProviderContext) => EmailProvider | Promise<EmailProvider>;