bitvid/docs/nip46-remote-signers.md

NIP-46 Remote Signer Integration

bitvid can delegate event signing to a remote NIP-46 compatible signer. This flow lets operators keep long-lived keys on hardened devices while approving publish/edit/delete actions from a separate browser session.

Connection workflow

Client-initiated handshake (preferred)

When an operator chooses the remote signer option, bitvid now generates a fresh nostrconnect:// URI and displays it alongside a QR code. The URI encodes:

• A short-lived client key pair dedicated to the session.
• The default WSS relay bundle (wss://relay.damus.io, wss://nos.lol, wss://relay.snort.social, wss://relay.primal.net, wss://relay.nostr.band).
• A random secret value that must be echoed back by the signer to prevent spoofed acknowledgements.
• Optional metadata (name, url, image) so the signer can display the client branding during pairing.
• Optional perms requested by the client.

Remote signers should scan the QR code or otherwise receive the nostrconnect:// link, subscribe to the advertised relays, and respond with a connect acknowledgement signed by the remote signer key. The response must include the secret value that was present in the URI. bitvid listens for this acknowledgement before attempting the RPC connect call so operators see a clear “waiting for signer” status in the modal.

Fallback bunker links

Some signers still distribute bunker:// URIs that point to the remote signer pubkey. The modal keeps a “paste bunker link” toggle so operators can supply the URI manually when QR pairing isn’t available. These URIs can advertise the same relay=, secret=, perms=, name, url, and image parameters described above. If no relays are specified the default bundle listed earlier is used.

Recent remote signers also append a remote-signer-key= parameter that identifies the key the bunker uses for encrypted RPC traffic. The hostname/path may now refer to the user pubkey instead of the signer key, so clients must:

1. Decrypt handshake acknowledgements with the remote-signer-key when provided, falling back to the event author as a legacy escape hatch.
2. Continue calling get_public_key after the connect RPC to learn the user pubkey rather than trusting the bunker URI host.

bitvid automatically persists both the signer key and the user pubkey returned by get_public_key so reconnect flows display accurate metadata.

Relay requirements

The remote signer must subscribe to kind 24133 events targeted at the client public key (included in the connection URI). bitvid publishes RPC requests to whichever relay list resolves from the URI + local fallback:

1. Explicit relay= parameters from the bunker URI (WSS only, duplicates removed and sanitized).
2. The relays persisted in a previous session, if any.
3. The default bitvid relay set listed above.

For reliable operation:

• Keep at least two relays online so publish attempts succeed within the 8 second relay publish timeout.
• Ensure every relay allows inbound events from both the browser’s IP and the remote signer. Corporate VPNs and Tor bridges frequently block public WSS relays.
• Avoid private relays that block unsigned events from unknown clients; the browser session publishes unsigned requests that the signer decrypts with the shared secret.

RPC expectations and timeouts

The RPC client issues the following methods:

• connect (optionally with secret and perms)
• get_public_key
• sign_event for publish/edit/delete flows

Each request is encrypted to the signer and published to the resolved relay set. bitvid waits up to 8 seconds for a relay to accept the event and up to 15 seconds for a response. sign_event calls allow up to 20 seconds before timing out. On transient failures the client retries once (except when the signer returns an authentication URL).

If the signer responds with error: auth_url, the UI surfaces the provided URL so the user can complete any additional verification the signer requires.

Session persistence and restoration

Successful connections write a session blob to localStorage under the key bitvid:nip46:session:v1. The payload includes the client key pair, remote pubkey, relay list, metadata, permissions, and the most recent user pubkey returned by the signer.

On page load bitvid reads the stored session, updates the login modal to show a saved signer, and silently attempts to reconnect in the background. If the attempt fails due to network timeouts or temporary relay outages the stored session remains intact so the user can retry manually. Fatal errors (for example shared secret mismatches) clear the saved session automatically. Users can also invoke “Disconnect” from the login modal to remove the stored credentials.

Operational checklist

• Issue bunker URIs that list WSS relays reachable by both the signer and the browser session.
• Keep the signer online and subscribed to kind 24133 events for the advertised relays.
• Respond to connect, get_public_key, and sign_event requests within the timeouts above.
• Rotate secrets or permissions as needed—bitvid surfaces signer metadata so operators can confirm which device they are connecting to before approving new sessions.