AUTH

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 PRD §8.6 + §9.6 + §11.2.3.

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 (PRD §8.6.1 — 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

PRD §11.2.3 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)