@ixo/editor 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/capabilityValidation-B3NRVwYZ.d.ts

@@ -0,0 +1,406 @@
+import { r as FlowNode, F as FlowNodeAuthzExtension, p as FlowNodeRuntimeState, J as IxoEditorType, S as SignedCapability, B as CreateRootDelegationParams, t as StoredDelegation, G as CreateDelegationParams, H as CreateInvocationParams, w as InvocationResult, x as ExecutionWithInvocationResult, s as UcanCapability, y as DelegationChainValidationResult, z as FindProofsResult, M as MigrationReport, U as UcanDelegationStore, l as InvocationStore, E as EvaluationStatus, C as Capability, a as CapabilityValidationResult } from './index-CnqA4qDa.mjs';
+import { Delegation } from '@ixo/ucan';
+import { Doc, Map } from 'yjs';
+
+declare const buildAuthzFromProps: (props: Record<string, any>) => FlowNodeAuthzExtension;
+declare const buildFlowNodeFromBlock: (block: any) => FlowNode;
+
+interface FlowRuntimeStateManager {
+    get: (nodeId: string) => FlowNodeRuntimeState;
+    update: (nodeId: string, updates: Partial<FlowNodeRuntimeState>) => void;
+}
+declare const createRuntimeStateManager: (editor?: IxoEditorType | null) => FlowRuntimeStateManager;
+/**
+ * Clears runtime and invocations from a Y.Doc.
+ * Used when cloning a flow as a template — the new document should
+ * carry only configuration (intent), not execution history.
+ */
+declare function clearRuntimeForTemplateClone(yDoc: Doc): void;
+
+interface DelegationStore {
+    get: (capabilityId: string) => SignedCapability | null;
+    set: (capability: SignedCapability) => void;
+    remove: (capabilityId: string) => void;
+    getRoot: () => SignedCapability | null;
+    setRootId: (capabilityId: string) => void;
+    getAll: () => SignedCapability[];
+    has: (capabilityId: string) => boolean;
+}
+/**
+ * Create a delegation store backed by Y.Map
+ */
+declare const createDelegationStore: (yMap: Map<any>) => DelegationStore;
+/**
+ * Create an in-memory delegation store (for testing or when Y.Map unavailable)
+ */
+declare const createMemoryDelegationStore: () => DelegationStore;
+
+interface CapabilityGrant {
+    raw: string;
+    with?: string;
+    audience?: string;
+    expiresAt?: number;
+    action?: string;
+}
+type DerivedCapability = CapabilityGrant;
+interface UCANManager {
+    loadParentCapability: (capability: string) => Promise<CapabilityGrant>;
+    deriveNodeCapability: (parent: CapabilityGrant, nodeId: string, actorDid: string) => Promise<DerivedCapability>;
+    validateDerivedCapability: (derived: DerivedCapability, nodeId: string, actorDid: string) => Promise<void>;
+}
+declare class SimpleUCANManager implements UCANManager {
+    loadParentCapability(capability: string): Promise<CapabilityGrant>;
+    deriveNodeCapability(parent: CapabilityGrant, nodeId: string, actorDid: string): Promise<DerivedCapability>;
+    validateDerivedCapability(derived: DerivedCapability): Promise<void>;
+}
+
+/**
+ * UCAN Service using @ixo/ucan directly
+ *
+ * This service provides a high-level API for:
+ * - Creating and managing delegations (CAR format)
+ * - Creating and validating invocations
+ * - Executing actions with invocation-based authorization
+ * - Migrating legacy delegations
+ *
+ * The host app only needs to provide the signer (private key) after PIN decryption.
+ * All UCAN operations are performed using @ixo/ucan directly.
+ */
+
+/**
+ * Signer session scope type
+ */
+type SignerSessionScope = 'session' | 'operation';
+/**
+ * Signer session returned by createSignerSession
+ */
+interface SignerSessionInfo {
+    sessionId: string;
+    did: string;
+    publicKey: string;
+    keyId: string;
+    expiresAt: number;
+    scope: SignerSessionScope;
+}
+/**
+ * Handler functions for getting signers from the host application
+ * The host app handles PIN decryption and key management
+ */
+interface UcanServiceHandlers {
+    /**
+     * Get a signer for the given DID after PIN verification
+     * The host app decrypts the private key using the PIN
+     *
+     * @returns The private key in multibase format (for parseSigner)
+     * @deprecated Prefer createSignerSession for better security
+     */
+    getPrivateKey?: (params: {
+        did: string;
+        didType: 'entity' | 'user';
+        entityRoomId?: string;
+        pin: string;
+    }) => Promise<string>;
+    /**
+     * Get a signer from mnemonic (alternative to getPrivateKey)
+     * The host app retrieves and decrypts the mnemonic using the PIN
+     *
+     * @returns The mnemonic phrase
+     * @deprecated Prefer createSignerSession for better security
+     */
+    getMnemonic?: (params: {
+        did: string;
+        didType: 'entity' | 'user';
+        entityRoomId?: string;
+        pin: string;
+    }) => Promise<string>;
+    /**
+     * Create a signer session that can be used for multiple sign operations.
+     * The host app keeps the key material secure; the editor only receives an opaque handle.
+     *
+     * @param params.scope - 'session' for multiple operations, 'operation' for one-time use
+     * @param params.ttlSeconds - Time-to-live for session scope (default: 300, max: 3600)
+     */
+    createSignerSession?: (params: {
+        did: string;
+        didType: 'entity' | 'user';
+        entityRoomId?: string;
+        pin: string;
+        scope: SignerSessionScope;
+        ttlSeconds?: number;
+    }) => Promise<SignerSessionInfo>;
+    /**
+     * Sign data using an existing session.
+     * For 'operation' scope, the session is automatically invalidated after this call.
+     */
+    signWithSession?: (params: {
+        sessionId: string;
+        data: string;
+        algorithm?: 'Ed25519';
+    }) => Promise<{
+        signature: string;
+        algorithm: 'Ed25519';
+        keyId: string;
+    }>;
+    /**
+     * Release a session before it expires.
+     * Safe to call on already-released or expired sessions.
+     */
+    releaseSignerSession?: (params: {
+        sessionId: string;
+    }) => Promise<{
+        released: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Create a delegation directly in the host app.
+     * The host handles all signing internally using session-based signing.
+     * This is the preferred approach for security.
+     */
+    createDelegationWithSession?: (params: {
+        sessionId: string;
+        audience: string;
+        capabilities: Array<{
+            can: string;
+            with: string;
+            nb?: Record<string, unknown>;
+        }>;
+        proofs?: string[];
+        expiration?: number;
+    }) => Promise<{
+        cid: string;
+        delegation: string;
+    }>;
+    /**
+     * Create an invocation directly in the host app.
+     * The host handles all signing internally using session-based signing.
+     * This is the preferred approach for security.
+     */
+    createInvocationWithSession?: (params: {
+        sessionId: string;
+        audience: string;
+        capability: {
+            can: string;
+            with: string;
+            nb?: Record<string, unknown>;
+        };
+        proofs: string[];
+    }) => Promise<{
+        cid: string;
+        invocation: string;
+    }>;
+}
+/**
+ * Configuration for UcanService
+ */
+interface UcanServiceConfig {
+    delegationStore: UcanDelegationStore;
+    invocationStore: InvocationStore;
+    handlers: UcanServiceHandlers;
+    flowOwnerDid: string;
+    flowUri: string;
+}
+/**
+ * UCAN Service interface
+ */
+interface UcanService {
+    createRootDelegation: (params: CreateRootDelegationParams) => Promise<StoredDelegation>;
+    createDelegation: (params: CreateDelegationParams) => Promise<StoredDelegation>;
+    revokeDelegation: (cid: string) => void;
+    getDelegation: (cid: string) => StoredDelegation | null;
+    getAllDelegations: () => StoredDelegation[];
+    getRootDelegation: () => StoredDelegation | null;
+    createAndValidateInvocation: (params: CreateInvocationParams, flowId: string, blockId?: string) => Promise<InvocationResult>;
+    executeWithInvocation: <T>(params: CreateInvocationParams, action: () => Promise<T>, flowId: string, blockId?: string) => Promise<ExecutionWithInvocationResult & {
+        actionResult?: T;
+    }>;
+    validateDelegationChain: (audienceDid: string, capability: UcanCapability) => Promise<DelegationChainValidationResult>;
+    findValidProofs: (audienceDid: string, capability: UcanCapability) => Promise<FindProofsResult>;
+    parseDelegationFromStore: (cid: string) => Promise<Delegation | null>;
+    migrateLegacyDelegation: (legacyId: string, pin: string) => Promise<StoredDelegation | null>;
+    migrateAllLegacy: (pin: string) => Promise<MigrationReport>;
+    getLegacyCount: () => number;
+    isConfigured: () => boolean;
+}
+/**
+ * Create a UCAN service instance
+ */
+declare const createUcanService: (config: UcanServiceConfig) => UcanService;
+
+interface NodeActionResult {
+    claimId?: string;
+    evaluationStatus?: EvaluationStatus;
+    submittedByDid?: string;
+    payload?: any;
+}
+interface ExecutionContext {
+    runtime: FlowRuntimeStateManager;
+    /** @deprecated Use delegationStore instead */
+    ucanManager?: UCANManager;
+    delegationStore?: DelegationStore;
+    verifySignature?: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    rootIssuer?: string;
+    flowUri?: string;
+    now?: () => number;
+}
+interface ExecutionOutcome {
+    success: boolean;
+    stage: 'activation' | 'authorization' | 'claim' | 'action' | 'complete';
+    error?: string;
+    result?: NodeActionResult;
+    capabilityId?: string;
+    /** Invocation CID (new @ixo/ucan) */
+    invocationCid?: string;
+}
+/**
+ * V2 Execution context for @ixo/ucan integration
+ */
+interface ExecutionContextV2 {
+    runtime: FlowRuntimeStateManager;
+    /** UCAN service for invocation-based execution */
+    ucanService?: UcanService;
+    /** Invocation store for audit trail */
+    invocationStore?: InvocationStore;
+    /** Flow URI */
+    flowUri: string;
+    /** Flow ID for invocation storage */
+    flowId: string;
+    /** Flow owner DID */
+    flowOwnerDid: string;
+    /** Current time function */
+    now?: () => number;
+    /** @deprecated Use ucanService instead */
+    ucanManager?: UCANManager;
+    /** @deprecated Use ucanService instead */
+    delegationStore?: DelegationStore;
+    /** @deprecated Use ucanService instead */
+    verifySignature?: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /** @deprecated Use flowOwnerDid instead */
+    rootIssuer?: string;
+}
+/**
+ * V2 Execute node params with PIN for invocation signing
+ */
+interface ExecuteNodeParamsV2 {
+    node: FlowNode;
+    actorDid: string;
+    actorType: 'entity' | 'user';
+    entityRoomId?: string;
+    context: ExecutionContextV2;
+    action: () => Promise<NodeActionResult>;
+    /** PIN for signing invocation (required for @ixo/ucan) */
+    pin: string;
+}
+interface ExecuteNodeParams {
+    node: FlowNode;
+    actorDid: string;
+    context: ExecutionContext;
+    action: () => Promise<NodeActionResult>;
+}
+declare const executeNode: ({ node, actorDid, context, action }: ExecuteNodeParams) => Promise<ExecutionOutcome>;
+/**
+ * V2 Execute node with invocation-based authorization
+ * Creates an invocation before execution and stores it for audit trail
+ */
+declare const executeNodeWithInvocation: ({ node, actorDid, actorType, entityRoomId, context, action, pin }: ExecuteNodeParamsV2) => Promise<ExecutionOutcome>;
+
+interface AuthorizationResult {
+    authorized: boolean;
+    reason?: string;
+    capabilityId?: string;
+    /** Proof chain CIDs for creating invocations (new @ixo/ucan) */
+    proofCids?: string[];
+    /** @deprecated */
+    derived?: DerivedCapability;
+}
+interface AuthorizationContext {
+    /** @deprecated Use delegationStore instead */
+    ucanManager?: UCANManager;
+    delegationStore?: DelegationStore;
+    verifySignature?: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    rootIssuer?: string;
+    flowUri?: string;
+}
+/**
+ * Authorization context V2 for @ixo/ucan integration
+ */
+interface AuthorizationContextV2 {
+    /** UCAN service for validation (new @ixo/ucan) */
+    ucanService?: UcanService;
+    /** Flow URI for resource matching */
+    flowUri?: string;
+    /** Flow owner DID (root issuer) */
+    flowOwnerDid?: string;
+    /** @deprecated Use ucanService instead */
+    ucanManager?: UCANManager;
+    /** @deprecated Use ucanService instead */
+    delegationStore?: DelegationStore;
+    /** @deprecated Use ucanService instead */
+    verifySignature?: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /** @deprecated Use flowOwnerDid instead */
+    rootIssuer?: string;
+}
+declare const isActorAuthorized: (node: FlowNode, actorDid: string, context?: AuthorizationContext) => Promise<AuthorizationResult>;
+/**
+ * V2 Authorization check using @ixo/ucan service
+ * Returns proof chain for invocation creation
+ */
+declare const isActorAuthorizedV2: (node: FlowNode, actorDid: string, context?: AuthorizationContextV2) => Promise<AuthorizationResult>;
+
+interface ActivationResult {
+    active: boolean;
+    reason?: string;
+}
+declare const isNodeActive: (node: FlowNode, runtime: FlowRuntimeStateManager) => ActivationResult;
+
+interface ValidateChainParams {
+    /** The capability to validate */
+    capability: SignedCapability;
+    /** The actor DID trying to use the capability */
+    actorDid: string;
+    /** Required capability (what the actor wants to do) */
+    requiredCapability: Capability;
+    /** The delegation store */
+    delegationStore: DelegationStore;
+    /** Handler to verify signatures */
+    verifySignature: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /** Expected root issuer (entity DID) */
+    rootIssuer: string;
+}
+/**
+ * Validate a capability chain back to the root
+ */
+declare const validateCapabilityChain: (params: ValidateChainParams) => Promise<CapabilityValidationResult>;
+/**
+ * Find a valid capability for an actor to perform an action
+ */
+declare const findValidCapability: (params: {
+    actorDid: string;
+    requiredCapability: Capability;
+    delegationStore: DelegationStore;
+    verifySignature: (capabilityRaw: string, issuerDid: string) => Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    rootIssuer: string;
+}) => Promise<{
+    found: boolean;
+    capabilityId?: string;
+    error?: string;
+}>;
+
+export { type AuthorizationResult as A, type CapabilityGrant as C, type DelegationStore as D, type ExecuteNodeParams as E, type FlowRuntimeStateManager as F, type NodeActionResult as N, SimpleUCANManager as S, type UcanService as U, isNodeActive as a, createMemoryDelegationStore as b, createDelegationStore as c, createRuntimeStateManager as d, executeNode as e, findValidCapability as f, buildFlowNodeFromBlock as g, buildAuthzFromProps as h, isActorAuthorized as i, type ExecutionOutcome as j, type ExecutionContext as k, type AuthorizationContext as l, type ActivationResult as m, clearRuntimeForTemplateClone as n, executeNodeWithInvocation as o, type ExecuteNodeParamsV2 as p, type ExecutionContextV2 as q, isActorAuthorizedV2 as r, type AuthorizationContextV2 as s, createUcanService as t, type UcanServiceConfig as u, validateCapabilityChain as v, type UcanServiceHandlers as w, type UCANManager as x, type DerivedCapability as y };