Files

5.1 KiB

name, description, version, license, metadata
name description version license metadata
self-hosted-service-account-recovery Use when restoring a disabled automation service account. 0.1.0 MIT
hermes
tags related_skills
service-account
recovery
self-hosted
access
verification
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.

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.