sealkeep 0.5.0

package/dist/src/control-plane/auth.d.ts

@@ -0,0 +1,62 @@
+import { type KeyObject } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import type { ControlPlaneStore, Device } from "./store.js";
+/**
+ * Device authentication for the control plane.
+ *
+ * A device signs a canonical string covering method, path, timestamp, nonce, and a
+ * hash of the body. That binds a signature to one request: replaying it elsewhere
+ * changes the string, and replaying it verbatim is caught by the nonce cache.
+ */
+export declare const SIGNATURE_WINDOW_MS: number;
+export declare const HEADERS: {
+    readonly device: "x-vaultline-device";
+    readonly timestamp: "x-vaultline-timestamp";
+    readonly nonce: "x-vaultline-nonce";
+    readonly signature: "x-vaultline-signature";
+};
+export declare function signingString(method: string, path: string, timestamp: string, nonce: string, body: Buffer | string): string;
+/** Client helper: produces the four headers a signed request needs. */
+export declare function signRequest(input: {
+    method: string;
+    path: string;
+    deviceId: string;
+    privateKey: KeyObject | string;
+    body?: Buffer | string;
+    timestamp?: string;
+    nonce: string;
+}): Record<string, string>;
+export type AuthFailure = {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+    deviceId?: string;
+};
+export type AuthSuccess = {
+    ok: true;
+    device: Device;
+};
+export type AuthResult = AuthFailure | AuthSuccess;
+export declare class NonceCache {
+    private readonly windowMs;
+    private readonly limit;
+    private readonly seen;
+    constructor(windowMs?: number, limit?: number);
+    /** True when the nonce is fresh; false when it has already been used inside the window. */
+    accept(nonce: string, now: number): boolean;
+}
+export declare function authenticate(store: ControlPlaneStore, request: IncomingMessage, path: string, body: Buffer, nonces: NonceCache, now?: number): AuthResult;
+/** Ed25519 SPKI wrapper around a raw 32-byte public key. */
+export declare function publicKeyFromRaw(base64: string): KeyObject;
+export declare function rawPublicKey(key: KeyObject): Buffer;
+export declare function hashEnrollmentToken(token: string): string;
+export declare function enrollmentTokenMatches(token: string, hash: string): boolean;
+/** A token bucket per key. Abuse control that does not need shared state. */
+export declare class RateLimiter {
+    private readonly capacity;
+    private readonly refillPerSecond;
+    private readonly buckets;
+    constructor(capacity?: number, refillPerSecond?: number);
+    take(key: string, now?: number): boolean;
+}

package/dist/src/control-plane/auth.js

@@ -0,0 +1,123 @@
+import { createHash, createPublicKey, sign as edSign, verify as edVerify, timingSafeEqual } from "node:crypto";
+/**
+ * Device authentication for the control plane.
+ *
+ * A device signs a canonical string covering method, path, timestamp, nonce, and a
+ * hash of the body. That binds a signature to one request: replaying it elsewhere
+ * changes the string, and replaying it verbatim is caught by the nonce cache.
+ */
+export const SIGNATURE_WINDOW_MS = 5 * 60_000;
+export const HEADERS = {
+    device: "x-vaultline-device",
+    timestamp: "x-vaultline-timestamp",
+    nonce: "x-vaultline-nonce",
+    signature: "x-vaultline-signature"
+};
+const sha256hex = (value) => createHash("sha256").update(value).digest("hex");
+export function signingString(method, path, timestamp, nonce, body) {
+    return `vaultline-request:v1\n${method.toUpperCase()}\n${path}\n${timestamp}\n${nonce}\n${sha256hex(body)}`;
+}
+/** Client helper: produces the four headers a signed request needs. */
+export function signRequest(input) {
+    const timestamp = input.timestamp ?? new Date().toISOString();
+    const message = signingString(input.method, input.path, timestamp, input.nonce, input.body ?? "");
+    const key = typeof input.privateKey === "string" ? createPublicKey(input.privateKey) : input.privateKey;
+    return {
+        [HEADERS.device]: input.deviceId,
+        [HEADERS.timestamp]: timestamp,
+        [HEADERS.nonce]: input.nonce,
+        [HEADERS.signature]: edSign(null, Buffer.from(message), key).toString("base64")
+    };
+}
+export class NonceCache {
+    windowMs;
+    limit;
+    seen = new Map();
+    constructor(windowMs = SIGNATURE_WINDOW_MS, limit = 10_000) {
+        this.windowMs = windowMs;
+        this.limit = limit;
+    }
+    /** True when the nonce is fresh; false when it has already been used inside the window. */
+    accept(nonce, now) {
+        for (const [key, at] of this.seen)
+            if (now - at > this.windowMs)
+                this.seen.delete(key);
+        if (this.seen.has(nonce))
+            return false;
+        if (this.seen.size >= this.limit)
+            this.seen.delete(this.seen.keys().next().value);
+        this.seen.set(nonce, now);
+        return true;
+    }
+}
+export function authenticate(store, request, path, body, nonces, now = Date.now()) {
+    const header = (name) => { const value = request.headers[name]; return typeof value === "string" ? value : undefined; };
+    const deviceId = header(HEADERS.device);
+    const timestamp = header(HEADERS.timestamp);
+    const nonce = header(HEADERS.nonce);
+    const signature = header(HEADERS.signature);
+    if (!deviceId || !timestamp || !nonce || !signature)
+        return { ok: false, status: 401, code: "unauthorized", message: "A signed device request is required" };
+    const at = Date.parse(timestamp);
+    if (!Number.isFinite(at))
+        return { ok: false, status: 401, code: "unauthorized", message: "Malformed request timestamp", deviceId };
+    if (Math.abs(now - at) > SIGNATURE_WINDOW_MS)
+        return { ok: false, status: 401, code: "unauthorized", message: "Request timestamp is outside the accepted window", deviceId };
+    if (!nonces.accept(`${deviceId}:${nonce}`, now))
+        return { ok: false, status: 401, code: "unauthorized", message: "This request was already presented", deviceId };
+    const device = store.device(deviceId);
+    if (!device)
+        return { ok: false, status: 401, code: "unauthorized", message: "Unknown device", deviceId };
+    if (device.revokedAt)
+        return { ok: false, status: 403, code: "forbidden", message: `Device revoked at ${device.revokedAt}`, deviceId };
+    const message = Buffer.from(signingString(request.method ?? "GET", path, timestamp, nonce, body));
+    let valid = false;
+    try {
+        valid = edVerify(null, message, publicKeyFromRaw(device.publicKey), Buffer.from(signature, "base64"));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { ok: false, status: 401, code: "unauthorized", message: "Request signature does not verify", deviceId };
+    return { ok: true, device };
+}
+/** Ed25519 SPKI wrapper around a raw 32-byte public key. */
+export function publicKeyFromRaw(base64) {
+    const raw = Buffer.from(base64, "base64");
+    if (raw.length !== 32)
+        throw new Error("An Ed25519 public key must be 32 bytes");
+    return createPublicKey({ key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), raw]), format: "der", type: "spki" });
+}
+export function rawPublicKey(key) {
+    return key.export({ type: "spki", format: "der" }).subarray(-32);
+}
+export function hashEnrollmentToken(token) {
+    return sha256hex(`vaultline-enrollment:v1:${token}`);
+}
+export function enrollmentTokenMatches(token, hash) {
+    const presented = Buffer.from(hashEnrollmentToken(token));
+    const expected = Buffer.from(hash);
+    return presented.length === expected.length && timingSafeEqual(presented, expected);
+}
+/** A token bucket per key. Abuse control that does not need shared state. */
+export class RateLimiter {
+    capacity;
+    refillPerSecond;
+    buckets = new Map();
+    constructor(capacity = 60, refillPerSecond = 1) {
+        this.capacity = capacity;
+        this.refillPerSecond = refillPerSecond;
+    }
+    take(key, now = Date.now()) {
+        const bucket = this.buckets.get(key) ?? { tokens: this.capacity, updatedAt: now };
+        const refill = ((now - bucket.updatedAt) / 1000) * this.refillPerSecond;
+        const tokens = Math.min(this.capacity, bucket.tokens + refill);
+        if (tokens < 1) {
+            this.buckets.set(key, { tokens, updatedAt: now });
+            return false;
+        }
+        this.buckets.set(key, { tokens: tokens - 1, updatedAt: now });
+        return true;
+    }
+}

package/dist/src/control-plane/server.d.ts

@@ -0,0 +1,31 @@
+import { type Server } from "node:http";
+import { ControlPlaneStore } from "./store.js";
+export type ControlPlaneOptions = {
+    /** Path for durable state. Omit for an in-memory instance. */
+    storePath?: string;
+    store?: ControlPlaneStore;
+    /** Development mode: skips device signatures. Never enable for a deployment. */
+    requireAuth?: boolean;
+    tls?: {
+        key: string | Buffer;
+        cert: string | Buffer;
+    };
+    now?: () => number;
+    leaseTtlMs?: number;
+    rateLimit?: {
+        capacity: number;
+        refillPerSecond: number;
+    };
+    /** Content-free request log. Receives counts and outcomes only. */
+    onLog?: (line: Record<string, string | number>) => void;
+};
+/**
+ * The Sealkeep control plane.
+ *
+ * It holds account, device, provider, and manifest state, and issues short-lived
+ * single-object upload leases. It never receives transcript plaintext, an archive
+ * key, or a recovery phrase, and every endpoint that mutates state records an
+ * audit event carrying identifiers and counts only.
+ */
+export declare function createControlPlaneServer(options?: ControlPlaneOptions): Server;
+export { ControlPlaneStore };

package/dist/src/control-plane/server.js

@@ -0,0 +1,263 @@
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { randomBytes, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { authenticate, enrollmentTokenMatches, hashEnrollmentToken, NonceCache, RateLimiter } from "./auth.js";
+import { ControlPlaneStore } from "./store.js";
+const MAX_BODY_BYTES = 512 * 1024;
+const DEFAULT_LEASE_TTL_MS = 15 * 60_000;
+const storageSchema = z.object({
+    provider: z.enum(["vaultline", "s3", "r2", "gcs"]),
+    bucket: z.string().min(1).max(255),
+    prefix: z.string().min(1).max(512),
+    region: z.string().min(1).max(64).optional(),
+    credentialMode: z.enum(["server-managed", "byo-role", "byo-service-account"]).default("server-managed")
+}).strict();
+const leaseSchema = z.object({
+    storageConfigId: z.string().uuid(),
+    archiveId: z.string().uuid(),
+    ciphertextSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().positive(),
+    partCount: z.number().int().positive().max(10_000).default(1)
+}).strict();
+const completeSchema = z.object({
+    leaseId: z.string().uuid(),
+    providerChecksum: z.string().min(1).max(128),
+    bytes: z.number().int().positive(),
+    manifestSha256: z.string().regex(/^[a-f0-9]{64}$/).optional()
+}).strict();
+// The manifest is opaque ciphertext. A strict schema is what stops a future caller
+// from "temporarily" posting plaintext transcript fields to this endpoint.
+const manifestSchema = z.object({ ciphertext: z.string().min(1).max(256 * 1024) }).strict();
+const enrollSchema = z.object({
+    accountId: z.string().uuid(),
+    enrollmentToken: z.string().min(8).max(200),
+    label: z.string().min(1).max(120),
+    publicKey: z.string().min(40).max(100)
+}).strict();
+function json(response, status, value) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    response.end(JSON.stringify(value));
+}
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error("Request body is too large");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+function parse(schema, body) {
+    let value;
+    try {
+        value = JSON.parse(body.toString("utf8") || "{}");
+    }
+    catch {
+        throw new Error("Request body must be valid JSON");
+    }
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new Error(result.error.issues.map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`).join("; "));
+    return result.data;
+}
+/**
+ * The Sealkeep control plane.
+ *
+ * It holds account, device, provider, and manifest state, and issues short-lived
+ * single-object upload leases. It never receives transcript plaintext, an archive
+ * key, or a recovery phrase, and every endpoint that mutates state records an
+ * audit event carrying identifiers and counts only.
+ */
+export function createControlPlaneServer(options = {}) {
+    const store = options.store ?? new ControlPlaneStore(options.storePath);
+    const requireAuth = options.requireAuth ?? true;
+    const now = options.now ?? Date.now;
+    const nonces = new NonceCache();
+    const limiter = new RateLimiter(options.rateLimit?.capacity ?? 120, options.rateLimit?.refillPerSecond ?? 2);
+    const handler = async (request, response) => {
+        const started = now();
+        const url = new URL(request.url ?? "/", "http://control-plane");
+        const method = request.method ?? "GET";
+        let status = 500;
+        let deviceId;
+        try {
+            const limitKey = request.headers["x-vaultline-device"] ?? request.socket.remoteAddress ?? "anonymous";
+            if (!limiter.take(limitKey, now())) {
+                status = 429;
+                store.audit({ action: `${method} ${url.pathname}`, outcome: "denied", detail: { reason: "rate_limited" } });
+                return json(response, 429, { error: { code: "rate_limited", message: "Too many requests" } });
+            }
+            if (method === "GET" && url.pathname === "/health") {
+                status = 200;
+                return json(response, 200, { ok: true, mode: requireAuth ? "control-plane" : "development-interface", credentials: "disabled" });
+            }
+            const body = await readBody(request);
+            // Account creation and device enrollment cannot be device-signed: they are
+            // what establish a device. Enrollment is gated on the account's token instead.
+            if (method === "POST" && url.pathname === "/v1/accounts") {
+                const label = JSON.parse(body.toString("utf8") || "{}").label ?? "account";
+                const enrollmentToken = randomBytes(24).toString("base64url");
+                const account = store.createAccount({ id: randomUUID(), label: String(label).slice(0, 120), createdAt: new Date(now()).toISOString(), enrollmentTokenHash: hashEnrollmentToken(enrollmentToken), quotaBytes: 50 * 1024 ** 3 });
+                store.audit({ accountId: account.id, action: "account.create", outcome: "allowed" });
+                status = 201;
+                // The token is shown once; only its hash is stored.
+                return json(response, 201, { id: account.id, label: account.label, enrollmentToken });
+            }
+            if (method === "POST" && url.pathname === "/v1/devices") {
+                const input = parse(enrollSchema, body);
+                const account = store.account(input.accountId);
+                if (!account || !enrollmentTokenMatches(input.enrollmentToken, account.enrollmentTokenHash)) {
+                    store.audit({ accountId: input.accountId, action: "device.enroll", outcome: "denied", detail: { reason: "bad_enrollment_token" } });
+                    status = 401;
+                    return json(response, 401, { error: { code: "unauthorized", message: "Enrollment token is not valid for this account" } });
+                }
+                const device = store.addDevice({ id: randomUUID(), accountId: account.id, label: input.label, publicKey: input.publicKey, createdAt: new Date(now()).toISOString() });
+                store.audit({ accountId: account.id, deviceId: device.id, action: "device.enroll", outcome: "allowed" });
+                status = 201;
+                return json(response, 201, { id: device.id, accountId: device.accountId, label: device.label, createdAt: device.createdAt });
+            }
+            let auth = { ok: true, device: { id: "development", accountId: "development", label: "development", publicKey: "", createdAt: new Date(now()).toISOString() } };
+            if (requireAuth) {
+                auth = authenticate(store, request, url.pathname, body, nonces, now());
+                deviceId = auth.ok ? auth.device.id : auth.deviceId;
+                if (!auth.ok) {
+                    store.audit({ deviceId, action: `${method} ${url.pathname}`, outcome: "denied", detail: { reason: auth.code } });
+                    status = auth.status;
+                    return json(response, auth.status, { error: { code: auth.code, message: auth.message } });
+                }
+            }
+            const device = auth.ok ? auth.device : undefined;
+            deviceId = device.id;
+            if (method === "GET" && url.pathname === "/v1/devices") {
+                status = 200;
+                return json(response, 200, store.devicesFor(device.accountId).map(({ id, label, createdAt, revokedAt }) => ({ id, label, createdAt, revokedAt: revokedAt ?? null })));
+            }
+            const revokeMatch = /^\/v1\/devices\/([0-9a-f-]{36})\/revoke$/.exec(url.pathname);
+            if (method === "POST" && revokeMatch) {
+                const target = store.device(revokeMatch[1]);
+                if (!target || target.accountId !== device.accountId) {
+                    status = 404;
+                    return json(response, 404, { error: { code: "not_found", message: "device not found" } });
+                }
+                const revoked = store.revokeDevice(target.id, new Date(now()).toISOString());
+                store.audit({ accountId: device.accountId, deviceId: device.id, action: "device.revoke", outcome: "allowed", detail: { target: target.id } });
+                status = 200;
+                // Revocation blocks new leases. It never deletes an archive.
+                return json(response, 200, { id: revoked.id, revokedAt: revoked.revokedAt, archivesRetained: store.archivesFor(device.accountId).length });
+            }
+            if (method === "POST" && url.pathname === "/v1/storage-configs") {
+                const input = parse(storageSchema, body);
+                const config = store.addStorageConfig({ id: randomUUID(), accountId: device.accountId, createdAt: new Date(now()).toISOString(), ...input });
+                store.audit({ accountId: device.accountId, deviceId: device.id, action: "storage-config.create", outcome: "allowed", detail: { provider: config.provider } });
+                status = 201;
+                return json(response, 201, config);
+            }
+            const configMatch = /^\/v1\/storage-configs\/([0-9a-f-]{36})$/.exec(url.pathname);
+            if (method === "GET" && configMatch) {
+                const config = store.storageConfig(configMatch[1]);
+                if (!config || config.accountId !== device.accountId) {
+                    status = 404;
+                    return json(response, 404, { error: { code: "not_found", message: "storage config not found" } });
+                }
+                status = 200;
+                return json(response, 200, config);
+            }
+            if (method === "POST" && url.pathname === "/v1/archives/leases") {
+                const input = parse(leaseSchema, body);
+                const config = store.storageConfig(input.storageConfigId);
+                if (!config || config.accountId !== device.accountId) {
+                    status = 404;
+                    return json(response, 404, { error: { code: "not_found", message: "storage config not found" } });
+                }
+                const account = store.account(device.accountId);
+                if (account && store.usedBytes(account.id) + input.bytes > account.quotaBytes) {
+                    store.audit({ accountId: device.accountId, deviceId: device.id, action: "lease.create", outcome: "denied", detail: { reason: "quota_exceeded", bytes: input.bytes } });
+                    status = 402;
+                    return json(response, 402, { error: { code: "quota_exceeded", message: "This account has no remaining quota" } });
+                }
+                // The object key is allocated here. A client cannot choose where its bytes land.
+                const objectKey = `${config.prefix.replace(/^\/+|\/+$/g, "")}/${input.archiveId}.vlarchive`;
+                const issuedAt = now();
+                const lease = store.addLease({
+                    id: randomUUID(), accountId: device.accountId, deviceId: device.id, archiveId: input.archiveId, storageConfigId: config.id,
+                    objectKey, bytes: input.bytes, ciphertextSha256: input.ciphertextSha256,
+                    issuedAt: new Date(issuedAt).toISOString(), expiresAt: new Date(issuedAt + (options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS)).toISOString()
+                });
+                store.upsertArchive({ accountId: device.accountId, archiveId: input.archiveId, bytes: input.bytes, ciphertextSha256: input.ciphertextSha256, objectKey, createdAt: new Date(issuedAt).toISOString() });
+                store.audit({ accountId: device.accountId, deviceId: device.id, action: "lease.create", outcome: "allowed", detail: { archiveId: input.archiveId, bytes: input.bytes } });
+                status = 201;
+                return json(response, 201, {
+                    leaseId: lease.id, archiveId: lease.archiveId, objectKey, expiresAt: lease.expiresAt,
+                    method: config.provider === "gcs" ? "RESUMABLE" : "MULTIPART", partCount: input.partCount,
+                    requiredHeaders: { "content-type": "application/vnd.vaultline.ciphertext", "x-vaultline-ciphertext-sha256": input.ciphertextSha256 },
+                    status: "pending-signer", uploadable: false,
+                    note: "This deployment issues lease records only. A signer service must mint provider URLs."
+                });
+            }
+            const completeMatch = /^\/v1\/archives\/([0-9a-f-]{36})\/complete$/.exec(url.pathname);
+            if (method === "POST" && completeMatch) {
+                const input = parse(completeSchema, body);
+                const lease = store.lease(input.leaseId);
+                if (!lease || lease.accountId !== device.accountId || lease.archiveId !== completeMatch[1]) {
+                    status = 404;
+                    return json(response, 404, { error: { code: "not_found", message: "lease not found for this archive" } });
+                }
+                if (Date.parse(lease.expiresAt) <= now()) {
+                    store.audit({ accountId: device.accountId, deviceId: device.id, action: "archive.complete", outcome: "denied", detail: { reason: "lease_expired", archiveId: lease.archiveId } });
+                    status = 409;
+                    return json(response, 409, { error: { code: "lease_expired", message: `Lease expired at ${lease.expiresAt}` } });
+                }
+                if (!store.consumeLease(lease.id, new Date(now()).toISOString())) {
+                    store.audit({ accountId: device.accountId, deviceId: device.id, action: "archive.complete", outcome: "denied", detail: { reason: "lease_replayed", archiveId: lease.archiveId } });
+                    status = 409;
+                    return json(response, 409, { error: { code: "lease_replayed", message: "This lease was already completed" } });
+                }
+                if (input.bytes !== lease.bytes) {
+                    store.audit({ accountId: device.accountId, deviceId: device.id, action: "archive.complete", outcome: "denied", detail: { reason: "size_mismatch", archiveId: lease.archiveId } });
+                    status = 409;
+                    return json(response, 409, { error: { code: "checksum_mismatch", message: `Lease promised ${lease.bytes} bytes; ${input.bytes} were reported` } });
+                }
+                const durable = store.upsertArchive({ accountId: device.accountId, archiveId: lease.archiveId, bytes: input.bytes, ciphertextSha256: lease.ciphertextSha256, objectKey: lease.objectKey, durableAt: new Date(now()).toISOString(), createdAt: new Date(now()).toISOString() });
+                store.audit({ accountId: device.accountId, deviceId: device.id, action: "archive.complete", outcome: "allowed", detail: { archiveId: lease.archiveId, bytes: input.bytes } });
+                status = 200;
+                return json(response, 200, { archiveId: durable.archiveId, durableAt: durable.durableAt, objectKey: durable.objectKey, providerChecksum: input.providerChecksum });
+            }
+            const manifestMatch = /^\/v1\/archives\/([0-9a-f-]{36})\/manifest$/.exec(url.pathname);
+            if (method === "PUT" && manifestMatch) {
+                const input = parse(manifestSchema, body);
+                const existing = store.archive(device.accountId, manifestMatch[1]);
+                if (!existing) {
+                    status = 404;
+                    return json(response, 404, { error: { code: "not_found", message: "archive not found" } });
+                }
+                store.upsertArchive({ ...existing, manifest: { ciphertext: input.ciphertext, updatedAt: new Date(now()).toISOString() } });
+                store.audit({ accountId: device.accountId, deviceId: device.id, action: "manifest.put", outcome: "allowed", detail: { archiveId: manifestMatch[1], bytes: input.ciphertext.length } });
+                status = 200;
+                return json(response, 200, { archiveId: manifestMatch[1], storedBytes: input.ciphertext.length });
+            }
+            if (method === "GET" && url.pathname === "/v1/archives") {
+                status = 200;
+                return json(response, 200, store.archivesFor(device.accountId).map(({ archiveId, bytes, objectKey, durableAt }) => ({ archiveId, bytes, objectKey, durableAt: durableAt ?? null })));
+            }
+            if (method === "GET" && url.pathname === "/v1/audit") {
+                status = 200;
+                return json(response, 200, store.auditEvents().filter((event) => !event.accountId || event.accountId === device.accountId).slice(-200));
+            }
+            status = 404;
+            return json(response, 404, { error: { code: "not_found", message: `No such endpoint: ${method} ${url.pathname}` } });
+        }
+        catch (error) {
+            status = 400;
+            return json(response, 400, { error: { code: "invalid_argument", message: error instanceof Error ? error.message : "bad request" } });
+        }
+        finally {
+            // Observability without content: method, path, status, timing, device id.
+            options.onLog?.({ method, path: url.pathname, status, ms: now() - started, device: deviceId ?? "-" });
+        }
+    };
+    return options.tls ? createHttpsServer({ key: options.tls.key, cert: options.tls.cert }, handler) : createHttpServer(handler);
+}
+export { ControlPlaneStore };

package/dist/src/control-plane/store.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Durable state for the control plane.
+ *
+ * One JSON document is written atomically (temp file, then rename) on every
+ * mutation, which gives crash-safety without a database dependency. It is sized
+ * for a self-hosted deployment; the migration path to Postgres or SQLite is to
+ * replace this class, since nothing above it touches the file layout.
+ */
+export type Account = {
+    id: string;
+    label: string;
+    createdAt: string;
+    enrollmentTokenHash: string;
+    quotaBytes: number;
+};
+export type Device = {
+    id: string;
+    accountId: string;
+    label: string;
+    publicKey: string;
+    createdAt: string;
+    revokedAt?: string;
+};
+export type StorageConfig = {
+    id: string;
+    accountId: string;
+    provider: string;
+    bucket: string;
+    region?: string;
+    prefix: string;
+    credentialMode: string;
+    createdAt: string;
+};
+export type LeaseRecord = {
+    id: string;
+    accountId: string;
+    deviceId: string;
+    archiveId: string;
+    storageConfigId: string;
+    objectKey: string;
+    bytes: number;
+    ciphertextSha256: string;
+    issuedAt: string;
+    expiresAt: string;
+    usedAt?: string;
+};
+export type ArchiveRecord = {
+    accountId: string;
+    archiveId: string;
+    bytes: number;
+    ciphertextSha256: string;
+    objectKey?: string;
+    durableAt?: string;
+    manifest?: {
+        ciphertext: string;
+        updatedAt: string;
+    };
+    createdAt: string;
+};
+export type AuditEvent = {
+    id: string;
+    at: string;
+    accountId?: string;
+    deviceId?: string;
+    action: string;
+    outcome: "allowed" | "denied";
+    detail?: Record<string, string | number>;
+};
+export declare class ControlPlaneStore {
+    private readonly path?;
+    private document;
+    constructor(path?: string | undefined);
+    private load;
+    private persist;
+    accounts(): Account[];
+    devices(): Device[];
+    storageConfigs(): StorageConfig[];
+    leases(): LeaseRecord[];
+    archives(): ArchiveRecord[];
+    auditEvents(): AuditEvent[];
+    createAccount(account: Account): Account;
+    account(id: string): Account | undefined;
+    addDevice(device: Device): Device;
+    device(id: string): Device | undefined;
+    devicesFor(accountId: string): Device[];
+    revokeDevice(id: string, at: string): Device | undefined;
+    addStorageConfig(config: StorageConfig): StorageConfig;
+    storageConfig(id: string): StorageConfig | undefined;
+    addLease(lease: LeaseRecord): LeaseRecord;
+    lease(id: string): LeaseRecord | undefined;
+    /** Single use: a lease that has already completed an archive can never be replayed. */
+    consumeLease(id: string, at: string): LeaseRecord | undefined;
+    upsertArchive(record: ArchiveRecord): ArchiveRecord;
+    archive(accountId: string, archiveId: string): ArchiveRecord | undefined;
+    archivesFor(accountId: string): ArchiveRecord[];
+    /** Audit entries record counts, ids, and outcomes. They never carry archive content. */
+    audit(event: Omit<AuditEvent, "id" | "at"> & {
+        at?: string;
+    }): AuditEvent;
+    usedBytes(accountId: string): number;
+}

package/dist/src/control-plane/store.js

@@ -0,0 +1,82 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+const EMPTY = { version: 1, accounts: [], devices: [], storageConfigs: [], leases: [], archives: [], audit: [] };
+const AUDIT_LIMIT = 5000;
+export class ControlPlaneStore {
+    path;
+    document;
+    constructor(path) {
+        this.path = path;
+        this.document = path ? this.load(path) : structuredClone(EMPTY);
+    }
+    load(path) {
+        try {
+            return { ...structuredClone(EMPTY), ...JSON.parse(readFileSync(path, "utf8")) };
+        }
+        catch {
+            return structuredClone(EMPTY);
+        }
+    }
+    persist() {
+        if (!this.path)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const temp = join(dirname(this.path), `.${randomUUID()}.tmp`);
+        writeFileSync(temp, JSON.stringify(this.document, null, 2) + "\n", { mode: 0o600 });
+        renameSync(temp, this.path);
+    }
+    accounts() { return this.document.accounts; }
+    devices() { return this.document.devices; }
+    storageConfigs() { return this.document.storageConfigs; }
+    leases() { return this.document.leases; }
+    archives() { return this.document.archives; }
+    auditEvents() { return this.document.audit; }
+    createAccount(account) { this.document.accounts.push(account); this.persist(); return account; }
+    account(id) { return this.document.accounts.find((item) => item.id === id); }
+    addDevice(device) { this.document.devices.push(device); this.persist(); return device; }
+    device(id) { return this.document.devices.find((item) => item.id === id); }
+    devicesFor(accountId) { return this.document.devices.filter((item) => item.accountId === accountId); }
+    revokeDevice(id, at) {
+        const device = this.device(id);
+        if (!device)
+            return undefined;
+        device.revokedAt = at;
+        this.persist();
+        return device;
+    }
+    addStorageConfig(config) { this.document.storageConfigs.push(config); this.persist(); return config; }
+    storageConfig(id) { return this.document.storageConfigs.find((item) => item.id === id); }
+    addLease(lease) { this.document.leases.push(lease); this.persist(); return lease; }
+    lease(id) { return this.document.leases.find((item) => item.id === id); }
+    /** Single use: a lease that has already completed an archive can never be replayed. */
+    consumeLease(id, at) {
+        const lease = this.lease(id);
+        if (!lease || lease.usedAt)
+            return undefined;
+        lease.usedAt = at;
+        this.persist();
+        return lease;
+    }
+    upsertArchive(record) {
+        const index = this.document.archives.findIndex((item) => item.archiveId === record.archiveId && item.accountId === record.accountId);
+        if (index >= 0)
+            this.document.archives[index] = { ...this.document.archives[index], ...record };
+        else
+            this.document.archives.push(record);
+        this.persist();
+        return this.archive(record.accountId, record.archiveId);
+    }
+    archive(accountId, archiveId) { return this.document.archives.find((item) => item.accountId === accountId && item.archiveId === archiveId); }
+    archivesFor(accountId) { return this.document.archives.filter((item) => item.accountId === accountId); }
+    /** Audit entries record counts, ids, and outcomes. They never carry archive content. */
+    audit(event) {
+        const entry = { id: randomUUID(), at: event.at ?? new Date().toISOString(), ...event };
+        this.document.audit.push(entry);
+        if (this.document.audit.length > AUDIT_LIMIT)
+            this.document.audit.splice(0, this.document.audit.length - AUDIT_LIMIT);
+        this.persist();
+        return entry;
+    }
+    usedBytes(accountId) { return this.archivesFor(accountId).filter((item) => item.durableAt).reduce((total, item) => total + item.bytes, 0); }
+}

package/dist/src/control-plane-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};