Skip to content

API.md

Latest commit

 

History

History
66 lines (50 loc) · 6.14 KB

API.md

File metadata and controls

66 lines (50 loc) · 6.14 KB
Raw

HTTP API

The API handles sign-in, account settings, and encrypted vault storage through Nuxt's same-origin /api proxy. Search and item organization run in the browser.

Routes

Health, password parameters, registration, and both login methods are public. Other routes require a session. POST, PUT, PATCH, and DELETE requests require the configured Origin, including command-line requests.

Method Route Purpose
POST /api/auth/password/parameters Get password derivation settings
POST /api/auth/register Create an account and sign in
POST /api/auth/login Check the sign-in credential and create a session
GET /api/auth/methods Get the account's passkey count
POST /api/auth/password/verify Confirm account access for sensitive changes
PATCH /api/auth/password Update account authentication and vault password protection together
POST /api/auth/login/options Start passkey sign-in
POST /api/auth/login/verify Complete passkey sign-in
POST /api/auth/reauth/options Start passkey verification for sensitive changes
POST /api/auth/reauth/verify Complete passkey verification
GET /api/auth/passkeys List the account's passkeys
POST /api/auth/passkeys/options Start adding a passkey
POST /api/auth/passkeys/verify Verify and save a passkey
DELETE /api/auth/passkeys/:id Remove a passkey from the account
GET /api/auth/me Get account details without extending the idle timeout
PATCH /api/auth/me Update name or email; email changes require recent verification
POST /api/auth/logout End the session and clear authentication cookies
GET /api/vault Get the encrypted vault snapshot, or null before setup
PUT /api/vault Create the account's encrypted vault
POST /api/vault/commit Save encrypted changes if the expected revision matches
GET /api/vault/records/:id Get one encrypted record from the account's vault
GET /api/health Check database connectivity

Routes are defined in the authentication, vault, and health controllers.

Request formats

schemas.ts, account-auth.ts, and vault.ts define accepted fields. Unknown properties are rejected.

  • Password parameters accept { email } and return a public salt and KDF profile. Dummy parameters for unknown accounts do not fully prevent account discovery across restarts, instances, or registration.
  • Registration accepts { name, email, credential, kdf }; login accepts { email, credential }; password verification accepts { credential }. The browser sends a canonical base64 32-byte credential, keeping raw passwords and vault secrets local.
  • Password changes accept { currentCredential, newCredential, kdf, vault? }. Existing vaults require a matching wrapper/catalogue update that preserves protection mode, generation, recovery wrapper, and records. Authentication, vault, session, and challenge changes share one transaction. The response is the updated snapshot, or null before vault setup.
  • Passkey requests use a challenge ID, WebAuthn response, and cookie linking the authentication flow. Adding a passkey requires a session; removal requires recent verification. Password sign-in remains available after removing the last passkey.
  • Vault writes contain encrypted data. The API checks ownership, sizes, and revisions; the browser checks decrypted contents. Key-bundle changes require recent verification. After a conflict, load and verify current state before retrying.

Credential, group, category, Trash, and reveal commands run locally, without separate HTTP endpoints.

Vault limits

VAULT_LIMITS keeps storage and full-vault key updates bounded:

Limit Value
Credential records, including Trash 2,000
Decoded catalogue payload 2 MiB
Decoded per-record payload 128 KiB
Total serialized record data 4 MiB
HTTP request body 8 MiB

Responses

Success returns { "data": result }. Errors return { "error": { "code": "VALIDATION_ERROR", "message": "...", "issues": [{ "path": "field", "message": "..." }] } }; issues is optional. Responses use Cache-Control: no-store.

Error statuses include 400 for validation, 401 for authentication, 403 for origin or verification checks, 404 for unavailable records, 409 for conflicts, 413 for oversized requests, and 429 for rate limits. Unexpected errors return 500; a failed database health check returns 503.

SESSION_EXPIRED clears local account/vault state. Failed login or passkey assertions use UNAUTHENTICATED; a rejected assertion leaves an existing session intact. See error handling and security.