mirror of
https://github.com/PR0M3TH3AN/bitlogin.git
synced 2026-10-27 08:31:21 +00:00
thePR0M3TH3ANandClaude Fable 5
b414cc53d2
An adversarial audit (five independent reviewers over crypto/protocol, the vault, the widget, relay flows, and doc honesty) found real bugs in code this repo shipped. Fixed here, worst first: CRITICAL - the widget worker ignored application_binding.origin on vaultRevealNwc, so any caller naming a connection id could pull a wallet credential the user granted to a DIFFERENT site. The worker now derives its own origin (self.location) instead of trusting a payload field -- which also closes binding forgery via vaultSaveNwc / vaultSetBinding / vaultOfferCheck, where a host could bind another site's wallet to itself and inherit its one-tap approval. CRITICAL - VaultSession.destroy() left the vault root live (the root regenerates every derived key) and, worse, left the session USABLE with a zeroed prk: deriveRecordKey/deriveVaultSigningKey over 32 zero bytes are deterministic and world-computable, so a stale reference could seal a wallet secret under a key any observer can derive and report success. Now wipes the root and fails loudly. CRITICAL - changePassword published the tombstone that DESTROYS the old capsule before checking that the new one reached quorum: a failed rotation could leave neither password working, phrase-only recovery. Reordered to fail closed with the old password intact, plus a regression test that drives it with a partially-hostile relay set. HIGH - enableConnectionVault never checked quorum on the recovery read, so one stale relay could make it mint a SECOND vault root and orphan every stored credential -- the outcome its own header calls unforgivable. HIGH - the rollback high-water mark used strict `<` and never compared the event id it stored, so a same-second sibling of a revocation could resurrect a revoked credential forever. Ties now break on event id. HIGH - §11.10 claimed derived secrets are wiped; wipe() had two callers and neither was on the password or recovery path. The Argon2id output, both PRKs, and the 64-byte BIP-39 seed now die at their derivation site. MEDIUM - one malformed record threw out of the listing loop and made every OTHER connection unlistable; recovery lacked the already-registered-at-this-locator guard that registration and rotation both carry; the recovery chain check silently passed on gaps and forks. Synthetic (untrusted) clicks and submits no longer drive consent UI. Docs corrected where they overstated: the README's "private keys never leave the worker" now says plainly that a same-origin host can reach exportIdentity, and connection-vault.md gains §19 recording six OPEN limitations -- no CAS on capsule writes, per-device-only rollback state, tombstones not destroying prior ciphertext, the sudo key shipping with the root, fetches not failing closed, and a plaintext mark store. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01CMr9Yt8SYmZcfgrg3CV2G1
BitLogin Documentation
BitLogin is a static, relay-backed portable account protocol that gives users a familiar login name and password while preserving a user-controlled Nostr identity and independent phrase recovery.
This directory contains the core protocol specification, implementation notes, and experimental designs for expanding BitLogin into a portable account layer for compatible applications.
Core protocol
spec.md— canonical BitLogin protocol specificationsecond-factor.md— second-factor design notes
Portable account layer
These documents describe proposed capabilities that build on BitLogin's core identity and recovery model.
account-switching.md— multiple independent accounts on one device, fast switching, locking, logout, and account-aware signer behaviorportable-app-state.md— encrypted, user-owned application settings and lightweight state that follow the account across devicesportable-entitlements.md— discovery, verification, recovery, and presentation of purchases, licenses, memberships, and access rightsrelay-and-messaging-portability.md— relay-role management, DM inbox and outbox synchronization, sent-message recovery, and conversation reconstruction
Connection Vault
The Connection Vault stores portable application credentials outside the core
identity capsules as independently encrypted records. Its protocol layer
(records, key hierarchy, relay sync, migration, tiers) is implemented in
@bitlogin/core's src/vault/; the widget authorization layer (consent
UI, grants, Connected apps) is still to come.
connection-vault.md— overall vault architecture, key hierarchy, relay storage, authorization, recovery, and deletion; §18 records the implementation-time decisions (tier model, sudo key)vault-ux.md— the agreed user-experience walkthroughs, serving as the authorization layer's acceptance criterianwc-connections.md— Nostr Wallet Connect credential profile (parser/exporter implemented insrc/vault/nwc.ts)s3c-format.md— portables3c1:format for S3-compatible storage connections
How the pieces fit together
BitLogin account
├── Identity and recovery
│ ├── Credential capsule
│ ├── Recovery capsule
│ └── Everyday Nostr identity
│
├── Accounts and sessions
│ └── Multiple-account switching
│
├── Communication
│ ├── Relay preferences
│ ├── DM inbox synchronization
│ ├── DM outbox and sent-message recovery
│ └── Conversation reconstruction
│
├── Portable application experience
│ ├── App settings
│ ├── Saved state
│ └── Per-app authorization
│
├── Ownership
│ ├── Purchases
│ ├── Licenses
│ ├── Memberships
│ └── Access entitlements
│
└── Connection Vault
├── NWC wallet connections
├── S3-compatible storage connections
└── Future service credentials
Status terminology
Documents use these labels:
- Implemented — available in the current codebase
- Partially implemented — some required primitives or flows exist, but the complete user-facing feature does not
- Experimental design — documented for review and future implementation; wire formats and APIs may change
Experimental documents are not part of the stable BitLogin protocol until their schemas, security properties, migrations, and test vectors are finalized.
Recommended product sequence
A practical development sequence is:
- Complete the core account and messaging foundations.
- Add independent multi-account sessions and switching.
- Add relay management, inbox synchronization, and sent-message recovery.
- Add portable application state and per-app permissions.
- Add entitlement discovery and a portable ownership library.
- Implement the Connection Vault and its NWC and S3 profiles.
- Move high-value authorization into stronger extension, native, or cross-origin execution boundaries.
Design principle
BitLogin should coordinate portable identity, state, ownership, and service access without becoming the centralized custodian of the user's identity, money, files, messages, or purchases.