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.
48 lines
3.3 KiB
Markdown
48 lines
3.3 KiB
Markdown
# 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.
|