AUTH

AUTH on this page is presented at three time horizons simultaneously: the P0 · slice 2 stub that unblocks the rest of P0, the P3 full identity platform, and the Lumi's BRAIN tenant identity that turns BRAIN's universal protocol into a multi-tenant cloud product. Holding all three lenses lets engineers reading the page cold understand both what ships first and what the end-state looks like — without conflating them.

The reordered P0 build sequence (per research review §2.4)

Why this order: AI Gateway is the cost-of-everything-else gate (every CHAT @genie, every CUO Phase 2, every BRAIN semantic search depends on it). AUTH at P0 · slice 2 is a stub because for the first 6 months CyberSkill has 10 Members and one tenant — full WebAuthn + 22-role RBAC at P0 · slice 1 is over-engineering. Per reviewer: "AUTH at P0 · slice 2 can be magic-link + TOTP with a stub RBAC. WebAuthn passkeys for the Founder and a per-tenant authz server can land at P0 · exit without blocking any other module."

Per-module auth is one of the easiest mistakes to make and one of the hardest to unmake. The first version of any platform ships with one module that has "owns its own login", the second module copies the pattern, the third inherits a subtle bug, and within a year there are four MFA implementations, three session models, and zero coherent answer to "who can do what". CyberOS treats this as a P0 design constraint: a single authentication service, a single authorisation predicate, a single audit trail. Every module that wants to know "can this actor do X to that resource?" asks AUTH the same way.

The bet is the same bet BRAIN makes about audit: pay the cost once at the infrastructure layer, and every module inherits the property for free. Without AUTH as a shared plane, every module re-implements login, every module ships its own MFA bug, and "who has access to what" is a vibes question. With AUTH as a shared plane, the answer is a row in auth.decision and a JWT claim — the regulator can read it, the auditor can verify it, the engineer can replay it.

A structured decomposition of AUTH's scope. Every cell traces back to + §9.6 + §11.2.3.

Per the reviewer's reorder, AUTH ships in two distinct shapes separated by 10 months. The P0 · slice 2 stub is mergeable in one week; it unblocks every other P0 module by giving them an actor identity. The P3 full AUTH ships over slices 2–5 across P0 · exit through P3 · exit and is what the SOC 2 Type II auditor evaluates. Confusing the two is the most common bug in module-page reading; this table is the disambiguator.

Migration discipline

The transition from P0 · slice 2 stub to P3 full is not a rewrite — it is a layered addition. Each slice adds capability without changing the P0 · slice 2 contract. Pre-existing tenants/subjects/JWT claims continue to validate at every slice boundary. The conformance test suite runs both old and new code paths through P3 · exit; once Type I evidence is collected, the stub-only paths are retired.

What the P0 · slice 2 stub does not compromise on: (a) agent-equal evaluation (the agent-persona role is in the 5-role stub catalogue), (b) audit-chain emission (every decision is chain-linked from day one), (c) RLS isolation (the database scope is set correctly from slice 1, even if WebAuthn isn't there). What it does defer: signing key in KMS, OIDC SSO, full 22-role catalogue, JWKS rotation, passkey enrolment, impossible-travel challenge, HIBP integration.

The closed RBAC catalogue is the same shape per the original AUTH spec, refactored slightly so the P0 · slice 2 stub catalogue is a strict subset. Adding a new role to the catalogue is an ADR — not a code change. The 5 stub roles are the first 5; the remaining 17 land across P0→P3.

Adding a new role requires an ADR (Architecture Decision Record) with: business rationale, scope-creep risk assessment, audit-trail implications, and explicit DPO + CSEC review. Removing a role requires a deprecation window of 90 days with shadow-monitoring of the role's actual usage. The 22-role boundary is a design assertion — ABAC complexity is deferred indefinitely.

Per BRAIN_AUTOSYNC_DESIGN.md §6, Lumi's BRAIN is the cloud-hosted org-tenant instance of the BRAIN protocol. It depends on AUTH for two non-negotiable properties: (1) a tenant-scoped JWT issued by AUTH that identifies which tenant a sync request belongs to, (2) a subject-scoped JWT with the agent-persona claim that identifies which user within that tenant is reading or writing. Without both, multi-tenant isolation is impossible.

The JWT claim shape

{
  "iss": "https://auth.cyberos.com",
  "sub": "user:stephen@cyberskill.world",
  "aud": ["brain.cyberos.com"],
  "iat": 1778765128,
  "exp": 1778766028,                          // 15 min
  "jti": "",
  // === Tenant identity ===
  "tenant_id": "org:cyberskill",
  "tenant_residency": "sg-1",                 // sg-1 | vn-hanoi-1 | eu-fra-1
  "tenant_plan": "pro",                       // free | pro | enterprise
  // === Subject scope ===
  "role": ["tenant-member", "cpo"],
  "rbac_grants": ["feature-request-author:execute", "kb:read", "brain:read:personal:*"],
  // === Persona stamp (when agent-issued) ===
  "agent_persona": null,                      // or "cuo-cpo@0.4.1" for agent JWTs
  "agent_persona_version": null,
  // === Scope Contract Grants (slice 4+) ===
  "scope_grants": [
    {"resource": "lumi:org:cyberskill:shareable", "rights": ["read"]},
    {"resource": "lumi:org:cyberskill:fr-decisions", "rights": ["read", "write"]}
  ]
}

How Lumi's BRAIN enforces the JWT

What this contract requires from AUTH

• tenant_id is non-removable. Every JWT — human, agent, service account — carries a tenant_id. Tenant-less JWTs are rejected at issuance.
• JWKS endpoint is reachable from Lumi's BRAIN cloud region. ~1 RTT cost on cold cache; cached for the JWT's lifetime.
• Refresh-token reuse detection is enforced at AUTH. A reused refresh token revokes the whole session (per AUTH RFC §3 slice 2). Lumi's BRAIN's pull queue must handle 401 by triggering re-auth, not by silently failing.
• Agent-persona claims survive the agent-equal property. When the CUO router issues a JWT on a user's behalf, the agent_persona claim is set; Lumi's BRAIN's read scope is then determined by the intersection of user RBAC + persona Scope Contract Grant.
• Tenant residency pinning flows through. A vn-hanoi-1-pinned tenant's JWT is rejected at the sg-1 Lumi's BRAIN shard. Cross-shard sync requires a special cross-shard-migrate claim (CDO + CLO approval).

The services/auth/RFC.md §6 lists 5 open decisions that block slice 1. The proposed defaults below were drafted from the research review §2 + the BRAIN_AUTOSYNC_DESIGN.md Stage 3 dependencies. They land as ADRs once Stephen signs off.

Once Stephen signs off, each default becomes a numbered ADR (services/auth/decisions/DEC-AUTH-001..005.md) — same as the existing DEC-058 pattern. Slice 1 unblocks immediately after Q1 + Q3 are signed (workspace + bootstrap are mechanical); Q2 + Q4 + Q5 can land later without code rewrites.

AUTH is one Rust service with five surfaces (OIDC issuer, OAuth 2.1 token endpoint, WebAuthn endpoints, RBAC gRPC API, admin REST), three stores (Postgres for identity / role / session, Redis for hot-path session and RBAC cache, KMS for signing-key wrap), and a single audit sink (BRAIN). The diagram below shows the canonical request flow for a cross-module call.

Internal components

Identity, role, and session live in PostgreSQL with row-level security keyed by tenant_id. The schema is normalised but optimised for hot-path RBAC: the subject_role and role_permission tables are de-normalised into a materialised subject_effective_permission view that Redis caches with a 15-minute TTL.

RBAC role catalogue ( — closed)

Four surfaces: an OIDC + OAuth 2.1 HTTPS edge for browsers and agents, a gRPC API for internal RBAC predicate evaluation, an MCP tool catalogue (the security-sensitive subset), and a small admin CLI surface.

GraphQL subgraph (federated)

AUTH publishes a thin federated subgraph for cross-module identity queries. Sensitive writes (role grant, session revoke) remain on the admin REST API.

extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@external", "@shareable", "@requiresScopes"])

type Subject @key(fields: "id") {
 id: ID!
 tenantId: ID!
 kind: SubjectKind!
 email: String
 displayName: String!
 status: SubjectStatus!
 roles: [Role!]! @requiresScopes(scopes: [["auth.read"]])
 effectivePermissions: [String!]! @requiresScopes(scopes: [["auth.read"]])
 lastLoginAt: DateTime
 createdAt: DateTime!
}

type Role @key(fields: "code tenantId") {
 code: String!
 tenantId: ID!
 displayName: String!
 scopeLevel: ScopeLevel!
}

type Session @key(fields: "id") @requiresScopes(scopes: [["auth.session_read"]]) {
 id: ID!
 subjectId: ID!
 issuedAt: DateTime!
 expiresAt: DateTime!
 status: SessionStatus!
 device: Device
}

type Device {
 id: ID!
 label: String!
 trusted: Boolean!
 lastSeenAt: DateTime!
}

type AuthDecision @key(fields: "id") @requiresScopes(scopes: [["auth.audit_read"]]) {
 id: ID!
 subjectId: ID!
 action: String!
 resource: String!
 decision: Decision!
 reasonCode: String!
 ts: DateTime!
 brainChain: String!
}

enum SubjectKind { HUMAN AGENT SERVICE API_KEY }
enum SubjectStatus { ACTIVE LOCKED DISABLED }
enum ScopeLevel { PLATFORM TENANT PROJECT }
enum SessionStatus { ACTIVE REVOKED EXPIRED }
enum Decision { ALLOW DENY CHALLENGE }

type Query {
 me: Subject!
 subject(id: ID!): Subject
 decisions(subjectId: ID, since: DateTime, limit: Int = 50): [AuthDecision!]!
 @requiresScopes(scopes: [["auth.audit_read"]])
}

type Mutation {
 revokeSession(id: ID!): Boolean!
 @requiresScopes(scopes: [["auth.session_revoke"]])
 grantRole(subjectId: ID!, roleCode: String!, expiresAt: DateTime): Boolean!
 @requiresScopes(scopes: [["auth.role_grant"]])
 rotateApiKey(id: ID!): ApiKeyRotation!
 @requiresScopes(scopes: [["auth.api_key_rotate"]])
}

REST + OAuth surface (planned)

gRPC RBAC API (internal)

syntax = "proto3";
package cyberos.auth.v1;

service RBAC {
 / Hot-path predicate. Sub-millisecond Redis cache.
 rpc Check(CheckRequest) returns (CheckResponse);/ Batch variant for module gateways.
 rpc CheckBatch(CheckBatchRequest) returns (CheckBatchResponse);/ Resolve effective permissions for a subject.
 rpc EffectivePermissions(SubjectRef) returns (PermissionSet);
}

message CheckRequest {
 string subject_jwt = 1;/ verified upstream
 string action = 2;/ "rew.write_run"
 string resource = 3;/ "rew/run/2026-05"
 map<string, string> attrs = 4;/ optional ABAC hints (P3+)
}

message CheckResponse {
 bool allow = 1;
 string reason_code = 2;/ "policy.role.cfo_required" | "ok"
 string brain_chain = 3;/ audit row chain hash
}

MCP tool catalogue

Flow 1 — Human login with WebAuthn passkey

Flow 2 — TOTP MFA login (member tier)

Flow 3 — Agent authentication (CUO persona-stamped token)

Flow 4 — RBAC predicate on cross-module call

Flow 5 — Service-account token-exchange (module-to-module)

A session traverses six states from issuance to expiry, with three terminal states (revoked, expired, replaced). Every transition writes an auth.decision row to BRAIN.

Token lifetime budget

security NFRs all flow through AUTH. Cross-referenced at nfr-catalog.html#auth.

AUTH depends on three primitives (BRAIN for audit, OBS for telemetry, KMS for the signing key) and is depended on by every module that does anything cross-tenant or cross-module — which is to say, all of them.

AUTH is the regulator's first stop. The audit chain it produces — co-owned with BRAIN — answers every identity, access, and breach-notification question across PDPL, GDPR, ISO 27001, and SOC 2.

AUTH-specific risks tracked in the risk register. AUTH carries the highest single-module risk weight; one bug here is platform-wide.

AUTH health rolls up into 9 KPIs covering authentication success, authorisation correctness, performance, and compliance posture.

AUTH is owned by the CSO seat. Today (CSO vacant), the CEO is interim accountable with the CTO as engineering owner.

A single admin CLI cyberos-auth for tenant operators. Every destructive command writes a chained audit row before exit.

1. Create a tenant

$ cyberos-auth tenant create \
 --slug stephen-personal \
 --display "Stephen Personal" \
 --country VN \
 --residency vn-hanoi-1

[tenant created]
 id: 01HZJ8R4M2K7QXP3F9D8YN7B2T
 slug: stephen-personal
 residency: vn-hanoi-1
 audit: brain seq=14823 chain=9f3e2a1b…8d4c

2. Enrol a passkey (interactive)

$ cyberos-auth webauthn enrol --subject stephen@cyberskill.com

→ open https://auth.cyberos.com/webauthn/enrol?token=eyJhbGc… on the device
✓ credential registered
 credential_id: AaJ9K… (TouchID, MacBook Pro 16, 2023)
 aaguid: adce0002-35bc-c60a-648b-0b25f1f05503

3. Grant a role

$ cyberos-auth role grant \
 --subject acme-cfo@acme.com \
 --role cfo \
 --expires 2027-12-31T00:00:00Z

[role granted] subject=acme-cfo@acme.com role=cfo expires=2027-12-31
[audit] brain seq=14831 chain=b8d4…e3f7

4. Revoke a session

$ cyberos-auth session revoke --id 01HZJ8…JTC

[revoke] session 01HZJ8…JTC → status=revoked
[propagated] Redis cache invalidated; Apollo Router will reject within 5 s
[audit] brain seq=14832 chain=c9e5…f4a8

5. Read auth decisions for a subject (DSAR-style)

$ cyberos-auth decisions list --subject stephen@cyberskill.com --since 7d --format jsonl | head -3
{"ts":"2026-05-13T09:21:08Z","action":"login","decision":"allow","reason":"webauthn.aal3","device":"MacBook Pro 16"}
{"ts":"2026-05-13T09:21:09Z","action":"brain.put","decision":"allow","reason":"role.founder","resource":"memories/decisions/holdco-flip.md"}
{"ts":"2026-05-13T11:04:32Z","action":"rew.write_run","decision":"deny","reason":"policy.cfo_co_sign_required","resource":"rew/run/2026-05"}

6. Rotate the JWT signing key

$ cyberos-auth keys rotate --reason "quarterly-scheduled"

[rotate] new key id: 2026-q2-sig
[kms] old key id 2026-q1-sig retained for verification (30 d)
[jwks] /.well-known/jwks.json updated; downstream propagation: ≤ 60 s
[audit] brain seq=14841 chain=d1f3…a8c7

7. Export DSAR bundle

$ cyberos-auth dsar-export --subject acme-contact@acme.com --output dsar.zip

[dsar] subject: acme-contact@acme.com
[dsar] identity: 1 row
[dsar] decisions: 4,217 rows (28 d)
[dsar] sessions: 12 rows
[dsar] devices: 3 rows
[dsar] webauthn: 0 credentials (none registered)
[dsar] written: dsar.zip (412 KB)

AUTH issues 47 distinct agent-persona JWT shapes (one per active CUO persona, plus the human roles in the 22-role RBAC catalogue). The personas below govern AUTH's policy itself, while every other persona consumes the JWTs AUTH issues.

Every other CUO persona (42 of 47) consumes AUTH JWTs to read scope-limited BRAIN data per the Scope Contract Grant mechanism. See § RBAC catalogue above.