@farcaster/frame-node 0.0.2

package/README.md

@@ -0,0 +1,19 @@
+# Frame Backend (Node) SDK
+
+Provides utility methods for the backend of V2 frames:
+
+- `parseWebhookEvent`: parses and verifies webhook events, using a `VerifyAppKey` method
+- `verifyJsonFarcasterSignature`: verifies a [JSON Farcaster Signature](https://github.com/farcasterxyz/protocol/discussions/208) payload, using a `VerifyAppKey` method
+- `createJsonFarcasterSignature`: creates a [JSON Farcaster Signature](https://github.com/farcasterxyz/protocol/discussions/208) payload
+
+For signature verification, you need to pass in a `VerifyAppKey` method that verifies that an app key is valid for an FID. You can use the included `verifyAppKeyWithNeynar` which uses [Neynar](https://neynar.com) and requires the `NEYNAR_API_KEY` environment variable to be defined.
+
+Not yet stable. [Learn more](https://github.com/farcasterxyz/frames/wiki/frames-v2-developer-playground-preview).
+
+## Install
+
+Install using your favorite manager:
+
+```
+npm install @farcaster/frame-node
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "@farcaster/frame-core";
+export * from "./jfs";
+export * from "./neynar";
+export * from "./types";
+export * from "./webhook";
+export * from "./util";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@farcaster/frame-core"), exports);
+__exportStar(require("./jfs"), exports);
+__exportStar(require("./neynar"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./webhook"), exports);
+__exportStar(require("./util"), exports);

package/dist/jfs.d.ts

@@ -0,0 +1,21 @@
+import { EncodedJsonFarcasterSignatureSchema } from "@farcaster/frame-core";
+import { BaseError, VerifyAppKey, VerifyJfsResult } from "./types";
+export declare namespace VerifyJsonFarcasterSignature {
+    type ErrorType = InvalidJfsDataError | InvalidJfsAppKeyError | VerifyAppKeyError;
+}
+export declare class InvalidJfsDataError<C extends Error | undefined = undefined> extends BaseError<C> {
+    readonly name = "VerifyJsonFarcasterSignature.InvalidDataError";
+}
+export declare class InvalidJfsAppKeyError<C extends Error | undefined = undefined> extends BaseError<C> {
+    readonly name = "VerifyJsonFarcasterSignature.InvalidAppKeyError";
+}
+export declare class VerifyAppKeyError<C extends Error | undefined = undefined> extends BaseError<C> {
+    readonly name = "VerifyJsonFarcasterSignature.VerifyAppKeyError";
+}
+export declare function verifyJsonFarcasterSignature(data: unknown, verifyAppKey: VerifyAppKey): Promise<VerifyJfsResult>;
+export declare function createJsonFarcasterSignature({ fid, type, privateKey, payload, }: {
+    fid: number;
+    type: "app_key";
+    privateKey: Uint8Array;
+    payload: Uint8Array;
+}): EncodedJsonFarcasterSignatureSchema;

package/dist/jfs.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyAppKeyError = exports.InvalidJfsAppKeyError = exports.InvalidJfsDataError = void 0;
+exports.verifyJsonFarcasterSignature = verifyJsonFarcasterSignature;
+exports.createJsonFarcasterSignature = createJsonFarcasterSignature;
+const frame_core_1 = require("@farcaster/frame-core");
+const ed25519_1 = require("@noble/curves/ed25519");
+const types_1 = require("./types");
+const util_1 = require("./util");
+class InvalidJfsDataError extends types_1.BaseError {
+    constructor() {
+        super(...arguments);
+        this.name = "VerifyJsonFarcasterSignature.InvalidDataError";
+    }
+}
+exports.InvalidJfsDataError = InvalidJfsDataError;
+class InvalidJfsAppKeyError extends types_1.BaseError {
+    constructor() {
+        super(...arguments);
+        this.name = "VerifyJsonFarcasterSignature.InvalidAppKeyError";
+    }
+}
+exports.InvalidJfsAppKeyError = InvalidJfsAppKeyError;
+class VerifyAppKeyError extends types_1.BaseError {
+    constructor() {
+        super(...arguments);
+        this.name = "VerifyJsonFarcasterSignature.VerifyAppKeyError";
+    }
+}
+exports.VerifyAppKeyError = VerifyAppKeyError;
+async function verifyJsonFarcasterSignature(data, verifyAppKey) {
+    //
+    // Parse, decode and validate data
+    //
+    const body = frame_core_1.encodedJsonFarcasterSignatureSchema.safeParse(data);
+    if (body.success === false) {
+        throw new InvalidJfsDataError("Error parsing data", body.error);
+    }
+    let headerData;
+    try {
+        headerData = JSON.parse(Buffer.from(body.data.header, "base64url").toString("utf-8"));
+    }
+    catch (error) {
+        throw new InvalidJfsDataError("Error decoding and parsing header");
+    }
+    const header = frame_core_1.jsonFarcasterSignatureHeaderSchema.safeParse(headerData);
+    if (header.success === false) {
+        throw new InvalidJfsDataError("Error parsing header", header.error);
+    }
+    const payload = Buffer.from(body.data.payload, "base64url");
+    const signature = Buffer.from(body.data.signature, "base64url");
+    if (signature.byteLength !== 64) {
+        throw new InvalidJfsDataError("Invalid signature length");
+    }
+    //
+    // Verify the signature
+    //
+    const fid = header.data.fid;
+    const appKey = header.data.key;
+    const appKeyBytes = (0, util_1.hexToBytes)(appKey);
+    const signedInput = new Uint8Array(Buffer.from(body.data.header + "." + body.data.payload));
+    let verifyResult;
+    try {
+        verifyResult = ed25519_1.ed25519.verify(signature, signedInput, appKeyBytes);
+    }
+    catch (e) {
+        throw new InvalidJfsDataError("Error checking signature", e instanceof Error ? e : undefined);
+    }
+    if (!verifyResult) {
+        throw new InvalidJfsDataError("Invalid signature");
+    }
+    //
+    // Verify that the app key belongs to the FID
+    //
+    let appKeyResult;
+    try {
+        appKeyResult = await verifyAppKey(fid, appKey);
+    }
+    catch (error) {
+        throw new VerifyAppKeyError("Error verifying app key", error instanceof Error ? error : undefined);
+    }
+    if (!appKeyResult.valid) {
+        throw new InvalidJfsAppKeyError("App key not valid for FID");
+    }
+    return { fid, appFid: appKeyResult.appFid, payload };
+}
+function createJsonFarcasterSignature({ fid, type, privateKey, payload, }) {
+    const publicKey = ed25519_1.ed25519.getPublicKey(privateKey);
+    const header = { fid, type, key: (0, util_1.bytesToHex)(publicKey) };
+    const encodedHeader = Buffer.from(JSON.stringify(header)).toString("base64url");
+    const encodedPayload = Buffer.from(payload).toString("base64url");
+    const signatureInput = new Uint8Array(Buffer.from(encodedHeader + "." + encodedPayload, "utf-8"));
+    const signature = ed25519_1.ed25519.sign(signatureInput, privateKey);
+    const encodedSignature = Buffer.from(signature).toString("base64url");
+    return {
+        header: encodedHeader,
+        payload: encodedPayload,
+        signature: encodedSignature,
+    };
+}

package/dist/neynar.d.ts

@@ -0,0 +1,19 @@
+import { VerifyAppKey } from "./types";
+export declare const signedKeyRequestAbi: readonly [{
+    readonly components: readonly [{
+        readonly name: "requestFid";
+        readonly type: "uint256";
+    }, {
+        readonly name: "requestSigner";
+        readonly type: "address";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+    readonly name: "SignedKeyRequest";
+    readonly type: "tuple";
+}];
+export declare const verifyAppKeyWithNeynar: VerifyAppKey;

package/dist/neynar.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAppKeyWithNeynar = exports.signedKeyRequestAbi = void 0;
+const types_1 = require("./types");
+const zod_1 = require("zod");
+const ox_1 = require("ox");
+const apiKey = process.env.NEYNAR_API_KEY || "";
+exports.signedKeyRequestAbi = [
+    {
+        components: [
+            {
+                name: "requestFid",
+                type: "uint256",
+            },
+            {
+                name: "requestSigner",
+                type: "address",
+            },
+            {
+                name: "signature",
+                type: "bytes",
+            },
+            {
+                name: "deadline",
+                type: "uint256",
+            },
+        ],
+        name: "SignedKeyRequest",
+        type: "tuple",
+    },
+];
+const neynarResponseSchema = zod_1.z.object({
+    events: zod_1.z.array(zod_1.z.object({
+        signerEventBody: zod_1.z.object({
+            key: zod_1.z.string(),
+            metadata: zod_1.z.string(),
+        }),
+    })),
+});
+const verifyAppKeyWithNeynar = async (fid, appKey) => {
+    if (!apiKey) {
+        throw new Error("Environment variable NEYNAR_API_KEY needs to be set to use Neynar for app key verification");
+    }
+    const url = new URL("https://hub-api.neynar.com/v1/onChainSignersByFid");
+    url.searchParams.append("fid", fid.toString());
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            "x-api-key": apiKey,
+        },
+    });
+    if (response.status !== 200) {
+        throw new types_1.BaseError(`Non-200 response received: ${await response.text()}`);
+    }
+    const responseJson = await response.json();
+    const parsedResponse = neynarResponseSchema.safeParse(responseJson);
+    if (parsedResponse.error) {
+        throw new types_1.BaseError("Error parsing Neynar response", parsedResponse.error);
+    }
+    const appKeyLower = appKey.toLowerCase();
+    const signerEvent = parsedResponse.data.events.find((event) => event.signerEventBody.key.toLowerCase() === appKeyLower);
+    if (!signerEvent) {
+        return { valid: false };
+    }
+    const decoded = ox_1.AbiParameters.decode(exports.signedKeyRequestAbi, Buffer.from(signerEvent.signerEventBody.metadata, "base64"));
+    if (decoded.length !== 1) {
+        throw new types_1.BaseError("Error decoding metadata");
+    }
+    const appFid = Number(decoded[0].requestFid);
+    return { valid: true, appFid };
+};
+exports.verifyAppKeyWithNeynar = verifyAppKeyWithNeynar;

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+import { FrameEvent } from "@farcaster/frame-core";
+export type VerifyAppKeyResult = {
+    valid: true;
+    appFid: number;
+} | {
+    valid: false;
+};
+export type VerifyAppKey = (fid: number, appKey: string) => Promise<VerifyAppKeyResult>;
+export type VerifyJfsResult = {
+    fid: number;
+    appFid: number;
+    payload: Uint8Array;
+};
+export type ParseWebhookEventResult = {
+    fid: number;
+    appFid: number;
+    event: FrameEvent;
+};
+export declare class BaseError<C extends Error | undefined = undefined> extends Error {
+    name: string;
+    cause: C;
+    constructor(message: string, cause?: C);
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseError = void 0;
+class BaseError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "BaseError";
+        this.cause = cause;
+    }
+}
+exports.BaseError = BaseError;

package/dist/util.d.ts

@@ -0,0 +1,2 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;

package/dist/util.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bytesToHex = bytesToHex;
+exports.hexToBytes = hexToBytes;
+function bytesToHex(bytes) {
+    return `0x${Buffer.from(bytes).toString("hex")}`;
+}
+function hexToBytes(hex) {
+    return Uint8Array.from(Buffer.from(hex.startsWith("0x") ? hex.slice(2) : hex, "hex"));
+}

package/dist/webhook.d.ts

@@ -0,0 +1,9 @@
+import { VerifyJsonFarcasterSignature } from "./jfs";
+import { BaseError, ParseWebhookEventResult, VerifyAppKey } from "./types";
+export declare namespace ParseWebhookEvent {
+    type ErrorType = VerifyJsonFarcasterSignature.ErrorType | InvalidEventDataError;
+}
+export declare class InvalidEventDataError<C extends Error | undefined = undefined> extends BaseError<C> {
+    readonly name = "VerifyJsonFarcasterSignature.InvalidEventDataError";
+}
+export declare function parseWebhookEvent(rawData: unknown, verifyAppKey: VerifyAppKey): Promise<ParseWebhookEventResult>;

package/dist/webhook.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidEventDataError = void 0;
+exports.parseWebhookEvent = parseWebhookEvent;
+const frame_core_1 = require("@farcaster/frame-core");
+const jfs_1 = require("./jfs");
+const types_1 = require("./types");
+class InvalidEventDataError extends types_1.BaseError {
+    constructor() {
+        super(...arguments);
+        this.name = "VerifyJsonFarcasterSignature.InvalidEventDataError";
+    }
+}
+exports.InvalidEventDataError = InvalidEventDataError;
+async function parseWebhookEvent(rawData, verifyAppKey) {
+    const { fid, appFid, payload } = await (0, jfs_1.verifyJsonFarcasterSignature)(rawData, verifyAppKey);
+    // Pase and validate event payload
+    let payloadJson;
+    try {
+        payloadJson = JSON.parse(Buffer.from(payload).toString("utf-8"));
+    }
+    catch (error) {
+        throw new InvalidEventDataError("Error decoding and parsing payload", error instanceof Error ? error : undefined);
+    }
+    const event = frame_core_1.eventPayloadSchema.safeParse(payload);
+    if (event.success === false) {
+        throw new InvalidEventDataError("Invalid event payload", event.error);
+    }
+    return { fid, appFid, event: event.data };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@farcaster/frame-node",
+  "version": "0.0.2",
+  "main": "dist/index.js",
+  "module": "esm/index.js",
+  "scripts": {
+    "clean": "rm -rf dist esm",
+    "prebuild": "npm run clean",
+    "build": "yarn build:cjs & yarn build:esm",
+    "build:cjs": "tsc -p tsconfig.node.json",
+    "build:esm": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "@farcaster/tsconfig": "*",
+    "@vitest/coverage-v8": "^2.1.8",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "@farcaster/frame-core": "^0.0.15",
+    "ox": "^0.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "@farcaster/frame-core";
+export * from "./jfs";
+export * from "./neynar";
+export * from "./types";
+export * from "./webhook";
+export * from "./util";

package/src/jfs.ts

@@ -0,0 +1,146 @@
+import {
+  EncodedJsonFarcasterSignatureSchema,
+  encodedJsonFarcasterSignatureSchema,
+  jsonFarcasterSignatureHeaderSchema,
+} from "@farcaster/frame-core";
+import { ed25519 } from "@noble/curves/ed25519";
+import { BaseError, VerifyAppKey, VerifyJfsResult } from "./types";
+import { bytesToHex, hexToBytes } from "./util";
+
+export declare namespace VerifyJsonFarcasterSignature {
+  type ErrorType =
+    | InvalidJfsDataError
+    | InvalidJfsAppKeyError
+    | VerifyAppKeyError;
+}
+
+export class InvalidJfsDataError<
+  C extends Error | undefined = undefined,
+> extends BaseError<C> {
+  override readonly name = "VerifyJsonFarcasterSignature.InvalidDataError";
+}
+
+export class InvalidJfsAppKeyError<
+  C extends Error | undefined = undefined,
+> extends BaseError<C> {
+  override readonly name = "VerifyJsonFarcasterSignature.InvalidAppKeyError";
+}
+
+export class VerifyAppKeyError<
+  C extends Error | undefined = undefined,
+> extends BaseError<C> {
+  override readonly name = "VerifyJsonFarcasterSignature.VerifyAppKeyError";
+}
+
+export async function verifyJsonFarcasterSignature(
+  data: unknown,
+  verifyAppKey: VerifyAppKey,
+): Promise<VerifyJfsResult> {
+  //
+  // Parse, decode and validate data
+  //
+
+  const body = encodedJsonFarcasterSignatureSchema.safeParse(data);
+  if (body.success === false) {
+    throw new InvalidJfsDataError("Error parsing data", body.error);
+  }
+
+  let headerData;
+  try {
+    headerData = JSON.parse(
+      Buffer.from(body.data.header, "base64url").toString("utf-8"),
+    );
+  } catch (error: unknown) {
+    throw new InvalidJfsDataError("Error decoding and parsing header");
+  }
+
+  const header = jsonFarcasterSignatureHeaderSchema.safeParse(headerData);
+  if (header.success === false) {
+    throw new InvalidJfsDataError("Error parsing header", header.error);
+  }
+
+  const payload = Buffer.from(body.data.payload, "base64url");
+
+  const signature = Buffer.from(body.data.signature, "base64url");
+  if (signature.byteLength !== 64) {
+    throw new InvalidJfsDataError("Invalid signature length");
+  }
+
+  //
+  // Verify the signature
+  //
+
+  const fid = header.data.fid;
+  const appKey = header.data.key;
+  const appKeyBytes = hexToBytes(appKey);
+
+  const signedInput = new Uint8Array(
+    Buffer.from(body.data.header + "." + body.data.payload),
+  );
+
+  let verifyResult;
+  try {
+    verifyResult = ed25519.verify(signature, signedInput, appKeyBytes);
+  } catch (e) {
+    throw new InvalidJfsDataError(
+      "Error checking signature",
+      e instanceof Error ? e : undefined,
+    );
+  }
+
+  if (!verifyResult) {
+    throw new InvalidJfsDataError("Invalid signature");
+  }
+
+  //
+  // Verify that the app key belongs to the FID
+  //
+
+  let appKeyResult;
+  try {
+    appKeyResult = await verifyAppKey(fid, appKey);
+  } catch (error: unknown) {
+    throw new VerifyAppKeyError(
+      "Error verifying app key",
+      error instanceof Error ? error : undefined,
+    );
+  }
+
+  if (!appKeyResult.valid) {
+    throw new InvalidJfsAppKeyError("App key not valid for FID");
+  }
+
+  return { fid, appFid: appKeyResult.appFid, payload };
+}
+
+export function createJsonFarcasterSignature({
+  fid,
+  type,
+  privateKey,
+  payload,
+}: {
+  fid: number;
+  type: "app_key";
+  privateKey: Uint8Array;
+  payload: Uint8Array;
+}): EncodedJsonFarcasterSignatureSchema {
+  const publicKey = ed25519.getPublicKey(privateKey);
+
+  const header = { fid, type, key: bytesToHex(publicKey) };
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString(
+    "base64url",
+  );
+  const encodedPayload = Buffer.from(payload).toString("base64url");
+  const signatureInput = new Uint8Array(
+    Buffer.from(encodedHeader + "." + encodedPayload, "utf-8"),
+  );
+
+  const signature = ed25519.sign(signatureInput, privateKey);
+  const encodedSignature = Buffer.from(signature).toString("base64url");
+
+  return {
+    header: encodedHeader,
+    payload: encodedPayload,
+    signature: encodedSignature,
+  };
+}

package/src/neynar.ts

@@ -0,0 +1,93 @@
+import { BaseError, VerifyAppKey, VerifyAppKeyResult } from "./types";
+import { z } from "zod";
+import { AbiParameters } from "ox";
+
+const apiKey = process.env.NEYNAR_API_KEY || "";
+
+export const signedKeyRequestAbi = [
+  {
+    components: [
+      {
+        name: "requestFid",
+        type: "uint256",
+      },
+      {
+        name: "requestSigner",
+        type: "address",
+      },
+      {
+        name: "signature",
+        type: "bytes",
+      },
+      {
+        name: "deadline",
+        type: "uint256",
+      },
+    ],
+    name: "SignedKeyRequest",
+    type: "tuple",
+  },
+] as const;
+
+const neynarResponseSchema = z.object({
+  events: z.array(
+    z.object({
+      signerEventBody: z.object({
+        key: z.string(),
+        metadata: z.string(),
+      }),
+    }),
+  ),
+});
+
+export const verifyAppKeyWithNeynar: VerifyAppKey = async (
+  fid: number,
+  appKey: string,
+): Promise<VerifyAppKeyResult> => {
+  if (!apiKey) {
+    throw new Error(
+      "Environment variable NEYNAR_API_KEY needs to be set to use Neynar for app key verification",
+    );
+  }
+
+  const url = new URL("https://hub-api.neynar.com/v1/onChainSignersByFid");
+  url.searchParams.append("fid", fid.toString());
+
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      "x-api-key": apiKey,
+    },
+  });
+
+  if (response.status !== 200) {
+    throw new BaseError(`Non-200 response received: ${await response.text()}`);
+  }
+
+  const responseJson = await response.json();
+  const parsedResponse = neynarResponseSchema.safeParse(responseJson);
+  if (parsedResponse.error) {
+    throw new BaseError("Error parsing Neynar response", parsedResponse.error);
+  }
+
+  const appKeyLower = appKey.toLowerCase();
+
+  const signerEvent = parsedResponse.data.events.find(
+    (event) => event.signerEventBody.key.toLowerCase() === appKeyLower,
+  );
+  if (!signerEvent) {
+    return { valid: false };
+  }
+
+  const decoded = AbiParameters.decode(
+    signedKeyRequestAbi,
+    Buffer.from(signerEvent.signerEventBody.metadata, "base64"),
+  );
+  if (decoded.length !== 1) {
+    throw new BaseError("Error decoding metadata");
+  }
+
+  const appFid = Number(decoded[0].requestFid);
+
+  return { valid: true, appFid };
+};

package/src/types.ts

@@ -0,0 +1,32 @@
+import { FrameEvent } from "@farcaster/frame-core";
+
+export type VerifyAppKeyResult =
+  | { valid: true; appFid: number }
+  | { valid: false };
+
+export type VerifyAppKey = (
+  fid: number,
+  appKey: string,
+) => Promise<VerifyAppKeyResult>;
+
+export type VerifyJfsResult = {
+  fid: number;
+  appFid: number;
+  payload: Uint8Array;
+};
+
+export type ParseWebhookEventResult = {
+  fid: number;
+  appFid: number;
+  event: FrameEvent;
+};
+
+export class BaseError<C extends Error | undefined = undefined> extends Error {
+  override name = "BaseError";
+  cause: C;
+
+  constructor(message: string, cause?: C) {
+    super(message);
+    this.cause = cause as any;
+  }
+}

package/src/util.ts

@@ -0,0 +1,9 @@
+export function bytesToHex(bytes: Uint8Array): string {
+  return `0x${Buffer.from(bytes).toString("hex")}`;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  return Uint8Array.from(
+    Buffer.from(hex.startsWith("0x") ? hex.slice(2) : hex, "hex"),
+  );
+}

package/src/webhook.ts

@@ -0,0 +1,46 @@
+import { eventPayloadSchema } from "@farcaster/frame-core";
+import {
+  VerifyJsonFarcasterSignature,
+  verifyJsonFarcasterSignature,
+} from "./jfs";
+import { BaseError, ParseWebhookEventResult, VerifyAppKey } from "./types";
+
+export declare namespace ParseWebhookEvent {
+  type ErrorType =
+    | VerifyJsonFarcasterSignature.ErrorType
+    | InvalidEventDataError;
+}
+
+export class InvalidEventDataError<
+  C extends Error | undefined = undefined,
+> extends BaseError<C> {
+  override readonly name = "VerifyJsonFarcasterSignature.InvalidEventDataError";
+}
+
+export async function parseWebhookEvent(
+  rawData: unknown,
+  verifyAppKey: VerifyAppKey,
+): Promise<ParseWebhookEventResult> {
+  const { fid, appFid, payload } = await verifyJsonFarcasterSignature(
+    rawData,
+    verifyAppKey,
+  );
+
+  // Pase and validate event payload
+  let payloadJson;
+  try {
+    payloadJson = JSON.parse(Buffer.from(payload).toString("utf-8"));
+  } catch (error: unknown) {
+    throw new InvalidEventDataError(
+      "Error decoding and parsing payload",
+      error instanceof Error ? error : undefined,
+    );
+  }
+
+  const event = eventPayloadSchema.safeParse(payload);
+  if (event.success === false) {
+    throw new InvalidEventDataError("Invalid event payload", event.error);
+  }
+
+  return { fid, appFid, event: event.data };
+}