@adminiumjs/adminium 0.1.0-rc.1

package/dist/export/readme.js

@@ -0,0 +1,154 @@
+/**
+ * The bundle's README. Its whole job is to answer, before anyone opens
+ * `config/`, the question this export is most likely to be misread as: "is this
+ * my admin panel's source code?" It is not, it never will be, and the first
+ * heading says so (BRIEF §3 / 16-milestones M10-T03).
+ *
+ * Not user-facing dashboard copy — this is a file written into a downloadable
+ * artifact, so it is deliberately plain English and not routed through i18n
+ * (t('key') has no meaning in a zip read outside the app).
+ */
+import { NPM_PACKAGE_NAME } from '../version.js';
+function secretsSection(manifest) {
+    if (manifest.secrets.policy === 'omitted') {
+        const dropped = manifest.secrets.omitted.length === 0
+            ? 'This instance had no secrets configured.'
+            : `Dropped: ${manifest.secrets.omitted.join(', ')}.`;
+        return [
+            '## Secrets',
+            '',
+            'This bundle contains **no credentials**. Database connection strings and',
+            'LLM provider keys were left out entirely, so the file is safe to store and',
+            `hand around like any other config. ${dropped}`,
+            '',
+            'After importing, re-enter each connection\'s credentials in Studio (or with',
+            '`adminium init`) before the connection will work.',
+        ].join('\n');
+    }
+    return [
+        '## Secrets — this bundle is sensitive',
+        '',
+        'This bundle was exported with `--include-secrets`. It carries the following',
+        'still **AES-256-GCM encrypted** values:',
+        '',
+        ...manifest.secrets.encrypted.map((name) => `- \`${name}\``),
+        '',
+        'They are ciphertext, not plaintext — but they are only ciphertext. **The same',
+        '`ADMINIUM_SECRET` that the exporting instance used is required to re-open',
+        'them.** Import into an instance with a different `ADMINIUM_SECRET` and these',
+        'values will not decrypt; you will need to re-enter them.',
+        '',
+        'Treat this file as you would the secret itself: anyone who obtains both it',
+        'and `ADMINIUM_SECRET` has your database credentials.',
+    ].join('\n');
+}
+/** Render the bundle README for `manifest`. */
+export function renderReadme(manifest) {
+    const scope = manifest.connectionId === null
+        ? 'the whole instance'
+        : `connection \`${manifest.connectionId}\``;
+    return [
+        '# Adminium configuration bundle',
+        '',
+        '## This is configuration, not source code',
+        '',
+        'There is no application source in this archive, and there is no generated',
+        'app to compile or deploy. Adminium does not emit code: it reads',
+        'configuration at runtime and renders your admin panel from it. What you have',
+        'here is that configuration — pages, navigation, settings, roles and',
+        'permissions, connection definitions, schema snapshots and overrides — as',
+        'portable JSON, plus the manifest that says which Adminium version it came',
+        'from.',
+        '',
+        'To run it you need the Adminium server — a source checkout (or the Docker',
+        'image) of the same project that wrote this bundle. The `package.json`',
+        'beside this file records the exact version that produced the bundle',
+        `(\`${NPM_PACKAGE_NAME}@${manifest.appVersion}\`); run the same or a newer build. A`,
+        'checkout is the complete install — it contains the server, the dashboard',
+        'build, and the meta-store migrations.',
+        '',
+        '## What is in here',
+        '',
+        '```',
+        'manifest.json      versions + counts + the secrets policy for this bundle',
+        'package.json       pins the Adminium version that wrote it',
+        'config/            the instance configuration, one JSON file per resource',
+        '  settings.json        global settings (secret keys handled per policy below)',
+        '  roles.json           roles',
+        '  rolePermissions.json the permission matrix',
+        '  connections.json     connection definitions (credentials per policy below)',
+        '  snapshots.json       the active schema snapshot per connection',
+        '  overrides.json       schema overrides (remaps, LLM-applied corrections)',
+        '  pages.json           pages and dashboards, nav placement included',
+        '  views.json           shared saved views',
+        '```',
+        '',
+        `Scope: ${scope}.`,
+        '',
+        '## Restoring it',
+        '',
+        'From a built source checkout (see docs: Quickstart from source), with',
+        '`adminium` aliased to `node apps/server/dist/cli/index.js`:',
+        '',
+        '```sh',
+        'export ADMINIUM_SECRET=…       # 32+ chars; the target instance\'s secret',
+        'adminium import-zip --in <this-archive>.zip',
+        'adminium start',
+        '```',
+        '',
+        '`import-zip` runs the meta-store migrations first, then replays every config',
+        'document forward to the version the running build understands. Add',
+        '`--dry-run` to validate the bundle and print what would change without',
+        'writing anything.',
+        '',
+        '## Version replay',
+        '',
+        `This bundle was written by Adminium \`${manifest.appVersion}\` at config`,
+        `version \`${String(manifest.configVersion)}\`, meta schema \`${manifest.metaVersion}\`.`,
+        '',
+        'It imports into that version or any later one: config documents are migrated',
+        'forward on the way in. It will **not** import into an older Adminium — that',
+        'build would not understand documents newer than itself, and importing them',
+        'would silently drop the parts it cannot read. Upgrade the target instead.',
+        '',
+        secretsSection(manifest),
+        '',
+        '## Not included',
+        '',
+        'Deliberately absent, because these are instance data rather than',
+        'configuration — an export is meant to be a portable configuration, not a',
+        'clone of your install:',
+        '',
+        '- users, sessions, and API keys (the target creates its own first super admin)',
+        '- the audit log, jobs, and notifications',
+        '- LLM run history',
+        '- uploaded files',
+        '- per-user preferences and per-user saved views (shared views are included)',
+        '- **your database contents** — Adminium never copies the data in your source',
+        '  database; it only records how to connect to it and how to display it.',
+        '',
+        '---',
+        '',
+        'Docs: https://docs.adminium.dev',
+        '',
+    ].join('\n');
+}
+/**
+ * The bundle's `package.json`. Pins the published package exactly: a bundle
+ * that replayed into a *different* build than the one it names would defeat
+ * the point of the manifest carrying versions at all.
+ *
+ * The dependency key MUST come from `NPM_PACKAGE_NAME` and never be the bare
+ * string `adminium`: that unscoped npm name is an unrelated third party's
+ * package, so a hand-written pin would send restorers to install a stranger's
+ * library (and fail outright, since its versions start at 1.0.0).
+ */
+export function renderPackageJson(manifest) {
+    return (JSON.stringify({
+        name: 'adminium-instance',
+        private: true,
+        description: 'Adminium configuration bundle — run `adminium import-zip --in <archive>.zip` then `adminium start` from a built source checkout. Configuration only; contains no application source.',
+        dependencies: { [NPM_PACKAGE_NAME]: manifest.appVersion },
+    }, null, 2) + '\n');
+}
+//# sourceMappingURL=readme.js.map

package/dist/export/readme.js.map

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

package/dist/export/redaction.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The export's secret policy (M10-T03; BRIEF §3).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE RULE: **a plaintext secret must never reach the bundle.** Adminium keeps
+ * source DSNs and provider keys AES-256-GCM-encrypted at rest (`enc:v1:` tokens,
+ * `config/secrets.ts`), so the only two defensible outcomes for a secret-bearing
+ * field are: OMIT it, or carry the *still-encrypted* token and say loudly that
+ * `ADMINIUM_SECRET` is required to re-open it. This module is the single place
+ * that decides which, and it fails closed.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * WHY AN ALLOW-LIST AND NOT A DENY-LIST. A deny-list rots: the next migration
+ * adds a column, nobody remembers this file, and the column ships in every
+ * export from then on. {@link EXPORTED_COLUMNS} names — per table — the exact
+ * columns that may leave the instance. A new column is invisible to the export
+ * until someone adds it here, which is the failure direction we want.
+ *
+ * Notable exclusions and the reason each is not an oversight:
+ * - `adminium_connections.introspect_dsn_encrypted` / `data_dsn_encrypted` —
+ *   the DSNs. Ciphertext only, and only under `includeSecrets`.
+ * - `adminium_connections.last_error` — driver errors routinely quote the whole
+ *   connection string ("password authentication failed for user … host=…").
+ *   It is a *plaintext* DSN leak wearing a diagnostics costume. Never exported.
+ * - `adminium_connections.ssl.caFileId` — a live file reference the target
+ *   instance has no file for; nulled rather than left dangling.
+ * - `adminium_settings` secret keys (`llm.apiKey`, `email.smtp` — sourced from
+ *   the registry's own `secret` flag, never a local copy of the list).
+ * - `adminium_settings` non-`portable` keys — the instance's own identity
+ *   (`system.instanceId`, `system.bootstrappedAt`) and, above all, the
+ *   `system.superAdminCreatedAt` bootstrap CLAIM. Also sourced from the
+ *   registry, for the same reason and by the same mechanism as `secret`.
+ * - every `*_hash` column, `totp_secret_encrypted`, `secret_encrypted`,
+ *   `license_key_encrypted` — they live in tables the export does not carry at
+ *   all (users/sessions/api-keys/webhooks/manifests are instance data, not
+ *   config), and {@link assertNoCredentialColumns} keeps it that way.
+ */
+/** Thrown when a value that must be ciphertext is not — the export aborts. */
+export declare class PlaintextSecretError extends Error {
+    readonly name = "PlaintextSecretError";
+    constructor(where: string);
+}
+/**
+ * Settings keys the export always drops, whatever `includeSecrets` says: they
+ * identify the *source instance* or record that its bootstrap already happened,
+ * neither of which is configuration.
+ *
+ * DERIVED from the registry's `portable` flag, not maintained here. It used to
+ * be a hand-written list of two — and it rotted inside the same wave that wrote
+ * it: `system.superAdminCreatedAt`, the once-only first-boot claim, was added to
+ * the registry and nobody remembered this file, so every full-instance bundle
+ * carried the claim. Importing one into a fresh install left it with zero users
+ * and `/setup/*` closed forever: unusable, unrecoverable, silent. Exactly the
+ * rot this module's header predicts of deny-lists. The registry is now the
+ * authority — a new key is non-portable until declared otherwise — and this
+ * constant is kept only because the manifest and the tests name it.
+ */
+export declare const INSTANCE_IDENTITY_SETTINGS: readonly string[];
+/**
+ * The per-table column allow-list. Keys are the tables the bundle carries;
+ * every other `adminium_*` table is instance data (users, sessions, api keys,
+ * audit, jobs, notifications, llm runs, files, …) and is not config.
+ *
+ * Columns listed here are the ONLY ones serialized. Secret-bearing columns are
+ * absent on purpose and are added back — as ciphertext — by
+ * {@link secretColumnsFor} when `includeSecrets` is on.
+ */
+export declare const EXPORTED_COLUMNS: {
+    readonly adminium_settings: readonly ["key", "value"];
+    readonly adminium_roles: readonly ["id", "slug", "name", "description", "isBuiltin"];
+    readonly adminium_role_permissions: readonly ["id", "roleId", "resourceKind", "resourceRef", "actions"];
+    readonly adminium_connections: readonly ["id", "name", "engine", "sourceKind", "readOnly", "ssl", "settings"];
+    readonly adminium_schema_snapshots: readonly ["id", "connectionId", "source", "importFormat", "engineVersion", "schema", "stats", "checksum", "isActive"];
+    readonly adminium_schema_overrides: readonly ["id", "connectionId", "op", "tableName", "columnName", "value", "origin", "status", "confidence"];
+    readonly adminium_pages: readonly ["id", "connectionId", "slug", "type", "title", "icon", "navGroup", "navOrder", "config", "origin", "generatedFromSnapshotId", "isEnabled"];
+    readonly adminium_views: readonly ["id", "pageId", "kind", "name", "config", "isDefault"];
+};
+export type ExportedTable = keyof typeof EXPORTED_COLUMNS;
+/** Ciphertext columns re-admitted only under `--include-secrets`. */
+export declare function secretColumnsFor(table: ExportedTable): readonly string[];
+/** Throws if any allow-listed column looks credential-bearing. */
+export declare function assertNoCredentialColumns(): void;
+/**
+ * Project a row down to its allow-listed columns. Anything not named is
+ * dropped — including columns added by a future migration.
+ */
+export declare function pickColumns(row: Record<string, unknown>, columns: readonly string[]): Record<string, unknown>;
+/**
+ * Verify a value destined for the bundle is an `enc:v1:` token, and return it.
+ * `null` passes through (an unset secret is not a secret).
+ */
+export declare function assertCiphertext(value: unknown, where: string): string | null;
+export interface SettingsRedactionResult {
+    /** Rows safe to bundle. */
+    rows: {
+        key: string;
+        value: unknown;
+    }[];
+    /** Secret keys dropped because `includeSecrets` was off. */
+    droppedSecretKeys: string[];
+    /** Secret keys carried as ciphertext (require ADMINIUM_SECRET to re-open). */
+    encryptedKeys: string[];
+}
+/**
+ * Apply the settings policy. BOTH flags — `secret` and `portable` — come from
+ * the `@adminium/meta` settings registry: the registry is the authority on what
+ * is sensitive and on what is configuration at all, so a new key is handled
+ * correctly the day it is declared, with no edit here. That is the "one code
+ * path" rule applied to redaction, and it fails closed in both directions (a new
+ * key is neither exported nor assumed harmless).
+ */
+export declare function redactSettings(rows: readonly {
+    key: string;
+    value: unknown;
+}[], includeSecrets: boolean): SettingsRedactionResult;
+/** True when the registry declares `key` secret. Re-exported for the manifest. */
+export declare function isSecretKey(key: string): boolean;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/export/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/export/redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,8EAA8E;AAC9E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;gBACpC,KAAK,EAAE,MAAM;CAO1B;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAEvD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;CA0CyB,CAAC;AAEvD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAE1D,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAIxE;AAmBD,kEAAkE;AAClE,wBAAgB,yBAAyB,IAAI,IAAI,CAShD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7E;AAED,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IACxC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,EAChD,cAAc,EAAE,OAAO,GACtB,uBAAuB,CA2BzB;AA0BD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/export/redaction.js

@@ -0,0 +1,233 @@
+/**
+ * The export's secret policy (M10-T03; BRIEF §3).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE RULE: **a plaintext secret must never reach the bundle.** Adminium keeps
+ * source DSNs and provider keys AES-256-GCM-encrypted at rest (`enc:v1:` tokens,
+ * `config/secrets.ts`), so the only two defensible outcomes for a secret-bearing
+ * field are: OMIT it, or carry the *still-encrypted* token and say loudly that
+ * `ADMINIUM_SECRET` is required to re-open it. This module is the single place
+ * that decides which, and it fails closed.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * WHY AN ALLOW-LIST AND NOT A DENY-LIST. A deny-list rots: the next migration
+ * adds a column, nobody remembers this file, and the column ships in every
+ * export from then on. {@link EXPORTED_COLUMNS} names — per table — the exact
+ * columns that may leave the instance. A new column is invisible to the export
+ * until someone adds it here, which is the failure direction we want.
+ *
+ * Notable exclusions and the reason each is not an oversight:
+ * - `adminium_connections.introspect_dsn_encrypted` / `data_dsn_encrypted` —
+ *   the DSNs. Ciphertext only, and only under `includeSecrets`.
+ * - `adminium_connections.last_error` — driver errors routinely quote the whole
+ *   connection string ("password authentication failed for user … host=…").
+ *   It is a *plaintext* DSN leak wearing a diagnostics costume. Never exported.
+ * - `adminium_connections.ssl.caFileId` — a live file reference the target
+ *   instance has no file for; nulled rather than left dangling.
+ * - `adminium_settings` secret keys (`llm.apiKey`, `email.smtp` — sourced from
+ *   the registry's own `secret` flag, never a local copy of the list).
+ * - `adminium_settings` non-`portable` keys — the instance's own identity
+ *   (`system.instanceId`, `system.bootstrappedAt`) and, above all, the
+ *   `system.superAdminCreatedAt` bootstrap CLAIM. Also sourced from the
+ *   registry, for the same reason and by the same mechanism as `secret`.
+ * - every `*_hash` column, `totp_secret_encrypted`, `secret_encrypted`,
+ *   `license_key_encrypted` — they live in tables the export does not carry at
+ *   all (users/sessions/api-keys/webhooks/manifests are instance data, not
+ *   config), and {@link assertNoCredentialColumns} keeps it that way.
+ */
+import { SETTING_KEYS, isPortableSettingKey, isSecretSettingKey, isSettingKey } from '@adminium/meta';
+import { ENC_TOKEN_PREFIX, isEncryptedSecret } from '../config/secrets.js';
+/** Thrown when a value that must be ciphertext is not — the export aborts. */
+export class PlaintextSecretError extends Error {
+    name = 'PlaintextSecretError';
+    constructor(where) {
+        super(`refusing to export ${where}: the value is not an "${ENC_TOKEN_PREFIX}" token. ` +
+            'A secret is only ever bundled still-encrypted; this one would have gone out in plaintext. ' +
+            'This is a bug in the write path that stored it — report it rather than working around it.');
+    }
+}
+/**
+ * Settings keys the export always drops, whatever `includeSecrets` says: they
+ * identify the *source instance* or record that its bootstrap already happened,
+ * neither of which is configuration.
+ *
+ * DERIVED from the registry's `portable` flag, not maintained here. It used to
+ * be a hand-written list of two — and it rotted inside the same wave that wrote
+ * it: `system.superAdminCreatedAt`, the once-only first-boot claim, was added to
+ * the registry and nobody remembered this file, so every full-instance bundle
+ * carried the claim. Importing one into a fresh install left it with zero users
+ * and `/setup/*` closed forever: unusable, unrecoverable, silent. Exactly the
+ * rot this module's header predicts of deny-lists. The registry is now the
+ * authority — a new key is non-portable until declared otherwise — and this
+ * constant is kept only because the manifest and the tests name it.
+ */
+export const INSTANCE_IDENTITY_SETTINGS = SETTING_KEYS.filter((key) => !isPortableSettingKey(key));
+/**
+ * The per-table column allow-list. Keys are the tables the bundle carries;
+ * every other `adminium_*` table is instance data (users, sessions, api keys,
+ * audit, jobs, notifications, llm runs, files, …) and is not config.
+ *
+ * Columns listed here are the ONLY ones serialized. Secret-bearing columns are
+ * absent on purpose and are added back — as ciphertext — by
+ * {@link secretColumnsFor} when `includeSecrets` is on.
+ */
+export const EXPORTED_COLUMNS = {
+    adminium_settings: ['key', 'value'],
+    adminium_roles: ['id', 'slug', 'name', 'description', 'isBuiltin'],
+    adminium_role_permissions: ['id', 'roleId', 'resourceKind', 'resourceRef', 'actions'],
+    adminium_connections: ['id', 'name', 'engine', 'sourceKind', 'readOnly', 'ssl', 'settings'],
+    adminium_schema_snapshots: [
+        'id',
+        'connectionId',
+        'source',
+        'importFormat',
+        'engineVersion',
+        'schema',
+        'stats',
+        'checksum',
+        'isActive',
+    ],
+    adminium_schema_overrides: [
+        'id',
+        'connectionId',
+        'op',
+        'tableName',
+        'columnName',
+        'value',
+        'origin',
+        'status',
+        'confidence',
+    ],
+    adminium_pages: [
+        'id',
+        'connectionId',
+        'slug',
+        'type',
+        'title',
+        'icon',
+        'navGroup',
+        'navOrder',
+        'config',
+        'origin',
+        'generatedFromSnapshotId',
+        'isEnabled',
+    ],
+    adminium_views: ['id', 'pageId', 'kind', 'name', 'config', 'isDefault'],
+};
+/** Ciphertext columns re-admitted only under `--include-secrets`. */
+export function secretColumnsFor(table) {
+    return table === 'adminium_connections'
+        ? ['introspectDsnEncrypted', 'dataDsnEncrypted']
+        : [];
+}
+/**
+ * Column-name shapes that must never appear in a bundle. This is the
+ * belt-and-braces companion to the allow-list: the allow-list decides what gets
+ * in, this asserts nothing credential-shaped slipped through a typo or a future
+ * edit. Checked in a unit test against {@link EXPORTED_COLUMNS} itself, so the
+ * violation is caught at CI time and not at export time.
+ */
+const CREDENTIAL_COLUMN_PATTERNS = [
+    /hash$/i,
+    /token/i,
+    /password/i,
+    /secret/i,
+    /^recoveryCodes$/i,
+    /apiKey/i,
+    /lastError/i,
+];
+/** Throws if any allow-listed column looks credential-bearing. */
+export function assertNoCredentialColumns() {
+    for (const [table, columns] of Object.entries(EXPORTED_COLUMNS)) {
+        for (const column of columns) {
+            const bad = CREDENTIAL_COLUMN_PATTERNS.find((re) => re.test(column));
+            if (bad !== undefined) {
+                throw new PlaintextSecretError(`${table}.${column} (matches ${String(bad)})`);
+            }
+        }
+    }
+}
+/**
+ * Project a row down to its allow-listed columns. Anything not named is
+ * dropped — including columns added by a future migration.
+ */
+export function pickColumns(row, columns) {
+    const out = {};
+    for (const column of columns) {
+        if (row[column] !== undefined)
+            out[column] = row[column];
+    }
+    return out;
+}
+/**
+ * Verify a value destined for the bundle is an `enc:v1:` token, and return it.
+ * `null` passes through (an unset secret is not a secret).
+ */
+export function assertCiphertext(value, where) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string' || !isEncryptedSecret(value)) {
+        throw new PlaintextSecretError(where);
+    }
+    return value;
+}
+/**
+ * Apply the settings policy. BOTH flags — `secret` and `portable` — come from
+ * the `@adminium/meta` settings registry: the registry is the authority on what
+ * is sensitive and on what is configuration at all, so a new key is handled
+ * correctly the day it is declared, with no edit here. That is the "one code
+ * path" rule applied to redaction, and it fails closed in both directions (a new
+ * key is neither exported nor assumed harmless).
+ */
+export function redactSettings(rows, includeSecrets) {
+    const out = { rows: [], droppedSecretKeys: [], encryptedKeys: [] };
+    for (const row of rows) {
+        // Unknown/stale keys are not config this build understands — drop them
+        // rather than round-trip something we cannot validate.
+        if (!isSettingKey(row.key))
+            continue;
+        // Not configuration: instance identity, or the bootstrap claim.
+        if (!isPortableSettingKey(row.key))
+            continue;
+        if (!isSecretSettingKey(row.key)) {
+            out.rows.push({ key: row.key, value: row.value });
+            continue;
+        }
+        if (!includeSecrets) {
+            out.droppedSecretKeys.push(row.key);
+            continue;
+        }
+        // Secret key, secrets requested: it may only travel as ciphertext.
+        assertSecretSettingIsEncrypted(row.key, row.value);
+        out.rows.push({ key: row.key, value: row.value });
+        out.encryptedKeys.push(row.key);
+    }
+    return out;
+}
+/**
+ * A secret setting is either a bare `enc:v1:` token (`llm.apiKey`) or an object
+ * with encrypted leaves (`email.smtp.passEncrypted`). Both are checked; a
+ * `null` value is an unset key and is fine.
+ */
+function assertSecretSettingIsEncrypted(key, value) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string') {
+        assertCiphertext(value, `settings.${key}`);
+        return;
+    }
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        for (const [field, leaf] of Object.entries(value)) {
+            // Only the *Encrypted fields are secrets; host/port/user/from are config.
+            if (field.endsWith('Encrypted'))
+                assertCiphertext(leaf, `settings.${key}.${field}`);
+        }
+        return;
+    }
+    throw new PlaintextSecretError(`settings.${key} (unexpected value shape)`);
+}
+/** True when the registry declares `key` secret. Re-exported for the manifest. */
+export function isSecretKey(key) {
+    return isSettingKey(key) && isSecretSettingKey(key);
+}
+//# sourceMappingURL=redaction.js.map

package/dist/export/redaction.js.map

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

package/dist/export/zip-service.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Zip-export service (M10-T03, 01-architecture.md §4.1/§6.1/§8.2; BRIEF §3).
+ *
+ * WHAT IT EXPORTS — the design decision the docs make loudly, so the
+ * implementation cannot drift: **server + config, never source code.** The zip
+ * carries the runtime-interpreted configuration — connection definitions
+ * (secrets excluded unless {@link ExportZipOptions.includeSecrets} is set),
+ * schema snapshots, overrides, pages/dashboards, views, settings, roles — plus a
+ * manifest for version replay on re-import and a README that says all of this in
+ * its first heading. Adminium does not emit an app; the bundle names its runtime
+ * by pinning the `@adminiumjs/adminium` npm package (01 §4.1: that one package *is* the
+ * complete install — server + dashboard dist + meta migrations), it does not
+ * carry a copy of it.
+ *
+ * The secret policy lives in `redaction.ts` and fails closed: every field that
+ * leaves is on an allow-list, and any value that must be ciphertext is asserted
+ * to be ciphertext before it is written. See that module's header.
+ */
+import { type MetaDb } from '@adminium/meta';
+/** Bumped when the bundle layout changes (re-import replay). */
+export declare const EXPORT_ZIP_MANIFEST_VERSION = 1;
+export interface ExportZipOptions {
+    /** The meta store to read the configuration out of. */
+    meta: MetaDb;
+    /**
+     * Restrict the bundle to one connection's configuration. `null`/omitted
+     * exports the whole instance (every connection + instance-level settings).
+     */
+    connectionId?: string | null | undefined;
+    /** Absolute or cwd-relative destination path for the `.zip`. */
+    outPath: string;
+    /**
+     * Include encrypted DSNs / provider keys in the bundle. Default `false` —
+     * an export is shareable by default; secrets are re-entered on re-import.
+     */
+    includeSecrets?: boolean | undefined;
+    /** `ADMINIUM_DATA_DIR` — the bootstrap file + any file-backed artifacts. */
+    dataDir: string;
+    /** Version stamped into the manifest (defaults to the running app version). */
+    appVersion?: string | undefined;
+    /** Clock override — tests. */
+    now?: () => number;
+}
+export interface ExportZipResult {
+    /** Absolute path of the written archive. */
+    path: string;
+    /** Size of the written archive in bytes. */
+    bytes: number;
+    /** Archive member paths, for the CLI's summary line and the tests. */
+    entries: string[];
+    /** {@link EXPORT_ZIP_MANIFEST_VERSION} the bundle was written at. */
+    manifestVersion: number;
+    /** Row counts per exported resource, e.g. `{ pages: 12, overrides: 41 }`. */
+    counts: Readonly<Record<string, number>>;
+}
+/** The seam the CLI (and, later, the Studio download route) call. */
+export type ExportZip = (opts: ExportZipOptions) => Promise<ExportZipResult>;
+/**
+ * Export the instance's configuration to `outPath`.
+ *
+ * Ordering carries the secret guarantee: redaction runs while reading, the
+ * manifest is built from what redaction actually *did* (not from what was
+ * asked for), and only then are bytes produced.
+ */
+export declare const exportZip: ExportZip;
+//# sourceMappingURL=zip-service.d.ts.map

package/dist/export/zip-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-service.d.ts","sourceRoot":"","sources":["../../src/export/zip-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAA6B,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAuBxE,gEAAgE;AAChE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAU7C,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1C;AAED,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAqP7E;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,SAgEvB,CAAC"}