@the-ai-company/cbio-node-runtime 1.46.0 → 1.47.2

package/docs/CUSTODY_MODEL.md

@@ -1,148 +1,46 @@
-# Custody Model
+# Custody Model (v1.47.0)
 
-This document defines the intended key and custody model for the local vault runtime.
-
-It exists to remove ambiguity around `owner` identity, secret recovery, and the vault's working-key model.
+This document defines the **Sovereign Vault** custody model for the local vault runtime.
 
 ## Scope
 
-This runtime is a local vault / password-safe style infrastructure layer.
-
-It is not primarily a cloud secret manager.
-It is not a browser extension.
-It is not a CLI.
-
-The runtime is responsible for:
-
-- storing secret material safely at rest
-- using stored secret material during trusted vault operations
-- supporting explicit owner export / reveal operations
-- providing a stable custody model for higher-level products built on top
-
-## Design Goal
-
-The runtime must satisfy all of the following:
-
-1. Normal vault operation must not depend on repeated owner intervention.
-2. Owner must retain explicit recovery and export authority.
-3. Identity proof and secret-material control must not be collapsed into one key by default.
-4. The runtime must not treat a raw process-level string as the final product model.
-
-## Core Terms
-
-### `ownerPrivateKey`
-
-The owner's identity-signing key.
-
-In the current product model, this owner is the single vault admin.
-Other principals should be modeled as agents with capabilities rather than additional owners.
+The runtime is an authority-centric "password safe" style infrastructure. It is responsible for:
+- Storing secret material safely at rest.
+- Providing a **Managed Custody** home for agent identities.
+- Centering all administrative authority on a master password.
 
-Purpose:
+## Design Goals
 
-- prove "this request came from the owner"
-- authorize owner-scoped operations
-- bind audit-visible actions to the owner identity
+1. **Authority via Proof of Knowledge**: Access to the vault's root secrets depends on knowing the master password.
+2. **Managed Agency**: The vault can generate and store private keys for its agents, removing the need for external key management by delegated actors.
+3. **Internalized Identity**: Administrative "Ownership" is a byproduct of unlocking the vault, not a pre-registered cryptographic identity.
 
-Non-purpose:
+## Core Keys
 
-- not the vault's secret-material root
-- not the working encryption key for stored secrets
-- not the recovery key for vault custody
+### Master Password
+The root of all authority. Used to derive the `vaultWorkingKey`.
 
 ### `vaultWorkingKey`
+The runtime's internal encryption key for all stored material (secrets and registries).
+- **Derivation**: Derived from the Master Password + `vaultId` using `scrypt` (KDF).
+- **Purpose**: Protects the vault profile, secret custody, and agent registries at rest.
 
-The runtime's working secret-material key.
-
-Purpose:
-
-- protect secret material at rest
-- support runtime secret use after the vault is in an operational state
-- back vault-side secret load / decrypt operations
-
-Non-purpose:
-
-- not an owner identity key
-- not a user-facing day-to-day API credential
-- not the preferred recovery artifact presented to the owner
-
-## Current Runtime Surface
-
-The persistent runtime surface uses `vaultWorkingKey` as the runtime material-control key.
-The working key is now derived from the owner's private key plus `vaultId` in the high-level runtime path.
+### Managed Agent Keys
+Standard Ed25519 private keys generated and stored *inside* the vault.
+- **Purpose**: Allow agents to sign requests for dispatch without the agent process ever needing to persist its own identity material.
 
 ## Required Separation
 
-The runtime separates two concerns in the high-level path:
-
-1. Identity authority
-   `ownerPrivateKey`
-
-2. Runtime material control
-   `vaultWorkingKey`
-
-This separation is deliberate.
-
-The runtime should not default to a model where one owner signing key directly acts as the encryption root for all stored secret material.
-
-## Owner Relationship To Custody
-
-Owner is the authorization authority for the vault.
-
-Owner is not defined as the same thing as the runtime working key.
-
-Instead:
-
-- owner authorizes actions
-- runtime custody performs storage / load / export work
-- owner retains ultimate recovery and export authority through explicit product mechanisms
-
-In practical terms:
-
-- owner must be able to export secret plaintext through a formal audited interface
-- owner must be able to recover the vault through the owner identity path
-- owner does not need to directly hold the working key during normal runtime operation
+The runtime enforces a hard process boundary (A/B Architecture):
+1. **Security Process (A)**: Holds the Master Password and performs all crypto operations on the `vaultWorkingKey`.
+2. **Agent Process (B)**: Receives a "Managed Identity" (provided by A) to perform authorized dispatches.
 
 ## Export / Reveal Policy
 
-For this runtime family, export is a first-class password-safe capability, not an exception.
-
-That means:
-
-- `exportSecret(...)` is valid product behavior
-- export must be explicit
-- export must be owner-scoped
-- export must be audited
-
-Future hardening such as MFA/TOTP may be added on top of this model, but it does not replace the need to define custody clearly.
-
-## Already Added
-
-The runtime now includes:
-
-1. formal vault creation through `createVault(...)`
-2. owner-identity based re-entry through `recoverVault(...)`
-3. explicit `vaultWorkingKey` terminology in the persistent dependency surface
-4. continued support for explicit owner export through `exportSecret(...)`
-
-## Next
-
-The remaining intended direction is:
-
-1. continue tightening recovery and migration flows
-2. continue reducing low-level helper use in favor of high-level lifecycle entrypoints
-3. keep the custody terminology stable across docs and APIs
-
-## What This Runtime Should Remove
-
-The runtime should move away from these ambiguous product meanings:
-
-- "owner cannot read secrets back"
-- "owner signing key and vault secret-material key are the same by default"
-
-## Non-Goals
-
-This document does not require the runtime to become a cloud KMS product.
+Exporting secret plaintext is a first-class capability of the Sovereign Vault.
+- `exportSecret(...)` is a valid, audited administrative operation.
+- Requires the vault to be in an unlocked (operational) state.
 
-This document also does not require browser, CLI, or MCP concerns to be handled inside the runtime itself.
+## Conclusion
 
-Those layers may consume this runtime, but they do not define the runtime's custody model.
+The Sovereign Vault model prioritizes **Ease of Use** and **Security through Isolation**. By moving away from complex external identity hierarchies, it provides a stable, "password-manager" style experience for automated agency.

package/docs/IDENTITY_MODEL.md

@@ -1,128 +1,50 @@
-# Identity Model
+# Identity Model (v1.47.0)
 
-This document defines the runtime's current identity model.
+This document defines the identity model for the **Sovereign Vault**. 
 
-Its purpose is to separate three things that are easy to confuse:
+## Principle: Authority, Not Identity
 
-- cryptographic identity
-- human-readable naming
-- vault-local role assignment
+The Sovereign Vault model simplifies the relationship between actors and the vault:
 
-## Core Rule
+1. **Administrator (Owner)**: Authority is rooted in **knowledge of the master password**. There is no pre-registered `OwnerIdentity`. If you can unlock the vault, you are the master.
+2. **Delegates (Agents)**: Identities authorized by the master to perform specific tasks.
 
-Outside the vault, there are only identities.
+## Identity Types
 
-Inside a specific vault, identities may be bound to roles such as `owner` or `agent`.
+### 1. External Identity
+A principal represented by a public/private keypair managed *outside* the vault. These are registered by providing a public key.
 
-This means:
+### 2. Managed Identity (New in v1.47.0)
+An identity whose public/private keypair is generated and stored **inside** the vault. 
+- The vault acts as the custodian of the private key.
+- This is the preferred model for preventing lost keys in isolated agent processes.
 
-- `owner` is not a different species of identity
-- `agent` is not a different species of identity
-- role comes from vault-local authorization state, not from the keypair itself
+## Identifying Principals
 
-## Identity
+### Identity ID
+A stable, public-key-derived identifier (via `deriveIdentityId(...)`). 
+- Used for internal registries, capability assignment, and audit logs.
+- Decoupled from human-readable labels.
 
-An `identity` is an external principal represented by a public/private keypair.
+### Nicknames
+Human-friendly labels (e.g., "Main Worker", "Auth Service"). 
+- Stored as metadata within the registry.
+- Purely for display and audit traceability.
 
-Properties:
+## Vault Role: "vault-master"
 
-- root identities are independent
-- child identities may be deterministically derived from a parent identity private key plus a path
-- no built-in inheritance
-- no built-in "owner creates agent identity" relationship
+All administrative operations performed by the password-holder are recorded under the special principal **`vault-master`**. 
 
-An identity may participate in multiple vaults, and may hold different roles in different vaults.
+## What was Removed
 
-Example:
+To achieve the Sovereign Vault's simplicity, the following legacy concepts were removed:
+- **Child Identities**: Deterministic derivation of keys from a parent identity is no longer supported. Use **Managed Identities** instead.
+- **Identity-Private Vaults**: Every identity used to have its own encrypted "mini-vault". This has been replaced by the unified storage of the Sovereign Vault.
 
-- the same identity may be `owner` in vault A
-- and `agent` in vault B
+## Relationship Summary
 
-## Identity Material
-
-The runtime treats public/private keys as the cryptographic identity material.
-
-- `publicKey`
-  used for verification and binding
-- `privateKey`
-  held outside the vault by the identity holder
-
-The vault should not treat a display label as the root identity truth.
-
-## Stable Identity ID
-
-The runtime already has a stable public-key-derived identity primitive available through `deriveIdentityId(...)`.
-
-That derived value is useful for:
-
-- stable machine identity
-- local naming
-- deterministic display-independent references
-
-It should not, by itself, determine vault-local role.
-
-## Labels And Human-Readable Names
-
-Human-friendly names are still useful.
-
-Examples:
-
-- `owner-1`
-- `agent-prod`
-- `crawler`
-- `alice`
-
-These should be treated as labels, aliases, or local names rather than the deepest identity truth.
-
-The runtime now exposes this concept directly as optional `nickname` on `createIdentity(...)`.
-
-For existing private keys, the runtime exposes `restoreIdentity(...)`, which reconstructs the same identity shape from the private key alone.
-
-For child identities, the runtime exposes `createChildIdentity(storage, parentIdentity, { nickname })` for user-facing creation, and `deriveChildIdentity(parentIdentity, childIndex, { nickname })` for deterministic reconstruction when the stored `childIndex` is known. `nickname` remains display-only.
-
-Identity-private state is stored under `vault/private/identities/<identityId>/...` and encrypted with a key derived from that identity's private key. To inspect those records, callers use `readIdentityPrivateVaultProfile(...)` and `readIdentityPrivateVaultChildrenState(...)` with the identity object or private key.
-
-In other words:
-
-- public key or a stable derived id answers "who is this cryptographically"
-- label answers "what do humans call this identity here"
-
-## Vault Roles
-
-Vault roles are authorization bindings applied to identities inside a specific vault.
-
-Current role model:
-
-- `owner`
-  the single admin role for one vault
-- `agent`
-  a delegated role registered and authorized by the owner
-
-These roles are vault-local.
-
-So:
-
-- an identity does not become globally `owner`
-- an identity does not become globally `agent`
-- the same identity may appear with different roles in different vaults
-
-## Current Runtime Reality
-
-Today the runtime API still uses fields such as:
-
-- `ownerId`
-- `agentId`
-
-In practice, these currently behave closer to role-bound local identifiers or labels than to the deepest cryptographic identity root.
-
-The long-term intended direction is:
-
-1. keep cryptographic identity separate from labels
-2. keep vault-local role separate from both
-3. avoid treating naming conventions such as prefixes as identity truth
-
-## Non-Goals
-
-This model does not require every current API field to be renamed immediately.
-
-Its purpose is to define the correct semantics first, so later API changes can converge on one stable interpretation.
+| Actor | Source of Authority | Registry |
+| :--- | :--- | :--- |
+| **Owner** | Master Password | Implicit (via Unlock) |
+| **Managed Agent** | Vault Registry (Internal Key) | `agentIdentities` registry |
+| **External Agent** | External Signer (Public Key) | `agentIdentities` registry |