@atumlabs/payment-gateway-client 2.2.0 → 3.0.1

package/dist/signing.d.ts

@@ -0,0 +1,223 @@
+import { P as PaymentRequest } from './sender-auth-verify-C-Q-zvAO.js';
+export { A as AuthTerms, a as ParsedPermit, V as VerifiedSenderAuth, b as VerifyPaymentRequestExpectations, c as VerifyResult, v as verifyPaymentRequest } from './sender-auth-verify-C-Q-zvAO.js';
+
+/** Options for {@link signDeclaration}. */
+interface SignDeclarationOptions {
+    /** EVM chain id used in the verificationMethod DID. Defaults to 1. */
+    chainId?: number;
+    /**
+     * Override for proof.created, as an ISO-8601 UTC string. Defaults to now.
+     *
+     * The value is inside the signed payload, so pass it explicitly wherever a signature has to
+     * be reproducible — conformance fixtures and tests — and leave it unset in production.
+     */
+    created?: string;
+}
+/** A W3C Data Integrity proof as it appears on a signed PaymentRequest. */
+interface DeclarationProof {
+    type: string;
+    created: string;
+    verificationMethod: string;
+    proofPurpose: string;
+    jws?: string;
+    proofValue?: string;
+}
+/** A PaymentRequest with its `@context` and `proof` attached. */
+type SignedDeclaration = PaymentRequest & {
+    '@context': string[];
+    proof: DeclarationProof;
+};
+/**
+ * The identity a verified document proof yields.
+ *
+ * Discriminated, and deliberately so. The two cases carry different weight, and flattening
+ * them into one shape is how a self-asserted key gets read as a proven one:
+ *
+ * - `recovered-secp256k1`: the address is recovered FROM the signature, so it is self-evident
+ *   proof of which key signed.
+ * - `self-asserted-ed25519`: the public key is taken from the document's own
+ *   verificationMethod. A successful verify proves the signature matches that key — NOT that
+ *   the key belongs to anyone in particular. Bind it to a trusted source before relying on it.
+ *
+ * This mirrors the sealed Signer interface in the Go verifier, which exists for the same
+ * reason.
+ */
+type VerifiedDeclarationSigner = {
+    kind: 'recovered-secp256k1';
+    address: string;
+    did: string;
+} | {
+    kind: 'self-asserted-ed25519';
+    publicKey: Uint8Array;
+    did: string;
+};
+/** What {@link verifyDeclaration} reports about a valid proof. */
+interface VerifyDeclarationResult {
+    /** The verified identity. Discriminate on `kind` before reading it. */
+    signer: VerifiedDeclarationSigner;
+    /** The cryptosuite that produced the proof. */
+    cryptosuite: string;
+}
+/**
+ * Signs a 32-byte digest with the holder's secp256k1 key.
+ *
+ * This surface takes a signer rather than a private key, deliberately. A hex key forces raw key
+ * material into a JavaScript string that cannot be zeroized, is copied on assignment, and lands
+ * in heap snapshots and any log line that stringifies the surrounding object — and it locks out
+ * every custodian, since a holder whose key sits in a KMS, an HSM, or a provider like Turnkey
+ * has no key to hand over. Implement this over the provider's own digest-signing call, or use
+ * {@link signerFromEthersWallet} for a local key.
+ *
+ * Same shape as the SenderSigner seam this package already uses for the transfer authorization,
+ * and as the Go client's Secp256k1Signer.
+ */
+interface DeclarationSigner {
+    /** The 0x address this signer's key derives to; it becomes the did:pkh verificationMethod. */
+    getAddress(): Promise<string> | string;
+    /**
+     * Signs a 32-byte digest, returning 65 bytes of `r || s || v` with **v ∈ {0, 1}**.
+     *
+     * v is the raw recovery id. The alignment the W3C suite expects is applied once downstream,
+     * and a signature whose v is already 27 or 28 is REFUSED — applying it twice recovers a
+     * different address, i.e. a proof that verifies as somebody else.
+     */
+    signDigest(digest: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+/**
+ * Adapts an ethers `Wallet` to {@link DeclarationSigner}, for the local-key case.
+ *
+ * ethers owns the key material; this borrows only the digest-signing capability. It signs a RAW
+ * digest, not `signMessage`: the proof is over a canonicalized document hash, so the EIP-191
+ * prefix would produce a signature that does not verify as a Data Integrity proof.
+ */
+declare const signerFromEthersWallet: (wallet: unknown) => DeclarationSigner;
+/**
+ * Signs a PaymentRequest document, returning a copy with `@context` and `proof` attached.
+ *
+ * The proof covers the URDNA2015-canonicalized document, so it is stable across key reordering
+ * and whitespace. Signing artifacts and the deprecated credential carriers are excluded from
+ * that hash by the signing library, and the verifier strips the identical set.
+ *
+ * One consequence worth knowing: canonicalization drops terms the declaration `@context` does
+ * not define, so a field this package's types do not model travels inside the signed document
+ * without being covered by the proof. Making a new field tamper-evident means adding it to the
+ * context, not just to the payload.
+
+ */
+declare function signDeclaration(request: PaymentRequest, signer: DeclarationSigner, options?: SignDeclarationOptions): Promise<SignedDeclaration>;
+/**
+ * Verifies a signed PaymentRequest document and recovers its signer.
+ *
+ * THROWS if the proof is missing, malformed, does not verify, or — for a recovery-based
+ * suite — recovers a signer other than the one the document claims. Callers branch on the
+ * exception, not on a return value.
+ *
+ * This checks the document proof only. It says nothing about whether sender_auth authorizes a
+ * transfer, nor whether the originator's identity is established.
+ */
+declare function verifyDeclaration(signed: SignedDeclaration): Promise<VerifyDeclarationResult>;
+/**
+ * Computes the canonical content hash of a PaymentRequest.
+ *
+ * This is the value an identity envelope binds as its `challenge`, so a caller assembling one
+ * needs the same hash the gateway will recompute.
+ */
+declare function computeRequestHash(request: PaymentRequest): Promise<string>;
+
+declare const PAYMENT_REQUEST_ENVELOPE_CONTEXT_URL = "https://schemas.atum.network/declarations/PaymentRequestEnvelope/v1/context.jsonld";
+declare const PAYMENT_REQUEST_ENVELOPE_TYPE = "PaymentRequestEnvelope";
+
+/**
+ * Signs a 32-byte digest with the holder's secp256k1 key.
+ *
+ * Takes a signer, never a private key, so a holder whose key sits in a KMS, an HSM, or a
+ * custodial provider can sign without it entering this process. `signerFromEthersWallet` covers
+ * a local key.
+ *
+ * Returns 65 bytes of `r || s || v` with **v ∈ {0, 1}**. A signature whose v is already 27 or
+ * 28 is refused: applying the alignment twice recovers a different holder.
+ */
+interface EnvelopeSigner {
+    signDigest(digest: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+/**
+ * A holder-signed PaymentRequestEnvelope.
+ *
+ * Typed rather than returned as `unknown`: a caller that has to cast cannot be told by the
+ * compiler when a field it reads stops existing, and the fields below are the ones the gateway
+ * checks — so getting them wrong is a rejected payment, not a type error at the call site.
+ */
+interface SignedPaymentRequestEnvelope {
+    '@context': string[];
+    type: string[];
+    holder: string;
+    verifiableCredential: unknown[];
+    proof: {
+        type: string;
+        created: string;
+        verificationMethod: string;
+        proofPurpose: string;
+        /** Binds the envelope to one request; the gateway recomputes it. */
+        challenge: string;
+        /** Binds the envelope to one environment. */
+        domain: string;
+        /** Present for secp256k1 proofs. */
+        jws?: string;
+        /** Present for ed25519 proofs. */
+        proofValue?: string;
+    };
+}
+/** Inputs to {@link buildEnvelope}. Every field is required unless noted. */
+interface BuildEnvelopeOptions {
+    /**
+     * The originator's issuer-signed credentials, each a fully-formed W3C VC with its own
+     * `@context` and `proof`.
+     *
+     * MUST be non-empty: the envelope schema requires at least one and the verifier rejects an
+     * empty bag. An originator that holds no credential about itself cannot build one yet.
+     */
+    holderVCs: unknown[];
+    /** Signs the holder proof. See {@link EnvelopeSigner}. */
+    signer: EnvelopeSigner;
+    /** The holder's did:pkh identifier, e.g. `did:pkh:eip155:1:0xabc…`. */
+    holder: string;
+    /** The DID URL naming the holder's signing key, usually `holder + '#blockchainAccountId'`. */
+    verificationMethod: string;
+    /**
+     * The cross-request replay binding: the payment's `request_hash`, which the gateway recomputes over the inner request. Use `computeRequestHash` to derive it.
+     */
+    challenge: string;
+    /**
+     * The cross-environment replay binding: the network-wide, env-suffixed did:web identifier
+     * (e.g. `did:web:devnet.atum.network`). NOT service-bound — the envelope has several
+     * consumers.
+     */
+    domain: string;
+    /**
+     * Anchors `proof.created`, as an ISO-8601 UTC string. Defaults to now.
+     *
+     * It is inside the signed payload, so pass it explicitly wherever a signature must be
+     * reproducible.
+     */
+    created?: string;
+}
+/** Builds the did:pkh identifier for a wallet account on a CAIP-2 chain. */
+declare function didForAccount(chainId: string, account: string): string;
+/** Builds the DID URL naming a wallet account's signing key. */
+declare function verificationMethodForAccount(chainId: string, account: string): string;
+/**
+ * Wraps the originator's credentials in a holder-signed PaymentRequestEnvelope and returns the
+ * envelope JSON.
+ *
+ * It does NOT sign the inner PaymentRequest. That is a separate artifact — see
+ * `signDeclaration` — and the verifier checks the two independently, asserting the inner signer
+ * is this envelope's holder. Sign both with the same key, or the gateway rejects the pair.
+ */
+declare function buildEnvelope(options: BuildEnvelopeOptions): Promise<SignedPaymentRequestEnvelope>;
+/**
+ * Convenience over {@link buildEnvelope} for the common case: derive the holder DID and
+ * verification method from the wallet's chain and address.
+ */
+declare function buildEnvelopeForAccount(chainId: string, account: string, options: Omit<BuildEnvelopeOptions, 'holder' | 'verificationMethod'>): Promise<SignedPaymentRequestEnvelope>;
+
+export { type BuildEnvelopeOptions, type DeclarationSigner, type EnvelopeSigner, PAYMENT_REQUEST_ENVELOPE_CONTEXT_URL, PAYMENT_REQUEST_ENVELOPE_TYPE, type SignDeclarationOptions, type SignedDeclaration, type SignedPaymentRequestEnvelope, type VerifiedDeclarationSigner, type VerifyDeclarationResult, buildEnvelope, buildEnvelopeForAccount, computeRequestHash, didForAccount, signDeclaration, signerFromEthersWallet, verificationMethodForAccount, verifyDeclaration };