bitvid/docs/nostr-auth.md

Nostr authentication storage

Bitvid keeps lightweight state in localStorage so the UI can remember which accounts signed in recently. This document explains the storage schema so future updates can evolve it without breaking existing users.

Storage keys

• bitvid:profileCache:v1 – short-lived metadata cache for profile names and avatars. See js/app.js for TTL and eviction rules.
• bitvid:savedProfiles:v1 – persistent list of accounts the user authenticated with in this browser. The payload embeds a version field that is currently 2.

Both keys live in the main origin scope. Clearing one should not affect the other.

Saved profile schema

bitvid:savedProfiles:v1 is a JSON object with the shape:

{
  "version": 2,
  "entries": [
    {
      "pubkey": "<hex-encoded pubkey>",
      "npub": "<bech32 npub, optional>",
      "name": "<cached display name>",
      "picture": "<cached avatar URL>",
      "authType": "<auth strategy or null>"
    }
  ],
  "activePubkey": "<hex pubkey or null>"
}

Notes:

• pubkey always stores a lowercase 64-character hex string and is the primary dedupe key.
• npub is optional. When omitted, the UI regenerates it on load using NostrTools.nip19.npubEncode.
• name and picture are cached hints that keep the profile switcher snappy. They may be empty strings and should be treated as hints, not the source of truth.
• activePubkey tracks the last account that successfully authenticated in this browser. It may be null when the user logs out but keeps saved entries.

authType handling

authType describes how the profile authenticated and is stored exactly as the provider reported it (after trimming whitespace). Bitvid does not attempt to normalise these strings, so future auth integrations can safely persist custom identifiers.

• Legacy payloads (version 1) did not include the field, so the loader treats those entries as "nip07" and rewrites the payload at version 2.
• Newer providers may surface alternative IDs (for example, Wallet Connect flows). UI components use provider metadata when available and otherwise fall back to a generic label so unknown identifiers do not break rendering.

Migration notes

Earlier builds only persisted a single userPubKey string. During startup the app now:

1. Attempts to read bitvid:savedProfiles:v1 and validate the payload.
2. If the key is missing (or malformed) but a legacy userPubKey entry exists, it seeds savedProfiles with that value and writes the new structure.
3. Once the JSON payload is written successfully, the legacy userPubKey entry is removed.

Future migrations should follow the same pattern: validate, normalise, write the new format, then clean up legacy keys to avoid data loss.