@farcaster/snap 1.15.4 → 1.16.1

package/src/react-native/v2/snap-view.tsx

@@ -0,0 +1,239 @@
+import type { ReactNode } from "react";
+import { useEffect, useMemo } from "react";
+import { Platform, StyleSheet, Text, View } from "react-native";
+import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
+import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  validateSnapResponse,
+  type ValidationResult,
+} from "@farcaster/snap";
+import type { SnapPage, SnapActionHandlers } from "../types";
+
+// ─── Constants ───────────────────────────────────────
+
+const SNAP_MAX_HEIGHT = 500;
+const SNAP_WARNING_HEIGHT = 700;
+
+// ─── Validation fallback ─────────────────────────────
+
+function SnapValidationFallback({ message }: { message?: string }) {
+  const { colors } = useSnapTheme();
+  return (
+    <View style={fallbackStyles.container}>
+      <Text style={[fallbackStyles.text, { color: colors.textSecondary }]}>
+        {message ? `Unable to render snap: ${message}` : "Unable to render snap"}
+      </Text>
+    </View>
+  );
+}
+
+const fallbackStyles = StyleSheet.create({
+  container: {
+    width: "100%",
+    padding: 16,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  text: {
+    fontSize: 14,
+  },
+});
+
+// ─── SnapViewV2 (with validation) ────────────────────
+
+export function SnapViewV2Inner({
+  snap,
+  handlers,
+  loading = false,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  const validation = useMemo(() => validateSnapResponse(snap), [snap]);
+  const valid = validation.valid;
+  const validationMessage = validation.issues[0]?.message;
+
+  useEffect(() => {
+    if (!valid) {
+      if (onValidationError) {
+        onValidationError(validation);
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn("[Snap] validation issues:", validation.issues);
+      }
+    }
+  }, [valid, validation, onValidationError]);
+
+  if (!valid) {
+    if (validationErrorFallback === null) return null;
+    return (
+      <>{validationErrorFallback ?? <SnapValidationFallback message={validationMessage} />}</>
+    );
+  }
+
+  return (
+    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+  );
+}
+
+export function SnapViewV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapViewV2Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+// ─── SnapCardV2 (card frame + height limits) ─────────
+
+function SnapCardV2Inner({
+  snap,
+  handlers,
+  loading,
+  borderRadius,
+  showOverflowWarning,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  borderRadius: number;
+  showOverflowWarning: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  const { colors } = useSnapTheme();
+  const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
+
+  return (
+    <View style={cardStyles.frameRing}>
+      <View
+        style={[
+          cardStyles.card,
+          {
+            borderRadius,
+            maxHeight,
+            borderColor: colors.border,
+            backgroundColor: colors.surface,
+          },
+        ]}
+      >
+        <View style={cardStyles.body}>
+          <SnapViewV2Inner
+            snap={snap}
+            handlers={handlers}
+            loading={loading}
+            onValidationError={onValidationError}
+            validationErrorFallback={validationErrorFallback}
+          />
+        </View>
+        {showOverflowWarning && (
+          <View style={cardStyles.warningOverlay}>
+            <View style={cardStyles.warningLine} />
+            <View style={cardStyles.warningLabel}>
+              <Text style={cardStyles.warningLabelText}>{SNAP_MAX_HEIGHT}px</Text>
+            </View>
+          </View>
+        )}
+      </View>
+    </View>
+  );
+}
+
+export function SnapCardV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  borderRadius = 16,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  borderRadius?: number;
+  showOverflowWarning?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapCardV2Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        borderRadius={borderRadius}
+        showOverflowWarning={showOverflowWarning}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+const cardStyles = StyleSheet.create({
+  frameRing: { alignSelf: "stretch" },
+  card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
+  body: { paddingHorizontal: 16, paddingVertical: 16 },
+  warningOverlay: {
+    position: "absolute",
+    top: SNAP_MAX_HEIGHT,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: 10,
+  },
+  warningLine: {
+    height: 1,
+    borderTopWidth: 1,
+    borderStyle: "dashed",
+    borderColor: "rgba(255,100,100,0.6)",
+  },
+  warningLabel: {
+    position: "absolute",
+    top: -10,
+    right: 4,
+    backgroundColor: "rgba(0,0,0,0.7)",
+    paddingHorizontal: 4,
+    paddingVertical: 1,
+    borderRadius: 3,
+  },
+  warningLabelText: {
+    fontSize: 10,
+    color: "rgba(255,100,100,0.7)",
+    fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }),
+  },
+});

package/src/schemas.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { Spec } from "@json-render/core";
-import { EFFECT_VALUES, SPEC_VERSION } from "./constants";
+import { EFFECT_VALUES, SUPPORTED_SPEC_VERSIONS, type SpecVersion } from "./constants";
 import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES } from "./colors";
 
 // ─── Theme ─────────────────────────────────────────────
@@ -21,7 +21,7 @@ const themeSchema = z
 
 export const snapResponseSchema = z
   .object({
-    version: z.literal(SPEC_VERSION),
+    version: z.enum(SUPPORTED_SPEC_VERSIONS),
     theme: themeSchema.optional().default({ accent: DEFAULT_THEME_ACCENT }),
     effects: z.array(z.enum(EFFECT_VALUES)).optional(),
     ui: z.custom<Spec>(
@@ -66,7 +66,7 @@ export type SnapSpecInput = {
  * without type casts. Runtime validation via the Zod schema still catches invalid shapes.
  */
 export type SnapHandlerResult = {
-  version: typeof SPEC_VERSION;
+  version: SpecVersion;
   theme?: { accent?: z.input<typeof themeAccentSchema> };
   effects?: z.input<typeof snapResponseSchema>["effects"];
   ui: SnapSpecInput;
@@ -85,10 +85,11 @@ export const payloadSchema = z
   .object({
     fid: z.number().int().nonnegative(),
     inputs: z.record(z.string(), postInputValueSchema).default({}),
-    button_index: z.number().int().nonnegative(),
     timestamp: z.number().int(),
+    nonce: z.string().optional(),
+    audience: z.string().optional(),
   })
-  .strict();
+  .strip();
 
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
@@ -101,11 +102,9 @@ const snapGetActionSchema = z.object({
 
 export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
 
-const snapPostActionSchema = payloadSchema
-  .extend({
-    type: z.literal(ACTION_TYPE_POST),
-  })
-  .strict();
+const snapPostActionSchema = payloadSchema.extend({
+  type: z.literal(ACTION_TYPE_POST),
+});
 
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 

package/src/server/parseRequest.ts

@@ -29,6 +29,10 @@ export type ParseRequestError =
   | {
       type: "signature";
       message: string;
+    }
+  | {
+      type: "origin_mismatch";
+      message: string;
     };
 
 export type ParseRequestOptions = {
@@ -43,6 +47,12 @@ export type ParseRequestOptions = {
    * potential replays. Defaults to 300 (5 minutes) when not provided.
    */
   maxSkewSeconds?: number;
+
+  /**
+   * The origin of the request. Derived from the request when not provided.
+   */
+  requestOrigin?: string;
+
 };
 
 export type ParseRequestResult =
@@ -137,6 +147,30 @@ export async function parseRequest(
       },
     };
   }
+
+  // Audience validation: only enforce when the client sends an audience field.
+  // v1 clients may not include nonce/audience yet.
+  if (body.audience !== undefined) {
+    let expectedOrigin = options.requestOrigin;
+    if (expectedOrigin === undefined) {
+      try {
+        expectedOrigin = new URL(request.url).origin;
+      } catch {
+        // do nothing
+      }
+    }
+
+    if (expectedOrigin !== undefined && body.audience !== expectedOrigin) {
+      return {
+        success: false,
+        error: {
+          type: "origin_mismatch",
+          message: `payload audience "${body.audience}" does not match expected origin "${expectedOrigin}"`,
+        },
+      };
+    }
+  }
+
   return {
     success: true,
     action: {

package/src/ui/schema.ts

@@ -30,7 +30,7 @@ export const snapJsonRenderSchema = defineSchema(
   {
     defaultRules: [
       "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Item, Badge, ButtonGroup, Input, Switch, ToggleGroup, Slider, Progress, Image, Separator).",
-      "Snap pages use a Stack root with at most 6 body children and 1 media element (Image); keep generated trees small.",
+      "Snap structural limits: max 64 elements, max 7 children on root, max 6 children per non-root container, max 4 levels of nesting. Keep generated trees small.",
       "Bottom-of-card snap buttons are Button components; use actions post / link / mini_app / sdk per SPEC.md.",
     ],
   },

package/src/validator.ts

@@ -1,15 +1,225 @@
 import { z } from "zod";
 import { snapResponseSchema } from "./schemas";
+import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants";
 
 export type ValidationResult = {
   valid: boolean;
   issues: z.core.$ZodIssue[];
 };
 
+// ─── Helpers ──────────────────────────────────────────
+
+/** Actions whose `params.target` must be a valid URL. */
+const URL_TARGET_ACTIONS = new Set(["submit", "open_url", "open_mini_app"]);
+
+/** Image file extensions allowed in image URLs. */
+const ALLOWED_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "gif", "webp"]);
+
+/**
+ * Returns true if the URL is a loopback address (localhost dev exception).
+ */
+function isLoopback(url: URL): boolean {
+  const host = url.hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+
+/**
+ * Validate a URL string: must be HTTPS (or HTTP on loopback for dev).
+ * Returns an error message or null if valid.
+ */
+function validateUrl(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return `Invalid URL: "${raw}"`;
+  }
+
+  if (url.protocol === "https:") return null;
+  if (url.protocol === "http:" && isLoopback(url)) return null;
+  if (url.protocol === "javascript:") return `javascript: URIs are not allowed`;
+
+  return `URL must use HTTPS (got ${url.protocol.replace(":", "")}): "${raw}"`;
+}
+
+/**
+ * Validate an image URL: must pass URL validation + have an allowed extension.
+ */
+function validateImageUrl(raw: string): string | null {
+  const urlError = validateUrl(raw);
+  if (urlError) return urlError;
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null; // already caught above
+  }
+
+  const pathname = url.pathname;
+  const lastDot = pathname.lastIndexOf(".");
+  if (lastDot === -1) {
+    return `Image URL must end with a supported extension (${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
+  }
+
+  const ext = pathname.slice(lastDot + 1).toLowerCase();
+  if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
+    return `Image URL has unsupported extension ".${ext}" (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
+  }
+
+  return null;
+}
+
+// ─── Depth measurement ────────────────────────────────
+
+/**
+ * Walk the element tree from `root` and return the max depth reached.
+ * Avoids infinite loops by tracking visited element ids.
+ */
+function measureDepth(
+  elements: Record<string, { children?: string[] }>,
+  id: string,
+  visited: Set<string> = new Set(),
+): number {
+  if (visited.has(id)) return 0;
+  visited.add(id);
+
+  const el = elements[id];
+  if (!el?.children?.length) return 1;
+
+  let max = 0;
+  for (const childId of el.children) {
+    max = Math.max(max, measureDepth(elements, childId, visited));
+  }
+  return 1 + max;
+}
+
+// ─── Element types for traversal ──────────────────────
+
+type ElementShape = {
+  type?: string;
+  children?: string[];
+  props?: Record<string, unknown>;
+  on?: Record<string, { action?: string; params?: Record<string, unknown> }>;
+};
+
+// ─── Structural validation ────────────────────────────
+
+/**
+ * Validate structural constraints on the snap UI tree:
+ * - root must reference an existing element
+ * - Total element count ≤ MAX_ELEMENTS
+ * - Children per element ≤ MAX_CHILDREN
+ * - Nesting depth ≤ MAX_DEPTH
+ */
+function validateStructure(
+  ui: { root: string; elements: Record<string, unknown> },
+): z.core.$ZodIssue[] {
+  const issues: z.core.$ZodIssue[] = [];
+  const elements = ui.elements as Record<string, ElementShape>;
+
+  const elementCount = Object.keys(elements).length;
+  if (elementCount > MAX_ELEMENTS) {
+    issues.push({
+      code: "custom",
+      message: `Snap exceeds maximum of ${MAX_ELEMENTS} elements (found ${elementCount})`,
+      path: ["ui", "elements"],
+    });
+  }
+
+  // Root element has a stricter children limit
+  const rootEl = elements[ui.root];
+  if (rootEl?.children && rootEl.children.length > MAX_ROOT_CHILDREN) {
+    issues.push({
+      code: "custom",
+      message: `Root element "${ui.root}" exceeds maximum of ${MAX_ROOT_CHILDREN} children (found ${rootEl.children.length})`,
+      path: ["ui", "elements", ui.root, "children"],
+    });
+  }
+
+  for (const [id, el] of Object.entries(elements)) {
+    if (id === ui.root) continue; // already checked above
+    if (el.children && el.children.length > MAX_CHILDREN) {
+      issues.push({
+        code: "custom",
+        message: `Element "${id}" exceeds maximum of ${MAX_CHILDREN} children (found ${el.children.length})`,
+        path: ["ui", "elements", id, "children"],
+      });
+    }
+  }
+
+  const depth = measureDepth(
+    elements as Record<string, { children?: string[] }>,
+    ui.root,
+  );
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      code: "custom",
+      message: `Snap exceeds maximum nesting depth of ${MAX_DEPTH} (found ${depth})`,
+      path: ["ui", "root"],
+    });
+  }
+
+  return issues;
+}
+
+// ─── URL validation ───────────────────────────────────
+
 /**
- * Validates a snap response against the schema.
+ * Validate all URLs in the snap:
+ * - image.url: must be HTTPS with allowed extension
+ * - action target URLs (submit, open_url, open_mini_app): must be HTTPS
+ */
+function validateUrls(
+  elements: Record<string, unknown>,
+): z.core.$ZodIssue[] {
+  const issues: z.core.$ZodIssue[] = [];
+  const els = elements as Record<string, ElementShape>;
+
+  for (const [id, el] of Object.entries(els)) {
+    // Validate image URLs
+    if (el.type === "image" && typeof el.props?.url === "string") {
+      const error = validateImageUrl(el.props.url);
+      if (error) {
+        issues.push({
+          code: "custom",
+          message: error,
+          path: ["ui", "elements", id, "props", "url"],
+        });
+      }
+    }
+
+    // Validate action target URLs
+    if (el.on) {
+      for (const [event, binding] of Object.entries(el.on)) {
+        if (
+          binding &&
+          URL_TARGET_ACTIONS.has(binding.action ?? "") &&
+          typeof binding.params?.target === "string"
+        ) {
+          const error = validateUrl(binding.params.target);
+          if (error) {
+            issues.push({
+              code: "custom",
+              message: error,
+              path: ["ui", "elements", id, "on", event, "params", "target"],
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+// ─── Public API ───────────────────────────────────────
+
+/**
+ * Validates a snap response against the schema, structural constraints, and URL rules.
  * Element-level prop validation is handled by the json-render catalog.
- * This validates the snap envelope (version, theme, effects, spec shape).
+ * This validates the snap envelope (version, theme, effects, spec shape)
+ * and enforces structural limits (element count, children, depth) and URL validation.
  */
 export function validateSnapResponse(json: unknown): ValidationResult {
   const parsed = snapResponseSchema.safeParse(json);
@@ -19,5 +229,33 @@ export function validateSnapResponse(json: unknown): ValidationResult {
       issues: parsed.error.issues,
     };
   }
+
+  const ui = parsed.data.ui;
+
+  // Root reference check applies to all versions
+  if (!(ui.root in ui.elements)) {
+    return {
+      valid: false,
+      issues: [{
+        code: "custom",
+        message: `ui.root "${ui.root}" does not exist in ui.elements`,
+        path: ["ui", "root"],
+      }],
+    };
+  }
+
+  // Structural limits and URL validation only apply to v2+ snaps
+  if (parsed.data.version !== SPEC_VERSION_1) {
+    const structuralIssues = validateStructure(ui);
+    if (structuralIssues.length > 0) {
+      return { valid: false, issues: structuralIssues };
+    }
+
+    const urlIssues = validateUrls(ui.elements);
+    if (urlIssues.length > 0) {
+      return { valid: false, issues: urlIssues };
+    }
+  }
+
   return { valid: true, issues: [] };
 }