@farcaster/snap 2.1.2 → 2.2.0

package/dist/ui/cell-grid.d.ts

@@ -6,7 +6,7 @@ export declare const cellGridProps: z.ZodObject<{
     cells: z.ZodArray<z.ZodObject<{
         row: z.ZodNumber;
         col: z.ZodNumber;
-        color: z.ZodOptional<z.ZodEnum<{
+        color: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodUnion<readonly [z.ZodEnum<{
             gray: "gray";
             blue: "blue";
             red: "red";
@@ -15,7 +15,7 @@ export declare const cellGridProps: z.ZodObject<{
             teal: "teal";
             purple: "purple";
             pink: "pink";
-        }>>;
+        }>, z.ZodString]>>>;
         content: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     gap: z.ZodOptional<z.ZodEnum<{

package/dist/ui/cell-grid.js

@@ -1,10 +1,19 @@
 import { z } from "zod";
-import { PALETTE_COLOR_VALUES } from "../colors.js";
+import { isSnapHexColorString, PALETTE_COLOR_VALUES } from "../colors.js";
 import { GRID_MIN_COLS, GRID_MAX_COLS, GRID_MIN_ROWS, GRID_MAX_ROWS, GRID_GAP_VALUES, } from "../constants.js";
+/** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
+const cellGridCellColorSchema = z.preprocess((v) => (typeof v === "string" ? v.trim() : v), z.union([
+    z.enum(PALETTE_COLOR_VALUES),
+    z
+        .string()
+        .refine(isSnapHexColorString, {
+        message: "cell_grid cell hex color must be #rrggbb",
+    }),
+]));
 const cellGridCellSchema = z.object({
     row: z.number().int().nonnegative(),
     col: z.number().int().nonnegative(),
-    color: z.enum(PALETTE_COLOR_VALUES).optional(),
+    color: cellGridCellColorSchema.optional(),
     content: z.string().optional(),
 });
 export const cellGridProps = z

package/dist/verify.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { verifyJFSRequestBody } from "./server/verify.js";
+import { verifyJFS } from "./server/verify.js";
 const validRequestBody = `{
   "header":"eyJmaWQiOjI2MTMxOSwidHlwZSI6ImFwcF9rZXkiLCJrZXkiOiIweGY0ZGQyNjczYTUzMjEwYzQ3ZGYzZjFmNTk0NjZlZTdhMTM3ZmQxOGQ5NTVjMmU2OGExMmQwOTE2MGE2NmMyMTUifQ",
   "payload":"eyJmaWQiOjI2MTMxOSwiaW5wdXRzIjp7ImRpc3BsYXkiOiJJU08gKFVUQykifSwiYnV0dG9uX2luZGV4IjowLCJ0aW1lc3RhbXAiOjE3NzQ2OTMyMTN9",
@@ -7,7 +7,7 @@ const validRequestBody = `{
 }`;
 /** Matches JFS header `key` (Ed25519 public key, 32 bytes hex without `0x` in hub JSON field). */
 const HUB_SIGNER_KEY_HEX = "f4dd2673a53210c47df3f1f59466ee7a137fd18d955c2e68a12d09160a66c215";
-describe("verifyJFSRequestBody", () => {
+describe("verifyJFS", () => {
     beforeEach(() => {
         vi.stubGlobal("fetch", vi.fn(async (input) => {
             const u = String(input);
@@ -41,7 +41,7 @@ describe("verifyJFSRequestBody", () => {
         vi.unstubAllGlobals();
     });
     it("accepts JSON JFS body and verifies crypto + hub signer list", async () => {
-        const result = await verifyJFSRequestBody(JSON.parse(validRequestBody));
+        const result = await verifyJFS(JSON.parse(validRequestBody));
         expect(result.valid).toBe(true);
         if (result.valid) {
             expect(result.data).toEqual({

package/llms.txt

@@ -95,7 +95,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `name` (string, optional): POST inputs key. Default: `"grid_tap"`
 - `cols` (number, required, 2–32)
 - `rows` (number, required, 2–16)
-- `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor, content?: string }`
+- `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor | #rrggbb, content?: string }`
 - `gap` (optional): `"none"` (0px) | `"sm"` (1px) | `"md"` (2px) | `"lg"` (4px). Default: `"sm"`
 - `rowHeight` (number, optional, 8–64): pixel height per row. Default: 28. Grid height = rows × rowHeight
 - `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button`; `on.press` is ignored.
@@ -172,6 +172,16 @@ Bound to buttons via `on.press`:
 | `send_token` | `token`, `amount?`, `recipientFid?`, `recipientAddress?` | Send token flow |
 | `swap_token` | `sellToken?`, `buyToken?` | Swap token flow |
 
+## Authenticated requests
+
+POST requests carry a JFS envelope (JSON object **or** compact dot-separated string). `parseRequest` validates the payload and (unless `skipJFSVerification`) cryptographically verifies the JFS against an active hub signer for `user.fid`. On the server, `ctx.action.user.fid` is **always present and verified** for `type === "post"`.
+
+GET requests MAY include optional viewer identity in the `X-Snap-Payload` request header (a JFS compact string with the same shape as POST minus `inputs` and `fid`). When present and valid, `ctx.action` on GET MAY include `user`, `timestamp`, `audience`, and `surface`.
+
+`ctx.action.user` on GET is **best-effort and never guaranteed** — older or custom clients, cache layers, crawlers, and `curl` may yield an anonymous GET even for users who have POSTed to this snap before. Always render a working anonymous first load; treat viewer fields on GET as a strict enhancement. `parseRequest` (and `@farcaster/snap-hono`'s GET handler) silently fall back to anonymous `{ type: "get" }` when `X-Snap-Payload` is missing or invalid.
+
+When responses depend on viewer identity, send `Vary: Accept, X-Snap-Payload` and consider `Cache-Control: private` so caches don't serve viewer-specific bodies to other viewers (`@farcaster/snap-hono` sets `Vary` automatically).
+
 ## Icon Names (34)
 
 `arrow-right`, `arrow-left`, `external-link`, `chevron-right`, `check`, `x`, `alert-triangle`, `info`, `clock`, `heart`, `message-circle`, `repeat`, `share`, `user`, `users`, `star`, `trophy`, `zap`, `flame`, `gift`, `image`, `play`, `pause`, `wallet`, `coins`, `plus`, `minus`, `refresh-cw`, `bookmark`, `thumbs-up`, `thumbs-down`, `trending-up`, `trending-down`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/colors.ts

@@ -38,6 +38,33 @@ export const PALETTE_COLOR_VALUES = [
 
 export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
 
+/** Strict `#rrggbb` literal used by cell_grid (and clients that accept hex). */
+const SNAP_HEX_6 = /^#[0-9a-fA-F]{6}$/;
+
+export function isSnapHexColorString(s: string): boolean {
+  return SNAP_HEX_6.test(s.trim());
+}
+
+/**
+ * Resolve a snap color token for inline styles: `accent`, palette names, or
+ * literal `#rrggbb`. Unknown values fall back to `accentHex` (same as legacy
+ * `colorHex` behavior for non-hex strings).
+ */
+export function resolveSnapColorHex(
+  color: string | undefined,
+  opts: { accentHex: string; appearance: "light" | "dark" },
+): string {
+  if (!color || color === PALETTE_COLOR_ACCENT) return opts.accentHex;
+  const trimmed = color.trim();
+  if (isSnapHexColorString(trimmed)) return trimmed;
+  const map =
+    opts.appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+  if (Object.hasOwn(map, trimmed)) {
+    return map[trimmed as PaletteColor];
+  }
+  return opts.accentHex;
+}
+
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
   gray: "#6E6A86",

package/src/constants.ts

@@ -1,9 +1,14 @@
 export const SPEC_VERSION_1 = "1.0" as const;
 export const SPEC_VERSION_2 = "2.0" as const;
 export const SPEC_VERSION = SPEC_VERSION_2;
-export const SUPPORTED_SPEC_VERSIONS = [SPEC_VERSION_1, SPEC_VERSION_2] as const;
+export const SUPPORTED_SPEC_VERSIONS = [
+  SPEC_VERSION_1,
+  SPEC_VERSION_2,
+] as const;
 export type SpecVersion = (typeof SUPPORTED_SPEC_VERSIONS)[number];
 
+export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload" as const;
+
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json" as const;
 
 export const EFFECT_VALUES = ["confetti"] as const;

package/src/index.ts

@@ -8,6 +8,7 @@ export {
   SPEC_VERSION_2,
   SUPPORTED_SPEC_VERSIONS,
   type SpecVersion,
+  SNAP_PAYLOAD_HEADER,
   MEDIA_TYPE,
   EFFECT_VALUES,
   POST_GRID_TAP_KEY,
@@ -23,6 +24,8 @@ export {
   PALETTE_COLOR_VALUES,
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
+  isSnapHexColorString,
+  resolveSnapColorHex,
   type PaletteColor,
 } from "./colors";
 export {
@@ -30,7 +33,9 @@ export {
   ACTION_TYPE_POST,
   snapResponseSchema,
   payloadSchema,
+  getPayloadSchema,
   type SnapAction,
+  type SnapGetAction,
   type SnapContext,
   type SnapResponse,
   type SnapHandlerResult,
@@ -38,5 +43,6 @@ export {
   type SnapSpecInput,
   type SnapFunction,
   type SnapPayload,
+  type SnapGetPayload,
 } from "./schemas";
 export { validateSnapResponse, type ValidationResult } from "./validator";

package/src/react/hooks/use-snap-colors.ts

@@ -4,8 +4,7 @@ import { useMemo } from "react";
 import { useStateStore } from "@json-render/react";
 import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import { useSnapPreviewPageAccent, useSnapAppearance } from "../accent-context";
-import type { PaletteColor } from "@farcaster/snap";
-import { PALETTE_DARK_HEX, PALETTE_LIGHT_HEX } from "@farcaster/snap";
+import { resolveSnapColorHex } from "@farcaster/snap";
 
 /** Readable foreground color (black or white) for a given hex background. */
 export function pickForegroundForBg(hex: string): string {
@@ -76,7 +75,6 @@ function buildSnapColors(
   const accent = resolveSnapPaletteHex(accentName, mode);
   const accentFg = pickForegroundForBg(accent);
   const neutrals = mode === "dark" ? NEUTRAL_DARK : NEUTRAL_LIGHT;
-  const paletteMap = mode === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
 
   const accentHover =
     mode === "light"
@@ -87,11 +85,8 @@ function buildSnapColors(
 
   const paletteHex = (name: string) => resolveSnapPaletteHex(name, mode);
 
-  const colorHex = (name: string | undefined) => {
-    if (!name || name === "accent") return accent;
-    if (Object.hasOwn(paletteMap, name)) return paletteMap[name as PaletteColor];
-    return accent;
-  };
+  const colorHex = (name: string | undefined) =>
+    resolveSnapColorHex(name, { accentHex: accent, appearance: mode });
 
   return {
     accent,

package/src/react-native/use-snap-palette.ts

@@ -3,6 +3,7 @@ import {
   PALETTE_COLOR_VALUES,
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
+  resolveSnapColorHex,
   type PaletteColor,
 } from "@farcaster/snap";
 import { useStateStore } from "@json-render/react-native";
@@ -35,7 +36,7 @@ export function useSnapPalette() {
   const accentHex = resolveHex(accentName, mode);
 
   const hex = (semantic: string) =>
-    semantic === "accent" ? accentHex : resolveHex(semantic, mode);
+    resolveSnapColorHex(semantic, { accentHex, appearance: mode });
 
   return { appearance: mode, accentName, accentHex, hex };
 }

package/src/schemas.ts

@@ -104,26 +104,36 @@ const surfaceSchema = z.discriminatedUnion("type", [
   standaloneSurfaceSchema,
 ]);
 
+const fidSchema = z.number().int().nonnegative();
+const userSchema = z.object({ fid: fidSchema });
+
 export const payloadSchema = z
   .object({
-    fid: z.number().int().nonnegative().optional(), // deprecated in favor of user.fid
+    fid: fidSchema.optional(), // deprecated in favor of user.fid
     inputs: z.record(z.string(), postInputValueSchema).default({}),
     timestamp: z.number().int(),
     audience: z.string(),
-    user: z.object({
-      fid: z.number().int().nonnegative(),
-    }),
+    user: userSchema,
     surface: surfaceSchema,
   })
   .strip();
 
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
+/** JFS payload shape for POST minus deprecated `fid`; used for GET auth via payload header. */
+export const getPayloadSchema = payloadSchema.omit({ inputs: true, fid: true });
+
+export type SnapGetPayload = z.infer<typeof getPayloadSchema>;
+
 export const ACTION_TYPE_GET = "get" as const;
 export const ACTION_TYPE_POST = "post" as const;
 
 const snapGetActionSchema = z.object({
   type: z.literal(ACTION_TYPE_GET),
+  user: userSchema.optional(),
+  timestamp: z.number().int().optional(),
+  audience: z.string().optional(),
+  surface: surfaceSchema.optional(),
 });
 
 export type SnapGetAction = z.infer<typeof snapGetActionSchema>;

package/src/server/index.ts

@@ -1,4 +1,10 @@
-export { verifyJFSRequestBody, decodePayload, encodePayload } from "./verify";
+export {
+  verifyJFS as verifyJFSRequestBody, // deprecated alias. drop in v3
+  parseJfs,
+  verifyJFS,
+  decodePayload,
+  encodePayload,
+} from "./verify";
 export {
   DEFAULT_SNAP_HUB_HTTP_BASE_URL,
   getActiveEd25519SignerKeysFromHubHttp,

package/src/server/parseRequest.ts

@@ -1,11 +1,15 @@
+import { z } from "zod";
 import {
   ACTION_TYPE_GET,
   ACTION_TYPE_POST,
+  getPayloadSchema,
   payloadSchema,
   type SnapAction,
+  type SnapPayload,
+  type SnapGetPayload,
 } from "../schemas";
-import { decodePayload, verifyJFSRequestBody } from "./verify";
-import { z } from "zod";
+import { decodePayload, parseJfs, verifyJFS } from "./verify";
+import { SNAP_PAYLOAD_HEADER } from "../constants";
 
 const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300 as const;
 
@@ -62,98 +66,156 @@ export type ParseRequestResult =
   | { success: true; action: SnapAction }
   | { success: false; error: ParseRequestError };
 
-const requestBodySchema = z.object({
-  header: z.string(),
-  payload: z.string(),
-  signature: z.string(),
-});
-
 /**
  * Parse and validate Farcaster snap requests:
- * - `GET` is allowed for first-page loads and returns `{ type: "get" }`.
- * - `POST`: the body must be JSON in JFS form (`header` / `payload` / `signature`) even if JFS verification is skipped.
+ * - `GET`: returns `{ type: "get" }`, or optional viewer fields when `X-Snap-Payload`
+ *   carries a JFS compact string whose decoded payload validates against {@link getPayloadSchema}.
+ * - `POST`: the body must be a JFS envelope — either JSON `{ header, payload, signature }` or the same **compact** string form as GET (`BASE64URL(header).BASE64URL(payload).BASE64URL(signature)`), even if JFS verification is skipped.
  */
 export async function parseRequest(
   request: Request,
   options: ParseRequestOptions = {},
 ): Promise<ParseRequestResult> {
-  if (!["GET", "POST"].includes(request.method)) {
-    return {
-      success: false,
-      error: {
-        type: "method_not_allowed",
-        message: `expected POST, received ${request.method}`,
-      },
-    };
+  if (request.method === "GET") {
+    return await parseGetRequest(request, options);
+  }
+  if (request.method === "POST") {
+    return await parsePostRequest(request, options);
   }
+  return {
+    success: false,
+    error: {
+      type: "method_not_allowed",
+      message: `expected GET or POST, received ${request.method}`,
+    },
+  };
+}
 
-  if (request.method === "GET") {
-    return {
-      success: true,
-      action: { type: ACTION_TYPE_GET },
-    };
+async function parseGetRequest(
+  request: Request,
+  options: ParseRequestOptions,
+): Promise<ParseRequestResult> {
+  const compactHeader = request.headers.get(SNAP_PAYLOAD_HEADER)?.trim();
+  if (!compactHeader) {
+    return { success: true, action: { type: ACTION_TYPE_GET } };
   }
 
-  const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
-  const nowSec = Math.floor(Date.now() / 1000);
+  const result = await validateJfsPayload({
+    jfsText: compactHeader,
+    schema: getPayloadSchema,
+    request,
+    options,
+    invalidJsonMessage: `${SNAP_PAYLOAD_HEADER} must be a valid JFS compact string`,
+  });
+  if (!result.ok) {
+    return { success: false, error: result.error };
+  }
 
-  const text = await request.text();
+  return {
+    success: true,
+    action: { type: ACTION_TYPE_GET, ...result.payload },
+  };
+}
 
-  let jsonBody: unknown;
-  try {
-    jsonBody = JSON.parse(text);
-  } catch {
+async function parsePostRequest(
+  request: Request,
+  options: ParseRequestOptions,
+): Promise<ParseRequestResult> {
+  const result = await validateJfsPayload({
+    jfsText: await request.text(),
+    schema: payloadSchema,
+    request,
+    options,
+  });
+  if (!result.ok) {
+    return { success: false, error: result.error };
+  }
+
+  const payload = result.payload;
+  if (payload.fid !== undefined && payload.fid !== payload.user.fid) {
     return {
       success: false,
       error: {
-        type: "invalid_json",
-        message: "request body is not valid JSON",
+        type: "fid_mismatch",
+        message: `fid "${payload.fid}" does not match user.fid "${payload.user.fid}"`,
       },
     };
   }
 
-  const parsed = requestBodySchema.safeParse(jsonBody);
-  if (!parsed.success) {
+  return {
+    success: true,
+    action: { type: ACTION_TYPE_POST, ...payload },
+  };
+}
+
+/**
+ * Shared pipeline for authenticated snap requests: parse the JFS envelope,
+ * decode and schema-validate the payload, optionally verify the JFS signature
+ * against an active hub signer (matching `user.fid`), then check timestamp
+ * skew and that `audience` matches the request origin.
+ *
+ * Both GET (payload header) and POST (request body) feed into this.
+ */
+async function validateJfsPayload<T extends SnapPayload | SnapGetPayload>({
+  jfsText,
+  schema,
+  request,
+  options,
+  invalidJsonMessage,
+}: {
+  jfsText: string;
+  schema: z.ZodType<T>;
+  request: Request;
+  options: ParseRequestOptions;
+  invalidJsonMessage?: string;
+}): Promise<
+  { ok: true; payload: T } | { ok: false; error: ParseRequestError }
+> {
+  const parsed = parseJfs(jfsText);
+  if (!parsed.ok) {
     return {
-      success: false,
-      error: { type: "invalid_json", message: parsed.error.message },
+      ok: false,
+      error: {
+        type: "invalid_json",
+        message: invalidJsonMessage ?? parsed.error,
+      },
     };
   }
+  const jfs = parsed.jfs;
 
-  const payloadParsed = payloadSchema.safeParse(
-    decodePayload(parsed.data.payload),
-  );
+  const payloadParsed = schema.safeParse(decodePayload(jfs.payload));
   if (!payloadParsed.success) {
     return {
-      success: false,
+      ok: false,
       error: { type: "validation", issues: payloadParsed.error.issues },
     };
   }
-
-  const body = payloadParsed.data;
+  const payload = payloadParsed.data;
 
   if (!options.skipJFSVerification) {
-    const jfs = await verifyJFSRequestBody(parsed.data);
-    if (!jfs.valid) {
+    const verified = await verifyJFS(jfs);
+    if (!verified.valid) {
       return {
-        success: false,
-        error: { type: "signature", message: jfs.error.message },
+        ok: false,
+        error: { type: "signature", message: verified.error.message },
       };
     }
-    if (jfs.signingUserFid !== body.user.fid) {
+    if (verified.signingUserFid !== payload.user.fid) {
       return {
-        success: false,
+        ok: false,
         error: {
           type: "fid_mismatch",
-          message: `JFS header fid "${jfs.signingUserFid}" does not match user.fid "${body.user.fid}"`,
+          message: `JFS header fid "${verified.signingUserFid}" does not match user.fid "${payload.user.fid}"`,
         },
       };
     }
   }
 
-  if (Math.abs(nowSec - body.timestamp) > maxSkew) {
+  const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
+  const nowSec = Math.floor(Date.now() / 1000);
+  if (Math.abs(nowSec - payload.timestamp) > maxSkew) {
     return {
-      success: false,
+      ok: false,
       error: {
         type: "replay",
         message: `timestamp outside allowed skew of ${maxSkew}s`,
@@ -176,31 +238,15 @@ export async function parseRequest(
     }
   }
 
-  if (expectedOrigin !== undefined && body.audience !== expectedOrigin) {
+  if (expectedOrigin !== undefined && payload.audience !== expectedOrigin) {
     return {
-      success: false,
+      ok: false,
       error: {
         type: "origin_mismatch",
-        message: `payload audience "${body.audience}" does not match expected origin "${expectedOrigin}"`,
+        message: `payload audience "${payload.audience}" does not match expected origin "${expectedOrigin}"`,
       },
     };
   }
 
-  if (body.fid !== undefined && body.fid !== body.user.fid) {
-    return {
-      success: false,
-      error: {
-        type: "fid_mismatch",
-        message: `fid "${body.fid}" does not match user.fid "${body.user.fid}"`,
-      },
-    };
-  }
-
-  return {
-    success: true,
-    action: {
-      type: ACTION_TYPE_POST,
-      ...body,
-    },
-  };
+  return { ok: true, payload };
 }