@bitsocial/pubsub-voting 0.6.0 → 0.6.1

package/README.md

@@ -42,7 +42,7 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | `chains` | `ChainClientFactory` | yes | resolves the chain a contest counts in (`{ chainId }`, from `criteria.bucketChainId`) to a viem `PublicClient`; every gate rule and the weight rule read through it. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
 | `nameResolvers` | `NameResolver[]` | no | community-name resolvers (same interface and instances as pkc-js's `nameResolvers`, e.g. `@bitsocial/bso-resolver` for `name.bso`); each vote's `community.name` claim is verified through them — inline at the forward-gate for live votes, in the background verifier for cold-join admits — and a bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted |
 | `dataPath` | `string \| false` | no | directory for the voter's persistent state (gate-result + name-resolution caches, and each joined contest's **checkpoint snapshot** — its last fully-verified winner-set, reloaded at join so a restart with no other peer online keeps the tally), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/` + `{dataPath}/checkpoints.db`); in the browser the path is ignored and everything lives in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC, and restores each contest's checkpoint before the cold-start pull. A seeder should always set a stable path |
-| `httpRouterUrls` | `string[]` | no | Delegated Routing V1 router base URLs to **announce provider records to** (one unsigned `PUT /routing/v1/providers` per router; `Keys` batches every joined contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced on root changes, and on address changes). **Seeders only**: absent/empty means never announce (the default — plain clients are not dialable), and the browser build never announces regardless. The node must be publicly **reachable** (its listening port open/forwarded/published), but it does not need to know its own public IP: private, loopback, and link-local addrs are filtered client-side, and when nothing survives — the normal zero-config case behind NAT or a Docker bridge, and even on public-IP hosts, since libp2p withholds unconfirmed public addrs pending AutoNAT — the announcer sends the wildcard sentinels (`/ip4/0.0.0.0/...`, `/ip6/::/...`) that the router rewrites to the PUT's observed source IP, exactly as kubo announces work. Configured `addresses.announce` values (concrete public addrs, DNS/AutoTLS, or a kubo-style wildcard) are used as-is. Only a loopback-only node announces nothing. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
+| `httpRouterUrls` | `string[]` | no | Delegated Routing V1 router base URLs to **announce provider records to** (one signed `PUT /routing/v1/providers` per router — IPIP-0526: the record carries a `Signature` made by the node's own libp2p key and a fresh `Payload.Timestamp`, both required by [pkc-http-router](https://github.com/pkcprotocol/pkc-http-router), the router implementation this library targets, which rejects the whole PUT with 403 otherwise; `Keys` batches every joined contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced on root changes, and on address changes). **Seeders only**: absent/empty means never announce (the default — plain clients are not dialable), and the browser build never announces regardless. The node must be publicly **reachable** (its listening port open/forwarded/published), but it does not need to know its own public IP: private, loopback, and link-local addrs are filtered client-side, and when nothing survives — the normal zero-config case behind NAT or a Docker bridge, and even on public-IP hosts, since libp2p withholds unconfirmed public addrs pending AutoNAT — the announcer sends the wildcard sentinels (`/ip4/0.0.0.0/...`, `/ip6/::/...`) that the router rewrites to the PUT's observed source IP, exactly as kubo announces work. Configured `addresses.announce` values (concrete public addrs, DNS/AutoTLS, or a kubo-style wildcard) are used as-is. Only a loopback-only node announces nothing. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
 
 A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry + the `chains` factory: an unimplemented rule throws `UnknownRuleError`, an unresolvable required chain throws `MissingChainClientError` — recuse, don't miscount), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists. The document names its chain only by `bucketChainId`; RPC endpoints stay out of it, so operators can swap gateways without forking the topic.
 
@@ -85,7 +85,7 @@ const voter = new PubsubVoter({
 });
 ```
 
-Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingFetchError` if the node lacks a usable pubsub service, blockstore, or libp2p fetch service — the library fails fast rather than letting a later `publish`/`subscribe`/`fetch` fail obscurely. ("Bitswap" is not a separately checkable property — it is a block broker wired beneath `blockstore` — so the validated guarantee is a well-formed blockstore, the surface bitswap retrieves through. The fetch service carries the checkpoint root-record pull; the library registers its own responder on it.)
+Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingFetchError` if the node lacks a usable pubsub service, blockstore, or libp2p fetch service (and `MissingPrivateKeyError` if `httpRouterUrls` is set but the node exposes no signing key, since provider records must be signed) — the library fails fast rather than letting a later `publish`/`subscribe`/`fetch` fail obscurely. ("Bitswap" is not a separately checkable property — it is a block broker wired beneath `blockstore` — so the validated guarantee is a well-formed blockstore, the surface bitswap retrieves through. The fetch service carries the checkpoint root-record pull; the library registers its own responder on it.)
 
 ### Read a tally reactively
 

package/dist/errors.d.ts

@@ -68,6 +68,17 @@ export declare class MissingBlockstoreError extends Error {
 export declare class MissingFetchError extends Error {
     constructor();
 }
+/**
+ * Thrown at construction when `PubsubVoterOptions.httpRouterUrls` is set but the injected Helia
+ * node's libp2p exposes no signing key (neither `libp2p.privateKey` nor `libp2p.components.privateKey`).
+ * Delegated-routing providers are announced as IPIP-0526 **signed** records — the production router
+ * verifies by default and rejects the whole PUT otherwise — so a node that cannot sign cannot
+ * announce, and announcing unsigned would silently leave the seeder undiscoverable on every
+ * verifying router. See DESIGN.md "Provider-record announces".
+ */
+export declare class MissingPrivateKeyError extends Error {
+    constructor();
+}
 /**
  * Thrown once a voter has been `destroy()`ed and something tries to keep using it. Unlike `stop()`
  * (which leaves every topic but keeps the client reusable), `destroy()` is terminal: every contest

package/dist/errors.js

@@ -103,6 +103,25 @@ export class MissingFetchError extends Error {
         this.name = "MissingFetchError";
     }
 }
+/**
+ * Thrown at construction when `PubsubVoterOptions.httpRouterUrls` is set but the injected Helia
+ * node's libp2p exposes no signing key (neither `libp2p.privateKey` nor `libp2p.components.privateKey`).
+ * Delegated-routing providers are announced as IPIP-0526 **signed** records — the production router
+ * verifies by default and rejects the whole PUT otherwise — so a node that cannot sign cannot
+ * announce, and announcing unsigned would silently leave the seeder undiscoverable on every
+ * verifying router. See DESIGN.md "Provider-record announces".
+ */
+export class MissingPrivateKeyError extends Error {
+    constructor() {
+        super("The injected Helia node's libp2p exposes no private key (`libp2p.privateKey` / " +
+            "`libp2p.components.privateKey`), so provider records cannot be signed. Delegated " +
+            "Routing V1 routers verify the IPIP-0526 signature and reject unsigned records, so " +
+            "`httpRouterUrls` needs a node that can sign for its own peer id. Pass a real libp2p " +
+            "node, or drop `httpRouterUrls` to stop announcing. See DESIGN.md " +
+            "\"Provider-record announces\".");
+        this.name = "MissingPrivateKeyError";
+    }
+}
 /**
  * Thrown once a voter has been `destroy()`ed and something tries to keep using it. Unlike `stop()`
  * (which leaves every topic but keeps the client reusable), `destroy()` is terminal: every contest

package/dist/transport/announce/node.d.ts

@@ -1,13 +1,15 @@
 import type { Announcer, AnnouncerOptions } from "./types.js";
 /**
  * The Node provider-record announcer (see types.ts for the seam rationale, and DESIGN.md
- * "Deferred pkc-js work", provider-record announces): one unsigned `PUT /routing/v1/providers`
+ * "Deferred pkc-js work", provider-record announces): one **signed** `PUT /routing/v1/providers`
  * per configured router per tick, kubo's body shape —
- * `{ Providers: [{ Schema: "peer", Payload: { ID, Addrs, Keys } }] }` — with `Keys` batched
- * across ALL joined contests. Unsigned is correct against the production router
- * (pkc-http-router reads only `Payload.{ID, Addrs, Keys, AdvisoryTTL}`; no signature field
- * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
- * source IP — which a seeder announcing its own addresses passes naturally.
+ * `{ Providers: [{ Schema: "peer", Signature, Payload: { ID, Addrs, Keys, Timestamp } }] }` —
+ * with `Keys` batched across ALL joined contests. The signature is IPIP-0526, built by
+ * {@link signedProvidersBody} over the exact payload bytes put on the wire; the production router
+ * verifies by default and answers 403 for the whole request otherwise, so an unsigned record made
+ * the announcing node absent from every verifying router (issue #38). Its address anti-spoofing
+ * keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's source IP — which a seeder
+ * announcing its own addresses passes naturally.
  *
  * Addresses: the announceable set is `getMultiaddrs()` filtered to public/DNS addrs plus
  * exactly-unspecified addrs (`0.0.0.0`/`::`), which the production router rewrites to the PUT's

package/dist/transport/announce/node.js

@@ -1,12 +1,15 @@
+import { requireAnnounceSigner, signedProvidersBody } from "./record.js";
 /**
  * The Node provider-record announcer (see types.ts for the seam rationale, and DESIGN.md
- * "Deferred pkc-js work", provider-record announces): one unsigned `PUT /routing/v1/providers`
+ * "Deferred pkc-js work", provider-record announces): one **signed** `PUT /routing/v1/providers`
  * per configured router per tick, kubo's body shape —
- * `{ Providers: [{ Schema: "peer", Payload: { ID, Addrs, Keys } }] }` — with `Keys` batched
- * across ALL joined contests. Unsigned is correct against the production router
- * (pkc-http-router reads only `Payload.{ID, Addrs, Keys, AdvisoryTTL}`; no signature field
- * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
- * source IP — which a seeder announcing its own addresses passes naturally.
+ * `{ Providers: [{ Schema: "peer", Signature, Payload: { ID, Addrs, Keys, Timestamp } }] }` —
+ * with `Keys` batched across ALL joined contests. The signature is IPIP-0526, built by
+ * {@link signedProvidersBody} over the exact payload bytes put on the wire; the production router
+ * verifies by default and answers 403 for the whole request otherwise, so an unsigned record made
+ * the announcing node absent from every verifying router (issue #38). Its address anti-spoofing
+ * keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's source IP — which a seeder
+ * announcing its own addresses passes naturally.
  *
  * Addresses: the announceable set is `getMultiaddrs()` filtered to public/DNS addrs plus
  * exactly-unspecified addrs (`0.0.0.0`/`::`), which the production router rewrites to the PUT's
@@ -113,7 +116,7 @@ export function sentinelAddrs(addrs) {
     }
     return [...sentinels];
 }
-/** One unsigned kubo-shape provider PUT; throws on timeout or a non-2xx answer. */
+/** One signed kubo-shape provider PUT; throws on timeout or a non-2xx answer. */
 async function putProviders(baseUrl, body, timeoutMs) {
     const endpoint = `${baseUrl.replace(/\/+$/, "")}/routing/v1/providers`;
     const res = await fetch(endpoint, {
@@ -132,6 +135,10 @@ export function makeAnnouncer(options) {
     const intervalMs = options.intervalMs ?? ANNOUNCE_INTERVAL_MS;
     const debounceMs = options.debounceMs ?? ANNOUNCE_DEBOUNCE_MS;
     const timeoutMs = options.timeoutMs ?? ANNOUNCE_ROUTER_TIMEOUT_MS;
+    // Resolved once, at construction: a node that cannot sign for its own peer id can only
+    // produce records the routers reject, so that is a config error to raise now, not an
+    // announce to make hourly and have refused (see MissingPrivateKeyError).
+    const signer = requireAnnounceSigner(options.libp2p);
     let started = false;
     let intervalTimer;
     let debounceTimer;
@@ -159,9 +166,19 @@ export function makeAnnouncer(options) {
                 // announce nothing — the production router drops addr-less providers anyway.
                 if (keys.length === 0 || addrs.length === 0)
                     continue;
-                const body = JSON.stringify({
-                    Providers: [{ Schema: "peer", Payload: { ID: options.libp2p.peerId.toString(), Addrs: addrs, Keys: keys } }]
-                });
+                let body;
+                try {
+                    // Fresh clock reading per tick: the router bounds a record's staleness and
+                    // skew, so a cached timestamp ages into a rejection (see record.ts).
+                    body = await signedProvidersBody({ peerId: options.libp2p.peerId.toString(), addrs, keys, timestamp: Date.now() }, signer);
+                }
+                catch (error) {
+                    // A key that cannot sign fails every router identically; report it on each
+                    // (the announcer never throws into the voter) and let the next tick retry.
+                    for (const url of options.routerUrls)
+                        options.onError?.(url, error);
+                    continue;
+                }
                 await Promise.all(options.routerUrls.map(async (url) => {
                     try {
                         await putProviders(url, body, timeoutMs);

package/dist/transport/announce/record.d.ts

@@ -0,0 +1,57 @@
+import type { AnnounceSigner, AnnouncerLibp2p } from "./types.js";
+/**
+ * The signed provider record the announcer PUTs (IPIP-0526, as implemented by the production
+ * router — pkc-http-router `lib/signature.ts`). Verification is ON by default there, so an
+ * unsigned record is a 403 for the WHOLE request: the announcing node is simply absent from
+ * every verifying router (issue #38 — four of six default routers rejected every announce).
+ *
+ * Two things make a record verifiable:
+ *
+ * - **`Signature`** — multibase (base64, the `m` prefix) over the sha256 digest of the raw
+ *   `Payload` bytes, made by the private key the announcing peer id was derived from. libp2p's
+ *   `PrivateKey.sign` is what the router's key types line up with: an ed25519 key signs those 32
+ *   digest bytes directly (`crypto.verify(null, digest, key, sig)`), a secp256k1 key hashes them
+ *   again through ECDSA (`crypto.verify("sha256", digest, key, sig)`) — both are exactly
+ *   `sign(digest)` on this side. The public key is recovered from `Payload.ID` itself (an identity
+ *   multihash), so nothing else has to travel.
+ * - **`Payload.Timestamp`** — epoch milliseconds, read fresh per announce: the router rejects a
+ *   missing one, and bounds it against replay (24 h stale / 1 h future). Never cache it.
+ *
+ * **The bytes signed must be the bytes sent.** The router verifies against the `Payload` byte
+ * range it locates in the raw request body (`extractRawPayloads`), not against a re-serialized
+ * parse of it — so serializing the payload to sign it and then handing the enclosing object to
+ * `JSON.stringify` a second time is a real (and observed) failure mode: any difference in key
+ * order, spacing, or number formatting reads as `invalid_signature`. Hence this builder
+ * serializes the payload ONCE and splices that exact string into the body it returns; the body is
+ * a string all the way to `fetch`, and no object is ever re-serialized.
+ */
+/** What the announcer signs with: libp2p's `PrivateKey` surface, narrowed to `sign`. */
+export type { AnnounceSigner };
+/**
+ * Find the injected node's signing key. libp2p keeps it on the `components` registry of the
+ * running node (it is deliberately absent from the public `Libp2p` interface, which exposes only
+ * the derived `peerId`); `privateKey` is checked first so a host that surfaces it directly — or a
+ * test double — is honoured without reaching into internals. Structural, like every other host
+ * probe in `transport/`: the injected node is `unknown` shaped, never trusted by type.
+ *
+ * Throws {@link MissingPrivateKeyError} when no key is reachable, at construction, rather than
+ * announcing records every verifying router will reject.
+ */
+export declare function requireAnnounceSigner(libp2p: AnnouncerLibp2p): AnnounceSigner;
+/** What one announce says: who, where, which CIDs, and when it was said. */
+export interface AnnounceRecord {
+    /** The announcing node's peer id — also where the router recovers the verifying key from. */
+    peerId: string;
+    /** Already filtered/synthesized by the caller (see `announceableAddrs` / `sentinelAddrs`). */
+    addrs: readonly string[];
+    /** Every joined contest's criteria CID + checkpoint root + chunk CIDs, batched. */
+    keys: readonly string[];
+    /** Epoch ms, read fresh per announce (the router bounds staleness and skew). */
+    timestamp: number;
+}
+/**
+ * Build the signed `PUT /routing/v1/providers` body, as the exact string to send. Returns a
+ * string — not an object — on purpose: the signature covers the `Payload` substring inside it,
+ * and re-serializing anything here would break it (see the module comment).
+ */
+export declare function signedProvidersBody(record: AnnounceRecord, signer: AnnounceSigner): Promise<string>;

package/dist/transport/announce/record.js

@@ -0,0 +1,41 @@
+import { base64 } from "multiformats/bases/base64";
+import { sha256 } from "multiformats/hashes/sha2";
+import { MissingPrivateKeyError } from "../../errors.js";
+/**
+ * Find the injected node's signing key. libp2p keeps it on the `components` registry of the
+ * running node (it is deliberately absent from the public `Libp2p` interface, which exposes only
+ * the derived `peerId`); `privateKey` is checked first so a host that surfaces it directly — or a
+ * test double — is honoured without reaching into internals. Structural, like every other host
+ * probe in `transport/`: the injected node is `unknown` shaped, never trusted by type.
+ *
+ * Throws {@link MissingPrivateKeyError} when no key is reachable, at construction, rather than
+ * announcing records every verifying router will reject.
+ */
+export function requireAnnounceSigner(libp2p) {
+    const direct = libp2p.privateKey;
+    if (isSigner(direct))
+        return direct;
+    const component = libp2p.components?.privateKey;
+    if (isSigner(component))
+        return component;
+    throw new MissingPrivateKeyError();
+}
+function isSigner(value) {
+    return value !== null && typeof value === "object" && typeof value.sign === "function";
+}
+/**
+ * Build the signed `PUT /routing/v1/providers` body, as the exact string to send. Returns a
+ * string — not an object — on purpose: the signature covers the `Payload` substring inside it,
+ * and re-serializing anything here would break it (see the module comment).
+ */
+export async function signedProvidersBody(record, signer) {
+    const payloadJson = JSON.stringify({
+        ID: record.peerId,
+        Addrs: record.addrs,
+        Keys: record.keys,
+        Timestamp: record.timestamp
+    });
+    const digest = (await sha256.digest(new TextEncoder().encode(payloadJson))).digest;
+    const signature = base64.encode(await signer.sign(digest));
+    return `{"Providers":[{"Schema":"peer","Signature":${JSON.stringify(signature)},"Payload":${payloadJson}}]}`;
+}

package/dist/transport/announce/types.d.ts

@@ -26,9 +26,28 @@ export interface AnnouncerLibp2p {
     getMultiaddrs(): Array<{
         toString(): string;
     }>;
+    /**
+     * The node's own signing key, if it is surfaced directly. libp2p's public `Libp2p` interface
+     * exposes only the derived `peerId`, so this is normally absent and the key is read from
+     * {@link AnnouncerLibp2p.components} instead — both are optional because the announcer probes
+     * the injected node structurally (see `requireAnnounceSigner`).
+     */
+    privateKey?: unknown;
+    /** libp2p's component registry on the running node — where `privateKey` actually lives. */
+    components?: {
+        privateKey?: unknown;
+    };
     addEventListener(type: "self:peer:update", listener: () => void): void;
     removeEventListener(type: "self:peer:update", listener: () => void): void;
 }
+/**
+ * The signing surface a provider record needs: libp2p's `PrivateKey.sign`, narrowed to the one
+ * call the announcer makes. The announcer hands it the sha256 digest of the payload bytes and
+ * multibase-encodes what comes back — see `record.ts` for why that is what the router verifies.
+ */
+export interface AnnounceSigner {
+    sign(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
 export interface AnnouncerOptions {
     /** Delegated Routing V1 base URLs to PUT provider records to. Empty means never announce. */
     routerUrls: readonly string[];

package/dist/transport/gossip-validator.d.ts

@@ -47,8 +47,13 @@ export interface GossipGateDeps {
         cid: CID;
         bundle: VotesBundle;
     }>;
-    /** The full validity pipeline for one bundle (see verify/bundle.ts). */
-    verifier: BundleVerifier;
+    /**
+     * The full validity pipeline for one bundle (see verify/bundle.ts). Declared as the `verify`
+     * half of {@link BundleVerifier}: the gate never runs a stage on its own (no `verifyOffline`,
+     * no `checkGates` — those belong to the cold-join chase and `Contest.checkEligibility`), and
+     * asking only for what it calls keeps that true.
+     */
+    verifier: Pick<BundleVerifier, "verify">;
     /**
      * Clock-aware freshness guard, kept OUT of the pure (cacheable) verifier: is this bundle's
      * bucket sample block already reachable from our chain head? A bundle dated to a future

package/dist/verify/cache.d.ts

@@ -44,5 +44,8 @@ export interface CachingBundleVerifier {
  * valid bundle or a provable `reject` is remembered (a known-bad bundle is not re-fetched or
  * re-checked), while a transient `ignore` is re-evaluated next time so a stale head/record
  * cannot pin it.
+ *
+ * Takes the `verify` half of a {@link BundleVerifier}: the cache memoizes whole-pipeline verdicts
+ * by CID and has nothing to say about the offline stage or a gate check, so it asks for neither.
  */
-export declare function makeCachingVerifier(verifier: BundleVerifier, cache: VerdictCache): CachingBundleVerifier;
+export declare function makeCachingVerifier(verifier: Pick<BundleVerifier, "verify">, cache: VerdictCache): CachingBundleVerifier;

package/dist/verify/cache.js

@@ -46,6 +46,9 @@ export function makeVerdictCache(maxEntries = 4096) {
  * valid bundle or a provable `reject` is remembered (a known-bad bundle is not re-fetched or
  * re-checked), while a transient `ignore` is re-evaluated next time so a stale head/record
  * cannot pin it.
+ *
+ * Takes the `verify` half of a {@link BundleVerifier}: the cache memoizes whole-pipeline verdicts
+ * by CID and has nothing to say about the offline stage or a gate check, so it asks for neither.
  */
 export function makeCachingVerifier(verifier, cache) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -25,6 +25,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
     "typecheck:bench": "npm run build && tsc -p benchmark/tsconfig.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",