@adminiumjs/adminium 0.1.0-rc.1

package/dist/notifications/notify.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The shared in-app notification writer (07-meta-store.md §3.20,
+ * 08-server-api.md §3 `notifications:<userId>`): every producer inserts
+ * through `notificationsRepo` and, when it has the hub, publishes the row on
+ * the recipient's channel so an open session's bell/badge updates without a
+ * refetch cycle.
+ *
+ * Channel-preference gating lives HERE, not in the repo: a producer names its
+ * `kind` (which doubles as the §3.21 `event_key`) and the writer consults
+ * `notificationPrefsRepo.channelsFor(...).inApp` — a user who switched the
+ * event off gets no row. Email/push channels are stored intent only in this
+ * build (no SMTP / no push transport); the prefs ROUTE explains that, per the
+ * never-hide-always-explain rule — the writer just ignores them.
+ */
+import { type CreateNotificationInput, type MetaDb, type Notification } from '@adminium/meta';
+/** Event type published on `notifications:<userId>` for a fresh row. */
+export declare const NOTIFICATION_CREATED_EVENT = "notification.created";
+/** Event type published when rows flip to read (badge sync across tabs). */
+export declare const NOTIFICATION_READ_EVENT = "notification.read";
+/** The §3 channel name for one user's notification stream. */
+export declare function notificationsChannel(userId: string): string;
+/** The slice of RealtimeHub the writer needs (tests pass a recorder). */
+export interface NotificationPublisher {
+    publish(channel: string, type: string, data: unknown): unknown;
+}
+export interface NotifyOptions {
+    /** When present, the row is fanned out on `notifications:<userId>`. */
+    hub?: NotificationPublisher | undefined;
+    /**
+     * Consult the user's §3.21 prefs for `kind` before inserting; default true.
+     * Producers of rows the user cannot opt out of (none today) pass false.
+     */
+    respectPrefs?: boolean | undefined;
+    at?: number | undefined;
+}
+/**
+ * Insert one notification (prefs permitting) and publish it. Returns the row,
+ * or `null` when the recipient has the event's in-app channel switched off.
+ * Best-effort belongs at the CALL SITE (backup/notify.ts precedent): a failed
+ * courtesy row must not fail the operation that succeeded.
+ */
+export declare function notify(meta: MetaDb, input: CreateNotificationInput, opts?: NotifyOptions): Promise<Notification | null>;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notifications/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/notifications/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AACjE,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,GAAG,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,uBAAuB,EAC9B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAU9B"}

package/dist/notifications/notify.js

@@ -0,0 +1,42 @@
+/**
+ * The shared in-app notification writer (07-meta-store.md §3.20,
+ * 08-server-api.md §3 `notifications:<userId>`): every producer inserts
+ * through `notificationsRepo` and, when it has the hub, publishes the row on
+ * the recipient's channel so an open session's bell/badge updates without a
+ * refetch cycle.
+ *
+ * Channel-preference gating lives HERE, not in the repo: a producer names its
+ * `kind` (which doubles as the §3.21 `event_key`) and the writer consults
+ * `notificationPrefsRepo.channelsFor(...).inApp` — a user who switched the
+ * event off gets no row. Email/push channels are stored intent only in this
+ * build (no SMTP / no push transport); the prefs ROUTE explains that, per the
+ * never-hide-always-explain rule — the writer just ignores them.
+ */
+import { notificationPrefsRepo, notificationsRepo, } from '@adminium/meta';
+/** Event type published on `notifications:<userId>` for a fresh row. */
+export const NOTIFICATION_CREATED_EVENT = 'notification.created';
+/** Event type published when rows flip to read (badge sync across tabs). */
+export const NOTIFICATION_READ_EVENT = 'notification.read';
+/** The §3 channel name for one user's notification stream. */
+export function notificationsChannel(userId) {
+    return `notifications:${userId}`;
+}
+/**
+ * Insert one notification (prefs permitting) and publish it. Returns the row,
+ * or `null` when the recipient has the event's in-app channel switched off.
+ * Best-effort belongs at the CALL SITE (backup/notify.ts precedent): a failed
+ * courtesy row must not fail the operation that succeeded.
+ */
+export async function notify(meta, input, opts = {}) {
+    if (opts.respectPrefs ?? true) {
+        const channels = await notificationPrefsRepo(meta).channelsFor(input.userId, input.kind);
+        if (!channels.inApp)
+            return null;
+    }
+    const row = await notificationsRepo(meta).create(input, opts.at);
+    opts.hub?.publish(notificationsChannel(row.userId), NOTIFICATION_CREATED_EVENT, {
+        notification: row,
+    });
+    return row;
+}
+//# sourceMappingURL=notify.js.map

package/dist/notifications/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/notifications/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAIlB,MAAM,gBAAgB,CAAC;AAExB,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,sBAAsB,CAAC;AACjE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAE3D,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,iBAAiB,MAAM,EAAE,CAAC;AACnC,CAAC;AAkBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,IAAY,EACZ,KAA8B,EAC9B,OAAsB,EAAE;IAExB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzF,IAAI,CAAC,QAAQ,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;IACnC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACjE,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,0BAA0B,EAAE;QAC9E,YAAY,EAAE,GAAG;KAClB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/plugins/auth.d.ts

@@ -0,0 +1,42 @@
+import { type ApiKey, type MetaDb, type Session, type User } from '@adminium/meta';
+import type { Env } from '../config/env.js';
+/** Payload handed to the reset-delivery hook (email transport lands later). */
+export interface PasswordResetDelivery {
+    userId: string;
+    email: string;
+    /** Plaintext single-use token — never stored, never logged. */
+    token: string;
+    expiresAt: number;
+}
+export interface AuthContext {
+    meta: MetaDb;
+    env: Env;
+    /** HKDF-derived AES key for TOTP secrets at rest. */
+    totpKey: Buffer;
+    /** Test/email hook: receives plaintext reset tokens on `password/forgot`. */
+    deliverResetToken: ((delivery: PasswordResetDelivery) => void) | undefined;
+}
+export interface AuthPluginOptions {
+    env: Env;
+    metaDb?: MetaDb | null | undefined;
+    deliverResetToken?: ((delivery: PasswordResetDelivery) => void) | undefined;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** Active-session user; `null` for anonymous or API-key principals. */
+        user: User | null;
+        /** The resolved live session row backing `user`. */
+        session: Session | null;
+        /** API-key principal (bearer) — RBAC wiring is the rbac plugin's. */
+        apiKey: ApiKey | null;
+        /** True when a session token was presented but timed out (§1.4). */
+        sessionExpired: boolean;
+    }
+    interface FastifyInstance {
+        authContext: AuthContext | null;
+        requireMeta: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+        requireAuth: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    }
+}
+export declare const authPlugin: import("fastify").FastifyPluginCallback<AuthPluginOptions, import("fastify").RawServerDefault, import("fastify").FastifyTypeProviderDefault, import("fastify").FastifyBaseLogger>;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/plugins/auth.ts"],"names":[],"mappings":"AAeA,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAS5C,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,iBAAiB,EAAE,CAAC,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC5E;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,iBAAiB,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC7E;AAKD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,uEAAuE;QACvE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;QAClB,oDAAoD;QACpD,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACxB,qEAAqE;QACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,oEAAoE;QACpE,cAAc,EAAE,OAAO,CAAC;KACzB;IACD,UAAU,eAAe;QACvB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;QAChC,WAAW,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7E,WAAW,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9E;CACF;AAED,eAAO,MAAM,UAAU,mLA0EtB,CAAC"}

package/dist/plugins/auth.js

@@ -0,0 +1,84 @@
+/**
+ * `auth` plugin (08-server-api.md §1.2, §2.1): resolves the signed
+ * `adminium_session` cookie (or an `Authorization: Bearer adm_…` API key —
+ * stub for the key-management routes) to a principal on every request and
+ * decorates `request.user` / `request.session` / `request.apiKey`.
+ *
+ * Exposes:
+ * - `app.authContext` — meta handle + derived keys + delivery hooks, `null`
+ *   when the server boots without a meta DB (wave-1 compatible);
+ * - `app.requireMeta` — preHandler: 503 META_NOT_CONFIGURED without meta;
+ * - `app.requireAuth` — preHandler: 401 UNAUTHENTICATED (no/invalid/revoked
+ *   token) or 401 SESSION_EXPIRED (session existed but idle/absolute timed out).
+ */
+import fp from 'fastify-plugin';
+import { apiKeysRepo, sessionsRepo, usersRepo, } from '@adminium/meta';
+import { AppError, UnauthorizedError } from '../errors.js';
+import { hashToken, readSessionCookie, resolveSessionByToken, } from '../auth/sessions.js';
+import { totpEncryptionKey } from '../auth/totp.js';
+/** API keys are Stripe-style `adm_…` bearer tokens (07-meta-store.md §3.7). */
+const API_KEY_PREFIX = 'adm_';
+export const authPlugin = fp(async (app, opts) => {
+    const meta = opts.metaDb ?? null;
+    const context = meta === null
+        ? null
+        : {
+            meta,
+            env: opts.env,
+            totpKey: totpEncryptionKey(opts.env.ADMINIUM_SECRET),
+            deliverResetToken: opts.deliverResetToken,
+        };
+    app.decorate('authContext', context);
+    app.decorateRequest('user', null);
+    app.decorateRequest('session', null);
+    app.decorateRequest('apiKey', null);
+    app.decorateRequest('sessionExpired', false);
+    app.decorate('requireMeta', async () => {
+        if (context === null) {
+            throw new AppError(503, 'META_NOT_CONFIGURED', 'No meta store is configured — authentication is unavailable.');
+        }
+    });
+    app.decorate('requireAuth', async (request) => {
+        if (request.user !== null && request.session !== null)
+            return;
+        if (request.sessionExpired)
+            throw new UnauthorizedError('SESSION_EXPIRED');
+        throw new UnauthorizedError('UNAUTHENTICATED');
+    });
+    if (context === null)
+        return;
+    app.addHook('onRequest', async (request) => {
+        const now = Date.now();
+        // API-key bearer stub (§8): resolves the principal; RBAC comes later.
+        const authorization = request.headers.authorization;
+        if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+            const bearer = authorization.slice('Bearer '.length).trim();
+            if (bearer.startsWith(API_KEY_PREFIX)) {
+                const key = await apiKeysRepo(context.meta).findValidByTokenHash(hashToken(bearer), now);
+                if (key !== null) {
+                    request.apiKey = key;
+                    await apiKeysRepo(context.meta).touchLastUsed(key.id, now);
+                }
+                return;
+            }
+        }
+        const token = readSessionCookie(request);
+        if (token === null)
+            return;
+        const resolution = await resolveSessionByToken(context.meta, token, now);
+        if (resolution.state === 'expired') {
+            request.sessionExpired = true;
+            return;
+        }
+        if (resolution.state !== 'active')
+            return;
+        const user = await usersRepo(context.meta).findById(resolution.session.userId);
+        if (user === null || user.status !== 'active')
+            return;
+        request.user = user;
+        request.session = resolution.session;
+        // Sliding idle window: throttled to one write per minute by the repo.
+        await sessionsRepo(context.meta).touch(resolution.session.id, now);
+    });
+}, { name: 'adminium-auth', fastify: '5.x', dependencies: ['adminium-core'] });
+//# sourceMappingURL=auth.js.map

package/dist/plugins/auth.js.map

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

package/dist/plugins/core.d.ts

@@ -0,0 +1,48 @@
+import type { Env } from '../config/env.js';
+/** One §6 bucket: a fixed window of `max` requests per `timeWindowMs`. */
+export interface RateBucket {
+    max: number;
+    timeWindowMs: number;
+}
+/**
+ * The §6 bucket table (08-server-api.md §6). Keys are the
+ * `config.rateLimitBucket` markers routes declare; a route declaring a bucket
+ * that is not in this table fails AT BOOT (the onRoute hook throws), so the
+ * two spellings cannot drift apart silently.
+ *
+ *  - `auth-login`      — `/auth/login`, `/auth/2fa/verify`, `/setup/super-admin`,
+ *                        `/auth/desktop-session` (5/min, §6 row 1; §7 item 7
+ *                        "TOTP … verify rate-limited").
+ *  - `auth-password-forgot` — `/auth/password/forgot` (3/hour, §6 row 2).
+ *  - `auth-password-reset`  — `/auth/password/reset`: the token CONSUME side.
+ *                        Not in the §6 table by name, but §7 item 7's
+ *                        single-use + 30-min-TTL reset tokens are only as
+ *                        strong as the guess rate this cap sets.
+ *  - `search`          — `GET /search` (60/min, §6 row 5): each request fans
+ *                        out parallel ILIKE queries over up to 20 tables, the
+ *                        cheapest DoS lever of the unbucketed routes.
+ *
+ * DELIBERATE §6 DEVIATIONS (documented here so the table can't drift
+ * silently):
+ *  - The auth buckets key per-IP, not the spec'd "IP + email": per-IP keying
+ *    is what guarantees a LAN flood can never lock the loopback
+ *    `/auth/desktop-session` exchange out (tested in rate-limit.test.ts). A
+ *    per-account counter for distributed credential sprays is a possible
+ *    additive follow-up, not a replacement.
+ *  - The remaining §6 rows (General API 300/min, widget-data 120/min,
+ *    exports/imports 10/h, LLM 20/h, files 30/h) and the
+ *    `adminium_settings.security` override are a tracked pre-v1 hardening
+ *    follow-up — they need principal-resolution (session-keyed) buckets,
+ *    which this per-IP fixed-window store does not provide yet.
+ */
+export declare const RATE_BUCKETS: Readonly<Record<string, RateBucket>>;
+export interface CorePluginOptions {
+    env: Env;
+    /**
+     * The dashboard build directory `app.ts` hands the static plugin — read here
+     * (never served) to compute the CSP inline-script hash allowance.
+     */
+    staticRoot?: string | undefined;
+}
+export declare const corePlugin: import("fastify").FastifyPluginCallback<CorePluginOptions, import("fastify").RawServerDefault, import("fastify").FastifyTypeProviderDefault, import("fastify").FastifyBaseLogger>;
+//# sourceMappingURL=core.d.ts.map

package/dist/plugins/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/plugins/core.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAG5C,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAK7D,CAAC;AA2EF,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,GAAG,CAAC;IACT;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,eAAO,MAAM,UAAU,mLA+FtB,CAAC"}

package/dist/plugins/core.js

@@ -0,0 +1,248 @@
+/**
+ * `core` plugin (08-server-api.md §1.2): cookie support (signed with
+ * ADMINIUM_SECRET), the same-origin CORS default — no CORS headers are emitted
+ * unless ADMINIUM_CORS_ORIGINS opts specific origins in (§7 item 4) — plus the
+ * §7-item-5 security headers (@fastify/helmet) and the §6 rate limiter
+ * (@fastify/rate-limit). Request-id, redaction, and the error envelope live in
+ * `app.ts` because they attach at instance creation.
+ *
+ * ─── Rate limiting (§6) ───────────────────────────────────────────────────────
+ *
+ * The limiter is registered `global: false` and enabled per route by the
+ * `config.rateLimitBucket` markers the credential-facing routes already carry
+ * (routes/auth, routes/setup, routes/auth/desktop-session). An `onRoute` hook
+ * added HERE, before @fastify/rate-limit registers its own, translates each
+ * marker into the plugin's per-route `config.rateLimit` — so a route declares
+ * WHICH bucket it is in and this table stays the single owner of the limits
+ * (08 §6: "Limits are constants in `apps/server/src/plugins/core.ts`
+ * (`RATE_BUCKETS`)"; the `adminium_settings.security` override is a later
+ * wave — core composes before any meta store exists).
+ *
+ * Buckets are FIXED-WINDOW counters in one shared in-memory map (§6: "the
+ * in-memory store — single-process: droplet, self-host, and Electron all run
+ * one instance"). The store is shared across ROUTES, not just requests, and
+ * keys are `<bucket>:<ip>`: `/auth/login`, `/auth/2fa/verify`,
+ * `/setup/super-admin` and `/auth/desktop-session` all draw down the same five
+ * tries per minute per address — per-route counters would hand an attacker one
+ * budget per door. Keying by ip (not ip+session) because every bucketed route
+ * is unauthenticated by nature; it also means a LAN peer hammering
+ * `/auth/desktop-session` (11-electron.md §8.3) can never lock the loopback
+ * exchange out.
+ *
+ * A limit hit throws the SAME `RateLimitedError` handlers would throw, so the
+ * 429 rides the one §1.4 envelope (`details: { bucket, limit, resetAt }`) and
+ * the plugin's own `retry-after` / `x-ratelimit-*` headers survive on the
+ * reply the global error handler sends.
+ *
+ * ─── Security headers (§7 item 5) ─────────────────────────────────────────────
+ *
+ * CSP is `default-src 'self'` with exactly one script allowance: sha256 hashes
+ * of the inline scripts in the SERVED dashboard `index.html` — in practice the
+ * theme pre-hydration flash guard (02-design-system.md §4.3), hashed from the
+ * build at boot so the allowance tracks the artifact rather than a constant
+ * that can drift. No `upgrade-insecure-requests` and no HSTS unless
+ * `ADMINIUM_TRUST_PROXY` (behind Caddy/TLS): the desktop shell and §8.3 LAN
+ * share serve plain `http://` loopback/LAN origins by design, and either
+ * directive would quietly break them. `connect-src` adds `ws://<host>
+ * wss://<host>` derived from each request's Host header, because CSP's
+ * `'self'` does not reliably cover same-host WebSocket upgrades (`/ws`, §4)
+ * across engines — but bare `ws:`/`wss:` scheme sources would allow a socket
+ * to ANY origin, which defeats the exfiltration boundary `'self'` sets.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import fastifyCookie from '@fastify/cookie';
+import fastifyCors from '@fastify/cors';
+import fastifyHelmet from '@fastify/helmet';
+import fastifyRateLimit from '@fastify/rate-limit';
+import fp from 'fastify-plugin';
+import { RateLimitedError } from '../errors.js';
+/**
+ * The §6 bucket table (08-server-api.md §6). Keys are the
+ * `config.rateLimitBucket` markers routes declare; a route declaring a bucket
+ * that is not in this table fails AT BOOT (the onRoute hook throws), so the
+ * two spellings cannot drift apart silently.
+ *
+ *  - `auth-login`      — `/auth/login`, `/auth/2fa/verify`, `/setup/super-admin`,
+ *                        `/auth/desktop-session` (5/min, §6 row 1; §7 item 7
+ *                        "TOTP … verify rate-limited").
+ *  - `auth-password-forgot` — `/auth/password/forgot` (3/hour, §6 row 2).
+ *  - `auth-password-reset`  — `/auth/password/reset`: the token CONSUME side.
+ *                        Not in the §6 table by name, but §7 item 7's
+ *                        single-use + 30-min-TTL reset tokens are only as
+ *                        strong as the guess rate this cap sets.
+ *  - `search`          — `GET /search` (60/min, §6 row 5): each request fans
+ *                        out parallel ILIKE queries over up to 20 tables, the
+ *                        cheapest DoS lever of the unbucketed routes.
+ *
+ * DELIBERATE §6 DEVIATIONS (documented here so the table can't drift
+ * silently):
+ *  - The auth buckets key per-IP, not the spec'd "IP + email": per-IP keying
+ *    is what guarantees a LAN flood can never lock the loopback
+ *    `/auth/desktop-session` exchange out (tested in rate-limit.test.ts). A
+ *    per-account counter for distributed credential sprays is a possible
+ *    additive follow-up, not a replacement.
+ *  - The remaining §6 rows (General API 300/min, widget-data 120/min,
+ *    exports/imports 10/h, LLM 20/h, files 30/h) and the
+ *    `adminium_settings.security` override are a tracked pre-v1 hardening
+ *    follow-up — they need principal-resolution (session-keyed) buckets,
+ *    which this per-IP fixed-window store does not provide yet.
+ */
+export const RATE_BUCKETS = {
+    'auth-login': { max: 5, timeWindowMs: 60_000 },
+    'auth-password-forgot': { max: 3, timeWindowMs: 3_600_000 },
+    'auth-password-reset': { max: 5, timeWindowMs: 60_000 },
+    search: { max: 60, timeWindowMs: 60_000 },
+};
+/** Expired-entry sweep trigger — keeps the map bounded under key churn. */
+const SWEEP_SIZE = 5_000;
+/**
+ * The §6 in-memory store, as a @fastify/rate-limit custom-store class whose
+ * instances (the per-route `child()`ren the plugin creates) all share ONE
+ * `Map` captured per server instance. Sharing is the point — see the module
+ * header — and is safe because keys embed the bucket name, so two buckets
+ * can never collide even though they share the map. Fixed-window: the first
+ * hit opens a window of the route's `timeWindow`, and the counter resets when
+ * it lapses (`incr` receives the window per call, per the store contract).
+ */
+function createBucketStoreClass() {
+    const hits = new Map();
+    return class BucketStore {
+        incr(key, callback, timeWindow) {
+            const now = Date.now();
+            if (hits.size >= SWEEP_SIZE) {
+                for (const [staleKey, hit] of hits) {
+                    if (hit.resetAt <= now)
+                        hits.delete(staleKey);
+                }
+            }
+            let hit = hits.get(key);
+            if (hit === undefined || hit.resetAt <= now) {
+                hit = { current: 0, resetAt: now + timeWindow };
+                hits.set(key, hit);
+            }
+            hit.current += 1;
+            callback(null, { current: hit.current, ttl: hit.resetAt - now });
+        }
+        child() {
+            return new BucketStore();
+        }
+    };
+}
+/** Matches inline `<script>` blocks (no `src=`) in the dashboard index.html. */
+const INLINE_SCRIPT_PATTERN = /<script(?![^>]*\bsrc\s*=)[^>]*>([\s\S]*?)<\/script>/gi;
+/**
+ * CSP `'sha256-…'` allowances for the inline scripts the served SPA actually
+ * carries. Read from the same `index.html` the static plugin will serve, so a
+ * rebuilt pre-hydration script never turns into a white screen behind a stale
+ * hash. Absent or unreadable build ⇒ no allowances (API-only boot).
+ */
+async function inlineScriptHashes(staticRoot) {
+    if (staticRoot === undefined || staticRoot === '')
+        return [];
+    let html;
+    try {
+        html = await readFile(join(resolve(staticRoot), 'index.html'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const hashes = [];
+    for (const match of html.matchAll(INLINE_SCRIPT_PATTERN)) {
+        const body = match[1] ?? '';
+        if (body.trim() === '')
+            continue;
+        // CSP hashes cover the EXACT bytes between the tags — no trimming.
+        hashes.push(`'sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}'`);
+    }
+    return hashes;
+}
+export const corePlugin = fp(async (app, { env, staticRoot }) => {
+    await app.register(fastifyCookie, {
+        secret: env.ADMINIUM_SECRET,
+        hook: 'onRequest',
+    });
+    const origins = env.ADMINIUM_CORS_ORIGINS;
+    if (origins !== undefined && origins.length > 0) {
+        await app.register(fastifyCors, {
+            origin: [...origins],
+            credentials: true,
+        });
+    }
+    // §7 item 5. Helmet's hook is global, so API replies, static assets and
+    // the SPA fallback all carry the same headers.
+    await app.register(fastifyHelmet, {
+        contentSecurityPolicy: {
+            useDefaults: false,
+            directives: {
+                'default-src': ["'self'"],
+                'base-uri': ["'self'"],
+                'object-src': ["'none'"],
+                'frame-ancestors': ["'none'"],
+                'form-action': ["'self'"],
+                'script-src': ["'self'", ...(await inlineScriptHashes(staticRoot))],
+                // Runtime style injection (chart/table libraries set style attrs).
+                'style-src': ["'self'", "'unsafe-inline'"],
+                // The map widgets' basemap tiles load from the Carto CDN
+                // (packages/widgets geo-lib.ts CARTO_TILES) — without this
+                // allowance every deployed MapBubble renders over a blank basemap.
+                'img-src': ["'self'", 'data:', 'blob:', 'https://*.basemaps.cartocdn.com'],
+                'font-src': ["'self'", 'data:'],
+                // Same-HOST WebSocket only. Bare `ws:`/`wss:` scheme sources would
+                // authorize a socket to ANY origin — an XSS foothold could
+                // exfiltrate through `new WebSocket('wss://attacker/…')` — so the
+                // allowance is derived per request from the Host header the page
+                // itself was served on (loopback, LAN ip, or proxied domain alike).
+                'connect-src': [
+                    "'self'",
+                    (req) => {
+                        const host = req.headers.host;
+                        return host === undefined || host === ''
+                            ? "'self'"
+                            : `ws://${host} wss://${host}`;
+                    },
+                ],
+                'worker-src': ["'self'", 'blob:'],
+                'manifest-src': ["'self'"],
+            },
+        },
+        // frame-ancestors 'none' is the modern half; X-Frame-Options must agree.
+        frameguard: { action: 'deny' },
+        // HSTS only behind TLS (§7 item 5); on the desktop shell's loopback and
+        // §8.3's LAN origins it would pin browsers to an https that isn't there.
+        ...(env.ADMINIUM_TRUST_PROXY ? {} : { hsts: false }),
+    });
+    // §6 marker translation. Added BEFORE @fastify/rate-limit registers so its
+    // own onRoute hook (which reads `config.rateLimit`) runs after this one.
+    app.addHook('onRoute', (route) => {
+        const bucket = route.config?.rateLimitBucket;
+        if (bucket === undefined)
+            return;
+        const spec = RATE_BUCKETS[bucket];
+        if (spec === undefined) {
+            const methods = Array.isArray(route.method) ? route.method.join(',') : route.method;
+            throw new Error(`route ${methods} ${route.url} declares unknown rate-limit bucket "${bucket}" — add it to RATE_BUCKETS (plugins/core.ts, 08-server-api.md §6)`);
+        }
+        route.config = {
+            ...route.config,
+            rateLimit: {
+                max: spec.max,
+                timeWindow: spec.timeWindowMs,
+                keyGenerator: (request) => `${bucket}:${request.ip}`,
+            },
+        };
+    });
+    await app.register(fastifyRateLimit, {
+        global: false,
+        store: createBucketStoreClass(),
+        // Thrown by the plugin, serialized by the global §1.4 error handler; the
+        // plugin has already set `retry-after` + `x-ratelimit-*` on the reply.
+        errorResponseBuilder: (request, context) => new RateLimitedError(`Too many requests. Try again in ${context.after}.`, {
+            bucket: request.routeOptions.config?.rateLimitBucket ?? 'unknown',
+            limit: context.max,
+            resetAt: new Date(Date.now() + context.ttl).toISOString(),
+        }),
+    });
+}, { name: 'adminium-core', fastify: '5.x' });
+//# sourceMappingURL=core.js.map

package/dist/plugins/core.js.map

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

package/dist/plugins/rbac.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `rbac` plugin (08-server-api.md §5, M2-T05): decorates
+ *
+ * - `request.can(permission)` — lazy, per-request-cached allow/deny against
+ *   the resolved permission set (union of role grants; super-admin bypass;
+ *   deny-by-default),
+ * - `app.rbac.require(permission)` — route `preHandler` that throws
+ *   `ForbiddenError` with the missing permission in `details` and writes an
+ *   `rbac`-category `permission.denied` audit entry,
+ * - `app.rbac.audit(request, entry)` — actor/ip/ua/request-id-stamped audit
+ *   append for the mutating routes in this wave,
+ * - the API-key request-auth path: `Authorization: Bearer adm_sk_…` →
+ *   hashed lookup → `request.apiKeyPrincipal` acting with the key's role
+ *   (§2.16), with a throttled `last_used_at` touch.
+ *
+ * Session users arrive as `request.user` from `plugins/auth.ts`; this plugin
+ * only *reads* that decoration (structurally — see rbac/principal.ts).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type AuditEntryInput, type MetaDb } from '@adminium/meta';
+import { type ApiKeyPrincipal } from '../rbac/principal.js';
+import { type PermissionSet } from '../rbac/resolver.js';
+/** Audit fields the caller provides; actor/ip/ua/request-id come from the request. */
+export type RequestAuditInput = Omit<AuditEntryInput, 'actorKind' | 'actorId' | 'actorLabel' | 'ip' | 'userAgent' | 'requestId'>;
+export interface RbacDecoration {
+    meta: MetaDb;
+    /** Route guard: 401 without a principal, 403 (+ audit) without the grant. */
+    require(permission: string): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    /** Resolve (and per-request cache) the acting principal's permission set. */
+    resolve(request: FastifyRequest): Promise<PermissionSet>;
+    /** Append an audit entry stamped with the request's actor + transport info. */
+    audit(request: FastifyRequest, entry: RequestAuditInput): Promise<void>;
+    now(): number;
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        rbac: RbacDecoration;
+    }
+    interface FastifyRequest {
+        /** Set by the rbac plugin when a valid `adm_sk_…` bearer key is presented. */
+        apiKeyPrincipal: ApiKeyPrincipal | null;
+        /** Allow/deny check against the resolved permission set (cached per request). */
+        can(permission: string): Promise<boolean>;
+        /** @internal per-request resolution cache — use `request.can()` instead. */
+        rbacResolution: PermissionSet | null;
+    }
+}
+export interface RbacPluginOptions {
+    meta: MetaDb;
+    /** Injectable clock (tests: last-used throttling, key expiry). */
+    now?: () => number;
+}
+export declare const rbacPlugin: import("fastify").FastifyPluginCallback<RbacPluginOptions, import("fastify").RawServerDefault, import("fastify").FastifyTypeProviderDefault, import("fastify").FastifyBaseLogger>;
+//# sourceMappingURL=rbac.d.ts.map

package/dist/plugins/rbac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.d.ts","sourceRoot":"","sources":["../../src/plugins/rbac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAE7B,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,GAAG,WAAW,GAAG,WAAW,CAC1E,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,6EAA6E;IAC7E,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzD,+EAA+E;IAC/E,KAAK,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,GAAG,IAAI,MAAM,CAAC;CACf;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,IAAI,EAAE,cAAc,CAAC;KACtB;IACD,UAAU,cAAc;QACtB,8EAA8E;QAC9E,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;QACxC,iFAAiF;QACjF,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1C,4EAA4E;QAC5E,cAAc,EAAE,aAAa,GAAG,IAAI,CAAC;KACtC;CACF;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,UAAU,mLAqFtB,CAAC"}