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

package/docs/TODO-multi-vault.md

@@ -1,29 +0,0 @@
-# TODO: Multi-Vault Management
-
-TUI startup flow: list vaults first, then select or create. No direct key prompt at start.
-
-## Core Flow
-
-1. **Startup**: Scan `C_BIO_VAULT_DIR` (default `~/.c-bio/`) for `vault_*.enc`
-2. **List**: Show all vault files with full path; add "Create vault" option
-3. **Select**: User picks vault → prompt for private key → load
-4. **Create**: Generate new identity (like `init`) → show keys for user to save → load vault
-
-## Edge Cases
-
-- [ ] Empty directory: show only "Create vault", no empty list
-- [ ] Wrong key: decrypt fails → show error, allow retry or back to list
-- [ ] Corrupted vault: load fails → show error, allow back to list
-- [ ] Quit: from vault list, allow Quit without selecting
-- [ ] Directory permission: `C_BIO_VAULT_DIR` unreadable → show permission error
-
-## Optional Enhancements
-
-- [ ] Vault label: optional `.label` file next to vault for user-friendly identification
-- [ ] Import from backup: "Import vault" alongside "Create vault"
-- [ ] Switch vault: from main menu, return to vault list and select another
-
-## Out of Scope (for now)
-
-- Label file format and storage convention
-- Reading activity log metadata for display before unlock (requires decrypt)

package/docs/spec/runtime/README.md

@@ -1,44 +0,0 @@
-# CBIO Runtime Spec
-
-This directory defines runtime rules that must stay consistent across language implementations such as Node and Rust.
-
-These files are not Node-specific API docs. They are shared runtime contracts.
-
-Use this directory for:
-- local persisted record schemas
-- runtime-only policy rules
-- merge and recovery semantics
-- audit/event semantics
-
-Do not use this directory for:
-- Node-only helper APIs
-- examples or tutorials
-- protocol-layer governance objects already defined by `@the-ai-company/cbio-protocol`
-
-## Current Runtime Spec Set
-
-- [managed-agent-record.md](./managed-agent-record.md): persisted local record for a managed agent identity
-- [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
-
-If a Node runtime and a Rust runtime both claim to implement CBIO runtime behavior, these rules must mean the same thing in both implementations.

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

@@ -1,71 +0,0 @@
-# Activity Log
-
-## Purpose
-
-Defines the local audit trail for vault-authenticated runtime actions.
-
-This log is runtime-local. It is not a protocol object and is not required to be shared across peers.
-
-## Entry Shape
-
-Each entry must contain:
-
-```json
-{
-  "ts": 0,
-  "action": "fetchWithAuth",
-  "secretName": "string",
-  "url": "string",
-  "method": "GET",
-  "success": true
-}
-```
-
-Required fields:
-- `ts`: event timestamp in Unix milliseconds
-- `action`: runtime action name
-- `secretName`: vault secret involved
-- `url`: request URL
-- `method`: HTTP method
-- `success`: whether the action succeeded
-
-Optional fields:
-- `error`: failure message when `success` is `false`
-
-## Defined Actions
-
-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
-
-If activity log persistence fails:
-
-- `fetchWithAuth` may still throw its primary runtime error
-- `fetchJsonAndAddSecret` and `fetchJsonAndUpdateSecret` must return their normal `FetchResult` shape
-- those returned results must set `activityLogWriteFailed: true`
-
-The primary operation outcome must not be silently rewritten into a different success/failure class solely because audit persistence failed.
-
-## Compatibility
-
-- Action names are part of the runtime contract.
-- Writers may append extra fields, but readers must tolerate unknown fields.
-
-## Non-Goals
-
-- Defining centralized logging
-- Defining protocol-visible governance audit records
-- Defining retention policy for local log files

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

@@ -1,99 +0,0 @@
-# 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/managed-agent-record.md

@@ -1,52 +0,0 @@
-# Managed Agent Record
-
-## Purpose
-
-Defines the persisted local record format used by a parent identity to store a managed agent identity in its own vault.
-
-This is a runtime record, not a protocol object.
-
-## Record Shape
-
-The persisted JSON object must contain:
-
-```json
-{
-  "agentId": "string",
-  "publicKey": "string",
-  "privateKey": "string",
-  "issuedIdentity": {},
-  "storageKey": "string"
-}
-```
-
-Required fields:
-- `agentId`: the derived root agent id for `publicKey`
-- `publicKey`: the managed agent public key
-- `privateKey`: the managed agent private key
-- `issuedIdentity`: the signed `IssuedAgentIdentity` protocol object for the managed agent
-
-Optional fields:
-- `storageKey`: the vault storage key where the managed agent's vault data is or should be persisted. When present, loaders must use it to restore the same vault binding used at issuance; when absent, loaders may use an implementation-defined default (e.g. derived from `publicKey`).
-
-## Required Semantics
-
-1. `issuedIdentity.agent.public_key` must equal `publicKey`.
-2. `issuedIdentity.agent.agent_id` must equal `agentId`.
-3. `privateKey` must derive to `publicKey`.
-4. The record is stored in the authority vault under an authority-chosen record key.
-5. Loading a managed agent from this record must fail if the managed agent has been revoked by the authority.
-6. When `storageKey` is present, loaders must prefer it for vault binding; writers may depend on this for correctness.
-
-## Compatibility
-
-- Field names are part of the runtime contract.
-- `storageKey` is a defined optional field; writers may depend on readers honoring it when present.
-- Other additional fields may be ignored by readers, and writers should not depend on them for correctness.
-- A future versioned schema must use an explicit version field instead of changing meanings silently.
-
-## Non-Goals
-
-- Defining the `IssuedAgentIdentity` protocol object itself
-- Defining how the vault encrypts or persists this record
-- Defining language-specific API shapes such as `issueManagedAgent(...)`

package/docs/spec/runtime/merge-rules.md

@@ -1,52 +0,0 @@
-# Merge Rules
-
-## Purpose
-
-Defines when one runtime vault may merge secrets from another vault representing the same root identity.
-
-## Preconditions
-
-1. Both vaults must belong to the same root identity.
-2. If root identities differ, the merge must fail with `MERGE_IDENTITY_MISMATCH`.
-
-## Conflict Modes
-
-Supported conflict modes:
-- `abort`
-- `skip`
-- `overwrite`
-
-### `abort`
-
-- If any incoming secret name already exists in the target vault, the merge must fail.
-- No partial merge may be committed.
-
-### `skip`
-
-- Existing target secrets keep their current value.
-- Incoming secrets with new names are merged.
-
-### `overwrite`
-
-- Incoming secrets replace target secrets with the same name.
-- Incoming secrets with new names are merged.
-
-## Required Semantics
-
-1. Merge identity matching is determined from the vault owner identity, not from caller trust.
-2. Secret names are the merge keys.
-3. Secret values and their associated policy metadata must move together.
-4. Merge behavior must be deterministic for a given source vault, target vault, and conflict mode.
-
-## Result Shape
-
-Implementations may expose result objects differently, but they must be able to report at least:
-- added secret names
-- skipped secret names
-- overwritten secret names
-
-## Non-Goals
-
-- Defining a protocol object for merges
-- Defining cross-process locking
-- Defining transport/import mechanisms for moving sealed vault data

package/docs/spec/runtime/secret-origin-policy.md

@@ -1,46 +0,0 @@
-# Secret Origin Policy
-
-## Purpose
-
-Defines the runtime policy for secrets acquired from remote endpoints and for later rotation of those secrets.
-
-## URL Acceptance
-
-An acquisition or rotation URL is allowed only if:
-- it uses `https:`, or
-- it uses `http:` with a loopback host for local development
-
-Loopback hosts include:
-- `localhost`
-- `127.0.0.1`
-- `[::1]`
-
-Non-loopback plain HTTP must be rejected.
-
-## Acquisition Semantics
-
-When a secret is fetched from a remote endpoint and stored:
-
-1. If the caller does not provide `allowedOrigins`, the stored secret policy must default to the fetch URL origin.
-2. If the requested secret name already exists, the runtime must allocate a unique name by suffixing `_N` where `N` starts at `1`.
-3. The returned payload must not leak the extracted secret value in cleartext.
-
-## Rotation Semantics
-
-When a secret is rotated from a remote endpoint:
-
-1. The rotation source origin must be allowed by the existing secret policy.
-2. If no origin policy exists for the secret, rotation must fail with `SECRET_POLICY_REQUIRED`.
-3. If the fetch origin is not allowed, rotation must fail with `SECRET_SOURCE_ORIGIN_MISMATCH`.
-4. A failed rotation must not replace the existing active secret value.
-
-## Normalization
-
-- Origin comparison is performed on normalized origin strings.
-- Path, query, and fragment are not part of the policy match.
-
-## Non-Goals
-
-- Defining provider-specific API behavior
-- Defining generic HTTP request libraries
-- Defining how secret values are used after storage

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

@@ -1,113 +0,0 @@
-# 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