Identity & Security Module Technical Specifications

How TOTP works in Aeion:

• Each user gets a unique, randomly generated secret (160 bits — the RFC 4226 minimum) at enrollment, shown as a QR code for any standard authenticator app (Google Authenticator, Authy, 1Password, etc.).
• Codes are 6 digits, refresh every 30 seconds, and follow the same SHA-1-based algorithm (RFC 4226 + RFC 6238) every major authenticator app already implements — no proprietary client needed.
• A ±1 time-step tolerance absorbs normal clock drift between the user's device and the server, so a slightly-off phone clock doesn't lock anyone out.
• 10 single-use backup codes are issued at enrollment for account recovery if the authenticator device is lost. Codes are hashed at rest and each one is consumed exactly once.
• The TOTP secret itself is encrypted at rest — even a database-level compromise doesn't expose enrolled secrets directly.

How the OAuth flow works:

1. Aeion generates a PKCE code-verifier and its S256 challenge, plus a single-use state token, and stores the pair server-side with a short expiry.
2. The user is redirected to the provider's real authorization page — Google, GitHub, Microsoft, Apple, Facebook, Twitter/X, LinkedIn, Discord, Slack, or any generic OIDC-compatible IdP.
3. On return, Aeion validates the state token, then exchanges the authorization code for tokens directly with the provider (server-to-server, PKCE-protected).
4. The returned refresh token is encrypted before it's stored, and re-encrypted automatically whenever it's rotated.

Supported providers ship with their real, correct authorization / token / userinfo endpoints out of the box — no manual endpoint configuration required for the 9 named providers. Generic OIDC accepts any spec-compliant identity provider's endpoints.

Every login attempt — successful, failed, or blocked — is recorded with a computed risk score based on signals like: first login ever, sign-in from a new IP or new country, a new/unrecognized device, unusual hours, a burst of recent failed attempts, or traffic from a known proxy or bot network.

Registration: The browser's native WebAuthn API (navigator.credentials.create) generates a hardware-bound key pair; Aeion verifies the attestation, confirms the challenge and origin match, and stores the public key plus a replay-detection counter. The private key never leaves the user's device or security key.

Sign-in: The browser's WebAuthn assertion API (navigator.credentials.get) produces a signed assertion using the hardware-bound key; Aeion verifies the signature against the stored public key and checks that the replay counter has advanced, so a captured assertion can't be reused.

Supports platform authenticators (Touch ID, Face ID, Windows Hello) and cross-platform security keys (YubiKey and other FIDO2-compliant hardware) side by side.

Key lifecycle: Keys are generated with a visible prefix and a secret portion; only a one-way hash of the full key is ever stored, and the plaintext key is shown to the user exactly once at creation.

On every API request, a key is:

1. Hashed and looked up (never compared in plaintext)
2. Checked for expiry
3. Checked against its IP allowlist, if one is configured
4. Checked against its per-key rate limit
5. Checked against its granted scopes for the requested action

Any failed check returns a clean, generic authorization failure — scopes, expiry, and rate limits are all enforced before a request ever reaches your data.