@the-ai-company/cbio-node-runtime 0.39.0 → 1.0.0

package/dist/agent/agent.d.ts

@@ -1,267 +0,0 @@
-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 LocalSecretIngressHandle, type LocalSecretIngressOptions } from "../http/localSecretIngress.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;
-}
-export type StartLocalSecretIngressOptions = Omit<LocalSecretIngressOptions, "vault">;
-export type SecretProofAlgorithm = "sha256" | "sha512";
-export type SecretValidationStatus = "valid" | "invalid" | "indeterminate";
-export interface SecretValidationResult {
-    valid: boolean;
-    status: SecretValidationStatus;
-    reason?: string;
-    providerSubject?: string;
-    expiresAt?: string;
-    scopes?: readonly string[];
-    metadata?: Record<string, unknown>;
-}
-export interface SecretValidatorHandle {
-    fetchWithAuth(url: string, options?: FetchWithAuthOptions): Promise<Response>;
-    compare(candidate: string): Promise<boolean>;
-    prove(challenge: string, options?: {
-        algorithm?: SecretProofAlgorithm;
-    }): Promise<string>;
-}
-export interface SecretValidator {
-    validate(handle: SecretValidatorHandle): Promise<SecretValidationResult>;
-}
-/**
- * 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>>;
-    startLocalSecretIngress(options: StartLocalSecretIngressOptions): Promise<LocalSecretIngressHandle>;
-    compareSecret(secretName: string, candidate: string): Promise<boolean>;
-    proveSecret(secretName: string, challenge: string, options?: {
-        algorithm?: SecretProofAlgorithm;
-    }): Promise<string>;
-    validateSecret(secretName: string, validator: SecretValidator): Promise<SecretValidationResult>;
-    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, vault: CbioVault, 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>>;
-    startLocalSecretIngress(options: StartLocalSecretIngressOptions): Promise<LocalSecretIngressHandle>;
-    compareSecret(secretName: string, candidate: string): Promise<boolean>;
-    proveSecret(secretName: string, challenge: string, options?: {
-        algorithm?: SecretProofAlgorithm;
-    }): Promise<string>;
-    validateSecret(secretName: string, validator: SecretValidator): Promise<SecretValidationResult>;
-    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);
-    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 {};