@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.
- package/README.md +27 -17
- package/dist/adapters/express.d.mts +1 -1
- package/dist/adapters/express.d.ts +1 -1
- package/dist/adapters/express.js +477 -240
- package/dist/adapters/express.js.map +1 -1
- package/dist/adapters/express.mjs +477 -240
- package/dist/adapters/express.mjs.map +1 -1
- package/dist/adapters/mcp.d.mts +1 -1
- package/dist/adapters/mcp.d.ts +1 -1
- package/dist/adapters/mcp.js +20 -6
- package/dist/adapters/mcp.js.map +1 -1
- package/dist/adapters/mcp.mjs +20 -6
- package/dist/adapters/mcp.mjs.map +1 -1
- package/dist/adapters/nextjs.d.mts +1 -1
- package/dist/adapters/nextjs.d.ts +1 -1
- package/dist/adapters/nextjs.js +460 -239
- package/dist/adapters/nextjs.js.map +1 -1
- package/dist/adapters/nextjs.mjs +460 -239
- package/dist/adapters/nextjs.mjs.map +1 -1
- package/dist/adapters/sdk.d.mts +18 -10
- package/dist/adapters/sdk.d.ts +18 -10
- package/dist/adapters/sdk.js +80 -23
- package/dist/adapters/sdk.js.map +1 -1
- package/dist/adapters/sdk.mjs +80 -23
- package/dist/adapters/sdk.mjs.map +1 -1
- package/dist/agent/index.js +1 -1
- package/dist/agent/index.js.map +1 -1
- package/dist/agent/index.mjs +1 -1
- package/dist/agent/index.mjs.map +1 -1
- package/dist/bin/astrasync-claude-hook.js +55 -11
- package/dist/bin/astrasync-codex-hook.js +55 -11
- package/dist/bin/astrasync-guard.js +55 -11
- package/dist/bin/astrasync.js +288 -33
- package/dist/browser/background.js +50 -6
- package/dist/browser/background.js.map +1 -1
- package/dist/browser/background.mjs +60 -6
- package/dist/browser/background.mjs.map +1 -1
- package/dist/cli/index.js +1 -1
- package/dist/cli/index.js.map +1 -1
- package/dist/cli/index.mjs +1 -1
- package/dist/cli/index.mjs.map +1 -1
- package/dist/codex/index.js +55 -11
- package/dist/codex/index.js.map +1 -1
- package/dist/codex/index.mjs +65 -11
- package/dist/codex/index.mjs.map +1 -1
- package/dist/cursor/extension.js +55 -11
- package/dist/cursor/extension.js.map +1 -1
- package/dist/cursor/extension.mjs +65 -11
- package/dist/cursor/extension.mjs.map +1 -1
- package/dist/edge-config.d.mts +31 -2
- package/dist/edge-config.d.ts +31 -2
- package/dist/edge-config.js +35 -5
- package/dist/edge-config.js.map +1 -1
- package/dist/edge-config.mjs +32 -4
- package/dist/edge-config.mjs.map +1 -1
- package/dist/edge-core/index.d.mts +11 -2
- package/dist/edge-core/index.d.ts +11 -2
- package/dist/edge-core/index.js +93 -10
- package/dist/edge-core/index.js.map +1 -1
- package/dist/edge-core/index.mjs +91 -10
- package/dist/edge-core/index.mjs.map +1 -1
- package/dist/gateway/gateway.js +50 -6
- package/dist/gateway/gateway.js.map +1 -1
- package/dist/gateway/gateway.mjs +60 -6
- package/dist/gateway/gateway.mjs.map +1 -1
- package/dist/git-trigger/git-hooks.d.mts +1 -1
- package/dist/git-trigger/git-hooks.d.ts +1 -1
- package/dist/index.d.mts +1314 -34
- package/dist/index.d.ts +1314 -34
- package/dist/index.js +5116 -2612
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +5063 -2614
- package/dist/index.mjs.map +1 -1
- package/dist/registration/index.d.mts +28 -2
- package/dist/registration/index.d.ts +28 -2
- package/dist/registration/index.js +18 -3
- package/dist/registration/index.js.map +1 -1
- package/dist/registration/index.mjs +15 -2
- package/dist/registration/index.mjs.map +1 -1
- package/dist/transport/index.d.mts +7 -5
- package/dist/transport/index.d.ts +7 -5
- package/dist/transport/index.js +61 -5
- package/dist/transport/index.js.map +1 -1
- package/dist/transport/index.mjs +67 -11
- package/dist/transport/index.mjs.map +1 -1
- package/dist/{types-C_b4QTyO.d.ts → types-DtJjlW4O.d.ts} +104 -10
- package/dist/{types-BCkwBA84.d.mts → types-Dxf9DBpr.d.mts} +106 -12
- package/dist/{types-BCkwBA84.d.ts → types-Dxf9DBpr.d.ts} +106 -12
- package/dist/{types-DlshIIR-.d.mts → types-Eg6VoBNH.d.mts} +104 -10
- package/dist/ui/index.d.mts +1 -1
- package/dist/ui/index.d.ts +1 -1
- package/dist/verify.d.mts +1 -1
- package/dist/verify.d.ts +1 -1
- package/dist/verify.js +20 -6
- package/dist/verify.js.map +1 -1
- package/dist/verify.mjs +20 -6
- package/dist/verify.mjs.map +1 -1
- 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
|
-
*
|
|
677
|
-
*
|
|
678
|
-
*
|
|
679
|
-
*
|
|
680
|
-
*
|
|
681
|
-
* `no_instrument` = policy passed but the owner has
|
|
682
|
-
*
|
|
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
|
-
*
|
|
687
|
-
*
|
|
688
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
1949
|
-
*
|
|
1950
|
-
*
|
|
1951
|
-
* /orders and the agent's poll surface reconcile.
|
|
1952
|
-
*
|
|
1953
|
-
*
|
|
1954
|
-
*
|
|
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
|
|
2056
|
+
sessionId?: string;
|
|
2057
|
+
orderId?: string;
|
|
1958
2058
|
status: 'settled' | 'declined' | 'failed';
|
|
1959
2059
|
amountMinor: number;
|
|
1960
2060
|
currency: string;
|
|
1961
|
-
/** Stripe PaymentIntent id —
|
|
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
|
-
* -
|
|
2976
|
-
*
|
|
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.
|
|
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.
|
|
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 };
|