@adminiumjs/adminium 0.1.0-rc.1

package/dist/config/env.js

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+/**
+ * Environment validation (01-architecture.md §7.1). `loadEnv()` is called
+ * first in the boot sequence; on invalid input it prints a fail-fast table
+ * (variable | problem | hint) to stderr and throws — it never calls
+ * `process.exit` so callers (CLI, tests, Electron) decide how to die.
+ */
+export const LOG_LEVELS = ['fatal', 'error', 'warn', 'info', 'debug', 'trace'];
+/**
+ * The DEPLOYMENT WRAPPER this process is running under (01-architecture.md §4:
+ * "All four deployment modes run the identical `@adminium/server` process; only
+ * the wrapper differs"). Only the wrapper sets it, and only `desktop` means
+ * anything today: 11-electron.md §5 registers `POST /api/v1/auth/desktop-session`
+ * ONLY under that value, so a self-host or Docker instance does not expose the
+ * boot-token exchange at all — it has no route to attack, not merely a guarded
+ * one. Everything that is not the Electron shell is `self-host` (Docker and npx
+ * included); `cloud` joins when 12-cloud-platform.md lands.
+ */
+export const RUNTIMES = ['self-host', 'desktop'];
+/** 11-electron.md §2.2 step 4: the per-boot token is 32 random bytes, hex. */
+export const BOOT_TOKEN_HEX_LENGTH = 64;
+const TRUTHY = new Set(['on', 'true', '1']);
+const BOOLEANISH = ['on', 'off', 'true', 'false', '1', '0'];
+/** Treat empty strings as unset so `FOO= adminium start` behaves like unset FOO. */
+const emptyToUndefined = (value) => (value === '' ? undefined : value);
+export const envSchema = z.object({
+    ADMINIUM_SECRET: z
+        .string({ error: 'is required' })
+        .min(16, 'must be at least 16 characters'),
+    PORT: z.preprocess(emptyToUndefined, z.coerce
+        .number({ error: 'must be a number' })
+        .int('must be an integer')
+        .min(1, 'must be between 1 and 65535')
+        .max(65535, 'must be between 1 and 65535')
+        .default(4600)),
+    HOST: z.preprocess(emptyToUndefined, z.string().default('0.0.0.0')),
+    DATABASE_URL: z.preprocess(emptyToUndefined, z.string().min(1).optional()),
+    ADMINIUM_META_URL: z.preprocess(emptyToUndefined, z.string().min(1).optional()),
+    ADMINIUM_DATA_DIR: z.preprocess(emptyToUndefined, z.string().default('./data')),
+    ADMINIUM_LOG_LEVEL: z.preprocess(emptyToUndefined, z.enum(LOG_LEVELS).default('info')),
+    /**
+     * ─── The desktop block (11-electron.md §2.2 step 5) ───────────────────────
+     *
+     * Set by `apps/desktop`'s `buildServerEnv` when it forks the utilityProcess,
+     * and by nothing else. They live HERE, in the schema every front door
+     * validates through, rather than being read off `process.env` at the point of
+     * use, because {@link Runtime} decides whether a route EXISTS: a value that
+     * changes the server's attack surface has to be parsed once, at the boot
+     * everything else already fails fast in, not sampled from ambient state deep
+     * inside a request handler where a typo reads as "not desktop" and silently
+     * ships a server with no auto-login (or, worse, the reverse).
+     */
+    ADMINIUM_RUNTIME: z.preprocess(emptyToUndefined, z.enum(RUNTIMES).default('self-host')),
+    /**
+     * The per-boot token the desktop main process generated this launch (§2.2
+     * step 4), which `POST /api/v1/auth/desktop-session` exchanges for a session.
+     * NEVER persisted anywhere — it exists in the main process's memory, in this
+     * child's environment, and in the one URL that opens the window.
+     *
+     * Optional even under `ADMINIUM_RUNTIME=desktop`: absent ⇒ the route is not
+     * registered and the app lands on the normal login screen. That is a
+     * degradation, not a failure, so it must not be a boot error — the desktop
+     * shell's own schema (`apps/desktop/src/server/env.ts`) already requires the
+     * variable, which is the right place to fail a desktop boot over it.
+     */
+    ADMINIUM_BOOT_TOKEN: z.preprocess(emptyToUndefined, z
+        .string()
+        .regex(new RegExp(`^[0-9a-fA-F]{${String(BOOT_TOKEN_HEX_LENGTH)}}$`), `must be ${String(BOOT_TOKEN_HEX_LENGTH)} hex characters (32 bytes)`)
+        .optional()),
+    /**
+     * The §5 "Skip login on this computer" answer, mirrored out of the desktop's
+     * `config.json` (§2.3 `singleUser`) on every boot.
+     *
+     * Tri-state, for the same reason `ADMINIUM_TELEMETRY` is: `config.json` is the
+     * source of truth for this value (§2.3 — the main process owns it, because the
+     * settings panel writes it through the preload bridge), and the env var is the
+     * only channel that reaches the child at boot. Set ⇒ compose mirrors it into
+     * `adminium_settings.desktop.singleUser`, which is what the route reads (§5).
+     * Unset ⇒ NOTHING is written and the stored value stands, so a wrapper that
+     * has not wired the mirror cannot silently flip a user's answer.
+     */
+    ADMINIUM_DESKTOP_SINGLE_USER: z.preprocess(emptyToUndefined, z
+        .enum(BOOLEANISH)
+        .optional()
+        .transform((value) => (value === undefined ? undefined : TRUTHY.has(value)))),
+    /**
+     * Absolute path to `demo-seed.mjs` — the §6 step 2 "Explore the demo database"
+     * seed script, which ships in `apps/desktop/resources/` (11-T08).
+     *
+     * The server cannot find this itself and must not try: the script's location is
+     * a fact about the SHELL's layout (`resources/demo/` in the repo, inside the
+     * app bundle once §10 packages it), and `@adminium/server` may not import
+     * `@adminium/desktop` to ask. So the shell states it, the same way it states
+     * the boot token — and, like the boot token, this being absent is a
+     * DEGRADATION rather than an error: `compose.ts` skips the route and the
+     * wizard's demo card has nothing to call, while every other first-run path
+     * still works. A missing demo must not cost you your app.
+     *
+     * Only meaningful when {@link Runtime} is `desktop`; compose requires both.
+     */
+    ADMINIUM_DEMO_SEED_SCRIPT: z.preprocess(emptyToUndefined, z.string().min(1).optional()),
+    /**
+     * The telemetry OVERRIDE, and — unlike its siblings — deliberately tri-state:
+     * `true` / `false` / `undefined` (unset).
+     *
+     * `undefined` MUST survive parsing. The real gate is the `telemetry.enabled`
+     * setting, written by the first-run consent screen; an env var that collapsed
+     * "unset" to `false` could not be layered over it without silently vetoing
+     * every consenting instance. So: set ⇒ the environment wins outright (01 §7.2
+     * "environment always wins"); unset ⇒ the consent answer stands.
+     *
+     * It is layered at all because it was documented as the kill-switch
+     * (`self-hosting/telemetry.md`, `env-vars.md`) while being read by NOTHING —
+     * an org that put `ADMINIUM_TELEMETRY=off` in its compose file to enforce a
+     * no-phone-home policy had exactly no protection if any user later clicked
+     * "yes" on the consent screen. A documented control has to be a control.
+     */
+    ADMINIUM_TELEMETRY: z.preprocess(emptyToUndefined, z
+        .enum(BOOLEANISH)
+        .optional()
+        .transform((value) => (value === undefined ? undefined : TRUTHY.has(value)))),
+    /**
+     * May this deployment use network-dependent features at all
+     * (11-electron.md §8.2 `networkFeaturesAllowed`)?
+     *
+     * READ THIS BEFORE USING IT: THIS IS A POLICY ANSWER, NOT A REACHABILITY
+     * ANSWER. It does not mean "the internet is up" and must never be rendered as
+     * if it did. The server cannot know whether the network is reachable without
+     * making an outbound call, and 11-electron.md §7 ("Offline is the default,
+     * network is the exception. Every network touchpoint … is explicit,
+     * user-visible, and individually disableable") is precisely the promise an
+     * unprompted reachability probe would break — the desktop offline smoke test
+     * fails the build over exactly that request. So the honest thing the server
+     * CAN report is the one it owns: whether the operator has permitted outbound
+     * features here. §8.2's webhooks row is written to match — those rows carry a
+     * "Requires internet" HINT rather than a claim, because nothing in this
+     * process is entitled to make the claim.
+     *
+     * Default `on`, because a self-host behind a normal internet connection is the
+     * common case and webhooks/OAuth are ordinary features there. `off` is the
+     * air-gap switch for the fleet admin who already reaches for
+     * `ADMINIUM_DISABLE_UPDATES=1` (§11) and `ADMINIUM_TELEMETRY=off`: it tells the
+     * SPA to stop offering what this network cannot do, instead of letting users
+     * discover it one timeout at a time.
+     *
+     * NOT tri-state, unlike `ADMINIUM_TELEMETRY`: there is no stored setting
+     * underneath for an unset value to defer to, so "unset" has exactly one
+     * possible meaning and a boolean says it without pretending otherwise.
+     */
+    ADMINIUM_NETWORK_FEATURES: z.preprocess(emptyToUndefined, z
+        .enum(BOOLEANISH)
+        .optional()
+        .transform((value) => (value === undefined ? true : TRUTHY.has(value)))),
+    ADMINIUM_TRUST_PROXY: z.preprocess(emptyToUndefined, z
+        .enum(BOOLEANISH)
+        .optional()
+        .transform((value) => (value === undefined ? false : TRUTHY.has(value)))),
+    // CORS is off by default — the SPA is same-origin (08-server-api.md §7 item 4).
+    // A CSV of exact origins opts split deployments in; wildcard is rejected here
+    // because responses are credentialed (cookies).
+    ADMINIUM_CORS_ORIGINS: z.preprocess(emptyToUndefined, z
+        .string()
+        .optional()
+        .transform((value, ctx) => {
+        if (value === undefined)
+            return undefined;
+        const origins = value
+            .split(',')
+            .map((origin) => origin.trim())
+            .filter((origin) => origin.length > 0);
+        if (origins.length === 0)
+            return undefined;
+        if (origins.includes('*')) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'wildcard origin is not allowed with credentialed requests',
+            });
+            return z.NEVER;
+        }
+        return origins;
+    })),
+});
+const ENV_HINTS = {
+    ADMINIUM_SECRET: 'set a random string of at least 16 characters, e.g. `openssl rand -hex 32`',
+    PORT: 'integer between 1 and 65535 (default 4600)',
+    HOST: 'bind address, e.g. 0.0.0.0 or 127.0.0.1',
+    DATABASE_URL: 'optional seed source-DB DSN, e.g. postgres://user:pass@host:5432/db',
+    ADMINIUM_META_URL: 'optional meta-store DSN: postgres://, mysql://, or sqlite:<path>',
+    ADMINIUM_DATA_DIR: 'writable directory for files, exports, and backups (default ./data)',
+    ADMINIUM_LOG_LEVEL: `one of ${LOG_LEVELS.join(', ')} (default info)`,
+    ADMINIUM_RUNTIME: `one of ${RUNTIMES.join(', ')} (default self-host; set to desktop only by the Electron shell)`,
+    ADMINIUM_BOOT_TOKEN: `${String(BOOT_TOKEN_HEX_LENGTH)} hex characters, generated per boot by the desktop shell`,
+    ADMINIUM_DESKTOP_SINGLE_USER: `one of ${BOOLEANISH.join(', ')} (desktop only; mirrors config.json's singleUser)`,
+    ADMINIUM_DEMO_SEED_SCRIPT: 'absolute path to the desktop shell’s demo-seed.mjs (desktop only; enables the first-run demo card)',
+    ADMINIUM_TELEMETRY: `one of ${BOOLEANISH.join(', ')} (default off)`,
+    ADMINIUM_NETWORK_FEATURES: `one of ${BOOLEANISH.join(', ')} (default on; set off on air-gapped installs so the UI stops offering webhooks/OAuth)`,
+    ADMINIUM_TRUST_PROXY: `one of ${BOOLEANISH.join(', ')} (default off; enable behind Caddy/TLS)`,
+    ADMINIUM_CORS_ORIGINS: 'CSV of exact origins for split deployments, e.g. https://admin.acme.io — no wildcard',
+};
+export class EnvValidationError extends Error {
+    name = 'EnvValidationError';
+    issues;
+    table;
+    constructor(issues, table) {
+        super(`invalid environment configuration (${String(issues.length)} problem(s)):\n${table}`);
+        this.issues = issues;
+        this.table = table;
+    }
+}
+/** Renders the fail-fast `variable | problem | hint` table. */
+export function formatEnvErrorTable(issues) {
+    const header = ['variable', 'problem', 'hint'];
+    const rows = issues.map((issue) => {
+        const variable = issue.path.length > 0 ? issue.path.map(String).join('.') : '(env)';
+        return [variable, issue.message, ENV_HINTS[variable] ?? '—'];
+    });
+    const all = [header, ...rows];
+    const widths = header.map((_, col) => Math.max(...all.map((row) => (row[col] ?? '').length)));
+    const line = (row) => `| ${row.map((cell, col) => cell.padEnd(widths[col] ?? 0)).join(' | ')} |`;
+    const separator = `|${widths.map((w) => '-'.repeat(w + 2)).join('|')}|`;
+    return [line(header), separator, ...rows.map(line)].join('\n');
+}
+/**
+ * Parses and validates the process environment. On failure, prints the
+ * problem table to stderr and throws `EnvValidationError`.
+ */
+export function loadEnv(env = process.env, stderr = process.stderr) {
+    const result = envSchema.safeParse(env);
+    if (!result.success) {
+        const table = formatEnvErrorTable(result.error.issues);
+        stderr.write(`Adminium failed to start — invalid environment configuration:\n\n${table}\n`);
+        throw new EnvValidationError(result.error.issues, table);
+    }
+    return result.data;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAExF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,WAAW,EAAE,SAAS,CAAU,CAAC;AAG1D,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC5C,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAErE,oFAAoF;AACpF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAEzF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,eAAe,EAAE,CAAC;SACf,MAAM,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;SAChC,GAAG,CAAC,EAAE,EAAE,gCAAgC,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,UAAU,CAChB,gBAAgB,EAChB,CAAC,CAAC,MAAM;SACL,MAAM,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;SACrC,GAAG,CAAC,oBAAoB,CAAC;SACzB,GAAG,CAAC,CAAC,EAAE,6BAA6B,CAAC;SACrC,GAAG,CAAC,KAAK,EAAE,6BAA6B,CAAC;SACzC,OAAO,CAAC,IAAI,CAAC,CACjB;IACD,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnE,YAAY,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC1E,iBAAiB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/E,iBAAiB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/E,kBAAkB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtF;;;;;;;;;;;OAWG;IACH,gBAAgB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvF;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,CAAC,CAAC,UAAU,CAC/B,gBAAgB,EAChB,CAAC;SACE,MAAM,EAAE;SACR,KAAK,CACJ,IAAI,MAAM,CAAC,gBAAgB,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAC7D,WAAW,MAAM,CAAC,qBAAqB,CAAC,4BAA4B,CACrE;SACA,QAAQ,EAAE,CACd;IACD;;;;;;;;;;;OAWG;IACH,4BAA4B,EAAE,CAAC,CAAC,UAAU,CACxC,gBAAgB,EAChB,CAAC;SACE,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAC/E;IACD;;;;;;;;;;;;;;OAcG;IACH,yBAAyB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACvF;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,EAAE,CAAC,CAAC,UAAU,CAC9B,gBAAgB,EAChB,CAAC;SACE,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAC/E;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,yBAAyB,EAAE,CAAC,CAAC,UAAU,CACrC,gBAAgB,EAChB,CAAC;SACE,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAC1E;IACD,oBAAoB,EAAE,CAAC,CAAC,UAAU,CAChC,gBAAgB,EAChB,CAAC;SACE,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAC3E;IACD,gFAAgF;IAChF,8EAA8E;IAC9E,gDAAgD;IAChD,qBAAqB,EAAE,CAAC,CAAC,UAAU,CACjC,gBAAgB,EAChB,CAAC;SACE,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,OAAO,GAAG,KAAK;aAClB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;aAC9B,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC3C,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,2DAA2D;aACrE,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CACL;CACF,CAAC,CAAC;AAIH,MAAM,SAAS,GAA2B;IACxC,eAAe,EAAE,4EAA4E;IAC7F,IAAI,EAAE,4CAA4C;IAClD,IAAI,EAAE,yCAAyC;IAC/C,YAAY,EAAE,qEAAqE;IACnF,iBAAiB,EAAE,kEAAkE;IACrF,iBAAiB,EAAE,qEAAqE;IACxF,kBAAkB,EAAE,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB;IACpE,gBAAgB,EAAE,UAAU,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,iEAAiE;IAChH,mBAAmB,EAAE,GAAG,MAAM,CAAC,qBAAqB,CAAC,0DAA0D;IAC/G,4BAA4B,EAAE,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,mDAAmD;IAChH,yBAAyB,EACvB,oGAAoG;IACtG,kBAAkB,EAAE,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB;IACnE,yBAAyB,EAAE,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,uFAAuF;IACjJ,oBAAoB,EAAE,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,yCAAyC;IAC9F,qBAAqB,EACnB,sFAAsF;CACzF,CAAC;AAEF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAG,oBAAoB,CAAC;IACrC,MAAM,CAA8B;IACpC,KAAK,CAAS;IAEvB,YAAY,MAAmC,EAAE,KAAa;QAC5D,KAAK,CAAC,sCAAsC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,MAAmC;IACrE,MAAM,MAAM,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QACpF,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9F,MAAM,IAAI,GAAG,CAAC,GAAa,EAAU,EAAE,CACrC,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC7E,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACxE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,OAAO,CACrB,MAA0C,OAAO,CAAC,GAAG,EACrD,SAAoB,OAAO,CAAC,MAAM;IAElC,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,CAAC,KAAK,CAAC,oEAAoE,KAAK,IAAI,CAAC,CAAC;QAC5F,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/config/secrets.d.ts

@@ -0,0 +1,24 @@
+export declare const ENC_TOKEN_PREFIX = "enc:v1:";
+export declare class SecretFormatError extends Error {
+    readonly name = "SecretFormatError";
+}
+export declare class SecretIntegrityError extends Error {
+    readonly name = "SecretIntegrityError";
+}
+/**
+ * Derives a 32-byte key from the master secret via HKDF-SHA256. `info`
+ * scopes the key to a purpose so encryption, HMAC, and CSRF keys never
+ * coincide even for the same secret + salt.
+ */
+export declare function deriveKey(secret: string, salt: string | Uint8Array, info?: string): Buffer;
+/** Encrypts a UTF-8 string to an `enc:v1:` token with a fresh random IV. */
+export declare function encryptSecret(plaintext: string, key: Uint8Array): string;
+/**
+ * Decrypts an `enc:v1:` token. Throws `SecretFormatError` on malformed
+ * tokens and `SecretIntegrityError` when the GCM tag does not verify
+ * (tampered payload or wrong key).
+ */
+export declare function decryptSecret(token: string, key: Uint8Array): string;
+/** True when `value` looks like an `enc:v1:` token (format check only). */
+export declare function isEncryptedSecret(value: string): boolean;
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/config/secrets.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;CAC9C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;CACjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,IAAI,SAAiB,GAAG,MAAM,CAKlG;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAOxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAoBpE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/config/secrets.js

@@ -0,0 +1,74 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+/**
+ * Secret handling (01-architecture.md §7.1): `ADMINIUM_SECRET` is the master
+ * secret; HKDF-SHA256 derives purpose-scoped keys (DSN/LLM-key encryption at
+ * rest, session-token HMAC, CSRF). Values at rest are AES-256-GCM tokens of
+ * the form `enc:v1:<base64(iv|tag|ciphertext)>`.
+ */
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+export const ENC_TOKEN_PREFIX = 'enc:v1:';
+export class SecretFormatError extends Error {
+    name = 'SecretFormatError';
+}
+export class SecretIntegrityError extends Error {
+    name = 'SecretIntegrityError';
+}
+/**
+ * Derives a 32-byte key from the master secret via HKDF-SHA256. `info`
+ * scopes the key to a purpose so encryption, HMAC, and CSRF keys never
+ * coincide even for the same secret + salt.
+ */
+export function deriveKey(secret, salt, info = 'adminium:enc') {
+    if (secret.length === 0) {
+        throw new SecretFormatError('cannot derive a key from an empty secret');
+    }
+    return Buffer.from(hkdfSync('sha256', secret, salt, info, KEY_BYTES));
+}
+/** Encrypts a UTF-8 string to an `enc:v1:` token with a fresh random IV. */
+export function encryptSecret(plaintext, key) {
+    assertKeyLength(key);
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return ENC_TOKEN_PREFIX + Buffer.concat([iv, tag, ciphertext]).toString('base64');
+}
+/**
+ * Decrypts an `enc:v1:` token. Throws `SecretFormatError` on malformed
+ * tokens and `SecretIntegrityError` when the GCM tag does not verify
+ * (tampered payload or wrong key).
+ */
+export function decryptSecret(token, key) {
+    assertKeyLength(key);
+    if (!token.startsWith(ENC_TOKEN_PREFIX)) {
+        throw new SecretFormatError(`expected an "${ENC_TOKEN_PREFIX}" token`);
+    }
+    const raw = Buffer.from(token.slice(ENC_TOKEN_PREFIX.length), 'base64');
+    // empty plaintext is legal: GCM yields zero ciphertext bytes, the tag still authenticates it
+    if (raw.length < IV_BYTES + TAG_BYTES) {
+        throw new SecretFormatError('encrypted token payload is too short');
+    }
+    const iv = raw.subarray(0, IV_BYTES);
+    const tag = raw.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const ciphertext = raw.subarray(IV_BYTES + TAG_BYTES);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    }
+    catch {
+        throw new SecretIntegrityError('decryption failed — token was tampered with or the key is wrong');
+    }
+}
+/** True when `value` looks like an `enc:v1:` token (format check only). */
+export function isEncryptedSecret(value) {
+    return value.startsWith(ENC_TOKEN_PREFIX);
+}
+function assertKeyLength(key) {
+    if (key.byteLength !== KEY_BYTES) {
+        throw new SecretFormatError(`key must be exactly ${String(KEY_BYTES)} bytes (use deriveKey)`);
+    }
+}
+//# sourceMappingURL=secrets.js.map

package/dist/config/secrets.js.map

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

package/dist/connections/crypto.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DSN encryption closures (01-architecture.md §3/§7.1): AES-256-GCM with an
+ * HKDF key derived from `ADMINIUM_SECRET`, purpose-scoped so DSN, TOTP, and
+ * session keys never coincide. `@adminium/meta` receives only these
+ * closures — the meta store stays crypto-agnostic.
+ */
+import type { DsnCrypto } from '@adminium/meta';
+export declare function dsnCryptoFromSecret(masterSecret: string): DsnCrypto;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/connections/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/connections/crypto.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAMnE"}

package/dist/connections/crypto.js

@@ -0,0 +1,16 @@
+/**
+ * DSN encryption closures (01-architecture.md §3/§7.1): AES-256-GCM with an
+ * HKDF key derived from `ADMINIUM_SECRET`, purpose-scoped so DSN, TOTP, and
+ * session keys never coincide. `@adminium/meta` receives only these
+ * closures — the meta store stays crypto-agnostic.
+ */
+import { decryptSecret, deriveKey, encryptSecret } from '../config/secrets.js';
+const DSN_KEY_SALT = 'adminium:dsn:v1';
+export function dsnCryptoFromSecret(masterSecret) {
+    const key = deriveKey(masterSecret, DSN_KEY_SALT);
+    return {
+        encrypt: (plaintext) => encryptSecret(plaintext, key),
+        decrypt: (token) => decryptSecret(token, key),
+    };
+}
+//# sourceMappingURL=crypto.js.map

package/dist/connections/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/connections/crypto.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE/E,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAEvC,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,MAAM,GAAG,GAAG,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAClD,OAAO;QACL,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC;QACrD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/connections/dsn.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DSN parsing, masking, and the connection-string SSRF guard
+ * (08-server-api.md §7 item 2). Scheme allowlist `postgres|mysql|sqlite`;
+ * cloud-metadata addresses are always refused. Loopback blocking is
+ * production-only by default — a DB on the same box is the normal self-host
+ * case (§7's `ADMINIUM_NETWORK_POLICY=strict` tightens it further at M15).
+ */
+import { AppError } from '../errors.js';
+export interface ParsedDsn {
+    scheme: 'postgres' | 'mysql' | 'sqlite';
+    host: string | null;
+    port: number | null;
+    database: string | null;
+    user: string | null;
+    /** SQLite: the file path. */
+    file: string | null;
+}
+/** Parse + allowlist a DSN; throws 422 `VALIDATION_FAILED` outside the grammar. */
+export declare function parseDsn(dsn: string): ParsedDsn;
+export interface DsnGuardOptions {
+    /** Default: `NODE_ENV === 'production'` at the call site. */
+    blockLoopback?: boolean | undefined;
+}
+/**
+ * §7 item 2 guard, run before any dial. Cloud-metadata (169.254.0.0/16) is
+ * always blocked; loopback per {@link DsnGuardOptions}. Throws 422.
+ */
+export declare function guardDsn(dsn: string, opts?: DsnGuardOptions): ParsedDsn;
+/** `postgres://ava:secret@db.acme.io:5432/prod` → `postgres://ava@db.acme.io:5432/prod`. */
+export declare function maskDsn(dsn: string | null): string | null;
+/**
+ * True when two DSNs point at the same physical database (host+port+db, or
+ * the same SQLite file) — drives the meta-placement same-db check
+ * (01-architecture.md §3.1).
+ */
+export declare function sameDatabase(a: string | null, b: string | null): boolean;
+/** 409 `META_PLACEMENT_INVALID` (01-architecture.md §3.1, enforced server-side). */
+export declare class MetaPlacementError extends AppError {
+    readonly name = "MetaPlacementError";
+    constructor(message: string, details?: unknown);
+}
+//# sourceMappingURL=dsn.d.ts.map

package/dist/connections/dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../../src/connections/dsn.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAyB,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAiBD,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA4B/C;AASD,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,SAAS,CAc3E;AAED,4FAA4F;AAC5F,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAazD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAiBxE;AAED,oFAAoF;AACpF,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,SAAkB,IAAI,wBAAwB;gBAElC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAG/C"}

package/dist/connections/dsn.js

@@ -0,0 +1,131 @@
+/**
+ * DSN parsing, masking, and the connection-string SSRF guard
+ * (08-server-api.md §7 item 2). Scheme allowlist `postgres|mysql|sqlite`;
+ * cloud-metadata addresses are always refused. Loopback blocking is
+ * production-only by default — a DB on the same box is the normal self-host
+ * case (§7's `ADMINIUM_NETWORK_POLICY=strict` tightens it further at M15).
+ */
+import { AppError, ValidationFailedError } from '../errors.js';
+const SCHEME_ALIASES = {
+    postgres: 'postgres',
+    postgresql: 'postgres',
+    mysql: 'mysql',
+    mariadb: 'mysql',
+    sqlite: 'sqlite',
+    file: 'sqlite',
+};
+const DEFAULT_PORTS = {
+    postgres: 5432,
+    mysql: 3306,
+    sqlite: null,
+};
+/** Parse + allowlist a DSN; throws 422 `VALIDATION_FAILED` outside the grammar. */
+export function parseDsn(dsn) {
+    const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(dsn);
+    const rawScheme = schemeMatch?.[1]?.toLowerCase();
+    const scheme = rawScheme === undefined ? undefined : SCHEME_ALIASES[rawScheme];
+    if (scheme === undefined) {
+        throw new ValidationFailedError('Unsupported DSN scheme — postgres, mysql, or sqlite only.', {
+            allowed: ['postgres', 'mysql', 'sqlite'],
+        });
+    }
+    if (scheme === 'sqlite') {
+        const file = dsn.replace(/^(sqlite:\/\/|sqlite:|file:)/i, '');
+        return { scheme, host: null, port: null, database: null, user: null, file };
+    }
+    let url;
+    try {
+        url = new URL(dsn);
+    }
+    catch {
+        throw new ValidationFailedError('Malformed DSN.', {});
+    }
+    const port = url.port.length > 0 ? Number(url.port) : DEFAULT_PORTS[scheme];
+    return {
+        scheme,
+        host: url.hostname.length > 0 ? url.hostname : null,
+        port,
+        database: url.pathname.replace(/^\//, '') || null,
+        user: url.username.length > 0 ? decodeURIComponent(url.username) : null,
+        file: null,
+    };
+}
+function ipv4Octets(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (m === null)
+        return null;
+    const octets = m.slice(1).map(Number);
+    return octets.every((o) => o <= 255) ? octets : null;
+}
+/**
+ * §7 item 2 guard, run before any dial. Cloud-metadata (169.254.0.0/16) is
+ * always blocked; loopback per {@link DsnGuardOptions}. Throws 422.
+ */
+export function guardDsn(dsn, opts = {}) {
+    const parsed = parseDsn(dsn);
+    if (parsed.scheme === 'sqlite')
+        return parsed;
+    const host = parsed.host?.toLowerCase() ?? '';
+    const octets = ipv4Octets(host);
+    if ((octets !== null && octets[0] === 169 && octets[1] === 254) || host === 'metadata.google.internal') {
+        throw new ValidationFailedError('DSN host resolves to a blocked address range.', { host });
+    }
+    const loopback = host === 'localhost' || host === '::1' || host === '[::1]' || (octets !== null && octets[0] === 127);
+    if (loopback && opts.blockLoopback === true) {
+        throw new ValidationFailedError('Loopback DSN hosts are not allowed in production.', { host });
+    }
+    return parsed;
+}
+/** `postgres://ava:secret@db.acme.io:5432/prod` → `postgres://ava@db.acme.io:5432/prod`. */
+export function maskDsn(dsn) {
+    if (dsn === null)
+        return null;
+    let parsed;
+    try {
+        parsed = parseDsn(dsn);
+    }
+    catch {
+        return null; // never leak an unparseable (possibly credentialed) string
+    }
+    if (parsed.scheme === 'sqlite')
+        return `sqlite:${parsed.file ?? ''}`;
+    const auth = parsed.user === null ? '' : `${parsed.user}@`;
+    const port = parsed.port === null ? '' : `:${String(parsed.port)}`;
+    const db = parsed.database === null ? '' : `/${parsed.database}`;
+    return `${parsed.scheme}://${auth}${parsed.host ?? ''}${port}${db}`;
+}
+/**
+ * True when two DSNs point at the same physical database (host+port+db, or
+ * the same SQLite file) — drives the meta-placement same-db check
+ * (01-architecture.md §3.1).
+ */
+export function sameDatabase(a, b) {
+    if (a === null || b === null)
+        return false;
+    let pa;
+    let pb;
+    try {
+        pa = parseDsn(a);
+        pb = parseDsn(b);
+    }
+    catch {
+        return false;
+    }
+    if (pa.scheme !== pb.scheme)
+        return false;
+    if (pa.scheme === 'sqlite')
+        return pa.file !== null && pa.file === pb.file;
+    const hostA = pa.host?.toLowerCase() ?? '';
+    const hostB = pb.host?.toLowerCase() ?? '';
+    const localA = hostA === 'localhost' || hostA === '127.0.0.1' ? 'localhost' : hostA;
+    const localB = hostB === 'localhost' || hostB === '127.0.0.1' ? 'localhost' : hostB;
+    return localA === localB && pa.port === pb.port && pa.database === pb.database;
+}
+/** 409 `META_PLACEMENT_INVALID` (01-architecture.md §3.1, enforced server-side). */
+export class MetaPlacementError extends AppError {
+    name = 'MetaPlacementError';
+    constructor(message, details) {
+        super(409, 'META_PLACEMENT_INVALID', message, details);
+    }
+}
+//# sourceMappingURL=dsn.js.map

package/dist/connections/dsn.js.map

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