@the-ai-company/cbio-node-runtime 0.31.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,100 @@
+# CBIO Runtime Architecture
+
+This document defines the architectural boundaries and naming rules for the runtime.
+
+For cross-language runtime rules that Node and Rust must share, see [spec/runtime/README.md](./spec/runtime/README.md).
+
+## Layer Boundaries
+
+- `runtime/`: public consumer surface only.
+- `protocol/`: protocol adapters and identity/crypto helpers layered on top of `cbio-protocol`.
+- `vault/`: local secret storage, persistence, recovery, and secret policy enforcement.
+- `agent/`: identity and managed-agent orchestration.
+- `http/`: HTTP-facing workflows and local proxy helpers.
+- `audit/`: activity log data structures and persistence helpers.
+- `docs/`: examples, guidance, and integration patterns. Not executable product logic.
+- `docs/spec/runtime/`: shared runtime contracts for multi-language implementations.
+
+## Naming Rules
+
+### 1. One name, one layer
+
+Do not use the same term for different layers of authority or behavior.
+
+- Protocol-level privileges must be named differently from runtime handle permissions.
+- Internal storage records must not be named like public API concepts.
+
+Good examples:
+
+- `issuedCapabilities`: privileges embedded into a signed identity document
+- `runtimePermissions`: permissions granted to a returned `CbioAgent` handle
+
+### 2. Name by responsibility
+
+Names should describe what the code does, not merely what topic it is near.
+
+Good:
+
+- `startLocalAuthProxy`
+- `fetchWithAuth`
+- `getManagedAgentCapabilities`
+
+Bad:
+
+- vague helper names
+- names that only imply a provider or product example
+
+### 3. Name public contracts by actual requirements
+
+Public option and parameter names must reflect what callers truly need.
+
+Good:
+
+- `IdentityLoadKeys`: requires `privateKey`, allows optional `publicKey`
+
+Bad:
+
+- names that imply stronger requirements than the implementation actually needs
+
+### 4. Do not promote examples into core abstractions
+
+Common configurations belong in docs, not in the core naming system.
+
+- External service examples such as OpenAI, Anthropic, or Resend are documentation concerns.
+- Core APIs should accept general configuration such as `upstreamBaseUrl`, `authHeaderName`, and `authPrefix`.
+
+### 5. Split option objects by operation
+
+If one options type starts describing multiple operations, split it.
+
+A single options object may still group inputs that are consumed by one concrete operation path.
+For example, an identity load API may accept both storage binding and issued-identity binding if both are applied during the same load step.
+
+Good:
+
+- `ManagedAgentIssueOptions`
+- `ManagedAgentLoadOptions`
+- `RegisterChildIdentityOptions`
+
+Bad:
+
+- one broad options object that mixes issue, load, storage, and permission semantics
+
+### 6. Internal escape hatches stay internal
+
+If a method exists only to let implementation pieces cooperate, it should not become part of the public API shape.
+
+- Prefer module-local coordination over public bridge methods.
+- Avoid exposing internal records, vault objects, or persistence schemas from `runtime/`.
+
+## Review Checklist
+
+When evaluating a new function, type, or field name, ask:
+
+1. Does this name describe one thing only?
+2. Does it reveal the correct layer and authority level?
+3. Would a user infer the correct behavior without reading implementation code?
+4. Is this a stable domain concept, or just a popular example?
+5. Is this exposing an internal detail as if it were public API?
+
+If any answer is "no", rename or split before expanding the API surface.

package/docs/REFERENCE.md

@@ -0,0 +1,184 @@
+# CBIO SDK Deep Reference
+
+This document provides a comprehensive technical reference for the CBIO SDK, covering advanced API usage, custom storage implementation, and structured error handling.
+
+For high-level concepts and quick start, see [README.md](../README.md). For module structure and naming rules, see [ARCHITECTURE.md](./ARCHITECTURE.md). For cross-language runtime contracts, see [spec/runtime/README.md](./spec/runtime/README.md).
+
+---
+
+## 1. Advanced Identity APIs
+
+These methods are available under `identity.admin` and its sub-facets, and are intended for administrative or high-privilege bootstrap logic.
+
+### 1.1 Vault Synchronization & Merging
+- **`identity.admin.vault.mergeFrom(otherIdentity, options?)`**: Atomically merges secrets from another vault.
+  - `onConflict`: `'abort'` (default), `'skip'`, or `'overwrite'`.
+  - Throws `MERGE_IDENTITY_MISMATCH` if root identities differ.
+
+### 1.2 Backups & Sealing
+- **`identity.admin.vault.seal(kdk: string): string`**: Exports the entire vault as an encrypted blob.
+- **`identity.admin.vault.loadFromSealedBlob(kdk: string, blob: string)`**: Restores a vault from a sealed backup.
+- **`identity.admin.vault.saveVault()`**: Persists the current vault back to its bound storage.
+- **`identity.admin.vault.saveVaultAs(storageKey)`**: One-time save of the vault to an explicit key/path. Does NOT change the bound storage for subsequent `saveVault()` or autosave.
+
+Lower-level sealed blob primitives are also exported from the package subpath:
+
+```ts
+import { sealBlob, unsealBlob } from '@the-ai-company/cbio-node-runtime/sealed';
+```
+
+### 1.3 Audit & Lifecycle
+- **`identity.admin.vault.getActivityLog()`**: Returns a read-only list of all vault-authenticated actions.
+- **`identity.admin.managedAgents.revokeManagedAgent(publicKey, reason?)`**: Permanently revokes a child identity.
+- **`identity.admin.managedAgents.getManagedAgentCapabilities(publicKey)`**: Returns `{ status, capabilities }` for a managed agent, so callers can distinguish active, revoked, missing, and invalid records.
+
+### 1.4 Agent Handles
+- **`getAgent()`**: Returns a minimally privileged handle with `vault:fetch` and `vault:list`.
+- **`getAgent({ permissions })`**: Returns a handle with explicitly provided runtime permissions.
+- **`getAgent({ deriveFromIssuedIdentity: true })`**: Derives runtime permissions from the issued identity's protocol capabilities.
+
+`permissions` and `deriveFromIssuedIdentity` are mutually exclusive; do not pass both.
+
+### 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:
+```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 });
+}
+```
+
+---
+
+## 2. Storage Customization
+
+The SDK can run on any backend by implementing the `IStorageProvider` interface.
+
+### 2.1 Interface Definition
+```ts
+export interface IStorageProvider {
+  read(key: string): Promise<Buffer | null>;
+  write(key: string, data: Buffer): Promise<void>;
+  delete(key: string): Promise<void>;
+  has(key: string): Promise<boolean>;
+  rename?(fromKey: string, toKey: string): Promise<void>; // Improves atomic writes
+}
+```
+
+### 2.2 Pre-built Providers
+- **`MemoryStorageProvider`**: Ephemeral storage for testing or in-memory caches.
+- **Filesystem (Default)**: Persists to `~/.c-bio/`. Use `C_BIO_VAULT_DIR` environment variable to override.
+
+When loading an identity, use `storageKey` to choose the persisted vault location or provider key. Activity log behavior is configured explicitly with `activityLog`, for example `activityLog: { key: 'my-vault.activity.jsonl' }` or `activityLog: { enabled: false }`.
+
+---
+
+## 3. Advanced Request Patterns
+
+### 3.1 Custom Fetch for SDKs (OpenAI/Anthropic)
+If a third-party SDK supports a custom `fetch` implementation, use `createFetchWithAuth`. This keeps the vault boundary while using the official client.
+```ts
+const openai = new OpenAI({
+  fetch: agent.createFetchWithAuth('openai'),
+});
+```
+
+### 3.2 Complex HTTP Calls
+Use full request options for `fetchWithAuth`:
+```ts
+const response = await agent.fetchWithAuth('my-secret', 'https://api.example.com', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ key: 'value' }),
+  authPrefix: 'Token ', // Optional: default is 'Bearer '
+  withSignature: true,  // Optional: adds X-CBIO-Signature
+});
+```
+
+### 3.3 JSON Secret Acquisition
+Use `fetchJsonAndAddSecret(...)` and `fetchJsonAndUpdateSecret(...)` when the upstream returns a JSON payload that contains a secret value to store or rotate.
+
+```ts
+const acquired = await agent.fetchJsonAndAddSecret({
+  secretName: 'service-token',
+  url: 'https://issuer.example.com/token',
+  body: { scope: 'read' },
+  extractKey: (response: { api_key?: string }) => response.api_key ?? '',
+});
+```
+
+These methods are intentionally JSON-specific:
+- request bodies are JSON-stringified
+- responses are parsed with `response.json()`
+- `extractKey(...)` receives the parsed JSON body
+
+### 3.4 Local Auth Proxy
+Use `startLocalAuthProxy(...)` when a local process should forward requests to an upstream API while vault-backed auth is injected automatically.
+
+Required fields:
+- `authHandle`: any object with `fetchWithAuth(...)`
+- `secretName`: vault secret to inject
+- `upstreamBaseUrl`: upstream API base URL
+
+Optional fields:
+- `authHeaderName`: defaults to `Authorization`
+- `authPrefix`: defaults to `Bearer `
+- `host`: defaults to `127.0.0.1`
+- `port`: defaults to an ephemeral port
+
+OpenAI example:
+```ts
+const proxy = await startLocalAuthProxy({
+  authHandle: agent,
+  secretName: 'openai',
+  upstreamBaseUrl: 'https://api.openai.com',
+});
+```
+
+Anthropic example:
+```ts
+const proxy = await startLocalAuthProxy({
+  authHandle: agent,
+  secretName: 'anthropic',
+  upstreamBaseUrl: 'https://api.anthropic.com',
+  authHeaderName: 'x-api-key',
+  authPrefix: '',
+});
+```
+
+Resend example:
+```ts
+const proxy = await startLocalAuthProxy({
+  authHandle: agent,
+  secretName: 'resend',
+  upstreamBaseUrl: 'https://api.resend.com',
+});
+```
+
+---
+
+## 4. Error Code Dictionary
+
+The SDK uses structured `IdentityError` objects with the following codes:
+
+| Code | Meaning | Typical Fix / Recovery |
+| :--- | :--- | :--- |
+| `PERMISSION_DENIED` | Handle lacks the required runtime capability. | Check `agent.can()` before calling. |
+| `SECRET_NOT_FOUND` | Secret name does not exist in the vault. | Add it first or check the naming. |
+| `ISSUED_IDENTITY_INVALID` | Bound or persisted issued identity failed protocol or authority/subject validation. | Re-issue the managed identity or load with the correct authority context. |
+| `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. |
+| `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. |
+| `VAULT_CORRUPTED` | Vault file is truncated or unreadable. | Restore from backup; do not overwrite. |
+| `VAULT_DECRYPT_FAILED` | Decryption failed (wrong key or tampered). | Verify the correct Private Key was used. |
+| `MERGE_IDENTITY_MISMATCH` | Tried to merge vaults of different identities. | Only merge vaults of the same identity. |
+| `CHILD_IDENTITY_REQUIRES_PRIVATE_KEY` | Child keys were incomplete on registration. | Ensure child keys include Private Key. |
+| `SIGNER_REQUIRES_PRIVATE_KEY` | Administrative action requires a full signer. | Load identity from a full private key. |

package/docs/TODO-multi-vault.md

@@ -0,0 +1,29 @@
+# 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/WORKS_WITH_CUSTOM_FETCH.md

@@ -0,0 +1,196 @@
+# Works With SDKs That Support Custom Fetch
+
+This is the recommended integration path for `@the-ai-company/agent-identity-sdk`.
+
+If a provider SDK accepts a custom `fetch`, you can keep the provider's official client and still avoid ever reading the API key in plaintext.
+
+## Why this is the preferred path
+
+- you keep using the provider's official SDK surface
+- the vault still injects authentication headers for each request
+- agent logic never needs `identity.getSecret(...)`
+- the integration stays close to normal provider examples
+
+## General pattern
+
+```ts
+const authFetch = agent.createFetchWithAuth('provider-secret-name');
+
+const client = new ProviderSDK({
+  fetch: authFetch,
+});
+```
+
+Use `fetchWithAuth(...)` instead when you do not need the provider SDK at all.
+
+## OpenAI
+
+The official OpenAI JavaScript SDK supports a custom `fetch` function.
+
+```ts
+import OpenAI from 'openai';
+import { CbioIdentity } from '@the-ai-company/agent-identity-sdk';
+
+const identity = await CbioIdentity.load({
+  privateKey: process.env.AGENT_PRIV_KEY!,
+});
+
+const agent = identity.getAgent();
+
+const openai = new OpenAI({
+  fetch: agent.createFetchWithAuth('openai'),
+});
+
+const response = await openai.responses.create({
+  model: 'gpt-4.1',
+  input: 'Say hello in one sentence.',
+});
+```
+
+Store the secret under a name like `openai`, then reuse that secret name for all OpenAI requests.
+
+## Anthropic
+
+The official Anthropic TypeScript SDK also supports a custom `fetch` function.
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { CbioIdentity } from '@the-ai-company/agent-identity-sdk';
+
+const identity = await CbioIdentity.load({
+  privateKey: process.env.AGENT_PRIV_KEY!,
+});
+
+const agent = identity.getAgent();
+
+const anthropic = new Anthropic({
+  fetch: agent.createFetchWithAuth('anthropic'),
+});
+
+const message = await anthropic.messages.create({
+  model: 'claude-sonnet-4-5',
+  max_tokens: 256,
+  messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
+});
+```
+
+Use a dedicated secret name such as `anthropic`.
+
+## Other SDKs that support custom fetch
+
+Use the same pattern for any SDK that accepts:
+
+- `fetch`
+- a custom HTTP client built on `fetch`
+- request options that let you swap the transport layer
+
+The SDK does not need to know anything about Claw-biometric. It only needs to accept a `fetch` implementation.
+
+## If the SDK does not support custom fetch
+
+Do not solve that by calling `identity.getSecret(...)` inside agent logic just to feed a constructor that wants `apiKey: string`.
+
+Use one of these official alternatives instead:
+
+## Option 1: Call the provider API directly
+
+Best when:
+
+- the provider has a normal HTTP API
+- you only need a few endpoints
+- you want the smallest trusted surface
+
+Example:
+
+```ts
+const response = await agent.fetchWithAuth(
+  'resend',
+  'https://api.resend.com/emails',
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      from: 'onboarding@example.com',
+      to: ['user@example.com'],
+      subject: 'Hello',
+      html: '<strong>Welcome</strong>',
+    }),
+  }
+);
+```
+
+This is the recommended path for SDKs whose official client only accepts a raw API key.
+
+## Option 2: Use a local trusted proxy or broker
+
+Best when:
+
+- your team wants to keep the provider's official SDK
+- the SDK only accepts `apiKey: string`
+- you want to isolate key use from agent logic
+
+Pattern:
+
+```text
+agent/runtime -> local trusted broker -> provider API
+```
+
+The agent talks to a local process over HTTP or IPC. The local process holds `identity` privileges or another trusted handle and injects authentication on the outbound request.
+
+With the runtime helper, configure the upstream explicitly:
+
+```ts
+const proxy = await startLocalAuthProxy({
+  authHandle: agent,
+  secretName: 'openai',
+  upstreamBaseUrl: 'https://api.openai.com',
+});
+```
+
+For providers that do not use `Authorization: Bearer ...`, override the auth settings:
+
+```ts
+const proxy = await startLocalAuthProxy({
+  authHandle: agent,
+  secretName: 'anthropic',
+  upstreamBaseUrl: 'https://api.anthropic.com',
+  authHeaderName: 'x-api-key',
+  authPrefix: '',
+});
+```
+
+Common examples:
+
+- OpenAI: `upstreamBaseUrl: 'https://api.openai.com'`
+- Anthropic: `upstreamBaseUrl: 'https://api.anthropic.com'`, `authHeaderName: 'x-api-key'`, `authPrefix: ''`
+- Resend: `upstreamBaseUrl: 'https://api.resend.com'`
+
+## Option 3: Run key-holding code in a separate trusted process
+
+Best when:
+
+- you already have a worker/service boundary
+- you need the provider SDK exactly as-is
+- you want process-level separation without introducing a local HTTP proxy
+
+Pattern:
+
+1. trusted process loads `AGENT_PRIV_KEY`
+2. trusted process creates `identity`, then `agent`
+3. untrusted process calls into the trusted process over RPC, IPC, or a queue
+
+The important part is not the transport. The important part is that the untrusted runtime never gets plaintext credentials and never gets `identity`.
+
+## Decision guide
+
+Use this order:
+
+1. If the SDK supports custom `fetch`, use `createFetchWithAuth(...)`.
+2. If you only need HTTP calls, use `fetchWithAuth(...)` directly.
+3. If the SDK only accepts a raw key, use a trusted proxy or separate trusted process.
+
+Avoid:
+
+- `identity.getSecret(...)` inside agent logic
+- passing plaintext API keys into prompts, tools, or third-party SDK constructors
+- loading `AGENT_PRIV_KEY` in the same process as untrusted tools or model-driven code

package/docs/es/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+Runtime Node.js para caja de identidad y credenciales cbio. Solo biblioteca, sin CLI ni TUI.
+
+Importa y usa `CbioIdentity`, `CbioAgent` desde el export principal.
+
+## Instalación
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## Uso
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## Compilación
+
+```bash
+npm run build
+npm run test
+```

package/docs/fr/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+Runtime Node.js pour le coffre d'identité et de credentials cbio. Bibliothèque uniquement, pas de CLI ni TUI.
+
+Importez et utilisez `CbioIdentity`, `CbioAgent` depuis l'export principal.
+
+## Installation
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## Utilisation
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## Compilation
+
+```bash
+npm run build
+npm run test
+```

package/docs/ja/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+cbio アイデンティティと credential vault の Node.js ランタイム。ライブラリのみ、CLI / TUI なし。
+
+メインエクスポートから `CbioIdentity`、`CbioAgent` をインポートして使用。
+
+## インストール
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## 使用例
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## ビルド
+
+```bash
+npm run build
+npm run test
+```

package/docs/ko/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+cbio identity 및 credential vault용 Node.js 런타임. 라이브러리만 제공, CLI/TUI 없음.
+
+메인 export에서 `CbioIdentity`, `CbioAgent`를 import하여 사용.
+
+## 설치
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## 사용법
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## 빌드
+
+```bash
+npm run build
+npm run test
+```

package/docs/pt/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+Runtime Node.js para cofre de identidade e credenciais cbio. Apenas biblioteca, sem CLI ou TUI.
+
+Importe e use `CbioIdentity`, `CbioAgent` do export principal.
+
+## Instalação
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## Uso
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## Compilação
+
+```bash
+npm run build
+npm run test
+```

package/docs/spec/runtime/README.md

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