@data-club/ai-hub-server 0.0.1

package/dist/auth/roleRules.js

@@ -0,0 +1,365 @@
+/**
+ * Shield + min-count rules + the transactional helpers that compose them.
+ *
+ * Three concerns live here:
+ *
+ * 1. **Role hierarchy** — a tiny `ROLE_RANK` map + `hasRoleAtLeast` used by the
+ *    middleware to drive §8.2 matrix checks.
+ * 2. **Pure assertion helpers** — `assertCanChangeUserRole`,
+ *    `assertCanResetPassword`, `assertCanDeleteUser`. Each throws
+ *    `RoleRuleError` on a §8.1 shield or super-admin-min-count violation.
+ *    Pure functions of `(caller, target, newState, totalSuperAdmins)` so they
+ *    are trivial to unit-test against every cell.
+ * 3. **Transactional appliers** — `applyUserRoleChangeInTx`,
+ *    `applyPasswordResetInTx` (signature only; Step 4 wires the password
+ *    write), `applyUserDeletionInTx`. Each opens one SQLite transaction,
+ *    re-reads the target row + super-admin count inside the transaction so a
+ *    concurrent demote cannot bypass the invariant, calls the matching
+ *    assertion helper, then applies the write. Returns a discriminated
+ *    `{ ok: true, ... } | { ok: false, status, code, message }` so the
+ *    Step-4 handler maps it directly into a `Response`.
+ *
+ * Step 3 ships the helpers + extensive tests; Step 4 is the first endpoint
+ * that consumes them.
+ *
+ * @see SPECIFICATIONS.md §8.1 — role model + shield + min-count rules
+ * @see SPECIFICATIONS.md §8.5 — password reset
+ * @see SPECIFICATIONS.md §8.6 — endpoint enforcement order
+ */
+import { eq, sql } from "drizzle-orm";
+import { user } from "../db/schema.js";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Role hierarchy                                                            */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Role ordering — least → most privileged. Authoritative for any
+ * "is this role at least as privileged as X" comparison.
+ *
+ * @see SPECIFICATIONS.md §8.1
+ */
+export const ROLE_HIERARCHY = [
+    "user",
+    "power_user",
+    "admin",
+    "super_admin",
+];
+/**
+ * Rank within the hierarchy — higher = more privileged. Driven by
+ * `ROLE_HIERARCHY` so a future role addition is one constant change.
+ *
+ * @see SPECIFICATIONS.md §8.1
+ */
+export const ROLE_RANK = Object.freeze({
+    user: 0,
+    power_user: 1,
+    admin: 2,
+    super_admin: 3,
+});
+/**
+ * Returns `true` if `actual` is at least as privileged as `required`. Used by
+ * the role-enforcement middleware to gate every protected endpoint per the
+ * §8.2 matrix.
+ *
+ * @param actual - the role the caller's JWT carries.
+ * @param required - the minimum role the endpoint requires.
+ * @returns `true` if `actual >= required` in the hierarchy.
+ */
+export function hasRoleAtLeast(actual, required) {
+    return ROLE_RANK[actual] >= ROLE_RANK[required];
+}
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Error type                                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Thrown by the assertion helpers below. The transactional helpers catch
+ * `RoleRuleError`s and translate them into the `{ ok: false, ... }` return
+ * shape; raw throws are reserved for unexpected programmer errors.
+ */
+export class RoleRuleError extends Error {
+    /** HTTP status the caller should return (typically 403, sometimes 404). */
+    status;
+    /** Machine-readable code matching the §7.5 `AIHubError` codes. */
+    code;
+    /**
+     * @param status - HTTP status code to surface.
+     * @param code - machine-readable code.
+     * @param message - human-readable description.
+     */
+    constructor(status, code, message) {
+        super(message);
+        this.name = "RoleRuleError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Asserts a role-change is allowed under the §8.1 shield + min-count rules.
+ *
+ * The rules in plain English:
+ *
+ * - **Only `super_admin` can demote the last `super_admin`** — min-count rule.
+ *   Applies regardless of who the caller is (including the super_admin's own
+ *   self-demote when they are the only one).
+ * - **Only `super_admin` can promote anyone to `super_admin`**.
+ * - **`admin` callers can only mutate `user` / `power_user` targets** — they
+ *   cannot change the role of another `admin` or a `super_admin` (including
+ *   themselves — we block all admin-touches-admin, by an explicit decision
+ *   recorded in the Step-3 prompt).
+ * - **`power_user` and `user` cannot change any role** — the matrix gates
+ *   that at the endpoint level, but we double-check here so the helper is
+ *   safe to call from anywhere.
+ *
+ * @param caller - the caller's id + current role.
+ * @param target - the target user row (loaded inside the same transaction).
+ * @param newRole - the requested new role for `target`.
+ * @param totalSuperAdmins - count of super-admin rows in the DB, read inside
+ *   the same transaction so a concurrent demote can't bypass the rule.
+ * @throws {RoleRuleError} when the requested change violates any rule.
+ */
+export function assertCanChangeUserRole(caller, target, newRole, totalSuperAdmins) {
+    // Min-count rule first — it applies regardless of caller role.
+    if (target.role === "super_admin" &&
+        newRole !== "super_admin" &&
+        totalSuperAdmins <= 1) {
+        throw new RoleRuleError(403, "forbidden", "Cannot demote the only remaining super_admin.");
+    }
+    if (caller.role === "super_admin") {
+        // Super-admin can do anything subject to the min-count rule above.
+        return;
+    }
+    if (caller.role === "admin") {
+        // Admin cannot promote anyone to super_admin.
+        if (newRole === "super_admin") {
+            throw new RoleRuleError(403, "forbidden", "Only super_admin can promote a user to super_admin.");
+        }
+        // Shield rule: admin cannot touch admin or super_admin targets — including
+        // themselves (per the Step-3 prompt decision).
+        if (target.role === "admin" || target.role === "super_admin") {
+            throw new RoleRuleError(403, "forbidden", "Only super_admin can change the role of an admin or super_admin.");
+        }
+        return;
+    }
+    // power_user and user cannot change roles at all.
+    throw new RoleRuleError(403, "forbidden", "Only admin and super_admin can change user roles.");
+}
+/**
+ * Asserts a password reset is allowed under the §8.1 shield + min-count rules.
+ *
+ * - `admin` cannot reset another `admin`'s or any `super_admin`'s password
+ *   (shield rule).
+ * - Cannot reset the only `super_admin`'s password — would amount to
+ *   demotion (min-count rule, §8.5).
+ *
+ * @param caller - the caller's id + current role.
+ * @param target - the target user row.
+ * @param totalSuperAdmins - count of super-admin rows read inside the same
+ *   transaction.
+ * @throws {RoleRuleError} on shield or min-count violation.
+ */
+export function assertCanResetPassword(caller, target, totalSuperAdmins) {
+    if (caller.role === "super_admin") {
+        // Min-count: cannot reset the only super_admin's password.
+        if (target.role === "super_admin" && totalSuperAdmins <= 1) {
+            throw new RoleRuleError(403, "forbidden", "Cannot reset the only remaining super_admin's password.");
+        }
+        return;
+    }
+    if (caller.role === "admin") {
+        if (target.role === "admin" || target.role === "super_admin") {
+            throw new RoleRuleError(403, "forbidden", "Only super_admin can reset the password of an admin or super_admin.");
+        }
+        return;
+    }
+    throw new RoleRuleError(403, "forbidden", "Only admin and super_admin can reset passwords.");
+}
+/**
+ * Asserts a user deletion is allowed under the §8.1 shield + min-count rules.
+ *
+ * Same shape as `assertCanResetPassword`:
+ *
+ * - `admin` cannot delete another `admin` or any `super_admin`.
+ * - Cannot delete the only `super_admin`.
+ *
+ * @param caller - the caller's id + current role.
+ * @param target - the target user row.
+ * @param totalSuperAdmins - count of super-admin rows read inside the same
+ *   transaction.
+ * @throws {RoleRuleError} on shield or min-count violation.
+ */
+export function assertCanDeleteUser(caller, target, totalSuperAdmins) {
+    if (caller.role === "super_admin") {
+        if (target.role === "super_admin" && totalSuperAdmins <= 1) {
+            throw new RoleRuleError(403, "forbidden", "Cannot delete the only remaining super_admin.");
+        }
+        return;
+    }
+    if (caller.role === "admin") {
+        if (target.role === "admin" || target.role === "super_admin") {
+            throw new RoleRuleError(403, "forbidden", "Only super_admin can delete an admin or super_admin.");
+        }
+        return;
+    }
+    throw new RoleRuleError(403, "forbidden", "Only admin and super_admin can delete users.");
+}
+/**
+ * Counts super-admin rows through `tx`. Reads inside whatever transaction
+ * the caller is in.
+ *
+ * @param tx - any handle that can run a Drizzle `select` against `user`.
+ * @returns the integer count.
+ */
+function countSuperAdmins(tx) {
+    const row = tx
+        .select({ c: sql `count(*)`.as("c") })
+        .from(user)
+        .where(eq(user.role, "super_admin"))
+        .get();
+    return Number(row?.c ?? 0);
+}
+/**
+ * Applies a role change inside one SQLite transaction.
+ *
+ * Reads the target row + super-admin count inside the transaction so that a
+ * racing demote cannot win against the min-count rule. The Drizzle
+ * `db.transaction(fn)` API runs `fn` synchronously inside `BEGIN` / `COMMIT`;
+ * any thrown error inside `fn` triggers a `ROLLBACK` automatically.
+ *
+ * @param db - Drizzle client (the caller passes `ctx.db`; the helper opens
+ *   its own transaction internally).
+ * @param caller - caller's id + role.
+ * @param targetId - the user whose role is being changed.
+ * @param newRole - the new role.
+ * @returns the updated row on success, or an error result.
+ */
+export function applyUserRoleChangeInTx(db, caller, targetId, newRole) {
+    try {
+        return db.transaction((tx) => {
+            const target = tx
+                .select()
+                .from(user)
+                .where(eq(user.id, targetId))
+                .get();
+            if (!target) {
+                throw new RoleRuleError(404, "not_found", "User not found.");
+            }
+            const count = countSuperAdmins(tx);
+            assertCanChangeUserRole(caller, target, newRole, count);
+            tx
+                .update(user)
+                .set({ role: newRole, updatedAt: nowIso() })
+                .where(eq(user.id, targetId))
+                .run();
+            const updated = tx
+                .select()
+                .from(user)
+                .where(eq(user.id, targetId))
+                .get();
+            if (!updated) {
+                // Should be impossible — we just updated.
+                throw new RoleRuleError(500, "internal", "User vanished mid-transaction.");
+            }
+            return { ok: true, data: { updated } };
+        });
+    }
+    catch (err) {
+        if (err instanceof RoleRuleError) {
+            return {
+                ok: false,
+                status: err.status,
+                code: err.code,
+                message: err.message,
+            };
+        }
+        throw err;
+    }
+}
+/**
+ * Applies a user deletion inside one SQLite transaction. Same shape as
+ * `applyUserRoleChangeInTx` but DELETEs rather than UPDATEs.
+ *
+ * @param db - Drizzle client.
+ * @param caller - caller's id + role.
+ * @param targetId - the user to delete.
+ * @returns `{ ok: true, data: { deleted: <row before delete> } }` on success.
+ */
+export function applyUserDeletionInTx(db, caller, targetId) {
+    try {
+        return db.transaction((tx) => {
+            const target = tx
+                .select()
+                .from(user)
+                .where(eq(user.id, targetId))
+                .get();
+            if (!target) {
+                throw new RoleRuleError(404, "not_found", "User not found.");
+            }
+            const count = countSuperAdmins(tx);
+            assertCanDeleteUser(caller, target, count);
+            tx.delete(user).where(eq(user.id, targetId)).run();
+            return { ok: true, data: { deleted: target } };
+        });
+    }
+    catch (err) {
+        if (err instanceof RoleRuleError) {
+            return {
+                ok: false,
+                status: err.status,
+                code: err.code,
+                message: err.message,
+            };
+        }
+        throw err;
+    }
+}
+/**
+ * Runs the password-reset assertion inside a transaction and yields the
+ * fresh target row. The caller (Step 4's `POST /admin/users/{id}/reset-password`
+ * handler) generates the new password, hashes it, and writes inside the
+ * same transaction — this helper exposes the read-and-assert plumbing so
+ * the write can happen alongside.
+ *
+ * The shape is slightly different from the role-change / delete helpers
+ * because the password generation + hashing is async (Argon2) and cannot
+ * happen inside better-sqlite3's synchronous transaction. The Step-4 handler
+ * will run this helper first (to validate + lock-read), then write outside
+ * the transaction. The risk of a concurrent role-change is small but real;
+ * Step 4 can re-verify after the write or accept the tiny window.
+ *
+ * @param db - Drizzle client.
+ * @param caller - caller's id + role.
+ * @param targetId - the user whose password is being reset.
+ * @returns the target row on success, or an error result.
+ */
+export function assertPasswordResetInTx(db, caller, targetId) {
+    try {
+        return db.transaction((tx) => {
+            const target = tx
+                .select()
+                .from(user)
+                .where(eq(user.id, targetId))
+                .get();
+            if (!target) {
+                throw new RoleRuleError(404, "not_found", "User not found.");
+            }
+            const count = countSuperAdmins(tx);
+            assertCanResetPassword(caller, target, count);
+            return { ok: true, data: { target } };
+        });
+    }
+    catch (err) {
+        if (err instanceof RoleRuleError) {
+            return {
+                ok: false,
+                status: err.status,
+                code: err.code,
+                message: err.message,
+            };
+        }
+        throw err;
+    }
+}
+/** Returns the current ISO-8601 timestamp with millisecond precision. */
+function nowIso() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=roleRules.js.map

package/dist/auth/roleRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roleRules.js","sourceRoot":"","sources":["../../src/auth/roleRules.ts"],"names":[],"mappings":"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"}

package/dist/auth/userView.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Builds the `{ user, deployment }` envelope returned by `/auth/me`,
+ * `/auth/me/preferences`, and embedded in `/auth/login`'s response.
+ *
+ * Two non-obvious concerns this module owns:
+ *
+ * 1. **Per-user vs. per-deployment split.** `user` carries strictly per-user
+ *    fields (id, username, role, theme_preference, …); `deployment` carries
+ *    strictly per-deployment fields (theme_default, theme_switcher_enabled,
+ *    letta_ade_url). The split makes it impossible for a client to confuse
+ *    "this is my preference" with "this is how the deployment is configured."
+ * 2. **Role-gated `letta_ade_url`.** The URL is only included for callers
+ *    with role `power_user` or higher (§6.3.4). For `user`-role callers it's
+ *    omitted entirely (not set to null) so the React client cannot render
+ *    a link element it shouldn't see.
+ *
+ * The resolved theme is **not** computed here — the client does the simple
+ * precedence calculation client-side from `user.theme_preference +
+ * deployment.{theme_default, theme_switcher_enabled}` per §7.6.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `/auth/me`
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+import type { AIHubAuthContext, AIHubDeployment, AIHubUser } from "@data-club/ai-hub";
+import type { AdminSettingRow, UserRow } from "../db/schema.js";
+/**
+ * Builds the per-user identity payload. Pure per-user state.
+ *
+ * @param row - the `user` DB row.
+ * @returns the wire-format `AIHubUser`.
+ */
+export declare function buildUserView(row: UserRow): AIHubUser;
+/**
+ * Builds the per-deployment context payload. The `letta_ade_url` field is
+ * gated by `callerRole >= power_user` (§6.3.4).
+ *
+ * @param settings - the `admin_setting` singleton row (pass null only when
+ *   the row genuinely doesn't exist — first-boot before the seed has run,
+ *   which shouldn't happen in practice).
+ * @param callerRole - role from the JWT's claim, used to gate
+ *   `letta_ade_url`.
+ * @returns the wire-format `AIHubDeployment`.
+ */
+export declare function buildDeploymentView(settings: AdminSettingRow | null, callerRole: UserRow["role"]): AIHubDeployment;
+/**
+ * Convenience: builds both halves and returns them as the
+ * `AIHubAuthContext` envelope `/auth/me` (and `/auth/login` post-change)
+ * use directly.
+ *
+ * @param row - the user row.
+ * @param settings - the `admin_setting` singleton row.
+ * @returns the combined envelope.
+ */
+export declare function buildAuthContext(row: UserRow, settings: AdminSettingRow | null): AIHubAuthContext;
+//# sourceMappingURL=userView.d.ts.map

package/dist/auth/userView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userView.d.ts","sourceRoot":"","sources":["../../src/auth/userView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAQrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,GAC1B,eAAe,CAUjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,eAAe,GAAG,IAAI,GAC/B,gBAAgB,CAKlB"}

package/dist/auth/userView.js

@@ -0,0 +1,77 @@
+/**
+ * Builds the `{ user, deployment }` envelope returned by `/auth/me`,
+ * `/auth/me/preferences`, and embedded in `/auth/login`'s response.
+ *
+ * Two non-obvious concerns this module owns:
+ *
+ * 1. **Per-user vs. per-deployment split.** `user` carries strictly per-user
+ *    fields (id, username, role, theme_preference, …); `deployment` carries
+ *    strictly per-deployment fields (theme_default, theme_switcher_enabled,
+ *    letta_ade_url). The split makes it impossible for a client to confuse
+ *    "this is my preference" with "this is how the deployment is configured."
+ * 2. **Role-gated `letta_ade_url`.** The URL is only included for callers
+ *    with role `power_user` or higher (§6.3.4). For `user`-role callers it's
+ *    omitted entirely (not set to null) so the React client cannot render
+ *    a link element it shouldn't see.
+ *
+ * The resolved theme is **not** computed here — the client does the simple
+ * precedence calculation client-side from `user.theme_preference +
+ * deployment.{theme_default, theme_switcher_enabled}` per §7.6.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — `/auth/me`
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+/**
+ * Builds the per-user identity payload. Pure per-user state.
+ *
+ * @param row - the `user` DB row.
+ * @returns the wire-format `AIHubUser`.
+ */
+export function buildUserView(row) {
+    return {
+        id: row.id,
+        username: row.username,
+        display_name: row.displayName ?? null,
+        role: row.role,
+        theme_preference: row.themePreference ?? null,
+    };
+}
+/**
+ * Builds the per-deployment context payload. The `letta_ade_url` field is
+ * gated by `callerRole >= power_user` (§6.3.4).
+ *
+ * @param settings - the `admin_setting` singleton row (pass null only when
+ *   the row genuinely doesn't exist — first-boot before the seed has run,
+ *   which shouldn't happen in practice).
+ * @param callerRole - role from the JWT's claim, used to gate
+ *   `letta_ade_url`.
+ * @returns the wire-format `AIHubDeployment`.
+ */
+export function buildDeploymentView(settings, callerRole) {
+    const out = {
+        theme_default: settings?.themeDefault ?? "light",
+        theme_switcher_enabled: settings?.themeSwitcherEnabled ?? true,
+    };
+    if (callerRole !== "user") {
+        const ade = settings?.lettaAdeUrl ?? null;
+        if (ade)
+            out.letta_ade_url = ade;
+    }
+    return out;
+}
+/**
+ * Convenience: builds both halves and returns them as the
+ * `AIHubAuthContext` envelope `/auth/me` (and `/auth/login` post-change)
+ * use directly.
+ *
+ * @param row - the user row.
+ * @param settings - the `admin_setting` singleton row.
+ * @returns the combined envelope.
+ */
+export function buildAuthContext(row, settings) {
+    return {
+        user: buildUserView(row),
+        deployment: buildDeploymentView(settings, row.role),
+    };
+}
+//# sourceMappingURL=userView.js.map

package/dist/auth/userView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userView.js","sourceRoot":"","sources":["../../src/auth/userView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,YAAY,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;QACrC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,gBAAgB,EAAE,GAAG,CAAC,eAAe,IAAI,IAAI;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgC,EAChC,UAA2B;IAE3B,MAAM,GAAG,GAAoB;QAC3B,aAAa,EAAE,QAAQ,EAAE,YAAY,IAAI,OAAO;QAChD,sBAAsB,EAAE,QAAQ,EAAE,oBAAoB,IAAI,IAAI;KAC/D,CAAC;IACF,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,QAAQ,EAAE,WAAW,IAAI,IAAI,CAAC;QAC1C,IAAI,GAAG;YAAE,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAY,EACZ,QAAgC;IAEhC,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC;QACxB,UAAU,EAAE,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC;KACpD,CAAC;AACJ,CAAC"}

package/dist/bootstrap.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Boot orchestration: env → open DB → migrate → seed → ready.
+ *
+ * The pieces that compose this (env loader, `openDb`, `runMigrations`,
+ * `runFirstBootSeed`, `createLogger`) are independently importable so tests
+ * and embedders can wire bespoke combinations. `bootServer` is the
+ * convenience entry point the `dev/server.ts` runner and the per-customer
+ * wrapper's Next.js mount call.
+ *
+ * @see SPECIFICATIONS.md §12.1 — env vars
+ * @see SPECIFICATIONS.md §6.7 — signing key bootstrap
+ * @see SPECIFICATIONS.md §6.10 — metrics token bootstrap
+ */
+import type Database from "better-sqlite3";
+import { type DrizzleDB } from "./db/connection.js";
+import { type SeedReport } from "./db/seed.js";
+import { type FetchHandler } from "./handlers/fetch.js";
+import type { LettaClient } from "./letta/client.js";
+import { type Logger } from "./observability/logger.js";
+/** Subset of `process.env` we care about — narrows for tests. */
+export type EnvLike = Record<string, string | undefined>;
+/**
+ * Parsed env config used by `bootServer`. Everything is optional except
+ * `encryptionKey`, which `parseEnvConfig` will raise on if missing.
+ */
+export interface EnvConfig {
+    /** Filesystem dir for SQLite + state. Default `./data`. */
+    dataDir: string;
+    /** SQLite connection string (file path or `:memory:`). */
+    databaseUrl: string;
+    /** Required AES-256 key parsed from `AI_HUB_ENCRYPTION_KEY`. */
+    encryptionKey: Buffer;
+    /** Bootstrap-only signing key (env value, decoded). */
+    signingKeyFromEnv: Buffer | undefined;
+    /** Bootstrap-only metrics scrape token (env value). */
+    metricsScrapeTokenFromEnv: string | undefined;
+    /** Letta API key from env. */
+    lettaApiKey: string | undefined;
+    /** Letta base URL from env. */
+    lettaBaseUrl: string | undefined;
+    /** Letta ADE URL override from env. */
+    lettaAdeUrl: string | undefined;
+    /** Pino log level. */
+    logLevel: string;
+    /** CORS origins (comma-separated). */
+    corsAllowedOrigins: string;
+}
+/**
+ * Parses `process.env` (or a test-supplied stand-in) into an `EnvConfig`.
+ * Throws on any required-but-missing variable so the operator gets a clear
+ * error on first boot instead of a confusing runtime failure.
+ *
+ * @param env - the env-var record to read from.
+ * @returns the parsed config.
+ */
+export declare function parseEnvConfig(env: EnvLike): EnvConfig;
+/** Returned by `bootServer` — everything the dev/Next.js mount needs. */
+export interface BootedServer {
+    /** The Fetch handler — `(Request) => Promise<Response>`. */
+    fetchHandler: FetchHandler;
+    /** Drizzle client (in case the embedder wants to read directly). */
+    db: DrizzleDB;
+    /** Raw better-sqlite3 handle. */
+    sqlite: Database.Database;
+    /** Logger configured per env. */
+    logger: Logger;
+    /** Parsed env config. */
+    config: EnvConfig;
+    /** What the seed actually wrote on this boot. */
+    seedReport: SeedReport;
+    /** Closes the DB handle. Call this on graceful shutdown. */
+    close: () => void;
+}
+/** Optional override: pass a pre-built logger or destination to capture. */
+export interface BootServerOptions {
+    /**
+     * Custom env source. Defaults to `process.env`. Tests pass a synthesized
+     * record so they don't have to mutate the actual environment.
+     */
+    env?: EnvLike;
+    /** Override the logger (e.g. test capture). */
+    logger?: Logger;
+    /** Override the connection — tests use `:memory:` here. */
+    databaseUrl?: string;
+    /**
+     * Override the Letta client (§6.4). Tests pass a mock so the server
+     * never reaches a real Letta. Production omits this — the default reads
+     * `admin_setting.letta_base_url` + decrypted API key on each use.
+     */
+    lettaClient?: LettaClient;
+}
+/**
+ * One-shot boot: parses env, opens the DB, runs migrations, runs the
+ * first-boot seed (idempotent), and returns the Fetch handler.
+ *
+ * Called by `dev/server.ts` and by per-customer wrappers' Next.js mount
+ * (typically wrapped in a module-level singleton so it runs once per
+ * Next.js process).
+ *
+ * @param opts - optional overrides for testing.
+ * @returns the booted server bundle.
+ */
+export declare function bootServer(opts?: BootServerOptions): Promise<BootedServer>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAMtE,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,uDAAuD;IACvD,yBAAyB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,8BAA8B;IAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+BAA+B;IAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uCAAuC;IACvC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAiCtD;AAyDD,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,YAAY,EAAE,YAAY,CAAC;IAC3B,oEAAoE;IACpE,EAAE,EAAE,SAAS,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAC1B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,iDAAiD;IACjD,UAAU,EAAE,UAAU,CAAC;IACvB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6CvB"}