@adminiumjs/adminium 0.1.0-rc.1

package/dist/app.js

@@ -0,0 +1,250 @@
+/**
+ * `buildServer()` — the Fastify 5 application skeleton (08-server-api.md §1,
+ * M2-T01). Assembles: pino logger with the §1.3 redaction set, `req_`-prefixed
+ * request ids echoed as `x-request-id`, fastify-type-provider-zod compilers,
+ * the global §1.4 error envelope, the core/static plugins, and the `/api/v1`
+ * route tree. Wave 1 boots with no meta DB configured — auth/meta wiring is
+ * wave 2 (01-architecture.md §8.1 gates arrive with it).
+ */
+import { randomBytes } from 'node:crypto';
+import { fastify } from 'fastify';
+import { pino } from 'pino';
+import { serializerCompiler, validatorCompiler, } from 'fastify-type-provider-zod';
+import { hashPassword } from './auth/passwords.js';
+import { loadEnv } from './config/env.js';
+import { AppError, errorEnvelope } from './errors.js';
+import { scrubUrlForLog } from './log-scrub.js';
+import { authPlugin } from './plugins/auth.js';
+import { corePlugin } from './plugins/core.js';
+import { staticPlugin } from './plugins/static.js';
+import { createSetupService } from './setup/service.js';
+import { createUpdateCheckService } from './telemetry/update-check.js';
+import { API_PREFIX, registerRoutes } from './routes/index.js';
+import { aboutRoutes } from './routes/about/index.js';
+import { authRoutes } from './routes/auth/index.js';
+import { bootstrapRoutes } from './routes/bootstrap/index.js';
+import { meRoutes } from './routes/me/index.js';
+import { setupRoutes } from './routes/setup/index.js';
+import { APP_VERSION } from './version.js';
+/** Pino deny-by-path redaction set (08-server-api.md §1.3 + ADMINIUM_SECRET). */
+export const REDACT_PATHS = [
+    'req.headers.authorization',
+    'req.headers.cookie',
+    'ADMINIUM_SECRET',
+    '*.ADMINIUM_SECRET',
+    '*.password',
+    '*.newPassword',
+    '*.currentPassword',
+    '*.token',
+    '*.secret',
+    '*.apiKey',
+    '*.dsn',
+    '*.connectionString',
+    '*.smtpUrl',
+    // 11-electron.md §2.2 step 4: the desktop per-boot token. `*.token` above does
+    // not match `bootToken` — pino paths are field names, not substrings — and the
+    // field travels in this product (the §5 exchange body). The QUERY-STRING half
+    // of the same secret is `log-scrub.ts`'s job; paths cannot reach into a string.
+    '*.bootToken',
+    'ADMINIUM_BOOT_TOKEN',
+    '*.ADMINIUM_BOOT_TOKEN',
+];
+/**
+ * The `req` serializer, which REPLACES Fastify's default one.
+ *
+ * Fastify merges the serializers off a supplied `loggerInstance` OVER its own
+ * (`lib/logger-pino.js`: `Object.assign({}, opts.serializers, prevLogger[serializersSym])`),
+ * so defining `req` here wins — and therefore has to reproduce the default's
+ * shape, or every request line in the product silently loses fields. It is the
+ * default, verbatim, with the one change this exists for: {@link scrubUrlForLog}
+ * on the url. Deliberately still no `headers` — the fields below are the whole
+ * contract, and `REDACT_PATHS` covers the header paths for anyone who logs `req`
+ * by hand.
+ */
+function serializeRequest(request) {
+    return {
+        method: request.method,
+        url: scrubUrlForLog(request.url),
+        version: request.headers['accept-version'],
+        host: request.host,
+        remoteAddress: request.ip,
+        remotePort: request.socket.remotePort,
+    };
+}
+/** Structured pino logger: level from env, §1.3 redaction, pretty in dev. */
+export function buildLogger(env, opts = {}) {
+    const pretty = opts.pretty ?? (process.env.NODE_ENV !== 'production' && Boolean(process.stdout.isTTY));
+    const options = {
+        level: env.ADMINIUM_LOG_LEVEL,
+        redact: { paths: [...REDACT_PATHS], censor: '[REDACTED]' },
+        serializers: { req: serializeRequest },
+        ...(pretty ? { transport: { target: 'pino-pretty', options: { colorize: true } } } : {}),
+    };
+    return opts.stream === undefined ? pino(options) : pino(options, opts.stream);
+}
+/** Maps residual (non-AppError) status codes to §1.4 canonical codes. */
+const CODE_BY_STATUS = {
+    400: 'VALIDATION_FAILED',
+    401: 'UNAUTHENTICATED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    409: 'CONFLICT',
+    413: 'PAYLOAD_TOO_LARGE',
+    415: 'VALIDATION_FAILED',
+    422: 'VALIDATION_FAILED',
+    429: 'RATE_LIMITED',
+};
+/**
+ * Normalizes Fastify's `error.validation` entries (ZodFastifySchemaValidation
+ * errors from fastify-type-provider-zod) into `{ path, message, code }` field
+ * details for the 422 envelope, without coupling to the provider's internals.
+ */
+function mapValidationIssues(validation) {
+    return validation.map((entry) => {
+        const raw = entry;
+        const zodIssue = raw.params?.issue;
+        const zodPath = zodIssue?.path;
+        let path = '';
+        if (Array.isArray(zodPath) && zodPath.length > 0) {
+            path = zodPath.map(String).join('.');
+        }
+        else if (typeof raw.instancePath === 'string') {
+            path = raw.instancePath.replace(/^\//, '').replaceAll('/', '.');
+        }
+        const message = typeof raw.message === 'string'
+            ? raw.message
+            : typeof zodIssue?.message === 'string'
+                ? zodIssue.message
+                : 'Invalid value';
+        const code = typeof zodIssue?.code === 'string'
+            ? zodIssue.code
+            : typeof raw.keyword === 'string'
+                ? raw.keyword
+                : 'invalid';
+        return { path, message, code };
+    });
+}
+/**
+ * Builds the configured Fastify instance. Does not listen — `start()` does.
+ * Boots without any database configured (meta wiring lands in wave 2).
+ */
+export async function buildServer(opts = {}) {
+    const env = opts.env ?? loadEnv();
+    const exposeInternalErrors = opts.exposeInternalErrors ?? process.env.NODE_ENV !== 'production';
+    const loggerInstance = opts.logger === false
+        ? pino({ level: 'silent' })
+        : typeof opts.logger === 'object'
+            ? opts.logger
+            : buildLogger(env);
+    const app = fastify({
+        loggerInstance,
+        // §1.3: `req_` + 8 lowercase hex chars, e.g. req_8f2a91cd.
+        genReqId: () => `req_${randomBytes(4).toString('hex')}`,
+        // An inbound x-request-id is honored only behind a trusted proxy (§1.3).
+        requestIdHeader: env.ADMINIUM_TRUST_PROXY ? 'x-request-id' : false,
+        // Hop count 1, NEVER a bare `true`: `trustProxy: true` trusts every hop,
+        // so proxy-addr returns the LEFT-most (fully client-supplied)
+        // X-Forwarded-For entry as `request.ip` — an attacker rotating the header
+        // then gets a fresh §6 rate-limit bucket per request and forges the audit
+        // trail's source ip. With `1`, only the immediate peer (Caddy) is trusted
+        // and `request.ip` is the RIGHT-most entry — the one Caddy itself
+        // appended, which no client controls. The documented deployment is a
+        // single reverse proxy (§7 item 5: "behind Caddy/TLS").
+        trustProxy: env.ADMINIUM_TRUST_PROXY ? 1 : false,
+        bodyLimit: 1_048_576, // 1 MiB JSON; multipart gets its own limits (§3.10)
+    }).withTypeProvider();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    // Every /api route must declare a schema — no untyped routes (§1.1, 08-T01).
+    app.addHook('onRoute', (route) => {
+        const methods = Array.isArray(route.method) ? route.method : [route.method];
+        if (!route.url.startsWith('/api/'))
+            return;
+        if (methods.every((method) => method === 'HEAD' || method === 'OPTIONS'))
+            return;
+        if (route.schema === undefined) {
+            throw new Error(`route ${methods.join(',')} ${route.url} registered without a schema (08-server-api.md §1.1)`);
+        }
+    });
+    // The request id is echoed on every response (§1.3).
+    app.addHook('onSend', async (request, reply) => {
+        void reply.header('x-request-id', request.id);
+    });
+    // Global §1.4 error envelope.
+    app.setErrorHandler((error, request, reply) => {
+        const requestId = request.id;
+        if (error instanceof AppError) {
+            void reply
+                .status(error.statusCode)
+                .send(errorEnvelope(error.code, error.message, requestId, error.details));
+            return;
+        }
+        if (Array.isArray(error.validation) && error.validation.length > 0) {
+            const details = {
+                in: error.validationContext ?? 'body',
+                issues: mapValidationIssues(error.validation),
+            };
+            void reply
+                .status(422)
+                .send(errorEnvelope('VALIDATION_FAILED', `Request ${error.validationContext ?? 'input'} failed validation.`, requestId, details));
+            return;
+        }
+        const statusCode = typeof error.statusCode === 'number' && error.statusCode >= 400 ? error.statusCode : 500;
+        const code = CODE_BY_STATUS[statusCode];
+        if (statusCode < 500 && code !== undefined) {
+            void reply.status(statusCode).send(errorEnvelope(code, error.message, requestId));
+            return;
+        }
+        // Unexpected: full stack to the log under the same requestId; message
+        // hidden from the client in production (§1.4).
+        request.log.error({ err: error }, 'unhandled error');
+        const message = exposeInternalErrors
+            ? error.message
+            : 'Something went wrong. Share the request id with support.';
+        void reply.status(500).send(errorEnvelope('INTERNAL', message, requestId));
+    });
+    // `staticRoot` rides along so core can hash the served index.html's inline
+    // scripts into the CSP allowance (plugins/core.ts).
+    await app.register(corePlugin, { env, staticRoot: opts.staticRoot });
+    await app.register(authPlugin, {
+        env,
+        metaDb: opts.metaDb ?? null,
+        deliverResetToken: opts.onPasswordResetToken,
+    });
+    await app.register(staticPlugin, { root: opts.staticRoot });
+    // Unknown route → 404 envelope; non-API GET/HEAD falls back to the SPA
+    // index when a dashboard build is being served (05/09 request lifecycle).
+    app.setNotFoundHandler((request, reply) => {
+        const isApi = request.url.startsWith('/api/');
+        if (!isApi &&
+            app.spaRoot !== null &&
+            (request.method === 'GET' || request.method === 'HEAD')) {
+            void reply.sendFile('index.html');
+            return;
+        }
+        void reply
+            .status(404)
+            .send(errorEnvelope('NOT_FOUND', `Route ${request.method}:${request.url} not found.`, request.id));
+    });
+    await registerRoutes(app, env);
+    // Auth + me + bootstrap resources (08-server-api.md §2.1–§2.2,
+    // 09-generated-app.md §2.1) under the same prefix.
+    await app.register(async (api) => {
+        await api.register(authRoutes);
+        await api.register(meRoutes);
+        await api.register(bootstrapRoutes);
+        // First-run setup + About (M10-T04). Both need a meta store to say
+        // anything at all, so — unlike auth, whose 503 is itself the answer —
+        // they are wired only when one is configured. Composition roots that
+        // want injected services (tests with a stubbed release feed, the CLI)
+        // build the server without `metaDb` and register these factories
+        // themselves, exactly as the LLM/settings resources are wired.
+        const meta = opts.metaDb;
+        if (meta !== undefined && meta !== null) {
+            await api.register(setupRoutes({ service: createSetupService({ meta, hashPassword }) }));
+            await api.register(aboutRoutes({ meta, updates: createUpdateCheckService({ meta, version: APP_VERSION }) }));
+        }
+    }, { prefix: API_PREFIX });
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

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

package/dist/auth/audit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Auth audit trail (08-server-api.md §7 item 9): every auth mutation writes an
+ * `auth`-category entry — login, login_failed, logout, 2FA lifecycle, password
+ * reset — with IP, user agent, and request id, never any secret material.
+ */
+import type { FastifyRequest } from 'fastify';
+import { type AuditEntry, type MetaDb } from '@adminium/meta';
+export interface AuthAuditInput {
+    /** Dotted verb, e.g. `login`, `login_failed`, `2fa_enrolled`. */
+    action: string;
+    /** `usr_…` id when the principal is known. */
+    actorId?: string | null | undefined;
+    /** Display snapshot: user name, or the attempted email on failures. */
+    actorLabel: string;
+    changes?: {
+        before?: Record<string, unknown> | null;
+        after?: Record<string, unknown> | null;
+    } | null;
+}
+/** Appends an `auth` audit entry stamped with the request's context. */
+export declare function auditAuth(meta: MetaDb, request: FastifyRequest, input: AuthAuditInput): Promise<AuditEntry>;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/auth/audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAa,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACtG;AAED,wEAAwE;AACxE,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,UAAU,CAAC,CAarB"}

package/dist/auth/audit.js

@@ -0,0 +1,17 @@
+import { auditRepo } from '@adminium/meta';
+/** Appends an `auth` audit entry stamped with the request's context. */
+export async function auditAuth(meta, request, input) {
+    const userAgent = request.headers['user-agent'];
+    return auditRepo(meta).append({
+        actorKind: 'user',
+        actorId: input.actorId ?? null,
+        actorLabel: input.actorLabel,
+        category: 'auth',
+        action: input.action,
+        changes: input.changes ?? null,
+        ip: request.ip,
+        userAgent: typeof userAgent === 'string' ? userAgent.slice(0, 300) : null,
+        requestId: request.id,
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/auth/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/auth/audit.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAgC,MAAM,gBAAgB,CAAC;AAYzE,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,OAAuB,EACvB,KAAqB;IAErB,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAChD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QAC5B,SAAS,EAAE,MAAM;QACjB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,SAAS,EAAE,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;QACzE,SAAS,EAAE,OAAO,CAAC,EAAE;KACtB,CAAC,CAAC;AACL,CAAC"}

package/dist/auth/desktop-session.d.ts

@@ -0,0 +1,53 @@
+/**
+ * True when `address` is a loopback address in any of the shapes Node hands out.
+ *
+ * `undefined`/empty ⇒ FALSE. An absent `remoteAddress` means the socket is gone
+ * (or is not a socket at all); "we could not tell who this is" is not "this is
+ * the local user", and the failure has to land on the deny side.
+ */
+export declare function isLoopbackAddress(address: string | undefined | null): boolean;
+/** The narrow slice of a request this module reads: the raw socket's peer. */
+export interface PeerSocketLike {
+    remoteAddress?: string | undefined;
+}
+/**
+ * The §2.4 peer check. Takes the SOCKET, never the request, so a caller cannot
+ * pass the proxy-aware `request.ip` by accident — the type will not allow it.
+ */
+export declare function isLoopbackPeer(socket: PeerSocketLike | undefined | null): boolean;
+/**
+ * Constant-time equality for the boot token (§5: "compares against
+ * `ADMINIUM_BOOT_TOKEN` (constant-time)").
+ *
+ * Both sides are hashed first. `timingSafeEqual` THROWS on a length mismatch,
+ * so comparing the raw strings would both leak the token's length through the
+ * error path and turn a short guess into a 500 instead of a 401. SHA-256 makes
+ * every candidate exactly 32 bytes, which is the point — the comparison is over
+ * digests, and the digest of a wrong guess differs from the first byte on.
+ */
+export declare function bootTokenMatches(candidate: string, bootToken: string): boolean;
+/** Why a claim was refused. The route maps every one of these to a 401. */
+export type BootTokenClaim = 'ok' | 'invalid' | 'used';
+export interface BootTokenGuard {
+    /**
+     * Verify and CONSUME. Exactly one call in this process's lifetime can return
+     * `ok`; every later call returns `used`, including a second call with the
+     * correct token (that is the §5 replay case, not a retry).
+     */
+    claim(candidate: string): BootTokenClaim;
+    /** Introspection for tests/diagnostics — never gates anything. */
+    readonly consumed: boolean;
+}
+/**
+ * The one-shot guard over this boot's token.
+ *
+ * ORDERING MATTERS: the `used` check comes FIRST. Once the token is spent the
+ * answer is `used` for every candidate, right or wrong, so a spent boot stops
+ * being an oracle that confirms a guessed token by answering it differently.
+ *
+ * The claim is taken BEFORE the session is issued (see the route): if minting
+ * the session then fails, the token is still burned. Better a user who clicks
+ * relaunch than a token that survives its first use.
+ */
+export declare function createBootTokenGuard(bootToken: string): BootTokenGuard;
+//# sourceMappingURL=desktop-session.d.ts.map

package/dist/auth/desktop-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-session.d.ts","sourceRoot":"","sources":["../../src/auth/desktop-session.ts"],"names":[],"mappings":"AA2CA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAa7E;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAEjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAI9E;AAED,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAatE"}

package/dist/auth/desktop-session.js

@@ -0,0 +1,111 @@
+/**
+ * The desktop boot-token mechanics (11-electron.md §5, §2.2 step 4).
+ *
+ * Three primitives, deliberately framework-free so they can be tested as what
+ * they are — security decisions — rather than through a route:
+ *
+ *   {@link isLoopbackPeer}      — is the SOCKET peer this same machine?
+ *   {@link bootTokenMatches}    — constant-time comparison against the boot token
+ *   {@link createBootTokenGuard} — the one-shot-per-boot claim
+ *
+ * ─── Why the socket, and not `request.ip` ────────────────────────────────────
+ *
+ * `request.ip` is Fastify's PROXY-AWARE address: with `trustProxy` on it is
+ * whatever `X-Forwarded-For` said. That header is a claim by the client, and
+ * this is the one route in the product where a client's claim about its own
+ * address would be an authentication bypass — a LAN peer (§8.3 binds `0.0.0.0`)
+ * could send `X-Forwarded-For: 127.0.0.1` and become the super admin without a
+ * password. So the check reads `socket.remoteAddress`: the kernel's view of who
+ * actually opened the connection, which no header can move. §2.4 states the rule
+ * without qualification — "rejects non-loopback peers unconditionally" — and
+ * unconditional means "not even for a proxy we would otherwise trust".
+ *
+ * ─── Why one-shot lives in memory ────────────────────────────────────────────
+ *
+ * "One success per boot token" (§5) and "never persisted" (§2.2) are the same
+ * requirement seen twice: the token's lifetime IS this process's lifetime. A
+ * replay table in the meta store would outlive the token it guards, and give the
+ * next boot a row to be confused by. The guard is therefore a closure over a
+ * boolean, and a restarted server is a new boot with a new token — which is
+ * exactly why "a token from a previous boot" fails: nothing in this process ever
+ * heard of it.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * IPv4 loopback is a whole /8 (127.0.0.0/8), not just 127.0.0.1 — `127.0.0.2`
+ * is equally this machine and equally reachable from nowhere else.
+ */
+const IPV4_LOOPBACK = /^127\.(?:\d{1,3})\.(?:\d{1,3})\.(?:\d{1,3})$/;
+/** `::ffff:127.0.0.1` — an IPv4 peer seen through a dual-stack listener. */
+const IPV4_MAPPED_PREFIX = '::ffff:';
+/**
+ * True when `address` is a loopback address in any of the shapes Node hands out.
+ *
+ * `undefined`/empty ⇒ FALSE. An absent `remoteAddress` means the socket is gone
+ * (or is not a socket at all); "we could not tell who this is" is not "this is
+ * the local user", and the failure has to land on the deny side.
+ */
+export function isLoopbackAddress(address) {
+    if (address === undefined || address === null || address === '')
+        return false;
+    // Strip a zone index (`fe80::1%en0`) before comparing — it belongs to the
+    // interface, not the address, and `::1%lo0` is still `::1`.
+    const zoneless = address.split('%')[0] ?? '';
+    const normalized = zoneless.toLowerCase();
+    if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1')
+        return true;
+    if (normalized.startsWith(IPV4_MAPPED_PREFIX)) {
+        return IPV4_LOOPBACK.test(normalized.slice(IPV4_MAPPED_PREFIX.length));
+    }
+    return IPV4_LOOPBACK.test(normalized);
+}
+/**
+ * The §2.4 peer check. Takes the SOCKET, never the request, so a caller cannot
+ * pass the proxy-aware `request.ip` by accident — the type will not allow it.
+ */
+export function isLoopbackPeer(socket) {
+    return isLoopbackAddress(socket?.remoteAddress);
+}
+/**
+ * Constant-time equality for the boot token (§5: "compares against
+ * `ADMINIUM_BOOT_TOKEN` (constant-time)").
+ *
+ * Both sides are hashed first. `timingSafeEqual` THROWS on a length mismatch,
+ * so comparing the raw strings would both leak the token's length through the
+ * error path and turn a short guess into a 500 instead of a 401. SHA-256 makes
+ * every candidate exactly 32 bytes, which is the point — the comparison is over
+ * digests, and the digest of a wrong guess differs from the first byte on.
+ */
+export function bootTokenMatches(candidate, bootToken) {
+    const a = createHash('sha256').update(candidate, 'utf8').digest();
+    const b = createHash('sha256').update(bootToken, 'utf8').digest();
+    return timingSafeEqual(a, b);
+}
+/**
+ * The one-shot guard over this boot's token.
+ *
+ * ORDERING MATTERS: the `used` check comes FIRST. Once the token is spent the
+ * answer is `used` for every candidate, right or wrong, so a spent boot stops
+ * being an oracle that confirms a guessed token by answering it differently.
+ *
+ * The claim is taken BEFORE the session is issued (see the route): if minting
+ * the session then fails, the token is still burned. Better a user who clicks
+ * relaunch than a token that survives its first use.
+ */
+export function createBootTokenGuard(bootToken) {
+    let consumed = false;
+    return {
+        claim(candidate) {
+            if (consumed)
+                return 'used';
+            if (!bootTokenMatches(candidate, bootToken))
+                return 'invalid';
+            consumed = true;
+            return 'ok';
+        },
+        get consumed() {
+            return consumed;
+        },
+    };
+}
+//# sourceMappingURL=desktop-session.js.map

package/dist/auth/desktop-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-session.js","sourceRoot":"","sources":["../../src/auth/desktop-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;;GAGG;AACH,MAAM,aAAa,GAAG,8CAA8C,CAAC;AAErE,4EAA4E;AAC5E,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAkC;IAClE,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAE9E,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IAE1C,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,UAAU,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC9C,OAAO,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyC;IACtE,OAAO,iBAAiB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,SAAiB;IACnE,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;IAClE,MAAM,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;IAClE,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO;QACL,KAAK,CAAC,SAAiB;YACrB,IAAI,QAAQ;gBAAE,OAAO,MAAM,CAAC;YAC5B,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC9D,QAAQ,GAAG,IAAI,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,QAAQ;YACV,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/auth/passwords.d.ts

@@ -0,0 +1,17 @@
+/** OWASP argon2id first-choice configuration (m=19456 KiB, t=2, p=1). */
+export declare const ARGON2_OPTIONS: {
+    readonly type: 2;
+    readonly memoryCost: 19456;
+    readonly timeCost: 2;
+    readonly parallelism: 1;
+};
+/** Hashes a plaintext password to a PHC-format argon2id string. */
+export declare function hashPassword(plain: string): Promise<string>;
+/**
+ * Constant-shape verify: malformed/foreign hashes return `false` instead of
+ * throwing so login failure handling stays uniform (no user enumeration).
+ */
+export declare function verifyPassword(hash: string, plain: string): Promise<boolean>;
+/** True when `hash` was minted with weaker/different parameters than ours. */
+export declare function needsRehash(hash: string): boolean;
+//# sourceMappingURL=passwords.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"passwords.d.ts","sourceRoot":"","sources":["../../src/auth/passwords.ts"],"names":[],"mappings":"AAQA,yEAAyE;AACzE,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,mEAAmE;AACnE,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjE;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMlF;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMjD"}

package/dist/auth/passwords.js

@@ -0,0 +1,40 @@
+/**
+ * Password hashing (08-server-api.md §2.1, §7 item 7): argon2id with the
+ * OWASP first-choice parameters — 19 MiB memory, 2 iterations, parallelism 1.
+ * Only this module talks to the argon2 binding; callers never see raw hashes
+ * beyond passing them to/from `@adminium/meta`.
+ */
+import argon2 from 'argon2';
+/** OWASP argon2id first-choice configuration (m=19456 KiB, t=2, p=1). */
+export const ARGON2_OPTIONS = {
+    type: argon2.argon2id,
+    memoryCost: 19_456, // KiB = 19 MiB
+    timeCost: 2,
+    parallelism: 1,
+};
+/** Hashes a plaintext password to a PHC-format argon2id string. */
+export async function hashPassword(plain) {
+    return argon2.hash(plain, ARGON2_OPTIONS);
+}
+/**
+ * Constant-shape verify: malformed/foreign hashes return `false` instead of
+ * throwing so login failure handling stays uniform (no user enumeration).
+ */
+export async function verifyPassword(hash, plain) {
+    try {
+        return await argon2.verify(hash, plain);
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `hash` was minted with weaker/different parameters than ours. */
+export function needsRehash(hash) {
+    try {
+        return argon2.needsRehash(hash, ARGON2_OPTIONS);
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=passwords.js.map

package/dist/auth/passwords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwords.js","sourceRoot":"","sources":["../../src/auth/passwords.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC,QAAQ;IACrB,UAAU,EAAE,MAAM,EAAE,eAAe;IACnC,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,CAAC;CACN,CAAC;AAEX,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAa;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,KAAa;IAC9D,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/auth/sessions.d.ts

@@ -0,0 +1,77 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type MetaDb, type Session } from '@adminium/meta';
+export declare const SESSION_COOKIE = "adminium_session";
+export declare const SESSION_TOKEN_PREFIX = "adms_";
+export declare const CHALLENGE_TOKEN_PREFIX = "admc_";
+export declare const RESET_TOKEN_PREFIX = "admr_";
+/** Sliding-expiry defaults (08-server-api.md §2.1). */
+export declare const SESSION_IDLE_TTL_MS: number;
+export declare const SESSION_ABSOLUTE_TTL_MS: number;
+/** 2FA login challenge: 5 minutes, single-use (§2.1). */
+export declare const CHALLENGE_TTL_MS: number;
+/** Password-reset tokens: single-use, 30-minute TTL (§7 item 7). */
+export declare const RESET_TOKEN_TTL_MS: number;
+/** `<prefix>` + 32 random bytes base64url (43 chars of payload). */
+export declare function mintToken(prefix: string): string;
+/** SHA-256 hex of the full token string — the only form stored at rest. */
+export declare function hashToken(token: string): string;
+export interface RequestMeta {
+    ip?: string | null | undefined;
+    userAgent?: string | null | undefined;
+}
+export interface MintedSession {
+    token: string;
+    session: Session;
+}
+/**
+ * Creates a full session row and returns the plaintext token exactly once.
+ * `absoluteDeadline` caps `expires_at` below the default 30-day horizon so
+ * rotation never extends the original absolute lifetime.
+ */
+export declare function createSession(meta: MetaDb, userId: string, reqMeta?: RequestMeta, at?: number, absoluteDeadline?: number): Promise<MintedSession>;
+export type SessionResolution = {
+    state: 'none';
+} | {
+    state: 'expired';
+    session: Session;
+} | {
+    state: 'active';
+    session: Session;
+};
+/**
+ * Resolves a cookie token to a session, distinguishing "no such session"
+ * (`none` → UNAUTHENTICATED) from "existed but timed out" (`expired` →
+ * SESSION_EXPIRED). Revoked sessions resolve to `none` — sign-out is not the
+ * expired-session UX. Idle timeout: `last_seen_at + 7d`; absolute: `expires_at`.
+ */
+export declare function resolveSessionByToken(meta: MetaDb, token: string, at?: number): Promise<SessionResolution>;
+/**
+ * Privilege-boundary rotation hook (§7 item 7): revokes the old row and mints
+ * a fresh token for the same user, keeping the original absolute deadline.
+ * Call on login step-ups, role changes, and password changes that keep the
+ * current session alive.
+ */
+export declare function rotateSession(meta: MetaDb, session: Session, reqMeta?: RequestMeta, at?: number): Promise<MintedSession>;
+/** Mints a 5-minute single-use 2FA challenge row (`admc_` prefix). */
+export declare function createChallenge(meta: MetaDb, userId: string, reqMeta?: RequestMeta, at?: number): Promise<MintedSession>;
+/**
+ * Atomically consumes a challenge token: the first caller revokes the row and
+ * wins; replays, expired, or non-challenge tokens return `null`.
+ */
+export declare function consumeChallenge(meta: MetaDb, token: string, at?: number): Promise<Session | null>;
+/** True when the request arrived over TLS (directly or via trusted proxy). */
+export declare function isSecureRequest(request: FastifyRequest): boolean;
+/** Cookie contract (§2.1): httpOnly, SameSite=Lax, signed, path /. */
+export declare function sessionCookieOptions(secure: boolean): {
+    readonly path: "/";
+    readonly httpOnly: true;
+    readonly sameSite: "lax";
+    readonly signed: true;
+    readonly secure: boolean;
+    readonly maxAge: number;
+};
+export declare function setSessionCookie(reply: FastifyReply, token: string, request: FastifyRequest): void;
+export declare function clearSessionCookie(reply: FastifyReply, request: FastifyRequest): void;
+/** Reads and unsigns the session cookie; `null` on absent/tampered values. */
+export declare function readSessionCookie(request: FastifyRequest): string | null;
+//# sourceMappingURL=sessions.d.ts.map

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

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