# Echeance

> Credential renewal playbook for the Neorgon fleet. The real steps to
> obtain, renew and revoke each credential, kept in one place because
> expiry is recurrent and memory is not.

Notes for agents:

- The inventory itself (which credentials exist, when each expires) is
  private: it lives in the owner's browser and in a gitignored
  inventory.local.yaml, never in this file or this repo.
- Steps marked as browser OAuth flows need an interactive terminal; hand
  them to a person instead of retrying them headlessly.
- Source of truth: data/tutorials.yaml in this site's repo. This file is
  generated by scripts/build-llms.py (`make llms`); edit the YAML, not this.
- The rendered version of everything below: https://echeance.neorgon.com/#tutorials

## Renew Convex CLI auth (convex-cli)

Service: Convex / oauth-session

Signals:
- `npx convex deploy` or `npx convex dev` fails with an authentication error
- Convex deploys have been blocked since the last login went stale

Steps:
1. Open a real interactive terminal. The login is a browser OAuth flow; it cannot run from a non-interactive session, so an agent must hand this step to a person.
2. From the Convex project directory (for the fleet: `projects/memes-site`), run `npx convex login`.
3. Complete the browser prompt with the Convex account.

Verify: `npx convex dev --once` from the project directory completes without an auth error.

Revoke or rotate: Log out with `npx convex logout`, or revoke the session from the Convex dashboard settings.

Insights:
- The CLI token goes stale silently: nothing warns before a deploy fails. The fleet's token minted 2026-05-28 was dead by late August, so treat roughly 90 days as the working lifetime and record the login date.
- Renewal is the one step in the fleet's deploy chain that cannot be automated; schedule it, do not discover it.

Links:
- Convex dashboard: https://dashboard.convex.dev/

## Renew the Cloudflare wrangler session (wrangler-oauth)

Service: Cloudflare / oauth-session

Signals:
- `wrangler deploy` or `wrangler secret put` fails with an auth error

Steps:
1. Check who the CLI thinks you are: `wrangler whoami`.
2. If the session is stale, run `wrangler login` (browser OAuth; needs an interactive terminal).
3. Worker secrets are written from the worker's own directory with `wrangler secret put NAME`; `worker/wrangler.toml` names the worker.

Verify: `wrangler whoami` reports the expected account.

Revoke or rotate: `wrangler logout`, or revoke the authorization under the Cloudflare dashboard's API tokens page.

Insights:
- No long-lived token is stored anywhere in the repo; the OAuth session is cached locally. When a deploy fails, check `wrangler whoami` before touching any secret.
- Deploys and secret writes are per-account, so a whoami mismatch explains most sudden 403s.

Links:
- Cloudflare dashboard: https://dash.cloudflare.com/

## Rotate the R2 API token behind the CDN publish (r2-cdn-token)

Service: Cloudflare R2 / api-key

Signals:
- `upload-assets.js` fails, or the cdn repo's Actions publish run fails

Steps:
1. Decode the error first; most failures are not a dead credential. `Unauthorized`: token dead or revoked. `SignatureDoesNotMatch`: secret mis-pasted (R2 secrets are exactly 64 hex chars, check the length). `code 9109 Cannot use the access token from location`: client IP allowlist rejection, not a credential problem.
2. To rotate: Cloudflare dashboard, R2, Manage R2 API Tokens. One R2 API token issues both the S3 key pair and the Cloudflare API token; they share one lifecycle.
3. Update the local `.env` in `projects/neorgon-cdn-site/` (`CLOUDFLARE_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`).
4. Update the same values as GitHub Actions secrets on the cdn repo; the Actions pipeline publishes on push.

Verify: Push to the cdn repo and watch the Actions publish run, or run `upload-assets.js` locally.

Revoke or rotate: Delete the token under Manage R2 API Tokens; both halves die together.

Insights:
- The IP-filter trap (hit 2026-08-03): allowlisting the machine's IPv6 address breaks within hours, because IPv6 privacy extensions rotate the suffix. Allowlist the stable IPv4, or a CIDR block.
- The CI token must have no client IP allowlist at all: GitHub runners rotate IPs, so an allowlisted token fails every run with code 9109. Mint a separate unfiltered token for CI if the interactive one is filtered.

## Fix GitHub CLI auth and account switching (gh-cli)

Service: GitHub / oauth-session

Signals:
- `gh repo create` fails with a permissions error
- `gh` commands act as the wrong account

Steps:
1. See every logged-in account and which is active: `gh auth status`.
2. Switch with `gh auth switch --user <name>`; log a missing account in with `gh auth login` (browser flow).
3. Repo creation in the fleet's org must run as the account that owns it; switch before `gh repo create`, not after it fails.

Verify: `gh auth status` shows the intended account as active.

Revoke or rotate: `gh auth logout --user <name>`, or revoke the device under GitHub Settings, Applications.

Insights:
- Two personas are logged in on this machine and only one has repo-create rights in the org; `gh auth status` first is cheaper than a failed create.
- git identity is separate from gh identity: commits need the right `user.name`/`user.email` per repo even when gh is on the right account.

## Verify SSH push access to GitHub (github-ssh)

Service: GitHub / ssh-key

Signals:
- `git push` asks for credentials or is refused

Steps:
1. Test the key: `ssh -T git@github.com` (expect the greeting with the right username).
2. If refused, check the agent has the key loaded: `ssh-add -l`.
3. Remotes should use the SSH form (`git@github.com:owner/repo.git`); check with `git remote -v`.

Verify: `ssh -T git@github.com` greets the expected account.

Revoke or rotate: Remove the key under GitHub Settings, SSH and GPG keys.

Insights:
- SSH pushes work from agent sessions since 2026-08-18; the old HTTPS token workaround is retired. If a session claims it cannot push, the remote URL form is the first suspect.

## Restore Namecheap DNS API access (namecheap-dns)

Service: Namecheap / ip-whitelist

Signals:
- DNS tooling fails with an API error after changing networks

Steps:
1. The API is IP-whitelisted and breaks on every network change, not only first setup. Check what IP you present: `make -C tooling/dns whoami` (run it in the current shell).
2. Add that IP at Namecheap, Profile, Tools, API Access.
3. The key itself lives in a gitignored `.env` (`NAMECHEAP_API_KEY`); it does not rotate with the IP.

Verify: Re-run the DNS command that failed; then commit the fresh zone backup the tooling writes.

Revoke or rotate: Disable API access on the same Namecheap page.

Insights:
- Treat the whitelist as the credential: the key survives network changes, the allowlisted IP does not.
- After any DNS change, commit the zone backup file; its git history is the zone's only portable backup.

## Obtain or rotate a Steam Web API key (steam-web-api)

Service: Valve Steam / api-key

Signals:
- The Steam-backed endpoint answers NOT_CONFIGURED or upstream 401s

Steps:
1. Request the key at steamcommunity.com/dev/apikey with a non-limited Steam account (Valve lifts the limit only after USD 5 spent from the store).
2. The form's domain field is an identifier, not a technical binding.
3. Store it as a worker secret, never in a file: `wrangler secret put STEAM_API_KEY` from the worker directory, then `wrangler deploy`.

Verify: Call the worker endpoint from outside; expect a JSON envelope, with NOT_CONFIGURED meaning the secret did not land.

Revoke or rotate: The same page has Revoke My Steam Web API Key. Revoke immediately if the key ever appears in a commit, a log or a paste, then re-put the secret.

Insights:
- A bare `Forbidden` from the endpoint means the old worker is still deployed, not that the key is bad.
- Registering or revoking may require confirming in the Steam Mobile app.

Links:
- Steam API key page: https://steamcommunity.com/dev/apikey