@agent-score/commerce 1.8.0 → 2.0.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 (90) hide show
  1. package/README.md +73 -9
  2. package/dist/{_response-BMt2y4Or.d.mts → _response-BFYN3b6i.d.mts} +19 -22
  3. package/dist/{_response-DyJ3mWI3.d.ts → _response-_iPD5AIj.d.ts} +19 -22
  4. package/dist/challenge/index.d.mts +106 -198
  5. package/dist/challenge/index.d.ts +106 -198
  6. package/dist/challenge/index.js +238 -111
  7. package/dist/challenge/index.js.map +1 -1
  8. package/dist/challenge/index.mjs +238 -111
  9. package/dist/challenge/index.mjs.map +1 -1
  10. package/dist/checkout-BoFwnVsj.d.ts +931 -0
  11. package/dist/checkout-DRbQ0Fsh.d.mts +931 -0
  12. package/dist/core.d.mts +2 -2
  13. package/dist/core.d.ts +2 -2
  14. package/dist/core.js +1 -1
  15. package/dist/core.js.map +1 -1
  16. package/dist/core.mjs +1 -1
  17. package/dist/core.mjs.map +1 -1
  18. package/dist/discovery/index.d.mts +453 -51
  19. package/dist/discovery/index.d.ts +453 -51
  20. package/dist/discovery/index.js +1092 -58
  21. package/dist/discovery/index.js.map +1 -1
  22. package/dist/discovery/index.mjs +1060 -57
  23. package/dist/discovery/index.mjs.map +1 -1
  24. package/dist/identity/express.d.mts +3 -3
  25. package/dist/identity/express.d.ts +3 -3
  26. package/dist/identity/express.js +30 -19
  27. package/dist/identity/express.js.map +1 -1
  28. package/dist/identity/express.mjs +30 -19
  29. package/dist/identity/express.mjs.map +1 -1
  30. package/dist/identity/fastify.d.mts +4 -4
  31. package/dist/identity/fastify.d.ts +4 -4
  32. package/dist/identity/fastify.js +30 -19
  33. package/dist/identity/fastify.js.map +1 -1
  34. package/dist/identity/fastify.mjs +30 -19
  35. package/dist/identity/fastify.mjs.map +1 -1
  36. package/dist/identity/hono.d.mts +3 -3
  37. package/dist/identity/hono.d.ts +3 -3
  38. package/dist/identity/hono.js +30 -19
  39. package/dist/identity/hono.js.map +1 -1
  40. package/dist/identity/hono.mjs +30 -19
  41. package/dist/identity/hono.mjs.map +1 -1
  42. package/dist/identity/nextjs.d.mts +6 -7
  43. package/dist/identity/nextjs.d.ts +6 -7
  44. package/dist/identity/nextjs.js +30 -19
  45. package/dist/identity/nextjs.js.map +1 -1
  46. package/dist/identity/nextjs.mjs +30 -19
  47. package/dist/identity/nextjs.mjs.map +1 -1
  48. package/dist/identity/policy.d.mts +41 -4
  49. package/dist/identity/policy.d.ts +41 -4
  50. package/dist/identity/policy.js +3662 -18
  51. package/dist/identity/policy.js.map +1 -1
  52. package/dist/identity/policy.mjs +3648 -3
  53. package/dist/identity/policy.mjs.map +1 -1
  54. package/dist/identity/web.d.mts +3 -3
  55. package/dist/identity/web.d.ts +3 -3
  56. package/dist/identity/web.js +30 -19
  57. package/dist/identity/web.js.map +1 -1
  58. package/dist/identity/web.mjs +30 -19
  59. package/dist/identity/web.mjs.map +1 -1
  60. package/dist/index.d.mts +72 -329
  61. package/dist/index.d.ts +72 -329
  62. package/dist/index.js +3651 -373
  63. package/dist/index.js.map +1 -1
  64. package/dist/index.mjs +3628 -361
  65. package/dist/index.mjs.map +1 -1
  66. package/dist/payment/index.d.mts +257 -266
  67. package/dist/payment/index.d.ts +257 -266
  68. package/dist/payment/index.js +586 -149
  69. package/dist/payment/index.js.map +1 -1
  70. package/dist/payment/index.mjs +573 -148
  71. package/dist/payment/index.mjs.map +1 -1
  72. package/dist/{agent_instructions-DiMSGkdm.d.mts → pricing-CQ9DIFaw.d.ts} +109 -56
  73. package/dist/{agent_instructions-DiMSGkdm.d.ts → pricing-CxzwyiO6.d.mts} +109 -56
  74. package/dist/rail_spec-XP0wKgJV.d.mts +132 -0
  75. package/dist/rail_spec-XP0wKgJV.d.ts +132 -0
  76. package/dist/{signer-CFVQsWjL.d.mts → signer-3FAit11j.d.mts} +27 -1
  77. package/dist/{signer-CFVQsWjL.d.ts → signer-3FAit11j.d.ts} +27 -1
  78. package/dist/solana-Cds87OTu.d.mts +67 -0
  79. package/dist/solana-Cds87OTu.d.ts +67 -0
  80. package/dist/stripe-multichain/index.d.mts +56 -67
  81. package/dist/stripe-multichain/index.d.ts +56 -67
  82. package/dist/stripe-multichain/index.js +68 -42
  83. package/dist/stripe-multichain/index.js.map +1 -1
  84. package/dist/stripe-multichain/index.mjs +68 -41
  85. package/dist/stripe-multichain/index.mjs.map +1 -1
  86. package/dist/{wwwauthenticate-CU1eNvMQ.d.mts → wwwauthenticate-D_FMnPgU.d.mts} +9 -10
  87. package/dist/{wwwauthenticate-CU1eNvMQ.d.ts → wwwauthenticate-D_FMnPgU.d.ts} +9 -10
  88. package/dist/x402_server-hgQzWQwB.d.mts +81 -0
  89. package/dist/x402_server-hgQzWQwB.d.ts +81 -0
  90. package/package.json +13 -9
package/dist/index.d.ts CHANGED
@@ -1,7 +1,13 @@
1
- export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AgentScoreCoreOptions, AssessResult, CreateSessionOnMissing, DenialCode, DenialReason, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, VerifyWalletSignerResult, buildAgentMemoryHint } from './core.js';
2
- export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, r as readX402PaymentHeader } from './signer-CFVQsWjL.js';
3
- export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from './_response-DyJ3mWI3.js';
4
- export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateOptionsFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed } from './identity/policy.js';
1
+ export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, DenialReason, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, VerifyWalletSignerResult, buildAgentMemoryHint } from './core.js';
2
+ export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.js';
3
+ export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from './_response-_iPD5AIj.js';
4
+ import { U as UCPSigningKey, a as UCPProfile } from './checkout-BoFwnVsj.js';
5
+ export { A as AGENTSCORE_UCP_CAPABILITY, b as AgentScoreGatePolicy, C as Checkout, c as CheckoutContext, d as CheckoutGateConfig, e as CheckoutRailSpec, f as CheckoutRequest, g as CheckoutResult, h as CheckoutValidationError, i as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, j as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, k as PricingFn, l as PricingResult, R as RecipientsFn, m as ReferenceIdFn, n as RunGateFn, S as SettleOutcome, o as UCPCapabilityBinding, p as UCPPaymentHandlerBinding, q as UCPProfileBody, r as UCPServiceBinding, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-BoFwnVsj.js';
6
+ export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.js';
7
+ export { S as SolanaMppRailSpec, b as StripeRailSpec, T as TempoRailSpec, a as TempoSessionRailSpec, X as X402BaseRailSpec } from './rail_spec-XP0wKgJV.js';
8
+ export { f as formatUsdCents, l as loadSolanaFeePayer } from './solana-Cds87OTu.js';
9
+ import './pricing-CQ9DIFaw.js';
10
+ import './x402_server-hgQzWQwB.js';
5
11
 
6
12
  /**
7
13
  * Google A2A (Agent-to-Agent) v1.0 Agent Card builder.
@@ -209,320 +215,6 @@ interface BuildA2AAgentCardInput {
209
215
  */
210
216
  declare function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard;
211
217
 
212
- /**
213
- * Construct a UCPSigningKey from a public JWK dict (e.g. the `publicJWK` returned by
214
- * `generateUCPSigningKey()`). Validates required fields and rejects symmetric keys that
215
- * can't publicly verify a JWS in trust-mode UCP. Mirrors python's
216
- * `UCPSigningKey.from_jwk(public_jwk)` classmethod via the `UCPSigningKey.fromJWK`
217
- * static-method-style namespace export below.
218
- */
219
- declare function ucpSigningKeyFromJWKImpl(jwk: Record<string, unknown>): UCPSigningKey;
220
- /**
221
- * UCP (Universal Commerce Protocol) profile builder.
222
- *
223
- * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec.
224
- * Output shape matches the spec example: top-level `{ ucp: {...}, signing_keys: [...] }`
225
- * envelope, with `services` / `capabilities` / `payment_handlers` as MAPs keyed by
226
- * reverse-DNS service / capability / handler name.
227
- *
228
- * AgentScore identity claims layer over UCP via the `sh.agentscore.identity` capability
229
- * (vendor-namespaced; UCP doesn't define KYC/sanctions/age/jurisdiction natively). The
230
- * capability extends `dev.ucp.shopping.checkout` AND `dev.ucp.shopping.cart` (multi-parent,
231
- * the standard pattern UCP allows for capabilities that compose multiple parents).
232
- *
233
- * The unsigned profile body returned here is what merchants publish; pass it through
234
- * `signUCPProfile` to attach the `agentscore-profile+jws` signature for trust-mode
235
- * verifiers (vendor extension; UCP itself doesn't mandate profile-body signing).
236
- *
237
- * Spec reference: https://ucp.dev/
238
- */
239
- /**
240
- * UCP per-element shape note: each binding interface (`UCPServiceBinding`,
241
- * `UCPCapabilityBinding`, `UCPPaymentHandlerBinding`) carries the canonical UCP fields
242
- * plus arbitrary vendor extras flat on the same object via `[k: string]: unknown`. The
243
- * python sibling models these as dataclasses with an explicit `extras: dict` field. Both
244
- * designs offer equivalent guarantees through different mechanisms.
245
- */
246
- interface UCPSigningKey {
247
- /** JWK kid (key id). */
248
- kid: string;
249
- /** JWK kty (key type) — `EC`, `RSA`, or `OKP`. */
250
- kty: string;
251
- /** JWK alg (signing algorithm) — `ES256`, `RS256`, or `EdDSA`. */
252
- alg?: string;
253
- /** JWK use, typically `sig`. */
254
- use?: string;
255
- /** JWK crv (curve) for EC / OKP keys. */
256
- crv?: string;
257
- /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */
258
- [k: string]: unknown;
259
- }
260
- /** Static-method-style namespace on the `UCPSigningKey` interface — mirrors python's
261
- * `UCPSigningKey.from_jwk(jwk)` classmethod. Use as `UCPSigningKey.fromJWK(jwk)`. */
262
- declare const UCPSigningKey: {
263
- fromJWK: typeof ucpSigningKeyFromJWKImpl;
264
- };
265
- /** Transport binding — keyed under a service name (e.g., `dev.ucp.shopping`). */
266
- interface UCPServiceBinding {
267
- /** Spec version, YYYY-MM-DD per UCP convention. REQUIRED. */
268
- version: string;
269
- /** URL to human-readable specification. REQUIRED. */
270
- spec: string;
271
- /** Transport — `rest` / `mcp` / `a2a` / `embedded`. REQUIRED. */
272
- transport: 'rest' | 'mcp' | 'a2a' | 'embedded';
273
- /** Endpoint URL — required for rest/mcp; A2A points at the agent-card.json URL. */
274
- endpoint?: string;
275
- /** URL to JSON Schema — required for rest/mcp/embedded per spec. */
276
- schema?: string;
277
- /** Optional id for entity-instance disambiguation. */
278
- id?: string;
279
- /** Entity-specific config. */
280
- config?: Record<string, unknown>;
281
- /** Vendor-specific extras. */
282
- [k: string]: unknown;
283
- }
284
- /** Capability binding — keyed under a capability name (e.g., `dev.ucp.shopping.checkout`). */
285
- interface UCPCapabilityBinding {
286
- /** Capability version, YYYY-MM-DD. REQUIRED. */
287
- version: string;
288
- /** URL to human-readable specification. REQUIRED. */
289
- spec: string;
290
- /** URL to JSON Schema. REQUIRED. */
291
- schema: string;
292
- /** Optional id for entity-instance disambiguation. */
293
- id?: string;
294
- /** Entity-specific config (feature flags, callback URLs, etc). */
295
- config?: Record<string, unknown>;
296
- /** Parent capability(ies) extended — single string or array for multi-parent. */
297
- extends?: string | string[];
298
- /** Optional version requirements per UCP §6.5. */
299
- requires?: {
300
- protocol?: {
301
- min: string;
302
- max?: string;
303
- };
304
- capabilities?: Record<string, {
305
- min: string;
306
- max?: string;
307
- }>;
308
- };
309
- /** Vendor-specific extras allowed per UCP convention (e.g., the AgentScore identity
310
- * capability adds a vendor-namespaced policy declaration here). */
311
- [k: string]: unknown;
312
- }
313
- /** Payment handler binding — keyed under a handler reverse-DNS name (e.g., `com.google.pay`). */
314
- interface UCPPaymentHandlerBinding {
315
- /** Handler instance id (short, human-readable, e.g., `gpay`, `tempo`, `x402`). REQUIRED. */
316
- id: string;
317
- /** Handler spec version, YYYY-MM-DD. REQUIRED. */
318
- version: string;
319
- /** URL to handler spec. REQUIRED. */
320
- spec: string;
321
- /** URL to handler config schema. REQUIRED. */
322
- schema: string;
323
- /** Available instruments — type + per-type constraints (cards, wallets, etc.). */
324
- available_instruments?: Array<{
325
- type: string;
326
- constraints?: Record<string, unknown>;
327
- [k: string]: unknown;
328
- }>;
329
- /** Handler config — gateway IDs, merchant IDs, public keys, etc. */
330
- config?: Record<string, unknown>;
331
- /** Vendor-specific extras. */
332
- [k: string]: unknown;
333
- }
334
- /** UCP body — nested under the `ucp` key of the published profile. */
335
- interface UCPProfileBody {
336
- /** UCP spec version (YYYY-MM-DD). */
337
- version: string;
338
- /** Display name for the merchant / agent surface. */
339
- name?: string;
340
- /** Services — keyed by service name (e.g., `dev.ucp.shopping`). Each value is an
341
- * array of transport bindings (one merchant typically advertises multiple transports
342
- * under one service name). */
343
- services: Record<string, UCPServiceBinding[]>;
344
- /** Capabilities — keyed by capability name (e.g., `dev.ucp.shopping.checkout`). */
345
- capabilities: Record<string, UCPCapabilityBinding[]>;
346
- /** Payment handlers — keyed by handler reverse-DNS name (e.g., `com.google.pay`). */
347
- payment_handlers: Record<string, UCPPaymentHandlerBinding[]>;
348
- /** Optional `supported_versions` map linking historical version-specific profile URLs.
349
- * Pattern: `{ "2026-01-23": "https://merchant/.well-known/ucp/2026-01-23", ... }`. */
350
- supported_versions?: Record<string, string>;
351
- /** Vendor-specific extras inside the `ucp` envelope. */
352
- [k: string]: unknown;
353
- }
354
- /** Full UCP profile body as published at `/.well-known/ucp`. Top-level shape:
355
- * `{ ucp: {...}, signing_keys: [...], signature?: "..." }`. */
356
- interface UCPProfile {
357
- /** UCP body. ALL UCP-spec fields nest here per spec. */
358
- ucp: UCPProfileBody;
359
- /** JWKS — public keys at the OUTER level per UCP spec. Verifiers fetch this profile,
360
- * match the kid from a JWS / RFC 9421 signature header against this list, and validate. */
361
- signing_keys: UCPSigningKey[];
362
- /** Set when JWS-signed via `signUCPProfile` — JWS Compact Serialization with detached
363
- * payload (header..signature; payload is the canonicalized body minus this field). */
364
- signature?: string;
365
- /** Top-level vendor-specific extras (outside the `ucp` envelope). */
366
- [k: string]: unknown;
367
- }
368
- interface BuildUCPProfileInput {
369
- /** UCP spec version. Default `'2026-04-08'` (the latest published UCP spec date). MUST match a published UCP spec version, not a free-form date. */
370
- version?: string;
371
- /** Display name for the merchant / agent surface. */
372
- name?: string;
373
- /** Services map, keyed by service name. UCP-shopping merchants typically advertise
374
- * bindings under `'dev.ucp.shopping'`. */
375
- services?: Record<string, UCPServiceBinding[]>;
376
- /** Capabilities map, keyed by capability name. The `sh.agentscore.identity` capability
377
- * is auto-added when `agentscore_gate` is provided. */
378
- capabilities?: Record<string, UCPCapabilityBinding[]>;
379
- /** Payment handlers map, keyed by handler reverse-DNS name. */
380
- payment_handlers?: Record<string, UCPPaymentHandlerBinding[]>;
381
- /** JWKS — public keys the merchant signs with. REQUIRED by spec. */
382
- signing_keys: UCPSigningKey[];
383
- /** Merchant gate policy declaration. When provided, the SDK auto-injects an
384
- * `sh.agentscore.identity` capability binding into `capabilities`, with the
385
- * policy as the binding's `config`. Static merchant declaration only — no
386
- * per-operator data ever ends up on the public profile. Per-operator identity
387
- * attestation lives on the AP2 risk-signal endpoint, not here. */
388
- agentscore_gate?: AgentScoreGatePolicy;
389
- /** Optional override for the AgentScore capability schema URL. Field is snake_cased
390
- * for cross-language parity with the Python sibling. */
391
- agentscore_schema_url?: string;
392
- /** Optional override for the AgentScore capability spec URL. */
393
- agentscore_spec_url?: string;
394
- /** `supported_versions` map at the profile root for backwards-compat across
395
- * spec dates. Pattern: `{ "<date>": "<base>/.well-known/ucp/<date>" }`. */
396
- supported_versions?: Record<string, string>;
397
- /** Vendor-specific extras at the OUTER level (alongside `ucp` + `signing_keys`). */
398
- extras?: Record<string, unknown>;
399
- /** Vendor-specific extras INSIDE the `ucp` envelope (alongside `version`, `services`, etc.). */
400
- ucp_extras?: Record<string, unknown>;
401
- }
402
- /** Merchant gate policy declared on the UCP profile via `sh.agentscore.identity` capability config.
403
- * All fields optional; merchant declares which AgentScore checks the gate enforces. Snake-case
404
- * field names match the AgentScore API's `/v1/assess` policy contract verbatim — no conversion
405
- * layer between this declaration and what the gate actually enforces at runtime. */
406
- interface AgentScoreGatePolicy {
407
- /** Gate denies if the operator/account behind the agent is not Stripe-Identity-verified. */
408
- require_kyc?: boolean;
409
- /** Gate denies if the operator/account is flagged by OpenSanctions screening. */
410
- require_sanctions_clear?: boolean;
411
- /** Gate denies if the verified age (from KYC) is below this threshold. Common values: 18, 21. */
412
- min_age?: number;
413
- /** ISO-3166-1 alpha-2 country codes the gate accepts. Empty/absent allows any. Mutually exclusive
414
- * with `blocked_jurisdictions` (set one or the other, not both). */
415
- allowed_jurisdictions?: string[];
416
- /** ISO-3166-1 alpha-2 country codes the gate denies. Empty/absent denies none. Mutually exclusive
417
- * with `allowed_jurisdictions`. */
418
- blocked_jurisdictions?: string[];
419
- }
420
- /**
421
- * Compose a UCP profile body for `/.well-known/ucp` publication. Returns the spec-
422
- * compliant shape: `{ ucp: { version, services, capabilities, payment_handlers, ... },
423
- * signing_keys: [...] }`. Pass through `signUCPProfile` to attach a JWS signature for
424
- * trust-mode verifiers.
425
- *
426
- * Auto-injects `sh.agentscore.identity` as a vendor capability extending both
427
- * `dev.ucp.shopping.checkout` and `dev.ucp.shopping.cart` when `agentscore_gate`
428
- * is provided. The capability's `config` carries the merchant's static gate
429
- * policy declaration (require_kyc / require_sanctions_clear / min_age /
430
- * allowed_jurisdictions / blocked_jurisdictions). NO per-operator data is ever
431
- * placed on the public profile — per-operator identity attestation flows through
432
- * the AP2 risk-signal endpoint, not here.
433
- *
434
- * Example:
435
- * ```ts
436
- * import { buildUCPProfile } from '@agent-score/commerce';
437
- *
438
- * const profile = buildUCPProfile({
439
- * name: 'Example Merchant',
440
- * services: {
441
- * 'dev.ucp.shopping': [
442
- * { version: '2026-04-08', spec: 'https://ucp.dev/2026-04-08/specification/overview',
443
- * transport: 'mcp', endpoint: 'https://merchant.example/api/ucp/mcp',
444
- * schema: 'https://ucp.dev/services/shopping/mcp.openrpc.json' },
445
- * ],
446
- * },
447
- * payment_handlers: {
448
- * ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217, recipient: TEMPO_ADDR }] }),
449
- * },
450
- * signing_keys: [signingKey],
451
- * agentscore_gate: { require_kyc: true, min_age: 21, allowed_jurisdictions: ['US'] },
452
- * });
453
- * ```
454
- */
455
- declare function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile;
456
- declare const AGENTSCORE_UCP_CAPABILITY = "sh.agentscore.identity";
457
- type MppNetwork = 'tempo-mainnet' | 'tempo-testnet' | 'mpp-solana-mainnet' | 'mpp-solana-devnet' | (string & {});
458
- interface MppNetworkEntry {
459
- network: MppNetwork;
460
- /** EVM-style chain id (e.g. 4217 for Tempo mainnet). Omit for non-EVM networks. */
461
- chain_id?: number;
462
- /** Static settlement address. Omit for per-order recipients (e.g. Stripe-derived deposits). */
463
- recipient?: string;
464
- [k: string]: unknown;
465
- }
466
- interface MppPaymentHandlerInput {
467
- networks: MppNetworkEntry[];
468
- }
469
- type X402Network = `base-${number}` | 'solana-mainnet-beta' | 'solana-devnet' | 'stellar-pubnet' | 'stellar-testnet' | (string & {});
470
- interface X402NetworkEntry {
471
- network: X402Network;
472
- /** Static settlement address. Omit for per-order recipients. */
473
- recipient?: string;
474
- [k: string]: unknown;
475
- }
476
- interface X402PaymentHandlerInput {
477
- networks: X402NetworkEntry[];
478
- }
479
- interface StripeSptPaymentHandlerInput {
480
- /** Stripe profile id (the merchant-side network identifier the agent's SPT is scoped to). */
481
- profile_id: string;
482
- }
483
- /**
484
- * Build the `sh.agentscore.payment.mpp` payment handler block for a UCP profile.
485
- *
486
- * @example
487
- * ```ts
488
- * buildUCPProfile({
489
- * ...,
490
- * payment_handlers: {
491
- * ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217 }] }),
492
- * },
493
- * });
494
- * ```
495
- */
496
- declare function mppPaymentHandler(input: MppPaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
497
- /**
498
- * Build the `sh.agentscore.payment.x402` payment handler block for a UCP profile.
499
- *
500
- * @example
501
- * ```ts
502
- * buildUCPProfile({
503
- * ...,
504
- * payment_handlers: {
505
- * ...x402PaymentHandler({ networks: [{ network: 'base-8453', recipient: '0xabc...' }] }),
506
- * },
507
- * });
508
- * ```
509
- */
510
- declare function x402PaymentHandler(input: X402PaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
511
- /**
512
- * Build the `sh.agentscore.payment.stripe_spt` payment handler block for a UCP profile.
513
- *
514
- * @example
515
- * ```ts
516
- * buildUCPProfile({
517
- * ...,
518
- * payment_handlers: {
519
- * ...stripeSptPaymentHandler({ profile_id: 'profile_5xKvNqM9BaH' }),
520
- * },
521
- * });
522
- * ```
523
- */
524
- declare function stripeSptPaymentHandler(input: StripeSptPaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
525
-
526
218
  /**
527
219
  * UCP profile signing helpers (JWKS + JWS).
528
220
  *
@@ -560,15 +252,6 @@ interface GeneratedUCPKey {
560
252
  interface JWKSResponse {
561
253
  keys: UCPSigningKey[];
562
254
  }
563
- /** Options for `signUCPProfile()`. */
564
- interface SignUCPProfileOptions {
565
- /** Private signing key — opaque KeyLike from `generateUCPSigningKey()` or `importJWK()`. */
566
- signingKey: unknown;
567
- /** Key ID (must match a `kid` in the profile's `signing_keys[]`). */
568
- kid: string;
569
- /** Signing algorithm — `EdDSA` (default) or `ES256`. */
570
- alg?: 'EdDSA' | 'ES256';
571
- }
572
255
  /** A signed UCP profile envelope. Same shape as `UCPProfile` plus the `signature` field
573
256
  * carrying the JWS Compact Serialization over the canonicalized profile body. */
574
257
  interface SignedUCPProfile extends UCPProfile {
@@ -625,7 +308,14 @@ declare function generateUCPSigningKey(opts: {
625
308
  * c.json(signed);
626
309
  * ```
627
310
  */
628
- declare function signUCPProfile(profile: UCPProfile, opts: SignUCPProfileOptions): Promise<SignedUCPProfile>;
311
+ declare function signUCPProfile(profile: UCPProfile, { signingKey, kid, alg, }: {
312
+ /** Private signing key — opaque KeyLike from `generateUCPSigningKey()` or `importJWK()`. */
313
+ signingKey: unknown;
314
+ /** Key ID (must match a `kid` in the profile's `signing_keys[]`). */
315
+ kid: string;
316
+ /** Signing algorithm — `EdDSA` (default) or `ES256`. */
317
+ alg?: 'EdDSA' | 'ES256';
318
+ }): Promise<SignedUCPProfile>;
629
319
  /**
630
320
  * Verify a signed UCP profile against a JWKS. Returns `true` when the JWS validates
631
321
  * against a matching key in `jwks`; throws on signature mismatch, missing key, or
@@ -653,5 +343,58 @@ declare function verifyUCPProfile(profile: SignedUCPProfile, jwks: JWKSResponse)
653
343
  * ```
654
344
  */
655
345
  declare function buildJWKSResponse(keys: UCPSigningKey[]): JWKSResponse;
346
+ /**
347
+ * Load the merchant's UCP signing key from env, with concurrent-safe caching.
348
+ *
349
+ * On first call (per `opts`): reads `opts.envJwkVar`, parses it as a JWK, validates
350
+ * `kty`/`crv` (OKP+Ed25519 or EC+P-256), and projects to a canonical public JWK.
351
+ * Falls back to an ephemeral keypair when the env var is missing or whitespace-only.
352
+ *
353
+ * Subsequent calls with the same `opts` return the cached key without re-reading env.
354
+ * Concurrent first-callers await the same in-flight Promise so only one key generation
355
+ * runs (preventing the race where two callers each generate an independent ephemeral
356
+ * pair and one signs a JWS the published JWKS then rejects).
357
+ *
358
+ * Different `opts` values get separate cache entries.
359
+ *
360
+ * Env-driven precedence:
361
+ *
362
+ * - Embedded `kid` in the JWK wins over `opts.envKidVar` env value;
363
+ * empty-string `kid` in the env JWK falls through to `opts.defaultKid`.
364
+ * - Structural `kty`+`crv` in the JWK wins over `opts.envAlgVar` env value
365
+ * (which is only consulted in the ephemeral fallback path).
366
+ *
367
+ * @throws Error with a sanitized message for malformed env JWKs; raw exception
368
+ * detail is intentionally suppressed so key bytes can never reach logs.
369
+ */
370
+ declare function loadUCPSigningKeyFromEnv({ envJwkVar, envKidVar, envAlgVar, defaultKid, defaultAlg, }?: {
371
+ /** Env var name carrying the JSON-encoded private JWK. Default `UCP_SIGNING_KEY_JWK_PRIVATE`. */
372
+ envJwkVar?: string;
373
+ /** Env var name carrying an explicit kid override. Default `UCP_SIGNING_KEY_KID`. */
374
+ envKidVar?: string;
375
+ /** Env var name carrying the alg in the ephemeral fallback. Default `UCP_SIGNING_KEY_ALG`. */
376
+ envAlgVar?: string;
377
+ /** Kid to publish when neither the env JWK nor `envKidVar` carries one. Default `merchant-default`. */
378
+ defaultKid?: string;
379
+ /** Alg for the ephemeral fallback path. Default `EdDSA`. */
380
+ defaultAlg?: 'EdDSA' | 'ES256';
381
+ }): Promise<GeneratedUCPKey>;
382
+
383
+ /**
384
+ * Operator-token hashing.
385
+ *
386
+ * Plaintext operator tokens (`opc_...`) never persist on disk. Merchants hash
387
+ * them before storing in DB columns and before comparing against persisted
388
+ * hashes. This helper exposes the canonical hash so every consumer agrees on
389
+ * the shape.
390
+ */
391
+ /**
392
+ * sha256 hex digest of a plaintext operator token.
393
+ *
394
+ * Use at every persistence boundary (INSERT) AND every comparison boundary
395
+ * (SELECT WHERE operator_token_id = ...) so plaintext tokens never land in
396
+ * durable storage.
397
+ */
398
+ declare function hashOperatorToken(plaintext: string): string;
656
399
 
657
- export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, AGENTSCORE_UCP_CAPABILITY, type AgentScoreGatePolicy, type BuildA2AAgentCardInput, type BuildUCPProfileInput, type GeneratedUCPKey, type JWKSResponse, type MppNetworkEntry, type MppPaymentHandlerInput, type SignUCPProfileOptions, type SignedUCPProfile, type StripeSptPaymentHandlerInput, type UCPCapabilityBinding, type UCPPaymentHandlerBinding, type UCPProfile, type UCPProfileBody, type UCPServiceBinding, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type X402NetworkEntry, type X402PaymentHandlerInput, buildA2AAgentCard, buildJWKSResponse, buildUCPProfile, generateUCPSigningKey, mppPaymentHandler, signUCPProfile, stripeSptPaymentHandler, ucpA2AExtension, verifyUCPProfile, x402PaymentHandler };
400
+ export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, type GeneratedUCPKey, type JWKSResponse, type SignedUCPProfile, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, buildA2AAgentCard, buildJWKSResponse, generateUCPSigningKey, hashOperatorToken, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verifyUCPProfile };