@adminiumjs/adminium 0.1.0-rc.1

package/dist/compose.js

@@ -0,0 +1,383 @@
+/**
+ * THE COMPOSITION ROOT (01-architecture.md §4: "All four deployment modes run
+ * the identical `@adminium/server` process; only the wrapper differs").
+ *
+ * `buildServer` is the Fastify *skeleton* — logger, error envelope, auth, static,
+ * and the handful of resources that need no injected services (system/auth/me/
+ * bootstrap/setup/about). Every other resource is a FACTORY over injected
+ * services (`connectionsRoutes({ manager, meta })`, `llmRoutes({ … })`, …),
+ * because 01 §2.3 forbids the route tree from reaching out and constructing a
+ * `ConnectionManager` or importing `@adminium/widgets` on its own. Somebody has
+ * to do that construction. This module is that somebody, and it is the ONLY one.
+ *
+ * WHY IT EXISTS. It used to be `scripts/demo-v01.mjs` — a demo script — which
+ * meant `adminium start`, `adminium init`'s final boot and the Docker CMD all
+ * served a hollow API: the SPA loaded, setup created the super admin, and then
+ * the connect wizard's `POST /api/v1/connections` 404'd, because the plugin that
+ * answers it was only ever registered by a script nobody runs in production. The
+ * dashboard calls 17 `/api/v1` namespaces; the skeleton serves 6. This module
+ * closes that gap so the M10 exit criterion — "`npx adminium` (or `docker run`)
+ * on a clean machine → first-run wizard → create super admin → connect any of the
+ * 3 engines → generated app" — is met by the shipped artifact and not only by a
+ * script in the repo.
+ *
+ * DEGRADATION. The LLM surface is the one optional part: `LLM_ALLOWED_TEMPLATES`
+ * / `LLM_ALLOWED_WIDGETS` come from `@adminium/widgets` (01 §2.3: the server tree
+ * may not import it), loaded by file path at runtime. When that load fails the
+ * `/llm` routes are skipped and everything else boots — the demo script's
+ * behavior, kept, because a missing AI vocabulary must not cost you your CRUD.
+ */
+import { llmKeyCryptoFromSecret } from '@adminium/llm';
+import { exportsRepo, filesRepo, settingsRepo } from '@adminium/meta';
+import { buildServer } from './app.js';
+import { decryptSecret, deriveKey, encryptSecret } from './config/secrets.js';
+import { dsnCryptoFromSecret } from './connections/crypto.js';
+import { registerIntrospectJob } from './connections/introspect.js';
+import { UndoStore } from './crud/undo.js';
+import { createFileStorage } from './files/storage.js';
+import { registerJobsAndRealtime } from './jobs/register.js';
+import { SCHEDULED_REPORTS_POLL_CRON, SCHEDULED_REPORTS_POLL_NAME, enqueueDueReports, } from './jobs/report-run.js';
+import { createProviderResolver } from './llm/provider-resolver.js';
+import { rbacPlugin } from './plugins/rbac.js';
+import { permissionSetAllows, resolvePermissionSet } from './rbac/resolver.js';
+import { API_PREFIX } from './routes/index.js';
+import { apiKeysRoutes } from './routes/api-keys/index.js';
+import { auditRoutes } from './routes/audit/index.js';
+import { desktopSessionRoutes } from './routes/auth/desktop-session.js';
+import { desktopRoutes } from './routes/desktop/index.js';
+import { demoSeedScriptPath } from './desktop/demo-seed.js';
+import { desktopDemoRoutes } from './routes/desktop-demo/index.js';
+import { desktopLanRoutes } from './routes/desktop-lan/index.js';
+import { desktopLocalDbRoutes } from './routes/desktop-local-db/index.js';
+import { desktopCapabilityRoutes } from './routes/desktop-capabilities/index.js';
+import { connectionsRoutes } from './routes/connections/index.js';
+import { dataRoutes } from './routes/data/index.js';
+import { emailTemplatesRoutes } from './routes/email-templates/index.js';
+import { exportsRoutes } from './routes/exports/index.js';
+import { generateRoutes } from './routes/generate/index.js';
+import { importsRoutes } from './routes/imports/index.js';
+import { llmRoutes } from './routes/llm/index.js';
+import { meViewsRoutes } from './routes/me-views/index.js';
+import { notificationsRoutes } from './routes/notifications/index.js';
+import { onboardingRoutes } from './routes/onboarding/index.js';
+import { pagesRoutes } from './routes/pages/index.js';
+import { rolesRoutes } from './routes/roles/index.js';
+import { scheduledReportsRoutes } from './routes/scheduled-reports/index.js';
+import { schemaRoutes } from './routes/schema/index.js';
+import { schemaImportRoutes } from './routes/schema-import/index.js';
+import { searchRoutes } from './routes/search/index.js';
+import { settingsRoutes } from './routes/settings/index.js';
+import { viewsRoutes } from './routes/views/index.js';
+import { widgetDataRoutes } from './routes/widget-data/index.js';
+import { createTelemetryService } from './telemetry/service.js';
+import { APP_VERSION } from './version.js';
+import { sqlitePathFromUrl } from './meta/store.js';
+/**
+ * Daily, at 04:00 UTC, with an hour of jitter (below). Telemetry is the least
+ * urgent thing this process does; a daily ping is what the payload documents
+ * (`telemetry/payload.ts`) and nothing downstream reads it sooner. Runs on the
+ * existing croner scheduler rather than a `setInterval`, per BRIEF §3 (no
+ * external scheduler, and no second timing mechanism either).
+ */
+export const TELEMETRY_SCHEDULE_NAME = 'telemetry-ping';
+export const TELEMETRY_CRON = '0 4 * * *';
+/** De-synchronize a fleet so a self-host cohort does not ping in lockstep. */
+export const TELEMETRY_JITTER_MS = 60 * 60 * 1000;
+/**
+ * Daily export-retention sweep (M7-T07): flips `ready` → `expired` on
+ * `adminium_exports` rows past `expires_at`, then GCs the expired artifacts'
+ * BYTES (`filesRepo.markDeleted` + `storage.remove`) so a snapshot never
+ * outlives the "kept for 30 days, then expire" promise on disk. Offset from
+ * the telemetry ping so the two dailies never contend.
+ */
+export const EXPORTS_RETENTION_SCHEDULE_NAME = 'exports-retention-sweep';
+export const EXPORTS_RETENTION_CRON = '30 4 * * *';
+/**
+ * Mirror `config.json`'s §2.3 `singleUser` into the setting the §5 route reads.
+ *
+ * §5: "only while `config.singleUser` is true (mirrored into `adminium_settings`
+ * … by the server at boot)". The desktop main process owns `config.json` and the
+ * child cannot read it (different process, different lifetime, and §2.3 makes the
+ * main process its only writer), so the env var IS the mirror channel — see
+ * `config/env.ts`. Unset ⇒ this does nothing at all, deliberately: absent input
+ * must not be read as `false` and quietly overwrite an answer the user gave.
+ */
+async function mirrorDesktopSingleUser(meta, value) {
+    await settingsRepo(meta).set('desktop.singleUser', value, { updatedBy: null });
+}
+/**
+ * Build the COMPLETE server: skeleton + RBAC + jobs/realtime + every resource
+ * the dashboard calls. Does not listen — the caller decides that (`startServer`
+ * for the CLI, a test's `inject` for the suites).
+ */
+export async function composeServer(opts) {
+    const { env, manager, runService, applyService, allowed } = opts;
+    const meta = opts.metaStore.meta;
+    const app = await buildServer({
+        env,
+        metaDb: meta,
+        ...(opts.staticRoot === undefined ? {} : { staticRoot: opts.staticRoot }),
+        ...(opts.logger === undefined ? {} : { logger: opts.logger }),
+    });
+    await app.register(rbacPlugin, { meta });
+    // LLM assist (M6, 06-llm-assist.md §10.5). Only the vocabulary is optional;
+    // the key crypto and the resolver are cheap and pure.
+    const llm = allowed === null
+        ? null
+        : (() => {
+            const keyCrypto = llmKeyCryptoFromSecret(env.ADMINIUM_SECRET, {
+                deriveKey,
+                encryptSecret,
+                decryptSecret,
+            });
+            return {
+                keyCrypto,
+                resolve: createProviderResolver({
+                    meta,
+                    keyCrypto,
+                    allowedTemplates: allowed.templates,
+                    allowedWidgets: allowed.widgets,
+                }),
+            };
+        })();
+    // Artifact storage for the data-io pipeline (M7-T07): exports, imports and
+    // scheduled-report snapshots all live under `<dataDir>/files/`.
+    const storage = createFileStorage({ dataDir: env.ADMINIUM_DATA_DIR });
+    const jobs = await registerJobsAndRealtime(app, {
+        meta,
+        resolveUser: (req) => req.user ?? null,
+        // Registers the export-run / import-run / report-run handlers on the shared
+        // registry — the same instances the exports/imports routes receive below.
+        dataIo: { manager, storage },
+        // The realtime hub authorizes a SUBSCRIBED USER, not a request, so it cannot
+        // reuse `request.can()` (which caches per request and needs a principal on
+        // one). It goes through the same resolver + the same decision function the
+        // route guards use — `resolvePermissionSet` → `permissionSetAllows`, including
+        // the super-admin bypass — so a channel can never grant what a route denies.
+        can: async (user, permission) => permissionSetAllows(
+        // `label` is only ever read for audit `actor_label`; a channel
+        // subscription writes no audit entry, so the id is the whole principal.
+        await resolvePermissionSet(meta, { kind: 'user', id: user.id, label: user.id }), permission),
+        ...(llm === null ? {} : { llm: { resolve: llm.resolve } }),
+    });
+    // The `introspect` job kind (08 §2.4): without this, POST
+    // /connections/:id/introspect silently falls back to its synchronous
+    // dev/test path (30s request-thread budget) in every deployment and the
+    // wizard's job-polling branch never runs.
+    registerIntrospectJob(jobs.registry, { manager, meta });
+    const undoStore = new UndoStore();
+    /**
+     * THE DESKTOP AUTO-LOGIN DOOR (11-electron.md §5) — the one route in the
+     * product that mints a super-admin session without a password.
+     *
+     * Both conditions are load-bearing, and the AND is the point:
+     *
+     *  - `ADMINIUM_RUNTIME=desktop` — §5 registers this "only when" the Electron
+     *    shell is the wrapper. Every other deployment (self-host, Docker, npx, and
+     *    every test that does not opt in) composes a server with NO such route:
+     *    `/auth/desktop-session` 404s there, which is a stronger guarantee than any
+     *    runtime check inside a handler could make.
+     *  - a boot token — a desktop boot without one has nothing to exchange, so the
+     *    route would be an unreachable surface. §2.2 mints a fresh token per boot;
+     *    absence means the shell chose not to (or could not), and the app lands on
+     *    the normal login screen.
+     *
+     * The mirror runs first so the route's own §5 policy gate reads THIS boot's
+     * answer rather than the last one's.
+     */
+    const desktopSession = env.ADMINIUM_RUNTIME === 'desktop' && env.ADMINIUM_BOOT_TOKEN !== undefined
+        ? { bootToken: env.ADMINIUM_BOOT_TOKEN }
+        : null;
+    if (env.ADMINIUM_RUNTIME === 'desktop' && env.ADMINIUM_DESKTOP_SINGLE_USER !== undefined) {
+        await mirrorDesktopSingleUser(meta, env.ADMINIUM_DESKTOP_SINGLE_USER);
+    }
+    /**
+     * §8.3's share panel, behind gate 1 of `routes/desktop-lan/index.ts`.
+     *
+     * ONE condition, unlike the boot-token door above, and the asymmetry is
+     * deliberate. That route needs a token to exchange, so a desktop boot without
+     * one has nothing to serve. This one reports on the SOCKET this process is
+     * bound to, which every desktop boot has — including (especially) a
+     * loopback-only one, where the honest answer `active: false` is what tells the
+     * panel that a toggle the user flipped has not taken effect.
+     */
+    const desktopLan = env.ADMINIUM_RUNTIME === 'desktop';
+    /**
+     * §6 step 2's two server-side source cards — "Create a new local database"
+     * (card 1) and "Explore the demo database" (card 4).
+     *
+     * Both are gated on the runtime for the same reason, and it is not the §5
+     * reason: neither mints a credential, and both do exactly what
+     * `POST /connections` does, under the same `system:connections:manage` grant.
+     * What makes them desktop-only is their SUBJECT. Both write into
+     * `<dataDir>/databases/`, a directory that exists because the Electron shell
+     * created it and passed `ADMINIUM_DATA_DIR` (§2.2 step 5). On Docker that path
+     * is inside a container, so a database created there is one the user can
+     * neither find with a file dialog, back up, nor delete — a button that appears
+     * to work and produces something unreachable.
+     *
+     * The demo carries a second condition, and it is load-bearing in the same way
+     * the boot token is for §5: with no seed script there is nothing to run, so the
+     * route would be an unreachable surface and the wizard hides the card instead
+     * of offering a demo it cannot seed.
+     */
+    const desktopLocalDb = env.ADMINIUM_RUNTIME === 'desktop';
+    // `demoSeedScriptPath` rather than the condition inline: `/system/info`'s
+    // `desktopDemo` flag reports whether this route exists, and the wizard gates
+    // its fourth source card on that answer. Two spellings of one condition is a
+    // card that offers a 404 (or hides a working one) the day they diverge.
+    const seedScriptPath = demoSeedScriptPath(env);
+    const desktopDemo = seedScriptPath === null ? null : { seedScriptPath };
+    /**
+     * §9's backup, behind gate 1 of `routes/desktop/index.ts` (the route's own
+     * header documents gates 2 and 3 — loopback peer, then `settings:manage`).
+     *
+     * One condition, like the LAN panel and for the same reason: every desktop
+     * boot has data to back up. What makes it desktop-only is `<dataDir>/backups`
+     * and `config.json` — self-host's answer to "back up my instance" is
+     * `adminium export-zip` plus whatever backs up its Postgres.
+     *
+     * `metaPath` is derived rather than passed because §2.1 makes it an invariant:
+     * the meta store is ALWAYS local SQLite on desktop (`ADMINIUM_META_DSN=
+     * sqlite:<dataDir>/meta.db`, §2.2 step 5), even when the source DB is a remote
+     * Postgres. `metaStore.url` is therefore the one true answer to "which file is
+     * the live meta store", and asking the caller to repeat it would let the two
+     * drift — the backup would snapshot a file the server is not using.
+     */
+    const desktopBackup = env.ADMINIUM_RUNTIME === 'desktop';
+    /**
+     * §12's capability grant table, behind gate 1 of
+     * `routes/desktop-capabilities/index.ts`. One condition, like its siblings:
+     * every desktop boot can install an app that declares a capability, so the
+     * consent/revoke door and the grant reader the `CapabilityHost` calls both
+     * need to exist. Off-desktop there is no host and no hardware, so §12's answer
+     * there is "every capability `unavailable`" — a claim the SPA makes, not a
+     * grant table.
+     */
+    const desktopCapabilities = env.ADMINIUM_RUNTIME === 'desktop';
+    await app.register(async (api) => {
+        if (desktopSession !== null) {
+            await api.register(desktopSessionRoutes({ meta, bootToken: desktopSession.bootToken }));
+        }
+        // AFTER `rbacPlugin` above, which is what `app.rbac.require` needs to
+        // exist at registration time — the reason this lives here and not in
+        // `buildServer`'s route block, where `settingsManage` could not be
+        // enforced at all.
+        if (desktopLan) {
+            await api.register(desktopLanRoutes({ meta, env }));
+        }
+        // Also after `rbacPlugin`: both guard on `system:connections:manage`.
+        if (desktopLocalDb) {
+            await api.register(desktopLocalDbRoutes({ manager, dataDir: env.ADMINIUM_DATA_DIR }));
+        }
+        if (desktopDemo !== null) {
+            await api.register(desktopDemoRoutes({
+                manager,
+                dataDir: env.ADMINIUM_DATA_DIR,
+                seedScriptPath: desktopDemo.seedScriptPath,
+            }));
+        }
+        // Also after `rbacPlugin`: guards on `system:settings:manage`.
+        if (desktopBackup) {
+            await api.register(desktopRoutes({
+                meta,
+                crypto: dsnCryptoFromSecret(env.ADMINIUM_SECRET),
+                dataDir: env.ADMINIUM_DATA_DIR,
+                metaPath: sqlitePathFromUrl(opts.metaStore.url),
+            }));
+        }
+        // Also after `rbacPlugin`: all three verbs guard on `system:settings:manage`.
+        if (desktopCapabilities) {
+            await api.register(desktopCapabilityRoutes({ meta }));
+        }
+        await api.register(connectionsRoutes({ manager, meta }));
+        await api.register(schemaRoutes({ manager, meta }));
+        await api.register(dataRoutes({ manager, meta, undoStore }));
+        // M7 data-io + reports/notifications (T5/T6): exports and imports share
+        // the jobs pipeline wired above; scheduled reports ride the same registry
+        // via the poll schedule below.
+        const enqueueDataIo = (input) => jobs.enqueue(input);
+        await api.register(exportsRoutes({ meta, manager, storage, enqueue: enqueueDataIo }));
+        await api.register(importsRoutes({ meta, manager, storage, enqueue: enqueueDataIo }));
+        await api.register(notificationsRoutes({ meta, hub: jobs.hub }));
+        await api.register(scheduledReportsRoutes({ meta }));
+        await api.register(emailTemplatesRoutes({ meta }));
+        await api.register(generateRoutes({ manager, meta }));
+        await api.register(schemaImportRoutes());
+        await api.register(pagesRoutes({ meta }));
+        // ⌘K global search (08 §2.9, M4-T06): pages by title + records via the
+        // crud quick-search path, RBAC/PII-filtered like the data routes.
+        await api.register(searchRoutes({ manager, meta }));
+        await api.register(widgetDataRoutes({ manager, meta }));
+        await api.register(settingsRoutes({ meta }));
+        await api.register(viewsRoutes({ meta }));
+        await api.register(meViewsRoutes({ meta }));
+        await api.register(onboardingRoutes({ meta }));
+        await api.register(rolesRoutes);
+        await api.register(apiKeysRoutes);
+        await api.register(auditRoutes);
+        if (llm !== null && allowed !== null) {
+            await api.register(llmRoutes({
+                meta,
+                runService,
+                applyService,
+                keyCrypto: llm.keyCrypto,
+                allowed,
+                ...(opts.collectStats === undefined ? {} : { collectStats: opts.collectStats }),
+            }));
+        }
+    }, { prefix: API_PREFIX });
+    // Telemetry (M10-T04). OPT-IN: `report()` reads `telemetry.enabled` FIRST and
+    // returns before building a payload, so an instance that has not consented
+    // makes zero network calls — the property `telemetry-network-isolation.test.ts`
+    // pins. Registering the schedule is not consent; the schedule ticking on an
+    // opted-out instance is a no-op read of one settings row.
+    if (opts.telemetry !== false) {
+        const telemetry = createTelemetryService({
+            meta,
+            version: APP_VERSION,
+            envOverride: env.ADMINIUM_TELEMETRY,
+        });
+        jobs.scheduler.registerSchedule(TELEMETRY_SCHEDULE_NAME, TELEMETRY_CRON, async () => {
+            await telemetry.report();
+        }, { jitterMs: TELEMETRY_JITTER_MS });
+    }
+    // Scheduled-reports poll (M7 T6): every minute, enqueue a `report-run` job
+    // per due report. `enqueueDueReports` dedupes per occurrence
+    // (`report-run:<id>:<nextRunAt>`), so overlapping ticks collapse; the
+    // scheduler's own no-overlap guard rides on top.
+    jobs.scheduler.registerSchedule(SCHEDULED_REPORTS_POLL_NAME, SCHEDULED_REPORTS_POLL_CRON, async () => {
+        await enqueueDueReports(meta, (input) => jobs.enqueue(input));
+    });
+    // Export retention (M7-T07): daily `ready` → `expired` sweep past
+    // `expires_at`, then byte GC — expired snapshots (potentially unmasked PII)
+    // must not persist on disk past the promised retention window. `remove` is
+    // idempotent and the worklist re-derives from rows, so a crash mid-pass
+    // self-heals on the next tick.
+    jobs.scheduler.registerSchedule(EXPORTS_RETENTION_SCHEDULE_NAME, EXPORTS_RETENTION_CRON, async () => {
+        const repo = exportsRepo(meta);
+        await repo.expireDue();
+        const files = filesRepo(meta);
+        for (const artifact of await repo.listExpiredArtifacts()) {
+            await files.markDeleted(artifact.fileId);
+            await storage.remove(artifact.storageKey);
+        }
+    });
+    // The manager owns live source-DB pools; the server owns the manager's
+    // lifetime once it is listening (the CLI hands it over at `startServer`).
+    app.addHook('onClose', async () => {
+        await manager.disposeAll();
+    });
+    return {
+        app,
+        jobs,
+        llmEnabled: llm !== null,
+        desktopSessionEnabled: desktopSession !== null,
+        desktopLanEnabled: desktopLan,
+        desktopLocalDbEnabled: desktopLocalDb,
+        desktopDemoEnabled: desktopDemo !== null,
+        desktopBackupEnabled: desktopBackup,
+        desktopCapabilitiesEnabled: desktopCapabilities,
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

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

package/dist/config/bootstrap.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+/**
+ * Bootstrap file `<dataDir>/adminium.json` (01-architecture.md §7.2). The
+ * meta DSN cannot live in the meta store itself (chicken-and-egg), so when
+ * it is not provided by `ADMINIUM_META_URL` the first-run wizard persists it
+ * here, AES-256-GCM-encrypted with the key derived from `ADMINIUM_SECRET`.
+ * Environment always wins over this file.
+ */
+export declare const BOOTSTRAP_FILENAME = "adminium.json";
+export declare const bootstrapSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    metaUrl: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    instanceId: z.ZodString;
+}, z.core.$strip>;
+export type Bootstrap = z.infer<typeof bootstrapSchema>;
+export declare class BootstrapFileError extends Error {
+    readonly name = "BootstrapFileError";
+}
+export declare function bootstrapPath(dataDir: string): string;
+/**
+ * Reads and validates `<dataDir>/adminium.json`. Returns `null` when the
+ * file does not exist (first run); throws `BootstrapFileError` when it
+ * exists but is unreadable as a bootstrap document.
+ */
+export declare function readBootstrap(dataDir: string): Promise<Bootstrap | null>;
+/**
+ * Atomically writes `<dataDir>/adminium.json` with mode 0600: the document
+ * is written to a temp file in the same directory, then renamed over the
+ * target, so a crash mid-write can never leave a truncated bootstrap file.
+ */
+export declare function writeBootstrap(dataDir: string, bootstrap: Bootstrap): Promise<void>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/config/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/config/bootstrap.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,eAAO,MAAM,eAAe;;;;;iBAS1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;CAC/C;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAyB9E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzF"}

package/dist/config/bootstrap.js

@@ -0,0 +1,81 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { ENC_TOKEN_PREFIX } from './secrets.js';
+/**
+ * Bootstrap file `<dataDir>/adminium.json` (01-architecture.md §7.2). The
+ * meta DSN cannot live in the meta store itself (chicken-and-egg), so when
+ * it is not provided by `ADMINIUM_META_URL` the first-run wizard persists it
+ * here, AES-256-GCM-encrypted with the key derived from `ADMINIUM_SECRET`.
+ * Environment always wins over this file.
+ */
+export const BOOTSTRAP_FILENAME = 'adminium.json';
+export const bootstrapSchema = z.object({
+    v: z.literal(1),
+    /** Encrypted meta-store DSN (`enc:v1:` token); absent until the wizard sets it. */
+    metaUrl: z
+        .string()
+        .startsWith(ENC_TOKEN_PREFIX, `must be an encrypted "${ENC_TOKEN_PREFIX}" token`)
+        .optional(),
+    createdAt: z.iso.datetime(),
+    instanceId: z.string().min(1),
+});
+export class BootstrapFileError extends Error {
+    name = 'BootstrapFileError';
+}
+export function bootstrapPath(dataDir) {
+    return join(dataDir, BOOTSTRAP_FILENAME);
+}
+/**
+ * Reads and validates `<dataDir>/adminium.json`. Returns `null` when the
+ * file does not exist (first run); throws `BootstrapFileError` when it
+ * exists but is unreadable as a bootstrap document.
+ */
+export async function readBootstrap(dataDir) {
+    const file = bootstrapPath(dataDir);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new BootstrapFileError(`${file} is not valid JSON`);
+    }
+    const result = bootstrapSchema.safeParse(parsed);
+    if (!result.success) {
+        const problems = result.error.issues
+            .map((issue) => `${issue.path.map(String).join('.') || '(root)'}: ${issue.message}`)
+            .join('; ');
+        throw new BootstrapFileError(`${file} is not a valid bootstrap file — ${problems}`);
+    }
+    return result.data;
+}
+/**
+ * Atomically writes `<dataDir>/adminium.json` with mode 0600: the document
+ * is written to a temp file in the same directory, then renamed over the
+ * target, so a crash mid-write can never leave a truncated bootstrap file.
+ */
+export async function writeBootstrap(dataDir, bootstrap) {
+    const doc = bootstrapSchema.parse(bootstrap);
+    await mkdir(dataDir, { recursive: true });
+    const target = bootstrapPath(dataDir);
+    const tmp = `${target}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await writeFile(tmp, `${JSON.stringify(doc, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+        await rename(tmp, target);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/config/bootstrap.js.map

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

package/dist/config/env.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+/**
+ * Environment validation (01-architecture.md §7.1). `loadEnv()` is called
+ * first in the boot sequence; on invalid input it prints a fail-fast table
+ * (variable | problem | hint) to stderr and throws — it never calls
+ * `process.exit` so callers (CLI, tests, Electron) decide how to die.
+ */
+export declare const LOG_LEVELS: readonly ["fatal", "error", "warn", "info", "debug", "trace"];
+/**
+ * The DEPLOYMENT WRAPPER this process is running under (01-architecture.md §4:
+ * "All four deployment modes run the identical `@adminium/server` process; only
+ * the wrapper differs"). Only the wrapper sets it, and only `desktop` means
+ * anything today: 11-electron.md §5 registers `POST /api/v1/auth/desktop-session`
+ * ONLY under that value, so a self-host or Docker instance does not expose the
+ * boot-token exchange at all — it has no route to attack, not merely a guarded
+ * one. Everything that is not the Electron shell is `self-host` (Docker and npx
+ * included); `cloud` joins when 12-cloud-platform.md lands.
+ */
+export declare const RUNTIMES: readonly ["self-host", "desktop"];
+export type Runtime = (typeof RUNTIMES)[number];
+/** 11-electron.md §2.2 step 4: the per-boot token is 32 random bytes, hex. */
+export declare const BOOT_TOKEN_HEX_LENGTH = 64;
+export declare const envSchema: z.ZodObject<{
+    ADMINIUM_SECRET: z.ZodString;
+    PORT: z.ZodPreprocess<z.ZodDefault<z.ZodCoercedNumber<unknown>>>;
+    HOST: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
+    DATABASE_URL: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    ADMINIUM_META_URL: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    ADMINIUM_DATA_DIR: z.ZodPreprocess<z.ZodDefault<z.ZodString>>;
+    ADMINIUM_LOG_LEVEL: z.ZodPreprocess<z.ZodDefault<z.ZodEnum<{
+        fatal: "fatal";
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+    }>>>;
+    ADMINIUM_RUNTIME: z.ZodPreprocess<z.ZodDefault<z.ZodEnum<{
+        "self-host": "self-host";
+        desktop: "desktop";
+    }>>>;
+    ADMINIUM_BOOT_TOKEN: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    ADMINIUM_DESKTOP_SINGLE_USER: z.ZodPreprocess<z.ZodPipe<z.ZodOptional<z.ZodEnum<{
+        on: "on";
+        0: "0";
+        true: "true";
+        1: "1";
+        off: "off";
+        false: "false";
+    }>>, z.ZodTransform<boolean | undefined, "on" | "0" | "true" | "1" | "off" | "false" | undefined>>>;
+    ADMINIUM_DEMO_SEED_SCRIPT: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    ADMINIUM_TELEMETRY: z.ZodPreprocess<z.ZodPipe<z.ZodOptional<z.ZodEnum<{
+        on: "on";
+        0: "0";
+        true: "true";
+        1: "1";
+        off: "off";
+        false: "false";
+    }>>, z.ZodTransform<boolean | undefined, "on" | "0" | "true" | "1" | "off" | "false" | undefined>>>;
+    ADMINIUM_NETWORK_FEATURES: z.ZodPreprocess<z.ZodPipe<z.ZodOptional<z.ZodEnum<{
+        on: "on";
+        0: "0";
+        true: "true";
+        1: "1";
+        off: "off";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "on" | "0" | "true" | "1" | "off" | "false" | undefined>>>;
+    ADMINIUM_TRUST_PROXY: z.ZodPreprocess<z.ZodPipe<z.ZodOptional<z.ZodEnum<{
+        on: "on";
+        0: "0";
+        true: "true";
+        1: "1";
+        off: "off";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "on" | "0" | "true" | "1" | "off" | "false" | undefined>>>;
+    ADMINIUM_CORS_ORIGINS: z.ZodPreprocess<z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[] | undefined, string | undefined>>>;
+}, z.core.$strip>;
+export type Env = z.infer<typeof envSchema>;
+export declare class EnvValidationError extends Error {
+    readonly name = "EnvValidationError";
+    readonly issues: readonly z.core.$ZodIssue[];
+    readonly table: string;
+    constructor(issues: readonly z.core.$ZodIssue[], table: string);
+}
+/** Renders the fail-fast `variable | problem | hint` table. */
+export declare function formatEnvErrorTable(issues: readonly z.core.$ZodIssue[]): string;
+export interface EnvWriter {
+    write(chunk: string): unknown;
+}
+/**
+ * Parses and validates the process environment. On failure, prints the
+ * problem table to stderr and throws `EnvValidationError`.
+ */
+export declare function loadEnv(env?: Record<string, string | undefined>, stderr?: EnvWriter): Env;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,UAAU,+DAAgE,CAAC;AAExF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,mCAAoC,CAAC;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAQxC,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkLpB,CAAC;AAEH,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAsB5C,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM;CAK/D;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,CAY/E;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,MAAM,GAAE,SAA0B,GACjC,GAAG,CAQL"}