@zadq/x402 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+zadq-x402-tools — x402 extension helpers and explorer integration code
+Copyright 2026 CONECTIA group
+
+This product includes software developed for the ZadQ project.
+Licensed under the Apache License, Version 2.0.
+
+"x402" is used descriptively. This project is not affiliated with, sponsored
+by or maintained by the x402 ecosystem's trademark holders.

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @zadq/x402
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Verifiable accountability for agent payments. Prove accountability. Keep identity private.**
+
+Client helpers for the free seller-verification path of x402 endpoints, from
+[ZadQ](https://zadq.info/docs): fetch the signed verdict for an endpoint and
+check its freshness and Ed25519 signature locally; attach or read the HTTP 402
+identity-policy extension and the `X-PAYMENT-IDENTITY` companion header; verify
+the issuer's receipt; resolve an explorer signal with a TTL cache; verify
+`verdict.updated` webhook deliveries; drive the seller's own credential holder
+(Node only). Strict TypeScript, ES modules, zero runtime dependencies, no
+default exports.
+
+Every helper degrades gracefully: an unreachable service, a timeout, an absent
+or stale verdict or a failed signature check resolve to `unknown` — never an
+exception, never a blocked payment. Checking a verdict costs nothing for
+whoever runs the check.
+
+```bash
+npm install @zadq/x402
+```
+
+```ts
+import { fetchVerdict, freshness, verifyVerdictSignature } from '@zadq/x402/verdict';
+import { withIdentityPolicy } from '@zadq/x402/extension';
+import { resolveSignal } from '@zadq/x402/explorer';
+```
+
+Subpath exports: `verdict`, `extension`, `header`, `receipt`, `explorer`,
+`keys`, `webhook`, `holder` (Node only) — or everything from the root. The
+contracts each module honours are documented at
+<https://zadq.info/docs/sdk>; the modules are also available as copy-in files
+in the repository's `snippets/` folder for integrators who prefer to vendor.
+
+"x402" is used descriptively. About ZadQ and who operates it:
+<https://zadq.info/about>. Apache-2.0 — see `LICENSE` and `NOTICE`.

package/dist/brand.d.ts

@@ -0,0 +1 @@
+export declare const BRAND = "ZadQ";

package/dist/brand.js

@@ -0,0 +1,3 @@
+// Single brand constant: a rename is an edit here plus DNS. No brand string
+// appears anywhere else in src/ (scripts/check-brand.mjs enforces it).
+export const BRAND = 'ZadQ';

package/dist/explorer.d.ts

@@ -0,0 +1,47 @@
+import { type Freshness, type Verdict, type VerdictSubject } from './verdict.js';
+/** Display signal for one endpoint row. Everything uncertain is "unknown". */
+export type VerificationSignal = {
+    state: 'human-backed' | 'revoked' | 'unknown';
+    /** Assurance grade of the positive claim (e.g. "G"), when present. */
+    assuranceLevel?: string;
+    /** RFC 3339 time of the last re-check, when present. */
+    verifiedAt?: string;
+    /** The cadence promise the verdict carries ("re-checked every N hours"). */
+    recheckEveryHours?: number;
+    /** Local freshness of the verdict against its own cadence promise. */
+    freshness: Freshness;
+};
+/** The signal rendered when no verdict is available. Rendering never blocks on it. */
+export declare const UNKNOWN_SIGNAL: VerificationSignal;
+export type VerificationClientOptions = {
+    /** Base URL of the verification service (its free path is used). */
+    baseUrl: string;
+    /**
+     * Optional verification public key (base64, 32 raw bytes). When provided, a
+     * positive claim whose signature fails the local check is demoted to
+     * "unknown". When the runtime cannot check signatures, the verdict is used
+     * as delivered — the listing keeps working either way.
+     */
+    publicKey?: string;
+    /** Fetch timeout in milliseconds (default 3000). */
+    timeoutMs?: number;
+    /** In-memory cache TTL in milliseconds (default 5 minutes; 0 disables). */
+    cacheTtlMs?: number;
+};
+export type VerificationClient = {
+    /** Resolves the display signal for one endpoint. Never rejects. */
+    signalFor(subject: VerdictSubject): Promise<VerificationSignal>;
+};
+/**
+ * Creates a small client for explorer listings: per-endpoint signal with an
+ * in-memory TTL cache (positive and "unknown" results alike, so an
+ * unreachable service is not re-queried on every row render).
+ */
+export declare function createVerificationClient(options: VerificationClientOptions): VerificationClient;
+/**
+ * Maps a verdict (or its absence) to the display signal, optionally checking
+ * the signature of positive claims locally. Exported for callers that already
+ * hold a verdict — e.g. one delivered inline in a `PaymentRequired` extension
+ * (extension.ts) or by a webhook.
+ */
+export declare function toSignal(verdict: Verdict | undefined, publicKey?: string): Promise<VerificationSignal>;

package/dist/explorer.js

@@ -0,0 +1,76 @@
+// Explorer-side integration: resolve the verification signal for x402
+// endpoints a listing displays, next to the traffic metrics it already shows.
+//
+// The free verification path is consumed anonymously and is never charged
+// for. Graceful degradation, by design: a listing keeps rendering exactly as
+// before when no verification response is available — the signal degrades to
+// "unknown", it never becomes an error state, a spinner or a blocked row.
+import { canonicalPayTo, fetchVerdict, freshness, verifyVerdictSignature, } from "./verdict.js";
+/** The signal rendered when no verdict is available. Rendering never blocks on it. */
+export const UNKNOWN_SIGNAL = { state: 'unknown', freshness: 'unknown' };
+/**
+ * Creates a small client for explorer listings: per-endpoint signal with an
+ * in-memory TTL cache (positive and "unknown" results alike, so an
+ * unreachable service is not re-queried on every row render).
+ */
+export function createVerificationClient(options) {
+    const ttl = options.cacheTtlMs ?? 300_000;
+    const cache = new Map();
+    async function resolve(subject) {
+        const verdict = await fetchVerdict(options.baseUrl, subject, options.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs });
+        return toSignal(verdict, options.publicKey);
+    }
+    return {
+        async signalFor(subject) {
+            // One cache entry per endpoint, whatever spelling of an EVM address the
+            // listing passes (checksum and lowercase name the same account).
+            const key = [
+                subject.chain,
+                canonicalPayTo(subject.chain, subject.payTo),
+                subject.resourceUrl,
+            ].join('\u0000');
+            const hit = cache.get(key);
+            if (hit !== undefined && Date.now() - hit.at <= ttl) {
+                return hit.signal;
+            }
+            const signal = await resolve(subject);
+            if (ttl > 0) {
+                cache.set(key, { at: Date.now(), signal });
+            }
+            return signal;
+        },
+    };
+}
+/**
+ * Maps a verdict (or its absence) to the display signal, optionally checking
+ * the signature of positive claims locally. Exported for callers that already
+ * hold a verdict — e.g. one delivered inline in a `PaymentRequired` extension
+ * (extension.ts) or by a webhook.
+ */
+export async function toSignal(verdict, publicKey) {
+    if (verdict === undefined) {
+        return UNKNOWN_SIGNAL;
+    }
+    if (verdict.outcome === 'human_backed' && publicKey !== undefined) {
+        const check = await verifyVerdictSignature(verdict, publicKey);
+        if (check === 'invalid') {
+            // An unverified positive claim is not displayed; the row still renders.
+            return UNKNOWN_SIGNAL;
+        }
+    }
+    switch (verdict.outcome) {
+        case 'human_backed':
+            return {
+                state: 'human-backed',
+                ...(verdict.assuranceLevel !== undefined && { assuranceLevel: verdict.assuranceLevel }),
+                ...(verdict.verifiedAt !== undefined && { verifiedAt: verdict.verifiedAt }),
+                recheckEveryHours: verdict.recheckEveryHours,
+                freshness: freshness(verdict),
+            };
+        case 'revoked':
+            return { state: 'revoked', freshness: 'unknown' };
+        default:
+            // `stale` and `no_signal` both display as "unknown".
+            return UNKNOWN_SIGNAL;
+    }
+}

package/dist/extension.d.ts

@@ -0,0 +1,169 @@
+import type { Verdict } from './verdict.js';
+/**
+ * The identity policy a seller advertises on its 402 response, following the
+ * bIP-0002 profile — sub-profile `bip-0002/0-seller`, the canonical v0 seller
+ * object (MintID canonical set `canonical-2026-09-24b`, restated in
+ * test/fixtures). It makes ONE claim and carries exactly these fields; the
+ * schema is closed, so anything else inside it fails the canonical check.
+ * v0 seller rail: the endpoint (chain-qualified `payTo` + resource URL) is
+ * bound to an accountable, verified operator — without revealing who.
+ */
+export type IdentityPolicy = {
+    /** What the signal claims. v0 ships seller-endpoint accountability only. */
+    claim: 'seller-endpoint-accountability';
+    /** Minimum assurance grade the attestation meets, e.g. "G". */
+    assuranceAtLeast: string;
+    /** Free verification path where any party can fetch the current signed verdict. */
+    verifyUrl: string;
+    /**
+     * Optional inline copy of the latest signed verdict, so counterparties can
+     * check the claim locally (verdict.ts#verifyVerdictSignature) without any
+     * round-trip. Refresh it on your side at the cadence the verdict itself
+     * promises; a missing or outdated copy simply degrades to "check later or
+     * show unknown".
+     */
+    verdict?: Verdict;
+};
+/**
+ * The vendor's invitation to its counterparties — the trust perimeter
+ * . It is a vendor stance, not protocol, so it never rides inside
+ * `identityPolicy` (whose canonical object makes one claim only): it
+ * has its own extension key next to it. `welcome`: any agent pays as usual and
+ * attested ones are welcome; `preferred`: the vendor prefers attested
+ * counterparties — an agent's client may surface it. Neither changes the
+ * payment flow, and this snippet never enforces anything: an agent that
+ * ignores the block pays exactly as before. A vendor that REQUIRES attested
+ * agents does not express it here at all — that is the complete v1 policy
+ * (`extensions.mintid_identity`, profile `bip-0002/1`) declared by a vendor
+ * that runs its own verifier; until that line exists, required is not offered.
+ */
+export type PerimeterInvitation = {
+    attestation: 'welcome' | 'preferred';
+    /** Where an agent operator starts its own attestation (public page, https). */
+    attestUrl: string;
+};
+/**
+ * Minimal shape of an x402 `PaymentRequired` (HTTP 402) JSON body. The
+ * payment entries stay whatever your x402 stack produces; this snippet only
+ * touches `extensions`.
+ */
+export type PaymentRequiredBody = {
+    x402Version: number;
+    error?: string;
+    accepts: unknown[];
+    extensions?: Record<string, unknown>;
+};
+/** Extension key defined by the bIP-0002 profile for the identity policy. */
+export declare const IDENTITY_POLICY_EXTENSION = "identityPolicy";
+/** The vendor-owned extension key the trust-perimeter invitation rides under. */
+export declare const PERIMETER_EXTENSION = "trustPerimeter";
+/**
+ * Seller side: returns a copy of the 402 body with the identity policy
+ * attached under `extensions.identityPolicy`. Existing extensions are
+ * preserved. Only the canonical fields are emitted, so the object always
+ * validates against the closed v0 seller schema whatever else the caller's
+ * policy value carried.
+ */
+export declare function withIdentityPolicy<T extends PaymentRequiredBody>(body: T, policy: IdentityPolicy): T;
+/**
+ * Counterparty side: reads the identity policy from a 402 body, if present
+ * and well-formed. Returns `undefined` otherwise — an absent or malformed
+ * policy is a normal state, and the payment flow proceeds unchanged. Fields
+ * outside the canonical object are dropped, never fatal.
+ */
+export declare function readIdentityPolicy(body: PaymentRequiredBody): IdentityPolicy | undefined;
+/**
+ * Vendor side: returns a copy of the 402 body with the trust-perimeter
+ * invitation attached under its own key. `identityPolicy` is untouched.
+ */
+export declare function withPerimeterInvitation<T extends PaymentRequiredBody>(body: T, invitation: PerimeterInvitation): T;
+/**
+ * Agent side: reads the vendor's invitation, if present and well-formed.
+ * Anything else — absent, malformed, or a value this line does not offer
+ * (such as "required") — reads as `undefined`, and the payment proceeds
+ * exactly as before.
+ */
+export declare function readPerimeterInvitation(body: PaymentRequiredBody): PerimeterInvitation | undefined;
+/**
+ * One entry of a v1 claim policy, byte-shaped as the frozen verifier
+ * contract's `ClaimPredicate`: a claim name, a value, an optional operator.
+ * The canonical v1 schema admits exactly the predicate family the proof core
+ * proves; nothing else validates.
+ */
+export type ClaimPolicyEntry = {
+    claim: string;
+    value: string | number | boolean;
+    operator?: '>=';
+};
+/**
+ * The complete v1 object `extensions.mintid_identity` (profile `bip-0002/1`,
+ * MintID canonical set `canonical-2026-09-26`, restated in test/fixtures):
+ * the verifying party's challenge endpoint, the claim policy the paying
+ * party must prove, an optional issuer policy and the session mode. Policy
+ * only, never invariants — no lifetime, no nonce, no audience, no price —
+ * and closed: anything else inside it fails the canonical check.
+ *
+ * Meaning, exactly as the profile defines it: a party that pays here can
+ * prove, to the challenge endpoint's own verifier, that an accountable
+ * operator stands behind it, within the declared bounds. The seller's OWN
+ * credential is not carried on the 402 at all — the seller's holder
+ * presents it to the verification service's challenges (holder/), and the
+ * verdict on the endpoint stays readable at `identityPolicy.verifyUrl`.
+ */
+export type MintidIdentityPolicy = {
+    profile: 'bip-0002/1';
+    /** The verifying party's challenge front (https), resolving to its own verifier's `createChallenge`. */
+    challenge_endpoint: string;
+    claim_policy: ClaimPolicyEntry[];
+    issuer_policy?: {
+        accepted_issuer_ids?: string[];
+        issuer_state_minimum?: 'ACTIVE' | 'ENHANCED_MONITORING';
+    };
+    session_mode: 'token_exchange';
+};
+/** Extension key defined by the bIP-0002 profile for the complete v1 object. */
+export declare const MINTID_IDENTITY_EXTENSION = "mintid_identity";
+/**
+ * Returns a copy of the 402 body with the canonical v1 object attached under
+ * `extensions.mintid_identity`. Only the canonical fields are emitted (each
+ * claim entry reduced to `{claim, operator?, value}`), so the object always
+ * validates against the closed v1 schema whatever else the caller's value
+ * carried. `identityPolicy` and every other key are untouched.
+ */
+export declare function withMintidIdentity<T extends PaymentRequiredBody>(body: T, policy: MintidIdentityPolicy): T;
+/**
+ * Counterparty side: reads the v1 object from a 402 body, if present and
+ * well-formed for this profile. Anything else — absent, another profile,
+ * a non-https challenge endpoint, an empty policy — reads as `undefined`,
+ * and the payment proceeds exactly as before.
+ */
+export declare function readMintidIdentity(body: PaymentRequiredBody): MintidIdentityPolicy | undefined;
+/**
+ * What a seller's middleware knows about the credential its holder keeps
+ * (holder/): the same states the operator's dashboard shows — never a key.
+ */
+export type CredentialState = 'none' | 'offered' | 'held' | 'expired' | 'revoked';
+/**
+ * The seller's identity declaration during the coexistence window of the
+ * bIP-0002 profile (§3A.4): the v0 object `identityPolicy` always, and the
+ * v1 object `mintid_identity` next to it only while the seller's holder
+ * holds its credential and the seller declares a v1 policy. Both keys may
+ * coexist on one 402; a counterparty that understands v1 prefers it, one
+ * that does not pays exactly as before. A middleware without a credential
+ * emits v0 only: nothing blocks.
+ */
+export type SellerIdentity = {
+    /** The canonical v0 object: the verdict path on this endpoint (always emitted). */
+    policy: IdentityPolicy;
+    /** The canonical v1 object, emitted only while `credential` is `held`. */
+    v1?: MintidIdentityPolicy;
+    /** What the holder reports; anything but `held` keeps the 402 on v0 only. */
+    credential?: CredentialState;
+};
+/**
+ * Seller side: one call for the coexistence window. Returns a copy of the
+ * 402 body with `identityPolicy` attached and, when the credential is held
+ * and a v1 policy is declared, `mintid_identity` beside it. Neither object
+ * ever absorbs a field of the other; both stay canonical and closed.
+ */
+export declare function withSellerIdentity<T extends PaymentRequiredBody>(body: T, identity: SellerIdentity): T;