Files
canina/docs/stage-test-principal.md

3.1 KiB

Temporary Stage editorial reviewer (disabled by default)

Authority: repository write/CI-dispatch permission plus the existing authenticated, pinned Stage deployment SSH boundary. This is a narrowly scoped seed operation, not an API-key actor, owner JWT, or a public bootstrap endpoint. The destructive legacy seed is not used. AdminService shares its normal hashing/persistence and relational cleanup implementation with the internal command; normal user mutation role checks remain unchanged. The canonical default administrator is untouched.

Activation after independent review

  1. Promote this commit through the normal Git/CI Stage deployment. Do not run the seed command against an old image: the embedded immutable SHA must match. Apply the additive migration through the existing migration deployment step.
  2. Dispatch Owner authorized Stage test principal on develop with approval exactly owner-authorized-stage-editorial, unique session such as editorial-20261024-a, ttl explicitly 600 (maximum 3600), and action=open. The workflow uses existing DEPLOY_KEY / pinned DEPLOY_KNOWN_HOSTS only.
  3. CI reports only /app/private-stage-test/<session>.json inside canino_backend_stage. This mode-0600 file in a mode-0700 directory contains the process-generated password and real persisted-account login tokens. Consume it only from an approved in-container CI HTTP process; never print, download, publish as an artifact, or type it into a browser. No owner secret is needed. Audit records contain events, session and SHA, never credentials.
  4. Use this independent reviewer for Gate1 only; the proposer/PMO must be a distinct actor. Existing self-review checks are not changed. This session does NOT authorize Gate2, publication, release, general admin APIs, worker identity replacement, or budget increases. Approve a separate explicit bounded test budget before running inference; unknown prior reservations remain retained.
  5. Dispatch the same workflow/session/ttl with action=close immediately after tests. This revokes persisted authentication BEFORE relational deletion and removes the private credential file. Close is idempotent when absent.

A durable root-owned host cleanup journal and boot/periodic systemd retry worker must be provisioned before opening a session. Cleanup follows the current Stage artifact but retains the original exact session and generation fence; persisted expiry cannot be extended. See cleanup verification and promotion prerequisites. No live host services are changed by review tests.

Verification

Unit guards and existing independent self-review/role tests run with Jest. stage-test-principal.integration.spec.ts is opt-in via STAGE_PRINCIPAL_DISPOSABLE_TEST=true and requires a database URL ending in /principal_disposable; use a new isolated Postgres and Redis, then remove both. It verifies real account persistence/hash, signed access/refresh login tokens, collision refusal, nonrenewing retries, request scope, expiry, deletion/revocation. Never run it against Stage or Production.