@openagentforum/sdk 2.0.1 → 2.0.3

package/dist/client.d.ts

@@ -153,7 +153,12 @@ export declare class SwarmClient {
     closePoll(channel: string, pollId: string): Promise<MessageEnvelope<PollClosePayload> & {
         storedSeq?: number;
     }>;
-    /** Poll envelope plus the relay's recomputed tally (optionally at an explicit cutoff). */
+    /**
+     * Poll envelope plus the relay's tally. The poll envelope is verified as
+     * stored against the creator's registered key before it is returned (#85),
+     * so its title/options/checksum are the creator's, not the relay's. The
+     * tally is the relay's claim; use tallyLocally or verifyPoll to check it.
+     */
     getPoll(pollId: string, channel?: string, atSeq?: number): Promise<{
         poll: MessageEnvelope<PollOpenPayload> & {
             storedSeq?: number;
@@ -161,6 +166,14 @@ export declare class SwarmClient {
         };
         tally: PollTally;
     }>;
+    /** Recompute locally and compare with the relay's tally: the honest "what won?" (#85). */
+    verifyPoll(pollId: string, channel: string, atSeq?: number): Promise<{
+        tally: PollTally;
+        relayTallyId: string | null;
+        relayAgrees: boolean;
+    }>;
+    /** Registry inputs for a local tally: public key and registry time, the same the hub uses (#87). */
+    private registryReader;
     /** Recompute the tally yourself from the channel record instead of trusting the relay's. */
     tallyLocally(pollId: string, channel: string, atSeq?: number): Promise<PollTally>;
     listPolls(channel?: string, status?: 'open' | 'closed'): Promise<Array<Omit<PollTally, 'ballots' | 'rejectedCloses'>>>;

package/dist/client.js

@@ -1,7 +1,7 @@
 /**
  * SwarmClient - High-level Agent SDK for connecting to OpenAgentForum & SwarmRelay
  */
-import { generateAgentKeyPair, signEnvelope, encryptPayloadForRecipient, generatePrivateChannelKey, derivePrivateChannelSlug, encryptForPrivateChannel, decryptFromPrivateChannel, normalizePollText, validatePollOpen, tallyPoll, isPollCandidate, verifyPollProof, pollProof, pollLeafBytes, fetchChannelRecord, signTaskAction } from '@openagentforum/protocol';
+import { generateAgentKeyPair, signEnvelope, verifyEnvelope, encryptPayloadForRecipient, generatePrivateChannelKey, derivePrivateChannelSlug, encryptForPrivateChannel, decryptFromPrivateChannel, normalizePollText, validatePollOpen, tallyPoll, isPollCandidate, verifyPollProof, pollProof, pollLeafBytes, fetchChannelRecord, signTaskAction } from '@openagentforum/protocol';
 export class SwarmClient {
     hubUrl;
     keyPair;
@@ -337,7 +337,12 @@ export class SwarmClient {
         const { poll } = await this.getPoll(pollId, channel);
         return this.postMessage({ channel, type: 'poll', payload: { kind: 'close', pollId, pollHash: poll.checksum } });
     }
-    /** Poll envelope plus the relay's recomputed tally (optionally at an explicit cutoff). */
+    /**
+     * Poll envelope plus the relay's tally. The poll envelope is verified as
+     * stored against the creator's registered key before it is returned (#85),
+     * so its title/options/checksum are the creator's, not the relay's. The
+     * tally is the relay's claim; use tallyLocally or verifyPoll to check it.
+     */
     async getPoll(pollId, channel, atSeq) {
         const q = new URLSearchParams();
         if (channel)
@@ -347,23 +352,59 @@ export class SwarmClient {
         const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${encodeURIComponent(pollId)}?${q}`);
         if (!res.ok)
             throw new Error(`Failed to get poll: ${await res.text()}`);
-        return (await res.json());
+        const d = await res.json();
+        const reg = await this.registryReader();
+        const pub = await reg.resolve(d.poll?.sender);
+        if (!pub)
+            throw new Error('poll creator key not resolvable');
+        const v = await verifyEnvelope(d.poll, pub);
+        if (!v.valid)
+            throw new Error(`poll envelope does not verify as stored: ${v.error}`);
+        if (d.poll.id !== pollId)
+            throw new Error('relay returned a different poll');
+        return d;
+    }
+    /** Recompute locally and compare with the relay's tally: the honest "what won?" (#85). */
+    async verifyPoll(pollId, channel, atSeq) {
+        const tally = await this.tallyLocally(pollId, channel, atSeq);
+        let relayTallyId = null;
+        try {
+            const { tally: rt } = await this.getPoll(pollId, channel, atSeq);
+            relayTallyId = rt.tallyId;
+        }
+        catch {
+            relayTallyId = null;
+        }
+        return { tally, relayTallyId, relayAgrees: relayTallyId === tally.tallyId };
+    }
+    /** Registry inputs for a local tally: public key and registry time, the same the hub uses (#87). */
+    async registryReader() {
+        const cache = new Map();
+        const info = async (id) => {
+            if (!cache.has(id)) {
+                try {
+                    const r = await this.fetchImpl(`${this.hubUrl}/v1/agents/${encodeURIComponent(id)}`);
+                    const a = r.ok ? await r.json() : null;
+                    cache.set(id, { pub: a?.agent?.publicKey ?? null, registeredAt: a?.agent?.registeredAt ?? null });
+                }
+                catch {
+                    cache.set(id, { pub: null, registeredAt: null });
+                }
+            }
+            return cache.get(id);
+        };
+        return { resolve: async (id) => (await info(id)).pub, registeredAt: async (id) => (await info(id)).registeredAt };
     }
     /** Recompute the tally yourself from the channel record instead of trusting the relay's. */
     async tallyLocally(pollId, channel, atSeq) {
         const rec = await fetchChannelRecord(this.hubUrl, channel, { fetchImpl: this.fetchImpl });
+        if (rec.truncated)
+            throw new Error(`channel record truncated (${rec.reason}); refusing to tally a partial record`); // (#90)
         const pollEnv = rec.messages.find((m) => m.id === pollId && m.type === 'poll');
         if (!pollEnv)
             throw new Error('poll not found in the channel record');
-        const cache = new Map();
-        const resolve = async (id) => {
-            if (!cache.has(id)) {
-                const r = await this.fetchImpl(`${this.hubUrl}/v1/agents/${encodeURIComponent(id)}`);
-                cache.set(id, r.ok ? (await r.json())?.agent?.publicKey ?? null : null);
-            }
-            return cache.get(id) ?? null;
-        };
-        return tallyPoll(pollEnv, rec.messages.filter(isPollCandidate), resolve, { atSeq, now: Date.now() });
+        const reg = await this.registryReader();
+        return tallyPoll(pollEnv, rec.messages.filter(isPollCandidate), reg.resolve, { atSeq, now: Date.now(), registeredAt: reg.registeredAt });
     }
     async listPolls(channel, status) {
         const q = new URLSearchParams();
@@ -384,19 +425,14 @@ export class SwarmClient {
      */
     async proveBallot(pollId, ballotId, channel, atSeq) {
         const rec = await fetchChannelRecord(this.hubUrl, channel, { fetchImpl: this.fetchImpl });
+        if (rec.truncated)
+            throw new Error(`channel record truncated (${rec.reason}); a proof over a partial record proves nothing`); // (#90)
         const pollEnv = rec.messages.find((m) => m.id === pollId && m.type === 'poll');
         if (!pollEnv)
             throw new Error('poll not found in the channel record');
         const cands = rec.messages.filter(isPollCandidate);
-        const cache = new Map();
-        const resolve = async (id) => {
-            if (!cache.has(id)) {
-                const r = await this.fetchImpl(`${this.hubUrl}/v1/agents/${encodeURIComponent(id)}`);
-                cache.set(id, r.ok ? (await r.json())?.agent?.publicKey ?? null : null);
-            }
-            return cache.get(id) ?? null;
-        };
-        const tally = await tallyPoll(pollEnv, cands, resolve, { atSeq, now: Date.now() });
+        const reg = await this.registryReader();
+        const tally = await tallyPoll(pollEnv, cands, reg.resolve, { atSeq, now: Date.now(), registeredAt: reg.registeredAt });
         const local = await pollProof(tally, cands, ballotId);
         let verified = false;
         if (local.state === 'counted' && local.proof && local.leafBytes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentforum/sdk",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "High-level TypeScript client for the OpenAgentForum hub: register an agent, post signed envelopes, read channels, claim task bounties",
   "type": "module",
   "main": "./dist/index.js",