- {metrics?.sourceMode === "derived" ? "Observed active FIDs · rolling 24h" : "Active FIDs · rolling 24h"}
-
- Exact unique valid FIDs with a qualifying successful user action in (now − 24 hours, now], in UTC.
+ {metrics?.sourceMode === "derived" ? "Observed rolling 24h DAU" : "Rolling 24h DAU"}
+
+ DAU is the exact count of unique valid FIDs with a qualifying successful user action in the shared UTC window (now − 24 hours, now].
-
+
Unique active FIDs · shared UTC window
+
{metrics ? exact(metrics.rolling24h) : "—"}
@@ -90,28 +91,32 @@ export function ProtocolPanel({
<>
{changeDirection === "up" ? "↗" : changeDirection === "down" ? "↘" : "→"}
{signed(metrics.changeAbsolute)}
- {percent(metrics.changePercent)} vs prior 24h
+ {percent(metrics.changePercent)} vs prior 24h DAU
) : {status === "loading" ? "Hydrating exact windows…" : "Waiting for a trustworthy source"}}
- 30d active
- {metrics ? compact(metrics.rolling30d) : "—"}
- {metrics ? `${compact(metrics.todayUtc)} today UTC` : "No source data"}
+ Today UTC DAU
+ {metrics ? compact(metrics.todayUtc) : "—"}
+ {metrics ? "Since 00:00 UTC" : "No source data"}
-
+
Actions/min{metrics ? compact(metrics.actionsPerMinute1m) : "—"}1m
-
Last action{metrics ? ageFrom(metrics.lastActionAtMs, now) : "—"}{metrics ? ageFrom(metrics.updatedAtMs, now) + " update" : "Unavailable"}
-
7d trend{metrics?.trend.label ?? "—"}{metrics ? percent(metrics.trend.percentChange) : "No samples"}
+
+ 30d active FIDs
+ {metrics ? compact(metrics.rolling30d) : "—"}
+ Unique · rolling 30d
+
+
7d DAU trend{metrics?.trend.label ?? "—"}{metrics ? percent(metrics.trend.percentChange) : "No samples"}
-
Today / 30d daily median
+
Today UTC DAU / 30d daily DAU median
{metrics ? `${Math.round((metrics.todayUtc / Math.max(1, metrics.dailyMedian30d)) * 100)}%` : "—"}
diff --git a/apps/dashboard/src/components/heartbeatGeometry.test.ts b/apps/dashboard/src/components/heartbeatGeometry.test.ts
new file mode 100644
index 0000000..8bf44d6
--- /dev/null
+++ b/apps/dashboard/src/components/heartbeatGeometry.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { buildHeartbeatGeometry, HEARTBEAT_GEOMETRY_POINTS } from "./heartbeatGeometry";
+
+describe("heartbeat geometry", () => {
+ it("is deterministic, bounded, and returns quietly to baseline", () => {
+ const first = buildHeartbeatGeometry("snapchain", 17, 24);
+ const again = buildHeartbeatGeometry("snapchain", 17, 24);
+
+ expect(first).toEqual(again);
+ expect(first.samples).toHaveLength(HEARTBEAT_GEOMETRY_POINTS);
+ expect(first.depths).toHaveLength(HEARTBEAT_GEOMETRY_POINTS);
+ expect(first.torsion).toHaveLength(HEARTBEAT_GEOMETRY_POINTS);
+ expect(first.samples[0]).toBe(0);
+ expect(first.samples.at(-1)).toBe(0);
+ expect(first.depths[0]).toBe(0);
+ expect(first.depths.at(-1)).toBe(0);
+ expect(Math.max(...first.samples.map(Math.abs))).toBeLessThanOrEqual(0.78);
+ expect(Math.max(...first.depths)).toBeLessThanOrEqual(1);
+ });
+
+ it("varies successive pulses and gives each source a distinct anatomy", () => {
+ const first = buildHeartbeatGeometry("snapchain", 18, 24);
+ const next = buildHeartbeatGeometry("snapchain", 19, 24);
+ const hyper = buildHeartbeatGeometry("hypersnap", 18, 24);
+
+ expect(next.samples).not.toEqual(first.samples);
+ expect(next.torsion).not.toEqual(first.torsion);
+ expect(hyper.samples).not.toEqual(first.samples);
+ });
+
+ it("uses event volume for size without increasing luminance or escaping its cap", () => {
+ const quiet = buildHeartbeatGeometry("snapchain", 9, 1);
+ const active = buildHeartbeatGeometry("snapchain", 9, 10_000);
+
+ expect(active.amplitude).toBeGreaterThan(quiet.amplitude);
+ expect(active.amplitude).toBe(0.78);
+ });
+});
diff --git a/apps/dashboard/src/components/heartbeatGeometry.ts b/apps/dashboard/src/components/heartbeatGeometry.ts
new file mode 100644
index 0000000..f04ae00
--- /dev/null
+++ b/apps/dashboard/src/components/heartbeatGeometry.ts
@@ -0,0 +1,86 @@
+import type { Source } from "@snapmeter/contracts";
+
+export const HEARTBEAT_GEOMETRY_POINTS = 20;
+
+export interface HeartbeatGeometry {
+ samples: number[];
+ depths: number[];
+ torsion: number[];
+ amplitude: number;
+}
+
+function gaussian(value: number, center: number, width: number): number {
+ const distance = (value - center) / width;
+ return Math.exp(-0.5 * distance * distance);
+}
+
+function seededUnit(seed: number): () => number {
+ let value = seed >>> 0;
+ return () => {
+ value += 0x6d2b79f5;
+ let mixed = value;
+ mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+ mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+ return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
+ };
+}
+
+/**
+ * Builds a bounded, deterministic pulse form. Event count changes its scale,
+ * while pulse identity changes its proportions so live activity never becomes
+ * a repeated ECG stamp.
+ */
+export function buildHeartbeatGeometry(source: Source, pulseId: number, count: number): HeartbeatGeometry {
+ const safePulseId = Number.isSafeInteger(pulseId) ? Math.max(0, pulseId) : 0;
+ const safeCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+ const sourceSeed = source === "snapchain" ? 0x51a7c4d3 : 0x8f31b5e7;
+ const random = seededUnit((safePulseId ^ sourceSeed) >>> 0);
+ const centerShift = (random() - 0.5) * 0.055;
+ const spread = 0.91 + random() * 0.18;
+ const secondary = 0.82 + random() * 0.3;
+ const phase = random() * Math.PI * 2;
+ const topology = Math.floor(random() * 3);
+ const amplitude = Math.min(0.78, 0.24 + Math.log2(safeCount + 1) / 11);
+ const raw: number[] = [];
+ const depths: number[] = [];
+ const torsion: number[] = [];
+
+ for (let index = 0; index < HEARTBEAT_GEOMETRY_POINTS; index += 1) {
+ const t = index / (HEARTBEAT_GEOMETRY_POINTS - 1);
+ const envelope = Math.sin(Math.PI * t) ** 1.45;
+ let value: number;
+
+ if (source === "snapchain") {
+ value =
+ 0.14 * gaussian(t, 0.18 + centerShift, 0.065 * spread)
+ - 0.18 * gaussian(t, 0.32 + centerShift, 0.052 * spread)
+ + (0.94 + topology * 0.045) * gaussian(t, 0.47 + centerShift, 0.084 * spread)
+ - 0.42 * gaussian(t, 0.61 + centerShift, 0.072 * spread)
+ + 0.28 * secondary * gaussian(t, 0.76 + centerShift * 0.4, 0.095 * spread);
+ } else {
+ value =
+ 0.2 * gaussian(t, 0.16 + centerShift * 0.5, 0.07 * spread)
+ - 0.12 * gaussian(t, 0.29 + centerShift, 0.055 * spread)
+ + 0.67 * secondary * gaussian(t, 0.43 + centerShift, 0.1 * spread)
+ - 0.29 * gaussian(t, 0.57 + centerShift, 0.07 * spread)
+ + (0.78 + topology * 0.05) * gaussian(t, 0.7 - centerShift * 0.5, 0.086 * spread)
+ - 0.26 * gaussian(t, 0.83, 0.065 * spread);
+ }
+
+ value += Math.sin(t * Math.PI * (2.1 + topology * 0.28) + phase) * envelope * 0.045;
+ raw.push(index === 0 || index === HEARTBEAT_GEOMETRY_POINTS - 1 ? 0 : value);
+ depths.push(index === 0 || index === HEARTBEAT_GEOMETRY_POINTS - 1
+ ? 0
+ : envelope * (0.46 + 0.16 * Math.sin(t * Math.PI + phase) ** 2));
+ torsion.push(index === 0 || index === HEARTBEAT_GEOMETRY_POINTS - 1
+ ? 0
+ : envelope * Math.sin(t * Math.PI * (1.65 + topology * 0.16) + phase) * 0.62);
+ }
+
+ const maximum = Math.max(...raw.map((value) => Math.abs(value)), 1);
+ const samples = raw.map((value, index) => index === 0 || index === raw.length - 1
+ ? 0
+ : Math.max(-0.78, Math.min(0.78, (value / maximum) * amplitude)));
+
+ return { samples, depths, torsion, amplitude };
+}
diff --git a/apps/dashboard/src/data/demo.ts b/apps/dashboard/src/data/demo.ts
index c1ef3f3..7719de4 100644
--- a/apps/dashboard/src/data/demo.ts
+++ b/apps/dashboard/src/data/demo.ts
@@ -54,7 +54,9 @@ function sourceMetrics(source: Source, random: () => number): SourceMetrics {
sourceMode: isSnapchain ? "verified" : "derived",
status: "demo",
quality: isSnapchain ? "high" : "derived",
- updatedAtMs: DEMO_CLOCK_MS - (isSnapchain ? 1_200 : 2_800),
+ // Both sources share one metric-window anchor. Source-specific collector
+ // freshness remains represented independently by lastCollectorAtMs.
+ updatedAtMs: DEMO_CLOCK_MS - 2_800,
lastActionAtMs: DEMO_CLOCK_MS - (isSnapchain ? 4_000 : 7_000),
lastCollectorAtMs: DEMO_CLOCK_MS - (isSnapchain ? 1_200 : 2_800),
rolling24h,
diff --git a/apps/dashboard/src/farcaster/MiniAppProvider.test.tsx b/apps/dashboard/src/farcaster/MiniAppProvider.test.tsx
new file mode 100644
index 0000000..e8101d4
--- /dev/null
+++ b/apps/dashboard/src/farcaster/MiniAppProvider.test.tsx
@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+import { StrictMode } from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { MiniAppProvider, useMiniAppHost } from "./MiniAppProvider";
+import type {
+ MiniAppBrowserRuntime,
+ MiniAppSdk
+} from "./miniAppRuntime";
+
+function makeShell(): HTMLDivElement {
+ const shell = document.createElement("div");
+ shell.dataset.miniAppTestShell = "true";
+ document.body.appendChild(shell);
+ return shell;
+}
+
+function runtimeFor(
+ shell: Element,
+ search = "?miniApp=true"
+): MiniAppBrowserRuntime {
+ return Object.freeze({
+ search: () => search,
+ viewport: () => ({ width: 390, height: 844 }),
+ document,
+ getMountedShell: () => shell,
+ waitForAnimationFrame: vi.fn(async () => {})
+ });
+}
+
+function HostState(): React.JSX.Element {
+ const host = useMiniAppHost();
+ return (
+
+ );
+}
+
+afterEach(() => {
+ document.querySelectorAll("[data-mini-app-test-shell]").forEach((node) => {
+ node.remove();
+ });
+ for (const property of ["top", "right", "bottom", "left"]) {
+ document.documentElement.style.removeProperty(`--fc-safe-area-inset-${property}`);
+ }
+});
+
+describe("MiniAppProvider", () => {
+ it("does not load the SDK without the exact Mini App hint", () => {
+ const shell = makeShell();
+ const sdkLoader = vi.fn();
+ render(
+
+ Dashboard remains available
+ ,
+ { container: shell }
+ );
+
+ expect(screen.getByText("Dashboard remains available")).toBeVisible();
+ expect(sdkLoader).not.toHaveBeenCalled();
+ });
+
+ it("signals ready once under StrictMode and exposes only the server-verified FID", async () => {
+ const shell = makeShell();
+ const ready = vi.fn(async () => {});
+ const quickAuthFetch = vi.fn(async () => new Response(
+ JSON.stringify({
+ schemaVersion: 1,
+ authenticated: true,
+ fid: 777,
+ username: "ignored-server-field"
+ }),
+ { status: 200, headers: { "content-type": "application/json; charset=utf-8" } }
+ ));
+ const sdk: MiniAppSdk = {
+ isInMiniApp: vi.fn(async () => true),
+ context: Promise.resolve({
+ user: { fid: 111, username: "untrusted-host-name" },
+ client: {
+ clientFid: 9_152,
+ safeAreaInsets: { top: 20, right: 4, bottom: 16, left: 4 }
+ }
+ }),
+ actions: { ready },
+ quickAuth: { fetch: quickAuthFetch }
+ };
+ const sdkLoader = vi.fn(async () => sdk);
+
+ render(
+
+
+ Dashboard remains available
+
+
+ ,
+ { container: shell }
+ );
+
+ expect(screen.getByText("Dashboard remains available")).toBeVisible();
+ await waitFor(() => {
+ expect(screen.getByTestId("miniapp-state")).toHaveTextContent("miniapp · 777");
+ });
+ expect(screen.queryByText(/FID 777/i)).not.toBeInTheDocument();
+ expect(screen.queryByText(/FID 111/i)).not.toBeInTheDocument();
+ expect(ready).toHaveBeenCalledTimes(1);
+ expect(ready).toHaveBeenCalledWith({ disableNativeGestures: true });
+ expect(quickAuthFetch).toHaveBeenCalledTimes(1);
+ expect(quickAuthFetch).toHaveBeenCalledWith(
+ "/api/v1/farcaster/me",
+ expect.objectContaining({
+ method: "GET",
+ credentials: "omit",
+ headers: { Accept: "application/json" },
+ signal: expect.any(AbortSignal)
+ })
+ );
+ expect(document.documentElement.style.getPropertyValue(
+ "--fc-safe-area-inset-top"
+ )).toBe("20px");
+ });
+
+ it("falls back to public web without gating the dashboard", async () => {
+ const shell = makeShell();
+ const ready = vi.fn(async () => {});
+ const quickAuthFetch = vi.fn();
+ const sdk: MiniAppSdk = {
+ isInMiniApp: vi.fn(async () => false),
+ context: Promise.resolve({}),
+ actions: { ready },
+ quickAuth: { fetch: quickAuthFetch }
+ };
+
+ render(
+
sdk}
+ >
+ Dashboard remains available
+
+ ,
+ { container: shell }
+ );
+
+ expect(screen.getByText("Dashboard remains available")).toBeVisible();
+ await waitFor(() => {
+ expect(screen.getByTestId("miniapp-state")).toHaveTextContent("regular-web");
+ });
+ expect(ready).not.toHaveBeenCalled();
+ expect(quickAuthFetch).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/dashboard/src/farcaster/MiniAppProvider.tsx b/apps/dashboard/src/farcaster/MiniAppProvider.tsx
new file mode 100644
index 0000000..996db38
--- /dev/null
+++ b/apps/dashboard/src/farcaster/MiniAppProvider.tsx
@@ -0,0 +1,295 @@
+import {
+ createContext,
+ useContext,
+ useEffect,
+ useMemo,
+ useState,
+ type ReactNode
+} from "react";
+
+import {
+ DEFAULT_MINI_APP_BROWSER_RUNTIME,
+ defaultMiniAppSdkLoader,
+ hasExactMiniAppHint,
+ installMiniAppSafeAreaVariables,
+ readMiniAppSdk,
+ sanitizeMiniAppContext,
+ type MiniAppBrowserRuntime,
+ type MiniAppSdk,
+ type MiniAppSdkLoader
+} from "./miniAppRuntime";
+
+export type MiniAppHostState = "regular-web" | "detecting" | "miniapp";
+
+export type MiniAppHostValue = Readonly<{
+ state: MiniAppHostState;
+ isMiniApp: boolean;
+ /** This FID has been verified by SnapMeter's server, not copied from host context. */
+ verifiedFid: number | null;
+}>;
+
+export type MiniAppProviderProps = Readonly<{
+ children: ReactNode;
+ sdkLoader?: MiniAppSdkLoader;
+ runtime?: MiniAppBrowserRuntime;
+ /** Test seam; production keeps host operations bounded to four seconds. */
+ deadlineMilliseconds?: number;
+}>;
+
+const DEFAULT_HOST_DEADLINE_MILLISECONDS = 4_000;
+const MAX_IDENTITY_RESPONSE_BYTES = 1_024;
+const IDENTITY_PATH = "/api/v1/farcaster/me";
+
+const REGULAR_WEB_VALUE: MiniAppHostValue = Object.freeze({
+ state: "regular-web",
+ isMiniApp: false,
+ verifiedFid: null
+});
+
+const MiniAppHostContext = createContext
(REGULAR_WEB_VALUE);
+
+class MiniAppDeadlineError extends Error {
+ constructor() {
+ super("Mini App host operation timed out.");
+ this.name = "MiniAppDeadlineError";
+ }
+}
+
+function normalizedDeadline(value: number | undefined): number {
+ return Number.isFinite(value)
+ ? Math.min(10_000, Math.max(50, Math.round(value!)))
+ : DEFAULT_HOST_DEADLINE_MILLISECONDS;
+}
+
+function withDeadline(operation: PromiseLike, milliseconds: number): Promise {
+ return new Promise((resolve, reject) => {
+ let settled = false;
+ const finish = (callback: () => void) => {
+ if (settled) return;
+ settled = true;
+ window.clearTimeout(timer);
+ callback();
+ };
+ const timer = window.setTimeout(() => {
+ finish(() => reject(new MiniAppDeadlineError()));
+ }, milliseconds);
+ Promise.resolve(operation).then(
+ (value) => finish(() => resolve(value)),
+ (error: unknown) => finish(() => reject(error))
+ );
+ });
+}
+
+// React StrictMode replays effects. Sharing the SDK-bound attempt prevents a
+// verified page mount from signaling readiness twice.
+const READY_ATTEMPTS = new WeakMap>();
+
+function signalReadyOnce(sdk: MiniAppSdk, deadline: number): Promise {
+ const existing = READY_ATTEMPTS.get(sdk);
+ if (existing) return existing;
+
+ const actions = sdk.actions;
+ const attempt = withDeadline(
+ Promise.resolve().then(() => actions.ready.call(actions, {
+ disableNativeGestures: true
+ })),
+ deadline
+ );
+ READY_ATTEMPTS.set(sdk, attempt);
+ void attempt.catch(() => {
+ if (READY_ATTEMPTS.get(sdk) === attempt) READY_ATTEMPTS.delete(sdk);
+ });
+ return attempt;
+}
+
+function positiveFid(value: unknown): number | null {
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+ ? value
+ : null;
+}
+
+async function readVerifiedFid(response: Response): Promise {
+ if (!response.ok) return null;
+ const contentType = response.headers.get("content-type") ?? "";
+ if (!/^application\/json(?:\s*;.*)?$/i.test(contentType)) return null;
+
+ const advertisedLength = response.headers.get("content-length");
+ if (
+ advertisedLength !== null
+ && (!/^\d+$/.test(advertisedLength)
+ || Number(advertisedLength) > MAX_IDENTITY_RESPONSE_BYTES)
+ ) {
+ return null;
+ }
+
+ let source: string;
+ try {
+ source = await response.text();
+ } catch {
+ return null;
+ }
+ if (
+ source.length === 0
+ || new TextEncoder().encode(source).byteLength > MAX_IDENTITY_RESPONSE_BYTES
+ ) {
+ return null;
+ }
+
+ try {
+ const parsed: unknown = JSON.parse(source);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+ return null;
+ }
+ const envelope = parsed as Record;
+ if (envelope.schemaVersion !== 1 || envelope.authenticated !== true) {
+ return null;
+ }
+ return positiveFid(envelope.fid);
+ } catch {
+ return null;
+ }
+}
+
+async function fetchVerifiedFid(
+ sdk: MiniAppSdk,
+ signal: AbortSignal
+): Promise {
+ const quickAuth = sdk.quickAuth;
+ if (!quickAuth || typeof quickAuth.fetch !== "function") return null;
+ try {
+ const response = await quickAuth.fetch.call(quickAuth, IDENTITY_PATH, {
+ method: "GET",
+ credentials: "omit",
+ headers: { Accept: "application/json" },
+ signal
+ });
+ return await readVerifiedFid(response);
+ } catch {
+ return null;
+ }
+}
+
+export function MiniAppProvider({
+ children,
+ sdkLoader = defaultMiniAppSdkLoader,
+ runtime = DEFAULT_MINI_APP_BROWSER_RUNTIME,
+ deadlineMilliseconds
+}: MiniAppProviderProps): React.JSX.Element {
+ const hinted = hasExactMiniAppHint(runtime.search());
+ const deadline = normalizedDeadline(deadlineMilliseconds);
+ const [value, setValue] = useState(
+ hinted
+ ? Object.freeze({ state: "detecting", isMiniApp: false, verifiedFid: null })
+ : REGULAR_WEB_VALUE
+ );
+
+ useEffect(() => {
+ if (!hinted) {
+ setValue(REGULAR_WEB_VALUE);
+ return;
+ }
+
+ let cancelled = false;
+ let removeSafeAreaVariables: (() => void) | undefined;
+ const authController = new AbortController();
+ setValue(Object.freeze({
+ state: "detecting",
+ isMiniApp: false,
+ verifiedFid: null
+ }));
+
+ const recoverToWeb = () => {
+ if (cancelled) return;
+ removeSafeAreaVariables?.();
+ removeSafeAreaVariables = undefined;
+ setValue(REGULAR_WEB_VALUE);
+ };
+
+ void (async () => {
+ let sdk: MiniAppSdk;
+ try {
+ const candidate = readMiniAppSdk(await withDeadline(sdkLoader(), deadline));
+ if (!candidate) {
+ recoverToWeb();
+ return;
+ }
+ sdk = candidate;
+ const isMiniApp = await withDeadline(sdk.isInMiniApp(), deadline);
+ if (cancelled) return;
+ if (isMiniApp !== true) {
+ recoverToWeb();
+ return;
+ }
+
+ const context = sanitizeMiniAppContext(
+ await withDeadline(sdk.context, deadline),
+ runtime.viewport()
+ );
+ if (cancelled) return;
+ if (!context) {
+ recoverToWeb();
+ return;
+ }
+ removeSafeAreaVariables = installMiniAppSafeAreaVariables(
+ runtime.document,
+ context.safeAreaInsets
+ );
+
+ const shell = runtime.getMountedShell();
+ if (!shell?.isConnected || shell.childNodes.length === 0) {
+ recoverToWeb();
+ return;
+ }
+ await withDeadline(runtime.waitForAnimationFrame(), deadline);
+ await withDeadline(runtime.waitForAnimationFrame(), deadline);
+ if (
+ cancelled
+ || runtime.getMountedShell() !== shell
+ || !shell.isConnected
+ || shell.childNodes.length === 0
+ ) {
+ if (!cancelled) recoverToWeb();
+ return;
+ }
+
+ await signalReadyOnce(sdk, deadline);
+ if (cancelled) return;
+ setValue(Object.freeze({
+ state: "miniapp",
+ isMiniApp: true,
+ verifiedFid: null
+ }));
+
+ // Authentication enriches the already-visible dashboard; it never
+ // gates metrics or trusts the presentation-only host FID above.
+ void fetchVerifiedFid(sdk, authController.signal).then((verifiedFid) => {
+ if (cancelled || verifiedFid === null) return;
+ setValue(Object.freeze({
+ state: "miniapp",
+ isMiniApp: true,
+ verifiedFid
+ }));
+ });
+ } catch {
+ recoverToWeb();
+ }
+ })();
+
+ return () => {
+ cancelled = true;
+ authController.abort();
+ removeSafeAreaVariables?.();
+ };
+ }, [deadline, hinted, runtime, sdkLoader]);
+
+ const contextValue = useMemo(() => value, [value]);
+ return (
+
+ {children}
+
+ );
+}
+
+export function useMiniAppHost(): MiniAppHostValue {
+ return useContext(MiniAppHostContext);
+}
diff --git a/apps/dashboard/src/farcaster/index.ts b/apps/dashboard/src/farcaster/index.ts
new file mode 100644
index 0000000..1612fcf
--- /dev/null
+++ b/apps/dashboard/src/farcaster/index.ts
@@ -0,0 +1,18 @@
+export {
+ MiniAppProvider,
+ useMiniAppHost,
+ type MiniAppHostState,
+ type MiniAppHostValue,
+ type MiniAppProviderProps
+} from "./MiniAppProvider";
+
+export {
+ hasExactMiniAppHint,
+ installMiniAppSafeAreaVariables,
+ sanitizeMiniAppContext,
+ type MiniAppBrowserRuntime,
+ type MiniAppPresentationContext,
+ type MiniAppSafeAreaInsets,
+ type MiniAppSdk,
+ type MiniAppSdkLoader
+} from "./miniAppRuntime";
diff --git a/apps/dashboard/src/farcaster/miniAppRuntime.test.ts b/apps/dashboard/src/farcaster/miniAppRuntime.test.ts
new file mode 100644
index 0000000..6e50bf7
--- /dev/null
+++ b/apps/dashboard/src/farcaster/miniAppRuntime.test.ts
@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ defaultMiniAppSdkLoader,
+ hasExactMiniAppHint,
+ installMiniAppSafeAreaVariables,
+ sanitizeMiniAppContext
+} from "./miniAppRuntime";
+
+describe("Mini App runtime boundary", () => {
+ afterEach(() => {
+ for (const property of ["top", "right", "bottom", "left"]) {
+ document.documentElement.style.removeProperty(`--fc-safe-area-inset-${property}`);
+ }
+ });
+
+ it("accepts exactly one literal miniApp=true query entry", () => {
+ expect(hasExactMiniAppHint("?miniApp=true")).toBe(true);
+ expect(hasExactMiniAppHint("?demo=1&miniApp=true")).toBe(true);
+ expect(hasExactMiniAppHint("?miniApp=false")).toBe(false);
+ expect(hasExactMiniAppHint("?miniApp=True")).toBe(false);
+ expect(hasExactMiniAppHint("?miniApp=%74rue")).toBe(false);
+ expect(hasExactMiniAppHint("?miniApp=true&miniApp=true")).toBe(false);
+ expect(hasExactMiniAppHint("?miniApp=true&miniApp=false")).toBe(false);
+ });
+
+ it("keeps only bounded presentation FIDs and safe-area values", () => {
+ expect(sanitizeMiniAppContext({
+ user: { fid: 44, username: "untrusted-host-name" },
+ client: {
+ clientFid: 9_152,
+ safeAreaInsets: { top: 999, right: -3, bottom: 24.4567, left: 8 }
+ },
+ authorization: "must-not-cross"
+ }, { width: 320, height: 640 })).toEqual({
+ fid: 44,
+ clientFid: 9_152,
+ safeAreaInsets: { top: 160, right: 0, bottom: 24.457, left: 8 }
+ });
+
+ expect(sanitizeMiniAppContext({
+ user: { fid: "44" },
+ client: { clientFid: 9_152 }
+ }, { width: 320, height: 640 })).toBeNull();
+ });
+
+ it("installs and removes only the sanitized CSS variables", () => {
+ document.documentElement.style.setProperty("--fc-safe-area-inset-left", "1px");
+ const remove = installMiniAppSafeAreaVariables(document, {
+ top: 12,
+ right: 7,
+ bottom: 18,
+ left: 3
+ });
+ expect(document.head.querySelector("[data-snapmeter-miniapp-safe-area]")).toBeNull();
+ expect(document.documentElement.style.getPropertyValue("--fc-safe-area-inset-top")).toBe("12px");
+ expect(document.documentElement.style.getPropertyValue("--fc-safe-area-inset-bottom")).toBe("18px");
+ expect(document.documentElement.style.getPropertyValue("--fc-safe-area-inset-left")).toBe("3px");
+ remove();
+ expect(document.documentElement.style.getPropertyValue("--fc-safe-area-inset-top")).toBe("");
+ expect(document.documentElement.style.getPropertyValue("--fc-safe-area-inset-left")).toBe("1px");
+ });
+
+ it("loads the narrow host bridge without requiring wallet capabilities", async () => {
+ const sdk = await defaultMiniAppSdkLoader();
+ expect(sdk).toMatchObject({
+ isInMiniApp: expect.any(Function),
+ actions: { ready: expect.any(Function) },
+ quickAuth: { fetch: expect.any(Function) }
+ });
+ await expect((sdk as { isInMiniApp: () => Promise }).isInMiniApp()).resolves.toBe(false);
+ });
+});
diff --git a/apps/dashboard/src/farcaster/miniAppRuntime.ts b/apps/dashboard/src/farcaster/miniAppRuntime.ts
new file mode 100644
index 0000000..2489064
--- /dev/null
+++ b/apps/dashboard/src/farcaster/miniAppRuntime.ts
@@ -0,0 +1,290 @@
+export type MiniAppSafeAreaInsets = Readonly<{
+ top: number;
+ right: number;
+ bottom: number;
+ left: number;
+}>;
+
+/** Host identity is presentation-only; server-verified identity is separate. */
+export type MiniAppPresentationContext = Readonly<{
+ fid: number;
+ clientFid: number;
+ safeAreaInsets: MiniAppSafeAreaInsets;
+}>;
+
+export type MiniAppSdk = Readonly<{
+ isInMiniApp: () => Promise;
+ context: Promise;
+ actions: Readonly<{
+ ready: (options: { disableNativeGestures: true }) => Promise;
+ }>;
+ quickAuth?: Readonly<{
+ fetch: typeof fetch;
+ }>;
+}>;
+
+export type MiniAppSdkLoader = () => Promise;
+
+type MiniAppHost = Readonly<{
+ context: Promise;
+ ready: (options: { disableNativeGestures: true }) => Promise;
+ signIn: (options: { nonce: string; acceptAuthAddress: true }) => Promise;
+}>;
+
+type QuickAuthLightClient = Readonly<{
+ generateNonce: () => Promise<{ nonce: string }>;
+ verifySiwf: (options: {
+ domain: string;
+ message: string;
+ signature: string;
+ }) => Promise<{ token: string }>;
+}>;
+
+export type MiniAppBrowserRuntime = Readonly<{
+ search: () => string;
+ viewport: () => Readonly<{ width: number; height: number }>;
+ document: Document;
+ getMountedShell: () => Element | null;
+ waitForAnimationFrame: () => Promise;
+}>;
+
+const SAFE_AREA_PROPERTIES = [
+ "--fc-safe-area-inset-top",
+ "--fc-safe-area-inset-right",
+ "--fc-safe-area-inset-bottom",
+ "--fc-safe-area-inset-left"
+] as const;
+const FRAME_FALLBACK_MILLISECONDS = 160;
+const MINI_APP_DETECTION_MILLISECONDS = 1_000;
+const TOKEN_REFRESH_SKEW_SECONDS = 15;
+
+function isRecord(value: unknown): value is Record {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function positiveFid(value: unknown): number | null {
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+ ? value
+ : null;
+}
+
+function positiveAxis(value: unknown): number {
+ return typeof value === "number" && Number.isFinite(value) && value > 0
+ ? value
+ : 0;
+}
+
+function clampInset(value: unknown, axis: number): number {
+ const untrusted = typeof value === "number" && Number.isFinite(value)
+ ? value
+ : 0;
+ const maximum = Math.min(160, positiveAxis(axis) * 0.25);
+ return Math.round(Math.min(maximum, Math.max(0, untrusted)) * 1_000) / 1_000;
+}
+
+/** Accept exactly one literal query entry; encoded or duplicate hints are inert. */
+export function hasExactMiniAppHint(search: string): boolean {
+ if (typeof search !== "string" || !search.startsWith("?")) return false;
+ const matches = search
+ .slice(1)
+ .split("&")
+ .filter((segment) => segment === "miniApp=true");
+ if (matches.length !== 1) return false;
+ const values = new URLSearchParams(search).getAll("miniApp");
+ return values.length === 1 && values[0] === "true";
+}
+
+export function readMiniAppSdk(value: unknown): MiniAppSdk | null {
+ if (!isRecord(value) || !isRecord(value.actions)) return null;
+ if (
+ typeof value.isInMiniApp !== "function"
+ || typeof value.actions.ready !== "function"
+ ) {
+ return null;
+ }
+ return value as unknown as MiniAppSdk;
+}
+
+export function sanitizeMiniAppContext(
+ value: unknown,
+ viewport: Readonly<{ width: number; height: number }>
+): MiniAppPresentationContext | null {
+ try {
+ if (!isRecord(value) || !isRecord(value.user) || !isRecord(value.client)) {
+ return null;
+ }
+ const fid = positiveFid(value.user.fid);
+ const clientFid = positiveFid(value.client.clientFid);
+ if (fid === null || clientFid === null) return null;
+
+ const rawInsets = isRecord(value.client.safeAreaInsets)
+ ? value.client.safeAreaInsets
+ : {};
+ return Object.freeze({
+ fid,
+ clientFid,
+ safeAreaInsets: Object.freeze({
+ top: clampInset(rawInsets.top, viewport.height),
+ right: clampInset(rawInsets.right, viewport.width),
+ bottom: clampInset(rawInsets.bottom, viewport.height),
+ left: clampInset(rawInsets.left, viewport.width)
+ })
+ });
+ } catch {
+ return null;
+ }
+}
+
+export function installMiniAppSafeAreaVariables(
+ document: Document,
+ insets: MiniAppSafeAreaInsets
+): () => void {
+ const root = document.documentElement;
+ const previous = SAFE_AREA_PROPERTIES.map((property) => ({
+ property,
+ value: root.style.getPropertyValue(property),
+ priority: root.style.getPropertyPriority(property)
+ }));
+ root.style.setProperty(SAFE_AREA_PROPERTIES[0], `${insets.top}px`);
+ root.style.setProperty(SAFE_AREA_PROPERTIES[1], `${insets.right}px`);
+ root.style.setProperty(SAFE_AREA_PROPERTIES[2], `${insets.bottom}px`);
+ root.style.setProperty(SAFE_AREA_PROPERTIES[3], `${insets.left}px`);
+ return () => {
+ for (const value of previous) {
+ if (value.value) root.style.setProperty(value.property, value.value, value.priority);
+ else root.style.removeProperty(value.property);
+ }
+ };
+}
+
+function defaultViewport(): Readonly<{ width: number; height: number }> {
+ const root = document.documentElement;
+ return Object.freeze({
+ width: positiveAxis(window.innerWidth) || positiveAxis(root.clientWidth),
+ height: positiveAxis(window.innerHeight) || positiveAxis(root.clientHeight)
+ });
+}
+
+function waitForBoundedAnimationFrame(): Promise {
+ return new Promise((resolve) => {
+ let settled = false;
+ let frame = 0;
+ const finish = () => {
+ if (settled) return;
+ settled = true;
+ window.clearTimeout(timeout);
+ window.cancelAnimationFrame(frame);
+ resolve();
+ };
+ const timeout = window.setTimeout(finish, FRAME_FALLBACK_MILLISECONDS);
+ frame = window.requestAnimationFrame(finish);
+ });
+}
+
+export const DEFAULT_MINI_APP_BROWSER_RUNTIME: MiniAppBrowserRuntime =
+ Object.freeze({
+ search: () => window.location.search,
+ viewport: defaultViewport,
+ document,
+ getMountedShell: () => document.getElementById("root"),
+ waitForAnimationFrame: waitForBoundedAnimationFrame
+ });
+
+function tokenExpiresAfter(token: string, nowSeconds: number): boolean {
+ try {
+ if (token.length > 8 * 1_024) return false;
+ const segment = token.split(".")[1];
+ if (!segment || !/^[A-Za-z0-9_-]+$/.test(segment)) return false;
+ const normalized = segment.replaceAll("-", "+").replaceAll("_", "/");
+ const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+ const payload: unknown = JSON.parse(window.atob(padded));
+ return isRecord(payload)
+ && typeof payload.exp === "number"
+ && Number.isSafeInteger(payload.exp)
+ && payload.exp > nowSeconds + TOKEN_REFRESH_SKEW_SECONDS;
+ } catch {
+ return false;
+ }
+}
+
+function createQuickAuthFetch(
+ miniAppHost: MiniAppHost,
+ quickAuthClient: QuickAuthLightClient
+): typeof fetch {
+ let currentToken: string | undefined;
+ let pendingToken: Promise | undefined;
+
+ const getToken = async (): Promise => {
+ const nowSeconds = Math.floor(Date.now() / 1_000);
+ if (currentToken && tokenExpiresAfter(currentToken, nowSeconds)) return currentToken;
+ if (pendingToken) return pendingToken;
+
+ pendingToken = (async () => {
+ const { nonce } = await quickAuthClient.generateNonce();
+ const response = await miniAppHost.signIn({ nonce, acceptAuthAddress: true });
+ if (!isRecord(response) || !isRecord(response.result)) {
+ throw new Error("Quick Auth was not approved.");
+ }
+ const message = response.result.message;
+ const signature = response.result.signature;
+ if (typeof message !== "string" || typeof signature !== "string") {
+ throw new Error("Quick Auth returned an invalid response.");
+ }
+ const verified = await quickAuthClient.verifySiwf({
+ // Fail closed against the actual loaded origin. A host-supplied SIWE
+ // message for any other domain cannot mint a token for SnapMeter.
+ domain: window.location.host,
+ message,
+ signature
+ });
+ if (!isRecord(verified) || typeof verified.token !== "string") {
+ throw new Error("Quick Auth returned an invalid token.");
+ }
+ currentToken = verified.token;
+ return verified.token;
+ })().finally(() => {
+ pendingToken = undefined;
+ });
+ return pendingToken;
+ };
+
+ return async (input: RequestInfo | URL, init?: RequestInit): Promise => {
+ const token = await getToken();
+ const headers = new Headers(init?.headers);
+ headers.set("Authorization", `Bearer ${token}`);
+ return fetch(input, { ...init, headers });
+ };
+}
+
+export const defaultMiniAppSdkLoader: MiniAppSdkLoader = async () => {
+ // Import only the host bridge. The SDK root re-exports optional Solana
+ // support, which would otherwise ship an unused wallet/RPC stack in this
+ // read-only dashboard's browser bundle.
+ const [{ miniAppHost }, { createLightClient }] = await Promise.all([
+ import("@farcaster/miniapp-sdk/dist/miniAppHost.js"),
+ import("@farcaster/quick-auth/light")
+ ]);
+ const host = miniAppHost as unknown as MiniAppHost;
+ const context = host.context;
+ const isInMiniApp = async (): Promise => {
+ const webView = (window as Window & { ReactNativeWebView?: unknown }).ReactNativeWebView;
+ if (!webView && window === window.parent) return false;
+ return await Promise.race([
+ Promise.resolve(context).then(Boolean).catch(() => false),
+ new Promise((resolve) => window.setTimeout(
+ () => resolve(false),
+ MINI_APP_DETECTION_MILLISECONDS
+ ))
+ ]);
+ };
+
+ const quickAuthClient = createLightClient() as unknown as QuickAuthLightClient;
+ return Object.freeze({
+ isInMiniApp,
+ context,
+ actions: Object.freeze({
+ ready: (options: { disableNativeGestures: true }) => host.ready(options)
+ }),
+ quickAuth: Object.freeze({ fetch: createQuickAuthFetch(host, quickAuthClient) })
+ }) satisfies MiniAppSdk;
+};
diff --git a/apps/dashboard/src/hooks/useLiveMetrics.test.tsx b/apps/dashboard/src/hooks/useLiveMetrics.test.tsx
index a625ebf..af5e149 100644
--- a/apps/dashboard/src/hooks/useLiveMetrics.test.tsx
+++ b/apps/dashboard/src/hooks/useLiveMetrics.test.tsx
@@ -82,7 +82,7 @@ describe("live dashboard transport", () => {
};
act(() => socket.receive(pulse));
- expect(result.current.pulses.snapchain).toMatchObject({ id: 1, count: 12 });
+ expect(result.current.pulses.snapchain).toMatchObject({ id: 1, count: 12, lastActionAtMs: 1_200 });
act(() => socket.receive(pulse));
expect(result.current.pulses.snapchain.id).toBe(1);
act(() => socket.receive({ ...pulse, sequence: 8, data: { ...pulse.data, eventCount: 3 } }));
@@ -91,6 +91,24 @@ describe("live dashboard transport", () => {
expect(result.current.pulses.snapchain.id).toBe(1);
act(() => socket.receive({ ...pulse, sequence: 10, deliveryId: "00000000-0000-4000-8000-000000000002:pulse:0", deliveryIds: undefined, data: { ...pulse.data, eventCount: 3 } }));
expect(result.current.pulses.snapchain).toMatchObject({ id: 2, count: 3 });
+
+ const metricWindowEnd = result.current.summary!.sources.snapchain.updatedAtMs;
+ act(() => socket.receive({
+ type: "status",
+ schemaVersion: 1,
+ sequence: 11,
+ deliveryId: "00000000-0000-4000-8000-000000000002:status:0",
+ data: {
+ schemaVersion: 1,
+ source: "snapchain",
+ sourceMode: "verified",
+ status: "partial",
+ observedAtMs: metricWindowEnd + 5_000,
+ node: result.current.summary!.sources.snapchain.node,
+ message: null
+ }
+ }));
+ expect(result.current.summary!.sources.snapchain.updatedAtMs).toBe(metricWindowEnd);
});
it("never substitutes demo data after a server failure", async () => {
diff --git a/apps/dashboard/src/hooks/useLiveMetrics.ts b/apps/dashboard/src/hooks/useLiveMetrics.ts
index 7efa706..33e9971 100644
--- a/apps/dashboard/src/hooks/useLiveMetrics.ts
+++ b/apps/dashboard/src/hooks/useLiveMetrics.ts
@@ -7,12 +7,12 @@ export type TransportState = "loading" | "connecting" | "live" | "reconnecting"
export interface PulseState {
id: number;
count: number;
- observedAtMs: number | null;
+ lastActionAtMs: number | null;
}
const EMPTY_PULSE: Record = {
- snapchain: { id: 0, count: 0, observedAtMs: null },
- hypersnap: { id: 0, count: 0, observedAtMs: null }
+ snapchain: { id: 0, count: 0, lastActionAtMs: null },
+ hypersnap: { id: 0, count: 0, lastActionAtMs: null }
};
export function applyClientFreshness(summary: Summary, nowMs: number): Summary {
@@ -176,7 +176,7 @@ export function useLiveMetrics(): {
[envelope.data.source]: {
id: current[envelope.data.source].id + 1,
count: envelope.data.eventCount,
- observedAtMs: envelope.data.windowEndMs
+ lastActionAtMs: envelope.data.lastActionAtMs
}
}));
} else if (envelope.type === "status") {
@@ -188,7 +188,6 @@ export function useLiveMetrics(): {
...current.sources[envelope.data.source],
sourceMode: envelope.data.sourceMode,
status: envelope.data.status,
- updatedAtMs: envelope.data.observedAtMs,
node: envelope.data.node,
caveat: envelope.data.message
}
diff --git a/apps/dashboard/src/styles.css b/apps/dashboard/src/styles.css
index 5f33c64..595d62f 100644
--- a/apps/dashboard/src/styles.css
+++ b/apps/dashboard/src/styles.css
@@ -16,6 +16,10 @@
--green: #6ee7b7;
--amber: #ffd166;
--red: #ff817b;
+ --fc-safe-area-inset-top: 0px;
+ --fc-safe-area-inset-right: 0px;
+ --fc-safe-area-inset-bottom: 0px;
+ --fc-safe-area-inset-left: 0px;
background: var(--surface);
color: var(--ink);
}
@@ -126,7 +130,7 @@ canvas:focus-visible {
min-width: 0;
min-height: 0;
overflow: hidden;
- padding: max(12px, env(safe-area-inset-top)) max(14px, env(safe-area-inset-right)) 10px max(14px, env(safe-area-inset-left));
+ padding: max(12px, env(safe-area-inset-top), var(--fc-safe-area-inset-top)) max(14px, env(safe-area-inset-right), var(--fc-safe-area-inset-right)) 10px max(14px, env(safe-area-inset-left), var(--fc-safe-area-inset-left));
border-bottom: 1px solid rgba(var(--accent-rgb), 0.24);
background:
linear-gradient(90deg, rgba(var(--accent-rgb), 0.025) 1px, transparent 1px),
@@ -140,7 +144,7 @@ canvas:focus-visible {
--accent: var(--violet);
--accent-rgb: 188, 127, 255;
padding-top: 10px;
- padding-bottom: max(12px, env(safe-area-inset-bottom));
+ padding-bottom: max(12px, env(safe-area-inset-bottom), var(--fc-safe-area-inset-bottom));
border-bottom: 0;
background-position: 13px 8px, 13px 8px, center, center;
}
@@ -169,21 +173,6 @@ canvas:focus-visible {
box-shadow: 0 0 0 2rem rgba(var(--accent-rgb), 0.015), 0 0 0 4rem rgba(var(--accent-rgb), 0.012);
}
-.panel-glow {
- position: absolute;
- z-index: -1;
- inset: 0;
- pointer-events: none;
- background: radial-gradient(circle at 42% 55%, rgba(var(--accent-rgb), 0.12), transparent 56%);
- animation: panel-pulse 520ms ease-out both;
-}
-
-@keyframes panel-pulse {
- 0% { opacity: 0; }
- 20% { opacity: 1; }
- 100% { opacity: 0; }
-}
-
.protocol-head {
display: flex;
align-items: flex-start;
@@ -281,6 +270,10 @@ canvas:focus-visible {
font-weight: 500;
}
+.protocol-wordmark span {
+ color: var(--accent);
+}
+
.primary-metric {
display: flex;
align-items: flex-end;
@@ -297,7 +290,7 @@ canvas:focus-visible {
display: flex;
align-items: center;
gap: 6px;
- margin: 0 0 2px;
+ margin: 0;
color: #b6c0ca;
font-family: ui-monospace, "SFMono-Regular", Consolas, monospace;
font-size: clamp(0.57rem, 2.25vw, 0.69rem);
@@ -306,6 +299,14 @@ canvas:focus-visible {
white-space: nowrap;
}
+.metric-window {
+ margin: 1px 0 3px;
+ color: var(--dim);
+ font-family: ui-monospace, "SFMono-Regular", Consolas, monospace;
+ font-size: clamp(0.49rem, 1.8vw, 0.57rem);
+ line-height: 1.15;
+}
+
.metric-number {
overflow: hidden;
color: #f7fbfd;
@@ -388,6 +389,8 @@ canvas:focus-visible {
}
.heartbeat-heading {
+ position: relative;
+ z-index: 2;
display: flex;
align-items: center;
justify-content: space-between;
@@ -412,12 +415,36 @@ canvas:focus-visible {
}
.heartbeat canvas {
+ position: relative;
+ z-index: 1;
display: block;
width: 100%;
height: 100%;
min-height: 32px;
}
+.heartbeat-bloom {
+ position: absolute;
+ z-index: 0;
+ top: 16px;
+ right: 7%;
+ bottom: 1px;
+ width: 44%;
+ pointer-events: none;
+ border-radius: 50%;
+ background: radial-gradient(ellipse at center, rgba(var(--accent-rgb), 0.055), rgba(var(--accent-rgb), 0.016) 42%, transparent 74%);
+ filter: blur(7px);
+ opacity: 0;
+ transform: scale(.58, .52);
+ animation: heartbeat-bloom 980ms cubic-bezier(.18, .72, .22, 1) both;
+}
+
+@keyframes heartbeat-bloom {
+ 0% { opacity: 0; transform: scale(.58, .52); }
+ 34% { opacity: .42; }
+ 100% { opacity: 0; transform: scale(1.08, .94); }
+}
+
.motion-note {
position: absolute;
right: 4px;
@@ -586,7 +613,7 @@ canvas:focus-visible {
}
.demo-ribbon + .hero-grid .protocol-snapchain {
- padding-top: max(34px, calc(env(safe-area-inset-top) + 32px));
+ padding-top: max(34px, calc(env(safe-area-inset-top) + 32px), calc(var(--fc-safe-area-inset-top) + 32px));
}
.transport-notice {
@@ -765,12 +792,27 @@ canvas:focus-visible {
grid-template-columns: repeat(3, 1fr);
align-self: flex-start;
width: 100%;
- max-width: 310px;
+ max-width: none;
padding: 3px;
border: 1px solid var(--line);
background: rgba(255,255,255,.02);
}
+.range-stack {
+ width: 100%;
+ max-width: 310px;
+}
+
+.range-context {
+ margin: 0 0 7px;
+ color: var(--muted);
+ font-family: ui-monospace, "SFMono-Regular", Consolas, monospace;
+ font-size: 0.55rem;
+ letter-spacing: 0.04em;
+ line-height: 1.2;
+ text-transform: uppercase;
+}
+
.range-control button {
min-height: 42px;
padding: 0 14px;
@@ -1040,6 +1082,17 @@ canvas:focus-visible {
gap: 9px;
}
+.window-unavailable {
+ margin: 0;
+ padding: 16px;
+ border: 1px solid rgba(255, 209, 102, 0.18);
+ border-left: 2px solid var(--amber);
+ color: #d8c79e;
+ background: rgba(255, 209, 102, 0.025);
+ font-size: 0.7rem;
+ line-height: 1.5;
+}
+
.mix-head,
.mix-row {
display: grid;
@@ -1364,7 +1417,7 @@ canvas:focus-visible {
@media (min-width: 640px) {
.analytics { padding-right: 30px; padding-left: 30px; }
.analytics-head { flex-direction: row; align-items: flex-end; justify-content: space-between; }
- .range-control { flex: 0 0 270px; }
+ .range-stack { flex: 0 0 270px; }
.comparison-facts { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.comparison-facts > div { padding: 18px 15px; border-right: 1px solid var(--line-soft); border-bottom: 0; }
.comparison-facts > div:last-child { border-right: 0; }
@@ -1383,20 +1436,20 @@ canvas:focus-visible {
.protocol-panel {
grid-template-rows: auto auto minmax(90px, 1fr) auto auto;
gap: clamp(8px, 1.2dvh, 15px);
- padding: max(24px, env(safe-area-inset-top)) 28px max(24px, env(safe-area-inset-bottom)) max(28px, env(safe-area-inset-left));
+ padding: max(24px, env(safe-area-inset-top), var(--fc-safe-area-inset-top)) 28px max(24px, env(safe-area-inset-bottom), var(--fc-safe-area-inset-bottom)) max(28px, env(safe-area-inset-left), var(--fc-safe-area-inset-left));
border-right: 1px solid rgba(var(--accent-rgb), .22);
border-bottom: 0;
}
.protocol-hypersnap {
- padding-right: max(28px, env(safe-area-inset-right));
+ padding-right: max(28px, env(safe-area-inset-right), var(--fc-safe-area-inset-right));
padding-left: 28px;
border-right: 0;
}
.demo-ribbon + .hero-grid .protocol-snapchain,
.demo-ribbon + .hero-grid .protocol-hypersnap {
- padding-top: max(42px, calc(env(safe-area-inset-top) + 32px));
+ padding-top: max(42px, calc(env(safe-area-inset-top) + 32px), calc(var(--fc-safe-area-inset-top) + 32px));
}
.protocol-head h1 { font-size: clamp(1.3rem, 2.1vw, 1.8rem); }
@@ -1438,13 +1491,13 @@ canvas:focus-visible {
}
@media (max-height: 820px) and (max-width: 759px) {
- .protocol-panel { gap: 3px; padding-top: 9px; padding-bottom: 7px; }
- .protocol-hypersnap { padding-top: 7px; padding-bottom: max(9px, env(safe-area-inset-bottom)); }
+ .protocol-panel { gap: 3px; padding-top: max(9px, var(--fc-safe-area-inset-top)); padding-bottom: 7px; }
+ .protocol-hypersnap { padding-top: 7px; padding-bottom: max(9px, env(safe-area-inset-bottom), var(--fc-safe-area-inset-bottom)); }
.metric-number { font-size: clamp(2.4rem, 12.5vw, 3.2rem); }
.heartbeat { grid-template-rows: 12px minmax(28px, 1fr); }
.compact-readouts > div { padding-top: 2px; }
.thirty-day strong { font-size: 1rem; }
- .demo-ribbon + .hero-grid .protocol-snapchain { padding-top: 31px; }
+ .demo-ribbon + .hero-grid .protocol-snapchain { padding-top: max(31px, calc(var(--fc-safe-area-inset-top) + 29px)); }
}
@media (max-width: 355px) {
@@ -1463,12 +1516,13 @@ canvas:focus-visible {
animation-iteration-count: 1 !important;
transition-duration: 0.001ms !important;
}
+ .heartbeat-bloom { display: none; }
}
@media (forced-colors: active) {
.protocol-panel::before,
.protocol-panel::after,
- .panel-glow { display: none; }
+ .heartbeat-bloom { display: none; }
.status-shape { forced-color-adjust: none; }
.range-control button[aria-pressed="true"] { outline: 2px solid CanvasText; color: CanvasText; background: Canvas; }
}
diff --git a/apps/dashboard/src/test/setup.ts b/apps/dashboard/src/test/setup.ts
index 979356b..ffbdd18 100644
--- a/apps/dashboard/src/test/setup.ts
+++ b/apps/dashboard/src/test/setup.ts
@@ -29,6 +29,7 @@ const context = {
arc: vi.fn(),
beginPath: vi.fn(),
clearRect: vi.fn(),
+ closePath: vi.fn(),
fill: vi.fn(),
fillRect: vi.fn(),
fillText: vi.fn(),
@@ -37,6 +38,7 @@ const context = {
lineTo: vi.fn(),
lineWidth: 1,
moveTo: vi.fn(),
+ quadraticCurveTo: vi.fn(),
restore: vi.fn(),
save: vi.fn(),
setLineDash: vi.fn(),
diff --git a/apps/dashboard/vite.config.ts b/apps/dashboard/vite.config.ts
index 3292164..5db3a34 100644
--- a/apps/dashboard/vite.config.ts
+++ b/apps/dashboard/vite.config.ts
@@ -3,5 +3,11 @@ import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
- plugins: [react(), cloudflare()]
+ plugins: [react(), cloudflare()],
+ build: {
+ // Vite derives these from modules that actually enter each environment,
+ // so dependency additions cannot silently bypass redistribution notices.
+ // The post-build verifier combines and validates both emitted artifacts.
+ license: { fileName: ".vite/third-party-licenses.md" }
+ }
});
diff --git a/apps/dashboard/vitest.worker.config.ts b/apps/dashboard/vitest.worker.config.ts
index a1977e6..394d811 100644
--- a/apps/dashboard/vitest.worker.config.ts
+++ b/apps/dashboard/vitest.worker.config.ts
@@ -17,7 +17,10 @@ export default defineConfig(async () => {
],
test: {
include: ["worker/**/*.worker.test.ts"],
- setupFiles: ["./worker/test-setup.ts"]
+ setupFiles: ["./worker/test-setup.ts"],
+ // Durable Object + D1 integration can exceed Vitest's 5s unit-test
+ // default on a busy development host without indicating a product SLA.
+ testTimeout: 15_000
}
};
});
diff --git a/apps/dashboard/worker/farcaster-auth.ts b/apps/dashboard/worker/farcaster-auth.ts
new file mode 100644
index 0000000..a8f4dbd
--- /dev/null
+++ b/apps/dashboard/worker/farcaster-auth.ts
@@ -0,0 +1,92 @@
+import { createClient } from "@farcaster/quick-auth";
+
+export const FARCASTER_AUTH_DOMAIN = "snapmeter.ael-dev3.workers.dev";
+export const FARCASTER_AUTH_ISSUER = "https://auth.farcaster.xyz";
+export const FARCASTER_AUTH_ORIGIN = `https://${FARCASTER_AUTH_DOMAIN}`;
+
+const MAX_TOKEN_BYTES = 8 * 1024;
+const MAX_TOKEN_LIFETIME_SECONDS = 60 * 60;
+const MAX_FUTURE_IAT_SKEW_SECONDS = 60;
+const COMPACT_JWT_PATTERN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const RESPONSE_HEADERS = {
+ "content-type": "application/json; charset=utf-8",
+ "cache-control": "no-store",
+ "vary": "Authorization, Origin",
+ "x-content-type-options": "nosniff",
+ "referrer-policy": "no-referrer"
+};
+
+export type FarcasterJwtClaims = Readonly<{
+ iss: unknown;
+ aud: unknown;
+ sub: unknown;
+ iat: unknown;
+ exp: unknown;
+}>;
+
+export type FarcasterJwtVerifier = (options: Readonly<{
+ token: string;
+ domain: string;
+}>) => Promise;
+
+const quickAuthClient = createClient();
+
+export const verifyFarcasterJwt: FarcasterJwtVerifier = (options) =>
+ quickAuthClient.verifyJwt(options);
+
+function json(body: unknown, status: number): Response {
+ return new Response(JSON.stringify(body), { status, headers: RESPONSE_HEADERS });
+}
+
+function unauthorized(): Response {
+ return json({ schemaVersion: 1, authenticated: false, error: "unauthorized" }, 401);
+}
+
+function bearerToken(request: Request): string | null {
+ const authorization = request.headers.get("authorization");
+ const prefix = "Bearer ";
+ if (!authorization || authorization.length > MAX_TOKEN_BYTES + prefix.length) return null;
+ if (!authorization.startsWith(prefix)) return null;
+ const token = authorization.slice(prefix.length);
+ if (!COMPACT_JWT_PATTERN.test(token)) return null;
+ return new TextEncoder().encode(token).byteLength <= MAX_TOKEN_BYTES ? token : null;
+}
+
+function isRecord(value: unknown): value is Record {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validatedFid(value: unknown, nowSeconds: number): number | null {
+ if (!isRecord(value) || !Number.isFinite(nowSeconds)) return null;
+ try {
+ const { iss, aud, sub, iat, exp } = value as FarcasterJwtClaims;
+ if (iss !== FARCASTER_AUTH_ISSUER || aud !== FARCASTER_AUTH_DOMAIN) return null;
+ if (typeof sub !== "number" || !Number.isSafeInteger(sub) || sub <= 0) return null;
+ if (typeof iat !== "number" || !Number.isFinite(iat) || iat <= 0) return null;
+ if (typeof exp !== "number" || !Number.isFinite(exp) || exp <= nowSeconds) return null;
+ if (iat > nowSeconds + MAX_FUTURE_IAT_SKEW_SECONDS) return null;
+ const lifetime = exp - iat;
+ if (lifetime <= 0 || lifetime > MAX_TOKEN_LIFETIME_SECONDS) return null;
+ return sub;
+ } catch {
+ return null;
+ }
+}
+
+export async function handleFarcasterMe(
+ request: Request,
+ verifier: FarcasterJwtVerifier = verifyFarcasterJwt,
+ nowSeconds = Math.floor(Date.now() / 1000)
+): Promise {
+ const origin = request.headers.get("origin");
+ if (origin !== null && origin !== FARCASTER_AUTH_ORIGIN) return unauthorized();
+ const token = bearerToken(request);
+ if (!token) return unauthorized();
+ try {
+ const fid = validatedFid(await verifier({ token, domain: FARCASTER_AUTH_DOMAIN }), nowSeconds);
+ if (fid === null) return unauthorized();
+ return json({ schemaVersion: 1, authenticated: true, fid }, 200);
+ } catch {
+ return unauthorized();
+ }
+}
diff --git a/apps/dashboard/worker/farcaster-auth.worker.test.ts b/apps/dashboard/worker/farcaster-auth.worker.test.ts
new file mode 100644
index 0000000..65504a7
--- /dev/null
+++ b/apps/dashboard/worker/farcaster-auth.worker.test.ts
@@ -0,0 +1,134 @@
+import { SELF } from "cloudflare:test";
+import { describe, expect, it, vi } from "vitest";
+import {
+ FARCASTER_AUTH_DOMAIN,
+ FARCASTER_AUTH_ISSUER,
+ FARCASTER_AUTH_ORIGIN,
+ handleFarcasterMe,
+ type FarcasterJwtVerifier
+} from "./farcaster-auth";
+
+const NOW_SECONDS = 1_800_000_000;
+const TOKEN = "header.payload.signature";
+
+function request(authorization?: string, origin?: string): Request {
+ return new Request("https://snapmeter.test/api/v1/farcaster/me", {
+ headers: {
+ ...(authorization ? { authorization } : {}),
+ ...(origin ? { origin } : {})
+ }
+ });
+}
+
+function claims(overrides: Record = {}): Record {
+ return {
+ iss: FARCASTER_AUTH_ISSUER,
+ aud: FARCASTER_AUTH_DOMAIN,
+ sub: 539_854,
+ iat: NOW_SECONDS - 30,
+ exp: NOW_SECONDS + 300,
+ ...overrides
+ };
+}
+
+function verifier(result: unknown): ReturnType> {
+ return vi.fn().mockResolvedValue(result);
+}
+
+async function expectUnauthorized(response: Response): Promise {
+ expect(response.status).toBe(401);
+ expect(response.headers.get("cache-control")).toBe("no-store");
+ expect(response.headers.get("vary")).toBe("Authorization, Origin");
+ expect(response.headers.get("content-type")).toBe("application/json; charset=utf-8");
+ expect(await response.json()).toEqual({ schemaVersion: 1, authenticated: false, error: "unauthorized" });
+}
+
+describe("Farcaster Quick Auth", () => {
+ it("routes GET /api/v1/farcaster/me through the Worker", async () => {
+ await expectUnauthorized(await SELF.fetch("https://snapmeter.test/api/v1/farcaster/me"));
+ });
+
+ it("rejects a missing or malformed exact Bearer compact JWT before verification", async () => {
+ const verify = verifier(claims());
+ const malformed = [
+ undefined,
+ "Basic header.payload.signature",
+ "bearer header.payload.signature",
+ "Bearer",
+ "Bearer header.payload",
+ "Bearer header.payload.signature.extra",
+ "Bearer header.payload.sign+ature",
+ `Bearer a.${"a".repeat(8_190)}.a`
+ ];
+ for (const authorization of malformed) {
+ await expectUnauthorized(await handleFarcasterMe(request(authorization), verify, NOW_SECONDS));
+ }
+ expect(verify).not.toHaveBeenCalled();
+ });
+
+ it("returns only a verified positive FID and pins the exact audience domain", async () => {
+ const verify = verifier(claims());
+ const response = await handleFarcasterMe(
+ request(`Bearer ${TOKEN}`, FARCASTER_AUTH_ORIGIN),
+ verify,
+ NOW_SECONDS
+ );
+ expect(response.status).toBe(200);
+ expect(response.headers.get("cache-control")).toBe("no-store");
+ expect(response.headers.get("vary")).toBe("Authorization, Origin");
+ expect(await response.json()).toEqual({ schemaVersion: 1, authenticated: true, fid: 539_854 });
+ expect(verify).toHaveBeenCalledOnce();
+ expect(verify).toHaveBeenCalledWith({ token: TOKEN, domain: FARCASTER_AUTH_DOMAIN });
+ });
+
+ it("rejects a present Origin unless it is the exact production origin", async () => {
+ const verify = verifier(claims());
+ await expectUnauthorized(await handleFarcasterMe(
+ request(`Bearer ${TOKEN}`, "https://attacker.example"),
+ verify,
+ NOW_SECONDS
+ ));
+ expect(verify).not.toHaveBeenCalled();
+
+ const directResponse = await handleFarcasterMe(request(`Bearer ${TOKEN}`), verify, NOW_SECONDS);
+ expect(directResponse.status).toBe(200);
+ });
+
+ it.each([
+ ["wrong issuer", { iss: "https://attacker.example" }],
+ ["wrong audience", { aud: "attacker.example" }],
+ ["audience array", { aud: [FARCASTER_AUTH_DOMAIN] }],
+ ["zero FID", { sub: 0 }],
+ ["negative FID", { sub: -1 }],
+ ["string FID", { sub: "539854" }],
+ ["unsafe FID", { sub: Number.MAX_SAFE_INTEGER + 1 }],
+ ["missing issued-at", { iat: undefined }],
+ ["non-finite issued-at", { iat: Number.POSITIVE_INFINITY }],
+ ["non-positive issued-at", { iat: 0 }],
+ ["issued too far in the future", { iat: NOW_SECONDS + 61, exp: NOW_SECONDS + 300 }],
+ ["missing expiry", { exp: undefined }],
+ ["non-finite expiry", { exp: Number.NaN }],
+ ["expired token", { exp: NOW_SECONDS }],
+ ["expiry before issuance", { iat: NOW_SECONDS - 10, exp: NOW_SECONDS - 20 }],
+ ["lifetime over one hour", { iat: NOW_SECONDS - 10, exp: NOW_SECONDS + 3_591 }]
+ ])("rejects independently invalid claims: %s", async (_label, overrides) => {
+ await expectUnauthorized(await handleFarcasterMe(
+ request(`Bearer ${TOKEN}`),
+ verifier(claims(overrides)),
+ NOW_SECONDS
+ ));
+ });
+
+ it("fails closed without leaking verifier errors or bearer material", async () => {
+ const verify = vi.fn().mockRejectedValue(
+ new Error(`upstream rejected secret ${TOKEN}`)
+ );
+ const response = await handleFarcasterMe(request(`Bearer ${TOKEN}`), verify, NOW_SECONDS);
+ expect(response.status).toBe(401);
+ const body = await response.text();
+ expect(body).toBe('{"schemaVersion":1,"authenticated":false,"error":"unauthorized"}');
+ expect(body).not.toContain(TOKEN);
+ expect(body).not.toContain("upstream");
+ expect(body).not.toContain("secret");
+ });
+});
diff --git a/apps/dashboard/worker/index.ts b/apps/dashboard/worker/index.ts
index adb0254..86c3af9 100644
--- a/apps/dashboard/worker/index.ts
+++ b/apps/dashboard/worker/index.ts
@@ -5,13 +5,15 @@ import {
verifyIngestSignature,
type IngestBatch
} from "@snapmeter/contracts";
+import { handleFarcasterMe } from "./farcaster-auth";
import { LiveRoom } from "./live-room";
-import { checkRateLimit, knownIngestBatch, latestStatus, markLiveDeliveryPublished, pendingLiveDeliveries, persistBatch, readSummary, refundRateLimit, releaseLiveDeliveryLease } from "./repository";
+import { checkRateLimit, claimCollectorBinding, collectorBindingAllows, knownIngestBatch, latestStatus, markLiveDeliveryPublished, pendingLiveDeliveries, persistBatch, readSummary, refundRateLimit, releaseLiveDeliveryLease } from "./repository";
import type { Env, ExecutionContextLike, ScheduledControllerLike } from "./types";
export { LiveRoom };
const MAX_BODY_BYTES = 512 * 1024;
+const MAX_FUTURE_RECORD_SKEW_MS = 60_000;
const JSON_HEADERS = {
"content-type": "application/json; charset=utf-8",
"cache-control": "no-store",
@@ -32,6 +34,7 @@ export async function handleRequest(request: Request, env: Env, _ctx?: Execution
const url = new URL(request.url);
if (!url.pathname.startsWith("/api/")) return new Response("Not found", { status: 404 });
if (url.pathname === "/api/v1/ingest/batch" && request.method === "POST") return handleIngest(request, env);
+ if (url.pathname === "/api/v1/farcaster/me" && request.method === "GET") return handleFarcasterMe(request);
if (url.pathname === "/api/v1/summary" && request.method === "GET") return json(await readSummary(env));
if (url.pathname === "/api/v1/status" && request.method === "GET") {
const summary = await readSummary(env);
@@ -137,8 +140,8 @@ async function handleIngest(request: Request, env: Env): Promise {
if (mediaType !== "application/json") return json({ error: "unsupported_content_type" }, {}, 415);
const declaredLength = Number(request.headers.get("content-length") ?? "0");
if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) return json({ error: "payload_too_large" }, {}, 413);
- const rawBody = await request.text();
- if (new TextEncoder().encode(rawBody).byteLength > MAX_BODY_BYTES) return json({ error: "payload_too_large" }, {}, 413);
+ const rawBody = await readBodyLimited(request, MAX_BODY_BYTES);
+ if (rawBody === null) return json({ error: "payload_too_large" }, {}, 413);
const timestamp = request.headers.get("x-snapmeter-timestamp") ?? "";
const nonce = request.headers.get("x-snapmeter-nonce") ?? "";
const signature = request.headers.get("x-snapmeter-signature") ?? "";
@@ -152,18 +155,26 @@ async function handleIngest(request: Request, env: Env): Promise {
if (!parsed.success) return json({ error: "invalid_batch", issues: parsed.error.issues.map((issue) => ({ path: issue.path.join("."), code: issue.code })) }, {}, 400);
const batch = parsed.data;
if (batch.batchId.toLowerCase() !== nonce.toLowerCase()) return json({ error: "nonce_batch_mismatch" }, {}, 401);
+ const receivedAtMs = Date.now();
+ const timeError = validateBatchTimes(batch, Number(timestamp), receivedAtMs);
+ if (timeError !== null) return json({ error: "invalid_batch_time", field: timeError }, {}, 400);
const recordCount = batch.actorDays.length + batch.minuteBuckets.length + batch.cursors.length + batch.health.length + batch.snapshots.length + batch.comparisonSnapshots.length;
if (recordCount > 700) return json({ error: "too_many_records", max: 700 }, {}, 413);
if (request.headers.get("x-snapmeter-doctor") === "1") {
if (!isEmptyProbe(batch)) return json({ error: "doctor_probe_must_be_empty" }, {}, 400);
+ if (!(await collectorBindingAllows(env, batch.collectorId))) {
+ return json({ error: "collector_identity_conflict" }, {}, 409);
+ }
return json({ ok: true, authenticated: true, serverTimeMs: Date.now() });
}
+ if (!(await claimCollectorBinding(env, batch.collectorId, receivedAtMs))) {
+ return json({ error: "collector_identity_conflict" }, {}, 409);
+ }
const known = await knownIngestBatch(env, batch.batchId);
if (known) {
await drainLiveDeliveryOutbox(env);
return json({ ok: true, batchId: batch.batchId, duplicate: true, acceptedAtMs: known.receivedAtMs });
}
- const receivedAtMs = Date.now();
if (!(await checkRateLimit(env, batch, receivedAtMs))) {
const becameKnown = await knownIngestBatch(env, batch.batchId);
if (becameKnown) {
@@ -177,7 +188,7 @@ async function handleIngest(request: Request, env: Env): Promise {
catch (error) {
await refundRateLimit(env, batch, receivedAtMs);
if (error instanceof RangeError) return json({ error: error.message }, {}, 413);
- console.error(JSON.stringify({ level: "error", event: "ingest_failed", batchId: batch.batchId, error: error instanceof Error ? error.message : String(error) }));
+ console.error(JSON.stringify({ level: "error", event: "ingest_failed", batchId: batch.batchId, errorKind: safeErrorKind(error) }));
return json({ error: "ingest_failed" }, {}, 500);
}
if (disposition === "duplicate") {
@@ -188,12 +199,87 @@ async function handleIngest(request: Request, env: Env): Promise {
}
try { await drainLiveDeliveryOutbox(env); }
catch (error) {
- console.error(JSON.stringify({ level: "error", event: "live_delivery_deferred", batchId: batch.batchId, error: error instanceof Error ? error.message : String(error) }));
+ console.error(JSON.stringify({ level: "error", event: "live_delivery_deferred", batchId: batch.batchId, errorKind: safeErrorKind(error) }));
return json({ error: "live_delivery_deferred" }, { "retry-after": "1" }, 503);
}
return json({ ok: true, batchId: batch.batchId, duplicate: false, acceptedAtMs: receivedAtMs }, {}, 202);
}
+async function readBodyLimited(request: Request, maximumBytes: number): Promise {
+ if (request.body === null) return "";
+ const reader = request.body.getReader();
+ const chunks: Uint8Array[] = [];
+ let totalBytes = 0;
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ totalBytes += value.byteLength;
+ if (totalBytes > maximumBytes) {
+ try { await reader.cancel(); } catch { /* the size rejection still wins if upstream cancellation fails */ }
+ return null;
+ }
+ chunks.push(value);
+ }
+ } finally {
+ reader.releaseLock();
+ }
+
+ const bytes = new Uint8Array(totalBytes);
+ let offset = 0;
+ for (const chunk of chunks) {
+ bytes.set(chunk, offset);
+ offset += chunk.byteLength;
+ }
+ return new TextDecoder().decode(bytes);
+}
+
+function validateBatchTimes(batch: IngestBatch, signedAtMs: number, receivedAtMs: number): string | null {
+ // The body can be retried long after it was created, so old sentAtMs values
+ // remain valid. Only reject a body whose claimed creation time is ahead of
+ // the already-fresh signed request/server clocks.
+ const requestFutureLimit = Math.max(receivedAtMs, signedAtMs) + MAX_FUTURE_RECORD_SKEW_MS;
+ if (batch.sentAtMs > requestFutureLimit) return "sentAtMs";
+ const recordFutureLimit = batch.sentAtMs + MAX_FUTURE_RECORD_SKEW_MS;
+ const future = (value: number): boolean => value > recordFutureLimit;
+
+ for (const pulse of batch.pulses) {
+ if (pulse.windowStartMs > pulse.windowEndMs) return "pulses.window";
+ if (pulse.lastActionAtMs > pulse.windowEndMs) return "pulses.lastActionAtMs";
+ if (future(pulse.windowStartMs) || future(pulse.windowEndMs) || future(pulse.lastActionAtMs)) return "pulses.future";
+ }
+ if (batch.snapshots.length > 0 && batch.snapshots.some((snapshot) => snapshot.updatedAtMs !== batch.sentAtMs)) {
+ return "snapshots.updatedAtMs";
+ }
+ for (const snapshot of batch.snapshots) {
+ if (future(snapshot.updatedAtMs)) return "snapshots.updatedAtMs";
+ if (snapshot.lastActionAtMs !== null && (snapshot.lastActionAtMs > snapshot.updatedAtMs || future(snapshot.lastActionAtMs))) {
+ return "snapshots.lastActionAtMs";
+ }
+ if (snapshot.lastCollectorAtMs !== null && future(snapshot.lastCollectorAtMs)) return "snapshots.lastCollectorAtMs";
+ }
+ for (const comparison of batch.comparisonSnapshots) {
+ if (comparison.generatedAtMs !== batch.sentAtMs) return "comparisonSnapshots.generatedAtMs";
+ if (future(comparison.generatedAtMs)) return "comparisonSnapshots.generatedAtMs";
+ }
+ for (const bucket of batch.minuteBuckets) {
+ if (future(bucket.minuteStartMs)) return "minuteBuckets.minuteStartMs";
+ }
+ for (const cursor of batch.cursors) {
+ if (future(cursor.verifiedAtMs)) return "cursors.verifiedAtMs";
+ }
+ for (const health of batch.health) {
+ if (future(health.observedAtMs)) return "health.observedAtMs";
+ if (health.node.historyCoverageStartMs !== null && future(health.node.historyCoverageStartMs)) {
+ return "health.node.historyCoverageStartMs";
+ }
+ }
+ for (const actor of batch.actorDays) {
+ if (actor.day > new Date(recordFutureLimit).toISOString().slice(0, 10)) return "actorDays.day";
+ }
+ return null;
+}
+
async function drainLiveDeliveryOutbox(env: Env): Promise {
for (const pending of await pendingLiveDeliveries(env)) {
try {
@@ -288,3 +374,7 @@ function isEmptyProbe(batch: IngestBatch): boolean {
function json(body: unknown, headers: Record = {}, status = 200): Response {
return new Response(JSON.stringify(body), { status, headers: { ...JSON_HEADERS, ...headers } });
}
+
+function safeErrorKind(error: unknown): "error" | "unknown" {
+ return error instanceof Error ? "error" : "unknown";
+}
diff --git a/apps/dashboard/worker/index.worker.test.ts b/apps/dashboard/worker/index.worker.test.ts
index 6c6f40c..d5f94ff 100644
--- a/apps/dashboard/worker/index.worker.test.ts
+++ b/apps/dashboard/worker/index.worker.test.ts
@@ -9,6 +9,7 @@ import type { Env } from "./types";
import { checkRateLimit, SOURCE_RATE_SCOPE } from "./repository";
const SECRET = "worker-test-secret-with-32-characters";
+const MAX_INGEST_BODY_BYTES = 512 * 1024;
function batch(batchId = crypto.randomUUID(), pulse = false): IngestBatch {
const now = Date.now();
@@ -28,7 +29,7 @@ function batch(batchId = crypto.randomUUID(), pulse = false): IngestBatch {
uniqueFids: 2,
actionCounts: { cast: 2, reaction: 1 },
lastActionAtMs: now,
- maxEventId: "1:49153",
+ maxEventId: "49153",
isReplay: false
}] : [],
snapshots: [],
@@ -42,35 +43,81 @@ function batch(batchId = crypto.randomUUID(), pulse = false): IngestBatch {
async function signedRequest(payload: ReturnType, extraHeaders: Record = {}): Promise {
const raw = JSON.stringify(payload);
+ return signedRawRequest(raw, payload.batchId, raw, extraHeaders);
+}
+
+async function signedRawRequest(
+ raw: string,
+ batchId: string,
+ body: BodyInit,
+ extraHeaders: Record = {}
+): Promise {
const timestamp = String(Date.now());
return new Request("https://snapmeter.test/api/v1/ingest/batch", {
method: "POST",
headers: {
"content-type": "application/json",
"x-snapmeter-timestamp": timestamp,
- "x-snapmeter-nonce": payload.batchId,
- "x-snapmeter-signature": await signIngest(SECRET, timestamp, payload.batchId, raw),
+ "x-snapmeter-nonce": batchId,
+ "x-snapmeter-signature": await signIngest(SECRET, timestamp, batchId, raw),
...extraHeaders
},
- body: raw
+ body
+ });
+}
+
+function paddedBatch(payload: ReturnType, targetBytes: number): string {
+ const empty = JSON.stringify({ ...payload, _padding: "" });
+ const paddingBytes = targetBytes - new TextEncoder().encode(empty).byteLength;
+ if (paddingBytes < 0) throw new RangeError("target body is smaller than the base batch");
+ const raw = JSON.stringify({ ...payload, _padding: "x".repeat(paddingBytes) });
+ if (new TextEncoder().encode(raw).byteLength !== targetBytes) throw new Error("failed to construct exact-size ingest body");
+ return raw;
+}
+
+function chunkedBody(raw: string, chunkBytes = 64 * 1024): ReadableStream {
+ const bytes = new TextEncoder().encode(raw);
+ let offset = 0;
+ return new ReadableStream({
+ pull(controller) {
+ if (offset >= bytes.byteLength) {
+ controller.close();
+ return;
+ }
+ const end = Math.min(offset + chunkBytes, bytes.byteLength);
+ controller.enqueue(bytes.slice(offset, end));
+ offset = end;
+ }
});
}
-function nextMessage(socket: WebSocket): Promise {
+function nextMessage(socket: WebSocket, timeoutMs = 8_000): Promise {
return new Promise((resolve, reject) => {
- const timeout = setTimeout(() => reject(new Error("Timed out waiting for WebSocket message")), 2_000);
- socket.addEventListener("message", (event) => {
+ const onMessage = (event: MessageEvent): void => {
clearTimeout(timeout);
resolve(String(event.data));
- }, { once: true });
+ };
+ const timeout = setTimeout(() => {
+ socket.removeEventListener("message", onMessage);
+ reject(new Error("Timed out waiting for WebSocket message"));
+ }, timeoutMs);
+ socket.addEventListener("message", onMessage, { once: true });
});
}
async function expectQuiet(socket: WebSocket, durationMs = 400): Promise {
- await expect(Promise.race([
- nextMessage(socket).then(() => "message"),
- new Promise((resolve) => setTimeout(() => resolve("quiet"), durationMs))
- ])).resolves.toBe("quiet");
+ const result = await new Promise<"message" | "quiet">((resolve) => {
+ const onMessage = (): void => {
+ clearTimeout(timeout);
+ resolve("message");
+ };
+ const timeout = setTimeout(() => {
+ socket.removeEventListener("message", onMessage);
+ resolve("quiet");
+ }, durationMs);
+ socket.addEventListener("message", onMessage, { once: true });
+ });
+ expect(result).toBe("quiet");
}
describe("Worker API", () => {
@@ -99,6 +146,55 @@ describe("Worker API", () => {
expect(await response.json()).toMatchObject({ ok: true, authenticated: true });
const row = await env.DB.prepare("SELECT COUNT(*) AS total FROM ingest_batches").first<{ total: number }>();
expect(row?.total).toBe(0);
+ expect(await env.DB.prepare("SELECT 1 AS present FROM collector_binding WHERE slot=1").first()).toBeNull();
+
+ await env.DB.prepare("INSERT INTO collector_binding(slot, collector_id, claimed_at_ms) VALUES (1, ?, ?)")
+ .bind(payload.collectorId, Date.now()).run();
+ const same = await SELF.fetch(await signedRequest(batch(), { "x-snapmeter-doctor": "1" }));
+ expect(same.status).toBe(200);
+
+ const differentPayload = batch();
+ differentPayload.collectorId = "collector-doctor-conflict";
+ const different = await SELF.fetch(await signedRequest(differentPayload, { "x-snapmeter-doctor": "1" }));
+ expect(different.status).toBe(409);
+ expect(await different.json()).toEqual({ error: "collector_identity_conflict" });
+ const stillBound = await env.DB.prepare("SELECT collector_id FROM collector_binding WHERE slot=1")
+ .first<{ collector_id: string }>();
+ expect(stillBound?.collector_id).toBe(payload.collectorId);
+ });
+
+ it("accepts an exactly bounded signed body streamed without Content-Length", async () => {
+ const payload = batch();
+ const raw = paddedBatch(payload, MAX_INGEST_BODY_BYTES);
+ const request = await signedRawRequest(raw, payload.batchId, chunkedBody(raw), { "x-snapmeter-doctor": "1" });
+ expect(request.headers.has("content-length")).toBe(false);
+
+ const response = await SELF.fetch(request);
+ expect(response.status).toBe(200);
+ expect(await response.json()).toMatchObject({ ok: true, authenticated: true });
+ });
+
+ it("stops a streamed body without Content-Length as soon as it exceeds the byte cap", async () => {
+ const payload = batch();
+ const raw = paddedBatch(payload, MAX_INGEST_BODY_BYTES + 1);
+ const request = await signedRawRequest(raw, payload.batchId, chunkedBody(raw));
+ expect(request.headers.has("content-length")).toBe(false);
+
+ const response = await SELF.fetch(request);
+ expect(response.status).toBe(413);
+ expect(await response.json()).toMatchObject({ error: "payload_too_large" });
+ });
+
+ it("rejects an oversized declared Content-Length", async () => {
+ const payload = batch();
+ const raw = JSON.stringify(payload);
+ const request = await signedRawRequest(raw, payload.batchId, raw, {
+ "content-length": String(MAX_INGEST_BODY_BYTES + 1)
+ });
+
+ const response = await SELF.fetch(request);
+ expect(response.status).toBe(413);
+ expect(await response.json()).toMatchObject({ error: "payload_too_large" });
});
it("rejects a modified body and stale replay timestamp", async () => {
@@ -131,6 +227,53 @@ describe("Worker API", () => {
expect(await response.json()).toMatchObject({ error: "invalid_batch" });
});
+ it("rejects authenticated future-dated state before it can poison monotonic storage", async () => {
+ const now = Date.now();
+ const future = now + 24 * 60 * 60_000;
+ const cases: Array<[string, (payload: ReturnType) => void]> = [
+ ["sentAtMs", (payload) => { payload.sentAtMs = future; }],
+ ["snapshots.updatedAtMs", (payload) => { payload.snapshots = [{ ...emptySource("snapchain", future), updatedAtMs: future }]; }],
+ ["minuteBuckets.minuteStartMs", (payload) => { payload.minuteBuckets = [{ source: "snapchain", minuteStartMs: future, actions: 1, uniqueFids: 1, actionCounts: { cast: 1 } }]; }],
+ ["cursors.verifiedAtMs", (payload) => { payload.cursors = [{ source: "snapchain", shard: 1, eventId: "1", verifiedAtMs: future }]; }],
+ ["health.observedAtMs", (payload) => { payload.health = [{ source: "snapchain", sourceMode: "verified", status: "stale", observedAtMs: future, node: emptySource("snapchain", now).node, message: null }]; }],
+ ["actorDays.day", (payload) => { payload.actorDays = [{ source: "snapchain", day: "9999-12-31", fidHash: "a".repeat(64) }]; }]
+ ];
+
+ for (const [field, mutate] of cases) {
+ const payload = batch();
+ mutate(payload);
+ const response = await SELF.fetch(await signedRequest(payload));
+ expect(response.status, field).toBe(400);
+ expect(await response.json(), field).toMatchObject({ error: "invalid_batch_time", field });
+ const stored = await env.DB.prepare("SELECT 1 AS present FROM ingest_batches WHERE batch_id=?")
+ .bind(payload.batchId).first();
+ expect(stored, field).toBeNull();
+ }
+ });
+
+ it("rejects internally incoherent pulse and snapshot timestamps", async () => {
+ const pulsePayload = batch(crypto.randomUUID(), true);
+ pulsePayload.pulses[0]!.lastActionAtMs = pulsePayload.pulses[0]!.windowEndMs + 1;
+ const pulseResponse = await SELF.fetch(await signedRequest(pulsePayload));
+ expect(pulseResponse.status).toBe(400);
+ expect(await pulseResponse.json()).toMatchObject({ error: "invalid_batch_time", field: "pulses.lastActionAtMs" });
+
+ const now = Date.now();
+ const snapshotPayload = batch();
+ snapshotPayload.snapshots = [{ ...emptySource("snapchain", now), lastActionAtMs: now + 1 }];
+ const snapshotResponse = await SELF.fetch(await signedRequest(snapshotPayload));
+ expect(snapshotResponse.status).toBe(400);
+ expect(await snapshotResponse.json()).toMatchObject({ error: "invalid_batch_time", field: "snapshots.lastActionAtMs" });
+ });
+
+ it("accepts a delayed, newly signed retry of an old body", async () => {
+ const payload = batch();
+ payload.sentAtMs = Date.now() - 24 * 60 * 60_000;
+ const response = await SELF.fetch(await signedRequest(payload));
+ expect(response.status).toBe(202);
+ expect(await response.json()).toMatchObject({ ok: true, batchId: payload.batchId });
+ });
+
it("accepts each batch once and broadcasts a coalesced real pulse", async () => {
const upgrade = await SELF.fetch("https://snapmeter.test/api/v1/live", { headers: { Upgrade: "websocket" } });
expect(upgrade.status).toBe(101);
@@ -161,6 +304,63 @@ describe("Worker API", () => {
socket?.close(1000, "done");
});
+ it("claims the first real collector, permits it again, and rejects another before rate limit or persistence", async () => {
+ const first = batch();
+ first.collectorId = "collector-binding-primary";
+ expect((await SELF.fetch(await signedRequest(first))).status).toBe(202);
+ const binding = await env.DB.prepare("SELECT collector_id FROM collector_binding WHERE slot=1")
+ .first<{ collector_id: string }>();
+ expect(binding?.collector_id).toBe(first.collectorId);
+
+ const same = batch();
+ same.collectorId = first.collectorId;
+ expect((await SELF.fetch(await signedRequest(same))).status).toBe(202);
+
+ const conflict = batch();
+ conflict.collectorId = "collector-binding-secondary";
+ conflict.cursors = [{ source: "snapchain", shard: 1, eventId: "123", verifiedAtMs: Date.now() }];
+ const windowStartMs = Math.floor(Date.now() / 60_000) * 60_000;
+ const rateBefore = await env.DB.prepare(
+ "SELECT batch_count FROM rate_windows WHERE window_start_ms=? AND source='snapchain' AND collector_id=?"
+ ).bind(windowStartMs, SOURCE_RATE_SCOPE).first<{ batch_count: number }>();
+ const response = await SELF.fetch(await signedRequest(conflict));
+ expect(response.status).toBe(409);
+ const conflictBody = await response.text();
+ expect(JSON.parse(conflictBody)).toEqual({ error: "collector_identity_conflict" });
+ expect(await env.DB.prepare("SELECT 1 AS present FROM ingest_batches WHERE batch_id=?")
+ .bind(conflict.batchId).first()).toBeNull();
+ const rateAfter = await env.DB.prepare(
+ "SELECT batch_count FROM rate_windows WHERE window_start_ms=? AND source='snapchain' AND collector_id=?"
+ ).bind(windowStartMs, SOURCE_RATE_SCOPE).first<{ batch_count: number }>();
+ expect(rateAfter).toEqual(rateBefore);
+ expect(conflictBody).not.toContain(first.collectorId);
+ expect(conflictBody).not.toContain(conflict.collectorId);
+
+ await env.DB.prepare("DELETE FROM collector_binding WHERE slot=1").run();
+ });
+
+ it("atomically allows exactly one of two different first collectors to claim an empty dataset", async () => {
+ const left = batch();
+ left.collectorId = "collector-concurrent-left";
+ const right = batch();
+ right.collectorId = "collector-concurrent-right";
+ const responses = await Promise.all([
+ SELF.fetch(await signedRequest(left)),
+ SELF.fetch(await signedRequest(right))
+ ]);
+ expect(responses.map((response) => response.status).sort()).toEqual([202, 409]);
+ const bound = await env.DB.prepare("SELECT collector_id FROM collector_binding WHERE slot=1")
+ .first<{ collector_id: string }>();
+ expect([left.collectorId, right.collectorId]).toContain(bound?.collector_id);
+ const stored = await env.DB.prepare(
+ "SELECT collector_id FROM ingest_batches WHERE batch_id IN (?, ?)"
+ ).bind(left.batchId, right.batchId).all<{ collector_id: string }>();
+ expect(stored.results).toHaveLength(1);
+ expect(stored.results[0]?.collector_id).toBe(bound?.collector_id);
+
+ await env.DB.prepare("DELETE FROM collector_binding WHERE slot=1").run();
+ });
+
it("does not charge authenticated known-batch replays against a saturated source budget", async () => {
const payload = batch();
payload.cursors = [{ source: "snapchain", shard: 1, eventId: "10", verifiedAtMs: Date.now() }];
@@ -235,10 +435,14 @@ describe("Worker API", () => {
WHEN NEW.collector_id = 'collector-persist-failure-test'
BEGIN SELECT RAISE(ABORT, 'forced_persist_failure'); END
`).run();
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
try {
const response = await SELF.fetch(await signedRequest(payload));
expect(response.status).toBe(500);
expect(await response.json()).toMatchObject({ error: "ingest_failed" });
+ const logs = consoleError.mock.calls.flat().join(" ");
+ expect(logs).toContain('"errorKind":"error"');
+ expect(logs).not.toContain("forced_persist_failure");
const after = await env.DB.prepare(
"SELECT batch_count FROM rate_windows WHERE source='snapchain' AND collector_id=? AND window_start_ms=?"
).bind(SOURCE_RATE_SCOPE, windowStartMs).first<{ batch_count: number }>();
@@ -247,6 +451,7 @@ describe("Worker API", () => {
.bind(payload.batchId).first();
expect(stored).toBeNull();
} finally {
+ consoleError.mockRestore();
await env.DB.prepare("DROP TRIGGER IF EXISTS reject_test_ingest").run();
}
});
@@ -258,6 +463,7 @@ describe("Worker API", () => {
await nextMessage(socket);
const payload = batch(crypto.randomUUID(), true);
payload.pulses[0]!.windowEndMs = Date.now() - 121_000;
+ payload.pulses[0]!.windowStartMs = payload.pulses[0]!.windowEndMs - 250;
payload.pulses[0]!.lastActionAtMs = payload.pulses[0]!.windowEndMs;
const response = await SELF.fetch(await signedRequest(payload));
expect(response.status).toBe(202);
@@ -272,7 +478,8 @@ describe("Worker API", () => {
});
it("hydrates a new WebSocket with the latest accepted snapshot", async () => {
- const now = Date.now();
+ const base = batch();
+ const now = base.sentAtMs;
const snapchain = {
...emptySource("snapchain", now),
status: "live" as const,
@@ -293,7 +500,6 @@ describe("Worker API", () => {
historyComplete: true
}
};
- const base = batch();
const payload = { ...base, snapshots: [snapchain] };
const accepted = await SELF.fetch(await signedRequest(payload));
expect(accepted.status).toBe(202);
@@ -443,7 +649,8 @@ describe("Worker API", () => {
});
it("hydrates a new WebSocket with freshness-adjusted disconnected state", async () => {
- const now = Date.now();
+ const base = batch();
+ const now = base.sentAtMs;
const snapchain = {
...emptySource("snapchain", now),
status: "live" as const,
@@ -459,7 +666,7 @@ describe("Worker API", () => {
historyComplete: true
}
};
- const payload = { ...batch(), snapshots: [snapchain] };
+ const payload = { ...base, snapshots: [snapchain] };
expect((await SELF.fetch(await signedRequest(payload))).status).toBe(202);
const upgrade = await SELF.fetch("https://snapmeter.test/api/v1/live", { headers: { Upgrade: "websocket" } });
const socket = upgrade.webSocket!;
@@ -469,7 +676,8 @@ describe("Worker API", () => {
});
it("preserves partial quality while 30-day history is incomplete", async () => {
- const now = Date.now();
+ const base = batch();
+ const now = base.sentAtMs;
const snapchain = {
...emptySource("snapchain", now),
status: "partial" as const,
@@ -485,7 +693,7 @@ describe("Worker API", () => {
historyComplete: false
}
};
- const payload = { ...batch(), snapshots: [snapchain] };
+ const payload = { ...base, snapshots: [snapchain] };
expect((await SELF.fetch(await signedRequest(payload))).status).toBe(202);
const summary = await SELF.fetch("https://snapmeter.test/api/v1/summary");
expect(await summary.json()).toMatchObject({ sources: { snapchain: { status: "partial", quality: "degraded", node: { historyComplete: false } } } });
diff --git a/apps/dashboard/worker/repository.ts b/apps/dashboard/worker/repository.ts
index 7ad246b..6366b87 100644
--- a/apps/dashboard/worker/repository.ts
+++ b/apps/dashboard/worker/repository.ts
@@ -124,6 +124,23 @@ export interface PendingLiveDelivery {
leaseToken: string;
}
+export async function claimCollectorBinding(env: Env, collectorId: string, claimedAtMs: number): Promise {
+ const result = await env.DB.prepare(`
+ INSERT INTO collector_binding(slot, collector_id, claimed_at_ms)
+ VALUES (1, ?, ?)
+ ON CONFLICT(slot) DO UPDATE SET claimed_at_ms = collector_binding.claimed_at_ms
+ WHERE collector_binding.collector_id = excluded.collector_id
+ RETURNING collector_id
+ `).bind(collectorId, claimedAtMs).first<{ collector_id: string }>();
+ return result?.collector_id === collectorId;
+}
+
+export async function collectorBindingAllows(env: Env, collectorId: string): Promise {
+ const result = await env.DB.prepare("SELECT collector_id FROM collector_binding WHERE slot=1")
+ .first<{ collector_id: string }>();
+ return result === null || result.collector_id === collectorId;
+}
+
export async function pendingLiveDeliveries(env: Env, limit = 20, nowMs = Date.now(), leaseMs = 30_000): Promise {
const result = await env.DB.prepare(
"SELECT batch_id, payload_json FROM live_delivery_outbox WHERE published_at_ms IS NULL AND (lease_until_ms IS NULL OR lease_until_ms<=?) ORDER BY created_at_ms, batch_id LIMIT ?"
diff --git a/apps/dashboard/worker/test-setup.ts b/apps/dashboard/worker/test-setup.ts
index 7df97f4..b53e041 100644
--- a/apps/dashboard/worker/test-setup.ts
+++ b/apps/dashboard/worker/test-setup.ts
@@ -4,4 +4,5 @@ import { beforeEach } from "vitest";
beforeEach(async () => {
await applyD1Migrations(env.DB, env.TEST_MIGRATIONS);
+ await env.DB.prepare("DELETE FROM collector_binding").run();
});
diff --git a/docs/data-sources.md b/docs/data-sources.md
index 7976958..10dd58c 100644
--- a/docs/data-sources.md
+++ b/docs/data-sources.md
@@ -19,7 +19,7 @@ The canonical source is plaintext `HubService` gRPC on upstream port `3383`. Sna
- `GetEvents` for ordered per-shard durable reconciliation;
- `GetEvent` to point-verify a durable cursor during `doctor` when that event remains inside upstream retention.
-There is no reflection service, so the collector ships protobufs pinned to Snapchain SHA `6152402aea2dbe732fb73076f674b038bfd4aee5`. Native gRPC is plaintext. `https` support requires an external TLS terminator. Optional authorization metadata remains useful for authenticated proxies; the inspected read RPCs themselves do not enforce upstream `rpc_auth`.
+There is no reflection service, so the collector ships protobufs pinned to Snapchain SHA `6152402aea2dbe732fb73076f674b038bfd4aee5`. Native self-hosted gRPC is plaintext; remote services need TLS termination. Optional `authorization` metadata supports authenticated proxies, and optional `x-api-key` metadata supports hosted providers such as Neynar. Configure Neynar with `snapchain-grpc-api.neynar.com:443`, TLS enabled, and `SNAPCHAIN_GRPC_API_KEY`.
Event IDs encode `(block height << 14) | sequence` and are unique only within one data shard. Decimal-string IDs and per-shard cursors are mandatory. `Subscribe` has a replay-to-live race and a lagged receiver can lose live notifications, so periodic `GetEvents` reconciliation is authoritative.
diff --git a/docs/deployment.md b/docs/deployment.md
index 3294b98..1ad9191 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -47,6 +47,12 @@ pnpm --filter @snapmeter/dashboard run deploy
Record the exact URL returned by Wrangler, but do not commit it yet.
+## Collector binding
+
+Migration `0005_collector_binding.sql` creates the single-row `collector_binding` table. The first authenticated, non-doctor ingest atomically claims `slot=1` with that batch's `collectorId`; an empty doctor probe does not claim it. Later batches with a different ID receive HTTP 409 `{ "error": "collector_identity_conflict" }` before rate limiting or persistence, even when they have a valid ingest signature. This binding prevents a newly initialized database with a different local pseudonym key from overlapping the authoritative dataset and inflating DAU.
+
+Normal failover restores the complete stopped, WAL-consistent collector SQLite state, preserving its ID, pseudonym key, cursors, and outbox. Never export or provision the pseudonym key separately. An intentional fresh-database replacement requires a D1 backup, a reviewed metric-continuity plan, and the manual statement `DELETE FROM collector_binding WHERE slot=1`. Run it only while both collectors are stopped. Prefer a UTC-day boundary when no older-day reconciliation will occur, or clear and deliberately rebuild the affected `actor_day_membership` rows before accepting the new ID. Confirm the next intended batch claims the slot, then verify health and DAU continuity before resuming. Record and review the intervention; neither ingest-secret rotation nor a code rollback resets the binding.
+
## Required smoke test
Against the exact returned origin:
diff --git a/docs/farcaster-miniapp.md b/docs/farcaster-miniapp.md
new file mode 100644
index 0000000..da1517f
--- /dev/null
+++ b/docs/farcaster-miniapp.md
@@ -0,0 +1,37 @@
+# Farcaster Mini App release
+
+SnapMeter's Mini App launch URL and signed identity are tied to the exact production host:
+
+```text
+https://snapmeter.ael-dev3.workers.dev/?miniApp=true
+```
+
+The repository contains the app metadata, `fc:miniapp` embed, and exact-size opaque PNG assets. Ordinary local builds accept the deliberately unsigned manifest so development is not blocked. Production deployment fails closed until the domain association is present and passes local validation.
+
+## Complete the account association
+
+1. Sign in to Farcaster and enable [Developer Mode](https://farcaster.xyz/~/settings/developer-tools).
+2. Open the [Mini App Manifest Tool for SnapMeter](https://farcaster.xyz/~/developers/mini-apps/manifest?domain=snapmeter.ael-dev3.workers.dev).
+3. Approve signing for exactly `snapmeter.ael-dev3.workers.dev`. Never paste or commit a custody private key.
+4. Copy only the generated `accountAssociation` object (`header`, `payload`, and `signature`) into `apps/dashboard/public/.well-known/farcaster.json` beside `miniapp`.
+5. Run the release check:
+
+ ```powershell
+ pnpm --filter @snapmeter/dashboard verify:miniapp:release
+ ```
+
+The verifier checks the official manifest schema, accepted custody/auth header type, decoded payload, exact domain, ERC-191 signature against the declared signer, Mini App embed, URLs, CSP, and all asset dimensions/opacity. Farcaster's Manifest Tool still performs the authoritative custody/auth-address registration check.
+
+## Preview and publish
+
+After the signed manifest is deployed:
+
+1. Confirm `https://snapmeter.ael-dev3.workers.dev/.well-known/farcaster.json` returns HTTP 200 JSON.
+2. Open the [Mini App preview](https://farcaster.xyz/~/developers/mini-apps/preview?url=https%3A%2F%2Fsnapmeter.ael-dev3.workers.dev%2F%3FminiApp%3Dtrue) while signed in and confirm the splash clears, the dashboard fits the vertical surface, and authentication succeeds.
+3. Use the Manifest Tool to register or refresh the deployed manifest and confirm the green account-association check.
+4. Preview the root URL's `fc:miniapp` card, launch it, and confirm the app opens at the canonical `?miniApp=true` URL.
+5. Run `pnpm --filter @snapmeter/dashboard deploy`. This command requires the association before it invokes Wrangler.
+
+Do not copy Warpkeep's association: its signature is bound to another domain. A future custom domain also requires a new association unless it is handled through Farcaster's documented domain-migration flow.
+
+Official references: [publishing](https://miniapps.farcaster.xyz/docs/guides/publishing), [sharing](https://miniapps.farcaster.xyz/docs/guides/sharing), [authentication](https://miniapps.farcaster.xyz/docs/guides/auth), and the [release checklist](https://miniapps.farcaster.xyz/docs/guides/agents-checklist).
diff --git a/docs/local-reconstruction.md b/docs/local-reconstruction.md
new file mode 100644
index 0000000..9321c7f
--- /dev/null
+++ b/docs/local-reconstruction.md
@@ -0,0 +1,241 @@
+# Local reconstruction
+
+This guide reconstructs SnapMeter from a clean public checkout without copying any private credential, production database, collector state, log, or node snapshot. The deterministic dashboard and the complete validation suite require no private data. A live deployment becomes useful only after an operator supplies their own infrastructure and newly generated credentials.
+
+## Reproducibility boundary
+
+| Material | In the repository? | Reconstruction rule |
+|---|---:|---|
+| Dashboard, Worker, collector, shared packages, tests, migrations, scripts, documentation | Yes | Restore from the selected SnapMeter Git commit. |
+| Locked JavaScript dependency graph | Yes | Run `pnpm install --frozen-lockfile`; do not commit `node_modules`. |
+| Farcaster Mini App images and public signed `accountAssociation` | Yes | These are public release metadata. A custody private key is never stored here. |
+| Snapchain-compatible protobuf subset | Yes | Pinned to the Snapchain SHA below and subject to the upstream license noted in `THIRD_PARTY_NOTICES.md`. |
+| `.env`, `.env.*`, `.dev.vars*`, API keys, auth headers, ingest secrets, Cloudflare tokens | No | Create fresh local values or provision them in the target secret store. Never recover them from Git. |
+| Production D1 contents and local `.wrangler` state | No | Recreate the schema from `migrations/`; begin with an empty database. |
+| Collector SQLite database, WAL files, cursor, outbox, health snapshot, and logs | No | Let the collector create fresh bounded state outside the repository. |
+| Snapchain/Hypersnap source trees, binaries, images, chain databases, and snapshots | No | Obtain them separately at the pinned commits and follow their own build, license, and operator documentation. |
+| Historical DAU values | No | Rebuild prospectively from an upstream node or from an independently trusted operator-owned history source. |
+
+Excluding state is intentional. A source release should not contain production telemetry, user-level databases, local paths, or access material.
+
+## Exact source pins
+
+The runtime classifier and vendored protocol definitions were audited against these immutable upstream commits:
+
+| Upstream | Repository | Commit |
+|---|---|---|
+| Snapchain | `https://github.com/farcasterxyz/snapchain` | `6152402aea2dbe732fb73076f674b038bfd4aee5` |
+| Hypersnap | `https://github.com/farcasterorg/hypersnap` | `2eee4c9f2a7833ce7971dfef028480abbe9c4720` |
+
+Do not replace either SHA with a branch name or a floating tag. See [Pinned upstream sources](upstream-sources.md) for the inspected package versions, protocol behavior, retention limits, and upgrade procedure.
+
+## Prerequisites
+
+Required for the application and tests:
+
+- Git.
+- Node.js 24 or later. Node 24 is required for the collector's stable `node:sqlite` API.
+- pnpm exactly `11.19.0`, as declared by the root `packageManager` field.
+- Internet access for the initial locked dependency download, unless the pnpm store is already populated.
+
+Optional by task:
+
+- Playwright Chromium for end-to-end tests.
+- PowerShell 5.1 or PowerShell 7 on Windows for the bootstrap and Scheduled Task scripts.
+- A local Docker engine; Docker Compose 2.24.4 or later is required only for the documented `!override` node-port fragment.
+- A Cloudflare account for remote deployment. The workspace already pins Wrangler, so no global Wrangler installation is needed.
+- Private or authenticated Snapchain-compatible gRPC endpoints for live collection.
+
+Confirm the required toolchain before installing:
+
+```powershell
+node --version
+pnpm --version
+git --version
+```
+
+## Clean checkout and locked install
+
+```powershell
+git clone https://github.com/ael-dev3/SnapMeter.git
+Set-Location SnapMeter
+git rev-parse --verify HEAD
+git status --short
+pnpm install --frozen-lockfile
+```
+
+`git status --short` should be empty before installation. Record the printed SnapMeter commit when reproducing a specific release. The lockfile, workspace build allowlist, exact direct dependency versions, vendored protobufs, and SQL migrations are part of that commit.
+
+Do not copy an existing `node_modules`, `.wrangler`, `.env`, database, or build directory into the checkout. They are neither required nor trustworthy reconstruction inputs.
+
+## Reproduce the dashboard without private data
+
+Start the Cloudflare/Vite development server:
+
+```powershell
+pnpm dev
+```
+
+Open the printed loopback URL with `?demo=1`, normally:
+
+```text
+http://127.0.0.1:5173/?demo=1
+```
+
+Demo mode is deterministic and synthetic. It bypasses API hydration and the live WebSocket, remains visibly labelled `DEMO`, and never silently substitutes for production data. No `.env`, credential, node, D1 data, or collector process is needed.
+
+For a local empty Worker/D1 environment, use a deliberately disposable value of at least 32 characters and apply only local migrations:
+
+```powershell
+$env:SNAPMETER_INGEST_SECRET = 'local-development-only-not-a-real-secret'
+pnpm --filter @snapmeter/dashboard exec wrangler d1 migrations apply snapmeter-prod --local
+pnpm --filter @snapmeter/dashboard dev --host 127.0.0.1
+```
+
+`--local` is important: it creates ignored development state under `.wrangler` and does not mutate production D1. Without collector input, the normal dashboard should truthfully show unavailable/disconnected sources rather than invented activity.
+
+## Reproduce tests and the production bundle
+
+Install the browser once when end-to-end coverage is required:
+
+```powershell
+pnpm exec playwright install chromium
+```
+
+On Linux CI hosts, use `pnpm exec playwright install --with-deps chromium` instead. Run the same gates as pull-request CI:
+
+```powershell
+pnpm lint
+pnpm typecheck
+pnpm security:check
+pnpm test
+pnpm build
+pnpm test:e2e
+```
+
+The test suites use temporary/in-memory state and non-production fixture secrets. `pnpm build` validates Mini App metadata and creates distributable output under ignored `dist` directories. A release deployment performs the stricter signed-association check.
+
+## Reconstruct a local collector
+
+The collector can be built and tested without a node, but a meaningful `doctor`, backfill, or continuous run needs at least one reachable source. Create a local environment from the public blank template:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Edit `.env` locally. Leave credentials blank unless your endpoint requires them. If one source is absent, set its source mode to `unavailable`; do not point both source names at one endpoint and present the result as an independent comparison.
+
+For local nodes, the documented host endpoints are:
+
+```dotenv
+SNAPCHAIN_GRPC_URL=127.0.0.1:3383
+HYPERSNAP_GRPC_URL=127.0.0.1:4383
+SNAPCHAIN_GRPC_TLS=false
+HYPERSNAP_GRPC_TLS=false
+```
+
+Both upstream node types use internal gRPC port `3383`. Port `4383` is only the loopback host remap for a co-located Hypersnap node. Never publish either native plaintext RPC port to the Internet.
+
+Choose a data directory outside the Git checkout. On Windows the default is `%LOCALAPPDATA%\SnapMeter`; an explicit secondary-drive layout is also valid:
+
+```dotenv
+SNAPMETER_DATA_DIR=D:\SnapMeter\collector
+```
+
+The collector creates and migrates `snapmeter.sqlite3` itself, including its WAL, cursors, local identity, schema-v3 actor pseudonym key, bounded analytics state, and durable delivery outbox. These files must remain untracked. A clean reconstruction creates a new collector ID and key inside its new database; neither value comes from production or belongs in configuration. Never inspect, print, extract, or export the key separately.
+
+Pair that new collector only with the clean local or remote D1 dataset created for the reconstruction. Migration `0005_collector_binding.sql` makes the first non-doctor delivery claim that dataset's global collector slot; an empty doctor probe only validates access and does not claim it. An existing production D1 dataset rejects a newly reconstructed database with HTTP 409 `collector_identity_conflict`. Production failover therefore restores the entire stopped, WAL-consistent collector state rather than reconstructing a new database; follow the [Windows runbook](windows-runbook.md).
+
+To deliver to a local Worker, set the exact loopback ingest URL printed by Vite and use the same disposable local secret in both processes:
+
+```dotenv
+SNAPMETER_INGEST_URL=http://127.0.0.1:5173/api/v1/ingest/batch
+SNAPMETER_INGEST_SECRET=replace-with-a-new-local-value-at-least-32-characters
+```
+
+Then run:
+
+```powershell
+./scripts/run-collector.ps1 -EnvFile .env -Mode doctor
+./scripts/run-collector.ps1 -EnvFile .env -Mode run
+```
+
+The runner imports `.env` into the collector process, validates the configuration, and redacts sensitive values from terminal/file logs. Direct `pnpm collector ...` commands read only the current process environment; they do not load `.env` automatically.
+
+Use `Ctrl+C` for a graceful stop. `./scripts/run-collector.ps1 -EnvFile .env -Mode status` reads the last local health snapshot, and `./scripts/run-collector.ps1 -EnvFile .env -Mode backfill` performs bounded reconciliation without generating fake live pulses. On Windows, `./scripts/bootstrap.ps1` combines the locked install, directory checks, endpoint probes, and doctor; [the Windows runbook](windows-runbook.md) covers Scheduled Task installation and recovery.
+
+## Obtain optional upstream node source
+
+A clear sibling layout keeps external GPL projects and heavyweight state out of the SnapMeter repository:
+
+```text
+C:\src\SnapMeter\
+C:\src\upstream\snapchain\
+C:\src\upstream\hypersnap\
+D:\SnapMeter\collector\
+D:\SnapMeter\nodes\snapchain\
+D:\SnapMeter\nodes\hypersnap\
+```
+
+From `C:\src\SnapMeter`, clone and detach the inspected revisions:
+
+```powershell
+New-Item -ItemType Directory -Force ..\upstream | Out-Null
+git clone https://github.com/farcasterxyz/snapchain.git ..\upstream\snapchain
+git -C ..\upstream\snapchain switch --detach 6152402aea2dbe732fb73076f674b038bfd4aee5
+git clone https://github.com/farcasterorg/hypersnap.git ..\upstream\hypersnap
+git -C ..\upstream\hypersnap switch --detach 2eee4c9f2a7833ce7971dfef028480abbe9c4720
+git -C ..\upstream\snapchain rev-parse HEAD
+git -C ..\upstream\hypersnap rev-parse HEAD
+```
+
+The last two commands must print the exact full SHAs above. Build and configure each node from the documentation contained in that detached checkout. SnapMeter deliberately does not duplicate upstream build flags, bootstrap peers, snapshots, or chain configuration because those operational details can change independently and have material storage/network consequences.
+
+`docker-compose.nodes.override.yml` is an illustrative Compose 2.24.4+ fragment for a separately reviewed upstream-node project. It is not a standalone node launcher. It binds Snapchain host port `3383` and Hypersnap host port `4383` to each container's internal port `3383`, both on loopback.
+
+An exact 30-day cold start requires at least 31 days of authoritative event retention or a separately trusted history source. The pinned default Snapchain HubEvent retention is only three days. Missing older history must remain visibly partial until sufficient prospective coverage accumulates.
+
+## Reconstruct Cloudflare resources
+
+Local reconstruction never requires Cloudflare. For a separate remote environment, create a new D1 database, update only that environment's database ID, apply every checked-in migration in order, create a new ingest secret, and deploy with a least-privilege account token. Do not reuse SnapMeter production D1 contents or credentials.
+
+```powershell
+pnpm --filter @snapmeter/dashboard exec wrangler d1 create snapmeter-prod
+pnpm --filter @snapmeter/dashboard exec wrangler d1 migrations apply snapmeter-prod --remote
+pnpm --filter @snapmeter/dashboard exec wrangler secret put SNAPMETER_INGEST_SECRET
+pnpm --filter @snapmeter/dashboard run deploy
+```
+
+Review and replace the checked-in production database identifier before targeting another account. D1 database identifiers and the Farcaster `accountAssociation` are public configuration, not authorization credentials; Cloudflare tokens, ingest secrets, RPC keys, and Farcaster custody keys are secrets. Follow [Cloudflare deployment](deployment.md) for first-deploy smoke tests, CI secret names, and rollback.
+
+## Pre-publication secret check
+
+Ignoring a file now does not remove it from earlier commits. Before publishing any branch:
+
+1. Rotate any credential that was pasted into chat, a terminal command, an issue, a log, or a previously published commit. Treat it as exposed even if the message or file was later deleted.
+2. Confirm only the blank template is tracked among environment files:
+
+ ```powershell
+ git ls-files '.env*' '.dev.vars*' '.collector.env'
+ ```
+
+ The expected output is only `.env.example`.
+
+3. Confirm local credential and state files are ignored:
+
+ ```powershell
+ git check-ignore -v .env .env.neynar .env.collector.production .dev.vars
+ git status --ignored --short
+ ```
+
+4. Review every staged path and patch, including binary additions:
+
+ ```powershell
+ git diff --cached --name-status
+ git diff --cached
+ ```
+
+5. Run a maintained secret scanner against both the working tree and complete Git history. Investigate findings; do not suppress a match merely to make CI green.
+6. Never attach `.env`, `.wrangler`, SQLite/WAL files, node data, logs, raw ingest bodies, authorization headers, or diagnostic archives to a GitHub issue or release.
+
+See [Security](security.md) for the complete data-minimization and credential-rotation policy. A public reconstruction is complete when the clean checkout installs from the lockfile, passes all gates, runs the deterministic demo, creates empty local schemas from source, and can accept operator-owned endpoints and newly provisioned secrets. Reproducing private historical data is neither required nor desired.
diff --git a/docs/metrics.md b/docs/metrics.md
index 411475d..3f613ef 100644
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -68,9 +68,12 @@ For a set of valid, deduplicated actions `A` and evaluation time `t`:
- **Active FIDs 5m:** unique FIDs with `t - 5m < actionAt <= t`.
- **Actions/minute 1m:** qualifying action count in the latest minute.
- **Actions/minute 5m:** qualifying action count in the latest five minutes divided by five.
+- **Qualifying action mix:** qualifying action count grouped by action family in the same exact rolling 24-hour window used for the rolling active-FID metric.
The same FID is counted once per unique-FID window regardless of action count. It can appear once in each source because sources measure observations through distinct configured nodes. Never add two source totals and call the result network-wide unique activity without actor-level union data.
+Snapchain and Hypersnap snapshots in a comparison batch use one shared evaluation time `t`. The dashboard may compare their rolling metrics and action mix only when both source snapshots have that same window end; it must label or withhold a mismatched comparison rather than silently compare different periods. “Today UTC DAU” is the UTC calendar-day measure. “Rolling 24h active” is a continuously moving daily-activity window and must remain visibly distinguished from calendar-day DAU.
+
Current-versus-previous absolute change is `current24 - previous24`. Percentage change is `(current - previous) / previous * 100`; it is `null` rather than infinity when the previous value is zero.
## Time authority
diff --git a/docs/screenshot-mobile.png b/docs/screenshot-mobile.png
index 5d10003..624223f 100644
Binary files a/docs/screenshot-mobile.png and b/docs/screenshot-mobile.png differ
diff --git a/docs/security.md b/docs/security.md
index 190911e..01ccf28 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -2,7 +2,7 @@
## Assets and trust boundaries
-Sensitive assets are the ingest HMAC secret, optional RPC authorization metadata, Cloudflare API token/account configuration, local actor/cursor database, and retry outbox. The public dashboard, summary APIs, and WebSocket clients are untrusted readers. Node RPC endpoints and collector state stay private.
+Sensitive assets are the ingest HMAC secret, optional RPC authorization/API-key metadata, Cloudflare API token/account configuration, local actor/cursor database, and retry outbox. The schema-v3 collector database also contains the authoritative collector ID and actor pseudonym key. The public dashboard, summary APIs, and WebSocket clients are untrusted readers. Node RPC endpoints and collector state stay private.
Primary threats are forged/replayed ingest, duplicate or out-of-order delivery, secret leakage through logs/bundles, public node exposure, oversized/schema-confusing requests, SQL injection, source-quality spoofing, WebSocket abuse, and unbounded local/cloud storage.
@@ -14,6 +14,7 @@ The collector signs the exact raw request body with `SNAPMETER_INGEST_SECRET`, t
- parse timestamp strictly and enforce a five-minute tolerance;
- verify the HMAC in constant time over the same canonical payload;
- validate the complete runtime schema and schema version;
+- reject impossible UTC days, internally incoherent times, and future-dated records that could pin monotonic latest-state storage;
- enforce a unique batch ID/nonce in bounded D1 replay storage;
- perform idempotent storage so retries cannot double-count;
- rate-limit by source and reject source/header/body mismatches;
@@ -28,13 +29,22 @@ Allowed analytics metadata includes source, source mode, shard/event identity, n
Do not collect, persist, log, or upload cast text, signatures, signer keys, raw message bodies, authorization metadata, `.env` contents, or unnecessary onchain/user payloads. Bound retention of event idempotency, minute buckets, health, nonces, and logs. Retain daily aggregates long-term only as required by product policy.
+## Collector identity and failover
+
+Migration `0005_collector_binding.sql` gives each D1 dataset one global `collector_binding` row at `slot=1`. The first authenticated, non-doctor ingest atomically claims it with the batch's `collectorId`; an empty doctor probe does not claim it. Later traffic from a different ID receives HTTP 409 `collector_identity_conflict` before rate limiting or persistence. This prevents two independently initialized databases, which have different actor pseudonym keys, from double-counting the same actors. Run only one authoritative collector database against a production D1 dataset.
+
+For failover, stop the collector and take a SQLite-consistent backup of the entire collector state, including `snapmeter.sqlite3` and any associated WAL/SHM state. Restore or clone that stopped state as one unit so the collector ID, pseudonym key, cursors, deduplication records, and outbox stay aligned. Never inspect, print, extract, export, copy, or persist the pseudonym key separately. A fresh database is a new collector identity and is not a replacement for this backup.
+
+Accepting an intentionally new database requires an explicit operator reset of the D1 collector binding: `DELETE FROM collector_binding WHERE slot=1`. Perform that statement only after backing up D1 and completing the metric-continuity plan. Treat the reset as a metric-data boundary: preferably perform it at a UTC-day boundary when no reconciliation will add actors to earlier retained days, or clear and deliberately rebuild the affected cloud actor-day membership before accepting the new ID. Changing the ingest secret does not reset this binding. Schema v3 is forward-only; if a release fails after migration, restore the stopped pre-upgrade database with its compatible binary or fix forward, rather than running a pre-v3 binary against a v3 database.
+
## Secrets
- Local collector secrets live in a gitignored `.env` with restrictive ACLs.
- Production Worker secrets use `wrangler secret`; GitHub uses protected environment/repository secrets.
- No secret may use a `VITE_` prefix or otherwise enter the browser bundle.
- PowerShell scripts validate presence and print only names/status, never values.
-- Structured logs use field allowlists and redact `authorization`, cookies, signatures, tokens, secrets, URLs with credentials, and raw bodies.
+- Structured logs use field allowlists and redact API keys, `authorization`, cookies, signatures, tokens, secrets, URLs with credentials, and raw bodies.
+- Remote cloud ingest must use HTTPS. Plain HTTP is accepted only for an explicit loopback development endpoint; RPC credentials similarly require TLS except on loopback.
- `.env.example` contains no usable credentials.
If a secret is exposed, stop affected ingest, rotate the Worker secret/token, update collectors securely, review replay/idempotency logs, and invalidate the old value. Git history rewriting is a separate release-owner decision; deleting a working-tree file alone is insufficient.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 49fab30..ce5cdd7 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -4,8 +4,8 @@ Start with a redacted diagnostic snapshot:
```powershell
./scripts/check-health.ps1 -EnvFile .env
-pnpm collector doctor
-pnpm collector status
+./scripts/run-collector.ps1 -EnvFile .env -Mode doctor
+./scripts/run-collector.ps1 -EnvFile .env -Mode status
```
Do not paste `.env`, signatures, authorization headers, raw ingest bodies, or database files into an issue.
@@ -67,6 +67,7 @@ This can be correct. Idle sources have no fake beat, and replay/catch-up/reconci
- Check schema version and request size.
- Verify the D1 replay/idempotency migration and `DB` binding.
- A temporary Worker failure should leave the batch in the durable local outbox.
+- HTTP 409 `collector_identity_conflict` means D1 is already bound to another collector ID. Stop the new process and restore the complete registered collector database state. Do not weaken the check or delete its outbox. Moving intentionally to a fresh database requires the documented manual collector-binding reset and actor-day continuity plan.
## Site loads but status is stale/disconnected
diff --git a/docs/windows-runbook.md b/docs/windows-runbook.md
index 98cd61f..0bb517e 100644
--- a/docs/windows-runbook.md
+++ b/docs/windows-runbook.md
@@ -28,6 +28,8 @@ SNAPCHAIN_GRPC_URL=127.0.0.1:3383
HYPERSNAP_GRPC_URL=127.0.0.1:4383
SNAPCHAIN_GRPC_TLS=false
HYPERSNAP_GRPC_TLS=false
+SNAPCHAIN_GRPC_API_KEY=
+SNAPCHAIN_RPC_MIN_INTERVAL_MS=0
SNAPMETER_INGEST_URL=
SNAPMETER_INGEST_SECRET=
SNAPMETER_DATA_DIR=C:\ProgramData\SnapMeter
@@ -35,6 +37,8 @@ SNAPMETER_DATA_DIR=C:\ProgramData\SnapMeter
After a verified deployment, fill the URL with the exact origin plus `/api/v1/ingest/batch` and place the matching Wrangler-managed secret only in this local file. Restrict `.env` ACLs to the collector account and administrators.
+For Neynar-hosted Snapchain, set `SNAPCHAIN_GRPC_URL=snapchain-grpc-api.neynar.com:443`, `SNAPCHAIN_GRPC_TLS=true`, and `SNAPCHAIN_GRPC_API_KEY` to the key from the Neynar developer portal. Set `SNAPCHAIN_RPC_MIN_INTERVAL_MS=250` to serialize GetEvents request starts across both shard workers at no more than four starts per second. If no independent Hypersnap source is available, set `HYPERSNAP_SOURCE_MODE=unavailable`. The collector never prints the API-key value.
+
## Interactive operation
```powershell
@@ -77,7 +81,7 @@ Uninstalling the task does not delete databases, logs, `.env`, or outbox data.
## Data, logs, and permissions
-If `SNAPMETER_DATA_DIR` is empty, scripts resolve `%LOCALAPPDATA%\SnapMeter`. Production boot tasks should use an explicit absolute path, commonly `C:\ProgramData\SnapMeter`. Logs default to a `logs` child directory. The runner keeps `collector-*.log` files for 14 days by default; set `SNAPMETER_LOG_RETENTION_DAYS` from 1 through 365. Cleanup resolves and verifies every target under the configured log directory before deletion. The SQLite database, lock, health snapshot, and outbox remain local.
+If `SNAPMETER_DATA_DIR` is empty, scripts resolve `%LOCALAPPDATA%\SnapMeter`. Production boot tasks should use an explicit absolute path, commonly `C:\ProgramData\SnapMeter`. Logs default to a `logs` child directory. The runner keeps `collector-*.log` files for 14 days by default; set `SNAPMETER_LOG_RETENTION_DAYS` from 1 through 365. Cleanup resolves and verifies every target under the configured log directory before deletion. The SQLite database, lock, health snapshot, and outbox remain local. Schema v3 keeps the authoritative collector ID and actor pseudonym key inside the SQLite database; never print, extract, or export that key separately.
Check free space regularly:
@@ -89,6 +93,14 @@ Get-ChildItem C:\ProgramData\SnapMeter -Recurse -File |
Do not delete a live database or outbox to clear space. Stop the task, preserve a backup, use documented retention/maintenance, run integrity checks, and restart only after confirming the path and capacity.
+### Backup and failover
+
+The production D1 dataset accepts only its registered collector ID. A separately initialized collector has a different ID and pseudonym key and is rejected; do not run two independent collector databases against the same dataset.
+
+For backup or failover, stop the Scheduled Task, confirm the collector process has exited, and copy the entire resolved data directory as one SQLite-consistent unit. Preserve `snapmeter.sqlite3` together with any `snapmeter.sqlite3-wal` and `snapmeter.sqlite3-shm` files, the outbox, and their access controls. Restore that stopped state as a unit before starting the replacement host. Do not copy only a live main database, and do not move the pseudonym key into `.env` or another key store.
+
+An intentional move to a fresh database requires the guarded manual reset of `collector_binding` documented in [Cloudflare deployment](deployment.md#collector-binding). Prefer a UTC-day boundary when no older-day reconciliation is pending; otherwise clear and deliberately rebuild affected cloud actor-day membership so two key domains cannot inflate DAU. This is an operator recovery action, not automatic failover. A schema-v3 database must not be opened by a pre-v3 collector binary; restore a compatible pre-upgrade database or fix forward.
+
## Firewall and port binding
- Bind local gRPC only to `127.0.0.1` when the collector is on the same host.
@@ -124,7 +136,7 @@ For a collector container talking to Windows-hosted nodes, use `host.docker.inte
1. Stop the scheduled task and confirm no collector process remains.
2. Back up `.env` and the data directory without exposing them in source control.
3. Pull the reviewed release and run `./scripts/bootstrap.ps1 -SkipDoctor`.
-4. Run `pnpm collector doctor`, including database integrity/cursor checks.
+4. Run `./scripts/run-collector.ps1 -EnvFile .env -Mode doctor`, including database integrity/cursor checks.
5. Reinstall the task so its resolved executable paths and arguments match the release.
6. Start it and run `./scripts/check-health.ps1`.
diff --git a/migrations/0005_collector_binding.sql b/migrations/0005_collector_binding.sql
new file mode 100644
index 0000000..98f922f
--- /dev/null
+++ b/migrations/0005_collector_binding.sql
@@ -0,0 +1,5 @@
+CREATE TABLE collector_binding (
+ slot INTEGER PRIMARY KEY CHECK (slot = 1),
+ collector_id TEXT NOT NULL,
+ claimed_at_ms INTEGER NOT NULL
+);
diff --git a/package.json b/package.json
index 70cb2ab..70da52e 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,7 @@
"collector": "pnpm --filter @snapmeter/collector collector",
"dev": "pnpm --filter @snapmeter/dashboard dev",
"lint": "eslint .",
+ "security:check": "node scripts/check-publication-safety.mjs && pnpm audit --prod --audit-level high",
"test": "vitest run && pnpm --filter @snapmeter/dashboard test && pnpm --filter @snapmeter/dashboard test:worker",
"test:coverage": "vitest run --coverage",
"test:e2e": "pnpm --filter @snapmeter/dashboard test:e2e",
diff --git a/packages/contracts/src/schemas.test.ts b/packages/contracts/src/schemas.test.ts
new file mode 100644
index 0000000..12d550a
--- /dev/null
+++ b/packages/contracts/src/schemas.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { ActorDaySchema, DailyDatumSchema, UtcDaySchema } from "./schemas";
+
+describe("UTC calendar-day schemas", () => {
+ it.each(["2024-02-29", "2026-08-13", "0000-01-01", "9999-12-31"])(
+ "accepts a canonical real day: %s",
+ (day) => expect(UtcDaySchema.safeParse(day).success).toBe(true)
+ );
+
+ it.each(["2023-02-29", "2026-02-30", "2026-13-01", "2026-00-01", "2026-1-01", "not-a-day"])(
+ "rejects an impossible or noncanonical day: %s",
+ (day) => expect(UtcDaySchema.safeParse(day).success).toBe(false)
+ );
+
+ it("applies the strict day check to daily metrics and actor membership", () => {
+ expect(DailyDatumSchema.safeParse({ day: "2026-02-30", activeFids: 1, actions: 1 }).success).toBe(false);
+ expect(ActorDaySchema.safeParse({ source: "snapchain", day: "2026-02-30", fidHash: "a".repeat(64) }).success).toBe(false);
+ });
+
+ it("requires the collector's exact keyed actor pseudonym format", () => {
+ expect(ActorDaySchema.safeParse({ source: "snapchain", day: "2026-08-13", fidHash: "a".repeat(64) }).success).toBe(true);
+ expect(ActorDaySchema.safeParse({ source: "snapchain", day: "2026-08-13", fidHash: "raw-fid-12345678" }).success).toBe(false);
+ expect(ActorDaySchema.safeParse({ source: "snapchain", day: "2026-08-13", fidHash: "A".repeat(64) }).success).toBe(false);
+ });
+});
diff --git a/packages/contracts/src/schemas.ts b/packages/contracts/src/schemas.ts
index 43bd5bb..24e2eba 100644
--- a/packages/contracts/src/schemas.ts
+++ b/packages/contracts/src/schemas.ts
@@ -42,8 +42,20 @@ export type ActionFamily = z.infer;
export const TrendLabelSchema = z.enum(["Improving", "Worsening", "Stable", "Insufficient data"]);
+const UTC_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+function isRealUtcDay(value: string): boolean {
+ if (!UTC_DAY_PATTERN.test(value)) return false;
+ const parsed = new Date(`${value}T00:00:00.000Z`);
+ return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
+export const UtcDaySchema = z.string().refine(isRealUtcDay, {
+ message: "Expected a real UTC calendar day in YYYY-MM-DD format"
+});
+
export const DailyDatumSchema = z.object({
- day: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+ day: UtcDaySchema,
activeFids: z.number().int().nonnegative(),
actions: z.number().int().nonnegative()
});
@@ -142,7 +154,7 @@ export const PulsePacketSchema = z.object({
uniqueFids: z.number().int().positive(),
actionCounts: z.partialRecord(ActionFamilySchema, z.number().int().nonnegative()),
lastActionAtMs: z.number().int().nonnegative(),
- maxEventId: z.string(),
+ maxEventId: z.string().regex(/^\d+$/),
isReplay: z.literal(false)
});
export type PulsePacket = z.infer;
@@ -158,8 +170,8 @@ export type MinuteBucket = z.infer;
export const ActorDaySchema = z.object({
source: SourceSchema,
- day: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
- fidHash: z.string().min(16).max(128)
+ day: UtcDaySchema,
+ fidHash: z.string().regex(/^[0-9a-f]{64}$/)
});
export type ActorDay = z.infer;
diff --git a/packages/contracts/src/security.test.ts b/packages/contracts/src/security.test.ts
index 82fef6f..721eecb 100644
--- a/packages/contracts/src/security.test.ts
+++ b/packages/contracts/src/security.test.ts
@@ -6,6 +6,8 @@ describe("ingest HMAC", () => {
const signature = await signIngest("secret-value", "1700000000000", "batch-a", "{\"a\":1}");
await expect(verifyIngestSignature("secret-value", "1700000000000", "batch-a", "{\"a\":1}", signature)).resolves.toBe(true);
await expect(verifyIngestSignature("secret-value", "1700000000000", "batch-a", "{\"a\":2}", signature)).resolves.toBe(false);
+ await expect(verifyIngestSignature("secret-value", "1700000000000", "batch-a", "{\"a\":1}", signature.slice(3))).resolves.toBe(false);
+ await expect(verifyIngestSignature("secret-value", "1700000000000", "batch-a", "{\"a\":1}", signature.toUpperCase())).resolves.toBe(false);
});
it("rejects malformed or stale timestamps", () => {
diff --git a/packages/contracts/src/security.ts b/packages/contracts/src/security.ts
index 7029d06..4bf797c 100644
--- a/packages/contracts/src/security.ts
+++ b/packages/contracts/src/security.ts
@@ -45,7 +45,8 @@ export async function verifyIngestSignature(
rawBody: string,
suppliedSignature: string
): Promise {
- const supplied = hexToBytes(suppliedSignature.replace(/^v1=/, ""));
+ if (!/^v1=[0-9a-f]{64}$/.test(suppliedSignature)) return false;
+ const supplied = hexToBytes(suppliedSignature.slice(3));
if (!supplied) return false;
const expectedHex = (await signIngest(secret, timestamp, nonce, rawBody)).slice(3);
const expected = hexToBytes(expectedHex);
diff --git a/packages/protocol/src/rpc.test.ts b/packages/protocol/src/rpc.test.ts
new file mode 100644
index 0000000..4a0815f
--- /dev/null
+++ b/packages/protocol/src/rpc.test.ts
@@ -0,0 +1,161 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+import {
+ createRpcMetadata,
+ createSubscribeRequest,
+ invokeUnaryWithAbort,
+ MinimumIntervalGate,
+ observeSubscriptionStream,
+ type RawHubEvent
+} from "./rpc";
+
+describe("Snapchain RPC metadata", () => {
+ it("sends proxy authorization and hosted-provider API keys under distinct headers", () => {
+ const metadata = createRpcMetadata({ authorization: "Bearer proxy-secret", apiKey: "neynar-secret" });
+
+ expect(metadata.get("authorization")).toEqual(["Bearer proxy-secret"]);
+ expect(metadata.get("x-api-key")).toEqual(["neynar-secret"]);
+ });
+
+ it("does not add authentication headers when credentials are absent", () => {
+ const metadata = createRpcMetadata({});
+
+ expect(metadata.get("authorization")).toEqual([]);
+ expect(metadata.get("x-api-key")).toEqual([]);
+ });
+});
+
+describe("Snapchain live subscription request", () => {
+ it("omits fromId when subscribing at the live head", () => {
+ const request = createSubscribeRequest(2);
+ expect(request).toEqual({
+ eventTypes: ["HUB_EVENT_TYPE_MERGE_MESSAGE", "HUB_EVENT_TYPE_BLOCK_CONFIRMED"],
+ shardIndex: 2
+ });
+ expect(Object.hasOwn(request, "fromId")).toBe(false);
+ });
+
+ it("retains an explicit cursor when one is intentionally supplied", () => {
+ expect(createSubscribeRequest(1, "123")).toMatchObject({ shardIndex: 1, fromId: "123" });
+ });
+
+ it("does not become ready on metadata and incorporates first data before readiness", async () => {
+ const emitter = new EventEmitter();
+ const cancel = vi.fn();
+ const stream = Object.assign(emitter, { cancel }) as unknown as Parameters[0];
+ const seen: string[] = [];
+ const subscription = observeSubscriptionStream(stream, (event) => seen.push(String(event.id)), () => {});
+ let ready = false;
+ void subscription.ready.then(() => { ready = true; });
+
+ emitter.emit("metadata", createRpcMetadata({}));
+ await Promise.resolve();
+ expect(ready).toBe(false);
+ expect(seen).toEqual([]);
+
+ emitter.emit("data", { id: "123" } satisfies RawHubEvent);
+ await subscription.ready;
+ expect(seen).toEqual(["123"]);
+ expect(ready).toBe(true);
+ });
+
+ it("rejects readiness when the stream ends before its first data event", async () => {
+ const emitter = new EventEmitter();
+ const stream = Object.assign(emitter, { cancel: vi.fn() }) as unknown as Parameters[0];
+ const subscription = observeSubscriptionStream(stream, () => {}, () => {});
+ const rejection = expect(subscription.ready).rejects.toThrow(/ended before becoming ready/);
+ emitter.emit("end");
+ await rejection;
+ await subscription.done;
+ });
+
+ it("settles readiness and completion immediately when cancelled before first data", async () => {
+ const emitter = new EventEmitter();
+ const cancel = vi.fn();
+ const stream = Object.assign(emitter, { cancel }) as unknown as Parameters[0];
+ const subscription = observeSubscriptionStream(stream, () => {}, () => {});
+ const rejection = expect(subscription.ready).rejects.toMatchObject({
+ name: "AbortError",
+ message: "subscription cancelled"
+ });
+
+ subscription.cancel();
+
+ await rejection;
+ await subscription.done;
+ expect(cancel).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe("shared GetEvents start throttling", () => {
+ it("spaces concurrent callers by the configured minimum interval", async () => {
+ let nowMs = 1_000;
+ const waits: number[] = [];
+ const gate = new MinimumIntervalGate(250, {
+ now: () => nowMs,
+ delay: async (milliseconds) => {
+ waits.push(milliseconds);
+ nowMs += milliseconds;
+ }
+ });
+
+ const starts = await Promise.all([
+ gate.waitForStart(),
+ gate.waitForStart(),
+ gate.waitForStart()
+ ]);
+
+ expect(starts).toEqual([1_000, 1_250, 1_500]);
+ expect(waits).toEqual([250, 250]);
+ });
+
+ it("allows unthrottled calls when the interval is zero", async () => {
+ const gate = new MinimumIntervalGate(0, { now: () => 123 });
+ expect(await Promise.all([gate.waitForStart(), gate.waitForStart()])).toEqual([123, 123]);
+ });
+
+ it("aborts a queued caller promptly without starting its RPC", async () => {
+ let nowMs = 1_000;
+ let releaseDelay: (() => void) | undefined;
+ const delay = vi.fn(() => new Promise((resolve) => { releaseDelay = resolve; }));
+ const gate = new MinimumIntervalGate(250, { now: () => nowMs, delay });
+ await gate.waitForStart();
+
+ const predecessor = gate.waitForStart();
+ await vi.waitFor(() => expect(delay).toHaveBeenCalledTimes(1));
+ const controller = new AbortController();
+ let rpcStarts = 0;
+ const queued = (async () => {
+ await gate.waitForStart(controller.signal);
+ rpcStarts += 1;
+ })();
+
+ controller.abort();
+ await expect(queued).rejects.toMatchObject({ name: "AbortError", message: "RPC pacing aborted" });
+ expect(rpcStarts).toBe(0);
+
+ nowMs = 1_250;
+ releaseDelay?.();
+ await predecessor;
+ await Promise.resolve();
+ expect(rpcStarts).toBe(0);
+ });
+});
+
+describe("abortable unary RPC", () => {
+ it("cancels an in-flight call and rejects once with AbortError", async () => {
+ const controller = new AbortController();
+ const cancel = vi.fn();
+ let callback: ((error: Error | null, response: { ok: boolean }) => void) | undefined;
+ const pending = invokeUnaryWithAbort<{ ok: boolean }>((settle) => {
+ callback = settle;
+ return { cancel } as unknown as ReturnType>[0]>;
+ }, controller.signal);
+
+ controller.abort();
+ await expect(pending).rejects.toMatchObject({ name: "AbortError", message: "RPC request aborted" });
+ expect(cancel).toHaveBeenCalledTimes(1);
+ callback?.(null, { ok: true });
+ expect(cancel).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/protocol/src/rpc.ts b/packages/protocol/src/rpc.ts
index 7177c65..40b1030 100644
--- a/packages/protocol/src/rpc.ts
+++ b/packages/protocol/src/rpc.ts
@@ -1,4 +1,4 @@
-import { credentials, loadPackageDefinition, Metadata, type ClientReadableStream, type ServiceError } from "@grpc/grpc-js";
+import { credentials, loadPackageDefinition, Metadata, type ClientReadableStream, type ClientUnaryCall, type ServiceError } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { fileURLToPath } from "node:url";
import { actionFamilyForMessage, isHyperEligible } from "./classifier";
@@ -11,7 +11,9 @@ export interface RpcConfig {
url: string;
tls: boolean;
authorization?: string;
+ apiKey?: string;
timeoutMs?: number;
+ getEventsMinIntervalMs?: number;
}
export interface ShardInfo {
@@ -37,15 +39,27 @@ export interface RawHubEvent {
blockConfirmedBody?: Record;
}
+export interface ProtocolRpcSubscription {
+ cancel(): void;
+ ready: Promise;
+ done: Promise;
+}
+
interface DynamicHubClient {
- getInfo(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: any) => void): void;
- getEvent(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: RawHubEvent) => void): void;
- getEvents(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: { events?: RawHubEvent[]; nextPageToken?: Buffer }) => void): void;
+ getInfo(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: any) => void): ClientUnaryCall;
+ getEvent(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: RawHubEvent) => void): ClientUnaryCall;
+ getEvents(request: object, metadata: Metadata, options: object, callback: (error: ServiceError | null, value: { events?: RawHubEvent[]; nextPageToken?: Buffer }) => void): ClientUnaryCall;
subscribe(request: object, metadata: Metadata): ClientReadableStream;
close(): void;
}
-type HubConstructor = new (address: string, channelCredentials: ReturnType) => DynamicHubClient;
+type HubConstructor = new (
+ address: string,
+ channelCredentials: ReturnType,
+ options?: { "grpc.max_receive_message_length"?: number }
+) => DynamicHubClient;
+
+const MAX_RECEIVE_MESSAGE_BYTES = 20 * 1024 * 1024;
let cachedConstructor: HubConstructor | null = null;
@@ -66,20 +80,24 @@ export function loadHubServiceConstructor(): HubConstructor {
export class SnapchainRpcClient {
readonly #client: DynamicHubClient;
- readonly #metadata = new Metadata();
+ readonly #metadata: Metadata;
readonly #timeoutMs: number;
+ readonly #getEventsStartGate: MinimumIntervalGate;
constructor(config: RpcConfig) {
if (!config.url || config.url.includes("://")) throw new Error("gRPC URL must be host:port without a scheme");
const Constructor = loadHubServiceConstructor();
const channelCredentials = config.tls ? credentials.createSsl() : credentials.createInsecure();
- this.#client = new Constructor(config.url, channelCredentials as ReturnType);
+ this.#client = new Constructor(config.url, channelCredentials as ReturnType, {
+ "grpc.max_receive_message_length": MAX_RECEIVE_MESSAGE_BYTES
+ });
this.#timeoutMs = config.timeoutMs ?? 10_000;
- if (config.authorization) this.#metadata.set("authorization", config.authorization);
+ this.#metadata = createRpcMetadata(config);
+ this.#getEventsStartGate = new MinimumIntervalGate(config.getEventsMinIntervalMs ?? 0);
}
- async getInfo(): Promise {
- const response = await this.#unary("getInfo", {});
+ async getInfo(signal?: AbortSignal): Promise {
+ const response = await this.#unary("getInfo", {}, signal);
const shardInfos: ShardInfo[] = Array.isArray(response.shardInfos) ? response.shardInfos.map((shard: any) => ({
shardId: Number(shard.shardId ?? 0),
maxHeight: Number(shard.maxHeight ?? 0),
@@ -90,11 +108,18 @@ export class SnapchainRpcClient {
return { version: String(response.version ?? "unknown"), numShards: declared || shardInfos.filter((shard) => shard.shardId > 0).length, shardInfos };
}
- async getEvent(shardIndex: number, id: string): Promise {
- return this.#unary("getEvent", { shardIndex, id });
+ async getEvent(shardIndex: number, id: string, signal?: AbortSignal): Promise {
+ return this.#unary("getEvent", { shardIndex, id }, signal);
}
- async getEvents(shardIndex: number, startId: string, pageToken?: Uint8Array, stopId?: string): Promise<{ events: RawHubEvent[]; nextPageToken?: Uint8Array }> {
+ async getEvents(
+ shardIndex: number,
+ startId: string,
+ pageToken?: Uint8Array,
+ stopId?: string,
+ signal?: AbortSignal
+ ): Promise<{ events: RawHubEvent[]; nextPageToken?: Uint8Array }> {
+ await this.#getEventsStartGate.waitForStart(signal);
const response = await this.#unary<{ events?: RawHubEvent[]; nextPageToken?: Buffer }>("getEvents", {
shardIndex,
startId,
@@ -102,41 +127,235 @@ export class SnapchainRpcClient {
pageSize: 500,
pageToken: pageToken ? Buffer.from(pageToken) : undefined,
reverse: false
- });
+ }, signal);
return {
events: response.events ?? [],
nextPageToken: response.nextPageToken?.length ? new Uint8Array(response.nextPageToken) : undefined
};
}
- subscribe(shardIndex: number, fromId: string, onEvent: (event: RawHubEvent) => void, onError: (error: Error) => void): { cancel: () => void; done: Promise } {
+ subscribe(
+ shardIndex: number,
+ fromId: string | undefined,
+ onEvent: (event: RawHubEvent) => void,
+ onError: (error: Error) => void
+ ): ProtocolRpcSubscription {
const stream = this.#client.subscribe(
- { eventTypes: ["HUB_EVENT_TYPE_MERGE_MESSAGE", "HUB_EVENT_TYPE_BLOCK_CONFIRMED"], fromId, shardIndex },
+ createSubscribeRequest(shardIndex, fromId),
this.#metadata
);
- let settle: (() => void) | undefined;
- const done = new Promise((resolve) => { settle = resolve; });
- stream.on("data", onEvent);
- stream.on("error", (error: Error) => { onError(error); settle?.(); });
- stream.on("end", () => settle?.());
- stream.on("close", () => settle?.());
- return { cancel: () => stream.cancel(), done };
+ return observeSubscriptionStream(stream, onEvent, onError);
}
close(): void {
this.#client.close();
}
- #unary(method: "getInfo" | "getEvent" | "getEvents", request: object): Promise {
- return new Promise((resolve, reject) => {
- this.#client[method](request, this.#metadata, { deadline: Date.now() + this.#timeoutMs }, (error: ServiceError | null, response: any) => {
- if (error) reject(error);
- else resolve(response as T);
- });
+ #unary(method: "getInfo" | "getEvent" | "getEvents", request: object, signal?: AbortSignal): Promise {
+ return invokeUnaryWithAbort((callback) => this.#client[method](
+ request,
+ this.#metadata,
+ { deadline: Date.now() + this.#timeoutMs },
+ (error: ServiceError | null, response: any) => callback(error, response as T)
+ ), signal);
+ }
+}
+
+export function invokeUnaryWithAbort(
+ start: (callback: (error: Error | null, response: T) => void) => ClientUnaryCall,
+ signal?: AbortSignal
+): Promise {
+ return new Promise((resolve, reject) => {
+ let call: ClientUnaryCall | undefined;
+ let settled = false;
+ const cleanup = (): void => signal?.removeEventListener("abort", onAbort);
+ const settle = (error: Error | null, response?: T): void => {
+ if (settled) return;
+ settled = true;
+ cleanup();
+ if (error) reject(error);
+ else resolve(response as T);
+ };
+ const onAbort = (): void => {
+ if (settled) return;
+ settled = true;
+ cleanup();
+ call?.cancel();
+ reject(rpcAbortError());
+ };
+ if (signal?.aborted) {
+ onAbort();
+ return;
+ }
+ signal?.addEventListener("abort", onAbort, { once: true });
+ try {
+ call = start((error, response) => settle(error, response));
+ } catch (error) {
+ settle(error instanceof Error ? error : new Error(String(error)));
+ }
+ });
+}
+
+function rpcAbortError(message = "RPC request aborted"): Error {
+ const error = new Error(message);
+ error.name = "AbortError";
+ return error;
+}
+
+export function observeSubscriptionStream(
+ stream: ClientReadableStream,
+ onEvent: (event: RawHubEvent) => void,
+ onError: (error: Error) => void
+): ProtocolRpcSubscription {
+ let settleDone: (() => void) | undefined;
+ let resolveReady: (() => void) | undefined;
+ let rejectReady: ((error: Error) => void) | undefined;
+ let readySettled = false;
+ let doneSettled = false;
+ const ready = new Promise((resolve, reject) => {
+ resolveReady = resolve;
+ rejectReady = reject;
});
+ const done = new Promise((resolve) => { settleDone = resolve; });
+ const markReady = (): void => {
+ if (readySettled) return;
+ readySettled = true;
+ resolveReady?.();
+ };
+ const failBeforeReady = (error: Error): void => {
+ if (readySettled) return;
+ readySettled = true;
+ rejectReady?.(error);
+ };
+ const finish = (): void => {
+ if (doneSettled) return;
+ doneSettled = true;
+ settleDone?.();
+ };
+ stream.on("data", (event: RawHubEvent) => {
+ // Snapchain sends response metadata before its spawned subscription task
+ // installs the broadcast receiver. Incorporate the first data event
+ // before declaring readiness so the subsequent fixed-bound replay sees it.
+ onEvent(event);
+ markReady();
+ });
+ stream.on("error", (error: Error) => {
+ failBeforeReady(error);
+ onError(error);
+ finish();
+ });
+ stream.on("end", () => {
+ failBeforeReady(new Error("subscription ended before becoming ready"));
+ finish();
+ });
+ stream.on("close", () => {
+ failBeforeReady(new Error("subscription closed before becoming ready"));
+ finish();
+ });
+ return {
+ cancel: () => {
+ failBeforeReady(rpcAbortError("subscription cancelled"));
+ finish();
+ stream.cancel();
+ },
+ ready,
+ done
+ };
+}
+
+export interface SubscribeRequest {
+ eventTypes: string[];
+ shardIndex: number;
+ fromId?: string;
+}
+
+export function createSubscribeRequest(shardIndex: number, fromId?: string): SubscribeRequest {
+ const request: SubscribeRequest = {
+ eventTypes: ["HUB_EVENT_TYPE_MERGE_MESSAGE", "HUB_EVENT_TYPE_BLOCK_CONFIRMED"],
+ shardIndex
+ };
+ if (fromId !== undefined) request.fromId = fromId;
+ return request;
+}
+
+type Delay = (milliseconds: number) => Promise;
+
+/**
+ * Serializes only the start of calls. One instance is shared by every shard on
+ * a client, while requests may overlap after their rate-limited start time.
+ */
+export class MinimumIntervalGate {
+ readonly #minimumIntervalMs: number;
+ readonly #now: () => number;
+ readonly #delay: Delay;
+ #nextStartAtMs = 0;
+ #tail = Promise.resolve();
+
+ constructor(
+ minimumIntervalMs: number,
+ options: { now?: () => number; delay?: Delay } = {}
+ ) {
+ if (!Number.isSafeInteger(minimumIntervalMs) || minimumIntervalMs < 0) {
+ throw new Error("minimum RPC start interval must be a nonnegative integer");
+ }
+ this.#minimumIntervalMs = minimumIntervalMs;
+ this.#now = options.now ?? Date.now;
+ this.#delay = options.delay ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+ }
+
+ waitForStart(signal?: AbortSignal): Promise {
+ const scheduled = this.#tail.then(async () => {
+ throwIfRpcAborted(signal);
+ const waitMs = Math.max(0, this.#nextStartAtMs - this.#now());
+ if (waitMs > 0) {
+ await waitForPromiseOrAbort(this.#delay(waitMs), signal, "RPC pacing aborted");
+ }
+ throwIfRpcAborted(signal);
+ const startedAtMs = this.#now();
+ this.#nextStartAtMs = startedAtMs + this.#minimumIntervalMs;
+ return startedAtMs;
+ });
+ this.#tail = scheduled.then(() => undefined, () => undefined);
+ return waitForPromiseOrAbort(scheduled, signal, "RPC pacing aborted");
}
}
+function throwIfRpcAborted(signal?: AbortSignal): void {
+ if (signal?.aborted) throw rpcAbortError();
+}
+
+function waitForPromiseOrAbort(
+ promise: Promise,
+ signal: AbortSignal | undefined,
+ message: string
+): Promise {
+ if (!signal) return promise;
+ if (signal.aborted) return Promise.reject(rpcAbortError(message));
+ return new Promise((resolve, reject) => {
+ let settled = false;
+ const cleanup = (): void => signal.removeEventListener("abort", onAbort);
+ const settle = (continuation: () => void): void => {
+ if (settled) return;
+ settled = true;
+ cleanup();
+ continuation();
+ };
+ const onAbort = (): void => settle(() => reject(rpcAbortError(message)));
+ signal.addEventListener("abort", onAbort, { once: true });
+ promise.then(
+ (value) => settle(() => resolve(value)),
+ (error) => settle(() => reject(error))
+ );
+ });
+}
+
+export function createRpcMetadata(config: Pick): Metadata {
+ const metadata = new Metadata();
+ if (config.authorization) metadata.set("authorization", config.authorization);
+ if (config.apiKey) metadata.set("x-api-key", config.apiKey);
+ return metadata;
+}
+
export function normalizeMergeEvent(
event: RawHubEvent,
source: Source,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d228656..a73392e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,6 +4,9 @@ settings:
autoInstallPeers: true
excludeLinksFromLockfile: false
+overrides:
+ uuid@<11.1.1: 11.1.1
+
importers:
.:
@@ -37,7 +40,7 @@ importers:
version: 8.67.0(eslint@10.8.1(supports-color@10.2.2))(supports-color@10.2.2)(typescript@5.9.3)
vitest:
specifier: 4.1.10
- version: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(supports-color@10.2.2))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
+ version: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
apps/collector:
dependencies:
@@ -53,6 +56,12 @@ importers:
apps/dashboard:
dependencies:
+ '@farcaster/miniapp-sdk':
+ specifier: 0.3.0
+ version: 0.3.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)(zod@4.4.3)
+ '@farcaster/quick-auth':
+ specifier: 0.0.8
+ version: 0.0.8(typescript@5.9.3)
'@snapmeter/contracts':
specifier: workspace:*
version: link:../../packages/contracts
@@ -68,13 +77,16 @@ importers:
devDependencies:
'@cloudflare/vite-plugin':
specifier: 1.52.0
- version: 1.52.0(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))(wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1))
+ version: 1.52.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))(wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6))
'@cloudflare/vitest-pool-workers':
specifier: 0.21.2
- version: 0.21.2(@cloudflare/workers-types@5.20260813.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)
+ version: 0.21.2(@cloudflare/workers-types@5.20260813.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(bufferutil@4.1.0)(utf-8-validate@6.0.6)(vitest@4.1.10)
'@cloudflare/workers-types':
specifier: 5.20260813.1
version: 5.20260813.1
+ '@farcaster/miniapp-core':
+ specifier: 0.6.0
+ version: 0.6.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)
'@playwright/test':
specifier: 1.62.1
version: 1.62.1
@@ -101,19 +113,22 @@ importers:
version: 6.0.5(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
jsdom:
specifier: 26.1.0
- version: 26.1.0(supports-color@10.2.2)
+ version: 26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6)
typescript:
specifier: 5.9.3
version: 5.9.3
+ viem:
+ specifier: 2.55.0
+ version: 2.55.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)(zod@4.4.3)
vite:
specifier: 8.2.1
version: 8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12)
vitest:
specifier: 4.1.10
- version: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(supports-color@10.2.2))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
+ version: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
wrangler:
specifier: 4.122.0
- version: 4.122.0(@cloudflare/workers-types@5.20260813.1)
+ version: 4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6)
packages/contracts:
dependencies:
@@ -147,6 +162,9 @@ packages:
'@adobe/css-tools@4.5.0':
resolution: {integrity: sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==}
+ '@adraffy/ens-normalize@1.11.1':
+ resolution: {integrity: sha512-nhCBV3quEgesuf7c7KYfperqSS14T8bYuvJ8PcLJp6znkZpFc0AuW4qBtr8eKVyPPe/8RSr7sglCWPU5eaxwKQ==}
+
'@asamuzakjp/css-color@3.2.0':
resolution: {integrity: sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==}
@@ -625,6 +643,22 @@ packages:
resolution: {integrity: sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+ '@farcaster/miniapp-core@0.6.0':
+ resolution: {integrity: sha512-sgDQdU6fQDXYbNbjuvvwhww1rwf/S0JCnKsp/o2K+ubtboA3SOiy3Wrc+taBnAh56CCxVbZN9Hck3OpYh9wINw==}
+
+ '@farcaster/miniapp-sdk@0.3.0':
+ resolution: {integrity: sha512-mxze24B5SSLwqpPqUmzthfsGGPeevJvDuOEbLJay1DDgPS/B0LswA0XXfz4d6pViA7Y4TkbeAPMAfuVZ9nIqgQ==}
+
+ '@farcaster/quick-auth@0.0.6':
+ resolution: {integrity: sha512-tiZndhpfDtEhaKlkmS5cVDuS+A/tafqZT3y9I44rC69m3beJok6e8dIH2JhxVy3EvOWTyTBnrmNn6GOOh+qK6A==}
+ peerDependencies:
+ typescript: 5.8.3
+
+ '@farcaster/quick-auth@0.0.8':
+ resolution: {integrity: sha512-NRIq1BcbcQCC6xBF5owfckkY00xKQVpqhpLNl5rICVpl0xeDsiVbkenIrHaUuyjtCK2W28YVc2ZCFRyz9ERHKg==}
+ peerDependencies:
+ typescript: 5.8.3
+
'@grpc/grpc-js@1.14.4':
resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}
engines: {node: '>=12.10.0'}
@@ -832,6 +866,22 @@ packages:
'@js-sdsl/ordered-map@4.4.2':
resolution: {integrity: sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==}
+ '@noble/ciphers@1.3.0':
+ resolution: {integrity: sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==}
+ engines: {node: ^14.21.3 || >=16}
+
+ '@noble/curves@1.9.1':
+ resolution: {integrity: sha512-k11yZxZg+t+gWvBbIswW0yoJlu8cHOC7dhunwOzoWH/mXGBiYyR4YY6hAEK/3EUs4UpB8la1RfdRpeGsFHkWsA==}
+ engines: {node: ^14.21.3 || >=16}
+
+ '@noble/curves@1.9.7':
+ resolution: {integrity: sha512-gbKGcRUYIjA3/zCCNaWDciTMFI0dCkvou3TL8Zmy5Nc7sJ47a0jtOeZoTaMxkuqRo9cRhjOdZJXegxYE5FN/xw==}
+ engines: {node: ^14.21.3 || >=16}
+
+ '@noble/hashes@1.8.0':
+ resolution: {integrity: sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==}
+ engines: {node: ^14.21.3 || >=16}
+
'@oxc-project/types@0.143.0':
resolution: {integrity: sha512-u6JZdLBTLotrNC9Vd6vPssINdzcCzleKAH6EJKImQb7GtYvX5keN2dxkoK44stCc4tffE6QQRtZTXVSzsLUlWA==}
@@ -969,16 +1019,54 @@ packages:
'@rolldown/pluginutils@1.0.1':
resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+ '@scure/base@1.2.6':
+ resolution: {integrity: sha512-g/nm5FgUa//MCj1gV09zTJTaM6KBAHqLN907YVQqf7zC49+DcO4B1so4ZX07Ef10Twr6nuqYEH9GEggFXA4Fmg==}
+
+ '@scure/bip32@1.7.0':
+ resolution: {integrity: sha512-E4FFX/N3f4B80AKWp5dP6ow+flD1LQZo/w8UnLGYZO674jS6YnYeepycOOksv+vLPSpgN35wgKgy+ybfTb2SMw==}
+
+ '@scure/bip39@1.6.0':
+ resolution: {integrity: sha512-+lF0BbLiJNwVlev4eKelw1WWLaiKXw7sSl8T6FvBlWkdX+94aGJ4o8XjUdlyhTCjd8c+B3KT3JfS8P0bLRNU6A==}
+
'@sindresorhus/is@7.2.0':
resolution: {integrity: sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==}
engines: {node: '>=18'}
+ '@solana/buffer-layout@4.0.1':
+ resolution: {integrity: sha512-E1ImOIAD1tBZFRdjeM4/pzTiTApC0AOBGwyAMS4fwIodCWArzJ3DWdoh8cKxeFM2fElkxBh2Aqts1BPC373rHA==}
+ engines: {node: '>=5.10'}
+
+ '@solana/codecs-core@2.3.0':
+ resolution: {integrity: sha512-oG+VZzN6YhBHIoSKgS5ESM9VIGzhWjEHEGNPSibiDTxFhsFWxNaz8LbMDPjBUE69r9wmdGLkrQ+wVPbnJcZPvw==}
+ engines: {node: '>=20.18.0'}
+ peerDependencies:
+ typescript: '>=5.3.3'
+
+ '@solana/codecs-numbers@2.3.0':
+ resolution: {integrity: sha512-jFvvwKJKffvG7Iz9dmN51OGB7JBcy2CJ6Xf3NqD/VP90xak66m/Lg48T01u5IQ/hc15mChVHiBm+HHuOFDUrQg==}
+ engines: {node: '>=20.18.0'}
+ peerDependencies:
+ typescript: '>=5.3.3'
+
+ '@solana/errors@2.3.0':
+ resolution: {integrity: sha512-66RI9MAbwYV0UtP7kGcTBVLxJgUxoZGm8Fbc0ah+lGiAw17Gugco6+9GrJCV83VyF2mDWyYnYM9qdI3yjgpnaQ==}
+ engines: {node: '>=20.18.0'}
+ hasBin: true
+ peerDependencies:
+ typescript: '>=5.3.3'
+
+ '@solana/web3.js@1.98.4':
+ resolution: {integrity: sha512-vv9lfnvjUsRiq//+j5pBdXig0IQdtzA0BRZ3bXEP4KaIyF1CcaydWqgyzQgfZMNIsWNWmG+AUHwPy4AHOD6gpw==}
+
'@speed-highlight/core@1.2.24':
resolution: {integrity: sha512-qeW2e1l78afw8VhRPfPQ1Gjj+KU5XFQ/OFV5ti6eTa9bruO7mJyZtA4vw0ofqmA3tKCkROE9xLk3VZoeRc98nw==}
'@standard-schema/spec@1.1.0':
resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+ '@swc/helpers@0.5.23':
+ resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
+
'@testing-library/dom@10.4.1':
resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
engines: {node: '>=18'}
@@ -1014,6 +1102,9 @@ packages:
'@types/chai@5.2.3':
resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+ '@types/connect@3.4.38':
+ resolution: {integrity: sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==}
+
'@types/deep-eql@4.0.2':
resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
@@ -1026,6 +1117,9 @@ packages:
'@types/json-schema@7.0.15':
resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+ '@types/node@12.20.55':
+ resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
+
'@types/node@24.10.13':
resolution: {integrity: sha512-oH72nZRfDv9lADUBSo104Aq7gPHpQZc4BTx38r9xf9pg5LfP6EzSyH2n7qFmmxRQXh7YlUXODcYsg6PuTDSxGg==}
@@ -1037,6 +1131,15 @@ packages:
'@types/react@19.2.18':
resolution: {integrity: sha512-AnzbBERsrLKtk2XSfTbYRLjQPdy116Sty4q+T+Bp3IC4l6jNBvreVPAHmpq9qhXQM7CXZPjLVmGMw9sy+hxQ3w==}
+ '@types/uuid@10.0.0':
+ resolution: {integrity: sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ==}
+
+ '@types/ws@7.4.7':
+ resolution: {integrity: sha512-JQbbmxZTZehdc2iszGKs5oC3NFnjeay7mtAWrdt7qNtAVK0g19muApzAy4bm9byz79xa2ZnO/BOBC2R8RC5Lww==}
+
+ '@types/ws@8.18.1':
+ resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
+
'@typescript-eslint/eslint-plugin@8.67.0':
resolution: {integrity: sha512-Un7Heoyj65NREbKAyIrFxeM143NZpExWmy1Nep4DLeQOeLlTeumPjoNKnBrU5D5moWXbPJgRa5Uwcdu0faVNGQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -1147,6 +1250,28 @@ packages:
'@vitest/utils@4.1.10':
resolution: {integrity: sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==}
+ abitype@1.2.3:
+ resolution: {integrity: sha512-Ofer5QUnuUdTFsBRwARMoWKOH1ND5ehwYhJ3OJ/BQO+StkwQjHw0XyVh4vDttzHB7QOFhPHa/o413PJ82gU/Tg==}
+ peerDependencies:
+ typescript: '>=5.0.4'
+ zod: ^3.22.0 || ^4.0.0
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+ zod:
+ optional: true
+
+ abitype@1.3.0:
+ resolution: {integrity: sha512-fk6Te+bojIFrMvMZrnOO+SxCB+RUksTGOzq/60ZRvs1L+BVzvi2bqt9L3W/17ZLdZsyM1FuYf65P5nlmoiH1Bg==}
+ peerDependencies:
+ typescript: '>=5.0.4'
+ zod: ^3.22.0 || ^4.0.0
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+ zod:
+ optional: true
+
acorn-jsx@5.3.2:
resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
peerDependencies:
@@ -1161,6 +1286,10 @@ packages:
resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
engines: {node: '>= 14'}
+ agentkeepalive@4.6.0:
+ resolution: {integrity: sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ==}
+ engines: {node: '>= 8.0.0'}
+
ajv@6.15.0:
resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
@@ -1194,17 +1323,43 @@ packages:
resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
engines: {node: 18 || 20 || >=22}
+ base-x@3.0.11:
+ resolution: {integrity: sha512-xz7wQ8xDhdyP7tQxwdteLYeFfS68tSMNCZ/Y37WJ4bhGfKPpqEIlmIyueQHqOyoPhE6xNUqjzRr8ra0eF9VRvA==}
+
+ base64-js@1.5.1:
+ resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
+
blake3-wasm@2.1.5:
resolution: {integrity: sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==}
+ bn.js@5.2.5:
+ resolution: {integrity: sha512-Vq886eXykuP5E6HcKSSStP3bJgrE6In5WKxVUvJ8XGpWWYs2xZHWqUwzCtGgEtBcxyd57KBFDPFoUfNzdaHCNg==}
+
+ borsh@0.7.0:
+ resolution: {integrity: sha512-CLCsZGIBCFnPtkNnieW/a8wmreDmfUtjU2m9yHrzPXIlNbqVs0AQrSatSG6vdNYUqdc83tkQi2eHfF98ubzQLA==}
+
brace-expansion@5.0.9:
resolution: {integrity: sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==}
engines: {node: 20 || >=22}
+ bs58@4.0.1:
+ resolution: {integrity: sha512-Ok3Wdf5vOIlBrgCvTq96gBkJw+JUEzdBgyaza5HLtPm7yTHkjRy8+JzNyHF7BHa0bNWOQIp3m5YF0nnFcOIKLw==}
+
+ buffer@6.0.3:
+ resolution: {integrity: sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==}
+
+ bufferutil@4.1.0:
+ resolution: {integrity: sha512-ZMANVnAixE6AWWnPzlW2KpUrxhm9woycYvPOo67jWHyFowASTEd9s+QN1EIMsSDtwhIxN4sWE1jotpuDUIgyIw==}
+ engines: {node: '>=6.14.2'}
+
chai@6.2.2:
resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
engines: {node: '>=18'}
+ chalk@5.6.2:
+ resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+ engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
cjs-module-lexer@1.2.3:
resolution: {integrity: sha512-0TNiGstbQmCFwt4akjjBg5pLRTSyj/PkWQ1ZoO2zntmg9yLqSRxwEa4iCfQLGjqhiqBfOJa7W/E8wfGrTDmlZQ==}
@@ -1219,6 +1374,16 @@ packages:
color-name@1.1.4:
resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+ comlink@4.4.2:
+ resolution: {integrity: sha512-OxGdvBmJuNKSCMO4NTl1L47VRp6xn2wG4F/2hYzB6tiCb709otOxtEYCSvK80PtjODfXXZu8ds+Nw5kVCjqd2g==}
+
+ commander@14.0.3:
+ resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+ engines: {node: '>=20'}
+
+ commander@2.20.3:
+ resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
+
convert-source-map@2.0.0:
resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
@@ -1259,6 +1424,10 @@ packages:
deep-is@0.1.4:
resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+ delay@5.0.0:
+ resolution: {integrity: sha512-ReEBKkIfe4ya47wlPYf/gu5ib6yUG0/Aez0JQZQz94kiWtRQvZIQbTiehsnwHvLSWJnQdhVeqYue7Id1dKr0qw==}
+ engines: {node: '>=10'}
+
dequal@2.0.3:
resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
engines: {node: '>=6'}
@@ -1286,6 +1455,12 @@ packages:
es-module-lexer@2.3.1:
resolution: {integrity: sha512-shc1dbU90Yl/xq1QrC7QRtfcwURZuVRfPhZbDoldJ1cn1gzDvBaBWlv0eFolj5+0znnPJz5TXLxsN77X/12KTA==}
+ es6-promise@4.2.8:
+ resolution: {integrity: sha512-HJDGx5daxeIvxdBxvG2cb9g4tEvwIk3i8+nhX0yGrYmZUzbkdg8QbDevheDB8gd0//uPj4c1EQua8Q+MViT0/w==}
+
+ es6-promisify@5.0.0:
+ resolution: {integrity: sha512-C+d6UdsYDk0lMebHNR4S2NybQMMngAOnOwYBQjTOiv0MkoJMP0Myw2mgpDLBcpfCmRLxyFqYhS/CfOENq4SJhQ==}
+
esbuild@0.28.1:
resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
engines: {node: '>=18'}
@@ -1349,10 +1524,20 @@ packages:
resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
engines: {node: '>=0.10.0'}
+ eventemitter3@5.0.1:
+ resolution: {integrity: sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==}
+
+ eventemitter3@5.0.4:
+ resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
+
expect-type@1.4.0:
resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
engines: {node: '>=12.0.0'}
+ eyes@0.1.8:
+ resolution: {integrity: sha512-GipyPsXO1anza0AOZdy69Im7hGFCNB7Y/NGjDlZGJ3GJJLtwNSb2vrzYrTYJRrRloVx7pl+bhUaTB8yiccPvFQ==}
+ engines: {node: '> 0.1.90'}
+
fast-deep-equal@3.1.3:
resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
@@ -1362,6 +1547,9 @@ packages:
fast-levenshtein@2.0.6:
resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+ fast-stable-stringify@1.0.0:
+ resolution: {integrity: sha512-wpYMUmFu5f00Sm0cj2pfivpmawLZ0NKdviQ4w9zJeR8JVtOpOxHmLaJuj0vxvGqMJQWyP/COUkF75/57OKyRag==}
+
fdir@6.5.0:
resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
engines: {node: '>=12.0.0'}
@@ -1427,10 +1615,16 @@ packages:
resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
engines: {node: '>= 14'}
+ humanize-ms@1.2.1:
+ resolution: {integrity: sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==}
+
iconv-lite@0.6.3:
resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
engines: {node: '>=0.10.0'}
+ ieee754@1.2.1:
+ resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
+
ignore@5.3.2:
resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
engines: {node: '>= 4'}
@@ -1465,6 +1659,16 @@ packages:
isexe@2.0.0:
resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+ isomorphic-ws@4.0.1:
+ resolution: {integrity: sha512-BhBvN2MBpWTaSHdWRb/bwdZJ1WaehQ2L1KngkCkfLUGF0mAWAT1sQUQacEmQ0jXkFw/czDXPNQSL5u2/Krsz1w==}
+ peerDependencies:
+ ws: '*'
+
+ isows@1.0.7:
+ resolution: {integrity: sha512-I1fSfDCZL5P0v33sVqeTDSpcstAg/N+wF5HS033mogOVIp4B+oHC7oOCsA3axAbBSGTJ8QubbNmnIRN/h8U7hg==}
+ peerDependencies:
+ ws: '*'
+
istanbul-lib-coverage@3.2.2:
resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==}
engines: {node: '>=8'}
@@ -1477,6 +1681,14 @@ packages:
resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==}
engines: {node: '>=8'}
+ jayson@4.3.0:
+ resolution: {integrity: sha512-AauzHcUcqs8OBnCHOkJY280VaTiCm57AbuO7lqzcw7JapGj50BisE3xhksye4zlTSR1+1tAz67wLTl8tEH1obQ==}
+ engines: {node: '>=8'}
+ hasBin: true
+
+ jose@5.10.0:
+ resolution: {integrity: sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg==}
+
js-tokens@10.0.0:
resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
@@ -1501,6 +1713,9 @@ packages:
json-stable-stringify-without-jsonify@1.0.1:
resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+ json-stringify-safe@5.0.1:
+ resolution: {integrity: sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==}
+
keyv@4.5.4:
resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
@@ -1636,6 +1851,19 @@ packages:
natural-compare@1.4.0:
resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+ node-fetch@2.7.0:
+ resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+ engines: {node: 4.x || >=6.0.0}
+ peerDependencies:
+ encoding: ^0.1.0
+ peerDependenciesMeta:
+ encoding:
+ optional: true
+
+ node-gyp-build@4.8.4:
+ resolution: {integrity: sha512-LA4ZjwlnUblHVgq0oBF3Jl/6h/Nvs5fzBLwdEF4nuxnFdsfajde4WfxtJr3CaiH+F6ewcIB/q4jQ4UzPyid+CQ==}
+ hasBin: true
+
nwsapi@2.2.24:
resolution: {integrity: sha512-7YRhZ3jS45LwmSCT4b2sVFHt/WuovaktDU07QrtOBY2PXskss5a9jfmR9jptyumwXST+rFjrmppMY1KT/yn35A==}
@@ -1647,6 +1875,22 @@ packages:
resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
engines: {node: '>= 0.8.0'}
+ ox@0.14.30:
+ resolution: {integrity: sha512-LI11uu+8iiM1B3CLckgd++YF1a0A2k5wDoM9ZeQMiL21BOzQs6L//BLS6hb1HSEKCyycdDIQLsVQx9MjpcC0hA==}
+ peerDependencies:
+ typescript: '>=5.4.0'
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+
+ ox@0.14.33:
+ resolution: {integrity: sha512-rooA/4o7bBof4Ge2VH/eovfNPb/AEEYyrNj03wggc55g5HZD8Pjs/OeWhttgjic3dDcqn0r29bDuvQEdTiUemQ==}
+ peerDependencies:
+ typescript: '>=5.4.0'
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+
p-limit@3.1.0:
resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
engines: {node: '>=10'}
@@ -1734,9 +1978,15 @@ packages:
engines: {node: ^20.19.0 || >=22.12.0}
hasBin: true
+ rpc-websockets@9.3.9:
+ resolution: {integrity: sha512-2iQDaTB4g5fDB2ihrTFSJSibCEuxaRi1q7qTW7ZO9/M5/TC+ToHA4D9/ffNLEbAoHNNrcdeP05oATNk44SKZXA==}
+
rrweb-cssom@0.8.0:
resolution: {integrity: sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==}
+ safe-buffer@5.2.1:
+ resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
safer-buffer@2.1.2:
resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
@@ -1777,6 +2027,12 @@ packages:
std-env@4.2.0:
resolution: {integrity: sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==}
+ stream-chain@2.2.5:
+ resolution: {integrity: sha512-1TJmBx6aSWqZ4tx7aTpBDXK0/e2hhcNSTV8+CbFJtDjbb+I1mZ8lHit0Grw9GRT+6JbIrrDd8esncgBi8aBXGA==}
+
+ stream-json@1.9.1:
+ resolution: {integrity: sha512-uWkjJ+2Nt/LO9Z/JyKZbMusL8Dkh97uUBTv3AJQ74y07lVahLY4eEFsPsE97pxYBwr8nnjMAIch5eqI0gPShyw==}
+
string-width@4.2.3:
resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
engines: {node: '>=8'}
@@ -1789,6 +2045,10 @@ packages:
resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==}
engines: {node: '>=8'}
+ superstruct@2.0.2:
+ resolution: {integrity: sha512-uV+TFRZdXsqXTL2pRvujROjdZQ4RAlBUS5BTh9IGm+jTqQntYThciG/qu57Gs69yjnVUSqdxF9YLmSnpupBW9A==}
+ engines: {node: '>=14.0.0'}
+
supports-color@10.2.2:
resolution: {integrity: sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==}
engines: {node: '>=18'}
@@ -1800,6 +2060,9 @@ packages:
symbol-tree@3.2.4:
resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
+ text-encoding-utf-8@1.0.2:
+ resolution: {integrity: sha512-8bw4MY9WjdsD2aMtO0OzOCY3pXGYNx2d2FfHRVUKkiCPDWjKuOlhLVASS+pD7VkLTVjW268LYJHwsnPFlBpbAg==}
+
tinybench@2.9.0:
resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
@@ -1826,6 +2089,9 @@ packages:
resolution: {integrity: sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A==}
engines: {node: '>=16'}
+ tr46@0.0.3:
+ resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
tr46@5.1.1:
resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
engines: {node: '>=18'}
@@ -1873,6 +2139,26 @@ packages:
uri-js@4.4.1:
resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+ utf-8-validate@6.0.6:
+ resolution: {integrity: sha512-q3l3P9UtEEiAHcsgsqTgf9PPjctrDWoIXW3NpOHFdRDbLvu4DLIcxHangJ4RLrWkBcKjmcs/6NkerI8T/rE4LA==}
+ engines: {node: '>=6.14.2'}
+
+ uuid@11.1.1:
+ resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==}
+ hasBin: true
+
+ uuid@14.0.1:
+ resolution: {integrity: sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==}
+ hasBin: true
+
+ viem@2.55.0:
+ resolution: {integrity: sha512-5XWSTCTmNvHCeT38Fsp31uofmOZFJdj4nOUH+H2Vh/hzsx9M7r+KgL3fSYUZeVn4H0UyQxjwPFqEaV4M0CI1tA==}
+ peerDependencies:
+ typescript: '>=5.0.4'
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+
vite@8.2.1:
resolution: {integrity: sha512-EU/eS7BH3XROHh2YnBefjM6DBKA6ZeMZEYQbj7NLWg5wHYlhB8B/Mayd5XsgWq+NFYccDOTemRpdETWR6Ka/lw==}
engines: {node: ^20.19.0 || >=22.12.0}
@@ -1961,6 +2247,9 @@ packages:
resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
engines: {node: '>=18'}
+ webidl-conversions@3.0.1:
+ resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
webidl-conversions@7.0.0:
resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
engines: {node: '>=12'}
@@ -1978,6 +2267,9 @@ packages:
resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
engines: {node: '>=18'}
+ whatwg-url@5.0.0:
+ resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
which@2.0.2:
resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
engines: {node: '>= 8'}
@@ -2011,6 +2303,18 @@ packages:
resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
engines: {node: '>=10'}
+ ws@7.5.13:
+ resolution: {integrity: sha512-rsKI6xDBFVf4r/x8XyChGK04QR/XHroxs/jUcoWvtEZM8TPU/X/uIY9B1CsSzYws9ZJb/6bbBu7dPhFW00CAoA==}
+ engines: {node: '>=8.3.0'}
+ peerDependencies:
+ bufferutil: ^4.0.1
+ utf-8-validate: ^5.0.2
+ peerDependenciesMeta:
+ bufferutil:
+ optional: true
+ utf-8-validate:
+ optional: true
+
ws@8.21.0:
resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==}
engines: {node: '>=10.0.0'}
@@ -2064,6 +2368,9 @@ packages:
youch@4.1.0-beta.10:
resolution: {integrity: sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==}
+ zod@3.25.76:
+ resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
zod@4.4.3:
resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
@@ -2071,6 +2378,8 @@ snapshots:
'@adobe/css-tools@4.5.0': {}
+ '@adraffy/ens-normalize@1.11.1': {}
+
'@asamuzakjp/css-color@3.2.0':
dependencies:
'@csstools/css-calc': 2.1.4(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)
@@ -2110,28 +2419,28 @@ snapshots:
optionalDependencies:
workerd: 1.20260811.1
- '@cloudflare/vite-plugin@1.52.0(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))(wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1))':
+ '@cloudflare/vite-plugin@1.52.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))(wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6))':
dependencies:
'@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260811.1)
- miniflare: 5.20260811.0-alpha
+ miniflare: 5.20260811.0-alpha(bufferutil@4.1.0)(utf-8-validate@6.0.6)
unenv: 2.0.0-rc.24
vite: 8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12)
workerd: 1.20260811.1
- wrangler: 4.122.0(@cloudflare/workers-types@5.20260813.1)
- ws: 8.21.0
+ wrangler: 4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
transitivePeerDependencies:
- bufferutil
- utf-8-validate
- '@cloudflare/vitest-pool-workers@0.21.2(@cloudflare/workers-types@5.20260813.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)':
+ '@cloudflare/vitest-pool-workers@0.21.2(@cloudflare/workers-types@5.20260813.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(bufferutil@4.1.0)(utf-8-validate@6.0.6)(vitest@4.1.10)':
dependencies:
'@vitest/runner': 4.1.10
'@vitest/snapshot': 4.1.10
cjs-module-lexer: 1.2.3
esbuild: 0.28.1
- miniflare: 5.20260811.0-alpha
- vitest: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(supports-color@10.2.2))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
- wrangler: 4.122.0(@cloudflare/workers-types@5.20260813.1)
+ miniflare: 5.20260811.0-alpha(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ vitest: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
+ wrangler: 4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6)
zod: 4.4.3
transitivePeerDependencies:
- '@cloudflare/workers-types'
@@ -2374,6 +2683,43 @@ snapshots:
'@eslint/core': 1.2.1
levn: 0.4.1
+ '@farcaster/miniapp-core@0.6.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)':
+ dependencies:
+ '@solana/web3.js': 1.98.4(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)
+ ox: 0.14.33(typescript@5.9.3)(zod@4.4.3)
+ zod: 4.4.3
+ transitivePeerDependencies:
+ - bufferutil
+ - encoding
+ - typescript
+ - utf-8-validate
+
+ '@farcaster/miniapp-sdk@0.3.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)(zod@4.4.3)':
+ dependencies:
+ '@farcaster/miniapp-core': 0.6.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)
+ '@farcaster/quick-auth': 0.0.6(typescript@5.9.3)
+ comlink: 4.4.2
+ eventemitter3: 5.0.4
+ ox: 0.14.33(typescript@5.9.3)(zod@4.4.3)
+ transitivePeerDependencies:
+ - bufferutil
+ - encoding
+ - typescript
+ - utf-8-validate
+ - zod
+
+ '@farcaster/quick-auth@0.0.6(typescript@5.9.3)':
+ dependencies:
+ jose: 5.10.0
+ typescript: 5.9.3
+ zod: 3.25.76
+
+ '@farcaster/quick-auth@0.0.8(typescript@5.9.3)':
+ dependencies:
+ jose: 5.10.0
+ typescript: 5.9.3
+ zod: 3.25.76
+
'@grpc/grpc-js@1.14.4':
dependencies:
'@grpc/proto-loader': 0.8.1
@@ -2524,6 +2870,18 @@ snapshots:
'@js-sdsl/ordered-map@4.4.2': {}
+ '@noble/ciphers@1.3.0': {}
+
+ '@noble/curves@1.9.1':
+ dependencies:
+ '@noble/hashes': 1.8.0
+
+ '@noble/curves@1.9.7':
+ dependencies:
+ '@noble/hashes': 1.8.0
+
+ '@noble/hashes@1.8.0': {}
+
'@oxc-project/types@0.143.0': {}
'@playwright/test@1.62.1':
@@ -2606,12 +2964,73 @@ snapshots:
'@rolldown/pluginutils@1.0.1': {}
+ '@scure/base@1.2.6': {}
+
+ '@scure/bip32@1.7.0':
+ dependencies:
+ '@noble/curves': 1.9.7
+ '@noble/hashes': 1.8.0
+ '@scure/base': 1.2.6
+
+ '@scure/bip39@1.6.0':
+ dependencies:
+ '@noble/hashes': 1.8.0
+ '@scure/base': 1.2.6
+
'@sindresorhus/is@7.2.0': {}
+ '@solana/buffer-layout@4.0.1':
+ dependencies:
+ buffer: 6.0.3
+
+ '@solana/codecs-core@2.3.0(typescript@5.9.3)':
+ dependencies:
+ '@solana/errors': 2.3.0(typescript@5.9.3)
+ typescript: 5.9.3
+
+ '@solana/codecs-numbers@2.3.0(typescript@5.9.3)':
+ dependencies:
+ '@solana/codecs-core': 2.3.0(typescript@5.9.3)
+ '@solana/errors': 2.3.0(typescript@5.9.3)
+ typescript: 5.9.3
+
+ '@solana/errors@2.3.0(typescript@5.9.3)':
+ dependencies:
+ chalk: 5.6.2
+ commander: 14.0.3
+ typescript: 5.9.3
+
+ '@solana/web3.js@1.98.4(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)':
+ dependencies:
+ '@babel/runtime': 7.29.7
+ '@noble/curves': 1.9.7
+ '@noble/hashes': 1.8.0
+ '@solana/buffer-layout': 4.0.1
+ '@solana/codecs-numbers': 2.3.0(typescript@5.9.3)
+ agentkeepalive: 4.6.0
+ bn.js: 5.2.5
+ borsh: 0.7.0
+ bs58: 4.0.1
+ buffer: 6.0.3
+ fast-stable-stringify: 1.0.0
+ jayson: 4.3.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ node-fetch: 2.7.0
+ rpc-websockets: 9.3.9
+ superstruct: 2.0.2
+ transitivePeerDependencies:
+ - bufferutil
+ - encoding
+ - typescript
+ - utf-8-validate
+
'@speed-highlight/core@1.2.24': {}
'@standard-schema/spec@1.1.0': {}
+ '@swc/helpers@0.5.23':
+ dependencies:
+ tslib: 2.8.1
+
'@testing-library/dom@10.4.1':
dependencies:
'@babel/code-frame': 7.29.7
@@ -2653,6 +3072,10 @@ snapshots:
'@types/deep-eql': 4.0.2
assertion-error: 2.0.1
+ '@types/connect@3.4.38':
+ dependencies:
+ '@types/node': 24.10.13
+
'@types/deep-eql@4.0.2': {}
'@types/esrecurse@4.3.1': {}
@@ -2661,6 +3084,8 @@ snapshots:
'@types/json-schema@7.0.15': {}
+ '@types/node@12.20.55': {}
+
'@types/node@24.10.13':
dependencies:
undici-types: 7.16.0
@@ -2673,6 +3098,16 @@ snapshots:
dependencies:
csstype: 3.2.3
+ '@types/uuid@10.0.0': {}
+
+ '@types/ws@7.4.7':
+ dependencies:
+ '@types/node': 24.10.13
+
+ '@types/ws@8.18.1':
+ dependencies:
+ '@types/node': 24.10.13
+
'@typescript-eslint/eslint-plugin@8.67.0(@typescript-eslint/parser@8.67.0(eslint@10.8.1(supports-color@10.2.2))(supports-color@10.2.2)(typescript@5.9.3))(eslint@10.8.1(supports-color@10.2.2))(supports-color@10.2.2)(typescript@5.9.3)':
dependencies:
'@eslint-community/regexpp': 4.12.2
@@ -2781,7 +3216,7 @@ snapshots:
obug: 2.1.4
std-env: 4.2.0
tinyrainbow: 3.1.1
- vitest: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(supports-color@10.2.2))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
+ vitest: 4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
'@vitest/expect@4.1.10':
dependencies:
@@ -2824,6 +3259,16 @@ snapshots:
convert-source-map: 2.0.0
tinyrainbow: 3.1.1
+ abitype@1.2.3(typescript@5.9.3)(zod@4.4.3):
+ optionalDependencies:
+ typescript: 5.9.3
+ zod: 4.4.3
+
+ abitype@1.3.0(typescript@5.9.3)(zod@4.4.3):
+ optionalDependencies:
+ typescript: 5.9.3
+ zod: 4.4.3
+
acorn-jsx@5.3.2(acorn@8.18.0):
dependencies:
acorn: 8.18.0
@@ -2832,6 +3277,10 @@ snapshots:
agent-base@7.1.4: {}
+ agentkeepalive@4.6.0:
+ dependencies:
+ humanize-ms: 1.2.1
+
ajv@6.15.0:
dependencies:
fast-deep-equal: 3.1.3
@@ -2863,14 +3312,44 @@ snapshots:
balanced-match@4.0.4: {}
+ base-x@3.0.11:
+ dependencies:
+ safe-buffer: 5.2.1
+
+ base64-js@1.5.1: {}
+
blake3-wasm@2.1.5: {}
+ bn.js@5.2.5: {}
+
+ borsh@0.7.0:
+ dependencies:
+ bn.js: 5.2.5
+ bs58: 4.0.1
+ text-encoding-utf-8: 1.0.2
+
brace-expansion@5.0.9:
dependencies:
balanced-match: 4.0.4
+ bs58@4.0.1:
+ dependencies:
+ base-x: 3.0.11
+
+ buffer@6.0.3:
+ dependencies:
+ base64-js: 1.5.1
+ ieee754: 1.2.1
+
+ bufferutil@4.1.0:
+ dependencies:
+ node-gyp-build: 4.8.4
+ optional: true
+
chai@6.2.2: {}
+ chalk@5.6.2: {}
+
cjs-module-lexer@1.2.3: {}
cliui@8.0.1:
@@ -2885,6 +3364,12 @@ snapshots:
color-name@1.1.4: {}
+ comlink@4.4.2: {}
+
+ commander@14.0.3: {}
+
+ commander@2.20.3: {}
+
convert-source-map@2.0.0: {}
cookie@1.1.1: {}
@@ -2919,6 +3404,8 @@ snapshots:
deep-is@0.1.4: {}
+ delay@5.0.0: {}
+
dequal@2.0.3: {}
detect-libc@2.1.2: {}
@@ -2935,6 +3422,12 @@ snapshots:
es-module-lexer@2.3.1: {}
+ es6-promise@4.2.8: {}
+
+ es6-promisify@5.0.0:
+ dependencies:
+ es6-promise: 4.2.8
+
esbuild@0.28.1:
optionalDependencies:
'@esbuild/aix-ppc64': 0.28.1
@@ -3065,14 +3558,22 @@ snapshots:
esutils@2.0.3: {}
+ eventemitter3@5.0.1: {}
+
+ eventemitter3@5.0.4: {}
+
expect-type@1.4.0: {}
+ eyes@0.1.8: {}
+
fast-deep-equal@3.1.3: {}
fast-json-stable-stringify@2.1.0: {}
fast-levenshtein@2.0.6: {}
+ fast-stable-stringify@1.0.0: {}
+
fdir@6.5.0(picomatch@4.0.5):
optionalDependencies:
picomatch: 4.0.5
@@ -3129,10 +3630,16 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ humanize-ms@1.2.1:
+ dependencies:
+ ms: 2.1.3
+
iconv-lite@0.6.3:
dependencies:
safer-buffer: 2.1.2
+ ieee754@1.2.1: {}
+
ignore@5.3.2: {}
ignore@7.0.6: {}
@@ -3153,6 +3660,14 @@ snapshots:
isexe@2.0.0: {}
+ isomorphic-ws@4.0.1(ws@7.5.13(bufferutil@4.1.0)(utf-8-validate@6.0.6)):
+ dependencies:
+ ws: 7.5.13(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+
+ isows@1.0.7(ws@8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)):
+ dependencies:
+ ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+
istanbul-lib-coverage@3.2.2: {}
istanbul-lib-report@3.0.1:
@@ -3166,11 +3681,31 @@ snapshots:
html-escaper: 2.0.2
istanbul-lib-report: 3.0.1
+ jayson@4.3.0(bufferutil@4.1.0)(utf-8-validate@6.0.6):
+ dependencies:
+ '@types/connect': 3.4.38
+ '@types/node': 12.20.55
+ '@types/ws': 7.4.7
+ commander: 2.20.3
+ delay: 5.0.0
+ es6-promisify: 5.0.0
+ eyes: 0.1.8
+ isomorphic-ws: 4.0.1(ws@7.5.13(bufferutil@4.1.0)(utf-8-validate@6.0.6))
+ json-stringify-safe: 5.0.1
+ stream-json: 1.9.1
+ uuid: 11.1.1
+ ws: 7.5.13(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ transitivePeerDependencies:
+ - bufferutil
+ - utf-8-validate
+
+ jose@5.10.0: {}
+
js-tokens@10.0.0: {}
js-tokens@4.0.0: {}
- jsdom@26.1.0(supports-color@10.2.2):
+ jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6):
dependencies:
cssstyle: 4.6.0
data-urls: 5.0.0
@@ -3190,7 +3725,7 @@ snapshots:
whatwg-encoding: 3.1.1
whatwg-mimetype: 4.0.0
whatwg-url: 14.2.0
- ws: 8.21.3
+ ws: 8.21.3(bufferutil@4.1.0)(utf-8-validate@6.0.6)
xml-name-validator: 5.0.0
transitivePeerDependencies:
- bufferutil
@@ -3203,6 +3738,8 @@ snapshots:
json-stable-stringify-without-jsonify@1.0.1: {}
+ json-stringify-safe@5.0.1: {}
+
keyv@4.5.4:
dependencies:
json-buffer: 3.0.1
@@ -3291,13 +3828,13 @@ snapshots:
min-indent@1.0.1: {}
- miniflare@5.20260811.0-alpha:
+ miniflare@5.20260811.0-alpha(bufferutil@4.1.0)(utf-8-validate@6.0.6):
dependencies:
'@cspotcode/source-map-support': 0.8.1
sharp: 0.35.2
undici: 7.29.0
workerd: 1.20260811.1
- ws: 8.21.0
+ ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
youch: 4.1.0-beta.10
transitivePeerDependencies:
- bufferutil
@@ -3313,6 +3850,13 @@ snapshots:
natural-compare@1.4.0: {}
+ node-fetch@2.7.0:
+ dependencies:
+ whatwg-url: 5.0.0
+
+ node-gyp-build@4.8.4:
+ optional: true
+
nwsapi@2.2.24: {}
obug@2.1.4: {}
@@ -3326,6 +3870,36 @@ snapshots:
type-check: 0.4.0
word-wrap: 1.2.5
+ ox@0.14.30(typescript@5.9.3)(zod@4.4.3):
+ dependencies:
+ '@adraffy/ens-normalize': 1.11.1
+ '@noble/ciphers': 1.3.0
+ '@noble/curves': 1.9.1
+ '@noble/hashes': 1.8.0
+ '@scure/bip32': 1.7.0
+ '@scure/bip39': 1.6.0
+ abitype: 1.3.0(typescript@5.9.3)(zod@4.4.3)
+ eventemitter3: 5.0.1
+ optionalDependencies:
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - zod
+
+ ox@0.14.33(typescript@5.9.3)(zod@4.4.3):
+ dependencies:
+ '@adraffy/ens-normalize': 1.11.1
+ '@noble/ciphers': 1.3.0
+ '@noble/curves': 1.9.1
+ '@noble/hashes': 1.8.0
+ '@scure/bip32': 1.7.0
+ '@scure/bip39': 1.6.0
+ abitype: 1.3.0(typescript@5.9.3)(zod@4.4.3)
+ eventemitter3: 5.0.1
+ optionalDependencies:
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - zod
+
p-limit@3.1.0:
dependencies:
yocto-queue: 0.1.0
@@ -3424,8 +3998,23 @@ snapshots:
'@rolldown/binding-win32-arm64-msvc': 1.2.3
'@rolldown/binding-win32-x64-msvc': 1.2.3
+ rpc-websockets@9.3.9:
+ dependencies:
+ '@swc/helpers': 0.5.23
+ '@types/uuid': 10.0.0
+ '@types/ws': 8.18.1
+ buffer: 6.0.3
+ eventemitter3: 5.0.4
+ uuid: 14.0.1
+ ws: 8.21.3(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ optionalDependencies:
+ bufferutil: 4.1.0
+ utf-8-validate: 6.0.6
+
rrweb-cssom@0.8.0: {}
+ safe-buffer@5.2.1: {}
+
safer-buffer@2.1.2: {}
saxes@6.0.0:
@@ -3482,6 +4071,12 @@ snapshots:
std-env@4.2.0: {}
+ stream-chain@2.2.5: {}
+
+ stream-json@1.9.1:
+ dependencies:
+ stream-chain: 2.2.5
+
string-width@4.2.3:
dependencies:
emoji-regex: 8.0.0
@@ -3496,6 +4091,8 @@ snapshots:
dependencies:
min-indent: 1.0.1
+ superstruct@2.0.2: {}
+
supports-color@10.2.2: {}
supports-color@7.2.0:
@@ -3504,6 +4101,8 @@ snapshots:
symbol-tree@3.2.4: {}
+ text-encoding-utf-8@1.0.2: {}
+
tinybench@2.9.0: {}
tinyexec@1.3.0: {}
@@ -3525,6 +4124,8 @@ snapshots:
dependencies:
tldts: 6.1.86
+ tr46@0.0.3: {}
+
tr46@5.1.1:
dependencies:
punycode: 2.3.1
@@ -3533,8 +4134,7 @@ snapshots:
dependencies:
typescript: 5.9.3
- tslib@2.8.1:
- optional: true
+ tslib@2.8.1: {}
tsx@4.23.12:
dependencies:
@@ -3571,6 +4171,32 @@ snapshots:
dependencies:
punycode: 2.3.1
+ utf-8-validate@6.0.6:
+ dependencies:
+ node-gyp-build: 4.8.4
+ optional: true
+
+ uuid@11.1.1: {}
+
+ uuid@14.0.1: {}
+
+ viem@2.55.0(bufferutil@4.1.0)(typescript@5.9.3)(utf-8-validate@6.0.6)(zod@4.4.3):
+ dependencies:
+ '@noble/curves': 1.9.1
+ '@noble/hashes': 1.8.0
+ '@scure/bip32': 1.7.0
+ '@scure/bip39': 1.6.0
+ abitype: 1.2.3(typescript@5.9.3)(zod@4.4.3)
+ isows: 1.0.7(ws@8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))
+ ox: 0.14.30(typescript@5.9.3)(zod@4.4.3)
+ ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+ optionalDependencies:
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - bufferutil
+ - utf-8-validate
+ - zod
+
vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12):
dependencies:
lightningcss: 1.33.0
@@ -3584,7 +4210,7 @@ snapshots:
fsevents: 2.3.3
tsx: 4.23.12
- vitest@4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(supports-color@10.2.2))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12)):
+ vitest@4.1.10(@types/node@24.10.13)(@vitest/coverage-v8@4.1.10)(jsdom@26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6))(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12)):
dependencies:
'@vitest/expect': 4.1.10
'@vitest/mocker': 4.1.10(vite@8.2.1(@types/node@24.10.13)(esbuild@0.28.2)(tsx@4.23.12))
@@ -3609,7 +4235,7 @@ snapshots:
optionalDependencies:
'@types/node': 24.10.13
'@vitest/coverage-v8': 4.1.10(vitest@4.1.10)
- jsdom: 26.1.0(supports-color@10.2.2)
+ jsdom: 26.1.0(bufferutil@4.1.0)(supports-color@10.2.2)(utf-8-validate@6.0.6)
transitivePeerDependencies:
- msw
@@ -3617,6 +4243,8 @@ snapshots:
dependencies:
xml-name-validator: 5.0.0
+ webidl-conversions@3.0.1: {}
+
webidl-conversions@7.0.0: {}
whatwg-encoding@3.1.1:
@@ -3630,6 +4258,11 @@ snapshots:
tr46: 5.1.1
webidl-conversions: 7.0.0
+ whatwg-url@5.0.0:
+ dependencies:
+ tr46: 0.0.3
+ webidl-conversions: 3.0.1
+
which@2.0.2:
dependencies:
isexe: 2.0.0
@@ -3649,13 +4282,13 @@ snapshots:
'@cloudflare/workerd-linux-arm64': 1.20260811.1
'@cloudflare/workerd-windows-64': 1.20260811.1
- wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1):
+ wrangler@4.122.0(@cloudflare/workers-types@5.20260813.1)(bufferutil@4.1.0)(utf-8-validate@6.0.6):
dependencies:
'@cloudflare/kv-asset-handler': 0.5.0
'@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260811.1)
blake3-wasm: 2.1.5
esbuild: 0.28.1
- miniflare: 5.20260811.0-alpha
+ miniflare: 5.20260811.0-alpha(bufferutil@4.1.0)(utf-8-validate@6.0.6)
path-to-regexp: 6.3.0
unenv: 2.0.0-rc.24
workerd: 1.20260811.1
@@ -3672,9 +4305,20 @@ snapshots:
string-width: 4.2.3
strip-ansi: 6.0.1
- ws@8.21.0: {}
+ ws@7.5.13(bufferutil@4.1.0)(utf-8-validate@6.0.6):
+ optionalDependencies:
+ bufferutil: 4.1.0
+ utf-8-validate: 6.0.6
+
+ ws@8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6):
+ optionalDependencies:
+ bufferutil: 4.1.0
+ utf-8-validate: 6.0.6
- ws@8.21.3: {}
+ ws@8.21.3(bufferutil@4.1.0)(utf-8-validate@6.0.6):
+ optionalDependencies:
+ bufferutil: 4.1.0
+ utf-8-validate: 6.0.6
xml-name-validator@5.0.0: {}
@@ -3709,4 +4353,6 @@ snapshots:
cookie: 1.1.1
youch-core: 0.3.3
+ zod@3.25.76: {}
+
zod@4.4.3: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 28cae45..e710e07 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -2,9 +2,14 @@ packages:
- apps/*
- packages/*
+overrides:
+ uuid@<11.1.1: 11.1.1
+
allowBuilds:
+ bufferutil: false
esbuild: true
protobufjs: true
+ utf-8-validate: false
workerd: true
minimumReleaseAgeExclude:
diff --git a/scripts/SnapMeter.Common.psm1 b/scripts/SnapMeter.Common.psm1
index 6c52014..b22a329 100644
--- a/scripts/SnapMeter.Common.psm1
+++ b/scripts/SnapMeter.Common.psm1
@@ -34,6 +34,22 @@ function Import-SnapMeterEnvironment {
param([Parameter(Mandatory = $true)][string]$Path)
$envPath = Resolve-SnapMeterPath -Path $Path -MustExist
+ if ([Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT) {
+ $acl = Get-Acl -LiteralPath $envPath
+ $unsafeRules = @($acl.Access | Where-Object {
+ $_.AccessControlType -eq [System.Security.AccessControl.AccessControlType]::Allow -and
+ $_.IdentityReference.Value -match '(?i)(?:^|\\)(Everyone|Users|Authenticated Users)$' -and
+ ($_.FileSystemRights -band (
+ [System.Security.AccessControl.FileSystemRights]::Read -bor
+ [System.Security.AccessControl.FileSystemRights]::ReadData -bor
+ [System.Security.AccessControl.FileSystemRights]::ReadAndExecute -bor
+ [System.Security.AccessControl.FileSystemRights]::FullControl
+ )) -ne 0
+ })
+ if ($unsafeRules.Count -gt 0) {
+ throw "Environment file permissions are too broad: $envPath. Restrict read access to the collector account and administrators."
+ }
+ }
$loadedNames = [System.Collections.Generic.List[string]]::new()
foreach ($rawLine in [System.IO.File]::ReadAllLines($envPath)) {
@@ -73,7 +89,7 @@ function Import-SnapMeterEnvironment {
function Get-SnapMeterEndpoint {
param([Parameter(Mandatory = $true)][string]$Value)
- $match = [regex]::Match($Value.Trim(), '^(?:\[(?[^\]]+)\]|(?[^:/\s]+)):(?[0-9]{1,5})$')
+ $match = [regex]::Match($Value.Trim(), '^(?:\[(?[^\]\s]+)\]|(?[^:/\\@?#\s]+)):(?[0-9]{1,5})$')
if (-not $match.Success) {
throw 'gRPC endpoint must be host:port without a URL scheme or credentials.'
}
@@ -160,6 +176,13 @@ function Test-SnapMeterConfiguration {
throw 'HYPERSNAP_SOURCE_MODE cannot be verified with the currently pinned upstream source; use derived or unavailable.'
}
+ foreach ($name in @('SNAPMETER_INGEST_SECRET', 'SNAPCHAIN_GRPC_AUTHORIZATION', 'HYPERSNAP_GRPC_AUTHORIZATION', 'SNAPCHAIN_GRPC_API_KEY', 'HYPERSNAP_GRPC_API_KEY')) {
+ $value = [Environment]::GetEnvironmentVariable($name, 'Process')
+ if (-not [string]::IsNullOrEmpty($value) -and ($value.Length -gt 8192 -or $value -match '[\x00-\x1F\x7F]')) {
+ throw "$name contains unsupported control characters or is too long."
+ }
+ }
+
if ($RequireCloud) {
if ([string]::IsNullOrWhiteSpace($env:SNAPMETER_INGEST_URL)) {
throw 'SNAPMETER_INGEST_URL is required for continuous cloud delivery.'
@@ -228,14 +251,14 @@ function Protect-SnapMeterText {
$text = if ($null -eq $InputObject) { '' } else { [string]$InputObject }
foreach ($entry in Get-ChildItem Env:) {
- if ($entry.Name -match '(?i)(secret|token|password|authorization|signature|cookie)' -and
+ if ($entry.Name -match '(?i)(api[_-]?key|secret|token|password|authorization|signature|cookie)' -and
-not [string]::IsNullOrWhiteSpace($entry.Value)) {
$text = $text.Replace([string]$entry.Value, '[REDACTED]')
}
}
$text = [regex]::Replace(
$text,
- '(?i)\b(authorization|secret|token|password|signature|cookie)\b\s*[:=]\s*([^\s,;]+)',
+ '(?i)\b(api[_-]?key|authorization|secret|token|password|signature|cookie)\b\s*[:=]\s*([^\s,;]+)',
'$1=[REDACTED]'
)
return $text
diff --git a/scripts/check-publication-safety.mjs b/scripts/check-publication-safety.mjs
new file mode 100644
index 0000000..de08a98
--- /dev/null
+++ b/scripts/check-publication-safety.mjs
@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import process from "node:process";
+
+const MAX_TEXT_BYTES = 10 * 1024 * 1024;
+const allowedEnvironmentFiles = new Set([".env.example"]);
+const forbiddenDirectories = new Set([
+ ".wrangler",
+ "blob-report",
+ "coverage",
+ "dist",
+ "node_modules",
+ "playwright-report",
+ "test-results",
+ "work"
+]);
+const forbiddenExtensions = new Set([
+ ".db",
+ ".key",
+ ".log",
+ ".p12",
+ ".pem",
+ ".pfx",
+ ".sqlite",
+ ".sqlite3"
+]);
+
+const secretPatterns = [
+ ["private key", /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/u],
+ ["GitHub token", /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/u],
+ ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/u],
+ ["Google API key", /\bAIza[0-9A-Za-z_-]{30,}\b/u],
+ ["Stripe live secret", /\bsk_live_[0-9A-Za-z]{16,}\b/u],
+ ["credential-bearing URL", /https?:\/\/[^\s/:]+:[^\s/@]+@/iu]
+];
+
+function trackedFiles() {
+ const raw = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "utf8" });
+ return raw.split("\0").filter(Boolean);
+}
+
+function pathViolation(path) {
+ const normalized = path.replaceAll("\\", "/");
+ const parts = normalized.split("/");
+ if (parts.some((part) => forbiddenDirectories.has(part))) return "generated/runtime directory";
+
+ const name = basename(normalized).toLowerCase();
+ if ((name === ".env" || name.startsWith(".env.") || name.startsWith(".dev.vars") || name === ".collector.env")
+ && !allowedEnvironmentFiles.has(name)) {
+ return "environment or secret file";
+ }
+
+ const extension = extname(name);
+ if (forbiddenExtensions.has(extension) || /\.(?:db|sqlite|sqlite3)-(?:journal|shm|wal)$/u.test(name)) {
+ return "credential, database, or log extension";
+ }
+ return null;
+}
+
+const violations = [];
+for (const path of trackedFiles()) {
+ const pathProblem = pathViolation(path);
+ if (pathProblem) violations.push(`${path}: ${pathProblem}`);
+
+ let stats;
+ try {
+ stats = statSync(path);
+ } catch {
+ violations.push(`${path}: tracked path is missing from the working tree`);
+ continue;
+ }
+ if (!stats.isFile() || stats.size > MAX_TEXT_BYTES) continue;
+
+ const bytes = readFileSync(path);
+ if (bytes.includes(0)) continue;
+ const text = bytes.toString("utf8").replaceAll(
+ "https://user:password@example.test/",
+ "https://example.test/"
+ );
+ for (const [label, pattern] of secretPatterns) {
+ if (pattern.test(text)) violations.push(`${path}: possible ${label}`);
+ }
+}
+
+if (violations.length > 0) {
+ process.stderr.write("Publication safety check failed:\n");
+ for (const violation of violations) process.stderr.write(`- ${violation}\n`);
+ process.exitCode = 1;
+} else {
+ process.stdout.write("Publication safety check passed: tracked paths and high-confidence secret patterns are clean.\n");
+}
diff --git a/scripts/run-collector.ps1 b/scripts/run-collector.ps1
index 9550c06..9bd8a9c 100644
--- a/scripts/run-collector.ps1
+++ b/scripts/run-collector.ps1
@@ -75,12 +75,22 @@ Write-Host $headerLine
$nativeExitCode = 1
Push-Location $repositoryRoot
try {
- & $resolvedPnpm collector $Mode 2>&1 | ForEach-Object {
- $line = Protect-SnapMeterText -InputObject $_
- Add-Content -LiteralPath $logPath -Value $line
- Write-Output $line
+ $savedErrorActionPreference = $ErrorActionPreference
+ try {
+ # Windows PowerShell wraps a native application's stderr as a
+ # non-terminating ErrorRecord. Do not let a harmless pnpm banner abort
+ # the log reader and orphan its long-running child process.
+ $ErrorActionPreference = 'Continue'
+ # pnpm buffers recursive package output unless streaming is explicit.
+ & $resolvedPnpm --stream collector $Mode 2>&1 | ForEach-Object {
+ $line = Protect-SnapMeterText -InputObject $_
+ Add-Content -LiteralPath $logPath -Value $line
+ Write-Output $line
+ }
+ $nativeExitCode = $LASTEXITCODE
+ } finally {
+ $ErrorActionPreference = $savedErrorActionPreference
}
- $nativeExitCode = $LASTEXITCODE
} finally {
Pop-Location
}
diff --git a/vitest.config.ts b/vitest.config.ts
index f01929c..e6a44ac 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,6 +3,8 @@ import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
include: ["packages/**/*.test.ts", "apps/collector/src/**/*.test.ts"],
+ maxWorkers: 4,
+ testTimeout: 15_000,
coverage: {
provider: "v8",
reporter: ["text", "json-summary"],