@jami-studio/orchestra 0.1.0

package/src/index.mjs

@@ -0,0 +1,897 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ORCHESTRA_DRIZZLE_SCHEMA, libsqlOrchestraSchema, pgOrchestraSchema } from "./drizzle.mjs";
+import { ORCHESTRA_SCHEMA_VERSION, ORCHESTRA_TABLE_NAMES, ORCHESTRA_TABLES } from "./schema.mjs";
+
+export { ORCHESTRA_DRIZZLE_SCHEMA, libsqlOrchestraSchema, pgOrchestraSchema } from "./drizzle.mjs";
+export { ORCHESTRA_SCHEMA_VERSION, ORCHESTRA_TABLE_NAMES, ORCHESTRA_TABLES } from "./schema.mjs";
+export {
+  JOSE_SOURCE_LOCK,
+  OAuthTokenSecurityError,
+  assertSecretContextIsolation,
+  createOAuthTokenAuthority,
+  resolveSecretRefsForRun,
+  signLinkToken,
+  verifyLinkToken,
+} from "./oauth.mjs";
+
+import { createOAuthTokenAuthority } from "./oauth.mjs";
+
+export const ORCHESTRA_PACKAGE = {
+  name: "@jami-studio/orchestra",
+  version: "0.1.0",
+  schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+};
+
+export const DISPATCH_SOURCE_ATTRIBUTION = {
+  upstreamPackage: "@agent-native/dispatch",
+  upstreamVersion: "0.11.5",
+  upstreamRepository: "https://github.com/BuilderIO/agent-native/tree/main/packages/dispatch",
+  upstreamLicense: "MIT",
+  verifiedAt: "2026-06-22",
+  npmTarball: "https://registry.npmjs.org/@agent-native/dispatch/-/dispatch-0.11.5.tgz",
+  adoptionBoundary: "Control-plane dispatch concepts were reimplemented behind Jami-owned schema, vault, approval, grant, and audit contracts; no upstream source files are vendored.",
+};
+
+export const ORCHESTRA_MIGRATION_FIXTURES = [
+  {
+    fixtureId: "orchestra_vault_schema_2026_06_22_initial",
+    fromSchemaVersion: null,
+    toSchemaVersion: ORCHESTRA_SCHEMA_VERSION,
+    affectedTables: ["orchestra_secrets", "orchestra_secret_key_versions", "orchestra_audit_logs"],
+    verifies: ["sealed_payload_has_no_plaintext", "active_key_version_exists", "audit_records_secret_mutations_without_values"],
+  },
+  {
+    fixtureId: "orchestra_vault_key_rotation_2026_06_22",
+    fromSchemaVersion: ORCHESTRA_SCHEMA_VERSION,
+    toSchemaVersion: ORCHESTRA_SCHEMA_VERSION,
+    affectedTables: ["orchestra_secrets", "orchestra_secret_key_versions"],
+    verifies: ["old_key_version_retired", "secret_resealed_with_active_key", "plaintext_round_trips_after_rotation"],
+  },
+  {
+    fixtureId: "orchestra_oauth_token_binding_2026_06_23",
+    fromSchemaVersion: ORCHESTRA_SCHEMA_VERSION,
+    toSchemaVersion: ORCHESTRA_SCHEMA_VERSION,
+    affectedTables: ["orchestra_secrets", "orchestra_grants", "orchestra_audit_logs"],
+    verifies: [
+      "oauth_token_sealed_with_owner_org_audience_aad",
+      "cross_owner_or_org_read_denied",
+      "audience_binding_required_for_read",
+      "scope_change_revokes_active_tokens",
+    ],
+  },
+];
+
+const STATUS = new Set(["todo", "queued", "running", "waiting_approval", "completed", "failed", "cancelled", "blocked"]);
+const APPROVAL_STATUS = new Set(["requested", "approved", "denied", "expired"]);
+const RISK = new Set(["read", "write", "destructive", "external", "secret_adjacent", "unknown"]);
+const REDACTED = "[redacted]";
+const SECURITY_FORMAT_CHARS = /[\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g;
+const STRUCTURED_REDACTION_LIMIT = 65_536;
+const SENSITIVE_FIELD_PATTERN = /secret|apiKey|api_key|credential|password|plaintext|plain_text|tokenValue|token_value|clientSecret|client_secret|authorization|cookie|session|^value$/i;
+const SENSITIVE_TOKEN_FIELD_PATTERN = /^token$|^token(value|secret|credential|key|payload|plaintext)$|[a-z0-9_-]*token$/i;
+const SECRET_REF_SCHEMA_FIELDS = new Set(["schemaVersion", "secretId", "provider", "scope", "redactionClass", "createdAt", "expiresAt", "rotationRef", "description"]);
+
+export class OrchestraControlPlaneError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "OrchestraControlPlaneError";
+    this.code = code;
+  }
+}
+
+export function createInMemoryOrchestraControlPlane(options = {}) {
+  const now = options.now ?? (() => new Date());
+  const vault = options.vault ?? createSealedSecretVault({ now });
+  const oauth = createOAuthTokenAuthority({
+    now,
+    vault,
+    auditSink: { write: (event) => audit(adaptOAuthAuditEvent(event)) },
+  });
+  const state = {
+    orgDirectory: new Map(),
+    agents: new Map(),
+    dreams: new Map(),
+    tasks: new Map(),
+    runs: new Map(),
+    runEvents: new Map(),
+    toolCalls: new Map(),
+    artifacts: new Map(),
+    grants: new Map(),
+    approvals: new Map(),
+    secrets: new Map(),
+    secretKeyVersions: new Map(vault.keyVersionRecords().map((record) => [record.keyVersionId, record])),
+    auditLogs: new Map(),
+  };
+
+  function audit(input) {
+    const auditId = input.auditId ?? makeId("aud", input.actorId, input.eventType, state.auditLogs.size);
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      auditId,
+      actorId: normalizeId(input.actorId, "actor"),
+      eventType: input.eventType,
+      resourceRef: input.resourceRef ?? "resource_unknown",
+      outcome: input.outcome ?? "recorded",
+      summary: redactSummary(input.summary ?? input.eventType),
+      recordedAt: input.recordedAt ?? now().toISOString(),
+      metadata: redactObject(input.metadata ?? {}),
+    };
+    state.auditLogs.set(auditId, record);
+    return record;
+  }
+
+  function upsertDirectoryActor(input) {
+    const actorId = normalizeId(input.actorId, "actor");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      actorId,
+      actorType: input.actorType ?? "agent",
+      displayName: input.displayName ?? actorId,
+      status: input.status ?? "active",
+      metadata: redactObject(input.metadata ?? {}),
+      createdAt: input.createdAt ?? now().toISOString(),
+      updatedAt: input.updatedAt ?? now().toISOString(),
+    };
+    state.orgDirectory.set(actorId, record);
+    audit({ actorId, eventType: "org_directory.upserted", resourceRef: actorId, outcome: "allow", summary: "directory actor upserted" });
+    return record;
+  }
+
+  function registerAgent(input) {
+    const agentId = normalizeId(input.agentId, "agent");
+    const directoryActorId = normalizeId(input.directoryActorId ?? `actor_${agentId.replace(/^agent_/, "")}`, "actor");
+    if (!state.orgDirectory.has(directoryActorId)) {
+      upsertDirectoryActor({ actorId: directoryActorId, actorType: "agent", displayName: input.displayName ?? agentId });
+    }
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      agentId,
+      directoryActorId,
+      modelFamily: input.modelFamily ?? "unknown",
+      capabilities: redactObject(input.capabilities ?? {}),
+      status: input.status ?? "active",
+      createdAt: input.createdAt ?? now().toISOString(),
+      updatedAt: input.updatedAt ?? now().toISOString(),
+    };
+    state.agents.set(agentId, record);
+    audit({ actorId: directoryActorId, eventType: "agent.registered", resourceRef: agentId, outcome: "allow", summary: "agent registered" });
+    return record;
+  }
+
+  function createDream(input) {
+    const dreamId = normalizeId(input.dreamId, "dream");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      dreamId,
+      title: requireString(input.title, "title"),
+      status: input.status ?? "todo",
+      ownerActorId: normalizeId(input.ownerActorId, "actor"),
+      priority: Number.isInteger(input.priority) ? input.priority : 0,
+      metadata: redactObject(input.metadata ?? {}),
+      createdAt: input.createdAt ?? now().toISOString(),
+      updatedAt: input.updatedAt ?? now().toISOString(),
+    };
+    state.dreams.set(dreamId, record);
+    audit({ actorId: record.ownerActorId, eventType: "dream.created", resourceRef: dreamId, outcome: "allow", summary: "dream created" });
+    return record;
+  }
+
+  function createTask(input) {
+    const taskId = normalizeId(input.taskId, "task");
+    const assigneeAgentId = normalizeId(input.assigneeAgentId, "agent");
+    if (!state.agents.has(assigneeAgentId)) {
+      throw new OrchestraControlPlaneError("unknown_agent", `agent ${assigneeAgentId} is not registered`);
+    }
+    if (input.dreamId && !state.dreams.has(input.dreamId)) {
+      throw new OrchestraControlPlaneError("unknown_dream", `dream ${input.dreamId} does not exist`);
+    }
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      taskId,
+      dreamId: input.dreamId,
+      assigneeAgentId,
+      status: normalizeStatus(input.status ?? "queued"),
+      input: redactObject(input.input ?? {}),
+      requiredScopes: [...new Set(asArray(input.requiredScopes))].sort(),
+      createdAt: input.createdAt ?? now().toISOString(),
+      updatedAt: input.updatedAt ?? now().toISOString(),
+    };
+    state.tasks.set(taskId, record);
+    audit({ actorId: assigneeAgentId, eventType: "task.created", resourceRef: taskId, outcome: "allow", summary: "task created" });
+    return record;
+  }
+
+  function createRun(input) {
+    const runId = normalizeId(input.runId, "run");
+    const task = state.tasks.get(input.taskId);
+    if (!task) throw new OrchestraControlPlaneError("unknown_task", `task ${input.taskId} does not exist`);
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      runId,
+      taskId: task.taskId,
+      agentId: normalizeId(input.agentId ?? task.assigneeAgentId, "agent"),
+      status: normalizeStatus(input.status ?? "running"),
+      attempt: Number.isInteger(input.attempt) ? input.attempt : nextAttempt(task.taskId),
+      startedAt: input.startedAt ?? now().toISOString(),
+      completedAt: input.completedAt,
+      metadata: redactObject(input.metadata ?? {}),
+    };
+    state.runs.set(runId, record);
+    audit({ actorId: record.agentId, eventType: "run.created", resourceRef: runId, outcome: "allow", summary: "run created" });
+    return record;
+  }
+
+  function recordRunEvent(input) {
+    const run = state.runs.get(input.runId);
+    if (!run) throw new OrchestraControlPlaneError("unknown_run", `run ${input.runId} does not exist`);
+    const sequence = Number.isInteger(input.sequence) ? input.sequence : [...state.runEvents.values()].filter((event) => event.runId === run.runId).length;
+    const eventId = normalizeId(input.eventId ?? makeId("evt", run.runId, sequence), "evt");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      eventId,
+      runId: run.runId,
+      eventType: requireString(input.eventType, "eventType"),
+      sequence,
+      payload: redactObject(input.payload ?? {}),
+      recordedAt: input.recordedAt ?? now().toISOString(),
+    };
+    state.runEvents.set(eventId, record);
+    audit({ actorId: run.agentId, eventType: "run.event_recorded", resourceRef: eventId, outcome: "allow", summary: record.eventType });
+    return record;
+  }
+
+  function recordToolCall(input) {
+    const run = state.runs.get(input.runId);
+    if (!run) throw new OrchestraControlPlaneError("unknown_run", `run ${input.runId} does not exist`);
+    const toolCallId = normalizeId(input.toolCallId, "tool");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      toolCallId,
+      runId: run.runId,
+      toolName: requireString(input.toolName, "toolName"),
+      risk: RISK.has(input.risk) ? input.risk : "unknown",
+      status: input.status ?? "requested",
+      inputRef: normalizeResourceRef(input.inputRef ?? `artifact://${toolCallId}/input`),
+      outputRef: input.outputRef ? normalizeResourceRef(input.outputRef) : undefined,
+      createdAt: input.createdAt ?? now().toISOString(),
+    };
+    state.toolCalls.set(toolCallId, record);
+    audit({ actorId: run.agentId, eventType: "tool_call.recorded", resourceRef: toolCallId, outcome: "allow", summary: "tool call recorded" });
+    return record;
+  }
+
+  function writeArtifact(input) {
+    const run = state.runs.get(input.runId);
+    if (!run) throw new OrchestraControlPlaneError("unknown_run", `run ${input.runId} does not exist`);
+    const artifactId = normalizeId(input.artifactId, "art");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      artifactId,
+      runId: run.runId,
+      kind: input.kind ?? "evidence",
+      uri: normalizeResourceRef(input.uri ?? `memory://${artifactId}`),
+      provenance: redactObject(input.provenance ?? {}),
+      createdAt: input.createdAt ?? now().toISOString(),
+    };
+    state.artifacts.set(artifactId, record);
+    audit({ actorId: run.agentId, eventType: "artifact.written", resourceRef: artifactId, outcome: "allow", summary: "artifact written" });
+    return record;
+  }
+
+  function grantScope(input) {
+    const grantId = normalizeId(input.grantId, "grant");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      grantId,
+      subjectActorId: normalizeId(input.subjectActorId, "actor"),
+      scope: requireString(input.scope, "scope"),
+      resourceRef: normalizeResourceRef(input.resourceRef ?? "*"),
+      status: input.status ?? "active",
+      expiresAt: input.expiresAt,
+      createdAt: input.createdAt ?? now().toISOString(),
+    };
+    state.grants.set(grantId, record);
+    audit({ actorId: record.subjectActorId, eventType: "grant.created", resourceRef: grantId, outcome: "allow", summary: "grant created" });
+    return record;
+  }
+
+  function requestApproval(input) {
+    const approvalId = normalizeId(input.approvalId, "approval");
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      approvalId,
+      runId: normalizeId(input.runId, "run"),
+      actionId: normalizeId(input.actionId, "act"),
+      requestedBy: normalizeId(input.requestedBy, "actor"),
+      decidedBy: undefined,
+      status: "requested",
+      requiredScopes: [...new Set(asArray(input.requiredScopes))].sort(),
+      requestedAt: input.requestedAt ?? now().toISOString(),
+      decidedAt: undefined,
+      expiresAt: input.expiresAt,
+    };
+    state.approvals.set(approvalId, record);
+    audit({ actorId: record.requestedBy, eventType: "approval.requested", resourceRef: approvalId, outcome: "needs_approval", summary: "approval requested" });
+    return record;
+  }
+
+  function decideApproval(input) {
+    const approval = state.approvals.get(input.approvalId);
+    if (!approval) throw new OrchestraControlPlaneError("unknown_approval", `approval ${input.approvalId} does not exist`);
+    const status = input.status ?? "approved";
+    if (!APPROVAL_STATUS.has(status) || status === "requested") {
+      throw new OrchestraControlPlaneError("invalid_approval_status", `unsupported approval decision ${status}`);
+    }
+    const record = {
+      ...approval,
+      status,
+      decidedBy: normalizeId(input.decidedBy, "actor"),
+      decidedAt: input.decidedAt ?? now().toISOString(),
+    };
+    state.approvals.set(record.approvalId, record);
+    audit({ actorId: record.decidedBy, eventType: "approval.decided", resourceRef: record.approvalId, outcome: status, summary: `approval ${status}` });
+    return record;
+  }
+
+  function writeSecret(input) {
+    const secretId = normalizeId(input.secretId, "secret");
+    const sealed = vault.seal(requireString(input.value, "value"), {
+      secretId,
+      aad: input.name ?? secretId,
+    });
+    const record = {
+      schemaVersion: ORCHESTRA_SCHEMA_VERSION,
+      secretId,
+      name: input.name ?? secretId,
+      keyVersionId: sealed.keyVersionId,
+      sealedPayload: sealed,
+      metadata: redactObject(input.metadata ?? {}),
+      createdAt: input.createdAt ?? now().toISOString(),
+      rotatedAt: undefined,
+    };
+    state.secrets.set(secretId, record);
+    syncKeyVersions();
+    audit({ actorId: normalizeId(input.actorId, "actor"), eventType: "secret.sealed", resourceRef: secretId, outcome: "allow", summary: "secret sealed at rest" });
+    return publicSecretRecord(record);
+  }
+
+  function readSecret(input) {
+    const secretId = normalizeId(input.secretId, "secret");
+    const actorId = normalizeId(input.actorId, "actor");
+    const secret = state.secrets.get(secretId);
+    if (!secret) throw new OrchestraControlPlaneError("unknown_secret", `secret ${secretId} does not exist`);
+    if (!hasGrant(actorId, `secret:read:${secretId}`, `secret://${secretId}`)) {
+      audit({ actorId, eventType: "secret.read_denied", resourceRef: secretId, outcome: "deny", summary: "secret read denied" });
+      throw new OrchestraControlPlaneError("missing_secret_grant", `actor ${actorId} lacks secret read grant`);
+    }
+    const value = vault.open(secret.sealedPayload, { aad: secret.name });
+    audit({ actorId, eventType: "secret.read", resourceRef: secretId, outcome: "allow", summary: "secret read allowed; value omitted" });
+    return { secretId, name: secret.name, value };
+  }
+
+  function rotateVaultKey(input = {}) {
+    const rotation = vault.rotateKey({ retiredAt: input.retiredAt ?? now().toISOString() });
+    syncKeyVersions();
+    for (const secret of state.secrets.values()) {
+      const plaintext = vault.open(secret.sealedPayload, { aad: secret.name });
+      const sealedPayload = vault.seal(plaintext, { secretId: secret.secretId, aad: secret.name });
+      state.secrets.set(secret.secretId, {
+        ...secret,
+        keyVersionId: sealedPayload.keyVersionId,
+        sealedPayload,
+        rotatedAt: input.rotatedAt ?? now().toISOString(),
+      });
+    }
+    syncKeyVersions();
+    audit({ actorId: normalizeId(input.actorId ?? "actor_system", "actor"), eventType: "vault.rotated", resourceRef: rotation.activeKeyVersionId, outcome: "allow", summary: "vault key rotated and secrets resealed" });
+    return rotation;
+  }
+
+  function snapshot() {
+    return {
+      ...Object.fromEntries(Object.entries(state).map(([key, map]) => [key, [...map.values()].map((record) => (key === "secrets" ? publicSecretRecord(record) : structuredClone(record)))])),
+      oauthTokens: oauth.listTokenRecords(),
+    };
+  }
+
+  function inspect() {
+    return {
+      package: ORCHESTRA_PACKAGE,
+      attribution: DISPATCH_SOURCE_ATTRIBUTION,
+      schema: {
+        version: ORCHESTRA_SCHEMA_VERSION,
+        tableCount: ORCHESTRA_TABLE_NAMES.length,
+        tables: ORCHESTRA_TABLE_NAMES,
+        drizzleDialects: Object.keys(ORCHESTRA_DRIZZLE_SCHEMA.dialects),
+      },
+      capabilities: {
+        controlPlane: true,
+        dispatchState: true,
+        postgresSchema: true,
+        libsqlSchema: true,
+        sealedSecretsAtRest: true,
+        keyRotation: true,
+        approvals: true,
+        grants: true,
+        auditLogs: true,
+        oauthScopedRead: true,
+        oauthTokensEncryptedAtRest: true,
+        oauthAudienceBinding: true,
+        oauthRotationAndRevocation: true,
+        linkTokenJoseVerification: true,
+        secretContextIsolation: true,
+        hostedRuntime: false,
+      },
+      migrationFixtures: ORCHESTRA_MIGRATION_FIXTURES,
+    };
+  }
+
+  function syncKeyVersions() {
+    for (const record of vault.keyVersionRecords()) {
+      state.secretKeyVersions.set(record.keyVersionId, record);
+    }
+  }
+
+  function hasGrant(actorId, scope, resourceRef) {
+    const currentTime = now().getTime();
+    return [...state.grants.values()].some((grant) => {
+      if (grant.subjectActorId !== actorId || grant.status !== "active") return false;
+      if (grant.expiresAt && Date.parse(grant.expiresAt) <= currentTime) return false;
+      const scopeMatches = grant.scope === scope || grant.scope === "secret:read:*" || grant.scope === "*";
+      const resourceMatches = grant.resourceRef === resourceRef || grant.resourceRef === "*" || grant.resourceRef === `secret://${resourceRef.replace(/^secret:\/\//, "")}`;
+      return scopeMatches && resourceMatches;
+    });
+  }
+
+  function nextAttempt(taskId) {
+    return [...state.runs.values()].filter((run) => run.taskId === taskId).length + 1;
+  }
+
+  return {
+    inspect,
+    snapshot,
+    upsertDirectoryActor,
+    registerAgent,
+    createDream,
+    createTask,
+    createRun,
+    recordRunEvent,
+    recordToolCall,
+    writeArtifact,
+    grantScope,
+    requestApproval,
+    decideApproval,
+    writeSecret,
+    readSecret,
+    rotateVaultKey,
+    oauth,
+    audit,
+  };
+}
+
+export function createSealedSecretVault(options = {}) {
+  const now = options.now ?? (() => new Date());
+  const keys = new Map();
+  let activeKeyVersionId = options.activeKeyVersionId ?? "key_2026_06_22_0001";
+  keys.set(activeKeyVersionId, {
+    keyVersionId: activeKeyVersionId,
+    key: normalizeKey(options.key),
+    status: "active",
+    algorithm: "AES-256-GCM",
+    createdAt: now().toISOString(),
+    retiredAt: undefined,
+    rotationPolicy: options.rotationPolicy ?? { maxAgeDays: 90, rotateBeforePublish: true },
+  });
+
+  function seal(value, input = {}) {
+    const keyRecord = keys.get(activeKeyVersionId);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", keyRecord.key, iv);
+    const aad = Buffer.from(input.aad ?? input.secretId ?? "secret", "utf8");
+    cipher.setAAD(aad);
+    const ciphertext = Buffer.concat([cipher.update(String(value), "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+      schemaVersion: "2026-06-22.sealed-secret-envelope",
+      algorithm: keyRecord.algorithm,
+      keyVersionId: keyRecord.keyVersionId,
+      iv: iv.toString("base64url"),
+      ciphertext: ciphertext.toString("base64url"),
+      tag: tag.toString("base64url"),
+      aadHash: sha256(aad),
+    };
+  }
+
+  function open(envelope, input = {}) {
+    const keyRecord = keys.get(envelope?.keyVersionId);
+    if (!keyRecord) throw new OrchestraControlPlaneError("unknown_key_version", `key version ${envelope?.keyVersionId} is not available`);
+    const decipher = createDecipheriv("aes-256-gcm", keyRecord.key, Buffer.from(envelope.iv, "base64url"));
+    const aad = Buffer.from(input.aad ?? "secret", "utf8");
+    if (sha256(aad) !== envelope.aadHash) {
+      throw new OrchestraControlPlaneError("secret_aad_mismatch", "sealed secret associated data does not match");
+    }
+    decipher.setAAD(aad);
+    decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+    return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64url")), decipher.final()]).toString("utf8");
+  }
+
+  function rotateKey(input = {}) {
+    const previousKeyVersionId = activeKeyVersionId;
+    const previous = keys.get(previousKeyVersionId);
+    keys.set(previousKeyVersionId, {
+      ...previous,
+      status: "retired",
+      retiredAt: input.retiredAt ?? now().toISOString(),
+    });
+    activeKeyVersionId = input.keyVersionId ?? makeId("key", now().toISOString(), keys.size + 1);
+    keys.set(activeKeyVersionId, {
+      keyVersionId: activeKeyVersionId,
+      key: normalizeKey(input.key),
+      status: "active",
+      algorithm: "AES-256-GCM",
+      createdAt: now().toISOString(),
+      retiredAt: undefined,
+      rotationPolicy: input.rotationPolicy ?? previous.rotationPolicy,
+    });
+    return { previousKeyVersionId, activeKeyVersionId };
+  }
+
+  function keyVersionRecords() {
+    return [...keys.values()].map(({ key, ...record }) => structuredClone(record));
+  }
+
+  return {
+    seal,
+    open,
+    rotateKey,
+    keyVersionRecords,
+    get activeKeyVersionId() {
+      return activeKeyVersionId;
+    },
+  };
+}
+
+function publicSecretRecord(record) {
+  return {
+    ...structuredClone(record),
+    sealedPayload: {
+      ...record.sealedPayload,
+      ciphertext: record.sealedPayload.ciphertext,
+    },
+  };
+}
+
+function normalizeKey(value) {
+  if (Buffer.isBuffer(value) && value.length === 32) return value;
+  if (typeof value === "string" && Buffer.byteLength(value) >= 32) {
+    return createHash("sha256").update(value).digest();
+  }
+  return randomBytes(32);
+}
+
+function normalizeIdBody(value) {
+  const source = String(value).toLowerCase();
+  let out = "";
+  let prevUnderscore = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const code = source.charCodeAt(index);
+    const isLowerAlpha = code >= 97 && code <= 122;
+    const isDigit = code >= 48 && code <= 57;
+    const isSafe = isLowerAlpha || isDigit || char === "_" || char === "-";
+    if (isSafe) {
+      out += char;
+      prevUnderscore = false;
+      continue;
+    }
+    if (!prevUnderscore) {
+      out += "_";
+      prevUnderscore = true;
+    }
+  }
+
+  let start = 0;
+  while (start < out.length && out[start] === "_") {
+    start += 1;
+  }
+  let end = out.length;
+  while (end > start && out[end - 1] === "_") {
+    end -= 1;
+  }
+  return out.slice(start, end);
+}
+
+function stripLeadingAlphaPrefix(value) {
+  const text = String(value);
+  let index = 0;
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if (code < 97 || code > 122) break;
+    index += 1;
+  }
+  if (index > 0 && text[index] === "_") {
+    return text.slice(index + 1);
+  }
+  return text;
+}
+
+function normalizeId(value, prefix) {
+  const normalized = normalizeIdBody(value ?? `${prefix}_unknown`);
+  const withPrefix = normalized.startsWith(`${prefix}_`) ? normalized : `${prefix}_${stripLeadingAlphaPrefix(normalized)}`;
+  if (!isHarnessIdentifier(withPrefix)) {
+    throw new OrchestraControlPlaneError("invalid_identifier", `${prefix} identifier is invalid`);
+  }
+  return withPrefix.slice(0, 96);
+}
+
+function normalizeStatus(value) {
+  if (STATUS.has(value)) return value;
+  throw new OrchestraControlPlaneError("invalid_status", `unsupported status ${value}`);
+}
+
+function normalizeResourceRef(value) {
+  const resource = String(value ?? "");
+  if (resource === "*" || isSupportedUri(resource)) return resource;
+  if (isHarnessIdentifier(resource)) return resource;
+  throw new OrchestraControlPlaneError("invalid_resource_ref", "resource ref must be a URI, wildcard, or harness id");
+}
+
+function isHarnessIdentifier(value) {
+  if (typeof value !== "string" || value.length < 3) return false;
+  const separatorIndex = value.indexOf("_");
+  if (separatorIndex <= 0 || separatorIndex === value.length - 1) return false;
+  if (!isLowerAlpha(value[0])) return false;
+  if (!isLowerAlpha(value[separatorIndex + 1]) && !isDigit(value[separatorIndex + 1])) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (index === separatorIndex) continue;
+    if (isLowerAlpha(character) || isDigit(character)) continue;
+    if (index > separatorIndex && (character === "_" || character === "-")) continue;
+    return false;
+  }
+  return true;
+}
+
+function isSupportedUri(value) {
+  if (value.length > 2048) return false;
+  try {
+    const url = new URL(value);
+    return isUriScheme(url.protocol.slice(0, -1));
+  } catch {
+    return false;
+  }
+}
+
+function isUriScheme(value) {
+  if (value.length === 0 || !isLowerAlpha(value[0])) return false;
+  for (let index = 1; index < value.length; index += 1) {
+    const character = value[index];
+    if (isLowerAlpha(character) || isDigit(character) || character === "+" || character === "." || character === "-") continue;
+    return false;
+  }
+  return true;
+}
+
+function isLowerAlpha(character) {
+  return character >= "a" && character <= "z";
+}
+
+function isDigit(character) {
+  return character >= "0" && character <= "9";
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new OrchestraControlPlaneError("invalid_input", `${field} is required`);
+  }
+  return value;
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function redactObject(value) {
+  if (Array.isArray(value)) return value.map(redactObject);
+  if (value === null || typeof value !== "object") {
+    return typeof value === "string" ? redactSummary(value) : value;
+  }
+  const secretRefRecord = isSecretRefRecord(value);
+  return Object.fromEntries(Object.entries(value).map(([key, child], index) => {
+    const outputKey = containsSensitiveString(key) ? `[redacted-key-${index}]` : key;
+    return [
+      outputKey,
+      isSecretRefField(key) || (secretRefRecord && SECRET_REF_SCHEMA_FIELDS.has(key))
+        ? redactObject(child)
+        : isSensitiveField(key) ? REDACTED : redactObject(child),
+    ];
+  }));
+}
+
+function redactSummary(value) {
+  const normalized = normalizeSecurityText(String(value));
+  const structured = redactStructuredText(normalized);
+  return structured
+    .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]+/g, `$1 ${REDACTED}`)
+    .replace(/(["']?\b(api[_-]?key|tokenValue|token|password|credential|clientSecret|plaintext)\b["']?)(\s*[:=]\s*)("[^"]*"|'[^']*'|[^,\s;}]+)/gi, (_match, key, _name, separator) => {
+      const assignment = separator.includes(":") ? separator : "=";
+      return `${key}${assignment}${assignment.includes(":") ? JSON.stringify(REDACTED) : REDACTED}`;
+    })
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted-email]")
+    .replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[redacted-ssn]")
+    .replace(/(?<!\d)(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g, "[redacted-phone]");
+}
+
+function redactStructuredText(value) {
+  const decoded = decodeSensitiveString(value);
+  if (decoded && containsSensitiveString(decoded)) return REDACTED;
+
+  const exact = parseJsonAst(value);
+  if (exact !== undefined) return stringifyRedactedAst(value, exact);
+
+  return redactEmbeddedJsonAsts(value);
+}
+
+function stringifyRedactedAst(source, ast) {
+  const redacted = redactObject(ast);
+  const before = JSON.stringify(ast);
+  const after = JSON.stringify(redacted);
+  return before === after ? source : after;
+}
+
+function redactEmbeddedJsonAsts(value) {
+  if (value.length > STRUCTURED_REDACTION_LIMIT) return value;
+  let output = "";
+  let cursor = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const open = value[index];
+    if (open !== "{" && open !== "[") continue;
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let end = index; end < value.length; end += 1) {
+      const char = value[end];
+      if (inString) {
+        if (escaped) {
+          escaped = false;
+        } else if (char === "\\") {
+          escaped = true;
+        } else if (char === "\"") {
+          inString = false;
+        }
+        continue;
+      }
+      if (char === "\"") {
+        inString = true;
+        continue;
+      }
+      if (char === open) depth += 1;
+      if (char === close) depth -= 1;
+      if (depth !== 0) continue;
+      const fragment = value.slice(index, end + 1);
+      const ast = parseJsonAst(fragment);
+      if (ast !== undefined) {
+        output += value.slice(cursor, index) + stringifyRedactedAst(fragment, ast);
+        cursor = end + 1;
+        index = end;
+      }
+      break;
+    }
+  }
+  return cursor === 0 ? value : output + value.slice(cursor);
+}
+
+function parseJsonAst(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > STRUCTURED_REDACTION_LIMIT) return undefined;
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+function decodeSensitiveString(value) {
+  const compact = value.trim();
+  if (compact.length < 16 || compact.length > 8192 || compact.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(compact)) return undefined;
+  try {
+    const decoded = Buffer.from(compact, "base64").toString("utf8");
+    if (!decoded || /[\u0000-\u0008\u000E-\u001F]/.test(decoded)) return undefined;
+    return decoded;
+  } catch {
+    return undefined;
+  }
+}
+
+function containsSensitiveString(value) {
+  const normalized = normalizeSecurityText(value);
+  return /["']?\b(api[_-]?key|tokenValue|token|password|credential|clientSecret|plaintext|authorization|cookie|session)\b["']?\s*[:=]/i.test(normalized)
+    || /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i.test(normalized)
+    || /\b\d{3}-\d{2}-\d{4}\b/.test(normalized)
+    || /(?<!\d)(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/.test(normalized)
+    || containsSensitiveJson(normalized);
+}
+
+function containsSensitiveJson(value) {
+  const ast = parseJsonAst(value);
+  return ast !== undefined && hasSensitiveJsonKey(ast);
+}
+
+function hasSensitiveJsonKey(value) {
+  if (Array.isArray(value)) return value.some(hasSensitiveJsonKey);
+  if (value === null || typeof value !== "object") return false;
+  return Object.entries(value).some(([key, child]) => isSensitiveField(key) || hasSensitiveJsonKey(child));
+}
+
+function isSensitiveField(key) {
+  const normalized = normalizeFieldKey(key);
+  return SENSITIVE_FIELD_PATTERN.test(key)
+    || SENSITIVE_TOKEN_FIELD_PATTERN.test(key)
+    || SENSITIVE_FIELD_PATTERN.test(normalized)
+    || SENSITIVE_TOKEN_FIELD_PATTERN.test(normalized);
+}
+
+function isSecretRefField(key) {
+  const normalized = normalizeFieldKey(key);
+  return normalized === "secretref" || normalized === "secretrefs";
+}
+
+function isSecretRefRecord(value) {
+  return value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && value.schemaVersion === "2026-06-09"
+    && typeof value.secretId === "string"
+    && /^sec_[a-z0-9][a-z0-9_-]*$/.test(value.secretId)
+    && typeof value.provider === "string"
+    && typeof value.scope === "string"
+    && typeof value.redactionClass === "string"
+    && typeof value.createdAt === "string";
+}
+
+function normalizeFieldKey(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function normalizeSecurityText(value) {
+  return String(value).normalize("NFKC").replace(SECURITY_FORMAT_CHARS, "");
+}
+
+function adaptOAuthAuditEvent(event = {}) {
+  const actorId = event.ownerId ?? event.requesterOwnerId ?? "actor_system";
+  const summaryParts = [event.eventType];
+  if (event.audience) summaryParts.push(`audience=${event.audience}`);
+  if (event.resource) summaryParts.push(`resource=${event.resource}`);
+  if (event.reason) summaryParts.push(`reason=${event.reason}`);
+  return {
+    actorId,
+    eventType: event.eventType ?? "oauth.token.event",
+    resourceRef: event.tokenId ?? "resource_unknown",
+    outcome: event.outcome ?? "recorded",
+    summary: summaryParts.filter(Boolean).join(" "),
+    metadata: {
+      ownerId: event.ownerId,
+      orgId: event.orgId,
+      requesterOwnerId: event.requesterOwnerId,
+      requesterOrgId: event.requesterOrgId,
+    },
+  };
+}
+
+function makeId(prefix, ...parts) {
+  const body = parts
+    .filter((part) => part !== undefined && part !== null)
+    .join("_")
+    .toLowerCase()
+    .replace(/^(run|task|agent|actor|dream|evt|tool|art|grant|approval|secret|aud|key|act)_/g, "")
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 72);
+  return `${prefix}_${body || "record"}`;
+}
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}