@me2em/core 1.0.0-rc.2 → 1.0.0-rc.4

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.
@@ -0,0 +1,70 @@
1
+ // wallet-binding.ts
2
+ //
3
+ // Default wallet-binding verification for the payment layer
4
+ // (Документ 2 v1.2 §6): the core default combines the attestation
5
+ // token's signature with subject agreement and address equality.
6
+ // Chain adapters MAY override `PaymentAdapter.verifyWalletBinding` with
7
+ // stronger checks (on-curve validation, Mode 1 re-derivation from
8
+ // `subjectWalletPath`); Mode 2 verifiers (root public key only) accept
9
+ // path↔address consistency on the strength of the Identity signature —
10
+ // a deliberate v1 limitation. Transport layers (x402) never invoke this
11
+ // implicitly; regulatory / compliance flows call it explicitly.
12
+ //
13
+ // This module lives apart from payment.ts so the runtime module graph
14
+ // stays acyclic: payment.ts is a leaf, attestation.ts imports payment.ts
15
+ // (fail-closed wallet validation), and only this module pulls in the
16
+ // Attestation class itself.
17
+
18
+ import { Attestation } from './attestation.js';
19
+ import type { WalletDescriptor, WalletEntityRef } from './payment.js';
20
+
21
+ /** Options for the default {@link verifyWalletBinding}. */
22
+ export interface WalletBindingOptions {
23
+ /**
24
+ * Ed25519 public key of the attestation ISSUER — the root Identity
25
+ * public key for Identity→Handle attestations, the Handle public key
26
+ * for Handle→SubHandle attestations.
27
+ */
28
+ issuerPublicKey: Uint8Array;
29
+ }
30
+
31
+ /**
32
+ * Default wallet-binding check (v1.2 §6): answers "does this attestation
33
+ * bind this wallet to this entity?".
34
+ *
35
+ * Order of the three fail-closed checks:
36
+ *
37
+ * 1. **Signature** — the token verifies against the expected issuer
38
+ * public key (`Attestation.verifySignature`).
39
+ * 2. **Subject agreement** — the attestation must attest THIS entity
40
+ * (`payload.subjectId === entity.id`); without it any valid
41
+ * attestation of a different subject would "bind" its wallet here.
42
+ * 3. **Address equality** — `payload.subjectWallet` string-equals the
43
+ * wallet address to be bound; an attestation without wallet fields
44
+ * fails (undefined never equals an address).
45
+ *
46
+ * On-curve checking and path re-derivation are NOT part of the default —
47
+ * they are adapter overrides (Mode 1) per v1.2 §6/§6.1.
48
+ *
49
+ * @returns `false` on every failed check — never throws for a
50
+ * verification mismatch (only structural token errors surface as
51
+ * `AttestationError` from `verifySignature`/decode, per its contract).
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * const ok = await verifyWalletBinding(wallet, entity, attestation, {
56
+ * issuerPublicKey: rootIdentity.getPublicKey(),
57
+ * });
58
+ * ```
59
+ */
60
+ export async function verifyWalletBinding(
61
+ wallet: WalletDescriptor,
62
+ entity: WalletEntityRef,
63
+ attestation: Attestation,
64
+ opts: WalletBindingOptions
65
+ ): Promise<boolean> {
66
+ const signatureOk = await Attestation.verifySignature(attestation.token, opts.issuerPublicKey);
67
+ if (!signatureOk) return false;
68
+ if (attestation.payload.subjectId !== entity.id) return false;
69
+ return attestation.payload.subjectWallet === wallet.address;
70
+ }