enigma-memory 0.1.18 → 0.1.22

package/packages/dev-tools/src/swarm-simulator.js

@@ -0,0 +1,101 @@
+// Enigma GhostMesh Multi-Node Swarm Simulator.
+// Simulates P2P routing convergence, multi-hop packet dispatching,
+// and delivery success metrics across N autonomous agent nodes.
+import {
+  MeshGossipNode,
+  InMemoryBus,
+  InMemoryTransport,
+  generateMeshIdentity,
+} from '../../mesh/src/index.js';
+
+export async function simulateSwarmNetwork(options = {}) {
+  const nodeCount = Math.max(2, Math.min(options.nodeCount || 5, 20));
+  const messageCount = Math.max(1, options.messageCount || 10);
+  const bus = new InMemoryBus();
+
+  const nodes = [];
+  const identities = [];
+  const receivedMessages = new Map(); // targetDestinationHex -> Array<plaintext>
+
+  // 1. Initialize nodes
+  for (let i = 0; i < nodeCount; i++) {
+    const identity = generateMeshIdentity();
+    const nodeId = `sim_node_${i + 1}`;
+    const transport = new InMemoryTransport(nodeId, bus);
+    const node = new MeshGossipNode({
+      nodeId,
+      identity,
+      transports: [transport],
+    });
+
+    const destHex = identity.destinationHex;
+    receivedMessages.set(destHex, []);
+    node.on('capsule', ({ plaintext }) => {
+      const list = receivedMessages.get(destHex);
+      if (list) list.push(plaintext);
+    });
+
+    await node.start();
+    nodes.push(node);
+    identities.push(identity);
+  }
+
+  // 2. Announce routes sequentially to establish topology
+  for (let i = 0; i < nodeCount; i++) {
+    await nodes[i].announce({ name: `Agent-${i + 1}`, index: i });
+  }
+  await new Promise(r => setTimeout(r, 60));
+
+  // 3. Dispatch simulated messages across random pairs
+  let deliveredCount = 0;
+  const deliveryLatenciesMs = [];
+
+  for (let m = 0; m < messageCount; m++) {
+    const senderIdx = m % nodeCount;
+    let targetIdx = (m + 1) % nodeCount;
+    if (senderIdx === targetIdx) targetIdx = (targetIdx + 1) % nodeCount;
+
+    const sender = nodes[senderIdx];
+    const target = identities[targetIdx];
+    const payload = `Swarm message #${m + 1} from Node ${senderIdx + 1} to Node ${targetIdx + 1}`;
+
+    const start = Date.now();
+    const res = await sender.sendEncryptedCapsule(
+      target.destinationHex,
+      target.encryptionPublicKey,
+      payload
+    );
+
+    // Wait briefly for in-memory delivery to process
+    await new Promise(r => setTimeout(r, 10));
+
+    const targetInbox = receivedMessages.get(target.destinationHex) || [];
+    const received = targetInbox.includes(payload);
+
+    if (res.routed && received) {
+      deliveredCount++;
+      deliveryLatenciesMs.push(Date.now() - start);
+    }
+  }
+
+  // 4. Teardown
+  for (const n of nodes) {
+    await n.stop();
+  }
+
+  const successRate = Math.round((deliveredCount / messageCount) * 100);
+  const meanLatency = deliveryLatenciesMs.length > 0
+    ? Math.round((deliveryLatenciesMs.reduce((a, b) => a + b, 0) / deliveryLatenciesMs.length) * 10) / 10
+    : 0;
+
+  return {
+    ok: true,
+    simulation: 'ghostmesh_swarm_simulation_v1',
+    nodeCount,
+    messageCount,
+    deliveredCount,
+    deliverySuccessRatePercent: successRate,
+    meanLatencyMs: meanLatency,
+    timestamp: Date.now(),
+  };
+}

package/packages/dev-tools/src/vault-inspector.js

@@ -0,0 +1,114 @@
+// Enigma Vault Bundle Inspector.
+// Analyzes encrypted vault headers, KDF metadata, scope distribution,
+// and Merkle tree roots with strict zero-leakage boundaries.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { deriveKeysFromPassphrase, PBKDF2_KDF_SPEC } from '../../vault/src/index.js';
+
+export async function inspectVaultBundle(bundlePath, options = {}) {
+  const resolved = path.resolve(bundlePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Vault file not found at path: ${resolved}`);
+  }
+
+  const fileStats = fs.statSync(resolved);
+  const rawText = fs.readFileSync(resolved, 'utf8');
+
+  let bundle;
+  try {
+    bundle = JSON.parse(rawText);
+  } catch (err) {
+    throw new Error(`Corrupt JSON in vault file: ${err.message}`);
+  }
+
+  const format = bundle.format || 'unknown';
+  const version = bundle.version || 1;
+  const isEncrypted = typeof bundle.ciphertext === 'string' && typeof bundle.authTag === 'string';
+  const kdf = bundle.kdf || null;
+
+  const inspectionReport = {
+    ok: true,
+    file: {
+      path: resolved,
+      sizeBytes: fileStats.size,
+      updatedAt: fileStats.mtime.toISOString(),
+    },
+    envelope: {
+      format,
+      version,
+      isEncrypted,
+      count: bundle.count || 0,
+      kdf: kdf ? {
+        algorithm: kdf.algorithm,
+        iterations: kdf.iterations,
+        hash: kdf.hash,
+        saltPresent: Boolean(kdf.salt),
+      } : null,
+      ivLengthBytes: bundle.iv ? Buffer.from(bundle.iv, 'hex').length : 0,
+      authTagLengthBytes: bundle.authTag ? Buffer.from(bundle.authTag, 'hex').length : 0,
+    },
+    contents: null,
+  };
+
+  // If passphrase is provided, perform deep inspection
+  if (options.passphrase && isEncrypted) {
+    try {
+      if (!kdf || !kdf.salt) throw new Error('Missing KDF salt in bundle');
+      const saltBuf = /^[0-9a-fA-F]+$/.test(kdf.salt)
+        ? Buffer.from(kdf.salt, 'hex')
+        : Buffer.from(kdf.salt, 'base64');
+      const kdfSpec = {
+        algorithm: kdf.algorithm || 'scrypt',
+        n: kdf.n || 16384,
+        r: kdf.r || 8,
+        p: kdf.p || 1,
+        iterations: kdf.iterations || 600000,
+        hash: kdf.hash || 'sha256',
+      };
+      const vaultKey = deriveKeysFromPassphrase(options.passphrase, saltBuf, kdfSpec).vaultKey;
+
+      const iv = Buffer.from(bundle.iv, 'hex');
+      const authTag = Buffer.from(bundle.authTag, 'hex');
+      const ciphertext = Buffer.from(bundle.ciphertext, 'base64');
+
+      const decipher = crypto.createDecipheriv('aes-256-gcm', vaultKey, iv);
+      if (bundle.aad) {
+        decipher.setAAD(Buffer.isBuffer(bundle.aad) ? bundle.aad : Buffer.from(bundle.aad));
+      }
+      decipher.setAuthTag(authTag);
+      const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      const data = JSON.parse(decrypted.toString('utf8'));
+
+      const scopes = {};
+      const memories = data.memories || [];
+      let oldest = Infinity;
+      let newest = 0;
+
+      for (const m of memories) {
+        const sc = m.scope || 'default';
+        scopes[sc] = (scopes[sc] || 0) + 1;
+        if (m.createdAt && m.createdAt < oldest) oldest = m.createdAt;
+        if (m.createdAt && m.createdAt > newest) newest = m.createdAt;
+      }
+
+      inspectionReport.contents = {
+        unlocked: true,
+        memoryCount: memories.length,
+        scopeDistribution: scopes,
+        timeline: {
+          oldestMemory: oldest !== Infinity ? new Date(oldest).toISOString() : null,
+          newestMemory: newest !== 0 ? new Date(newest).toISOString() : null,
+        },
+        hasVectorBundle: Boolean(data.vectorBundle),
+      };
+    } catch (err) {
+      inspectionReport.contents = {
+        unlocked: false,
+        error: `Decryption failed: ${err.message}`,
+      };
+    }
+  }
+
+  return inspectionReport;
+}

package/packages/dev-tools/src/vector-benchmark.js

@@ -0,0 +1,100 @@
+// Enigma Vector Benchmark Suite.
+// Benchmarks embedding generation throughput, semantic search latency,
+// and Int8 quantization memory savings and cosine fidelity.
+import { performance } from 'node:perf_hooks';
+import {
+  computeLexicalEmbedding,
+  cosineSimilarity,
+  quantizeVector,
+  dequantizeVector,
+  EncryptedVectorStore,
+} from '../../rag/src/index.js';
+
+/**
+ * @param {Object} [options]
+ * @param {number} [options.itemCount]
+ * @param {number} [options.queryCount]
+ * @param {Object} [options.embeddingProvider]
+ * @param {EncryptedVectorStore} [options.vectorStore]
+ */
+export async function runVectorBenchmark(options = {}) {
+  const itemCount = Math.max(10, options.itemCount || 100);
+  const queryCount = Math.max(5, options.queryCount || 50);
+
+  const sampleCorpus = [
+    'Always enforce 0.5% maximum slippage on Jupiter DEX Solana swaps',
+    'Verify on-chain zero-knowledge commitments before releasing private memory data',
+    'Use Aztec Indexed Merkle Trees for constant-time non-membership nullifier proof verification',
+    'GhostMesh peer communications require X25519 ECDH key exchange with AES-256-GCM AEAD',
+    'Autonomous agents must fail closed when cryptographic custody is absent',
+    'Token budget allocation for prompt context compilation should prioritize high importance memory atoms',
+    'Sealed Sale fair exchange atomically reveals data encryption keys upon Solana claim settlement',
+    'Poseidon hash sponge arithmetic over BN254 scalar field guarantees SNARK proof efficiency',
+  ];
+
+  // 1. Benchmark Embedding Throughput
+  const startEmbed = performance.now();
+  const embeddings = [];
+  for (let i = 0; i < itemCount; i++) {
+    const text = `${sampleCorpus[i % sampleCorpus.length]} (instance #${i})`;
+    embeddings.push(computeLexicalEmbedding(text));
+  }
+  const embedDurationMs = performance.now() - startEmbed;
+  const embedThroughput = Math.round((itemCount / (embedDurationMs / 1000)) * 10) / 10;
+
+  // 2. Benchmark Quantization Memory & Fidelity
+  let totalFidelity = 0;
+  for (let i = 0; i < Math.min(itemCount, 50); i++) {
+    const orig = embeddings[i];
+    const quantized = quantizeVector(orig);
+    const restored = dequantizeVector(quantized);
+    totalFidelity += cosineSimilarity(orig, restored);
+  }
+  const meanQuantizationFidelity = Math.round((totalFidelity / Math.min(itemCount, 50)) * 10000) / 10000;
+  const floatBytes = itemCount * 384 * 4;
+  const int8Bytes = itemCount * 384 * 1;
+  const memoryCompressionPercent = Math.round(((floatBytes - int8Bytes) / floatBytes) * 100);
+
+  // 3. Benchmark Vector Store Search Latency
+  const store = options.vectorStore || new EncryptedVectorStore({
+    quantize: true,
+    ...(options.embeddingProvider ? { embeddingProvider: options.embeddingProvider } : {}),
+  });
+  for (let i = 0; i < itemCount; i++) {
+    const text = `${sampleCorpus[i % sampleCorpus.length]} (instance #${i})`;
+    await store.add(`item_${i}`, text, { scope: 'benchmark' });
+  }
+
+  const startQuery = performance.now();
+  for (let q = 0; q < queryCount; q++) {
+    const query = sampleCorpus[q % sampleCorpus.length];
+    await store.search(query, { topK: 5 });
+  }
+  const queryDurationMs = performance.now() - startQuery;
+  const queryThroughput = Math.round((queryCount / (queryDurationMs / 1000)) * 10) / 10;
+  const meanLatencyMs = Math.round((queryDurationMs / queryCount) * 1000) / 1000;
+
+  return {
+    ok: true,
+    benchmark: 'enigma_vector_performance_v1',
+    itemCount,
+    queryCount,
+    embedding: {
+      totalDurationMs: Math.round(embedDurationMs * 100) / 100,
+      throughputPerSecond: embedThroughput,
+    },
+    quantization: {
+      dimension: 384,
+      float32Bytes: floatBytes,
+      int8Bytes: int8Bytes,
+      memoryReductionPercent: memoryCompressionPercent,
+      meanCosineFidelity: meanQuantizationFidelity,
+    },
+    retrieval: {
+      totalDurationMs: Math.round(queryDurationMs * 100) / 100,
+      queriesPerSecond: queryThroughput,
+      meanLatencyMs,
+    },
+    timestamp: Date.now(),
+  };
+}

package/packages/developer-platform/src/access-credentials.js

@@ -0,0 +1,341 @@
+import { randomBytes, randomUUID, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+export const ENIGMA_API_KEY_STORE_SCHEMA = 'enigma.api_key_store.v1';
+export const ENIGMA_API_KEY_SCHEMA = 'enigma.api_key.v1';
+const scrypt = promisify(scryptCallback);
+const KEY_PATTERN = /^enigma_sk_(live|test)_([A-Za-z0-9_-]{12})_([A-Za-z0-9_-]{43})$/;
+
+function clockIso(clock) {
+  return new Date(clock()).toISOString();
+}
+
+function boundedInteger(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new TypeError(`${name} must be an integer from ${minimum} through ${maximum}`);
+  }
+  return resolved;
+}
+
+function requiredString(value, name, maximum = 512) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${name} exceeds ${maximum} characters`);
+  return normalized;
+}
+
+function normalizeScopes(value, supportedScopes) {
+  const scopes = [...new Set((value || []).map((scope) => requiredString(scope, 'scope', 128)))].sort();
+  if (!scopes.length) throw new TypeError('at least one API key scope is required');
+  if (scopes.some((scope) => !supportedScopes.has(scope))) throw new TypeError('API key contains an unsupported scope');
+  return scopes;
+}
+
+function emptyState() {
+  return { schema: ENIGMA_API_KEY_STORE_SCHEMA, revision: 0, keys: {}, prefixIndex: {}, audit: [] };
+}
+
+function publicRecord(record) {
+  return {
+    schema: ENIGMA_API_KEY_SCHEMA,
+    id: record.id,
+    prefix: record.prefix,
+    environment: record.environment,
+    label: record.label,
+    ownerId: record.ownerId,
+    tenantId: record.tenantId,
+    scopes: [...record.scopes],
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+    lastUsedAt: record.lastUsedAt,
+    revokedAt: record.revokedAt,
+    revokeReason: record.revokeReason,
+    rotatedFrom: record.rotatedFrom,
+    rotatedTo: record.rotatedTo,
+    status: record.revokedAt ? 'revoked' : Date.parse(record.expiresAt) <= Date.now() ? 'expired' : 'active',
+  };
+}
+
+function createStoreAdapter(load, save, { clock, auditLimit }) {
+  let queue = Promise.resolve();
+  const transaction = (operation) => {
+    const run = queue.then(async () => {
+      const state = await load();
+      const result = await operation(state);
+      state.revision += 1;
+      if (state.audit.length > auditLimit) state.audit.splice(0, state.audit.length - auditLimit);
+      await save(state);
+      return result;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const view = async (operation) => {
+    await queue;
+    return operation(await load());
+  };
+  const appendAudit = (state, event) => state.audit.push({ eventId: randomUUID(), at: clockIso(clock), ...event });
+
+  return Object.freeze({
+    async insert(record, event) {
+      return transaction((state) => {
+        if (state.keys[record.id] || state.prefixIndex[record.prefix]) throw new Error('API key identifier collision');
+        state.keys[record.id] = structuredClone(record);
+        state.prefixIndex[record.prefix] = record.id;
+        appendAudit(state, event);
+        return structuredClone(record);
+      });
+    },
+    async rotate(previousId, nextRecord, event) {
+      return transaction((state) => {
+        const previous = state.keys[previousId];
+        if (!previous) return null;
+        if (previous.revokedAt) throw new Error('revoked API key cannot be rotated');
+        if (state.prefixIndex[nextRecord.prefix]) throw new Error('API key identifier collision');
+        previous.revokedAt = clockIso(clock);
+        previous.revokeReason = 'rotated';
+        previous.rotatedTo = nextRecord.id;
+        state.keys[nextRecord.id] = structuredClone(nextRecord);
+        state.prefixIndex[nextRecord.prefix] = nextRecord.id;
+        appendAudit(state, event);
+        return { previous: structuredClone(previous), next: structuredClone(nextRecord) };
+      });
+    },
+    async revoke(id, reason, event) {
+      return transaction((state) => {
+        const record = state.keys[id];
+        if (!record) return null;
+        if (!record.revokedAt) {
+          record.revokedAt = clockIso(clock);
+          record.revokeReason = reason;
+          appendAudit(state, event);
+        }
+        return structuredClone(record);
+      });
+    },
+    async getById(id) {
+      return view((state) => state.keys[id] ? structuredClone(state.keys[id]) : null);
+    },
+    async getByPrefix(prefix) {
+      return view((state) => {
+        const id = state.prefixIndex[prefix];
+        return id && state.keys[id] ? structuredClone(state.keys[id]) : null;
+      });
+    },
+    async list(ownerId, tenantId) {
+      return view((state) => Object.values(state.keys)
+        .filter((record) => record.ownerId === ownerId && record.tenantId === tenantId)
+        .map((record) => structuredClone(record))
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt)));
+    },
+    async markUsed(id, at) {
+      return transaction((state) => {
+        const record = state.keys[id];
+        if (!record || record.revokedAt || Date.parse(record.expiresAt) <= clock()) return false;
+        record.lastUsedAt = at;
+        return true;
+      });
+    },
+    async audit(ownerId, tenantId, limit = 100) {
+      return view((state) => state.audit
+        .filter((event) => event.ownerId === ownerId && event.tenantId === tenantId)
+        .slice(-limit)
+        .reverse()
+        .map((event) => structuredClone(event)));
+    },
+  });
+}
+
+export function createEphemeralApiKeyStore(options = {}) {
+  const clock = options.clock || Date.now;
+  const auditLimit = boundedInteger(options.auditLimit, 'auditLimit', 100, 100_000, 10_000);
+  let state = emptyState();
+  return createStoreAdapter(async () => structuredClone(state), async (next) => { state = structuredClone(next); }, { clock, auditLimit });
+}
+
+export function createFileApiKeyStore(options = {}) {
+  const path = resolve(String(options.path || '.enigma/api-keys.json'));
+  const clock = options.clock || Date.now;
+  const auditLimit = boundedInteger(options.auditLimit, 'auditLimit', 100, 100_000, 10_000);
+  async function load() {
+    try {
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state?.schema !== ENIGMA_API_KEY_STORE_SCHEMA) throw new Error('unsupported API key store schema');
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyState();
+      throw error;
+    }
+  }
+  async function save(state) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(state));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  }
+  return createStoreAdapter(load, save, { clock, auditLimit });
+}
+
+async function deriveSecret(secret, salt) {
+  return Buffer.from(await scrypt(secret, Buffer.from(salt, 'base64url'), 32, { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }));
+}
+
+function parseRawKey(value) {
+  const match = KEY_PATTERN.exec(String(value || ''));
+  return match ? { environment: match[1], prefix: match[2], secret: match[3] } : null;
+}
+
+function principalIdentity(input = {}) {
+  return {
+    ownerId: requiredString(input.ownerId || input.subject, 'ownerId'),
+    tenantId: requiredString(input.tenantId || input.tenant_id || 'default', 'tenantId'),
+  };
+}
+
+export function createApiKeyService(options = {}) {
+  const store = options.store;
+  if (!store || typeof store.insert !== 'function' || typeof store.getByPrefix !== 'function') throw new TypeError('API key store is required');
+  const clock = options.clock || Date.now;
+  const environment = options.environment === 'test' ? 'test' : 'live';
+  const supportedScopes = new Set(options.scopes || [
+    'mcp:invoke', 'models:invoke', 'images:generate', 'video:generate', 'code:execute', 'browser:control', 'usage:read', 'credits:create',
+    'memory:read', 'memory:write', 'memory:delete', 'vault:admin', 'swarm:read', 'swarm:write',
+    'security:inspect', 'metering:write', 'settlement:read', 'settlement:write', 'settlement:operator', 'nullifier:prepare', 'payments:execute',
+  ]);
+  const defaultScopes = normalizeScopes(options.defaultScopes || ['mcp:invoke', 'models:invoke'], supportedScopes);
+  const maxActiveKeys = boundedInteger(options.maxActiveKeys, 'maxActiveKeys', 1, 100, 20);
+  const maximumTtlSeconds = boundedInteger(options.maximumTtlSeconds, 'maximumTtlSeconds', 300, 366 * 24 * 60 * 60, 90 * 24 * 60 * 60);
+  const defaultTtlSeconds = boundedInteger(options.defaultTtlSeconds, 'defaultTtlSeconds', 300, maximumTtlSeconds, 30 * 24 * 60 * 60);
+
+  async function createRecord(input, rotation = {}) {
+    const identity = principalIdentity(input);
+    const scopes = normalizeScopes(input.scopes || defaultScopes, supportedScopes);
+    const ttlSeconds = boundedInteger(input.ttlSeconds, 'ttlSeconds', 300, maximumTtlSeconds, defaultTtlSeconds);
+    const issuedAt = clock();
+    const prefix = randomBytes(9).toString('base64url');
+    const secret = randomBytes(32).toString('base64url');
+    const salt = randomBytes(16).toString('base64url');
+    const secretDigest = (await deriveSecret(secret, salt)).toString('base64url');
+    const record = {
+      id: randomUUID(),
+      prefix,
+      environment,
+      label: requiredString(input.label || 'API key', 'label', 120),
+      ownerId: identity.ownerId,
+      tenantId: identity.tenantId,
+      scopes,
+      salt,
+      secretDigest,
+      createdAt: new Date(issuedAt).toISOString(),
+      expiresAt: new Date(issuedAt + ttlSeconds * 1_000).toISOString(),
+      lastUsedAt: null,
+      revokedAt: null,
+      revokeReason: null,
+      rotatedFrom: rotation.rotatedFrom || null,
+      rotatedTo: null,
+    };
+    return { record, rawKey: `enigma_sk_${environment}_${prefix}_${secret}` };
+  }
+
+  function assertOwned(record, identity) {
+    if (!record || record.ownerId !== identity.ownerId || record.tenantId !== identity.tenantId) {
+      const error = new Error('API key not found');
+      error.code = 'not_found';
+      throw error;
+    }
+  }
+
+  return Object.freeze({
+    supportedScopes: Object.freeze([...supportedScopes].sort()),
+    async issue(input = {}) {
+      const identity = principalIdentity(input);
+      const active = (await store.list(identity.ownerId, identity.tenantId))
+        .filter((record) => !record.revokedAt && Date.parse(record.expiresAt) > clock());
+      if (active.length >= maxActiveKeys) throw new Error(`active API key limit of ${maxActiveKeys} reached`);
+      const { record, rawKey } = await createRecord(input);
+      await store.insert(record, {
+        action: 'issued', keyId: record.id, prefix: record.prefix, ownerId: record.ownerId, tenantId: record.tenantId,
+        actorId: requiredString(input.actorId || identity.ownerId, 'actorId'),
+      });
+      return { key: publicRecord(record), secret: rawKey, secretShownOnce: true };
+    },
+    async list(input = {}) {
+      const identity = principalIdentity(input);
+      return (await store.list(identity.ownerId, identity.tenantId)).map(publicRecord);
+    },
+    async rotate(id, input = {}) {
+      const identity = principalIdentity(input);
+      const previous = await store.getById(requiredString(id, 'key id'));
+      assertOwned(previous, identity);
+      if (previous.revokedAt || Date.parse(previous.expiresAt) <= clock()) throw new Error('only an active API key can be rotated');
+      const { record, rawKey } = await createRecord({
+        ...input,
+        ownerId: identity.ownerId,
+        tenantId: identity.tenantId,
+        label: input.label || previous.label,
+        scopes: input.scopes || previous.scopes,
+      }, { rotatedFrom: previous.id });
+      const rotated = await store.rotate(previous.id, record, {
+        action: 'rotated', keyId: record.id, previousKeyId: previous.id, prefix: record.prefix,
+        ownerId: identity.ownerId, tenantId: identity.tenantId,
+        actorId: requiredString(input.actorId || identity.ownerId, 'actorId'),
+      });
+      if (!rotated) throw new Error('API key not found');
+      return { key: publicRecord(rotated.next), previous: publicRecord(rotated.previous), secret: rawKey, secretShownOnce: true };
+    },
+    async revoke(id, input = {}) {
+      const identity = principalIdentity(input);
+      const existing = await store.getById(requiredString(id, 'key id'));
+      assertOwned(existing, identity);
+      const reason = requiredString(input.reason || 'revoked_by_owner', 'reason', 200);
+      const record = await store.revoke(existing.id, reason, {
+        action: 'revoked', keyId: existing.id, prefix: existing.prefix, reason,
+        ownerId: identity.ownerId, tenantId: identity.tenantId,
+        actorId: requiredString(input.actorId || identity.ownerId, 'actorId'),
+      });
+      return publicRecord(record);
+    },
+    async authenticate(value, input = {}) {
+      const parsed = parseRawKey(value);
+      if (!parsed || parsed.environment !== environment) return null;
+      const record = await store.getByPrefix(parsed.prefix);
+      if (!record || record.revokedAt || Date.parse(record.expiresAt) <= clock()) return null;
+      const actual = await deriveSecret(parsed.secret, record.salt);
+      const expected = Buffer.from(record.secretDigest, 'base64url');
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return null;
+      const requiredScopes = [...new Set(input.requiredScopes || [])];
+      if (requiredScopes.some((scope) => !record.scopes.includes(scope))) return null;
+      if (input.tenantId && input.tenantId !== record.tenantId) return null;
+      const usedAt = clockIso(clock);
+      if (!await store.markUsed(record.id, usedAt)) return null;
+      return Object.freeze({
+        subject: record.ownerId,
+        ownerId: record.ownerId,
+        tenantId: record.tenantId,
+        keyId: record.id,
+        scopes: [...record.scopes],
+        authentication: 'api_key',
+      });
+    },
+    async audit(input = {}) {
+      const identity = principalIdentity(input);
+      const limit = boundedInteger(input.limit, 'limit', 1, 500, 100);
+      return store.audit(identity.ownerId, identity.tenantId, limit);
+    },
+  });
+}
+
+export function apiKeyFromAuthorization(value) {
+  if (!value || !String(value).startsWith('Bearer ')) return null;
+  const candidate = String(value).slice(7);
+  return KEY_PATTERN.test(candidate) ? candidate : null;
+}