@the-ai-company/cbio-node-runtime 1.4.0 → 1.6.0

package/README.md

@@ -8,6 +8,7 @@ Node.js vault runtime with a hard-cut architecture: vault core first, explicit c
 
 - [English](README.md)
 - [Custody Model](docs/CUSTODY_MODEL.md)
+- [Identity Model](docs/IDENTITY_MODEL.md)
 - [中文](docs/zh/README.md)
 - [日本語](docs/ja/README.md)
 - [한국어](docs/ko/README.md)
@@ -40,8 +41,9 @@ npm install @the-ai-company/cbio-node-runtime
 import {
   createVaultService,
   createDefaultVaultCoreDependencies,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   createOwnerHttpFlowBoundary,
   createStandardAcquireBoundary,
   createStandardDispatchBoundary,
@@ -54,6 +56,21 @@ import {
 
 ## Architecture
 
+Core terms:
+
+- `identity`
+  An external principal represented by a public/private keypair.
+- `owner`
+  The single admin role that a vault binds to one identity.
+- `agent`
+  A delegated role that a vault binds to an identity registered by the owner.
+
+Important role rule:
+
+- outside the vault there are only identities
+- inside a specific vault, those identities may be bound to roles such as `owner` or `agent`
+- identities are independent; they do not imply parent/child lineage or inheritance by default
+
 The public runtime surface follows four hard rules:
 
 1. Secret plaintext lives only in vault core.
@@ -116,10 +133,12 @@ This package now exposes the production local vault runtime surface as the prima
 ## Example Shape
 
 ```ts
+const ownerIdentity = createIdentity({ nickname: 'owner-main' });
+const agentIdentity = createIdentity({ nickname: 'agent-worker' });
 const vault = createVaultService(createDefaultVaultCoreDependencies());
-const owner = createOwnerClient(ownerIdentity, vault, ownerSigner, clock);
+const owner = createOwnerClient({ ownerId: ownerIdentity.identityId }, vault, new LocalSigner(ownerIdentity), clock);
 const transport = new LocalVaultTransport(vault, capability.capabilityId);
-const agent = createAgentClient(agentIdentity, capability, signer, transport, clock);
+const agent = createAgentClient({ agentId: agentIdentity.identityId }, capability, new LocalSigner(agentIdentity), transport, clock);
 ```
 
 Capability example:
@@ -183,22 +202,19 @@ console.log(exported.plaintext);
 Persistent custody bootstrap example:
 
 ```ts
+const ownerIdentity = createIdentity({ nickname: 'owner-main' });
 const storage = new FsStorageProvider('/tmp/cbio-vault');
-const initializedVault = await initializePersistentVault(storage, {
+const createdVault = await createVault(storage, {
   vaultId: 'vault-persistent',
-  bootstrapOwner: {
-    vaultId: { value: 'vault-persistent' },
-    ownerId: 'owner-1',
-    publicKey: ownerPublicKey,
-  },
+  ownerIdentity,
 });
 
 // Show once to the owner and let them store it offline.
-console.log(initializedVault.initializedCustody.vaultRecoveryKey);
+console.log(createdVault.initializedCustody.vaultRecoveryKey);
 
-const recoveredVault = await recoverPersistentVault(storage, {
+const recoveredVault = await recoverVault(storage, {
   vaultId: 'vault-persistent',
-  vaultRecoveryKey: initializedVault.initializedCustody.vaultRecoveryKey,
+  vaultRecoveryKey: createdVault.initializedCustody.vaultRecoveryKey,
 });
 ```
 

package/dist/protocol/childSecretNaming.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vault secret naming for child identities. CHILD_KEY_PREFIX, getChildIdentitySecretName.
+ * Not protocol objects. Protocol talks about public identities and signatures,
+ * not local secret names or internal storage prefixes.
+ */
+export declare const CHILD_KEY_PREFIX: "cbio:child:";
+export declare function getChildIdentitySecretName(publicKey: string): string;

package/dist/protocol/childSecretNaming.js

@@ -0,0 +1,12 @@
+/**
+ * Vault secret naming for child identities. CHILD_KEY_PREFIX, getChildIdentitySecretName.
+ * Not protocol objects. Protocol talks about public identities and signatures,
+ * not local secret names or internal storage prefixes.
+ */
+import * as crypto from 'node:crypto';
+export const CHILD_KEY_PREFIX = 'cbio:child:';
+export function getChildIdentitySecretName(publicKey) {
+    const hash = crypto.createHash('sha256').update(publicKey).digest('hex').substring(0, 12);
+    return CHILD_KEY_PREFIX + hash;
+}
+//# sourceMappingURL=childSecretNaming.js.map

package/dist/protocol/childSecretNaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"childSecretNaming.js","sourceRoot":"","sources":["../../src/protocol/childSecretNaming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAsB,CAAC;AAEvD,MAAM,UAAU,0BAA0B,CAAC,SAAiB;IACxD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1F,OAAO,gBAAgB,GAAG,IAAI,CAAC;AACnC,CAAC"}

package/dist/protocol/identity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Claw-biometric Core Identity. Runtime utilities over protocol primitives.
+ * getVaultPath (runtime). Re-exports protocol for consumers.
+ */
+import { deriveRootAgentId } from '@the-ai-company/cbio-protocol';
+import { getChildIdentitySecretName, CHILD_KEY_PREFIX } from './childSecretNaming.js';
+export { deriveRootAgentId, getChildIdentitySecretName, CHILD_KEY_PREFIX };
+export declare function getVaultPath(publicKey: string): string;

package/dist/protocol/identity.js

@@ -0,0 +1,16 @@
+/**
+ * Claw-biometric Core Identity. Runtime utilities over protocol primitives.
+ * getVaultPath (runtime). Re-exports protocol for consumers.
+ */
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { deriveRootAgentId } from '@the-ai-company/cbio-protocol';
+import { getChildIdentitySecretName, CHILD_KEY_PREFIX } from './childSecretNaming.js';
+export { deriveRootAgentId, getChildIdentitySecretName, CHILD_KEY_PREFIX };
+export function getVaultPath(publicKey) {
+    const hash = crypto.createHash('sha256').update(publicKey).digest('hex').substring(0, 12);
+    const baseDir = process.env.C_BIO_VAULT_DIR || path.join(os.homedir(), '.c-bio');
+    return path.join(baseDir, `vault_${hash}.enc`);
+}
+//# sourceMappingURL=identity.js.map

package/dist/protocol/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/protocol/identity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,CAAC;AAE3E,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACjF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,IAAI,MAAM,CAAC,CAAC;AACnD,CAAC"}

package/dist/runtime/bootstrap.d.ts

@@ -1,20 +1,21 @@
-import { type CreatePersistentVaultCoreDependenciesOptions, type InitializedVaultCustody, type InitializeVaultCustodyOptions, type OwnerIdentityRecord, type VaultCore } from "../vault-core/index.js";
+import { type CreatePersistentVaultCoreDependenciesOptions, type InitializedVaultCustody, type InitializeVaultCustodyOptions, type VaultCore } from "../vault-core/index.js";
 import { type VaultService, type VaultCustomFlowResolver } from "../vault-ingress/index.js";
 import type { IStorageProvider } from "../storage/provider.js";
-export interface InitializePersistentVaultOptions extends Omit<CreatePersistentVaultCoreDependenciesOptions, "vaultWorkingKey"> {
+import type { CreatedIdentity } from "./identity.js";
+export interface CreateVaultOptions extends Omit<CreatePersistentVaultCoreDependenciesOptions, "vaultWorkingKey"> {
     custody?: InitializeVaultCustodyOptions;
-    bootstrapOwner: OwnerIdentityRecord;
+    ownerIdentity: CreatedIdentity;
     vault?: {
         customFlows?: VaultCustomFlowResolver;
         fetchImpl?: typeof fetch;
     };
 }
-export interface InitializedPersistentVault {
+export interface CreatedVault {
     initializedCustody: InitializedVaultCustody;
     core: VaultCore;
     vault: VaultService;
 }
-export interface RecoverPersistentVaultOptions extends Omit<CreatePersistentVaultCoreDependenciesOptions, "vaultWorkingKey"> {
+export interface RecoverVaultOptions extends Omit<CreatePersistentVaultCoreDependenciesOptions, "vaultWorkingKey"> {
     vaultRecoveryKey: string;
     custodyStorageKey?: string;
     vault?: {
@@ -22,10 +23,10 @@ export interface RecoverPersistentVaultOptions extends Omit<CreatePersistentVaul
         fetchImpl?: typeof fetch;
     };
 }
-export interface RecoveredPersistentVault {
+export interface RecoveredVault {
     vaultWorkingKey: string;
     core: VaultCore;
     vault: VaultService;
 }
-export declare function initializePersistentVault(storage: IStorageProvider, options: InitializePersistentVaultOptions): Promise<InitializedPersistentVault>;
-export declare function recoverPersistentVault(storage: IStorageProvider, options: RecoverPersistentVaultOptions): Promise<RecoveredPersistentVault>;
+export declare function createVault(storage: IStorageProvider, options: CreateVaultOptions): Promise<CreatedVault>;
+export declare function recoverVault(storage: IStorageProvider, options: RecoverVaultOptions): Promise<RecoveredVault>;

package/dist/runtime/bootstrap.js

@@ -1,21 +1,26 @@
 import { createVaultCore } from "../vault-core/core.js";
 import { createPersistentVaultCoreDependencies, initializeVaultCustody, recoverVaultWorkingKey, } from "../vault-core/index.js";
 import { wrapVaultCoreAsVaultService, } from "../vault-ingress/index.js";
-export async function initializePersistentVault(storage, options) {
+export async function createVault(storage, options) {
     const initializedCustody = await initializeVaultCustody(storage, options.custody);
     const deps = createPersistentVaultCoreDependencies(storage, {
         ...options,
         vaultWorkingKey: initializedCustody.vaultWorkingKey,
     });
     const core = createVaultCore(deps);
-    await core.bootstrapOwnerIdentity(options.bootstrapOwner);
+    const bootstrapOwner = {
+        vaultId: core.vaultId,
+        ownerId: options.ownerIdentity.identityId,
+        publicKey: options.ownerIdentity.publicKey,
+    };
+    await core.bootstrapOwnerIdentity(bootstrapOwner);
     return {
         initializedCustody,
         core,
         vault: wrapVaultCoreAsVaultService(core, options.vault),
     };
 }
-export async function recoverPersistentVault(storage, options) {
+export async function recoverVault(storage, options) {
     const vaultWorkingKey = await recoverVaultWorkingKey(storage, options.vaultRecoveryKey, options.custodyStorageKey);
     const deps = createPersistentVaultCoreDependencies(storage, {
         ...options,

package/dist/runtime/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,GAMvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,GAG5B,MAAM,2BAA2B,CAAC;AAiCnC,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAyB,EACzB,OAAyC;IAEzC,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,qCAAqC,CAAC,OAAO,EAAE;QAC1D,GAAG,OAAO;QACV,eAAe,EAAE,kBAAkB,CAAC,eAAe;KACpD,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D,OAAO;QACL,kBAAkB;QAClB,IAAI;QACJ,KAAK,EAAE,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAyB,EACzB,OAAsC;IAEtC,MAAM,eAAe,GAAG,MAAM,sBAAsB,CAClD,OAAO,EACP,OAAO,CAAC,gBAAgB,EACxB,OAAO,CAAC,iBAAiB,CAC1B,CAAC;IACF,MAAM,IAAI,GAAG,qCAAqC,CAAC,OAAO,EAAE;QAC1D,GAAG,OAAO;QACV,eAAe;KAChB,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,KAAK,EAAE,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC;KACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,GAMvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,GAG5B,MAAM,2BAA2B,CAAC;AAkCnC,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAyB,EACzB,OAA2B;IAE3B,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,qCAAqC,CAAC,OAAO,EAAE;QAC1D,GAAG,OAAO;QACV,eAAe,EAAE,kBAAkB,CAAC,eAAe;KACpD,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,cAAc,GAAwB;QAC1C,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,UAAU;QACzC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,SAAS;KAC3C,CAAC;IACF,MAAM,IAAI,CAAC,sBAAsB,CAAC,cAAc,CAAC,CAAC;IAClD,OAAO;QACL,kBAAkB;QAClB,IAAI;QACJ,KAAK,EAAE,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAyB,EACzB,OAA4B;IAE5B,MAAM,eAAe,GAAG,MAAM,sBAAsB,CAClD,OAAO,EACP,OAAO,CAAC,gBAAgB,EACxB,OAAO,CAAC,iBAAiB,CAC1B,CAAC;IACF,MAAM,IAAI,GAAG,qCAAqC,CAAC,OAAO,EAAE;QAC1D,GAAG,OAAO;QACV,eAAe;KAChB,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,KAAK,EAAE,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC;KACxD,CAAC;AACJ,CAAC"}

package/dist/runtime/identity.d.ts

@@ -0,0 +1,10 @@
+export interface CreatedIdentity {
+    identityId: string;
+    nickname?: string;
+    publicKey: string;
+    privateKey: string;
+}
+export interface CreateIdentityOptions {
+    nickname?: string;
+}
+export declare function createIdentity(options?: CreateIdentityOptions): CreatedIdentity;

package/dist/runtime/identity.js

@@ -0,0 +1,16 @@
+import { generateIdentityKeys } from "../protocol/crypto.js";
+import { deriveRootAgentId } from "../protocol/identity.js";
+export function createIdentity(options = {}) {
+    const keyPair = generateIdentityKeys();
+    if (!keyPair.publicKey || !keyPair.privateKey) {
+        throw new Error("identity generation failed");
+    }
+    const nickname = options.nickname?.trim() ? options.nickname.trim() : undefined;
+    return {
+        identityId: deriveRootAgentId(keyPair.publicKey),
+        nickname,
+        publicKey: keyPair.publicKey,
+        privateKey: keyPair.privateKey,
+    };
+}
+//# sourceMappingURL=identity.js.map

package/dist/runtime/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/runtime/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAa5D,MAAM,UAAU,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,OAAO,GAAG,oBAAoB,EAAE,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,OAAO;QACL,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC;QAChD,QAAQ;QACR,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;AACJ,CAAC"}

package/dist/runtime/index.d.ts

@@ -3,11 +3,12 @@
  * Hard-cut public surface: vault core plus explicit clients only.
  */
 export { IdentityError, IdentityErrorCode } from "../errors.js";
-export { generateIdentityKeys, derivePublicKey, LocalSigner } from "../protocol/crypto.js";
+export { derivePublicKey, LocalSigner } from "../protocol/crypto.js";
 export type { IStorageProvider } from "../storage/provider.js";
 export { FsStorageProvider } from "../storage/fs.js";
 export { MemoryStorageProvider } from "../storage/memory.js";
-export { initializePersistentVault, recoverPersistentVault, type InitializePersistentVaultOptions, type InitializedPersistentVault, type RecoverPersistentVaultOptions, type RecoveredPersistentVault, } from "./bootstrap.js";
+export { createIdentity, type CreateIdentityOptions, type CreatedIdentity, } from "./identity.js";
+export { createVault, recoverVault, type CreateVaultOptions, type CreatedVault, type RecoverVaultOptions, type RecoveredVault, } 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, PersistentVaultAuditLog, 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 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 { createOwnerClient, type OwnerClient, type OwnerIdentity, type OwnerSigner, type OwnerAuditQueryInput, type OwnerExportSecretInput, type OwnerRegisterCapabilityInput, type OwnerRegisterCustomHttpFlowInput, type OwnerRegisterAgentIdentityInput, type OwnerSecretTargetBinding, type OwnerWriteSecretInput, } from "../clients/owner/index.js";
 export { createAgentClient, type AgentClient, type AgentIdentity, type AgentCapabilityEnvelope, type AgentDispatchIntent, type AgentDispatchTransport, type AgentSigner, } from "../clients/agent/index.js";

package/dist/runtime/index.js

@@ -3,10 +3,11 @@
  * Hard-cut public surface: vault core plus explicit clients only.
  */
 export { IdentityError, IdentityErrorCode } from "../errors.js";
-export { generateIdentityKeys, derivePublicKey, LocalSigner } from "../protocol/crypto.js";
+export { derivePublicKey, LocalSigner } from "../protocol/crypto.js";
 export { FsStorageProvider } from "../storage/fs.js";
 export { MemoryStorageProvider } from "../storage/memory.js";
-export { initializePersistentVault, recoverPersistentVault, } from "./bootstrap.js";
+export { createIdentity, } from "./identity.js";
+export { createVault, recoverVault, } from "./bootstrap.js";
 export { createVaultCore, DefaultVaultCore, VaultCoreError, createDefaultVaultCoreDependencies, DefaultPolicyEngine, createPersistentVaultCoreDependencies, initializeVaultCustody, recoverVaultWorkingKey, DEFAULT_VAULT_KEY_CUSTODY_BLOB_KEY, PersistentVaultAuditLog, 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 { createOwnerClient, } from "../clients/owner/index.js";
 export { createAgentClient, } from "../clients/agent/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,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,yBAAyB,EACzB,sBAAsB,GAKvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kCAAkC,EAGlC,mBAAmB,EACnB,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,EACtB,kCAAkC,EAIlC,uBAAuB,EACvB,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,GA8CZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,iBAAiB,GAWlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,iBAAiB,GAOlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,uBAAuB,GAWxB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,mBAAmB,GACpB,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;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,YAAY,GAKb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kCAAkC,EAGlC,mBAAmB,EACnB,qCAAqC,EACrC,sBAAsB,EACtB,sBAAsB,EACtB,kCAAkC,EAIlC,uBAAuB,EACvB,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,GA8CZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,iBAAiB,GAWlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,iBAAiB,GAOlB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,8BAA8B,EAC9B,uBAAuB,GAWxB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,mBAAmB,GACpB,MAAM,8BAA8B,CAAC"}

package/docs/ARCHITECTURE.md

@@ -5,11 +5,30 @@ Current product architecture is vault-first.
 Related design note:
 
 - [Custody Model](CUSTODY_MODEL.md)
+- [Identity Model](IDENTITY_MODEL.md)
 
 Recommended persistent-vault lifecycle:
 
-- initialize through `initializePersistentVault(...)`
-- recover through `recoverPersistentVault(...)`
+- create through `createVault(...)`
+- recover through `recoverVault(...)`
+
+## Identity And Roles
+
+The runtime distinguishes external identities from vault-local roles.
+
+- `identity`
+  An external principal represented by a public/private keypair.
+- `owner`
+  The single admin role that a vault binds to one identity.
+- `agent`
+  A delegated role that a vault binds to an identity registered by the owner.
+
+This means:
+
+- outside the vault there are only identities
+- inside a specific vault, identities are bound to roles such as `owner` or `agent`
+- identities are independent; there is no built-in parent/child lineage between identities
+- an identity may be the `owner` of one vault and an `agent` in another vault
 
 ## Public Modules
 

package/docs/CUSTODY_MODEL.md

@@ -144,8 +144,8 @@ Future hardening such as MFA/TOTP may be added on top of this model, but it does
 
 The runtime now includes:
 
-1. formal persistent-vault initialization through `initializePersistentVault(...)`
-2. formal recovery-key based re-entry through `recoverPersistentVault(...)`
+1. formal vault creation through `createVault(...)`
+2. formal recovery-key based re-entry through `recoverVault(...)`
 3. explicit `vaultWorkingKey` terminology in the persistent dependency surface
 4. continued support for explicit owner export through `exportSecret(...)`
 

package/docs/IDENTITY_MODEL.md

@@ -0,0 +1,122 @@
+# Identity Model
+
+This document defines the runtime's current identity model.
+
+Its purpose is to separate three things that are easy to confuse:
+
+- cryptographic identity
+- human-readable naming
+- vault-local role assignment
+
+## Core Rule
+
+Outside the vault, there are only identities.
+
+Inside a specific vault, identities may be bound to roles such as `owner` or `agent`.
+
+This means:
+
+- `owner` is not a different species of identity
+- `agent` is not a different species of identity
+- role comes from vault-local authorization state, not from the keypair itself
+
+## Identity
+
+An `identity` is an external principal represented by a public/private keypair.
+
+Properties:
+
+- independent by default
+- no built-in parent/child lineage
+- no built-in inheritance
+- no built-in "owner creates agent identity" relationship
+
+An identity may participate in multiple vaults, and may hold different roles in different vaults.
+
+Example:
+
+- the same identity may be `owner` in vault A
+- and `agent` in vault B
+
+## Identity Material
+
+The runtime treats public/private keys as the cryptographic identity material.
+
+- `publicKey`
+  used for verification and binding
+- `privateKey`
+  held outside the vault by the identity holder
+
+The vault should not treat a display label as the root identity truth.
+
+## Stable Identity ID
+
+The runtime already has a stable public-key-derived identity primitive available through `deriveRootAgentId(...)`.
+
+That derived value is useful for:
+
+- stable machine identity
+- local naming
+- deterministic display-independent references
+
+It should not, by itself, determine vault-local role.
+
+## Labels And Human-Readable Names
+
+Human-friendly names are still useful.
+
+Examples:
+
+- `owner-1`
+- `agent-prod`
+- `crawler`
+- `alice`
+
+These should be treated as labels, aliases, or local names rather than the deepest identity truth.
+
+The runtime now exposes this concept directly as optional `nickname` on `createIdentity(...)`.
+
+In other words:
+
+- public key or a stable derived id answers "who is this cryptographically"
+- label answers "what do humans call this identity here"
+
+## Vault Roles
+
+Vault roles are authorization bindings applied to identities inside a specific vault.
+
+Current role model:
+
+- `owner`
+  the single admin role for one vault
+- `agent`
+  a delegated role registered and authorized by the owner
+
+These roles are vault-local.
+
+So:
+
+- an identity does not become globally `owner`
+- an identity does not become globally `agent`
+- the same identity may appear with different roles in different vaults
+
+## Current Runtime Reality
+
+Today the runtime API still uses fields such as:
+
+- `ownerId`
+- `agentId`
+
+In practice, these currently behave closer to role-bound local identifiers or labels than to the deepest cryptographic identity root.
+
+The long-term intended direction is:
+
+1. keep cryptographic identity separate from labels
+2. keep vault-local role separate from both
+3. avoid treating naming conventions such as prefixes as identity truth
+
+## Non-Goals
+
+This model does not require every current API field to be renamed immediately.
+
+Its purpose is to define the correct semantics first, so later API changes can converge on one stable interpretation.

package/docs/REFERENCE.md

@@ -17,8 +17,9 @@ The main constructors are:
 
 - `createVaultCore(...)`
 - `createVaultService(...)`
-- `initializePersistentVault(...)`
-- `recoverPersistentVault(...)`
+- `createIdentity(...)`
+- `createVault(...)`
+- `recoverVault(...)`
 - `createOwnerClient(...)`
 - `createAgentClient(...)`
 - `LocalVaultTransport`
@@ -29,14 +30,41 @@ Related design note:
 
 Recommended persistent-vault entrypoints:
 
-- `initializePersistentVault(...)`
-- `recoverPersistentVault(...)`
+- `createVault(...)`
+- `recoverVault(...)`
 
 Lower-level custody helpers:
 
 - `initializeVaultCustody(...)`
 - `recoverVaultWorkingKey(...)`
 
+## Terms
+
+- `identity`
+  An external principal represented by a public/private keypair.
+- `owner`
+  The single admin role that a vault binds to one identity.
+- `agent`
+  A delegated role that a vault binds to an identity registered by the owner.
+
+Role rules:
+
+- outside the vault there are only identities
+- inside a vault, identities are bound to roles such as `owner` or `agent`
+- identities are independent; there is no built-in lineage or inheritance between identities
+- the same identity may be `owner` in one vault and `agent` in another
+
+## Identity Creation
+
+`createIdentity(...)` returns:
+
+- `identityId`
+- `publicKey`
+- `privateKey`
+- optional `nickname`
+
+`nickname` is human-readable only. It does not affect the derived `identityId`, cryptographic verification, or vault-local role binding.
+
 ## Secret-Flow Model
 
 The current HTTP-facing API supports two explicit secret-flow classes:
@@ -93,7 +121,7 @@ The runtime treats this first owner as the single vault admin. Additional princi
 
 ## Owner Client
 
-`clients/owner` is the owner-facing caller surface.
+`clients/owner` is the caller surface for the identity currently bound to the vault's single owner role.
 
 Current owner operations:
 
@@ -142,7 +170,7 @@ const exportedSecret = await owner.exportSecret({
 
 ## Agent Client
 
-`clients/agent` creates signed dispatch requests. It never receives plaintext secrets.
+`clients/agent` creates signed dispatch requests for an identity currently bound to an agent role in that vault. It never receives plaintext secrets.
 
 Current dispatch capabilities use `dispatch_http` as the explicit secret-send operation.
 It is intended for standard secret-backed resource access, not for token mint / refresh / exchange / registration-finalize style acquisition flows.
@@ -294,8 +322,9 @@ If the custom flow mode includes secret acquisition, the owner also defines a re
 - persistent replay guard
 - persistent rate-limit state
 - persistent capability revocation state
-
-It still expects caller-provided identity registries unless you supply your own persistent registry adapters.
+- persistent owner identity record
+- persistent agent identity registry
+- persistent capability registry
 
 ## Storage Provider
 

package/docs/es/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 Ruta principal recomendada para vault persistente:
 
-- inicializar el vault persistente con `initializePersistentVault(...)`
-- recuperar el vault persistente con `recoverPersistentVault(...)` usando la recovery key
+- crear el vault persistente con `createVault(...)`
+- recuperar el vault persistente con `recoverVault(...)` usando la recovery key
 
 La API antigua centrada en `CbioIdentity` ya no es la superficie principal del producto.
 

package/docs/fr/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 Chemin principal recommande pour un vault persistant :
 
-- initialiser le vault persistant avec `initializePersistentVault(...)`
-- restaurer le vault persistant avec `recoverPersistentVault(...)` via la recovery key
+- creer le vault persistant avec `createVault(...)`
+- restaurer le vault persistant avec `recoverVault(...)` via la recovery key
 
 L'ancienne API centree sur `CbioIdentity` n'est plus la surface principale du produit.
 

package/docs/ja/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 推奨される persistent-vault の主経路:
 
-- `initializePersistentVault(...)` で persistent vault を初期化する
-- `recoverPersistentVault(...)` で recovery key を使って persistent vault を復旧する
+- `createVault(...)` で persistent vault を作成する
+- `recoverVault(...)` で recovery key を使って persistent vault を復旧する
 
 旧 `CbioIdentity` 中心 API は、もはや主要な公開面ではありません。
 

package/docs/ko/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 권장되는 persistent-vault 주 경로:
 
-- `initializePersistentVault(...)` 로 persistent vault 를 초기화합니다
-- `recoverPersistentVault(...)` 로 recovery key 를 사용해 persistent vault 를 복구합니다
+- `createVault(...)` 로 persistent vault 를 생성합니다
+- `recoverVault(...)` 로 recovery key 를 사용해 persistent vault 를 복구합니다
 
 이전 `CbioIdentity` 중심 API 는 더 이상 주요 제품 표면이 아닙니다.
 

package/docs/pt/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 Caminho principal recomendado para vault persistente:
 
-- inicializar o vault persistente com `initializePersistentVault(...)`
-- recuperar o vault persistente com `recoverPersistentVault(...)` usando a recovery key
+- criar o vault persistente com `createVault(...)`
+- recuperar o vault persistente com `recoverVault(...)` usando a recovery key
 
 A antiga API centrada em `CbioIdentity` nao e mais a superficie principal do produto.
 

package/docs/zh/README.md

@@ -19,8 +19,9 @@ npm install @the-ai-company/cbio-node-runtime
 ```ts
 import {
   createVaultService,
-  initializePersistentVault,
-  recoverPersistentVault,
+  createIdentity,
+  createVault,
+  recoverVault,
   LocalVaultTransport,
   createOwnerClient,
   createAgentClient,
@@ -37,8 +38,8 @@ import {
 
 推荐的持久化主路径：
 
-- 通过 `initializePersistentVault(...)` 初始化持久化 vault
-- 通过 `recoverPersistentVault(...)` 用 recovery key 恢复持久化 vault
+- 通过 `createVault(...)` 创建持久化 vault
+- 通过 `recoverVault(...)` 用 recovery key 恢复持久化 vault
 
 ## 构建
 

package/package.json

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