@adminiumjs/adminium 0.1.0-rc.1

package/dist/auth/sessions.js

@@ -0,0 +1,137 @@
+/**
+ * Session mechanics (08-server-api.md §2.1, 07-meta-store.md §3.5).
+ *
+ * Opaque tokens: `adms_` + 32 random bytes base64url; only the SHA-256 hex of
+ * the full token string is stored in `adminium_sessions`. The cookie
+ * `adminium_session` is httpOnly, SameSite=Lax, signed, path `/`, and Secure
+ * whenever the request arrived over https. Expiry is sliding: 7 days idle
+ * (from `last_seen_at`) and 30 days absolute (from `created_at`, persisted as
+ * `expires_at`). 2FA login challenges reuse the same table with an `admc_`
+ * token prefix and a 5-minute TTL — the prefix guarantees a challenge token
+ * can never authenticate as a session.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { sessionsRepo } from '@adminium/meta';
+export const SESSION_COOKIE = 'adminium_session';
+export const SESSION_TOKEN_PREFIX = 'adms_';
+export const CHALLENGE_TOKEN_PREFIX = 'admc_';
+export const RESET_TOKEN_PREFIX = 'admr_';
+/** Sliding-expiry defaults (08-server-api.md §2.1). */
+export const SESSION_IDLE_TTL_MS = 7 * 86_400_000; // 7 days idle
+export const SESSION_ABSOLUTE_TTL_MS = 30 * 86_400_000; // 30 days absolute
+/** 2FA login challenge: 5 minutes, single-use (§2.1). */
+export const CHALLENGE_TTL_MS = 5 * 60_000;
+/** Password-reset tokens: single-use, 30-minute TTL (§7 item 7). */
+export const RESET_TOKEN_TTL_MS = 30 * 60_000;
+/** `<prefix>` + 32 random bytes base64url (43 chars of payload). */
+export function mintToken(prefix) {
+    return `${prefix}${randomBytes(32).toString('base64url')}`;
+}
+/** SHA-256 hex of the full token string — the only form stored at rest. */
+export function hashToken(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+/**
+ * Creates a full session row and returns the plaintext token exactly once.
+ * `absoluteDeadline` caps `expires_at` below the default 30-day horizon so
+ * rotation never extends the original absolute lifetime.
+ */
+export async function createSession(meta, userId, reqMeta = {}, at = Date.now(), absoluteDeadline) {
+    const token = mintToken(SESSION_TOKEN_PREFIX);
+    const expiresAt = Math.min(at + SESSION_ABSOLUTE_TTL_MS, absoluteDeadline ?? Number.MAX_SAFE_INTEGER);
+    const session = await sessionsRepo(meta).create({
+        userId,
+        tokenHash: hashToken(token),
+        expiresAt,
+        ip: reqMeta.ip ?? null,
+        userAgent: reqMeta.userAgent ?? null,
+    }, at);
+    return { token, session };
+}
+/**
+ * Resolves a cookie token to a session, distinguishing "no such session"
+ * (`none` → UNAUTHENTICATED) from "existed but timed out" (`expired` →
+ * SESSION_EXPIRED). Revoked sessions resolve to `none` — sign-out is not the
+ * expired-session UX. Idle timeout: `last_seen_at + 7d`; absolute: `expires_at`.
+ */
+export async function resolveSessionByToken(meta, token, at = Date.now()) {
+    if (!token.startsWith(SESSION_TOKEN_PREFIX))
+        return { state: 'none' };
+    const session = await meta.db
+        .selectFrom('adminium_sessions')
+        .selectAll()
+        .where('tokenHash', '=', hashToken(token))
+        .executeTakeFirst();
+    if (session === undefined || session.revokedAt !== null)
+        return { state: 'none' };
+    if (at >= session.expiresAt || at >= session.lastSeenAt + SESSION_IDLE_TTL_MS) {
+        return { state: 'expired', session };
+    }
+    return { state: 'active', session };
+}
+/**
+ * Privilege-boundary rotation hook (§7 item 7): revokes the old row and mints
+ * a fresh token for the same user, keeping the original absolute deadline.
+ * Call on login step-ups, role changes, and password changes that keep the
+ * current session alive.
+ */
+export async function rotateSession(meta, session, reqMeta = {}, at = Date.now()) {
+    await sessionsRepo(meta).revoke(session.id, at);
+    return createSession(meta, session.userId, reqMeta, at, session.expiresAt);
+}
+/** Mints a 5-minute single-use 2FA challenge row (`admc_` prefix). */
+export async function createChallenge(meta, userId, reqMeta = {}, at = Date.now()) {
+    const token = mintToken(CHALLENGE_TOKEN_PREFIX);
+    const session = await sessionsRepo(meta).create({
+        userId,
+        tokenHash: hashToken(token),
+        expiresAt: at + CHALLENGE_TTL_MS,
+        ip: reqMeta.ip ?? null,
+        userAgent: reqMeta.userAgent ?? null,
+    }, at);
+    return { token, session };
+}
+/**
+ * Atomically consumes a challenge token: the first caller revokes the row and
+ * wins; replays, expired, or non-challenge tokens return `null`.
+ */
+export async function consumeChallenge(meta, token, at = Date.now()) {
+    if (!token.startsWith(CHALLENGE_TOKEN_PREFIX))
+        return null;
+    const row = await sessionsRepo(meta).findValidByTokenHash(hashToken(token), at);
+    if (row === null)
+        return null;
+    const consumed = await sessionsRepo(meta).revoke(row.id, at);
+    return consumed ? row : null;
+}
+/** True when the request arrived over TLS (directly or via trusted proxy). */
+export function isSecureRequest(request) {
+    return request.protocol === 'https';
+}
+/** Cookie contract (§2.1): httpOnly, SameSite=Lax, signed, path /. */
+export function sessionCookieOptions(secure) {
+    return {
+        path: '/',
+        httpOnly: true,
+        sameSite: 'lax',
+        signed: true,
+        secure,
+        maxAge: Math.floor(SESSION_ABSOLUTE_TTL_MS / 1000),
+    };
+}
+export function setSessionCookie(reply, token, request) {
+    void reply.setCookie(SESSION_COOKIE, token, sessionCookieOptions(isSecureRequest(request)));
+}
+export function clearSessionCookie(reply, request) {
+    const { path, httpOnly, sameSite, signed, secure } = sessionCookieOptions(isSecureRequest(request));
+    void reply.clearCookie(SESSION_COOKIE, { path, httpOnly, sameSite, signed, secure });
+}
+/** Reads and unsigns the session cookie; `null` on absent/tampered values. */
+export function readSessionCookie(request) {
+    const raw = request.cookies[SESSION_COOKIE];
+    if (raw === undefined)
+        return null;
+    const unsigned = request.unsignCookie(raw);
+    return unsigned.valid && unsigned.value !== null ? unsigned.value : null;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/auth/sessions.js.map

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

package/dist/auth/totp.d.ts

@@ -0,0 +1,30 @@
+export declare const TOTP_ISSUER = "Adminium";
+export declare const TOTP_DIGITS = 6;
+export declare const TOTP_PERIOD_S = 30;
+/** ±1 time-step tolerance (§2.1). */
+export declare const TOTP_WINDOW = 1;
+export declare const RECOVERY_CODE_COUNT = 10;
+export interface TotpEnrollment {
+    /** Base32 secret for manual entry. */
+    secret: string;
+    /** `otpauth://totp/...` URI — QR-able as-is. */
+    otpauthUrl: string;
+}
+/** Generates a fresh 20-byte secret plus its otpauth:// provisioning URI. */
+export declare function generateTotpEnrollment(accountLabel: string): TotpEnrollment;
+/** Verifies a 6-digit code against the secret with a ±1 step window. */
+export declare function verifyTotpCode(secretBase32: string, code: string, at?: number): boolean;
+/** Derives the purpose-scoped key for TOTP-secret encryption at rest. */
+export declare function totpEncryptionKey(masterSecret: string): Buffer;
+export declare function encryptTotpSecret(secretBase32: string, key: Uint8Array): string;
+export declare function decryptTotpSecret(token: string, key: Uint8Array): string;
+/** The 10 plaintext codes — shown to the user exactly once. */
+export declare function generateRecoveryCodes(count?: number): string[];
+/** argon2id hashes for storage in `adminium_users.recovery_codes`. */
+export declare function hashRecoveryCodes(codes: readonly string[]): Promise<string[]>;
+/**
+ * Single-use consume: returns the remaining hashes when `code` matches one of
+ * them (the matched hash is removed), or `null` when nothing matches.
+ */
+export declare function consumeRecoveryCode(hashes: readonly string[], code: string): Promise<string[] | null>;
+//# sourceMappingURL=totp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"totp.d.ts","sourceRoot":"","sources":["../../src/auth/totp.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,qCAAqC;AACrC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAgBtC,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CAG3E;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,OAAO,CAQnG;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAE/E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAExE;AAQD,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,MAA4B,GAAG,MAAM,EAAE,CAEnF;AAED,sEAAsE;AACtE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnF;AAMD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAe1B"}

package/dist/auth/totp.js

@@ -0,0 +1,97 @@
+/**
+ * TOTP two-factor auth (08-server-api.md §2.1): RFC 6238 via `otpauth`,
+ * 6 digits / 30 s / SHA-1 / ±1 step verify window. Secrets are encrypted at
+ * rest (AES-256-GCM, HKDF-derived key from ADMINIUM_SECRET); recovery codes
+ * are 10 single-use strings stored as argon2id hashes (07-meta-store.md §3.3).
+ */
+import { randomBytes } from 'node:crypto';
+import * as OTPAuth from 'otpauth';
+import argon2 from 'argon2';
+import { decryptSecret, deriveKey, encryptSecret } from '../config/secrets.js';
+import { ARGON2_OPTIONS } from './passwords.js';
+export const TOTP_ISSUER = 'Adminium';
+export const TOTP_DIGITS = 6;
+export const TOTP_PERIOD_S = 30;
+/** ±1 time-step tolerance (§2.1). */
+export const TOTP_WINDOW = 1;
+export const RECOVERY_CODE_COUNT = 10;
+/** HKDF salt scoping the TOTP-secret encryption key. */
+const TOTP_KEY_SALT = 'adminium:totp-secret';
+function buildTotp(secretBase32, label = 'account') {
+    return new OTPAuth.TOTP({
+        issuer: TOTP_ISSUER,
+        label,
+        algorithm: 'SHA1',
+        digits: TOTP_DIGITS,
+        period: TOTP_PERIOD_S,
+        secret: OTPAuth.Secret.fromBase32(secretBase32),
+    });
+}
+/** Generates a fresh 20-byte secret plus its otpauth:// provisioning URI. */
+export function generateTotpEnrollment(accountLabel) {
+    const secret = new OTPAuth.Secret({ size: 20 }).base32;
+    return { secret, otpauthUrl: buildTotp(secret, accountLabel).toString() };
+}
+/** Verifies a 6-digit code against the secret with a ±1 step window. */
+export function verifyTotpCode(secretBase32, code, at = Date.now()) {
+    const token = code.replaceAll(/[\s-]/g, '');
+    if (!/^\d{6}$/.test(token))
+        return false;
+    try {
+        return buildTotp(secretBase32).validate({ token, timestamp: at, window: TOTP_WINDOW }) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/** Derives the purpose-scoped key for TOTP-secret encryption at rest. */
+export function totpEncryptionKey(masterSecret) {
+    return deriveKey(masterSecret, TOTP_KEY_SALT);
+}
+export function encryptTotpSecret(secretBase32, key) {
+    return encryptSecret(secretBase32, key);
+}
+export function decryptTotpSecret(token, key) {
+    return decryptSecret(token, key);
+}
+/** `xxxxx-xxxxx` from an unbiased hex alphabet — easy to read aloud. */
+function mintRecoveryCode() {
+    const hex = randomBytes(5).toString('hex'); // 10 chars
+    return `${hex.slice(0, 5)}-${hex.slice(5)}`;
+}
+/** The 10 plaintext codes — shown to the user exactly once. */
+export function generateRecoveryCodes(count = RECOVERY_CODE_COUNT) {
+    return Array.from({ length: count }, mintRecoveryCode);
+}
+/** argon2id hashes for storage in `adminium_users.recovery_codes`. */
+export async function hashRecoveryCodes(codes) {
+    return Promise.all(codes.map(async (code) => argon2.hash(normalizeRecoveryCode(code), ARGON2_OPTIONS)));
+}
+function normalizeRecoveryCode(code) {
+    return code.replaceAll(/[\s-]/g, '').toLowerCase();
+}
+/**
+ * Single-use consume: returns the remaining hashes when `code` matches one of
+ * them (the matched hash is removed), or `null` when nothing matches.
+ */
+export async function consumeRecoveryCode(hashes, code) {
+    const normalized = normalizeRecoveryCode(code);
+    if (normalized.length === 0)
+        return null;
+    for (let i = 0; i < hashes.length; i += 1) {
+        const hash = hashes[i];
+        if (hash === undefined)
+            continue;
+        let ok = false;
+        try {
+            ok = await argon2.verify(hash, normalized);
+        }
+        catch {
+            ok = false;
+        }
+        if (ok)
+            return [...hashes.slice(0, i), ...hashes.slice(i + 1)];
+    }
+    return null;
+}
+//# sourceMappingURL=totp.js.map

package/dist/auth/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","sourceRoot":"","sources":["../../src/auth/totp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AACnC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,wDAAwD;AACxD,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAE7C,SAAS,SAAS,CAAC,YAAoB,EAAE,KAAK,GAAG,SAAS;IACxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;QACtB,MAAM,EAAE,WAAW;QACnB,KAAK;QACL,SAAS,EAAE,MAAM;QACjB,MAAM,EAAE,WAAW;QACnB,MAAM,EAAE,aAAa;QACrB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC;KAChD,CAAC,CAAC;AACL,CAAC;AASD,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CAAC,YAAoB;IACzD,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;IACvD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC5E,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,IAAY,EAAE,KAAa,IAAI,CAAC,GAAG,EAAE;IACxF,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,KAAK,IAAI,CAAC;IAClG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,OAAO,SAAS,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,YAAoB,EAAE,GAAe;IACrE,OAAO,aAAa,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,GAAe;IAC9D,OAAO,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,wEAAwE;AACxE,SAAS,gBAAgB;IACvB,MAAM,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW;IACvD,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,qBAAqB,CAAC,QAAgB,mBAAmB;IACvE,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;AACzD,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAwB;IAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;AAC1G,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAyB,EACzB,IAAY;IAEZ,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,IAAI,EAAE,GAAG,KAAK,CAAC;QACf,IAAI,CAAC;YACH,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,EAAE,GAAG,KAAK,CAAC;QACb,CAAC;QACD,IAAI,EAAE;YAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/backup/backup-service.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The §9 backup writer (11-electron.md §9) — the thing behind
+ * `POST /api/v1/desktop/backup`.
+ *
+ * It runs HERE, in the server, and not in the Electron main process, because §1
+ * principle 2 says so and because the reason it says so is load-bearing: this
+ * process is the one holding `ADMINIUM_SECRET`, the meta connection and the
+ * source-DB pools. A main process that produced the archive itself would have to
+ * open every database behind the back of the process writing to them.
+ *
+ * ─── Order is the guarantee ──────────────────────────────────────────────────
+ *
+ * discover → snapshot to a scratch dir → hash what was actually written →
+ * build the manifest FROM THOSE HASHES → zip → move into place.
+ *
+ * Every step reads the previous step's output rather than its intent. The
+ * manifest cannot overstate the archive (its checksums are of the bytes that
+ * went in, not of the files that were meant to), and the destination does not
+ * exist until the whole archive does — a crash mid-backup leaves a scratch
+ * directory, never a truncated `.zip` that a restore would cheerfully open.
+ *
+ * ─── Redaction ───────────────────────────────────────────────────────────────
+ *
+ * `config.json` travels with `secretEncrypted`/`secretPlain` stripped (§9). This
+ * module does not do the stripping and must not learn how: the desktop config is
+ * the main process's (§2.3), so the REDACTED body arrives as a parameter, and
+ * {@link assertNoSecrets} refuses to write it if it carries a secret-shaped key
+ * anyway. That is the `export/redaction.ts` rule — fail closed at the boundary,
+ * do not trust the caller's promise — applied to the one config this server does
+ * not own.
+ */
+import type { DsnCrypto, MetaDb } from '@adminium/meta';
+import { type BackupManifest } from './format.js';
+/** `<dataDir>/backups` — §9's auto-backup home and the staging root. */
+export declare const BACKUPS_DIR = "backups";
+/**
+ * §9's rotation depth, default 7.
+ *
+ * Stated here AND in `apps/desktop/src/main/config.ts`, which is a duplication
+ * with a reason: that file is the schema for `config.json`, whose default this
+ * genuinely is, and this file is the server, which may not import the Electron
+ * app (`.dependency-cruiser.cjs` — the edge only runs the other way). The value
+ * is a number in a spec, not a decision either module gets to make, and the two
+ * are pinned to each other by `backup-defaults.test.ts`.
+ */
+export declare const DEFAULT_AUTO_BACKUP_KEEP = 7;
+/**
+ * Where a `staged` archive lands before the main process moves it to the path
+ * the user picked in the save dialog.
+ *
+ * Dot-prefixed and inside `backups/` on purpose. Inside, because the move to the
+ * user's chosen path is then a same-filesystem `rename` in the common case
+ * (both under the data dir's volume) instead of a cross-device copy. Dotted,
+ * because `<dataDir>/backups` is a folder §9 reveals to the user, and a
+ * half-written staging file appearing in it next to their real backups is
+ * confusing at best; the rotation sweep also skips it, since
+ * `BACKUP_FILE_PATTERN` cannot match a directory name.
+ */
+export declare const BACKUP_STAGING_DIR = ".staging";
+/** Thrown when a redacted config is not, in fact, redacted. The backup aborts. */
+export declare class BackupRedactionError extends Error {
+    readonly name = "BackupRedactionError";
+    constructor(key: string);
+}
+/**
+ * Refuse a config body carrying anything secret-shaped, at any depth.
+ *
+ * Recursive because `config.json` is nested (`lanShare`, `updates`, `window`)
+ * and a top-level-only check would pass `{ updates: { token: "…" } }` — which is
+ * exactly the shape a future field would take.
+ */
+export declare function assertNoSecrets(value: unknown, path?: string): void;
+export interface CreateBackupOptions {
+    meta: MetaDb;
+    /** Decrypts source DSNs so local SQLite files can be found (`connections/crypto.ts`). */
+    crypto: DsnCrypto;
+    /** `ADMINIUM_DATA_DIR` — the meta.db's home, `backups/`'s parent. */
+    dataDir: string;
+    /** Absolute path of the live meta store file. */
+    metaPath: string;
+    /**
+     * The desktop `config.json`, ALREADY REDACTED by its owner (§2.3 makes the
+     * main process the only reader of that file). `null` outside the Electron
+     * shell — the archive then simply has no `config.json` member, which is
+     * honest: there is no desktop config to describe.
+     */
+    redactedConfig: unknown;
+    /** `app.getVersion()` from the shell; `null` when there is no shell. */
+    appVersion?: string | null | undefined;
+    /**
+     * `auto`  → `<dataDir>/backups/adminium-backup-<ts>.zip`, rotated.
+     * `staged` → `<dataDir>/backups/.staging/<id>.zip`, for the main process to
+     *            move to the user's chosen path. See {@link BACKUP_STAGING_DIR}.
+     */
+    destination: 'auto' | 'staged';
+    now?: (() => number) | undefined;
+}
+export interface CreateBackupResult {
+    /** Absolute path of the written archive. */
+    path: string;
+    bytes: number;
+    manifest: BackupManifest;
+}
+/**
+ * Produce a §9 archive. Returns where it landed and what went in it.
+ *
+ * `zipSync` + in-memory buffers rather than a streaming writer: a desktop
+ * install's databases are the ones a person keeps on a laptop, the snapshots are
+ * already on disk before any of this runs, and a streaming zip would trade a
+ * bounded, obvious memory profile for a partially-written archive on the failure
+ * path. `mtime: createdAt` (not the zip epoch the M10 config bundle uses)
+ * because a backup is a MOMENT, not a diffable artifact — the reproducibility
+ * that matters there is exactly what would be wrong here.
+ */
+export declare function createBackup(opts: CreateBackupOptions): Promise<CreateBackupResult>;
+/**
+ * How long a staged archive is allowed to sit unclaimed before a later backup
+ * removes it.
+ *
+ * Generous on purpose: the only thing between the server writing a staged
+ * archive and the main process moving it is one `rename`, so anything still
+ * there an hour later was abandoned. The window exists at all because a sweep
+ * that deleted by mtime alone could race a move that is genuinely in flight —
+ * on a slow cross-device copy to a USB stick, of a multi-gigabyte archive.
+ */
+export declare const STAGING_TTL_MS: number;
+/** A rotation sweep's outcome, so the caller can log/report what it removed. */
+export interface RotateBackupsResult {
+    kept: string[];
+    removed: string[];
+}
+/**
+ * §9: keep the newest `keep` archives in `<dataDir>/backups/`, delete the rest.
+ *
+ * ─── The two rules that keep this from being a data-loss bug ─────────────────
+ *
+ * 1. It only ever considers files matching {@link BACKUP_FILE_PATTERN}. That
+ *    directory is `showItemInFolder`-revealed (§9), so users WILL put things in
+ *    it — a copy of a backup they renamed, a note. "Delete the oldest files in
+ *    the folder" would eat them. This deletes archives this code wrote, and
+ *    nothing else.
+ * 2. It sorts by NAME, not mtime. The names are UTC-stamped and
+ *    lexicographically ordered by construction ({@link backupFileName}), whereas
+ *    mtime is metadata that a file copy, an rsync, or a restore-from-Time-Machine
+ *    rewrites — and a rotation that sorted on it after such an event would delete
+ *    a real backup and keep an old one.
+ *
+ * Best-effort per file: a locked archive (Windows, an open zip viewer) must not
+ * fail the BACKUP that just succeeded. The next sweep gets it.
+ */
+export declare function rotateBackups(dataDir: string, keep: number, deps: {
+    readdir: (dir: string) => Promise<string[]>;
+    rm: (path: string) => Promise<void>;
+}): Promise<RotateBackupsResult>;
+/** The real filesystem, for {@link rotateBackups}. */
+export declare function rotateBackupsOnDisk(dataDir: string, keep: number): Promise<RotateBackupsResult>;
+//# sourceMappingURL=backup-service.d.ts.map

package/dist/backup/backup-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-service.d.ts","sourceRoot":"","sources":["../../src/backup/backup-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAIxD,OAAO,EAUL,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAGrB,wEAAwE;AACxE,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAC;AA4B7C,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;gBACpC,GAAG,EAAE,MAAM;CAQxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAW,GAAG,IAAI,CAWrE;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,MAAM,EAAE,SAAS,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;CAC1B;AA6BD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsGzF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,QAAiB,CAAC;AA+C7C,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,GACA,OAAO,CAAC,mBAAmB,CAAC,CAsB9B;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAK/F"}