feat: support app key signatures

Author: michalkvasnicak

.changeset/rich-bags-begin.md

@@ -0,0 +1,6 @@
+---
+"frames.js": patch
+"@frames.js/debugger": patch
+---
+
+feat: support for app key signatures

packages/frames.js/package.json

@@ -187,6 +187,16 @@
         "default": "./dist/farcaster-v2/types.cjs"
       }
     },
+    "./farcaster-v2/verify-app-key-with-neynar": {
+      "import": {
+        "types": "./dist/farcaster-v2/verify-app-key-with-neynar.d.ts",
+        "default": "./dist/farcaster-v2/verify-app-key-with-neynar.js"
+      },
+      "require": {
+        "types": "./dist/farcaster-v2/verify-app-key-with-neynar.d.cts",
+        "default": "./dist/farcaster-v2/verify-app-key-with-neynar.cjs"
+      }
+    },
     "./core": {
       "import": {
         "types": "./dist/core/index.d.ts",
@@ -420,12 +430,14 @@
   },
   "dependencies": {
     "@farcaster/frame-core": "^0.0.24",
-    "@farcaster/frame-node": "^0.0.13",
+    "@noble/ed25519": "^2.2.3",
+    "@noble/hashes": "^1.7.1",
     "@vercel/og": "^0.6.3",
     "cheerio": "^1.0.0-rc.12",
+    "ox": "^0.4.4",
     "protobufjs": "^7.2.6",
-    "viem": "^2.7.8",
     "type-fest": "^4.28.1",
+    "viem": "^2.7.8",
     "zod": "^3.24.1"
   }
 }

packages/frames.js/src/farcaster-v2/es25519.ts

@@ -0,0 +1,8 @@
+import { sha512 } from "@noble/hashes/sha512";
+import { etc, getPublicKey, sign, verify } from "@noble/ed25519";
+
+if (!etc.sha512Sync) {
+  etc.sha512Sync = (...m: Uint8Array[]) => sha512(etc.concatBytes(...m));
+}
+
+export { getPublicKey, sign, verify };

packages/frames.js/src/farcaster-v2/events.ts

@@ -3,11 +3,9 @@ import type {
   EncodedJsonFarcasterSignatureSchema,
 } from "@farcaster/frame-core";
 import { serverEventSchema } from "@farcaster/frame-core";
-import {
-  createJsonFarcasterSignature,
-  hexToBytes,
-} from "@farcaster/frame-node";
-import type { Hex } from "viem";
+import { bytesToHex, type Hex } from "viem";
+import { sign, signMessageWithAppKey } from "./json-signature";
+import { getPublicKey } from "./es25519";
 
 export class InvalidWebhookResponseError extends Error {
   constructor(
@@ -22,7 +20,7 @@ export type { FrameServerEvent };
 
 type SendEventOptions = {
   /**
-   * App private key
+   * Private app key (signer private key)
    */
   privateKey: Hex | Uint8Array;
   fid: number;
@@ -36,13 +34,16 @@ export async function sendEvent(
   event: FrameServerEvent,
   { privateKey, fid, webhookUrl }: SendEventOptions
 ): Promise<void> {
+  const appKey = bytesToHex(getPublicKey(privateKey));
   const payload = serverEventSchema.parse(event);
-  const signature = createJsonFarcasterSignature({
+  const signature = await sign({
     fid,
-    payload: Buffer.from(JSON.stringify(payload)),
-    privateKey:
-      typeof privateKey === "string" ? hexToBytes(privateKey) : privateKey,
-    type: "app_key",
+    payload,
+    signer: {
+      type: "app_key",
+      appKey,
+    },
+    signMessage: signMessageWithAppKey(privateKey),
   });
 
   const response = await fetch(webhookUrl, {
@@ -52,11 +53,11 @@ export async function sendEvent(
       "Content-Type": "application/json",
     },
     body: JSON.stringify(
-      signature satisfies EncodedJsonFarcasterSignatureSchema
+      signature.json satisfies EncodedJsonFarcasterSignatureSchema
     ),
   });
 
-  if (response.status >= 200 && response.status < 300) {
+  if (response.ok) {
     return;
   }
 

packages/frames.js/src/farcaster-v2/json-signature.test.ts

@@ -1,4 +1,8 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment -- for expect.any() */
+import * as ed25519 from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import type { Hex } from "viem";
+import { bytesToHex, hexToBytes } from "viem";
 import {
   sign,
   verify,
@@ -8,10 +12,16 @@ import {
   encodeSignature,
   decodeHeader,
   decodePayload,
-  decodeSignature,
+  decodeCustodyTypeSignature,
+  decodeAppKeyTypeSignature,
   constructJSONFarcasterSignatureAccountAssociationPaylod,
+  signMessageWithAppKey,
 } from "./json-signature";
 
+process.env.NEYNAR_API_KEY = "NEYNAR_FRAMES_JS";
+
+ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
+
 const fcDemoSignature = {
   header:
     "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
@@ -33,58 +43,144 @@ const framesJsDemoSignature = {
 const framesJsDemoCompactSignature =
   "eyJmaWQiOjM0MTc5NCwidHlwZSI6ImN1c3RvZHkiLCJrZXkiOiIweDc4Mzk3RDlEMTg1RDNhNTdEMDEyMTNDQmUzRWMxRWJBQzNFRWM3N2QifQ.eyJkb21haW4iOiJmcmFtZXNqcy5vcmcifQ.MHgwOWExNWMyZDQ3ZDk0NTM5NWJjYTJlNGQzNDg3MzYxMGUyNGZiMDFjMzc0NTUzYTJmOTM2NjM3YjU4YTA5NzdjNzAxOWZiYzljNGUxY2U5ZmJjOGMzNWVjYTllNzViMTM5Zjg3ZGQyNTBlMzhkMjBmM2YyZmEyNDk2MDQ1NGExMjFi";
 
-const signatures = [framesJsDemoSignature, fcDemoSignature];
+const custodySignatures = [framesJsDemoSignature, fcDemoSignature];
 
-const compactSignatures = [
+const dummyAppKeySignature = {
+  header:
+    "eyJmaWQiOjM0MTc5NCwidHlwZSI6ImFwcF9rZXkiLCJrZXkiOiIweGJkZGVhNDQ2ODUxZDYwZjQ4OTAxNjU1NDc4YTIwNTQ3MmNjOTJmNGUwMzdiNTIzNmE1YzVhYmZjMWI4ZTA5MWIifQ",
+  payload: "eyJ0ZXN0Ijp0cnVlfQ",
+  signature:
+    "Y1C9-m6EIAPDqd8-2NrSXBKrpvWKUfA3Qjy865De5yUu7MV_b1TjsQKtwqbaVv_UzFz5ghmvygVbGjhx-kbRDw",
+};
+
+const dummyAppKeyCompactSignature = `${dummyAppKeySignature.header}.${dummyAppKeySignature.payload}.${dummyAppKeySignature.signature}`;
+const appKeySignatures = [dummyAppKeySignature];
+
+const custodyCompactSignatures = [
   framesJsDemoCompactSignature,
   fcDemoCompactSignature,
 ];
+const appKeyCompactSignatures = [dummyAppKeyCompactSignature];
 
 describe("verifyCompact", () => {
-  it.each(compactSignatures)("verifies valid message", async (signature) => {
-    await expect(verifyCompact(signature)).resolves.toBe(true);
+  describe("custody", () => {
+    it.each(custodyCompactSignatures)(
+      "verifies valid message",
+      async (signature) => {
+        await expect(verifyCompact(signature)).resolves.toBe(true);
+      }
+    );
+  });
+
+  describe("app_key", () => {
+    it.each(appKeyCompactSignatures)(
+      "verifies valid message",
+      async (signature) => {
+        await expect(verifyCompact(signature)).resolves.toBe(true);
+      }
+    );
   });
 });
 
 describe("verify", () => {
-  it.each(signatures)("verifies valid message", async (signature) => {
-    await expect(verify(signature)).resolves.toBe(true);
+  describe("custody", () => {
+    it.each(custodySignatures)("verifies valid message", async (signature) => {
+      await expect(verify(signature)).resolves.toBe(true);
+    });
+  });
+
+  describe("app_key", () => {
+    it.each(appKeySignatures)("verifies valid message", async (signature) => {
+      await expect(verify(signature)).resolves.toBe(true);
+    });
   });
 });
 
 describe("sign", () => {
-  it("signs any payload", async () => {
-    const signature = await sign({
-      fid: 1,
-      payload: { test: true },
-      signer: {
-        type: "custody",
-        custodyAddress: "0x1234567890abcdef1234567890abcdef12345678",
-      },
-      signMessage: (message) => {
-        expect(typeof message === "string").toBe(true);
-        expect(message.length).toBeGreaterThan(0);
+  describe("custody", () => {
+    it("signs any payload", async () => {
+      const signature = await sign({
+        fid: 1,
+        payload: { test: true },
+        signer: {
+          type: "custody",
+          custodyAddress: "0x1234567890abcdef1234567890abcdef12345678",
+        },
+        signMessage: (message) => {
+          expect(typeof message === "string").toBe(true);
+          expect(message.length).toBeGreaterThan(0);
 
-        return Promise.resolve("0x0000000");
-      },
-    });
+          return Promise.resolve("0x0000000");
+        },
+      });
 
-    expect(signature).toMatchObject({
-      compact: expect.any(String),
-      json: {
-        header: expect.any(String),
-        payload: expect.any(String),
-        signature: expect.any(String),
-      },
+      expect(signature).toMatchObject({
+        compact: expect.any(String),
+        json: {
+          header: expect.any(String),
+          payload: expect.any(String),
+          signature: expect.any(String),
+        },
+      });
+
+      expect(decodePayload(signature.json.payload)).toEqual({ test: true });
+      expect(decodeHeader(signature.json.header)).toEqual({
+        fid: 1,
+        type: "custody",
+        key: "0x1234567890abcdef1234567890abcdef12345678",
+      });
+      expect(decodeCustodyTypeSignature(signature.json.signature)).toEqual(
+        "0x0000000"
+      );
     });
+  });
 
-    expect(decodePayload(signature.json.payload)).toEqual({ test: true });
-    expect(decodeHeader(signature.json.header)).toEqual({
-      fid: 1,
-      type: "custody",
-      key: "0x1234567890abcdef1234567890abcdef12345678",
+  describe("app_key", () => {
+    it("signs any payload", async () => {
+      const privateKey = ed25519.utils.randomPrivateKey();
+      let messageSignature: Hex = "0x";
+      const signature = await sign({
+        fid: 1,
+        payload: { test: true },
+        signer: {
+          type: "app_key",
+          appKey: bytesToHex(ed25519.getPublicKey(privateKey)),
+        },
+        signMessage: (message) => {
+          expect(typeof message === "string").toBe(true);
+          expect(message.length).toBeGreaterThan(0);
+
+          messageSignature = bytesToHex(
+            ed25519.sign(Buffer.from(message, "utf-8"), privateKey)
+          );
+
+          return Promise.resolve(messageSignature);
+        },
+      });
+
+      expect(signature).toMatchObject({
+        compact: expect.any(String),
+        json: {
+          header: expect.any(String),
+          payload: expect.any(String),
+          signature: expect.any(String),
+        },
+      });
+
+      expect(Buffer.from(signature.json.signature, "base64url")).toHaveProperty(
+        "byteLength",
+        64
+      );
+      expect(decodePayload(signature.json.payload)).toEqual({ test: true });
+      expect(decodeHeader(signature.json.header)).toEqual({
+        fid: 1,
+        type: "app_key",
+        key: bytesToHex(ed25519.getPublicKey(privateKey)),
+      });
+      expect(decodeAppKeyTypeSignature(signature.json.signature)).toEqual(
+        messageSignature
+      );
     });
-    expect(decodeSignature(signature.json.signature)).toEqual("0x0000000");
   });
 });
 
@@ -140,17 +236,77 @@ describe("decodePayload", () => {
 
 describe("encodeSignature", () => {
   it("encodes signature", () => {
-    const value = encodeSignature("0x0000000");
+    const input = "0x0000000";
+    const value = encodeSignature(Buffer.from("0x0000000", "utf-8"));
 
     expect(typeof value).toBe("string");
+    expect(Buffer.from(input, "utf-8").toString("base64url")).toEqual(value);
+  });
+
+  it("encodes signature as Buffer", () => {
+    const input = hexToBytes("0x0000001");
+    const value = encodeSignature(Buffer.from(input));
+
+    expect(Buffer.from(input).toString("base64url")).toEqual(value);
+  });
+});
+
+describe("decodeAppKeyTypeSignature", () => {
+  it("decodes signature (string)", () => {
+    const buf = Buffer.from("0x0000000", "utf-8");
+    const encodedSignature = encodeSignature(buf);
+    const value = decodeAppKeyTypeSignature(encodedSignature);
+
+    expect(value).toBe(bytesToHex(buf));
+  });
+
+  it("decodes signature (from buffer)", () => {
+    const input = hexToBytes("0x0000001");
+    const encodedSignature = encodeSignature(Buffer.from(input));
+    const value = decodeAppKeyTypeSignature(encodedSignature);
+
+    expect(value).toBe(bytesToHex(input));
+  });
+});
+
+describe("decodeCustodyTypeSignature", () => {
+  it("decodes signature (string)", () => {
+    const buf = Buffer.from("0x0000000", "utf-8");
+    const encodedSignature = encodeSignature(buf);
+    const value = decodeCustodyTypeSignature(encodedSignature);
+
+    expect(value).toBe(buf.toString("utf-8"));
+  });
+
+  it("decodes signature (from buffer)", () => {
+    const input = "0x0000001";
+    const encodedSignature = encodeSignature(Buffer.from(input, "utf-8"));
+    const value = decodeCustodyTypeSignature(encodedSignature);
+
+    expect(value).toBe(input);
   });
 });
 
-describe("decodeSignature", () => {
-  it("decodes signature", () => {
-    const encodedSignature = encodeSignature("0x0000000");
-    const value = decodeSignature(encodedSignature);
+describe("signMessageWithAppKey", () => {
+  it("signs any payload", async () => {
+    const privateKey = ed25519.utils.randomPrivateKey();
+    const signature = await sign({
+      fid: 1,
+      payload: { test: true },
+      signer: {
+        type: "app_key",
+        appKey: bytesToHex(ed25519.getPublicKey(privateKey)),
+      },
+      signMessage: signMessageWithAppKey(privateKey),
+    });
 
-    expect(value).toBe("0x0000000");
+    expect(signature).toMatchObject({
+      compact: expect.any(String),
+      json: {
+        header: expect.any(String),
+        payload: expect.any(String),
+        signature: expect.any(String),
+      },
+    });
   });
 });