Schulcloud-MCP/docs/AUTH.md

# Authentication

## What this server uses

The `jwt` cookie from a logged-in browser session, sent verbatim as
`Authorization: Bearer <token>`. That is the whole mechanism.

This was worth confirming rather than assuming, because the obvious reading of
"it's a cookie" leads somewhere much more complicated. Verified live:

```
Authorization: Bearer <jwt>  → 200    # what this server does
Cookie: jwt=<jwt>            → 200    # also works
(no auth)                    → 401
```

`connect.sid`, `SERVERID` and `isLoggedIn` are **not** needed — there is no
cookie jar. There *is* a session to keep alive, though not in the way the
cookies suggest; see the next section.

## Token lifetime, and the thing that actually kills it

Two clocks govern the token:

| Clock | Value | Notes |
|---|---|---|
| **Session** — a whitelist entry in Valkey, `jwt:{accountId}:{jti}` | `JWT_TIMEOUT_SECONDS` = **7200 s** | **Sliding**: every authenticated request re-sets it |
| **Hard expiry** — the JWT's own `exp` claim | **30 days** | Cannot be extended |

`JwtStrategy.validate()` calls `JwtWhitelistAdapter.isWhitelisted()`, which
reads the key, throws
`'Session was expired due to inactivity - autologout.'` if it is gone, and then
**re-sets it** with a fresh TTL. The legacy Feathers implementation does the
same. So the window really does slide with use, and a keepalive holds a session
up to the 30-day ceiling.

### But a browser tab will log this server out

The trap is not a clock at all. **The `jwt` cookie you copy is the browser's own
session token — same `jti`.** This server and that tab share one session, and
the tab will end it:

1. On login the front end starts a **purely client-side** timer:
   `sessionTimeoutTimestamp = Date.now() + JWT_TIMEOUT_SECONDS`. It is reset
   only on *route change* — `watch(router.currentRoute, startTimer)` — never by
   API activity, and never read back from the server's real TTL.
   (`nuxt-client/src/modules/data/application/application.store.ts`)
2. After `JWT_SHOW_TIMEOUT_WARNING_SECONDS` (3600 s) remain it shows the
   "Sitzung verlängern" dialog. (`AutoLogoutWarning.vue`)
3. At zero it calls `autoLogout()` →
   `location.replace('/logout?auto-logout=true')`.
4. That route, in the legacy client, issues `POST /api/v3/logout`
   (`schulcloud-client/controllers/login.js:439`) →
   `removeJwtFromWhitelist(jwt)` → **the shared key is deleted.**

An idle tab therefore revokes this server's token about two hours after login,
no matter how diligently the server refreshes it. Measured exactly that way: a
keepalive pinged successfully at t+0/30/60/90 and was dead by t+120, ~2 h after
login, while `exp` still had 29 days left.

Note the timer is client-side and reset only by navigation. That is why the
dialog appears after an idle hour even in a tab you consider "in use", and why
no amount of API traffic prevents it.

### So: close the tab

**After copying the `jwt` cookie, close the Schulportal tab** — all of them; the
front end also syncs logout across tabs over a `BroadcastChannel`. Closing a tab
runs no logout itself (`autoLogout` fires only from the expiry timer), so the
session survives on the server with nothing left to revoke it.

The tidiest recipe is a **private/incognito window**: log in there, copy the
`jwt`, close the window. That session is separate from your normal browsing, and
`POST /api/v3/logout` only ever removes its own `jti`, so your everyday session
and this server cannot end each other.

With no tab attached, the keepalive holds the session to the 30-day hard expiry,
and replacing the token becomes the monthly chore it looked like at first.

## Replacing the token without a restart

`schulcloud token set` (paste at a hidden prompt, or pipe it in) and the
server's `/token` page both send a fresh token to `PUT /api/token`, behind the
bearer check. `core/session-token.ts` then:

1. **Cleans the paste.** A bare value, `jwt=…; Path=/`, quotes and newlines all
   work.
2. **Checks before it swaps.** A malformed or expired token is refused without
   asking Schulcloud; otherwise `GET /api/v3/me` must succeed *with the new
   token*, and for the same `userId` the current one carries. A refused token
   changes nothing. Switching accounts stays a deliberate act — change
   `TSC_JWT_COOKIE` and restart.
3. **Swaps it in place.** Every request reads `config.jwt` at the moment it is
   sent, so the next one uses the new token; nothing caches a copy.
4. **Restarts the keepalive**, which stopped for good on a 401. Its pings carry
   a generation number, so one still in flight with the old token cannot stop
   the new cycle when its 401 arrives.
5. **Saves it** to `STATE_DIR` (0600, written beside itself and renamed). At
   startup the newer of the saved token and `TSC_JWT_COOKIE` wins, by `exp` —
   unless they belong to different accounts, when the environment does.

The token appears in no log line and no response; `/api/token` reports only
the expiry, where the token came from, and the keepalive's state. The claims
are decoded, never verified — Schulcloud verifies, this only reads dates.

The cookie is **HttpOnly**, so no script — no bookmarklet, no page on another
origin — can read it out of the browser. The DevTools copy is the one manual
step, and it cannot be automated away short of a headless browser holding the
Schulportal password (see below).

### There is no longer window available

`config/default.schema.json` documents `JWT_EXTENDED_TIMEOUT_SECONDS`
(2629746 s ≈ 1 month), reachable in the legacy stack via a `privateDevice`
login flag. On the current NestJS server that is vestigial: `privateDevice` has
no references in `apps/server/src`, and `generateJwtAndAddToWhitelist` calls
`addToWhitelist` with no TTL override. A "remember me" login buys nothing.

## How this server stays alive

`src/keepalive.ts` calls `POST /api/v3/authentication/refresh-session` every 30
minutes (`KEEPALIVE_INTERVAL_MS`; `0` disables it), from both entry points and
independently of whether any MCP client is connected — the session expires on
wall time, not on usage. It logs the budget each time:

```
[schulcloud-mcp] keepalive: session extended, 7200s (120 min) of budget left
```

A plain `GET` would also slide the TTL today. `refresh-session` is used anyway
because it states the intent contractually rather than relying on a side effect
of an unrelated read — upstream has refactored this whitelist twice in 2026, and
a GET-based keepalive would fail *silently* if extend-on-check ever went away.
The budget readout also turns "is the session healthy" into something the log
answers directly.

**It is the one non-GET request in the server.** No body, touches only the
caller's own session, cannot read or modify user data, and is not exposed as a
tool — so no model-driven call can ever be a POST, and the property that matters
is intact: nobody reaching this endpoint can act as the user in Schulcloud.

A transient failure retries in 5 minutes. A `401` stops the keepalive
permanently and says what to do, because a deleted whitelist entry cannot be
revived by retrying — and if it happens roughly two hours after login, suspect
an open tab before anything else.

Two ways to check that a token is holding:

- `npm run keepalive-status` reads the running container's logs and summarises
  its extensions. It makes **no** API call on purpose — any authenticated
  request slides the TTL, so a checker that talked to Schulcloud would be
  keeping the session alive itself and could not tell you whether the keepalive
  works.
- `npm run session-diagnose` calls refresh-session every 10 minutes for ~2.5 h
  and logs the budget, for when there is no container to read logs from.

**Operational consequence:** if the container is down for over two hours the
session lapses on its own, and restarting will not recover it. The startup log
says so immediately:

```
[schulcloud-mcp] keepalive: token rejected (401). The session is gone …
```

## WebUntis: a second credential, of a different kind

The timetable is not in Schulcloud, so the server talks to WebUntis as well —
and that side authenticates far more comfortably. In WebUntis, open **Profil →
Freigaben → Untis Mobile → QR-Code**. The dialog shows four values, which go
into `.env` as `UNTIS_SERVER` (its "Url"), `UNTIS_SCHOOL`, `UNTIS_USER` and
`UNTIS_SECRET` (its "Schlüssel"). The school number shown there is not used.

Why this is the right credential for a server:

- **No password.** The key is what the Untis Mobile app is given, and it works
  even where the WebUntis login goes through the school's SSO.
- **Nothing to keep alive.** Every request carries a fresh time-based code
  derived from the key, so there is no session to refresh and nothing that dies
  when the Pi is off for a day. Unlike the Schulcloud token, this needs no
  monthly chore: the key stays valid until you replace it.
- **Revocable on its own.** Generating a new key in that dialog invalidates the
  old one, and it has nothing to do with your password.

Two things to know:

- **The host's clock matters.** A time-based code from a drifting clock is
  refused with `-8524 invalid client time`, which the tools report as such. Any
  Pi with working NTP is fine.
- **The key is not read-only — the server is.** It can do what the app can, and
  on this account that includes reporting an absence (`W_OWN_ABSENCE`). Untis'
  API is JSON-RPC, where reads are POSTs too, so "GET only" cannot be the
  guarantee here as it is for Schulcloud. Instead `core/untis.ts` carries an
  allowlist of five read methods and refuses everything else; `test/untis.test.ts`
  holds it to that. Replacing `UNTIS_SECRET` needs a restart — there is no live
  swap for it, because it does not expire.

## Why not username + password

The instance's login redirects to Keycloak (realm `TIS`) with a `redirect_uri`
pointing back at Schulcloud's own server, so the authorization-code exchange
happens server-side with a client secret only Schulcloud holds. A third party
cannot replicate that flow. `POST /api/v3/authentication/local` exists but is
for accounts with local credentials, which federated school accounts do not
have.

Given a keepalive that holds a session to its 30-day ceiling, the pasted-JWT
approach is the right trade: one manual step a month against re-implementing an
OAuth client whose secret we cannot hold. If that monthly step ever becomes
unacceptable, the honest options are a service account issued by the school's
IDM, or driving the Keycloak login with a headless browser — not a
reimplementation of the code exchange. A headless browser would have to hold
the Schulportal password, which unlocks far more than this account's school
files, so it is not done here.

## Protecting this server's own endpoint

Distinct from the above, and just as important. The MCP endpoint is reachable
from the public internet by construction: Claude's connectors call it from
Anthropic's cloud, not from your machine. It is protected by `MCP_AUTH_TOKEN`,
a shared secret checked in constant time on every `/mcp` and `/api` request
(`src/http/auth.ts`). It is accepted as `Authorization: Bearer …`, as a bare
`Authorization` value — claude.ai sends a header exactly as typed — or as
`X-Api-Key` or `X-Auth-Token`. `/healthz` is deliberately open and reveals
nothing.

Generate one with `openssl rand -hex 32`. If it is unset the server logs a loud
warning and serves unauthenticated — only acceptable bound to localhost.

Rotating it: change `MCP_AUTH_TOKEN` in `.env`, recreate the container, and
update Claude Code and the CLI (`schulcloud login`). Nothing else stores it.

### The connector token, for claude.ai

claude.ai sends a request header whose value it stores, so its token is a
credential held by a third party. `MCP_CONNECTOR_TOKEN` gives it one of its
own: accepted on `/mcp` alone, refused on `/api` — which can replace the
Schulcloud token and stream the file mirror — and rotated without touching
Claude Code or the CLI. `config.ts` requires at least 32 characters, a value
different from `MCP_AUTH_TOKEN`, and `MCP_AUTH_TOKEN` itself, so it can never
leave `/api` unguarded; its errors never echo a value. All accepted tokens are
compared in full, so the timing does not tell which one matched.

### The secret path, for clients without request headers

For a client that can send no header, `MCP_PATH_SECRET` opens another way in:
`/<secret>/mcp`, with no token at all. The path is the credential there. `http/auth.ts` compares it in constant time and answers a
wrong one with the same 404 as any unknown path; `config.ts` insists on at
least 32 URL-safe characters and never echoes the value; the server never logs
request paths; and `deploy/Caddyfile.snippet` rewrites the segment before an
access log entry is written. Rotating it means a new value, a recreated
container, and re-adding the connector. Prefer the connector token wherever a
header can be sent: a URL is copied into more places than a header is.

### The app password, for a person

`WEB_PASSWORD` is unlike every other credential here: it is typed by a human, on
a phone, in a lesson. That single fact drives its whole design.

- **It is a passphrase, not a token.** `config.ts` insists on 12 characters and
  nothing else; demanding punctuation would buy little next to length, and the
  failure mode of a fussy rule is a shorter password, not a better one.
- **It is never stored in the clear.** scrypt (N=16384) at startup; a login
  hashes the attempt and compares in constant time. The error states the rule
  and never echoes the value.
- **Logins are rate-limited per address**, eight failures in fifteen minutes.
  Not optional: a password is guessable in a way a 32-byte token is not, and the
  scrypt cost that makes guessing expensive is itself a denial-of-service vector
  without a limiter in front of it.
- **The session is a signed cookie**, `HttpOnly` and `SameSite=Strict` — the
  latter standing in for CSRF tokens, since nothing links into the app from
  anywhere else. 30 days, because the alternative is a login screen at the start
  of a lesson.
- **The signing key is derived from the password**, so changing it invalidates
  every session that exists. No second secret, nothing to store, and the
  behaviour anyone changing a password already expects.
- **The cookie opens `/api` and not `/mcp`.** A session *is* the user, and the
  app is built on `/api` — but nothing in a browser speaks MCP, and a surface
  that is not needed is not offered.

Unset, the app is not served at all. A login screen that no password can open is
worse than no page, because it looks like a way in.

## Blast radius

Every path in this server is a `GET`, including the `api_get` escape hatch,
which rejects anything not starting with `/api/` and anything carrying a scheme
or host. Someone who obtained both the endpoint URL and `MCP_AUTH_TOKEN` — or
the connector token, the secret MCP path, or the app password — could read this
account's Schulcloud data; they could not
post, submit, delete, or otherwise act as the user. With `MCP_AUTH_TOKEN` they
could also call `PUT /api/token`, but it accepts only a live token for the same
account, so the most it can do is hand the server a session the owner already
has. Keep it that way — adding a single write tool would change that property
entirely.

The app password and `MCP_AUTH_TOKEN` additionally reach the notes: they can
read, write and overwrite files under `NOTES_DIR`, and nothing outside it —
`safeComponent` and `resolveWithin` are what make that a property rather than a
hope. That is the only write anywhere in this server, and it touches the user's
own files, never Schulcloud. `NOTES_READONLY=1` removes even that.