stable
`@noy-db/on-*` — Authentication / unlock paths
The unlock catalog: every on-* method a user can prove identity with — passkeys, OIDC, magic links, TOTP, recovery codes, Shamir, PIN, and threat defence.
How a user proves who they are. noy-db encrypts everything client-side: each vault's data is protected by data-encryption keys (DEKs), held in the user's keyring and wrapped by a single key-encryption key (KEK). Each
on-*package is one way to unlock that keyring. Composable — stack them however your threat model needs.
The on- prefix reads as "you get on via this method." Every
package in this family is a crypto primitive only — storage,
rate-limiting, audit integration, and UI belong to the caller.
Overview — by tier and integration
The whole family at a glance, next to the one kernel-built credential (the tier-1 secret). This is the same catalog surfaced on the authentication page — single-sourced:
Auth methods — the on-* family and the kernel tier
| Method | Tier / role | Factor | Integration | What it does |
|---|---|---|---|---|
| secret → KEK | Tier 1Root secret | Knowledge | kernel | The master secret; PBKDF2-SHA256 (600k) derives the KEK. Built into @noy-db/hub — no on- package. |
| on-password | Tier 2Authenticator | Knowledge | external pkg | A separate frequently-typed password as a keyring slot wrapping the DEK set (LUKS-style); unlock yields kek: null. |
| on-webauthn | Tier 2Authenticator (passkey/biometric) | Possession · Biometric | external pkg | Hardware-key / passkey unlock via WebAuthn PRF (rawId fallback); wraps the DEK map, not the KEK. |
| on-oidc GoogleAppleLINEMicrosoftMetaAWS Cognito | Tier 2Authenticator (federated) | Provider-set | external pkg | Federated login via a Bitwarden-style XOR key connector; the server never sees the KEK. |
| on-pin | Tier 3Quick unlock | Knowledge | external pkg | Short-PIN warm resume of an already-unlocked session; cannot cold-open, never holds a KEK. |
| on-totp Google AuthenticatorAuthy1PasswordMicrosoft Authenticator | 2FAStep-up factor | Possession | external pkg | RFC-6238 TOTP second factor a policy gate can demand; not an unlock. |
| on-email-otp | 2FAStep-up factor | Possession | external pkg | Short-lived emailed codes via caller transport; not an unlock. |
| on-recovery | RecoveryRecovery (paper) | Possession | external pkg | Printable one-time codes; last-resort unlock, burned after use. |
| on-shamir | RecoveryRecovery (k-of-n) | Possession ×N | external pkg | Splits the KEK into k-of-n shares; combining reconstructs the real KEK. |
| on-magic-link | ViewerDelegated viewer | Possession | external pkg | Single-use link opening a read-only viewer session, no secret; server-secret-bound HKDF. |
| on-threat | OverlayThreat overlay | — | external pkg | Lockout / duress-wipe / honeypot logic layered on unlock attempts; not a factor. |
Factor — Knowledge (something you remember) · Possession (a device you hold) · Biometric (something you are) · Provider-set (chosen by the OIDC issuer) · — not a factor.
Catalog
Device / SSO
| Package | What it does |
|---|---|
| webauthn | Hardware-key passkey unlock via WebAuthn PRF — Touch ID, Face ID, Windows Hello, YubiKey. No secret at all. |
| oidc | Split-key OIDC bridge — the KEK is XOR-split between a device half and a server half; the server never sees plaintext. Requires operating a key-connector server. |
Delegation
| Package | What it does |
|---|---|
| magic-link | One-shot viewer session — a single-use, vault-bound URL opens a read-only session; no account, no shared secret. |
Recovery
| Package | What it does |
|---|---|
| recovery | Last-resort unlock via printable Base32 codes (28 chars, 120 bits of entropy) that burn on use. |
| shamir | k-of-n Shamir Secret Sharing of the KEK for multi-party custody; each share composable with another on-* method. |
Second factor
| Package | What it does |
|---|---|
| totp | RFC 6238 authenticator-app codes, zero dependencies, constant-time verification against the official test vectors. |
| email-otp | Email OTP with a caller-supplied transport (SMTP / SES / Postmark / any function) and constant-time verification. |
| password | Routine tier-2 login password — a separate secret from the tier-1 master phrase, PBKDF2-SHA256 600K wrapping the DEK set. |
Local lock
| Package | What it does |
|---|---|
| pin | Session-resume PIN / biometric quick-lock (tier 3) — re-unlocks cached DEKs without re-typing the secret. |
Defence
| Package | What it does |
|---|---|
| threat | Lockout + duress + honeypot triad — pure stateful primitives for brute-force lockout, coercion response, and decoy vaults. |
Compare
| Package | Proves | Needs a server? | Role |
|---|---|---|---|
| webauthn | possession-of-device (hardware authenticator, optional biometric) | ✗ | primary unlock |
| oidc | federated identity (OIDC ID token) | ✓ | primary unlock |
| magic-link | email-delegation (bearer of a single-use URL) | ✓ | delegated unlock |
| recovery | one-time recovery code (burns on use) | ✗ | recovery |
| shamir | recovery-shares (k-of-n reconstruction) | ✗ | recovery |
| totp | one-time-code (authenticator app) | ✗ | step-up 2FA |
| email-otp | one-time-code (email) | ✓ | step-up 2FA |
| password | knowledge (tier-2 password) | ✗ | primary unlock |
| pin | knowledge (short PIN / biometric) | ✗ | quick-resume (tier 3) |
| threat | n/a | ✗ | defence overlay |