@astrasyncai/verification-gateway 5.14.0 → 5.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +27 -17
  2. package/dist/adapters/express.d.mts +1 -1
  3. package/dist/adapters/express.d.ts +1 -1
  4. package/dist/adapters/express.js +477 -240
  5. package/dist/adapters/express.js.map +1 -1
  6. package/dist/adapters/express.mjs +477 -240
  7. package/dist/adapters/express.mjs.map +1 -1
  8. package/dist/adapters/mcp.d.mts +1 -1
  9. package/dist/adapters/mcp.d.ts +1 -1
  10. package/dist/adapters/mcp.js +20 -6
  11. package/dist/adapters/mcp.js.map +1 -1
  12. package/dist/adapters/mcp.mjs +20 -6
  13. package/dist/adapters/mcp.mjs.map +1 -1
  14. package/dist/adapters/nextjs.d.mts +1 -1
  15. package/dist/adapters/nextjs.d.ts +1 -1
  16. package/dist/adapters/nextjs.js +460 -239
  17. package/dist/adapters/nextjs.js.map +1 -1
  18. package/dist/adapters/nextjs.mjs +460 -239
  19. package/dist/adapters/nextjs.mjs.map +1 -1
  20. package/dist/adapters/sdk.d.mts +18 -10
  21. package/dist/adapters/sdk.d.ts +18 -10
  22. package/dist/adapters/sdk.js +80 -23
  23. package/dist/adapters/sdk.js.map +1 -1
  24. package/dist/adapters/sdk.mjs +80 -23
  25. package/dist/adapters/sdk.mjs.map +1 -1
  26. package/dist/agent/index.js +1 -1
  27. package/dist/agent/index.js.map +1 -1
  28. package/dist/agent/index.mjs +1 -1
  29. package/dist/agent/index.mjs.map +1 -1
  30. package/dist/bin/astrasync-claude-hook.js +55 -11
  31. package/dist/bin/astrasync-codex-hook.js +55 -11
  32. package/dist/bin/astrasync-guard.js +55 -11
  33. package/dist/bin/astrasync.js +288 -33
  34. package/dist/browser/background.js +50 -6
  35. package/dist/browser/background.js.map +1 -1
  36. package/dist/browser/background.mjs +60 -6
  37. package/dist/browser/background.mjs.map +1 -1
  38. package/dist/cli/index.js +1 -1
  39. package/dist/cli/index.js.map +1 -1
  40. package/dist/cli/index.mjs +1 -1
  41. package/dist/cli/index.mjs.map +1 -1
  42. package/dist/codex/index.js +55 -11
  43. package/dist/codex/index.js.map +1 -1
  44. package/dist/codex/index.mjs +65 -11
  45. package/dist/codex/index.mjs.map +1 -1
  46. package/dist/cursor/extension.js +55 -11
  47. package/dist/cursor/extension.js.map +1 -1
  48. package/dist/cursor/extension.mjs +65 -11
  49. package/dist/cursor/extension.mjs.map +1 -1
  50. package/dist/edge-config.d.mts +31 -2
  51. package/dist/edge-config.d.ts +31 -2
  52. package/dist/edge-config.js +35 -5
  53. package/dist/edge-config.js.map +1 -1
  54. package/dist/edge-config.mjs +32 -4
  55. package/dist/edge-config.mjs.map +1 -1
  56. package/dist/edge-core/index.d.mts +11 -2
  57. package/dist/edge-core/index.d.ts +11 -2
  58. package/dist/edge-core/index.js +93 -10
  59. package/dist/edge-core/index.js.map +1 -1
  60. package/dist/edge-core/index.mjs +91 -10
  61. package/dist/edge-core/index.mjs.map +1 -1
  62. package/dist/gateway/gateway.js +50 -6
  63. package/dist/gateway/gateway.js.map +1 -1
  64. package/dist/gateway/gateway.mjs +60 -6
  65. package/dist/gateway/gateway.mjs.map +1 -1
  66. package/dist/git-trigger/git-hooks.d.mts +1 -1
  67. package/dist/git-trigger/git-hooks.d.ts +1 -1
  68. package/dist/index.d.mts +1314 -34
  69. package/dist/index.d.ts +1314 -34
  70. package/dist/index.js +5116 -2612
  71. package/dist/index.js.map +1 -1
  72. package/dist/index.mjs +5063 -2614
  73. package/dist/index.mjs.map +1 -1
  74. package/dist/registration/index.d.mts +28 -2
  75. package/dist/registration/index.d.ts +28 -2
  76. package/dist/registration/index.js +18 -3
  77. package/dist/registration/index.js.map +1 -1
  78. package/dist/registration/index.mjs +15 -2
  79. package/dist/registration/index.mjs.map +1 -1
  80. package/dist/transport/index.d.mts +7 -5
  81. package/dist/transport/index.d.ts +7 -5
  82. package/dist/transport/index.js +61 -5
  83. package/dist/transport/index.js.map +1 -1
  84. package/dist/transport/index.mjs +67 -11
  85. package/dist/transport/index.mjs.map +1 -1
  86. package/dist/{types-C_b4QTyO.d.ts → types-DtJjlW4O.d.ts} +104 -10
  87. package/dist/{types-BCkwBA84.d.mts → types-Dxf9DBpr.d.mts} +106 -12
  88. package/dist/{types-BCkwBA84.d.ts → types-Dxf9DBpr.d.ts} +106 -12
  89. package/dist/{types-DlshIIR-.d.mts → types-Eg6VoBNH.d.mts} +104 -10
  90. package/dist/ui/index.d.mts +1 -1
  91. package/dist/ui/index.d.ts +1 -1
  92. package/dist/verify.d.mts +1 -1
  93. package/dist/verify.d.ts +1 -1
  94. package/dist/verify.js +20 -6
  95. package/dist/verify.js.map +1 -1
  96. package/dist/verify.mjs +20 -6
  97. package/dist/verify.mjs.map +1 -1
  98. package/package.json +1 -1
package/dist/index.d.mts CHANGED
@@ -1,7 +1,8 @@
1
- import { RequestHandler, Request, Response as Response$1 } from 'express';
1
+ import { RequestHandler, Request as Request$1, Response as Response$1 } from 'express';
2
2
  import * as next_server from 'next/server';
3
3
  import { NextRequest } from 'next/server';
4
- import { JWK } from 'jose';
4
+ import { JWK, KeyLike, JWTPayload } from 'jose';
5
+ import { KeyObject } from 'crypto';
5
6
 
6
7
  /**
7
8
  * Maximal metadata capture — the shared, edge-safe sanitiser.
@@ -358,6 +359,30 @@ interface VerifiedAgent {
358
359
  blockchainAnchored: boolean;
359
360
  /** Agent status */
360
361
  status: 'active' | 'inactive' | 'suspended' | 'migrating' | 'terminated' | 'retired';
362
+ /**
363
+ * 5.15.0: the protocol identities the agent declared at registration (its
364
+ * shared signing key, UCP profile, Web Bot Auth key directory, x402 wallet,
365
+ * network agent ids). Bind incoming protocol requests to these — e.g.
366
+ * {@link checkUcpAgentBinding} rejects a `UCP-Agent` profile that isn't the
367
+ * agent's. Identities AstraSync failed to verify are never included.
368
+ */
369
+ protocolIdentities?: AgentProtocolIdentities;
370
+ }
371
+ interface AgentProtocolIdentities {
372
+ /** Shared signing key (AP2 / VI `cnf`, RFC 9421). `thumbprint` = RFC 7638. */
373
+ agentKey?: {
374
+ kid: string | null;
375
+ thumbprint: string | null;
376
+ jwk: Record<string, unknown>;
377
+ };
378
+ ucpProfile?: string;
379
+ webBotAuthKeyDirectory?: string;
380
+ a2aCard?: string;
381
+ x402Wallet?: string;
382
+ visaAgentId?: string;
383
+ mastercardAgentId?: string;
384
+ /** Protocols whose identity AstraSync checked successfully. */
385
+ verified: string[];
361
386
  }
362
387
  /**
363
388
  * Verified developer (KYD) information
@@ -498,6 +523,13 @@ interface GuidanceInfo {
498
523
  interface StepUpApprovalInfo {
499
524
  approvalId: string;
500
525
  pollUrl: string;
526
+ /**
527
+ * 5.15.0: absolute https URL of the buyer-facing approval page. A UCP
528
+ * merchant returns it as `continue_url` with status `requires_escalation`;
529
+ * after the buyer approves, complete the same checkout again and the
530
+ * approval is redeemed once. Absent from backends older than 27.9.
531
+ */
532
+ approvalUrl?: string;
501
533
  expiresAt: string;
502
534
  }
503
535
  /**
@@ -673,19 +705,19 @@ interface VerificationResult {
673
705
  /** Settlement voucher (present on clean merchant-mediated grants with a verified wallet). */
674
706
  settlement?: SettlementArtifact;
675
707
  /**
676
- * 5.3.0 (astra-pay): sanitized first-party settlement outcome. Present
677
- * INSTEAD of `settlement` when the counterparty is an AstraSync-operated
678
- * storefront and the request carried `commercePhase: 'confirm'` — the
679
- * backend redeemed the voucher and executed the charge server-side
680
- * (charge-at-redeem), so there is no artifact to deliver, only the result.
681
- * `no_instrument` = policy passed but the owner has no chargeable
682
- * instrument on file (steer the user to add one via onboarding).
708
+ * Sanitized order outcome for a purchase leg. 5.14.1: AstraSync never
709
+ * charges — every purchase grant records an order and hands YOU the
710
+ * settlement artifact, so the status is `pending_merchant` (with
711
+ * `orderId`): charge the `settlementToken` (card, first-party tenant) or
712
+ * redeem the `settlement` voucher (stablecoin), then `reportSettlement()`.
713
+ * `no_instrument` = policy passed but the owner has nothing usable on file
714
+ * (steer the user to add one via onboarding).
683
715
  */
684
716
  settlementOutcome?: SettlementOutcomeInfo;
685
717
  /**
686
- * 5.5.0 (astra-pay): interim merchant self-settlement token. Present ONLY
687
- * for firstParty merchants opted into settlement_mode='self_settle' on the
688
- * confirm leg — YOUR server charges with this material on the shared Stripe
718
+ * Card settlement token. Present on a card purchase at a first-party
719
+ * storefront (our Stripe tenant) — 5.14.1: always, there is no charge-here
720
+ * mode. YOUR server charges with this material on the shared Stripe
689
721
  * account and reports the outcome via `client.reportSettlement()`.
690
722
  * MERCHANT-ONLY lane: never expose it to the agent plane, never log it,
691
723
  * never echo it back over the bridge handoff (the bridge strips it
@@ -706,6 +738,29 @@ interface VerificationResult {
706
738
  * confirm handoff body wins over `fulfilment.email` (the platform default).
707
739
  */
708
740
  fulfilment?: FulfilmentInfo;
741
+ /**
742
+ * 5.15.0: AP2 v0.2 mandates AstraSync issued for this purchase (merchant
743
+ * lane — never forward to the agent). `mode: 'closed'` on a purchase leg
744
+ * (Checkout + Payment, bound to your `checkoutJwt`), `'open'` on a quote
745
+ * leg for an agent with a registered key. Verify with `verifyAp2Mandate()`
746
+ * against AstraSync's JWKS (`kid`).
747
+ */
748
+ mandates?: AstraSyncMandates;
749
+ /**
750
+ * 5.15.0: a KYAPay `kya+jwt` identity token AstraSync issued for this agent
751
+ * at your endpoint (commerce legs; merchant lane). `hid.email` is where to
752
+ * send the receipt. Verify with `verifyKyaPayTokens()` (issuer = the
753
+ * AstraSync origin, audience = your ASTRAE-id).
754
+ */
755
+ kyaToken?: string;
756
+ /**
757
+ * 5.15.0: A-Comm Evidence Protocol (AEP v1.0.3-rc.2) artifact payloads for
758
+ * your AEP chain — present when your endpoint lists `aep`: `policy` (section 3.4),
759
+ * `delegation` (section 3.9 protocol_metadata: kya_identity, consumer_authorization)
760
+ * and, for AstraSync bridge traffic, platform-countersigned `intents` (section 8.7).
761
+ * Append them with `AepChain` (your Ed25519 key). Merchant lane only.
762
+ */
763
+ aep?: AstraSyncAepEvidence;
709
764
  /** Timestamp of verification */
710
765
  verifiedAt: Date;
711
766
  /** TTL for this result (seconds) */
@@ -857,6 +912,12 @@ interface VerificationRequest {
857
912
  * key charge the owner's card at most once. Omit for raw one-shot confirms.
858
913
  */
859
914
  checkoutSessionId?: string;
915
+ /**
916
+ * 5.15.0: your signed checkout as a compact JWS (AP2 `checkout_jwt`). At a
917
+ * merchant whose endpoint lists `ap2`, a granted purchase leg returns
918
+ * `mandates` — closed AP2 Checkout + Payment mandates bound to it.
919
+ */
920
+ checkoutJwt?: string;
860
921
  /**
861
922
  * 5.3.0 (astra-pay): the checkout's authoritative line items, forwarded on
862
923
  * the confirm leg for the ORDER plane (receipts + digital-goods fulfillment
@@ -1194,7 +1255,7 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
1194
1255
  onDenied?: (result: VerificationResult, req: unknown, res: unknown) => void;
1195
1256
  /** Automatically create sessions and record grant/deny decisions (default: true) */
1196
1257
  recordDecisions?: boolean;
1197
- /** Enable runtime challenge for all verify-access calls (default: true) */
1258
+ /** Ask for a runtime challenge on every verify-access call (default: false — opt-in, round 27.8) */
1198
1259
  enableRuntimeChallenge?: boolean;
1199
1260
  /**
1200
1261
  * Refresh interval (ms) for the remote-fetched route policy. Default:
@@ -1291,7 +1352,7 @@ interface NextJsMiddlewareOptions extends GatewayConfig {
1291
1352
  message?: string;
1292
1353
  allowGuestAccess?: boolean;
1293
1354
  };
1294
- /** Enable runtime challenge for all verify-access calls (default: true) */
1355
+ /** Ask for a runtime challenge on every verify-access call (default: false — opt-in, round 27.8) */
1295
1356
  enableRuntimeChallenge?: boolean;
1296
1357
  /**
1297
1358
  * Emit a fire-and-forget beacon for bot- and agent-shaped traffic that
@@ -1430,6 +1491,40 @@ interface VerificationInterstitialProps {
1430
1491
  }
1431
1492
  /** @deprecated Renamed VerificationInterstitialProps in 4.1.0; alias removed next major. */
1432
1493
  type CommerceShieldProps = VerificationInterstitialProps;
1494
+ /** 5.15.0: AP2 mandates AstraSync issued (see VerificationResult.mandates). */
1495
+ interface AstraSyncMandates {
1496
+ kid: string;
1497
+ mode: 'closed' | 'open';
1498
+ /** Delegate SD-JWT: mandate.checkout.1 / mandate.checkout.open.1. */
1499
+ checkout: string;
1500
+ /** Delegate SD-JWT: mandate.payment.1 / mandate.payment.open.1. */
1501
+ payment?: string;
1502
+ }
1503
+ /** 5.15.0: AstraSync's AEP evidence (see VerificationResult.aep). */
1504
+ interface AstraSyncAepEvidence {
1505
+ spec_version: string;
1506
+ policy: {
1507
+ artifact_type: 'policy';
1508
+ actor_type: 'merchant';
1509
+ payload: Record<string, unknown>;
1510
+ };
1511
+ delegation?: {
1512
+ artifact_type: 'delegation';
1513
+ actor_type: 'agent';
1514
+ actor_id: string;
1515
+ payload: {
1516
+ protocol_metadata: Record<string, unknown>;
1517
+ };
1518
+ };
1519
+ intents?: Array<{
1520
+ artifact_type: 'intent';
1521
+ actor_type: 'agent';
1522
+ actor_id: string;
1523
+ payload: Record<string, unknown>;
1524
+ /** Compact JWS (ES256) over the canonical payload; key in AstraSync's JWKS. */
1525
+ platform_countersignature: string;
1526
+ }>;
1527
+ }
1433
1528
 
1434
1529
  /**
1435
1530
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -1786,7 +1881,7 @@ declare global {
1786
1881
  * Extract extended AstraSync credentials (X-Astra-* headers) from Express request.
1787
1882
  * Returns null if no AstraSync headers are present.
1788
1883
  */
1789
- declare function extractAstraSyncCredentials(req: Request): AstraSyncCredentials | null;
1884
+ declare function extractAstraSyncCredentials(req: Request$1): AstraSyncCredentials | null;
1790
1885
  /**
1791
1886
  * Create Express middleware for agent verification.
1792
1887
  *
@@ -1936,6 +2031,8 @@ declare class VerificationGatewayClient {
1936
2031
  currency?: string;
1937
2032
  checkoutSessionId?: string;
1938
2033
  checkoutItems?: VerificationRequest['checkoutItems'];
2034
+ /** 5.15.0: your signed checkout (AP2 checkout_jwt) — returns `mandates` at AP2 merchants. */
2035
+ checkoutJwt?: string;
1939
2036
  /** 5.12.0: the `att_…` attempt-chain id from the bridge handoff body. */
1940
2037
  attemptId?: string;
1941
2038
  /** 5.6.0: alternate receipt/delivery email (transit-only) — omit to let
@@ -1945,21 +2042,27 @@ declare class VerificationGatewayClient {
1945
2042
  counterpartyType?: string;
1946
2043
  }): Promise<VerificationResult>;
1947
2044
  /**
1948
- * 5.5.0 (astra-pay): report a self-settled charge outcome back to the
1949
- * platform — the other half of the `settlementToken` contract. Call after
1950
- * your PaymentIntent reaches a terminal state so the buyer's dashboard,
1951
- * /orders and the agent's poll surface reconcile. Authenticated with this
1952
- * client's api key (must be the merchant's own). Amounts must match the
1953
- * order EXACTLY (integer minor units) or the report is rejected whole
1954
- * (409 amount_mismatch). Replays of the same terminal state are safe.
2045
+ * Report a settlement outcome back to the platform. 5.14.1: AstraSync never
2046
+ * charges — EVERY merchant settles the orders it is handed (card token,
2047
+ * stablecoin voucher, or a protocol-native credential) and reports here, so
2048
+ * the buyer's dashboard, /orders and the agent's poll surface reconcile.
2049
+ * Identify the order by the confirm's `sessionId` or the `orderId` from
2050
+ * `settlementOutcome`. A settled card charge carries `processorRef` (pi_…);
2051
+ * a settled stablecoin transfer carries `txHash` (+ `chainId`). Amounts must
2052
+ * match the order EXACTLY (integer minor units) or the report is rejected
2053
+ * whole (409 amount_mismatch). Replays of the same terminal state are safe.
1955
2054
  */
1956
2055
  reportSettlement(options: {
1957
- sessionId: string;
2056
+ sessionId?: string;
2057
+ orderId?: string;
1958
2058
  status: 'settled' | 'declined' | 'failed';
1959
2059
  amountMinor: number;
1960
2060
  currency: string;
1961
- /** Stripe PaymentIntent id — REQUIRED when status is 'settled'. */
2061
+ /** Stripe PaymentIntent id (card) — this or `txHash` is required when settled. */
1962
2062
  processorRef?: string;
2063
+ /** Stablecoin transfer transaction hash (0x…, 32 bytes). */
2064
+ txHash?: string;
2065
+ chainId?: number;
1963
2066
  failureCode?: string;
1964
2067
  }): Promise<{
1965
2068
  orderId: string;
@@ -2230,7 +2333,7 @@ interface ParsedRFC9421 {
2230
2333
  */
2231
2334
  declare function parseRFC9421(headers: Record<string, string | string[] | undefined>): ParsedRFC9421 | null;
2232
2335
 
2233
- type RegistryName = 'mastercard' | 'visa' | 'web-bot-auth';
2336
+ type RegistryName = 'mastercard' | 'visa' | 'web-bot-auth' | 'astrasync';
2234
2337
  interface RegistryResolver {
2235
2338
  readonly name: RegistryName;
2236
2339
  resolve(kid: string, context?: ResolveContext): Promise<JWK | null>;
@@ -2971,9 +3074,11 @@ declare function verifyMPP(input: MPPVerifyInput): MPPVerifyResult;
2971
3074
  * superset of x402; this module normalizes x402 output to MPP-shape so
2972
3075
  * downstream pipeline code is uniform.
2973
3076
  *
2974
- * Where x402 lives on the wire:
2975
- * - 402 response body (v2) OR `X-PAYMENT-REQUIRED` header (v1) — PaymentRequired
2976
- * - Request body (v2) OR `X-PAYMENT` header (v1, base64) — PaymentPayload
3077
+ * Where x402 lives on the wire (x402 Foundation transports-v2/http.md):
3078
+ * - v2: `PAYMENT-REQUIRED` header (402, base64 JSON) — PaymentRequired;
3079
+ * `PAYMENT-SIGNATURE` request header (base64 JSON) — PaymentPayload.
3080
+ * Bodies are a server concern; a JSON body is accepted as a fallback.
3081
+ * - v1: `X-PAYMENT-REQUIRED` / `X-PAYMENT` headers (and a 402 JSON body).
2977
3082
  */
2978
3083
  type X402Kind = 'required' | 'payload' | 'error' | 'unknown';
2979
3084
  interface X402RequirementsSummary {
@@ -3209,7 +3314,7 @@ interface CommerceContext {
3209
3314
  };
3210
3315
  paymentToken?: {
3211
3316
  present: boolean;
3212
- type: 'stripe-spt' | 'acp-vt' | 'tempo-tx' | 'other' | null;
3317
+ type: 'stripe-spt' | 'acp-vt' | 'tempo-tx' | 'x402-payload' | 'ap2-payment-mandate' | 'other' | null;
3213
3318
  };
3214
3319
  mppMethodsOffered?: string[];
3215
3320
  constraints?: ConstraintEvalResult;
@@ -3764,7 +3869,7 @@ interface McpMiddlewareOptions extends GatewayConfig {
3764
3869
  /** Skip verification + dedupe entirely. For testing. */
3765
3870
  skip?: boolean;
3766
3871
  /** Custom denied handler. Defaults to a structured JSON-RPC error response. */
3767
- onDenied?: (result: VerificationResult, req: Request, res: Response$1) => void;
3872
+ onDenied?: (result: VerificationResult, req: Request$1, res: Response$1) => void;
3768
3873
  /**
3769
3874
  * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
3770
3875
  * verify-access when it carries a recent marker for the resolved agent.
@@ -3897,7 +4002,7 @@ interface AstraSyncConfig {
3897
4002
  * Multi-protocol declarations the agent participates in.
3898
4003
  * Promoted from `metadata.protocols[]` to a first-class field in agent-registration v1.0.0.
3899
4004
  */
3900
- type AgentProtocol = 'a2a' | 'acp' | 'ap2' | 'ucp' | 'mpp' | 'x402' | 'erc8004' | 'vi' | 'agentpay' | 'tap' | 'other';
4005
+ type AgentProtocol = 'a2a' | 'acp' | 'ap2' | 'ucp' | 'mpp' | 'x402' | 'erc8004' | 'vi' | 'agentpay' | 'tap' | 'webbotauth' | 'other';
3901
4006
  /** PDLSS purpose configuration. */
3902
4007
  interface PDLSSPurpose {
3903
4008
  categories: string[];
@@ -4284,6 +4389,32 @@ declare class RegistrationTimeoutError extends AstraSyncError {
4284
4389
  readonly requestId: string;
4285
4390
  constructor(requestId: string);
4286
4391
  }
4392
+ /**
4393
+ * 5.15.0: thrown by `client.reportSettlement()`. `statusCode` is the HTTP
4394
+ * status (0 = the request never got a response: network error / timeout);
4395
+ * `code` is the platform's error code (e.g. `amount_mismatch`,
4396
+ * `conflicting_report`, `conflicting_reference`, `not_your_merchant`,
4397
+ * `unknown_session`, `unknown_order`, `VALIDATION`, `api_key_expired`).
4398
+ * `retryable` is the safe retry decision — see isRetryableSettlementError.
4399
+ */
4400
+ declare class SettlementReportError extends AstraSyncError {
4401
+ readonly issues?: Array<{
4402
+ field: string;
4403
+ message: string;
4404
+ }>;
4405
+ readonly retryable: boolean;
4406
+ constructor(message: string, statusCode: number, code?: string, issues?: Array<{
4407
+ field: string;
4408
+ message: string;
4409
+ }>);
4410
+ }
4411
+ /**
4412
+ * Retry a settlement report only on a network error / timeout (statusCode
4413
+ * 0), 429 or 5xx. Every 4xx is a decision about this report (wrong amount,
4414
+ * not your order, conflicting outcome …) and replaying it can't succeed.
4415
+ * Replaying the SAME terminal outcome is always safe (200 alreadySettled).
4416
+ */
4417
+ declare function isRetryableSettlementError(err: unknown): boolean;
4287
4418
 
4288
4419
  /**
4289
4420
  * Guidance envelope for credentials-required cases.
@@ -4605,6 +4736,28 @@ declare namespace index {
4605
4736
  export { index_AgentClient as AgentClient, index_AstraSyncSdkError as AstraSyncSdkError, index_ChallengeHandler as ChallengeHandler, index_OwnershipMismatchError as OwnershipMismatchError, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
4606
4737
  }
4607
4738
 
4739
+ /**
4740
+ * Route pattern compiler shared by every matcher of endpoint route policy:
4741
+ * the express and Next.js middleware, the edge config and the AstraSync
4742
+ * bridge (round 27.9 — they each had their own copy, and none understood
4743
+ * path parameters).
4744
+ *
4745
+ * Pattern syntax:
4746
+ * - `*` any characters, including `/` (unchanged since v1)
4747
+ * - `:name` exactly one path segment (no `/`), e.g.
4748
+ * `/ucp/v1/checkout-sessions/:id/complete`
4749
+ * - anything else is literal — `.`, `?`, `+`, `(`… are escaped (they used
4750
+ * to be live regex syntax, so `/robots.txt` also matched `/robotsXtxt`).
4751
+ * Anchored `^…$`. Case-sensitive unless `caseInsensitive` is set.
4752
+ */
4753
+ declare function routePatternToRegExp(pattern: string, opts?: {
4754
+ caseInsensitive?: boolean;
4755
+ }): RegExp | null;
4756
+ /** True when `path` matches `pattern` (see routePatternToRegExp). */
4757
+ declare function matchRoutePattern(pattern: string, path: string, opts?: {
4758
+ caseInsensitive?: boolean;
4759
+ }): boolean;
4760
+
4608
4761
  /**
4609
4762
  * Edge verification config — the per-endpoint policy the Trusted Agent
4610
4763
  * Gateway edge adapters (e.g. `@astrasyncai/adapter-lambda`) fetch from the
@@ -4704,6 +4857,13 @@ interface EdgeConfig {
4704
4857
  * endpoint owner explicitly configures this.
4705
4858
  */
4706
4859
  queryValueAllowlist?: string[];
4860
+ /**
4861
+ * 5.15.0: minimum TLS version for AGENT traffic (UCP 2026-08-25 requires
4862
+ * TLS 1.3). Read from CloudFront-Viewer-TLS; follows the path's mode —
4863
+ * enforce answers 426 Upgrade Required, observe only logs. Human browsers
4864
+ * are never gated, and an unknown version never blocks. ABSENT = no check.
4865
+ */
4866
+ minTls?: '1.2' | '1.3';
4707
4867
  /**
4708
4868
  * 4.5.0: the EFFECTIVE failure posture is derived from the effective
4709
4869
  * mode — fail posture follows success posture. Observe fails open
@@ -4935,7 +5095,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
4935
5095
  * silently (never throwing), so this is a no-op there — which is correct:
4936
5096
  * in a browser the page's real UA is the honest identity.
4937
5097
  */
4938
- declare const SDK_USER_AGENT = "astrasync-sdk/5.14.0";
5098
+ declare const SDK_USER_AGENT = "astrasync-sdk/5.15.0";
4939
5099
  declare const sdkFetch: typeof fetch;
4940
5100
 
4941
5101
  interface LocalPolicy {
@@ -5053,6 +5213,1126 @@ declare function parseYaml(yamlContent: string): ParseResult;
5053
5213
  * is fine — bumping both in the release-ceremony commit keeps them
5054
5214
  * lockstep.
5055
5215
  */
5056
- declare const SDK_VERSION = "5.14.0";
5216
+ declare const SDK_VERSION = "5.15.0";
5217
+
5218
+ /**
5219
+ * 5.15.0 — the `UCP-Agent` request header (UCP 2026-08-25): an RFC 8941
5220
+ * structured-field dictionary whose `profile` member is the URL of the calling
5221
+ * platform's UCP profile, e.g.
5222
+ *
5223
+ * UCP-Agent: profile="https://agent.example/.well-known/ucp"
5224
+ *
5225
+ * A UCP merchant behind AstraSync binds it to the verified agent: the profile
5226
+ * must be the one the agent registered (gadget D, round 27.9). Without the
5227
+ * binding, any caller could present a verified agent's id with someone
5228
+ * else's profile and capabilities.
5229
+ */
5230
+
5231
+ /** The `profile` URL from a `UCP-Agent` header, or null when absent/malformed. */
5232
+ declare function parseUcpAgentHeader(header: string | string[] | null | undefined): string | null;
5233
+ type UcpAgentBinding = {
5234
+ ok: true;
5235
+ profile: string | null;
5236
+ } | {
5237
+ ok: false;
5238
+ code: 'invalid_ucp_agent' | 'ucp_agent_mismatch';
5239
+ message: string;
5240
+ };
5241
+ /**
5242
+ * Check a request's `UCP-Agent` header against the verified agent's registered
5243
+ * UCP profile. Rules:
5244
+ * - header absent and agent has no registered profile → ok (not a UCP caller)
5245
+ * - header absent but agent registered one → ok, profile = the registered one
5246
+ * - header present but malformed / not https → `invalid_ucp_agent`
5247
+ * - header present and agent registered a DIFFERENT profile → `ucp_agent_mismatch`
5248
+ * - header present, agent registered none → `ucp_agent_mismatch` (unbound
5249
+ * profiles are refused; register it in the agent's protocol step)
5250
+ */
5251
+ declare function checkUcpAgentBinding(header: string | string[] | null | undefined, identities: AgentProtocolIdentities | undefined): UcpAgentBinding;
5252
+
5253
+ /**
5254
+ * 5.15.0 — the business profile at `/.well-known/ucp` (UCP 2026-08-25,
5255
+ * docs/specification/overview). `ucp.version`, `ucp.services` and
5256
+ * `ucp.payment_handlers` are required even when empty; signing keys are the
5257
+ * TOP-LEVEL `keys[]` (a JWK Set). Served over HTTPS, never redirected, with
5258
+ * `Cache-Control: public, max-age >= 60`.
5259
+ */
5260
+
5261
+ declare const UCP_VERSION = "2026-08-25";
5262
+ interface UcpServiceEntry {
5263
+ version: string;
5264
+ spec: string;
5265
+ transport: 'rest' | 'mcp' | 'a2a' | 'embedded';
5266
+ endpoint: string;
5267
+ schema?: string;
5268
+ }
5269
+ interface UcpCapabilityEntry {
5270
+ version: string;
5271
+ spec: string;
5272
+ schema: string;
5273
+ extends?: string;
5274
+ config?: Record<string, unknown>;
5275
+ }
5276
+ interface UcpPaymentHandlerEntry {
5277
+ id: string;
5278
+ version: string;
5279
+ spec: string;
5280
+ schema: string;
5281
+ available_instruments?: Array<{
5282
+ type: string;
5283
+ constraints?: Record<string, unknown>;
5284
+ }>;
5285
+ config?: Record<string, unknown>;
5286
+ }
5287
+ interface UcpProfile {
5288
+ ucp: {
5289
+ version: string;
5290
+ services: Record<string, UcpServiceEntry[]>;
5291
+ capabilities?: Record<string, UcpCapabilityEntry[]>;
5292
+ payment_handlers: Record<string, UcpPaymentHandlerEntry[]>;
5293
+ };
5294
+ keys?: JWK[];
5295
+ }
5296
+ /** AstraSync payment handler declarations (spec pages hosted on astrasync.ai). */
5297
+ declare function astrasyncPaymentHandlers(handlers: string[], specBase?: string): Record<string, UcpPaymentHandlerEntry[]>;
5298
+ interface BuildProfileOptions {
5299
+ /** REST base, e.g. https://shop.example/ucp/v1 */
5300
+ endpoint: string;
5301
+ /** Public signing keys (JWKs with kid). */
5302
+ keys?: JWK[];
5303
+ /** Payment handler ids you accept (see the endpoint's paymentHandlers). */
5304
+ paymentHandlers?: string[];
5305
+ /** Accept AP2 mandates (adds dev.ucp.common.payment.ap2_mandate). */
5306
+ ap2Mandates?: boolean;
5307
+ /** Extra capabilities beyond checkout (e.g. order). */
5308
+ capabilities?: Record<string, UcpCapabilityEntry[]>;
5309
+ }
5310
+ declare function buildUcpProfile(opts: BuildProfileOptions): UcpProfile;
5311
+ /** A fetch-style handler for GET /.well-known/ucp. */
5312
+ declare function ucpProfileHandler(profile: UcpProfile, maxAgeSec?: number): () => Promise<Response>;
5313
+
5314
+ type UcpDiscoveryError = {
5315
+ ok: false;
5316
+ status: 400 | 422 | 424;
5317
+ code: 'invalid_profile_url' | 'profile_unreachable' | 'profile_malformed' | 'version_unsupported';
5318
+ content: string;
5319
+ };
5320
+ type UcpProfileResult = {
5321
+ ok: true;
5322
+ profile: UcpProfile;
5323
+ } | UcpDiscoveryError;
5324
+ /** True for loopback / private / link-local / CGNAT / multicast / reserved addresses. */
5325
+ declare function isSpecialUseIp(ip: string): boolean;
5326
+ interface FetchProfileOptions {
5327
+ timeoutMs?: number;
5328
+ fetch?: typeof fetch;
5329
+ /** Skip DNS resolution checks (tests only). */
5330
+ skipDnsCheck?: boolean;
5331
+ /** Bypass the cache (unknown signing key → refresh once per TTL). */
5332
+ fresh?: boolean;
5333
+ }
5334
+ declare function fetchUcpProfile(url: string, opts?: FetchProfileOptions): Promise<UcpProfileResult>;
5335
+ interface NegotiationResult {
5336
+ ok: boolean;
5337
+ version: string;
5338
+ /** Capability names both sides support (extensions only with their base). */
5339
+ capabilities: Record<string, UcpCapabilityEntry[]>;
5340
+ error?: UcpDiscoveryError;
5341
+ }
5342
+ /**
5343
+ * Intersect the business's and platform's profiles. `supportedVersions` is
5344
+ * every protocol version the business still serves (current first).
5345
+ */
5346
+ declare function negotiateUcp(business: UcpProfile, platform: UcpProfile, supportedVersions?: string[]): NegotiationResult;
5347
+
5348
+ /**
5349
+ * 5.15.0 — UCP `messages[]` and response envelopes (UCP 2026-08-25
5350
+ * shopping/checkout). Error severities: recoverable, requires_buyer_input,
5351
+ * requires_buyer_review, unrecoverable — `requires_*` contribute to
5352
+ * `status: 'requires_escalation'`, which MUST carry an absolute https
5353
+ * `continue_url`.
5354
+ */
5355
+ type UcpSeverity = 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review' | 'unrecoverable';
5356
+ type UcpMessage = {
5357
+ type: 'error';
5358
+ code: string;
5359
+ content: string;
5360
+ severity: UcpSeverity;
5361
+ path?: string;
5362
+ content_type?: 'plain' | 'markdown';
5363
+ } | {
5364
+ type: 'warning';
5365
+ code: string;
5366
+ content: string;
5367
+ presentation?: 'notice' | 'disclosure';
5368
+ url?: string;
5369
+ } | {
5370
+ type: 'info';
5371
+ content: string;
5372
+ code?: string;
5373
+ };
5374
+ declare const ucpError: (code: string, content: string, severity?: UcpSeverity, path?: string) => UcpMessage;
5375
+ /**
5376
+ * The AstraSync step-up → UCP escalation: the buyer approves on AstraSync's
5377
+ * approval page (`approvalUrl`), then the platform completes again.
5378
+ */
5379
+ declare function ucpEscalation(approvalUrl: string, content?: string): {
5380
+ status: "requires_escalation";
5381
+ continue_url: string;
5382
+ messages: UcpMessage[];
5383
+ };
5384
+ /** A failed-operation envelope: `{ ucp: { version, status: 'error' }, messages, continue_url? }`. */
5385
+ declare function ucpFailure(version: string, messages: UcpMessage[], continueUrl?: string): {
5386
+ continue_url?: string | undefined;
5387
+ ucp: {
5388
+ version: string;
5389
+ status: "error";
5390
+ };
5391
+ messages: UcpMessage[];
5392
+ };
5393
+
5394
+ /**
5395
+ * 5.15.0 — UCP message signatures (UCP 2026-08-25 signatures.md): RFC 9421
5396
+ * with
5397
+ * covered: "@method" "@authority" "@path" (+ "@query" when present)
5398
+ * + "ucp-agent" / "signature-agent" when those headers are sent
5399
+ * + "idempotency-key" on POST / PUT / PATCH / DELETE
5400
+ * + "content-digest" "content-type" when there is a body
5401
+ * params: keyid (created optional; `alg` NOT included — the JWK's
5402
+ * kty/crv decides). ECDSA signatures are raw r||s.
5403
+ * `keyid` resolves to a `kid` in the signer's profile `keys[]` (keys with
5404
+ * `use: 'enc'` are skipped); an unknown kid forces one profile refresh.
5405
+ * Responses sign ("@status" "content-digest" "content-type").
5406
+ * Errors: signature_missing / signature_invalid / key_not_found (401),
5407
+ * digest_mismatch / algorithm_unsupported (400).
5408
+ */
5409
+
5410
+ interface UcpSignableRequest {
5411
+ method: string;
5412
+ url: string;
5413
+ headers: Record<string, string>;
5414
+ body?: string;
5415
+ }
5416
+ /** The components UCP requires for this request. */
5417
+ declare function ucpRequiredComponents(req: UcpSignableRequest): string[];
5418
+ /** Sign a UCP request (platform → business, or business → platform webhook). */
5419
+ declare function signUcpRequest(req: UcpSignableRequest, key: {
5420
+ privateKey: KeyObject | string;
5421
+ keyId: string;
5422
+ }): Promise<Record<string, string>>;
5423
+ /** Sign a UCP response: ("@status" "content-digest" "content-type"). */
5424
+ declare function signUcpResponse(res: {
5425
+ status: number;
5426
+ headers: Record<string, string>;
5427
+ body: string;
5428
+ }, key: {
5429
+ privateKey: KeyObject | string;
5430
+ keyId: string;
5431
+ }): Promise<Record<string, string>>;
5432
+ type UcpSignatureResult = {
5433
+ ok: true;
5434
+ keyId: string;
5435
+ } | {
5436
+ ok: false;
5437
+ status: 400 | 401;
5438
+ code: 'signature_missing' | 'signature_invalid' | 'key_not_found' | 'digest_mismatch' | 'algorithm_unsupported';
5439
+ content: string;
5440
+ };
5441
+ /**
5442
+ * Verify a signed UCP request against the signer's profile keys.
5443
+ * `getKeys(fresh)` returns the signer profile's `keys[]` (refreshed once on
5444
+ * an unknown kid).
5445
+ */
5446
+ declare function verifyUcpRequest(req: UcpSignableRequest, getKeys: (fresh: boolean) => Promise<JWK[]>): Promise<UcpSignatureResult>;
5447
+ interface UcpWebhookOptions {
5448
+ url: string;
5449
+ /** The order event body (JSON). */
5450
+ body: unknown;
5451
+ privateKey: KeyObject | string;
5452
+ keyId: string;
5453
+ /** Your business profile URL (sent as UCP-Agent). */
5454
+ businessProfileUrl: string;
5455
+ attempts?: number;
5456
+ fetch?: typeof fetch;
5457
+ }
5458
+ /** Send a signed UCP order webhook with retry/backoff on network errors, 429 and 5xx. */
5459
+ declare function sendUcpWebhook(opts: UcpWebhookOptions): Promise<{
5460
+ ok: boolean;
5461
+ status: number;
5462
+ attempts: number;
5463
+ }>;
5464
+
5465
+ interface IdempotencyRecord {
5466
+ state: 'in_progress' | 'done';
5467
+ requestHash: string;
5468
+ status?: number;
5469
+ headers?: Record<string, string>;
5470
+ body?: string;
5471
+ }
5472
+ interface IdempotencyStore {
5473
+ get(key: string): Promise<IdempotencyRecord | null>;
5474
+ /** Store only when absent (the lock). Returns false when the key exists. */
5475
+ create(key: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
5476
+ set(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>;
5477
+ delete(key: string): Promise<void>;
5478
+ }
5479
+ /** In-process store (single instance / tests). */
5480
+ declare class MemoryIdempotencyStore implements IdempotencyStore {
5481
+ private now;
5482
+ private map;
5483
+ constructor(now?: () => number);
5484
+ private live;
5485
+ get(key: string): Promise<IdempotencyRecord | null>;
5486
+ create(key: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
5487
+ set(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>;
5488
+ delete(key: string): Promise<void>;
5489
+ }
5490
+ /** The subset of a Redis client this store needs (ioredis / node-redis v4 compatible). */
5491
+ interface RedisLike {
5492
+ get(key: string): Promise<string | null>;
5493
+ set(key: string, value: string, ...args: Array<string | number>): Promise<unknown>;
5494
+ del(key: string): Promise<unknown>;
5495
+ }
5496
+ /** Shared store across instances. */
5497
+ declare class RedisIdempotencyStore implements IdempotencyStore {
5498
+ private redis;
5499
+ private prefix;
5500
+ constructor(redis: RedisLike, prefix?: string);
5501
+ get(key: string): Promise<IdempotencyRecord | null>;
5502
+ create(key: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
5503
+ set(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>;
5504
+ delete(key: string): Promise<void>;
5505
+ }
5506
+ interface IdempotencyOptions {
5507
+ store: IdempotencyStore;
5508
+ /** 'ucp' (default) or 'acp' — see the module comment. */
5509
+ profile?: 'ucp' | 'acp';
5510
+ /** Default 24 h. */
5511
+ ttlMs?: number;
5512
+ /** Default `idempotency-key`. */
5513
+ header?: string;
5514
+ /** Methods covered. Default POST, PUT, PATCH, DELETE. */
5515
+ methods?: string[];
5516
+ /** Require the header on covered methods (400 when missing). Default false. */
5517
+ required?: boolean;
5518
+ }
5519
+ declare const DEFAULT_IDEMPOTENCY_TTL_MS: number;
5520
+ type IdempotencyDecision = {
5521
+ kind: 'skip';
5522
+ } | {
5523
+ kind: 'proceed';
5524
+ storeKey: string;
5525
+ requestHash: string;
5526
+ } | {
5527
+ kind: 'replay';
5528
+ status: number;
5529
+ headers: Record<string, string>;
5530
+ body: string;
5531
+ } | {
5532
+ kind: 'reject';
5533
+ status: number;
5534
+ code: string;
5535
+ message: string;
5536
+ retryAfterSec?: number;
5537
+ };
5538
+ /**
5539
+ * SHA-256 of the request body: raw bytes for 'ucp', canonical JSON (when it
5540
+ * parses) for 'acp'.
5541
+ */
5542
+ declare function requestFingerprint(body: string, profile?: 'ucp' | 'acp'): string;
5543
+ /** Platform-neutral core: decide before handling a request. */
5544
+ declare function beginIdempotent(opts: IdempotencyOptions, req: {
5545
+ method: string;
5546
+ path: string;
5547
+ body: string;
5548
+ key: string | undefined;
5549
+ auth?: string;
5550
+ }): Promise<IdempotencyDecision>;
5551
+ /** Platform-neutral core: record the outcome after handling. */
5552
+ declare function finishIdempotent(opts: IdempotencyOptions, decision: Extract<IdempotencyDecision, {
5553
+ kind: 'proceed';
5554
+ }>, response: {
5555
+ status: number;
5556
+ headers: Record<string, string>;
5557
+ body: string;
5558
+ }): Promise<void>;
5559
+ interface ExpressReq {
5560
+ method: string;
5561
+ originalUrl?: string;
5562
+ url: string;
5563
+ body?: unknown;
5564
+ headers: Record<string, string | string[] | undefined>;
5565
+ }
5566
+ interface ExpressRes {
5567
+ statusCode: number;
5568
+ status(code: number): ExpressRes;
5569
+ setHeader(name: string, value: string): unknown;
5570
+ getHeader(name: string): unknown;
5571
+ send(body: unknown): unknown;
5572
+ json(body: unknown): unknown;
5573
+ end(...args: unknown[]): unknown;
5574
+ }
5575
+ /** Express middleware. Mount after body parsing, before the checkout routes. */
5576
+ declare function idempotencyMiddleware(opts: IdempotencyOptions): (req: ExpressReq, res: ExpressRes, next: (err?: unknown) => void) => Promise<void>;
5577
+ /** Next.js / fetch-style route handler wrapper. */
5578
+ declare function withIdempotency(opts: IdempotencyOptions, handler: (req: Request) => Promise<Response>): (req: Request) => Promise<Response>;
5579
+
5580
+ interface CatalogItem {
5581
+ id: string;
5582
+ title: string;
5583
+ /** Minor units. */
5584
+ price: number;
5585
+ }
5586
+ interface CheckoutLine {
5587
+ id: string;
5588
+ item: CatalogItem;
5589
+ quantity: number;
5590
+ totals: Array<{
5591
+ type: string;
5592
+ amount: number;
5593
+ }>;
5594
+ }
5595
+ interface CheckoutSession {
5596
+ id: string;
5597
+ status: 'incomplete' | 'requires_escalation' | 'ready_for_complete' | 'complete_in_progress' | 'completed' | 'canceled';
5598
+ currency: string;
5599
+ line_items: CheckoutLine[];
5600
+ totals: Array<{
5601
+ type: string;
5602
+ amount: number;
5603
+ }>;
5604
+ buyer?: Record<string, unknown>;
5605
+ messages?: UcpMessage[];
5606
+ continue_url?: string;
5607
+ order?: {
5608
+ id: string;
5609
+ permalink_url?: string;
5610
+ };
5611
+ /** Kit state (never serialised). */
5612
+ _platformProfile?: string;
5613
+ _ap2?: boolean;
5614
+ _platformKeys?: JWK[];
5615
+ _astraOrderId?: string;
5616
+ _attemptId?: string;
5617
+ /** The AstraSync cart id the platform sent (X-Astra-Checkout-Session). */
5618
+ _astraCheckoutSessionId?: string;
5619
+ /** The attached checkout JWS behind the last merchant_authorization sent. */
5620
+ _checkoutJwt?: string;
5621
+ }
5622
+ interface CheckoutStore {
5623
+ get(id: string): Promise<CheckoutSession | null>;
5624
+ put(s: CheckoutSession): Promise<void>;
5625
+ }
5626
+ declare class MemoryCheckoutStore implements CheckoutStore {
5627
+ private m;
5628
+ get(id: string): Promise<CheckoutSession | null>;
5629
+ put(s: CheckoutSession): Promise<void>;
5630
+ }
5631
+ type SettleResult = {
5632
+ status: 'settled';
5633
+ processorRef?: string;
5634
+ txHash?: string;
5635
+ chainId?: number;
5636
+ } | {
5637
+ status: 'pending';
5638
+ } | {
5639
+ status: 'failed';
5640
+ failureCode?: string;
5641
+ };
5642
+ interface UcpCheckoutKitOptions {
5643
+ /** Profile inputs (endpoint, keys, paymentHandlers, ap2Mandates). */
5644
+ profile: BuildProfileOptions;
5645
+ currency: string;
5646
+ /** Your catalog: the item, or null when unknown. */
5647
+ catalog: (itemId: string) => Promise<CatalogItem | null>;
5648
+ /** AstraSync verification of the purchase (e.g. `client.confirmCheckout`). */
5649
+ verifyPurchase: (ctx: {
5650
+ session: CheckoutSession;
5651
+ /**
5652
+ * Pass as `checkoutSessionId` to AstraSync: the platform's cart id when
5653
+ * it sent one (an owner approval is bound to that cart), else this
5654
+ * checkout's id.
5655
+ */
5656
+ checkoutSessionId: string;
5657
+ astraId?: string;
5658
+ attemptId?: string;
5659
+ checkoutJwt?: string;
5660
+ valueMajor: number;
5661
+ }) => Promise<VerificationResult>;
5662
+ /** Charge / redeem with YOUR processor using the artifact AstraSync handed you. */
5663
+ settle: (ctx: {
5664
+ session: CheckoutSession;
5665
+ result: VerificationResult;
5666
+ instrument?: Record<string, unknown>;
5667
+ }) => Promise<SettleResult>;
5668
+ /** Report the outcome to AstraSync (e.g. `client.reportSettlement`). */
5669
+ reportSettlement?: (r: Parameters<VerificationGatewayClient['reportSettlement']>[0]) => Promise<unknown>;
5670
+ /** Create your order once paid. */
5671
+ fulfil: (ctx: {
5672
+ session: CheckoutSession;
5673
+ result: VerificationResult;
5674
+ }) => Promise<{
5675
+ id: string;
5676
+ permalink_url?: string;
5677
+ }>;
5678
+ /** Merchant key for ap2.merchant_authorization (when ap2Mandates). */
5679
+ signingKey?: {
5680
+ privateKey: KeyLike | KeyObject;
5681
+ kid: string;
5682
+ };
5683
+ /** Resolve an AP2 mandate signer key by kid (default: the platform profile keys). */
5684
+ mandateKey?: (kid: string | undefined, session: CheckoutSession) => Promise<JWK | null>;
5685
+ store?: CheckoutStore;
5686
+ idempotencyStore?: IdempotencyStore;
5687
+ /** Require RFC 9421 signatures on platform requests. Default false. */
5688
+ requireSignedRequests?: boolean;
5689
+ /** Where to send a buyer when nothing better exists (continue_url). */
5690
+ fallbackContinueUrl?: string;
5691
+ /** Profile fetch override (tests). */
5692
+ fetchProfile?: (url: string, fresh: boolean) => Promise<UcpProfile | UcpDiscoveryError>;
5693
+ }
5694
+ declare function createUcpCheckoutKit(opts: UcpCheckoutKitOptions): {
5695
+ handle: (req: Request) => Promise<Response>;
5696
+ profile: UcpProfile;
5697
+ profileHandler: () => Response;
5698
+ };
5699
+
5700
+ /** RFC 8785-style canonical JSON (sorted keys, no whitespace). */
5701
+ declare function canonicalJson(value: unknown): string;
5702
+
5703
+ /**
5704
+ * 5.15.0 — x402 v2 (x402 Foundation, specs/transports-v2/http.md) helpers for
5705
+ * a MERCHANT. The merchant's own facilitator verifies and settles; AstraSync
5706
+ * never facilitates or touches the funds. All protocol data travels in
5707
+ * headers as standard base64 JSON:
5708
+ * PAYMENT-REQUIRED (server → client, with HTTP 402) PaymentRequired
5709
+ * PAYMENT-SIGNATURE (client → server) PaymentPayload
5710
+ * PAYMENT-RESPONSE (server → client) SettlementResponse
5711
+ */
5712
+ interface X402ResourceInfo {
5713
+ url: string;
5714
+ description?: string;
5715
+ mimeType?: string;
5716
+ /** ≤ 32 characters. */
5717
+ serviceName?: string;
5718
+ /** ≤ 5 entries. */
5719
+ tags?: string[];
5720
+ iconUrl?: string;
5721
+ }
5722
+ interface X402PaymentRequirements {
5723
+ scheme: string;
5724
+ /** CAIP-2, e.g. `eip155:8453`. */
5725
+ network: string;
5726
+ /** Atomic token units, as a string. */
5727
+ amount: string;
5728
+ /** Token contract address, or ISO 4217 code for fiat. */
5729
+ asset: string;
5730
+ payTo: string;
5731
+ maxTimeoutSeconds: number;
5732
+ extra?: Record<string, unknown>;
5733
+ }
5734
+ interface X402PaymentRequired {
5735
+ x402Version: 2;
5736
+ error?: string;
5737
+ resource: X402ResourceInfo;
5738
+ accepts: X402PaymentRequirements[];
5739
+ extensions?: Record<string, {
5740
+ info: unknown;
5741
+ schema?: unknown;
5742
+ }>;
5743
+ }
5744
+ interface X402PaymentPayload {
5745
+ x402Version: number;
5746
+ resource?: X402ResourceInfo;
5747
+ accepted: X402PaymentRequirements;
5748
+ payload: Record<string, unknown>;
5749
+ extensions?: Record<string, unknown>;
5750
+ }
5751
+ interface X402SettlementResponse {
5752
+ success: boolean;
5753
+ errorReason?: string;
5754
+ payer?: string;
5755
+ /** Empty string when settlement failed. */
5756
+ transaction: string;
5757
+ network: string;
5758
+ amount?: string;
5759
+ extensions?: Record<string, unknown>;
5760
+ }
5761
+ /** A 402 answer: status, the PAYMENT-REQUIRED header, and an empty JSON body. */
5762
+ declare function buildX402Challenge(input: Omit<X402PaymentRequired, 'x402Version'>): {
5763
+ status: 402;
5764
+ headers: Record<string, string>;
5765
+ body: Record<string, never>;
5766
+ };
5767
+ /** Decode the client's PAYMENT-SIGNATURE header (null when absent/malformed). */
5768
+ declare function parseX402Payment(header: string | null | undefined): X402PaymentPayload | null;
5769
+ /** Decode a PAYMENT-REQUIRED header (agent side / tests). */
5770
+ declare function parseX402Challenge(header: string | null | undefined): X402PaymentRequired | null;
5771
+ /** The PAYMENT-RESPONSE header value for your facilitator's settlement result. */
5772
+ declare function encodeX402SettlementResponse(r: X402SettlementResponse): string;
5773
+ /**
5774
+ * The chosen requirement must be one you offered (scheme, network, asset,
5775
+ * payTo, amount) — check before handing the payload to your facilitator.
5776
+ */
5777
+ declare function x402PaymentMatchesOffer(payment: X402PaymentPayload, offered: X402PaymentRequirements[]): boolean;
5778
+
5779
+ interface MppChallenge {
5780
+ id: string;
5781
+ realm: string;
5782
+ /** Lowercase ASCII, e.g. `stripe`, `tempo`. */
5783
+ method: string;
5784
+ /** e.g. `charge`, `session`, `subscription`. */
5785
+ intent: string;
5786
+ /** base64url (no padding) of the method request JSON. */
5787
+ request: string;
5788
+ expires?: string;
5789
+ digest?: string;
5790
+ description?: string;
5791
+ opaque?: string;
5792
+ header?: 'Payment-Authorization';
5793
+ }
5794
+ interface MppCredential {
5795
+ challenge: MppChallenge;
5796
+ source?: string;
5797
+ payload: Record<string, unknown>;
5798
+ }
5799
+ interface MppReceipt {
5800
+ status: 'success';
5801
+ method: string;
5802
+ timestamp: string;
5803
+ reference: string;
5804
+ }
5805
+ /**
5806
+ * One `WWW-Authenticate: Payment …` value. Offer several methods by sending
5807
+ * one header per method. `request` is the method's request object
5808
+ * (e.g. stripe: `{ amount: '5000', currency: 'usd', … }`).
5809
+ */
5810
+ declare function buildMppChallenge(input: Omit<MppChallenge, 'id' | 'request'> & {
5811
+ request: Record<string, unknown>;
5812
+ }, hmacSecret: string): {
5813
+ challenge: MppChallenge;
5814
+ header: string;
5815
+ };
5816
+ /** Decode `Authorization: Payment <…>` (or Payment-Authorization). */
5817
+ declare function parseMppCredential(header: string | null | undefined): MppCredential | null;
5818
+ /** True when the echoed challenge is one this server issued (and isn't expired). */
5819
+ declare function verifyMppChallenge(challenge: MppChallenge, hmacSecret: string, now?: Date): boolean;
5820
+ /** The decoded method request from a challenge. */
5821
+ declare function decodeMppRequest(challenge: MppChallenge): Record<string, unknown> | null;
5822
+ /** `Payment-Receipt` header value — 2xx responses only. */
5823
+ declare function encodeMppReceipt(r: MppReceipt): string;
5824
+
5825
+ /**
5826
+ * 5.15.0 — KYAPay token verification for a seller
5827
+ * (draft-skyfire-oauth-kyapay-token; header `KYAPay-Token`, comma-separated
5828
+ * JWTs). AstraSync's use is IDENTITY: by default only `kya+jwt` tokens are
5829
+ * accepted. `pay+jwt` / `kya-pay+jwt` carry payment value (settled by the
5830
+ * issuer, never AstraSync) and are refused unless you opt in.
5831
+ *
5832
+ * Validation per the draft: signature by the issuer's key (`kid`, JWKS at
5833
+ * `{iss}/.well-known/jwks.json`), `iss`, `exp`/`iat` with 30 s skew, `jti` a
5834
+ * UUID, `aud` = you, `env` when configured; `alg: none` refused. Issuer
5835
+ * values differ between Skyfire's docs and examples, so `issuer` is
5836
+ * configuration (production `https://app.skyfire.xyz` per docs.skyfire.xyz).
5837
+ * When the token carries `cnf`, the request must also be RFC 9421-signed by
5838
+ * that key — returned as `requiresSignatureKey` for the caller to enforce.
5839
+ */
5840
+
5841
+ type KyaPayTokenType = 'kya+jwt' | 'pay+jwt' | 'kya-pay+jwt';
5842
+ interface KyaPayVerifyOptions {
5843
+ issuer: string;
5844
+ /** Your seller id (the token's `aud`). */
5845
+ audience: string;
5846
+ /** Defaults to `${issuer}/.well-known/jwks.json`. */
5847
+ jwksUrl?: string;
5848
+ /** Pinned issuer keys instead of fetching the JWKS. */
5849
+ keys?: JWK[];
5850
+ /** Default ['kya+jwt'] — identity only. */
5851
+ acceptTypes?: KyaPayTokenType[];
5852
+ env?: 'production' | 'sandbox';
5853
+ clockToleranceSec?: number;
5854
+ }
5855
+ interface KyaPayIdentity {
5856
+ type: KyaPayTokenType;
5857
+ jti: string;
5858
+ subject: string;
5859
+ /** Human identity (`hid`): email + any verified names. Treat as PII. */
5860
+ human?: Record<string, unknown>;
5861
+ /** Agent platform (`apd`). */
5862
+ platform?: Record<string, unknown>;
5863
+ /** Agent (`aid`). */
5864
+ agent?: Record<string, unknown>;
5865
+ /** The key the request must be RFC 9421-signed with (`cnf.jwk`), if any. */
5866
+ requiresSignatureKey?: JWK;
5867
+ claims: JWTPayload;
5868
+ }
5869
+ type KyaPayResult = {
5870
+ ok: true;
5871
+ tokens: KyaPayIdentity[];
5872
+ } | {
5873
+ ok: false;
5874
+ error: string;
5875
+ };
5876
+ declare function verifyKyaPayTokens(header: string | null | undefined, opts: KyaPayVerifyOptions): Promise<KyaPayResult>;
5877
+
5878
+ /**
5879
+ * 5.15.0 — A-Comm Evidence Protocol (AEP) v1.0.3-rc.2 core
5880
+ * (github.com/A-Comm-Tech/a-comm-evidence-protocol, spec section 4).
5881
+ *
5882
+ * AEP is an evidence layer beside the transaction ("parallel to the
5883
+ * transaction, never gating it"): a sequential, tamper-evident hash chain of
5884
+ * typed artifacts, each signed Ed25519 by the implementing party. This module
5885
+ * is the byte-level core, verified against the published conformance vectors:
5886
+ *
5887
+ * - Section 4.1 canonical JSON: RFC 8785 (JCS) + NFC normalization of member names
5888
+ * and string values; member names sorted by UTF-16 code unit at every
5889
+ * level; numbers MUST be integers.
5890
+ * - current_hash = "sha256:" + hex(SHA-256(canonical(hash_input))), where the
5891
+ * hash input is exactly {actor_id, actor_type, artifact_type,
5892
+ * interaction_channel, metadata, payload, previous_hash, timestamp};
5893
+ * previous_hash is inside it (null for genesis).
5894
+ * - Section 4.3 server_signature = Ed25519 over the RAW 32 digest bytes (base64).
5895
+ * - timestamps are RFC 3339 UTC 'Z', whole seconds.
5896
+ */
5897
+
5898
+ declare const AEP_SPEC_VERSION = "aep-1.0.3-rc.2";
5899
+ type AepArtifactType = 'discovery' | 'referral' | 'intent' | 'delegation' | 'policy' | 'cart' | 'authorization' | 'fulfillment' | 'refund';
5900
+ type AepActorType = 'user' | 'agent' | 'merchant' | 'psp' | 'fulfillment_provider' | 'credentials_provider' | 'identity_verifier';
5901
+ interface AepHashInput {
5902
+ actor_id: string;
5903
+ actor_type: AepActorType;
5904
+ artifact_type: AepArtifactType;
5905
+ interaction_channel: 'voice' | 'text_chat' | 'voice_and_text' | null;
5906
+ metadata: Record<string, unknown> | null;
5907
+ payload: Record<string, unknown>;
5908
+ previous_hash: string | null;
5909
+ timestamp: string;
5910
+ }
5911
+ /** AEP section 4.1 canonical JSON (JCS + NFC + UTF-16 key order + integer-only numbers). */
5912
+ declare function aepCanonicalJson(value: unknown): string;
5913
+ /** "sha256:<64 lowercase hex>" of a hash input (or any canonicalizable value). */
5914
+ declare function aepHash(input: AepHashInput | unknown): string;
5915
+ /** AEP timestamp: RFC 3339 UTC 'Z', whole seconds. */
5916
+ declare function aepTimestamp(d?: Date): string;
5917
+ /** An Ed25519 private key from a 32-byte seed (base64). */
5918
+ declare function aepPrivateKeyFromSeed(seedBase64: string): KeyObject;
5919
+ /** An Ed25519 public key from its raw 32 bytes (base64). */
5920
+ declare function aepPublicKeyFromBase64(raw: string): KeyObject;
5921
+ /** The raw 32-byte public key (base64) of an Ed25519 key. */
5922
+ declare function aepRawPublicKey(key: KeyObject): string;
5923
+ /** Section 4.3: Ed25519 over the RAW 32 digest bytes; base64. */
5924
+ declare function aepSign(currentHash: string, privateKey: KeyObject): string;
5925
+ declare function aepVerifySignature(currentHash: string, signature: string, publicKey: KeyObject): boolean;
5926
+ interface AepArtifactRecord {
5927
+ sequence_number: number;
5928
+ artifact_type: AepArtifactType;
5929
+ hash_input: AepHashInput;
5930
+ current_hash: string;
5931
+ server_signature: string;
5932
+ }
5933
+ interface AepChainVerification {
5934
+ ok: boolean;
5935
+ /** The first failing artifact's sequence number and why. */
5936
+ failure?: {
5937
+ sequence_number: number;
5938
+ reason: string;
5939
+ };
5940
+ /** current_hash of the authorization artifact (the seal, section 2.5), if present. */
5941
+ sealedHash?: string;
5942
+ }
5943
+ /** Section 4.3 verification steps for every artifact, in order. */
5944
+ declare function verifyAepChain(records: AepArtifactRecord[], publicKey: KeyObject): AepChainVerification;
5945
+ interface AepChainOptions {
5946
+ privateKey: KeyObject;
5947
+ /** Your published key id (signing_key_id at chain level). */
5948
+ keyId: string;
5949
+ merchantId: string;
5950
+ chainId?: string;
5951
+ /** Section 2.7 HMAC-SHA256 of your session token with a per-merchant salt. */
5952
+ sessionIdHash?: string;
5953
+ /** Extra hash-input metadata on every artifact (protocol, sdk_version…). */
5954
+ metadata?: Record<string, unknown>;
5955
+ }
5956
+ /**
5957
+ * An AEP chain for one transaction. Append artifacts in order; each gets
5958
+ * previous_hash, current_hash and server_signature. After the
5959
+ * authorization artifact (the seal) only fulfillment / refund may follow.
5960
+ */
5961
+ declare class AepChain {
5962
+ private opts;
5963
+ readonly records: AepArtifactRecord[];
5964
+ readonly chainId: string;
5965
+ private sealed;
5966
+ constructor(opts: AepChainOptions);
5967
+ append(a: {
5968
+ artifact_type: AepArtifactType;
5969
+ actor_type: AepActorType;
5970
+ actor_id: string;
5971
+ interaction_channel?: AepHashInput['interaction_channel'];
5972
+ payload: Record<string, unknown>;
5973
+ timestamp?: string;
5974
+ }): AepArtifactRecord;
5975
+ /** Chain-level fields (section 2.7) + records, for export. */
5976
+ toBundle(): {
5977
+ artifacts: AepArtifactRecord[];
5978
+ session_id_hash?: string | undefined;
5979
+ chain_id: string;
5980
+ merchant_id: string;
5981
+ spec_version: string;
5982
+ signing_key_id: string;
5983
+ };
5984
+ }
5985
+ /**
5986
+ * The document to serve at /.well-known/aep-public-key (section 4.3: "tagged with a
5987
+ * key_id"; keep a replaced key ≥ 90 days; list revocations). AEP rc.2 fixes
5988
+ * no field names for it — this shape is AstraSync's.
5989
+ */
5990
+ declare function aepPublicKeyDocument(keys: Array<{
5991
+ keyId: string;
5992
+ publicKey: KeyObject;
5993
+ notBefore?: string;
5994
+ notAfter?: string;
5995
+ }>, revocations?: Array<{
5996
+ keyId: string;
5997
+ revokedAt: string;
5998
+ }>): {
5999
+ spec_version: string;
6000
+ keys: {
6001
+ not_after?: string | undefined;
6002
+ not_before?: string | undefined;
6003
+ key_id: string;
6004
+ alg: string;
6005
+ public_key_base64: string;
6006
+ }[];
6007
+ revocations: {
6008
+ key_id: string;
6009
+ revoked_at: string;
6010
+ }[];
6011
+ };
6012
+
6013
+ declare const ACP_API_VERSION = "2026-04-17";
6014
+ type AcpStatus = 'not_ready_for_payment' | 'ready_for_payment' | 'pending_approval' | 'complete_in_progress' | 'completed' | 'canceled';
6015
+ interface AcpMessage {
6016
+ type: 'error' | 'info' | 'warning';
6017
+ code?: string;
6018
+ content: string;
6019
+ severity?: 'info' | 'low' | 'medium' | 'high' | 'critical';
6020
+ resolution?: 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review';
6021
+ param?: string | null;
6022
+ }
6023
+ interface AcpCheckoutSession {
6024
+ id: string;
6025
+ status: AcpStatus;
6026
+ currency: string;
6027
+ line_items: Array<{
6028
+ id: string;
6029
+ item: {
6030
+ id: string;
6031
+ name: string;
6032
+ unit_amount: number;
6033
+ };
6034
+ quantity: number;
6035
+ name: string;
6036
+ unit_amount: number;
6037
+ totals: Array<{
6038
+ type: string;
6039
+ amount: number;
6040
+ }>;
6041
+ }>;
6042
+ totals: Array<{
6043
+ type: string;
6044
+ amount: number;
6045
+ }>;
6046
+ messages: AcpMessage[];
6047
+ continue_url?: string;
6048
+ order?: Record<string, unknown>;
6049
+ _caller?: string;
6050
+ _astraCheckoutSessionId?: string;
6051
+ }
6052
+ interface AcpCheckoutKitOptions {
6053
+ currency: string;
6054
+ /** Payment handlers you accept (endpoint paymentHandlers), e.g. ['ai.astrasync.voucher']. */
6055
+ paymentHandlers: string[];
6056
+ catalog: (itemId: string) => Promise<CatalogItem | null>;
6057
+ verifyPurchase: (ctx: {
6058
+ session: AcpCheckoutSession;
6059
+ /** Pass as `checkoutSessionId` to AstraSync (the platform's cart id when sent). */
6060
+ checkoutSessionId: string;
6061
+ astraId?: string;
6062
+ attemptId?: string;
6063
+ valueMajor: number;
6064
+ }) => Promise<VerificationResult>;
6065
+ settle: (ctx: {
6066
+ session: AcpCheckoutSession;
6067
+ result: VerificationResult;
6068
+ paymentData?: Record<string, unknown>;
6069
+ }) => Promise<SettleResult>;
6070
+ reportSettlement?: (r: Parameters<VerificationGatewayClient['reportSettlement']>[0]) => Promise<unknown>;
6071
+ fulfil: (ctx: {
6072
+ session: AcpCheckoutSession;
6073
+ result: VerificationResult;
6074
+ }) => Promise<{
6075
+ id: string;
6076
+ permalink_url?: string;
6077
+ }>;
6078
+ /** Base path the kit is mounted at (default ''). */
6079
+ basePath?: string;
6080
+ store?: {
6081
+ get(id: string): Promise<AcpCheckoutSession | null>;
6082
+ put(s: AcpCheckoutSession): Promise<void>;
6083
+ };
6084
+ idempotencyStore?: IdempotencyStore;
6085
+ fallbackContinueUrl?: string;
6086
+ }
6087
+ declare function createAcpCheckoutKit(opts: AcpCheckoutKitOptions): {
6088
+ handle: (req: Request) => Promise<Response>;
6089
+ };
6090
+
6091
+ interface IssueDelegateOptions {
6092
+ /** The mandate object (e.g. `{ vct: 'mandate.checkout.1', … }`). */
6093
+ mandate: Record<string, unknown>;
6094
+ /** Top-level mandate fields to make selectively disclosable (e.g. ['checkout_jwt']). */
6095
+ sdFields?: string[];
6096
+ privateKey: KeyLike;
6097
+ kid: string;
6098
+ alg?: 'ES256' | 'ES384';
6099
+ /** Header `typ`. AP2 leaves the root's unspecified; omitted by default. */
6100
+ typ?: string;
6101
+ /** Extra signed claims on the token (KB hops: iat / aud / nonce / sd_hash). */
6102
+ claims?: Record<string, unknown>;
6103
+ }
6104
+ /** Sign a delegate SD-JWT; returns `jwt~disclosure~…~`. */
6105
+ declare function issueDelegateSdJwt(opts: IssueDelegateOptions): Promise<string>;
6106
+ type RootKeyResolver = (kid: string | undefined, header: Record<string, unknown>) => Promise<JWK | null>;
6107
+ interface VerifiedChain {
6108
+ /** Mandates of the LAST hop (what was finally authorised). */
6109
+ mandates: Record<string, unknown>[];
6110
+ /** Mandates of every hop, root first. */
6111
+ hops: Array<{
6112
+ header: Record<string, unknown>;
6113
+ payload: Record<string, unknown>;
6114
+ mandates: Record<string, unknown>[];
6115
+ }>;
6116
+ }
6117
+ /**
6118
+ * Verify an AP2 delegate chain: the root against `resolveRootKey(kid)`, each
6119
+ * KB hop against the previous hop's `cnf.jwk` with its `sd_hash` /
6120
+ * `issuer_jwt_hash` binding; terminal hops carry no `cnf`.
6121
+ */
6122
+ declare function verifyDelegateChain(chain: string, resolveRootKey: RootKeyResolver, opts?: {
6123
+ expectedAud?: string;
6124
+ expectedNonce?: string;
6125
+ }): Promise<VerifiedChain>;
6126
+
6127
+ declare const AP2_VCT: {
6128
+ readonly checkout: "mandate.checkout.1";
6129
+ readonly checkoutOpen: "mandate.checkout.open.1";
6130
+ readonly payment: "mandate.payment.1";
6131
+ readonly paymentOpen: "mandate.payment.open.1";
6132
+ };
6133
+ interface Ap2Party {
6134
+ id: string;
6135
+ name?: string;
6136
+ website?: string;
6137
+ }
6138
+ /** b64url(SHA-256(ascii(checkout_jwt))) — also the payment mandate's transaction_id. */
6139
+ declare function checkoutHash(checkoutJwt: string): string;
6140
+ declare function closedCheckoutMandate(checkoutJwt: string, ttlSec?: number, now?: number): {
6141
+ vct: "mandate.checkout.1";
6142
+ checkout_jwt: string;
6143
+ checkout_hash: string;
6144
+ iat: number;
6145
+ exp: number;
6146
+ };
6147
+ declare function closedPaymentMandate(input: {
6148
+ transactionId: string;
6149
+ payee: Ap2Party;
6150
+ amountMinor: number;
6151
+ currency: string;
6152
+ instrument: {
6153
+ id: string;
6154
+ type: string;
6155
+ description?: string;
6156
+ };
6157
+ ttlSec?: number;
6158
+ }, now?: number): {
6159
+ vct: "mandate.payment.1";
6160
+ transaction_id: string;
6161
+ payee: Ap2Party;
6162
+ payment_amount: {
6163
+ amount: number;
6164
+ currency: string;
6165
+ };
6166
+ payment_instrument: {
6167
+ id: string;
6168
+ type: string;
6169
+ description?: string;
6170
+ };
6171
+ iat: number;
6172
+ exp: number;
6173
+ };
6174
+ declare function openCheckoutMandate(input: {
6175
+ agentJwk: JWK;
6176
+ merchants: Ap2Party[];
6177
+ lineItems: Array<{
6178
+ id: string;
6179
+ acceptableItems: Array<{
6180
+ id: string;
6181
+ title?: string;
6182
+ }>;
6183
+ quantity: number;
6184
+ }>;
6185
+ ttlSec?: number;
6186
+ }, now?: number): {
6187
+ vct: "mandate.checkout.open.1";
6188
+ constraints: ({
6189
+ type: string;
6190
+ items: {
6191
+ id: string;
6192
+ acceptable_items: {
6193
+ id: string;
6194
+ title?: string;
6195
+ }[];
6196
+ quantity: number;
6197
+ }[];
6198
+ allowed?: undefined;
6199
+ } | {
6200
+ type: string;
6201
+ allowed: Ap2Party[];
6202
+ items?: undefined;
6203
+ })[];
6204
+ cnf: {
6205
+ jwk: JWK;
6206
+ };
6207
+ iat: number;
6208
+ exp: number;
6209
+ };
6210
+ declare function openPaymentMandate(input: {
6211
+ agentJwk: JWK;
6212
+ payees: Ap2Party[];
6213
+ currency: string;
6214
+ maxMinor: number;
6215
+ /** Digest binding this to the open checkout mandate (payment.reference). */
6216
+ conditionalTransactionId: string;
6217
+ ttlSec?: number;
6218
+ }, now?: number): {
6219
+ vct: "mandate.payment.open.1";
6220
+ constraints: ({
6221
+ type: string;
6222
+ currency: string;
6223
+ max: number;
6224
+ min: number;
6225
+ allowed?: undefined;
6226
+ conditional_transaction_id?: undefined;
6227
+ } | {
6228
+ type: string;
6229
+ allowed: Ap2Party[];
6230
+ currency?: undefined;
6231
+ max?: undefined;
6232
+ min?: undefined;
6233
+ conditional_transaction_id?: undefined;
6234
+ } | {
6235
+ type: string;
6236
+ conditional_transaction_id: string;
6237
+ currency?: undefined;
6238
+ max?: undefined;
6239
+ min?: undefined;
6240
+ allowed?: undefined;
6241
+ })[];
6242
+ cnf: {
6243
+ jwk: JWK;
6244
+ };
6245
+ iat: number;
6246
+ exp: number;
6247
+ };
6248
+ /** Sign a root mandate (AstraSync as trusted agent provider). */
6249
+ declare function signRootMandate(mandate: Record<string, unknown>, key: {
6250
+ privateKey: KeyLike;
6251
+ kid: string;
6252
+ }): Promise<string>;
6253
+ /**
6254
+ * The digest of a root mandate's delegate disclosure — used as the open
6255
+ * payment mandate's `payment.reference.conditional_transaction_id`.
6256
+ */
6257
+ declare function rootMandateDigest(rootToken: string): string;
6258
+ /**
6259
+ * Agent side: close an open mandate with a KB hop signed by the agent key in
6260
+ * its `cnf` (terminal: the closed mandate carries no cnf).
6261
+ */
6262
+ declare function createKbHop(prevToken: string, closedMandate: Record<string, unknown>, agentKey: {
6263
+ privateKey: KeyLike;
6264
+ kid?: string;
6265
+ }, aud: string, nonce?: string): Promise<string>;
6266
+ interface VerifyAp2Options {
6267
+ /** Resolve the root signer's key (e.g. AstraSync's JWKS by kid). */
6268
+ resolveRootKey: RootKeyResolver;
6269
+ /** The vct you expect in the final hop. */
6270
+ expectedVct: string;
6271
+ /** For closed checkout mandates: the checkout JWT you signed. */
6272
+ checkoutJwt?: string;
6273
+ /** For closed payment mandates: the checkout hash it must reference. */
6274
+ transactionId?: string;
6275
+ expectedAud?: string;
6276
+ expectedNonce?: string;
6277
+ now?: number;
6278
+ }
6279
+ type Ap2VerifyResult = {
6280
+ ok: true;
6281
+ mandate: Record<string, unknown>;
6282
+ chainLength: number;
6283
+ } | {
6284
+ ok: false;
6285
+ code: 'mandate_invalid_signature' | 'mandate_expired' | 'mandate_scope_mismatch';
6286
+ error: string;
6287
+ };
6288
+ /** Verify an AP2 mandate (root or chain) end to end. */
6289
+ declare function verifyAp2Mandate(token: string, opts: VerifyAp2Options): Promise<Ap2VerifyResult>;
6290
+
6291
+ /**
6292
+ * 5.15.0 — RFC 9421 HTTP Message Signatures: signing.
6293
+ *
6294
+ * Signs an outbound request (agent → merchant, platform → merchant webhook)
6295
+ * with an ES256 or Ed25519 private key. Covered components default to
6296
+ * `@method`, `@authority`, `@path` (+ `content-digest` when there's a body,
6297
+ * computed per RFC 9530). Protocol profiles (Web Bot Auth, Visa TAP,
6298
+ * Mastercard Agent Pay, UCP) pass their own `components`, `tag` and
6299
+ * parameters. Verification is transport/rfc9421-verify.
6300
+ */
6301
+
6302
+ type HttpSignatureAlgorithm = 'ecdsa-p256-sha256' | 'ed25519';
6303
+ interface SignHttpRequestOptions {
6304
+ /** Private key (Node KeyObject / PEM). */
6305
+ privateKey: KeyObject | string;
6306
+ keyId: string;
6307
+ alg?: HttpSignatureAlgorithm;
6308
+ /** Covered components. Default @method @authority @path (+ content-digest with a body). */
6309
+ components?: string[];
6310
+ /** Signature label. Default `sig1`. */
6311
+ label?: string;
6312
+ /** `tag` parameter (profile name, e.g. a Web Bot Auth or TAP tag). */
6313
+ tag?: string;
6314
+ /** `nonce` parameter: a value, or true for 32 random bytes (base64url). */
6315
+ nonce?: string | true;
6316
+ /** Lifetime in seconds (expires = created + this). Default 300. */
6317
+ expiresInSec?: number;
6318
+ /** Include the `alg` parameter. Default false (key type implies it). */
6319
+ includeAlg?: boolean;
6320
+ /** Include `expires`. Default true (UCP: keyid only, created optional). */
6321
+ includeExpires?: boolean;
6322
+ now?: () => Date;
6323
+ }
6324
+ interface SignableRequest {
6325
+ method: string;
6326
+ url: string;
6327
+ headers: Record<string, string>;
6328
+ body?: string;
6329
+ }
6330
+ /** RFC 9530 Content-Digest (sha-256) of a body. */
6331
+ declare function contentDigest(body: string): string;
6332
+ /**
6333
+ * Returns the request's headers plus `Signature-Input`, `Signature` (and
6334
+ * `Content-Digest` when a body is covered). Never mutates the input.
6335
+ */
6336
+ declare function signHttpRequest(req: SignableRequest, opts: SignHttpRequestOptions): Promise<Record<string, string>>;
5057
6337
 
5058
- export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DECLARED_SOURCE_MAX, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, type ParseResult as LocalPolicyParseResult, type ValidationError as LocalPolicyValidationError, type ValidationResult as LocalPolicyValidationResult, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type MerchantSettlementToken, type ModelConfig, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type ReportAttemptOptions, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, VERIFICATION_STATUS_HEADER, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, buildVerificationUnavailableBody, clearCache, createMcpMiddleware, degradeToObserve, denyStatusFor, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isRejectedIdentityClaim, isVerificationUnavailable, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, normalizeDeclaredSource, parseYaml as parseLocalPolicyYaml, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, unavailableRetryAfterSeconds, validatePolicy as validateLocalPolicy, verify };
6338
+ export { ACP_API_VERSION, AEP_SPEC_VERSION, AP2_VCT, type AcpCheckoutKitOptions, type AcpCheckoutSession, type AepActorType, type AepArtifactRecord, type AepArtifactType, AepChain, type AepChainOptions, type AepChainVerification, type AepHashInput, AgentClient, type AgentCredentials, type AgentProtocol, type AgentProtocolIdentities, type AgentRecord, type Ap2Party, type Ap2VerifyResult, AstraSync, type AstraSyncAepEvidence, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AstraSyncMandates, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DECLARED_SOURCE_MAX, DEFAULT_EDGE_CONFIG, DEFAULT_IDEMPOTENCY_TTL_MS, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, type HttpSignatureAlgorithm, type IdempotencyOptions, type IdempotencyRecord, type IdempotencyStore, KYDRequiredError, type KyaPayIdentity, type KyaPayResult, type KyaPayTokenType, type KyaPayVerifyOptions, type ParseResult as LocalPolicyParseResult, type ValidationError as LocalPolicyValidationError, type ValidationResult as LocalPolicyValidationResult, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, MemoryCheckoutStore, MemoryIdempotencyStore, type MerchantSettlementToken, type ModelConfig, type MppChallenge, type MppCredential, type MppReceipt, type NegotiationResult, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, RedisIdempotencyStore, type RedisLike, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type ReportAttemptOptions, type RootKeyResolver, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, SettlementReportError, type SettlementRequest, type SignHttpRequestOptions, type SignableRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, UCP_VERSION, type UcpAgentBinding, type CatalogItem as UcpCatalogItem, type UcpCheckoutKitOptions, type CheckoutSession as UcpCheckoutSession, type CheckoutStore as UcpCheckoutStore, type UcpMessage, type UcpProfile, type UcpProfileResult, type SettleResult as UcpSettleResult, type UcpSeverity, type UcpSignatureResult, VERIFICATION_STATUS_HEADER, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyAp2Options, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, type X402PaymentPayload, type X402PaymentRequired, type X402PaymentRequirements, type X402ResourceInfo, type X402SettlementResponse, _resetEdgeConfigCache, aepCanonicalJson, aepHash, aepPrivateKeyFromSeed, aepPublicKeyDocument, aepPublicKeyFromBase64, aepRawPublicKey, aepSign, aepTimestamp, aepVerifySignature, index as agent, astrasyncPaymentHandlers, authorizeSettlement, awaitStepUpApproval, beginIdempotent, buildGuidance, buildMppChallenge, buildSdkObservedMetadata, buildUcpProfile, buildVerificationUnavailableBody, buildX402Challenge, canonicalJson, checkUcpAgentBinding, checkoutHash, clearCache, closedCheckoutMandate, closedPaymentMandate, contentDigest, createAcpCheckoutKit, createKbHop, createMcpMiddleware, createUcpCheckoutKit, decodeMppRequest, degradeToObserve, denyStatusFor, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, encodeMppReceipt, encodeX402SettlementResponse, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, fetchUcpProfile, finishIdempotent, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, idempotencyMiddleware, isEdgeConfig, isRejectedIdentityClaim, isRetryableSettlementError, isSpecialUseIp, isVerificationUnavailable, isVerifiedHopValidFor, issueDelegateSdJwt, matchEdgePathRule, matchPlatformSignature, matchRoutePattern, negotiateUcp, nextjs, normalizeDeclaredSource, openCheckoutMandate, openPaymentMandate, parseYaml as parseLocalPolicyYaml, parseMppCredential, parseUcpAgentHeader, parseVerifiedHop, parseX402Challenge, parseX402Payment, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, requestFingerprint, rootMandateDigest, routePatternToRegExp, sanitizeHeaders, sdk, sdkFetch, sendUcpWebhook, serializeVerifiedHop, setMcpMeta, signHttpRequest, signRootMandate, signUcpRequest, signUcpResponse, index$1 as transport, ucpError, ucpEscalation, ucpFailure, ucpProfileHandler, ucpRequiredComponents, unavailableRetryAfterSeconds, validatePolicy as validateLocalPolicy, verify, verifyAepChain, verifyAp2Mandate, verifyDelegateChain, verifyKyaPayTokens, verifyMppChallenge, verifyUcpRequest, withIdempotency, x402PaymentMatchesOffer };