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

406 lines
12 KiB
Go

package users
import (
"database/sql"
"errors"
"fmt"
"math"
"strings"
"time"
"unicode"
"unicode/utf8"
)
const (
RepeaterStatusActive = "active"
RepeaterStatusMaintenance = "maintenance"
RepeaterStatusDecommissioned = "decommissioned"
RepeaterPowerMains = "mains"
RepeaterPowerBattery = "battery"
RepeaterPowerSolar = "solar"
MaxRepeaterNotes = 500
MaxRepeaterHeightM = 300
MinRepeaterGainDBi = -10
MaxRepeaterGainDBi = 30
)
// RepeaterEdit is one community edit of a repeater's details. HeightM nil is
// unknown (distinct from 0); an empty Status or Power is unset.
type RepeaterEdit struct {
HeightM *float64
GainDBi float64
Status string
Power string
Notes string
}
// ValidateRepeaterEdit returns the cleaned edit or a *ValidationError.
func ValidateRepeaterEdit(e RepeaterEdit) (RepeaterEdit, error) {
if e.HeightM != nil {
h := *e.HeightM
if math.IsNaN(h) || math.IsInf(h, 0) || h < 0 || h > MaxRepeaterHeightM {
return RepeaterEdit{}, &ValidationError{Msg: fmt.Sprintf("height must be between 0 and %d m", MaxRepeaterHeightM)}
}
hc := h
e.HeightM = &hc
}
if math.IsNaN(e.GainDBi) || math.IsInf(e.GainDBi, 0) || e.GainDBi < MinRepeaterGainDBi || e.GainDBi > MaxRepeaterGainDBi {
return RepeaterEdit{}, &ValidationError{Msg: fmt.Sprintf("antenna gain must be between %d and %d dBi", MinRepeaterGainDBi, MaxRepeaterGainDBi)}
}
switch e.Status {
case "", RepeaterStatusActive, RepeaterStatusMaintenance, RepeaterStatusDecommissioned:
default:
return RepeaterEdit{}, &ValidationError{Msg: "status must be active, maintenance or decommissioned"}
}
switch e.Power {
case "", RepeaterPowerMains, RepeaterPowerBattery, RepeaterPowerSolar:
default:
return RepeaterEdit{}, &ValidationError{Msg: "power must be mains, battery or solar"}
}
n := strings.ToValidUTF8(e.Notes, "")
n = strings.ReplaceAll(n, "\r\n", "\n")
n = strings.Map(func(r rune) rune {
switch {
case r == '\t' || r == '\r':
return ' '
case r != '\n' && unicode.IsControl(r):
return -1
case (r >= 0x202A && r <= 0x202E) || (r >= 0x2066 && r <= 0x2069):
return -1
}
return r
}, n)
lines := strings.Split(n, "\n")
for i, l := range lines {
lines[i] = strings.TrimRight(l, " ")
}
n = strings.TrimSpace(strings.Join(lines, "\n"))
for strings.Contains(n, "\n\n\n") {
n = strings.ReplaceAll(n, "\n\n\n", "\n\n")
}
if utf8.RuneCountInString(n) > MaxRepeaterNotes {
return RepeaterEdit{}, &ValidationError{Msg: fmt.Sprintf("notes must be at most %d characters", MaxRepeaterNotes)}
}
e.Notes = n
return e, nil
}
// ErrRepeaterConflict: a conditional SaveRepeaterInfoAt was given a base
// revision that is not the stored one.
var ErrRepeaterConflict = errors.New("users: repeater details revision conflict")
// RepeaterInfo is the community-maintained detail row of one repeater.
// UpdatedBy and UpdatedByName are empty when the editor was deleted or is not
// an active user. Revision counts saves from 1; a repeater without a row is
// at revision 0.
type RepeaterInfo struct {
Pubkey string
Revision int64
HeightM *float64
GainDBi float64
Status string
Power string
Notes string
UpdatedAt time.Time
UpdatedBy *int64
UpdatedByName string
}
// RepeaterClaim says a user operates a repeater.
type RepeaterClaim struct {
Pubkey string
UserID int64
DisplayName string
ClaimedAt time.Time
}
const repeaterInfoSelect = `SELECT i.pubkey, i.revision, i.height_m, i.gain_dbi, i.status, i.power, i.notes, i.updated_at, u.id, u.display_name
FROM repeater_info i LEFT JOIN users u ON u.id = i.updated_by AND u.status = 'active'`
func scanRepeaterInfo(r rowScanner) (*RepeaterInfo, error) {
var (
ri RepeaterInfo
h sql.NullFloat64
st, pw, name sql.NullString
ub sql.NullInt64
updatedAtUnix int64
)
if err := r.Scan(&ri.Pubkey, &ri.Revision, &h, &ri.GainDBi, &st, &pw, &ri.Notes, &updatedAtUnix, &ub, &name); err != nil {
return nil, err
}
if h.Valid {
v := h.Float64
ri.HeightM = &v
}
ri.Status, ri.Power = st.String, pw.String
ri.UpdatedAt = fromUnix(updatedAtUnix)
if ub.Valid {
v := ub.Int64
ri.UpdatedBy = &v
ri.UpdatedByName = name.String
}
return &ri, nil
}
func (s *Store) GetRepeaterInfo(pubkey string) (*RepeaterInfo, error) {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return nil, err
}
ri, err := scanRepeaterInfo(s.db.QueryRow(repeaterInfoSelect+` WHERE i.pubkey = ?`, pk))
if errors.Is(err, sql.ErrNoRows) {
return nil, ErrNotFound
}
return ri, err
}
// ListRepeaterInfo returns every info row ordered by pubkey.
func (s *Store) ListRepeaterInfo() ([]RepeaterInfo, error) {
rows, err := s.db.Query(repeaterInfoSelect + ` ORDER BY i.pubkey`)
if err != nil {
return nil, err
}
defer rows.Close()
var out []RepeaterInfo
for rows.Next() {
ri, err := scanRepeaterInfo(rows)
if err != nil {
return nil, err
}
out = append(out, *ri)
}
return out, rows.Err()
}
// SaveRepeaterInfo validates and upserts the row, whatever its revision. It
// returns the row the write replaced (nil if there was none), read in the
// same transaction, for the audit diff.
func (s *Store) SaveRepeaterInfo(userID int64, pubkey string, e RepeaterEdit) (*RepeaterInfo, error) {
return s.saveRepeaterInfo(userID, pubkey, e, nil)
}
// SaveRepeaterInfoAt is SaveRepeaterInfo only while the stored revision is
// base (0: no row yet). Otherwise it writes nothing and returns
// ErrRepeaterConflict. The check is part of the write statement, so of two
// saves from the same base exactly one wins.
func (s *Store) SaveRepeaterInfoAt(userID int64, pubkey string, e RepeaterEdit, base int64) (*RepeaterInfo, error) {
return s.saveRepeaterInfo(userID, pubkey, e, &base)
}
func (s *Store) saveRepeaterInfo(userID int64, pubkey string, e RepeaterEdit, base *int64) (*RepeaterInfo, error) {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return nil, err
}
e, err = ValidateRepeaterEdit(e)
if err != nil {
return nil, err
}
tx, err := s.db.Begin()
if err != nil {
return nil, err
}
defer tx.Rollback()
prev, err := scanRepeaterInfo(tx.QueryRow(repeaterInfoSelect+` WHERE i.pubkey = ?`, pk))
if errors.Is(err, sql.ErrNoRows) {
prev = nil
} else if err != nil {
return nil, err
}
var h any
if e.HeightM != nil {
h = *e.HeightM
}
var st, pw any
if e.Status != "" {
st = e.Status
}
if e.Power != "" {
pw = e.Power
}
now := unix(s.now())
var res sql.Result
switch {
case base == nil:
res, err = tx.Exec(`INSERT INTO repeater_info (pubkey, revision, height_m, gain_dbi, status, power, notes, updated_at, updated_by)
VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(pubkey) DO UPDATE SET revision = repeater_info.revision + 1,
height_m = excluded.height_m, gain_dbi = excluded.gain_dbi,
status = excluded.status, power = excluded.power, notes = excluded.notes,
updated_at = excluded.updated_at, updated_by = excluded.updated_by`,
pk, h, e.GainDBi, st, pw, e.Notes, now, userID)
case *base == 0:
// Only the first save of a repeater: a row that exists is a conflict.
res, err = tx.Exec(`INSERT INTO repeater_info (pubkey, revision, height_m, gain_dbi, status, power, notes, updated_at, updated_by)
VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(pubkey) DO NOTHING`,
pk, h, e.GainDBi, st, pw, e.Notes, now, userID)
default:
res, err = tx.Exec(`UPDATE repeater_info SET revision = revision + 1, height_m = ?, gain_dbi = ?,
status = ?, power = ?, notes = ?, updated_at = ?, updated_by = ?
WHERE pubkey = ? AND revision = ?`,
h, e.GainDBi, st, pw, e.Notes, now, userID, pk, *base)
}
if err != nil {
return nil, err
}
if n, err := res.RowsAffected(); err != nil {
return nil, err
} else if n != 1 {
return nil, ErrRepeaterConflict
}
if err := tx.Commit(); err != nil {
return nil, err
}
return prev, nil
}
// ClaimRepeater is idempotent: added is false when the user already claimed it.
func (s *Store) ClaimRepeater(userID int64, pubkey string) (bool, error) {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return false, err
}
res, err := s.db.Exec(`INSERT OR IGNORE INTO repeater_claims (pubkey, user_id, claimed_at) VALUES (?, ?, ?)`, pk, userID, unix(s.now()))
if err != nil {
return false, err
}
n, err := res.RowsAffected()
return n == 1, err
}
// UnclaimRepeater returns ErrNotFound when the user has no claim on it.
func (s *Store) UnclaimRepeater(userID int64, pubkey string) error {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return err
}
return expectOne(s.db.Exec(`DELETE FROM repeater_claims WHERE pubkey = ? AND user_id = ?`, pk, userID))
}
func scanRepeaterClaims(rows *sql.Rows) ([]RepeaterClaim, error) {
defer rows.Close()
var out []RepeaterClaim
for rows.Next() {
var c RepeaterClaim
var at int64
if err := rows.Scan(&c.Pubkey, &c.UserID, &c.DisplayName, &at); err != nil {
return nil, err
}
c.ClaimedAt = fromUnix(at)
out = append(out, c)
}
return out, rows.Err()
}
const repeaterClaimsSelect = `SELECT c.pubkey, c.user_id, u.display_name, c.claimed_at
FROM repeater_claims c JOIN users u ON u.id = c.user_id`
// RepeaterClaims lists the active claimers of one repeater.
func (s *Store) RepeaterClaims(pubkey string) ([]RepeaterClaim, error) {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return nil, err
}
rows, err := s.db.Query(repeaterClaimsSelect+` WHERE c.pubkey = ? AND u.status = 'active' ORDER BY c.claimed_at, c.user_id`, pk)
if err != nil {
return nil, err
}
return scanRepeaterClaims(rows)
}
// AllRepeaterClaims returns the active claimers of every repeater, by pubkey.
func (s *Store) AllRepeaterClaims() (map[string][]RepeaterClaim, error) {
rows, err := s.db.Query(repeaterClaimsSelect + ` WHERE u.status = 'active' ORDER BY c.pubkey, c.claimed_at, c.user_id`)
if err != nil {
return nil, err
}
list, err := scanRepeaterClaims(rows)
if err != nil {
return nil, err
}
out := make(map[string][]RepeaterClaim)
for _, c := range list {
out[c.Pubkey] = append(out[c.Pubkey], c)
}
return out, nil
}
// RepeaterClaimsByUser lists every claim of a user regardless of their
// status, newest first.
func (s *Store) RepeaterClaimsByUser(userID int64) ([]RepeaterClaim, error) {
rows, err := s.db.Query(repeaterClaimsSelect+` WHERE c.user_id = ? ORDER BY c.claimed_at DESC, c.pubkey`, userID)
if err != nil {
return nil, err
}
return scanRepeaterClaims(rows)
}
// RepeaterClaimsOfUserRepeaters returns the active claimers of every
// repeater the user claimed, by pubkey, in one query (My repeaters).
func (s *Store) RepeaterClaimsOfUserRepeaters(userID int64) (map[string][]RepeaterClaim, error) {
rows, err := s.db.Query(repeaterClaimsSelect+` WHERE u.status = 'active'
AND c.pubkey IN (SELECT pubkey FROM repeater_claims WHERE user_id = ?)
ORDER BY c.pubkey, c.claimed_at, c.user_id`, userID)
if err != nil {
return nil, err
}
list, err := scanRepeaterClaims(rows)
if err != nil {
return nil, err
}
out := make(map[string][]RepeaterClaim)
for _, c := range list {
out[c.Pubkey] = append(out[c.Pubkey], c)
}
return out, nil
}
// RepeaterInfoOfUserRepeaters returns the saved info of every repeater the
// user claimed that has some, by pubkey, in one query (My repeaters).
func (s *Store) RepeaterInfoOfUserRepeaters(userID int64) (map[string]RepeaterInfo, error) {
rows, err := s.db.Query(repeaterInfoSelect+` WHERE i.pubkey IN (SELECT pubkey FROM repeater_claims WHERE user_id = ?)`, userID)
if err != nil {
return nil, err
}
defer rows.Close()
out := make(map[string]RepeaterInfo)
for rows.Next() {
ri, err := scanRepeaterInfo(rows)
if err != nil {
return nil, err
}
out[ri.Pubkey] = *ri
}
return out, rows.Err()
}
// CanEditRepeater: admin always; a non-active user never; with no active
// claimers any active user; otherwise only the active claimers.
func (s *Store) CanEditRepeater(u *User, pubkey string) (bool, error) {
pk, err := NormalizePubkey(pubkey)
if err != nil {
return false, err
}
if u == nil || u.Status != StatusActive {
return false, nil
}
if u.Role == RoleAdmin {
return true, nil
}
claims, err := s.RepeaterClaims(pk)
if err != nil {
return false, err
}
if len(claims) == 0 {
return true, nil
}
for _, c := range claims {
if c.UserID == u.ID {
return true, nil
}
}
return false, nil
}