Repository navigation
Description
The plan for letting a person's AI assistant (Claude Code, Claude, ChatGPT and others that speak MCP) make and edit that person's courses on a Skrongle mini. The assistant writes the course; Skrongle checks it and stores it. The work is split into the issues listed at the end; this one holds the design they share and the threat list they must meet.
The hosted Skrongle already has this (alexbeeken/skrongle #1720, #1721, #1722, #1725 and its docs/security-oauth-mcp.md). This plan is that design cut down to a mini: one box, at most 50 accounts, often on a home network over plain HTTP, sometimes behind a reverse proxy on a path such as /skrongle.
What this is for
- A person connects an assistant to their own account and asks it for a course. The course shows up on their course list.
- It works on a home network with a client that runs on the person's own computer. It also works with cloud clients (claude.ai, ChatGPT) on a server that has a public HTTPS address.
- It is off until the owner turns it on. With it off, none of the new routes do anything.
- Skrongle makes no outgoing request for any of this and spends no AI allowance: the assistant is the model. This keeps the "one shape" rule.
Shared design (every issue relies on these names and numbers)
The owner's switch. A server-wide setting beside Hide AI features for everyone on Manage Users: Let apps connect (settings::APPS_ON, off on a new and on an upgraded server). Off means: /mcp, /oauth/*, the discovery documents and token creation answer 404, every existing token stops working at its next request, and the profile shows no Connected apps section. Turning it on again brings existing grants back. It is separate from the AI switch, because nothing here uses the server's AI keys.
Who may connect. An account needs Create courses (Perm::CreateCourses) to connect an app or make a token, since making courses is all an app can do. A Student has no Connected apps section. An account that loses the permission keeps its grants but every request from them is refused until it has the permission again. No new permission in this plan.
Grants. One row per connection, table api_grants: the account, the app's name and client id, the scopes, an optional list of course ids, created, expires, last used. Deleting the row ends the connection at the next request. A grant always has an expiry: 30 days, 90 days (the default) or a year. There is no "until revoked". At most 4 grants per account (caps::MAX_GRANTS_PER_ACCOUNT), as for sessions.
Tokens. 256 random bits from src/random.rs, shown once, with a fixed prefix so a leaked one can be recognised (skr_). Only the SHA-256 is stored, as for sessions. Access tokens from OAuth last one hour and come with a refresh token that works once. A personal token (made by hand on the profile) lasts as long as its grant.
Scopes. Two, fixed: courses:read (list the account's own courses, read their files, read the course format, validate) and courses:write (create a course, replace files). Nothing else exists to ask for.
What an app can never do, whatever its scopes: read or change another account's course, read a course that was only shared with the account (its text comes from someone else and could carry instructions for the assistant), make or remove invitation links, read anyone's progress, answers, notes or profile, touch accounts, permissions, settings or AI keys, start an AI job, delete a course.
Two kinds of sign-in, never mixed. API routes read only Authorization: Bearer … through a new extractor, ApiUser, beside CurrentUser in src/auth.rs. A session cookie authorises nothing on an API route, and a bearer token opens no page. The proxy sign-in header (SKRONGLE_PROXY_AUTH_HEADER) never stands in for a token.
Not found, not forbidden. Anything that is not the account's own answers as missing. A missing scope is the one 403 (insufficient_scope).
Addresses. Every URL Skrongle hands out (discovery documents, the WWW-Authenticate header, course links) is built from SKRONGLE_PUBLIC_URL and SKRONGLE_BASE_PATH, never from the request's Host header.
Memory and size. No new crate: JSON-RPC and OAuth are written with what is already in the tree (serde_json, sha2, getrandom). No SSE stream and no MCP session state, so a connected app holds no connection open (the server takes 128 at once). Request bodies are capped at the course limits (SKRONGLE_COURSE_BYTES). Every new table has a row cap in src/caps.rs. scripts/pi-budget.sh must still pass.
Release. New tables mean a database change, so this ships in a minor release.
Threats every issue is checked against
| Threat | What stops it | Issue |
|---|---|---|
| A stolen database gives working tokens | Only hashes are stored | #167 |
| A token leaks through a log, a history or a link | Tokens are never accepted in the address, never logged, shown once | #167, #168 |
| A web page uses a signed-in browser against the API | Bearer only; cookies do nothing there | #167 |
| A web page on the home network reaches the box by DNS rebinding | Any request with an Origin header is refused on /mcp; no CORS headers anywhere |
#168 |
| An app does more than the person allowed | Two scopes, an optional course list, own courses only | #167, #168 |
| A shared course's text steers the assistant | Shared courses are not readable through the API | #168 |
| Tokens are guessed | 256 bits, plus a limit on bad tokens per address | #167 |
| One app floods a Pi Zero | Per-grant request limit, the account's course-write limits, body caps, no open streams | #168 |
| A child's account connects an unknown app | Off by default; needs Create courses; the owner sees and can revoke every grant | #167 |
| A forgotten connection lives for ever | Every grant expires; expired rows are purged with sessions | #167 |
| A password change or a temporary password leaves an attacker's app connected | Both revoke every grant of the account | #167 |
| A stolen authorization code is used | PKCE S256 required; a code works once, for ten minutes | #169 |
| The code is sent to an attacker | Exact redirect match; HTTPS or loopback only | #169 |
| A look-alike app asks for consent | The consent page names the app and the host the answer goes to | #169 |
| Registration fills the SD card | Row cap, per-address limit, unused registrations gone in a day | #169 |
| A token is sent in clear on a public network | OAuth redirects need HTTPS; the docs say what plain HTTP on a home network means | #169, #171 |
Accepted risks (say so in the docs, don't engineer around them)
- On plain HTTP inside a home network a token crosses the network in clear, as the session cookie already does. Someone who can read the network can use it until it is revoked.
- Dynamic registration lets an app choose its own name. The consent page shows the host too.
- Rate limits live in memory and start empty after a restart.
Decisions I made that you may want to overrule
- Off by default, one owner switch, separate from the AI switch.
- No new permission; Create courses is the gate.
- No scope for sharing, progress or accounts. (The hosted app has an issue for a teacher's agent managing student accounts; that is left out here on purpose.)
- Personal tokens come first because they work on every install. OAuth is the second step and only matters to a server with a public HTTPS address.
The issues, in order
- MCP 1: agent credentials (grants, hashed tokens, ApiUser, Connected apps) and the owner's switch #167 Agent credentials: grants, tokens,
ApiUser, Connected apps, the owner's switch - MCP 2: the MCP server at /mcp, bearer only, with course tools #168 The MCP server at
/mcpwith course tools - MCP 3: OAuth 2.1 sign-in and consent for apps that connect from the cloud #169 OAuth 2.1 sign-in for apps that connect from the cloud
- MCP 4: security review page, an adversarial pass, limits and the owner's view #170 Security review page, limits and the owner's view
- MCP 5: docs for connecting an assistant, on a home network and through a domain #171 Docs: connect your assistant, on a home network and through a domain
- MCP 6 [human]: connect a real assistant to a real mini and make a course #172 (human) Connect a real assistant to a real mini and make a course
Activity
alexbeeken commentedon Nov 12, 2026
Correction to Addresses in the shared design:
SKRONGLE_PUBLIC_URLis optional on a mini. With it unset, course links in tool results are paths only (base path included), and the OAuth routes and discovery documents of issue 3 answer 404, because an issuer must be a fixed address. With it set, every address comes from it. In neither case is theHostheader used.