[ngjunsiang]

Closes #54.
Closes #56, #57, #58, #59 (review follow-up).

What

campus audit — the CLI's first non-OAuth command group. The audit
service (/audit/v1) only accepts its own API keys (audit_v1_…
Bearer), so this adds a second credential lane next to the device-flow
machinery, per the issue's use case: per-student minted keys for
dev-environment trace access, administered by the operator.

• campus audit login / logout — store/clear an audit key from
  --api-key, CAMPUS_AUDIT_API_KEY, or an interactive prompt, in the
  shared credential store. Login verifies the key against the service
  first (--skip-verify opts out): 401 rejects and stores nothing, 403
  counts as verified (valid key, no apikeys:read — the trace-only
  student case), unreachable stores unverified with a warning. Like
  OAuth tokens, the key is bound to the URL it was stored for;
  commands fail fast on a target mismatch with re-login as the remedy.
• campus audit keys list/new/get/update/revoke/regenerate — the
  operator lifecycle (--owner, repeatable --scope, --rate-limit,
  --expires-at; --all to include revoked/expired). Plaintext key
  material prints exactly once, at creation/regeneration, via a plain
  typer.echo so Rich never wraps the token.
• campus audit traces list/get/search — read-only queries
  (traces:read), cursor-paginated; the continuation prints the exact
  --cursor token to re-run with. get prints the full span tree as
  JSON.

Notes

• Surface vs the issue: the proposed surface is all here, plus
  logout (symmetry with auth logout; local-only — the help says a
  leaked key is disabled server-side via keys revoke) and
  keys update/regenerate (the issue summary's PATCH/rotation
  lifecycle; rotation kills the old value immediately and confirms
  first).
• URL resolution mirrors campus_python exactly: CAMPUS_AUDIT_URL
  → config file audit_url → ENV/CAMPUS_ENV (development Railway
  default; audit.campus.nyjc.dev/.app). No /audit/v1 prefix —
  AuditRoot.url_prefix carries it.
• Error handling covers both error shapes: campus_python maps
  non-2xx responses to errors.APIError (status + description), raw
  transport failures stay requests exceptions. 401/403 responses get
  standing remedy hints (re-login / widen the key).
• --dry-run works on every API-backed audit command with an
  audit-specific preamble (AuditRoot + API-key bearer) and shows only
  kwargs actually passed, matching the client/vault convention.
• Not exposed: the server's login-journey search filter
  (campus#803) — campus-api-python's traces.search() does not carry
  it yet; noted in the command help. Web counterpart remains
  campus#915.

Tests

• 277 passing (pytest), ruff clean (259 before the review
  follow-up; 18 new tests).
• New unit tests (tests/unit/test_audit.py): URL resolution
  precedence, endpoint binding, key input resolution, verification
  semantics per status, login/logout end-to-end, trace formatting,
  credential round-trip, APIError/HTTPError extraction.
• Dry-run integration tests: audit snippets carry the API-key
  preamble, omit unpassed fields, compile, and never touch the client;
  --dry-run documented in both new groups' help.

Review follow-up (12b62eb)

A review pass drove every command against a stub of the audit service and
cross-checked the client contract against the pinned campus-api-python and
the server's own routes and auth flow. The fixes that came out of it:

• fix(cli): campus.audit key status should distinguish expired from active #56 — the key status now distinguishes revoked / expired / active. A
  key with a future expiry is still active (the server counts it as such),
  so it no longer renders as expires; an expiry in the past renders as
  expired.
• fix(cli): report campus.audit credential-store failures instead of a traceback #57 — credential-store failures in the audit group are reported and
  exit 1 instead of escaping as a traceback (the login write, the client
  key read, the URL-binding read).
• chore(cli): auth logout should mention the stored campus.audit key #58 — campus auth logout names the still-stored campus.audit key
  and the command that clears it, so "logged out" does not read as "every
  stored credential is gone".
• chore(cli): campus.audit polish — message punctuation, --json on revoke, dry-run kwargs, README wording #59 — polish: no double full stop when the server's message is
  already a sentence, --json on keys revoke, keys list --dry-run
  shows only the arguments the caller passed, and the README leads with
  the env var / prompt for campus audit login and describes owner_id
  as a free-form label.

Three findings are left as issues rather than fixed here, with the
reasoning inline on the diff: #60 (audit error messages drop the HTTP
status when the response carries no description), #61 (the --json
output shapes differ between keys list and traces list), and #62
(no campus audit status equivalent to campus auth status).

Relates to campus#915 (web sign-in counterpart).

[ngjunsiang]

Reviewed the audit command group end to end: ran the full suite (277 passing, ruff clean), drove every command against a stub of the audit service, and cross-checked the client contract against the pinned campus-api-python (rev 89df17e) and the server's own routes and auth flow in nyjc-computing/campus.

The design holds up well — the URL binding, the 401/403 verification split (which matches the server's actual behaviour, not a guess), the once-only plaintext key printing via typer.echo, and the dry-run snippets all check out. The emitted snippets even run verbatim against a live stub.

Fixes pushed as 12b62eb (#56, #57, #58, #59): the key status now distinguishes expired from active, credential-store failures are reported instead of raising a traceback, auth logout names the still-stored audit key, and the small polish items (double full stop, --json on revoke, dry-run kwargs, README wording) are in.

Three items are left as issues, with the reasoning inline below.

[ngjunsiang]

Fixed in 12b62eb (#56). The status label used to come from the presence of expires_at alone, so a live key with a future expiry rendered as Status: expires and an expired key rendered identically — the operator could not tell a live key from a dead one without reading the date. _key_status now compares expires_at against the current time and reports revoked / expired / active, matching the server's APIKey.is_active(). An unparsable expiry is treated as active, not expired.

[ngjunsiang]

Open — #60. The str(e) fallback is empty for a campus_python APIError raised without an error_description, which is exactly what happens when the response body is not JSON (a proxy's HTML 502, an empty body, a 404 page from a misrouted deployment). The CLI then prints Failed to list API keys: . and drops the status code it already extracted a few lines up — the login warning shows the same empty parentheses. Falling back to the status (HTTP 502) would make these diagnosable; the same pass could surface the 422 field-level errors array, which the server sends and campus_python parses into APIError.errors but the CLI currently drops, leaving One or more fields are invalid with no indication of which field was rejected.

[ngjunsiang]

Open — #61. This prints just the array of key records, dropping the server's count, while campus audit traces list --json prints the whole server response including the pagination cursor. Two sibling commands, two JSON shapes — a script consuming both has to special-case one. Picking one shape for the group (the server response verbatim, as traces does) would settle it.

[ngjunsiang]

Open — #62. campus auth status (#45) answers "what can this stored credential do?", and the audit group has no equivalent: a trace-only student key cannot run campus audit keys list (it lacks apikeys:read), so the stored key's state is only visible when a command fails. The audit service has no "who am I" endpoint, so this would have to be a local view — the URL the key is bound to, the URL currently targeted, and whether a key is stored. The information the URL-binding check already uses would be worth surfacing.