Napplet Handler Preferences

This NIP defines an addressable event that records which napplets a user prefers to handle an archetype's intents. Shells use it to sync default handlers across devices and runtimes. Other users read its public entries as recommendations.

Napplets, manifests, archetypes, and convention identities are defined by NIP-5D. Handler resolution is defined by NAP-INTENT.

Event#

Kind 31129 is an addressable event. A user publishes one event per archetype.

{
  "kind": 31129,
  "pubkey": "<user pubkey>",
  "tags": [
    ["d", "profile"],
    ["a", "35129:<pubkey>:<d>", "wss://relay.example.com"],
    ["e", "<5129 snapshot id>", "wss://relay.example.com", "<pubkey>"],
    ["a", "15129:<pubkey>:"],
    ["i", "napplet:profile/edit", "35129:<pubkey>:<d2>"]
  ],
  "content": "<NIP-44 encrypted private entries, or empty>"
  // other fields...
}

Tags#

Tag	Form	Meaning
d	["d", "<archetype>"]	The archetype slug. Compared by exact equality.
a	["a", "<coordinate>", "<relay>"?]	Archetype-wide preference for a napplet, following its latest manifest.
e	["e", "<snapshot id>", "<relay>"?, "<pubkey>"?]	Archetype-wide preference for one pinned napplet version.
i	["i", "napplet:<archetype>/<intent>", "<ref>"]	Intent-specific preference. The second element is a stable convention identity.

• <coordinate> MUST be a named (35129:<pubkey>:<d>) or root (15129:<pubkey>:) napplet manifest address.
• <snapshot id> MUST be the id of a kind 5129 snapshot manifest. <pubkey> is its author.
• <ref> is either a <coordinate> or a <snapshot id>.
• <relay> is an optional discovery hint. It is not part of the napplet identity.
• An i convention identity MUST be queryless and fragment-free, and its archetype segment MUST equal the d value. Shells MUST ignore an i tag that fails either rule.
• Order is preference. Among a and e tags together, the first is preferred, and later ones are fallbacks. Among i tags with the same convention identity, the same rule applies.
• Shells MUST ignore unknown tags and malformed entries without discarding the event.

Versions#

An a reference follows the napplet: the shell uses the manifest that is current for the coordinate. An e reference pins a version. A snapshot is a regular event, so its id stays resolvable after the napplet updates.

Pins MUST reference snapshots. The id of a 15129 or 35129 manifest MUST NOT be used as a pin: relays retain only the latest replaceable or addressable event, so an older id becomes unresolvable.

A snapshot's a and A lineage tags are provenance only, per NIP-5D. A shell MUST NOT treat a pinned snapshot as the named napplet it derives from, or the reverse.

Locating referenced napplets#

An i tag carries no relay hint. A shell locates <ref> in this order:

1. The relay hint of an a or e tag in the same event with the same reference.
2. For a coordinate, the NIP-65 write relays of its pubkey.
3. For a snapshot id, the NIP-65 write relays of the author named by a matching e tag, then the shell's own relays.

Private entries#

Private entries use the same a, e, and i tag forms. They are encoded as a JSON array of tags, encrypted with NIP-44 to the author's own pubkey, and stored in content, as in NIP-51. content is empty when there are no private entries.

Public entries are recommendations visible to anyone. Private entries are visible only to the author.

Resolution#

A shell resolving a handler for an invocation of napplet:<archetype>/<intent> reads the user's event whose d is <archetype>. It considers candidates in this order:

1. Private i entries matching the convention identity.
2. Public i entries matching the convention identity.
3. Private a and e entries.
4. Public a and e entries.

Within each group, tag order applies. The first candidate that is usable becomes the user's default handler. A candidate is usable when it is installed, its verified manifest advertises the requested convention for the archetype, and shell policy permits it. Convention matching uses exact equality.

The preference only names a handler. It MUST NOT grant capabilities, bypass manifest verification, or authorize installation. A shell MAY offer to install an uninstalled candidate under its ordinary installation policy.

When no candidate is usable, the shell falls back to its normal resolution or user choice.

Recommendations from others#

A shell MAY read other users' public a, e, and i entries, for example from the user's follows, to suggest handlers in a chooser or install prompt. Another user's event MUST NOT set the user's default handler.

Publishing#

• Only the user's shell publishes this kind on the user's behalf, in response to the user's choice.
• Shells SHOULD publish to the user's NIP-65 write relays and read from them.
• Shells MUST verify the event signature and that the author is the user before applying it.
• Deleting all entries of an archetype MAY publish an event with no a, e, or i tags and empty content, or a NIP-09 deletion of the address.

Security Considerations#

• Napplet tampering. Default-handler state belongs to the user. A shell MUST NOT let a napplet publish kind 31129 or decrypt its content through relay, signing, or encryption capabilities, unless the user explicitly grants that napplet handler-preference management. Otherwise a napplet could silently redirect another archetype's intents to itself.
• Hostile recommendations. Public entries from others are untrusted input. They can suggest a handler. They cannot select one.
• Metadata leakage. The d tag is public. An event whose entries are all private still reveals that the user set preferences for that archetype.