AUTH

Purpose

AUTH is the gate. GitHub identity in, session token out. Every scope access checked. Fail-closed.

AUTH controls who sees what. GitHub OAuth provides the identity anchor (KYC). Sessions live in Cloudflare KV. Scope grants are resolved at query time from CANON.md readers and writers fields. Public content passes freely. Private content requires a valid session with matching grants. No session, no access.

Structure

Root AUTH domains: none currently (leaf service scope).

Required closure artifacts per scope: CANON.md, README.md, AUTH.md, VOCAB.md, ROADMAP.md, COVERAGE.md, LEARNING.md.

Learning lane per governed scope: LEARNING.md at the scope root is terminal and SHALL NOT nest further LEARNING/.

Routes

POST /auth/github      Exchange GitHub OAuth code for session token
GET  /auth/session     Validate session token, return user identity
POST /auth/logout      Delete session from KV
GET  /auth/grants      Check if session user can access scope X

Session Contract

{
  user:             GitHub username (KYC anchor)
  github_uid:       GitHub numeric user ID
  org:              hadleylab (ORG membership = permission boundary)
  scopes_granted:   [] (resolved at query time from CANON.md readers)
  ts:               session creation timestamp
  expires:          session expiry timestamp
}

Gate Logic

IF privacy = PUBLIC (or omitted)  → no gate, everyone sees it
IF privacy = PRIVATE:
  IF readers = *                  → all authenticated users
  IF readers declared             → check session.user against readers list
  IF no readers declared          → ORG members only (fail-closed to public)
writers:                          → same pattern, controls write/contribute access

CANON.md Extension

Any scope’s CANON.md MAY declare:

privacy: PRIVATE
readers: iDrDex, yanabeda, ir4y
writers: iDrDex
github: username

Fields:

• privacy: — PUBLIC (default) or PRIVATE
• readers: — comma-separated GitHub usernames granted read access
• writers: — comma-separated GitHub usernames granted write/contribute access
• github: — on USER principal CANON.md, binds identity to GitHub account

Ecosystem Connectivity

1. Upstream: SERVICES governance contracts and DEXTER scope inheritance.
2. Runtime: Cloudflare Worker (api.canonic.org) + TALK_KV for sessions.
3. Frontend: DESIGN.js auth flow, talk.js auth headers, magic.js scope gating.
4. Ledger plane: all auth events (login, grant, deny) ledgered to TALK_KV.

Pages

Default: Overview.