@the-ai-company/cbio-node-runtime 1.48.6 → 1.50.0

package/dist/vault-ingress/remote-transport.js

@@ -8,11 +8,13 @@
 export class AgentDispatchHttpTransport {
     _url;
     _fetchImpl;
-    constructor(_url, _fetchImpl = fetch) {
+    _controlUrl;
+    constructor(_url, _fetchImpl = fetch, _controlUrl = new URL("./agent/control", _url).toString()) {
         this._url = _url;
         this._fetchImpl = _fetchImpl;
+        this._controlUrl = _controlUrl;
     }
-    async dispatch(request) {
+    async agentDispatch(request) {
         const remoteRequest = {
             vaultId: request.vaultId.value,
             requestId: request.requestId,
@@ -25,7 +27,6 @@ export class AgentDispatchHttpTransport {
             headers: request.headers,
             body: request.body,
             proof: {
-                signature: request.proof.signature,
                 token: request.proof.token,
             },
         };
@@ -47,5 +48,62 @@ export class AgentDispatchHttpTransport {
         }
         return payload.result;
     }
+    async agentListCapabilities(request) {
+        const payload = await this._postControl({
+            action: "list_capabilities",
+            vaultId: request.vaultId.value,
+            requestId: request.requestId,
+            requestedAt: request.requestedAt,
+            agentId: request.agent.id,
+            proof: { token: request.proof.token },
+        });
+        return payload;
+    }
+    async agentListSecrets(request) {
+        const payload = await this._postControl({
+            action: "list_secrets",
+            vaultId: request.vaultId.value,
+            requestId: request.requestId,
+            requestedAt: request.requestedAt,
+            agentId: request.agent.id,
+            proof: { token: request.proof.token },
+        });
+        return payload;
+    }
+    async agentSubmitCapabilityRequest(request) {
+        const payload = await this._postControl({
+            action: "submit_capability_request",
+            vaultId: request.vaultId.value,
+            requestId: request.requestId,
+            requestedAt: request.requestedAt,
+            agentId: request.agent.id,
+            proof: { token: request.proof.token },
+            scope: request.scope.scope,
+            methods: [...request.scope.methods],
+            operation: request.scope.operation,
+            secretAliases: request.scope.secretAliases ? [...request.scope.secretAliases] : [],
+            justification: request.justification,
+        });
+        return payload;
+    }
+    async _postControl(body) {
+        const response = await this._fetchImpl(this._controlUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`VAULT_REMOTE_TRANSPORT_HTTP_ERROR: ${response.status} ${response.statusText}`);
+        }
+        const payload = await response.json();
+        if (!payload.ok) {
+            const error = new Error(`${payload.error.code}: ${payload.error.message}`);
+            error.code = payload.error.code;
+            throw error;
+        }
+        return payload.result;
+    }
 }
 //# sourceMappingURL=remote-transport.js.map

package/dist/vault-ingress/remote-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote-transport.js","sourceRoot":"","sources":["../../src/vault-ingress/remote-transport.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH;;GAEG;AACH,MAAM,OAAO,0BAA0B;IAElB;IACA;IAFnB,YACmB,IAAY,EACZ,aAA2B,KAAK;QADhC,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAsB;IAChD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,MAAM,aAAa,GAA8B;YAC/C,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK;YAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE;YACzB,YAAY,EAAE,OAAO,CAAC,UAAU,EAAE,YAAY;YAC9C,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE;gBACL,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,SAAS;gBAClC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;aAC3B;SACF,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE;YAChD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC;SACpC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QAClG,CAAC;QAED,MAAM,OAAO,GAAiE,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpG,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,KAAa,CAAC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;YACzC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;CACF"}
+{"version":3,"file":"remote-transport.js","sourceRoot":"","sources":["../../src/vault-ingress/remote-transport.ts"],"names":[],"mappings":"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"}

package/dist/vault-ingress/server-utils.d.ts

@@ -1,4 +1,4 @@
-import type { VaultService, VaultAgentDispatchResponse, VaultAgentDispatchErrorResponse } from "./index.js";
+import type { VaultService, VaultAgentDispatchResponse, VaultAgentDispatchErrorResponse, VaultAgentControlResponse, VaultAgentControlErrorResponse } from "./index.js";
 /**
  * Standard server-side helper to handle a vault agent dispatch request from an HTTP body.
  * This can be used in any HTTP server framework (Express, Fastify, etc.).
@@ -8,3 +8,4 @@ import type { VaultService, VaultAgentDispatchResponse, VaultAgentDispatchErrorR
  * @returns A JSON-serializable response object.
  */
 export declare function handleVaultHttpDispatch(service: VaultService, body: unknown): Promise<VaultAgentDispatchResponse | VaultAgentDispatchErrorResponse>;
+export declare function handleVaultAgentControlHttp(service: VaultService, body: unknown): Promise<VaultAgentControlResponse | VaultAgentControlErrorResponse>;

package/dist/vault-ingress/server-utils.js

@@ -13,6 +13,47 @@ export async function handleVaultHttpDispatch(service, body) {
             error: { code: "VAULT_INVALID_REQUEST_BODY", message: "Request body must be a JSON object" },
         };
     }
-    return service.handleAgentDispatch(body);
+    const request = body;
+    if (!request.proof?.token) {
+        return {
+            ok: false,
+            error: { code: "VAULT_REMOTE_TOKEN_REQUIRED", message: "Remote agent dispatch requires a session token" },
+        };
+    }
+    return service.agentHandleDispatch(request);
 }
+export async function handleVaultAgentControlHttp(service, body) {
+    if (!body || typeof body !== "object") {
+        return {
+            ok: false,
+            error: { code: "VAULT_INVALID_REQUEST_BODY", message: "Request body must be a JSON object" },
+        };
+    }
+    const request = body;
+    if (!request.proof?.token) {
+        return {
+            ok: false,
+            error: { code: "VAULT_REMOTE_TOKEN_REQUIRED", message: "Remote agent control requires a session token" },
+        };
+    }
+    return service.agentHandleControl(request);
+}
+/*
+ * Owner remote control is intentionally disabled for now.
+ * The original wiring is kept here as a commented stub so it can be restored
+ * after owner-side remote authentication is designed and implemented.
+ *
+ * export async function handleVaultOwnerControlHttp(
+ *   service: VaultService,
+ *   body: unknown,
+ * ): Promise<VaultOwnerControlResponse | VaultOwnerControlErrorResponse> {
+ *   if (!body || typeof body !== "object") {
+ *     return {
+ *       ok: false,
+ *       error: { code: "VAULT_INVALID_REQUEST_BODY", message: "Request body must be a JSON object" },
+ *     };
+ *   }
+ *   return service.ownerHandleControl(body as VaultOwnerControlRequest);
+ * }
+ */
 //# sourceMappingURL=server-utils.js.map

package/dist/vault-ingress/server-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-utils.js","sourceRoot":"","sources":["../../src/vault-ingress/server-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAqB,EACrB,IAAa;IAEb,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,OAAO,EAAE,oCAAoC,EAAE;SAC7F,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,mBAAmB,CAAC,IAAiC,CAAC,CAAC;AACxE,CAAC"}
+{"version":3,"file":"server-utils.js","sourceRoot":"","sources":["../../src/vault-ingress/server-utils.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAAqB,EACrB,IAAa;IAEb,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,OAAO,EAAE,oCAAoC,EAAE;SAC7F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAA0C,CAAC;IAC3D,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,gDAAgD,EAAE;SAC1G,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,mBAAmB,CAAC,OAAoC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAqB,EACrB,IAAa;IAEb,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,4BAA4B,EAAE,OAAO,EAAE,oCAAoC,EAAE;SAC7F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAyC,CAAC;IAC1D,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,+CAA+C,EAAE;SACzG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,kBAAkB,CAAC,OAAmC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG"}

package/docs/REFERENCE.md

@@ -36,42 +36,71 @@ Returns a `string[]` of vault IDs found in the storage.
 
 ### 1. Managed Identity (Recommended)
 Identity material (private keys) generated and stored securely within the vault's own registry. 
-- Use `client.createAgent(...)` to manage these.
+- Use `client.ownerCreateAgent(...)` to manage these.
 - **Session Tokens**: Owners can issue revocable `sat_...` tokens for managed agents to enable stateless authentication without raw private keys.
 
 ### 2. External Identity
-Identity material managed by the user outside the vault. Registered via `client.registerAgent({ publicKey, ... })`.
+Identity material already managed elsewhere can be imported into vault custody via `client.ownerImportAgent({ privateKey, ... })`.
 
 ## Vault Client (Owner/Admin)
 
 The `VaultClient` provides the administrative interface for the vault.
 
 ### Core Operations
-- `writeSecret(...)`: Store a secret and bind it to specific targets in one step.
-- `createAgent(...)`: Generate and host a new agent identity.
-- `listAgents()`: Enumerate authorized agents and retrieve managed private keys.
-- `grantCapability(...)`: Assign specific secret-use permissions to an agent. 
-- `listPendingDispatches()`: List agent requests awaiting manual approval (HITL).
-- `approveDispatch({ requestId, permanent, skipAudit })`: Grant a stalled request manual authorization.
-- `onPendingRequest(callback)`: Register a real-time observer to receive push notifications for discovery requests.
-- `rejectDispatch(requestId)`: Deny a stalled request.
-- `issueSessionToken(input)`: Issue a session token for a specific agent.
-- `issueAllSessionTokens()`: Batch-issue session tokens for ALL registered agents (Automatic during `createVaultClient` warmup).
-- `revokeSessionToken({ token })`: Invalidate a specific session token.
-- `exportSecret(...)`: Reveal a secret's plaintext (requires active authority).
-- `readAudit(...)`: Access the append-only record of all vault actions.
+- `ownerWriteSecret(...)`: Store a secret and bind it to specific targets in one step.
+- `ownerCreateAgent(...)`: Generate and host a new agent identity, then return its public record plus a session token.
+- `ownerImportAgent(...)`: Import an existing private key into vault custody, then return its public record plus a session token.
+- `ownerListAgents()`: Enumerate authorized agents and retrieve managed private keys.
+- `ownerGrantCapability(...)`: Assign specific secret-use permissions to an agent. 
+- `ownerSubmitCapabilityRequest(...)`: Submit a broader pending capability request for later owner review.
+- `ownerListPendingCapabilityRequests()`: List proactive capability requests that are waiting for approval.
+- `ownerApproveCapabilityRequest({ requestId, capabilityId })`: Turn a pending capability request into a real stored capability.
+- `ownerRejectCapabilityRequest(requestId)`: Deny a pending capability request.
+- `ownerOnPendingCapabilityRequest(callback)`: Register a real-time observer to receive proactive capability requests.
+- `ownerListPendingDispatches()`: List agent requests awaiting manual approval (HITL).
+- `ownerApproveDispatch({ requestId, permanent, skipAudit })`: Grant a stalled request manual authorization.
+- `ownerOnPendingDispatch(callback)`: Register a real-time observer to receive push notifications for discovery requests.
+- `ownerRejectDispatch(requestId)`: Deny a stalled request.
+- `ownerIssueSessionToken(input)`: Issue a session token for a specific agent.
+- `ownerIssueAllSessionTokens()`: Batch-issue session tokens for ALL registered agents (Automatic during `createVaultClient` warmup).
+- `ownerRevokeSessionToken({ token })`: Invalidate a specific session token.
+- `ownerExportSecret(...)`: Reveal a secret's plaintext (requires active authority).
+- `ownerReadAudit(...)`: Access the append-only record of all vault actions.
 
 ## Agent Client (Consumer)
 
 The `AgentClient` is used by delegated processes (e.g., LLMs or background workers) to perform authorized actions.
 
 ### Core Operations
-- `dispatch(...)`: Use a granted capability to send a secret to an authorized target.
+- `agentDispatch(...)`: Use a granted capability to send a secret to an authorized target.
   - **Status**: Returns `SUCCEEDED`, `FAILED`, or `PENDING`.
   - **Discovery Flow**: If an agent attempts an action not explicitly in its white-list, the request is automatically stalled as `PENDING` for owner review. 
-- **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.
+- `agentListCapabilities()`: Read the current capability table granted to that agent.
+- `agentListSecrets()`: Read all secret metadata in the vault, with per-secret authorization markers showing which entries the agent can currently use.
+- `agentSubmitCapabilityRequest(...)`: Ask the owner for a broader `scope + methods` grant before dispatching.
+- **Security**: The agent never handles the vault's master password. Agent execution uses **Session Tokens** rather than raw private-key dispatch.
 - **Auditing**: Dispatches are audited by default. Set `skipAudit: true` in the capability (or during approval) to disable logging for specific actions.
 
+## Proactive Capability Approval
+
+The runtime now supports a second approval path alongside dispatch discovery:
+
+- **Dispatch discovery**: A concrete dispatch misses existing capability coverage and becomes `PENDING`.
+- **Capability request**: An external planner or controller submits a broader capability proposal before any dispatch is attempted.
+
+This is useful for LLM-driven planners that can infer the needed scope ahead of time, for example:
+- scope `https://api.example.com/users/*`
+- methods `["GET"]`
+
+The request stays pending until the owner approves or rejects it:
+- `ownerSubmitCapabilityRequest(...)` creates the request record.
+- `ownerListPendingCapabilityRequests()` reads the current queue.
+- `ownerApproveCapabilityRequest(...)` persists a real capability.
+- `ownerRejectCapabilityRequest(...)` removes the request without granting access.
+- `ownerOnPendingCapabilityRequest(...)` supports push-style owner interfaces.
+
+The proactive request flow does not replace dispatch discovery. It is an additional, explicit path for requesting broader access without generating one pending dispatch per resource ID.
+
 ## Storage Layout
 
 The vault uses a unified encrypted partition:

package/docs/api/README.md

@@ -1,8 +1,8 @@
-**CBIO Node Runtime Agent API v1.48.6**
+**CBIO Node Runtime Agent API v1.50.0**
 
 ***
 
-# CBIO Node Runtime Agent API v1.48.6
+# CBIO Node Runtime Agent API v1.50.0
 
 ## Enumerations
 
@@ -21,6 +21,7 @@
 - [AgentDispatchTransport](interfaces/AgentDispatchTransport.md)
 - [AgentIdentity](interfaces/AgentIdentity.md)
 - [AgentSigner](interfaces/AgentSigner.md)
+- [AgentSubmitCapabilityRequestInput](interfaces/AgentSubmitCapabilityRequestInput.md)
 - [CbioRuntime](interfaces/CbioRuntime.md)
 - [CreateAgentClientOptions](interfaces/CreateAgentClientOptions.md)
 - [CreatedVault](interfaces/CreatedVault.md)
@@ -32,6 +33,7 @@
 - [InitializedVaultCustody](interfaces/InitializedVaultCustody.md)
 - [InitializeVaultCustodyOptions](interfaces/InitializeVaultCustodyOptions.md)
 - [IStorageProvider](interfaces/IStorageProvider.md)
+- [OwnerAgentProvisionResult](interfaces/OwnerAgentProvisionResult.md)
 - [OwnerDefineSecretTargetsInput](interfaces/OwnerDefineSecretTargetsInput.md)
 - [OwnerSecretTargetBinding](interfaces/OwnerSecretTargetBinding.md)
 - [OwnerStoreSecretInput](interfaces/OwnerStoreSecretInput.md)
@@ -40,6 +42,7 @@
 - [RecoverVaultOptions](interfaces/RecoverVaultOptions.md)
 - [RestoreIdentityOptions](interfaces/RestoreIdentityOptions.md)
 - [Signer](interfaces/Signer.md)
+- [VaultApproveCapabilityRequestInput](interfaces/VaultApproveCapabilityRequestInput.md)
 - [VaultAuditQueryInput](interfaces/VaultAuditQueryInput.md)
 - [VaultClient](interfaces/VaultClient.md)
 - [VaultCoreDependenciesOptions](interfaces/VaultCoreDependenciesOptions.md)
@@ -48,19 +51,22 @@
 - [VaultExportSecretInput](interfaces/VaultExportSecretInput.md)
 - [VaultGrantCapabilityInput](interfaces/VaultGrantCapabilityInput.md)
 - [VaultIdentity](interfaces/VaultIdentity.md)
+- [VaultImportAgentInput](interfaces/VaultImportAgentInput.md)
 - [VaultListAgentsInput](interfaces/VaultListAgentsInput.md)
 - [VaultListCapabilitiesInput](interfaces/VaultListCapabilitiesInput.md)
+- [VaultListSecretsInput](interfaces/VaultListSecretsInput.md)
 - [VaultMetadata](interfaces/VaultMetadata.md)
 - [VaultObject](interfaces/VaultObject.md)
 - [VaultProfile](interfaces/VaultProfile.md)
-- [VaultRegisterAgentInput](interfaces/VaultRegisterAgentInput.md)
 - [VaultRegisterFlowInput](interfaces/VaultRegisterFlowInput.md)
 - [VaultRevokeCapabilityInput](interfaces/VaultRevokeCapabilityInput.md)
 - [VaultSigner](interfaces/VaultSigner.md)
+- [VaultSubmitCapabilityRequestInput](interfaces/VaultSubmitCapabilityRequestInput.md)
 
 ## Type Aliases
 
 - [AgentCapabilityEnvelope](type-aliases/AgentCapabilityEnvelope.md)
+- [AgentVisibleSecretRecord](type-aliases/AgentVisibleSecretRecord.md)
 - [CbioRuntimeModule](type-aliases/CbioRuntimeModule.md)
 
 ## Variables
@@ -84,6 +90,7 @@
 - [deriveIdentityId](functions/deriveIdentityId.md)
 - [deriveVaultWorkingKeyFromPassword](functions/deriveVaultWorkingKeyFromPassword.md)
 - [getDefaultWorkspaceDir](functions/getDefaultWorkspaceDir.md)
+- [handleVaultAgentControlHttp](functions/handleVaultAgentControlHttp.md)
 - [handleVaultHttpDispatch](functions/handleVaultHttpDispatch.md)
 - [initializeVaultCustody](functions/initializeVaultCustody.md)
 - [listVaults](functions/listVaults.md)

package/docs/api/classes/IdentityError.md

@@ -1,4 +1,4 @@
-[**CBIO Node Runtime Agent API v1.48.6**](../README.md)
+[**CBIO Node Runtime Agent API v1.50.0**](../README.md)
 
 ***