Skip to content

API for scripts and agents: scoped tokens, plan/patch + base_rev, mr get/set, mr schema (#17, #38) - #67

Merged
Cd1s merged 1 commit into
mainfrom
feat/api-tokens
Sep 25, 2026
Merged

Cd1s merged 1 commit into
mainfrom
feat/api-tokens

Conversation

@Cd1s

@Cd1s Cd1s commented Sep 25, 2026

Copy link
Copy Markdown
Owner

What

Scoped API tokens (mr/api_token.go, module api).

  • Defined in api.tokens in router.yaml; secrets.yaml holds only api_token_<name>: sha256:<hex>. The token (mrt_ + 32 random bytes) is shown once.
  • Only Authorization: Bearer mrt_… authenticates (constant-time hash compare) — no cookie, no X-MR, so no CSRF.
  • Scopes read < operate < apply over an explicit action table; any action not listed (including future module actions) is refused. Optional allow (mon.*), from (CIDRs), expires.
  • No token can reach: the web password, login / sessions, logs, backup / restore, firmware, factory reset, reboot, SSH keys, subscription fetches / share-link parsing, list files, the DNS query log, token management.
  • A token's change (403) may not touch api, services.ssh, system.sysctl, the guard, point a *_file key at a new file, or add / change any item that references a secret (proxy node, PPPoE WAN, SSID, DDNS record — otherwise it could point the router at its own host and have the secret sent there; removing is allowed). A token cannot set token hashes, settles only its own pending change, needs base_rev for a whole config. Applies recorded as via=api:<name>.
  • Bad tokens count in the login throttle; a locked source is refused even with a valid token.
  • Last use in /run on every request, on flash at most hourly. CLI mr token list|create|revoke; web UI card under 管理与 SSH (the browser generates the token and sends only its hash).

plan / patch / base_rev (mr/api_plan.go). GET config returns rev (hash of router.yaml); POST plan is a dry run (errors, config-level changes, files, services); validate / plan / apply accept a patch ([{op: set|add|del, path, value}]); a stale base_rev gets 409 — the web UI now sends it too, so a browser and an agent cannot silently undo each other.

Config paths and mr get / set / add / del / export (mr/cfgpath.go). firewall.forwards[nas].enabled, [key=value], [N], quoted keys. Edits go through the layout-keeping editor (#11); the result must decode and validate before it is written; del returns a value to its default; export --flat | --json. Never prints secrets.

mr schema [PATH] / GET schema (mr/schema.go): JSON Schema from the Go types by reflection, with enums from the existing value sets — for editors and for #37's MCP tool schemas. This completes #38 (guard and risk levels came with #61).

Docs: new docs/api.md (tokens, scopes, endpoints, path syntax, curl examples), MODULES.md, sys.md, the skill (agents should use mr get/set + plan rather than editing router.yaml by hand).

Verification

  • Go tests: scopes / sources / expiry / throttle / validation; locked paths, the guard, secret-referencing items (new node reusing a secret, a node pointed elsewhere → refused; removing → allowed); token create + revoke restore a byte-identical file; path parsing; in-place edits keep comments; flat export round trips over the home and lab configs; mr set / del; patch + stale base_rev; schema checked against the home and lab configs.
  • CI step 5 runs the real mr api CGI with bearer tokens: scopes, sources, expiry, no secret value in any answer, plan on good / bad patches with 403 / 409 / 400, no apply job started, 20 parallel bad tokens → 5 × 401 + 15 × 429.
  • busybox httpd (1.36 / 1.37 source) passes Authorization: Bearer to CGI as HTTP_AUTHORIZATION.
  • tools/ci.sh passes (private and public trees).

Closes #17 · Closes #38

https://claude.ai/code/session_01HWeUjo1dmS7gBkCYHrVjCr

…, mr get/set, mr schema

- Tokens (api.tokens; secrets.yaml holds sha256 only): `Authorization: Bearer mrt_…` only, scopes
  read < operate < apply over an explicit action table, optional allow / from / expires; never the
  password, logs, backup / restore, firmware, reboot, SSH keys or token management; a token's change
  may not touch api, services.ssh, system.sysctl, the guard, new *_file paths, or add / change an item
  that references a secret. Bad tokens count in the login throttle. `mr token list|create|revoke`;
  web UI card.
- GET config returns rev; POST plan (dry run: errors, changes, files, services); validate / plan /
  apply accept a patch ([{op, path, value}]); a stale base_rev gets 409 (the web UI sends it too).
- Config paths (firewall.forwards[nas].enabled, [key=value], [N]): mr get / set / add / del / export,
  edits keep router.yaml's layout, never print secrets.
- mr schema [PATH] / GET schema: JSON Schema from the Go types.
- Tests; CI runs the real `mr api` CGI with tokens (scopes, sources, expiry, no secret in any answer,
  plan / 403 / 409 / 400, 20 parallel bad tokens -> 5 x 401 + 15 x 429). docs/api.md.

Closes #17
Closes #38
@Cd1s
Cd1s merged commit 8d3b744 into main Sep 25, 2026
2 checks passed
@Cd1s
Cd1s deleted the feat/api-tokens branch September 25, 2026 18:44
@Cd1s Cd1s mentioned this pull request Sep 25, 2026
52 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant