@the-ai-company/cbio-node-runtime 0.32.0 → 0.39.0

package/docs/REFERENCE.md

@@ -39,18 +39,15 @@ import { sealBlob, unsealBlob } from '@the-ai-company/cbio-node-runtime/sealed';
 
 `permissions` and `deriveFromIssuedIdentity` are mutually exclusive; do not pass both.
 
+Secret-use operations on a `CbioAgent` require:
+- `vault:fetch` for remote authenticated use such as `fetchWithAuth(...)`
+- `vault:acquire` for acquisition, ingress, compare, proof, and validation operations
+
 ### 1.5 Recursive Child Identity Management
-When a child is registered via `registerChildIdentity(keys)`, its key material is stored in the parent vault. The method returns `{ publicKey }` (domain-level identifier). The record naming scheme is an internal runtime detail; use the protocol subpath for low-level vault access:
+When a child is registered via `registerChildIdentity(keys)`, its key material is stored in the parent vault. The method returns `{ publicKey }` (domain-level identifier). Treat the persisted child record as runtime-managed state rather than application-readable plaintext.
 ```ts
-import { getChildIdentitySecretName } from '@the-ai-company/cbio-node-runtime/protocol';
-
 const { publicKey: childPublicKey } = await identity.registerChildIdentity(keys);
-const secretName = getChildIdentitySecretName(childPublicKey);
-const stored = identity.admin.vault.getSecret(secretName);
-if (stored) {
-  const { privateKey, publicKey } = JSON.parse(stored);
-  const childIdentity = await CbioIdentity.load({ privateKey, publicKey });
-}
+console.log(childPublicKey);
 ```
 
 ---
@@ -160,6 +157,115 @@ const proxy = await startLocalAuthProxy({
 });
 ```
 
+### 3.5 Local Secret Ingress
+Use `startLocalSecretIngress(...)` when a trusted local process already has a newly issued secret and should hand it directly into CBIO without printing it to terminal output first.
+
+```ts
+const ingress = await identity.startLocalSecretIngress({
+  secretName: 'service-token',
+});
+
+await fetch(ingress.url, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${ingress.authToken}`,
+    'Content-Type': 'text/plain',
+  },
+  body: 'new-secret-value',
+});
+```
+
+Optional fields:
+- `allowedOrigins`
+- `overwrite`
+- `host`
+- `port`
+- `path`
+- `authToken`
+- `once`
+- `maxBodyBytes`
+
+### 3.6 Local Compare / Proof
+Use `compareSecret(...)` and `proveSecret(...)` when the application needs a local KMS-like operation without exporting the stored secret.
+
+```ts
+const same = await identity.compareSecret('service-token', 'candidate-value');
+const proof = await identity.proveSecret('service-token', 'challenge-123');
+```
+
+Current proof algorithms:
+- `sha256`
+- `sha512`
+
+`proveSecret(...)` returns a base64url-encoded HMAC proof for the active secret value and the provided challenge.
+
+### 3.7 Secret Validation
+Use `validateSecret(...)` when the application wants a structured validity result rather than exporting a secret and probing manually.
+
+`validateSecret(...)` accepts a `SecretValidator`, whose `validate(handle)` method receives a restricted handle with:
+- `fetchWithAuth(url, options?)`
+- `compare(candidate)`
+- `prove(challenge, options?)`
+
+The validator never receives the plaintext secret value.
+
+Result shape:
+
+```ts
+type SecretValidationResult = {
+  valid: boolean;
+  status: 'valid' | 'invalid' | 'indeterminate';
+  reason?: string;
+  providerSubject?: string;
+  expiresAt?: string;
+  scopes?: readonly string[];
+  metadata?: Record<string, unknown>;
+};
+```
+
+Minimal example:
+
+```ts
+const result = await identity.validateSecret('service-token', {
+  async validate(handle) {
+    const response = await handle.fetchWithAuth('https://api.example.com/me');
+    return {
+      valid: response.ok,
+      status: response.ok ? 'valid' : 'invalid',
+    };
+  },
+});
+```
+
+### 3.8 Generic HTTP Validator
+Use `genericHttpValidator(...)` when a remote service can be probed by a normal authenticated HTTP request and you want a reusable validator without writing custom validator boilerplate.
+
+```ts
+const validator = genericHttpValidator({
+  url: 'https://api.example.com/me',
+  extractResult: (_response, data: { subject?: string; scopes?: string[] } | undefined) => ({
+    providerSubject: data?.subject,
+    scopes: data?.scopes,
+  }),
+});
+
+const result = await identity.validateSecret('service-token', validator);
+```
+
+Supported config fields:
+- `url`
+- `method`
+- `headers`
+- `body`
+- `isValid(response, data)`
+- `classifyStatus(response, data)`
+- `extractResult(response, data)`
+
+Default behavior:
+- `2xx` -> `{ valid: true, status: 'valid' }`
+- `401/403` -> `{ valid: false, status: 'invalid', reason: 'http_<status>' }`
+- other non-`2xx` -> `{ valid: false, status: 'indeterminate', reason: 'http_<status>' }`
+
 ---
 
 ## 4. Error Code Dictionary
@@ -174,6 +280,7 @@ The SDK uses structured `IdentityError` objects with the following codes:
 | `SECRET_ALREADY_EXISTS` | `addSecret` used on an existing name. | Use a new name or `update`. |
 | `SECRET_POLICY_REQUIRED` | Agent rotation attempted without allowed origins. | Set origins in identity code. |
 | `SECRET_SOURCE_ORIGIN_MISMATCH` | Rotation came from a disallowed origin. | Check secret policy and rotation URL. |
+| `SECRET_OPERATION_RATE_LIMITED` | Local compare/proof/validate operation exceeded the runtime limit window. | Back off, reduce probe frequency, or avoid low-entropy repeated guesses. |
 | `VAULT_PERSISTENCE_FAILED` | Storage is not writable. | Fix permissions or check storage path. |
 | `VAULT_FILE_NOT_FOUND` | Expected vault file does not exist. | Initialize identity or check storage key. |
 | `VAULT_WRITE_INTEGRITY_FAILED` | Save verification failed. | Check disk space/integrity. |

package/docs/spec/runtime/README.md

@@ -21,6 +21,23 @@ Do not use this directory for:
 - [merge-rules.md](./merge-rules.md): vault merge preconditions and conflict behavior
 - [secret-origin-policy.md](./secret-origin-policy.md): allowed origin policy for acquired and rotated secrets
 - [activity-log.md](./activity-log.md): local audit event schema and failure semantics
+- [secret-validation.md](./secret-validation.md): local compare/proof semantics and versioning contract for future validator adapters
+- [exposure-surfaces.md](./exposure-surfaces.md): current runtime exposure surfaces, mitigations, and future hardening areas
+
+## Spec Versioning
+
+Runtime specs in this directory use:
+
+- an integer version number
+- a lifecycle status suffix such as `draft` or `stable`
+
+Examples:
+
+- `v1-draft`
+- `v1-stable`
+- `v2-draft`
+
+This keeps compatibility decisions obvious while the runtime incubates behavior before anything graduates into a broader protocol contract.
 
 ## Design Goal
 

package/docs/spec/runtime/activity-log.md

@@ -38,12 +38,16 @@ Current action names:
 - `fetchWithAuth`
 - `fetchJsonAndAddSecret`
 - `fetchJsonAndUpdateSecret`
+- `compareSecret`
+- `proveSecret`
+- `validateSecret`
 
 ## Required Semantics
 
 1. `fetchWithAuth` success and failure attempts must append an activity entry.
 2. JSON secret acquisition and rotation success and failure attempts must append an activity entry.
 3. Direct admin secret mutation such as `addSecret` is not part of this audit stream.
+4. Local compare/proof/validate attempts should append activity entries without exporting plaintext secret values.
 
 ## Failure Semantics
 

package/docs/spec/runtime/exposure-surfaces.md

@@ -0,0 +1,99 @@
+# Exposure Surfaces
+
+## Purpose
+
+Documents the currently known secret exposure surfaces that still exist even after the runtime removes public plaintext secret export from its supported flows.
+
+This document is a runtime security inventory, not a protocol object.
+
+## Current Exposure Surfaces
+
+### 1. Root Initialization Window
+
+The root private key may still exist in cleartext during initial generation, import, prompt entry, environment injection, or process startup wiring.
+
+This is currently the primary accepted plaintext bootstrap window.
+
+### 2. Runtime Process Memory
+
+Secrets still exist in runtime memory while they are being:
+
+- acquired
+- used for authenticated requests
+- compared
+- proven
+- validated
+
+Memory compromise remains an exposure surface.
+
+### 3. Remote Target Disclosure
+
+When the runtime uses a secret against a remote service, that target service necessarily receives the credential or proof material required for the request.
+
+Examples:
+
+- `fetchWithAuth`
+- `startLocalAuthProxy`
+- provider-backed validation probes
+
+### 4. Local Ingress Channel
+
+Local secret ingress reduces terminal exposure, but the local handoff channel still exists.
+
+Relevant artifacts include:
+
+- loopback listener state
+- one-time ingress token
+- local process boundaries
+
+### 5. Secret Operation Oracles
+
+Local KMS-like operations such as compare, proof, and validation are safer than plaintext export, but they still create controlled oracles.
+
+Risk examples:
+
+- repeated compare attempts against low-entropy values
+- repeated proof generation against attacker-chosen challenges
+
+### 6. Authority-Held Managed Identity Material
+
+Authority vaults may still contain managed-agent or child-identity private key material as runtime-internal records.
+
+These records are hidden from the public secret namespace, but authority compromise remains a high-impact event.
+
+### 7. Backup and Sealed Export Assets
+
+Sealed vault exports are encrypted, but they remain high-value assets. Their security depends on the external key-encryption-key lifecycle.
+
+### 8. User-Supplied Surrounding Code
+
+The runtime can avoid plaintext export on its own surfaces, but surrounding application code may still leak:
+
+- ingress tokens
+- validation metadata
+- proofs
+- request traces
+- root bootstrap material
+
+## Current Mitigations
+
+Implemented mitigations include:
+
+- no public plaintext secret retrieval API
+- no public plaintext secret add API
+- direct remote acquisition into vault
+- local secret ingress instead of terminal handoff
+- local compare/proof/validate without plaintext export
+- hidden internal record namespace for managed-agent and revocation records
+- rate limiting for local compare/proof/validate operations
+- audit entries for local compare/proof/validate operations
+
+## Ongoing Hardening Areas
+
+Future hardening should focus on:
+
+- stronger rate limiting and policy controls for local secret oracles
+- stricter challenge/purpose rules for proof generation
+- tighter handling of authority-held managed identity material
+- guidance and tooling for safer bootstrap of the root private key
+- clearer backup/KDK operational guidance

package/docs/spec/runtime/secret-validation.md

@@ -0,0 +1,113 @@
+# Secret Validation
+
+## Spec Version
+
+- `version`: `1`
+- `status`: `draft`
+- Display form: `v1-draft`
+
+This document defines the runtime contract for local secret proof and validation-oriented operations.
+
+This is a runtime spec, not a protocol object.
+
+## Purpose
+
+Defines how a CBIO runtime may:
+
+- prove possession of a secret without exporting it
+- compare a candidate against a stored secret without exporting it
+- evolve toward provider-backed remote validation without changing the core result semantics
+
+## Scope
+
+This spec currently covers:
+
+- local compare semantics
+- local proof semantics
+- versioning rules for future remote validator adapters
+
+This spec does not yet define:
+
+- provider-specific validator endpoints
+- cross-network proof exchange formats
+- third-party CBIO-native validation endpoints
+
+## Versioning Rules
+
+Runtime secret validation specs use:
+
+- an integer `version`
+- a lifecycle `status`
+
+Examples:
+
+- `v1-draft`
+- `v1-stable`
+- `v2-draft`
+
+Rules:
+
+1. Increment the integer version when behavior, required fields, or result semantics change incompatibly.
+2. Change only the status when the semantics stay the same but implementation confidence changes.
+3. Do not reuse an older integer version for different semantics.
+
+## Local Compare Semantics
+
+`compareSecret(secretName, candidate)` must:
+
+1. return `true` only when the candidate exactly matches the active secret value
+2. return `false` when the candidate does not match
+3. fail with `SECRET_NOT_FOUND` when the named secret does not exist
+4. not return the stored secret value in cleartext
+5. use a comparison method suitable for secret material
+
+## Local Proof Semantics
+
+`proveSecret(secretName, challenge, options?)` must:
+
+1. fail with `SECRET_NOT_FOUND` when the named secret does not exist
+2. not return the stored secret value in cleartext
+3. deterministically derive a proof from:
+   - the active secret value
+   - the provided challenge
+   - the selected algorithm
+
+### Defined Algorithms
+
+Current algorithm names:
+
+- `sha256`
+- `sha512`
+
+For `v1-draft`, the proof value is:
+
+- `HMAC(algorithm, secretValue, challenge)`
+- encoded as `base64url`
+
+## Permission Semantics
+
+Runtime handles must treat local compare/proof operations as secret acquisition-class capabilities.
+
+For `v1-draft`:
+
+- `CbioIdentity` may invoke these operations
+- `CbioAgent` requires `vault:acquire`
+
+## Forward Compatibility
+
+Future versions may add remote validator contracts that return structured validation results such as:
+
+- `valid`
+- `reason`
+- `providerSubject`
+- `expiresAt`
+- `scopes`
+- `metadata`
+
+Those result objects must be versioned under this spec family rather than silently changing local compare/proof semantics.
+
+## Non-Goals
+
+- Defining a cloud KMS protocol
+- Defining provider-specific auth probe behavior
+- Defining how third-party websites must expose validation endpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-ai-company/cbio-node-runtime",
-  "version": "0.32.0",
+  "version": "0.39.0",
   "description": "Node.js runtime for cbio identity and credential vault. Library only, no CLI or TUI.",
   "type": "module",
   "main": "./dist/runtime/index.js",
@@ -34,7 +34,7 @@
     "build": "node ./scripts/clean-dist.mjs && tsc",
     "prepare": "npm run build",
     "test": "npm run build && npm run test:acceptance",
-    "test:acceptance": "node tests/runtime/derivation.js && node tests/runtime/errors.js && node tests/runtime/hardened_vault.js && node tests/runtime/isolation_local.js && node tests/runtime/managed_agent_identity.js && node tests/runtime/merge_security_local.js && node tests/runtime/recursive_cbio.js && node tests/runtime/register_child.js && node tests/runtime/transparency.js && node tests/runtime/vault_resilience.js && node tests/runtime/activity_log.js && node tests/runtime/secret_rotation_policy.js && node tests/runtime/local_auth_proxy.js && node tests/storage/adaptability.js && node tests/runtime/autosave.js"
+    "test:acceptance": "node tests/runtime/derivation.js && node tests/runtime/errors.js && node tests/runtime/hardened_vault.js && node tests/runtime/isolation_local.js && node tests/runtime/managed_agent_identity.js && node tests/runtime/merge_security_local.js && node tests/runtime/recursive_cbio.js && node tests/runtime/register_child.js && node tests/runtime/transparency.js && node tests/runtime/vault_resilience.js && node tests/runtime/activity_log.js && node tests/runtime/secret_rotation_policy.js && node tests/runtime/local_auth_proxy.js && node tests/runtime/local_secret_ingress.js && node tests/runtime/local_secret_proof.js && node tests/runtime/local_secret_validate.js && node tests/runtime/generic_secret_validator.js && node tests/runtime/local_secret_guardrails.js && node tests/storage/adaptability.js && node tests/runtime/autosave.js"
   },
   "keywords": [
     "claw-biometric",