@peac/schema 0.10.9 → 0.10.10

package/dist/interaction.mjs

@@ -0,0 +1,583 @@
+import { z } from 'zod';
+
+// src/interaction.ts
+var INTERACTION_EXTENSION_KEY = "org.peacprotocol/interaction@0.1";
+var CANONICAL_DIGEST_ALGS = [
+  "sha-256",
+  // Full SHA-256
+  "sha-256:trunc-64k",
+  // First 64KB (65536 bytes)
+  "sha-256:trunc-1m"
+  // First 1MB (1048576 bytes)
+];
+var DIGEST_SIZE_CONSTANTS = {
+  k: 1024,
+  // 1 KB = 1024 bytes (binary)
+  m: 1024 * 1024,
+  // 1 MB = 1048576 bytes (binary)
+  "trunc-64k": 65536,
+  // 64 * 1024
+  "trunc-1m": 1048576
+  // 1024 * 1024
+};
+var RESULT_STATUSES = ["ok", "error", "timeout", "canceled"];
+var REDACTION_MODES = ["hash_only", "redacted", "plaintext_allowlisted"];
+var POLICY_DECISIONS = ["allow", "deny", "constrained"];
+var WELL_KNOWN_KINDS = [
+  "tool.call",
+  "http.request",
+  "fs.read",
+  "fs.write",
+  "message"
+];
+var RESERVED_KIND_PREFIXES = ["peac.", "org.peacprotocol."];
+var INTERACTION_LIMITS = {
+  /** Maximum interaction ID length */
+  maxInteractionIdLength: 256,
+  /** Maximum kind length */
+  maxKindLength: 128,
+  /** Maximum platform name length */
+  maxPlatformLength: 64,
+  /** Maximum version string length */
+  maxVersionLength: 64,
+  /** Maximum plugin ID length */
+  maxPluginIdLength: 128,
+  /** Maximum tool name length */
+  maxToolNameLength: 256,
+  /** Maximum provider length */
+  maxProviderLength: 128,
+  /** Maximum URI length */
+  maxUriLength: 2048,
+  /** Maximum method length */
+  maxMethodLength: 16,
+  /** Maximum error code length */
+  maxErrorCodeLength: 128,
+  /** Maximum payment reference length */
+  maxPaymentReferenceLength: 256,
+  /** Maximum receipt RID length */
+  maxReceiptRidLength: 128
+};
+function requiresTool(kind) {
+  return kind.startsWith("tool.");
+}
+function requiresResource(kind) {
+  return kind.startsWith("http.") || kind.startsWith("fs.");
+}
+function usesReservedPrefix(kind) {
+  return RESERVED_KIND_PREFIXES.some((prefix) => kind.startsWith(prefix));
+}
+function hasMeaningfulResource(resource) {
+  if (!resource) return false;
+  if (typeof resource.uri === "string" && resource.uri.length > 0) return true;
+  return false;
+}
+var KIND_FORMAT_PATTERN = /^[a-z][a-z0-9._:-]{0,126}[a-z0-9]$/;
+var EXTENSION_KEY_PATTERN = /^([a-z0-9-]+\.)+[a-z0-9-]+\/[a-z][a-z0-9._:-]{0,126}[a-z0-9](?:@[0-9]+(?:\.[0-9]+)*)?$/;
+var DIGEST_VALUE_PATTERN = /^[a-f0-9]{64}$/;
+var DigestAlgSchema = z.enum(CANONICAL_DIGEST_ALGS);
+var DigestSchema = z.object({
+  /** Algorithm: 'sha-256' (full) or 'sha-256:trunc-{size}' (truncated) */
+  alg: DigestAlgSchema,
+  /** 64 lowercase hex chars (SHA-256 output) */
+  value: z.string().regex(DIGEST_VALUE_PATTERN, "Must be 64 lowercase hex chars"),
+  /** Original byte length before any truncation (REQUIRED) */
+  bytes: z.number().int().nonnegative()
+}).strict();
+var PayloadRefSchema = z.object({
+  /** Content digest */
+  digest: DigestSchema,
+  /** Redaction mode */
+  redaction: z.enum(REDACTION_MODES)
+}).strict();
+var ExecutorSchema = z.object({
+  /** Platform identifier: 'openclaw', 'mcp', 'a2a', 'claude-code' */
+  platform: z.string().min(1).max(INTERACTION_LIMITS.maxPlatformLength),
+  /** Platform version */
+  version: z.string().max(INTERACTION_LIMITS.maxVersionLength).optional(),
+  /** Plugin that captured this */
+  plugin_id: z.string().max(INTERACTION_LIMITS.maxPluginIdLength).optional(),
+  /** Hash of plugin package (provenance) */
+  plugin_digest: DigestSchema.optional()
+}).strict();
+var ToolTargetSchema = z.object({
+  /** Tool name */
+  name: z.string().min(1).max(INTERACTION_LIMITS.maxToolNameLength),
+  /** Tool provider */
+  provider: z.string().max(INTERACTION_LIMITS.maxProviderLength).optional(),
+  /** Tool version */
+  version: z.string().max(INTERACTION_LIMITS.maxVersionLength).optional()
+}).strict();
+var ResourceTargetSchema = z.object({
+  /** Resource URI */
+  uri: z.string().max(INTERACTION_LIMITS.maxUriLength).optional(),
+  /** HTTP method or operation */
+  method: z.string().max(INTERACTION_LIMITS.maxMethodLength).optional()
+}).strict();
+var ResultSchema = z.object({
+  /** Result status */
+  status: z.enum(RESULT_STATUSES),
+  /** Error code (PEAC error code or namespaced) */
+  error_code: z.string().max(INTERACTION_LIMITS.maxErrorCodeLength).optional(),
+  /** Whether the operation can be retried */
+  retryable: z.boolean().optional()
+}).strict();
+var PolicyContextSchema = z.object({
+  /** Policy decision */
+  decision: z.enum(POLICY_DECISIONS),
+  /** Whether sandbox mode was enabled */
+  sandbox_enabled: z.boolean().optional(),
+  /** Whether elevated permissions were granted */
+  elevated: z.boolean().optional(),
+  /** Hash of effective policy document */
+  effective_policy_digest: DigestSchema.optional()
+}).strict();
+var RefsSchema = z.object({
+  /** Links to evidence.payment.reference */
+  payment_reference: z.string().max(INTERACTION_LIMITS.maxPaymentReferenceLength).optional(),
+  /** Correlation across receipts */
+  related_receipt_rid: z.string().max(INTERACTION_LIMITS.maxReceiptRidLength).optional()
+}).strict();
+var KindSchema = z.string().min(2).max(INTERACTION_LIMITS.maxKindLength).regex(KIND_FORMAT_PATTERN, "Invalid kind format");
+var InteractionEvidenceV01BaseSchema = z.object({
+  /** Stable ID for idempotency/dedupe (REQUIRED) */
+  interaction_id: z.string().min(1).max(INTERACTION_LIMITS.maxInteractionIdLength),
+  /** Event kind - open string, not closed enum (REQUIRED) */
+  kind: KindSchema,
+  /** Executor identity (REQUIRED) */
+  executor: ExecutorSchema,
+  /** Tool target (when kind is tool-related) */
+  tool: ToolTargetSchema.optional(),
+  /** Resource target (when kind is http/fs-related) */
+  resource: ResourceTargetSchema.optional(),
+  /** Input payload reference */
+  input: PayloadRefSchema.optional(),
+  /** Output payload reference */
+  output: PayloadRefSchema.optional(),
+  /** Start time (RFC 3339) (REQUIRED) */
+  started_at: z.string().datetime(),
+  /** Completion time (RFC 3339) */
+  completed_at: z.string().datetime().optional(),
+  /** Duration in milliseconds (OPTIONAL, non-normative) */
+  duration_ms: z.number().int().nonnegative().optional(),
+  /** Execution outcome */
+  result: ResultSchema.optional(),
+  /** Policy context at execution */
+  policy: PolicyContextSchema.optional(),
+  /** References to related evidence */
+  refs: RefsSchema.optional(),
+  /** Platform-specific extensions (MUST be namespaced) */
+  extensions: z.record(z.unknown()).optional()
+}).strict();
+var InteractionEvidenceV01Schema = InteractionEvidenceV01BaseSchema.superRefine(
+  (ev, ctx) => {
+    if (ev.completed_at && ev.started_at) {
+      const startedAt = new Date(ev.started_at).getTime();
+      const completedAt = new Date(ev.completed_at).getTime();
+      if (completedAt < startedAt) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "completed_at must be >= started_at",
+          path: ["completed_at"]
+        });
+      }
+    }
+    if (ev.output && !ev.result?.status) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "result.status is required when output is present",
+        path: ["result"]
+      });
+    }
+    if (ev.result?.status === "error") {
+      const hasErrorCode = Boolean(ev.result.error_code);
+      const hasNonEmptyExtensions = ev.extensions !== void 0 && Object.keys(ev.extensions).length > 0;
+      if (!hasErrorCode && !hasNonEmptyExtensions) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "error_code or non-empty extensions required when status is error",
+          path: ["result", "error_code"]
+        });
+      }
+    }
+    if (ev.extensions) {
+      for (const key of Object.keys(ev.extensions)) {
+        if (!EXTENSION_KEY_PATTERN.test(key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Invalid extension key format: ${key} (must be reverse-DNS/name[@version])`,
+            path: ["extensions", key]
+          });
+        }
+      }
+    }
+    if (usesReservedPrefix(ev.kind) && !WELL_KNOWN_KINDS.includes(ev.kind)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `kind "${ev.kind}" uses reserved prefix`,
+        path: ["kind"]
+      });
+    }
+    if (requiresTool(ev.kind) && !ev.tool) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `kind "${ev.kind}" requires tool field`,
+        path: ["tool"]
+      });
+    }
+    if (requiresResource(ev.kind)) {
+      if (!ev.resource) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `kind "${ev.kind}" requires resource field`,
+          path: ["resource"]
+        });
+      } else if (!hasMeaningfulResource(ev.resource)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `kind "${ev.kind}" requires resource.uri to be non-empty`,
+          path: ["resource", "uri"]
+        });
+      }
+    }
+  }
+);
+function validateInteractionOrdered(input) {
+  const errors = [];
+  const warnings = [];
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          code: "E_INTERACTION_INVALID_FORMAT",
+          message: "Input must be an object"
+        }
+      ],
+      warnings: []
+    };
+  }
+  const obj = input;
+  if (typeof obj.interaction_id !== "string" || obj.interaction_id.length === 0) {
+    errors.push({
+      code: "E_INTERACTION_MISSING_ID",
+      message: "interaction_id is required",
+      field: "interaction_id"
+    });
+  } else if (obj.interaction_id.length > INTERACTION_LIMITS.maxInteractionIdLength) {
+    errors.push({
+      code: "E_INTERACTION_INVALID_FORMAT",
+      message: `interaction_id exceeds max length (${INTERACTION_LIMITS.maxInteractionIdLength})`,
+      field: "interaction_id"
+    });
+  }
+  if (typeof obj.kind !== "string" || obj.kind.length === 0) {
+    errors.push({
+      code: "E_INTERACTION_MISSING_KIND",
+      message: "kind is required",
+      field: "kind"
+    });
+  } else if (obj.kind.length < 2 || obj.kind.length > INTERACTION_LIMITS.maxKindLength) {
+    errors.push({
+      code: "E_INTERACTION_INVALID_KIND_FORMAT",
+      message: `kind must be 2-${INTERACTION_LIMITS.maxKindLength} characters`,
+      field: "kind"
+    });
+  } else if (!KIND_FORMAT_PATTERN.test(obj.kind)) {
+    errors.push({
+      code: "E_INTERACTION_INVALID_KIND_FORMAT",
+      message: "kind must match pattern: lowercase, start with letter, end with alphanumeric",
+      field: "kind"
+    });
+  } else {
+    for (const prefix of RESERVED_KIND_PREFIXES) {
+      if (obj.kind.startsWith(prefix) && !WELL_KNOWN_KINDS.includes(obj.kind)) {
+        errors.push({
+          code: "E_INTERACTION_KIND_RESERVED",
+          message: `kind "${obj.kind}" uses reserved prefix "${prefix}"`,
+          field: "kind"
+        });
+        break;
+      }
+    }
+    if (errors.length === 0 && !WELL_KNOWN_KINDS.includes(obj.kind)) {
+      warnings.push({
+        code: "W_INTERACTION_KIND_UNREGISTERED",
+        message: `kind "${obj.kind}" is not in the well-known registry`,
+        field: "kind"
+      });
+    }
+  }
+  if (typeof obj.started_at !== "string") {
+    errors.push({
+      code: "E_INTERACTION_MISSING_STARTED_AT",
+      message: "started_at is required",
+      field: "started_at"
+    });
+  } else {
+    const startedAtDate = new Date(obj.started_at);
+    if (isNaN(startedAtDate.getTime())) {
+      errors.push({
+        code: "E_INTERACTION_MISSING_STARTED_AT",
+        message: "started_at must be a valid ISO 8601 datetime",
+        field: "started_at"
+      });
+    }
+  }
+  if (typeof obj.executor !== "object" || obj.executor === null) {
+    errors.push({
+      code: "E_INTERACTION_MISSING_EXECUTOR",
+      message: "executor is required",
+      field: "executor"
+    });
+  } else {
+    const executor = obj.executor;
+    if (typeof executor.platform !== "string" || executor.platform.length === 0) {
+      errors.push({
+        code: "E_INTERACTION_MISSING_EXECUTOR",
+        message: "executor.platform is required",
+        field: "executor.platform"
+      });
+    } else if (executor.platform.length > INTERACTION_LIMITS.maxPlatformLength) {
+      errors.push({
+        code: "E_INTERACTION_INVALID_FORMAT",
+        message: `executor.platform exceeds max length (${INTERACTION_LIMITS.maxPlatformLength})`,
+        field: "executor.platform"
+      });
+    }
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+  const validateDigest = (digest, fieldPath) => {
+    const digestErrors = [];
+    if (typeof digest !== "object" || digest === null) {
+      digestErrors.push({
+        code: "E_INTERACTION_INVALID_DIGEST",
+        message: "digest must be an object",
+        field: fieldPath
+      });
+      return { errors: digestErrors, valid: false };
+    }
+    const d = digest;
+    if (!CANONICAL_DIGEST_ALGS.includes(d.alg)) {
+      digestErrors.push({
+        code: "E_INTERACTION_INVALID_DIGEST_ALG",
+        message: `digest.alg must be one of: ${CANONICAL_DIGEST_ALGS.join(", ")}`,
+        field: `${fieldPath}.alg`
+      });
+    }
+    if (typeof d.value !== "string" || !DIGEST_VALUE_PATTERN.test(d.value)) {
+      digestErrors.push({
+        code: "E_INTERACTION_INVALID_DIGEST",
+        message: "digest.value must be 64 lowercase hex chars",
+        field: `${fieldPath}.value`
+      });
+    }
+    if (typeof d.bytes !== "number" || !Number.isInteger(d.bytes) || d.bytes < 0) {
+      digestErrors.push({
+        code: "E_INTERACTION_INVALID_DIGEST",
+        message: "digest.bytes must be a non-negative integer",
+        field: `${fieldPath}.bytes`
+      });
+    }
+    return { errors: digestErrors, valid: digestErrors.length === 0 };
+  };
+  if (obj.input !== void 0) {
+    const inputObj = obj.input;
+    if (inputObj.digest !== void 0) {
+      const result = validateDigest(inputObj.digest, "input.digest");
+      errors.push(...result.errors);
+    }
+  }
+  if (obj.output !== void 0) {
+    const outputObj = obj.output;
+    if (outputObj.digest !== void 0) {
+      const result = validateDigest(outputObj.digest, "output.digest");
+      errors.push(...result.errors);
+    }
+  }
+  if (typeof obj.completed_at === "string" && typeof obj.started_at === "string") {
+    const startedAt = new Date(obj.started_at).getTime();
+    const completedAt = new Date(obj.completed_at).getTime();
+    if (!isNaN(startedAt) && !isNaN(completedAt) && completedAt < startedAt) {
+      errors.push({
+        code: "E_INTERACTION_INVALID_TIMING",
+        message: "completed_at must be >= started_at",
+        field: "completed_at"
+      });
+    }
+  }
+  if (obj.output !== void 0) {
+    const result = obj.result;
+    if (!result?.status) {
+      errors.push({
+        code: "E_INTERACTION_MISSING_RESULT",
+        message: "result.status is required when output is present",
+        field: "result"
+      });
+    }
+  }
+  if (obj.result !== void 0) {
+    const result = obj.result;
+    if (result.status === "error") {
+      const hasErrorCode = Boolean(result.error_code);
+      const hasNonEmptyExtensions = obj.extensions !== void 0 && typeof obj.extensions === "object" && obj.extensions !== null && Object.keys(obj.extensions).length > 0;
+      if (!hasErrorCode && !hasNonEmptyExtensions) {
+        errors.push({
+          code: "E_INTERACTION_MISSING_ERROR_DETAIL",
+          message: "error_code or non-empty extensions required when result.status is error",
+          field: "result.error_code"
+        });
+      }
+    }
+  }
+  if (obj.extensions !== void 0) {
+    if (typeof obj.extensions !== "object" || obj.extensions === null) {
+      errors.push({
+        code: "E_INTERACTION_INVALID_FORMAT",
+        message: "extensions must be an object",
+        field: "extensions"
+      });
+    } else {
+      for (const key of Object.keys(obj.extensions)) {
+        if (!EXTENSION_KEY_PATTERN.test(key)) {
+          errors.push({
+            code: "E_INTERACTION_INVALID_EXTENSION_KEY",
+            message: `Invalid extension key format: "${key}" (must be reverse-DNS/name[@version])`,
+            field: `extensions.${key}`
+          });
+        }
+      }
+    }
+  }
+  const kind = obj.kind;
+  const hasTool = obj.tool !== void 0;
+  const hasResource = obj.resource !== void 0;
+  if (requiresTool(kind) && !hasTool) {
+    errors.push({
+      code: "E_INTERACTION_MISSING_TARGET",
+      message: `kind "${kind}" requires tool field`,
+      field: "tool"
+    });
+  }
+  if (requiresResource(kind)) {
+    if (!hasResource) {
+      errors.push({
+        code: "E_INTERACTION_MISSING_TARGET",
+        message: `kind "${kind}" requires resource field`,
+        field: "resource"
+      });
+    } else if (!hasMeaningfulResource(obj.resource)) {
+      errors.push({
+        code: "E_INTERACTION_MISSING_TARGET",
+        message: `kind "${kind}" requires resource.uri to be non-empty`,
+        field: "resource.uri"
+      });
+    }
+  }
+  if (!hasTool && !hasResource && errors.length === 0) {
+    warnings.push({
+      code: "W_INTERACTION_MISSING_TARGET",
+      message: "Neither tool nor resource field is present",
+      field: "tool"
+    });
+  }
+  if (errors.length > 0) {
+    return { valid: false, errors, warnings };
+  }
+  const zodResult = InteractionEvidenceV01Schema.safeParse(input);
+  if (!zodResult.success) {
+    return {
+      valid: false,
+      errors: [
+        {
+          code: "E_INTERACTION_INVALID_FORMAT",
+          message: zodResult.error.issues[0]?.message || "Schema validation failed",
+          field: zodResult.error.issues[0]?.path.join(".")
+        }
+      ],
+      warnings
+    };
+  }
+  return { valid: true, value: zodResult.data, warnings };
+}
+function validateInteraction(input) {
+  const result = validateInteractionOrdered(input);
+  if (result.valid) {
+    return { valid: true };
+  }
+  const firstError = result.errors[0];
+  return {
+    valid: false,
+    error_code: firstError?.code,
+    error_field: firstError?.field
+  };
+}
+function validateInteractionEvidence(evidence) {
+  return InteractionEvidenceV01Schema.parse(evidence);
+}
+function isValidInteractionEvidence(evidence) {
+  return InteractionEvidenceV01Schema.safeParse(evidence).success;
+}
+function isWellKnownKind(kind) {
+  return WELL_KNOWN_KINDS.includes(kind);
+}
+function isReservedKindPrefix(kind) {
+  return RESERVED_KIND_PREFIXES.some((prefix) => kind.startsWith(prefix));
+}
+function isDigestTruncated(digest) {
+  return digest.alg.startsWith("sha-256:trunc-");
+}
+function getInteraction(receipt) {
+  return receipt.evidence?.extensions?.[INTERACTION_EXTENSION_KEY];
+}
+function setInteraction(receipt, interaction) {
+  if (!receipt.evidence) {
+    receipt.evidence = {};
+  }
+  if (!receipt.evidence.extensions) {
+    receipt.evidence.extensions = {};
+  }
+  receipt.evidence.extensions[INTERACTION_EXTENSION_KEY] = interaction;
+}
+function hasInteraction(receipt) {
+  return receipt.evidence?.extensions?.[INTERACTION_EXTENSION_KEY] !== void 0;
+}
+function createReceiptView(envelope) {
+  const interaction = getInteraction(envelope);
+  const workflow = envelope.auth?.extensions?.["org.peacprotocol/workflow"];
+  return {
+    envelope,
+    interaction,
+    interactions: interaction ? [interaction] : [],
+    workflow
+  };
+}
+function createInteractionEvidence(params) {
+  const evidence = {
+    interaction_id: params.interaction_id,
+    kind: params.kind,
+    executor: {
+      platform: params.executor.platform,
+      ...params.executor.version && { version: params.executor.version },
+      ...params.executor.plugin_id && { plugin_id: params.executor.plugin_id },
+      ...params.executor.plugin_digest && { plugin_digest: params.executor.plugin_digest }
+    },
+    ...params.tool && { tool: params.tool },
+    ...params.resource && { resource: params.resource },
+    ...params.input && { input: params.input },
+    ...params.output && { output: params.output },
+    started_at: params.started_at,
+    ...params.completed_at && { completed_at: params.completed_at },
+    ...params.duration_ms !== void 0 && { duration_ms: params.duration_ms },
+    ...params.result && { result: params.result },
+    ...params.policy && { policy: params.policy },
+    ...params.refs && { refs: params.refs },
+    ...params.extensions && { extensions: params.extensions }
+  };
+  return validateInteractionEvidence(evidence);
+}
+
+export { CANONICAL_DIGEST_ALGS, DIGEST_SIZE_CONSTANTS, DIGEST_VALUE_PATTERN, DigestAlgSchema, DigestSchema, EXTENSION_KEY_PATTERN, ExecutorSchema, INTERACTION_EXTENSION_KEY, INTERACTION_LIMITS, InteractionEvidenceV01Schema, KIND_FORMAT_PATTERN, KindSchema, POLICY_DECISIONS, PayloadRefSchema, PolicyContextSchema, REDACTION_MODES, RESERVED_KIND_PREFIXES, RESULT_STATUSES, RefsSchema, ResourceTargetSchema, ResultSchema, ToolTargetSchema, WELL_KNOWN_KINDS, createInteractionEvidence, createReceiptView, getInteraction, hasInteraction, isDigestTruncated, isReservedKindPrefix, isValidInteractionEvidence, isWellKnownKind, setInteraction, validateInteraction, validateInteractionEvidence, validateInteractionOrdered };
+//# sourceMappingURL=interaction.mjs.map
+//# sourceMappingURL=interaction.mjs.map