@livedesk/hub 0.1.30 → 0.1.32

package/src/security/device-credential-authority.js

@@ -0,0 +1,406 @@
+import crypto from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createOsSecretStore, OS_SECRET_REFERENCE } from '@livedesk/runtime-core/os-secret-store';
+
+const AUTHORITY_VERSION = 1;
+const CREDENTIAL_VERSION = 1;
+const DEFAULT_CREDENTIAL_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+const MAX_CREDENTIAL_TTL_MS = 366 * 24 * 60 * 60 * 1000;
+const MAX_DEVICES = 4096;
+
+function securityError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function clean(value, maximum = 256) {
+  return String(value || '').replace(/[\0\r\n]/g, '').trim().slice(0, maximum);
+}
+
+function exactBase64Url(value, minimumBytes, maximumBytes = minimumBytes) {
+  const text = String(value || '');
+  if (!/^[A-Za-z0-9_-]+$/.test(text)) throw securityError('device-credential-base64-invalid');
+  const bytes = Buffer.from(text, 'base64url');
+  if (bytes.length < minimumBytes || bytes.length > maximumBytes || bytes.toString('base64url') !== text) {
+    throw securityError('device-credential-base64-invalid');
+  }
+  return bytes;
+}
+
+function atomicPrivateJson(filePath, value) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, filePath);
+}
+
+function parseJsonFile(filePath) {
+  try {
+    const value = JSON.parse(readFileSync(filePath, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function requireP256PublicKey(publicKeyBase64Url) {
+  const der = exactBase64Url(publicKeyBase64Url, 80, 160);
+  let key;
+  try {
+    key = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    throw securityError('device-public-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw securityError('device-public-key-invalid');
+  }
+  return { key, der, text: der.toString('base64url') };
+}
+
+function requireP256PrivateKey(privateKeyBase64Url) {
+  const der = exactBase64Url(privateKeyBase64Url, 100, 512);
+  let key;
+  try {
+    key = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  } catch {
+    throw securityError('hub-private-key-invalid');
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') {
+    throw securityError('hub-private-key-invalid');
+  }
+  return key;
+}
+
+function encodeCredentialPayload(payload) {
+  return Buffer.from(JSON.stringify({
+    version: CREDENTIAL_VERSION,
+    serial: payload.serial,
+    accountId: payload.accountId,
+    hubId: payload.hubId,
+    deviceId: payload.deviceId,
+    devicePublicKey: payload.devicePublicKey,
+    hubPublicKey: payload.hubPublicKey,
+    issuedAt: payload.issuedAt,
+    expiresAt: payload.expiresAt
+  }), 'utf8').toString('base64url');
+}
+
+function parseCredential(credential) {
+  const text = String(credential || '');
+  if (text.length < 80 || text.length > 8192) throw securityError('device-credential-invalid');
+  const parts = text.split('.');
+  if (parts.length !== 2) throw securityError('device-credential-invalid');
+  const payloadBytes = exactBase64Url(parts[0], 32, 4096);
+  const signature = exactBase64Url(parts[1], 64, 64);
+  let payload;
+  try {
+    payload = JSON.parse(payloadBytes.toString('utf8'));
+  } catch {
+    throw securityError('device-credential-invalid');
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw securityError('device-credential-invalid');
+  const normalized = {
+    version: Number(payload.version),
+    serial: clean(payload.serial, 128),
+    accountId: clean(payload.accountId, 128),
+    hubId: clean(payload.hubId, 128),
+    deviceId: clean(payload.deviceId, 128),
+    devicePublicKey: clean(payload.devicePublicKey, 512),
+    hubPublicKey: clean(payload.hubPublicKey, 512),
+    issuedAt: Number(payload.issuedAt),
+    expiresAt: Number(payload.expiresAt)
+  };
+  if (normalized.version !== CREDENTIAL_VERSION
+    || !normalized.serial
+    || !normalized.accountId
+    || !normalized.hubId
+    || !normalized.deviceId
+    || !Number.isSafeInteger(normalized.issuedAt)
+    || !Number.isSafeInteger(normalized.expiresAt)
+    || normalized.expiresAt <= normalized.issuedAt
+    || normalized.expiresAt - normalized.issuedAt > MAX_CREDENTIAL_TTL_MS
+    || encodeCredentialPayload(normalized) !== parts[0]) {
+    throw securityError('device-credential-invalid');
+  }
+  requireP256PublicKey(normalized.devicePublicKey);
+  requireP256PublicKey(normalized.hubPublicKey);
+  return { text, payloadText: parts[0], payloadBytes, payload: normalized, signature };
+}
+
+export function createDeviceCredentialAuthority({
+  dataDir = path.join(os.homedir(), '.livedesk'),
+  now = () => Date.now(),
+  credentialTtlMs = DEFAULT_CREDENTIAL_TTL_MS
+} = {}) {
+  const securityDir = path.join(dataDir, 'security');
+  const authorityPath = path.join(securityDir, 'hub-device-authority.json');
+  const registryPath = path.join(securityDir, 'device-credentials.json');
+  const authoritySecretStore = createOsSecretStore({
+    service: 'LiveDesk',
+    account: `hub-device-authority:${crypto.createHash('sha256').update(path.resolve(authorityPath)).digest('hex').slice(0, 24)}`,
+    dataDir
+  });
+  const boundedTtlMs = Math.max(60_000, Math.min(MAX_CREDENTIAL_TTL_MS, Number(credentialTtlMs) || DEFAULT_CREDENTIAL_TTL_MS));
+
+  let authority = parseJsonFile(authorityPath);
+  if (!authority) {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const privateKeyText = privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url');
+    if (!authoritySecretStore.write(privateKeyText)) throw securityError('hub-private-key-secure-store-unavailable');
+    authority = {
+      version: AUTHORITY_VERSION,
+      hubId: crypto.randomUUID(),
+      publicKey: publicKey.export({ format: 'der', type: 'spki' }).toString('base64url'),
+      privateKeyRef: OS_SECRET_REFERENCE,
+      createdAt: new Date(now()).toISOString()
+    };
+    atomicPrivateJson(authorityPath, authority);
+  }
+  if (Number(authority.version) !== AUTHORITY_VERSION || !clean(authority.hubId, 128)) {
+    throw securityError('hub-device-authority-invalid');
+  }
+  const plaintextPrivateKey = clean(authority.privateKey, 1024);
+  if (plaintextPrivateKey) {
+    if (!authoritySecretStore.write(plaintextPrivateKey)) throw securityError('hub-private-key-migration-failed');
+    authority = { ...authority, privateKeyRef: OS_SECRET_REFERENCE };
+    delete authority.privateKey;
+    atomicPrivateJson(authorityPath, authority);
+  }
+  if (authority.privateKeyRef !== OS_SECRET_REFERENCE) throw securityError('hub-private-key-reference-invalid');
+  const privateKeyText = authoritySecretStore.read();
+  if (!privateKeyText) throw securityError('hub-private-key-secure-store-unavailable');
+  const hubPrivateKey = requireP256PrivateKey(privateKeyText);
+  const hubPublic = requireP256PublicKey(authority.publicKey);
+  const hubIssuerKeyId = crypto.createHash('sha256')
+    .update(Buffer.from(hubPublic.text, 'base64url'))
+    .digest('base64url');
+  const derivedPublic = crypto.createPublicKey(hubPrivateKey).export({ format: 'der', type: 'spki' }).toString('base64url');
+  if (derivedPublic !== hubPublic.text) throw securityError('hub-device-authority-key-mismatch');
+  const hubId = clean(authority.hubId, 128);
+
+  let registry = parseJsonFile(registryPath);
+  if (!registry || Number(registry.version) !== AUTHORITY_VERSION || !registry.devices || typeof registry.devices !== 'object') {
+    registry = { version: AUTHORITY_VERSION, devices: {} };
+  }
+
+  function persistRegistry(nextRegistry = registry) {
+    atomicPrivateJson(registryPath, nextRegistry);
+  }
+
+  function normalizeCredentialRequest({ accountId, deviceId, devicePublicKey } = {}) {
+    const owner = clean(accountId, 128);
+    const id = clean(deviceId, 128);
+    if (!owner) throw securityError('device-account-required');
+    if (!id) throw securityError('device-id-required');
+    const deviceKey = requireP256PublicKey(devicePublicKey);
+    return { owner, id, deviceKey };
+  }
+
+  function assertEnrollmentAllowed(request) {
+    const normalized = normalizeCredentialRequest(request);
+    const existing = registry.devices[normalized.id];
+    if (existing && !existing.revokedAt) throw securityError('device-already-enrolled');
+    if (!existing && Object.keys(registry.devices).length >= MAX_DEVICES) {
+      throw securityError('device-registry-capacity');
+    }
+    return true;
+  }
+
+  function issueCredential({ accountId, deviceId, devicePublicKey }) {
+    const { owner, id, deviceKey } = normalizeCredentialRequest({ accountId, deviceId, devicePublicKey });
+    const existing = registry.devices[id];
+    if (existing && !existing.revokedAt) throw securityError('device-already-enrolled');
+    if (!existing && Object.keys(registry.devices).length >= MAX_DEVICES) throw securityError('device-registry-capacity');
+    const issuedAt = Math.floor(now());
+    const payload = {
+      serial: crypto.randomBytes(16).toString('base64url'),
+      accountId: owner,
+      hubId,
+      deviceId: id,
+      devicePublicKey: deviceKey.text,
+      hubPublicKey: hubPublic.text,
+      issuedAt,
+      expiresAt: issuedAt + boundedTtlMs
+    };
+    const payloadText = encodeCredentialPayload(payload);
+    const signature = crypto.sign('sha256', Buffer.from(payloadText, 'utf8'), {
+      key: hubPrivateKey,
+      dsaEncoding: 'ieee-p1363'
+    }).toString('base64url');
+    const credential = `${payloadText}.${signature}`;
+    const nextRegistry = {
+      ...registry,
+      devices: {
+        ...registry.devices,
+        [id]: {
+          serial: payload.serial,
+          accountId: owner,
+          hubId,
+          devicePublicKey: deviceKey.text,
+          credential,
+          issuedAt,
+          expiresAt: payload.expiresAt,
+          revokedAt: '',
+          lastConnectedAt: ''
+        }
+      }
+    };
+    persistRegistry(nextRegistry);
+    registry = nextRegistry;
+    return { credential, payload: { ...payload }, hubPublicKey: hubPublic.text };
+  }
+
+  function verifyCredential(credential, { accountId, deviceId } = {}) {
+    const parsed = parseCredential(credential);
+    const signatureValid = crypto.verify('sha256', Buffer.from(parsed.payloadText, 'utf8'), {
+      key: hubPublic.key,
+      dsaEncoding: 'ieee-p1363'
+    }, parsed.signature);
+    if (!signatureValid) throw securityError('device-credential-signature-invalid');
+    const expectedAccountId = clean(accountId, 128);
+    const expectedDeviceId = clean(deviceId, 128);
+    if (parsed.payload.hubId !== hubId
+      || parsed.payload.hubPublicKey !== hubPublic.text
+      || expectedAccountId && parsed.payload.accountId !== expectedAccountId
+      || expectedDeviceId && parsed.payload.deviceId !== expectedDeviceId) {
+      throw securityError('device-credential-binding-invalid');
+    }
+    const record = registry.devices[parsed.payload.deviceId];
+    if (!record
+      || record.revokedAt
+      || record.serial !== parsed.payload.serial
+      || record.accountId !== parsed.payload.accountId
+      || record.hubId !== parsed.payload.hubId
+      || record.devicePublicKey !== parsed.payload.devicePublicKey
+      || record.credential !== parsed.text) {
+      throw securityError('device-credential-revoked');
+    }
+    const current = Math.floor(now());
+    if (parsed.payload.issuedAt > current + 30_000 || parsed.payload.expiresAt <= current) {
+      throw securityError('device-credential-expired');
+    }
+    return { ...parsed, record: { ...record } };
+  }
+
+  function verifyDeviceSignature(verifiedCredential, message, signature) {
+    const deviceKey = requireP256PublicKey(verifiedCredential?.payload?.devicePublicKey);
+    const signatureBytes = exactBase64Url(signature, 64, 64);
+    if (!crypto.verify('sha256', Buffer.from(String(message || ''), 'utf8'), {
+      key: deviceKey.key,
+      dsaEncoding: 'ieee-p1363'
+    }, signatureBytes)) {
+      throw securityError('device-signature-invalid');
+    }
+    return true;
+  }
+
+  function signHubMessage(message) {
+    return crypto.sign('sha256', Buffer.from(String(message || ''), 'utf8'), {
+      key: hubPrivateKey,
+      dsaEncoding: 'ieee-p1363'
+    }).toString('base64url');
+  }
+
+  function issueRendezvousProof({ roomId, accountId, deviceId, role, ttlMs = 60_000 } = {}) {
+    const room = clean(roomId, 160);
+    const owner = clean(accountId, 128);
+    const device = clean(deviceId, 128);
+    const normalizedRole = clean(role, 16).toLowerCase();
+    if (!room || !owner || !device) throw securityError('rendezvous-proof-binding-required');
+    if (!['hub', 'client'].includes(normalizedRole)) throw securityError('rendezvous-proof-role-required');
+    const issuedAt = Math.floor(now());
+    const payload = {
+      version: 2,
+      protocol: 'livedesk.udp.rendezvous-proof.v2',
+      issuerKeyId: hubIssuerKeyId,
+      roomId: room,
+      role: normalizedRole,
+      accountId: owner,
+      hubId,
+      deviceId: device,
+      issuedAt,
+      expiresAt: issuedAt + Math.max(10_000, Math.min(120_000, Number(ttlMs) || 60_000)),
+      nonce: crypto.randomBytes(16).toString('base64url')
+    };
+    const payloadText = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+    return { proof: `${payloadText}.${signHubMessage(payloadText)}`, payload };
+  }
+
+  function revokeDevice(deviceId, reason = 'operator-revoked') {
+    const id = clean(deviceId, 128);
+    const record = registry.devices[id];
+    if (!record || record.revokedAt) return false;
+    const nextRegistry = {
+      ...registry,
+      devices: {
+        ...registry.devices,
+        [id]: {
+          ...record,
+          revokedAt: new Date(now()).toISOString(),
+          revokeReason: clean(reason, 160)
+        }
+      }
+    };
+    persistRegistry(nextRegistry);
+    registry = nextRegistry;
+    return true;
+  }
+
+  function markConnected(deviceId) {
+    const id = clean(deviceId, 128);
+    const record = registry.devices[id];
+    if (!record || record.revokedAt) return false;
+    const nextRegistry = {
+      ...registry,
+      devices: {
+        ...registry.devices,
+        [id]: { ...record, lastConnectedAt: new Date(now()).toISOString() }
+      }
+    };
+    persistRegistry(nextRegistry);
+    registry = nextRegistry;
+    return true;
+  }
+
+  function listDevices() {
+    return Object.entries(registry.devices).map(([deviceId, record]) => ({
+      deviceId,
+      serial: record.serial,
+      accountId: record.accountId,
+      hubId: record.hubId,
+      issuedAt: record.issuedAt,
+      expiresAt: record.expiresAt,
+      revokedAt: record.revokedAt || '',
+      lastConnectedAt: record.lastConnectedAt || ''
+    }));
+  }
+
+  function clearDevices() {
+    const removed = Object.keys(registry.devices).length;
+    const nextRegistry = { version: AUTHORITY_VERSION, devices: {} };
+    persistRegistry(nextRegistry);
+    registry = nextRegistry;
+    return removed;
+  }
+
+  return Object.freeze({
+    hubId,
+    hubPublicKey: hubPublic.text,
+    hubIssuerKeyId,
+    assertEnrollmentAllowed,
+    issueCredential,
+    verifyCredential,
+    verifyDeviceSignature,
+    signHubMessage,
+    issueRendezvousProof,
+    revokeDevice,
+    markConnected,
+    listDevices,
+    clearDevices
+  });
+}
+
+export const DEVICE_CREDENTIAL_PROTOCOL = 'livedesk.device-credential.v1';

package/src/security/security-audit-store.js

@@ -0,0 +1,260 @@
+import crypto from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createOsSecretStore } from '@livedesk/runtime-core/os-secret-store';
+
+const AUDIT_VERSION = 1;
+const MAX_RECORDS = 50_000;
+const MAX_FILE_BYTES = 128 * 1024 * 1024;
+const MAX_FIELD = 2_000;
+
+function auditError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function text(value, maximum = MAX_FIELD) {
+  return String(value ?? '').replace(/[\0\r\n]/g, ' ').trim().slice(0, maximum);
+}
+
+function redact(value, depth = 0) {
+  if (depth > 4) return '[truncated]';
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => redact(item, depth + 1));
+  if (!value || typeof value !== 'object') return typeof value === 'string' ? text(value) : value;
+  return Object.fromEntries(Object.entries(value).slice(0, 100).map(([key, child]) => [
+    text(key, 120),
+    /content|payload|data(base64)?|command|script|token|secret|password|credential|api[-_]?key|authorization|private[-_]?key/i.test(key)
+      ? '[redacted]'
+      : redact(child, depth + 1)
+  ]));
+}
+
+function canonicalPayload(event = {}) {
+  return {
+    version: AUDIT_VERSION,
+    auditId: text(event.auditId || crypto.randomUUID(), 100),
+    timestamp: text(event.timestamp || new Date().toISOString(), 64),
+    actorAccountId: text(event.actorAccountId, 128),
+    actorUserId: text(event.actorUserId, 128),
+    hubId: text(event.hubId, 128),
+    deviceId: text(event.deviceId, 128),
+    deviceIds: Array.isArray(event.deviceIds)
+      ? [...new Set(event.deviceIds.map(item => text(item, 128)).filter(Boolean))].slice(0, 500)
+      : [],
+    sessionId: text(event.sessionId, 160),
+    action: text(event.action, 160),
+    phase: text(event.phase, 40),
+    result: text(event.result, 80),
+    reason: text(event.reason, 240),
+    authMethod: text(event.authMethod, 80),
+    requestHash: text(event.requestHash, 100),
+    startedAt: text(event.startedAt, 64),
+    completedAt: text(event.completedAt, 64),
+    details: redact(event.details || {})
+  };
+}
+
+function hashPayload(payload) {
+  return crypto.createHash('sha256').update(JSON.stringify(payload), 'utf8').digest('base64url');
+}
+
+function signRecord(key, previousHash, payloadHash) {
+  return crypto.createHmac('sha256', key).update(`${previousHash}.${payloadHash}`, 'utf8').digest('base64url');
+}
+
+function hashRecord(previousHash, payloadHash, mac) {
+  return crypto.createHash('sha256').update(`${previousHash}.${payloadHash}.${mac}`, 'utf8').digest('base64url');
+}
+
+function parseSeal(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    const key = Buffer.from(String(parsed?.key || ''), 'base64url');
+    if (Number(parsed?.version) !== AUDIT_VERSION || key.length !== 32) return null;
+    return {
+      version: AUDIT_VERSION,
+      key,
+      headHash: text(parsed.headHash, 100),
+      recordCount: Math.max(0, Number(parsed.recordCount) || 0)
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function syncFile(filePath, flags = 'r') {
+  const handle = await open(filePath, flags, 0o600);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function appendDurably(filePath, value) {
+  const handle = await open(filePath, 'a', 0o600);
+  try {
+    await handle.writeFile(value, { encoding: 'utf8' });
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export function createSecurityAuditStore({ dataDir = path.join(os.homedir(), '.livedesk') } = {}) {
+  const filePath = path.join(dataDir, 'security', 'security-audit-v1.jsonl');
+  const sealStore = createOsSecretStore({
+    service: 'LiveDesk',
+    account: `security-audit-seal:${crypto.createHash('sha256').update(path.resolve(filePath)).digest('hex').slice(0, 24)}`,
+    dataDir
+  });
+  const existingSealText = sealStore.read();
+  let seal = parseSeal(existingSealText);
+  if (!seal) {
+    if (existingSealText || existsSync(filePath)) throw auditError('security-audit-seal-unavailable');
+    seal = { version: AUDIT_VERSION, key: crypto.randomBytes(32), headHash: '', recordCount: 0 };
+    if (!persistSeal()) throw auditError('security-audit-secure-store-unavailable');
+  }
+
+  let records = null;
+  let writeQueue = Promise.resolve();
+
+  function persistSeal() {
+    return sealStore.write(JSON.stringify({
+      version: AUDIT_VERSION,
+      key: seal.key.toString('base64url'),
+      headHash: seal.headHash,
+      recordCount: seal.recordCount
+    }));
+  }
+
+  function verifyRecords(candidateRecords) {
+    let previousHash = '';
+    let sealedHeadObserved = seal.headHash === '';
+    for (const record of candidateRecords) {
+      const payload = canonicalPayload(record?.payload || {});
+      const payloadHash = hashPayload(payload);
+      const expectedMac = signRecord(seal.key, previousHash, payloadHash);
+      const expectedRecordHash = hashRecord(previousHash, payloadHash, expectedMac);
+      if (record?.version !== AUDIT_VERSION
+        || record.previousHash !== previousHash
+        || record.payloadHash !== payloadHash
+        || record.mac !== expectedMac
+        || record.recordHash !== expectedRecordHash) {
+        throw auditError('security-audit-integrity-failed');
+      }
+      previousHash = expectedRecordHash;
+      if (previousHash === seal.headHash) sealedHeadObserved = true;
+    }
+    if (seal.headHash && !sealedHeadObserved) throw auditError('security-audit-truncation-detected');
+    return previousHash;
+  }
+
+  async function load() {
+    if (records) return records;
+    try {
+      const metadata = await stat(filePath);
+      if (metadata.size > MAX_FILE_BYTES) throw auditError('security-audit-file-too-large');
+      const lines = (await readFile(filePath, 'utf8')).split(/\r?\n/).filter(Boolean);
+      records = lines.map(line => JSON.parse(line));
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      records = [];
+    }
+    const headHash = verifyRecords(records);
+    if (headHash !== seal.headHash || records.length !== seal.recordCount) {
+      seal.headHash = headHash;
+      seal.recordCount = records.length;
+      if (!persistSeal()) throw auditError('security-audit-secure-store-unavailable');
+    }
+    return records;
+  }
+
+  async function rewriteRetained(current) {
+    if (current.length <= MAX_RECORDS) return;
+    const retainedPayloads = current.slice(-(MAX_RECORDS - 1)).map(record => record.payload);
+    const pruned = current.length - retainedPayloads.length;
+    const payloads = [canonicalPayload({
+      action: 'security.audit.retention-pruned',
+      phase: 'complete',
+      result: 'success',
+      details: { prunedRecords: pruned, retentionLimit: MAX_RECORDS }
+    }), ...retainedPayloads];
+    const rebuilt = [];
+    let previousHash = '';
+    for (const payload of payloads) {
+      const payloadHash = hashPayload(payload);
+      const mac = signRecord(seal.key, previousHash, payloadHash);
+      const recordHash = hashRecord(previousHash, payloadHash, mac);
+      rebuilt.push({ version: AUDIT_VERSION, previousHash, payloadHash, mac, recordHash, payload });
+      previousHash = recordHash;
+    }
+    const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporary, `${rebuilt.map(record => JSON.stringify(record)).join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+    await syncFile(temporary);
+    await rename(temporary, filePath);
+    records = rebuilt;
+    seal.headHash = previousHash;
+    seal.recordCount = rebuilt.length;
+    if (!persistSeal()) throw auditError('security-audit-secure-store-unavailable');
+  }
+
+  return Object.freeze({
+    filePath,
+    async record(event) {
+      let written;
+      writeQueue = writeQueue.then(async () => {
+        const current = await load();
+        const payload = canonicalPayload(event);
+        const previousHash = current.at(-1)?.recordHash || '';
+        const payloadHash = hashPayload(payload);
+        const mac = signRecord(seal.key, previousHash, payloadHash);
+        const recordHash = hashRecord(previousHash, payloadHash, mac);
+        written = { version: AUDIT_VERSION, previousHash, payloadHash, mac, recordHash, payload };
+        await mkdir(path.dirname(filePath), { recursive: true });
+        // A successful record() is the mutation gate for security-sensitive
+        // operations. Resolve only after the JSONL record is on stable storage.
+        await appendDurably(filePath, `${JSON.stringify(written)}\n`);
+        current.push(written);
+        seal.headHash = recordHash;
+        seal.recordCount = current.length;
+        if (!persistSeal()) throw auditError('security-audit-secure-store-unavailable');
+        await rewriteRetained(current);
+      });
+      await writeQueue;
+      return written;
+    },
+    async list({ limit = 500, action = '' } = {}) {
+      const current = await load();
+      const bounded = Math.max(1, Math.min(2_000, Number(limit) || 500));
+      return current
+        .filter(record => !action || record.payload?.action === String(action))
+        .slice(-bounded)
+        .reverse()
+        .map(record => ({ ...record.payload, recordHash: record.recordHash }));
+    },
+    async verify() {
+      const current = await load();
+      const headHash = verifyRecords(current);
+      return { ok: true, records: current.length, headHash, sealed: headHash === seal.headHash };
+    },
+    async reset() {
+      writeQueue = writeQueue.then(async () => {
+        await rm(filePath, { force: true });
+        records = [];
+        seal = {
+          version: AUDIT_VERSION,
+          key: crypto.randomBytes(32),
+          headHash: '',
+          recordCount: 0
+        };
+        if (!persistSeal()) throw auditError('security-audit-secure-store-unavailable');
+      });
+      await writeQueue;
+      return { ok: true };
+    }
+  });
+}