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 a Farcaster specific implementation of JWS.

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 consistent of an FID, key type, and key and Base64Url encode it
2. Construct the payload and Base64Url encode it
3. Compute the signature using the algorithm corresponding to the key

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 'app_key' indicates the signature is from a registered App Key for the FID
• Extract and decode signature from the Authorization header and validate the following:
  • the signature is valid and came from the specified key

Signing methods:

• custody - key is an ERC-191 signature from the FID's custody address
• app_key - key is an EdDSA signature from an App Key registered to the FID

Custody Example

Signing

1. Construct the JFS Header consistent of an FID, key type, and key and 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 algorithm corresponding to the key and Base64Url encode it

const signature = await account.signMessage({ 
  message: `${encodedHeader}.${encodedPayload}`
});
const encodedSignature = Buffer.from(signature, 'utf-8').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")
}

2. Query a Hub or the Farcaster ID Registry contract to confirm the custody 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")
}

[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?