thePR0M3TH3ANandClaude Fable 5
a465e1d8fa
connection-vault.md 5-13 as code, with the implementation-time decisions recorded in a new section 18 and vault-ux.md holding the agreed UX walkthroughs as the authorization layer's acceptance criteria. Capsules gain paired optional fields connection_vault_root and vault_sudo_key (both or neither, validated); registration mints them, login/change-password/recovery carry them forward, and enableConnectionVault is the phrase-gated migration for existing accounts -- recovery capsule written first, fail closed, idempotent by reusing roots found in either capsule so a partial failure can never mint twice and strand records. src/vault/ holds the finalized key hierarchy (HKDF/ScalarExpand constants pinned by test vectors that must only ever be reverted, never updated), per-connection encrypted records signed by a derived vault identity with the capsule JCS+padding+AES-GCM pipeline and shared buckets so record types are indistinguishable by size, the NWC profile with lossless URI parse/export, relay sync reusing the publish-and- verify quorum bar, and per-record high-water marks so a stale replica is withheld and reported rather than silently resurrecting a revoked credential. The two-tier model makes sudo mode cryptographically real: personal- tier record keys require vault_sudo_key as HKDF input, VaultSession holds it only inside an enableSudo/endSudo window (wiping on the way in and out), and outside a window personal records are invisible -- the same trial-decrypt returns null, not an error. The app-facing API is structurally blind to the tier by construction. 118 tests passing, including four end-to-end scenarios against mock relays: clean-device restore, password-change carry, legacy-account migration (wrong phrase refused), and rollback detection. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01CMr9Yt8SYmZcfgrg3CV2G1
4.5 KiB
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.