auth-core v0.3.0

subsystem education.ctf

capsule://capsule-examples/auth-core@0.3.0

Issues and validates student session tokens for the WolfCTF platform.
Provides an HTTP introspection endpoint that downstream capsules use
to authorize requests, and emits a standard `student_id` claim that
other capsules can trust.

Owns

student credential storage (hashed)
session token issuance and revocation
HTTP introspection endpoint (POST /introspect)
per-student role assignment (student / instructor / admin)

Does not own

what a student is allowed to *do* with a lab (that's lab-runtime's call)
rate limiting (handled by the edge proxy capsule)
SSO / external IdP integration (separate adapter capsule)

AI orientation

You are looking at auth-core. It is the single source of truth for
who a request belongs to. Other capsules MUST call POST /introspect to
validate a token; they must NOT decode tokens themselves. If you need
a new claim (e.g. cohort_id), add it here, then expose it through
/introspect — do not invent parallel claim sources elsewhere.

Avoid

Decoding session tokens outside this capsule.
Storing plaintext passwords or password hashes outside the students table.
Adding role checks that bypass the introspection endpoint.

Extension points

claim-enricher at src/auth/claims.py:enrich: Pure function (token_record) -> dict of additional claims.
Must not perform I/O.

Provides

http_api:auth-introspect — POST /introspect — given a bearer token, returns the verified claims.
event:student.session.revoked

Requires

env:AUTH_DB_URL — PostgreSQL connection string for the students DB.
env:AUTH_SIGNING_KEY — HMAC key used to sign session tokens; must be >= 32 bytes.

Dependencies

Runtime

python >=3.11
postgres >=14

Invariants (must always hold)

A revoked token must never successfully introspect.
Two distinct students must never share a session token.
Token signing keys must never appear in logs.

Glossary

student: an authenticated user with the `student` role
introspection: the act of exchanging a token for verified claims
claim: a verified key/value (e.g. student_id, role) returned by introspect

Source

https://github.com/quake0day/capsule-examples/blob/main/wolfctf/auth-core/capsule.yaml

Pull this capsule locally:

capsule pull capsule://capsule-examples/auth-core@0.3.0

Or render to your terminal:

capsule man capsule://capsule-examples/auth-core@0.3.0