@solarpunkltd/swarm-id 0.9.0 → 0.10.1

package/dist/types.d.ts

@@ -537,10 +537,11 @@ export type UploadMode = z.infer<typeof UploadModeSchema>;
 /**
  * Why a session cannot upload, when `uploadMode` is `"unavailable"`.
  *
- * - `no-stamp`: the site has no stamp to use. The account has no drive (or
- *   its pointers name only drives that are gone), the person set this site to
- *   no drive, or the person has not yet confirmed the site's drive in the
- *   connect window since the site signed in.
+ * - `no-stamp`: the site has no stamp to use. The person has not picked a
+ *   drive for this site, the drive they picked is gone, they set this site to
+ *   no drive, or they have not yet confirmed the site's drive in the connect
+ *   window since the site signed in. The account's default drive never
+ *   stands in for a missing pick.
  * - `stamper-failed` — the stamp resolved and the stamper still did not build.
  *   `initializeStamper` logs and returns rather than throwing, so without this
  *   the symptom is indistinguishable from having no stamp at all.
@@ -610,6 +611,11 @@ export declare const ConnectionIdentitySchema: z.ZodObject<{
         }>;
         url: z.ZodString;
     }, z.core.$strip>;
+    walletLink: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        walletSignature: z.ZodString;
+        accountSignature: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ConnectionIdentity = z.infer<typeof ConnectionIdentitySchema>;
 export declare const ConnectionInfoSchema: z.ZodObject<{
@@ -646,6 +652,11 @@ export declare const ConnectionInfoSchema: z.ZodObject<{
             }>;
             url: z.ZodString;
         }, z.core.$strip>;
+        walletLink: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            walletSignature: z.ZodString;
+            accountSignature: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     appKey: z.ZodOptional<z.ZodObject<{
         address: z.ZodString;
@@ -2412,6 +2423,11 @@ export declare const ConnectionInfoChangedMessageSchema: z.ZodObject<{
             }>;
             url: z.ZodString;
         }, z.core.$strip>;
+        walletLink: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            walletSignature: z.ZodString;
+            accountSignature: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     appKey: z.ZodOptional<z.ZodObject<{
         address: z.ZodString;
@@ -2777,6 +2793,11 @@ export declare const IframeToParentMessageSchema: z.ZodDiscriminatedUnion<[z.Zod
             }>;
             url: z.ZodString;
         }, z.core.$strip>;
+        walletLink: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            walletSignature: z.ZodString;
+            accountSignature: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     appKey: z.ZodOptional<z.ZodObject<{
         address: z.ZodString;
@@ -3070,9 +3091,15 @@ export declare const AuthDataSchema: z.ZodObject<{
         settings: z.ZodOptional<z.ZodObject<{
             appSessionDuration: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        walletLink: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            walletSignature: z.ZodString;
+            accountSignature: z.ZodString;
+        }, z.core.$strip>>;
         accountNameAt: z.ZodOptional<z.ZodNumber>;
         defaultStampAt: z.ZodOptional<z.ZodNumber>;
         settingsAt: z.ZodOptional<z.ZodNumber>;
+        walletLinkAt: z.ZodOptional<z.ZodNumber>;
         lastModified: z.ZodOptional<z.ZodNumber>;
         partitionCount: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
@@ -3185,9 +3212,15 @@ export declare const SetSecretMessageSchema: z.ZodObject<{
             settings: z.ZodOptional<z.ZodObject<{
                 appSessionDuration: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
+            walletLink: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                walletSignature: z.ZodString;
+                accountSignature: z.ZodString;
+            }, z.core.$strip>>;
             accountNameAt: z.ZodOptional<z.ZodNumber>;
             defaultStampAt: z.ZodOptional<z.ZodNumber>;
             settingsAt: z.ZodOptional<z.ZodNumber>;
+            walletLinkAt: z.ZodOptional<z.ZodNumber>;
             lastModified: z.ZodOptional<z.ZodNumber>;
             partitionCount: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
@@ -3267,9 +3300,15 @@ export declare const PopupToIframeMessageSchema: z.ZodDiscriminatedUnion<[z.ZodO
             settings: z.ZodOptional<z.ZodObject<{
                 appSessionDuration: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
+            walletLink: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                walletSignature: z.ZodString;
+                accountSignature: z.ZodString;
+            }, z.core.$strip>>;
             accountNameAt: z.ZodOptional<z.ZodNumber>;
             defaultStampAt: z.ZodOptional<z.ZodNumber>;
             settingsAt: z.ZodOptional<z.ZodNumber>;
+            walletLinkAt: z.ZodOptional<z.ZodNumber>;
             lastModified: z.ZodOptional<z.ZodNumber>;
             partitionCount: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
@@ -3289,7 +3328,7 @@ export interface ClientOptions {
     initializationTimeout?: number;
     /**
      * Invoked whenever the dApp-visible ConnectionInfo changes (identity rename,
-     * default-stamp change, local↔synced account migration, postage stamp added,
+     * the site's drive changed, local↔synced account migration, postage stamp added,
      * auth transitions, etc.). Fires once on initial auth check, then on every
      * effective change. The current snapshot is also available synchronously
      * via `client.connectionInfo`.

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/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.9.0",
+  "version": "0.10.1",
   "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": {