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

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

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

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

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

@@ -0,0 +1,46 @@
+# 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/zh/README.md

@@ -0,0 +1,27 @@
+# cbio Node Runtime
+
+cbio 身份与凭证保险库的 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/examples/minimal.ts

@@ -0,0 +1,13 @@
+import { CbioIdentity } from '@the-ai-company/agent-identity-sdk';
+
+async function main() {
+  const privateKey = process.env.AGENT_PRIV_KEY!;
+  const identity = await CbioIdentity.load({ privateKey });
+  const agent = identity.getAgent();
+
+  // Use the agent to call external services with automatic authentication
+  const response = await agent.fetchWithAuth('my-service', 'https://api.example.com/data');
+  console.log(await response.json());
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@the-ai-company/cbio-node-runtime",
+  "version": "0.31.0",
+  "description": "Node.js runtime for cbio identity and credential vault. Library only, no CLI or TUI.",
+  "type": "module",
+  "main": "./dist/runtime/index.js",
+  "module": "./dist/runtime/index.js",
+  "types": "./dist/runtime/index.d.ts",
+  "files": [
+    "dist/",
+    "docs/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/runtime/index.js",
+      "types": "./dist/runtime/index.d.ts"
+    },
+    "./protocol": {
+      "import": "./dist/protocol/identity.js",
+      "types": "./dist/protocol/identity.d.ts"
+    },
+    "./sealed": {
+      "import": "./dist/sealed/index.js",
+      "types": "./dist/sealed/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@the-ai-company/cbio-protocol": "^1.0.3"
+  },
+  "scripts": {
+    "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"
+  },
+  "keywords": [
+    "claw-biometric",
+    "agent",
+    "identity",
+    "vault",
+    "secrets",
+    "node-runtime"
+  ],
+  "author": "The AI Company",
+  "license": "MIT",
+  "repository": "https://github.com/TheAICompany/cbio-node-runtime",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}