mcard-js 2.1.49 → 2.1.51

package/dist/chunk-6ZRJXVJ3.js

@@ -0,0 +1,529 @@
+import {
+  ContentTypeInterpreter,
+  MCard,
+  createVCardDOTSMetadata
+} from "./chunk-GGQCF7ZK.js";
+import {
+  GTime,
+  HashValidator
+} from "./chunk-ASW6AOA7.js";
+
+// src/model/VCard.ts
+import { parse } from "yaml";
+var CapabilityScope = /* @__PURE__ */ ((CapabilityScope2) => {
+  CapabilityScope2["READ"] = "read";
+  CapabilityScope2["WRITE"] = "write";
+  CapabilityScope2["EXECUTE"] = "execute";
+  CapabilityScope2["ADMIN"] = "admin";
+  CapabilityScope2["DELEGATE"] = "delegate";
+  return CapabilityScope2;
+})(CapabilityScope || {});
+var GatekeeperDirection = /* @__PURE__ */ ((GatekeeperDirection2) => {
+  GatekeeperDirection2["INGRESS"] = "ingress";
+  GatekeeperDirection2["EGRESS"] = "egress";
+  return GatekeeperDirection2;
+})(GatekeeperDirection || {});
+function isVCard(card) {
+  try {
+    const content = asVCardView(parseVCardContent(card));
+    if (content.vcard) return true;
+    return content.type === "VCard" || Boolean(content.subjectDid && content.capabilities);
+  } catch {
+    return false;
+  }
+}
+function getPCardRefs(vcard) {
+  const content = asVCardView(parseVCardContent(vcard));
+  const data = asVCardView(content.vcard || content);
+  const verificationRefs = data.verification?.pcard_refs || [];
+  const hashes = [];
+  for (const r of verificationRefs) {
+    if (typeof r === "string") hashes.push(r);
+    else if (r.hash) hashes.push(r.hash);
+  }
+  return hashes;
+}
+function getSubjectDid(vcard) {
+  const content = asVCardView(parseVCardContent(vcard));
+  const data = asVCardView(content.vcard || content);
+  return data.identity?.subject_did || data.subjectDid;
+}
+function parseVCardContent(card) {
+  try {
+    const text = card.getContentAsText();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return parse(text);
+    }
+  } catch {
+    return {};
+  }
+}
+function asVCardView(value) {
+  return value;
+}
+var VCard = class _VCard extends MCard {
+  // Mutable Runtime State (initialized via _initializeMutableState)
+  _subjectDid;
+  _controllerPubkeys;
+  _capabilities;
+  _externalRefs;
+  _exportManifest;
+  _gatekeeperLog;
+  _pcardRefsHashes;
+  _managedEventTypes;
+  _wrappedPcardHash;
+  constructor(content, hash, g_time, contentType, hashFunction, initialData) {
+    super(content, hash, g_time, contentType, hashFunction);
+    this._gatekeeperLog = [];
+    this._exportManifest = [];
+    this._initializeMutableState(initialData);
+  }
+  _initializeMutableState(data) {
+    const v = asVCardView(data.vcard || data);
+    this._subjectDid = v.identity?.subject_did || v.subjectDid || "";
+    this._controllerPubkeys = v.identity?.controller_pubkeys || v.controllerPubkeys || [];
+    const rawCaps = v.gatekeeper?.capabilities || v.capabilities || [];
+    this._capabilities = rawCaps.map((c) => {
+      const capabilityId = c.id || c.capabilityId;
+      const actorDid = c.actor || c.actorDid;
+      const resourcePattern = c.resourcePattern || c.resource_pattern;
+      const expiry = c.expiresAt || c.expires_at;
+      if (!capabilityId || !actorDid || !c.scope || !resourcePattern) {
+        return null;
+      }
+      return {
+        capabilityId,
+        actorDid,
+        scope: c.scope,
+        resourcePattern,
+        expiresAt: expiry ? new Date(expiry) : void 0,
+        transferable: c.transferable || false,
+        constraints: c.constraints
+      };
+    }).filter((c) => c !== null);
+    const rawRefs = v.externalRefs || v.external_refs || [];
+    this._externalRefs = rawRefs.map((r) => {
+      const uri = r.uri;
+      const contentHash = r.contentHash || r.content_hash;
+      const status = r.status;
+      if (!uri || !contentHash || !status) {
+        return null;
+      }
+      return {
+        uri,
+        contentHash,
+        status,
+        qosMetrics: r.qos || r.qosMetrics
+      };
+    }).filter((r) => r !== null);
+    const rawPCardRefs = v.verification?.pcard_refs || [];
+    this._pcardRefsHashes = rawPCardRefs.map((r) => typeof r === "string" ? r : r.hash).filter((hash) => typeof hash === "string");
+    this._managedEventTypes = v.managed_event_types || [];
+    this._wrappedPcardHash = v.wrapped_pcard_hash;
+  }
+  /**
+   * Create a new VCard from parameters.
+   * Follows strict UPTV structure { vcard: { ... } }.
+   */
+  static async createVCard(subjectDid, controllerPubkeys, capabilities = [], externalRefs = [], managedEventTypes = [], wrappedPcardHash, hashAlgorithm = "sha256", extraFields = {}) {
+    const structure = {
+      vcard: {
+        type: "authentication-authorization",
+        identity: {
+          subject_did: subjectDid,
+          controller_pubkeys: controllerPubkeys
+        },
+        gatekeeper: {
+          capabilities: capabilities.map((c) => ({
+            id: c.capabilityId,
+            actor: c.actorDid,
+            scope: c.scope,
+            resource_pattern: c.resourcePattern,
+            expires_at: c.expiresAt?.toISOString(),
+            transferable: c.transferable,
+            constraints: c.constraints
+          }))
+        },
+        verification: {
+          pcard_refs: []
+          // Populated if provided in a separate arg or we filter externalRefs?
+          // For now, we assume externalRefs are generic.
+          // To strictly follow PCard Logic, we could expose pcardRefs arg, but keeping signature for now.
+        },
+        external_refs: externalRefs.map((r) => ({
+          uri: r.uri,
+          content_hash: r.contentHash,
+          status: r.status,
+          qos: r.qosMetrics
+        })),
+        managed_event_types: managedEventTypes,
+        wrapped_pcard_hash: wrappedPcardHash,
+        ...extraFields
+      }
+    };
+    const contentString = JSON.stringify(structure, null, 2);
+    const bytes = new TextEncoder().encode(contentString);
+    const hash = await HashValidator.computeHash(bytes, hashAlgorithm);
+    const g_time = GTime.stampNow(hashAlgorithm);
+    const contentType = ContentTypeInterpreter.detect(bytes);
+    return new _VCard(bytes, hash, g_time, contentType, hashAlgorithm, structure);
+  }
+  /**
+   * Create a VCard wrapper from an existing MCard.
+   */
+  static async fromMCard(card) {
+    const content = parseVCardContent(card);
+    return new _VCard(
+      card.content,
+      card.hash,
+      card.g_time,
+      card.contentType,
+      card.hashFunction,
+      content
+    );
+  }
+  getDOTSMetadata() {
+    return createVCardDOTSMetadata();
+  }
+  // =========================================================================
+  // Accessors
+  // =========================================================================
+  get subjectDid() {
+    return this._subjectDid;
+  }
+  get controllerPubkeys() {
+    return this._controllerPubkeys;
+  }
+  get capabilities() {
+    return this._capabilities;
+  }
+  get externalRefs() {
+    return this._externalRefs;
+  }
+  // =========================================================================
+  // Runtime Mutability (Gatekeeper Logic)
+  // =========================================================================
+  addCapability(capability) {
+    this._capabilities.push(capability);
+  }
+  getValidCapabilities() {
+    const now = /* @__PURE__ */ new Date();
+    return this._capabilities.filter(
+      (c) => c.expiresAt === void 0 || new Date(c.expiresAt) > now
+    );
+  }
+  hasCapability(scope, resourceHash) {
+    for (const cap of this.getValidCapabilities()) {
+      if (cap.scope === scope) {
+        const regex = new RegExp(cap.resourcePattern);
+        if (regex.test(resourceHash)) return true;
+      }
+    }
+    return false;
+  }
+  addPCardReference(pcardHash) {
+    if (!this._pcardRefsHashes.includes(pcardHash)) {
+      this._pcardRefsHashes.push(pcardHash);
+    }
+    this.addExternalRef({
+      uri: `pcard://${pcardHash}`,
+      contentHash: pcardHash,
+      status: "verified"
+    });
+  }
+  getPCardReferences() {
+    const set = new Set(this._pcardRefsHashes);
+    this._externalRefs.forEach((r) => {
+      if (r.uri.startsWith("pcard://")) set.add(r.contentHash);
+    });
+    return Array.from(set);
+  }
+  addExternalRef(ref) {
+    this._externalRefs.push(ref);
+  }
+  getExternalRefsByStatus(status) {
+    return this._externalRefs.filter((r) => r.status === status);
+  }
+  verifyExternalRef(uri, newHash) {
+    for (const ref of this._externalRefs) {
+      if (ref.uri === uri) {
+        if (ref.contentHash === newHash) {
+          ref.status = "verified";
+          ref.lastVerified = /* @__PURE__ */ new Date();
+          return true;
+        } else {
+          ref.status = "stale";
+          return false;
+        }
+      }
+    }
+    return false;
+  }
+  authorizeIngress(sourceDid, contentHash, capabilityId) {
+    let authorized = false;
+    let usedCapability;
+    for (const cap of this.getValidCapabilities()) {
+      if (cap.actorDid === sourceDid && (cap.scope === "write" /* WRITE */ || cap.scope === "admin" /* ADMIN */)) {
+        if (capabilityId === void 0 || cap.capabilityId === capabilityId) {
+          authorized = true;
+          usedCapability = cap.capabilityId;
+          break;
+        }
+      }
+    }
+    const event = {
+      direction: "ingress" /* INGRESS */,
+      timestamp: /* @__PURE__ */ new Date(),
+      sourceDid,
+      contentHash,
+      authorized,
+      capabilityUsed: usedCapability
+    };
+    this._gatekeeperLog.push(event);
+    return authorized;
+  }
+  getManagedEventTypes() {
+    return this._managedEventTypes || [];
+  }
+  getWrappedPcardHash() {
+    return this._wrappedPcardHash;
+  }
+  registerForEgress(contentHash) {
+    if (!this._exportManifest.includes(contentHash)) {
+      this._exportManifest.push(contentHash);
+      return true;
+    }
+    return false;
+  }
+  authorizeEgress(destinationDid, contentHash, capabilityId) {
+    if (!this._exportManifest.includes(contentHash)) {
+      this._logEgress(destinationDid, contentHash, false, void 0);
+      return false;
+    }
+    let authorized = false;
+    let usedCapability;
+    for (const cap of this.getValidCapabilities()) {
+      if (cap.scope === "read" /* READ */ || cap.scope === "admin" /* ADMIN */) {
+        const regex = new RegExp(cap.resourcePattern);
+        if (regex.test(contentHash)) {
+          if (capabilityId === void 0 || cap.capabilityId === capabilityId) {
+            authorized = true;
+            usedCapability = cap.capabilityId;
+            break;
+          }
+        }
+      }
+    }
+    this._logEgress(destinationDid, contentHash, authorized, usedCapability);
+    return authorized;
+  }
+  _logEgress(dst, hash, auth, cap) {
+    const event = {
+      direction: "egress" /* EGRESS */,
+      timestamp: /* @__PURE__ */ new Date(),
+      destinationDid: dst,
+      contentHash: hash,
+      authorized: auth,
+      capabilityUsed: cap
+    };
+    this._gatekeeperLog.push(event);
+  }
+  getGatekeeperLog(direction) {
+    if (direction === void 0) return this._gatekeeperLog;
+    return this._gatekeeperLog.filter((e) => e.direction === direction);
+  }
+  logGatekeeperEvent(event) {
+    this._gatekeeperLog.push(event);
+  }
+  getExportManifest() {
+    return [...this._exportManifest];
+  }
+  // =========================================================================
+  // EOS Compliance
+  // =========================================================================
+  simulateMode() {
+    return new VCardSimulation(this);
+  }
+  // =========================================================================
+  // Petri Net Token Semantics
+  // =========================================================================
+  /**
+   * 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() {
+    const content = asVCardView(parseVCardContent(this));
+    const v = asVCardView(content.vcard || content);
+    return v.handle || v.token_handle || `vcard://${this.hash.substring(0, 16)}`;
+  }
+  /**
+   * 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() {
+    const content = asVCardView(parseVCardContent(this));
+    const v = asVCardView(content.vcard || content);
+    return v.type === "verification" || v.type === "verification-result" || Boolean(v.verification?.execution_result);
+  }
+  /**
+   * 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() {
+    const content = asVCardView(parseVCardContent(this));
+    const v = asVCardView(content.vcard || content);
+    return v.previous_hash || v.previousHash || v.verification?.previous_hash;
+  }
+  /**
+   * 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() {
+    const content = asVCardView(parseVCardContent(this));
+    const v = asVCardView(content.vcard || content);
+    return v.source_pcard || v.verification?.pcard_hash || v.produced_by;
+  }
+  /**
+   * 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 async createVerificationVCard(pcard, result, previousVCard, success = true, hashAlgorithm = "sha256", executionTelemetry) {
+    const handle = typeof pcard.getBalancedHandle === "function" ? pcard.getBalancedHandle() : `hash/${pcard.hash.substring(0, 16)}/balanced`;
+    const verificationData = {
+      pcard_hash: pcard.hash,
+      execution_result: result,
+      success,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      previous_hash: previousVCard?.hash
+    };
+    if (executionTelemetry) {
+      verificationData.execution_telemetry = executionTelemetry;
+    }
+    const structure = {
+      vcard: {
+        type: "verification",
+        handle,
+        identity: {
+          subject_did: "did:ptr:system",
+          controller_pubkeys: []
+        },
+        verification: verificationData,
+        gatekeeper: {
+          capabilities: []
+        },
+        external_refs: []
+      }
+    };
+    const contentString = JSON.stringify(structure, null, 2);
+    const bytes = new TextEncoder().encode(contentString);
+    const hash = await HashValidator.computeHash(bytes, hashAlgorithm);
+    const g_time = GTime.stampNow(hashAlgorithm);
+    const contentType = ContentTypeInterpreter.detect(bytes);
+    return new _VCard(bytes, hash, g_time, contentType, hashAlgorithm, structure);
+  }
+  /**
+   * 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) {
+    const myHandle = this.getTokenHandle();
+    return myHandle === requiredHandle;
+  }
+  // =========================================================================
+  // VCard Sandwich methods have been extracted to VCardSandwich.ts
+  // =========================================================================
+};
+var VCardSimulation = class {
+  vcard;
+  log;
+  constructor(vcard) {
+    this.vcard = vcard;
+    this.log = [];
+  }
+  logEffect(effectType, details) {
+    this.log.push({
+      timestamp: /* @__PURE__ */ new Date(),
+      effectType,
+      details,
+      simulated: true
+    });
+  }
+  getSimulationLog() {
+    return this.log;
+  }
+};
+var VCardPre = class extends VCard {
+  fireHook(eventType, mcard) {
+    if (this.getManagedEventTypes().includes(eventType)) {
+      this.logGatekeeperEvent({
+        direction: "ingress" /* INGRESS */,
+        timestamp: /* @__PURE__ */ new Date(),
+        sourceDid: void 0,
+        destinationDid: this.subjectDid || "unknown",
+        contentHash: mcard.hash,
+        authorized: true,
+        capabilityUsed: "VCardPre_Hook"
+      });
+    }
+  }
+};
+var VCardPost = class extends VCard {
+  dispatchEvents(logDb) {
+    const dispatchedCards = [];
+    for (const eventType of this.getManagedEventTypes()) {
+      const payload = JSON.stringify({ type: eventType, dispatched_by: this.hash });
+      const encoder = new TextEncoder();
+      if (logDb && typeof logDb.add === "function") {
+        logDb.add({ type: eventType, payload, dispatchedBy: this.hash });
+      }
+      dispatchedCards.push(new MCard(encoder.encode(payload), "temp-hash-" + Date.now(), "temp-time", "application/json", "sha256"));
+      this.logGatekeeperEvent({
+        direction: "egress" /* EGRESS */,
+        timestamp: /* @__PURE__ */ new Date(),
+        sourceDid: this.subjectDid || "unknown",
+        destinationDid: void 0,
+        contentHash: "temp-hash-" + Date.now(),
+        authorized: true,
+        capabilityUsed: "VCardPost_Dispatch"
+      });
+    }
+    return dispatchedCards;
+  }
+};
+
+export {
+  CapabilityScope,
+  GatekeeperDirection,
+  isVCard,
+  getPCardRefs,
+  getSubjectDid,
+  VCard,
+  VCardSimulation,
+  VCardPre,
+  VCardPost
+};