74 lines
5.1 KiB
Markdown
74 lines
5.1 KiB
Markdown
---
|
|
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.
|