Skip to content

MCP: let a person's AI assistant make courses on a mini, securely (plan) #166

Open

Description

@alexbeeken

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

Activity

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

    @alexbeeken
    OwnerAuthor

    Correction to Addresses in the shared design: SKRONGLE_PUBLIC_URL is 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 the Host header used.

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