enigma-memory 0.1.9 → 0.1.10

package/docs/developer-ecosystem.md

@@ -60,7 +60,7 @@ The example app prints ids, counts, roots, and verification status only. It does
 
 ## CLI and CI loop
 
-The CI example installs Node 24, installs the published `enigma-memory@0.1.9` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.10` package, runs:
 
 ```sh
 npx --yes --package enigma-memory enigma setup --overwrite

package/docs/hosted-cloud-product.md

@@ -10,6 +10,7 @@ The source package now has pure contract builders and validators in `packages/ho
 - tenant records;
 - hosted vault records;
 - API key metadata records;
+- API key lifecycle packets for issue/rotate/revoke/audit readiness;
 - usage billing records;
 - dashboard summaries;
 - backup drill records;
@@ -18,7 +19,7 @@ The source package now has pure contract builders and validators in `packages/ho
 
 These functions are contract and validation code only. They do not call an auth provider, billing provider, cloud deployment, KMS, backup target, support desk, status page, SIEM, or model provider. They are safe to import as package code because they do not start servers, read user files, mutate deployment state, publish packages, or contact external accounts.
 
-The lifecycle packet public API is `buildCustomerLifecyclePacket(input)` and `validateCustomerLifecyclePacket(packet)` under `enigma-memory/hosted-cloud`; the script command below emits the same schema for release evidence.
+The lifecycle packet public APIs are `buildCustomerLifecyclePacket(input)` / `validateCustomerLifecyclePacket(packet)` and `buildApiKeyLifecyclePacket(input)` / `validateApiKeyLifecyclePacket(packet)` under `enigma-memory/hosted-cloud`; the script commands below emit the same schemas for release evidence.
 
 The validators enforce hosted-cloud boundaries:
 
@@ -27,10 +28,11 @@ The validators enforce hosted-cloud boundaries:
 - raw memory, plaintext prompts, provider responses, transcripts, credential-looking values, token values, private keys, and API key secret material are rejected;
 - financial outcome claims, token ROI/profit claims, provider-side deletion claims, and model-forgetting claims are rejected;
 - API key contracts store identifiers, fingerprints, scopes, rotation refs, and timestamps only, not key material;
+- API key lifecycle packets store issue/rotate/revoke/audit evidence refs, event refs, fingerprints, opaque subjects, readiness status, and operator approval refs only; they reject raw key material, provider payloads, customer memory, plaintext prompts, credentials, ROI claims, provider-deletion claims, and model-forgetting claims;
 - hosted vault contracts are opaque-record and plaintext-minimized contracts only;
 - billing records remain contract records until an external billing provider invoice flow is wired.
 
-Individual surface builders emit `readiness.contract_ready: true`, `readiness.integration_kind: "contract_validator_only"`, and `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval. A customer lifecycle packet may only mark `hosted_cloud_sellable: true` when every lifecycle surface has a provided evidence ref and an explicit operator go-live approval ref is supplied; the packet remains evidence validation, not live hosted SaaS or provider wiring.
+Individual surface builders emit `readiness.contract_ready: true`, `readiness.integration_kind: "contract_validator_only"`, and `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval. A customer lifecycle packet may only mark `hosted_cloud_sellable: true` when every lifecycle surface has a provided evidence ref and an explicit operator go-live approval ref is supplied; the packet remains evidence validation, not live hosted SaaS or provider wiring. An API key lifecycle packet keeps `customer_api_keys_live:false` by default and can become live-ready only when every required issue/rotate/revoke/audit evidence ref is provided and an operator approval ref is supplied. That live-ready state is still evidence validation only: it does not issue a customer API key, create a secret, call an auth provider, rotate/revoke a provider credential, or prove provider-side deletion.
 
 ## Externally blocked before hosted cloud can be sold
 
@@ -53,6 +55,14 @@ A `provided` operator evidence ref means the contract can point to external evid
 
 The lifecycle packet records lifecycle phases, required surfaces, external blockers, missing evidence refs, no-secret/no-plaintext guarantees, and the sellability gate. Missing surfaces, blocked evidence refs, or absent operator go-live approval keep `hosted_cloud_sellable:false`.
 
+## API key lifecycle packet
+
+`npm run production:hosted-api-key -- --tenant <id> --subject <opaque-subject-ref> --operation <issue|rotate|revoke|audit> --out <file>` builds `enigma.hosted_cloud.api_key_lifecycle_packet.v1` readiness evidence for one customer API key lifecycle operation. Operators may pass repeatable `--evidence-ref <phase=status:ref>` values for the phases required by that operation, plus `--operator-approval-ref <ref>` when a reviewed operator approval exists.
+
+The command writes public-safe validation evidence only. It must not receive or print raw API keys, bearer tokens, credentials, provider response bodies, plaintext prompts, raw memory, customer content, financial ROI claims, provider deletion claims, or model forgetting claims. It creates no hosted account, customer API key, provider secret, KMS key, rotation job, revocation job, audit export, invoice, support ticket, Cloudflare resource, provider resource, or deployment.
+
+The packet records lifecycle events, required evidence refs, missing evidence refs, malformed operation blockers, the operator approval ref, readiness status, `customer_api_keys_live`, and no-secret/no-plaintext guarantees. Missing evidence refs, blocked evidence refs, malformed operation surfaces, or absent operator approval keep `customer_api_keys_live:false`.
+
 ## Non-claims
 
 Hosted cloud collateral must not say or imply:

package/docs/sdk-api.md

@@ -1,6 +1,6 @@
 # SDK and API guide
 
-This guide covers the public package imports for `enigma-memory@0.1.9`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+This guide covers the public package imports for `enigma-memory@0.1.10`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, settlement artifacts, and hosted-cloud contract packets are package-level developer surfaces. They are not evidence of hosted Enigma cloud, live customer API key issuance, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
 
 ## Install and import style
 
@@ -157,6 +157,27 @@ const job = createPermissionlessMemoryJob({
 });
 ```
 
+### `enigma-memory/hosted-cloud`
+
+The hosted-cloud module emits public-safe contract/readiness evidence only. Customer API key lifecycle packets model issue, rotate, revoke, and audit readiness with evidence refs, opaque subject refs, fingerprints, missing-evidence refs, readiness status, and operator approval refs. They never contain raw key material, provider payloads, plaintext prompts, raw memory, credentials, ROI claims, provider deletion claims, or model forgetting claims.
+
+```js
+import {
+  buildApiKeyLifecyclePacket,
+  validateApiKeyLifecyclePacket,
+} from 'enigma-memory/hosted-cloud';
+
+const packet = buildApiKeyLifecyclePacket({
+  tenant_id: 'tenant-alpha',
+  subject_ref: 'subject-ref-alpha',
+  environment: 'production',
+  operation: 'audit',
+});
+const valid = validateApiKeyLifecyclePacket(packet);
+```
+
+`customer_api_keys_live` stays `false` unless the issue/rotate/revoke/audit evidence refs are complete and an operator approval ref is supplied. Even then, the packet is readiness evidence validation only; it does not issue a key, create a secret, call KMS or auth providers, rotate or revoke a provider credential, or prove provider-side deletion.
+
 ## Verifying exported proof
 
 Package consumers should verify exported bundles through the CLI or MCP verifier rather than importing source-only verifier internals. Treat full bundles as private unless you have reviewed and removed local import key material before sharing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",
@@ -85,6 +85,7 @@
     "scripts/collect-hosted-backend-live-evidence.mjs",
     "scripts/build-hosted-probe-worker.mjs",
     "scripts/build-hosted-customer-lifecycle.mjs",
+    "scripts/build-hosted-api-key-lifecycle.mjs",
     "scripts/build-edge-backend-workers.mjs",
     "scripts/validate-cloudflare-worker-inspect.mjs",
     "scripts/validate-production-manifests.mjs",
@@ -177,6 +178,7 @@
     "production:edge-live": "node scripts/collect-edge-backend-bootstrap-evidence.mjs",
     "production:ref-draft": "node scripts/build-hosted-ref-draft.mjs",
     "production:hosted-customer": "node scripts/build-hosted-customer-lifecycle.mjs",
+    "production:hosted-api-key": "node scripts/build-hosted-api-key-lifecycle.mjs",
     "production:storage-bootstrap": "node scripts/cloudflare-storage-bootstrap.mjs",
     "production:worker-inspect": "node scripts/validate-cloudflare-worker-inspect.mjs",
     "production:cloudflare-credentials": "node scripts/validate-cloudflare-credentials.mjs",

package/packages/hosted-cloud/src/index.js

@@ -9,6 +9,7 @@ export const HOSTED_CLOUD_DASHBOARD_SCHEMA = 'enigma.hosted_cloud.dashboard_summ
 export const HOSTED_CLOUD_BACKUP_DRILL_SCHEMA = 'enigma.hosted_cloud.backup_drill.v1';
 export const HOSTED_CLOUD_INCIDENT_SLA_SCHEMA = 'enigma.hosted_cloud.incident_sla_refs.v1';
 export const HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PACKET_SCHEMA = 'enigma.hosted_cloud.customer_lifecycle_packet.v1';
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA = 'enigma.hosted_cloud.api_key_lifecycle_packet.v1';
 
 export const HOSTED_CLOUD_EXTERNAL_BLOCKERS = Object.freeze([
   'auth_provider',
@@ -63,6 +64,23 @@ const CUSTOMER_LIFECYCLE_CONTRACT_PHASES = Object.freeze([
   'incident_sla',
 ]);
 const CUSTOMER_LIFECYCLE_REQUIRED_EVIDENCE_PHASES = Object.freeze(HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PHASES.filter((phase) => phase !== 'operator_go_live'));
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS = Object.freeze(['issue', 'rotate', 'revoke', 'audit']);
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_PHASES = Object.freeze([
+  'current_key_metadata',
+  'next_key_metadata',
+  'revoked_key_metadata',
+  'issue_policy',
+  'rotation_policy',
+  'revocation_policy',
+  'audit_log',
+]);
+const API_KEY_LIFECYCLE_OPERATION_PHASES = Object.freeze({
+  issue: Object.freeze(['next_key_metadata', 'issue_policy', 'audit_log']),
+  rotate: Object.freeze(['current_key_metadata', 'next_key_metadata', 'rotation_policy', 'audit_log']),
+  revoke: Object.freeze(['current_key_metadata', 'revoked_key_metadata', 'revocation_policy', 'audit_log']),
+  audit: Object.freeze(['current_key_metadata', 'audit_log']),
+});
+const API_KEY_LIFECYCLE_KEY_SLOTS = Object.freeze(['current', 'next', 'revoked']);
 const CUSTOMER_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
   account: 'Hosted account contract evidence is not provided.',
   tenant: 'Hosted tenant contract evidence is not provided.',
@@ -78,8 +96,19 @@ const CUSTOMER_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
   security_review: 'Hosted security review evidence is not provided.',
   operator_go_live: 'Explicit operator go-live approval is not provided.',
 });
+const API_KEY_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
+  current_key_metadata: 'Current hosted API key metadata evidence is not provided.',
+  next_key_metadata: 'Next hosted API key metadata evidence is not provided.',
+  revoked_key_metadata: 'Revoked hosted API key metadata evidence is not provided.',
+  issue_policy: 'Hosted API key issue policy evidence is not provided.',
+  rotation_policy: 'Hosted API key rotation policy evidence is not provided.',
+  revocation_policy: 'Hosted API key revocation policy evidence is not provided.',
+  audit_log: 'Hosted API key lifecycle audit evidence is not provided.',
+  operator_approval: 'Explicit public-safe operator API key lifecycle approval is not provided.',
+});
+const API_KEY_SECRET_MATERIAL_KEY_RE = /(?:^|_)(?:raw_?api_?key|raw_?key|plaintext_?api_?key|plain_text_?api_?key|plaintext_?key|plain_text_?key|api_?key_?value|key_?value|key_?material|secret_?key|key_?secret|value)(?:$|_)/iu;
 const FORBIDDEN_KEY_RE = /(?:^|_)(?:raw_?memory|plaintext|plain_text|prompt|prompts|completion|completions|message_body|transcript|conversation|provider_?response|response_?body|credential|credentials|secret|password|private_?key|bearer|access_token|refresh_token|token_value|api_key_value|api_secret|token_?roi|token_?profit|roi_claim|profit_claim|provider_?deletion|provider_?erasure|model_?forgetting|model_?erasure)(?:$|_)/iu;
-const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|raw memory|private prompt|provider response|full transcript|decrypted memory)/iu;
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|\b(?:raw memory|plaintext prompts?|plain text prompts?|private prompts?|provider responses?|full transcript|decrypted memory|credentials?|secrets?|passwords?|private keys?|api key secret|api secrets?|access tokens?|refresh tokens?|token values?|credential material)\b)/iu;
 const FORBIDDEN_CLAIM_RE = /(?:token\s+(?:roi|profit|return|investment|price)|(?:roi|profit|return)\s+(?:from|on)\s+token|guaranteed\s+(?:savings|profit|return)|provider(?:-side|\s+side)?\s+(?:deletion|erasure)|model\s+(?:forgetting|forgot|erasure)|makes?\s+models?\s+forget|deleted\s+from\s+every\s+provider)/iu;
 
 function isPlainObject(value) {
@@ -880,7 +909,7 @@ function validateCustomerLifecycleEvidenceRefs(requiredEvidenceRefs) {
 function validateCustomerLifecycleContracts(contracts) {
   if (!isPlainObject(contracts)) throw new TypeError('contracts must be present');
   for (const phase of CUSTOMER_LIFECYCLE_CONTRACT_PHASES) {
-    if (!Object.prototype.hasOwnProperty.call(contracts, phase)) throw new TypeError(`contracts.${phase} must be present`);
+    if (!Object.prototype.hasOwnProperty.call(contracts, phase)) throw new TypeError(`contracts.${phase} must be present; missing_surface_refs must match contracts`);
     const contract = contracts[phase];
     if (contract === null) continue;
     if (!isPlainObject(contract)) throw new TypeError(`contracts.${phase} must be an object or null`);
@@ -982,3 +1011,392 @@ export function validateCustomerLifecyclePacket(packet) {
   validateCustomerLifecycleSafetyGuarantees(packet.guarantees ?? packet.public_safety_guarantees);
   return true;
 }
+
+function assertNoApiKeySecretMaterial(value, path = 'api_key_lifecycle') {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoApiKeySecretMaterial(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const allowedBoundaryKey = key === 'key_material_boundary' || key === 'key_material_in_contract' || key === 'api_key_material_absent';
+    const keyMetadataContext = /(?:^|\.)(?:current|next|revoked|current_key|currentKey|current_api_key|currentApiKey|next_key|nextKey|next_api_key|nextApiKey|revoked_key|revokedKey|revoked_api_key|revokedApiKey|key_contracts\.(?:current|next|revoked)|keyContracts\.(?:current|next|revoked)|key_metadata_contracts\.(?:current|next|revoked)|keyMetadataContracts\.(?:current|next|revoked)|contracts\.(?:current|next|revoked))$/u.test(path);
+    const bareSecretKey = key === 'api_key' || key === 'apiKey' || (keyMetadataContext && key === 'key');
+    if (!allowedBoundaryKey && (bareSecretKey || API_KEY_SECRET_MATERIAL_KEY_RE.test(key))) {
+      throw new TypeError(`${path}.${key} is not allowed in API key lifecycle packets`);
+    }
+    assertNoApiKeySecretMaterial(child, `${path}.${key}`);
+  }
+}
+
+function apiKeyLifecycleOperation(input) {
+  const operation = requiredString(input.operation, 'operation');
+  if (!HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS.includes(operation)) {
+    throw new TypeError(`operation must be one of ${HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS.join(', ')}`);
+  }
+  return operation;
+}
+
+function apiKeyLifecycleRequiredPhases(operation) {
+  return API_KEY_LIFECYCLE_OPERATION_PHASES[operation];
+}
+
+function apiKeyLifecycleSlotAliases(slot) {
+  switch (slot) {
+    case 'current':
+      return ['current', 'current_key', 'currentKey', 'current_api_key', 'currentApiKey', 'current_key_contract', 'currentKeyContract', 'current_api_key_contract', 'currentApiKeyContract'];
+    case 'next':
+      return ['next', 'next_key', 'nextKey', 'next_api_key', 'nextApiKey', 'next_key_contract', 'nextKeyContract', 'next_api_key_contract', 'nextApiKeyContract'];
+    case 'revoked':
+      return ['revoked', 'revoked_key', 'revokedKey', 'revoked_api_key', 'revokedApiKey', 'revoked_key_contract', 'revokedKeyContract', 'revoked_api_key_contract', 'revokedApiKeyContract'];
+    default:
+      throw new TypeError(`unknown API key lifecycle slot: ${slot}`);
+  }
+}
+
+function apiKeyLifecycleContractSource(input, slot) {
+  const aliases = apiKeyLifecycleSlotAliases(slot);
+  const contractCollections = [
+    input.key_contracts,
+    input.keyContracts,
+    input.key_metadata_contracts,
+    input.keyMetadataContracts,
+    input.contracts,
+  ];
+  for (const collection of contractCollections) {
+    if (!isPlainObject(collection)) continue;
+    for (const alias of aliases) {
+      if (collection[alias] !== undefined) return collection[alias];
+    }
+  }
+  for (const alias of aliases) {
+    if (input[alias] !== undefined) return input[alias];
+  }
+  return undefined;
+}
+
+function validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, name) {
+  if (contract.tenant_id !== tenantId) throw new TypeError(`${name}.tenant_id must match packet tenant_id`);
+  if (contract.subject_ref !== subjectRef) throw new TypeError(`${name}.subject_ref must match packet subject_ref`);
+}
+
+function buildOrValidateApiKeyLifecycleContract(slot, source, tenantId, subjectRef, generatedAt) {
+  if (source === undefined || source === null) return null;
+  if (!isPlainObject(source)) throw new TypeError(`key_contracts.${slot} must be an object`);
+  const name = `key_contracts.${slot}`;
+  if (source.schema === HOSTED_CLOUD_API_KEY_SCHEMA) {
+    validateApiKeyContract(source);
+    validateApiKeyLifecycleContractTenantSubject(source, tenantId, subjectRef, name);
+    return source;
+  }
+  const contract = buildApiKeyContract({
+    ...source,
+    tenant_id: source.tenant_id ?? source.tenantId ?? tenantId,
+    subject_ref: source.subject_ref ?? source.subjectRef ?? subjectRef,
+    generated_at: source.generated_at ?? source.generatedAt ?? generatedAt,
+  });
+  validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, name);
+  return contract;
+}
+
+function apiKeyLifecycleContractsFrom(input, tenantId, subjectRef, generatedAt) {
+  return Object.fromEntries(API_KEY_LIFECYCLE_KEY_SLOTS.map((slot) => [
+    slot,
+    buildOrValidateApiKeyLifecycleContract(slot, apiKeyLifecycleContractSource(input, slot), tenantId, subjectRef, generatedAt),
+  ]));
+}
+
+function explicitApiKeyLifecycleEvidenceRefs(input) {
+  const refs = input.required_evidence_refs ?? input.requiredEvidenceRefs ?? input.api_key_evidence_refs ?? input.apiKeyEvidenceRefs ?? input.lifecycle_evidence_refs ?? input.lifecycleEvidenceRefs ?? input.evidence_refs ?? input.evidenceRefs;
+  if (refs === undefined || refs === null) return {};
+  if (!isPlainObject(refs)) throw new TypeError('required_evidence_refs must be an object');
+  return refs;
+}
+
+function apiKeyLifecycleEvidenceRefFor(phase, value) {
+  const fallback = { ref: `blocked:${phase}`, status: BLOCKED, blocker: API_KEY_LIFECYCLE_BLOCKER_LABELS[phase] };
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'string') return { ref: requirePublicSafeLifecycleRef(value, `required_evidence_refs.${phase}`), status: PROVIDED };
+  if (!isPlainObject(value)) throw new TypeError(`required_evidence_refs.${phase} must be a string or object`);
+  const status = stringOrDefault(value.status, PROVIDED);
+  if (!EVIDENCE_STATUSES.has(status)) throw new TypeError(`required_evidence_refs.${phase}.status is invalid`);
+  const ref = status === PROVIDED
+    ? requirePublicSafeLifecycleRef(value.ref, `required_evidence_refs.${phase}.ref`)
+    : requiredString(value.ref, `required_evidence_refs.${phase}.ref`);
+  assertNoForbiddenPayload(ref, `required_evidence_refs.${phase}.ref`);
+  assertNoApiKeySecretMaterial(ref, `required_evidence_refs.${phase}.ref`);
+  const evidence = { ref, status };
+  const owner = optionalString(value.owner, `required_evidence_refs.${phase}.owner`);
+  const blocker = optionalString(value.blocker, `required_evidence_refs.${phase}.blocker`);
+  const contractSchema = optionalString(value.contract_schema, `required_evidence_refs.${phase}.contract_schema`);
+  const contractId = optionalString(value.contract_id, `required_evidence_refs.${phase}.contract_id`);
+  if (owner) evidence.owner = owner;
+  if (contractSchema) evidence.contract_schema = contractSchema;
+  if (contractId) evidence.contract_id = contractId;
+  if (status === BLOCKED) evidence.blocker = blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase];
+  return evidence;
+}
+
+function apiKeyLifecycleSlotForPhase(phase) {
+  switch (phase) {
+    case 'current_key_metadata':
+      return 'current';
+    case 'next_key_metadata':
+      return 'next';
+    case 'revoked_key_metadata':
+      return 'revoked';
+    default:
+      return null;
+  }
+}
+
+function apiKeyLifecycleContractEvidenceRef(phase, contract) {
+  if (!contract) return apiKeyLifecycleEvidenceRefFor(phase, undefined);
+  return {
+    ref: requiredString(contract.contract_hash, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.contract_hash`),
+    status: PROVIDED,
+    contract_schema: requiredString(contract.schema, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.schema`),
+    contract_id: requiredString(contract.api_key_id, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.api_key_id`),
+  };
+}
+
+function apiKeyLifecycleEvidenceRefsFrom(input, operation, keyContracts) {
+  const explicitRefs = explicitApiKeyLifecycleEvidenceRefs(input);
+  const requiredPhases = apiKeyLifecycleRequiredPhases(operation);
+  const evidenceRefs = {};
+  for (const phase of requiredPhases) {
+    const slot = apiKeyLifecycleSlotForPhase(phase);
+    evidenceRefs[phase] = explicitRefs[phase] === undefined && slot !== null
+      ? apiKeyLifecycleContractEvidenceRef(phase, keyContracts[slot])
+      : apiKeyLifecycleEvidenceRefFor(phase, explicitRefs[phase]);
+  }
+  return evidenceRefs;
+}
+
+function apiKeyLifecycleOperatorApprovalRefFromInput(input) {
+  const value = input.operator_approval_ref ?? input.operatorApprovalRef ?? input.operator_go_live_ref ?? input.operatorGoLiveRef;
+  if (value === undefined || value === null) return null;
+  return requirePublicSafeLifecycleRef(value, 'operator_approval_ref');
+}
+
+function apiKeyLifecycleOperatorApprovalRefFromPacket(packet) {
+  if (!Object.prototype.hasOwnProperty.call(packet, 'operator_approval_ref')) throw new TypeError('operator_approval_ref must be present');
+  if (packet.operator_approval_ref === null) return null;
+  return requirePublicSafeLifecycleRef(packet.operator_approval_ref, 'operator_approval_ref');
+}
+
+function missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation) {
+  return apiKeyLifecycleRequiredPhases(operation)
+    .filter((phase) => requiredEvidenceRefs[phase].status !== PROVIDED)
+    .map((phase) => ({
+      key: phase,
+      ref: requiredEvidenceRefs[phase].ref,
+      blocker: requiredEvidenceRefs[phase].blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase],
+    }));
+}
+
+function apiKeyLifecycleExternalBlockers(requiredEvidenceRefs, operation, operatorApprovalRef) {
+  const blockers = missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation);
+  if (operatorApprovalRef === null) {
+    blockers.push({
+      key: 'operator_approval',
+      ref: 'blocked:operator_approval',
+      blocker: API_KEY_LIFECYCLE_BLOCKER_LABELS.operator_approval,
+    });
+  }
+  return blockers;
+}
+
+function apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef) {
+  const missingEvidenceRefs = missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation);
+  const externalLifecycleBlockers = apiKeyLifecycleExternalBlockers(requiredEvidenceRefs, operation, operatorApprovalRef);
+  const evidenceApproved = missingEvidenceRefs.length === 0 && operatorApprovalRef !== null;
+  return {
+    ...HOSTED_CLOUD_CONTRACT_READY,
+    operation,
+    status: evidenceApproved ? 'operator_approved_api_key_lifecycle_evidence' : 'blocked_api_key_lifecycle_evidence_or_operator_approval',
+    evidence_validation_only: true,
+    no_provider_wiring: true,
+    actual_key_issuance: false,
+    lifecycle_evidence_complete: missingEvidenceRefs.length === 0,
+    operator_approval_provided: operatorApprovalRef !== null,
+    external_wiring_ready: externalLifecycleBlockers.length === 0,
+    customer_api_keys_live: evidenceApproved,
+    live_readiness_gate: evidenceApproved ? 'evidence_complete_operator_approved' : 'blocked_until_lifecycle_evidence_and_operator_approval',
+    external_blockers: externalLifecycleBlockers,
+    missing_evidence_refs: missingEvidenceRefs,
+  };
+}
+
+function apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs) {
+  const requiredPhases = apiKeyLifecycleRequiredPhases(operation);
+  return Object.fromEntries(API_KEY_LIFECYCLE_KEY_SLOTS.map((slot) => {
+    const phase = `${slot}_key_metadata`;
+    return [slot, requiredPhases.includes(phase) ? requiredEvidenceRefs[phase] : null];
+  }));
+}
+
+function apiKeyLifecycleEvents(operation, requiredEvidenceRefs, keyContracts) {
+  return apiKeyLifecycleRequiredPhases(operation).map((phase) => {
+    const evidence = requiredEvidenceRefs[phase];
+    const event = {
+      operation,
+      phase,
+      evidence_ref: evidence.ref,
+      evidence_status: evidence.status,
+      ready: evidence.status === PROVIDED,
+    };
+    if (evidence.status === BLOCKED) event.blocker = evidence.blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase];
+    const slot = apiKeyLifecycleSlotForPhase(phase);
+    if (slot !== null && keyContracts[slot]) {
+      event.key_slot = slot;
+      event.contract_schema = keyContracts[slot].schema;
+      event.contract_id = keyContracts[slot].api_key_id;
+      event.contract_hash = keyContracts[slot].contract_hash;
+    }
+    return event;
+  });
+}
+
+function apiKeyLifecycleSafetyGuarantees() {
+  return {
+    opaque_reference_only: true,
+    customer_content_absent: true,
+    sensitive_text_absent: true,
+    auth_material_absent: true,
+    api_key_material_absent: true,
+    provider_payloads_absent: true,
+    provider_wiring_absent: true,
+    evidence_validation_only: true,
+    actual_key_issuance_absent: true,
+    financial_outcome_claim_absent: true,
+    remote_erasure_claim_absent: true,
+  };
+}
+
+function validateApiKeyLifecycleSafetyGuarantees(guarantees) {
+  if (!isPlainObject(guarantees)) throw new TypeError('public_safety_guarantees must be present');
+  requiredTrue(guarantees.opaque_reference_only, 'public_safety_guarantees.opaque_reference_only');
+  requiredTrue(guarantees.customer_content_absent, 'public_safety_guarantees.customer_content_absent');
+  requiredTrue(guarantees.sensitive_text_absent, 'public_safety_guarantees.sensitive_text_absent');
+  requiredTrue(guarantees.auth_material_absent, 'public_safety_guarantees.auth_material_absent');
+  requiredTrue(guarantees.api_key_material_absent, 'public_safety_guarantees.api_key_material_absent');
+  requiredTrue(guarantees.provider_payloads_absent, 'public_safety_guarantees.provider_payloads_absent');
+  requiredTrue(guarantees.provider_wiring_absent, 'public_safety_guarantees.provider_wiring_absent');
+  requiredTrue(guarantees.evidence_validation_only, 'public_safety_guarantees.evidence_validation_only');
+  requiredTrue(guarantees.actual_key_issuance_absent, 'public_safety_guarantees.actual_key_issuance_absent');
+  requiredTrue(guarantees.financial_outcome_claim_absent, 'public_safety_guarantees.financial_outcome_claim_absent');
+  requiredTrue(guarantees.remote_erasure_claim_absent, 'public_safety_guarantees.remote_erasure_claim_absent');
+}
+
+function validateApiKeyLifecycleContracts(keyContracts, tenantId, subjectRef) {
+  if (!isPlainObject(keyContracts)) throw new TypeError('key_contracts must be present');
+  for (const slot of API_KEY_LIFECYCLE_KEY_SLOTS) {
+    if (!Object.prototype.hasOwnProperty.call(keyContracts, slot)) throw new TypeError(`key_contracts.${slot} must be present`);
+    const contract = keyContracts[slot];
+    if (contract === null) continue;
+    if (!isPlainObject(contract)) throw new TypeError(`key_contracts.${slot} must be an object or null`);
+    validateApiKeyContract(contract);
+    validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, `key_contracts.${slot}`);
+  }
+}
+
+function validateApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation) {
+  if (!isPlainObject(requiredEvidenceRefs)) throw new TypeError('required_evidence_refs must be present');
+  const expectedPhases = apiKeyLifecycleRequiredPhases(operation);
+  for (const phase of Object.keys(requiredEvidenceRefs)) {
+    if (!expectedPhases.includes(phase)) throw new TypeError(`required_evidence_refs.${phase} is not required for ${operation}`);
+  }
+  const normalized = {};
+  for (const phase of expectedPhases) {
+    if (!Object.prototype.hasOwnProperty.call(requiredEvidenceRefs, phase)) throw new TypeError(`required_evidence_refs.${phase} must be present`);
+    normalized[phase] = apiKeyLifecycleEvidenceRefFor(phase, requiredEvidenceRefs[phase]);
+  }
+  return normalized;
+}
+
+function assertSameLifecycleObject(actual, expected, name) {
+  if (!isPlainObject(actual)) throw new TypeError(`${name} must be an object`);
+  if (JSON.stringify(canonicalize(actual)) !== JSON.stringify(canonicalize(expected))) throw new TypeError(`${name} must match API key lifecycle evidence`);
+}
+
+function validateApiKeyLifecycleReadiness(readiness, expected) {
+  if (!isPlainObject(readiness)) throw new TypeError('readiness must be present');
+  requiredTrue(readiness.contract_ready, 'readiness.contract_ready');
+  if (readiness.integration_kind !== HOSTED_CLOUD_CONTRACT_READY.integration_kind) throw new TypeError('readiness.integration_kind must remain contract_validator_only');
+  requiredTrue(readiness.no_external_provider_calls, 'readiness.no_external_provider_calls');
+  if (readiness.operation !== expected.operation) throw new TypeError('readiness.operation must match operation');
+  if (readiness.status !== expected.status) throw new TypeError('readiness.status must match API key lifecycle evidence and operator approval');
+  requiredTrue(readiness.evidence_validation_only, 'readiness.evidence_validation_only');
+  requiredTrue(readiness.no_provider_wiring, 'readiness.no_provider_wiring');
+  requiredFalse(readiness.actual_key_issuance, 'readiness.actual_key_issuance');
+  if (readiness.lifecycle_evidence_complete !== expected.lifecycle_evidence_complete) throw new TypeError('readiness.lifecycle_evidence_complete must match required_evidence_refs');
+  if (readiness.operator_approval_provided !== expected.operator_approval_provided) throw new TypeError('readiness.operator_approval_provided must match operator_approval_ref');
+  if (readiness.external_wiring_ready !== expected.external_wiring_ready) throw new TypeError('readiness.external_wiring_ready must match blockers');
+  if (readiness.customer_api_keys_live !== expected.customer_api_keys_live) throw new TypeError('readiness.customer_api_keys_live must match lifecycle evidence and operator approval');
+  if (readiness.live_readiness_gate !== expected.live_readiness_gate) throw new TypeError('readiness.live_readiness_gate must match lifecycle evidence and operator approval');
+  assertSameLifecycleArray(readiness.external_blockers, expected.external_blockers, 'readiness.external_blockers');
+  assertSameLifecycleArray(readiness.missing_evidence_refs, expected.missing_evidence_refs, 'readiness.missing_evidence_refs');
+}
+
+export function buildApiKeyLifecyclePacket(input = {}) {
+  if (!isPlainObject(input)) throw new TypeError('buildApiKeyLifecyclePacket requires an options object');
+  assertNoForbiddenPayload(input, 'input');
+  assertNoApiKeySecretMaterial(input, 'input');
+  const tenantId = requiredString(input.tenant_id ?? input.tenantId, 'tenant_id');
+  const subjectRef = requiredString(input.subject_ref ?? input.subjectRef, 'subject_ref');
+  const generatedAt = isoTimestamp(input.generated_at ?? input.generatedAt, 'generated_at');
+  const operation = apiKeyLifecycleOperation(input);
+  const keyContracts = apiKeyLifecycleContractsFrom(input, tenantId, subjectRef, generatedAt);
+  const requiredEvidenceRefs = apiKeyLifecycleEvidenceRefsFrom(input, operation, keyContracts);
+  const operatorApprovalRef = apiKeyLifecycleOperatorApprovalRefFromInput(input);
+  const readiness = apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef);
+  const body = {
+    schema: HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA,
+    packet_id: stringOrDefault(input.packet_id ?? input.packetId, undefined),
+    generated_at: generatedAt,
+    tenant_id: tenantId,
+    subject_ref: subjectRef,
+    operation,
+    key_contracts: keyContracts,
+    key_metadata_refs: apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs),
+    lifecycle_events: apiKeyLifecycleEvents(operation, requiredEvidenceRefs, keyContracts),
+    required_evidence_refs: requiredEvidenceRefs,
+    external_blockers: readiness.external_blockers,
+    missing_evidence_refs: readiness.missing_evidence_refs,
+    operator_approval_ref: operatorApprovalRef,
+    readiness,
+    customer_api_keys_live: readiness.customer_api_keys_live,
+    guarantees: apiKeyLifecycleSafetyGuarantees(),
+    public_safety_guarantees: apiKeyLifecycleSafetyGuarantees(),
+  };
+  const packet = withContractIdentity(body, 'hcaklp', 'packet_id');
+  validateApiKeyLifecyclePacket(packet);
+  return packet;
+}
+
+export function validateApiKeyLifecyclePacket(packet) {
+  if (!isPlainObject(packet)) throw new TypeError('packet must be an object');
+  assertNoForbiddenPayload(packet, 'packet');
+  assertNoApiKeySecretMaterial(packet, 'packet');
+  if (packet.schema !== HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA) throw new TypeError(`schema must be ${HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA}`);
+  requiredString(packet.packet_id, 'packet_id');
+  isoTimestamp(packet.generated_at, 'generated_at');
+  requiredString(packet.contract_hash, 'contract_hash');
+  const tenantId = requiredString(packet.tenant_id, 'tenant_id');
+  const subjectRef = requiredString(packet.subject_ref, 'subject_ref');
+  const operation = apiKeyLifecycleOperation(packet);
+  validateApiKeyLifecycleContracts(packet.key_contracts, tenantId, subjectRef);
+  const requiredEvidenceRefs = validateApiKeyLifecycleEvidenceRefs(packet.required_evidence_refs, operation);
+  const operatorApprovalRef = apiKeyLifecycleOperatorApprovalRefFromPacket(packet);
+  const expectedReadiness = apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef);
+  assertSameLifecycleObject(packet.key_metadata_refs, apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs), 'key_metadata_refs');
+  assertSameLifecycleArray(packet.lifecycle_events, apiKeyLifecycleEvents(operation, requiredEvidenceRefs, packet.key_contracts), 'lifecycle_events');
+  assertSameLifecycleArray(packet.external_blockers, expectedReadiness.external_blockers, 'external_blockers');
+  assertSameLifecycleArray(packet.missing_evidence_refs, expectedReadiness.missing_evidence_refs, 'missing_evidence_refs');
+  validateApiKeyLifecycleReadiness(packet.readiness, expectedReadiness);
+  if (packet.customer_api_keys_live !== expectedReadiness.customer_api_keys_live) throw new TypeError('customer_api_keys_live must match readiness.customer_api_keys_live');
+  validateApiKeyLifecycleSafetyGuarantees(packet.guarantees ?? packet.public_safety_guarantees);
+  validateApiKeyLifecycleSafetyGuarantees(packet.public_safety_guarantees ?? packet.guarantees);
+  return true;
+}

package/packages/mcp-server/src/index.js

@@ -17,7 +17,7 @@ import {
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.9' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.10' });
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,

package/scripts/build-hosted-api-key-lifecycle.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS,
+  HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA,
+  HOSTED_CLOUD_API_KEY_LIFECYCLE_PHASES,
+  buildApiKeyLifecyclePacket,
+  validateApiKeyLifecyclePacket,
+} from '../packages/hosted-cloud/src/index.js';
+
+export const HOSTED_API_KEY_LIFECYCLE_PACKET_SCHEMA = HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA;
+export const HOSTED_API_KEY_LIFECYCLE_RELEASE_TARGET = '0.1.10';
+
+const PROVIDED = 'provided';
+const BLOCKED = 'blocked_external_dependency';
+const ALLOWED_OPERATIONS = new Set(HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS);
+const ALLOWED_STATUSES = new Set([PROVIDED, BLOCKED, 'blocked_missing_evidence']);
+const STATUS_ALIASES = Object.freeze({
+  blocked: BLOCKED,
+  missing: BLOCKED,
+  blocked_missing_evidence: BLOCKED,
+});
+
+const OPERATION_EVIDENCE_KEYS = Object.freeze({
+  issue: Object.freeze(['next_key_metadata', 'issue_policy', 'audit_log']),
+  rotate: Object.freeze(['current_key_metadata', 'next_key_metadata', 'rotation_policy', 'audit_log']),
+  revoke: Object.freeze(['current_key_metadata', 'revoked_key_metadata', 'revocation_policy', 'audit_log']),
+  audit: Object.freeze(['current_key_metadata', 'audit_log']),
+});
+
+const ALL_EVIDENCE_KEYS = Object.freeze(HOSTED_CLOUD_API_KEY_LIFECYCLE_PHASES);
+const ALL_EVIDENCE_KEY_SET = new Set(ALL_EVIDENCE_KEYS);
+
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|\b(?:raw[\s_-]*memory|plaintext[\s_-]*prompts?|plain[\s_-]*text[\s_-]*prompts?|private[\s_-]*prompts?|provider[\s_-]*responses?|full[\s_-]*transcript|decrypted[\s_-]*memory|credentials?|secrets?|passwords?|private[\s_-]*keys?|api[\s_-]*key[\s_-]*(?:secret|material|value)|api[\s_-]*secrets?|access[\s_-]*tokens?|refresh[\s_-]*tokens?|token[\s_-]*values?|credential[\s_-]*material)\b)/iu;
+const FORBIDDEN_CLAIM_RE = /(?:token[\s_-]*(?:roi|profit|return|investment|price)|financial[\s_-]*roi|roi[\s_-]*claim|(?:roi|profit|return)[\s_-]*(?:from|on)[\s_-]*token|guaranteed[\s_-]*(?:savings|profit|return)|provider(?:-side|[\s_-]*side)?[\s_-]*(?:deletion|erasure)|model[\s_-]*(?:forgetting|forgot|erasure)|makes?[\s_-]*models?[\s_-]*forget|deleted[\s_-]*from[\s_-]*every[\s_-]*provider)/iu;
+const ABSOLUTE_LOCAL_PATH_RE = /^(?:[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|tmp|var|etc|mnt|Volumes)\b)/u;
+
+function assertPublicSafeString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} must be a non-empty public ref`);
+  const normalized = value.trim();
+  if (SECRET_VALUE_RE.test(normalized) || FORBIDDEN_CLAIM_RE.test(normalized) || ABSOLUTE_LOCAL_PATH_RE.test(normalized)) {
+    throw new Error(`${label} contains non-public hosted-cloud material`);
+  }
+  return normalized;
+}
+
+function assertRelativeOutFile(value) {
+  const out = assertPublicSafeString(value, 'output file');
+  if (isAbsolute(out) || ABSOLUTE_LOCAL_PATH_RE.test(out)) throw new Error('output file must be a relative path');
+  return out;
+}
+
+function normalizeStatus(status) {
+  const normalized = STATUS_ALIASES[status] ?? status;
+  if (!ALLOWED_STATUSES.has(normalized)) throw new Error('evidence status must be provided, blocked_external_dependency, or blocked_missing_evidence');
+  return normalized;
+}
+
+function defaultEvidenceRef(key) {
+  return {
+    status: BLOCKED,
+    ref: `blocked:${key}`,
+    blocker: `Public-safe ${key.replaceAll('_', ' ')} evidence is not provided.`,
+  };
+}
+
+function normalizeEvidenceRecord(key, record) {
+  const status = normalizeStatus(record.status ?? PROVIDED);
+  const ref = assertPublicSafeString(record.ref, 'evidence ref');
+  const output = { status, ref };
+  if (status !== PROVIDED) output.blocker = record.blocker ?? defaultEvidenceRef(key).blocker;
+  return output;
+}
+
+export function parseEvidenceRef(value) {
+  const raw = assertPublicSafeString(value, 'evidence ref argument');
+  const equalsIndex = raw.indexOf('=');
+  if (equalsIndex <= 0 || equalsIndex === raw.length - 1) throw new Error('evidence refs must use key=status:ref');
+  const key = raw.slice(0, equalsIndex).trim();
+  if (!ALL_EVIDENCE_KEY_SET.has(key)) throw new Error(`evidence key must be one of: ${ALL_EVIDENCE_KEYS.join(', ')}`);
+  const body = raw.slice(equalsIndex + 1).trim();
+  const colonIndex = body.indexOf(':');
+  if (colonIndex > 0) {
+    const possibleStatus = body.slice(0, colonIndex);
+    if (ALLOWED_STATUSES.has(possibleStatus) || STATUS_ALIASES[possibleStatus]) {
+      return { key, ...normalizeEvidenceRecord(key, { status: possibleStatus, ref: body.slice(colonIndex + 1) }) };
+    }
+  }
+  return { key, ...normalizeEvidenceRecord(key, { status: PROVIDED, ref: body }) };
+}
+
+function evidenceRefsFor(operation, records = []) {
+  const requiredKeys = OPERATION_EVIDENCE_KEYS[operation];
+  const refs = Object.fromEntries(requiredKeys.map((key) => [key, defaultEvidenceRef(key)]));
+  for (const rawRecord of records) {
+    const record = typeof rawRecord === 'string' ? parseEvidenceRef(rawRecord) : rawRecord;
+    if (!requiredKeys.includes(record.key)) throw new Error(`evidence key ${record.key} is not required for ${operation}`);
+    refs[record.key] = normalizeEvidenceRecord(record.key, record);
+  }
+  return refs;
+}
+
+function providedRef(evidenceRefs, key) {
+  const evidence = evidenceRefs[key];
+  return evidence?.status === PROVIDED ? evidence.ref : null;
+}
+
+function fingerprintFromRef(ref, label) {
+  if (!ref) return `blocked:${label}`;
+  return `sha256:${createHash('sha256').update(`${label}\0${ref}`).digest('hex')}`;
+}
+
+function scopeList(scopes = []) {
+  if (!Array.isArray(scopes) || scopes.length === 0) return ['blocked:scope'];
+  return Object.freeze(scopes.map((scope, index) => assertPublicSafeString(scope, `scope ${index + 1}`)));
+}
+
+
+function keyInputsFor({ operation, tenantId, subjectRef, scopes, generatedAt, evidenceRefs }) {
+  const base = { tenant_id: tenantId, subject_ref: subjectRef, scopes, issued_at: generatedAt };
+  const currentRef = providedRef(evidenceRefs, 'current_key_metadata');
+  const nextRef = providedRef(evidenceRefs, 'next_key_metadata');
+  const revokedRef = providedRef(evidenceRefs, 'revoked_key_metadata');
+  const issueRef = providedRef(evidenceRefs, 'issue_policy') ?? nextRef;
+  const rotationRef = providedRef(evidenceRefs, 'rotation_policy') ?? currentRef;
+  const revokeRef = providedRef(evidenceRefs, 'revocation_policy') ?? revokedRef;
+  const inputs = {};
+
+  if (operation === 'issue') {
+    if (nextRef) inputs.next_key = { ...base, key_fingerprint: fingerprintFromRef(nextRef, 'issue_next_key'), rotation_ref: issueRef ?? 'blocked:issue_policy' };
+    return inputs;
+  }
+  if (operation === 'rotate') {
+    if (currentRef) inputs.current_key = { ...base, key_fingerprint: fingerprintFromRef(currentRef, 'rotate_current_key'), rotation_ref: rotationRef ?? 'blocked:rotation_policy' };
+    if (nextRef) inputs.next_key = { ...base, key_fingerprint: fingerprintFromRef(nextRef, 'rotate_next_key'), rotation_ref: rotationRef ?? 'blocked:rotation_policy' };
+    return inputs;
+  }
+  if (operation === 'revoke') {
+    if (currentRef) inputs.current_key = { ...base, key_fingerprint: fingerprintFromRef(currentRef, 'revoke_current_key'), rotation_ref: revokeRef ?? 'blocked:revocation_policy' };
+    if (revokedRef) inputs.revoked_key = { ...base, key_fingerprint: fingerprintFromRef(revokedRef, 'revoke_key'), rotation_ref: revokeRef ?? 'blocked:revocation_policy' };
+    return inputs;
+  }
+  if (currentRef) inputs.current_key = { ...base, key_fingerprint: fingerprintFromRef(currentRef, 'audit_key'), rotation_ref: providedRef(evidenceRefs, 'audit_log') ?? 'blocked:audit_log' };
+  return inputs;
+}
+
+function scriptBoundary() {
+  return {
+    public_safe_packet_only: true,
+    evidence_validation_only: true,
+    provider_wiring_performed: false,
+    deploys_or_calls_external_providers: false,
+    sensitive_material_written: false,
+    customer_api_key_material_written: false,
+    customer_content_written: false,
+  };
+}
+
+export function buildHostedApiKeyLifecyclePacket(options = {}) {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const tenantId = assertPublicSafeString(options.tenant ?? options.tenantId ?? 'blocked:tenant', 'tenant');
+  const subjectRef = assertPublicSafeString(options.subject ?? options.subjectRef ?? 'blocked:subject', 'subject');
+  const operation = options.operation ?? 'audit';
+  if (!ALLOWED_OPERATIONS.has(operation)) throw new Error('operation must be issue, rotate, revoke, or audit');
+  const scopes = scopeList(options.scopes ?? options.scope ?? []);
+  const evidenceRefs = evidenceRefsFor(operation, options.evidenceRefs ?? []);
+  const operatorApprovalRef = options.operatorApprovalRef === undefined
+    ? null
+    : assertPublicSafeString(options.operatorApprovalRef, 'operator approval ref');
+  const packet = buildApiKeyLifecyclePacket({
+    tenant_id: tenantId,
+    subject_ref: subjectRef,
+    generated_at: generatedAt,
+    operation,
+    ...keyInputsFor({ operation, tenantId, subjectRef, scopes, generatedAt, evidenceRefs }),
+    required_evidence_refs: evidenceRefs,
+    operator_approval_ref: operatorApprovalRef,
+  });
+  validateApiKeyLifecyclePacket(packet);
+  return {
+    ...packet,
+    schema: HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA,
+    release_target: HOSTED_API_KEY_LIFECYCLE_RELEASE_TARGET,
+    tenant_id: tenantId,
+    subject_ref: subjectRef,
+    operation,
+    scopes,
+    boundary: scriptBoundary(),
+  };
+}
+
+export function parseArgs(argv) {
+  const args = {
+    tenant: undefined,
+    subject: undefined,
+    operation: undefined,
+    scopes: [],
+    evidenceRefs: [],
+    operatorApprovalRef: undefined,
+    out: undefined,
+    help: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      continue;
+    }
+    const readValue = (name) => {
+      index += 1;
+      if (index >= argv.length || argv[index].startsWith('--')) throw new Error(`${name} requires a value`);
+      return argv[index];
+    };
+    if (arg === '--tenant') args.tenant = assertPublicSafeString(readValue('--tenant'), 'tenant');
+    else if (arg === '--subject') args.subject = assertPublicSafeString(readValue('--subject'), 'subject');
+    else if (arg === '--operation') args.operation = assertPublicSafeString(readValue('--operation'), 'operation');
+    else if (arg === '--scope') args.scopes.push(assertPublicSafeString(readValue('--scope'), `scope ${args.scopes.length + 1}`));
+    else if (arg === '--evidence-ref') args.evidenceRefs.push(parseEvidenceRef(readValue('--evidence-ref')));
+    else if (arg === '--operator-approval-ref') args.operatorApprovalRef = assertPublicSafeString(readValue('--operator-approval-ref'), 'operator approval ref');
+    else if (arg === '--out') args.out = assertRelativeOutFile(readValue('--out'));
+    else throw new Error('unknown option; use --help');
+  }
+  return args;
+}
+
+export function usage() {
+  return `Usage: node scripts/build-hosted-api-key-lifecycle.mjs [options]
+
+Build a public-safe hosted API key lifecycle evidence packet. The script validates metadata, fingerprints, and opaque refs only; it does not issue keys, call providers, create accounts, revoke provider credentials, or write secret material.
+
+Options:
+  --tenant <id>                         Tenant id. Defaults to blocked:tenant.
+  --subject <ref>                       Subject ref. Defaults to blocked:subject.
+  --operation <issue|rotate|revoke|audit>
+                                         Lifecycle operation. Defaults to audit.
+  --scope <scope>                       Repeatable public-safe scope. Defaults to blocked:scope.
+  --evidence-ref <key=status:ref>       Repeatable evidence ref. key=<ref> implies provided.
+                                         Status: provided, blocked_external_dependency, blocked_missing_evidence.
+                                         Keys: ${ALL_EVIDENCE_KEYS.join(', ')}
+  --operator-approval-ref <ref>         Operator approval evidence ref.
+  --out <file>                          Also write the packet JSON to a relative file path.
+  --help                                Show this help.
+`;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(usage());
+    return 0;
+  }
+  const packet = buildHostedApiKeyLifecyclePacket(args);
+  const json = `${JSON.stringify(packet, null, 2)}\n`;
+  if (args.out) {
+    try {
+      await writeFile(args.out, json, 'utf8');
+    } catch {
+      throw new Error('failed to write API key lifecycle packet output');
+    }
+  }
+  process.stdout.write(json);
+  return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main().catch((error) => {
+    process.stderr.write(`Error: ${error?.message ?? 'failed to build API key lifecycle packet'}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/build-hosted-customer-lifecycle.mjs

@@ -25,10 +25,10 @@ import {
   buildUserAccountContract,
   buildCustomerLifecyclePacket,
   validateCustomerLifecyclePacket,
-} from '../packages/hosted-cloud/src/index.js';
+} from 'enigma-memory/hosted-cloud';
 
 export const HOSTED_CUSTOMER_LIFECYCLE_PACKET_SCHEMA = HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PACKET_SCHEMA;
-export const HOSTED_CUSTOMER_LIFECYCLE_RELEASE_TARGET = '0.1.9';
+export const HOSTED_CUSTOMER_LIFECYCLE_RELEASE_TARGET = '0.1.10';
 
 const PROVIDED = 'provided';
 const BLOCKED_MISSING = 'blocked_missing_evidence';
@@ -181,8 +181,11 @@ export function parseEvidenceRef(value) {
 function normalizeEvidenceRefs(records = []) {
   const refs = Object.fromEntries(HOSTED_CUSTOMER_LIFECYCLE_EVIDENCE_KEYS.map((key) => [key, defaultEvidenceRef(key)]));
   for (const rawRecord of records) {
-    const record = typeof rawRecord === 'string' ? parseEvidenceRef(rawRecord) : rawRecord;
-    refs[record.key] = normalizeEvidenceRecord(record.key, record);
+    const parsedRecord = typeof rawRecord === 'string' ? parseEvidenceRef(rawRecord) : rawRecord;
+    const key = EVIDENCE_KEY_ALIASES[parsedRecord.key] ?? parsedRecord.key;
+    if (!HOSTED_CUSTOMER_LIFECYCLE_EVIDENCE_KEYS.includes(key)) throw new Error(`evidence key must be one of: ${HOSTED_CUSTOMER_LIFECYCLE_EVIDENCE_KEYS.join(', ')}`);
+    const record = { ...parsedRecord, key };
+    refs[key] = normalizeEvidenceRecord(key, record);
   }
   return refs;
 }
@@ -195,46 +198,6 @@ function operatorEvidenceRefsFrom(evidenceRefs) {
   }));
 }
 
-function phaseFor(definition, evidence, contract) {
-  return {
-    phase: definition.key,
-    label: definition.label,
-    contract_schema: definition.schema,
-    evidence_ref: evidence.ref,
-    status: evidence.status === PROVIDED ? 'evidence_ref_provided' : evidence.status,
-    contract_id: contract?.[definition.idField] ?? null,
-  };
-}
-
-function lifecycleReadiness(evidenceRefs, operatorGoLiveRef) {
-  const missingEvidenceRefs = Object.values(evidenceRefs)
-    .filter((evidence) => evidence.status !== PROVIDED)
-    .map(({ key, status, ref, blocker }) => ({ key, status, ref, blocker }));
-  const allEvidenceProvided = missingEvidenceRefs.length === 0;
-  const operatorGoLiveProvided = typeof operatorGoLiveRef === 'string' && operatorGoLiveRef.length > 0;
-  const hostedCloudSellable = allEvidenceProvided && operatorGoLiveProvided;
-  const status = hostedCloudSellable
-    ? 'operator_approved_evidence_packet'
-    : allEvidenceProvided
-      ? 'blocked_operator_go_live_approval'
-      : 'blocked_missing_evidence';
-  return {
-    status,
-    hosted_cloud_sellable: hostedCloudSellable,
-    evidence_validation_only: true,
-    provider_wiring_performed: false,
-    no_external_provider_calls: true,
-    all_evidence_refs_provided: allEvidenceProvided,
-    operator_go_live_approval_ref: operatorGoLiveRef ?? 'blocked:operator_go_live_approval',
-    operator_go_live_approval_provided: operatorGoLiveProvided,
-    missing_evidence_refs: missingEvidenceRefs,
-    external_blockers: HOSTED_CLOUD_EXTERNAL_BLOCKERS
-      .map((key) => evidenceRefs[key])
-      .filter((evidence) => evidence.status !== PROVIDED)
-      .map(({ key, ref, blocker }) => ({ key, ref, blocker })),
-  };
-}
-
 function refFor(evidenceRefs, key) {
   return evidenceRefs[key].ref;
 }

package/scripts/build-installer-assets.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 export const INSTALLER_ASSET_SCHEMA = 'enigma.installer_assets.v1';
 export const INSTALLER_ASSET_PACKAGE = 'enigma-memory';
-export const INSTALLER_ASSET_VERSION = '0.1.9';
+export const INSTALLER_ASSET_VERSION = '0.1.10';
 export const INSTALLER_ASSET_GENERATED_AT = '1970-01-01T00:00:00.000Z';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);

package/scripts/run-standard-memory-benchmarks.mjs

@@ -995,7 +995,7 @@ function buildSuiteReport(datasetRows, topK, options) {
     generated_at: options.generated_at ?? new Date().toISOString(),
     package: {
       name: 'enigma-memory',
-      version: '0.1.9',
+      version: '0.1.10',
     },
     public_safe: true,
     top_k: topK,