@adminiumjs/adminium 0.1.0-rc.1

package/dist/routes/setup/index.js

@@ -0,0 +1,68 @@
+import { AppError, ConflictError, ValidationFailedError } from '../../errors.js';
+import { createSession, setSessionCookie } from '../../auth/sessions.js';
+import { SetupClosedError, WeakPasswordError } from '../../setup/service.js';
+import { toUserView } from '../auth/handlers.js';
+import { RATE_LIMIT_BUCKETS } from '../auth/index.js';
+import { setupStateReply, setupSuperAdminBody, setupSuperAdminReply, } from './schema.js';
+export function setupRoutes(deps) {
+    const { service } = deps;
+    return async (app) => {
+        /** Non-null under requireMeta — the preHandler 503s before handlers run. */
+        const ctx = () => {
+            if (app.authContext === null) {
+                throw new AppError(503, 'META_NOT_CONFIGURED', 'No meta store is configured.');
+            }
+            return app.authContext;
+        };
+        app.get('/setup/state', {
+            preHandler: [app.requireMeta],
+            schema: { response: { 200: setupStateReply } },
+        }, async () => {
+            const state = await service.state();
+            return {
+                data: { required: state.required, passwordMinLength: state.passwordMinLength },
+            };
+        });
+        app.post('/setup/super-admin', {
+            preHandler: [app.requireMeta],
+            config: { rateLimitBucket: RATE_LIMIT_BUCKETS.login },
+            schema: { body: setupSuperAdminBody, response: { 201: setupSuperAdminReply } },
+        }, async (request, reply) => {
+            const body = request.body;
+            let user;
+            try {
+                user = await service.createSuperAdmin({
+                    email: body.email,
+                    password: body.password,
+                    name: body.name,
+                    consent: body.consent,
+                });
+            }
+            catch (error) {
+                if (error instanceof SetupClosedError) {
+                    // 409 — the terminal state. Identical for a second submit, a lost
+                    // race, and a probe against a long-running instance.
+                    throw new ConflictError('Setup has already been completed. Sign in instead.', 'CONFLICT');
+                }
+                if (error instanceof WeakPasswordError) {
+                    throw new ValidationFailedError(error.message, {
+                        in: 'body',
+                        issues: [{ path: 'password', message: error.message, code: 'too_small' }],
+                    });
+                }
+                throw error;
+            }
+            // Land the wizard signed in — re-typing the credentials you just chose
+            // is friction with no security value (you proved nothing by knowing it).
+            const userAgent = request.headers['user-agent'];
+            const { token } = await createSession(ctx().meta, user.id, {
+                ip: request.ip,
+                userAgent: typeof userAgent === 'string' ? userAgent.slice(0, 300) : null,
+            });
+            setSessionCookie(reply, token, request);
+            void reply.status(201);
+            return { data: { user: toUserView(user) } };
+        });
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/routes/setup/index.js.map

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

package/dist/routes/setup/schema.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Zod schemas for the first-run setup resource (M10-T04; naming per
+ * 08-server-api.md §1.5: `<resource><Action><Part>` consts, `z.infer`
+ * PascalCase types).
+ *
+ * These are the only UNAUTHENTICATED write-capable schemas in the API — there
+ * is no session to authorize against on a fresh install — so the bodies are
+ * deliberately narrow and `.strict()`: an unknown key is a rejection, not
+ * something silently dropped near super-admin creation.
+ */
+import { z } from 'zod';
+/**
+ * `GET /setup/state` — the only thing a fresh install exposes pre-auth.
+ * Carries NOTHING about the instance beyond "is setup still open" and the
+ * password policy the wizard mirrors client-side: an internet-reachable
+ * un-bootstrapped instance must not leak version, engine, or user counts here.
+ */
+export declare const setupStateReply: z.ZodObject<{
+    data: z.ZodObject<{
+        required: z.ZodBoolean;
+        passwordMinLength: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SetupStateReply = z.infer<typeof setupStateReply>;
+/** The first-run consent answers. Both OFF by default (v0.5 exit criterion). */
+export declare const setupConsentBody: z.ZodObject<{
+    telemetry: z.ZodBoolean;
+    updateCheck: z.ZodBoolean;
+}, z.core.$strict>;
+export type SetupConsentBody = z.infer<typeof setupConsentBody>;
+export declare const setupSuperAdminBody: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    consent: z.ZodOptional<z.ZodObject<{
+        telemetry: z.ZodBoolean;
+        updateCheck: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SetupSuperAdminBody = z.infer<typeof setupSuperAdminBody>;
+/** 201 — the super admin exists and the response carries their session cookie. */
+export declare const setupSuperAdminReply: z.ZodObject<{
+    data: z.ZodObject<{
+        user: z.ZodObject<{
+            id: z.ZodString;
+            email: z.ZodString;
+            name: z.ZodString;
+            status: z.ZodEnum<{
+                active: "active";
+                invited: "invited";
+                suspended: "suspended";
+            }>;
+            totpEnabled: z.ZodBoolean;
+            lastLoginAt: z.ZodNullable<z.ZodNumber>;
+            createdAt: z.ZodNumber;
+            updatedAt: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SetupSuperAdminReply = z.infer<typeof setupSuperAdminReply>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/routes/setup/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/routes/setup/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gFAAgF;AAChF,eAAO,MAAM,gBAAgB;;;kBAKlB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,mBAAmB;;;;;;;;kBASrB,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,kFAAkF;AAClF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAE/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/routes/setup/schema.js

@@ -0,0 +1,47 @@
+/**
+ * Zod schemas for the first-run setup resource (M10-T04; naming per
+ * 08-server-api.md §1.5: `<resource><Action><Part>` consts, `z.infer`
+ * PascalCase types).
+ *
+ * These are the only UNAUTHENTICATED write-capable schemas in the API — there
+ * is no session to authorize against on a fresh install — so the bodies are
+ * deliberately narrow and `.strict()`: an unknown key is a rejection, not
+ * something silently dropped near super-admin creation.
+ */
+import { z } from 'zod';
+import { authUserView } from '../auth/schema.js';
+/**
+ * `GET /setup/state` — the only thing a fresh install exposes pre-auth.
+ * Carries NOTHING about the instance beyond "is setup still open" and the
+ * password policy the wizard mirrors client-side: an internet-reachable
+ * un-bootstrapped instance must not leak version, engine, or user counts here.
+ */
+export const setupStateReply = z.object({
+    data: z.object({
+        /** True only when zero users exist AND bootstrap has never been claimed. */
+        required: z.boolean(),
+        passwordMinLength: z.number().int().positive(),
+    }),
+});
+/** The first-run consent answers. Both OFF by default (v0.5 exit criterion). */
+export const setupConsentBody = z
+    .object({
+    telemetry: z.boolean(),
+    updateCheck: z.boolean(),
+})
+    .strict();
+export const setupSuperAdminBody = z
+    .object({
+    email: z.string().trim().min(3).max(320).email('must be a valid email address'),
+    /** Upper bound only — the real floor is `auth.passwordMinLength` (server-side). */
+    password: z.string().min(1).max(200),
+    name: z.string().trim().min(1).max(120).optional(),
+    /** Omitted ⇒ registry defaults stand (telemetry + update check both off). */
+    consent: setupConsentBody.optional(),
+})
+    .strict();
+/** 201 — the super admin exists and the response carries their session cookie. */
+export const setupSuperAdminReply = z.object({
+    data: z.object({ user: authUserView }),
+});
+//# sourceMappingURL=schema.js.map

package/dist/routes/setup/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/routes/setup/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,4EAA4E;QAC5E,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;QACrB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;KAC/C,CAAC;CACH,CAAC,CAAC;AAGH,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;CACzB,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,+BAA+B,CAAC;IAC/E,mFAAmF;IACnF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,6EAA6E;IAC7E,OAAO,EAAE,gBAAgB,CAAC,QAAQ,EAAE;CACrC,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;CACvC,CAAC,CAAC"}

package/dist/routes/system/handlers.d.ts

@@ -0,0 +1,63 @@
+/** Handlers for the system resource (08-server-api.md §1.2 route-module layout). */
+import { type MetaDb } from '@adminium/meta';
+import type { Env } from '../../config/env.js';
+import type { SystemHealthzReply, SystemInfoReply, SystemReadyzReply } from './schema.js';
+/**
+ * LIVENESS: the process is up and serving. No dependency checks, on purpose —
+ * a liveness probe that fails on a dependency asks the orchestrator to restart a
+ * process whose problem a restart cannot fix, turning a database blip into a
+ * crash-loop.
+ *
+ * This is what the Dockerfile HEALTHCHECK runs, and it answers exactly one
+ * question: "is this the API, and is it serving?" (It hits `/api/v1/healthz`
+ * rather than bare `/healthz` because the latter has no route and would be
+ * answered by the SPA history fallback with index.html + 200 — i.e. "healthy"
+ * as long as the static files exist on disk.) It does NOT tell you the meta
+ * store is reachable; {@link readyz} is the probe that does.
+ */
+export declare function healthz(): SystemHealthzReply;
+/**
+ * READINESS (01-architecture.md §4.1 lists `/readyz` beside `/healthz`): can
+ * this instance actually serve a request? That means the meta store — without
+ * it every authenticated route 500s, however alive the process is.
+ *
+ * Load balancers and orchestrators key traffic on THIS, not on `healthz`: an
+ * instance whose Postgres has died or been partitioned away is live but
+ * useless, and should stop receiving traffic without being restarted.
+ *
+ * One `SELECT 1` — enough to prove the pool can hand out a working connection,
+ * cheap enough to run on a probe interval.
+ */
+export declare function readyz(meta: MetaDb | null): Promise<SystemReadyzReply>;
+export interface SystemInfoDeps {
+    env: Env;
+    /** `null` when the server booted without a meta store; every field stays answerable. */
+    meta: MetaDb | null;
+}
+/**
+ * Build/runtime info + the §8.2 capability flags (11-electron.md §8.1/§8.2).
+ * `dialect` reports the connected meta store, or `null` when the server booted
+ * without one (the wave-1 behavior the schema still allows, and what a
+ * pre-bootstrap install looks like).
+ *
+ * NO FLAG HERE IS A CONSTANT. `runtime`, `networkFeaturesAllowed` and `lanShare`
+ * come off the environment this process was booted with, `smtpConfigured` off
+ * the meta store — which is why this is async, and why it is worth the one
+ * indexed primary-key read per call rather than a value baked at compose time:
+ * SMTP is editable from Settings, so a cached answer would leave the "Configure
+ * SMTP to send email" state showing on a page whose Send button now works.
+ *
+ * `lanShare` is env-derived and therefore constant for a process lifetime — but
+ * that is the whole truth of it, not a limitation: §8.3 applies the toggle by
+ * RE-FORKING this process (`config.json` → `ADMINIUM_HOST` → a new child), so a
+ * change of answer and a change of process are the same event. There is no
+ * moment at which a fresh read here would say something this boot's environment
+ * does not.
+ *
+ * The no-meta case is not a degradation to paper over: without a meta store the
+ * `email.smtp` setting does not exist, so email genuinely cannot send, and
+ * `false` is the correct answer rather than an "unknown" the SPA would have to
+ * invent a third state for.
+ */
+export declare function systemInfo(deps: SystemInfoDeps): Promise<SystemInfoReply>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/routes/system/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/routes/system/handlers.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAI/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE1F;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,IAAI,kBAAkB,CAE5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAa5E;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,GAAG,CAAC;IACT,wFAAwF;IACxF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAa/E"}

package/dist/routes/system/handlers.js

@@ -0,0 +1,121 @@
+/** Handlers for the system resource (08-server-api.md §1.2 route-module layout). */
+import { settingsRepo } from '@adminium/meta';
+import { sql } from 'kysely';
+import { demoSeedAvailable } from '../../desktop/demo-seed.js';
+import { lanShareActive } from '../../desktop/lan-share.js';
+import { APP_VERSION } from '../../version.js';
+/**
+ * LIVENESS: the process is up and serving. No dependency checks, on purpose —
+ * a liveness probe that fails on a dependency asks the orchestrator to restart a
+ * process whose problem a restart cannot fix, turning a database blip into a
+ * crash-loop.
+ *
+ * This is what the Dockerfile HEALTHCHECK runs, and it answers exactly one
+ * question: "is this the API, and is it serving?" (It hits `/api/v1/healthz`
+ * rather than bare `/healthz` because the latter has no route and would be
+ * answered by the SPA history fallback with index.html + 200 — i.e. "healthy"
+ * as long as the static files exist on disk.) It does NOT tell you the meta
+ * store is reachable; {@link readyz} is the probe that does.
+ */
+export function healthz() {
+    return { ok: true, version: APP_VERSION, uptime: process.uptime() };
+}
+/**
+ * READINESS (01-architecture.md §4.1 lists `/readyz` beside `/healthz`): can
+ * this instance actually serve a request? That means the meta store — without
+ * it every authenticated route 500s, however alive the process is.
+ *
+ * Load balancers and orchestrators key traffic on THIS, not on `healthz`: an
+ * instance whose Postgres has died or been partitioned away is live but
+ * useless, and should stop receiving traffic without being restarted.
+ *
+ * One `SELECT 1` — enough to prove the pool can hand out a working connection,
+ * cheap enough to run on a probe interval.
+ */
+export async function readyz(meta) {
+    if (meta === null) {
+        return { ok: false, version: APP_VERSION, checks: { meta: 'not-configured' } };
+    }
+    try {
+        await sql `select 1`.execute(meta.db);
+        return { ok: true, version: APP_VERSION, checks: { meta: 'ok' } };
+    }
+    catch {
+        // Deliberately not surfacing the driver's message: a connection error
+        // routinely quotes the whole DSN ("password authentication failed for user
+        // … host=…"), and this route is unauthenticated.
+        return { ok: false, version: APP_VERSION, checks: { meta: 'unreachable' } };
+    }
+}
+/**
+ * Build/runtime info + the §8.2 capability flags (11-electron.md §8.1/§8.2).
+ * `dialect` reports the connected meta store, or `null` when the server booted
+ * without one (the wave-1 behavior the schema still allows, and what a
+ * pre-bootstrap install looks like).
+ *
+ * NO FLAG HERE IS A CONSTANT. `runtime`, `networkFeaturesAllowed` and `lanShare`
+ * come off the environment this process was booted with, `smtpConfigured` off
+ * the meta store — which is why this is async, and why it is worth the one
+ * indexed primary-key read per call rather than a value baked at compose time:
+ * SMTP is editable from Settings, so a cached answer would leave the "Configure
+ * SMTP to send email" state showing on a page whose Send button now works.
+ *
+ * `lanShare` is env-derived and therefore constant for a process lifetime — but
+ * that is the whole truth of it, not a limitation: §8.3 applies the toggle by
+ * RE-FORKING this process (`config.json` → `ADMINIUM_HOST` → a new child), so a
+ * change of answer and a change of process are the same event. There is no
+ * moment at which a fresh read here would say something this boot's environment
+ * does not.
+ *
+ * The no-meta case is not a degradation to paper over: without a meta store the
+ * `email.smtp` setting does not exist, so email genuinely cannot send, and
+ * `false` is the correct answer rather than an "unknown" the SPA would have to
+ * invent a third state for.
+ */
+export async function systemInfo(deps) {
+    const { env, meta } = deps;
+    return {
+        version: APP_VERSION,
+        node: process.version,
+        dialect: meta?.dialect ?? null,
+        runtime: env.ADMINIUM_RUNTIME,
+        smtpConfigured: await smtpConfigured(meta),
+        networkFeaturesAllowed: env.ADMINIUM_NETWORK_FEATURES,
+        lanShare: lanShareActive(env),
+        // The SAME predicate compose registers the route on — see `demo-seed.ts`.
+        desktopDemo: demoSeedAvailable(env),
+    };
+}
+/**
+ * Is `adminium_settings.email.smtp` set?
+ *
+ * THE TRY/CATCH IS THE POINT, and it is the same argument {@link readyz} makes
+ * one function up. This route was a pure function until the §8.2 flags arrived;
+ * adding a database read to it means a meta-store blip — or one row of stored
+ * JSON that no longer parses — can now throw, and an unhandled throw here costs
+ * the caller the WHOLE reply, including `runtime` and `networkFeaturesAllowed`,
+ * which come off the environment and were never in doubt.
+ *
+ * That is not a hypothetical inconvenience: `/system/info` is unauthenticated
+ * precisely so pre-auth screens can ask it, and `/forgot` disables its Send
+ * button when it cannot get an answer. A 500 here would take password reset down
+ * with the settings table.
+ *
+ * `false` on failure is the same answer the no-meta case gives, and it is the
+ * conservative one: it offers an explanation instead of a Send button that drops
+ * mail. The log line is what stops it from being a silent lie to the operator.
+ */
+async function smtpConfigured(meta) {
+    if (meta === null)
+        return false;
+    try {
+        return (await settingsRepo(meta).get('email.smtp')) !== null;
+    }
+    catch {
+        // Deliberately not surfacing the driver's message — same reason readyz
+        // does not: a connection error routinely quotes the whole DSN, and this
+        // route is unauthenticated.
+        return false;
+    }
+}
+//# sourceMappingURL=handlers.js.map

package/dist/routes/system/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/routes/system/handlers.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EAAE,YAAY,EAAe,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAG7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAmB;IAC9C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC;IACjF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,CAAA,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,2EAA2E;QAC3E,iDAAiD;QACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,CAAC;IAC9E,CAAC;AACH,CAAC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAoB;IACnD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC3B,OAAO;QACL,OAAO,EAAE,WAAW;QACpB,IAAI,EAAE,OAAO,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI;QAC9B,OAAO,EAAE,GAAG,CAAC,gBAAgB;QAC7B,cAAc,EAAE,MAAM,cAAc,CAAC,IAAI,CAAC;QAC1C,sBAAsB,EAAE,GAAG,CAAC,yBAAyB;QACrD,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC;QAC7B,0EAA0E;QAC1E,WAAW,EAAE,iBAAiB,CAAC,GAAG,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,cAAc,CAAC,IAAmB;IAC/C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,wEAAwE;QACxE,4BAA4B;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/routes/system/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * System routes: `GET /healthz`, `GET /readyz` and `GET /system/info` (mounted
+ * under /api/v1).
+ *
+ * TWO PROBES, TWO QUESTIONS (01-architecture.md §4.1 lists both):
+ *  - `/healthz` — LIVENESS. Is the process up and serving? Never fails on a
+ *    dependency, because a restart cannot fix a dependency. This is what the
+ *    Dockerfile HEALTHCHECK and docker-compose.yml run.
+ *  - `/readyz` — READINESS. Can it serve a real request, i.e. is the meta store
+ *    reachable? Answers 503 when not, so a load balancer stops routing to an
+ *    instance that would 500 every request.
+ * Point orchestration at whichever question you are actually asking; see
+ * `./handlers.ts` for why conflating the two is a trap.
+ *
+ * `/system/info` answers a third, unrelated question — "what is this
+ * deployment, and what may it do?" — and is the surface 11-electron.md §8.1/§8.2
+ * gate the desktop UX on (runtime chip, SMTP-gated email, network-dependent
+ * features). See `./schema.ts` for what each flag is entitled to claim.
+ */
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import type { Env } from '../../config/env.js';
+export interface SystemRoutesDeps {
+    /**
+     * The validated boot environment. INJECTED rather than read off `process.env`
+     * inside the handler for the reason `config/env.ts` gives at length: the two
+     * §8.2 flags this reply derives from the environment (`runtime`,
+     * `networkFeaturesAllowed`) are answers the SPA gates features on, and a typo
+     * sampled from ambient state deep in a handler reads as a plausible default
+     * instead of failing the boot.
+     */
+    env: Env;
+}
+export declare const systemRoutes: ({ env }: SystemRoutesDeps) => FastifyPluginAsyncZod;
+//# sourceMappingURL=index.d.ts.map

package/dist/routes/system/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/routes/system/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAI/C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,EAAE,GAAG,CAAC;CACV;AAED,eAAO,MAAM,YAAY,GAAI,SAAS,gBAAgB,KAAG,qBAuBxD,CAAC"}

package/dist/routes/system/index.js

@@ -0,0 +1,18 @@
+import { healthz, readyz, systemInfo } from './handlers.js';
+import { systemHealthzReply, systemInfoReply, systemReadyzReply } from './schema.js';
+export const systemRoutes = ({ env }) => async (app) => {
+    app.get('/healthz', { schema: { response: { 200: systemHealthzReply } } }, async () => healthz());
+    app.get('/readyz', { schema: { response: { 200: systemReadyzReply, 503: systemReadyzReply } } }, async (_request, reply) => {
+        // The meta handle rides on `authContext`, null when the server booted
+        // without a meta store — which `readyz` reports as not-ready too.
+        const result = await readyz(app.authContext?.meta ?? null);
+        void reply.status(result.ok ? 200 : 503);
+        return result;
+    });
+    app.get('/system/info', { schema: { response: { 200: systemInfoReply } } }, 
+    // The meta handle rides on `authContext`, which is null when the server
+    // boots without a meta store — then `dialect` is honestly null and
+    // `smtpConfigured` honestly false (the setting cannot exist without a store).
+    async () => systemInfo({ env, meta: app.authContext?.meta ?? null }));
+};
+//# sourceMappingURL=index.js.map

package/dist/routes/system/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/routes/system/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAcrF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAE,GAAG,EAAoB,EAAyB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC9F,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,kBAAkB,EAAE,EAAE,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IAElG,GAAG,CAAC,GAAG,CACL,SAAS,EACT,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,EAC5E,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QACxB,sEAAsE;QACtE,kEAAkE;QAClE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC;QAC3D,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC;IAChB,CAAC,CACF,CAAC;IAEF,GAAG,CAAC,GAAG,CACL,cAAc,EACd,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,EAAE,EAAE;IAClD,wEAAwE;IACxE,mEAAmE;IACnE,8EAA8E;IAC9E,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,CACrE,CAAC;AACJ,CAAC,CAAC"}

package/dist/routes/system/schema.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Zod schemas for the system resource (naming per 08-server-api.md §1.5:
+ * `<resource><Action><Part>` consts, `z.infer` PascalCase types).
+ */
+import { z } from 'zod';
+/** Meta-store dialects (07-meta-store.md); `null` until meta wiring (wave 2). */
+export declare const metaDialect: z.ZodEnum<{
+    postgres: "postgres";
+    mysql: "mysql";
+    sqlite: "sqlite";
+}>;
+/**
+ * The deployment wrapper, straight off `Env.ADMINIUM_RUNTIME` — the SAME enum,
+ * imported rather than re-spelled. 11-electron.md §4 makes this reply the
+ * authority the SPA gates on ("the SPA trusts the server for feature gating and
+ * the bridge only for native affordances"), so a copy that drifted from the env
+ * schema would be a gate that disagrees with the server it is gating.
+ */
+export declare const systemRuntime: z.ZodEnum<{
+    "self-host": "self-host";
+    desktop: "desktop";
+}>;
+export declare const systemHealthzReply: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    version: z.ZodString;
+    uptime: z.ZodNumber;
+}, z.core.$strip>;
+export type SystemHealthzReply = z.infer<typeof systemHealthzReply>;
+/** Per-dependency readiness verdicts (01-architecture.md §4.1 `/readyz`). */
+export declare const systemReadyzChecks: z.ZodObject<{
+    meta: z.ZodEnum<{
+        ok: "ok";
+        unreachable: "unreachable";
+        "not-configured": "not-configured";
+    }>;
+}, z.core.$strip>;
+export declare const systemReadyzReply: z.ZodObject<{
+    ok: z.ZodBoolean;
+    version: z.ZodString;
+    checks: z.ZodObject<{
+        meta: z.ZodEnum<{
+            ok: "ok";
+            unreachable: "unreachable";
+            "not-configured": "not-configured";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SystemReadyzReply = z.infer<typeof systemReadyzReply>;
+/**
+ * Build/runtime info + the 11-electron.md §8.2 CAPABILITY FLAGS the SPA gates
+ * on. Unauthenticated, like its two sibling probes — deliberately, because the
+ * surfaces that need the answers earliest are pre-auth (`/login`, `/forgot`,
+ * `/setup`), and every field here is either already public (`version`, `node`)
+ * or a yes/no about this deployment's own configuration. Nothing names a host, a
+ * credential, or a user.
+ *
+ * WHAT EACH FLAG IS ENTITLED TO CLAIM — the schema is only honest if the
+ * handler can actually answer it:
+ *
+ *  - `runtime` — parsed at boot from `ADMINIUM_RUNTIME`. Certain.
+ *  - `smtpConfigured` — is `adminium_settings.email.smtp` set? Certain, and it
+ *    is the exact question §8.2's email row asks. It is NOT "email will
+ *    succeed": a configured-but-wrong SMTP host still fails at send time, and no
+ *    flag can promise otherwise. The gap is narrow and the alternative — a probe
+ *    connection per page load — is worse.
+ *  - `networkFeaturesAllowed` — POLICY, from `ADMINIUM_NETWORK_FEATURES`, never
+ *    reachability. See that variable's comment in `config/env.ts`; the short
+ *    version is that a server which promises to make zero unprompted outbound
+ *    calls cannot also report whether outbound calls would work.
+ *  - `lanShare` — is this desktop process bound to every interface (§8.3)?
+ *    Certain, and the strongest kind of certain available: it is read off the
+ *    bind this process was booted with, not off a config file describing what
+ *    somebody meant to happen. See `desktop/lan-share.ts`.
+ */
+export declare const systemInfoReply: z.ZodObject<{
+    version: z.ZodString;
+    node: z.ZodString;
+    dialect: z.ZodNullable<z.ZodEnum<{
+        postgres: "postgres";
+        mysql: "mysql";
+        sqlite: "sqlite";
+    }>>;
+    runtime: z.ZodEnum<{
+        "self-host": "self-host";
+        desktop: "desktop";
+    }>;
+    smtpConfigured: z.ZodBoolean;
+    networkFeaturesAllowed: z.ZodBoolean;
+    lanShare: z.ZodBoolean;
+    desktopDemo: z.ZodBoolean;
+}, z.core.$strip>;
+export type SystemInfoReply = z.infer<typeof systemInfoReply>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/routes/system/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/routes/system/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,iFAAiF;AACjF,eAAO,MAAM,WAAW;;;;EAA0C,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;EAAmB,CAAC;AAE9C,eAAO,MAAM,kBAAkB;;;;iBAM7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB;;;;;;iBAG7B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;iBAK5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;iBA+C1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}