@elisym/commerce 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @elisym/commerce
+
+The elisym commerce protocol: sell digital goods to people and AI agents, paid directly to the merchant's wallet, with the catalog and orders on Nostr and no platform in the middle.
+
+```bash
+npm install @elisym/commerce @elisym/pay-core nostr-tools @solana/kit @solana-program/system @solana-program/token @solana-program/memo decimal.js-light
+```
+
+## What is in it
+
+| Piece               | Kind                   | Signed by     | Functions                                                           |
+| ------------------- | ---------------------- | ------------- | ------------------------------------------------------------------- |
+| Payout addresses    | 10133 (NIP-A3)         | owner         | `buildPaytoEvent`, `parsePayto`, `verifyPaytoProof`                 |
+| Store authorization | 30490 (provisional)    | owner         | `buildStoreAuthEvent`, `buildStoreRevocationEvent`, `readStoreAuth` |
+| Store profile       | 0                      | store         | `buildStoreProfileEvent`, `parseStoreProfile`                       |
+| Product             | 30402 (NIP-99, Gamma)  | store         | `buildProductEvent`, `parseProduct`, `priceInSubunits`              |
+| Orders, receipts    | 16 / 17 in a gift wrap | buyer / store | `buildOrderMessage`, `wrapOrderMessage`, `unwrapOrderMessage`       |
+| Offer verification  | -                      | -             | `verifyOffer`, `evaluateOffer`, `isOfferPayout`                     |
+
+## The one rule
+
+A payment goes only to an address from the owner's kind 10133 event. Any other source of an address (a payment request, an x402 or MPP challenge) must match it:
+
+```ts
+import { isOfferPayout, verifyOffer } from '@elisym/commerce';
+
+const result = await verifyOffer(naddr, { fetchEvents }, { pageOrigin });
+if (!result.ok) throw new Error(result.message);
+if (!isOfferPayout(result.offer, caip19, challenge.payTo)) throw new Error('Not the merchant');
+```
+
+`fetchEvents` queries relays (at least two, so one relay cannot hide the newest payout event) or a resolver. Every event it returns is checked again for its signature, author and kind.
+
+On a server, pass `verifyOffer` a `fetch` that refuses private addresses: the merchant's domain comes from the store's own profile.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,643 @@
+import { ChainConfig, Asset } from '@elisym/pay-core';
+import { EventTemplate, NostrEvent, Filter } from 'nostr-tools';
+import { z } from 'zod';
+
+/** Store profile (NIP-01), signed by the store key. */
+declare const KIND_STORE_PROFILE = 0;
+/** Payout addresses (NIP-A3 `payto` plus the elisym `accept` extension), signed by the owner key. */
+declare const KIND_PAYTO = 10133;
+/**
+ * "Store key S acts for owner O", signed by the owner key. Addressable, `d` = the
+ * store pubkey.
+ *
+ * PROVISIONAL: the number is not registered yet (spec, open question 1). It is
+ * named in one place so that fixing it is a one-line change.
+ */
+declare const KIND_STORE_AUTH = 30490;
+/** Product listing (NIP-99, Gamma Markets), signed by the store key. */
+declare const KIND_PRODUCT = 30402;
+/** Inbox relays for gift-wrapped messages (NIP-17). */
+declare const KIND_INBOX_RELAYS = 10050;
+/** Order message inside a gift wrap: `type` 1 order, 2 payment request, 3 status (Gamma Markets). */
+declare const KIND_ORDER_MESSAGE = 16;
+/** Payment receipt inside a gift wrap (Gamma Markets). */
+declare const KIND_PAYMENT_RECEIPT = 17;
+/** NIP-09 deletion: an `a` tag on the owner's AUTH address revokes it, like `mode` revoked. */
+declare const KIND_DELETION = 5;
+declare const KIND_SEAL = 13;
+declare const KIND_GIFT_WRAP = 1059;
+/** Opt-in tag value that lists a product in the elisym aggregator. */
+declare const ELISYM_NETWORK_TAG = "elisym";
+/**
+ * What a payout wallet signs to prove it belongs to the owner. The owner pubkey
+ * and the CAIP-19 id are both inside, so a proof made for one owner or one asset
+ * cannot be replayed for another.
+ */
+declare const PAYTO_PROOF_PREFIX = "elisym-payto:v1";
+declare const DELIVERY_METHODS: readonly ["download", "license", "access", "webhook", "api"];
+type DeliveryMethod = (typeof DELIVERY_METHODS)[number];
+declare const ORDER_STATUSES: readonly ["pending", "confirmed", "completed", "cancelled"];
+type OrderStatus = (typeof ORDER_STATUSES)[number];
+/** Gamma Markets visibility values under which a product can be bought. */
+declare const PURCHASABLE_VISIBILITIES: readonly ["on-sale", "pre-order"];
+/** A payout address younger than this is flagged: the owner key may have been taken over. */
+declare const PAYOUT_COOLDOWN_SECS: number;
+/** How far in the future an event's `created_at` may sit before it is ignored. */
+declare const MAX_FUTURE_SKEW_SECS: number;
+declare const LIMITS: {
+    readonly MAX_ORDER_ID_LENGTH: 64;
+    readonly MAX_TAG_VALUE_LENGTH: 1024;
+    readonly MAX_CONTENT_LENGTH: number;
+    readonly MAX_ITEMS_PER_ORDER: 50;
+    readonly MAX_NIP05_DOCUMENT_BYTES: number;
+};
+
+interface Caip19 {
+    /** The full id, exactly as written. */
+    id: string;
+    caip2: string;
+    chain: ChainConfig;
+    /** The registry coin it names, on that chain's environment. */
+    asset: Asset;
+}
+/**
+ * Parse a CAIP-19 id for a coin the payment registry knows: `solana:<ref>/token:<mint>`
+ * or `eip155:<id>/erc20:<lowercase contract>`. Anything else - an unknown chain,
+ * a namespace that does not fit the chain, a coin the registry does not hold -
+ * is `undefined`: an asset nothing can pay in is not an asset.
+ */
+declare function parseCaip19(id: string): Caip19 | undefined;
+/**
+ * Whether a mixed-case EVM address carries a valid EIP-55 checksum. An address
+ * in one case has none to check and passes; a mixed-case one with a wrong
+ * checksum is a typo.
+ */
+declare function hasValidEvmChecksum(address: string): boolean;
+/**
+ * The one canonical spelling of a payout address on a chain, or `undefined` if it
+ * is not one. EVM addresses are lowercase on the wire, so every comparison is
+ * plain equality; a virtual (TIP-1022) address is refused, as the payment rail does.
+ */
+declare function canonicalPayoutAddress(chain: ChainConfig, address: string): string | undefined;
+
+/**
+ * The exact text a payout wallet signs for an `accept` tag. A Solana wallet signs
+ * its UTF-8 bytes with `signMessage`; an EVM wallet signs it with `personal_sign`
+ * (EIP-191).
+ */
+declare function paytoProofMessage(ownerPubkey: string, caip19: string): string;
+/**
+ * Whether `signature` proves that the wallet at `address` agreed to receive
+ * `caip19` payments for `ownerPubkey`.
+ *
+ * Encodings, one per family and nothing else: Solana - the 64-byte ed25519
+ * signature in base58, `address` the base58 public key; EVM - the 65-byte
+ * `r || s || v` signature as `0x` hex, as `personal_sign` returns it, `address`
+ * lowercase. Any malformed input is `false`, never a throw.
+ */
+declare function verifyPaytoProof(params: {
+    chain: ChainConfig;
+    address: string;
+    ownerPubkey: string;
+    caip19: string;
+    signature: string;
+}): boolean;
+/** keccak256("\x19Ethereum Signed Message:\n" + len(message) + message). */
+declare function eip191Hash(message: Uint8Array): Uint8Array;
+
+/** The keys a merchant's domain vouches for. */
+interface DomainKeys {
+    domain: string;
+    /**
+     * The NIP-05 name that was looked up (`_` for the domain itself). The answer
+     * vouches for that name only: a profile under another name cannot borrow it.
+     */
+    name: string;
+    storePubkey?: string;
+    ownerPubkey?: string;
+    source: 'nostr.json' | 'dns';
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * A public DNS name: lowercase labels, at least two, no IP literal, no port. The
+ * domain comes from a store's own profile - attacker-controlled - so nothing
+ * else is fetched.
+ */
+declare function isPublicHostname(hostname: string): boolean;
+/** Split `local@domain` (NIP-05; a bare domain means `_@domain`), lowercased, or `undefined`. */
+declare function splitNip05(identifier: string): {
+    local: string;
+    domain: string;
+} | undefined;
+/** The store (under `local`) and the owner (under `owner`) a `nostr.json` names. */
+declare function readNostrJson(document: unknown, local: string): Pick<DomainKeys, 'storePubkey' | 'ownerPubkey'>;
+/** `v=elisym1; owner=npub1...; store=npub1...` - the DNS record for sites that cannot serve `/.well-known`. */
+declare function readElisymTxt(record: string): Pick<DomainKeys, 'storePubkey' | 'ownerPubkey'>;
+interface ResolveDomainOptions {
+    /**
+     * Defaults to the global `fetch`. A SERVER (resolver, merchant node) must pass
+     * a fetch that refuses private addresses: the domain comes from a store's
+     * profile, and an unguarded fetch is an SSRF.
+     */
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    dohEndpoint?: string;
+}
+/**
+ * The keys `nip05` vouches for, from `/.well-known/nostr.json` and then from the
+ * `_elisym` TXT record. `undefined` when the domain answers neither - which is
+ * not the same as vouching for OTHER keys, and the caller keeps the two apart.
+ */
+declare function resolveDomainKeys(nip05: string, options?: ResolveDomainOptions): Promise<DomainKeys | undefined>;
+
+/** One payout address for one asset, as the owner published it. */
+interface PayoutTarget {
+    caip19: Caip19;
+    /** Canonical spelling (lowercase on EVM). */
+    address: string;
+    /** The wallet signed the proof message for this owner and asset, and it checks out. */
+    walletSigned: boolean;
+}
+interface PaytoInput {
+    /** NIP-A3 `payto` entries, e.g. `{ type: 'solana', authority: '<address>' }`. */
+    payto?: readonly {
+        type: string;
+        authority: string;
+    }[];
+    accept: readonly {
+        caip19: string;
+        address: string;
+        signature?: string;
+    }[];
+    /**
+     * The owner key that will sign the event. Required with any wallet signature:
+     * a proof made for another owner or asset is checked here, since every reader
+     * would drop that address.
+     */
+    ownerPubkey?: string;
+    createdAt?: number;
+}
+/** Build the owner's kind 10133 event. The caller signs it with the OWNER key. */
+declare function buildPaytoEvent(input: PaytoInput): EventTemplate;
+interface ParsedPayto {
+    targets: PayoutTarget[];
+    /** `accept` entries dropped: an unknown asset, a malformed address, or a proof that fails. */
+    rejected: {
+        tag: readonly string[];
+        reason: 'unknown_asset' | 'bad_address' | 'bad_proof';
+    }[];
+}
+/**
+ * The payout targets an owner's 10133 declares, from its `accept` tags only.
+ *
+ * A bare NIP-A3 `payto` tag names no asset and no network environment, so it is
+ * shown to generic clients but never paid to by elisym: a payment always goes to
+ * an `accept` address for the exact CAIP-19 id. An `accept` tag whose wallet
+ * proof is present but wrong is DROPPED, not downgraded - a wrong proof is
+ * evidence of a mistake or of tampering, and neither is an address to pay.
+ *
+ * The caller has already checked the event's signature and that its author is
+ * the owner.
+ */
+declare function parsePayto(event: Pick<NostrEvent, 'pubkey' | 'tags'>): ParsedPayto;
+
+type StoreAuthMode = 'self-host' | 'hosted' | 'revoked';
+interface StoreAuthInput {
+    storePubkey: string;
+    mode: Exclude<StoreAuthMode, 'revoked'>;
+    /** Hosted mode: who runs the store, e.g. `elisym.network`. */
+    operator?: string;
+    /** Unix seconds (NIP-40). Short windows limit the damage of a stolen store key. */
+    expiresAt?: number;
+    createdAt?: number;
+}
+/** `<kind>:<owner>:<store>`, the address a NIP-09 deletion names to revoke an AUTH. */
+declare function storeAuthAddress(ownerPubkey: string, storePubkey: string): string;
+/** Build the owner's authorization of a store key. The caller signs it with the OWNER key. */
+declare function buildStoreAuthEvent(input: StoreAuthInput): EventTemplate;
+/** Revoke a store key: the same address (`d`), `mode` revoked. Newest wins. */
+declare function buildStoreRevocationEvent(storePubkey: string, createdAt?: number): EventTemplate;
+type StoreAuthState = {
+    status: 'active';
+    mode: Exclude<StoreAuthMode, 'revoked'>;
+    operator?: string;
+} | {
+    status: 'revoked';
+} | {
+    status: 'expired';
+} | {
+    status: 'malformed';
+};
+/**
+ * What an owner's newest AUTH event for `storePubkey` says at `now`. The caller
+ * has checked the signature and the author, and picked the newest event for the
+ * address. An event whose `d` or `p` names another store is malformed, never active.
+ */
+declare function readStoreAuth(event: Pick<NostrEvent, 'kind' | 'tags'>, storePubkey: string, now?: number): StoreAuthState;
+
+interface StoreProfile {
+    name?: string;
+    about?: string;
+    picture?: string;
+    website?: string;
+    nip05?: string;
+    /** The owner pubkey the store points at (tag `owner`). One half of the two-way link. */
+    ownerPubkey?: string;
+}
+interface StoreProfileInput extends Omit<StoreProfile, 'ownerPubkey'> {
+    ownerPubkey: string;
+    createdAt?: number;
+}
+/** Build the store's kind 0. The caller signs it with the STORE key. */
+declare function buildStoreProfileEvent(input: StoreProfileInput): EventTemplate;
+/**
+ * Read a store's kind 0, or `undefined` when its content is not a JSON object.
+ * A field of the wrong type or past its limit is dropped on its own: other
+ * clients edit the same kind 0, and one odd field is not a missing profile.
+ */
+declare function parseStoreProfile(event: Pick<NostrEvent, 'content' | 'tags'>): StoreProfile | undefined;
+
+declare const FREQUENCIES: readonly ["hour", "day", "week", "month", "year"];
+declare const ENDPOINT_TYPES: readonly ["x402", "mpp"];
+type PriceFrequency = (typeof FREQUENCIES)[number];
+type EndpointType = (typeof ENDPOINT_TYPES)[number];
+interface ProductPrice {
+    /** Decimal string, exactly as published: never a float. */
+    amount: string;
+    /** ISO 4217, e.g. `USD`. */
+    currency: string;
+    /** Subscriptions only (NIP-99). */
+    frequency?: PriceFrequency;
+}
+interface Product {
+    storePubkey: string;
+    d: string;
+    title: string;
+    summary?: string;
+    description: string;
+    price: ProductPrice;
+    images: string[];
+    topics: string[];
+    /** Gamma Markets visibility; absent means on sale. */
+    visibility: string;
+    delivery?: DeliveryMethod;
+    /** Opted into the elisym aggregator (`["network", "elisym"]`). */
+    listedOnElisym: boolean;
+    /** HTTP 402 entry points for agents. Never trusted on their own: a challenge must pay a 10133 address. */
+    endpoints: {
+        type: EndpointType;
+        url: string;
+    }[];
+    /** CAIP-19 ids of the assets the store accepts. Addresses come from the owner's 10133 only. */
+    accept: string[];
+    createdAt: number;
+}
+declare const ProductInputSchema: z.ZodObject<{
+    d: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    price: z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+        frequency: z.ZodOptional<z.ZodEnum<["hour", "day", "week", "month", "year"]>>;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        currency: string;
+        frequency?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    }, {
+        amount: string;
+        currency: string;
+        frequency?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    }>;
+    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    topics: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    visibility: z.ZodDefault<z.ZodString>;
+    delivery: z.ZodOptional<z.ZodEnum<["download", "license", "access", "webhook", "api"]>>;
+    listedOnElisym: z.ZodDefault<z.ZodBoolean>;
+    endpoints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["x402", "mpp"]>;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "x402" | "mpp";
+        url: string;
+    }, {
+        type: "x402" | "mpp";
+        url: string;
+    }>, "many">>;
+    accept: z.ZodArray<z.ZodString, "many">;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    accept: string[];
+    d: string;
+    title: string;
+    description: string;
+    price: {
+        amount: string;
+        currency: string;
+        frequency?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    };
+    images: string[];
+    topics: string[];
+    visibility: string;
+    listedOnElisym: boolean;
+    endpoints: {
+        type: "x402" | "mpp";
+        url: string;
+    }[];
+    createdAt?: number | undefined;
+    summary?: string | undefined;
+    delivery?: "download" | "license" | "access" | "webhook" | "api" | undefined;
+}, {
+    accept: string[];
+    d: string;
+    title: string;
+    description: string;
+    price: {
+        amount: string;
+        currency: string;
+        frequency?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    };
+    createdAt?: number | undefined;
+    summary?: string | undefined;
+    images?: string[] | undefined;
+    topics?: string[] | undefined;
+    visibility?: string | undefined;
+    delivery?: "download" | "license" | "access" | "webhook" | "api" | undefined;
+    listedOnElisym?: boolean | undefined;
+    endpoints?: {
+        type: "x402" | "mpp";
+        url: string;
+    }[] | undefined;
+}>;
+type ProductInput = z.input<typeof ProductInputSchema>;
+/** Build a kind 30402 listing. The caller signs it with the STORE key. */
+declare function buildProductEvent(input: ProductInput): EventTemplate;
+/**
+ * Read a kind 30402 listing, or `undefined` when it lacks what a sale needs (a
+ * `d`, a title, a price). Unknown extras are ignored, so a plain NIP-99 listing
+ * from another client still reads - it just accepts nothing elisym can pay.
+ * The caller has checked the signature.
+ */
+declare function parseProduct(event: Pick<NostrEvent, 'kind' | 'pubkey' | 'tags' | 'content' | 'created_at'>): Product | undefined;
+declare function isPurchasable(product: Pick<Product, 'visibility'>): boolean;
+/** `30402:<store>:<d>`, the address an order's `item` tag names. */
+declare function productAddress(product: Pick<Product, 'storePubkey' | 'd'>): string;
+declare function encodeProductNaddr(product: Pick<Product, 'storePubkey' | 'd'>, relays?: string[]): string;
+interface ProductPointer {
+    storePubkey: string;
+    d: string;
+    relays: string[];
+}
+/** Decode a product `naddr`, or `undefined` when it is not one. */
+declare function decodeProductNaddr(naddr: string): ProductPointer | undefined;
+/**
+ * The price in `asset` subunits. Only a one-off `USD` price paid in a USD-pegged
+ * coin at 1:1 has one; any other pairing needs a quote (quoted mode), so it is
+ * refused here rather than converted at a guessed rate.
+ */
+declare function priceInSubunits(price: ProductPrice, asset: Asset): bigint;
+
+type Tags = readonly (readonly string[])[];
+
+interface OrderItem {
+    /** `30402:<store>:<d>` */
+    product: string;
+    quantity: number;
+}
+interface Money {
+    /** Decimal string, never a float. */
+    amount: string;
+    currency: string;
+}
+/** Buyer -> store: kind 16, type 1. */
+interface OrderRequest {
+    type: 'order';
+    storePubkey: string;
+    orderId: string;
+    items: OrderItem[];
+    total: Money;
+    email?: string;
+}
+/** Store -> buyer: kind 16, type 2 (quoted mode). `payload` is opaque here: the payer parses it with pay-core. */
+interface PaymentRequestMessage {
+    type: 'payment_request';
+    buyerPubkey: string;
+    orderId: string;
+    total: Money;
+    options: {
+        medium: string;
+        payload: string;
+    }[];
+}
+/** Store -> buyer: kind 16, type 3. Signed by the store, so it is the proof of purchase. */
+interface OrderStatusMessage {
+    type: 'status';
+    buyerPubkey: string;
+    orderId: string;
+    status: OrderStatus;
+    /** Store-supplied and unchecked: show it as text, or open it only as an `https:` link. */
+    delivery?: {
+        method: DeliveryMethod;
+        value: string;
+    };
+    /** The payment the store credited: amounts in subunits of the paid asset. */
+    receipt?: {
+        medium: string;
+        tx: string;
+        amount: string;
+        fee: string;
+    };
+    refund?: {
+        tx: string;
+        amount: string;
+    };
+}
+/**
+ * Buyer -> store: kind 17. A HINT that says where to look, never proof: the
+ * store verifies the transaction on chain before it credits anything.
+ */
+interface PaymentReceipt {
+    type: 'receipt';
+    storePubkey: string;
+    orderId: string;
+    payment: {
+        medium: string;
+        reference: string;
+        tx: string;
+    };
+}
+type OrderMessage = OrderRequest | PaymentRequestMessage | OrderStatusMessage | PaymentReceipt;
+/**
+ * The unsigned rumor for an order message. It is never published as is: it goes
+ * through `wrapOrderMessage`, which seals it with the sender's key.
+ */
+declare function buildOrderMessage(message: OrderMessage, createdAt?: number): EventTemplate;
+/**
+ * Read an unwrapped rumor as an order message, or `undefined` when it is not a
+ * well-formed one. Who SENT it is not checked here: `unwrapOrderMessage` gives
+ * the authenticated sender, and the caller matches it against the role (a status
+ * must come from the store, an order from the buyer who pays).
+ */
+declare function parseOrderMessage(rumor: {
+    kind: number;
+    tags: Tags;
+}): OrderMessage | undefined;
+
+interface WrappedOrderMessage {
+    /** Publish to the recipient's inbox relays (kind 10050). */
+    recipientWrap: NostrEvent;
+    /** The sender's own copy, for its history on another device. */
+    selfWrap: NostrEvent;
+    /** The rumor id: the same in both wraps, the key to dedupe on. */
+    rumorId: string;
+}
+/**
+ * Seal and gift-wrap an order message (NIP-59) for `recipientPubkey`, plus a copy
+ * for the sender. Relays see neither the content nor who talks to whom.
+ */
+declare function wrapOrderMessage(rumor: EventTemplate, senderSecretKey: Uint8Array, recipientPubkey: string): WrappedOrderMessage;
+interface UnwrappedOrderMessage {
+    rumorId: string;
+    /** Authenticated by the seal signature. */
+    senderPubkey: string;
+    /** The `p` tag of the rumor: who the message is addressed to. */
+    recipientPubkey: string;
+    createdAt: number;
+    message: OrderMessage;
+}
+/**
+ * Open a gift wrap addressed to `recipientSecretKey` and read the order message
+ * inside, or `undefined` for anything that is not a genuine one.
+ *
+ * This replaces `nip59.unwrapEvent`, which verifies nothing: it would take a seal
+ * signed by anyone and report whatever `pubkey` the rumor claims. Here the wrap
+ * and the seal signatures are checked, the rumor must claim the seal's signer,
+ * and its id must be its hash.
+ */
+declare function unwrapOrderMessage(wrap: NostrEvent, recipientSecretKey: Uint8Array): UnwrappedOrderMessage | undefined;
+
+/**
+ * A: the merchant's domain names both the store and the owner.
+ * B: a hosted name (e.g. `shop@elisym.shop`) - trust in the name registrar.
+ * C: keys only - the owner is pinned on first use.
+ */
+type TrustLevel = 'A' | 'B' | 'C';
+type OfferRefusal = 'bad_pointer' | 'product_missing' | 'product_not_on_sale' | 'store_profile_missing' | 'owner_unknown' | 'owner_mismatch' | 'owner_pin_mismatch' | 'domain_mismatch' | 'store_auth_missing' | 'store_auth_revoked' | 'store_auth_expired' | 'origin_mismatch' | 'payto_missing' | 'no_payout_for_accepted_assets';
+type OfferWarning = 
+/** The profile names a domain that did not vouch for both keys; trust fell back to level C. */
+'domain_unverified'
+/** The page embedding the widget is not on the merchant's domain. */
+ | 'origin_mismatch'
+/** No domain to compare the page with (levels B and C). */
+ | 'origin_unverifiable'
+/** The newest payout event is younger than the cool-down: the owner key may be in new hands. */
+ | 'payout_recently_changed'
+/** A payout address is not among the `knownPayouts` of earlier purchases. */
+ | 'payout_changed'
+/** A payout address carries no wallet proof. */
+ | 'payout_unsigned'
+/**
+ * No `pinnedOwnerPubkey` (a first purchase): nothing but this bundle names the
+ * owner, and a stolen store key can name a new one - at level A through a
+ * domain of its own. Pin the owner after paying and pass it next time.
+ */
+ | 'owner_unpinned';
+interface VerifiedOffer {
+    level: TrustLevel;
+    /** Levels A and B: the domain that vouches for the store. */
+    domain?: string;
+    storePubkey: string;
+    ownerPubkey: string;
+    profile: StoreProfile;
+    product: Product;
+    /** Where a payment for this offer may go: the owner's 10133 addresses for the assets the product accepts. */
+    payouts: PayoutTarget[];
+    paytoCreatedAt: number;
+    warnings: OfferWarning[];
+}
+type OfferVerification = {
+    ok: true;
+    offer: VerifiedOffer;
+} | {
+    ok: false;
+    refusal: OfferRefusal;
+    message: string;
+};
+/**
+ * The signed events one offer rests on, as relays (or a resolver) handed them
+ * over. Nothing here is trusted: every event is checked for its signature, its
+ * author and its kind before it counts, and extras are ignored.
+ */
+interface OfferBundle {
+    events: readonly NostrEvent[];
+    /**
+     * What the store's `nip05` domain vouches for: keys, `'unreachable'` when it
+     * answered nothing, or absent when the profile names no domain or it was not
+     * looked up. The answer is unsigned: take it from the client's own lookup,
+     * never from a resolver.
+     */
+    domain?: DomainKeys | 'unreachable';
+}
+interface EvaluateOfferOptions {
+    now?: number;
+    /** The origin of the page embedding the checkout (from `postMessage`'s `event.origin`). */
+    pageOrigin?: string;
+    /** Refuse, rather than warn, when the page is not on the merchant's domain - or its origin is not given. */
+    strictOrigin?: boolean;
+    /** Domains that issue hosted names (level B), e.g. `['elisym.shop']`. */
+    hostedDomains?: readonly string[];
+    /** The owner pinned at the first purchase from this store (TOFU). A new owner then needs a re-pin. */
+    pinnedOwnerPubkey?: string;
+    cooldownSecs?: number;
+    /**
+     * When an index (resolver, relay) first saw the newest 10133. The cool-down
+     * counts from the later of this and the event's own `created_at`, which the
+     * signer picks and can back-date.
+     */
+    paytoFirstSeenAt?: number;
+    /**
+     * Payout addresses paid at earlier purchases from this store (TOFU). A payout
+     * outside this set is flagged `payout_changed`, however old its event claims to be.
+     * Leave it out on a first purchase: an empty list flags every address.
+     */
+    knownPayouts?: readonly {
+        caip19: string;
+        address: string;
+    }[];
+}
+/**
+ * Verify an offer from its signed events (spec section 3, steps 2-7 and 9's
+ * address set). Pure: no network, so the same code runs on relay results and
+ * on a resolver bundle, and a test feeds it exactly what it needs.
+ *
+ * The protocol fee (step 8) is not read here: the payer reads it from chain with
+ * `@elisym/pay-core` when it builds the payment.
+ */
+declare function evaluateOffer(pointer: {
+    storePubkey: string;
+    d: string;
+}, bundle: OfferBundle, options?: EvaluateOfferOptions): OfferVerification;
+/**
+ * Step 9: whether a recipient named by ANY other source - a payment request, an
+ * x402 `payTo`, an MPP challenge - is one of the owner's payout addresses for
+ * that asset. Anything else must not be paid.
+ */
+declare function isOfferPayout(offer: VerifiedOffer, caip19: string, recipient: string): boolean;
+interface VerifyOfferDeps extends ResolveDomainOptions {
+    /**
+     * Query relays (or a resolver). The spec asks for at least two relays so one
+     * cannot hide the newest payout event; that is this function's job, and its
+     * results are all checked again here.
+     */
+    fetchEvents: (filters: Filter[]) => Promise<NostrEvent[]>;
+    /**
+     * Replace the domain lookup. It must be the client's OWN nostr.json / DoH
+     * lookup: the answer is unsigned, so a resolver's copy is not evidence.
+     */
+    resolveDomain?: (nip05: string) => Promise<DomainKeys | undefined>;
+}
+/** Collect an offer's events from relays and verify it (spec section 3). */
+declare function verifyOffer(naddr: string, deps: VerifyOfferDeps, options?: EvaluateOfferOptions): Promise<OfferVerification>;
+
+export { type Caip19, DELIVERY_METHODS, type DeliveryMethod, type DomainKeys, ELISYM_NETWORK_TAG, type EndpointType, type EvaluateOfferOptions, type FetchLike, KIND_DELETION, KIND_GIFT_WRAP, KIND_INBOX_RELAYS, KIND_ORDER_MESSAGE, KIND_PAYMENT_RECEIPT, KIND_PAYTO, KIND_PRODUCT, KIND_SEAL, KIND_STORE_AUTH, KIND_STORE_PROFILE, LIMITS, MAX_FUTURE_SKEW_SECS, type Money, ORDER_STATUSES, type OfferBundle, type OfferRefusal, type OfferVerification, type OfferWarning, type OrderItem, type OrderMessage, type OrderRequest, type OrderStatus, type OrderStatusMessage, PAYOUT_COOLDOWN_SECS, PAYTO_PROOF_PREFIX, PURCHASABLE_VISIBILITIES, type ParsedPayto, type PaymentReceipt, type PaymentRequestMessage, type PayoutTarget, type PaytoInput, type PriceFrequency, type Product, type ProductInput, type ProductPointer, type ProductPrice, type ResolveDomainOptions, type StoreAuthInput, type StoreAuthMode, type StoreAuthState, type StoreProfile, type StoreProfileInput, type TrustLevel, type UnwrappedOrderMessage, type VerifiedOffer, type VerifyOfferDeps, type WrappedOrderMessage, buildOrderMessage, buildPaytoEvent, buildProductEvent, buildStoreAuthEvent, buildStoreProfileEvent, buildStoreRevocationEvent, canonicalPayoutAddress, decodeProductNaddr, eip191Hash, encodeProductNaddr, evaluateOffer, hasValidEvmChecksum, isOfferPayout, isPublicHostname, isPurchasable, parseCaip19, parseOrderMessage, parsePayto, parseProduct, parseStoreProfile, paytoProofMessage, priceInSubunits, productAddress, readElisymTxt, readNostrJson, readStoreAuth, resolveDomainKeys, splitNip05, storeAuthAddress, unwrapOrderMessage, verifyOffer, verifyPaytoProof, wrapOrderMessage };