OptionalaclACL policy for identities with no stored entry. 'restrictive' starts them
with nothing granted. When omitted, the policy is 'permissive' unless
persisted ACL state stores another one. When set, it replaces the policy in
persisted state on load. Stored entries are kept as they are, so a host
moving to 'restrictive' should clear entries it no longer trusts. With
permissions set it's a ceiling: an approval can't exceed what the ACL denies,
and no prompt is shown for it.
OptionalbleOptional shell-mediated BLE backend (NAP-BLE). When present and
isAvailable() is true, the shell advertises ble. The host still
registers the concrete service via registerService('ble').
OptionalcapabilitiesOptional capability advertisement override. Omitted by production hosts.
OptionalcommonOptional shell-mediated common social backend (NAP-COMMON). When present
and isAvailable() is true, the shell advertises common. The host still
registers the concrete service via registerService('common').
OptionaldmOptionalfilterDecides what happens to each NAP envelope from a bound port, before the
runtime sees it. onNappletMessage still observes every envelope first. A
filter that throws or returns an unknown value drops the envelope.
shell.ready never reaches this hook, because NAP-SHELL requires its first
shell.init reply. While envelopes are deferred, a later dispatch decision
joins the queue so it can't overtake them, and drop still discards. A window
holding more than MAX_DEFERRED_MESSAGES is revoked with deferred-overflow.
Spec gap: NAP docs don't define a request that a host holds or drops. A dropped request gets no reply, and a deferred one gets its reply on release.
The napplet window that sent the envelope
The envelope received on the bound port
The decision for this envelope
OptionalgetReports whether a napplet window has focus. Without it, every window counts
as focused, so unfocusedMultiplier never applies. Focus only scales rate
budgets and never blocks a message by itself. The legacy gate and the
permissions budgets both use it.
The napplet window to query
Current focus state and optional milliseconds since focus was gained
OptionalintentOptional archetype intent dispatcher (NAP-INTENT). When present and
isAvailable() is true, the shell advertises the intent domain so
napplets can call window.napplet.intent. The host still registers the
concrete service via registerService('intent').
OptionallegacySupplies optional legacy behavioral controls. Its config persistence belongs to
the supplied adapter. Without an adapter no temporal limits are installed.
Legacy gate only: with permissions set, grants use permissions.persistence.
OptionallinkOptional shell-mediated link backend (NAP-LINK). When present and
isAvailable() is true, the shell advertises link. The host still
registers the concrete service via registerService('link').
OptionallistsOptional shell-mediated NIP-51 list backend (NAP-LISTS). When present and
isAvailable() is true, the shell advertises lists. The host still
registers the concrete service via registerService('lists').
OptionalllmOptional NAP-LLM wiring state. When omitted, a registered llm service is
advertised as supported; when present, isAvailable() gates advertisement
and isConfigured() feeds the host's unconfigured indicator.
OptionalonCalled on every ACL enforcement check. Both allows and denials are reported.
OptionalonCalled when the runtime firewall flags, rejects or prompts for a message, so
a host can show the user what was refused. Passing messages without a flag
are not reported. Legacy gate only: with permissions set, the approval UI
sees refusals and permissions.onRateLimit reports budget events.
OptionalonCalled when aggregate hash verification fails (computed != declared).
OptionalonObserve-only: called with each NAP envelope received on a napplet's bound
NIP-5D port, before the shell dispatches it. NIP-5D moves NAP traffic off
window-level message events, so hosts that logged or tracked readiness
from those events use this hook instead. It cannot change or drop the
message; host hook errors are swallowed.
OptionalonCalled once when the shell revokes a NIP-5D napplet binding: a second
napplet.hello, any other window-level message, an invalid hello, a
second iframe load (see ShellBridge.observeFrame), the port closing,
or ShellBridge.revokeNapplet. The shell has already closed the port and
revoked the identity binding, sessions and grants. NIP-5D requires the
host to remove the iframe here; it MAY create a fresh iframe from the
verified bytes but MUST NOT reuse this one.
OptionalonCalled at iframe creation for NIP-5D napplets. Returns identity metadata for originRegistry.register(). Returning null means "not NIP-5D / skip registration".
OptionalonCalled when ShellBridge.handleMessage drops an incoming postMessage because
it cannot be routed to a registered napplet window (no source window, or the
source Window is not in originRegistry). Observe-only — the message is
still dropped; this hook exists so otherwise-silent drops are diagnosable
(the FEED-02 / hyprgate#21 class of "a napplet's messages vanish" bug).
OptionalpermissionsShared runtime approval UI/storage and temporal adapters.
OptionalserialOptional shell-mediated serial backend (NAP-SERIAL). When present and
isAvailable() is true, the shell advertises serial. The host still
registers the concrete service via registerService('serial').
OptionalservicesOptional service extensions. Each key is a service name (e.g., 'audio', 'notifications'). Napplets discover available services via kind 29010 service discovery events.
The runtime copies this object when createShellBridge() runs. A handler
added later is neither routed nor advertised until it is also registered
with bridge.runtime.registerService().
OptionaluploadOptional shell-mediated upload backend (NAP-UPLOAD). When present, the shell
advertises the upload domain so napplets can call window.napplet.upload.
The host still registers the concrete service via registerService('upload').
OptionalwebrtcOptional shell-mediated WebRTC backend (NAP-WEBRTC). When present and
isAvailable() is true, the shell advertises webrtc. The host still
registers the concrete service via registerService('webrtc').
All adapters that the shell requires from the host application.
Example