Repository navigation
feat(server): operator API: gate, hosted mode, audit log, org reads and writes - #13
Merged
Merged
Conversation
…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
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_TOKENis set. With the token unset, every/operator/path answers 404 and nothing else changes. See the newdocs/operator.md.What's in it
PRINTAPI_OPERATOR_TOKEN(at least 32 chars) andPRINTAPI_OPERATOR_FROM(the IPs or CIDRs it is accepted from). The address check uses the socket peer, neverX-Forwarded-For, so the request gets a raw peer field next to the resolved one./operator/.PRINTAPI_PRIVATE_URLSunset means deny andPRINTAPI_FETCHES_PER_ORGunset means 4. Both are fixed at startup.operator_audittable 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 withGET /operator/audit, which pages bybefore_id.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) andGET /operator/orgs/{id}/jobs. No payload, title, callback URL, idempotency key or secret ever appears. Every response isCache-Control: no-store.org_lockstable 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.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.Schema: only new tables (
operator_audit,org_locks) and additive indexes;store_compatchecks that the v2.5.1 Python server leaves them alone. A rollback to an older version does not enforce locks (noted indocs/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 warningsandfmt --checkclean.--db-compat: 23/23.pytest tools/docs,check_docs.py,pytest agent/tests, and weblint,testandcheck:bundlesall pass.No release comes from this PR.
🤖 Generated with Claude Code
https://claude.ai/code/session_01TEvvb3zrZ3bLSGJbCBaEYX