@the-ai-company/cbio-node-runtime 1.63.3 → 1.63.6

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.
Files changed (233) hide show
  1. package/README.md +48 -209
  2. package/dist/clients/agent/client.d.ts +18 -40
  3. package/dist/clients/agent/client.js +22 -109
  4. package/dist/clients/agent/client.js.map +1 -1
  5. package/dist/clients/agent/contracts.d.ts +1 -8
  6. package/dist/clients/agent/index.d.ts +1 -1
  7. package/dist/clients/owner/client.d.ts +2 -102
  8. package/dist/clients/owner/client.js +111 -266
  9. package/dist/clients/owner/client.js.map +1 -1
  10. package/dist/clients/owner/contracts.d.ts +37 -75
  11. package/dist/clients/owner/index.d.ts +2 -4
  12. package/dist/clients/owner/index.js +1 -2
  13. package/dist/clients/owner/index.js.map +1 -1
  14. package/dist/internal/id-factory.d.ts +0 -2
  15. package/dist/internal/id-factory.js +0 -6
  16. package/dist/internal/id-factory.js.map +1 -1
  17. package/dist/protocol/identity.d.ts +1 -1
  18. package/dist/protocol/identity.js +3 -3
  19. package/dist/protocol/identity.js.map +1 -1
  20. package/dist/public-types.d.ts +5 -14
  21. package/dist/public-types.js +1 -8
  22. package/dist/public-types.js.map +1 -1
  23. package/dist/runtime/bootstrap.d.ts +1 -3
  24. package/dist/runtime/bootstrap.js.map +1 -1
  25. package/dist/runtime/identity.d.ts +2 -2
  26. package/dist/runtime/identity.js +3 -5
  27. package/dist/runtime/identity.js.map +1 -1
  28. package/dist/runtime/index.d.ts +10 -12
  29. package/dist/runtime/index.js +7 -8
  30. package/dist/runtime/index.js.map +1 -1
  31. package/dist/runtime/owner-session.d.ts +7 -6
  32. package/dist/runtime/owner-session.js +5 -6
  33. package/dist/runtime/owner-session.js.map +1 -1
  34. package/dist/storage/fs.d.ts +3 -2
  35. package/dist/storage/fs.js +8 -5
  36. package/dist/storage/fs.js.map +1 -1
  37. package/dist/storage/prefix.d.ts +1 -0
  38. package/dist/storage/prefix.js +7 -0
  39. package/dist/storage/prefix.js.map +1 -1
  40. package/dist/storage/provider.d.ts +2 -0
  41. package/dist/vault-core/contracts.d.ts +95 -210
  42. package/dist/vault-core/contracts.js +8 -11
  43. package/dist/vault-core/contracts.js.map +1 -1
  44. package/dist/vault-core/core.d.ts +119 -62
  45. package/dist/vault-core/core.js +518 -1180
  46. package/dist/vault-core/core.js.map +1 -1
  47. package/dist/vault-core/defaults.d.ts +22 -44
  48. package/dist/vault-core/defaults.js +65 -234
  49. package/dist/vault-core/defaults.js.map +1 -1
  50. package/dist/vault-core/errors.d.ts +3 -2
  51. package/dist/vault-core/errors.js.map +1 -1
  52. package/dist/vault-core/index.d.ts +5 -5
  53. package/dist/vault-core/index.js +2 -2
  54. package/dist/vault-core/index.js.map +1 -1
  55. package/dist/vault-core/persistence.d.ts +72 -119
  56. package/dist/vault-core/persistence.js +310 -427
  57. package/dist/vault-core/persistence.js.map +1 -1
  58. package/dist/vault-core/ports.d.ts +19 -30
  59. package/dist/vault-core/read-policy.d.ts +3 -2
  60. package/dist/vault-core/read-policy.js.map +1 -1
  61. package/dist/vault-core/tool-metadata.js +2 -2
  62. package/dist/vault-core/tool-metadata.js.map +1 -1
  63. package/dist/vault-ingress/defaults.d.ts +4 -2
  64. package/dist/vault-ingress/defaults.js +14 -8
  65. package/dist/vault-ingress/defaults.js.map +1 -1
  66. package/dist/vault-ingress/index.d.ts +39 -119
  67. package/dist/vault-ingress/index.js +98 -456
  68. package/dist/vault-ingress/index.js.map +1 -1
  69. package/dist/vault-ingress/remote-transport.d.ts +5 -3
  70. package/dist/vault-ingress/remote-transport.js +8 -28
  71. package/dist/vault-ingress/remote-transport.js.map +1 -1
  72. package/docs/ARCHITECTURE.md +39 -22
  73. package/docs/CUSTODY_MODEL.md +1 -1
  74. package/docs/IDENTITY_MODEL.md +5 -5
  75. package/docs/MIGRATION-1.51.md +19 -19
  76. package/docs/MIGRATION-1.65.md +87 -0
  77. package/docs/PROCESS_ISOLATION.md +2 -2
  78. package/docs/REFERENCE.md +42 -224
  79. package/docs/api/README.md +48 -30
  80. package/docs/api/classes/IdentityError.md +1 -1
  81. package/docs/api/classes/OwnerClientError.md +1 -1
  82. package/docs/api/classes/PersistentVaultAgentIdentityRegistry.md +89 -0
  83. package/docs/api/classes/PersistentVaultAgentSecretGrantRegistry.md +125 -0
  84. package/docs/api/classes/PersistentVaultAuditLog.md +65 -0
  85. package/docs/api/classes/PersistentVaultSecretCustody.md +93 -0
  86. package/docs/api/classes/PersistentVaultSecretDestinationGrantRegistry.md +125 -0
  87. package/docs/api/classes/PersistentVaultSecretRepository.md +127 -0
  88. package/docs/api/classes/VaultCore.md +264 -237
  89. package/docs/api/classes/VaultCoreError.md +3 -3
  90. package/docs/api/enumerations/AuditAction.md +143 -0
  91. package/docs/api/enumerations/AuditOutcome.md +35 -0
  92. package/docs/api/enumerations/DispatchStatus.md +35 -0
  93. package/docs/api/enumerations/IdentityErrorCode.md +1 -1
  94. package/docs/api/enumerations/OwnerClientErrorCode.md +1 -1
  95. package/docs/api/functions/createAgentClient.md +1 -15
  96. package/docs/api/functions/createIdentity.md +2 -2
  97. package/docs/api/functions/createOwnerClient.md +17 -0
  98. package/docs/api/functions/createOwnerSession.md +1 -1
  99. package/docs/api/functions/createPersistentVaultCoreDependencies.md +4 -4
  100. package/docs/api/functions/createVault.md +1 -1
  101. package/docs/api/functions/createVaultCore.md +1 -1
  102. package/docs/api/functions/createVaultCoreDependencies.md +1 -1
  103. package/docs/api/functions/createVaultService.md +5 -13
  104. package/docs/api/functions/createWorkspaceStorage.md +1 -1
  105. package/docs/api/functions/deriveRootAgentId.md +17 -0
  106. package/docs/api/functions/deriveVaultWorkingKeyFromPassword.md +1 -1
  107. package/docs/api/functions/getDefaultWorkspaceDir.md +1 -1
  108. package/docs/api/functions/handleVaultAgentControlHttp.md +2 -2
  109. package/docs/api/functions/handleVaultHttpDispatch.md +2 -2
  110. package/docs/api/functions/initializeVaultCustody.md +7 -3
  111. package/docs/api/functions/listVaults.md +1 -1
  112. package/docs/api/functions/readVaultProfile.md +1 -1
  113. package/docs/api/functions/recoverVault.md +1 -1
  114. package/docs/api/functions/recoverVaultWorkingKey.md +4 -8
  115. package/docs/api/functions/restoreIdentity.md +1 -1
  116. package/docs/api/functions/updateVaultMetadata.md +1 -1
  117. package/docs/api/functions/writeVaultProfile.md +1 -1
  118. package/docs/api/interfaces/AgentClient.md +20 -59
  119. package/docs/api/interfaces/AgentDispatchIntent.md +1 -1
  120. package/docs/api/interfaces/AgentDispatchTransport.md +12 -44
  121. package/docs/api/interfaces/AgentIdentity.md +3 -3
  122. package/docs/api/interfaces/AgentIdentityRecord.md +47 -0
  123. package/docs/api/interfaces/AgentRequestResult.md +35 -0
  124. package/docs/api/interfaces/AgentRuntimeManifest.md +55 -0
  125. package/docs/api/interfaces/AgentSecretGrant.md +41 -0
  126. package/docs/api/interfaces/AgentSigner.md +1 -1
  127. package/docs/api/interfaces/AgentVisibleRequestRecord.md +53 -0
  128. package/docs/api/interfaces/AgentVisibleSecretRecord.md +65 -0
  129. package/docs/api/interfaces/AuditEntry.md +83 -0
  130. package/docs/api/interfaces/CbioRuntime.md +13 -154
  131. package/docs/api/interfaces/CreateAgentClientOptions.md +4 -10
  132. package/docs/api/interfaces/CreateIdentityOptions.md +1 -1
  133. package/docs/api/interfaces/{CreateVaultClientOptions.md → CreateOwnerClientOptions.md} +9 -11
  134. package/docs/api/interfaces/CreateOwnerSessionOptions.md +3 -121
  135. package/docs/api/interfaces/CreatePersistentVaultCoreDependenciesOptions.md +3 -131
  136. package/docs/api/interfaces/CreateVaultOptions.md +1 -125
  137. package/docs/api/interfaces/CreatedVault.md +2 -2
  138. package/docs/api/interfaces/DefaultPolicyEngineOptions.md +1 -13
  139. package/docs/api/interfaces/DispatchAuthorization.md +43 -0
  140. package/docs/api/interfaces/DispatchInstruction.md +47 -0
  141. package/docs/api/interfaces/DispatchRequest.md +83 -0
  142. package/docs/api/interfaces/DispatchResult.md +53 -0
  143. package/docs/api/interfaces/IStorageProvider.md +13 -1
  144. package/docs/api/interfaces/InitializeVaultCustodyOptions.md +31 -11
  145. package/docs/api/interfaces/InitializedVaultCustody.md +1 -7
  146. package/docs/api/interfaces/OwnerAgentProvisionResult.md +2 -2
  147. package/docs/api/interfaces/OwnerClient.md +401 -0
  148. package/docs/api/interfaces/OwnerCreateSecretInput.md +1 -1
  149. package/docs/api/interfaces/OwnerRemoveSecretInput.md +1 -1
  150. package/docs/api/interfaces/OwnerRequestRecord.md +97 -0
  151. package/docs/api/interfaces/OwnerSensitiveActionConfirmation.md +1 -1
  152. package/docs/api/interfaces/OwnerSensitiveActionContext.md +1 -1
  153. package/docs/api/interfaces/OwnerSession.md +3 -3
  154. package/docs/api/interfaces/OwnerUpdateSecretInput.md +1 -1
  155. package/docs/api/interfaces/OwnerVisibleRequestRecord.md +73 -0
  156. package/docs/api/interfaces/RecoverVaultOptions.md +1 -125
  157. package/docs/api/interfaces/RecoveredVault.md +2 -2
  158. package/docs/api/interfaces/RequestRecord.md +107 -0
  159. package/docs/api/interfaces/RestoreIdentityOptions.md +1 -1
  160. package/docs/api/interfaces/SecretAlias.md +11 -0
  161. package/docs/api/interfaces/SecretDestinationGrant.md +41 -0
  162. package/docs/api/interfaces/SecretId.md +11 -0
  163. package/docs/api/interfaces/SecretRecord.md +89 -0
  164. package/docs/api/interfaces/Signer.md +1 -1
  165. package/docs/api/interfaces/VaultApproveDispatchInput.md +3 -9
  166. package/docs/api/interfaces/VaultAuditQueryInput.md +1 -1
  167. package/docs/api/interfaces/VaultCoreDependenciesOptions.md +1 -5
  168. package/docs/api/interfaces/VaultCreateAgentInput.md +1 -1
  169. package/docs/api/interfaces/VaultExportSecretInput.md +1 -1
  170. package/docs/api/interfaces/VaultGetRequestInput.md +17 -0
  171. package/docs/api/interfaces/VaultGrantAgentSecretInput.md +23 -0
  172. package/docs/api/interfaces/VaultGrantSecretDestinationInput.md +23 -0
  173. package/docs/api/interfaces/VaultId.md +11 -0
  174. package/docs/api/interfaces/VaultImportAgentInput.md +1 -1
  175. package/docs/api/interfaces/VaultIssueSessionTokenInput.md +5 -5
  176. package/docs/api/interfaces/VaultListAgentsInput.md +1 -1
  177. package/docs/api/interfaces/VaultListGrantsInput.md +23 -0
  178. package/docs/api/interfaces/VaultListRequestsInput.md +17 -0
  179. package/docs/api/interfaces/VaultListSecretsInput.md +1 -1
  180. package/docs/api/interfaces/VaultMetadata.md +1 -1
  181. package/docs/api/interfaces/VaultObject.md +2 -2
  182. package/docs/api/interfaces/VaultPrincipal.md +17 -0
  183. package/docs/api/interfaces/VaultProfile.md +1 -1
  184. package/docs/api/interfaces/VaultReadAgentPrivateKeyInput.md +7 -7
  185. package/docs/api/interfaces/VaultReadSecretPlaintextInput.md +1 -1
  186. package/docs/api/interfaces/VaultRevokeAgentSecretInput.md +23 -0
  187. package/docs/api/interfaces/VaultRevokeSecretDestinationInput.md +23 -0
  188. package/docs/api/interfaces/VaultRevokeSessionTokenInput.md +1 -1
  189. package/docs/api/interfaces/VaultService.md +511 -0
  190. package/docs/api/interfaces/VaultUpdateAgentInput.md +7 -7
  191. package/docs/api/type-aliases/AgentId.md +7 -0
  192. package/docs/api/type-aliases/CbioRuntimeModule.md +1 -1
  193. package/docs/api/type-aliases/DispatchApprovalDecision.md +7 -0
  194. package/docs/api/type-aliases/GrantStatus.md +7 -0
  195. package/docs/api/type-aliases/SecretLifecycleStatus.md +7 -0
  196. package/docs/api/type-aliases/VaultPrincipalKind.md +7 -0
  197. package/docs/api/variables/DEFAULT_VAULT_KEY_CUSTODY_BLOB_KEY.md +2 -2
  198. package/docs/es/README.md +3 -3
  199. package/docs/fr/README.md +3 -3
  200. package/docs/ja/README.md +5 -5
  201. package/docs/ko/README.md +5 -5
  202. package/docs/pt/README.md +3 -3
  203. package/docs/zh/PROCESS_ISOLATION.md +2 -2
  204. package/docs/zh/README.md +47 -63
  205. package/examples/process-isolation.ts +26 -35
  206. package/package.json +1 -1
  207. package/docs/api/functions/createOwnerHttpFlowBoundary.md +0 -17
  208. package/docs/api/functions/createStandardAcquireBoundary.md +0 -31
  209. package/docs/api/functions/createStandardDispatchBoundary.md +0 -23
  210. package/docs/api/functions/createVaultClient.md +0 -32
  211. package/docs/api/functions/deriveIdentityId.md +0 -17
  212. package/docs/api/functions/wrapVaultCoreAsVaultService.md +0 -31
  213. package/docs/api/interfaces/AgentSubmitCapabilityRequestInput.md +0 -41
  214. package/docs/api/interfaces/VaultApproveCapabilityRequestInput.md +0 -23
  215. package/docs/api/interfaces/VaultClient.md +0 -473
  216. package/docs/api/interfaces/VaultGrantCapabilityInput.md +0 -79
  217. package/docs/api/interfaces/VaultGrantCapabilityRequest.md +0 -23
  218. package/docs/api/interfaces/VaultIdentity.md +0 -11
  219. package/docs/api/interfaces/VaultListCapabilitiesInput.md +0 -17
  220. package/docs/api/interfaces/VaultRegisterFlowInput.md +0 -77
  221. package/docs/api/interfaces/VaultRevokeCapabilityInput.md +0 -23
  222. package/docs/api/interfaces/VaultSigner.md +0 -21
  223. package/docs/api/interfaces/VaultSubmitCapabilityRequestInput.md +0 -73
  224. package/docs/api/type-aliases/AgentCapabilityEnvelope.md +0 -7
  225. package/docs/api/type-aliases/AgentVisibleSecretRecord.md +0 -7
  226. package/docs/api/type-aliases/CreateOwnerClientOptions.md +0 -7
  227. package/docs/api/type-aliases/OwnerAgentView.md +0 -7
  228. package/docs/api/type-aliases/OwnerClient.md +0 -13
  229. package/docs/api/type-aliases/OwnerGrantCapabilityInput.md +0 -7
  230. package/docs/api/type-aliases/OwnerPendingApprovalView.md +0 -7
  231. package/docs/api/type-aliases/OwnerRequestDetailView.md +0 -7
  232. package/docs/api/type-aliases/OwnerRequestSummaryView.md +0 -7
  233. package/docs/api/type-aliases/OwnerSecretView.md +0 -7
package/docs/es/README.md CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  listVaults,
24
24
  recoverVault,
25
25
  createOwnerSession,
26
- createVaultClient,
26
+ createOwnerClient,
27
27
  createAgentClient,
28
28
  FsStorageProvider,
29
29
  } from '@the-ai-company/cbio-node-runtime';
@@ -40,8 +40,8 @@ Ruta principal recomendada para vault persistente:
40
40
 
41
41
  - crear el vault persistente con `createVault(...)`
42
42
  - recuperar el vault persistente con `recoverVault(...)` usando `vaultId` + `password`
43
- - para GUIs o procesos de larga duración, conservar `createOwnerSession(...)` en lugar de cachear un `createVaultClient(...)` crudo
44
- - usar `createVaultClient(...)` solo para scripts breves o tareas puntuales en el runtime actual
43
+ - para GUIs o procesos de larga duración, conservar `createOwnerSession(...)` en lugar de cachear un `createOwnerClient(...)` crudo
44
+ - usar `createOwnerClient(...)` solo para scripts breves o tareas puntuales en el runtime actual
45
45
 
46
46
  La API antigua centrada en `CbioIdentity` ya no es la superficie principal del producto.
47
47
 
package/docs/fr/README.md CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  listVaults,
24
24
  recoverVault,
25
25
  createOwnerSession,
26
- createVaultClient,
26
+ createOwnerClient,
27
27
  createAgentClient,
28
28
  FsStorageProvider,
29
29
  } from '@the-ai-company/cbio-node-runtime';
@@ -40,8 +40,8 @@ Chemin principal recommande pour un vault persistant :
40
40
 
41
41
  - créer le coffre persistant avec `createVault(...)`
42
42
  - restaurer le coffre persistant avec `recoverVault(...)` via `vaultId` + `password`
43
- - pour les GUIs ou processus longs, conserver `createOwnerSession(...)` plutôt qu'un `createVaultClient(...)` brut en cache
44
- - réserver `createVaultClient(...)` aux scripts courts ou aux tâches ponctuelles dans le runtime courant
43
+ - pour les GUIs ou processus longs, conserver `createOwnerSession(...)` plutôt qu'un `createOwnerClient(...)` brut en cache
44
+ - réserver `createOwnerClient(...)` aux scripts courts ou aux tâches ponctuelles dans le runtime courant
45
45
 
46
46
  L'ancienne API centree sur `CbioIdentity` n'est plus la surface principale du produit.
47
47
 
package/docs/ja/README.md CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  listVaults,
24
24
  recoverVault,
25
25
  createOwnerSession,
26
- createVaultClient,
26
+ createOwnerClient,
27
27
  createAgentClient,
28
28
  FsStorageProvider,
29
29
  } from '@the-ai-company/cbio-node-runtime';
@@ -32,16 +32,16 @@ import {
32
32
  ## アーキテクチャ
33
33
 
34
34
  1. secret の平文は `vault-core` の内部にのみ存在します
35
- 2. `clients/owner` は、オーナーによる書き込み、平文エクスポート、監査の読み取り、および **Agent/権限管理** (`listAgents`, `listCapabilities`, `revokeCapability`) を担当します。
35
+ 2. `clients/owner` は、オーナーによる書き込み、平文エクスポート、監査の読み取り、および **Agent/権限管理** (`listAgents`, `listGrants`, `revokeGrant`) を担当します。
36
36
  3. `clients/agent` は agent の signed dispatch request を作ります
37
- 4. `vault-ingress` は vault 境界の内側で capability 解決と dispatch ingress を扱います
37
+ 4. `vault-ingress` は vault 境界の内側で grant 解決と dispatch ingress を扱います
38
38
 
39
39
  推奨される persistent-vault の主経路:
40
40
 
41
41
  - `createVault(...)` で persistent vault を作成する
42
42
  - `recoverVault(...)` で `vaultId` と `password` を使って persistent vault を復旧する
43
- - GUI や長寿命プロセスでは、生の `createVaultClient(...)` をキャッシュせず `createOwnerSession(...)` を保持する
44
- - `createVaultClient(...)` は短命スクリプトやその runtime 限定の単発処理に使う
43
+ - GUI や長寿命プロセスでは、生の `createOwnerClient(...)` をキャッシュせず `createOwnerSession(...)` を保持する
44
+ - `createOwnerClient(...)` は短命スクリプトやその runtime 限定の単発処理に使う
45
45
 
46
46
  旧 `CbioIdentity` 中心 API は、もはや主要な公開面ではありません。
47
47
 
package/docs/ko/README.md CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  listVaults,
24
24
  recoverVault,
25
25
  createOwnerSession,
26
- createVaultClient,
26
+ createOwnerClient,
27
27
  createAgentClient,
28
28
  FsStorageProvider,
29
29
  } from '@the-ai-company/cbio-node-runtime';
@@ -32,16 +32,16 @@ import {
32
32
  ## 아키텍처
33
33
 
34
34
  1. secret 평문은 `vault-core` 내부에만 존재합니다
35
- 2. `clients/owner`는 소유자 쓰기, 평문 내보내기, 감사 읽기 및 **Agent/권한 관리** (`listAgents`, `listCapabilities`, `revokeCapability`)를 담당합니다.
35
+ 2. `clients/owner`는 소유자 쓰기, 평문 내보내기, 감사 읽기 및 **Agent/권한 관리** (`listAgents`, `listGrants`, `revokeGrant`)를 담당합니다.
36
36
  3. `clients/agent` 는 agent 서명 dispatch 요청을 만듭니다
37
- 4. `vault-ingress` 는 vault 경계 내부에서 capability 해석과 dispatch ingress 를 처리합니다
37
+ 4. `vault-ingress` 는 vault 경계 내부에서 grant 해석과 dispatch ingress 를 처리합니다
38
38
 
39
39
  권장되는 persistent-vault 주 경로:
40
40
 
41
41
  - `createVault(...)` 로 persistent vault 를 생성합니다
42
42
  - `recoverVault(...)` 로 `vaultId` 와 `password` 를 사용해 persistent vault 를 복구합니다
43
- - GUI 나 장수명 프로세스에서는 raw `createVaultClient(...)` 를 캐시하지 말고 `createOwnerSession(...)` 을 유지합니다
44
- - `createVaultClient(...)` 는 현재 runtime 안의 짧은 스크립트나 일회성 작업에 사용합니다
43
+ - GUI 나 장수명 프로세스에서는 raw `createOwnerClient(...)` 를 캐시하지 말고 `createOwnerSession(...)` 을 유지합니다
44
+ - `createOwnerClient(...)` 는 현재 runtime 안의 짧은 스크립트나 일회성 작업에 사용합니다
45
45
 
46
46
  이전 `CbioIdentity` 중심 API 는 더 이상 주요 제품 표면이 아닙니다.
47
47
 
package/docs/pt/README.md CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  listVaults,
24
24
  recoverVault,
25
25
  createOwnerSession,
26
- createVaultClient,
26
+ createOwnerClient,
27
27
  createAgentClient,
28
28
  FsStorageProvider,
29
29
  } from '@the-ai-company/cbio-node-runtime';
@@ -40,8 +40,8 @@ Caminho principal recomendado para vault persistente:
40
40
 
41
41
  - criar o cofre persistente com `createVault(...)`
42
42
  - recuperar o cofre persistente com `recoverVault(...)` usando `vaultId` + `password`
43
- - para GUIs ou processos longos, manter `createOwnerSession(...)` em vez de cachear um `createVaultClient(...)` bruto
44
- - usar `createVaultClient(...)` apenas para scripts curtos ou tarefas pontuais no runtime atual
43
+ - para GUIs ou processos longos, manter `createOwnerSession(...)` em vez de cachear um `createOwnerClient(...)` bruto
44
+ - usar `createOwnerClient(...)` apenas para scripts curtos ou tarefas pontuais no runtime atual
45
45
 
46
46
  A antiga API centrada em `CbioIdentity` nao e mais a superficie principal do produto.
47
47
 
@@ -20,8 +20,8 @@ import { createAgentClient, AgentDispatchHttpTransport } from '@the-ai-company/c
20
20
  const transport = new AgentDispatchHttpTransport('http://localhost:3000/dispatch');
21
21
 
22
22
  const agent = createAgentClient({
23
- agentIdentity, // 进程 A 仅持有自己的身份私钥
24
- capability, // 进程 A 仅了解被授予的权限
23
+ rootAgentIdentity, // 进程 A 仅持有自己的身份私钥
24
+ grant, // 进程 A 仅了解被授予的权限
25
25
  transport,
26
26
  });
27
27
 
package/docs/zh/README.md CHANGED
@@ -49,9 +49,9 @@ const vault = await recoverVault(storage, {
49
49
 
50
50
  ### 3. GUI 的 Owner Session
51
51
 
52
- 对于 GUI 这类长生命周期进程,应该持有 `OwnerSession`,而不是长期缓存裸 `VaultClient`。
52
+ 对于 GUI 这类长生命周期进程,应该持有 `OwnerSession`,而不是长期缓存裸 `OwnerClient`。
53
53
 
54
- `createVaultClient(...)` 只负责基于当前 runtime 创建 owner client;它不应该跨 HMR、模块重载或 runtime 替换被长期复用。`OwnerSession` 会提供稳定的 SDK 句柄,并按需重新创建 owner client。
54
+ `createOwnerClient(...)` 只负责基于当前 runtime 创建 owner client;它不应该跨 HMR、模块重载或 runtime 替换被长期复用。`OwnerSession` 会提供稳定的 SDK 句柄,并按需重新创建 owner client。
55
55
 
56
56
  ```ts
57
57
  import { createOwnerSession } from '@the-ai-company/cbio-node-runtime';
@@ -72,14 +72,14 @@ const agents = await ownerClient.ownerListAgents();
72
72
  session.invalidate();
73
73
  ```
74
74
 
75
- 如果你写的是一次性脚本,`recoverVault(...)` 配合 `createVaultClient(...)` 仍然是合适的。
75
+ 如果你写的是一次性脚本,`recoverVault(...)` 配合 `createOwnerClient(...)` 仍然是合适的。
76
76
 
77
77
  ### 4. 托管 Agent 身份
78
78
 
79
79
  ```ts
80
- import { createVaultClient } from '@the-ai-company/cbio-node-runtime';
80
+ import { createOwnerClient } from '@the-ai-company/cbio-node-runtime';
81
81
 
82
- const client = createVaultClient({
82
+ const client = createOwnerClient({
83
83
  vault: vault.vault,
84
84
  passwordVerifier: vault.verifyPassword,
85
85
  });
@@ -88,101 +88,85 @@ const createdAgent = await client.ownerCreateAgent({
88
88
  nickname: '后台处理插件',
89
89
  });
90
90
 
91
- const agentId = createdAgent.agent.agentId;
91
+ const rootAgentId = createdAgent.agent.rootAgentId;
92
92
  const sessionToken = createdAgent.sessionToken;
93
93
  ```
94
94
 
95
- ### 5. 机密管理
95
+ ### 5. 机密与授权管理(Grant Model)
96
+
97
+ v1.65+ 采用了简化的 **Grant(授权)** 模型,通过白名单控制访问:
96
98
 
97
99
  ```ts
98
- const record = await client.ownerWriteSecret({
100
+ // 1. 创建机密
101
+ const record = await client.ownerCreateSecret({
99
102
  alias: 'api-token',
100
103
  plaintext: 'secret-value'
101
104
  });
102
105
 
103
- await client.ownerGrantCapability({
104
- agentId,
105
- write: {
106
- secretIds: [record.secretId.value],
107
- scope: 'https://api.example.com/*',
108
- methods: ['POST']
109
- },
110
- read: { paths: ['$'] }
106
+ // 2. 授权 Agent 使用该机密
107
+ await client.ownerGrantAgentSecret({
108
+ rootAgentId,
109
+ secretAlias: 'api-token',
110
+ });
111
+
112
+ // 3. 授权该机密可发送至的目标域名
113
+ await client.ownerGrantSecretDestination({
114
+ secretAlias: 'api-token',
115
+ domain: 'api.example.com',
111
116
  });
112
117
  ```
113
118
 
114
- ### 6. Agent 消费机密
119
+ ### 6. Agent 消费机密与自省
120
+
121
+ Agent 使用 `AgentClient` 进行操作,支持 **零配置(Zero-Configuration)** 自省:
115
122
 
116
123
  ```ts
117
124
  import { createAgentClient } from '@the-ai-company/cbio-node-runtime';
118
125
 
119
126
  const agent = createAgentClient({
120
- agentIdentity: { agentId },
121
- capability: myCapability,
127
+ rootAgentIdentity: { rootAgentId },
122
128
  token: sessionToken.token,
123
129
  vault: vault.vault
124
130
  });
125
131
 
126
- const result = await agent.agentDispatch({ ... });
127
- const requests = await agent.agentListRequests();
128
- const request = await agent.agentGetRequest(result.requestId);
129
- const ownerView = await client.ownerGetRequest({ requestId: result.requestId });
130
- ```
131
-
132
- Agent 进程不会直接使用原始私钥执行请求。即使 Agent 拥有身份材料,也应先换取 session token,再进行 dispatch。
133
-
134
- 给 LLM 的直白规则:
135
- - `agentDispatch(...)` = 立刻尝试执行真实任务
136
- - `agentDispatch(...)` 必须带一条给 owner 看的 `reason`,说明为什么要发这个请求
137
- - `agentSubmitCapabilityRequest(...)` = 只申请权限,不会执行任务
138
- - `agentSubmitCapabilityRequest(...)` 也必须带 `reason`,说明为什么需要这项权限
139
- - `agentListRequests()` / `agentGetRequest(...)` = 在请求执行后查看异步结果
140
- - `ownerListRequests()` / `ownerGetRequest(...)` = owner 查看完整请求记录,用于决定是否放行 read
141
- - `read.paths` 只控制哪些响应值可见;响应结构始终可见,`['$']` 表示整个 body 都可见
142
-
143
- ```ts
144
- const manifest = await agent.agentIntrospect();
132
+ // 执行机密驱动的请求
133
+ const result = await agent.agentDispatch({
134
+ targetUrl: 'https://api.example.com/data',
135
+ method: 'POST',
136
+ reason: '同步业务数据'
137
+ });
145
138
 
146
- console.log(manifest.agent.agentId);
147
- console.log(manifest.agent.identityId);
139
+ // 自省:查看自己的身份、权限和可用工具
140
+ const manifest = await agent.agentGetRuntimeManifest();
148
141
  console.log(manifest.agent.nickname);
149
- console.log(manifest.capabilities); // 同一组能力载体里包含 write/read 动作状态
142
+ console.log(manifest.grants.agentSecrets); // 已获得的机密授权
150
143
  ```
151
144
 
152
- `agentListCapabilities()` 返回能力载体视图,`agentListRequests()` / `agentGetRequest()` 则负责暴露请求历史和按权限裁剪后的结果。
153
-
154
- ### 7. 人机协同(HITL)工作流
145
+ ### 7. 人机协同(HITL)与语义化审计
155
146
 
156
- 如果 Agent 尝试执行的动作不在白名单内,dispatch 会返回 `PENDING`,同时运行时会写入一条能力载体记录,其 `write` 动作等待 Owner 审批。
147
+ 如果 Agent 尝试的请求未获授权,`agentDispatch` 会返回 `PENDING` 状态,进入人工审批流。
157
148
 
158
149
  ```ts
159
- const result = await agent.agentDispatch({ ... });
160
- if (result.status === 'PENDING') {
161
- console.log('触发发现流程:等待所有者审批...');
162
- }
163
-
164
- client.ownerOnCapabilityState((state) => {
165
- if (state.writeGrant === null) {
166
- console.log('收到新的待审批能力状态:', state.requestId);
167
- }
168
- });
169
-
170
- const pending = await client.ownerListCapabilityStates({ writeGranted: false });
150
+ // 审批待处理的请求
151
+ const pending = await client.ownerListRequests({ rootAgentId });
171
152
  if (pending.length > 0) {
172
- await client.ownerAllowAlways({
173
- requestId: pending[0].requestId
174
- });
175
- await client.ownerApproveCapabilityRead({
153
+ await client.ownerApproveDispatch({
176
154
  requestId: pending[0].requestId,
177
- read: { paths: ['data.id', 'data.status'] }
155
+ decision: 'allow_and_grant' // 允许执行并自动补齐缺少的授权
178
156
  });
179
157
  }
158
+
159
+ // 查看语义化审计日志
160
+ const logs = await client.ownerReadAudit({
161
+ action: 'APPROVE_DISPATCH' // 使用业务感知的语义化动作进行查询
162
+ });
180
163
  ```
181
164
 
182
165
  ---
183
166
 
184
167
  ## 详细文档
185
168
 
169
+ - [迁移指南 (v1.4 -> v1.65)](../MIGRATION-1.65.md)
186
170
  - [进程隔离(A/B 架构)](../PROCESS_ISOLATION.md)
187
171
  - [根目录 README(英文)](../../README.md)
188
172
 
@@ -190,5 +174,5 @@ if (pending.length > 0) {
190
174
 
191
175
  1. **机密隔离**:机密明文绝不离开安全进程。
192
176
  2. **密码即权限**:主密码是唯一的管理授权来源。
193
- 3. **可审计性**:所有管理动作均记录为 `vault-master` 或对应的 Agent 身份。
177
+ 3. **语义化审计**:所有操作均记录为具有业务含义的动作(如 `APPROVE_DISPATCH`),而非底层技术术语。
194
178
  4. **二元状态**:保险箱要么被解锁并可见,要么只是磁盘上一组加密碎片。
@@ -59,14 +59,13 @@ async function startVaultServer(port: number) {
59
59
  }
60
60
 
61
61
  // --- Process A: The LLM Agent Logic ---
62
- async function runAgentDemo(port: number, agentIdentity: any, capability: any, token: string) {
62
+ async function runAgentDemo(port: number, agentRecord: any, token: string) {
63
63
  // Process A ONLY knows the remote URL and its own Agent Identity.
64
64
  // It has NO access to the Vault's master key or storage.
65
65
  const transport = new AgentDispatchHttpTransport(`http://localhost:${port}/dispatch`);
66
66
 
67
67
  const agentClient = createAgentClient({
68
- agentIdentity,
69
- capability,
68
+ agentRecord: agentRecord,
70
69
  transport,
71
70
  token,
72
71
  });
@@ -78,6 +77,7 @@ async function runAgentDemo(port: number, agentIdentity: any, capability: any, t
78
77
  secretAlias: "api-token",
79
78
  targetUrl: "https://httpbin.org/post",
80
79
  method: "POST",
80
+ reason: "LLM agent needs to perform isolated dispatch",
81
81
  body: JSON.stringify({ message: "Hello from isolated Process A" }),
82
82
  });
83
83
 
@@ -97,65 +97,56 @@ async function main() {
97
97
  const { ownerIdentity, vault, server } = await startVaultServer(PORT);
98
98
 
99
99
  // 2. Setup: Owner (in Process B's context) grants permission to an Agent
100
- const agentIdentity = createIdentity({ nickname: "llm-agent-1" });
100
+ const agentRecord = createIdentity({ nickname: "llm-agent-1" });
101
101
 
102
- // Owner registers the agent and a capability (simulated local call for setup)
102
+ // Owner registers the agent and a grant (simulated local call for setup)
103
103
  await vault.ownerRegisterAgentIdentity({
104
104
  vaultId: vault.vaultId,
105
105
  requestId: `setup:${Date.now()}:register_agent`,
106
- owner: { kind: "owner", id: ownerIdentity.identityId },
107
- agentIdentity: {
106
+ owner: { kind: "owner", id: ownerIdentity.rootAgentId },
107
+ agentRecord: {
108
108
  vaultId: vault.vaultId,
109
- agentId: agentIdentity.identityId,
110
- publicKey: agentIdentity.publicKey,
109
+ rootAgentId: agentRecord.rootAgentId,
110
+ publicKey: agentRecord.publicKey,
111
111
  },
112
112
  requestedAt: new Date().toISOString(),
113
113
  });
114
114
 
115
115
  // Owner writes a secret (simulated local call for setup)
116
- const secret = await vault.ownerWriteSecret({
117
- kind: "owner.write_secret",
116
+ const secret = await vault.ownerCreateSecret({
117
+ kind: "owner.create_secret",
118
118
  vaultId: vault.vaultId,
119
119
  requestId: `setup:${Date.now()}:write_secret`,
120
- owner: { kind: "owner", id: ownerIdentity.identityId },
120
+ owner: { kind: "owner", id: ownerIdentity.rootAgentId },
121
121
  alias: "api-token",
122
122
  plaintext: "SK-PROD-12345",
123
123
  source: { kind: "manual" },
124
124
  requestedAt: new Date().toISOString(),
125
125
  });
126
126
 
127
- const capability = {
128
- vaultId: vault.vaultId,
129
- capabilityId: "cap-llm-1",
130
- agentId: agentIdentity.identityId,
131
- operation: "dispatch_http" as const,
132
- write: {
133
- secretIds: [secret.secretId.value],
134
- scope: "https://httpbin.org/post",
135
- methods: ["POST"],
136
- },
137
- read: { mode: "full" },
138
- issuedAt: new Date().toISOString(),
139
- };
127
+ // Owner grants permissions (New Grant-based API)
128
+ await vault.ownerGrantAgentSecret(
129
+ { kind: "owner", id: ownerIdentity.rootAgentId },
130
+ agentRecord.rootAgentId,
131
+ "api-token"
132
+ );
140
133
 
141
- await vault.ownerRegisterCapability({
142
- vaultId: vault.vaultId,
143
- requestId: `setup:${Date.now()}:register_capability`,
144
- owner: { kind: "owner", id: ownerIdentity.identityId },
145
- capability,
146
- requestedAt: new Date().toISOString(),
147
- });
134
+ await vault.ownerGrantSecretDestination(
135
+ { kind: "owner", id: ownerIdentity.rootAgentId },
136
+ "api-token",
137
+ "httpbin.org"
138
+ );
148
139
 
149
140
  const session = await vault.ownerIssueSessionToken({
150
141
  vaultId: vault.vaultId,
151
142
  requestId: `setup:${Date.now()}:issue_session_token`,
152
- actor: { kind: "owner", id: ownerIdentity.identityId },
153
- agentId: agentIdentity.identityId,
143
+ actor: { kind: "owner", id: ownerIdentity.rootAgentId },
144
+ rootAgentId: agentRecord.rootAgentId,
154
145
  requestedAt: new Date().toISOString(),
155
146
  });
156
147
 
157
148
  // 3. Run the "LLM Agent" (Process A)
158
- await runAgentDemo(PORT, agentIdentity, capability, session.token);
149
+ await runAgentDemo(PORT, agentRecord, session.token);
159
150
 
160
151
  // 4. Cleanup
161
152
  server.close();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@the-ai-company/cbio-node-runtime",
3
- "version": "1.63.3",
3
+ "version": "1.63.6",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -1,17 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: createOwnerHttpFlowBoundary()
6
-
7
- > **createOwnerHttpFlowBoundary**(`boundary`): `OwnerHttpFlowBoundary`
8
-
9
- ## Parameters
10
-
11
- ### boundary
12
-
13
- `OwnerHttpFlowBoundary`
14
-
15
- ## Returns
16
-
17
- `OwnerHttpFlowBoundary`
@@ -1,31 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: createStandardAcquireBoundary()
6
-
7
- > **createStandardAcquireBoundary**(`input`): `OwnerHttpFlowBoundary`
8
-
9
- ## Parameters
10
-
11
- ### input
12
-
13
- #### method?
14
-
15
- `string`
16
-
17
- #### responseField
18
-
19
- `"access_token"` \| `"refresh_token"` \| `"id_token"`
20
-
21
- #### storeAlias
22
-
23
- `string`
24
-
25
- #### targetUrl
26
-
27
- `string`
28
-
29
- ## Returns
30
-
31
- `OwnerHttpFlowBoundary`
@@ -1,23 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: createStandardDispatchBoundary()
6
-
7
- > **createStandardDispatchBoundary**(`input`): `OwnerHttpFlowBoundary`
8
-
9
- ## Parameters
10
-
11
- ### input
12
-
13
- #### method
14
-
15
- `string`
16
-
17
- #### targetUrl
18
-
19
- `string`
20
-
21
- ## Returns
22
-
23
- `OwnerHttpFlowBoundary`
@@ -1,32 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: createVaultClient()
6
-
7
- > **createVaultClient**(`options`): [`VaultClient`](../interfaces/VaultClient.md)
8
-
9
- Creates a [VaultClient](../interfaces/VaultClient.md) instance for a specific vault owner.
10
-
11
- ## Parameters
12
-
13
- ### options
14
-
15
- [`CreateVaultClientOptions`](../interfaces/CreateVaultClientOptions.md)
16
-
17
- Configuration including optional owner identity and the vault service.
18
-
19
- ## Returns
20
-
21
- [`VaultClient`](../interfaces/VaultClient.md)
22
-
23
- An initialized [VaultClient](../interfaces/VaultClient.md).
24
-
25
- ## Example
26
-
27
- ```ts
28
- const client = createVaultClient({
29
- ownerIdentity,
30
- vault
31
- });
32
- ```
@@ -1,17 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: deriveIdentityId()
6
-
7
- > **deriveIdentityId**(`publicKey`): `string`
8
-
9
- ## Parameters
10
-
11
- ### publicKey
12
-
13
- `string`
14
-
15
- ## Returns
16
-
17
- `string`
@@ -1,31 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Function: wrapVaultCoreAsVaultService()
6
-
7
- > **wrapVaultCoreAsVaultService**(`core`, `options?`): `VaultService`
8
-
9
- ## Parameters
10
-
11
- ### core
12
-
13
- [`VaultCore`](../classes/VaultCore.md)
14
-
15
- ### options?
16
-
17
- #### clock?
18
-
19
- `Clock`
20
-
21
- #### customFlows?
22
-
23
- `VaultCustomFlowResolver`
24
-
25
- #### fetchImpl?
26
-
27
- \{(`input`, `init?`): `Promise`\<`Response`\>; (`input`, `init?`): `Promise`\<`Response`\>; \}
28
-
29
- ## Returns
30
-
31
- `VaultService`
@@ -1,41 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Interface: AgentSubmitCapabilityRequestInput
6
-
7
- ## Properties
8
-
9
- ### operation?
10
-
11
- > `optional` **operation?**: `"dispatch_http"` \| `"custom_http"`
12
-
13
- ***
14
-
15
- ### read
16
-
17
- > **read**: `CapabilityReadPolicy`
18
-
19
- ***
20
-
21
- ### reason
22
-
23
- > **reason**: `string`
24
-
25
- ***
26
-
27
- ### requestedAt?
28
-
29
- > `optional` **requestedAt?**: `string`
30
-
31
- ***
32
-
33
- ### secretAliases?
34
-
35
- > `optional` **secretAliases?**: readonly `string`[]
36
-
37
- ***
38
-
39
- ### write
40
-
41
- > **write**: `Omit`\<`CapabilityWritePolicy`, `"secretIds"`\>
@@ -1,23 +0,0 @@
1
- [**CBIO Node Runtime Agent API v1.63.3**](../README.md)
2
-
3
- ***
4
-
5
- # Interface: VaultApproveCapabilityRequestInput
6
-
7
- ## Properties
8
-
9
- ### read?
10
-
11
- > `optional` **read?**: `CapabilityReadPolicy`
12
-
13
- ***
14
-
15
- ### requestedAt?
16
-
17
- > `optional` **requestedAt?**: `string`
18
-
19
- ***
20
-
21
- ### requestId
22
-
23
- > **requestId**: `string`