Auth Service

The IDToken Auth Service is the central server that orchestrates the entire X.1280 passwordless authentication protocol. It connects browsers, mobile apps, and relying parties through a trust chain anchored in government-issued VDS credentials.

Purpose

The Auth Service is the only component that communicates with every other part of the ecosystem:

Interaction	Channel	Description
Browser → Server	HTTPS + WebSocket	Receives auth requests, pushes real-time session status (OTP ready, approved, rejected)
Server → Mobile	FCM push notification	Delivers the OTP and session context to the user’s authenticator app
Mobile → Server	HTTPS	Receives the signed auth response from the mobile app
Server → Relying Party	JWT / SAML assertion	Returns verified identity claims to the requesting service
Server → Trust Infra	HTTPS	Fetches governance lists, trust service lists, and CA certificates for VDS verification

Core Responsibilities

Enrollment

The service registers a user’s VDS credential and device public key. When the mobile app calls POST /enroll, the server:

Verifies the VDS signature by walking the PKI trust chain
Extracts identity claims from the VDS payload
Stores the enrollment: tokenId → device public key + FCM token
Returns a confirmation to the app

No user database is created — the enrollment is simply a binding between the VDS token identifier and the device’s ECDSA public key.

Authentication

The core X.1280 mutual out-of-band flow:

Browser calls POST /auth/initiate with the user’s token identifier
Server generates a cryptographic OTP (HMAC-based, from master secret + session context)
Server pushes the OTP to the mobile app via FCM
Server sends the same OTP to the browser over WebSocket
User compares codes on both screens, approves on mobile with biometric verification
Mobile app signs the response and calls POST /auth/verify
Server validates the ECDSA signature against the enrolled public key
Server issues a JWT with scope-filtered claims and delivers it to the browser via WebSocket

OTP Generation

The one-time password is server-generated and deterministic — not TOTP or HOTP. It is derived from:

Input	Purpose
`OTP_SECRET_MASTER`	Server-side master secret (never leaves the server)
`sessionId`	Binds the OTP to a specific auth session
`tokenId`	Binds the OTP to a specific user enrollment
`timestamp`	Time-limits validity

The OTP is a 6-digit numeric code with a configurable TTL (default: 120 seconds).

VDS Verification

Before trusting any VDS credential, the server walks the full PKI chain:

Governance List → Scheme List → TSL → CA Certificate → VDS Signing Certificate

The verification checks:

ECDSA P-256 signature over the VDS payload (raw r|s format)
Certificate chain validity and expiry
Certificate UsageList includes the required usage type
VDS revocation status against the VDS Revocation List (VRL)

See Trust Architecture for the full verification process.

JWT Issuance

After successful authentication, the server issues a signed JWT (ES256) containing:

Standard claims: iss, sub (tokenId), aud (serviceId), exp, iat, jti
VDS identity claims filtered by the scopes the user granted
Derived claims computed from VDS data (e.g., age_over_18, age_over_21)

Relying parties verify tokens using the server’s public key, published at GET /jwks.

SAML 2.0 Identity Provider

The Auth Service can act as a SAML 2.0 IdP for enterprise integrations:

Publishes IdP metadata at GET /saml/metadata
Handles SSO via GET /saml/sso (HTTP-Redirect binding)
Signs SAML assertions with the server’s ECDSA key
Maps VDS claims to SAML attributes based on the SP’s attribute mapping configuration
Supports Single Logout (SLO)

See SAML 2.0 IdP for integration details.

Security Features

Feature	Implementation
Rate limiting	Per-IP and per-tokenId limits on auth and enrollment endpoints
Helmet headers	Strict CSP, HSTS, X-Frame-Options via `@fastify/helmet`
CORS	Configurable allowed origins
Immutable audit log	All security events logged to an append-only table (UPDATE/DELETE blocked at DB level)
Session expiry	Redis TTL enforces automatic session cleanup
Key rotation	Server signing keys can be rotated; JWKS endpoint publishes all active keys
Input validation	Zod schemas on every endpoint; malformed requests rejected before processing

Deployment

The Auth Service runs behind Cloudflare (TLS termination, DDoS protection, WebSocket proxying) and is containerized for production via Docker Compose.

Resource	Configuration
Server signing key	ECDSA P-256 PEM file (`SERVER_PRIVATE_KEY_PATH`)
PostgreSQL	Persistent volume, automated migrations on startup
Redis	Used for sessions and pub/sub; data is ephemeral (rebuilds from DB on restart)
FCM	Firebase service account credentials (`FCM_SERVICE_ACCOUNT_PATH`)
Health check	`GET /health` returns server status, DB connectivity, Redis connectivity, trust cache freshness

Architecture — System-wide overview and design principles
Authentication Flow — Protocol-level detail of the X.1280 phases
REST API — Complete endpoint reference
WebSocket API — Real-time browser notification protocol
Security Model — Cryptographic algorithms and threat model