Skip to content

Enforce the admin role and add an HTTP admin API - #17

Open
Skyfuller1303 wants to merge 19 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:admin-api
Open

Skyfuller1303 wants to merge 19 commits into
itrycodinganditsbad:mainfrom
Skyfuller1303:admin-api

Conversation

@Skyfuller1303

@Skyfuller1303 Skyfuller1303 commented Nov 4, 2026 •

Copy link
Copy Markdown

Builds on #14 (device sessions); please review that one first. This branch contains its commits until #14 is merged.

What

  • New require_admin layer; /api/v1/admin/... answers forbidden to members (a bad token is still 401).
  • Admin API: server counters, user list (paged, with a bounded query search), create account (role + invite), change role and per-account quota, disable, enable, mark for removal, invites (only for accounts without a password), password reset codes, list and revoke a user's devices.
  • Every change needs a fresh confirmation in the body: the acting admin's password. Device tokens never expire, so a stolen admin token alone is not enough. A missing or mistyped field is 400 invalid, a wrong password 403 wrong_password (never 401). Wrong passwords are counted per account in the password-change limiter.
  • Every change re-checks the acting admin's device, role, state and password hash inside its transaction, and takes locks in one order. A transaction-wide lock before the count keeps the last admin (last_admin): Postgres advisory lock, SQLite write transaction.
  • Disabling or removing signs all devices out and refuses sign-in, join and pairing (account_disabled, only after a right password or code). The check runs under the user's row lock, so a device that a pre-disable check let in is never created. A per-account counter (users.auth_gen, bumped by disable, enable, removal and every password change or reset) is read with the hash before the password is verified and compared again under the lock, so a sign-in that verified before a disable and an enable is refused as a wrong password although the hash is unchanged. Enabling brings back no device.
  • A reset code is redeemed through POST /join: it always sets a new password, signs every device out and signs the redeeming computer in.
  • A per-account quota_bytes replaces the server-wide cap for that account, in the preflight check (also when there is no global cap) and in the transactional charge.
  • New codes account_disabled, last_admin; forbidden is now used by the HTTP API.
  • One migration (0008) for SQLite and Postgres.

Server

Routes: GET /admin/server, GET|POST /admin/users, PATCH|DELETE /admin/users/{id}, POST …/disable|enable|invite|password-reset, DELETE …/invite, GET …/devices, DELETE …/devices/{device_id}. Store::kind() is new so the overview can say disk, s3 or memory without showing a path. Limiter::count no longer counts a try it refuses, so a refund can't leave a key above its limit (the answers of the existing limiters don't change).

CLI

user invite replaces a reset code (the account has one open code at a time). The CLI still does not enforce last_admin or the confirmation: whoever runs it has the files.

Docs

docs/design/sync.md (Admin API and roles, API table, codes) and docs/server.md (managing accounts over HTTP, upgrade note). The confirmation body is {password} today; a later two-factor release adds optional totp_code and recovery_code to the same bodies, and servers already ignore unknown fields.

Testing

  • cargo fmt --all -- --check, cargo check --workspace --all-targets --locked, cargo clippy --workspace --all-targets --locked -- -D warnings
  • cargo test -p craft-cloud-meta -p craft-cloud-server -p craft-cloud-api -p craft-cloud-proto --locked on SQLite
  • Postgres 17: meta with CRAFT_CLOUD_REQUIRE_BACKENDS=1, server with CRAFT_CLOUD_TEST_PG
  • MSRV 1.94 cargo check of the changed crates
  • A table-driven test calls every admin route as anonymous, member and admin. Confirmation tests cover each change. Concurrency tests (two admins demoting, disabling, removing and stepping down at once; a sign-in, join or pairing racing a disable) run on both databases; 15 repeated Postgres runs showed no flakes. The last_admin test fails without the lock.
  • A deterministic meta test plays disable and enable between a sign-in's read and its device creation, and an API test refunds a right password while 8 requests race; both fail without their fix.

Not tested

Left open

  • No two-factor yet: totp_code, reset-two-factor and redeeming a reset code for a 2FA account come with it. Until then resetting another admin's password over HTTP is forbidden (use the CLI).
  • Removing a user only marks the account; the data is freed when garbage collection exists.
  • No audit trail and no UI.
  • Other server processes and the CLI notice a revoked device's live connection at the next ping (about 30 s).
  • The migration cannot be rolled back: an older server refuses the newer database.

Skyfuller1303 and others added 17 commits November 4, 2026 00:04
Migration 0007 gives a device its client kind, platform and app version
and, once revoked, the time and the reason, and gives a user the time of
the last password change (plus a disabled time nothing reads yet). All
of it is additive, BIGINT on Postgres, and the flag stays the check.

Meta gets create_device_with and redeem_with, rename_device,
revoke_device_as, revoke_other_devices, revoke_all_devices, account,
change_password and reset_password. Flag, time and reason are set
together and only by the first revoke. A password change or reset sets
the hash, revokes the devices and deletes the account's invite and
pairings in one transaction.

Tests run on both databases, including the migration from 0006.

Co-Authored-By: Claude <noreply@anthropic.com>
New: GET /account, POST /account/password, PATCH /devices/{id} and
POST /devices/revoke-others. Sign-in and join take an optional client
kind, platform and app version, checked before a try is counted. The
device list shows them with the time and reason of a revoke; all new
fields are optional on the wire.

Changing the password answers a wrong current password with 403
wrong_password, never 401, since the agent reads every 401 on a
signed-in route as a revoked device. It is limited to five tries per
account in 15 minutes, takes a password-check slot, and ends the revoked
devices' live connections at once. Password and name bodies are read up
to the new TINY_JSON_BYTES (4 KiB).

wrong_password and forbidden move into the shared error codes; the local
API refers to them. The agent, app and desktop only change where they
build the extended types.

Co-Authored-By: Claude <noreply@anthropic.com>
user reset-password now revokes every device of the account (reason
reset) and deletes its open invite and pairings, so a stolen token does
not outlive the old password. --keep-devices restores the old behaviour
for the devices. device revoke-all signs out an account's devices
without touching the password. Both print how many devices they ended;
device revoke records the admin as the reason.

Co-Authored-By: Claude <noreply@anthropic.com>
The API table and error codes in the design document, the password and
sign-out commands, the live-connection delay of the command line and the
rollout note (an older server refuses the newer database) in the
server guide.

Co-Authored-By: Claude <noreply@anthropic.com>
…evice

A /changes long-poll that was waiting when its device was signed out
through the API now ends at once, and one that wakes for any other reason
looks the device up again before it answers, so a device signed out by
the command line gets 401 instead of the next change set.

The live endpoint listens for revocations and looks the device up before
the upgrade, so a revoke between the sign-in check and the subscription
is not missed.

Co-Authored-By: Claude <noreply@anthropic.com>
change_password checks, inside its transaction, that the calling device
is still signed in (it may have been revoked while the password was
hashed) and answers 401 if not. A password that changed meanwhile is now
409 conflict instead of 400 invalid. Both are new MetaError variants
mapped in the server.

set_password_hash had no caller outside a test and is removed. A new test
breaks the pairing deletes with a trigger and checks that a password
change, an admin reset and a revoke-others undo everything on SQLite and
Postgres.

Co-Authored-By: Claude <noreply@anthropic.com>
The long-poll now listens for revocations and looks its device up before
it waits, so a revoke between the sign-in check and the wait is not
missed, and looks it up once more after the change set is fetched, as
the last step before the answer, so a revoke during the fetch is not
answered with changes.

Co-Authored-By: Claude <noreply@anthropic.com>
…changes a password

change_password locked the caller's device row and then the user's row,
while revoke_other_devices from another device locked its own device and
then the user's, and reset_password locked the user before the devices.
On Postgres two of them at once could deadlock and fail with a database
error. All of them now take the user's row first (a no-op update), then
the devices, then the pairings.

A new scenario runs password changes, sign-outs and an admin reset at the
same moment, over and over, on both databases and expects only successes,
conflicts and signed-out callers. The test trigger helper also drops its
Postgres function.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
…-in adds a device

redeem consumed the invite and then updated the user, while a password
reset locks the user and then deletes the invite, so the two could
deadlock on Postgres. redeem now finds the invite or pairing with a plain
read, locks the account, and consumes the code again under the lock; a
code that is gone by then is invalid_code. create_pairing locks the
account first too.

A password sign-in verified the password outside any transaction, so a
reset or change that committed meanwhile could be followed by a new
device. sign_in_device locks the account and compares the stored hash
again before it creates the device; if it differs, login answers as for
a wrong password.

New scenarios run redeems, a sign-in, a pairing and a reset at the same
moment on both databases and expect no database error and no live device
once the reset is done.

Co-Authored-By: Claude <noreply@anthropic.com>
The invite delete and the pairing update now name the account the plain
read found, so a code hash removed and made again for another account
between that read and the lock is refused as invalid_code instead of
adding a device to the wrong account.

Co-Authored-By: Claude <noreply@anthropic.com>
The admin API's server overview shows whether blobs are on disk, in S3 or in memory. A backend that does not say is reported as other, so nothing outside the store crate has to change.

Co-Authored-By: Claude <noreply@anthropic.com>
New request and answer types for the routes under /api/v1/admin, with a redacting Debug for everything that holds a password or a code, and the error codes account_disabled and last_admin. The confirmation is a body with an optional password today, so an optional totp_code can join it later without breaking a client.

Co-Authored-By: Claude <noreply@anthropic.com>
Migration 0008 adds the purpose of an invite (invite or reset), a quota per space and a removal mark per user. The new Meta methods for the admin API each re-check the acting admin inside their own transaction and take the locks in one order, with a transaction-wide lock before the last-admin count. Disabled accounts are refused by the token check, sign-in, redeem, pairing and device creation, decided under the account's row lock. A reset code always sets a new password, signs every device out and then signs the redeeming computer in. A space's quota replaces the server-wide cap in the preflight check and in the count that follows.

Co-Authored-By: Claude <noreply@anthropic.com>
The require_admin layer and the routes under /api/v1/admin: counters, a paged and searchable user list, creating accounts, changing role and quota, disabling, enabling and removing, invites, password reset codes and a user's devices. Every change asks for the acting admin's password in its body. Sign-in and join answer account_disabled for a disabled account, and a redeemed reset code ends the live connections of the devices it signed out. Documents the API, the confirmation and the rollout in the design document and the server guide.

Co-Authored-By: Claude <noreply@anthropic.com>
Limiter::count added the attempt before comparing it with the maximum, so tries refused at the limit still raised the count. A refund of an attempt that had been accepted at the same moment then left the key above its limit with fewer wrong passwords than allowed. A refused try now leaves the count alone.

Co-Authored-By: Claude <noreply@anthropic.com>
Disabling and enabling an account leaves the password hash as it was, so a sign-in that verified the password before the disable could still create a usable device after the enable. Users get an auth_gen counter (migration 0008) that a disable, an enable, a removal and every password change or reset bump. The sign-in reads it with the hash and sign_in_device compares both under the account's lock. The server's refunds test covers the limiter change.

Co-Authored-By: Claude <noreply@anthropic.com>
The server (device sessions) shows a device's client_kind, platform and
app_version in the device list, but the agent never sent them. Every
sign-in and join of the agent now says it is an agent, which operating
system it runs on and its own version, cut to the server's 32-byte limit.
A server-backed test checks that the device list shows them after both.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant