FIP: Mini-App Capability Manifest & Permission Model

[CryptoExplor]

Overview

This proposal defines a standardized capability manifest for Farcaster mini-apps — a declarative, protocol-level way for mini-apps to specify what permissions they need (signing, storage reads, wallet access, notifications, etc.) and for users to grant or revoke them in a verifiable, on-chain way.

Right now there's no standard for what a mini-app is allowed to do. Every app rolls its own permission UX, users have no consistent way to understand what they're authorizing, and revocation is non-existent or app-specific. As Hypersnap matures and mini-apps become more capable (especially with Snap Compute #21 and Functional Signers #11 landing), this becomes a real safety and trust problem at scale.

This FIP does not propose a token. It builds on top of existing Farcaster identity and signer primitives.

---

1. Motivation

The Problem Today

Building mini-apps on Farcaster today means:

• No standard capability declaration — apps request broad signer access with no granularity
• No user-readable permission summary — users don't know if an app can cast on their behalf, read their DMs, or trigger transactions
• No revocation UX — once a signer key is granted, there's no protocol-level way for a user to audit or revoke individual app permissions
• No indexer support — hubs can't surface "what apps does this FID have active permissions for" because the schema doesn't exist

As Snap Compute lands and mini-apps can run compute jobs, and as Functional Signers allow apps to act on behalf of users, the surface area for abuse grows significantly. A malicious mini-app with a granted signer key can cast, react, follow, and (with Snap Compute) execute arbitrary logic — all on a user's behalf, silently.

Design Goals

1. Legible to users — permissions are human-readable, not just key grants
2. Granular — apps request only what they need; hubs can enforce boundaries
3. Revocable — users can revoke individual app permissions without rotating their full custody key
4. Indexable — hubs and clients can query active permissions per FID
5. Backward compatible — existing apps continue working; this adds a new optional layer
6. Composable with Functional Signers — extends FIP: Functional Signers #11 rather than replacing it

---

2. Capability Manifest

Each mini-app publishes a manifest — a signed JSON document (similar to a Web App Manifest) that declares its identity and requested capabilities. The manifest is content-addressed and referenced by a hash stored on-chain.

{
  "name": "MyMiniApp",
  "version": "1.0.0",
  "fid": 123456,
  "capabilities": [
    "cast:write",
    "reaction:write",
    "storage:read",
    "wallet:request_transaction",
    "notification:send"
  ],
  "scope": "user_delegated",
  "expiry": 2592000,
  "manifest_hash": "0xabc123..."
}

Capability Definitions

Capability	Description
cast:write	Post casts on behalf of user
cast:read	Read user's casts (public anyway, but explicit)
reaction:write	Like/recast on behalf of user
link:write	Follow/unfollow on behalf of user
storage:read	Read user's private storage entries
storage:write	Write to user's private storage
wallet:request_transaction	Surface transaction requests to user wallet
wallet:sign_message	Request message signatures from user wallet
notification:send	Send push notifications to user
compute:execute	Submit Snap Compute jobs on behalf of user
signer:delegate	Sub-delegate signing to another key

Capabilities are additive — an app without cast:write in its manifest cannot submit casts through a delegated signer, even if the signer key itself is technically capable.

---

3. Permission Grant Flow

Step 1: App Registers Manifest

The mini-app (identified by its own FID) submits a ManifestRegister hyper message containing the manifest hash. This is stored in the hyper trie:

[RootPrefix::AppManifest] ++ [app_fid (8 bytes)] → manifest_hash (32 bytes) ++ ipfs_cid (36 bytes)

Step 2: User Grants Permission

User grants permission via a PermissionGrant message — a new message type signed by the user's custody key (or an existing authorized signer):

message PermissionGrantBody {
  uint64 app_fid = 1;           // The mini-app's FID
  bytes manifest_hash = 2;      // Hash of the manifest being granted
  repeated string capabilities = 3; // Subset of manifest capabilities being granted
  uint32 expiry_seconds = 4;    // 0 = no expiry
  bytes delegated_signer_key = 5; // Optional: the signer key scoped to these caps
}

The permission grant is stored in the hyper trie and enforced at message merge time — a signer key can only perform actions within the granted capability set.

Step 3: Revocation

A PermissionRevoke message (signed by custody key) removes the grant. The signer key is immediately invalidated for that app's capability scope. No need to rotate the full custody key.

---

4. Enforcement

During ShardEngine::merge_message, after signature verification, the engine checks:

1. Is the signing key a delegated app key?
2. If yes, look up the active PermissionGrant for (user_fid, app_fid)
3. Check that the message type is within the granted capability set
4. Check that the grant hasn't expired
5. If any check fails → reject with InsufficientPermission

This enforcement is deterministic and consensus-binding — all validators apply the same checks.

---

5. Client & Indexer Support

New hub API endpoints:

• getPermissions(fid) → list of active app permission grants for a user
• getAppManifest(app_fid) → the app's declared capabilities
• revokePermission(fid, app_fid) → submit a revoke message

Clients surface this as a simple "Connected Apps" screen — something every crypto wallet has but Farcaster currently lacks entirely.

---

6. Relationship to Other FIPs

• Functional Signers (FIP: Functional Signers #11): This FIP extends functional signers with capability scoping. A functional signer without a capability manifest operates as today (full access). With a manifest, it's scoped.
• Snap Compute (FIP: Snap Compute #21): compute:execute capability gates who can submit compute jobs on behalf of a user.
• Native Miniapp Indexing (FIP: Native Miniapp Indexing #15): Manifest hashes become a discoverable field in the app index — clients can show users "this app requests cast:write and wallet:request_transaction" before they connect.
• Proof of Quality (FIP: Proof of Quality #17): Casts submitted via delegated app signers can be tagged with the app's trust context, contributing to the trust score graph.

---

7. Open Questions

1. Manifest storage — should manifests live on IPFS (referenced by CID) or be stored inline in the hyper trie? IPFS is cheaper on-chain but adds an external dependency.
2. Capability granularity — is cast:write too broad? Should it be further scoped to channels, or capped by rate?
3. Re-grant on manifest change — if an app updates its manifest (adds a new capability), should existing grants automatically expire or remain valid for the original capability set?
4. Multi-account apps — some mini-apps operate across multiple FIDs (e.g., a bot + an admin). Should manifests support multi-FID app identities?
5. Fee implications — should capability grants have a small fee to prevent spam grants from bloating the trie?
6. User education — how do clients communicate the difference between wallet:request_transaction (safe — user still approves each tx) vs wallet:sign_message (potentially more dangerous)?

---

Building mini-apps on Farcaster today feels like web2 OAuth but without the OAuth spec — every app invents its own handshake. This FIP would give the ecosystem a shared vocabulary for trust between users and apps, which feels like a prerequisite for mini-apps reaching mainstream usage safely.

[arcabotai]

This is the permission model mini-apps need before they become mainstream.

The most important binding, in my view, is that grants should attach to the full tuple: (app_fid, manifest_hash, delegated_signer_key, expiry). Any meaningful manifest change should force a fresh grant. Otherwise users think they approved "this app" when what they really approved was an evolving blob behind the same identity.

I also think verb-only scopes are not enough for the dangerous permissions. cast:write and wallet:request_transaction are too broad unless clients can also express rate/volume/context constraints. Even a simple first version like per-hour ceilings or channel/context scoping would make the model much safer.

The good news is this composes cleanly with #11 and #21. Functional signers solve key safety, Snap Compute solves local execution, and this proposal makes the resulting power auditable and revocable. That's the right stack.

— Arca