@the-ai-company/cbio-node-runtime 0.31.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claw-biometric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# cbio Node Runtime
+
+Node.js runtime for cbio identity and credential vault. Library only.
+
+**⚠️ Actively under development — not a stable release.**
+
+**Source:** [https://github.com/TheAICompany/cbio-node-runtime](https://github.com/TheAICompany/cbio-node-runtime)
+
+## Documentation / 文档 / ドキュメント / 문서 / Docs
+
+- [English](README.md)
+- [中文](docs/zh/README.md)
+- [日本語](docs/ja/README.md)
+- [한국어](docs/ko/README.md)
+- [Español](docs/es/README.md)
+- [Português](docs/pt/README.md)
+- [Français](docs/fr/README.md)
+
+---
+
+- No CLI
+- No TUI
+
+Import and use `CbioIdentity`, `CbioAgent` from the main export.
+
+## Install
+
+```bash
+npm install @the-ai-company/cbio-node-runtime
+```
+
+## Usage
+
+```ts
+import { CbioIdentity, generateIdentityKeys } from '@the-ai-company/cbio-node-runtime';
+
+const keys = generateIdentityKeys();
+const identity = await CbioIdentity.load({ privateKey: keys.privateKey });
+```
+
+## Build
+
+```bash
+npm run build
+npm run test
+```

package/dist/agent/agent.d.ts

@@ -0,0 +1,234 @@
+import { Signer, KeyPair } from "../protocol/crypto.js";
+import { CbioVault, type MergeResult, type SecretPolicy } from "../vault/vault.js";
+import { AuthClient, type FetchWithAuthOptions } from "../http/authClient.js";
+import { SecretAcquisition, type FetchJsonAndAddSecretOptions, type FetchJsonAndUpdateSecretOptions, type FetchResult } from "../http/secretAcquisition.js";
+import type { ActivityLogEntry, ActivityLogMetadata } from "../audit/ActivityLog.js";
+import { type IssuedAgentIdentity, type RevocationRecord } from "@the-ai-company/cbio-protocol";
+import type { IStorageProvider } from "../storage/provider.js";
+interface ManagedAgentRecord {
+    agentId: string;
+    publicKey: string;
+    privateKey: string;
+    issuedIdentity: IssuedAgentIdentity;
+    /** Vault storage key used when the managed agent was issued. Enables loadManagedAgent to restore the same binding. */
+    storageKey?: string;
+}
+export interface IdentityLoadKeys {
+    privateKey: string;
+    publicKey?: string;
+}
+export interface IdentityLoadOptions {
+    storage?: IStorageProvider;
+    storageKey?: string;
+    activityLog?: ActivityLogConfig;
+    issuedIdentity?: IssuedAgentIdentity;
+}
+export interface ActivityLogConfig {
+    enabled?: boolean;
+    key?: string;
+}
+/**
+ * Protocol-level capability strings embedded into signed identities.
+ */
+export type IssuedCapabilityName = "vault:list" | "vault:fetch" | "vault:acquire" | "admin:secrets" | "admin:issue" | "identity:sign";
+/**
+ * Valid runtime permission strings for a CbioAgent handle.
+ */
+export type RuntimePermissionName = "vault:list" | "vault:fetch" | "vault:acquire" | "admin:secrets" | "admin:issue" | "identity:sign";
+/**
+ * Granular permissions for a CbioAgent handle.
+ * These are runtime switches that control access to specific facets.
+ */
+export type RuntimePermissions = Partial<Record<RuntimePermissionName, boolean>>;
+/**
+ * Options for getAgent(). Mutually exclusive: either pass `permissions` OR `deriveFromIssuedIdentity`, not both.
+ * When deriving, pass `deriveFromIssuedIdentity: true` explicitly; only this literal has effect.
+ */
+export type GetAgentOptions = {
+    permissions: RuntimePermissions;
+    deriveFromIssuedIdentity?: never;
+} | {
+    permissions?: never;
+    deriveFromIssuedIdentity?: true;
+};
+/**
+ * CbioIdentity
+ *
+ * The primary Identity container. Represents an agent's identity and its associated vault.
+ * This is the high-privilege handle that contains administrative capabilities (.admin)
+ * and private keys.
+ */
+export declare class CbioIdentity {
+    #private;
+    readonly signer: Signer;
+    private readonly _vault;
+    readonly admin: CbioAdmin;
+    readonly agentId: string;
+    readonly publicKey: string;
+    private readonly _authClient;
+    private readonly _secretAcquisition;
+    private constructor();
+    /**
+     * Primary entry point: Load identity from keys and initialize vault.
+     */
+    static load(keys: IdentityLoadKeys, options?: IdentityLoadOptions): Promise<CbioIdentity>;
+    fetchWithAuth(secretName: string, url: string, options?: FetchWithAuthOptions): Promise<Response>;
+    createFetchWithAuth(secretName: string): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    getPublicKey(): Promise<string>;
+    getAgentId(): Promise<string>;
+    fetchJsonAndAddSecret<TResponse = unknown, TBody = unknown>(options: FetchJsonAndAddSecretOptions<TResponse, TBody>): Promise<FetchResult<TResponse>>;
+    fetchJsonAndUpdateSecret<TResponse = unknown, TBody = unknown>(options: FetchJsonAndUpdateSecretOptions<TResponse, TBody>): Promise<FetchResult<TResponse>>;
+    hasSecret(secretName: string): boolean;
+    listSecretNames(): string[];
+    /**
+     * Register a newly created child identity to the parent vault.
+     * @returns The child's publicKey (domain-level identifier). Use getChildIdentitySecretName(publicKey) from the protocol subpath for low-level vault access.
+     */
+    registerChildIdentity(keys: KeyPair, options?: RegisterChildIdentityOptions): Promise<RegisterChildIdentityResult>;
+    authenticate(nonce: string): Promise<string>;
+    /**
+     * Create a standard Agent handle for this identity.
+     * The Agent handle DOES NOT have an .admin property and does not expose the signer/private key.
+     * This is the recommended handle to pass to an autonomous LLM.
+     *
+     * By default this returns a minimally privileged handle (`vault:fetch`, `vault:list`).
+     * Runtime permissions are only widened when passed explicitly or when
+     * `deriveFromIssuedIdentity` is set to `true`.
+     */
+    getAgent(options?: GetAgentOptions): CbioAgent;
+}
+/**
+ * CbioAgent
+ *
+ * A safety-wrapped version of an Identity designed for autonomous LLMs.
+ * It provides only the Standard facet (fetchWithAuth, etc.) by default and hides
+ * all administrative capabilities and private keys.
+ */
+export declare class CbioAgent {
+    #private;
+    readonly agentId: string;
+    readonly publicKey: string;
+    constructor(authClient: AuthClient, secretAcquisition: SecretAcquisition, agentId: string, publicKey: string, permissions?: RuntimePermissions);
+    /**
+     * View the runtime permissions granted to this handle.
+     */
+    get permissions(): Readonly<RuntimePermissions>;
+    private _checkPermission;
+    fetchWithAuth(secretName: string, url: string, options?: FetchWithAuthOptions): Promise<Response>;
+    createFetchWithAuth(secretName: string): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    getPublicKey(): Promise<string>;
+    getAgentId(): Promise<string>;
+    fetchJsonAndAddSecret<TResponse = unknown, TBody = unknown>(options: FetchJsonAndAddSecretOptions<TResponse, TBody>): Promise<FetchResult<TResponse>>;
+    fetchJsonAndUpdateSecret<TResponse = unknown, TBody = unknown>(options: FetchJsonAndUpdateSecretOptions<TResponse, TBody>): Promise<FetchResult<TResponse>>;
+    hasSecret(secretName: string): boolean;
+    listSecretNames(): string[];
+    /**
+     * Check if this agent handle has the specified runtime permission.
+     */
+    can(permission: RuntimePermissionName): boolean;
+}
+export interface ManagedAgentContext {
+    agentId: string;
+    publicKey: string;
+    agent: CbioAgent;
+}
+export interface RegisterChildIdentityOptions {
+    /** Protocol-level capabilities embedded into the signed child identity. */
+    issuedCapabilities?: IssuedCapabilityName[];
+}
+export interface RegisterChildIdentityResult {
+    publicKey: string;
+}
+export interface ManagedAgentIssueConfig {
+    keys?: KeyPair;
+    secretName?: string;
+    /** Protocol-level capabilities embedded into the signed managed identity. */
+    issuedCapabilities?: IssuedCapabilityName[];
+}
+export interface ManagedAgentHandleConfig {
+    /** Runtime permissions granted to the returned `CbioAgent` handle. */
+    runtimePermissions?: RuntimePermissions;
+}
+export interface ManagedAgentStorageConfig {
+    storage?: IStorageProvider;
+    storageKey?: string;
+    activityLog?: ActivityLogConfig;
+}
+export interface ManagedAgentIssueOptions {
+    issue?: ManagedAgentIssueConfig;
+    handle?: ManagedAgentHandleConfig;
+    storage?: ManagedAgentStorageConfig;
+}
+export interface ManagedAgentLoadOptions {
+    handle?: ManagedAgentHandleConfig;
+    storage?: ManagedAgentStorageConfig;
+}
+export type ManagedAgentCapabilityStatus = "active" | "revoked" | "missing" | "invalid";
+export interface ManagedAgentCapabilityInfo {
+    status: ManagedAgentCapabilityStatus;
+    capabilities: readonly IssuedCapabilityName[];
+}
+/**
+ * CbioManagementFacet
+ *
+ * Provides administrative (high-risk) capabilities for a CbioIdentity.
+ */
+declare class ManagedAgentSupport {
+    protected readonly _identity: CbioIdentity;
+    protected readonly _vault: CbioVault;
+    constructor(_identity: CbioIdentity, _vault: CbioVault);
+    protected getSecret(secretName: string): string | undefined;
+    addSecret(secretName: string, secretValue: string, options?: SecretPolicy): Promise<void>;
+    protected _getManagedAgentRecord(publicKey: string): ManagedAgentRecord | null;
+    protected _getManagedAgentRevocation(publicKey: string): RevocationRecord | null;
+    protected _isManagedAgentRevoked(publicKey: string): boolean;
+    protected _assertManagedAgentNotRevoked(publicKey: string): void;
+}
+export declare class CbioVaultAdmin {
+    private readonly _identity;
+    private readonly _vault;
+    constructor(_identity: CbioIdentity, _vault: CbioVault);
+    addSecret(secretName: string, secretValue: string, options?: SecretPolicy): Promise<void>;
+    getSecret(secretName: string): string | undefined;
+    hasSecret(secretName: string): boolean;
+    deleteSecret(secretName: string): Promise<void>;
+    setSecretAllowedOrigins(secretName: string, allowedOrigins: readonly string[]): Promise<void>;
+    getActivityLog(): Promise<readonly ActivityLogEntry[]>;
+    getActivityLogMetadata(): Promise<ActivityLogMetadata | null>;
+    mergeFrom(otherIdentity: CbioIdentity, options?: {
+        onConflict?: "abort" | "skip" | "overwrite";
+    }): Promise<MergeResult>;
+    seal(kdk: string): string;
+    loadFromSealedBlob(kdk: string, sealedBlob: string): void;
+    serializeToBlob(): Promise<string>;
+    saveVault(): Promise<void>;
+    /**
+     * One-time save of the vault to the given storage key.
+     * Does NOT change the bound storage for subsequent saveVault() or autosave.
+     * Binding is set during identity load (initFromStorage/initFromBlob).
+     */
+    saveVaultAs(storageKey: string): Promise<void>;
+}
+export declare class CbioManagedAgentAdmin extends ManagedAgentSupport {
+    getManagedAgentCapabilities(publicKey: string): ManagedAgentCapabilityInfo;
+    revokeManagedAgent(publicKey: string, reason?: string): Promise<void>;
+    issueManagedAgent(options?: ManagedAgentIssueOptions): Promise<ManagedAgentContext>;
+    loadManagedAgent(publicKey: string, options?: ManagedAgentLoadOptions): Promise<ManagedAgentContext>;
+}
+export declare class CbioChildIdentityAdmin {
+    private readonly _identity;
+    private readonly _vault;
+    constructor(_identity: CbioIdentity, _vault: CbioVault);
+    /**
+     * Registers a child identity in the parent vault.
+     * @returns The child's publicKey (domain-level identifier). Use getChildIdentitySecretName from @the-ai-company/cbio-node-runtime/protocol for vault lookups.
+     */
+    registerChildIdentity(keys: KeyPair, options?: RegisterChildIdentityOptions): Promise<RegisterChildIdentityResult>;
+}
+export declare class CbioAdmin {
+    readonly vault: CbioVaultAdmin;
+    readonly managedAgents: CbioManagedAgentAdmin;
+    readonly children: CbioChildIdentityAdmin;
+    constructor(identity: CbioIdentity, vault: CbioVault);
+}
+export {};