@the-ai-company/cbio-node-runtime 1.17.0 → 1.19.0

package/README.md

@@ -42,7 +42,9 @@ import {
   createChildIdentity,
   createIdentity,
   createWorkspaceStorage,
-  ensurePrivateVault,
+  ensureIdentityPrivateVault,
+  readIdentityPrivateVaultProfile,
+  readIdentityPrivateVaultChildrenState,
   restoreIdentity,
   createVault,
   recoverVault,
@@ -64,10 +66,13 @@ Child identity example:
 
 ```ts
 const rootIdentity = createIdentity({ nickname: 'root' });
-await ensurePrivateVault(storage, rootIdentity);
+await ensureIdentityPrivateVault(storage, rootIdentity);
 const childIdentity = await createChildIdentity(storage, rootIdentity, {
   nickname: 'worker-1',
 });
+
+const profile = await readIdentityPrivateVaultProfile(storage, rootIdentity);
+const children = await readIdentityPrivateVaultChildrenState(storage, rootIdentity.privateKey);
 ```
 
 Vaults also support an optional human-readable nickname:
@@ -96,6 +101,8 @@ Each identity now has its own private namespace in storage under `vault/private/
 - `profile.json`
 - `children.json`
 
+Those files are encrypted with a key derived from the identity private key, so they are not stored as plaintext JSON.
+
 ## Architecture
 
 Core terms:

package/dist/runtime/child-identity.js

@@ -1,5 +1,5 @@
 import { deriveChildIdentity } from "./identity.js";
-import { ensurePrivateVault, readPrivateVaultChildrenState, withPrivateVaultLock, writePrivateVaultChildrenState, } from "./private-vault.js";
+import { ensureIdentityPrivateVault, readIdentityPrivateVaultChildrenState, withIdentityPrivateVaultLock, writeIdentityPrivateVaultChildrenState, } from "./private-vault.js";
 export async function createChildIdentity(storage, parentIdentity, options = {}) {
     const parent = typeof parentIdentity === "string"
         ? undefined
@@ -8,11 +8,11 @@ export async function createChildIdentity(storage, parentIdentity, options = {})
         throw new Error("parent identity object is required");
     }
     const run = async () => {
-        await ensurePrivateVault(storage, parent);
-        const state = await readPrivateVaultChildrenState(storage, parent.identityId);
+        await ensureIdentityPrivateVault(storage, parent);
+        const state = await readIdentityPrivateVaultChildrenState(storage, parent);
         const childIndex = state.nextChildIndex;
         const childIdentity = deriveChildIdentity(parent, childIndex, options);
-        await ensurePrivateVault(storage, childIdentity);
+        await ensureIdentityPrivateVault(storage, childIdentity);
         state.nextChildIndex += 1;
         state.children.push({
             identityId: childIdentity.identityId,
@@ -21,9 +21,9 @@ export async function createChildIdentity(storage, parentIdentity, options = {})
             nickname: childIdentity.nickname,
             publicKey: childIdentity.publicKey,
         });
-        await writePrivateVaultChildrenState(storage, parent.identityId, state);
+        await writeIdentityPrivateVaultChildrenState(storage, parent, state);
         return childIdentity;
     };
-    return withPrivateVaultLock(storage, parent.identityId, run);
+    return withIdentityPrivateVaultLock(storage, parent, run);
 }
 //# sourceMappingURL=child-identity.js.map

package/dist/runtime/child-identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"child-identity.js","sourceRoot":"","sources":["../../src/runtime/child-identity.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAI5B,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAyB,EACzB,cAAwC,EACxC,UAAsC,EAAE;IAExC,MAAM,MAAM,GACV,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,cAAc,CAAC;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,IAA4B,EAAE;QAC7C,MAAM,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,6BAA6B,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9E,MAAM,UAAU,GAAG,KAAK,CAAC,cAAc,CAAC;QACxC,MAAM,aAAa,GAAG,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACjD,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC;QAC1B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAClB,UAAU,EAAE,aAAa,CAAC,UAAU;YACpC,gBAAgB,EAAE,aAAa,CAAC,gBAAiB;YACjD,UAAU;YACV,QAAQ,EAAE,aAAa,CAAC,QAAQ;YAChC,SAAS,EAAE,aAAa,CAAC,SAAS;SACnC,CAAC,CAAC;QACH,MAAM,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACxE,OAAO,aAAa,CAAC;IACvB,CAAC,CAAC;IACF,OAAO,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"child-identity.js","sourceRoot":"","sources":["../../src/runtime/child-identity.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,qCAAqC,EACrC,4BAA4B,EAC5B,sCAAsC,GACvC,MAAM,oBAAoB,CAAC;AAI5B,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAyB,EACzB,cAAwC,EACxC,UAAsC,EAAE;IAExC,MAAM,MAAM,GACV,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,cAAc,CAAC;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,IAA4B,EAAE;QAC7C,MAAM,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,MAAM,qCAAqC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3E,MAAM,UAAU,GAAG,KAAK,CAAC,cAAc,CAAC;QACxC,MAAM,aAAa,GAAG,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,0BAA0B,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACzD,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC;QAC1B,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAClB,UAAU,EAAE,aAAa,CAAC,UAAU;YACpC,gBAAgB,EAAE,aAAa,CAAC,gBAAiB;YACjD,UAAU;YACV,QAAQ,EAAE,aAAa,CAAC,QAAQ;YAChC,SAAS,EAAE,aAAa,CAAC,SAAS;SACnC,CAAC,CAAC;QACH,MAAM,sCAAsC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACrE,OAAO,aAAa,CAAC;IACvB,CAAC,CAAC;IACF,OAAO,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;AAC5D,CAAC"}

package/dist/runtime/index.d.ts

@@ -12,7 +12,7 @@ export { createIdentity, deriveChildIdentity, restoreIdentity, type CreateIdenti
 export { createChildIdentity, type CreateChildIdentityOptions, } from "./child-identity.js";
 export { readVaultProfile, writeVaultProfile, type VaultProfile, } from "./vault-metadata.js";
 export { createWorkspaceStorage, getDefaultWorkspaceDir, } from "./workspace-storage.js";
-export { ensurePrivateVault, readPrivateVaultProfile, readPrivateVaultChildrenState, privateVaultPrefix, privateVaultProfileKey, privateVaultChildrenKey, type PrivateVaultProfile, type PrivateVaultChildRecord, type PrivateVaultChildrenState, } from "./private-vault.js";
+export { ensureIdentityPrivateVault, readIdentityPrivateVaultProfile, readIdentityPrivateVaultChildrenState, identityPrivateVaultPrefix, identityPrivateVaultProfileKey, identityPrivateVaultChildrenKey, type IdentityPrivateVaultProfile, type IdentityPrivateVaultChildRecord, type IdentityPrivateVaultChildrenState, } from "./private-vault.js";
 export { createVault, recoverVault, type CreateVaultOptions, type CreatedVault, type RecoverVaultOptions, type RecoveredVault, type VaultObject, } from "./bootstrap.js";
 export { createVaultCore, DefaultVaultCore, VaultCoreError, createDefaultVaultCoreDependencies, type CreateDefaultVaultCoreDependenciesOptions, type DefaultPolicyEngineOptions, DefaultPolicyEngine, createPersistentVaultCoreDependencies, initializeVaultCustody, recoverVaultWorkingKey, DEFAULT_VAULT_KEY_CUSTODY_BLOB_KEY, type InitializeVaultCustodyOptions, type InitializedVaultCustody, type CreatePersistentVaultCoreDependenciesOptions, PersistentVaultAgentIdentityRegistry, PersistentVaultAuditLog, PersistentVaultOwnerIdentityRegistry, PersistentVaultCapabilityRegistry, PersistentVaultCapabilityRevocationRegistry, PersistentVaultCustomHttpFlowRegistry, PersistentVaultRateLimitStore, PersistentVaultReplayGuard, PersistentVaultSecretCustody, PersistentVaultSecretRepository, HttpDispatchExecutor, InMemoryAgentIdentityRegistry, InMemoryCapabilityRegistry, InMemoryCapabilityRevocationRegistry, InMemoryCustomHttpFlowRegistry, InMemoryRateLimitStore, InMemoryReplayGuard, InMemoryAuditLog, InMemoryOwnerIdentityRegistry, InMemorySecretCustody, InMemorySecretRepository, RandomIdGenerator, SignatureOwnerProofVerifier, type SignatureAgentProofVerifierOptions, SignatureAgentProofVerifier, SystemClock, type AgentCapability, type AgentIdentityRecord, type AgentProof, type OwnerAuditRequest, type OwnerExportSecretRequest, type OwnerDefineSecretTargetsCommand, type OwnerRegisterCapabilityCommand, type OwnerRegisterAgentIdentityCommand, type OwnerRegisterCustomHttpFlowCommand, type OwnerSecretExport, type OwnerIdentityRecord, type CustomHttpFlowDefinition, type OwnerProof, type AuditEntry, type AuditLog, type AuditQuery, type Clock, type DispatchAuthorization, type DispatchInstruction, type DispatchRequest, type DispatchResult, type IdGenerator, type OwnerIdentityRegistry, type OwnerProofVerifier, type PolicyEngine, type RateLimitStore, type ReplayGuard, type CustomHttpFlowRegistry, type SecretAlias, type SecretCustody, type SecretId, type SecretRecord, type SecretRepository, type SecretVersion, type TrustedExecutor, type VaultCore, type VaultCoreDependencies, type VaultPrincipal, type VaultPrincipalKind, type VaultTargetBinding, type VaultWriteSecretCommand, type VaultId, type AgentIdentityRegistry, type AgentProofVerifier, type CapabilityRevocationRegistry, type CapabilityRegistry, } from "../vault-core/index.js";
 export { createVaultClient, type VaultClient, type CreateVaultClientOptions, type VaultIdentity, type VaultSigner, type VaultAuditQueryInput, type OwnerDefineSecretTargetsInput, type VaultExportSecretInput, type VaultGrantCapabilityInput, type VaultRegisterFlowInput, type VaultRegisterAgentInput, type OwnerSecretTargetBinding, type OwnerStoreSecretInput, type OwnerWriteSecretInput, } from "../clients/owner/index.js";
@@ -34,7 +34,9 @@ export interface CbioRuntime {
     restoreIdentity: typeof import("./identity.js").restoreIdentity;
     createChildIdentity: typeof import("./child-identity.js").createChildIdentity;
     deriveChildIdentity: typeof import("./identity.js").deriveChildIdentity;
-    ensurePrivateVault: typeof import("./private-vault.js").ensurePrivateVault;
+    ensureIdentityPrivateVault: typeof import("./private-vault.js").ensureIdentityPrivateVault;
+    readIdentityPrivateVaultProfile: typeof import("./private-vault.js").readIdentityPrivateVaultProfile;
+    readIdentityPrivateVaultChildrenState: typeof import("./private-vault.js").readIdentityPrivateVaultChildrenState;
     createVault: typeof import("./bootstrap.js").createVault;
     recoverVault: typeof import("./bootstrap.js").recoverVault;
     createVaultClient: typeof import("../clients/owner/index.js").createVaultClient;

package/dist/runtime/index.js

@@ -11,7 +11,7 @@ export { createIdentity, deriveChildIdentity, restoreIdentity, } from "./identit
 export { createChildIdentity, } from "./child-identity.js";
 export { readVaultProfile, writeVaultProfile, } from "./vault-metadata.js";
 export { createWorkspaceStorage, getDefaultWorkspaceDir, } from "./workspace-storage.js";
-export { ensurePrivateVault, readPrivateVaultProfile, readPrivateVaultChildrenState, privateVaultPrefix, privateVaultProfileKey, privateVaultChildrenKey, } from "./private-vault.js";
+export { ensureIdentityPrivateVault, readIdentityPrivateVaultProfile, readIdentityPrivateVaultChildrenState, identityPrivateVaultPrefix, identityPrivateVaultProfileKey, identityPrivateVaultChildrenKey, } from "./private-vault.js";
 export { createVault, recoverVault, } from "./bootstrap.js";
 export { createVaultCore, DefaultVaultCore, VaultCoreError, createDefaultVaultCoreDependencies, DefaultPolicyEngine, createPersistentVaultCoreDependencies, initializeVaultCustody, recoverVaultWorkingKey, DEFAULT_VAULT_KEY_CUSTODY_BLOB_KEY, PersistentVaultAgentIdentityRegistry, PersistentVaultAuditLog, PersistentVaultOwnerIdentityRegistry, PersistentVaultCapabilityRegistry, PersistentVaultCapabilityRevocationRegistry, PersistentVaultCustomHttpFlowRegistry, PersistentVaultRateLimitStore, PersistentVaultReplayGuard, PersistentVaultSecretCustody, PersistentVaultSecretRepository, HttpDispatchExecutor, InMemoryAgentIdentityRegistry, InMemoryCapabilityRegistry, InMemoryCapabilityRevocationRegistry, InMemoryCustomHttpFlowRegistry, InMemoryRateLimitStore, InMemoryReplayGuard, InMemoryAuditLog, InMemoryOwnerIdentityRegistry, InMemorySecretCustody, InMemorySecretRepository, RandomIdGenerator, SignatureOwnerProofVerifier, SignatureAgentProofVerifier, SystemClock, } from "../vault-core/index.js";
 export { createVaultClient, } from "../clients/owner/index.js";

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,eAAe,GAKhB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,6BAA6B,EAC7B,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,GAIxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,YAAY,GAMb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kCAAkC,EAGlC,mBAAmB,EACnB,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,EACtB,kCAAkC,EAIlC,oCAAoC,EACpC,uBAAuB,EACvB,oCAAoC,EACpC,iCAAiC,EACjC,2CAA2C,EAC3C,qCAAqC,EACrC,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,+BAA+B,EAC/B,oBAAoB,EACpB,6BAA6B,EAC7B,0BAA0B,EAC1B,oCAAoC,EACpC,8BAA8B,EAC9B,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,EAE3B,2BAA2B,EAC3B,WAAW,GA+CZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,iBAAiB,GAclB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,iBAAiB,GAQlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,uBAAuB,GAWxB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,eAAe,GAKhB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,qCAAqC,EACrC,0BAA0B,EAC1B,8BAA8B,EAC9B,+BAA+B,GAIhC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,YAAY,GAMb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kCAAkC,EAGlC,mBAAmB,EACnB,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,EACtB,kCAAkC,EAIlC,oCAAoC,EACpC,uBAAuB,EACvB,oCAAoC,EACpC,iCAAiC,EACjC,2CAA2C,EAC3C,qCAAqC,EACrC,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,+BAA+B,EAC/B,oBAAoB,EACpB,6BAA6B,EAC7B,0BAA0B,EAC1B,oCAAoC,EACpC,8BAA8B,EAC9B,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,EAE3B,2BAA2B,EAC3B,WAAW,GA+CZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,iBAAiB,GAclB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,iBAAiB,GAQlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,uBAAuB,GAWxB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/runtime/private-vault.d.ts

@@ -1,28 +1,30 @@
 import type { IStorageProvider } from "../storage/provider.js";
-import type { CreatedIdentity } from "./identity.js";
-export interface PrivateVaultProfile {
+import { type CreatedIdentity } from "./identity.js";
+export interface IdentityPrivateVaultProfile {
     identityId: string;
     nickname?: string;
     publicKey: string;
     parentIdentityId?: string;
     childIndex?: number;
 }
-export interface PrivateVaultChildRecord {
+export interface IdentityPrivateVaultChildRecord {
     identityId: string;
     parentIdentityId: string;
     childIndex: number;
     nickname?: string;
     publicKey: string;
 }
-export interface PrivateVaultChildrenState {
+export interface IdentityPrivateVaultChildrenState {
     nextChildIndex: number;
-    children: PrivateVaultChildRecord[];
+    children: IdentityPrivateVaultChildRecord[];
 }
-export declare function privateVaultPrefix(identityId: string): string;
-export declare function privateVaultProfileKey(identityId: string): string;
-export declare function privateVaultChildrenKey(identityId: string): string;
-export declare function ensurePrivateVault(storage: IStorageProvider, identity: CreatedIdentity): Promise<void>;
-export declare function readPrivateVaultProfile(storage: IStorageProvider, identityId: string): Promise<PrivateVaultProfile | null>;
-export declare function readPrivateVaultChildrenState(storage: IStorageProvider, identityId: string): Promise<PrivateVaultChildrenState>;
-export declare function writePrivateVaultChildrenState(storage: IStorageProvider, identityId: string, state: PrivateVaultChildrenState): Promise<void>;
-export declare function withPrivateVaultLock<T>(storage: IStorageProvider, identityId: string, task: () => Promise<T>): Promise<T>;
+type IdentityPrivateVaultAccess = CreatedIdentity | string;
+export declare function identityPrivateVaultPrefix(identityId: string): string;
+export declare function identityPrivateVaultProfileKey(identityId: string): string;
+export declare function identityPrivateVaultChildrenKey(identityId: string): string;
+export declare function ensureIdentityPrivateVault(storage: IStorageProvider, identity: CreatedIdentity): Promise<void>;
+export declare function readIdentityPrivateVaultProfile(storage: IStorageProvider, identityOrPrivateKey: IdentityPrivateVaultAccess): Promise<IdentityPrivateVaultProfile | null>;
+export declare function readIdentityPrivateVaultChildrenState(storage: IStorageProvider, identityOrPrivateKey: IdentityPrivateVaultAccess): Promise<IdentityPrivateVaultChildrenState>;
+export declare function writeIdentityPrivateVaultChildrenState(storage: IStorageProvider, identityOrPrivateKey: IdentityPrivateVaultAccess, state: IdentityPrivateVaultChildrenState): Promise<void>;
+export declare function withIdentityPrivateVaultLock<T>(storage: IStorageProvider, identityOrPrivateKey: IdentityPrivateVaultAccess, task: () => Promise<T>): Promise<T>;
+export {};

package/dist/runtime/private-vault.js

@@ -1,19 +1,64 @@
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { SEALED_BLOB_VERSION, sealBlob, unsealBlob } from "../sealed/seal.js";
+import { restoreIdentity } from "./identity.js";
 const PRIVATE_VAULT_PREFIX = "vault/private/identities";
 const PRIVATE_VAULT_LOCK_SUFFIX = ".lock";
-export function privateVaultPrefix(identityId) {
+export function identityPrivateVaultPrefix(identityId) {
     return `${PRIVATE_VAULT_PREFIX}/${identityId}`;
 }
-export function privateVaultProfileKey(identityId) {
-    return `${privateVaultPrefix(identityId)}/profile.json`;
+export function identityPrivateVaultProfileKey(identityId) {
+    return `${identityPrivateVaultPrefix(identityId)}/profile.json`;
 }
-export function privateVaultChildrenKey(identityId) {
-    return `${privateVaultPrefix(identityId)}/children.json`;
+export function identityPrivateVaultChildrenKey(identityId) {
+    return `${identityPrivateVaultPrefix(identityId)}/children.json`;
 }
 function lockKey(identityId) {
-    return `${privateVaultPrefix(identityId)}${PRIVATE_VAULT_LOCK_SUFFIX}`;
+    return `${identityPrivateVaultPrefix(identityId)}${PRIVATE_VAULT_LOCK_SUFFIX}`;
 }
-export async function ensurePrivateVault(storage, identity) {
+function normalizeIdentityAccess(identityOrPrivateKey) {
+    if (typeof identityOrPrivateKey === "string") {
+        return restoreIdentity(identityOrPrivateKey);
+    }
+    return identityOrPrivateKey;
+}
+function deriveIdentityPrivateVaultKey(identity) {
+    return createHash("sha256")
+        .update("cbio:identity-private-vault:v1")
+        .update("\n")
+        .update(identity.identityId)
+        .update("\n")
+        .update(identity.privateKey)
+        .digest("base64url");
+}
+function sealIdentityPrivateVaultJson(identity, value, kind) {
+    const sealed = sealBlob({
+        version: SEALED_BLOB_VERSION,
+        secrets: {
+            payload: JSON.stringify(value),
+        },
+        secretMetadata: {
+            kind,
+            identityId: identity.identityId,
+        },
+    }, deriveIdentityPrivateVaultKey(identity));
+    return Buffer.from(sealed, "utf8");
+}
+function unsealIdentityPrivateVaultJson(identity, payload, expectedKind) {
+    const unsealed = unsealBlob(payload.toString("utf8"), deriveIdentityPrivateVaultKey(identity));
+    if (unsealed.secretMetadata.kind !== expectedKind) {
+        throw new Error(`unexpected identity private vault payload kind: ${String(unsealed.secretMetadata.kind)}`);
+    }
+    if (unsealed.secretMetadata.identityId !== identity.identityId) {
+        throw new Error("identity private vault payload identity mismatch");
+    }
+    const secretPayload = unsealed.secrets.payload;
+    if (typeof secretPayload !== "string") {
+        throw new Error("identity private vault payload missing body");
+    }
+    return JSON.parse(secretPayload);
+}
+export async function ensureIdentityPrivateVault(storage, identity) {
     const profile = {
         identityId: identity.identityId,
         nickname: identity.nickname,
@@ -21,40 +66,44 @@ export async function ensurePrivateVault(storage, identity) {
         parentIdentityId: identity.parentIdentityId,
         childIndex: identity.childIndex,
     };
-    await storage.write(privateVaultProfileKey(identity.identityId), Buffer.from(JSON.stringify(profile, null, 2)));
-    const childrenKey = privateVaultChildrenKey(identity.identityId);
+    await storage.write(identityPrivateVaultProfileKey(identity.identityId), sealIdentityPrivateVaultJson(identity, profile, "identity_private_vault_profile"));
+    const childrenKey = identityPrivateVaultChildrenKey(identity.identityId);
     if (!(await storage.has(childrenKey))) {
         const emptyState = {
             nextChildIndex: 0,
             children: [],
         };
-        await storage.write(childrenKey, Buffer.from(JSON.stringify(emptyState, null, 2)));
+        await storage.write(childrenKey, sealIdentityPrivateVaultJson(identity, emptyState, "identity_private_vault_children"));
     }
 }
-export async function readPrivateVaultProfile(storage, identityId) {
-    const raw = await storage.read(privateVaultProfileKey(identityId));
+export async function readIdentityPrivateVaultProfile(storage, identityOrPrivateKey) {
+    const identity = normalizeIdentityAccess(identityOrPrivateKey);
+    const raw = await storage.read(identityPrivateVaultProfileKey(identity.identityId));
     if (!raw) {
         return null;
     }
-    return JSON.parse(raw.toString("utf8"));
+    return unsealIdentityPrivateVaultJson(identity, raw, "identity_private_vault_profile");
 }
-export async function readPrivateVaultChildrenState(storage, identityId) {
-    const raw = await storage.read(privateVaultChildrenKey(identityId));
+export async function readIdentityPrivateVaultChildrenState(storage, identityOrPrivateKey) {
+    const identity = normalizeIdentityAccess(identityOrPrivateKey);
+    const raw = await storage.read(identityPrivateVaultChildrenKey(identity.identityId));
     if (!raw) {
         return { nextChildIndex: 0, children: [] };
     }
-    const parsed = JSON.parse(raw.toString("utf8"));
+    const parsed = unsealIdentityPrivateVaultJson(identity, raw, "identity_private_vault_children");
     return {
         nextChildIndex: parsed.nextChildIndex ?? parsed.children.length,
         children: parsed.children ?? [],
     };
 }
-export async function writePrivateVaultChildrenState(storage, identityId, state) {
-    await storage.write(privateVaultChildrenKey(identityId), Buffer.from(JSON.stringify(state, null, 2)));
+export async function writeIdentityPrivateVaultChildrenState(storage, identityOrPrivateKey, state) {
+    const identity = normalizeIdentityAccess(identityOrPrivateKey);
+    await storage.write(identityPrivateVaultChildrenKey(identity.identityId), sealIdentityPrivateVaultJson(identity, state, "identity_private_vault_children"));
 }
-export async function withPrivateVaultLock(storage, identityId, task) {
+export async function withIdentityPrivateVaultLock(storage, identityOrPrivateKey, task) {
+    const identity = normalizeIdentityAccess(identityOrPrivateKey);
     if (storage.withLock) {
-        return storage.withLock(lockKey(identityId), task);
+        return storage.withLock(lockKey(identity.identityId), task);
     }
     return task();
 }

package/dist/runtime/private-vault.js.map

@@ -1 +1 @@
-{"version":3,"file":"private-vault.js","sourceRoot":"","sources":["../../src/runtime/private-vault.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"private-vault.js","sourceRoot":"","sources":["../../src/runtime/private-vault.ts"],"names":[],"mappings":"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"}

package/docs/IDENTITY_MODEL.md

@@ -80,6 +80,8 @@ For existing private keys, the runtime exposes `restoreIdentity(...)`, which rec
 
 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"

package/docs/REFERENCE.md

@@ -18,7 +18,9 @@ The main constructors are:
 - `createIdentity(...)`
 - `createChildIdentity(...)`
 - `deriveChildIdentity(...)`
-- `ensurePrivateVault(...)`
+- `ensureIdentityPrivateVault(...)`
+- `readIdentityPrivateVaultProfile(...)`
+- `readIdentityPrivateVaultChildrenState(...)`
 - `restoreIdentity(...)`
 - `createVault(...)`
 - `recoverVault(...)`
@@ -76,13 +78,29 @@ Role rules:
 
 `deriveChildIdentity(parentIdentity, childIndex, { nickname })` deterministically reconstructs a child identity for a known `childIndex`.
 
-`ensurePrivateVault(storage, identity)` creates or refreshes the identity's fixed namespace under `vault/private/identities/<identityId>/...`. That namespace stores identity-level files such as:
+`ensureIdentityPrivateVault(storage, identity)` creates or refreshes the identity's fixed namespace under `vault/private/identities/<identityId>/...`.
+
+That namespace stores identity-level files such as:
 
 - `profile.json`
 - `children.json`
 
+Those files are encrypted at rest with a key derived from that identity's private key. They are not readable as plain JSON on disk.
+
 `restoreIdentity(privateKey)` returns the same shape for an existing private key.
 
+`readIdentityPrivateVaultProfile(storage, identityOrPrivateKey)` decrypts and returns the current identity profile for the supplied identity or private key.
+
+`readIdentityPrivateVaultChildrenState(storage, identityOrPrivateKey)` decrypts and returns the child index state for the supplied identity or private key.
+
+Typical relationship lookup flow when you already have a private key:
+
+1. `const identity = restoreIdentity(privateKey)`
+2. `const profile = await readIdentityPrivateVaultProfile(storage, identity)`
+3. `const children = await readIdentityPrivateVaultChildrenState(storage, identity)`
+
+`profile.parentIdentityId` tells you whether the identity is a child. `children.children` tells you which child identities were created beneath that identity.
+
 ## Secret-Flow Model
 
 The current HTTP-facing API supports two explicit secret-flow classes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-ai-company/cbio-node-runtime",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Node.js runtime for cbio identity and credential vault. Library only, no CLI or TUI.",
   "type": "module",
   "main": "./dist/runtime/index.js",