VNOX-Server/docs/02-protocol/central-account.md
loki5512344 c18ccadf99
chore(server): checkpoint deployed services and unfinished forums
User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
2026-11-01 15:31:20 +01:00

3.3 KiB

LNEx v4: mandatory Central account admission

LNEx v4 requires a Central account proof in AUTH (field 6, bytes account_proof). There is no anonymous or private-mode exemption. v3 clients and gateways must be upgraded together. TLS 1.3 and existing channel-bound Ed25519 signatures remain; v4 changes their domain separator from VNOX-LNEx-v3- to VNOX-LNEx-v4-.

The proof is UTF-8 JSON { "claims": "<hex>", "signature": "<hex>" }. Claims are the exact UTF-8 JSON bytes (hex encoded), containing version (1), issuer (Hub issuer UUID), subject (Central account UUID), public_key (lowercase hex desktop Ed25519 key), issued_at and expires_at (Unix seconds), and audience (vnox-gateway). The Hub Ed25519 signature covers the bytes VNOX-CENTRAL-ACCOUNT-v1\0 followed by the decoded claims. Gateways use explicitly configured trusted issuer UUID/public key, never keys supplied by clients or fetched from arbitrary URLs. They reject missing, malformed, expired, future, overlong-lived (>600 seconds), wrong-audience, unknown-issuer and incorrectly signed proofs, and require the subject key to equal AUTH's client public key. AUTH's channel-bound signature includes the proof. Gateways verify before storage or session creation. Proofs authorize new admission for ten minutes; revoking a device stops refresh immediately, while already issued proofs expire naturally. Existing gateway session timeout remains independent of the admission proof.

Browser device authorization

Desktop POSTs /v1/auth/desktop/start with only its public key. The Hub returns a 256-bit device secret, separate random user code, expiry (600 seconds), and a same-origin browser URL /desktop?code=.... Only the user code enters the browser; no private identity key, device secret or account proof appears in URLs. The browser uses the existing real email/GitHub Central login. It displays the key fingerprint and requires explicit approval with the normal session cookie, exact-Origin and session-CSRF checks. An authenticated user's approval binds the request to that account; approval never creates a synthetic account. Desktop polls /v1/auth/desktop/poll with its device secret; pending is HTTP 202, expired or canceled requests fail closed. Approval yields the signed proof and a long random refresh secret. Secrets are stored only as SHA-256 hashes on Hub. Polling completion is single-use, so a captured browser code cannot retrieve credentials. Desktop cancellation deletes the pending request. Device enrollment expires after 30 days; refresh checks that enrollment is still live and issues a new short proof. Desktop logout disables local admission immediately by atomically moving credentials to a private revocation tombstone; online revocation removes it. Network failures retain the admission-disabled tombstone, retried on later sign-in/admission. HTTPS is required for all desktop Central calls; redirects are disabled and request timeouts bounded. Desktop local credential storage uses a private directory and 0600 file, bound to the local identity public key. The local Ed25519 private key never leaves desktop.

Rate limits and bounded request bodies apply. Expiry is checked on every operation; cleanup does not replace authorization checks. HTTP responses use no-store. All browser approval actions are explicit POSTs; GET requests never approve devices.