Files
AdamandAdam c83499763d Allow mobile clients to manage repeater claims and details (#2429)
Draft for feedback: a working version of native repeater claims and
edits from mobile clients, built on the repeater info feature from
#2415. Four open questions are at the end.

## Situation

Repeater info (#2415) can only be claimed and edited from a browser
session. Device tokens from `POST /api/auth/device-token` are limited to
`rx` (CoreDrive RX: settings and companion linking), and `GET
/api/repeaters/{pubkey}/info` treats a bearer token as anonymous. A
mobile client can show a repeater's details but can't offer "claim" or
"edit" natively.

`PUT /api/repeaters/{pubkey}/info` is also a full replace with no
precondition. Two people editing from the same copy silently overwrite
each other. That's rare in the browser, but likelier from an app that
keeps a cached copy.

## Change

Three commits, one per piece.

**1. Device-token scopes for the repeater routes** (`8aba3715`)

- `POST /api/auth/device-token` takes an optional `scopes` list. Omitted
(or `null`) still means `["rx"]`, so CoreDrive RX and every existing
token keep exactly their current permissions. An empty list or an
unknown scope answers 400, checked before the password.
- New scopes:
- `repeater:claim`: `POST` and `DELETE /api/repeaters/{pubkey}/claim`.
These already only add or remove the caller's own claim. Several
claimers per repeater, idempotent `POST`, unchanged.
- `repeater:edit`: `PUT /api/repeaters/{pubkey}/info`, still subject to
`CanEditRepeater`.
- Every device token may use `/api/auth/me` and `/api/auth/logout`, so a
repeater-only token can check and end its own login.
- `GET /api/repeaters/{pubkey}/info` with a token holding either
repeater scope returns `canEdit` and `claimedByMe`. An unknown or
expired token answers 401 rather than passing as anonymous, so a client
learns its login is gone. A valid token without a repeater scope still
gets the public view. A cookie still wins over a bearer header, as
elsewhere.
- `GET /api/account/repeaters` (My repeaters, from #2430) also takes a
token holding either repeater scope, so an app gets the account's claims
in one request. It can't build that list from the public catalog, where
claimers are display names, and reading repeaters one at a time would
miss a claimed repeater that has left the node list. An `rx`-only token
still answers 403.
- Scope checks are method-aware (`bearerScopesFor(method, path)`). The
repeater paths are added to the bearer CORS paths.
- Same handlers, validation, rate limit (`repeater`, 120/h per user and
per IP), audit actions and admin claim removal as the browser. Token
writes add `via: device` to the `repeater.claim`, `repeater.edit` and
`repeater.unclaim` rows, and the `user.login` row records the granted
scopes. The admin route keeps refusing bearer tokens.

**2. Conditional edits with a revision** (`9f9bf47b`)

- `users.db` schema v10 adds `repeater_info.revision`. Existing rows
start at 1; a repeater with no saved details is at 0. Claims don't
change it.
- `GET` (single and list) and `PUT` responses include `revision`.
- `PUT` accepts an optional `baseRevision`. The check is part of the
write statement, so of two saves from the same base exactly one lands:
- `baseRevision: 0` (first save): `INSERT … ON CONFLICT(pubkey) DO
NOTHING`.
- `baseRevision: n`: `UPDATE … SET revision = revision + 1 … WHERE
pubkey = ? AND revision = ?`.
- No match answers `409` with the stored details
(`canEdit`/`claimedByMe` included) and writes nothing. That's the same
shape `PUT /api/account/settings` uses for its conflicts.
  - A stale base is refused even when the body would change nothing.
- Permission is checked first, so a 409 never shows details to someone
who can't edit.
- Without `baseRevision` the save is unconditional and bumps the
revision, so `public/repeater-info.js` works unchanged.
- `/api/config/client` adds `userManagement.repeaterTokens: true`, so a
client can tell this server from one without the scopes or
`baseRevision` (older servers answer the device-token request with the
SPA page, as noted for `companionLinking`).

**Discovery and conflict recovery, for a client:**

1. Check `userManagement.repeaterTokens` in `/api/config/client`.
Without it, keep the claim and edit actions hidden.
2. Log in with `scopes: ["repeater:claim", "repeater:edit"]` (or just
what the client offers). The response echoes the granted `scopes`.
3. Read `GET /api/repeaters/{pubkey}/info` with the token. Show
Claim/Unclaim from `claimedByMe` and Edit from `canEdit`, and keep
`revision`.
4. Save with `PUT …/info` and `baseRevision` set to that revision. On
200, keep the new `revision` from the response. On 409, the body is the
current record: show or merge it, then retry with its `revision`. On
401, log in again. On 403, the account can no longer edit (for example
someone claimed it), so refresh from `canEdit`.

**3. Account page device list** (`d28374aa`)

My account, Devices labelled every device token "CoreDrive RX".
`/api/account/sessions` now includes a device token's `scopes`. The page
keeps the CoreDrive RX label for `rx` tokens (and rows without scopes).
It shows other tokens under the device name the app sent, with a line
such as "can claim repeaters and edit repeater details".

Docs: `openapi.go`, `docs/api-spec.md` and the Repeater info section of
`docs/user-guide/accounts.md`.

## Questions

1. **One scope or two?** This uses separate `repeater:claim` and
`repeater:edit`, so a client can ask for less, and a token that only
edits can't put the user's name on a repeater publicly. One `repeater`
scope would be simpler if you'd rather not split it.
2. **Editing unclaimed repeaters from mobile.** This keeps web parity:
any active user may edit a repeater nobody has claimed, and once it has
claimers only they (and admins) can. The alternative is to require a
claim before a token may edit. That's stricter, but then app and browser
rules differ.
3. **Operator switch.** There's no new setting: the scopes are available
whenever `userManagement` is on, and the user opts in when the app asks
for them at login. Would you want an explicit opt-in such as
`userManagement.mobileRepeaterWrites`?
4. **Stale-edit contract.** Does `revision` plus `baseRevision` in the
body, with 409 returning the current record, fit? I matched account
settings rather than `ETag`/`If-Match`, to keep one pattern in the API.
The browser editor doesn't send `baseRevision` yet. Making it send one
would be a small follow-up, if you want browser saves protected too.

## Tests

- `cmd/server/repeater_device_token_test.go`:
- default and requested scopes, rejected scopes, and the method-aware
route table;
- per-scope allowed and denied routes, logout with a repeater-only
token;
  - claim and unclaim of own claim only, alongside another claimer;
- edit permission (unclaimed repeater, claimer, non-claimer, admin) and
a disabled account;
  - the admin route refusing tokens;
  - authenticated, public and expired-token reads;
- `via: device` audit rows, cookie writes still needing CSRF, and
session scopes.
- My repeaters with a claim or edit token (own claims only), and 403 for
an `rx`-only token.
- `cmd/server/repeater_revision_test.go`:
- revision on reads, a first edit with no saved row, and a stale base
returning 409 with the current record and no audit row;
  - unconditional browser saves, validation and permission order;
- two concurrent saves from the same revision (one 200, one 409), and
the client config flag.
- `internal/users/repeater_revision_test.go`:
  - revision counting and conditional first and later saves;
  - an 8-way race for both cases (`-race`);
  - the v9 to v10 upgrade.
- `tests/unit/test-user-management-ui.js`: app token labels and scope
line.

Run locally:

- `make test`: all 16 modules OK.
- `sh test-all.sh`: all suites pass, run in `node:24-bookworm`. On
macOS, `test-manage-workflow.js` fails 2 cases on unchanged master
because of the BSD tools.
- `npx eslint public/*.js`: 0 errors, the same 87 warnings as master.
- `node tests/e2e/test-lint-network-calls.js`
- `tests/e2e/test-user-management-e2e.js` against local e2etest servers
with the CI config: 44/44.
- Manually against a local instance:
  - in the browser: claim, edit, unclaim, and the Devices list;
  - with curl: the token flow, including a 409 after a browser save.

Not run: the full Playwright shard matrix from CI.

---------

Co-authored-by: Adam <196335+anieto@users.noreply.github.com>
2026-11-21 22:27:48 +01:00

247 lines
8.5 KiB
Go

package users
import (
"database/sql"
"errors"
"fmt"
)
// migrations[i] upgrades the schema from version i to i+1. Forward-only:
// never edit a shipped entry, append a new one.
var migrations = [][]string{
{ // v1: sub-project A
`CREATE TABLE users (
id INTEGER PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
display_name TEXT NOT NULL,
password_hash TEXT NOT NULL,
role TEXT NOT NULL DEFAULT 'user' CHECK (role IN ('user','admin')),
status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','active','disabled')),
created_at INTEGER NOT NULL,
activated_at INTEGER,
activated_by INTEGER,
last_login_at INTEGER,
email_bouncing INTEGER NOT NULL DEFAULT 0
)`,
`CREATE TABLE sessions (
id INTEGER PRIMARY KEY,
token_hash TEXT NOT NULL UNIQUE,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
csrf_token TEXT NOT NULL,
created_at INTEGER NOT NULL,
expires_at INTEGER NOT NULL,
last_seen_at INTEGER NOT NULL,
user_agent TEXT NOT NULL DEFAULT ''
)`,
`CREATE INDEX sessions_user ON sessions(user_id)`,
`CREATE TABLE tokens (
token_hash TEXT PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
purpose TEXT NOT NULL CHECK (purpose IN ('activate','reset','email_change')),
new_email TEXT,
expires_at INTEGER NOT NULL,
used_at INTEGER
)`,
`CREATE INDEX tokens_user ON tokens(user_id, purpose)`,
`CREATE TABLE audit_log (
id INTEGER PRIMARY KEY,
at INTEGER NOT NULL,
actor_user_id INTEGER,
action TEXT NOT NULL,
target_user_id INTEGER,
detail TEXT NOT NULL DEFAULT '{}'
)`,
`CREATE INDEX audit_target ON audit_log(target_user_id)`,
`CREATE INDEX audit_actor ON audit_log(actor_user_id)`,
`CREATE TABLE mail_log (
id INTEGER PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
to_email TEXT NOT NULL,
purpose TEXT NOT NULL,
provider_message_id TEXT,
sent_at INTEGER NOT NULL,
last_event TEXT NOT NULL DEFAULT 'sent',
last_event_at INTEGER NOT NULL,
last_reason TEXT NOT NULL DEFAULT ''
)`,
`CREATE INDEX mail_user ON mail_log(user_id)`,
`CREATE UNIQUE INDEX mail_msgid ON mail_log(provider_message_id) WHERE provider_message_id IS NOT NULL`,
`CREATE TABLE mail_events (
mail_id INTEGER NOT NULL REFERENCES mail_log(id) ON DELETE CASCADE,
event TEXT NOT NULL,
at INTEGER NOT NULL,
reason TEXT NOT NULL DEFAULT '',
UNIQUE (mail_id, event, at)
)`,
},
{ // v2: sub-project B, settings sync (one document per user)
`CREATE TABLE user_settings (
user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
doc TEXT NOT NULL,
revision INTEGER NOT NULL,
generation TEXT NOT NULL,
updated_at INTEGER NOT NULL
)`,
},
{ // v3: sub-project C, global audit list ordered and filtered by time
`CREATE INDEX audit_at ON audit_log(at)`,
},
{ // v4: sub-project D, proposals (one generic table; this version ships the kind 'hashtag_channel')
`CREATE TABLE proposals (
id INTEGER PRIMARY KEY,
kind TEXT NOT NULL,
subject TEXT NOT NULL,
status TEXT NOT NULL CHECK (status IN ('pending','approved','rejected','revoked')),
proposer_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
reviewer_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
note TEXT NOT NULL DEFAULT '',
created_at INTEGER NOT NULL,
decided_at INTEGER
)`,
`CREATE UNIQUE INDEX proposals_kind_subject ON proposals(kind, subject)`,
`CREATE INDEX proposals_status ON proposals(status)`,
},
{ // v5: sub-project E, node notifications
`CREATE TABLE notification_prefs (
user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
enabled INTEGER NOT NULL DEFAULT 1,
events TEXT NOT NULL DEFAULT '',
unsub_token TEXT NOT NULL UNIQUE,
updated_at INTEGER NOT NULL
)`,
`CREATE TABLE notification_watches (
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
pubkey TEXT NOT NULL,
created_at INTEGER NOT NULL,
PRIMARY KEY (user_id, pubkey)
)`,
`CREATE TABLE notification_state (
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
event TEXT NOT NULL,
subject TEXT NOT NULL,
state TEXT NOT NULL,
changed_at INTEGER NOT NULL,
PRIMARY KEY (user_id, event, subject)
)`,
},
{ // v6: sub-project F, companion linking (device sessions, linked companions)
`ALTER TABLE sessions ADD COLUMN kind TEXT NOT NULL DEFAULT 'web'
CHECK (kind IN ('web','device'))`,
`ALTER TABLE sessions ADD COLUMN label TEXT NOT NULL DEFAULT ''`,
`ALTER TABLE sessions ADD COLUMN scopes TEXT NOT NULL DEFAULT ''`,
`CREATE TABLE companion_links (
pubkey TEXT PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
name TEXT NOT NULL DEFAULT '',
linked_at INTEGER NOT NULL
)`,
`CREATE INDEX companion_links_user ON companion_links(user_id)`,
`CREATE TABLE link_challenges (
challenge_hash TEXT PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
pubkey TEXT NOT NULL,
expires_at INTEGER NOT NULL
)`,
},
// v7: personal MQTT logins for observers, and the observer pubkeys bound
// to their owners (first claim wins; NULL user_id = orphaned).
{
`CREATE TABLE mqtt_logins (
user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
username TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL,
password_enc TEXT NOT NULL,
created_at INTEGER NOT NULL,
revoked_at INTEGER,
last_auth_at INTEGER
)`,
`CREATE TABLE observer_bindings (
pubkey TEXT PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
bound_at INTEGER NOT NULL,
bound_by TEXT NOT NULL CHECK (bound_by IN ('auto','admin'))
)`,
`CREATE INDEX observer_bindings_user ON observer_bindings(user_id)`,
},
// v8: confirmed_at is set once the owner's own personal login has
// published under the bound pubkey; 'auto' bindings are born from that
// login, so they count as confirmed at bound_at.
{
`ALTER TABLE observer_bindings ADD COLUMN confirmed_at INTEGER`,
`UPDATE observer_bindings SET confirmed_at = bound_at WHERE bound_by = 'auto'`,
},
// v9: repeater claims and community-maintained repeater details.
{
`CREATE TABLE repeater_claims (
pubkey TEXT NOT NULL,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
claimed_at INTEGER NOT NULL,
PRIMARY KEY (pubkey, user_id)
)`,
`CREATE INDEX repeater_claims_user ON repeater_claims(user_id)`,
`CREATE TABLE repeater_info (
pubkey TEXT PRIMARY KEY,
height_m REAL,
gain_dbi REAL NOT NULL DEFAULT 0,
status TEXT CHECK (status IN ('active','maintenance','decommissioned')),
power TEXT CHECK (power IN ('mains','battery','solar')),
notes TEXT NOT NULL DEFAULT '',
updated_at INTEGER NOT NULL,
updated_by INTEGER REFERENCES users(id) ON DELETE SET NULL
)`,
},
// v10: a repeater_info revision for conditional edits. It counts saves
// from 1; a repeater without a row is at revision 0, so the rows that
// exist start at 1.
{
`ALTER TABLE repeater_info ADD COLUMN revision INTEGER NOT NULL DEFAULT 0`,
`UPDATE repeater_info SET revision = 1`,
},
}
func (s *Store) migrate() error {
if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)`); err != nil {
return fmt.Errorf("users: schema_version: %w", err)
}
v, err := s.SchemaVersion()
if errors.Is(err, sql.ErrNoRows) {
if _, err := s.db.Exec(`INSERT INTO schema_version (version) VALUES (0)`); err != nil {
return fmt.Errorf("users: init schema_version: %w", err)
}
v = 0
} else if err != nil {
return fmt.Errorf("users: read schema_version: %w", err)
}
if v > len(migrations) {
return fmt.Errorf("users: database schema version %d is newer than this binary supports (%d)", v, len(migrations))
}
for i := v; i < len(migrations); i++ {
tx, err := s.db.Begin()
if err != nil {
return err
}
for _, stmt := range migrations[i] {
if _, err := tx.Exec(stmt); err != nil {
tx.Rollback()
return fmt.Errorf("users: migration %d: %w", i+1, err)
}
}
if _, err := tx.Exec(`UPDATE schema_version SET version = ?`, i+1); err != nil {
tx.Rollback()
return fmt.Errorf("users: migration %d: %w", i+1, err)
}
if err := tx.Commit(); err != nil {
return fmt.Errorf("users: migration %d: %w", i+1, err)
}
}
return nil
}
// SchemaVersion returns the applied schema version (sql.ErrNoRows on a
// database that has never been migrated).
func (s *Store) SchemaVersion() (int, error) {
var v int
err := s.db.QueryRow(`SELECT version FROM schema_version`).Scan(&v)
return v, err
}