Files
canina/scripts/stage-author-bootstrap

Stage-only public author bootstrap

Implemented locally, not executed against Stage. No production mode, commit, push or recovery-gate override.

Official operation path

  1. Review/commit the integrated backend auth, public-author restoration service, Prisma client/schema, versioned SQL and these scripts/workflow together. This shared worktree is not yet a releasable SHA.
  2. Independently approve that exact SHA in repository secret STAGE_AUTHOR_BOOTSTRAP_REVIEWED_SHA through existing authorized repository administration. No new API token is needed by these scripts. Gitea 1.22 uses exact push refs, not workflow_dispatch.
  3. Push the same reviewed commit, only when authorized, to ops/author-bootstrap-stage-rehearse first, then ops/author-bootstrap-stage-apply. The new .gitea/workflows/stage-author-bootstrap.yml does not call deploy.sh: the existing normal Stage recovery gate cannot pass before this repair.
  4. CI fetches the immutable event SHA and invokes ci.py. The driver builds only backend/Dockerfile with revision label and records its immutable image ID before any credential-file prerequisites. No migrate, seed, app recreation or live DDL occurs during build. Build failure blocks the operation.
  5. Existing Stage runtime env is read privately from canino_backend_stage into mode0600 runner files, with exact DB URL identity validation. Nothing is printed. Clone config overrides database/Redis with isolated loopback instances while retaining the existing Stage JWT verification configuration. No JWT is minted and no auth guard is bypassed. Do not upload any env files or dumps.
  6. Parent browser assistance must provide a currently valid human admin bearer privately in a mode0600 regular file visible to the CI runner. Set repository secret STAGE_AUTHOR_BOOTSTRAP_TOKEN_FILE to its path, not token value. No implicit host path, credential, token or runner mount is invented here. Missing prerequisite blocks repair after the image build. /opt/data/cache/scratch/author-bootstrap-parent-assistance.json describes the outstanding browser handoff; that agent-local path is not automatically runner-visible.
  7. Rehearsal must pass before apply: fixed Stage identity and orphan baseline; retained original full dump; expected original FK restore failure; new clone pre-data/data; two transactional schema applies; authenticated API once; all post-data; new repaired dump restored fully into another clean clone. Original invalid archive is never overwritten or relabeled clean.
  8. Apply repeats the entire rehearsal, rechecks Stage identity/lock, applies one live schema transaction in dedicated exact-SHA CI, then starts a separate temporary maintenance API with STAGE_AUTHOR_RESTORATION_MODE=maintenance. It shares the fixed Stage backend network namespace for existing DB DNS and real Redis blacklist validation, but HTTP is forced to loopback 127.0.0.1:39071, never published, avoiding existing port3000. It runs immutable image node directly, without startup migration/seed. The only business writes are the authenticated restoration API. POST is never automatically retried after ambiguity.
  9. Rerun the unchanged full Stage recovery gate and normal release acceptance afterward. This receipt is not live recovery/deployment acceptance. If live DDL succeeds but API fails, inspect retained evidence before deciding any recovery; do not blindly rerun the orphan-baseline tool. Prisma ledger remains untouched; SQL is a separately applied Stage bootstrap artifact, not migrate-deploy/resolve.

Clone authentication uses both restored Stage user/session rows and a read-only Stage Redis RDB snapshot in a disposable no-network Redis. An empty blacklist would silently accept revoked tokens and is deliberately not substituted. The clone backend has STAGE_AUTHOR_RESTORATION_MODE=rehearsal. Snapshot staleness is bounded by the operation; live authentication independently uses real Stage Redis.

Practical prerequisites/blockers

  • Source is currently uncommitted; a reviewed exact SHA and authorized official ref push remain parent responsibilities.
  • Approved browser bearer and secure CI-runner-visible file handoff are outstanding. Do not expose token values in chat/logs or create replacement tokens.
  • Host read-only inspection confirmed Stage backend port3000, Redis redis_stage:6379, and no explicit JWT_ACCESS_SECRET/JWT_SECRET env. Existing auth code's configured fallback is reused unchanged; no replacement secret is synthesized. This existing fallback should be reviewed separately, never rotated during repair without coordinating sessions.
  • Runner must have Docker/Python/git, sufficient disk for three DB clones, one Redis clone and two full archives, and the existing host deployment lock inode. All operations have bounded individual deadlines. No pre-existing lock helper is reclaimed.
  • PostgreSQL image ID is pinned in operation.py and must match the exact Stage DB image or execution fails closed.
  • Private env/archive evidence is retained in a mode0700 runner directory, printed before execution. Delete credential copies using an explicitly approved retention/cleanup action afterward; never generic prune/delete other workers' containers or images. Owned disposable containers/anonymous volumes are removed by captured ID in reverse order. Immutable backend image is retained for the subsequent official operation, not discarded as a test image.

Tests

python3 -m unittest discover -s scripts/stage-author-bootstrap -v
python3 -m unittest discover -s scripts/stage-schema -v
python3 scripts/stage-author-bootstrap/operation.py --help

Tests exercise the actual CI Python entrypoint with command doubles (build/rehearse/apply, missing token after build, wrong SHA/ref before transport, build failure), maintenance isolation and original/post-data restore failure ordering. They are offline tests, not CI execution or real database rehearsal.

For controlled local clone-only diagnostic use, operation.py rehearse --sha ... --sql-sha256 ... --backend-image sha256:... --clone-env-file ... --clone-token-file ... --evidence ... accepts explicit private files. Live apply-schema additionally requires --live-env-file, independently reviewed SHA and the exact dedicated CI event/ref; do not spoof CI variables on SSH. Backend image revision label must match source SHA. SQL digest and committed tool/workflow contents are verified in CI.

CHECK scope is row-local; application auth must deny public-author principals centrally. Authors must be the five genuine configured UUIDs, isPublicAuthor=true, role User_PetOwner, no mobile/email/password/session/expiry and zero balances. No invented identity, phone number or privileged role is permitted.