commit cd7cd0d05ae69e9261f99c34091b6f59665ac312 Author: Jarvis Jr Hermes Date: Mon Oct 26 10:18:46 2026 +0000 chore: preserve existing installed recovery package baseline diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..2197040 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,73 @@ +--- +name: self-hosted-service-account-recovery +description: Use when restoring a disabled automation service account. +version: 0.1.0 +license: MIT +metadata: + hermes: + tags: [service-account, recovery, self-hosted, access, verification] + related_skills: [gitea-repository-operations, home-v1--truenas] +--- + +# Self-hosted Service Account Recovery + +Restore an explicitly authorized automation account on a self-hosted service without borrowing another agent's identity, changing unrelated security settings, or claiming recovery before every access path is independently verified. + +## When to use + +Use this skill when: + +- an automation account is disabled, inactive, suspended, or prohibited from login; +- both API and transport credentials are expected to recover after account reactivation; +- the service runs on infrastructure the operator is authorized to administer; +- ordinary work is blocked by account state rather than repository or object permissions. + +Do not use it for forgotten passwords, MFA reset, credential rotation, privilege elevation, or another account unless the user explicitly authorizes that exact action. + +## Workflow + +1. **Freeze identity and scope.** Record the exact service, account, requested target state, and approving human. Account-secret availability is not authorization. +2. **Prove the failure mode.** Check the account through each affected access path. Distinguish disabled/inactive state from expired credentials, insufficient scope, missing repository permission, proxy failure, or transport failure. +3. **Discover the supported recovery path.** Prefer the service's authorized administrator UI or API. Inspect the installed version and live command/API contract before choosing a mutation. +4. **Do not borrow identities implicitly.** Never switch to a sibling agent's token, key, or account merely because it is available. Use another identity only when the user explicitly authorizes it for this recovery. +5. **Capture pre-state.** Require one exact account record and retain only non-secret fields relevant to recovery. +6. **Mutate narrowly.** Change only the field that implements the authorized target. Use a conditional/idempotent mutation and require exactly one affected record. Stop on zero or multiple matches. +7. **Verify the control plane.** Re-read the exact account record in a fresh request/session. +8. **Verify every original access path.** Reuse the original token/key rather than generating replacements by default. For a source-control account, verify API identity and read-only Git transport independently. +9. **Resume blocked work only after verification.** Account recovery is complete only when the expected identity and transport succeed; it does not waive task-specific review, CI, approval, or deployment gates. +10. **Report precisely.** State the account, final active/login state, and independently verified access paths. Never include credentials or shell tokens. + +## Escalation and fallback rules + +- Prefer supported administrator operations over direct database changes. +- A direct database fallback requires exact account-level authorization, verified schema/installed version, one-row pre-state, a conditional one-row mutation, and multi-path post-verification. +- Do not restart the hosting service merely to clear account state unless the supported recovery contract requires it and the operational impact is separately authorized. +- Keep management-plane TLS exceptions bounded and explicit. Prefer a trusted CA or certificate-matching hostname; never normalize disabled verification for routine operations. + +## Reference procedures + +- For the validated Gitea-on-TrueNAS fallback, including the proxied app-shell route, single-use token handling, non-interactive PostgreSQL safeguards, and verification layers, read [`references/gitea-on-truenas-reactivation.md`](references/gitea-on-truenas-reactivation.md). + +## Pitfalls + +1. Treating a disabled account as a bad token and rotating credentials unnecessarily. +2. Using a different agent's identity without authorization. +3. Assuming an administrator CLI subcommand exists without checking the installed version. +4. Matching an account by a partial or guessed identifier. +5. Updating every disabled user rather than one explicitly authorized account. +6. Letting a PTY command wait on a password prompt or pager indefinitely. +7. Claiming recovery from a database update response without fresh API and transport checks. +8. Treating restored access as permission to bypass repository, review, CI, or deployment gates. + +## Verification checklist + +- [ ] Exact service account and target state were explicitly authorized. +- [ ] Disabled/inactive state was distinguished from credential and permission failures. +- [ ] Supported admin path was checked first. +- [ ] No alternate agent identity was used implicitly. +- [ ] One exact account record was captured before mutation. +- [ ] The mutation was conditional and affected exactly one record. +- [ ] Fresh control-plane readback shows the intended state. +- [ ] Original API identity works and resolves to the expected account. +- [ ] Original secondary transport works independently. +- [ ] No credentials, generated tokens, or database passwords were exposed. diff --git a/references/gitea-on-truenas-reactivation.md b/references/gitea-on-truenas-reactivation.md new file mode 100644 index 0000000..874bba9 --- /dev/null +++ b/references/gitea-on-truenas-reactivation.md @@ -0,0 +1,50 @@ +# 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: + +```sql +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.