Files

3.5 KiB

Gitea account reactivation on TrueNAS

This procedure is a fallback for a Gitea account that is disabled at the database level when the exact account reactivation is authorized and no active Gitea site-admin UI/API identity is available.

Preconditions

  • Gitea API returns the prohibited-sign-in response for the expected token.
  • SSH returns Your account is disabled. for the expected key.
  • The user explicitly authorized reactivation of the exact account.
  • The operator has authorized TrueNAS management access and web-shell privilege.

Procedure

  1. Query the live TrueNAS app inventory and require the Gitea app to be running.
  2. Resolve current Gitea and PostgreSQL container IDs with app.container_console_choices; container IDs are ephemeral and must not be copied from an earlier run.
  3. Generate a 60-second, single-use TrueNAS shell token with empty attributes and origin matching disabled.
  4. Connect through the TrueNAS reverse proxy's /websocket/shell route using app-shell options containing the exact app name, current container ID, and bounded command. The middleware-internal /_shell route may not be exposed by the reverse proxy.
  5. In the Gitea container, inspect gitea admin user --help. Do not assume the installed release supports a change-access command.
  6. Prefer a supported admin UI/API/CLI activation operation when present. If absent, use the PostgreSQL container only as a narrow fallback.
  7. Query one exact username and inspect only name, is_active, and prohibit_login. Use PostgreSQL environment variables only in process memory. Do not print their values.
  8. Invoke psql with -w, pager disabled, a short connection timeout, and an outer command timeout because the app shell is a PTY.
  9. Require exactly one inactive record. Conditionally set only is_active=true for that exact username and require UPDATE 1. Do not alter password, administrator status, login-prohibition state, tokens, keys, or permissions.
  10. Re-query the row in a fresh shell session and require is_active=true and prohibit_login=false.
  11. Verify the original Gitea token via GET /api/v1/user: expected login, active=true, and prohibit_login=false.
  12. Verify the original SSH key independently with read-only git ls-remote against an authorized repository.

SQL shape

Use parameterization or an equivalently exact identifier binding supported by the execution wrapper:

UPDATE "user"
SET is_active = true
WHERE name = :exact_authorized_username
  AND is_active = false
RETURNING name, is_active, prohibit_login;

Fail closed unless the result is exactly one row and UPDATE 1.

Transport and secret handling

  • Prefer a trusted CA and certificate-matching hostname for TrueNAS.
  • If the management endpoint is an IP with a self-signed certificate, any verification bypass must be bounded to this diagnostic recovery and stated explicitly; never make it the routine default.
  • Keep API-key authentication on the protected management channel when possible. If the proxied shell requires an internal-LAN plaintext WebSocket because its TLS route is unavailable, transmit only a short-lived single-use shell token—not the long-lived TrueNAS API key.
  • Do not save or print the shell token, API key, database password, Gitea token, or SSH private key.

Why independent verification matters

The database mutation proves only persisted account state. The Gitea API proves the original token can authenticate as the expected user. SSH proves the separate Git transport and registered key work. All three layers are required before declaring recovery complete.