@floatonnear/float-adapter 0.2.0 → 0.3.0

package/dist/blocked-scan.d.ts

@@ -47,6 +47,51 @@ export declare function createRpc(url: string, opts?: {
     maxRetries?: number;
     onThrottle?: (waitMs: number) => void;
 }): RpcFn;
+/** An RPC failure that carries the JSON-RPC error object it came from. */
+export interface RpcError extends Error {
+    rpcError?: {
+        name?: string;
+        cause?: {
+            name?: string;
+        };
+        data?: unknown;
+    };
+}
+/**
+ * Did this failure mean "no block was ever produced at that height"?
+ *
+ * NEAR gives every slot a height, and when a producer misses its slot that
+ * height never gets a block. Measured on testnet: 8 of the 1,604 heights in
+ * one real scan, about 0.5%. Those heights are not gaps in coverage — there
+ * is nothing at them to read, by anyone, ever.
+ *
+ * The scanner used to record them as unread, so every scan of every vault
+ * reported holes that could never be filled and the dashboard said "refusal
+ * history is incomplete" permanently, for a reason that was not real.
+ *
+ * `UNKNOWN_BLOCK` ALONE IS NOT ENOUGH, and this is the trap. A non-archival
+ * node returns the same `UNKNOWN_BLOCK` for a block that genuinely exists
+ * but has been garbage-collected — measured against the default testnet RPC,
+ * which returned it for every height in that same scan, including ones the
+ * scanner had read successfully. Treating that as "nothing there" would
+ * claim coverage of a range never read, which is the exact failure this
+ * subsystem exists to prevent.
+ *
+ * The two are distinguishable by what the node could resolve:
+ *
+ *   never produced   data: "DB Not Found Error: BLOCK HEIGHT: 276175670"
+ *   node lacks it    data: "DB Not Found Error: BLOCK: DN5cUfsq…"
+ *
+ * A HEIGHT that resolves to nothing means no block exists. A HASH means the
+ * node resolved the height to a block and only lacks the body.
+ *
+ * FAILS SAFE. This matches a nearcore error string, which is not a stable
+ * API. If that wording changes, the match fails and the height is recorded
+ * as a hole — degrading to the old behaviour, which overstates gaps. The
+ * opposite error, overstating coverage, is the one that matters, and no
+ * change to this string can produce it.
+ */
+export declare function isAbsentHeight(e: unknown): boolean;
 export interface BlockedRecord {
     requestId: string;
     nodeId: number;
@@ -63,6 +108,14 @@ export interface ScanResult {
     chunksSkipped: number;
     /** Heights that could not be read. Coverage inside a hole is unknown. */
     holes: number[];
+    /**
+     * Heights where NEAR never produced a block, so there was nothing to read.
+     *
+     * NOT holes. Counted separately so a scan can still SAY how many it met —
+     * silently dropping them would make "1,604 blocks, 1,596 seen" look like
+     * an arithmetic error with no explanation on screen.
+     */
+    absentHeights: number[];
 }
 /**
  * Pull `request_blocked` events out of one transaction's receipt logs.
@@ -99,6 +152,31 @@ export interface BlockedStore {
 /** Merge overlapping/adjacent spans so the list stays short and readable. */
 export declare function coalesce(spans: Hole[]): Hole[];
 export declare function emptyStore(vault: string): BlockedStore;
+/**
+ * Decide whether a persisted log belongs to the vault being served.
+ *
+ * CAUGHT ON A LIVE DASHBOARD. The adapter was pointed at a vault with exactly
+ * ONE node, and the activity page showed six refusals attributed to nodes 5
+ * through 20, five days old, by agents named `s*.v3.floatvault-12329.testnet`
+ * — real refusals from a DIFFERENT vault, left in `.demo/blocked-log.json` by
+ * an earlier swarm test. The loader read `parsed.vault ?? env.vault` and never
+ * compared the two, so any vault's log loaded into any other vault's
+ * dashboard.
+ *
+ * Not merely cosmetic. The store also carries `scannedFrom`/`scannedTo`, so
+ * adopting a foreign log makes the follower believe it has COVERAGE of block
+ * ranges it never scanned for this vault — collapsing "we looked and found
+ * nothing" back into "we never looked here", which is the one distinction this
+ * module exists to preserve.
+ *
+ * Refusing a payment is this product's headline behaviour, so showing another
+ * vault's refusals as yours is worse than showing none.
+ *
+ * A log with NO vault recorded predates the field. That one is adopted — it is
+ * almost certainly ours, written before the field existed — but adopted under
+ * THIS vault's name, so the next load can check it.
+ */
+export declare function adoptBlockedStore(parsed: BlockedStore, vault: string): BlockedStore;
 /** Fold a scan result into a store. Pure, so the merge rules are testable. */
 export declare function mergeScan(store: BlockedStore, from: number, to: number, res: ScanResult): {
     store: BlockedStore;

package/dist/blocked-scan.js

@@ -71,14 +71,88 @@ export function createRpc(url, opts = {}) {
             await sleep(wait);
             return rpc(method, params, attempt + 1);
         }
+        /**
+         * READ THE BODY BEFORE JUDGING THE STATUS.
+         *
+         * NEAR answers a handler error with HTTP 422 AND a complete JSON-RPC
+         * error body. The previous order — `if (!r.ok) throw` first — threw a
+         * bare `RPC HTTP 422` and never looked, so every caller saw a failure
+         * with no idea what kind.
+         *
+         * That silently defeated the first version of `isAbsentHeight`: its
+         * unit tests passed, because they threw errors with the right shape by
+         * hand, and against the real chain it never matched once. Correct and
+         * unreachable. Measured: block 276175670 on fastnear's archival
+         * endpoint returns 422 with `cause.name = "UNKNOWN_BLOCK"`.
+         *
+         * `text()` then parse, not `json()`: a proxy or gateway error is HTML,
+         * and `json()` would throw over the status this is trying to report.
+         */
+        const raw = await r.text();
+        let j = null;
+        try {
+            j = JSON.parse(raw);
+        }
+        catch {
+            // Not JSON. The status is all there is to say.
+        }
+        if (j?.error) {
+            // THE ERROR TRAVELS AS DATA, not only as a message. A caller that
+            // needs to tell one failure from another should not be parsing a
+            // string that was built for a human and truncated to 140 characters.
+            // `scanRange` needs exactly that distinction — see `isAbsentHeight`.
+            const err = new Error(`${method}: ${JSON.stringify(j.error).slice(0, 140)}`);
+            err.rpcError = j.error;
+            throw err;
+        }
         if (!r.ok)
             throw new Error(`RPC HTTP ${r.status}`);
-        const j = await r.json();
-        if (j.error)
-            throw new Error(`${method}: ${JSON.stringify(j.error).slice(0, 140)}`);
-        return j.result;
+        return j?.result;
     };
 }
+/**
+ * Did this failure mean "no block was ever produced at that height"?
+ *
+ * NEAR gives every slot a height, and when a producer misses its slot that
+ * height never gets a block. Measured on testnet: 8 of the 1,604 heights in
+ * one real scan, about 0.5%. Those heights are not gaps in coverage — there
+ * is nothing at them to read, by anyone, ever.
+ *
+ * The scanner used to record them as unread, so every scan of every vault
+ * reported holes that could never be filled and the dashboard said "refusal
+ * history is incomplete" permanently, for a reason that was not real.
+ *
+ * `UNKNOWN_BLOCK` ALONE IS NOT ENOUGH, and this is the trap. A non-archival
+ * node returns the same `UNKNOWN_BLOCK` for a block that genuinely exists
+ * but has been garbage-collected — measured against the default testnet RPC,
+ * which returned it for every height in that same scan, including ones the
+ * scanner had read successfully. Treating that as "nothing there" would
+ * claim coverage of a range never read, which is the exact failure this
+ * subsystem exists to prevent.
+ *
+ * The two are distinguishable by what the node could resolve:
+ *
+ *   never produced   data: "DB Not Found Error: BLOCK HEIGHT: 276175670"
+ *   node lacks it    data: "DB Not Found Error: BLOCK: DN5cUfsq…"
+ *
+ * A HEIGHT that resolves to nothing means no block exists. A HASH means the
+ * node resolved the height to a block and only lacks the body.
+ *
+ * FAILS SAFE. This matches a nearcore error string, which is not a stable
+ * API. If that wording changes, the match fails and the height is recorded
+ * as a hole — degrading to the old behaviour, which overstates gaps. The
+ * opposite error, overstating coverage, is the one that matters, and no
+ * change to this string can produce it.
+ */
+export function isAbsentHeight(e) {
+    const err = e;
+    const rpc = err?.rpcError;
+    if (!rpc)
+        return false;
+    if (rpc.cause?.name !== "UNKNOWN_BLOCK")
+        return false;
+    return typeof rpc.data === "string" && /BLOCK HEIGHT:/i.test(rpc.data);
+}
 /**
  * Pull `request_blocked` events out of one transaction's receipt logs.
  * Exported for testing: this parsing is the part that silently breaks if the
@@ -121,14 +195,22 @@ export async function scanRange(rpc, vault, from, to) {
         chunksFetched: 0,
         chunksSkipped: 0,
         holes: [],
+        absentHeights: [],
     };
     for (let h = from; h <= to; h++) {
         let blk;
         try {
             blk = await rpc("block", { block_id: h });
         }
-        catch {
-            res.holes.push(h);
+        catch (e) {
+            // A height NEAR never produced is not a gap in coverage: there is
+            // nothing at it to read. Anything else is a genuine failure and stays
+            // a hole. See `isAbsentHeight` for why UNKNOWN_BLOCK alone is not
+            // enough to tell those apart.
+            if (isAbsentHeight(e))
+                res.absentHeights.push(h);
+            else
+                res.holes.push(h);
             continue;
         }
         res.blocksSeen++;
@@ -188,6 +270,41 @@ export function coalesce(spans) {
 export function emptyStore(vault) {
     return { vault, scannedFrom: null, scannedTo: null, holes: [], blocked: {} };
 }
+/**
+ * Decide whether a persisted log belongs to the vault being served.
+ *
+ * CAUGHT ON A LIVE DASHBOARD. The adapter was pointed at a vault with exactly
+ * ONE node, and the activity page showed six refusals attributed to nodes 5
+ * through 20, five days old, by agents named `s*.v3.floatvault-12329.testnet`
+ * — real refusals from a DIFFERENT vault, left in `.demo/blocked-log.json` by
+ * an earlier swarm test. The loader read `parsed.vault ?? env.vault` and never
+ * compared the two, so any vault's log loaded into any other vault's
+ * dashboard.
+ *
+ * Not merely cosmetic. The store also carries `scannedFrom`/`scannedTo`, so
+ * adopting a foreign log makes the follower believe it has COVERAGE of block
+ * ranges it never scanned for this vault — collapsing "we looked and found
+ * nothing" back into "we never looked here", which is the one distinction this
+ * module exists to preserve.
+ *
+ * Refusing a payment is this product's headline behaviour, so showing another
+ * vault's refusals as yours is worse than showing none.
+ *
+ * A log with NO vault recorded predates the field. That one is adopted — it is
+ * almost certainly ours, written before the field existed — but adopted under
+ * THIS vault's name, so the next load can check it.
+ */
+export function adoptBlockedStore(parsed, vault) {
+    if (parsed.vault && parsed.vault !== vault)
+        return emptyStore(vault);
+    return {
+        vault,
+        scannedFrom: parsed.scannedFrom ?? null,
+        scannedTo: parsed.scannedTo ?? null,
+        holes: Array.isArray(parsed.holes) ? parsed.holes : [],
+        blocked: parsed.blocked ?? {},
+    };
+}
 /** Fold a scan result into a store. Pure, so the merge rules are testable. */
 export function mergeScan(store, from, to, res) {
     let added = 0;
@@ -197,10 +314,47 @@ export function mergeScan(store, from, to, res) {
         store.blocked[r.requestId] = r;
         added++;
     }
+    // THE GAP BETWEEN DISJOINT SCANS IS A HOLE, and nothing but this merge can
+    // see it. A single `scanRange` reports the blocks IT could not read; it has
+    // no idea another range was scanned 54,000 blocks away.
+    //
+    // Without this, min/max over the two ranges claims the whole envelope as
+    // covered. Observed live: 1,500 blocks scanned, then 160 blocks scanned
+    // 54,300 later, and the store reported `scannedFrom 275882255, scannedTo
+    // 275938214, holes: []` — 55,960 blocks claimed, 1,660 actually read. The
+    // dashboard caveat written to prevent precisely this confusion would then
+    // have rendered the fabrication as fact.
+    const newHoles = [];
+    if (store.scannedFrom !== null && store.scannedTo !== null) {
+        // Scanning forward, away from the existing range.
+        if (from > store.scannedTo + 1)
+            newHoles.push({ from: store.scannedTo + 1, to: from - 1 });
+        // Scanning backward, leaving the gap above the new range.
+        if (to < store.scannedFrom - 1)
+            newHoles.push({ from: to + 1, to: store.scannedFrom - 1 });
+    }
     store.scannedFrom = store.scannedFrom === null ? from : Math.min(store.scannedFrom, from);
     store.scannedTo = Math.max(store.scannedTo ?? 0, to);
-    if (res.holes.length) {
-        store.holes = coalesce([...store.holes, ...res.holes.map((h) => ({ from: h, to: h }))]);
+    // CLEAR FIRST, THEN ADD. Order matters and getting it wrong is silent.
+    //
+    // Scanning a span that was previously a hole must REMOVE it, or a backfill
+    // that genuinely read those blocks leaves coverage understated forever.
+    // But this subtraction has to run BEFORE this scan's own holes are added —
+    // a scanner hole is by definition INSIDE the range just scanned, so doing it
+    // the other way round deletes the holes this very call just reported. The
+    // pre-existing "carries holes forward" test caught exactly that.
+    if (store.holes.length) {
+        store.holes = coalesce(store.holes.flatMap((h) => {
+            if (to < h.from || from > h.to)
+                return [h]; // untouched by this scan
+            const left = h.from < from ? [{ from: h.from, to: Math.min(h.to, from - 1) }] : [];
+            const right = h.to > to ? [{ from: Math.max(h.from, to + 1), to: h.to }] : [];
+            return [...left, ...right];
+        }));
+    }
+    const scannerHoles = res.holes.map((h) => ({ from: h, to: h }));
+    if (newHoles.length || scannerHoles.length) {
+        store.holes = coalesce([...store.holes, ...newHoles, ...scannerHoles]);
     }
     return { store, added };
 }

package/dist/env-file.d.ts

@@ -23,6 +23,22 @@
  *      just to start the adapter locally.
  *
  * One parser, tested, used by both.
+ *
+ * ---- WHERE THIS ARGUMENT STOPS
+ *
+ * Everything above is about how a secrets file is LOADED: as data, never as
+ * something a shell executes. It says nothing about whether the secret should
+ * be sitting in an env value in the first place — and it should not. Reading
+ * this file to check which vault is configured is routine, and it prints a live
+ * private key into a terminal scrollback and into the transcript of whatever
+ * agent is driving.
+ *
+ * So the keys named above have a second, preferred form: NEAR_VAULT_AGENT_KEY
+ * and FLOAT_QUOTE_SIGNER_KEY each accept a `*_FILE` variant holding a PATH.
+ * The reasoning, the accepted file shapes, and why a broken path must never
+ * fall back to the inline value all live in ONE place rather than being
+ * restated here — `@floatonnear/mcp`'s `key-file.ts`. The two variables still
+ * travel through this parser; it is only their VALUES that stop being secrets.
  */
 /**
  * Parse `KEY=value` lines into a plain object.

package/dist/env-file.js

@@ -23,6 +23,22 @@
  *      just to start the adapter locally.
  *
  * One parser, tested, used by both.
+ *
+ * ---- WHERE THIS ARGUMENT STOPS
+ *
+ * Everything above is about how a secrets file is LOADED: as data, never as
+ * something a shell executes. It says nothing about whether the secret should
+ * be sitting in an env value in the first place — and it should not. Reading
+ * this file to check which vault is configured is routine, and it prints a live
+ * private key into a terminal scrollback and into the transcript of whatever
+ * agent is driving.
+ *
+ * So the keys named above have a second, preferred form: NEAR_VAULT_AGENT_KEY
+ * and FLOAT_QUOTE_SIGNER_KEY each accept a `*_FILE` variant holding a PATH.
+ * The reasoning, the accepted file shapes, and why a broken path must never
+ * fall back to the inline value all live in ONE place rather than being
+ * restated here — `@floatonnear/mcp`'s `key-file.ts`. The two variables still
+ * travel through this parser; it is only their VALUES that stop being secrets.
  */
 /**
  * Parse `KEY=value` lines into a plain object.

package/dist/gate.d.ts

@@ -26,19 +26,23 @@ export type AuthVerdict = {
     error: string;
 };
 /**
- * Only mutating requests need the token.
+ * Reads are open; mutating routes need the token unless they sign nothing.
  *
- * GETs are read-only and the bind is loopback, so they are reachable only from
- * the machine itself. OPTIONS must pass or the browser never reaches the real
- * request and the dashboard breaks for a reason nobody can see.
+ * OPTIONS must pass or the browser never reaches the real request and the
+ * dashboard breaks for a reason nobody can see.
  *
  * A MISSING token is 503, not 401. They are different problems: 401 tells a
  * caller to go and find a credential, and here there is none to find — the
  * operator has not configured one. Conflating them sends people hunting for a
  * secret that does not exist.
+ *
+ * `path` is OPTIONAL and an absent one is GATED, never open. A caller that
+ * forgets to pass it gets the safe answer; the alternative defaults to
+ * exposure, which is how the `0.0.0.0` bind above happened.
  */
-export declare function authorize({ method, authHeader, token, }: {
+export declare function authorize({ method, path, authHeader, token, }: {
     method: string;
+    path?: string | undefined;
     authHeader: string | undefined;
     token: string | undefined;
 }): AuthVerdict;

package/dist/gate.js

@@ -51,20 +51,47 @@ export function corsHeaders(allowedOrigin, requestOrigin) {
     return base;
 }
 /**
- * Only mutating requests need the token.
+ * Mutating routes that sign NOTHING, and may therefore work without a token.
  *
- * GETs are read-only and the bind is loopback, so they are reachable only from
- * the machine itself. OPTIONS must pass or the browser never reaches the real
- * request and the dashboard breaks for a reason nobody can see.
+ * AN ALLOWLIST, AND THAT DIRECTION IS THE SAFETY ARGUMENT. Gating used to be
+ * by METHOD, so every non-GET needed the token — which cannot exist on a
+ * public box, because `apps/dashboard/app/api/float/[...path]/route.ts`
+ * attaches it to any mutating request WITHOUT authenticating the caller. A
+ * hosted dashboard with a token set is an open `/v1/pay` for the internet,
+ * bounded only by the vault's caps.
+ *
+ * `/v1/owner-plan` qualifies: it returns an UNSIGNED payload and holds no key.
+ * The owner approving it in their own wallet IS the authority, so a token adds
+ * nothing an attacker could not already do by building the payload themselves.
+ *
+ * A DENYLIST OF `/v1/pay` WOULD BE WRONG. The next money-moving route would be
+ * born public and nobody would notice until it was exploited. Named-open means
+ * a new route is born shut and someone has to argue it open in a visible diff.
+ */
+const SIGNS_NOTHING = new Set(["/v1/owner-plan"]);
+/**
+ * Reads are open; mutating routes need the token unless they sign nothing.
+ *
+ * OPTIONS must pass or the browser never reaches the real request and the
+ * dashboard breaks for a reason nobody can see.
  *
  * A MISSING token is 503, not 401. They are different problems: 401 tells a
  * caller to go and find a credential, and here there is none to find — the
  * operator has not configured one. Conflating them sends people hunting for a
  * secret that does not exist.
+ *
+ * `path` is OPTIONAL and an absent one is GATED, never open. A caller that
+ * forgets to pass it gets the safe answer; the alternative defaults to
+ * exposure, which is how the `0.0.0.0` bind above happened.
  */
-export function authorize({ method, authHeader, token, }) {
+export function authorize({ method, path, authHeader, token, }) {
     if (method === "GET" || method === "OPTIONS" || method === "HEAD")
         return { ok: true };
+    // EXACT match only. A prefix or case variant must not inherit the exemption:
+    // `/v1/owner-plan/extra` is a different route and may not exist yet, and
+    // NEAR paths are not case-folded anywhere else in this server.
+    if (path !== undefined && SIGNS_NOTHING.has(path))
+        return { ok: true };
     if (!token) {
         return {
             ok: false,