fix jfs and request formats

Author: lyoshenka

AGENTS.md

@@ -18,7 +18,7 @@
 - The `pkgs/ui-elements` workspace package (`@farcaster/snap-ui-elements`) defines the json-render catalog; the emulator depends on it to render snaps.
 - Local dev ports: emulator on 3000, `snap-template` on 3003; example apps under `examples/` use ports 3010 and higher with a distinct port per app.
 - For snap HTTP GET, send `Accept: application/json+farcaster-snap`; example servers typically expose JSON on `/snap`, not on bare `/`.
-- For local POST in `snap-template`, set `BYPASS_SIGNATURE_VERIFICATION=1` to skip hub signature verification (also accepts `true`/`yes`).
+- Local `registerSnapHandler` skips JFS when `NODE_ENV` is not `production` (unsigned JSON POSTs, including from `apps/emulator`). Set `SKIP_JFS_VERIFICATION=no` to require JFS anyway, or `=yes` / `=1` to force bypass in production (dev-only).
 - When using `FARCASTER_HUB_URL`, include the port (e.g. `https://rho.farcaster.xyz:3381`).
 - Set `SNAP_PUBLIC_BASE_URL` to the canonical HTTPS origin (no trailing slash) so `page.buttons[].target` URLs resolve correctly.
 - Snap hub verification uses the Hubble **HTTP** API only (no gRPC client). Hub URL helpers accept `http`/`https` with an explicit port or bare `host:port`; `grpc:`/`grpcs:` are invalid.

README.md

@@ -24,7 +24,7 @@ A local snap emulator where you paste a snap URL and interact with it.
 
 This emulator does **not** sign its payload with real private keys, so emulated snaps must bypass signature verification in order to work.
 
-An emulator with full signing is available inside the Farcaster web app.
+An emulator with JFS signing is available inside the Farcaster web app.
 
 ```bash
 pnpm --filter @farcaster/snap-emulator dev

agent-skills/create-farcaster-snap/SKILL.md

@@ -89,7 +89,7 @@ When the user wants a **live** snap (not just JSON), use the workspace package *
 - Local dev: **`pnpm --filter snap-template dev`** runs **`src/server.ts`** (default port **3003**).
 - **Vercel / edge:** **`template/src/index.ts`** wires the same Hono app via `hono/vercel` (`handle`) for `GET`/`POST` exports — match whatever your host expects (see **`template/README.md`**).
 - Set **`SNAP_PUBLIC_BASE_URL`** to your deployment origin (no trailing slash) so `page.buttons[].target` URLs resolve correctly.
-- For local POST testing, set **`BYPASS_SIGNATURE_VERIFICATION=1`**.
+- For local POST testing, set **`SKIP_JFS_VERIFICATION=1`**.
 
 Deploy (e.g. host.neynar.app): follow **`template/README.md`** — use the **`hono`** framework for this template, not Vite.
 

apps/emulator/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/emulator/package.json

@@ -4,19 +4,25 @@
   "private": true,
   "scripts": {
     "build": "next build",
+    "build:workspace-deps": "pnpm --filter @farcaster/snap --filter @farcaster/snap-ui-elements run build",
     "clean": "rm -rf .next",
+    "prebuild": "pnpm run build:workspace-deps",
+    "predev": "pnpm run build:workspace-deps",
     "dev": "next dev -p 3000 --webpack",
     "start": "next start -p 3000",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@farcaster/jfs": "0.2.2",
     "@farcaster/snap": "workspace:*",
     "@farcaster/snap-ui-elements": "workspace:*",
     "@json-render/core": "^0.15.0",
     "@json-render/react": "^0.15.0",
+    "@noble/curves": "2.0.1",
     "next": "^16.2.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "viem": "^2.21.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

apps/emulator/src/app/api/snap/route.ts

@@ -1,5 +1,6 @@
+import { encodePayload } from "@farcaster/jfs";
 import { NextRequest, NextResponse } from "next/server";
-import type { SnapPostRequestBody } from "@farcaster/snap";
+import type { SnapPayload } from "@farcaster/snap";
 import {
   coerceUpstreamUrlToMatchCurrentSnap,
   parseSnapPayload,
@@ -18,7 +19,9 @@ async function readUpstreamJson(upstream: Response): Promise<unknown> {
   } catch {
     const sample = trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
     throw new Error(
-      `Snap response is not JSON (${upstream.headers.get("content-type") ?? "unknown type"}). Body: ${sample}`,
+      `Snap response is not JSON (${
+        upstream.headers.get("content-type") ?? "unknown type"
+      }). Body: ${sample}`,
     );
   }
 }
@@ -153,14 +156,19 @@ export async function POST(request: NextRequest) {
 
   const userFid = normalizeUserFid(body.fid);
   const timestamp = Math.floor(Date.now() / 1000);
-  const wireBody: SnapPostRequestBody = {
+  const payload: SnapPayload = {
     fid: userFid,
-    inputs: (body.inputs ?? {}) as SnapPostRequestBody["inputs"],
+    inputs: (body.inputs ?? {}) as SnapPayload["inputs"],
     button_index: body.buttonIndex ?? 0,
     timestamp,
   };
 
-  const postBody = JSON.stringify(wireBody);
+  const jfsEnvelope = {
+    header: "dev",
+    payload: encodePayload(payload),
+    signature: "dev",
+  };
+  const postBody = JSON.stringify(jfsEnvelope);
   const contentType = "application/json; charset=utf-8";
 
   try {

apps/emulator/src/app/page.tsx

@@ -38,7 +38,7 @@ type LogPairResponse = {
   networkError?: boolean;
   /** From `Content-Type` when a `Response` was received; omitted for network failures. */
   contentType?: string | null;
-  /** Authoritative proxy → snap request from `/api/snap` (real signature, POST body, final URL). */
+  /** Authoritative proxy → snap request from `/api/snap` (JFS-shaped JSON POST: header/payload/signature, final URL). */
   resolvedOutboundToSnap?: OutboundSnapRequestLog;
 };
 
@@ -257,8 +257,8 @@ function splitEmulatorDebugForLog(parsed: unknown): {
     d.upstreamSnapMethod === "POST"
       ? "POST"
       : d.upstreamSnapMethod === "GET"
-        ? "GET"
-        : null;
+      ? "GET"
+      : null;
   const { _emulatorDebug: _, ...rest } = o;
   if (!method || !url || !headers) {
     return { bodyForLog: rest };
@@ -1016,8 +1016,9 @@ export default function EmulatorPage() {
                               type="button"
                               onClick={() => {
                                 void (async () => {
-                                  const ok =
-                                    await copyToClipboard(outboundToSnapText);
+                                  const ok = await copyToClipboard(
+                                    outboundToSnapText,
+                                  );
                                   if (!ok) return;
                                   flashCopied(outboundPartKey);
                                 })();
@@ -1116,8 +1117,9 @@ export default function EmulatorPage() {
                             type="button"
                             onClick={() => {
                               void (async () => {
-                                const ok =
-                                  await copyToClipboard(emulatorHeadersText);
+                                const ok = await copyToClipboard(
+                                  emulatorHeadersText,
+                                );
                                 if (!ok) return;
                                 flashCopied(emulatorHeadersPartKey);
                               })();

examples/current-time/api/index.ts

@@ -8,53 +8,47 @@ const OPT_LOCAL = "Local";
 
 const app = new Hono();
 
-registerSnapHandler(
-  app,
-  async ({ action }) => {
-    const pref =
-      action.type === "post" &&
-      typeof action.inputs[BUTTON_GROUP_NAME] === "string"
-        ? (action.inputs[BUTTON_GROUP_NAME] as string)
-        : undefined;
-    const body = timeBody(pref);
-    return {
-      version: "1.0",
-      page: {
-        theme: { accent: "blue" },
-        button_layout: "stack",
-        elements: {
-          type: "stack" as const,
-          children: [
-            { type: "text", style: "title", content: "Server time" },
-            { type: "text", style: "body", content: body },
-            {
-              type: "button_group",
-              name: BUTTON_GROUP_NAME,
-              options: [OPT_ISO, OPT_LOCAL],
-              style: "row",
-            },
-            {
-              type: "text",
-              style: "caption",
-              content:
-                "Choose format, then refresh. Time is from this server when it responds.",
-            },
-          ],
-        },
-        buttons: [
+registerSnapHandler(app, async ({ action }) => {
+  const pref =
+    action.type === "post" &&
+    typeof action.inputs[BUTTON_GROUP_NAME] === "string"
+      ? (action.inputs[BUTTON_GROUP_NAME] as string)
+      : undefined;
+  const body = timeBody(pref);
+  return {
+    version: "1.0",
+    page: {
+      theme: { accent: "blue" },
+      button_layout: "stack",
+      elements: {
+        type: "stack" as const,
+        children: [
+          { type: "text", style: "title", content: "Server time" },
+          { type: "text", style: "body", content: body },
+          {
+            type: "button_group",
+            name: BUTTON_GROUP_NAME,
+            options: [OPT_ISO, OPT_LOCAL],
+            style: "row",
+          },
           {
-            label: "Refresh",
-            action: "post",
-            target: `${snapBaseUrl()}/`,
+            type: "text",
+            style: "caption",
+            content:
+              "Choose format, then refresh. Time is from this server when it responds.",
           },
         ],
       },
-    };
-  },
-  {
-    bypassSignatureVerification: bypassSignatureVerification(),
-  },
-);
+      buttons: [
+        {
+          label: "Refresh",
+          action: "post",
+          target: `${snapBaseUrl()}/`,
+        },
+      ],
+    },
+  };
+});
 
 export default app;
 
@@ -69,11 +63,6 @@ function snapBaseUrl(): string {
   return raw.replace(/\/$/, "");
 }
 
-function bypassSignatureVerification(): boolean {
-  const v = process.env.BYPASS_SIGNATURE_VERIFICATION?.trim().toLowerCase();
-  return v === "1" || v === "true" || v === "yes";
-}
-
 function timeBody(pref: string | undefined): string {
   const now = new Date();
   if (pref === OPT_LOCAL) {

examples/current-time/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@9.15.4",
   "scripts": {
     "predev": "pnpm --filter @farcaster/snap run build",
-    "dev": "tsx watch src/server.ts",
+    "dev": "SKIP_JFS_VERIFICATION=true tsx watch src/server.ts",
     "build": "tsc --noEmit",
     "typecheck": "tsc --noEmit"
   },