Fabian Hamm
35125b7683
Read-only MCP server exposing a Schulcloud account to Claude: courses,
column boards, lessons, tasks, and file downloads with text extraction.
The API surface was verified against the live instance rather than
inferred from upstream source, which changed several design decisions:
- The `jwt` cookie works verbatim as `Authorization: Bearer` and lasts 30
days, so there is no cookie jar and no refresh-session timer.
- Course contents live at /api/v3/course-rooms/{courseId}/board; there is
no GET /api/v3/courses/{id}.
- Files are a separate service (/api/v3/file/*) with its own OpenAPI doc.
- Board file elements carry no file id; attachments are resolved by
listing files-storage with parentType=boardnodes and the element id.
Read-only by construction: every client method is a GET, including the
api_get escape hatch. The endpoint is internet-facing by necessity, so a
leaked token being unable to act as the user is the key safety property.
Deploys as a container behind the Pi's existing Caddy, guarded by a
constant-time bearer check. Stateless — no database.
Verified: 28 unit tests, plus a 30-check end-to-end run driving a real
MCP client over Streamable HTTP against the live account.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
56 lines
1.8 KiB
TypeScript
56 lines
1.8 KiB
TypeScript
import assert from 'node:assert/strict';
|
|
import { describe, it } from 'node:test';
|
|
import { bearerAuth } from '../src/http/auth.ts';
|
|
|
|
function run(headers: Record<string, string>): { status?: number; passed: boolean } {
|
|
const middleware = bearerAuth('correct-horse-battery-staple');
|
|
let status: number | undefined;
|
|
let passed = false;
|
|
const req = { get: (name: string) => headers[name.toLowerCase()] } as never;
|
|
const res = {
|
|
setHeader() {},
|
|
status(code: number) {
|
|
status = code;
|
|
return this;
|
|
},
|
|
json() {
|
|
return this;
|
|
},
|
|
} as never;
|
|
middleware(req, res, () => {
|
|
passed = true;
|
|
});
|
|
return { status, passed };
|
|
}
|
|
|
|
describe('bearerAuth', () => {
|
|
it('accepts the exact token', () => {
|
|
assert.equal(run({ authorization: 'Bearer correct-horse-battery-staple' }).passed, true);
|
|
});
|
|
|
|
it('accepts it via x-api-key, for connector UIs without an Authorization field', () => {
|
|
assert.equal(run({ 'x-api-key': 'correct-horse-battery-staple' }).passed, true);
|
|
});
|
|
|
|
it('is case-insensitive about the scheme but not the token', () => {
|
|
assert.equal(run({ authorization: 'bearer correct-horse-battery-staple' }).passed, true);
|
|
assert.equal(run({ authorization: 'Bearer CORRECT-HORSE-BATTERY-STAPLE' }).passed, false);
|
|
});
|
|
|
|
it('rejects a missing, empty, wrong or truncated token with 401', () => {
|
|
for (const headers of [
|
|
{},
|
|
{ authorization: '' },
|
|
{ authorization: 'Bearer ' },
|
|
{ authorization: 'Bearer wrong' },
|
|
{ authorization: 'Bearer correct-horse-battery-stapl' },
|
|
{ authorization: 'Bearer correct-horse-battery-staple-extra' },
|
|
{ authorization: 'Basic correct-horse-battery-staple' },
|
|
]) {
|
|
const result = run(headers as Record<string, string>);
|
|
assert.equal(result.passed, false, `should reject ${JSON.stringify(headers)}`);
|
|
assert.equal(result.status, 401);
|
|
}
|
|
});
|
|
});
|