RFC: Unified Authentication & Authorization System

[jakebromberg]

Unified Authentication System for WXYC

Status: Draft
Author: Jake
Date: 2026-02-27

1. Problem Statement

WXYC's authentication is fragmented across four dimensions:

1. First-party web services (Backend-Service, dj-site, archive, website) share an identity provider but not all consume it. The website and archive-search have no auth at all.
2. First-party backend services (request-o-matic, library-metadata-lookup) accept all traffic unconditionally. There is no service identity, no machine-to-machine auth, no way to distinguish an internal service call from an arbitrary internet request.
3. Cross-cutting capabilities (editor, webmaster) are defined as TypeScript types in @wxyc/shared but have no database table, no JWT claim, and no assignment mechanism.
4. Third-party platforms (PostHog, Sentry, Cloudflare, AzuraCast) each maintain their own isolated user accounts, manually created and manually revoked. Social media accounts (Facebook, Instagram, Bluesky) are even worse — a single shared password with no rotation. Departed members retain access to services that no one remembers to clean up.

Goals

1. Single identity — one account per person, managed in one place (better-auth).
2. Role-based access — WXYC roles and capabilities propagate to all services automatically.
3. Service identity — authenticated inter-service communication with caller traceability.
4. Shared verification — reusable JWT verification libraries for TypeScript and Python, eliminating ad hoc implementations.
5. Separation of concerns — station leadership manages people; the tech team manages infrastructure.
6. Zero budget — use free tiers and self-hosted open source exclusively.

Non-Goals

• Listener-facing authentication (public streaming, website visitors).
• Replacing better-auth as the first-party API token issuer or user store.
• Multi-organization / multi-station support.

---

2. Current State

Auth Infrastructure

Backend-Service is the identity provider for first-party services. It uses better-auth with email+password authentication, JWT access tokens, and a JWKS endpoint at /auth/jwks.

graph TB
    subgraph "Auth Service (port 8082)"
        BA[better-auth]
        JWKS["/auth/jwks"]
        BA --> JWKS
    end

    subgraph "Consumers"
        DJ[dj-site]
        AR[archive]
    end

    DJ -- "session cookie" --> BA
    AR -- "JWT via JWKS" --> JWKS

    subgraph "No Auth"
        ROM[request-o-matic]
        LML[library-metadata-lookup]
        WAS[wxyc-archive-search]
        WEB[website]
        IOS[wxyc-ios-64]
        AND[WXYC-Android]
    end

    subgraph "Third-Party (isolated accounts)"
        PH[PostHog]
        SE[Sentry]
        CF[Cloudflare]
        AC[AzuraCast]
    end

    subgraph "Third-Party (shared passwords)"
        FB[Facebook / Instagram]
        BSKY[Bluesky]
    end

    style ROM fill:#f96,stroke:#c00
    style LML fill:#f96,stroke:#c00
    style WAS fill:#f96,stroke:#c00
    style WEB fill:#f96,stroke:#c00
    style IOS fill:#eee,stroke:#999
    style AND fill:#eee,stroke:#999
    style PH fill:#eee,stroke:#999
    style SE fill:#eee,stroke:#999
    style CF fill:#eee,stroke:#999
    style AC fill:#eee,stroke:#999
    style FB fill:#c00,stroke:#900,color:#fff
    style BSKY fill:#c00,stroke:#900,color:#fff

Loading

Gaps

Service	Current Auth	Gap
dj-site	Full better-auth integration	None
archive	JWT via @wxyc/shared/auth-client	Working, limited to DJ role gating
archive-search	None	Needs JWT/JWKS verification for tiered access
website	None (TinaCMS has its own auth)	Needs editor/webmaster capability gating
request-o-matic	None	Accepts all traffic; needs service + user auth
library-metadata-lookup	None	Accepts all traffic; needs service auth
wxyc-ios-64	None	Needs user JWT for extended features, service auth for request-o-matic
WXYC-Android	None	Same as iOS
PostHog (cloud)	Email/password per user	GitHub social SSO only on free tier
Sentry (cloud)	Email/password per user	No SSO on free tier; manual account management
Cloudflare	Email/password per user	Zero Trust free tier supports GitHub IDP (50 users)
AzuraCast	Email/password per user	No native SSO; maintainer has explicitly declined
Facebook / Instagram	Shared password, no rotation	Needs Meta Business Suite + API-driven user management
Bluesky	Shared password, no rotation	Needs per-user app passwords via AT Protocol API

JWT Payload (current)

{
  "sub": "user-id",
  "id": "user-id",
  "email": "dj@wxyc.org",
  "role": "dj",
  "iat": 1739600000,
  "exp": 1739603600
}

JWT Verification (current)

Implemented ad hoc in archive/lib/jwt-utils.ts (~50 lines of jose calls). Every new TypeScript consumer would duplicate this. Python services have no JWT verification at all.

Role Model (current)

The current role hierarchy conflates organizational leadership with technical access:

Role	Permissions
stationManager	Everything — roster, catalog, flowsheet, bin, plus de facto infra access
musicDirector	Catalog, bin, flowsheet (read + write)
dj	Catalog (read), bin/flowsheet (read + write)
member	Catalog/flowsheet (read), bin (read + write)

Two cross-cutting capabilities (editor, webmaster) are defined in wxyc-shared/src/auth-client/capabilities.ts as pure types with a delegation chain, but none of this is persisted or enforceable.

In-Progress Work: admin Role

The fix/add-admin-role-to-wxyc-roles branch adds admin as a peer to stationManager with identical permissions. It fixes a 403 regression where users with role="admin" (assigned by better-auth's organization hooks) were rejected by requirePermissions middleware. The branch also removes the normalizeRole function in favor of direct role lookup. This proposal's superAdmin role subsumes the branch's admin — see Section 3 for the reconciliation path.

---

3. Proposed Role Model

Core Change: Separate Organizational Authority from Technical Authority

The station manager is always a student, typically a humanities major, elected by the board. They should manage people and programming — not infrastructure. A new superAdmin role handles all technical operations. Per-service named identities in a separate ServiceRoles constant handle machine-to-machine authentication.

Role Hierarchy

graph TD
    SA[superAdmin]
    SM[stationManager]
    MD[musicDirector]
    DJ[dj]
    M[member]

    SA -->|inherits all of| SM
    SM -->|inherits all of| MD
    MD -->|inherits all of| DJ
    DJ -->|inherits all of| M

    SA -.- SAD["iddqd mode<br/>All permissions<br/>Infrastructure access<br/>Create/modify roles<br/>Assign any role or capability"]
    SM -.- SMD["Account management<br/>Assign roles: dj, musicDirector<br/>Transfer stationManager<br/>Assign capabilities: editor, webmaster<br/>Roster management<br/>No infrastructure access"]
    MD -.- MDD["Catalog write<br/>Bin write<br/>Flowsheet write"]
    DJ -.- DJD["Flowsheet write<br/>Catalog read<br/>Bin read/write"]
    M -.- MD2["Catalog read<br/>Flowsheet read<br/>Bin read/write"]

    subgraph SVC["Service Identities (not in hierarchy)"]
        ROM_R["request-o-matic"]
        LML_R["library-metadata-lookup"]
    end
    ROM_R -.- SVCD["No resource permissions<br/>Identity only<br/>Bypasses role hierarchy<br/>Per-service named identity"]

    style SA fill:#b91c1c,color:#fff
    style SM fill:#7c3aed,color:#fff
    style MD fill:#2563eb,color:#fff
    style DJ fill:#059669,color:#fff
    style M fill:#6b7280,color:#fff
    style ROM_R fill:#d97706,color:#fff
    style LML_R fill:#d97706,color:#fff

Loading

Service identities are not part of the hierarchy. Each service gets its own named role (e.g., request-o-matic, library-metadata-lookup) in a separate ServiceRoles constant. Their presence in the JWT identifies the caller as a specific trusted internal service, not an arbitrary internet client.

stationManager Mutual Exclusivity

The stationManager role is mutually exclusive — only one user can hold it at a time. This reflects the real-world structure: there is one station manager at WXYC at any given time, elected by the staff.

Transfer rules:

• Assigning stationManager to a new user atomically revokes it from the current holder.
• Only stationManager (self-transfer) and superAdmin can initiate the transfer.
• The transfer is logged with both the granting and revoking user IDs for audit.

Implementation: The role assignment endpoint enforces this constraint:

// In the role assignment handler
if (newRole === 'stationManager') {
  await db.transaction(async (tx) => {
    // Revoke from current holder
    await tx.update(member)
      .set({ role: 'musicDirector' })  // Demote to musicDirector
      .where(and(eq(member.role, 'stationManager'), ne(member.userId, targetUserId)));
    // Assign to new holder
    await tx.update(member)
      .set({ role: 'stationManager' })
      .where(eq(member.userId, targetUserId));
  });
}

Role Permissions Matrix

Resource	Action	member	dj	musicDirector	stationManager	superAdmin
catalog	read	x	x	x	x	x
catalog	write			x	x	x
flowsheet	read	x	x	x	x	x
flowsheet	write		x	x	x	x
bin	read	x	x	x	x	x
bin	write	x	x	x	x	x
roster	read				x	x
roster	write				x	x
roles	read					x
roles	write					x
infrastructure	read					x
infrastructure	write					x

Service identities have no resource permissions and are not included in this matrix. They are identity assertions, not authorization grants. Services that need to perform authorized operations on behalf of a user forward the user's context (see Section 8).

Capabilities (Cross-Cutting)

Capabilities are independent of the role hierarchy. Any user with any role can be granted a capability.

Capability	Description	Who Can Assign
editor	Can edit website content via CMS	stationManager, superAdmin, users with webmaster
webmaster	Can assign editor capability; website admin access	stationManager, superAdmin

Assignment Rules

graph LR
    SA[superAdmin] -->|can assign| ANY[any role + any capability]
    SM[stationManager] -->|can assign| R1[dj]
    SM -->|can assign| R2[musicDirector]
    SM -->|can transfer| R3[stationManager]
    SM -->|can assign| C1[editor]
    SM -->|can assign| C2[webmaster]
    SM -.-x|cannot assign| SA2[superAdmin]
    WM[user with webmaster] -->|can assign| C3[editor]

    style SA fill:#b91c1c,color:#fff
    style SM fill:#7c3aed,color:#fff
    style SA2 fill:#b91c1c,color:#fff,stroke-dasharray: 5 5

Loading

The superAdmin role is reserved for the tech team. It is never assigned through the dj-site UI; it is assigned directly in the database or via an admin CLI.

Adding superAdmin to WXYCRoles and Defining ServiceRoles

// auth.roles.ts

// Human roles — hierarchical, used in the better-auth organization plugin
const WXYCRoles = {
  member:          { bin: ['read', 'write'], catalog: ['read'], flowsheet: ['read'] },
  dj:              { bin: ['read', 'write'], catalog: ['read'], flowsheet: ['read', 'write'] },
  musicDirector:   { bin: ['read', 'write'], catalog: ['read', 'write'], flowsheet: ['read', 'write'] },
  stationManager:  { bin: ['read', 'write'], catalog: ['read', 'write'], flowsheet: ['read', 'write'],
                     roster: ['read', 'write'] },
  superAdmin:      { bin: ['read', 'write'], catalog: ['read', 'write'], flowsheet: ['read', 'write'],
                     roster: ['read', 'write'], roles: ['read', 'write'],
                     infrastructure: ['read', 'write'] },
};

// Service identities — per-service named roles, no resource permissions.
// Each service gets its own identity for traceability and future per-service scoping.
const ServiceRoles = {
  'request-o-matic': {},
  'library-metadata-lookup': {},
} as const;

type WXYCRole = keyof typeof WXYCRoles;          // human roles only
type ServiceRole = keyof typeof ServiceRoles;      // per-service identities
type CallerRole = WXYCRole | ServiceRole;          // everything a JWT role field can be

The middleware resolves roles from both objects:

function resolveRole(role: string):
  | { type: 'human'; impl: RoleImpl }
  | { type: 'service'; name: ServiceRole }
  | null {
  if (role in WXYCRoles) return { type: 'human', impl: WXYCRoles[role as WXYCRole] };
  if (role in ServiceRoles) return { type: 'service', name: role as ServiceRole };
  return null; // 403
}

Human roles go through authorize() for permission checks. Service roles bypass it — they are identity assertions, not authorization grants.

Reconciliation with fix/add-admin-role-to-wxyc-roles Branch

The existing branch adds admin as a peer to stationManager with identical permissions. To reconcile:

1. Merge the branch's core improvements — remove normalizeRole, direct role lookup in WXYCRoles.
2. Replace admin with superAdmin in WXYCRoles — superAdmin has the same adminAc.statements base but adds infrastructure and roles resources.
3. Update adminRoles sync in auth.definition.ts — map superAdmin to user.role = 'admin' for better-auth's admin plugin.
4. Prevent better-auth built-in role leakage — configure the organization plugin's creatorRole to "member" (not the default "owner") and add an onMemberRoleUpdate hook that rejects any role not in WXYCRoles. This prevents admin/owner from ever being written to the member.role column. Add a contract test asserting that every member.role value in the DB is a valid WXYCRole.
5. Keep stationManager as the org-management role without infrastructure access.

---

4. JWT Claims

User JWT Payload (proposed)

{
  "sub": "user-id",
  "id": "user-id",
  "email": "dj@wxyc.org",
  "role": "dj",
  "capabilities": ["editor"],
  "org": "wxyc",
  "iat": 1739600000,
  "exp": 1739603600
}

Service JWT Payload

{
  "sub": "service-request-o-matic",
  "id": "service-request-o-matic",
  "email": "request-o-matic@services.wxyc.org",
  "role": "request-o-matic",
  "capabilities": [],
  "org": "wxyc",
  "iat": 1739600000,
  "exp": 1739603600
}

Claims Reference

Claim	Type	Description
sub	string	User ID (human) or service identifier (machine)
id	string	Alias for sub. Deprecated; retained for backwards compatibility with existing consumers. Will be removed in a future version.
email	string	User email or <service-name>@services.wxyc.org
role	string	Hierarchical role (member, dj, musicDirector, stationManager, superAdmin) or per-service identity (request-o-matic, library-metadata-lookup)
capabilities	string[]	Cross-cutting capabilities (editor, webmaster). Empty array if none. Always empty for service accounts.
org	string	Organization slug. Always "wxyc" for now.
exp	number	Token expiration
iat	number	Token issued-at

What Stays Out of the JWT

• Profile data (djName, appSkin) — mutable and not authorization-relevant.
• Fine-grained permissions — the ROLE_PERMISSIONS matrix in @wxyc/shared resolves role -> permissions locally. The JWT carries coarse authorization; the shared library resolves the details.

---

5. Capability Storage and Admin Endpoints

Database Schema

A new table in Backend-Service's PostgreSQL database stores capability assignments:

CREATE TABLE auth_user_capability (
    user_id      TEXT        NOT NULL REFERENCES auth_user(id) ON DELETE CASCADE,
    capability   TEXT        NOT NULL CHECK (capability IN ('editor', 'webmaster')),
    granted_by   TEXT        NOT NULL REFERENCES auth_user(id),
    granted_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (user_id, capability)
);

CREATE INDEX idx_user_capability_user ON auth_user_capability(user_id);

The granted_by column enables audit trails. The unique constraint prevents duplicate grants.

JWT Payload Extension

Modify definePayload in Backend-Service/shared/authentication/src/auth.definition.ts:

const SERVICE_EMAIL_DOMAIN = "@services.wxyc.org";

jwt({
  jwt: {
    definePayload: async ({ user }) => {
      if (!user?.id) return user;

      // Service account path: derive role from email prefix, skip org lookup.
      // Service accounts are not org members and have no capabilities.
      if (user.email.endsWith(SERVICE_EMAIL_DOMAIN)) {
        const serviceName = user.email.slice(0, -SERVICE_EMAIL_DOMAIN.length);
        if (!(serviceName in ServiceRoles)) {
          throw new Error(`Unknown service account: ${user.email}`);
        }
        return {
          sub: user.id,
          id: user.id,
          email: user.email,
          role: serviceName,  // e.g., "request-o-matic"
          capabilities: [],
          org: "wxyc",
        };
      }

      // Human user path: look up org membership, role, and capabilities.
      const [memberRecord, capabilityRecords, orgRecord] = await Promise.all([
        db.select({ role: member.role })
          .from(member)
          .where(eq(member.userId, user.id))
          .limit(1),
        db.select({ capability: userCapability.capability })
          .from(userCapability)
          .where(eq(userCapability.userId, user.id)),
        db.select({ slug: organization.slug })
          .from(organization)
          .innerJoin(member, eq(member.organizationId, organization.id))
          .where(eq(member.userId, user.id))
          .limit(1),
      ]);

      return {
        sub: user.id,
        id: user.id,  // Deprecated alias for sub
        email: user.email,
        role: memberRecord[0]?.role ?? "member",
        capabilities: capabilityRecords.map((c) => c.capability),
        org: orgRecord[0]?.slug ?? "wxyc",
      };
    },
  },
}),

Service accounts are regular better-auth accounts (email+password) but are not members of the WXYC organization. The @services.wxyc.org email domain convention separates the two paths. The organizationPlugin({ roles: WXYCRoles }) configuration only needs human roles — service accounts never enter the org member table.

Admin Endpoints

Three new routes in Backend-Service, protected by the delegation chain defined in @wxyc/shared:

POST /roster/:userId/capabilities

• Body: { "capability": "editor" | "webmaster" }
• Auth: Caller must satisfy canAssignCapability(callerUser, capability) from @wxyc/shared
• Inserts into auth_user_capability with granted_by = caller's user ID
• Returns 201 on success, 403 if caller lacks assignment authority, 409 if already granted

DELETE /roster/:userId/capabilities/:capability

• Auth: Same delegation check as grant (you can revoke what you can grant)
• Deletes from auth_user_capability
• Returns 204 on success, 404 if not found

GET /roster/:userId/capabilities

• Auth: stationManager+ or the user themselves
• Returns list of capabilities with grant metadata

Capability Delegation Chain

Already defined in wxyc-shared/src/auth-client/capabilities.ts:

graph TD
    A[superAdmin / stationManager] -->|can assign| W[webmaster]
    A -->|can assign| E[editor]
    W -->|can assign| E
    E -->|cannot assign| X[nothing]

    style A fill:#7c3aed,color:#fff
    style W fill:#f39c12,color:#fff
    style E fill:#2ecc71,color:#fff
    style X fill:#eee,stroke:#ccc

Loading

Scalability

Adding a new capability (e.g., archivist for extended archive management):

1. Add "archivist" to CAPABILITIES in wxyc-shared
2. Define its assignment policy in CAPABILITY_ASSIGNERS
3. Update the CHECK constraint on auth_user_capability.capability (migration)
4. Consuming services check for the new capability — no changes to JWT infrastructure, JWKS, or verification logic

---

6. Shared JWT Verification Libraries

JWT verification is currently implemented ad hoc in archive/lib/jwt-utils.ts (~50 lines of raw jose calls). Every new consumer — TypeScript or Python — would duplicate this. This section defines reusable, tested libraries for both ecosystems.

TypeScript: @wxyc/shared/auth-server

A new entry point in wxyc-shared, distinct from the existing auth-client (which is browser-side and depends on better-auth/client). Server-side verification has different dependencies (jose for JWKS) and no browser assumptions.

The library is structured as a framework-agnostic core with thin framework-specific adapters. JWT verification logic lives in the core; each adapter wraps it into the target framework's middleware signature.

wxyc-shared/
  src/
    auth-server/
      index.ts          # Re-exports core public API
      verify.ts         # Core: token verification (jose)
      types.ts          # AuthPayload, JWTConfig, VerifyResult
      hono.ts           # Hono adapter: honoOptionalAuth, honoRequiredAuth
      express.ts        # Express adapter: expressOptionalAuth, expressRequiredAuth
      next.ts           # Next.js adapter: nextOptionalAuth, nextRequiredAuth

Core exports (@wxyc/shared/auth-server):

Export	Purpose
verifyToken(token, config)	Verifies JWT against JWKS, returns typed AuthPayload
extractBearerToken(header)	Parses Authorization: Bearer <token>, returns string | null
AuthPayload	Type: verified JWT payload with role, capabilities, email, etc.
JWTConfig	Type: { jwksUrl, issuer?, audience? }

Hono adapter (@wxyc/shared/auth-server/hono):

Export	Purpose
honoOptionalAuth(config)	Middleware: sets c.get('auth') to AuthPayload | null. No token = null. Bad token = 401.
honoRequiredAuth(config)	Middleware: sets c.get('auth') to AuthPayload. No token or bad token = 401.

Express adapter (@wxyc/shared/auth-server/express):

Export	Purpose
expressOptionalAuth(config)	Middleware: sets req.auth to AuthPayload | undefined. No token = undefined. Bad token = 401.
expressRequiredAuth(config)	Middleware: sets req.auth to AuthPayload. No token or bad token = 401.

Next.js adapter (@wxyc/shared/auth-server/next):

Export	Purpose
nextOptionalAuth(config)	For Route Handlers / Server Components: takes a Web API Request, returns AuthPayload | null. No token = null. Bad token = 401 Response.
nextRequiredAuth(config)	For Route Handlers / Server Components: takes a Web API Request, returns AuthPayload. No token or bad token = 401 Response.
withAuth(config, handler)	Wrapper for Next.js Route Handlers: injects auth into the handler context.

The Next.js adapter targets the Web API Request/Response interface used by Next.js Route Handlers and Middleware. The website uses Next.js for editor/webmaster capability gating on /admin/** routes.

Why framework adapters?

Hono stores context via c.set()/c.get(). Express extends req. Next.js Route Handlers use the Web API Request/Response interface. A generic middleware can't serve all three without awkward abstractions. The adapters are thin (~30 lines each) and keep the core dependency-free of any framework. hono, express, and next are peer dependencies — you only pull in what you use.

Why a separate entry point from auth-client?

auth-client imports better-auth/client and is designed for browser environments (cookie credentials, fetch-based token retrieval). Keeping them separate avoids bundling jose into client builds and better-auth/client into server builds.

Package exports configuration:

{
  "exports": {
    "./auth-server": "./dist/auth-server/index.js",
    "./auth-server/hono": "./dist/auth-server/hono.js",
    "./auth-server/express": "./dist/auth-server/express.js",
    "./auth-server/next": "./dist/auth-server/next.js"
  },
  "peerDependencies": {
    "hono": "^4.0.0",
    "express": "^5.0.0",
    "next": ">=14.0.0"
  }
}

Python: wxyc-auth

A minimal shared package for FastAPI services.

wxyc-auth/
  wxyc_auth/
    __init__.py
    jwks.py             # PyJWKClient wrapper with caching
    verify.py           # Token verification
    dependencies.py     # FastAPI Depends() factories
    slack.py            # Slack webhook HMAC signature verification
    types.py            # CallerIdentity, UserCaller, ServiceCaller, SlackWebhook
  tests/
    test_verify.py      # Contract tests (same matrix as TS)
    test_slack.py       # Slack signature verification tests
    conftest.py         # Test keypair + JWT generation fixtures
  pyproject.toml

FastAPI dependency usage:

from wxyc_auth import require_auth, require_role, Authorization

# Protected endpoint requiring any authenticated caller
@router.post("/request")
async def create_request(
    body: RequestBody,
    caller: CallerIdentity = Depends(require_auth),
):
    ...

The package also exports optional_auth (verify if present, pass None if absent) for future consumers that need tiered access without requiring authentication. No current Python service uses this — the archive-search equivalent is handled by the Hono adapter in TypeScript.

Caller Identity Types (Python)

The verification dependency returns a discriminated union:

@dataclass
class UserCaller:
    """A human user calling via app or browser."""
    user_id: str
    email: str
    role: str  # member, dj, musicDirector, stationManager, superAdmin

    def role_at_least(self, minimum: Authorization) -> bool: ...

@dataclass
class ServiceCaller:
    """An internal WXYC service, identified by its per-service role name."""
    service_name: str  # e.g., "request-o-matic", "library-metadata-lookup"
    email: str  # e.g., request-o-matic@services.wxyc.org

@dataclass
class SlackWebhook:
    """A verified Slack webhook request."""
    team_id: str
    channel_id: str

CallerIdentity = UserCaller | ServiceCaller | SlackWebhook

Slack Webhook Verification

request-o-matic receives Slack webhooks signed with HMAC (X-Slack-Signature + X-Slack-Request-Timestamp). This is a separate auth mechanism from JWT. The wxyc-auth package provides a dedicated dependency:

from wxyc_auth import verify_slack_signature

@router.post("/api/v1/slack/events")
async def handle_slack_event(
    request: Request,
    slack: SlackWebhook = Depends(verify_slack_signature),
):
    # slack.team_id and slack.channel_id are verified
    ...

Implementation: Verify the X-Slack-Signature header against HMAC-SHA256(signing_secret, "v0:{timestamp}:{body}"). Reject if timestamp is older than 5 minutes (replay protection).

Cross-Language Contract Tests

A shared JSON file of test vectors ensures both TS and Python verify tokens identically:

[
  { "name": "valid_dj_token",       "token": "...", "expected": "valid",   "role": "dj" },
  { "name": "expired_token",        "token": "...", "expected": "expired"                },
  { "name": "wrong_audience",       "token": "...", "expected": "invalid"                },
  { "name": "bad_signature",        "token": "...", "expected": "invalid"                },
  { "name": "missing_role",         "token": "...", "expected": "invalid"                },
  { "name": "service_token_rom",     "token": "...", "expected": "valid",   "role": "request-o-matic" },
  { "name": "service_token_lml",     "token": "...", "expected": "valid",   "role": "library-metadata-lookup" },
  { "name": "token_with_caps",      "token": "...", "expected": "valid",   "capabilities": ["editor"] },
  { "name": "superAdmin_token",     "token": "...", "expected": "valid",   "role": "superAdmin" }
]

Both test suites load this file and assert identical results. Test vectors are generated by a shared script using a test RS256 keypair committed to the repo.

---

7. First-Party Service Integration

7.1 wxyc-archive-search (Role-Tier Gating)

Currently hard-filters to 2 weeks of results. With the shared verification library:

sequenceDiagram
    participant App as Mobile App / Browser
    participant WAS as wxyc-archive-search
    participant JWKS as Auth JWKS Endpoint

    App->>WAS: GET /search?q=radiohead
    Note over WAS: Extract Authorization header
    alt No token present
        WAS->>WAS: days_allowed = 14
    else Token present
        WAS->>JWKS: Fetch public keys (cached)
        JWKS-->>WAS: RSA public keys
        WAS->>WAS: Verify JWT signature + expiry
        alt Valid token, role >= DJ
            WAS->>WAS: days_allowed = 90
        else Valid token, role < DJ
            WAS->>WAS: days_allowed = 14
        end
    end
    WAS->>WAS: Filter results to days_allowed window
    WAS-->>App: Search results

Loading

Changes: Add @wxyc/shared/auth-server/hono dependency. Use honoOptionalAuth middleware on /search. Check role tier for extended access window. ~100 lines.

7.2 website (Capability-Gated TinaCMS)

The website currently has no auth. Integration gates TinaCMS admin routes behind capability checks:

graph TD
    subgraph "website (Next.js)"
        LP[Login Page]
        MW[Auth Middleware]
        TA[TinaCMS Admin /admin]
        API[API Routes /api/tina/*]
    end

    subgraph "Backend-Service"
        AUTH[Auth Service]
        JWKS[JWKS Endpoint]
    end

    LP -- "sign in" --> AUTH
    AUTH -- "JWT (with capabilities)" --> LP
    LP -- "store session" --> MW
    MW -- "verify JWT via JWKS" --> JWKS
    MW -- "check 'editor' capability" --> TA
    TA -- "content operations" --> API
    API -- "verify JWT, check capability" --> API
    API -- "proxy to TinaCMS" --> TINA[TinaCMS Backend]

Loading

Changes:

1. Add @wxyc/shared/auth-client for the login page (browser-side session)
2. Add @wxyc/shared/auth-server for API route verification (server-side JWKS)
3. Next.js middleware on /admin/** routes checks for valid JWT with editor or webmaster capability
4. TinaCMS API routes validate the JWT on every write operation
5. Read-only access (viewing the public site) remains unauthenticated

Deployment consideration: The website is currently a static Next.js export to GitHub Pages. Adding auth middleware requires server-side rendering or an API layer. It should move to Cloudflare Pages (like dj-site) or adopt client-side-only auth checks with a serverless function backend. This is an architectural decision to resolve during Phase 2 implementation.

7.3 Mobile Apps (User JWT for Extended Features)

The iOS and Android apps currently call api.wxyc.org without authentication. Adding auth enables:

• Extended archive access for authenticated DJs (90+ days vs 14 days)
• Authenticated song requests through request-o-matic (caller identity for audit)
• Personalized features (favorites, listening history)

Approach:

• Without sign-in: The app sends requests with no Authorization header. Archive-search returns the default 14-day window. request-o-matic rejects unauthenticated requests (users must sign in to submit song requests).
• With sign-in: The app authenticates with better-auth (email+password), receives a JWT with the user's role and capabilities, and includes it in subsequent requests. DJs get extended archive access; all authenticated users can submit song requests with caller identity for audit.
• No changes to auth infrastructure required — the JWT/JWKS pattern already scales to new consumers.

better-auth's anonymous() plugin was considered for frictionless initial access (auto-creating a session without credentials) but is not needed here. The archive-search honoOptionalAuth middleware already handles the no-token case gracefully, and request-o-matic requires real identity for audit. Anonymous sessions would add complexity (what role? what capabilities?) without a clear benefit.

7.4 dj-site and archive (Existing)

No changes to auth verification. The JWT format and JWKS verification remain identical.

---

8. Service-to-Service Authentication

Problem

request-o-matic and library-metadata-lookup accept all traffic unconditionally. They are meant to be called by apps and internal services, not exposed publicly. There is no way to identify callers, enforce access policies, or audit usage.

Solution: Service Accounts with JWT + User Context Forwarding

Use better-auth accounts for service identity, verified through the same JWKS infrastructure. User context flows through the service chain when applicable.

Service Account Setup

Each service gets a better-auth account with a reserved email domain and its own named role in ServiceRoles:

Service	Email	Role
request-o-matic	request-o-matic@services.wxyc.org	request-o-matic
library-metadata-lookup	library-metadata-lookup@services.wxyc.org	library-metadata-lookup

Auth Flow: Service Startup

sequenceDiagram
    participant SVC as request-o-matic
    participant AUTH as Auth Service

    Note over SVC: Application startup
    SVC->>AUTH: POST /auth/sign-in/credential<br/>{ email, password }
    AUTH-->>SVC: 200 OK + JWT
    SVC->>SVC: Cache JWT, schedule refresh before expiry

    Note over SVC: Periodic refresh
    loop Every N minutes (before expiry)
        SVC->>AUTH: POST /auth/sign-in/credential
        AUTH-->>SVC: Fresh JWT
        SVC->>SVC: Replace cached JWT
    end

Loading

Environment variables per service:

SERVICE_AUTH_EMAIL=request-o-matic@services.wxyc.org
SERVICE_AUTH_PASSWORD=<secret>
BETTER_AUTH_URL=https://api.wxyc.org/auth
BETTER_AUTH_JWKS_URL=https://api.wxyc.org/auth/jwks

Auth Flow: User-Initiated Request Through Service Chain

When a user action (e.g., song request from a mobile app) flows through services:

sequenceDiagram
    participant App as Mobile App
    participant ROM as request-o-matic
    participant LML as library-metadata-lookup
    participant JWKS as Auth JWKS

    App->>ROM: POST /api/v1/request<br/>Authorization: Bearer <user-jwt>
    ROM->>JWKS: Verify user JWT (cached keys)
    JWKS-->>ROM: Valid
    ROM->>ROM: Extract user identity for audit/analytics

    ROM->>LML: POST /api/v1/lookup<br/>Authorization: Bearer <service-jwt><br/>X-Forwarded-User: <user-id>
    LML->>JWKS: Verify service JWT (cached keys)
    JWKS-->>LML: Valid, role=request-o-matic
    LML->>LML: Process lookup
    LML-->>ROM: Lookup results

    ROM->>ROM: Compose response
    ROM-->>App: Request result

Loading

Why the service JWT on the internal hop instead of forwarding the user JWT?

• library-metadata-lookup doesn't need to make user-level access decisions — it returns the same data regardless of who asked.
• The service JWT proves the caller is a trusted WXYC service, not an arbitrary internet client.
• User identity is passed as metadata (X-Forwarded-User) for audit logging, not for access control.
• If library-metadata-lookup ever needs user-level decisions, it can verify the forwarded token from a second header.

Auth Flow: Slack Webhook

Slack calls request-o-matic directly with HMAC-signed webhooks. This is a separate auth path from JWT:

sequenceDiagram
    participant Slack
    participant ROM as request-o-matic

    Slack->>ROM: POST /api/v1/slack/events<br/>X-Slack-Signature: v0=...<br/>X-Slack-Request-Timestamp: ...
    ROM->>ROM: Verify HMAC-SHA256 signature<br/>Check timestamp freshness (< 5 min)
    alt Valid signature
        ROM->>ROM: Process event
        ROM-->>Slack: 200 OK
    else Invalid signature
        ROM-->>Slack: 401 Unauthorized
    end

Loading

Service Roles in Middleware

Service identities bypass the human role hierarchy. The middleware distinguishes callers by type:

def require_role(minimum: Authorization):
    async def dependency(caller: CallerIdentity = Depends(require_auth)):
        if isinstance(caller, ServiceCaller):
            return caller  # Services bypass role hierarchy checks
        if not caller.role_at_least(minimum):
            raise HTTPException(403, "Insufficient role")
        return caller
    return dependency

The verification layer resolves per-service roles into ServiceCaller instances:

SERVICE_ROLES = {"request-o-matic", "library-metadata-lookup"}

def _resolve_caller(payload: dict) -> CallerIdentity:
    role = payload["role"]
    if role in SERVICE_ROLES:
        return ServiceCaller(service_name=role, email=payload["email"])
    return UserCaller(user_id=payload["sub"], email=payload["email"], role=role)

Endpoint Access Matrix (Python Services)

Endpoint	Unauthenticated	User (any)	User (DJ+)	Service	Slack (HMAC)
GET /health	x	x	x	x
POST /api/v1/parse		x	x	x
POST /api/v1/request		x	x	x
POST /api/v1/artwork		x	x	x
GET /api/v1/library/search		x	x	x
POST /api/v1/discogs/search		x	x	x
POST /api/v1/slack/events					x
POST /api/v1/slack/commands					x

All endpoints except health and Slack webhooks require JWT authentication. Slack endpoints require HMAC signature verification. The auth boundary is "is this a known caller?" not "what level of DJ are you?"

---

9. Infrastructure Architecture

Approach: Cloudflare Access + GitHub (No Dedicated IDP)

Instead of deploying a dedicated identity provider (Authentik, Keycloak, etc.), this proposal uses Cloudflare Access with GitHub as the identity provider for infrastructure gating. This eliminates an entire infrastructure layer while achieving the same access control.

Why not Authentik:

• Adds ~512 MB RAM to an already-loaded EC2 instance.
• Creates a second user store, contradicting the "single identity" goal.
• Requires OIDC/SAML configuration and ongoing maintenance.
• Overkill for gating a handful of infrastructure services used by <10 people.

Why Cloudflare Access + GitHub:

• Zero infrastructure — Cloudflare hosts the auth layer.
• Free for up to 50 users (more than enough for WXYC).
• Tech team already has GitHub accounts.
• GitHub org + team membership provides sufficient access control granularity.
• Team-wide session sharing — authenticate once with GitHub, access all gated services.
• Built-in Cloudflare Tunnel support for secure ingress without opening firewall ports.

Target Architecture

flowchart TD
    BS["Backend-Service<br/>(better-auth + JWKS)"]

    BS -->|JWKS| PY["wxyc-auth<br/>(PyJWT)"]
    BS -->|JWKS| TS["@wxyc/shared/auth-server<br/>(jose)"]
    BS -.->|webhook| SYNC[Sync Service]

    PY --> ROM
    PY --> LML
    TS --> DS
    TS --> ARC
    TS --> WEB
    TS --> ARCS

    subgraph consumers["Auth-Protected Services"]
        subgraph pyApps["Python (via wxyc-auth)"]
            direction LR
            ROM[request-o-matic]
            LML[library-metadata-lookup]
        end
        subgraph tsApps["TypeScript (via auth-server)"]
            direction LR
            DS[dj-site]
            ARC[archive]
            WEB[website]
            ARCS[archive-search]
        end
    end

    ROM -- "service JWT" --> LML

    subgraph mobile["Mobile Apps"]
        direction LR
        IOS[wxyc-ios-64]
        AND[WXYC-Android]
    end

    mobile -->|user JWT| consumers

    subgraph external["Sync Targets"]
        direction LR
        AC[AzuraCast]
        PH[PostHog]
        META["Facebook /<br/>Instagram"]
        BSKY[Bluesky]
    end

    SYNC -.-> AC
    SYNC -.-> PH
    SYNC -.-> META
    SYNC -.-> BSKY

    CA["Cloudflare Access<br/>(GitHub IDP)"] -->|gate access| AC

    style BS fill:#2563eb,color:#fff
    style PY fill:#4a9,stroke:#287
    style TS fill:#4a9,stroke:#287
    style CA fill:#f38020,color:#fff
    style PH fill:#1d4aff,color:#fff
    style SYNC fill:#6b7280,color:#fff,stroke-dasharray: 5 5
    style META fill:#1877f2,color:#fff
    style BSKY fill:#0085ff,color:#fff

Loading

Not shown: Cloudflare Pages hosts dj-site and website. GitHub provides IDP for Cloudflare Access and social SSO for PostHog. Sentry uses manual accounts (no API integration). Mobile apps send user JWTs to archive-search and request-o-matic for authenticated features. AzuraCast and Backend-Service run on EC2.

Authentication Flows

First-Party Login

No change from today. Users authenticate directly with better-auth (email+password). better-auth issues JWTs verified via JWKS.

sequenceDiagram
    actor User
    participant App as dj-site / archive / website
    participant BS as Backend-Service<br/>(better-auth)

    User->>App: Click "Sign in"
    App->>BS: POST /auth/sign-in/credential
    BS->>BS: Verify credentials<br/>Issue JWT with role + capabilities
    BS->>App: JWT + session cookie
    App->>User: Authenticated

Loading

Infrastructure Access (Gated via Cloudflare Access)

sequenceDiagram
    actor User
    participant CF as Cloudflare Access
    participant GH as GitHub
    participant Svc as AzuraCast

    User->>CF: Navigate to service URL
    CF->>CF: Check Access policy
    CF->>GH: GitHub OAuth redirect
    GH->>User: GitHub login page
    User->>GH: Credentials / 2FA
    GH->>CF: OAuth callback
    CF->>CF: Check GitHub org/team membership<br/>against Access policy
    CF->>Svc: Proxy request (authenticated)
    Svc->>User: Service UI

Loading

---

10. Third-Party Service Integration

10.1 Cloudflare Access (Free Tier)

IDP: GitHub (org + team membership)
Limit: 50 users
Session: Team-wide session sharing — authenticate once, access all gated services
Documentation: Cloudflare + GitHub IDP

Cloudflare Access gates self-hosted infrastructure services. Policies use GitHub org and team membership.

Access Application	Required GitHub Team	Maps To
AzuraCast Admin	WXYC-Radio/tech-team OR WXYC-Radio/music-directors	superAdmin, musicDirector

Setup requirements:

• Create a GitHub OAuth App under the WXYC-Radio organization
• Enable "Include organization teams" in Cloudflare Access GitHub IDP config
• Approve the OAuth App in GitHub org settings (if OAuth app restrictions are enabled)

10.2 Sentry (Cloud, Free Tier)

SSO: Not available on free tier.
Approach: Manual account management. Tech team members create Sentry accounts with their work email.

Self-hosting Sentry was considered for SAML SSO but rejected: the Docker Compose stack is resource-intensive (~2-4 GB RAM), and the operational burden of maintaining self-hosted Sentry outweighs the SSO benefit for a team of <10 people. Sentry is used across the stack (Backend-Service, dj-site, Python services, mobile apps) which makes reliable uptime critical.

Who Needs Access	Sentry Role	Account Management
Tech team (superAdmin)	Admin	Manual invite/revoke

10.3 AzuraCast

Protocol: None (API-based sync + Cloudflare Access gate)
Cost: Free (self-hosted)

AzuraCast is the station's auto DJ and digital music library platform. It has no native SSO. The maintainer has explicitly declined SSO feature requests. Integration is two-layered:

1. Cloudflare Access gates who can reach the AzuraCast admin UI (tech team + music directors only).
2. Sync Service provisions AzuraCast user accounts and roles via the admin API.

AzuraCast separates web users (admin interface) from streamers (broadcast connections via Icecast/Shoutcast). The sync service manages web users; streamer account provisioning is out of scope (see Open Questions).

AzuraCast uses an ACL permission model, not preset roles. The sync service creates WXYC-specific roles:

WXYC Identity	AzuraCast Role	AzuraCast Permissions
superAdmin	WXYC Super Admin	Global: administer all
musicDirector	WXYC Music Director	Station: manage station media, view station management

10.4 PostHog (Cloud, Free Tier)

Protocol: GitHub social SSO
Cost: Free
Limitation: No SAML/OIDC (requires $750/mo Scale plan).

Tech team members sign in with GitHub SSO (all tech team members already have GitHub accounts). The sync service sends PostHog invites via the Invites API when a user is granted superAdmin. Manual revocation when someone leaves the tech team.

Only the tech team (superAdmin) needs PostHog access.

Email mapping note: PostHog invites are sent to the user's better-auth email. Since PostHog login uses GitHub SSO, the invitee's GitHub account must be associated with the same email, or they'll need to manually link the invite to their GitHub login. Tech team members should use the same email for both.

10.5 Facebook / Instagram (Meta Business Suite)

Protocol: Meta Business API (user invite/revoke)
Cost: Free
Prerequisite: Meta App Review with business_management permission (one-time)

Current state: A single shared username and password, handed to the next person without rotation. Departed members retain access indefinitely.

Target state: WXYC's Facebook Page and Instagram account are claimed under a Meta Business Suite account. Individual team members are invited by email with granular roles. The sync service automates invite/revoke via the Meta Business API.

Role mapping:

WXYC Identity	Meta Business Role	Permissions
superAdmin	Admin	Full control, can manage team members
stationManager	Admin	Full control, can manage team members
editor capability	Editor	Can create and publish posts

Sync service actions:

Event	Action
role.changed to stationManager/superAdmin	Invite as Admin (if not already a member)
capability.granted editor	Invite as Editor (if not already a member)
capability.revoked editor	Revoke access (if no other qualifying role)
role.changed away from stationManager	Downgrade to Editor (if has editor capability) or revoke

Email mapping note: Meta invites are sent to the user's better-auth email. The user must accept the invite using a personal Facebook account — they do not need to use the same email for both, but the invite flow is email-initiated. Users without a personal Facebook account cannot be provisioned (a reasonable assumption for social media managers).

Meta App Review: The sync service requires a Meta App with business_management permission. This is a one-time App Review submission explaining the use case. The review takes days to weeks. If rejected, the fallback is manual management via the Meta Business Suite web UI (same overhead as Sentry).

10.6 Bluesky (AT Protocol)

Protocol: AT Protocol API (app password management)
Cost: Free (open protocol)
Prerequisite: None

Current state: Same as Facebook/Instagram — single shared password, no rotation, no individual access control.

Target state: Each team member gets a named app password, created and revoked by the sync service. The main account password is stored in secrets management, known only to superAdmin.

Role mapping:

WXYC Identity	Bluesky Access
superAdmin	Main account password holder + named app password
stationManager	Named app password
editor capability	Named app password

Sync service actions:

Event	AT Protocol Call
Qualifying role/capability granted	com.atproto.server.createAppPassword with user's name as label
Qualifying role/capability revoked	com.atproto.server.revokeAppPassword

The sync service delivers the generated app password to the user via a notification channel (Slack DM or email). On revocation, the app password is revoked server-side — no user action required.

Limitation: App passwords work in third-party Bluesky clients and for API-based posting, but not for logging into the bsky.app web UI. For a station account where posting is the primary action, this is acceptable. If web UI access is needed, users can request the main account password from a superAdmin, and the password should be rotated when that access is revoked.

---

11. Sync Service

A lightweight service that keeps AzuraCast accounts, PostHog invites, Meta Business Suite access, and Bluesky app passwords in sync with Backend-Service's role data, triggered by webhooks from Backend-Service on role and capability changes.

flowchart TD
    subgraph Trigger["Trigger"]
        WH[Backend-Service webhook<br/>on role/capability change]
    end

    subgraph Sync["Sync Service (FastAPI)"]
        RCV[Receive webhook event]
        DIFF[Diff current state<br/>vs. desired state]
        AC_SYNC[Provision/deprovision<br/>AzuraCast users + roles]
        PH_SYNC[Send/revoke<br/>PostHog invites]
        META_SYNC[Invite/revoke<br/>Meta Business Suite users]
        BSKY_SYNC[Create/revoke<br/>Bluesky app passwords]
    end

    subgraph Sources["External APIs"]
        BS_API[Backend-Service API<br/>roster + capabilities]
        AC_API[AzuraCast API]
        PH_API[PostHog API]
        META_API[Meta Business API]
        BSKY_API[Bluesky AT Protocol API]
    end

    WH --> RCV
    RCV --> DIFF
    DIFF --> BS_API
    DIFF --> AC_SYNC
    DIFF --> PH_SYNC
    DIFF --> META_SYNC
    DIFF --> BSKY_SYNC
    AC_SYNC --> AC_API
    PH_SYNC --> PH_API
    META_SYNC --> META_API
    BSKY_SYNC --> BSKY_API

Loading

Implementation: Python (FastAPI). Runs on the same EC2 instance. Backend-Service emits webhooks when roles or capabilities change (e.g., after a role assignment, stationManager transfer, or capability grant/revoke). The sync service receives the event, fetches full user state from Backend-Service's roster API (not the DB directly — avoids schema coupling), diffs against each external service (AzuraCast, PostHog, Meta Business Suite, Bluesky), and reconciles.

Webhook events:

Event	Trigger	Payload fields
role.changed	Role assignment or stationManager transfer	userId, oldRole, newRole
role.transferred	stationManager transfer (fired for both users)	grantedUserId, revokedUserId, role
capability.granted	Capability assigned to user	userId, capability, grantedBy
capability.revoked	Capability removed from user	userId, capability, revokedBy

{
  "event": "role.changed",
  "userId": "user-id",
  "oldRole": "dj",
  "newRole": "superAdmin",
  "timestamp": "2026-03-15T12:00:00Z"
}

Backend-Service needs a webhook emission layer in its role/capability assignment endpoints. The sync service authenticates incoming webhooks using a shared secret (HMAC signature, same pattern as Slack webhooks).

AzuraCast password handling: The sync service generates random passwords for AzuraCast accounts. Since Cloudflare Access is the real authentication gate, AzuraCast passwords are a secondary concern. The sync service can store them encrypted or simply regenerate on each sync.

---

12. Test Strategy

Unit Tests

graph TD
    subgraph "Unit Tests (both TS and Python)"
        U1[Generate test JWT<br/>with RS256 test keypair]
        U2[Mock JWKS endpoint returning test public key]
        U3[Parameterize: valid/expired/wrong-aud/bad-sig/missing-role]
        U4[Verify each role tier: member/dj/md/sm/superAdmin + per-service roles]
        U5[Verify capability claim extraction]
        U6[Verify stationManager mutual exclusivity]
        U1 --> U3
        U2 --> U3
        U3 --> U4
        U3 --> U5
        U3 --> U6
    end

Loading

Shared verification libraries (@wxyc/shared/auth-server, wxyc-auth):

• Generate test JWTs with RS256 test keypair
• Mock JWKS endpoint returning test public key
• Parameterize: valid, expired, wrong audience, bad signature, missing role, with/without capabilities
• Verify each human role tier and per-service named roles (request-o-matic, library-metadata-lookup)
• Verify ServiceCaller bypasses role hierarchy but UserCaller does not
• Verify unknown service roles are rejected (role not in WXYCRoles or ServiceRoles = 403)
• Verify Slack webhook HMAC verification (valid, expired timestamp, bad signature)

Capability delegation (@wxyc/shared):

• Existing capabilities.test.ts already covers canAssignCapability
• Extend to verify JWT claim extraction and requireCapability middleware with mocked JWTs

Backend-Service admin endpoints:

• Test delegation: DJ with webmaster can grant editor; DJ without webmaster cannot
• Test assignment: stationManager can assign dj, musicDirector, webmaster; cannot assign superAdmin
• Test revocation: capability removed from DB, new JWT excludes it
• Test stationManager transfer: assigning stationManager atomically revokes from current holder

Contract Tests

graph TD
    C1["TS and Python verify the same JWT identically"]
    C2["Same parameterized test matrix in both languages"]
    C3["Shared test vectors<br/>(JSON fixtures)"]
    C3 --> C1
    C3 --> C2

Loading

Shared test vectors (JSON file of pre-generated test cases) loaded by both TS and Python test suites. Enforces identical behavior across implementations.

Integration Tests

• Seed user, grant editor capability, obtain JWT, verify capabilities claim is present
• Start auth service, create service account, authenticate, obtain real service JWT
• Call request-o-matic with service JWT, verify 200; without auth, verify 401
• Verify service token refresh works (authenticate, wait, re-authenticate)
• Call request-o-matic Slack endpoint with valid HMAC, verify 200; with bad HMAC, verify 401
• Transfer stationManager: verify old holder is demoted, new holder is promoted, in single transaction

E2E Tests

• archive-search: Authenticate as DJ, call archive-search with JWT, verify extended search window
• website: Authenticate with editor capability, navigate to /admin, verify access; without capability, verify 403
• service chain: Authenticate as service, call request-o-matic, which calls library-metadata-lookup, verify end-to-end completion
• service chain with user context: Authenticate as DJ, call request-o-matic with user JWT, verify X-Forwarded-User reaches library-metadata-lookup
• mobile request flow: Authenticate as DJ via mobile app, submit song request to request-o-matic, verify caller identity logged

---

13. Implementation Phases

Dependency Graph

graph TD
    A["Step 1: TS auth-server module<br/>(@wxyc/shared/auth-server)"] --> C
    A --> D
    B["Step 2: Capabilities schema +<br/>JWT enrichment +<br/>superAdmin role"] --> D
    B --> F
    C["Step 3: wxyc-archive-search<br/>(role-tier gating)"]
    D["Step 4: Website TinaCMS<br/>(capability-gated)"]
    E["Step 5: Python wxyc-auth<br/>package"] --> H
    B --> G
    F["Step 6: Capability admin<br/>endpoints + stationManager<br/>transfer"] --> D
    G["Step 7: Service accounts<br/>(better-auth)"] --> H
    H["Step 8: request-o-matic +<br/>library-metadata-lookup<br/>(service + Slack auth)"]
    I["Step 9: Mobile app auth<br/>(iOS + Android)"]
    J["Step 10: Cloudflare Access +<br/>GitHub IDP"] --> K
    K["Step 11: Gate AzuraCast<br/>via CF Access"]
    L["Step 12: Sync service<br/>(AzuraCast + PostHog +<br/>Meta + Bluesky +<br/>webhook emission)"]

    C --> I
    H --> I
    B --> L
    K --> L

    style A fill:#2ecc71,color:#fff
    style B fill:#2ecc71,color:#fff
    style E fill:#2ecc71,color:#fff
    style C fill:#3498db,color:#fff
    style F fill:#3498db,color:#fff
    style G fill:#3498db,color:#fff
    style D fill:#e67e22,color:#fff
    style H fill:#e67e22,color:#fff
    style I fill:#e67e22,color:#fff
    style J fill:#9b59b6,color:#fff
    style K fill:#9b59b6,color:#fff
    style L fill:#9b59b6,color:#fff

Loading

Gantt Chart

gantt
    title Implementation Phases
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Phase 1 - Foundation
        Step 1 - TS auth-server module           :a1, 2026-03-15, 5d
        Step 2 - Capabilities + JWT + superAdmin :a2, 2026-03-15, 5d
        Step 5 - Python wxyc-auth package        :a5, 2026-03-15, 8d

    section Phase 2 - First-Party Consumers
        Step 3 - archive-search (role gating)   :a3, after a1, 4d
        Step 6 - Capability endpoints + SM xfer :a6, after a2, 5d
        Step 7 - Service accounts (better-auth) :a7, after a2, 3d
        Step 8 - ROM + LML (service + Slack)    :a8, after a5, 6d
        Step 4 - Website TinaCMS (capability)   :a4, after a6, 8d
        Step 9 - Mobile app auth (iOS + Android) :a9, after a8, 5d

    section Phase 3 - Infrastructure Gating
        Step 10 - Cloudflare Access + GitHub    :p3a, after a4, 3d
        Step 10b - Meta Business Suite setup    :p3m, after a4, 5d
        Step 11 - Gate AzuraCast via CF Access  :p3b, after p3a, 2d

    section Phase 4 - Sync Service
        Step 12a - Webhook emission + scaffold  :p4a, after p3b, 5d
        Step 12b - AzuraCast user/role sync     :p4b, after p4a, 5d
        Step 12c - PostHog invite sync          :p4c, after p4b, 3d
        Step 12d - Meta Business Suite sync     :p4d, after p4c, 4d
        Step 12e - Bluesky app password sync    :p4e, after p4c, 3d

Loading

Phase 1: Foundation (No Consumer Changes)

No new infrastructure. Builds reusable libraries and schema.

Step	Repo	Description	Est. delta
1	wxyc-shared	Extract auth-server entry point from archive's jwt-utils.ts. Framework-agnostic core (verifyToken, extractBearerToken) plus Hono, Express, and Next.js adapters (optionalAuth, requiredAuth). Unit tests with test keypair.	~400 lines
2	Backend-Service, wxyc-shared	Merge fix/add-admin-role-to-wxyc-roles improvements, rename admin to superAdmin, add infrastructure and roles resources. Define ServiceRoles with per-service named roles. Update middleware to resolve from both WXYCRoles and ServiceRoles. Drizzle migration for auth_user_capability table. Extend definePayload to include capabilities, org, deprecated id alias, and service account email domain branching. Add stationManager mutual exclusivity constraint.	~400 lines
5	wxyc-auth (new)	Python package with PyJWKClient wrapper, FastAPI dependencies, CallerIdentity types, Slack HMAC verification. Contract tests matching TS test vectors.	~500 lines

Steps 1, 2, and 5 are independent and can be developed in parallel.

Phase 2: First-Party Consumers

Step	Repo	Description	Est. delta
3	wxyc-archive-search	Add @wxyc/shared/auth-server/hono. honoOptionalAuth on /search. Extended window for DJ+.	~100 lines
6	Backend-Service	POST/DELETE/GET /roster/:userId/capabilities. Delegation chain enforcement. stationManager transfer endpoint with atomicity.	~350 lines
7	Backend-Service	Create service accounts for request-o-matic and library-metadata-lookup.	~50 lines
8	request-o-matic, library-metadata-lookup	Add wxyc-auth dependency. require_auth on all endpoints except /health. Slack HMAC verification on /slack/* endpoints. Token refresh at startup.	~200 lines each
4	website	Login page, auth middleware on /admin/**, capability check for TinaCMS writes. Resolve deployment (static export vs Cloudflare Pages).	~500 lines
9	wxyc-ios-64, WXYC-Android	Optional sign-in flow, JWT storage, include token in requests to archive-search and request-o-matic.	~300 lines each

Steps 3 and 6 are independent. Step 7 depends on 2 (definePayload service account branching + ServiceRoles). Step 8 depends on 5 and 7. Step 4 depends on 1, 2, and 6 (auth-server library, capability table + definePayload, capability endpoints). Step 9 depends on 3 and 8 (archive-search optional auth, ROM/LML required auth).

Phase 3: Infrastructure Gating

New infrastructure: Cloudflare Access configuration (no servers to deploy). Meta Business Suite set-up.

Step	Description
10	Create GitHub OAuth App for WXYC-Radio org. Configure Cloudflare Access with GitHub IDP. Define Access Application policies per GitHub team.
11	Put AzuraCast admin behind Cloudflare Access. Verify GitHub team-based policies.
10b	Set up Meta Business Suite account, claim Facebook Page + Instagram account. Create Meta App and submit for App Review with business_management permission. (Can run in parallel with Steps 10-11; review takes days to weeks.)

Phase 4: Sync Service

New infrastructure: webhook emission in Backend-Service + small Python service on EC2.

Step	Description
12a	Add webhook emission to Backend-Service role/capability assignment endpoints (HMAC-signed). Scaffold sync service. Python FastAPI, receives webhooks, calls Backend-Service roster API + external service APIs.
12b	AzuraCast user/role provisioning. Create/update/delete AzuraCast users and roles via admin API.
12c	PostHog invite sync. Send invites to new superAdmin users via PostHog Invites API.
12d	Meta Business Suite sync. Invite/revoke Facebook + Instagram access via Meta Business API. Depends on Step 10b (Meta App Review approval).
12e	Bluesky app password sync. Create/revoke named app passwords via AT Protocol API. Deliver credentials to users via Slack DM or email.

---

---

Sections 14–16 (Open Questions, Risk Assessment, Decision Log) continue in the first comment below — GitHub's 65K character limit required splitting the proposal.

[jakebromberg]

14. Open Questions

1. Python package distribution: Should wxyc-auth be a published package (PyPI or private registry), a git submodule, or a vendored module with contract tests? Two consumers today (request-o-matic, library-metadata-lookup), possibly more later.

2. Website deployment model: The website is currently a static Next.js export to GitHub Pages. Auth middleware requires SSR or an API layer. Should it move to Cloudflare Pages (like dj-site) or stay on GitHub Pages with client-side-only auth + serverless functions?

3. AzuraCast streamer accounts: The sync service manages AzuraCast web users, but streamers/DJs who connect via broadcast software are a separate account type. Should streamer account provisioning be in scope?

4. GitHub org setup: Does WXYC-Radio have a GitHub organization with team management? If not, creating the org and teams is a prerequisite for Phase 3.

5. GitHub team membership sync: Cloudflare Access policies depend on GitHub teams (tech-team, music-directors), but team membership is managed manually in GitHub. Should the sync service also manage GitHub team membership via the GitHub Teams API? This would close the loop — a role change in better-auth propagates to GitHub teams, which propagate to CF Access policies. Without it, a stationManager promoting someone to musicDirector must also manually add them to the music-directors GitHub team.

6. Bluesky app password delivery: The sync service creates app passwords but needs a channel to deliver them to users. Options: Slack DM (requires Slack bot with DM permissions), email (requires SMTP or transactional email service), or display in dj-site admin UI (requires a new UI surface). Which delivery channel is preferred?

7. Bluesky web UI access: App passwords don't work for logging into bsky.app. Is third-party client / API-only access sufficient for station social media, or do some users need bsky.app web UI access (which would still require the shared main password)?

8. Meta App Review timing: The Meta App Review for business_management permission should be submitted early (Phase 3) since it takes days to weeks. If rejected, should we invest effort in resubmitting, or accept manual Meta Business Suite management as the permanent approach?

---

15. Risk Assessment

Risk	Likelihood	Impact	Mitigation
JWKS endpoint becomes a single point of failure	Low	Medium	jose and PyJWKClient cache JWKS keys. Services continue to verify tokens with cached keys for the cache TTL. Auth service is already a dependency for login — this adds no new SPOF.
Python and TS verification diverge	Medium	Medium	Shared test vectors (JSON fixtures) loaded by both test suites. Contract tests in CI.
Service account credentials leaked	Low	Medium	Rotate credentials via env vars. Service JWTs have short expiry. No resource permissions on service roles. Per-service identity means a leaked token for one service doesn't impersonate another.
Service token refresh failure	Low	Medium	Retry with backoff. Log loudly. Service continues with cached token until expiry. Health check reports auth status.
AzuraCast API changes break sync service	Low	Low	Pin AzuraCast version; sync service is non-critical (manual fallback).
JWT payload size grows with capabilities	Low	Low	Capabilities array is a few strings at most. If it grows, switch to a claims endpoint.
Website static export incompatible with auth middleware	Medium	Medium	Resolve in Phase 2: move to Cloudflare Pages or use client-side auth + serverless functions.
Slack signing secret rotation	Low	Low	Store in env var. Rotate via Railway/deployment config.
stationManager transfer race condition	Low	Medium	Transaction-level locking. The atomic transfer query prevents concurrent assignments.
Meta App Review rejected	Medium	Low	Fallback is manual management via Meta Business Suite web UI (same overhead as Sentry). Resubmit with revised justification if rejected.
Meta Business API rate limits or deprecation	Low	Low	Low call volume (role/capability changes are infrequent). Monitor Meta developer changelog. Manual fallback if API breaks.
Bluesky app password limit reached	Low	Low	Bluesky currently allows up to 32 app passwords. WXYC is unlikely to exceed this. Monitor and rotate stale passwords.
Bluesky API or AT Protocol breaking changes	Low	Low	AT Protocol is versioned and stable. Pin atproto client library version. Manual fallback (create/revoke app passwords in bsky.app settings).

---

16. Decision Log

Decision	Rationale	Alternatives Considered
No dedicated IDP (no Authentik/Keycloak)	Eliminates an entire infrastructure layer. CF Access + GitHub provides equivalent gating for infrastructure services. Better-auth remains the single user store, avoiding two-user-store complexity.	Authentik (adds ~512 MB RAM, second user store, OIDC/SAML config overhead), Keycloak (even heavier)
Cloudflare Access + GitHub for infra gating	Free for 50 users, zero infrastructure, team-wide session sharing, GitHub org/team filtering. Tech team already has GitHub accounts.	Authentik outpost (requires self-hosting), manual access control (doesn't scale)
Sentry stays on cloud (no self-hosting)	Self-hosted Sentry is resource-intensive (~2-4 GB RAM). Without SAML (which required Authentik), the SSO benefit disappears. Manual accounts for <10 tech team members are manageable.	Self-host Sentry for SAML SSO (too expensive in RAM and maintenance for the benefit)
GitHub SSO for PostHog	Only social SSO available on free tier; tech team already has GitHub accounts	Authentik SSO ($750/mo), self-host PostHog (deprecated, unsupported)
Dedicated capability table over JSON column	Queryable, auditable (who granted what), supports foreign key constraints	JSON column on auth_user (simpler but less queryable)
superAdmin separated from stationManager	Station managers are students without technical expertise; conflating org leadership with infra access is a security and usability problem. Subsumes the in-progress admin role from fix/add-admin-role-to-wxyc-roles.	Keep stationManager as top role (status quo, proven problematic)
Per-service named roles in separate ServiceRoles	Clean conceptual separation: WXYCRoles is human roles, ServiceRoles is machine identities. Per-service names (e.g., request-o-matic) provide better audit traceability than a generic service role and enable future per-service permission scoping. UI code showing role dropdowns doesn't need to filter out machine identities.	Generic service in WXYCRoles (simpler lookup but conceptually muddled, requires Exclude type gymnastics), magic string check in middleware (no type safety)
better-auth is the single user store	First-party services already verify JWTs via JWKS. No second user store means no sync, no drift, no "single identity" contradiction.	Authentik as user store (two stores to manage), Authentik as sole store (massive migration)
Framework-agnostic core + adapters for auth-server	JWT verification logic is identical across Hono, Express, and Next.js; only the middleware integration differs. Core (verify.ts) depends only on jose. Adapters (hono.ts, express.ts, next.ts) are thin (~30 lines) and use peer dependencies. Avoids duplicating verification logic across frameworks.	Single monolithic middleware (forces framework choice on consumers), per-framework packages (duplicates core logic)
Separate auth-server entry point in wxyc-shared	Server-side verification depends on jose; client-side depends on better-auth/client. Bundling both together bloats both sides.	Extend existing auth-client (cross-environment dependency conflicts)
Python wxyc-auth as shared package	Two consumers today (request-o-matic, library-metadata-lookup), possibly more. Shared package with contract tests prevents divergence.	Copied module per service (no contract enforcement), git submodule (complex)
Webhook-driven sync service (no cron fallback)	Role/capability changes are infrequent events. Backend-Service already has the context (which user, which role) at the point of change — emitting a webhook is the natural trigger. Avoids polling overhead and the "up to 15 minute delay" of cron-based sync.	Cron-only (simpler but delayed), webhook + cron fallback (belt and suspenders, but cron adds complexity for minimal safety benefit)
User context forwarding via X-Forwarded-User	library-metadata-lookup doesn't need user-level access decisions. Passing identity as metadata keeps the service JWT as the sole auth mechanism per hop.	Forward user JWT to downstream services (downstream must verify two tokens)
id retained as deprecated alias for sub	Existing consumers (dj-site, archive, Backend-Service middleware) may reference payload.id. Dropping it is a breaking change. Deprecate now, remove in a future version.	Drop id immediately (breaking change across multiple repos)
stationManager is mutually exclusive	Reflects real-world structure (one station manager at a time). Atomic transfer prevents split-brain.	Allow multiple stationManagers (contradicts org structure)
Mobile app auth in scope	Mobile apps already call request-o-matic today. Without auth, those calls are indistinguishable from arbitrary internet traffic.	Defer mobile auth (leaves request-o-matic partially exposed)
Slack HMAC as third auth path	Slack webhooks use HMAC, not JWT. Treating it as a separate CallerIdentity variant keeps the type system honest.	Require Slack to authenticate via JWT (impossible — Slack controls the request format)
Meta Business Suite for Facebook/Instagram	Eliminates shared passwords entirely. Each person uses their own Facebook account with a granular role. The Meta Business API enables sync service automation.	Continue sharing passwords (insecure, no audit trail), social media management tool like Buffer/Hootsuite (adds cost and another third-party dependency)
Meta App Review as prerequisite	business_management permission requires one-time App Review. Acceptable trade-off: a few weeks of review unlocks permanent API automation. Manual fallback via the web UI if rejected.	Skip API automation, manage manually (defeats the purpose of centralized access management)
Bluesky app passwords via AT Protocol	Open protocol, no review process, per-user named passwords with server-side revocation. Best available approach given Bluesky has no multi-user account management.	Continue sharing the main password (insecure), use a social media management tool (adds cost), wait for Bluesky to add org/team features (no timeline)