VNOX-Server/docs/02-protocol/account-presence.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

54 lines
8.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Account presence and profiles
LNEx v4 additive metadata: MemberInfo fields 4 account_id and 5 avatar_url; UserJoin fields 4 account_id and 5 avatar_url. user_id remains the authenticated Ed25519 device key, never an account UUID. Channel memberships and UDP routes retain their session IDs. Snapshots include each device once; repeated sessions on the same device emit UserLeave only after the last subscription leaves. Presence OFFLINE is emitted only after the last session of that device closes. Clients group member rows by nonempty account_id while retaining all device IDs for voice attribution, and remove only the leaving device.
Central v1 signed proof claims optionally include display_name and avatar_url. Names are bounded to 64 characters; avatar URLs are relative /v1/avatars/ paths, resolved only against https://central.loki-code.dev. Gateway ignores unsigned client nickname when a signed profile exists. Missing optional fields retain compatibility with existing proofs. Avatar HTTP requests have no auth/cookies, reject redirects, bound response and dimensions, and execute outside the UI thread. Default avatar paths use the authenticated account UUID. No database migration, ownership reassignment or protocol version change is required.
## Desktop avatar mutation and live summary refresh
`POST /v1/auth/desktop/avatar` uploads a cropped raw PNG (image/png, at most 2 MiB); `DELETE` on the same path uses an empty body. Both use Authorization: Bearer <desktop refresh secret>, X-Vnox-Public-Key (lowercase Ed25519 hex), X-Vnox-Timestamp (Unix seconds), and X-Vnox-Signature (hex Ed25519). Signature bytes cover `VNOX-CENTRAL-PROFILE-v1\0` followed by method ASCII, NUL, request path ASCII, NUL, decimal timestamp ASCII, NUL, then SHA-256(raw body). Timestamp skew is bounded to 60 seconds. Hub verifies the active unexpired enrollment matches the supplied key and account; cookies are never used. Replays within that window repeat the identical idempotent image/delete mutation. Existing avatar normalization, per-account/per-source budgets, bounded decoding and immutable content IDs apply. Success returns `{user: AccountSummary}` with effective same-origin avatar path. No schema migration is required.
Desktop refresh responses already return `user`; clients now validate subject consistency, atomically persist it only if the same enrollment remains active, and publish a non-secret profile update to UI. Admission, startup, periodic refresh and opening profile settings obtain current Central data. Mutation results use the same update path. Late network results cannot restore credentials or avatars after sign-out. Public PNG requests remain separate and never carry enrollment headers.
`POST /v1/auth/desktop/profile` uses the same enrollment headers and signature (including its distinct path) with JSON `{display_name: string}` limited to 1024 bytes. The trimmed name must contain 1–64 characters and no control/bidi override characters. Only existing accounts.display_name changes; handle, account UUID, device ID, roles and profile_complete remain unchanged. Account/source profile rate limits apply. Success returns `{user: AccountSummary}` and clients persist/publish it exactly like avatar changes. Signed proofs carry the new display name on admission and through the additive live update described below. No protocol version change is introduced.
## Live signed profile updates
LNEx v4 additive packets: `0x0042 ProfileUpdate { bytes account_proof = 1; }` (client to gateway), `0x0043 ProfileUpdated { string user_id = 1; string account_id = 2; string nickname = 3; string avatar_url = 4; int64 issued_at = 5; }` (gateway to client). Gateway verifies the Central issuer signature, lifetime, audience and device binding exactly as admission, and requires the subject to equal the current session account. Display name and avatar must be valid signed profile claims. No client-supplied unsigned nickname/avatar is accepted. Existing Ed25519 device keys, channel/session membership, ownership, permissions and UDP credentials stay unchanged.
The newest accepted issued_at among active sessions of an account prevents older proofs downgrading metadata. Equal-second proofs are accepted (Central proof timestamp resolution is one second); same-second cosmetic ordering is last-arrival. This is transient display metadata, not authorization. Gateway updates profile fields on account sessions and emits each affected device's ProfileUpdated only to its own sessions or peers currently sharing its text/voice channel. Delivery rechecks that visibility; no node-wide profile broadcast or join/leave event is generated.
Desktop forwards the proof obtained by its existing Central refresh; profile-only mutation notifications trigger one coalesced background refresh, not a refresh loop. Before chat/image send or channel/voice join, a proof older than five seconds causes those actions to wait for one bounded refresh; audio/UDP, incoming packets and keepalives continue. ProfileUpdate is written before the actions on the same TCP stream. A failed Central refresh leaves the gateway/voice session active, reports failure, and sends the action with its last verified profile. Opening settings and periodic refresh also propagate signed updates live. No reconnect is required.
## Registration display names and web onboarding
New accounts receive one locally generated friendly Russian word plus `_` and four
cryptographically random decimal digits. Neither email local parts nor GitHub names
become public defaults. Existing account names and immutable handle selection are
unchanged. Word data and its license ship with Hub; no network lookup occurs during
registration.
Migration 0009 adds an independent account_onboarding table. Only newly created
accounts receive pending rows; existing accounts do not acquire a prompt. Session
responses add optional top-level onboarding_pending. POST /v1/account/onboarding
accepts {decision:"rename"|"later"}, records an explicit choice once, and never
changes handle/name. POST /v1/account/display-name accepts {display_name:string},
updates only the existing display_name column, resolves a pending prompt as an
explicit rename, and returns {display_name,onboarding_pending:false}. Both routes
require the same own-origin cookie session and CSRF protection as avatar changes,
small JSON bodies, and per-account/source profile budgets. They do not depend on
pending migration 0006 or require LNEx changes.
## Explicit node administrator capability
Node operators may set `[gateway] admin_account_ids = ["<Central account UUID>"]`. The default empty list grants nobody node administration. Startup rejects invalid/nil UUIDs, duplicates and more than 256 entries. Only the verified Central subject on the authenticated Session is compared with this list; nickname and device public key never confer this role. This is a static operator setting, applied on daemon restart/admission, not first-visitor ownership.
Session gains additive `bool node_admin = 4`, advertising global channel management capability to clients. A listed account may create, rename and delete global (guild_id absent) channels; its other admitted devices receive the same capability. `general` and `voice` remain undeletable bootstrap IDs. Guild ownership/membership/role checks remain unchanged: node administrator status cannot create/edit/delete another guild's channels or bypass voice access. Server checks actual stored channel scope for edit/delete, never a client claim. Clients expose global management controls only for advertised capability and still handle gateway denial.
Global channel metadata changes are visible to all authenticated node sessions; guild metadata remains restricted to persisted guild members. Created/renamed channels are persisted through the existing storage bootstrap path. No database/protocol version migration is required.
Deferred activity is scoped to one TCP session, limited to 32 actions and 4 MiB total contents. Duplicate joins coalesce. Explicit leave cancels matching deferred activity; disconnect/server switch clears it, and session scope drop aborts the HTTP refresh task. Nothing is replayed into another node or session.
### Gateway capability negotiation
Session field 5 `bool live_profiles` is true on gateways supporting packets 0x0042/0x0043. Absent/false on older LNEx v4 gateways: desktop must not send ProfileUpdate, start activity-triggered profile HTTP refresh, or defer chat/image/join for it. Normal existing activity packets continue directly. The local Central profile UI can still refresh independently. This explicit opt-in preserves additive compatibility with older v4 gateways that reject unknown packet IDs.