@correntelabs/beeai-ashlar-bridge 1.0.0

package/dist/src/x402/mandate.d.ts

@@ -0,0 +1,449 @@
+import { type Ed25519Signer } from './manifest-sig.js';
+export declare const MANDATE_VERSION = "x402-mandate/1";
+/** Recipient sentinel: an EXPLICIT, signed opt-in to an unconstrained payee set. Must be the SOLE element. */
+export declare const ANY_RECIPIENT = "*";
+/** Accountant sentinel selecting Model B: spend entries are co-signed by their payees; no single accountant key. */
+export declare const PAYEES_ACCOUNTANT = "payees";
+export interface Mandate {
+    v: typeof MANDATE_VERSION;
+    /** base64url Ed25519 public key of the PRINCIPAL that issued this grant. */
+    issuer: string;
+    /** The agent payer identity this grant authorizes. Bound to the payment's payer. */
+    subject: string;
+    /** Asset the cap and amounts are denominated in. */
+    asset: string;
+    /** Maximum CUMULATIVE spend, integer minor units as a decimal string. */
+    cap: string;
+    /** Optional maximum for any SINGLE payment, integer minor units. MUST be <= cap. */
+    perPayment?: string;
+    /**
+     * Allowed payees. Under Model B ('payees' accountant) each recipient MUST
+     * itself be a base64url Ed25519 key — the identity IS the attesting key.
+     * Exactly [ANY_RECIPIENT] is a signed opt-in to any payee; mixing '*' with
+     * named recipients is invalid.
+     */
+    recipients: string[];
+    /**
+     * THE TRUST ROOT FOR ACCOUNTING: either one base64url Ed25519 key (Model A
+     * — this exact key must sign every committed head) or PAYEES_ACCOUNTANT
+     * (Model B). A verifier MUST take the accountant from here, never from the
+     * presenter.
+     */
+    accountant: string;
+    /** Human-readable purpose, carried verbatim. */
+    purpose: string;
+    /** Expiry, strict RFC 3339 UTC (must end in 'Z'). */
+    notAfter: string;
+    /** Uniqueness — distinguishes two otherwise-identical grants. */
+    nonce: string;
+    /**
+     * DELEGATION: the sha256:<hex> digest of the PARENT mandate this grant is
+     * carved from. Absent on a root grant. A delegated grant is signed by the
+     * parent's SUBJECT and may only NARROW every bound (see
+     * issueDelegatedMandate / verifyDelegationChain).
+     */
+    parent?: string;
+}
+export interface SignedMandate {
+    mandate: Mandate;
+    alg: 'Ed25519';
+    /** base64url Ed25519 signature over DS_TAG || jcsCanonical(mandate). */
+    sig: string;
+}
+/**
+ * One split leg: an ADDITIONAL recipient paid by the same payment. Mirrors an
+ * entry of x402's `PaymentRequirements.extra.splits` (platform fees, revenue
+ * share, referral commissions), reduced to the two fields authority cares
+ * about. All legs share the payment's `asset`; a scheme that splits ACROSS
+ * assets is out of scope here and MUST NOT be modelled with this field.
+ */
+export interface PaymentSplit {
+    recipient: string;
+    amount: string;
+}
+/**
+ * One payment presented for authorization against a Mandate.
+ *
+ * MULTI-PAYEE: `recipient`/`amount` are the primary (`payTo`) leg; `splits`
+ * carries any ADDITIONAL legs of the SAME payment, matching x402's model where
+ * `extra.splits` is additional to `payTo`. Absent or empty `splits` is exactly
+ * today's single-leg behaviour, so nothing existing changes. When splits ARE
+ * present, EVERY leg's recipient is scope-checked and the per-payment bound and
+ * cap bind the TOTAL across all legs — a payment cannot pay eight strangers, or
+ * move more than its cap, by moving the money into legs the check never reads.
+ */
+export interface MandatePayment {
+    payer: string;
+    recipient: string;
+    asset: string;
+    amount: string;
+    /** 'sha256:...' of the mandate this payment was made under — bound into the payment preimage. */
+    mandateDigest: string;
+    /** When the payment settled, strict RFC 3339 UTC. Advisory only — expiry is judged on the verifier's clock. */
+    at?: string;
+    /** ADDITIONAL legs beyond `recipient`/`amount`. Absent = single-leg. */
+    splits?: PaymentSplit[];
+}
+export interface MandateVerdict {
+    ok: boolean;
+    reasons: string[];
+    warnings: string[];
+}
+/** The digest a payment binds to (domain-separated). */
+export declare function mandateDigest(m: Mandate): string;
+/** Sign a mandate with the principal's key. Rejects malformed grants, perPayment>cap, and a signer that is not the issuer. */
+export declare function issueMandate(m: Mandate, signer: Ed25519Signer): SignedMandate;
+/** Verify the issuer's signature over the (domain-separated) grant, offline. False on any structural or crypto failure. */
+export declare function verifyMandateSignature(sm: SignedMandate): boolean;
+/**
+ * The offline authority check for ONE payment against a Mandate. Total —
+ * returns a verdict, never throws — and judges expiry on the VERIFIER's clock,
+ * not the payer's self-asserted `at`.
+ *
+ * MULTI-PAYEE (`payment.splits`): a payment may pay several recipients at once
+ * (x402 `extra.splits`). EVERY leg is scope-checked, and the per-payment bound
+ * and the cap bind the TOTAL across all legs. Without that, a mandate scoped to
+ * one merchant would authorize a payment that also pays eight strangers, and a
+ * cap would bind only the primary leg while the real outflow exceeded it — the
+ * exact failure this object exists to prevent, re-entering through a scheme
+ * feature. Absent/empty `splits` is byte-for-byte today's behaviour.
+ *
+ * HONESTY: this bounds ONE payment's total. The spend LOG still records a
+ * single (recipient, amount) per entry, so a multi-leg payment's per-leg
+ * breakdown is not represented in the Merkle log — cumulative accounting sees
+ * the primary leg only. Log the TOTAL as the entry amount until SpendEntry
+ * grows legs, and treat per-leg cumulative attribution as unsolved.
+ */
+export declare function checkPayment(sm: SignedMandate, payment: MandatePayment, opts?: {
+    now?: () => number;
+}): MandateVerdict;
+/** One committed spend under a mandate. Bound to the mandate + asset, and chained to the prior root (append-only). */
+export interface SpendEntry {
+    mandateDigest: string;
+    asset: string;
+    paymentId: string;
+    recipient: string;
+    amount: string;
+    /** Running total after this payment. Equals previous cumulative + amount. */
+    cumulative: string;
+    /** Merkle root of the log BEFORE this entry — an edit/reorder/insert breaks the chain. */
+    priorRoot: string;
+}
+/** An append-only, mandate-bound, Merkle-committed record of spend under one mandate. */
+export declare class SpendLog {
+    private readonly mandateDigestHex;
+    private readonly asset;
+    private entries;
+    private ids;
+    constructor(mandateDigestHex: string, asset: string);
+    add(paymentId: string, recipient: string, amount: string): this;
+    get size(): number;
+    all(): SpendEntry[];
+    total(): string;
+    root(): string;
+    prove(index: number): {
+        entry: SpendEntry;
+        index: number;
+        size: number;
+        proof: string[];
+    };
+    /**
+     * Produce the committed head over the current (root, total) at a monotonic
+     * seq. This is the ONLY blessed committing path: the root and total are
+     * derived from the entries the log actually holds, never handed in — an
+     * accountant signing a (root, total) it did not derive is signing blind.
+     */
+    commit(seq: number, accountant: Ed25519Signer, at: string): SignedCommitment;
+}
+/** Verify one spend entry belongs to a committed spend-log root, holding nothing else. */
+export declare function verifySpendEntry(entry: SpendEntry, index: number, size: number, proof: string[], root: string): boolean;
+/**
+ * Verify a presented spend history is INTERNALLY sound against a mandate:
+ * authenticated grant, every entry bound to THIS mandate + asset, scope and
+ * per-payment re-checked, duplicate paymentIds refused, append-only chain
+ * verified, running totals gap-free, total within cap.
+ *
+ * HONESTY: a truncated PREFIX of the true history passes all of this. This
+ * function alone is tamper-evidence, not completeness — completeness comes
+ * from a committed head (Model A) with a freshness floor.
+ */
+export declare function verifySpendWithinCap(sm: SignedMandate, entries: SpendEntry[]): MandateVerdict;
+export declare const COMMIT_VERSION = "x402-mandate-commit/1";
+/** A signed statement that "as of seq, the spend log for this mandate has this root and this total." */
+export interface SpendCommitment {
+    v: typeof COMMIT_VERSION;
+    mandateDigest: string;
+    /** The Ed25519 key that signs this head. MUST equal the mandate's accountant to be acceptable. */
+    accountant: string;
+    /** Monotonic per mandate — a later head MUST carry a strictly greater seq. */
+    seq: number;
+    root: string;
+    total: string;
+    at: string;
+}
+export interface SignedCommitment {
+    commitment: SpendCommitment;
+    alg: 'Ed25519';
+    sig: string;
+}
+/** Sign a committed head. Prefer SpendLog.commit, which derives root/total from real entries. */
+export declare function commitHead(c: SpendCommitment, accountant: Ed25519Signer): SignedCommitment;
+/**
+ * Verify a head is SELF-consistent: signed by the key it names as accountant.
+ * Self-consistency is not authorization — verifySpendAgainstCommitment also
+ * requires that key to equal the MANDATE's accountant (the trust root).
+ */
+export declare function verifyCommitment(sc: SignedCommitment): boolean;
+/** LAYER 2: the digest anchored on-chain / in a transparency log. */
+export declare function commitmentAnchorDigest(sc: SignedCommitment): string;
+/**
+ * LAYER 2 calldata (the evidence lane's x402note/1 grammar). Carries the
+ * mandate + seq so a scanner can find the highest anchored head for a mandate,
+ * and `by=<accountant>` so anchors are attributable without fetching the head.
+ * Anchoring is permissionless: an anchor proves WHEN, never honesty.
+ */
+export declare function commitmentAnchorCalldata(sc: SignedCommitment): string;
+/** Verify an on-chain anchor's calldata commits to exactly THIS head. Pair with the tx's block timestamp for the WHEN. */
+export declare function verifyCommitmentAnchor(sc: SignedCommitment, calldata: string): boolean;
+/**
+ * MODEL A cap check against a committed head. The accountant is taken from the
+ * MANDATE (the trust root) — a presenter can never name their own. The
+ * presented entries must reproduce the committed root AND total.
+ *
+ * `lastSeq` is REQUIRED: pass the highest seq you have previously accepted for
+ * this mandate (from your own state, or the highest anchored seq you read from
+ * Layer 2). Passing `null` means you have no freshness floor — the check still
+ * runs, but the verdict carries a loud warning: without a floor you get
+ * tamper-evidence, NOT completeness, because an old validly-signed head plus
+ * its prefix log passes (first-contact truncation).
+ */
+export declare function verifySpendAgainstCommitment(sm: SignedMandate, entries: SpendEntry[], sc: SignedCommitment, lastSeq: number | null): MandateVerdict;
+/**
+ * The counterparty's POST-SETTLE check (MUST-rule 2): the payment it just
+ * accepted is INCLUDED under a NEW committed head strictly newer than the one
+ * it saw before settling. This is what forces the head to advance per payment
+ * — an authorized payment that is never committed is otherwise invisible.
+ */
+export declare function verifyPaymentCommitted(sm: SignedMandate, paymentId: string, proof: {
+    entry: SpendEntry;
+    index: number;
+    size: number;
+    proof: string[];
+}, newHead: SignedCommitment, prevSeq: number, 
+/** OPTIONAL but STRONGLY RECOMMENDED: the fields decoded from the settled
+ * artifact. When supplied, the included entry's recipient/asset/amount MUST
+ * equal them — this is what stops an agent committing a truthful-looking
+ * head over an amount smaller than what actually settled (see §7/§13). */
+settled?: {
+    recipient: string;
+    asset: string;
+    amount: string;
+}): MandateVerdict;
+export declare const PAYEE_ATT_VERSION = "x402-mandate-payee/1";
+/**
+ * A payee's signed acknowledgement that it received a specific payment under a
+ * mandate. The payee identity IS its Ed25519 key (enforced by the mandate's
+ * shape when accountant='payees'), so there is no prose-level payee↔key
+ * binding for an agent to spoof: the signature verifies against the entry's
+ * recipient, or it does not verify.
+ */
+export interface PayeeAttestation {
+    v: typeof PAYEE_ATT_VERSION;
+    mandateDigest: string;
+    paymentId: string;
+    /** The payee — the base64url Ed25519 key that is BOTH the recipient identity and the signer. */
+    payee: string;
+    asset: string;
+    amount: string;
+    at: string;
+}
+export interface SignedPayeeAttestation {
+    attestation: PayeeAttestation;
+    alg: 'Ed25519';
+    sig: string;
+}
+/** The payee signs "I received this payment under this mandate." Signer's key must BE the payee identity. */
+export declare function attestPayment(a: PayeeAttestation, payee: Ed25519Signer): SignedPayeeAttestation;
+/** Verify a payee attestation's signature against the payee identity itself, offline. */
+export declare function verifyPayeeAttestation(spa: SignedPayeeAttestation): boolean;
+/**
+ * MODEL B check: every presented entry must be backed by an authentic
+ * attestation signed by the RECIPIENT ITSELF (identity == key). Requires the
+ * mandate's accountant to be 'payees'.
+ *
+ * WHAT THIS PROVES: no fabricated entries — an agent cannot invent a payment a
+ * payee never acknowledged.
+ * WHAT IT DOES NOT PROVE: completeness. Dropping an entry AND its attestation
+ * passes. Do not present this check alone as omission-proof — completeness in
+ * Model B comes from reconcilePayeeEvidence below, run against payee evidence
+ * the verifier gathered independently of the agent.
+ */
+export declare function verifySpendWithPayeeAttestations(sm: SignedMandate, entries: SpendEntry[], attestations: SignedPayeeAttestation[]): MandateVerdict;
+/** The digest a payee attestation is anchored under. */
+export declare function payeeAttestationAnchorDigest(spa: SignedPayeeAttestation): string;
+/**
+ * A payee anchors ITS OWN evidence (the x402note/1 grammar; `@<paymentId>`
+ * keeps attestation anchors distinguishable from head anchors' `#<seq>`). This
+ * is what makes an omitted payment publicly discoverable: the agent controls
+ * its log, but it does not control the payee's anchor.
+ */
+export declare function payeeAttestationAnchorCalldata(spa: SignedPayeeAttestation): string;
+/**
+ * MODEL B OMISSION-RESISTANCE — the payee-evidence reconciler. `evidence` is
+ * the set of payee attestations the VERIFIER gathered INDEPENDENTLY (from the
+ * payees, or by scanning their anchors) — never from the agent. Then:
+ *
+ *   1. the presented entries must all be payee-backed (no fabrication), AND
+ *   2. every valid attestation for THIS mandate must appear in the log — an
+ *      attested payment with no entry is the OMISSION, caught by the party who
+ *      cannot un-know it was paid, AND
+ *   3. the attested floor (sum over all attested payments, whether logged or
+ *      not) must be within cap — a short log cannot hide over-spend the payees
+ *      can prove.
+ *
+ * Hostile-input hygiene: attestations that fail signature verification or
+ * belong to other mandates are IGNORED with a warning (a stranger cannot DoS a
+ * verdict with junk); two authentic attestations from one payee for one
+ * paymentId with different facts = payee equivocation, refused loudly.
+ */
+export declare function reconcilePayeeEvidence(sm: SignedMandate, entries: SpendEntry[], evidence: SignedPayeeAttestation[]): MandateVerdict;
+/** The parent's subject carves a narrowed child grant. Refuses any widening. */
+export declare function issueDelegatedMandate(child: Mandate, parentSm: SignedMandate, delegator: Ed25519Signer): SignedMandate;
+/**
+ * Walk a delegation chain root→leaf, entirely offline: every link signed,
+ * every hop narrowing, the leaf usable exactly like any mandate. Returns the
+ * ROOT ISSUER — the human origin, recoverable at any depth.
+ */
+export declare function verifyDelegationChain(chain: SignedMandate[]): MandateVerdict & {
+    rootIssuer?: string;
+};
+export declare const BINDING_VERSION = "x402-mandate-binding/1";
+/** The bytes32 nonce an EIP-3009 TransferWithAuthorization MUST carry for this (mandate, payment). */
+export declare function eip3009BindingNonce(mandateDigestStr: string, paymentId: string): string;
+/** The uint256 nonce (decimal string) a Permit2 PermitTransferFrom MUST carry. */
+export declare function permit2BindingNonce(mandateDigestStr: string, paymentId: string): string;
+/** The InvoiceID (uppercase 64-hex, XRPL convention) a Payment tx MUST carry. */
+export declare function xrplBindingInvoiceId(mandateDigestStr: string, paymentId: string): string;
+export type BindingScheme = 'eip3009' | 'permit2' | 'xrpl';
+/**
+ * Verify the binding FROM THE SETTLED ARTIFACT: pass the value read out of the
+ * settled authorization/tx (the EIP-3009 nonce, the Permit2 nonce, the XRPL
+ * InvoiceID) and the claimed (mandate, paymentId). True iff the slot commits to
+ * exactly this pair. Total — false on anything malformed.
+ */
+export declare function verifyPaymentBinding(scheme: BindingScheme, settledValue: string, mandateDigestStr: string, paymentId: string): boolean;
+/** The fields a counterparty MUST decode OUT of the settled artifact (never presented). */
+export interface SettledTransfer {
+    scheme: BindingScheme;
+    /** The binding slot: EIP-3009 nonce / Permit2 nonce / XRPL InvoiceID, read from the settled tx. */
+    slot: string;
+    /** from / Account. */
+    payer: string;
+    /** to / Destination. */
+    recipient: string;
+    /** token contract / XRPL currency. */
+    asset: string;
+    /** value / delivered_amount, integer minor units. */
+    amount: string;
+    /**
+     * ADDITIONAL legs decoded from the SAME settled artifact (a multi-payee
+     * split: x402 `extra.splits`, one on-chain transfer per leg). A verifier
+     * that decodes only the primary transfer of a split settlement under-counts
+     * the outflow — decode EVERY transfer the artifact performed, or the cap
+     * binds nothing. Absent = single-transfer settlement.
+     */
+    splits?: PaymentSplit[];
+}
+/**
+ * THE ENFORCEMENT the §7 binding alone cannot give: the binding slot commits
+ * only to (mandate, paymentId), NOT to amount/recipient/asset. A cap that binds
+ * only self-asserted amounts binds nothing on a rail the agent controls. This
+ * check reads the ACTUAL transferred fields out of the settled artifact and
+ * runs the full §6 authority check on THEM — so an agent that settles 1,000,000
+ * cannot log amount='1'. A counterparty deriving cumulative-spend conclusions
+ * MUST call this, not verifyPaymentBinding alone. Total — never throws.
+ */
+export declare function verifySettledPayment(sm: SignedMandate, settled: SettledTransfer, paymentId: string, opts?: {
+    now?: () => number;
+}): MandateVerdict;
+export interface ParsedHeadAnchor {
+    anchorDigest: string;
+    mandateDigest: string;
+    seq: number;
+    /** Absent on pre-hardening anchors (the historic 2026-08-19 anchor has no by=). */
+    by?: string;
+}
+/**
+ * Parse an on-chain head-anchor calldata. Tolerates the historic pre-`by=`
+ * grammar so scanners can read every anchor ever made. Returns null on
+ * anything that is not a head anchor (payee anchors use `@`, not `#`).
+ */
+export declare function parseCommitmentAnchorCalldata(calldata: string): ParsedHeadAnchor | null;
+/**
+ * From a batch of decoded anchor calldatas (a scanner's haul), the highest
+ * anchored seq for a mandate — the FIRST-CONTACT FRESHNESS FLOOR to pass as
+ * lastSeq. When the mandate names a single-key accountant, anchors not
+ * carrying that `by=` are ignored (permissionless anchoring means strangers
+ * can anchor anything; only the accountant's own anchors set the floor).
+ * Returns null when no qualifying anchor exists — which a verifier must treat
+ * as "no floor", not "seq 0".
+ */
+/** An anchor read off-chain, paired with the head its digest points at. */
+export interface AnchorEvidence {
+    /** The `x402note/1` calldata as read from the chain. */
+    calldata: string;
+    /**
+     * The head retrieved out-of-band for this anchor's digest. Absent when the
+     * content could not be fetched — such an anchor is NOT floor-eligible.
+     */
+    head?: SignedCommitment;
+}
+/**
+ * RUNG 3, done properly: derive a freshness floor ONLY from anchors whose
+ * content has been retrieved and re-verified.
+ *
+ * WHY THIS EXISTS: anchoring is permissionless and `by=` is unauthenticated
+ * plaintext, while the accountant's key is public (it is named in the grant).
+ * So `highestAnchoredSeq` — which trusts the seq printed in calldata — is
+ * POISONABLE: a stranger anchors `…#999999999;by=<the real accountant>` and
+ * every honest head afterwards is refused as a rollback. That failure is not a
+ * missed omission, it is an honest record permanently refused.
+ *
+ * Here an anchored seq is a POINTER, never a fact. For an anchor to move the
+ * floor, all of the following must hold: the calldata parses and names THIS
+ * mandate; `by=` equals the mandate's accountant; the head was retrieved; the
+ * anchor digest recomputes over that head; the head's signature verifies; and
+ * the head itself names this mandate, this accountant, and this seq. Anything
+ * short of that is ignored with a warning — which can only LOWER the floor
+ * toward the tamper-evidence downgrade, never raise it.
+ */
+export declare function verifiedAnchoredSeq(sm: SignedMandate, anchors: AnchorEvidence[]): {
+    seq: number | null;
+    reasons: string[];
+    warnings: string[];
+};
+/**
+ * ⚠️ UNVERIFIED floor: trusts the seq printed in permissionless calldata and is
+ * therefore POISONABLE by any chain writer (see verifiedAnchoredSeq). Retained
+ * for scanning/equivocation surveys where a claimed seq is a lead to follow,
+ * NOT for deriving the floor a verifier will refuse honest heads against.
+ */
+export declare function highestAnchoredSeq(calldatas: string[], mandateDigestStr: string, accountant?: string): number | null;
+/**
+ * The accountant-side check the delegation section's honest limit calls for:
+ * given a parent grant and the set of children issued under it, every child
+ * must be an authentic, correctly-narrowing child of THIS parent, digests
+ * distinct, and the SUM of child caps must fit within the parent cap.
+ *
+ * HONESTY: this binds over the set it is GIVEN. Only the party that registers
+ * delegations (the accountant, or the delegator's own ledger) knows the set is
+ * complete — a verifier handed a partial set gets a partial answer. That is
+ * the same completeness shape as spend, and the same parties close it.
+ */
+export declare function verifySiblingBudget(parentSm: SignedMandate, children: SignedMandate[]): MandateVerdict;
+/** Authorize one payment against the LEAF of a verified delegation chain. */
+export declare function checkDelegatedPayment(chain: SignedMandate[], payment: MandatePayment, opts?: {
+    now?: () => number;
+}): MandateVerdict & {
+    rootIssuer?: string;
+};