FIP: JSON Farcaster Signatures

[deodad]

FIP: Farcaster JSON Signatures

FIP: Farcaster JSON Signatures
Title: Farcaster JSON Signatures
Authors: @deodad

Problem

Farcaster identities don't have a standardized way to sign arbitrary payloads.

Specification

JSON Farcaster Signatures (JFS) provides a simple standard to compactly and efficiently sign JSON data. This specification is inspired by JWS but it is not a strict implementation of it.

A JFS is made up of three components:

1. Header: Contains metadata about the signature
2. Payload: The content being signed
3. Signature: The cryptographic signature

To create a JFS:

1. Construct the JFS Header consisting of an FID, key type, and key. Base64Url encode it.
2. Construct the payload and Base64Url encode it.
3. Compute the signature using the signing algorithm corresponding to the key type

For step 3, the signing input is as follows:
ASCII(BASE64URL(UTF8(Header)) || '.' || BASE64URL(Payload))

The entire JFS can then be compactly serialized as follows:
BASE64URL(header) + "." + BASE64URL(payload) + "." + BASE64URL(signature)

Alternatively the JFS can be serialized into a JSON format as follows:

{
  header, // BASE64URL(header)
  payload, // BASE64URL(payload)
  signature, // BASE64URL(signature)
}

To validate a JFS:

• Extract and decode header from the serialized representation and validate the following:
  • the fid is a valid, registered Farcaster ID
  • the key is currently active and associated with the fid
    • the type of 'custody' indicates the signature is from the custody address of the FID
    • the type of 'auth' indicates the signature is from an auth address of the FID
    • the type of 'app_key' indicates the signature is from a registered App Key for the FID
• Extract and decode signature from the serialized representation and validate the following:
  • the signature is valid and came from the specified key

Signing methods:

• custody - key is a hex string prefixed with "0x" and the signature is an ERC-191 signature from the FID's custody address.
• auth - key is a hex string prefixed with "0x" and the signature is an ERC-191 signature from a registered auth address for the FID.
• app_key - key is a hex string prefixed with "0x" and the signature is an EdDSA signature from an App Key registered to the FID.

Custody Example

Signing

1. Construct the JFS Header consisting of an FID, key type, and key. Base64Url encode it:

const header = { 
  fid, // FID of the account
  type: 'custody', 
  key // custody address of the account
};
const encodedHeader = Buffer.from(JSON.stringify(header), 'utf-8').toString('base64url');

2. Construct the payload and Base64Url encode it

const payload = { domain: 'warpcast.com' };
const encodedPayload = Buffer.from(JSON.stringify(payload), 'utf-8').toString('base64url');

3. Compute the signature using the signing algorithm corresponding to the key type and Base64Url encode it

const signature = await account.signMessage({ 
  message: `${encodedHeader}.${encodedPayload}`
});
const encodedSignature = Buffer.from(signature.slice(2), 'hex').toString('base64url');

4. Combine into the compact serialized form

// compact
const compactJfs = `${encodedHeader}.${encodedPayload}.${encodedSignature}`

// JSON
const jsonJfs = {
  header: encodedHeader,
  payload: encodedPayload,
  signature: encodedSignature
}

Validating

1. Verify the signature to recover the signing address. If message verification fails, the JFS is not valid.

const { fid, type, key } = JSON.parse(Buffer.from(encodedHeader, 'base64Url').toString('utf-8'));

if (type !== 'custody') {
  throw new Error("Invalid type")
}

const valid = await verifyMessage({ 
  address: key,
  signature: signature,
  message: encodedHeader + '.' + encodedPayload
});

if (!valid) {
  throw new Error("Invalid signature")
}

Note on legacy custody signatures
For a long time this specification incorrectly had the following example for encoding ECDSA signatures:

const signature = await account.signMessage({ 
  message: `${encodedHeader}.${encodedPayload}`
});
const encodedSignature = Buffer.from(signature, 'utf-8').toString('base64url');

The problem here is signature returned is a hex string but the Buffer interprets it as utf-8. The result is that rather than the raw bytes getting encoded, the bytes of the utf-8 bytes of that string get encoded. To accept one of these misencoded signatures you can try falling back like so:

    try {
      await verifyMessage({
        address: decoded.header.key,
        signature: decoded.signature,
        message: signingInput,
      });
      return;
    } catch (error) {
      if (!strict) {
        const utf8EncodedHexSignature = Buffer.from(decoded.signature).toString("utf-8");

        if (isHex(utf8EncodedHexSignature)) {
          await verifyMessage({
            address: decoded.header.key,
            signature: utf8EncodedHexSignature,
            message: signingInput,
          });

          return;
        }
      }

      throw error;
    }
  }

2. Query a Hub or the Farcaster ID Registry contract to confirm the custody address or auth address of the FID equals the key value specified in the header.

const { fid, type, key } = JSON.parse(Buffer.from(encodedHeader, 'base64Url').toString('utf-8'));

const resolvedCustodyAddress = '' // lookup FID's custody address

if (resolvedCustodyAddress !== key) {
  throw new Error("Wrong custody address")
}

See the @farcaster/jfs package for a NodeJS implementation.

FAQ

Is there an official library for generating and verifying JFS signatures?
Yes. Use the @farcaster/jfs package.

Can a smart contract wallet generate a JFS signature?
Yes. Custody and auth address signatures may be signed by smart contract accounts. The @farcaster/jfs package verifies smart contract signatures using a Viem public client for OP mainnet, which verifies EOA, ERC-1271, ERC-6492, and ERC-8010 signatures. Note that you may need to generate a different signature type depending on whether the signing account is deployed to OP mainnet.

Why are some signatures longer than others?
The base64 encoded JFS "signature" field is either 176 characters or 88 characters. Signatures in the 176-character format are legacy custody signatures, which encode the signature bytes as a hex string. (See "note on legacy custody signatures" above). Signatures in the shorter 88-character format encode the signature bytes directly to base64. New tooling should use the shorter 88-character format, but accept legacy signatures for backwards compatibility.

[vrypan]

Is there something we should take care of to make this interoperable between languages? (I have the protobuf serialization issue in mind, is there a danger we will have a similar issue?)

[deodad]

We won't hit those same problems since the exact payload that is signed is transmitted along with the signature. I added more details since you wrote this comment that should clarify.

[manan19]

So glad we're standardizing this

[chejazi]

Do addresses need to be checksummed or is all lower case fine?

[nounder]

Correct verification code should operate on normalized form so checksummed representation should be supported.

[nounder]

Note that JFS are not JWS. There are two main differences:

1. JFS signature is encoded as hex string, not raw bytes.
2. JFS does not contain alg header and the signing method depends on type.

See JFS implementation below that documents in-depth signature validation for both app and custody keys:

https://github.com/nounder/json-farcaster-signature/blob/master/jfs.ts

[vrypan]

Extract and decode signature from the Authorization header and validate the following

Where is the Authorization header? I guess this is just the signature component of the JSON?

[deodad]

yes, the signature component of however the JFS is encoded.

will update to remove Authorization header, this is a relic from a previous version of this doc where we specifically gave an example of using this as a Bearer token

[MikeSofaer]

Is this something that could be done in Warpcast, or would we be expected to create a new Farcaster account using a terminal to host frames?

[chejazi]

You don't need to create another account.

You do need to use your custody address key.
You likely do need to use a terminal (there are no tools to automate this, as of Feb 2025).

[vrypan]

If you refer to obtaining an AppKey to be used to generate the signature, you can use https://github.com/stevedylandev/cast-keys if it's a one-off.

You can also programmatically generate an AppKey (used to be called a "Signer" if you check older docs), see https://docs.farcaster.xyz/developers/guides/accounts/create-account-key

[ic]

Is there a reference on "Compute the signature using the algorithm corresponding to the key" ? I have a custody address, but unclear what signing algorithm applies.

Perhaps missing a link?