@solarpunkltd/swarm-id 0.8.2 → 0.10.0

package/dist/utils/ens-name.d.ts

@@ -0,0 +1,33 @@
+/**
+ * How long a wallet's answer is kept before the chain is asked again. A name
+ * changed on chain shows at most this long after on a page that read it.
+ */
+export declare const ENS_NAME_CACHE_MS: number;
+/**
+ * How long a failed read is kept, so a page that shows many senders does not
+ * ask a broken or slow endpoint again for every message it renders, while a
+ * passing outage still clears soon.
+ */
+export declare const ENS_NAME_FAILURE_CACHE_MS: number;
+export interface EnsNameOptions {
+    /** An Ethereum mainnet JSON-RPC endpoint. Empty, no name is ever answered. */
+    rpcUrl: string;
+    /** Deadline for the whole lookup. Defaults to `CHAIN_READ_TIMEOUT_MS`. */
+    timeoutMs?: number;
+}
+/**
+ * The ENS name of `wallet`, when ENS's Universal Resolver answers a primary
+ * name whose address record names the wallet back, and the name is already
+ * ENSIP-15 normalised. Undefined for no such name and for everything that goes
+ * wrong: no endpoint, an endpoint that does not answer in time, an answer that
+ * does not decode, a name's offchain gateway that fails. Never throws.
+ *
+ * An answer, name or no name, is kept in memory for `ENS_NAME_CACHE_MS` per
+ * endpoint and wallet, and lookups that arrive together share one read. A
+ * failed read answers no name for `ENS_NAME_FAILURE_CACHE_MS`, and the first
+ * lookup after that asks again.
+ *
+ * @param wallet - the wallet's address, in any case, with or without `0x`,
+ *   such as `verifyWalletLink(...).wallet`
+ */
+export declare function resolveVerifiedEnsName(wallet: string, options: EnsNameOptions): Promise<string | undefined>;

package/dist/utils/ens.d.ts

@@ -0,0 +1,13 @@
+/** The ENS registry, at the same address on every chain ENS is deployed to. */
+export declare const ENS_REGISTRY_ADDRESS = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+/** How long each read may take. */
+export interface EnsReadOptions {
+    timeoutMs: number;
+}
+/** The EIP-137 namehash of a name already in its normalized form. */
+export declare function ensNamehash(name: string): string;
+/**
+ * The text record `key` of `name`, through the resolver the registry names.
+ * @throws when the name has no resolver or the answers do not decode.
+ */
+export declare function readEnsText(rpcUrl: string, name: string, key: string, options: EnsReadOptions): Promise<string>;

package/dist/utils/json-rpc.d.ts

@@ -8,6 +8,11 @@ export interface JsonRpcOptions {
      * RPC". Defaults to the endpoint's origin.
      */
     label?: string;
+    /**
+     * The longest response body read, in bytes. A longer body is refused as it
+     * streams in, before anything parses it. Unset, the body is read whole.
+     */
+    maxBodyBytes?: number;
 }
 /** One call in a batch. Ids are assigned by {@link jsonRpcBatch}. */
 export interface JsonRpcRequest {

package/dist/utils/personal-sign.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sign `message` as `personal_sign` does.
+ *
+ * @param privateKey - bare hex, 32 bytes
+ * @returns `0x` + r ‖ s ‖ v, v 27 or 28, s low
+ */
+export declare function personalSign(message: string, privateKey: string): string;
+/**
+ * The address that signed `message`, `0x` + 40 lower-case hex characters.
+ * A valid signature over a changed message recovers SOME address, so a caller
+ * always compares the result with the signer it expects.
+ *
+ * @param subject - how errors name the signature, e.g. "Chat binding signature"
+ * @throws on a signature that is not 65 bytes of 0x hex, has v other than 27
+ *   or 28, has a high s, or does not recover a public key.
+ */
+export declare function recoverPersonalSigner(message: string, signature: string, subject: string): string;

package/dist/utils/postage-stamp-association.d.ts

@@ -1,40 +1,39 @@
-import { type ConnectedApp, type PostageStamp, type SignedInAccount } from "../schemas";
+import { type ConnectedApp, type PostageStamp } from "../schemas";
 /**
- * Resolve which postage stamp an app should upload with.
+ * Resolve which postage stamp an app uploads with: the one the person picked
+ * for it (`postageStampBatchID`), and nothing else.
  *
- * An app may carry its own batch override (`postageStampBatchID`); otherwise it
- * falls back to the account's default stamp. The account owns the stamp set, so
- * these pointers are the single source of truth. An app set to
- * `NO_POSTAGE_STAMP` resolves to no stamp, the default included.
+ * The account default is never a fallback (Levi's ruling D4, 2026-10-16). A
+ * site with no pick, a site set to `NO_POSTAGE_STAMP`, and a site whose
+ * picked drive is gone all resolve to no stamp, and the person picks one in
+ * Swarm ID. Falling back let a drive bought after the site signed in, or the
+ * default left after the picked drive was removed, pay for the site's
+ * uploads without the person choosing it.
  *
- * The lookup is existence-checked: a pointer whose stamp is missing (e.g. a
- * removed or replaced batch) is skipped so resolution falls through to the next
- * candidate instead of failing.
+ * A deleted stamp (tombstone) resolves to nothing. An EXPIRED one still
+ * resolves: it can be renewed, and the session reports it as expired (#745).
  *
  * Paired with `stampsReachableByApp` below, which decides what a partitioned
- * session may HOLD while this decides what it SPENDS — over the same two
- * pointers, and deliberately differing on tombstones: this one skips them (a
- * deleted stamp cannot be spent), that one keeps them (a session learns its
- * stamp is deleted no other way). Change the pointer rule in one and the other
- * has to follow, or a session holds a stamp it cannot resolve, or resolves one
- * it was never handed.
+ * session may HOLD while this decides what it SPENDS, over the same pointer,
+ * and deliberately differing on tombstones: this one skips them (a deleted
+ * stamp cannot be spent), that one keeps them (a session learns its stamp is
+ * deleted no other way). Change the pointer rule in one and the other has to
+ * follow, or a session holds a stamp it cannot resolve, or resolves one it
+ * was never handed.
  */
-export declare function resolveStampForApp(app: Pick<ConnectedApp, "postageStampBatchID">, account: Pick<SignedInAccount, "defaultPostageStampBatchID">, stamps: PostageStamp[]): PostageStamp | undefined;
+export declare function resolveStampForApp(app: Pick<ConnectedApp, "postageStampBatchID">, stamps: PostageStamp[]): PostageStamp | undefined;
 /**
- * The stamps a connected app's session can ever reach: the ones its pointers
- * name — its own batch override, and the account default it falls through to.
+ * The stamps a connected app's session can ever reach: the one the person
+ * picked for it, and none while that pick waits for the person to confirm it.
  *
  * This is what a PARTITIONED session is handed and allowed to keep (#578). It
  * holds its account view in memory, in a context embedded by an arbitrary dApp
- * page, and it can only ever spend the stamp `resolveStampForApp` picks — so
+ * page, and it can only ever spend the stamp `resolveStampForApp` picks, so
  * the rest of the collection is signer keys it has no use for. Least privilege
  * rather than a broken boundary: an unpartitioned proxy reads the same material
  * out of shared storage, but it does not have to be handed it.
  *
- * BOTH pointers, not just the winner: the default is the fallthrough
- * `resolveStampForApp` takes when the override's stamp is gone, so shipping
- * only the override would turn a recoverable stale pointer into a session that
- * cannot upload at all. Tombstones its pointers still name are kept too — a
- * tombstone is how the session learns the stamp it was spending is deleted.
+ * A tombstone the pointer still names is kept: a tombstone is how the session
+ * learns the stamp it was spending is deleted.
  */
-export declare function stampsReachableByApp(app: Pick<ConnectedApp, "postageStampBatchID" | "stampPending">, account: Pick<SignedInAccount, "defaultPostageStampBatchID">, stamps: PostageStamp[]): PostageStamp[];
+export declare function stampsReachableByApp(app: Pick<ConnectedApp, "postageStampBatchID" | "stampPending">, stamps: PostageStamp[]): PostageStamp[];

package/dist/utils/site-allow-list.d.ts

@@ -8,8 +8,6 @@ export declare const DEFAULT_SITE_ALLOW_LIST_RECORD_KEY = "buzz.solarpunk.sites"
  * that read it before.
  */
 export declare const SITE_ALLOW_LIST_CACHE_MS: number;
-/** The ENS registry, at the same address on every chain ENS is deployed to. */
-export declare const ENS_REGISTRY_ADDRESS = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
 /** Why a site was refused, so a caller can word its own screen. */
 export type SiteRefusal = "not-clean" | "not-listed" | "list-unavailable";
 export type SiteCheck = {
@@ -37,8 +35,6 @@ export interface SiteAllowListSettings {
     storage?: Pick<Storage, "getItem" | "setItem">;
     now?: () => number;
 }
-/** The EIP-137 namehash of a name already in its normalized form. */
-export declare function ensNamehash(name: string): string;
 /**
  * The origins a record names. Entries are separated by white space or commas.
  * An entry that is not a clean https origin is ignored and logged, so one bad

package/dist/utils/storage-probe.d.ts

@@ -1,13 +1,16 @@
 /**
- * Whether the proxy iframe can read the trusted domain's first-party store —
+ * Whether a Swarm ID frame can read the trusted domain's first-party store,
  * asked BEFORE authentication, because it decides which transport the auth
- * popup has to take (#613).
+ * popup has to take (#613). Both frames a site embeds read it: the session
+ * frame, to tell the client whether `connect()` can work, and the button
+ * frame, to decide whether to leave the popup's challenge in storage.
  *
  * The mirror image of the probe the connect popup already runs: there, the
- * iframe writes a challenge and the popup checks whether it can read it back
- * first-party (`ui/src/lib/stores/connect.svelte.ts`). That answer arrives far
- * too late to choose a transport, so the same question is asked the other way
- * round — the first-party app leaves a marker, and the iframe reads it back.
+ * button frame writes a challenge and the popup checks whether it can read it
+ * back first-party (`ui/src/lib/stores/connect.svelte.ts`). That answer
+ * arrives far too late to choose a transport, so the same question is asked
+ * the other way round: the first-party app leaves a marker, and the frames
+ * read it back.
  *
  * Deliberately NOT any of these:
  *
@@ -24,7 +27,14 @@
  * The marker only ever answers YES with certainty. Absent means "not proven
  * shared" — a partitioned iframe, or a browser that has never had the SwarmID
  * site open at the top level — and the caller treats that as partitioned,
- * which is the safe direction: the delegated transport works in both modes.
+ * which is the safe direction: the handover through the Swarm ID button works
+ * in both modes.
+ *
+ * The marker is sealed, because the keys in that store are: a frame that sees
+ * the store but not the IndexedDB key that opens it sees no session in it.
+ * Playwright's WebKit gives a cross-site frame exactly that, one
+ * `localStorage` and its own IndexedDB (measured 2026-10-15), and a plain
+ * marker had it wait for a storage write it could never read.
  */
 export declare const STORAGE_SHARED_KEY = "swarm-id-first-party";
 /**
@@ -35,6 +45,6 @@ export declare const STORAGE_SHARED_KEY = "swarm-id-first-party";
  * bucket and make the iframe report itself shared — the one wrong answer this
  * must never give.
  */
-export declare function markFirstPartyStorage(): void;
-/** Whether this context can see the marker a first-party page left. */
-export declare function isStorageShared(): boolean;
+export declare function markFirstPartyStorage(): Promise<void>;
+/** Whether this context can see, and open, the marker a first-party page left. */
+export declare function isStorageShared(): Promise<boolean>;

package/dist/utils/wallet-link.d.ts

@@ -0,0 +1,70 @@
+/** The first line, which also versions the format. */
+export declare const WALLET_LINK_TITLE = "Swarm ID wallet link v1";
+/** The second line, what the wallet's owner agrees to, read exactly. */
+export declare const WALLET_LINK_STATEMENT = "I link this wallet to the Swarm ID account below, so sites may show my ENS name beside its messages.";
+/**
+ * One spelling per signature, lower case as `personalSign` writes it, so this
+ * reader and the chat library's, which signs the link's bytes into each
+ * message, accept exactly the same links.
+ */
+export declare const WALLET_LINK_SIGNATURE_PATTERN: RegExp;
+/** A signed link as it travels and is stored. */
+export interface WalletLink {
+    message: string;
+    /** The wallet's `personal_sign` of `message`, `0x` + r ‖ s ‖ v, 65 bytes. */
+    walletSignature: string;
+    /** The account key's `personal_sign` of `message`, in the same form. */
+    accountSignature: string;
+}
+/** The three fields a link message carries, as the message spells them. */
+export interface WalletLinkFields {
+    /** The Swarm ID account's address, `0x` + 40 lower-case hex characters. */
+    account: string;
+    /** The wallet's address, in the same form. */
+    wallet: string;
+    /** ISO 8601 UTC, as `Date.prototype.toISOString` writes it. */
+    date: string;
+}
+/** A link both signatures were checked for. Its fields are what it names. */
+export type VerifiedWalletLink = WalletLinkFields;
+/** What a link has to name for a reader to accept it. */
+export interface ExpectedWalletLink {
+    /** The account the reader expects, in any case, with or without `0x`. */
+    account: string;
+}
+/** Build the exact five-line message for these fields. */
+export declare function buildWalletLinkMessage(fields: {
+    account: string;
+    wallet: string;
+    date: Date;
+}): string;
+/**
+ * Read the fields out of a link message, refusing every shape but the one
+ * `buildWalletLinkMessage` writes: another first line, another statement, a
+ * missing or extra line, a trailing newline, an address in another spelling, a date in
+ * another form.
+ */
+export declare function parseWalletLinkMessage(message: string): WalletLinkFields;
+/**
+ * Check a link and return what it names, or undefined. It is accepted only
+ * when the message has exactly the v1 shape, the wallet signature recovers the
+ * wallet the message names, the account signature recovers the account the
+ * message names, and that account is `expected.account`. Never throws.
+ *
+ * A wallet whose signature does not recover its own address, such as a
+ * smart-contract wallet (ERC-1271), cannot make a link that passes.
+ */
+export declare function verifyWalletLink(link: WalletLink, expected: ExpectedWalletLink): VerifiedWalletLink | undefined;
+/**
+ * Countersign a message the wallet has already signed, with the account's own
+ * key, after checking the message's shape, that the wallet signature recovers
+ * the wallet it names, and that it names this key's account.
+ *
+ * @param accountKey - the account's private key (bare hex), whose address is
+ *   the account's `id`
+ * @param walletSignature - the wallet's `personal_sign` of `message`, already
+ *   in the canonical 65-byte form with v 27 or 28
+ * @throws on any of those checks failing, so no link is ever stored that a
+ *   reader would refuse.
+ */
+export declare function countersignWalletLink(accountKey: string, message: string, walletSignature: string): WalletLink;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarpunkltd/swarm-id",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "type": "module",
   "description": "Swarm ID library for authentication and Bee API operations",
   "main": "dist/swarm-id.esm.js",
@@ -62,6 +62,7 @@
     "@noble/curves": "1.2.0",
     "@noble/hashes": "1.3.2",
     "cafe-utility": "34.0.0",
+    "viem": "2.55.13",
     "zod": "4.1.13"
   },
   "devDependencies": {