mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-11-04 20:02:26 +00:00
76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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.
|