Skip to content

MCP 1: agent credentials (grants, hashed tokens, ApiUser, Connected apps) and the owner's switch #167

Closed

Description

@alexbeeken

Part of #166. First of six. Read "Shared design" and the threat table in #166 before starting; the names and numbers there are fixed.

What this issue is for

  • The owner's switch Let apps connect on Manage Users, off by default. Everything below does nothing while it is off.
  • One store for every connection, api_grants, and the tokens under it, api_tokens. Tokens are stored as SHA-256 only.
  • A second extractor, ApiUser, built only from Authorization: Bearer …. One probe route to test it: GET /api/v1/whoami (the account's id, the app's name, the scopes).
  • Connected apps on the profile: each grant with its name, scopes, courses, created, expires and last used, and Revoke. Below it, Make a token: a name, the scopes, an optional course list, an expiry (30 days, 90 days, a year). It asks for the account's password again, then shows the token once with a Copy button.
  • The owner sees every account's grants on Manage Users (app name, account, last used, expires) and can revoke any of them. A superuser does not see them.

Security rules for this issue

  • Hashed at rest. No token and no hash appears in any page, log line or error. A test reads the database after making a token and finds no plain token.
  • Bearer only. A cookie on /api/v1/whoami gets 401. A bearer token on /profile gets the sign-in redirect. The proxy sign-in header gives no API access.
  • Never in the address. A request with ?access_token= or ?token= is refused with 400, even beside a good header.
  • Checked on every request, not cached past it: the switch is on, the grant exists and has not expired, the account still has Create courses, the account is not waiting behind a temporary-password change. Any "no" is a 401 with an empty body that names nobody.
  • Constant work for a bad token. Look tokens up by hash, so timing says nothing about a near miss.
  • Revoked by events. Changing the password, the owner setting a temporary password, and the owner turning off two-factor for the account each delete every grant of that account. Say so on those screens.
  • Making a token is a sensitive action. It needs the current password in the same form, is counted by PASSWORD_PER_USER, and is not offered to a session that came from the proxy header without a password (that account has none to check; it uses OAuth from issue 3 instead).
  • Limits. Ten bad tokens per address in ten minutes, then 429 (security::RateLimits, keyed by security::client_ip). At most 4 grants per account and a cap on rows in both tables in src/caps.rs; a fifth grant is refused with a message saying to revoke one.
  • Expiry is real. Expired grants and tokens are purged in the job that purges sessions. No grant without an expiry.
  • Deletion. Both tables reference users with ON DELETE CASCADE, and are in docs/data-inventory.md.
  • last used is written at most once a minute per grant, so reads do not turn into SD-card writes.

Not here

/mcp (issue 2), OAuth (issue 3). No course route yet.

How to QA it

  • Run it: the dev server (./.dev-start --reset --seed --background, then /dev/login), or a release build (scripts/release-qa/matrix.sh dist to check a tarball you built; cd scripts/release-qa && docker compose up -d, then the owner link from docker compose logs). You are the owner.
  • Open Profile. There is no Connected apps section.
  • Open Manage Users. Under the AI switch there is Let apps connect, off. Turn it on.
  • Open Profile again. Connected apps says no app is connected, with Make a token under it.
  • Click Make a token, name it Test, leave the defaults, type a wrong password, click Make. You see the password error and no token.
  • Do it again with the right password. A dialog shows a token starting with skr_ and says it will not be shown again. Copy it and close. The list shows Test, both scopes, expires in 90 days, never used.
  • In a terminal: curl -H "Authorization: Bearer <token>" <url>/api/v1/whoami prints your id, Test and the scopes. Reload the profile: last used now has a time.
  • curl <url>/api/v1/whoami with one character of the token changed prints nothing and the status is 401 (-i to see it).
  • curl -i "<url>/api/v1/whoami?access_token=<token>" answers 400.
  • In a private window, register a second account. As the owner, make it a Student on Manage Users. As that account, Profile has no Connected apps section.
  • As the owner, Manage Users lists the Test grant under Connected apps with your address. Click Revoke there. The curl from before now answers 401 and the profile list is empty.
  • Make another token, then change your password on the profile. The page says your connected apps were disconnected, and the token answers 401.
  • Make another token, then turn Let apps connect off. The token answers 404. Turn it on: the token works again.

House rules for this repository

  • Read CLAUDE.md first, then docs/architecture.md ("Where things live").
  • Never run cargo fmt.
  • App text goes in i18n/en.yaml and, translated, in the five other language files.
  • A new migration is the next src/db/migrations/vNNN_<name>.sql, appended to MIGRATIONS; update the schema-version asserts in src/db/tests.rs and the tables in docs/architecture.md and docs/data-inventory.md.
  • No new crate. A source file stays under 1,500 non-test lines.
  • Add a line under "Unreleased" in CHANGELOG.md, written for the person running the server.
  • For reference only, the hosted app's version of this lives in alexbeeken/skrongle (src/auth/api.rs, src/oauth_server.rs, src/mcp.rs, src/routes/mcp.rs, docs/security-oauth-mcp.md). Don't copy what a mini has no use for: no publish scope, no REST routes, no vendor client list, no e-mail or Google sign-in.

Activity

  1. added
    mcpLetting an AI assistant connect (MCP, OAuth, tokens)
    on Nov 12, 2026
  2. alexbeeken commented on Nov 12, 2026

    @alexbeeken
    OwnerAuthor

    Implementation notes (where things are in this repo)

    Checked against main on 2026-11-12. Line numbers drift; search for the names.

    • Reference implementation. The hosted app's checkout is at ~/Code/spanish-learning (read only, do not change it): src/auth/api.rs (grants, tokens, ApiUser), its tests in src/auth/api/tests.rs, and docs/features-connected-apps.md. Port the ideas, not the file: leave out courses:publish, suspension, account export, REST routes and anything about e-mail or Google.
    • New module src/auth/api.rs (there is already src/auth/cache.rs): the Scope enum, Grant, mint, user_for_token, revoke, revoke_all_for_user, purge_expired, and the ApiUser extractor. Routes in a new src/routes/api.rs (whoami) and src/routes/profile/apps.rs (the Connected apps forms). Keep src/auth.rs and src/routes/profile.rs from growing: both are large.
    • Hashing. Session tokens are hashed with auth::hash_token (see DELETE FROM sessions WHERE session_token = ?1 in src/auth.rs). Use the same function for API tokens. Random bytes: random::fill (src/random.rs). Encode the 32 bytes as hex or base64url after the skr_ prefix with what is already in Cargo.toml.
    • Password check for Make a token: auth::verify_password_async (src/auth.rs), as routes::profile::change_password does. Count it with security::PASSWORD_PER_USER.
    • The switch. src/settings.rs has AI_OFF, ai_off and set_ai_off; add APPS_ON, apps_on and set_apps_on beside them (stored "1" when on; absent means off). The form is routes::manage::set_ai and its part of templates/manage.html; add a sibling route POST /manage/apps and a sibling switch. If CurrentUser carries ai_off from a cache (src/auth/cache.rs), do the same for apps_on so no request pays an extra query.
    • Events that revoke. Call revoke_all_for_user in the same Db::call as: routes::profile::change_password, routes::password::change, routes::manage::set_temp_password, routes::manage::turn_off_two_factor.
    • The gate behind a temporary password is CurrentUser::must_change_password / AppError::ApiPasswordChangeRequired; ApiUser reads users.must_change_password and answers 401.
    • Permission. Perm::CreateCourses in src/perms.rs; owners have every permission. ApiUser needs the same rule CurrentUser::can uses; share the function rather than copy it.
    • Limits. Add API_BAD_TOKENS_PER_IP beside LOGIN_PER_IP in src/security.rs; the client address is security::client_ip. Row caps go in src/caps.rs beside MAX_SESSIONS_PER_ACCOUNT.
    • Purge. Expired sessions are deleted by the DELETE FROM sessions WHERE expires_at < ?1 function in src/auth.rs; find its caller and call purge_expired from the same place.
    • Routes are registered in routes::router (src/routes/mod.rs), the /manage/... and /api/profile lines show the style. /api/v1/whoami must not sit behind any layer that reads the session cookie to decide access.
    • Errors. src/error.rs has Unauthorized, ApiNoPermission, ApiTooManyRequests. Add what is missing (an empty-body 401 for the API, a 400 for a token in the address); do not reuse a variant that renders a page.
    • Migration. Next file after src/db/migrations/v005_error_kind.sql (check what is newest on main first). Two tables: api_grants(id, user_id REFERENCES users ON DELETE CASCADE, client_id, client_name, scopes, courses, created_at, expires_at, last_used_at) and api_tokens(id, grant_id REFERENCES api_grants ON DELETE CASCADE, kind, token_hash UNIQUE, expires_at), with an index on api_tokens(expires_at) and api_grants(user_id). kind is personal, access or refresh (issue 3 uses the last two).
    • Tests live beside the code (src/auth/api/tests.rs) and in src/routes/tests.rs style for the HTTP checks. One browser spec e2e/specs/connected-apps.spec.ts (read .claude/rules/e2e.md and docs/testing.md "Markup hooks" first): switch on, make a token, see it listed, revoke.
    • Docs to touch: docs/features.md (a "Connected apps" section), docs/architecture.md ("Where things live", the route list, the schema), docs/data-inventory.md, docs/testing.md (the test ids), docs/self-hosting.md (one paragraph on the switch).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    mcpLetting an AI assistant connect (MCP, OAuth, tokens)

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions