@the-ai-company/cbio-node-runtime 1.47.0 → 1.48.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -231
- package/dist/clients/agent/client.d.ts +1 -0
- package/dist/clients/agent/client.js +26 -9
- package/dist/clients/agent/client.js.map +1 -1
- package/dist/clients/owner/client.js +57 -2
- package/dist/clients/owner/client.js.map +1 -1
- package/dist/clients/owner/contracts.d.ts +44 -1
- package/dist/vault-core/contracts.d.ts +58 -5
- package/dist/vault-core/contracts.js +8 -0
- package/dist/vault-core/contracts.js.map +1 -1
- package/dist/vault-core/core.d.ts +16 -2
- package/dist/vault-core/core.js +115 -1
- package/dist/vault-core/core.js.map +1 -1
- package/dist/vault-core/defaults.d.ts +25 -3
- package/dist/vault-core/defaults.js +71 -16
- package/dist/vault-core/defaults.js.map +1 -1
- package/dist/vault-core/errors.d.ts +2 -2
- package/dist/vault-core/errors.js.map +1 -1
- package/dist/vault-core/index.d.ts +3 -3
- package/dist/vault-core/index.js +1 -1
- package/dist/vault-core/index.js.map +1 -1
- package/dist/vault-core/persistence.js +7 -2
- package/dist/vault-core/persistence.js.map +1 -1
- package/dist/vault-core/ports.d.ts +13 -0
- package/dist/vault-ingress/index.d.ts +17 -2
- package/dist/vault-ingress/index.js +17 -0
- package/dist/vault-ingress/index.js.map +1 -1
- package/dist/vault-ingress/remote-transport.js +4 -1
- package/dist/vault-ingress/remote-transport.js.map +1 -1
- package/docs/ARCHITECTURE.md +34 -107
- package/docs/CUSTODY_MODEL.md +27 -129
- package/docs/IDENTITY_MODEL.md +35 -112
- package/docs/REFERENCE.md +60 -404
- package/docs/api/README.md +2 -2
- package/docs/api/classes/IdentityError.md +1 -1
- package/docs/api/classes/VaultCore.md +97 -1
- package/docs/api/classes/VaultCoreError.md +3 -3
- package/docs/api/enumerations/IdentityErrorCode.md +1 -1
- package/docs/api/functions/createAgentClient.md +1 -1
- package/docs/api/functions/createIdentity.md +1 -1
- package/docs/api/functions/createOwnerHttpFlowBoundary.md +1 -1
- package/docs/api/functions/createPersistentVaultCoreDependencies.md +1 -1
- package/docs/api/functions/createStandardAcquireBoundary.md +1 -1
- package/docs/api/functions/createStandardDispatchBoundary.md +1 -1
- package/docs/api/functions/createVault.md +1 -1
- package/docs/api/functions/createVaultClient.md +1 -1
- package/docs/api/functions/createVaultCore.md +1 -1
- package/docs/api/functions/createVaultCoreDependencies.md +1 -1
- package/docs/api/functions/createVaultService.md +1 -1
- package/docs/api/functions/createWorkspaceStorage.md +1 -1
- package/docs/api/functions/deriveIdentityId.md +1 -1
- package/docs/api/functions/deriveVaultWorkingKeyFromPassword.md +1 -1
- package/docs/api/functions/getDefaultWorkspaceDir.md +1 -1
- package/docs/api/functions/handleVaultHttpDispatch.md +1 -1
- package/docs/api/functions/initializeVaultCustody.md +1 -1
- package/docs/api/functions/listVaults.md +1 -1
- package/docs/api/functions/readVaultProfile.md +1 -1
- package/docs/api/functions/recoverVault.md +1 -1
- package/docs/api/functions/recoverVaultWorkingKey.md +1 -1
- package/docs/api/functions/restoreIdentity.md +1 -1
- package/docs/api/functions/updateVaultMetadata.md +1 -1
- package/docs/api/functions/wrapVaultCoreAsVaultService.md +1 -1
- package/docs/api/functions/writeVaultProfile.md +1 -1
- package/docs/api/interfaces/AgentClient.md +1 -1
- package/docs/api/interfaces/AgentDispatchIntent.md +1 -1
- package/docs/api/interfaces/AgentDispatchTransport.md +1 -1
- package/docs/api/interfaces/AgentIdentity.md +1 -1
- package/docs/api/interfaces/AgentSigner.md +1 -1
- package/docs/api/interfaces/CbioRuntime.md +1 -1
- package/docs/api/interfaces/CreateAgentClientOptions.md +7 -1
- package/docs/api/interfaces/CreateIdentityOptions.md +1 -1
- package/docs/api/interfaces/CreatePersistentVaultCoreDependenciesOptions.md +31 -1
- package/docs/api/interfaces/CreateVaultClientOptions.md +1 -1
- package/docs/api/interfaces/CreateVaultOptions.md +31 -1
- package/docs/api/interfaces/CreatedVault.md +1 -1
- package/docs/api/interfaces/DefaultPolicyEngineOptions.md +1 -1
- package/docs/api/interfaces/IStorageProvider.md +1 -1
- package/docs/api/interfaces/InitializeVaultCustodyOptions.md +1 -1
- package/docs/api/interfaces/InitializedVaultCustody.md +1 -1
- package/docs/api/interfaces/OwnerDefineSecretTargetsInput.md +1 -1
- package/docs/api/interfaces/OwnerSecretTargetBinding.md +1 -1
- package/docs/api/interfaces/OwnerStoreSecretInput.md +1 -1
- package/docs/api/interfaces/OwnerWriteSecretInput.md +1 -1
- package/docs/api/interfaces/RecoverVaultOptions.md +31 -1
- package/docs/api/interfaces/RecoveredVault.md +1 -1
- package/docs/api/interfaces/RestoreIdentityOptions.md +1 -1
- package/docs/api/interfaces/Signer.md +1 -1
- package/docs/api/interfaces/VaultAuditQueryInput.md +1 -1
- package/docs/api/interfaces/VaultClient.md +1 -1
- package/docs/api/interfaces/VaultCoreDependenciesOptions.md +19 -1
- package/docs/api/interfaces/VaultCreateAgentInput.md +1 -1
- package/docs/api/interfaces/VaultDeleteSecretInput.md +1 -1
- package/docs/api/interfaces/VaultExportSecretInput.md +1 -1
- package/docs/api/interfaces/VaultGrantCapabilityInput.md +71 -3
- package/docs/api/interfaces/VaultIdentity.md +1 -1
- package/docs/api/interfaces/VaultListAgentsInput.md +1 -1
- package/docs/api/interfaces/VaultListCapabilitiesInput.md +1 -1
- package/docs/api/interfaces/VaultMetadata.md +1 -1
- package/docs/api/interfaces/VaultObject.md +1 -1
- package/docs/api/interfaces/VaultProfile.md +1 -1
- package/docs/api/interfaces/VaultRegisterAgentInput.md +1 -1
- package/docs/api/interfaces/VaultRegisterFlowInput.md +1 -1
- package/docs/api/interfaces/VaultRevokeCapabilityInput.md +1 -1
- package/docs/api/interfaces/VaultSigner.md +1 -1
- package/docs/api/type-aliases/AgentCapabilityEnvelope.md +1 -1
- package/docs/api/type-aliases/CbioRuntimeModule.md +1 -1
- package/docs/api/variables/DEFAULT_VAULT_KEY_CUSTODY_BLOB_KEY.md +1 -1
- package/docs/zh/README.md +64 -39
- package/package.json +1 -1
package/docs/REFERENCE.md
CHANGED
|
@@ -1,428 +1,84 @@
|
|
|
1
|
-
# CBIO Vault Runtime Reference
|
|
1
|
+
# CBIO Vault Runtime Reference (v1.47.2)
|
|
2
2
|
|
|
3
|
-
This document describes the current implemented runtime surface
|
|
3
|
+
This document describes the current implemented runtime surface for the **Sovereign Vault**.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Primary API Surface
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The v1.47.2 runtime centers on a simplified, authority-centric model with managed agency and session tokens.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
### Main Constructors and Entrypoints
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
11
|
+
- `createVault(...)` - Initialize a new vault using a master password.
|
|
12
|
+
- `recoverVault(...)` - Reopen an existing vault using its master password.
|
|
13
|
+
- `listVaults(...)` - Scan the workspace for available vault IDs.
|
|
14
|
+
- `updateVaultMetadata(...)` - Update the nickname or other metadata of an unlocked vault.
|
|
15
|
+
- `createVaultClient(...)` - Create an administrative client for an unlocked vault.
|
|
16
|
+
- `createAgentClient(...)` - Create a delegated client for an agent.
|
|
17
|
+
- `createIdentity(...)` - Generate a standalone cryptographic identity keypair.
|
|
18
|
+
- `restoreIdentity(...)` - Restore an identity from a private key.
|
|
15
19
|
|
|
16
|
-
|
|
20
|
+
### Vault Lifecycle
|
|
17
21
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- `
|
|
21
|
-
- `
|
|
22
|
-
- `readIdentityPrivateVaultProfile(...)`
|
|
23
|
-
- `readIdentityPrivateVaultChildrenState(...)`
|
|
24
|
-
- `restoreIdentity(...)`
|
|
25
|
-
- `createVault(...)`
|
|
26
|
-
- `recoverVault(...)`
|
|
27
|
-
- `createVaultClient(...)`
|
|
28
|
-
- `createAgentClient(...)`
|
|
22
|
+
#### `createVault(storage, { vaultId, password, nickname, metadata })`
|
|
23
|
+
Creates a secure vault.
|
|
24
|
+
- **Authority**: Rooted in the `password`.
|
|
25
|
+
- **Storage**: All data is encrypted using a key derived from the password via `scrypt`.
|
|
29
26
|
|
|
30
|
-
|
|
27
|
+
#### `recoverVault(storage, { vaultId, password })`
|
|
28
|
+
Unlocks and reopens a vault.
|
|
29
|
+
- Returns a `RecoveredVault` object containing the `VaultService` and metadata.
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
#### `listVaults(storage)`
|
|
32
|
+
Returns a `string[]` of vault IDs found in the storage.
|
|
33
|
+
- **Privacy**: No metadata (like nicknames) is leaked during listing. You must recover a vault to see its details.
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
## Identity Models
|
|
35
36
|
|
|
36
|
-
|
|
37
|
-
|
|
37
|
+
### 1. Managed Identity (Recommended)
|
|
38
|
+
Identity material (private keys) generated and stored securely within the vault's own registry.
|
|
39
|
+
- Use `client.createAgent(...)` to manage these.
|
|
40
|
+
- **Session Tokens**: Owners can issue revocable `sat_...` tokens for managed agents to enable stateless authentication without raw private keys.
|
|
38
41
|
|
|
39
|
-
|
|
42
|
+
### 2. External Identity
|
|
43
|
+
Identity material managed by the user outside the vault. Registered via `client.registerAgent({ publicKey, ... })`.
|
|
40
44
|
|
|
41
|
-
|
|
45
|
+
## Vault Client (Owner/Admin)
|
|
42
46
|
|
|
43
|
-
|
|
47
|
+
The `VaultClient` provides the administrative interface for the vault.
|
|
44
48
|
|
|
45
|
-
|
|
49
|
+
### Core Operations
|
|
50
|
+
- `writeSecret(...)`: Store a secret and bind it to specific targets in one step.
|
|
51
|
+
- `createAgent(...)`: Generate and host a new agent identity.
|
|
52
|
+
- `listAgents()`: Enumerate authorized agents and retrieve managed private keys.
|
|
53
|
+
- `grantCapability(...)`: Assign specific secret-use permissions to an agent.
|
|
54
|
+
- `issueSessionToken(...)`: Generate a revocable session token for a managed agent.
|
|
55
|
+
- `revokeSessionToken(...)`: Immediately invalidate a previously issued session token.
|
|
56
|
+
- `exportSecret(...)`: Reveal a secret's plaintext (requires active authority).
|
|
57
|
+
- `readAudit(...)`: Access the append-only record of all vault actions.
|
|
46
58
|
|
|
47
|
-
|
|
59
|
+
## Agent Client (Consumer)
|
|
48
60
|
|
|
49
|
-
|
|
50
|
-
- **Workspace Storage**: The initial storage passed to the SDK (or the default one) points to the root of all vaults.
|
|
51
|
-
- **Vault Storage**: The storage returned by `createVault` / `recoverVault` is already scoped. You should pass this scoped storage to subsequent calls like `listIdentities` or `updateVaultMetadata`.
|
|
52
|
-
- **Warning**: Do not manually attempt to read files like `working-key.sealed` relative to the workspace root if you are using high-level SDK methods. The SDK handles these paths relative to the anchored storage.
|
|
61
|
+
The `AgentClient` is used by delegated processes (e.g., LLMs or background workers) to perform authorized actions.
|
|
53
62
|
|
|
54
|
-
###
|
|
63
|
+
### Core Operations
|
|
64
|
+
- `dispatch(...)`: Use a granted capability to send a secret to an authorized target.
|
|
65
|
+
- **Security**: The agent never handles the vault's master password. By using **Session Tokens**, the agent also avoids handling its own raw private key in memory.
|
|
55
66
|
|
|
56
|
-
|
|
67
|
+
## Storage Layout
|
|
57
68
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
## Terms
|
|
66
|
-
|
|
67
|
-
- `identity`
|
|
68
|
-
An external principal represented by a public/private keypair.
|
|
69
|
-
- `owner`
|
|
70
|
-
The single admin role that a vault binds to one identity.
|
|
71
|
-
- `agent`
|
|
72
|
-
A delegated role that a vault binds to an identity registered by the owner.
|
|
73
|
-
|
|
74
|
-
Role rules:
|
|
75
|
-
|
|
76
|
-
- outside the vault there are only identities
|
|
77
|
-
- inside a vault, identities are bound to roles such as `owner` or `agent`
|
|
78
|
-
- root identities are independent
|
|
79
|
-
- child identities may be deterministically derived from a parent identity
|
|
80
|
-
- the same identity may be `owner` in one vault and `agent` in another
|
|
81
|
-
|
|
82
|
-
## Identity Creation
|
|
83
|
-
|
|
84
|
-
`createIdentity(...)` returns:
|
|
85
|
-
|
|
86
|
-
- `identityId`
|
|
87
|
-
- `publicKey`
|
|
88
|
-
- `privateKey`
|
|
89
|
-
- optional `nickname`
|
|
90
|
-
- optional `parentIdentityId` for child identities
|
|
91
|
-
- optional `childIndex` for child identities
|
|
92
|
-
|
|
93
|
-
`nickname` is human-readable only. It does not affect the derived `identityId`, cryptographic verification, or vault-local role binding.
|
|
94
|
-
|
|
95
|
-
`createChildIdentity(storage, parentIdentity, { nickname })` allocates the next `childIndex` from storage and creates a child identity.
|
|
96
|
-
|
|
97
|
-
`deriveChildIdentity(parentIdentity, childIndex, { nickname })` deterministically reconstructs a child identity for a known `childIndex`.
|
|
98
|
-
|
|
99
|
-
`ensureIdentityPrivateVault(storage, identity)` creates or refreshes the identity's fixed namespace under `identities/<identityId>/...`.
|
|
100
|
-
|
|
101
|
-
That namespace stores identity-level files such as:
|
|
102
|
-
|
|
103
|
-
- `sealed/profile.sealed`
|
|
104
|
-
- `sealed/children.sealed`
|
|
105
|
-
|
|
106
|
-
Those files are encrypted at rest in the `sealed/` sub-directory and are not readable as plain JSON on disk.
|
|
107
|
-
|
|
108
|
-
Identities also maintain a **public discovery area**. This region is encrypted with a key derived from the identity ID, making it accessible via the API without the owner's private key, while ensuring all data on disk remains fully encrypted and tamper-resistant.
|
|
109
|
-
|
|
110
|
-
`restoreIdentity(privateKey)` returns the same shape for an existing private key.
|
|
111
|
-
|
|
112
|
-
`readIdentityPrivateVaultProfile(storage, identityOrPrivateKey)` decrypts and returns the current identity profile for the supplied identity or private key.
|
|
113
|
-
|
|
114
|
-
`readIdentityPrivateVaultChildrenState(storage, identityOrPrivateKey)` decrypts and returns the child index state for the supplied identity or private key.
|
|
115
|
-
|
|
116
|
-
`readIdentityMetadata(storage, identityId, [privateKey])` is the unified metadata reader.
|
|
117
|
-
If `privateKey` is provided, it returns the full sealed profile.
|
|
118
|
-
If `privateKey` is missing, it returns the public discovery profile (`IdentityPublicProfile`).
|
|
119
|
-
|
|
120
|
-
`listIdentities(storage)` returns `Promise<IdentityPublicProfile[]>`. These profiles are automatically verified for signature integrity.
|
|
121
|
-
|
|
122
|
-
`listVaults(storage)` returns `Promise<Array<{ vaultId: string; public: VaultPublicMetadata }>>`. These summaries are pulled from the public signed profiles and verified.
|
|
123
|
-
|
|
124
|
-
Typical relationship lookup flow when you already have a private key:
|
|
125
|
-
|
|
126
|
-
1. `const identity = restoreIdentity(privateKey)`
|
|
127
|
-
2. `const profile = await readIdentityPrivateVaultProfile(storage, identity)`
|
|
128
|
-
3. `const children = await readIdentityPrivateVaultChildrenState(storage, identity)`
|
|
129
|
-
|
|
130
|
-
`profile.parentIdentityId` tells you whether the identity is a child. `children.children` tells you which child identities were created beneath that identity.
|
|
131
|
-
|
|
132
|
-
## Secret-Flow Model
|
|
133
|
-
|
|
134
|
-
The current HTTP-facing API supports two explicit secret-flow classes:
|
|
69
|
+
The vault uses a unified encrypted partition:
|
|
70
|
+
- `vault/sealed/profile.sealed`: Unified vault profile.
|
|
71
|
+
- `vault/sealed/secrets.sealed`: Secret registry.
|
|
72
|
+
- `vault/sealed/custody/`: Encrypted secret material.
|
|
73
|
+
- `vault/sealed/identities/`: Agent and capability registries.
|
|
135
74
|
|
|
136
|
-
|
|
137
|
-
No secret leaves the vault. A response-derived secret is stored into the vault. Agent-visible output is limited to protocol metadata and a redacted response shape.
|
|
75
|
+
## Build & Integration
|
|
138
76
|
|
|
139
|
-
|
|
140
|
-
|
|
77
|
+
Ensure you are using the latest distribution:
|
|
78
|
+
- `dist/runtime/index.js`
|
|
79
|
+
- `dist/runtime/index.d.ts`
|
|
141
80
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
- dispatch responses are treated as ordinary HTTP results once the owner has authorized sending the secret to that target
|
|
146
|
-
|
|
147
|
-
The runtime does not try to reinterpret every remote protocol. If an approved target returns sensitive values during a normal dispatch call, that is part of the target contract and owner authorization scope rather than a vault-side parsing obligation.
|
|
148
|
-
|
|
149
|
-
The runtime does not claim to understand arbitrary network protocols. The API communicates only the currently supported boundary:
|
|
150
|
-
|
|
151
|
-
- supported: explicit acquisition into vault through built-in standard flows
|
|
152
|
-
- supported: explicit secret-backed outbound dispatch
|
|
153
|
-
- supported: owner-defined `custom_http` flows for explicit exception cases
|
|
154
|
-
- unsupported: mixed bidirectional-secret flows as a first-class surface
|
|
155
|
-
- unsupported: no-secret operations as a first-class vault primitive
|
|
156
|
-
|
|
157
|
-
## Vault Client
|
|
158
|
-
|
|
159
|
-
`clients/owner` implements the public vault-management client surface for the identity currently bound to the vault's single admin role.
|
|
160
|
-
|
|
161
|
-
Current management operations:
|
|
162
|
-
|
|
163
|
-
- `storeSecret(...)`
|
|
164
|
-
- `defineSecretTargets(...)`
|
|
165
|
-
- `writeSecret(...)`
|
|
166
|
-
- `deleteSecret(...)`
|
|
167
|
-
- `exportSecret(...)`
|
|
168
|
-
- `readAudit(...)`
|
|
169
|
-
- `registerAgent(...)`
|
|
170
|
-
- `listAgents()`
|
|
171
|
-
- `grantCapability(...)`
|
|
172
|
-
- `listCapabilities(...)`
|
|
173
|
-
- `revokeCapability(...)`
|
|
174
|
-
- `registerFlow(...)`
|
|
175
|
-
|
|
176
|
-
Example:
|
|
177
|
-
|
|
178
|
-
```ts
|
|
179
|
-
const client = createVaultClient({ ownerIdentity, vault });
|
|
180
|
-
|
|
181
|
-
const storedSecret = await client.storeSecret({
|
|
182
|
-
alias: 'api-token',
|
|
183
|
-
plaintext: 'secret-value',
|
|
184
|
-
});
|
|
185
|
-
|
|
186
|
-
await client.defineSecretTargets({
|
|
187
|
-
alias: storedSecret.alias.value,
|
|
188
|
-
targetBindings: [
|
|
189
|
-
{
|
|
190
|
-
kind: 'site',
|
|
191
|
-
targetId: 'api.example.com',
|
|
192
|
-
targetUrl: 'https://api.example.com/endpoint',
|
|
193
|
-
methods: ['POST'],
|
|
194
|
-
},
|
|
195
|
-
],
|
|
196
|
-
});
|
|
197
|
-
|
|
198
|
-
await client.registerAgent({
|
|
199
|
-
agentId: 'agent-1',
|
|
200
|
-
publicKey: agentPublicKey,
|
|
201
|
-
});
|
|
202
|
-
|
|
203
|
-
await client.registerFlow({
|
|
204
|
-
flowId: 'custom-status-read',
|
|
205
|
-
mode: 'send_secret',
|
|
206
|
-
targetUrl: 'https://api.example.com/custom-status',
|
|
207
|
-
method: 'POST',
|
|
208
|
-
responseVisibility: 'shape_only',
|
|
209
|
-
});
|
|
210
|
-
|
|
211
|
-
await client.writeSecret({
|
|
212
|
-
alias: 'secondary-token',
|
|
213
|
-
plaintext: 'secret-value',
|
|
214
|
-
targetBindings: [
|
|
215
|
-
{
|
|
216
|
-
kind: 'site',
|
|
217
|
-
targetId: 'api.example.com',
|
|
218
|
-
targetUrl: 'https://api.example.com/endpoint',
|
|
219
|
-
methods: ['POST'],
|
|
220
|
-
},
|
|
221
|
-
],
|
|
222
|
-
});
|
|
223
|
-
|
|
224
|
-
const exportedSecret = await client.exportSecret({
|
|
225
|
-
alias: 'api-token',
|
|
226
|
-
});
|
|
227
|
-
|
|
228
|
-
await client.deleteSecret({
|
|
229
|
-
alias: 'secondary-token',
|
|
230
|
-
});
|
|
81
|
+
For a full generated API reference, run:
|
|
82
|
+
```bash
|
|
83
|
+
npm run build:docs
|
|
231
84
|
```
|
|
232
|
-
|
|
233
|
-
`writeSecret(...)` is the one-step variant and requires `targetBindings`.
|
|
234
|
-
|
|
235
|
-
## Agent Client
|
|
236
|
-
|
|
237
|
-
`clients/agent` creates signed dispatch requests for an identity currently bound to an agent role in that vault. It never receives plaintext secrets.
|
|
238
|
-
|
|
239
|
-
Current dispatch capabilities use `dispatch_http` as the explicit secret-send operation.
|
|
240
|
-
It is intended for standard secret-backed resource access, not for token mint / refresh / exchange / registration-finalize style acquisition flows.
|
|
241
|
-
|
|
242
|
-
The runtime also supports `custom_http` as an owner-defined exception path. A `custom_http` capability must reference a registered `customFlowId`.
|
|
243
|
-
Owner-defined HTTP boundaries share one factory layer:
|
|
244
|
-
|
|
245
|
-
- `createOwnerHttpFlowBoundary(...)`
|
|
246
|
-
- `createStandardAcquireBoundary(...)`
|
|
247
|
-
- `createStandardDispatchBoundary(...)`
|
|
248
|
-
|
|
249
|
-
The owner-defined flow may use one of three modes:
|
|
250
|
-
|
|
251
|
-
- `acquire_secret`
|
|
252
|
-
- `send_secret`
|
|
253
|
-
- `bidirectional_secret`
|
|
254
|
-
|
|
255
|
-
Example:
|
|
256
|
-
|
|
257
|
-
```ts
|
|
258
|
-
const capability = {
|
|
259
|
-
vaultId: vault.vaultId,
|
|
260
|
-
capabilityId: 'cap-1',
|
|
261
|
-
agentId: agentIdentity.identityId,
|
|
262
|
-
secretAliases: ['api-token'],
|
|
263
|
-
operation: 'dispatch_http',
|
|
264
|
-
allowedTargets: ['https://api.example.com/endpoint'],
|
|
265
|
-
allowedMethods: ['POST'],
|
|
266
|
-
issuedAt: new Date().toISOString(),
|
|
267
|
-
};
|
|
268
|
-
|
|
269
|
-
await client.grantCapability({ capability });
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
The public agent capability type is the same shape as core `AgentCapability`, so `custom_http` capabilities are valid here too.
|
|
273
|
-
|
|
274
|
-
Custom capability example:
|
|
275
|
-
|
|
276
|
-
```ts
|
|
277
|
-
const customCapability = {
|
|
278
|
-
vaultId: vault.vaultId,
|
|
279
|
-
capabilityId: 'cap-custom',
|
|
280
|
-
agentId: agentIdentity.identityId,
|
|
281
|
-
customFlowId: 'custom-status-read',
|
|
282
|
-
secretAliases: ['api-token'],
|
|
283
|
-
operation: 'custom_http',
|
|
284
|
-
allowedTargets: ['https://api.example.com/custom-status'],
|
|
285
|
-
allowedMethods: ['POST'],
|
|
286
|
-
issuedAt: new Date().toISOString(),
|
|
287
|
-
};
|
|
288
|
-
|
|
289
|
-
await client.grantCapability({ capability: customCapability });
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
Recommended agent client shape:
|
|
293
|
-
|
|
294
|
-
```ts
|
|
295
|
-
const agent = createAgentClient({
|
|
296
|
-
agentIdentity,
|
|
297
|
-
capability,
|
|
298
|
-
vault,
|
|
299
|
-
});
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
## Acquisition Result Shape
|
|
303
|
-
|
|
304
|
-
`acquireSecret(...)` is the explicit acquisition operation.
|
|
305
|
-
|
|
306
|
-
It no longer accepts an open-ended extractor callback. The current surface only supports built-in protocol flows:
|
|
307
|
-
|
|
308
|
-
- `oauth_token_response.access_token`
|
|
309
|
-
- `oauth_token_response.refresh_token`
|
|
310
|
-
- `openid_token_response.id_token`
|
|
311
|
-
|
|
312
|
-
Input:
|
|
313
|
-
|
|
314
|
-
```ts
|
|
315
|
-
const acquireBoundary = createStandardAcquireBoundary({
|
|
316
|
-
targetUrl: 'https://issuer.example.com/token',
|
|
317
|
-
responseField: 'access_token',
|
|
318
|
-
storeAlias: 'issuer-token',
|
|
319
|
-
});
|
|
320
|
-
|
|
321
|
-
const acquired = await vault.acquireSecret({
|
|
322
|
-
alias: acquireBoundary.responseSecret.storeAlias,
|
|
323
|
-
issuerId: 'issuer-1',
|
|
324
|
-
url: acquireBoundary.targetUrl,
|
|
325
|
-
flow: 'oauth_token_response.access_token',
|
|
326
|
-
method: acquireBoundary.method,
|
|
327
|
-
});
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
Output:
|
|
331
|
-
|
|
332
|
-
```ts
|
|
333
|
-
type VaultAcquireSecretResult = {
|
|
334
|
-
vaultId: VaultId;
|
|
335
|
-
alias: string;
|
|
336
|
-
status: 'stored';
|
|
337
|
-
responseStatus: number;
|
|
338
|
-
contentType: string | null;
|
|
339
|
-
responseShape: RedactedResponseShape;
|
|
340
|
-
};
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
`responseShape` is flow-specific. It preserves only the protocol-defined non-sensitive fields that the runtime explicitly allows for that built-in flow.
|
|
344
|
-
|
|
345
|
-
Example:
|
|
346
|
-
|
|
347
|
-
```ts
|
|
348
|
-
{
|
|
349
|
-
token_type: 'Bearer',
|
|
350
|
-
expires_in: 3600,
|
|
351
|
-
scope: 'read write',
|
|
352
|
-
}
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
## Dispatch Result Shape
|
|
356
|
-
|
|
357
|
-
`dispatch_http` returns normal remote output:
|
|
358
|
-
|
|
359
|
-
```ts
|
|
360
|
-
type DispatchResult = {
|
|
361
|
-
vaultId: VaultId;
|
|
362
|
-
requestId: string;
|
|
363
|
-
status: 'succeeded' | 'denied' | 'failed';
|
|
364
|
-
targetUrl: string;
|
|
365
|
-
method: string;
|
|
366
|
-
responseStatus?: number;
|
|
367
|
-
responseBody?: string;
|
|
368
|
-
error?: string;
|
|
369
|
-
};
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
This is an intentional current-surface choice: `dispatch_http` is treated as secret-out / non-secret-in.
|
|
373
|
-
|
|
374
|
-
In other words, the vault respects the standard HTTP response surface for normal dispatch. It does not attempt to retroactively sanitize every downstream response body, because doing so would shift responsibility away from the target protocol and the owner's authorization decision.
|
|
375
|
-
|
|
376
|
-
For `custom_http`, response visibility is chosen by the owner at flow registration time:
|
|
377
|
-
|
|
378
|
-
- `passthrough`: return the remote body
|
|
379
|
-
- `shape_only`: return a redacted shape-only body
|
|
380
|
-
|
|
381
|
-
If the custom flow mode includes secret acquisition, the owner also defines a response secret rule. The current built-in rule shape is:
|
|
382
|
-
|
|
383
|
-
```ts
|
|
384
|
-
{
|
|
385
|
-
kind: 'json_field',
|
|
386
|
-
field: 'access_token',
|
|
387
|
-
storeAlias: 'new-token',
|
|
388
|
-
}
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
## Public-Ready Discovery (Encrypted)
|
|
392
|
-
|
|
393
|
-
The CBIO Node Runtime implements a **Public-Ready Encryption** model for discovery metadata. This allows public information (like nicknames) to be accessible via the API without requiring a private key, while ensuring all data on disk is encrypted.
|
|
394
|
-
|
|
395
|
-
- **Storage**: Managed internally within the `sealed/` directory.
|
|
396
|
-
- **Integrity**: These files are encrypted using a key derived from the Vault or Identity ID (`sha256(cbio:vault-public-metadata:v1 + id)`). This provides tamper-resistance and ensures that the file content remains a black box on disk.
|
|
397
|
-
- **Verification**: The SDK automatically derives the required discovery keys during `listVaults`, `listIdentities`, and retrieval. Corrupted or tampered files are identified by the cryptographic layer and safely ignored.
|
|
398
|
-
|
|
399
|
-
## Persistent Dependencies
|
|
400
|
-
|
|
401
|
-
`createPersistentVaultCoreDependencies(...)` builds a file-backed single-node profile under `vault/sealed/` with:
|
|
402
|
-
|
|
403
|
-
- persistent secret metadata
|
|
404
|
-
- sealed secret custody blobs
|
|
405
|
-
- append-only tamper-evident audit
|
|
406
|
-
- persistent replay guard
|
|
407
|
-
- persistent rate-limit state
|
|
408
|
-
- persistent capability revocation state
|
|
409
|
-
- persistent owner identity record
|
|
410
|
-
- persistent agent identity registry
|
|
411
|
-
- persistent capability registry
|
|
412
|
-
|
|
413
|
-
## Storage Provider
|
|
414
|
-
|
|
415
|
-
Any backend can be used by implementing `IStorageProvider`:
|
|
416
|
-
|
|
417
|
-
```ts
|
|
418
|
-
export interface IStorageProvider {
|
|
419
|
-
read(key: string): Promise<Buffer | null>;
|
|
420
|
-
write(key: string, data: Buffer): Promise<void>;
|
|
421
|
-
delete(key: string): Promise<void>;
|
|
422
|
-
has(key: string): Promise<boolean>;
|
|
423
|
-
rename?(fromKey: string, toKey: string): Promise<void>;
|
|
424
|
-
withLock?<T>(key: string, task: () => Promise<T>): Promise<T>;
|
|
425
|
-
}
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
`withLock(...)` is used when present to serialize read-modify-write persistence sequences.
|
package/docs/api/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
[**CBIO Node Runtime Agent API v1.
|
|
1
|
+
[**CBIO Node Runtime Agent API v1.48.1**](../README.md)
|
|
2
2
|
|
|
3
3
|
***
|
|
4
4
|
|
|
@@ -37,6 +37,22 @@ This is the primary implementation of the Vault logic.
|
|
|
37
37
|
|
|
38
38
|
## Methods
|
|
39
39
|
|
|
40
|
+
### approveDispatch()
|
|
41
|
+
|
|
42
|
+
> **approveDispatch**(`command`): `Promise`\<`DispatchResult`\>
|
|
43
|
+
|
|
44
|
+
#### Parameters
|
|
45
|
+
|
|
46
|
+
##### command
|
|
47
|
+
|
|
48
|
+
`OwnerApproveDispatchCommand`
|
|
49
|
+
|
|
50
|
+
#### Returns
|
|
51
|
+
|
|
52
|
+
`Promise`\<`DispatchResult`\>
|
|
53
|
+
|
|
54
|
+
***
|
|
55
|
+
|
|
40
56
|
### authorizeDispatch()
|
|
41
57
|
|
|
42
58
|
> **authorizeDispatch**(`request`): `Promise`\<`DispatchAuthorization`\>
|
|
@@ -173,6 +189,22 @@ This is the primary implementation of the Vault logic.
|
|
|
173
189
|
|
|
174
190
|
***
|
|
175
191
|
|
|
192
|
+
### issueAgentSessionToken()
|
|
193
|
+
|
|
194
|
+
> **issueAgentSessionToken**(`request`): `Promise`\<`OwnerSessionToken`\>
|
|
195
|
+
|
|
196
|
+
#### Parameters
|
|
197
|
+
|
|
198
|
+
##### request
|
|
199
|
+
|
|
200
|
+
`OwnerIssueSessionTokenRequest`
|
|
201
|
+
|
|
202
|
+
#### Returns
|
|
203
|
+
|
|
204
|
+
`Promise`\<`OwnerSessionToken`\>
|
|
205
|
+
|
|
206
|
+
***
|
|
207
|
+
|
|
176
208
|
### listAgents()
|
|
177
209
|
|
|
178
210
|
> **listAgents**(`actor`, `request?`): `Promise`\<readonly `AgentIdentityRecord`[]\>
|
|
@@ -217,6 +249,28 @@ This is the primary implementation of the Vault logic.
|
|
|
217
249
|
|
|
218
250
|
***
|
|
219
251
|
|
|
252
|
+
### listPendingDispatches()
|
|
253
|
+
|
|
254
|
+
> **listPendingDispatches**(`command`): `Promise`\<readonly `PendingDispatchRecord`[]\>
|
|
255
|
+
|
|
256
|
+
#### Parameters
|
|
257
|
+
|
|
258
|
+
##### command
|
|
259
|
+
|
|
260
|
+
###### owner
|
|
261
|
+
|
|
262
|
+
`VaultPrincipal`
|
|
263
|
+
|
|
264
|
+
###### vaultId
|
|
265
|
+
|
|
266
|
+
`VaultId`
|
|
267
|
+
|
|
268
|
+
#### Returns
|
|
269
|
+
|
|
270
|
+
`Promise`\<readonly `PendingDispatchRecord`[]\>
|
|
271
|
+
|
|
272
|
+
***
|
|
273
|
+
|
|
220
274
|
### registerAgentIdentity()
|
|
221
275
|
|
|
222
276
|
> **registerAgentIdentity**(`command`): `Promise`\<`void`\>
|
|
@@ -265,6 +319,48 @@ This is the primary implementation of the Vault logic.
|
|
|
265
319
|
|
|
266
320
|
***
|
|
267
321
|
|
|
322
|
+
### rejectDispatch()
|
|
323
|
+
|
|
324
|
+
> **rejectDispatch**(`command`): `Promise`\<`void`\>
|
|
325
|
+
|
|
326
|
+
#### Parameters
|
|
327
|
+
|
|
328
|
+
##### command
|
|
329
|
+
|
|
330
|
+
`OwnerRejectDispatchCommand`
|
|
331
|
+
|
|
332
|
+
#### Returns
|
|
333
|
+
|
|
334
|
+
`Promise`\<`void`\>
|
|
335
|
+
|
|
336
|
+
***
|
|
337
|
+
|
|
338
|
+
### revokeAgentSessionToken()
|
|
339
|
+
|
|
340
|
+
> **revokeAgentSessionToken**(`request`): `Promise`\<`void`\>
|
|
341
|
+
|
|
342
|
+
#### Parameters
|
|
343
|
+
|
|
344
|
+
##### request
|
|
345
|
+
|
|
346
|
+
###### actor
|
|
347
|
+
|
|
348
|
+
`VaultPrincipal` & `object`
|
|
349
|
+
|
|
350
|
+
###### token
|
|
351
|
+
|
|
352
|
+
`string`
|
|
353
|
+
|
|
354
|
+
###### vaultId
|
|
355
|
+
|
|
356
|
+
`VaultId`
|
|
357
|
+
|
|
358
|
+
#### Returns
|
|
359
|
+
|
|
360
|
+
`Promise`\<`void`\>
|
|
361
|
+
|
|
362
|
+
***
|
|
363
|
+
|
|
268
364
|
### revokeCapability()
|
|
269
365
|
|
|
270
366
|
> **revokeCapability**(`command`): `Promise`\<`void`\>
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
[**CBIO Node Runtime Agent API v1.
|
|
1
|
+
[**CBIO Node Runtime Agent API v1.48.1**](../README.md)
|
|
2
2
|
|
|
3
3
|
***
|
|
4
4
|
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
|
|
23
23
|
##### code
|
|
24
24
|
|
|
25
|
-
`"VAULT_SECRET_NOT_FOUND"` \| `"VAULT_WRITE_DENIED"` \| `"VAULT_IDENTITY_DENIED"` \| `"VAULT_DISPATCH_DENIED"` \| `"VAULT_AUDIT_DENIED"` \| `"VAULT_AUDIT_FAILED"`
|
|
25
|
+
`"VAULT_SECRET_NOT_FOUND"` \| `"VAULT_WRITE_DENIED"` \| `"VAULT_READ_DENIED"` \| `"VAULT_IDENTITY_DENIED"` \| `"VAULT_DISPATCH_DENIED"` \| `"VAULT_AUDIT_DENIED"` \| `"VAULT_AUDIT_FAILED"` \| `"VAULT_REQUEST_NOT_FOUND"` \| `"VAULT_AGENT_NOT_FOUND"` \| `"VAULT_CAPABILITY_NOT_FOUND"`
|
|
26
26
|
|
|
27
27
|
#### Returns
|
|
28
28
|
|
|
@@ -36,4 +36,4 @@
|
|
|
36
36
|
|
|
37
37
|
### code
|
|
38
38
|
|
|
39
|
-
> `readonly` **code**: `"VAULT_SECRET_NOT_FOUND"` \| `"VAULT_WRITE_DENIED"` \| `"VAULT_IDENTITY_DENIED"` \| `"VAULT_DISPATCH_DENIED"` \| `"VAULT_AUDIT_DENIED"` \| `"VAULT_AUDIT_FAILED"`
|
|
39
|
+
> `readonly` **code**: `"VAULT_SECRET_NOT_FOUND"` \| `"VAULT_WRITE_DENIED"` \| `"VAULT_READ_DENIED"` \| `"VAULT_IDENTITY_DENIED"` \| `"VAULT_DISPATCH_DENIED"` \| `"VAULT_AUDIT_DENIED"` \| `"VAULT_AUDIT_FAILED"` \| `"VAULT_REQUEST_NOT_FOUND"` \| `"VAULT_AGENT_NOT_FOUND"` \| `"VAULT_CAPABILITY_NOT_FOUND"`
|