enigma-memory 0.1.17 → 0.1.22

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;
+}

package/packages/developer-platform/src/http.js

@@ -0,0 +1,132 @@
+const MAX_BODY_BYTES = 64 * 1024;
+const KEY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+class ApiKeyHttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'ApiKeyHttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function writeJson(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.end(body);
+}
+
+async function readJson(request) {
+  const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== 'application/json') throw new ApiKeyHttpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+  const chunks = [];
+  let bytes = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    bytes += chunk.length;
+    if (bytes > MAX_BODY_BYTES) tooLarge = true;
+    else chunks.push(chunk);
+  }
+  if (tooLarge) throw new ApiKeyHttpError(413, 'payload_too_large', 'request body exceeds 64 KiB');
+  try {
+    const value = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8') || '{}');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+    return value;
+  } catch {
+    throw new ApiKeyHttpError(400, 'invalid_json', 'request body must be a JSON object');
+  }
+}
+
+function rejectUnknown(input, allowed) {
+  const unknown = Object.keys(input).find((key) => !allowed.has(key));
+  if (unknown) throw new ApiKeyHttpError(400, 'invalid_request', `unknown field: ${unknown}`);
+}
+
+function issueInput(input, principal) {
+  rejectUnknown(input, new Set(['label', 'scopes', 'ttlSeconds']));
+  return {
+    ownerId: principal.ownerId || principal.subject,
+    tenantId: principal.tenantId || 'default',
+    actorId: principal.subject || principal.ownerId,
+    label: input.label,
+    scopes: input.scopes,
+    ttlSeconds: input.ttlSeconds,
+  };
+}
+
+function operationStatus(error) {
+  if (error instanceof ApiKeyHttpError) return error;
+  if (error?.code === 'not_found') return new ApiKeyHttpError(404, 'not_found', 'API key not found');
+  if (error instanceof TypeError) return new ApiKeyHttpError(400, 'invalid_request', error.message);
+  if (/not found/i.test(error?.message || '')) return new ApiKeyHttpError(404, 'not_found', 'API key not found');
+  if (/limit|active API key|revoked API key/i.test(error?.message || '')) return new ApiKeyHttpError(409, 'conflict', error.message);
+  return new ApiKeyHttpError(500, 'internal_error', 'API key operation failed');
+}
+
+export function createApiKeyHttpHandler(options = {}) {
+  const apiKeys = options.apiKeys;
+  if (!apiKeys || typeof apiKeys.issue !== 'function' || typeof apiKeys.authenticate !== 'function') throw new TypeError('apiKeys service is required');
+  if (typeof options.authorizeAdmin !== 'function') throw new TypeError('authorizeAdmin is required');
+  const basePath = String(options.basePath || '/v1/api-keys').replace(/\/+$/, '');
+
+  return async function apiKeyHttpHandler(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) return false;
+    try {
+      let principal;
+      try { principal = await options.authorizeAdmin({ request, headers: request.headers }); } catch { principal = null; }
+      if (!principal?.subject && !principal?.ownerId) throw new ApiKeyHttpError(401, 'unauthorized', 'administrator authentication is required');
+      const identity = {
+        ownerId: principal.ownerId || principal.subject,
+        tenantId: principal.tenantId || 'default',
+        actorId: principal.subject || principal.ownerId,
+      };
+
+      if (request.method === 'GET' && url.pathname === `${basePath}/scopes`) {
+        writeJson(response, 200, { schema: 'enigma.api_key_scopes.v1', scopes: apiKeys.supportedScopes });
+        return true;
+      }
+      if (request.method === 'GET' && url.pathname === `${basePath}/audit`) {
+        const limitValue = url.searchParams.get('limit');
+        const limit = limitValue === null ? undefined : Number(limitValue);
+        writeJson(response, 200, { schema: 'enigma.api_key_audit.v1', events: await apiKeys.audit({ ...identity, limit }) });
+        return true;
+      }
+      if (request.method === 'GET' && url.pathname === basePath) {
+        writeJson(response, 200, { schema: 'enigma.api_key_list.v1', keys: await apiKeys.list(identity) });
+        return true;
+      }
+      if (request.method === 'POST' && url.pathname === basePath) {
+        const input = await readJson(request);
+        writeJson(response, 201, await apiKeys.issue(issueInput(input, identity)));
+        return true;
+      }
+
+      const suffix = url.pathname.slice(basePath.length + 1);
+      const [id, action, extra] = suffix.split('/');
+      if (!KEY_ID_PATTERN.test(id || '') || extra) throw new ApiKeyHttpError(404, 'not_found', 'API key endpoint not found');
+      if (request.method === 'POST' && action === 'rotate') {
+        const input = await readJson(request);
+        rejectUnknown(input, new Set(['label', 'scopes', 'ttlSeconds']));
+        writeJson(response, 201, await apiKeys.rotate(id, { ...issueInput(input, identity) }));
+        return true;
+      }
+      if (request.method === 'DELETE' && action === undefined) {
+        const input = await readJson(request);
+        rejectUnknown(input, new Set(['reason']));
+        writeJson(response, 200, await apiKeys.revoke(id, { ...identity, reason: input.reason }));
+        return true;
+      }
+      throw new ApiKeyHttpError(405, 'method_not_allowed', 'API key endpoint method is not allowed');
+    } catch (error) {
+      const normalized = operationStatus(error);
+      if (normalized.status === 401) response.setHeader('WWW-Authenticate', 'Bearer');
+      writeJson(response, normalized.status, { error: { code: normalized.code, message: normalized.message } });
+      return true;
+    }
+  };
+}

package/packages/developer-platform/src/index.js

@@ -0,0 +1,4 @@
+export * from './access-credentials.js';
+export * from './http.js';
+export * from './usage.js';
+export * from './usage-http.js';

package/packages/developer-platform/src/usage-http.js

@@ -0,0 +1,60 @@
+function json(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.end(body);
+}
+
+function queryInput(url, principal) {
+  const daysValue = url.searchParams.get('days');
+  const days = daysValue === null ? 30 : Number(daysValue);
+  if (!Number.isInteger(days) || days < 1 || days > 400) throw new TypeError('days must be an integer from 1 through 400');
+  const to = url.searchParams.get('to') || undefined;
+  const parsedTo = to === undefined ? Date.now() + 1 : Date.parse(to);
+  if (!Number.isFinite(parsedTo)) throw new TypeError('to must be an ISO timestamp');
+  const from = url.searchParams.get('from') || new Date(parsedTo - days * 24 * 60 * 60_000).toISOString();
+  if (!Number.isFinite(Date.parse(from))) throw new TypeError('from must be an ISO timestamp');
+  const limitValue = url.searchParams.get('limit');
+  const limit = limitValue === null ? undefined : Number(limitValue);
+  return { principal, from, to: new Date(parsedTo).toISOString(), limit };
+}
+
+export function createUsageHttpHandler(options = {}) {
+  const usage = options.usage;
+  if (!usage || typeof usage.aggregate !== 'function' || typeof usage.events !== 'function') throw new TypeError('usage service is required');
+  if (typeof options.authorize !== 'function') throw new TypeError('usage HTTP authorizer is required');
+  const basePath = String(options.basePath || '/v1/usage').replace(/\/+$/, '');
+
+  return async function usageHttpHandler(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== basePath && url.pathname !== `${basePath}/events`) return false;
+    try {
+      let principal;
+      try { principal = await options.authorize({ request, headers: request.headers, requiredScopes: ['usage:read'] }); } catch { principal = null; }
+      if (!principal) {
+        response.setHeader('WWW-Authenticate', 'Bearer scope="usage:read"');
+        json(response, 401, { error: { code: 'unauthorized', message: 'usage:read authorization is required' } });
+        return true;
+      }
+      if (request.method !== 'GET') {
+        response.setHeader('Allow', 'GET');
+        json(response, 405, { error: { code: 'method_not_allowed', message: 'usage endpoints are read-only' } });
+        return true;
+      }
+      const input = queryInput(url, principal);
+      if (url.pathname === `${basePath}/events`) {
+        json(response, 200, { schema: 'enigma.platform_usage_event_list.v1', events: await usage.events(input) });
+      } else {
+        json(response, 200, await usage.aggregate(input));
+      }
+      return true;
+    } catch (error) {
+      const status = error instanceof TypeError ? 400 : 500;
+      json(response, status, { error: { code: status === 400 ? 'invalid_request' : 'usage_error', message: error.message || 'usage query failed' } });
+      return true;
+    }
+  };
+}