mcard-js/dist/model/VCard.d.ts

MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers

/**
 * VCard Model (Application Plane) - Petri Net TOKEN / PRE-CONDITION CARRIER
 *
 * This module defines VCard, the sovereign decision layer in the MVP Cards architecture.
 * VCard is the Applicative that manages all side effects and authorization.
 *
 * ## Category Theory Role: APPLICATIVE
 *
 * VCard is the **Applicative** in the MVP Cards categorical hierarchy:
 * - **MCard (Monad)**: Data container with unit and bind
 * - **PCard (Functor)**: Pure transformation
 * - **VCard (Applicative)**: Context-aware application `<*> :: F (a -> b) -> F a -> F b`
 *
 * The Applicative nature means VCard can encode **static pre-conditions**:
 * the authorization graph is known ahead of time, while actual execution
 * depends on runtime results.
 *
 * ## Petri Net Role: TOKEN + PRE-CONDITION
 *
 * In the Categorical Petri Net model, VCard serves dual roles:
 *
 * ### As Token
 * - VCard is the **Token** that resides in Places (Handles)
 * - Tokens enable Transitions (PCards) to fire
 * - Token movement represents verification cascade
 *
 * ### As Pre-Condition (Firing Guard)
 * A Petri Net transition fires when all input VCards exist:
 *
 * ```
 * M' = M - •t + t•
 * ```
 *
 * VCard as Input Arc encodes:
 * - **Input Place**: Handle pointing to required VCard
 * - **Token in Place**: VCard content in `card` table
 * - **Arc Guard**: VCard's Applicative authorization check
 * - **Token "Consumption"**: Recording `previous_hash` in new VCard
 *
 * ### Hash as Token AND Certificate (Dual Role)
 *
 * | Role | Function | Implementation |
 * |------|----------|----------------|
 * | **Token** | Triggers firing (enables transitions) | `handle_registry.current_hash IS NOT NULL` |
 * | **Certificate** | Proves correctness after verification | VCard content witnesses Hoare Triple |
 *
 * ```
 * {h_pre} PCard {h_post}
 * ```
 *
 * Where:
 * - h_pre = hash of input VCard (precondition satisfied)
 * - PCard = CLM specification (transformation logic)
 * - h_post = hash of output VCard (postcondition witnessed)
 *
 * ## Cascade Pattern: Propagating Verification
 *
 * VCards enable **verification cascades** across the network:
 *
 * ```
 * T1 → V1 → T2 → V2 → T3 → ... → Vn
 * ```
 *
 * Each VerificationVCard (Vi) serves as:
 * 1. **Post-condition** of transition Ti (what it produces)
 * 2. **Pre-condition** of transition Ti+1 (what enables next step)
 *
 * ## DOTS Vocabulary Role: ARENA + ACTION
 *
 * VCard is both:
 * - **Arena**: Interface type defining what can interact (subject_did, capabilities, external_refs)
 * - **Action**: Morphism where interactions (PCards) act on systems (MCards)
 *
 * ## The Four Roles:
 * 1. Identity & Credential Container (The "Who")
 * 2. Verification Hub (The "Rules")
 * 3. Side Effect Manager (The "Bridge")
 * 4. Input/Output Gatekeeper (The "Gate")
 *
 * ## VCard as Egress Gate: The Sovereign Boundary
 *
 * When a VerificationVCard is produced, it may also serve as **egress authorization**:
 *
 * | Egress Role | VCard Content | Enables |
 * |-------------|--------------|---------|
 * | Export Authorization | `egress_capability: { destination_did, scope }` | Sharing to specific PKCs |
 * | Cross-PKC Transition | `transferable: true` | Token moves to destination's Petri Net |
 * | Federation Trigger | Signed VCard bundle | Downstream PKC's transitions enabled |
 *
 * @see docs/VCard_Impl.md for full implementation specification
 */
import { MCard } from './MCard';
import { DOTSMetadata } from '../types/dots';
/**
 * Scope of a capability token.
 */
export declare enum CapabilityScope {
    READ = "read",
    WRITE = "write",
    EXECUTE = "execute",
    ADMIN = "admin",
    DELEGATE = "delegate"
}
/**
 * Direction of gatekeeper authorization.
 */
export declare enum GatekeeperDirection {
    INGRESS = "ingress",
    EGRESS = "egress"
}
/**
 * A capability token defining authorized actions.
 */
export interface Capability {
    capabilityId: string;
    actorDid: string;
    scope: CapabilityScope;
    resourcePattern: string;
    expiresAt?: Date;
    constraints?: Record<string, any>;
    transferable: boolean;
}
/**
 * A verified external reference managed by VCard.
 */
export interface ExternalRef {
    uri: string;
    contentHash: string;
    status: 'verified' | 'pending' | 'stale' | 'invalid';
    signature?: string;
    lastVerified?: Date;
    qosMetrics?: Record<string, any>;
}
/**
 * An ingress or egress gatekeeper event.
 */
export interface GatekeeperEvent {
    direction: GatekeeperDirection;
    timestamp: Date;
    sourceDid?: string;
    destinationDid?: string;
    contentHash: string;
    authorized: boolean;
    capabilityUsed?: string;
    signature?: string;
}
/**
 * Check if an MCard follows the VCard structure.
 */
export declare function isVCard(card: MCard): boolean;
/**
 * Extract PCard reference hashes from VCard.
 */
export declare function getPCardRefs(vcard: MCard): string[];
/**
 * Extract subject DID from VCard.
 */
export declare function getSubjectDid(vcard: MCard): string | undefined;
/**
 * VCard - The Application Plane unit (Petri Net Token)
 *
 * Implements the Empty Schema Principle: VCard IS an MCard.
 * This class provides a view and runtime state management over the immutable content.
 *
 * In Petri Net terms:
 * - VCard is a **Token** that resides in a **Place** (Handle)
 * - VCard enables **Transitions** (PCards) to fire when present
 * - VCard serves as both **Pre-condition** (what enables) and **Post-condition** (what is produced)
 */
export declare class VCard extends MCard {
    private _subjectDid;
    private _controllerPubkeys;
    private _capabilities;
    private _externalRefs;
    private _exportManifest;
    private _gatekeeperLog;
    private _pcardRefsHashes;
    protected constructor(content: Uint8Array, hash: string, g_time: string, contentType: string, hashFunction: string, initialData: any);
    private _initializeMutableState;
    /**
     * Create a new VCard from parameters.
     * Follows strict UPTV structure { vcard: { ... } }.
     */
    static createVCard(subjectDid: string, controllerPubkeys: string[], capabilities?: Capability[], externalRefs?: ExternalRef[], hashAlgorithm?: string): Promise<VCard>;
    /**
     * Create a VCard wrapper from an existing MCard.
     */
    static fromMCard(card: MCard): Promise<VCard>;
    getDOTSMetadata(): DOTSMetadata;
    get subjectDid(): string;
    get controllerPubkeys(): string[];
    get capabilities(): Capability[];
    get externalRefs(): ExternalRef[];
    addCapability(capability: Capability): void;
    getValidCapabilities(): Capability[];
    hasCapability(scope: CapabilityScope, resourceHash: string): boolean;
    addPCardReference(pcardHash: string): void;
    getPCardReferences(): string[];
    addExternalRef(ref: ExternalRef): void;
    getExternalRefsByStatus(status: ExternalRef['status']): ExternalRef[];
    verifyExternalRef(uri: string, newHash: string): boolean;
    authorizeIngress(sourceDid: string, contentHash: string, capabilityId?: string): boolean;
    registerForEgress(contentHash: string): boolean;
    authorizeEgress(destinationDid: string, contentHash: string, capabilityId?: string): boolean;
    private _logEgress;
    getGatekeeperLog(direction?: GatekeeperDirection): GatekeeperEvent[];
    getExportManifest(): string[];
    simulateMode(): VCardSimulation;
    /**
     * Get the handle where this VCard token currently resides
     *
     * In Petri Net terms, this is the "Place" where the token is located.
     *
     * @returns Handle string if available in content, or hash-based handle
     */
    getTokenHandle(): string;
    /**
     * Check if this VCard is a VerificationVCard (result of PCard execution)
     *
     * VerificationVCards are produced by PCard transitions and contain
     * execution results with provenance chain.
     *
     * @returns True if this is a verification token
     */
    isVerificationVCard(): boolean;
    /**
     * Get the previous hash in the provenance chain
     *
     * In Petri Net terms, this links to the input VCard that was "consumed"
     * when the transition fired to produce this VCard.
     *
     * @returns Previous VCard hash if this is part of a verification cascade
     */
    getPreviousHash(): string | undefined;
    /**
     * Get the PCard hash that produced this VCard (if verification)
     *
     * This links the output token to the transition that created it.
     *
     * @returns PCard hash that produced this VCard
     */
    getSourcePCardHash(): string | undefined;
    /**
     * Create a VerificationVCard from PCard execution result
     *
     * This is the factory method for producing output tokens in the Petri Net.
     *
     * @param pcard - The PCard (Transition) that executed
     * @param result - Execution result
     * @param previousVCard - Input VCard (pre-condition) if any
     * @param success - Whether execution succeeded
     * @returns New VerificationVCard
     */
    static createVerificationVCard(pcard: {
        hash: string;
        getTransitionHandle?: () => string;
        getBalancedHandle?: () => string;
    }, result: unknown, previousVCard?: VCard, success?: boolean, hashAlgorithm?: string): Promise<VCard>;
    /**
     * Check if this VCard enables a specific PCard to fire
     *
     * @param requiredHandle - The handle where a precondition VCard must exist
     * @returns True if this VCard satisfies that precondition
     */
    enablesTransition(requiredHandle: string): boolean;
}
/**
 * Simulation context for VCard (EOS Compliance).
 */
export declare class VCardSimulation {
    private vcard;
    private log;
    constructor(vcard: VCard);
    logEffect(effectType: string, details: any): void;
    getSimulationLog(): any[];
}
//# sourceMappingURL=VCard.d.ts.map