@emilia-protocol/gate 0.11.0 → 0.14.0

package/action-escrow-verifiers.js

@@ -1,332 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
-/**
- * Adapters that turn independently verified protocol artifacts into the exact
- * result contract consumed by the Action Escrow state kernel.
- */
-import {
-  verifyDocumentActionBinding,
-} from '@emilia-protocol/verify/document-action-binding';
-import { canonicalize, hashCanonical } from './execution-binding.js';
-
-export const ACTION_ESCROW_AGREEMENT_DIGEST_VERSION =
-  'EP-ACTION-ESCROW-AGREEMENT-DIGEST-v1';
-
-const HASH = /^sha256:[0-9a-f]{64}$/;
-const AMOUNT = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
-const CURRENCY = /^[A-Z]{3}$/;
-export const ACTION_ESCROW_REQUIRED_MATERIAL_TERM_IDS = Object.freeze([
-  'amendment_version',
-  'completion_requirements_digest',
-  'document_authorizes_payment',
-  'milestone_name',
-  'payee_id',
-  'release.amount',
-  'release.destination_id',
-  'release.milestone_id',
-  'release_requires_mutual_approval',
-  'retainage_amount',
-]);
-const RELEASE_TEMPLATE_KEYS = new Set([
-  'action_type',
-  'action_escrow_profile_digest',
-  'agreement_id',
-  'agreement_digest',
-  'milestone_id',
-  'amount',
-  'currency',
-  'destination_id',
-  'payee_id',
-  'custodian_provider',
-  'custodian_environment',
-  'custodian_transaction_id',
-  'custodian_milestone_id',
-  'document_sha256',
-  'material_terms_sha256',
-  'completion_evidence_sha256',
-  'amendment_version',
-]);
-
-function isRecord(value) {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-
-function canonicalCopy(value) {
-  return JSON.parse(canonicalize(value));
-}
-
-function deepFreeze(value) {
-  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
-  Object.freeze(value);
-  for (const child of Object.values(value)) deepFreeze(child);
-  return value;
-}
-
-function validString(value, max = 256) {
-  return typeof value === 'string'
-    && value.length > 0
-    && value.length <= max
-    && !/[\u0000-\u001f\u007f]/.test(value);
-}
-
-function sortedParties(parties) {
-  if (!Array.isArray(parties)) return null;
-  try {
-    return canonicalCopy(parties).sort((left, right) => {
-      const leftKey = `${left.role}\u0000${left.party_id}`;
-      const rightKey = `${right.role}\u0000${right.party_id}`;
-      return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
-    });
-  } catch {
-    return null;
-  }
-}
-
-function bytesCopy(value) {
-  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
-    return Uint8Array.from(value);
-  }
-  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
-  return null;
-}
-
-function refusal(reason) {
-  return Object.freeze({
-    valid: false,
-    reason,
-  });
-}
-
-export function computeActionEscrowAgreementDigest(agreementId) {
-  if (!validString(agreementId)) return null;
-  try {
-    return `sha256:${hashCanonical({
-      '@version': ACTION_ESCROW_AGREEMENT_DIGEST_VERSION,
-      agreement_id: agreementId,
-    })}`;
-  } catch {
-    return null;
-  }
-}
-
-function exactExpected(value) {
-  if (!isRecord(value)
-    || !HASH.test(value.agreement_digest)
-    || !HASH.test(value.document_action_binding_digest)
-    || !HASH.test(value.release_action_digest)
-    || !HASH.test(value.parties_digest)
-    || !HASH.test(value.profile_digest)
-    || !validString(value.milestone_id)
-    || !Array.isArray(value.parties)) {
-    return null;
-  }
-  const parties = sortedParties(value.parties);
-  if (!parties || parties.length < 2) return null;
-  return {
-    agreement_digest: value.agreement_digest,
-    document_action_binding_digest: value.document_action_binding_digest,
-    release_action_digest: value.release_action_digest,
-    milestone_id: value.milestone_id,
-    parties,
-    parties_digest: value.parties_digest,
-    profile_digest: value.profile_digest,
-    supersedes_document_action_binding_digest:
-      value.supersedes_document_action_binding_digest ?? null,
-  };
-}
-
-export function validateActionEscrowReleaseTemplate(template, {
-  profileDigest,
-  agreementId,
-  agreementDigest,
-  milestoneId,
-  documentDigest,
-  materialTerms,
-} = {}) {
-  if (!isRecord(template)
-    || Object.keys(template).length !== RELEASE_TEMPLATE_KEYS.size
-    || Object.keys(template).some((key) => !RELEASE_TEMPLATE_KEYS.has(key))
-    || template.action_type !== 'escrow.milestone.release'
-    || template.action_escrow_profile_digest !== profileDigest
-    || template.agreement_id !== agreementId
-    || template.agreement_digest !== agreementDigest
-    || template.milestone_id !== milestoneId
-    || typeof template.amount !== 'string'
-    || !AMOUNT.test(template.amount)
-    || typeof template.currency !== 'string'
-    || !CURRENCY.test(template.currency)
-    || !validString(template.destination_id, 512)
-    || !validString(template.payee_id, 512)
-    || !validString(template.custodian_provider, 128)
-    || !['sandbox', 'production'].includes(template.custodian_environment)
-    || !validString(template.custodian_transaction_id, 256)
-    || !validString(template.custodian_milestone_id, 256)
-    || template.document_sha256 !== documentDigest
-    || !HASH.test(template.material_terms_sha256)
-    || (materialTerms !== undefined
-      && template.material_terms_sha256 !== `sha256:${hashCanonical(materialTerms)}`)
-    || !HASH.test(template.completion_evidence_sha256)
-    || !Number.isSafeInteger(template.amendment_version)
-    || template.amendment_version < 1) {
-    return null;
-  }
-  try {
-    const copy = canonicalCopy(template);
-    return Buffer.byteLength(canonicalize(copy), 'utf8') <= 64 * 1024 ? copy : null;
-  } catch {
-    return null;
-  }
-}
-
-function exactActionTemplate(binding, expected) {
-  return validateActionEscrowReleaseTemplate(binding?.release_action?.template, {
-    profileDigest: expected.profile_digest,
-    agreementId: binding?.agreement_id,
-    agreementDigest: expected.agreement_digest,
-    milestoneId: expected.milestone_id,
-    documentDigest: binding?.document?.digest,
-    materialTerms: binding?.material_terms,
-  });
-}
-
-function materialTermsMatchAction(binding, template) {
-  if (!Array.isArray(binding?.material_terms)) return false;
-  const terms = new Map(binding.material_terms.map((term) => [term.term_id, term]));
-  const amount = terms.get('release.amount');
-  const destination = terms.get('release.destination_id');
-  const milestone = terms.get('release.milestone_id');
-  const amendment = terms.get('amendment_version');
-  const completionRequirements = terms.get('completion_requirements_digest');
-  const documentAuthorizesPayment = terms.get('document_authorizes_payment');
-  const milestoneName = terms.get('milestone_name');
-  const payee = terms.get('payee_id');
-  const releaseRequiresMutualApproval = terms.get('release_requires_mutual_approval');
-  const retainage = terms.get('retainage_amount');
-  return amount?.type === 'amount'
-    && amount.value === template.amount
-    && amount.currency === template.currency
-    && ['identifier', 'string'].includes(destination?.type)
-    && destination.value === template.destination_id
-    && ['identifier', 'string'].includes(milestone?.type)
-    && milestone.value === template.milestone_id
-    && amendment?.type === 'integer'
-    && amendment.value === template.amendment_version
-    && completionRequirements?.type === 'digest'
-    && HASH.test(completionRequirements.value)
-    && documentAuthorizesPayment?.type === 'boolean'
-    && documentAuthorizesPayment.value === false
-    && milestoneName?.type === 'string'
-    && validString(milestoneName.value, 2048)
-    && payee?.type === 'identifier'
-    && payee.value === template.payee_id
-    && releaseRequiresMutualApproval?.type === 'boolean'
-    && releaseRequiresMutualApproval.value === true
-    && retainage?.type === 'amount'
-    && retainage.currency === template.currency;
-}
-
-/**
- * Create a kernel verifier backed by the public DAB verifier.
- *
- * The document resolver is mandatory: mapping authenticity without checking
- * the final bytes is insufficient for a release decision.
- */
-export function createActionEscrowDocumentBindingVerifier({
-  issuerKeys,
-  resolveDocumentBytes,
-  allowedMediaTypes = ['application/pdf'],
-  allowedPartyRoles = ['client', 'contractor'],
-  now = Date.now,
-} = {}) {
-  if (!isRecord(issuerKeys)
-    || Object.keys(issuerKeys).length === 0
-    || typeof resolveDocumentBytes !== 'function'
-    || typeof now !== 'function') {
-    throw new TypeError('pinned DAB keys, document resolver, and clock are required');
-  }
-  const pinnedIssuerKeys = deepFreeze(canonicalCopy(issuerKeys));
-  const mediaTypes = deepFreeze(canonicalCopy(allowedMediaTypes));
-  const partyRoles = deepFreeze(canonicalCopy(allowedPartyRoles));
-
-  return async function verifyForKernel(binding, untrustedExpected) {
-    try {
-      const expected = exactExpected(untrustedExpected);
-      if (!expected) return refusal('invalid_expected_binding_context');
-      const evaluationTime = now();
-      const options = {
-        issuerKeys: pinnedIssuerKeys,
-        now: evaluationTime,
-        allowedMediaTypes: mediaTypes,
-        allowedPartyRoles: partyRoles,
-        allowedActionTypes: ['escrow.milestone.release'],
-        requiredMaterialTermIds: ACTION_ESCROW_REQUIRED_MATERIAL_TERM_IDS,
-        expectedRequiredParties: expected.parties,
-        expectedSupersedesDigest:
-          expected.supersedes_document_action_binding_digest,
-      };
-      const authenticated = verifyDocumentActionBinding(binding, options);
-      if (!authenticated.valid) return refusal(authenticated.reason);
-      if (authenticated.binding_digest !== expected.document_action_binding_digest
-        || authenticated.action_digest !== expected.release_action_digest
-        || computeActionEscrowAgreementDigest(authenticated.agreement_id)
-          !== expected.agreement_digest) {
-        return refusal('kernel_binding_context_mismatch');
-      }
-
-      const actionTemplate = exactActionTemplate(binding, expected);
-      if (!actionTemplate || !materialTermsMatchAction(binding, actionTemplate)) {
-        return refusal('material_action_mapping_mismatch');
-      }
-      const resolved = await resolveDocumentBytes(deepFreeze({
-        agreement_id: authenticated.agreement_id,
-        binding_id: authenticated.binding_id,
-        binding_digest: authenticated.binding_digest,
-        document_digest: authenticated.document_digest,
-        document_media_type: binding.document.media_type,
-        document_byte_length: binding.document.byte_length,
-      }));
-      const documentBytes = bytesCopy(resolved);
-      if (!documentBytes) return refusal('document_bytes_unavailable');
-      const verified = verifyDocumentActionBinding(binding, {
-        ...options,
-        documentBytes,
-        documentMediaType: binding.document.media_type,
-        releaseActionTemplate: actionTemplate,
-      });
-      if (!verified.valid) return refusal(verified.reason);
-
-      return deepFreeze({
-        valid: true,
-        reason: 'valid',
-        verification_digest: verified.binding_digest,
-        document_digest: verified.document_digest,
-        agreement_id: verified.agreement_id,
-        binding_id: verified.binding_id,
-        release_action_template: actionTemplate,
-        agreement_digest: expected.agreement_digest,
-        document_action_binding_digest: verified.binding_digest,
-        milestone_id: expected.milestone_id,
-        release_action_digest: verified.action_digest,
-        parties_digest: expected.parties_digest,
-        profile_digest: expected.profile_digest,
-        ...(verified.supersedes_digest === null
-          ? {}
-          : {
-            supersedes_document_action_binding_digest:
-              verified.supersedes_digest,
-          }),
-      });
-    } catch {
-      return refusal('document_action_binding_verifier_failed');
-    }
-  };
-}
-
-export default Object.freeze({
-  ACTION_ESCROW_AGREEMENT_DIGEST_VERSION,
-  ACTION_ESCROW_REQUIRED_MATERIAL_TERM_IDS,
-  computeActionEscrowAgreementDigest,
-  createActionEscrowDocumentBindingVerifier,
-  validateActionEscrowReleaseTemplate,
-});
+// Compatibility entry point for the TypeScript action-escrow-verifiers module.
+export * from './dist/action-escrow-verifiers.js';
+export { default } from './dist/action-escrow-verifiers.js';