Skip to content

feat(server): operator API: gate, hosted mode, audit log, org reads and writes - #13

Merged
LukiPrince merged 5 commits into
mainfrom
feat/operator-api
Nov 14, 2026
Merged

LukiPrince merged 5 commits into
mainfrom
feat/operator-api

Conversation

@LukiPrince

Copy link
Copy Markdown
Owner

Adds an operator API: an interface for whoever runs a printpapi server for many orgs, so a separate console can look after them. It is generic: orgs, jobs counted as numbers, and an audit log, nothing specific to one business. It is off unless PRINTAPI_OPERATOR_TOKEN is set. With the token unset, every /operator/ path answers 404 and nothing else changes. See the new docs/operator.md.

What's in it

  • The gate. PRINTAPI_OPERATOR_TOKEN (at least 32 chars) and PRINTAPI_OPERATOR_FROM (the IPs or CIDRs it is accepted from). The address check uses the socket peer, never X-Forwarded-For, so the request gets a raw peer field next to the resolved one.
    • Root is refused on /operator/.
    • On every other route the operator token is dropped before any session, key, Basic, CloudPRNT or agent lookup. It cannot enroll an agent either, even with open enrollment.
  • Hosted mode. With the token set, PRINTAPI_PRIVATE_URLS unset means deny and PRINTAPI_FETCHES_PER_ORG unset means 4. Both are fixed at startup.
  • Audit log. The new operator_audit table has ids, numbers and setting values only, no e-mails, names or titles. It is kept forever and written in the same transaction as the change it records. Read it with GET /operator/audit, which pages by before_id.
  • Reads, metadata only. GET /operator/overview, GET /operator/orgs (status, search, usage, devices, terms), GET /operator/orgs/{id} (usage this month, users, agents, printers, keys without secrets, terms history, lock) and GET /operator/orgs/{id}/jobs. No payload, title, callback URL, idempotency key or secret ever appears. Every response is Cache-Control: no-store.
  • Writes, each one store function and one transaction with its audit row.
    • Change an org's name, quota or plan.
    • Lock and unlock. The new org_locks table is a plain flag and the quota stays untouched. Locking cancels queued jobs. While locked, every submit path answers 403, and a stale claimed job is cancelled instead of requeued. Locks are enforced only while the token is set.
    • Delete an org (the name must be typed to confirm).
    • Create an org with an invitation mail.
    • Send a reset mail, or revoke a key.
    • Every write checks org_created_at, because SQLite reuses the id of a deleted org. A page left open from before the delete gets 409 instead of hitting the new org.
  • Refactor first, on its own (86067d5): transaction-aware variants of the existing mutators, with no behaviour change and parity green on that commit alone.

Schema: only new tables (operator_audit, org_locks) and additive indexes; store_compat checks that the v2.5.1 Python server leaves them alone. A rollback to an older version does not enforce locks (noted in docs/operator.md).

Review

The design went through three reviews (security, scope, Codex adversarial; 48 points) before any code. The code had a security review and a Codex adversarial review, and an independent verifier checked each finding. Six were confirmed and fixed in 1fc61cb.

Checks (local, at 1fc61cb)

  • cargo test --workspace: 986 passed. Clippy -D warnings and fmt --check clean.
  • Parity against v2.5.1: 785 steps, 0 unexpected diffs. --db-compat: 23/23.
  • pytest tools/docs, check_docs.py, pytest agent/tests, and web lint, test and check:bundles all pass.

No release comes from this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX

LukiPrince and others added 5 commits November 14, 2026 01:09
…t mutators

Add *_tx variants (create_org, update_org with name/quota/plan, set_org_quota/plan,
delete_org, signup, create_password_reset, revoke_api_key) that run inside a caller's
transaction so an operator action can write its audit row in the same BEGIN IMMEDIATE.
The plain functions wrap them; put_org shares parse_job_quota. No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX
PRINTAPI_OPERATOR_TOKEN turns on a /operator/ API (404 everywhere while unset).
The token is accepted only from a socket peer in PRINTAPI_OPERATOR_FROM (never
X-Forwarded-For; Req gains a raw socket_peer), root is 401 there, and on every
other route the token is stripped before session, key, Basic, CloudPRNT, agent
or long-poll lookup and refused by enrollment_org even with open enrollment.
With the token set, private URLs default to deny and fetches_per_org to 4.
Every /operator/ response is no-store; the access log drops its query string.

New operator_audit table (new table only) with GET /operator/audit (keyset
paging by before_id), GET /operator/overview (features: [], cached 10 s,
indexed queries via the new jobs_created index), docs/operator.md and the
docs/server.md env rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX
GET /operator/orgs (derived status locked/new/idle/active, q over org name and user
e-mail, status filter, keyset paging by org id), GET /operator/orgs/{id} (usage_by_day
for the current UTC month, users, agents, printers, keys without secrets, terms
history, lock) and GET /operator/orgs/{id}/jobs (metadata only, before_id paging).
One correlated statement serves list and detail; new additive indexes (jobs(org_id),
jobs(org_id, state), printers, users, terms) keep it off full scans, checked by an
EXPLAIN QUERY PLAN test. New empty org_locks table (written by the lock endpoints
later). Tests assert no payload, title, callback, idempotency key, key secret or hash,
password hash or Shopify secret in any answer. docs/operator.md extended.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX
…te, create and invite, reset mail, key revoke

PUT /operator/orgs/{id} (name, job_quota, plan, validated first, one transaction), lock and
unlock via the org_locks table (a pure flag; lock cancels queued jobs; while locked POST /jobs,
POST /orders, the Shopify webhook and PrintNode POST /printjobs answer 403 "org locked", checked
next to check_quota in enqueue_job and in the fetch gate before any download), DELETE with name
confirmation (never the default org; delete_org also removes org_locks rows), POST /operator/orgs
with a random password hash and the reset mail as invitation after the commit, POST
/operator/users/{id}/reset and DELETE /operator/keys/{id} with an org_id check.

Each action is one store function and one transaction with its audit row; a failing audit insert
rolls the change back (insert_audit no longer reports a refused insert as Conflict). Mail and the
WAL truncate run after the commit; a failed mail writes user.reset_mail_failed. Audit content is
ids and numbers only. docs/operator.md gains the write endpoints and the lock rollback caveat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX
…h the token, no requeue for locked orgs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX
@LukiPrince
LukiPrince merged commit 991b542 into main Nov 14, 2026
28 checks passed
@LukiPrince
LukiPrince deleted the feat/operator-api branch November 14, 2026 01:20
@LukiPrince LukiPrince mentioned this pull request Nov 14, 2026
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