@agent-cards/checkout 0.19.0 → 0.21.0

package/examples/preflight/kernel-native/qualification.mjs

@@ -1,182 +0,0 @@
-// Maintainer tooling. Reports are trusted review inputs, never merchant-page inputs.
-import { createHash } from 'node:crypto';
-import { readFile, realpath } from 'node:fs/promises';
-import { isAbsolute, relative, resolve, sep } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { BUILTIN_REGISTRY } from '@agent-cards/checkout';
-import { assessCheckoutSupport, getCheckoutPreflightCatalog } from '@agent-cards/checkout/preflight';
-
-export const SUPPORTED_CHECKS = Object.freeze([
-  'native_recognition', 'approval_pause_resume', 'processor_replay',
-  'merchant_confirmation', 'unrecognized_request_passthrough', 'decline_or_error',
-  'no_duplicate_submission', 'authentication_or_explicit_exclusion',
-]);
-const SCENARIOS = ['one_time', 'save_card', 'subscription_initial', 'subscription_renewal'];
-const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
-const canonical = value => Array.isArray(value) ? value.map(canonical)
-  : value !== null && typeof value === 'object'
-    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
-export const digest = value => sha256(JSON.stringify(canonical(value)));
-const fail = message => { throw new Error(message); };
-const requireThat = (condition, message) => { if (!condition) fail(message); };
-const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const id = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._+-]{0,119}$/.test(value);
-const hash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
-const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 256 && !/[\x00-\x1f]/.test(value);
-const keys = (value, required, optional = []) => record(value)
-  && required.every(key => Object.hasOwn(value, key))
-  && Object.keys(value).every(key => [...required, ...optional].includes(key));
-
-function requireCompleteCatalog(catalog) {
-  requireThat(record(catalog) && catalog.schema_version === 1 && Array.isArray(catalog.processors), 'Invalid catalog.');
-  // This projection comes from request recognition, independently of preflight's
-  // capability projection. Regenerating a reduced inventory cannot hide a PSP.
-  const expected = new Map(BUILTIN_REGISTRY.map(({ psp, mode = 'token' }) => [psp, mode]));
-  const seen = new Set();
-  for (const processor of catalog.processors) {
-    requireThat(record(processor) && !seen.has(processor.psp) && expected.has(processor.psp)
-      && expected.get(processor.psp) === processor.mode, 'Canonical processor membership or mode mismatch.');
-    seen.add(processor.psp);
-  }
-  requireThat(seen.size === expected.size, 'The catalog omits a canonical processor.');
-}
-
-export function buildInventory(catalog, baseline) {
-  requireCompleteCatalog(catalog);
-  requireThat(baseline.evidence_level === 'documentation_only' && baseline.native_build === null
-    && Array.isArray(baseline.documented_adapters), 'Expected a documentation-only baseline.');
-  const documented = new Map(baseline.documented_adapters.map(adapter => [adapter.psp, adapter]));
-  requireThat(documented.size === baseline.documented_adapters.length
-    && [...documented.keys()].every(psp => catalog.processors.some(processor => processor.psp === psp)), 'Baseline processor drift.');
-  return {
-    schema_version: 1, catalog_version: catalog.catalog_version, catalog_sha256: digest(catalog),
-    baseline_version: baseline.baseline_version, baseline_sha256: digest(baseline), native_build: null,
-    processors: catalog.processors.map(({ psp, mode }) => ({
-      psp, mode, documentation: documented.has(psp) ? 'documented' : 'not_documented', status: 'unknown',
-      limitations: documented.has(psp) ? [...documented.get(psp).limitations, 'Native runtime evidence is missing.']
-        : ['No adapter declaration was found in the pinned documentation. Native runtime evidence is missing.'],
-    })),
-  };
-}
-
-function profileClaims(catalog, profile, now) {
-  requireThat(keys(profile, ['schema_version', 'profile_version', 'catalog_version', 'integration', 'entries'], ['processor_entries', 'expires_at'])
-    && profile.schema_version === 1 && id(profile.profile_version)
-    && keys(profile.integration, ['id', 'version']) && profile.integration.id === 'kernel_native'
-    && id(profile.integration.version), 'Invalid native profile.');
-  requireThat(profile.catalog_version === catalog.catalog_version, 'Profile catalog mismatch.');
-  // Ask the installed classifier to validate its own contract, including dates.
-  // Empty observations exercise profile validation without claiming a checkout.
-  const assessment = assessCheckoutSupport({ schema_version: 1, catalog_version: catalog.catalog_version,
-    signals: [], observation: { complete: true, truncated: false, reasons: [] } },
-  { integration: profile.integration, profile, now });
-  requireThat(assessment.reason_codes.every(code => ['psp_not_detected', 'checkout_flow_unidentified'].includes(code)),
-    'The installed classifier rejected the profile, catalog, or current time.');
-  requireThat(Array.isArray(profile.entries) && profile.entries.length <= 256
-    && (profile.processor_entries === undefined || (Array.isArray(profile.processor_entries) && profile.processor_entries.length <= 256)), 'Invalid profile declarations.');
-  const claims = new Map();
-  const add = (entry, kind) => {
-    const isFlow = kind === 'flow';
-    const required = isFlow ? ['flow', 'operation', 'operation_version', 'mode', 'scenario', 'status', 'limitations']
-      : ['psp', 'mode', 'scenario', 'status', 'limitations'];
-    requireThat(keys(entry, required) && SCENARIOS.includes(entry.scenario)
-      && ['supported', 'unsupported'].includes(entry.status)
-      && Array.isArray(entry.limitations) && entry.limitations.length > 0 && entry.limitations.length <= 16
-      && entry.limitations.every(text), 'Each declaration needs a valid status, scenario, and explicit limitations.');
-    const definition = isFlow ? catalog.flows.find(flow => flow.id === entry.flow)
-      : catalog.processors.find(processor => processor.psp === entry.psp);
-    requireThat(definition && definition.mode === entry.mode
-      && (!isFlow || (definition.operation === entry.operation && definition.operation_version === entry.operation_version)), 'Unknown declaration or operation/mode mismatch.');
-    if (entry.status === 'supported') {
-      requireThat(definition.server_constraint !== 'unsupported' && entry.scenario !== 'subscription_renewal'
-        && !(entry.mode === 'hosted_form' && entry.scenario !== 'one_time'), 'Shared Vault exclusion cannot be overridden.');
-    }
-    const key = isFlow ? `flow:${entry.flow}:${entry.operation}:${entry.operation_version}:${entry.mode}:${entry.scenario}`
-      : `processor:${entry.psp}:${entry.mode}:${entry.scenario}`;
-    requireThat(!claims.has(key), 'Duplicate profile declaration.');
-    const checks = entry.status === 'supported' ? [...SUPPORTED_CHECKS] : ['native_exclusion'];
-    if (entry.status === 'supported' && ['save_card', 'subscription_initial'].includes(entry.scenario)) {
-      checks.push('stored_card_consent', entry.scenario === 'save_card' ? 'merchant_card_saved' : 'merchant_subscription_confirmation');
-    }
-    claims.set(key, checks);
-  };
-  profile.entries.forEach(entry => add(entry, 'flow'));
-  (profile.processor_entries ?? []).forEach(entry => add(entry, 'processor'));
-  requireThat(claims.size > 0, 'An empty profile is an integration draft, not a qualified release.');
-  return claims;
-}
-
-async function verifyEvidence(evidence, directory) {
-  requireThat(keys(evidence, ['path', 'sha256']) && typeof evidence.path === 'string'
-    && evidence.path.length > 0 && evidence.path.length <= 1024 && !/[\x00-\x1f\\]/.test(evidence.path)
-    && !isAbsolute(evidence.path) && !evidence.path.split('/').includes('..') && hash(evidence.sha256), 'Invalid evidence path or digest.');
-  const actual = await realpath(resolve(directory, evidence.path));
-  const inside = relative(directory, actual);
-  requireThat(inside !== '' && inside !== '..' && !inside.startsWith(`..${sep}`) && !isAbsolute(inside), 'Evidence escapes its directory.');
-  requireThat(sha256(await readFile(actual)) === evidence.sha256, 'Evidence digest mismatch.');
-}
-
-/** Validates a trusted attestation and its retained files, not the truth of a test run. */
-export async function verifyRelease({ catalog, profile, report, runtime, evidenceDirectory, now = new Date().toISOString() }) {
-  requireCompleteCatalog(catalog);
-  const claims = profileClaims(catalog, profile, now);
-  requireThat(keys(runtime, ['version', 'artifact_sha256']) && id(runtime.version) && hash(runtime.artifact_sha256), 'Actual native build identity is required.');
-  requireThat(keys(report, ['schema_version', 'execution', 'adapter', 'catalog_sha256', 'profile_sha256', 'harness_commit', 'reviewed_by', 'claims'])
-    && report.schema_version === 1 && report.execution === 'kernel_native'
-    && keys(report.adapter, ['version', 'artifact_sha256'])
-    && typeof report.harness_commit === 'string' && /^[a-f0-9]{40}$/.test(report.harness_commit)
-    && text(report.reviewed_by) && Array.isArray(report.claims), 'A reviewed native execution report is required.');
-  requireThat(report.adapter.version === runtime.version && report.adapter.artifact_sha256 === runtime.artifact_sha256
-    && profile.integration.version === runtime.version, 'Native build mismatch.');
-  requireThat(report.catalog_sha256 === digest(catalog), 'Catalog evidence drift. Requalify this catalog.');
-  requireThat(report.profile_sha256 === digest(profile), 'Profile evidence drift. Requalify these declarations.');
-  requireThat(report.claims.length === claims.size, 'Evidence must cover exactly the declared claims.');
-  const directory = await realpath(evidenceDirectory);
-  const seen = new Set();
-  for (const claim of report.claims) {
-    requireThat(keys(claim, ['key', 'checks']) && claims.has(claim.key) && !seen.has(claim.key)
-      && Array.isArray(claim.checks), 'Unknown or duplicate evidence claim.');
-    seen.add(claim.key);
-    const expected = claims.get(claim.key);
-    requireThat(claim.checks.length === expected.length, 'Missing or extra native checks.');
-    const checks = new Set();
-    for (const check of claim.checks) {
-      requireThat(keys(check, ['id', 'outcome', 'evidence']) && expected.includes(check.id)
-        && !checks.has(check.id) && check.outcome === 'passed', 'Missing, failed, or duplicate native check.');
-      checks.add(check.id);
-      await verifyEvidence(check.evidence, directory);
-    }
-  }
-  return { status: 'qualified', integration: profile.integration, profile_sha256: digest(profile) };
-}
-
-async function main(args) {
-  const catalog = getCheckoutPreflightCatalog();
-  const readJSON = async path => JSON.parse(await readFile(path, 'utf8'));
-  if (args[0] === 'inventory' && (args.length === 1 || (args.length === 2 && args[1] === '--check'))) {
-    const inventory = buildInventory(catalog, await readJSON(new URL('./documented-adapters.json', import.meta.url)));
-    if (args[1] === '--check') {
-      requireThat(digest(inventory) === digest(await readJSON(new URL('./inventory.json', import.meta.url))), 'Inventory drift. Review the catalog and documentation before updating inventory.json.');
-      console.log('Native inventory matches the reviewed catalog and documentation. Runtime support remains unknown.');
-    } else console.log(JSON.stringify(inventory, null, 2));
-    return;
-  }
-  const flags = ['--profile', '--report', '--runtime', '--evidence-dir'];
-  requireThat(args[0] === 'release' && args.length === 9, 'Use inventory [--check] or release --profile JSON --report JSON --runtime JSON --evidence-dir DIRECTORY.');
-  const values = {};
-  for (let index = 1; index < args.length; index += 2) {
-    requireThat(flags.includes(args[index]) && !Object.hasOwn(values, args[index]) && args[index + 1], 'Invalid or duplicate release option.');
-    values[args[index]] = args[index + 1];
-  }
-  const result = await verifyRelease({ catalog, profile: await readJSON(values['--profile']), report: await readJSON(values['--report']),
-    runtime: await readJSON(values['--runtime']), evidenceDirectory: values['--evidence-dir'] });
-  console.log(JSON.stringify(result, null, 2));
-}
-
-if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
-  main(process.argv.slice(2)).catch(() => {
-    // Paths/reports may contain private deployment metadata. Keep failures out of CLI logs.
-    console.error('Native qualification failed. Check the arguments, catalog, build identity, profile, and retained evidence against README.md.');
-    process.exitCode = 1;
-  });
-}

package/examples/preflight/kernel-profile.empty.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 1,
-  "profile_version": "kernel-template-1",
-  "catalog_version": "2026-09-15.1",
-  "integration": {
-    "id": "kernel_native",
-    "version": "example-native-adapter"
-  },
-  "entries": [],
-  "processor_entries": []
-}

package/examples/preflight/mollie-hosted.observations.json

@@ -1,23 +0,0 @@
-{
-  "signals": [
-    {
-      "kind": "document",
-      "url": "https://www.mollie.com/checkout/credit-card/session/synthetic-example",
-      "frame_id": 0,
-      "parent_frame_id": null,
-      "visible": true
-    },
-    {
-      "kind": "script",
-      "url": "https://js.mollie.com/v2/mollie.js",
-      "frame_id": 0,
-      "parent_frame_id": null,
-      "visible": null
-    }
-  ],
-  "observation": {
-    "complete": true,
-    "truncated": false,
-    "reasons": []
-  }
-}

package/examples/preflight/mollie-hosted.result.json

@@ -1,103 +0,0 @@
-{
-  "snapshot": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "signals": [
-      {
-        "rule_id": "mollie-hosted-credit-card",
-        "kind": "document",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": true
-      },
-      {
-        "rule_id": "mollie-components-script",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      },
-      {
-        "rule_id": "mollie-components-v2",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      }
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    }
-  },
-  "result": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "integration": {
-      "id": "kernel_native",
-      "version": "example-native-adapter"
-    },
-    "scenario": "one_time",
-    "scenario_defaulted": false,
-    "psp": "mollie",
-    "flow": "mollie.hosted_components",
-    "mode": "token",
-    "status": "unknown",
-    "support_scope": null,
-    "checkout_flow_status": "identified",
-    "candidates": [
-      {
-        "psp": "mollie",
-        "relevance": "active",
-        "evidence": [
-          {
-            "rule_id": "mollie-hosted-credit-card",
-            "kind": "document",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": true,
-            "origin": "https://www.mollie.com",
-            "path_pattern": "/checkout/credit-card/session/:session"
-          },
-          {
-            "rule_id": "mollie-components-script",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.mollie.com",
-            "path_pattern": "/v2/mollie.js"
-          },
-          {
-            "rule_id": "mollie-components-v2",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.mollie.com",
-            "path_pattern": "^/v2/mollie\\.js$"
-          }
-        ]
-      }
-    ],
-    "reason_codes": [
-      "integration_flow_undeclared"
-    ],
-    "limitations": [
-      "The payment request must match the supported Mollie Components card-token format.",
-      "Authentication and merchant confirmation must finish in the merchant browser.",
-      "Merchant configuration, card eligibility and processor approval still determine whether the purchase succeeds."
-    ],
-    "missing_evidence": [
-      "integration_flow_capability"
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    },
-    "scope": "preflight_hint",
-    "merchant_confirmation_required": true
-  }
-}

package/examples/preflight/stripe-script.direct.result.json

@@ -1,92 +0,0 @@
-{
-  "snapshot": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "signals": [
-      {
-        "rule_id": "stripe-js-v3",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      },
-      {
-        "rule_id": "stripe-js-script",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      }
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    }
-  },
-  "result": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "integration": {
-      "id": "direct_sdk",
-      "version": "bundled"
-    },
-    "scenario": "one_time",
-    "scenario_defaulted": false,
-    "psp": "stripe",
-    "flow": null,
-    "mode": "token",
-    "status": "supported",
-    "support_scope": "processor_integration",
-    "checkout_flow_status": "unknown",
-    "candidates": [
-      {
-        "psp": "stripe",
-        "relevance": "undetermined",
-        "evidence": [
-          {
-            "rule_id": "stripe-js-v3",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.stripe.com",
-            "path_pattern": "/v3/*"
-          },
-          {
-            "rule_id": "stripe-js-script",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.stripe.com",
-            "path_pattern": "^/v3/?$"
-          }
-        ]
-      }
-    ],
-    "reason_codes": [
-      "checkout_flow_unidentified",
-      "processor_supported_by_integration"
-    ],
-    "limitations": [
-      "Processor assets alone do not establish the active card payment flow.",
-      "Tokenization replays a token response; it does not authorize a later PaymentIntent confirm.",
-      "Direct PaymentIntent confirms require a card-bearing template; the intent’s amount is read from Stripe and a hint sent as amount with currency must agree with it.",
-      "Direct SetupIntent confirms require a card-bearing template and save a card without charging it; future charges are merchant-managed.",
-      "Automatic token-to-PaymentIntent or token-to-SetupIntent continuation is unsupported; tokenization does not bind a later intent.",
-      "A token response does not bind a later PaymentIntent confirmation.",
-      "A token response does not bind a later SetupIntent confirmation."
-    ],
-    "missing_evidence": [
-      "active_checkout_flow"
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    },
-    "scope": "preflight_hint",
-    "merchant_confirmation_required": true
-  }
-}

package/examples/preflight/stripe-script.observations.json

@@ -1,16 +0,0 @@
-{
-  "signals": [
-    {
-      "kind": "script",
-      "url": "https://js.stripe.com/v3/?example=discard-this-query",
-      "frame_id": 0,
-      "parent_frame_id": null,
-      "visible": null
-    }
-  ],
-  "observation": {
-    "complete": true,
-    "truncated": false,
-    "reasons": []
-  }
-}

package/examples/preflight/stripe-script.result.json

@@ -1,87 +0,0 @@
-{
-  "snapshot": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "signals": [
-      {
-        "rule_id": "stripe-js-v3",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      },
-      {
-        "rule_id": "stripe-js-script",
-        "kind": "script",
-        "frame_id": 0,
-        "parent_frame_id": null,
-        "visible": null
-      }
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    }
-  },
-  "result": {
-    "schema_version": 1,
-    "catalog_version": "2026-09-15.1",
-    "integration": {
-      "id": "kernel_native",
-      "version": "example-native-adapter"
-    },
-    "scenario": "one_time",
-    "scenario_defaulted": false,
-    "psp": "stripe",
-    "flow": null,
-    "mode": "token",
-    "status": "unknown",
-    "support_scope": null,
-    "checkout_flow_status": "unknown",
-    "candidates": [
-      {
-        "psp": "stripe",
-        "relevance": "undetermined",
-        "evidence": [
-          {
-            "rule_id": "stripe-js-v3",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.stripe.com",
-            "path_pattern": "/v3/*"
-          },
-          {
-            "rule_id": "stripe-js-script",
-            "kind": "script",
-            "frame_id": 0,
-            "parent_frame_id": null,
-            "visible": null,
-            "origin": "https://js.stripe.com",
-            "path_pattern": "^/v3/?$"
-          }
-        ]
-      }
-    ],
-    "reason_codes": [
-      "checkout_flow_unidentified",
-      "integration_processor_undeclared"
-    ],
-    "limitations": [
-      "Processor assets alone do not establish the active card payment flow."
-    ],
-    "missing_evidence": [
-      "active_checkout_flow",
-      "integration_processor_capability"
-    ],
-    "observation": {
-      "complete": true,
-      "truncated": false,
-      "reasons": []
-    },
-    "scope": "preflight_hint",
-    "merchant_confirmation_required": true
-  }
-}