@chaindaddy/js 0.3.4 → 0.3.5

package/dist/api.d.ts

@@ -27,6 +27,50 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v2/public/signed/coins/{chain}/{symbol}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a coin's registration, signed
+         * @description **Not available yet.** It answers 404 until Chain Daddy turns it on; the record on
+         *     `chaindaddy.eth` and `verifyAnswer` arrive with it.
+         *
+         *     Whether a ticker is registered on a chain and which wallet holds the registration, signed by
+         *     Chain Daddy so you can check it wherever you got it from: a cache, a gateway, or another site's
+         *     server. `jws` is the signed answer (a compact JWS); `claims` repeats what it says so you can read
+         *     it, but trust only what you get out of `jws` after verifying it.
+         *
+         *     `status` is `registered` (the ticker has a verified page on that chain), `not_registered` (it
+         *     has none) or `removed` (it has one and Chain Daddy took it down). All three answer 200 and are
+         *     signed, so nobody between you and Chain Daddy can make up a missing registration. Only
+         *     `registered` carries `tokenAddress`, `crownId`, `holder`, `pageUrl` and, when known,
+         *     `registeredAt`.
+         *
+         *     To verify: split `jws` at the dots; the first part is the header (`alg` must be `EdDSA`, and
+         *     `kid` names the key), the second the claims. Check the Ed25519 signature over the first two
+         *     parts against the key with that `kid`, then check `typ` is `cd-answer+v1`, `iss` is
+         *     `https://chaindaddy.io` and `exp` has not passed. `verifyAnswer` in `@chaindaddy/js/verify` does
+         *     all of it. The keys are at `GET /api/v2/iap/jwks` (the keys receipts are signed with). They are
+         *     also named on `chaindaddy.eth`, in the text record `io.chaindaddy.signing-keys`: `ed25519:<x>`
+         *     entries separated by a space, the current key first, where `<x>` is the key's `x` in the key
+         *     set. Read the record yourself and you do not depend on this API for the keys either.
+         *
+         *     An answer is valid for 15 minutes (`exp`), and caches keep it for less than that. Keyless, the
+         *     same for every caller.
+         */
+        get: operations["getPublicSignedCoin"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v2/public/coins/{chain}/{symbol}/apps": {
         parameters: {
             query?: never;
@@ -138,7 +182,8 @@ export interface paths {
         /**
          * Receipt signing keys (JWKS)
          * @description The Ed25519 public keys receipts are signed with (the current key and the previous one), as a JSON Web Key Set.
-         *     Match a receipt's `kid` header to a key and verify its EdDSA signature offline.
+         *     Match a receipt's `kid` header to a key and verify its EdDSA signature offline. Signed answers
+         *     (`GET /api/v2/public/signed/coins/{chain}/{symbol}`) are signed with the same keys.
          */
         get: operations["getIapJwks"];
         put?: never;
@@ -1496,6 +1541,73 @@ export interface components {
             /** @description Machine-readable error code */
             code?: string;
         };
+        /** @description A signed answer and what it says. Trust `claims` only as read out of `jws` after verifying it. */
+        PublicSignedAnswer: {
+            /** @description The signed answer: a compact JWS (header, claims and signature, base64url, joined by dots), signed with Ed25519 (`alg` `EdDSA`) by the key its header's `kid` names */
+            jws: string;
+            claims: components["schemas"]["SignedAnswerClaims"];
+        };
+        /** @description What a signed answer says. The same object is the payload of `jws`. */
+        SignedAnswerClaims: {
+            /**
+             * @description Who signed it. Always `https://chaindaddy.io`.
+             * @example https://chaindaddy.io
+             */
+            iss: string;
+            /**
+             * @description What kind of signed document this is. Always `cd-answer+v1`; a store receipt, signed by the same keys, is `iap-receipt+v1`.
+             * @enum {string}
+             */
+            typ: "cd-answer+v1";
+            /**
+             * Format: int64
+             * @description When it was signed, in Unix seconds
+             */
+            iat: number;
+            /**
+             * Format: int64
+             * @description When it stops being valid, in Unix seconds, 15 minutes after `iat`. Do not act on it after this.
+             */
+            exp: number;
+            /**
+             * @description What the answer is about. `registration` is a ticker's registration on a chain.
+             * @enum {string}
+             */
+            kind: "registration";
+            /**
+             * @description CAIP-2 chain ID
+             * @example eip155:8453
+             */
+            chainId: string;
+            /**
+             * @description Chain key
+             * @example base
+             */
+            chain: string;
+            /** @description The ticker: as registered when `status` is `registered`, otherwise the one asked about, in upper case. Tickers match in any case, so compare without regard to case. */
+            symbol: string;
+            /**
+             * @description `registered`: the ticker has a verified page on the chain. `not_registered`: it has none. `removed`: it has one, and Chain Daddy took it down.
+             * @enum {string}
+             */
+            status: "registered" | "not_registered" | "removed";
+            /** @description The registered token's address (lowercase on EVM chains). Only when `status` is `registered`. */
+            tokenAddress?: string;
+            /**
+             * Format: int64
+             * @description The registration's ID on that chain. Only when `status` is `registered`.
+             */
+            crownId?: number;
+            /** @description The wallet that holds the registration (lowercase on EVM chains). Only when `status` is `registered`. */
+            holder?: string;
+            /**
+             * Format: date-time
+             * @description When the registration was made. Only when `status` is `registered`, and left out when not known.
+             */
+            registeredAt?: string;
+            /** @description The coin's page on chaindaddy.io. Only when `status` is `registered`. */
+            pageUrl?: string;
+        };
         IapError: {
             /** @description Human-readable description */
             error: string;
@@ -3147,6 +3259,96 @@ export interface operations {
             };
         };
     };
+    getPublicSignedCoin: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Chain key, lowercase, as in the page's own address (e.g. `base`, `solana`). A numeric chain ID answers 404. */
+                chain: string;
+                /** @description The coin's ticker (letters and digits, any case) */
+                symbol: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The signed answer, whatever the status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicSignedAnswer"];
+                };
+            };
+            /** @description The request came with the user agent of an AI or LLM crawler, and no cached answer was there to serve instead. Never sent to a browser or to a server using its own user agent. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "ai_bot_blocked",
+                     *       "message": "AI/LLM scraping is not permitted. Use our API with a developer-tier API key for programmatic access."
+                     *     }
+                     */
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description An unknown chain, or a ticker that is not letters and digits. Not signed; there is nothing to attest. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "not_found",
+                     *       "code": "not_found",
+                     *       "message": "Not found."
+                     *     }
+                     */
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description More than 400 requests in a minute from one IP address, across the whole API. Never cached. */
+            429: {
+                headers: {
+                    /** @description Seconds to wait before trying again */
+                    "Retry-After"?: number;
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Too many requests. Please try again later.",
+                     *       "code": "rate_limit_exceeded",
+                     *       "message": "Too many requests. Please try again later."
+                     *     }
+                     */
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The answer could not be read or signed right now. Never cached, never signed; try again. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "unavailable",
+                     *       "code": "unavailable",
+                     *       "message": "Unavailable right now. Try again."
+                     *     }
+                     */
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     listPublicCoinApps: {
         parameters: {
             query?: never;
@@ -5231,7 +5433,8 @@ export interface operations {
             };
             /**
              * @description `STORE_KEY_REQUIRED`: called with a signed-in session instead of a store key. `SCOPE_REQUIRED`: the key
-             *     lacks `orders:write`. `STORE_NOT_LIVE`: the store is paused or its plan lapsed. `SELLER_TERMS_REQUIRED`:
+             *     lacks `orders:write`. `STORE_NOT_LIVE`: the store is paused or its plan lapsed, or (`reason`
+             *     `owner_changed`) its page has a new owner who has not opened it yet. `SELLER_TERMS_REQUIRED`:
              *     the wallet that opened the store has not signed the Seller Terms
              */
             403: {
@@ -5447,7 +5650,8 @@ export interface operations {
             /**
              * @description `STORE_KEY_REQUIRED`: called with a signed-in session instead of a store key. `SCOPE_REQUIRED`: the
              *     key lacks `orders:write`. `CHECKOUT_SESSION_WALLET`: the session names another wallet.
-             *     `IAP_PLAN_REQUIRED` or `STORE_NOT_LIVE`: the store's plan lapsed or the store is paused.
+             *     `IAP_PLAN_REQUIRED` or `STORE_NOT_LIVE`: the store's plan lapsed or the store is paused, or (`reason`
+             *     `owner_changed`) its page has a new owner who has not opened it yet.
              *     `SESSION_REQUIRED`: the session's item belongs to an installed app
              */
             403: {

package/dist/cd.js

@@ -1,4 +1,4 @@
-"use strict";(()=>{var R="0.3.4";function C(t){let e="";for(let i of t)e+=String.fromCharCode(i);return btoa(e).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}function w(){return C(crypto.getRandomValues(new Uint8Array(32)))}function T(t,e,i,o,r){let u=n=>{if(n&&typeof n=="object"&&n.type===t)try{i(n)}catch{}},l=n=>{n.origin===e&&(!r||n.source===r)&&u(n.data)};window.addEventListener("message",l);let a=null;if(o&&typeof BroadcastChannel=="function"&&e===location.origin)try{a=new BroadcastChannel(o),a.onmessage=n=>u(n.data)}catch{a=null}return()=>{window.removeEventListener("message",l),a?.close()}}var y={get(t){try{return sessionStorage.getItem(t)}catch{return null}},set(t,e){try{sessionStorage.setItem(t,e)}catch{}},remove(t){try{sessionStorage.removeItem(t)}catch{}}};var F="https://api.chaindaddy.io",G={"https://api.chaindaddy.io":"https://chaindaddy.io/_oauth/authorize","https://staging-api.chaindaddy.io":"https://staging.chaindaddy.io/_oauth/authorize"},b="cd-signin",U="cd:signin",v="cd.signin",_=300;async function K(t){let e=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(t));return C(new Uint8Array(e))}function W(t="openid"){let e=t.split(/\s+/).filter(Boolean);return(e.includes("openid")?e:["openid",...e]).join(" ")}async function Y(t,e,i){let o=new URLSearchParams({response_type:"code",client_id:e.clientId,redirect_uri:e.redirectUri,scope:W(t.scope),state:e.state,nonce:e.nonce,code_challenge:await K(e.verifier),code_challenge_method:"S256"});return t.claims&&o.set("claims",typeof t.claims=="string"?t.claims:JSON.stringify(t.claims)),`${i}?${o}`}function A(t,e){return{code:e,codeVerifier:t.verifier,state:t.state,nonce:t.nonce,issuer:t.issuer,clientId:t.clientId,redirectUri:t.redirectUri}}var m;function k(t){let e=(t.issuer??F).replace(/\/$/,""),i=t.authorizeUrl??G[e];if(!i)return Promise.reject(new Error("authorizeUrl is required for this issuer"));if(!t.clientId||!t.redirectUri)return Promise.reject(new Error("clientId and redirectUri are required"));if(m&&!m.popup.closed)return m.popup.focus(),m.waiting;let o={state:w(),nonce:w(),verifier:w(),issuer:e,clientId:t.clientId,redirectUri:t.redirectUri};y.set(v,JSON.stringify(o));let r=window.open("",b,"popup,width=480,height=720"),u=(async()=>{let l=await Y(t,o,i);if(!r)return location.assign(l),null;r.location.href=l;let a=new URL(t.redirectUri,location.href).origin;return new Promise((n,c)=>{let s,d=()=>{g(),clearInterval(h),clearTimeout(s)},g=T(U,a,p=>{p.state===o.state&&(d(),y.remove(v),typeof p.error=="string"&&p.error?c(new Error(p.error)):p.iss!==e?c(new Error("the answer came from another issuer")):typeof p.code!="string"||!p.code?c(new Error("the answer carried no code")):n(A(o,p.code)))},b,r),h=setInterval(()=>{r.closed&&(clearInterval(h),s=setTimeout(()=>{d(),c(new Error("closed"))},_))},_);t.signal?.addEventListener("abort",()=>{d(),c(new Error("aborted"))})})})();if(r){m={popup:r,waiting:u};let l=()=>{m&&m.popup===r&&(m=void 0)};u.then(l,l)}return u}async function L(){let t=new URLSearchParams(location.search),e={type:U,code:t.get("code"),state:t.get("state"),iss:t.get("iss"),error:t.get("error")};if(window.name===b){try{window.opener?.postMessage(e,location.origin)}catch{}try{let r=new BroadcastChannel(b);r.postMessage(e),r.close()}catch{}return window.close(),null}let i=y.get(v);y.remove(v);let o=i?JSON.parse(i):null;if(!o||e.state!==o.state)throw new Error("the sign-in state does not match: start again");if(e.error)throw new Error(e.error);if(e.iss!==o.issuer)throw new Error("the answer came from another issuer");if(!e.code)throw new Error("the answer carried no code");return A(o,e.code)}async function M(t){let e=await fetch(`${t.issuer}/api/v2/oauth/token`,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"authorization_code",code:t.code,redirect_uri:t.redirectUri,client_id:t.clientId,code_verifier:t.codeVerifier})}),i=await e.json();if(!e.ok)throw new Error(`${i.error??e.status}: ${i.error_description??""}`.trim());return i}var J='<svg viewBox="0 0 24 24" fill="#FFD700" width="20" height="20" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><path d="M5 16L3 5l5.5 5L12 4l3.5 6L21 5l-2 11H5z" stroke="#B8860B" stroke-width="0.5"/><path d="M5 18h14v2H5v-2z" stroke="#B8860B" stroke-width="0.5"/></svg>',X=`
+"use strict";(()=>{var R="0.3.5";function C(t){let e="";for(let i of t)e+=String.fromCharCode(i);return btoa(e).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}function w(){return C(crypto.getRandomValues(new Uint8Array(32)))}function T(t,e,i,o,r){let u=n=>{if(n&&typeof n=="object"&&n.type===t)try{i(n)}catch{}},l=n=>{n.origin===e&&(!r||n.source===r)&&u(n.data)};window.addEventListener("message",l);let a=null;if(o&&typeof BroadcastChannel=="function"&&e===location.origin)try{a=new BroadcastChannel(o),a.onmessage=n=>u(n.data)}catch{a=null}return()=>{window.removeEventListener("message",l),a?.close()}}var y={get(t){try{return sessionStorage.getItem(t)}catch{return null}},set(t,e){try{sessionStorage.setItem(t,e)}catch{}},remove(t){try{sessionStorage.removeItem(t)}catch{}}};var F="https://api.chaindaddy.io",G={"https://api.chaindaddy.io":"https://chaindaddy.io/_oauth/authorize","https://staging-api.chaindaddy.io":"https://staging.chaindaddy.io/_oauth/authorize"},b="cd-signin",U="cd:signin",v="cd.signin",_=300;async function K(t){let e=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(t));return C(new Uint8Array(e))}function W(t="openid"){let e=t.split(/\s+/).filter(Boolean);return(e.includes("openid")?e:["openid",...e]).join(" ")}async function Y(t,e,i){let o=new URLSearchParams({response_type:"code",client_id:e.clientId,redirect_uri:e.redirectUri,scope:W(t.scope),state:e.state,nonce:e.nonce,code_challenge:await K(e.verifier),code_challenge_method:"S256"});return t.claims&&o.set("claims",typeof t.claims=="string"?t.claims:JSON.stringify(t.claims)),`${i}?${o}`}function A(t,e){return{code:e,codeVerifier:t.verifier,state:t.state,nonce:t.nonce,issuer:t.issuer,clientId:t.clientId,redirectUri:t.redirectUri}}var m;function k(t){let e=(t.issuer??F).replace(/\/$/,""),i=t.authorizeUrl??G[e];if(!i)return Promise.reject(new Error("authorizeUrl is required for this issuer"));if(!t.clientId||!t.redirectUri)return Promise.reject(new Error("clientId and redirectUri are required"));if(m&&!m.popup.closed)return m.popup.focus(),m.waiting;let o={state:w(),nonce:w(),verifier:w(),issuer:e,clientId:t.clientId,redirectUri:t.redirectUri};y.set(v,JSON.stringify(o));let r=window.open("",b,"popup,width=480,height=720"),u=(async()=>{let l=await Y(t,o,i);if(!r)return location.assign(l),null;r.location.href=l;let a=new URL(t.redirectUri,location.href).origin;return new Promise((n,c)=>{let s,d=()=>{g(),clearInterval(h),clearTimeout(s)},g=T(U,a,p=>{p.state===o.state&&(d(),y.remove(v),typeof p.error=="string"&&p.error?c(new Error(p.error)):p.iss!==e?c(new Error("the answer came from another issuer")):typeof p.code!="string"||!p.code?c(new Error("the answer carried no code")):n(A(o,p.code)))},b,r),h=setInterval(()=>{r.closed&&(clearInterval(h),s=setTimeout(()=>{d(),c(new Error("closed"))},_))},_);t.signal?.addEventListener("abort",()=>{d(),c(new Error("aborted"))})})})();if(r){m={popup:r,waiting:u};let l=()=>{m&&m.popup===r&&(m=void 0)};u.then(l,l)}return u}async function L(){let t=new URLSearchParams(location.search),e={type:U,code:t.get("code"),state:t.get("state"),iss:t.get("iss"),error:t.get("error")};if(window.name===b){try{window.opener?.postMessage(e,location.origin)}catch{}try{let r=new BroadcastChannel(b);r.postMessage(e),r.close()}catch{}return window.close(),null}let i=y.get(v);y.remove(v);let o=i?JSON.parse(i):null;if(!o||e.state!==o.state)throw new Error("the sign-in state does not match: start again");if(e.error)throw new Error(e.error);if(e.iss!==o.issuer)throw new Error("the answer came from another issuer");if(!e.code)throw new Error("the answer carried no code");return A(o,e.code)}async function M(t){let e=await fetch(`${t.issuer}/api/v2/oauth/token`,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"authorization_code",code:t.code,redirect_uri:t.redirectUri,client_id:t.clientId,code_verifier:t.codeVerifier})}),i=await e.json();if(!e.ok)throw new Error(`${i.error??e.status}: ${i.error_description??""}`.trim());return i}var J='<svg viewBox="0 0 24 24" fill="#FFD700" width="20" height="20" aria-hidden="true" xmlns="http://www.w3.org/2000/svg"><path d="M5 16L3 5l5.5 5L12 4l3.5 6L21 5l-2 11H5z" stroke="#B8860B" stroke-width="0.5"/><path d="M5 18h14v2H5v-2z" stroke="#B8860B" stroke-width="0.5"/></svg>',X=`
 :host { display: inline-block; }
 button { display: inline-flex; align-items: center; justify-content: center; gap: 10px; box-sizing: border-box;
   min-height: 40px; padding: 0 16px; border-radius: 10px; font: 600 15px/1 system-ui, -apple-system, "Segoe UI", sans-serif;

package/dist/cd.js.sri

@@ -1 +1 @@
-sha384-Skwsv/FQCtenMYT3zex2SCnlERwJPOsytod8T05hRGAb8yUoTlD/nF2tx+0d590b
+sha384-yNIDKP+1edth+ChOSlYVUWmXdlE3j2HVn66BpXQ0x1J4Bs87EUmozo6w2bxKCXFZ

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/core.ts
-var VERSION = true ? "0.3.4" : "0.0.0";
+var VERSION = true ? "0.3.5" : "0.0.0";
 function b64url(bytes) {
   let s = "";
   for (const b of bytes) s += String.fromCharCode(b);

package/dist/verify.d.ts

@@ -13,7 +13,7 @@ export declare const MIN_CONFIRMATIONS: Readonly<Record<string, number>>;
 /** `token` of an order paid in the chain's own coin (ETH on Base, POL on Polygon). */
 export declare const NATIVE_TOKEN = "0x0000000000000000000000000000000000000000";
 export type VerifyErrorCode = 
-/** A Solana order: follow the manual recipe for now. */
+/** A Solana order: follow the manual recipe for now. Or, from verifyAnswer, a runtime whose Web Crypto has no Ed25519. */
 'unsupported'
 /** What you passed (options, expect) is missing or malformed. */
  | 'bad_options'
@@ -26,8 +26,24 @@ export type VerifyErrorCode =
 /** The block is not the order, asset, payout address or amount you expect. */
  | 'expectation_mismatch'
 /** The RPC endpoint failed or answered something that is not an answer. */
- | 'rpc_error';
-/** Every failure of verifyPayment. A payment that is simply not there yet is not an error: it resolves `paid: false`. */
+ | 'rpc_error'
+/** verifyAnswer: not a compact JWS, not signed with EdDSA, not a signed answer (a receipt, say), not from the issuer you expect, or missing a claim an answer carries. */
+ | 'bad_answer'
+/** verifyAnswer: the answer names a key that is not one of the keys. */
+ | 'unknown_key'
+/** verifyAnswer: the signature is not that key's signature over this answer. */
+ | 'bad_signature'
+/** verifyAnswer: a genuine answer past its `exp`. Fetch a new one. */
+ | 'expired'
+/** The keys you passed, or the record value, are not Ed25519 keys. */
+ | 'bad_keys'
+/** verifyAnswer: the key set could not be fetched, or holds no Ed25519 key. */
+ | 'keys_unavailable';
+/**
+ * Every failure of verifyPayment and verifyAnswer. A payment that is simply not
+ * there yet is not an error: it resolves `paid: false`. Nor is a coin that is
+ * not registered: that is a signed answer with `status: "not_registered"`.
+ */
 export declare class VerifyError extends Error {
     readonly code: VerifyErrorCode;
     constructor(code: VerifyErrorCode, message: string);
@@ -124,3 +140,104 @@ export declare function isKnownCheckout(chainId: string | number, checkout: stri
  * `paid: true` on a doubt.
  */
 export declare function verifyPayment(verification: Verification, options: VerifyOptions): Promise<PaymentResult>;
+/** The `typ` claim of a signed answer. A store receipt, signed by the same keys, is "iap-receipt+v1" and is refused. */
+export declare const ANSWER_TYPE = "cd-answer+v1";
+/** The `iss` claim of a signed answer. */
+export declare const ANSWER_ISSUER = "https://chaindaddy.io";
+/** Where the signing keys are published, as a JSON Web Key Set. */
+export declare const SIGNING_KEYS_URL = "https://api.chaindaddy.io/api/v2/iap/jwks";
+/** The text record on chaindaddy.eth that names the signing keys: `ed25519:<x>` entries separated by a space, the current key first. */
+export declare const SIGNING_KEYS_RECORD = "io.chaindaddy.signing-keys";
+/** One Ed25519 signing key. */
+export interface SigningKey {
+    /** The first 16 hex characters of the SHA-256 of the raw public key: what a JWS header's `kid` names. */
+    kid: string;
+    /** The raw 32-byte public key, base64url without padding (a JWK's `x`). */
+    x: string;
+}
+/** What a signed answer says. */
+export interface AnswerClaims {
+    iss: string;
+    typ: typeof ANSWER_TYPE;
+    /** Unix seconds. */
+    iat: number;
+    /** Unix seconds: 15 minutes after `iat`. */
+    exp: number;
+    /** What the answer is about. More kinds may be added. */
+    kind: 'registration' | (string & {});
+    /** CAIP-2, e.g. "eip155:8453". */
+    chainId: string;
+    /** The chain key, e.g. "base". */
+    chain: string;
+    /** The ticker: as registered when `status` is "registered", otherwise the one asked about, in upper case. */
+    symbol: string;
+    /** "registered": a verified page. "not_registered": none. "removed": one Chain Daddy took down. More may be added: treat one you do not know as not registered. */
+    status: 'registered' | 'not_registered' | 'removed' | (string & {});
+    /** The fields below are present only when `status` is "registered". Addresses are lowercase on EVM chains. */
+    tokenAddress?: string;
+    /** The registration's ID on that chain. */
+    crownId?: number;
+    /** The wallet that holds the registration. */
+    holder?: string;
+    /** RFC 3339. Left out when not known. */
+    registeredAt?: string;
+    pageUrl?: string;
+}
+/** What you asked about. An answer about anything else is refused. */
+export interface AnswerExpectation {
+    /** The chain key you asked about, e.g. "base". */
+    chain?: string;
+    /** Or its CAIP-2 ID, e.g. "eip155:8453". */
+    chainId?: string;
+    /** The ticker you asked about, in any case. */
+    symbol?: string;
+    /** The kind of answer, e.g. "registration". */
+    kind?: string;
+}
+export interface VerifyAnswerOptions {
+    /**
+     * The keys to trust: what signingKeysFromRecord returns, or JWKs (the `keys`
+     * of the key set). A key's `kid` is always computed from the key itself.
+     */
+    keys?: readonly (SigningKey | {
+        x: string;
+        kty?: string;
+        crv?: string;
+    })[];
+    /** Instead of keys: a key set to fetch. Default SIGNING_KEYS_URL, when neither is passed. */
+    jwksUrl?: string;
+    /**
+     * What you asked about. Pass it whenever the answer did not come straight
+     * from Chain Daddy: whoever relays answers can hand you a genuine one about
+     * a different coin.
+     */
+    expect?: AnswerExpectation;
+    /** The `iss` to accept. Default ANSWER_ISSUER. */
+    issuer?: string;
+    /** Seconds past `exp` an answer is still accepted, for a clock that runs fast. Default 0. */
+    clockToleranceSeconds?: number;
+    /** The time to check `exp` against, in Unix seconds. Default: the clock. */
+    now?: number;
+    /** Used to fetch the key set, in place of the global fetch. */
+    fetch?: typeof fetch;
+    /** Aborts the key set request. */
+    signal?: AbortSignal;
+}
+/**
+ * The signing keys named by the text record SIGNING_KEYS_RECORD on
+ * chaindaddy.eth: `ed25519:<x>` entries separated by whitespace, the current
+ * key first. An entry of another kind is skipped (a new kind of key can be
+ * added to the record); an `ed25519:` entry that is not a key throws, so a
+ * damaged record is never read as fewer keys.
+ */
+export declare function signingKeysFromRecord(value: string): SigningKey[];
+/**
+ * Checks a signed answer and resolves what it says. It resolves only when the
+ * JWS is signed with EdDSA by one of the keys, is a signed answer (`typ`) from
+ * the issuer you expect (`iss`), has not expired (`exp`) and, when you pass
+ * `expect`, is about what you asked. Anything else rejects with a VerifyError.
+ *
+ * A coin that is not registered resolves too, with `status: "not_registered"`:
+ * read `status` before anything else.
+ */
+export declare function verifyAnswer(jws: string, options?: VerifyAnswerOptions): Promise<AnswerClaims>;

package/dist/verify.js

@@ -330,13 +330,259 @@ async function verifyPayment(verification, options) {
   const paid = payer !== NATIVE_TOKEN;
   return { paid, payer: paid ? payer : null, blockNumber: Number(at), ...result };
 }
+var ANSWER_TYPE = "cd-answer+v1";
+var ANSWER_ISSUER = "https://chaindaddy.io";
+var SIGNING_KEYS_URL = "https://api.chaindaddy.io/api/v2/iap/jwks";
+var SIGNING_KEYS_RECORD = "io.chaindaddy.signing-keys";
+function fromBase64Url(v) {
+  if (typeof v !== "string" || !/^[A-Za-z0-9_-]*$/.test(v) || v.length % 4 === 1) return null;
+  let bin;
+  try {
+    bin = atob(v.replace(/-/g, "+").replace(/_/g, "/"));
+  } catch {
+    return null;
+  }
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return toBase64Url(out) === v ? out : null;
+}
+function toBase64Url(bytes) {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+var SHA256_K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var rotr = (x, n) => x >>> n | x << 32 - n;
+function keyId(key) {
+  const block = new Uint8Array(64);
+  block.set(key);
+  block[32] = 128;
+  block[62] = 1;
+  const view = new DataView(block.buffer);
+  const w = new Uint32Array(64);
+  for (let i = 0; i < 16; i++) w[i] = view.getUint32(i * 4);
+  for (let i = 16; i < 64; i++) {
+    const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+    const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+    w[i] = w[i - 16] + s0 + w[i - 7] + s1;
+  }
+  const h = [1779033703, 3144134277, 1013904242, 2773480762, 1359893119, 2600822924, 528734635, 1541459225];
+  let [a, b, c, d, e, f, g, hh] = h;
+  for (let i = 0; i < 64; i++) {
+    const t1 = hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + SHA256_K[i] + w[i] >>> 0;
+    const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+    hh = g;
+    g = f;
+    f = e;
+    e = d + t1 >>> 0;
+    d = c;
+    c = b;
+    b = a;
+    a = t1 + t2 >>> 0;
+  }
+  return [a, b].map((v, i) => (h[i] + v >>> 0).toString(16).padStart(8, "0")).join("");
+}
+function keyFromX(x) {
+  const raw = typeof x === "string" && x.length === 43 ? fromBase64Url(x) : null;
+  return raw && raw.length === 32 ? { kid: keyId(raw), x, raw } : null;
+}
+function keyFromObject(v) {
+  if (!isObject(v)) return null;
+  if (v.kty !== void 0 && v.kty !== "OKP" || v.crv !== void 0 && v.crv !== "Ed25519") return null;
+  return keyFromX(v.x);
+}
+function signingKeysFromRecord(value) {
+  if (typeof value !== "string") throw new VerifyError("bad_keys", "the record value is not a string");
+  const out = [];
+  for (const entry of value.split(/\s+/)) {
+    if (!entry.startsWith("ed25519:")) continue;
+    const key = keyFromX(entry.slice("ed25519:".length));
+    if (!key) throw new VerifyError("bad_keys", `"${entry.slice(0, 60)}" is not an Ed25519 key: expected ed25519: and 43 base64url characters`);
+    if (!out.some((k) => k.kid === key.kid)) out.push({ kid: key.kid, x: key.x });
+  }
+  return out;
+}
+async function fetchKeys(url, o) {
+  const doFetch = o.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") throw new VerifyError("bad_options", "no fetch here: pass options.fetch, or options.keys");
+  let body;
+  try {
+    const res = await doFetch(url, { headers: { accept: "application/json" }, signal: o.signal });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    body = await res.json();
+  } catch (e) {
+    throw new VerifyError("keys_unavailable", `the key set at ${url} could not be read: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const keys = isObject(body) && Array.isArray(body.keys) ? body.keys.map(keyFromObject).filter((k) => k !== null) : [];
+  if (keys.length === 0) throw new VerifyError("keys_unavailable", `the key set at ${url} holds no Ed25519 key`);
+  return keys;
+}
+function passedKeys(v) {
+  if (!Array.isArray(v) || v.length === 0) throw new VerifyError("bad_keys", "options.keys must be a list of keys, one or more");
+  return Array.from(v, (k, i) => {
+    const key = keyFromObject(k);
+    if (!key) throw new VerifyError("bad_keys", `options.keys[${i}] is not an Ed25519 key (x: 43 base64url characters)`);
+    return key;
+  });
+}
+function parseAnswerExpectation(v) {
+  if (v === void 0) return null;
+  const fields = ["chain", "chainId", "symbol", "kind"];
+  if (!isObject(v) || Object.keys(v).length === 0 || Object.keys(v).some((k) => !fields.includes(k) || typeof v[k] !== "string" || v[k] === "")) {
+    throw new VerifyError("bad_options", "options.expect takes chain or chainId, symbol and kind, each a string: what you asked about");
+  }
+  return v;
+}
+function jsonObject(bytes) {
+  try {
+    const v = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    return isObject(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+async function ed25519Verify(key, signature, data) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new VerifyError("unsupported", "this runtime has no Web Crypto (crypto.subtle) to check an Ed25519 signature with");
+  let imported;
+  try {
+    imported = await subtle.importKey("raw", key, { name: "Ed25519" }, false, ["verify"]);
+  } catch (e) {
+    throw new VerifyError("unsupported", `this runtime's Web Crypto cannot check an Ed25519 signature: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return subtle.verify({ name: "Ed25519" }, imported, signature, data);
+}
+var isText = (v) => typeof v === "string" && v !== "";
+async function verifyAnswer(jws, options = {}) {
+  if (!isObject(options)) throw new VerifyError("bad_options", "options must be an object: keys or jwksUrl, and expect");
+  const o = options;
+  const tolerance = o.clockToleranceSeconds ?? 0;
+  if (typeof tolerance !== "number" || !Number.isSafeInteger(tolerance) || tolerance < 0) {
+    throw new VerifyError("bad_options", "options.clockToleranceSeconds must be a whole number of seconds, 0 or more");
+  }
+  const now = o.now ?? Math.floor(Date.now() / 1e3);
+  if (typeof now !== "number" || !Number.isFinite(now)) throw new VerifyError("bad_options", "options.now must be a time in Unix seconds");
+  const issuer = o.issuer ?? ANSWER_ISSUER;
+  if (!isText(issuer)) throw new VerifyError("bad_options", "options.issuer must be a string");
+  const expect = parseAnswerExpectation(o.expect);
+  if (o.keys !== void 0 && o.jwksUrl !== void 0) throw new VerifyError("bad_options", "pass keys or jwksUrl, one of the two");
+  if (o.jwksUrl !== void 0 && !isText(o.jwksUrl)) throw new VerifyError("bad_options", "options.jwksUrl must be a URL");
+  const parts = typeof jws === "string" ? jws.trim().split(".") : [];
+  if (parts.length !== 3) throw new VerifyError("bad_answer", "not a compact JWS: three base64url parts joined by dots");
+  const headerBytes = fromBase64Url(parts[0]);
+  const payloadBytes = fromBase64Url(parts[1]);
+  const signature = fromBase64Url(parts[2]);
+  const header = headerBytes && jsonObject(headerBytes);
+  if (!header || !payloadBytes || !signature) throw new VerifyError("bad_answer", "not a compact JWS: a part is not base64url, or the header is not JSON");
+  if (header.alg !== "EdDSA") throw new VerifyError("bad_answer", `the answer is signed with ${JSON.stringify(header.alg)}, not EdDSA`);
+  if (signature.length !== 64) throw new VerifyError("bad_answer", "the signature is not an Ed25519 signature");
+  const keys = o.keys !== void 0 ? passedKeys(o.keys) : await fetchKeys(o.jwksUrl ?? SIGNING_KEYS_URL, o);
+  const key = keys.find((k) => k.kid === header.kid);
+  if (!key) throw new VerifyError("unknown_key", `the answer is signed by key ${JSON.stringify(header.kid)}, which is not one of the keys`);
+  if (!await ed25519Verify(key.raw, signature, new TextEncoder().encode(`${parts[0]}.${parts[1]}`))) {
+    throw new VerifyError("bad_signature", "the signature does not match: the answer was changed, or another key signed it");
+  }
+  const c = jsonObject(payloadBytes);
+  if (!c) throw new VerifyError("bad_answer", "the signed payload is not a JSON object");
+  if (c.typ !== ANSWER_TYPE) throw new VerifyError("bad_answer", `not a signed answer: typ is ${JSON.stringify(c.typ)}, not "${ANSWER_TYPE}"`);
+  if (c.iss !== issuer) throw new VerifyError("bad_answer", `the answer is from ${JSON.stringify(c.iss)}, not ${issuer}`);
+  if (!Number.isSafeInteger(c.iat) || !Number.isSafeInteger(c.exp)) throw new VerifyError("bad_answer", "the answer has no iat or no exp");
+  for (const name of ["kind", "chainId", "chain", "symbol", "status"]) {
+    if (!isText(c[name])) throw new VerifyError("bad_answer", `the answer has no ${name}`);
+  }
+  if (c.status === "registered" && (!isText(c.tokenAddress) || !isText(c.holder) || !Number.isSafeInteger(c.crownId))) {
+    throw new VerifyError("bad_answer", "a registered answer must name the token, the registration and its holder");
+  }
+  if (now >= c.exp + tolerance) throw new VerifyError("expired", `the answer expired at ${c.exp} (Unix seconds): fetch a new one`);
+  const claims = c;
+  if (expect) {
+    if (expect.chain !== void 0 && claims.chain !== expect.chain) throw new VerifyError("expectation_mismatch", `the answer is about chain ${claims.chain}, not ${expect.chain}`);
+    if (expect.chainId !== void 0 && claims.chainId !== expect.chainId) throw new VerifyError("expectation_mismatch", `the answer is about chain ${claims.chainId}, not ${expect.chainId}`);
+    if (expect.symbol !== void 0 && claims.symbol.toUpperCase() !== expect.symbol.toUpperCase()) {
+      throw new VerifyError("expectation_mismatch", `the answer is about ${claims.symbol}, not ${expect.symbol}`);
+    }
+    if (expect.kind !== void 0 && claims.kind !== expect.kind) throw new VerifyError("expectation_mismatch", `the answer is a ${claims.kind}, not a ${expect.kind}`);
+  }
+  return claims;
+}
 export {
+  ANSWER_ISSUER,
+  ANSWER_TYPE,
   CHECKOUTS,
   MIN_CONFIRMATIONS,
   NATIVE_TOKEN,
+  SIGNING_KEYS_RECORD,
+  SIGNING_KEYS_URL,
   VerifyError,
   encodeHashOrder,
   encodePaidBy,
   isKnownCheckout,
+  signingKeysFromRecord,
+  verifyAnswer,
   verifyPayment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaindaddy/js",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Chain Daddy for any website: Sign in with Chain Daddy (a popup and a button), a coin's apps on its own site (<cd-app>), checkout for a coin's store in a popup, and a server-side check that a store order was paid on chain",
   "homepage": "https://docs.chaindaddy.io/developer/javascript-sdk",
   "repository": {