Skip to content

README: people sign in, programs use keys - #263

Merged
webdevtodayjason merged 1 commit into
mainfrom
fable/login-docs
Sep 22, 2026
Merged

webdevtodayjason merged 1 commit into
mainfrom
fable/login-docs

Conversation

@webdevtodayjason

Copy link
Copy Markdown
Contributor

The README half of the front door login (#261). A person signs in to the dashboard with a name and a password now, and the session lasts until sign out or until an admin revokes it. Programs keep presenting an API key. The access control section said the key was the whole story, and that the dashboard asks for it on first open, so it described a node nobody will have after this ships.

Documentation only. No code, no test, no CHANGELOG.md, and no AGENTS.md: the invariants belong to the three branches building the feature, not to this one.

The docs site half is getainode/ainode-docs#8, which adds the page this README links to.

What changed

Place Change
Access control, installer paragraph It no longer says the dashboard asks for the key the first time you open the node. A person signs in there now, and the key is what a program presents. The rest of the paragraph (what the installer mints, AINODE_AUTH=off, an update never changing an installed node's state) is untouched
Access control, new paragraph People sign in, programs use keys. What each one presents, the two setup commands on the master, accounts replicated from the master with sessions per node, the two roles, the account page and the Users page, ~/.ainode/users.json at 0600 with hashes only beside auth.json, and a link to the docs page
Access control, the keyless list Gains /api/auth/me and /api/auth/login, each with its reason: the page has to be able to ask whether you are signed in, and the request that signs you in cannot need a session first
Join paragraph "It is one of five keyless paths" drops the count. tests/test_join_flow.py::test_the_readme_lists_the_join_route_among_the_keyless_ones asserts the paths and deliberately not a number, because the count is the half that drifts (it already said four while the middleware had five once)
CLI reference ainode auth user add NAME --admin, then the user verbs (list, passwd, disable, enable, remove) and the session verbs (list, revoke, clear) on one line each, beside the auth key lines that were already there

The two commands, as the README now prints them:

ainode auth user add <name> --admin
ainode auth enable           # only if this node is not requiring auth yet

Changelog text for the release PR

CHANGELOG.md is not touched here. This is the entry for the release PR to carry, under Changed:

- **The docs describe how a person gets in, not only how a program does.** The docs
  site has a new page next to API keys in the Security group,
  [Sign in and accounts](https://docs.ainode.dev/security/sign-in): why there is a
  login, the first account on a fresh node and on a fleet that is already running
  (`ainode auth user add <name> --admin`, then `ainode auth enable`), signing in, the
  account page, the Users page and the two roles, the `auth user` and `auth session`
  commands, why a login belongs behind HTTPS with the TLS page linked, the two files
  and their modes, the guard rails (HttpOnly and Secure cookie, the
  `X-AINode-Client: dashboard` CSRF header, ten failed sign-ins in five minutes
  pausing an address, scrypt hashes), the paths that stay open, and troubleshooting
  for locked out, no accounts yet and a revoked session. The README's access control
  section says people sign in and programs use keys, carries the two setup commands,
  and lists `/api/auth/me` and `/api/auth/login` among the keyless paths. Docs PR
  getainode/ainode-docs#8.

Gates

Markdown only, so neither pytest nor ruff is a gate on this diff. The house em dash check, on this branch:

$ grep -c $'—' README.md
0

The suite was not run here: this checkout has no aiohttp, so every test module that imports ainode.api.server fails collection. Nothing in the diff is code, and the one test that reads the README for this area (tests/test_join_flow.py::TestDocs) is satisfied by inspection: POST /api/cluster/join is still named, and every member of SKIP_PATHS except / and /api/cluster/join still appears in backticks. /api/auth/me and /api/auth/login are in the README before they are in SKIP_PATHS, so that test keeps passing when the login branches land.

Left out

  • No feature table row. Every row there carries a version, and the release that carries the login does not have one yet. It belongs in the release PR beside the changelog entry above.
  • No changelog edit. The text is in this body, per the release train.
  • No AGENTS.md edit. The users store, the session store and the login route are edit contracts owned by the branches writing them.
  • No API documentation for the login routes. The request and response shapes are not in this contract, and a guessed body is worse than no line. The docs PR says the same.
  • How long the sign-in pause lasts after ten failures, and what the doctor's Login check verdicts on: both are described in the release notes rather than invented here.
  • Nothing about the dashboard's key paste panel changing. Whether the login page replaces it, sits beside it, or keeps it as the automation fallback is the dashboard branch's call, so the README only says a person signs in and a program presents a key.

The access control section said the key was the whole story and that the
dashboard asks for it on first open. With the front door login (#261) a person
signs in with a name and a password and keeps a session; a key is what a program
presents. Documentation only, and `CHANGELOG.md` is not touched.

- **A new paragraph in Access control**: what a person presents and what a
  program presents, the two setup commands on the master (`ainode auth user add
  <name> --admin`, then `ainode auth enable`), accounts replicated from the
  master with sessions per node, the two roles, the account page and the Users
  page, `~/.ainode/users.json` at 0600 with hashes only, and a link to the docs
  site's new page.
- **The installer paragraph** no longer says the dashboard asks for the key on
  first open, because a person signs in there now.
- **The keyless list** gains `/api/auth/me` and `/api/auth/login`, with the
  reason for each: the page has to be able to ask whether you are signed in, and
  the request that signs you in cannot need a session first. The join
  paragraph's "one of five keyless paths" drops the count, which is the half
  that drifts (`tests/test_join_flow.py` asserts the paths, never a number).
- **The CLI reference** gains `ainode auth user add|list|passwd|disable|enable|
  remove` and `ainode auth session list|revoke|clear`.

No version number is claimed and no feature row is added: the release that
carries the login names it in the release notes. Docs site page:
https://docs.ainode.dev/security/sign-in (getainode/ainode-docs#8).

Co-authored-by: webdevtodayjason <jason4mail@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
@webdevtodayjason
webdevtodayjason merged commit 0b7e981 into main Sep 22, 2026
1 check passed
@webdevtodayjason
webdevtodayjason deleted the fable/login-docs branch September 22, 2026 00:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant