Trust · Identity stack
Identity, verified by hardware. Stamped to the chain.
Every Conceptual Health login flows through a layered identity stack: passkey-first when the account has one, hardware-backed where the silicon allows, NIST-aligned by role, and every successful or denied event written to a tamper-evident HMAC chain so the audit trail can never be quietly rewritten. This page documents what we built, the algorithms in use today, the migrations already in flight, and the receipts.
At a glance
What runs every time a Conceptual Health user signs in.
Five pillars. Each one is described in plain English below; every claim links to the code, the algorithm, and the chain entry that proves it shipped.
Pillar 1 — Factors
Passkey, authenticator, SMS.
Passkey (WebAuthn / FIDO2) is the strongest factor offered and the default whenever an account has one enrolled. The CH Authenticator app (TOTP + push) is the second tier. SMS remains as a recovery and rural-coverage fallback only — never the strongest factor on a privileged account.
Pillar 2 — Hardware
Secure Enclave & FIDO L2.
Apple Secure Enclave (T2 / Apple Silicon) is FIPS 140-2 / 140-3 validated and unlocks via Face ID or Touch ID. FIDO2 hardware tokens (e.g. YubiKey 5 FIPS series) are validated at FIPS 140-3 once Apple's transition certifications land. Both produce origin-bound, unphishable signatures.
Pillar 3 — Audit chain
Every event stamped.
Each MFA challenge, verify, enrollment, revocation, replay attempt, biometric refusal, and AiTM-relay signal writes a row to audit_logs under an HMAC chain with per-row crypto-agility — SHA3-512 forward as of sequence #24971 (2026-05-26), SHA-256 history preserved exactly as written. Verifier dispatches on each row’s hash_algo. See crypto agility. Each row carries the previous row's hash, so any rewrite breaks the chain irreversibly.
Pillar 4 — Phishing resistance
Origin + session binding.
WebAuthn ceremonies are bound to the verified browser origin by the standard itself — adversary-in-the-middle proxies cannot forge it. For non-passkey paths, the server issues a session-binding token at login and requires it on verify so a relayed approval on the user's phone cannot pay out to the attacker's tab.
Pillar 5 — Crypto agility
Every primitive is one column away from rotation.
Every load-bearing artifact carries an algo_version field — TOTP secrets, push challenges, audit chain rows. The verifier dispatches on it per-row. We can move a primitive forward (SHA-256 → SHA-3-512, P-256 → Ed25519) without re-enrolling users or re-stamping history.
Standing principle
Survive the people who built us.
No load-bearing primitive ships without a documented migration path. If a primitive needs to change ten years from now, the engineer running that migration finds a version field, a verifier dispatch, and a documented transition row pattern — not a one-week archaeology project.
Factor model
What we offer, what we require, where each one fits.
The factor a user sees is determined by the factors enrolled on their account AND what their role requires. The login dispatcher prefers the strongest factor available; the UI surfaces it as the default.
| Factor | Primitive | NIST AAL | Phishing-resistant | Status today |
|---|---|---|---|---|
| Passkey · WebAuthn / FIDO2 | P-256 ECDSA (default) · Ed25519 (transitioning) | AAL3 | Yes — origin-bound by spec | Shipped |
| Push · CH Authenticator (number-match) | APNs HTTP/2 + ES256 JWT delivery · 3-digit match | AAL2 (AAL3-eligible with biometric) | Mitigated — session-binding token | Code shipped, APNs creds pending |
| TOTP · CH Authenticator app | HMAC-SHA-256 RFC 6238 (default) · SHA-1 (legacy, per users.totp_algo) |
AAL2 | No — code is replayable in a 90s window | Shipped |
| SMS · Telnyx (in-house, no SDK) | 6-digit numeric, 5-min TTL, single-use, per-user rate-limited | AAL2 (NIST restricted) | No — SS7 / SIM swap risks | Shipped — recovery use only on role ≥ 4 |
| Email · in-house SMTP | 6-digit numeric, 5-min TTL, single-use | AAL1 | No | Shipped — last-resort fallback when SMS unavailable |
| Backup codes | 12-char Crockford base32 (~60 bits) · Argon2id at rest · single-use | AAL1 (recovery only) | No | Shipped — formatted XXXX-XXXX-XXXX |
Role-tier policy
Privileged accounts cannot stop at the SMS floor.
NIST 800-63B classifies SMS OTP as a restricted authenticator at AAL2 and disallows it at AAL3. We honour that boundary by role.
| Role | Examples | AAL floor | Allowed primary factors | SMS-as-primary |
|---|---|---|---|---|
| 0–2 | Patient, staff, provider | AAL1–AAL2 | Any enrolled | Allowed |
| 3–4 | Clinic admin, regional admin | AAL2 | TOTP / passkey / push | Fallback only |
| 5 | System admin (CEO, CMO, CFO, CIO, COO) | AAL3 | Passkey or push + biometric | Forbidden as primary |
Enforcement of the role-5 AAL3 floor at /auth/login/finalize is in flight — pending a one-pass user audit so we never lock a privileged user out of their own system before their passkey is enrolled. Once that lands, a role-5 sign-in attempt with only SMS available will refuse with a clear "your account requires a stronger factor — enroll a passkey or hardware token."
Crypto agility
Every primitive ships with a version field. Every verifier dispatches on it.
The pinned governance principle reads: "We want to future-proof our system to be updated long after I am gone." Concretely this means every load-bearing artifact records the algorithm that produced it, and every verifier reads that field before deciding which library to call. No more "everything is SHA-256 because it was SHA-256 when we shipped."
| Artifact | Version field | Today | Migration target |
|---|---|---|---|
| TOTP enrollment secret | authenticator_enrollments.algo_version |
sha256-v1 |
n/a — already on the strong primitive |
| Legacy TOTP (pre-enrollment-table users) | users.totp_algo |
sha1-rfc6238-v0 |
Re-enroll under sha256-v1 at next opportunity |
| Push challenge protocol | authentication_challenges.algo_version |
ch-push-v2 (3-digit match + session-binding) |
ch-push-v3 when FIDO L3 lands |
| Audit chain HMAC | audit_logs.hash_algo |
HMAC-SHA3-512 (forward) + HMAC-SHA-256 (history) | Per-row dispatch; chain bridges at sequence #24971 |
| Session-binding token | Token-internal algo claim |
sha256-v1 |
sha3-512-v1 — chain migration complete, token migration scheduled |
Audit chain coverage
Every authentication event lands on the chain.
Each row in audit_logs is HMAC-signed with the previous row's hash. The chain is verifiable by any caller via /api/v1/proof/verify-chain and surfaced on the Proof page. Authentication events that previously lived only in a SOC-analytics table now write to the chain as well.
| Event type | What it records | Triggers a SOC shadow? |
|---|---|---|
AUTH_MFA_CH_DEVICE_ENROLL_INITIATED | User started CH Authenticator enrollment | — |
AUTH_MFA_CH_DEVICE_ENROLL_VERIFIED | Enrollment activated with valid TOTP | — |
AUTH_MFA_CH_PUSH_CHALLENGE_ISSUED | Push delivered to user device | — |
AUTH_MFA_CH_PUSH_APPROVED | User approved the push (with biometric where required) | — |
AUTH_MFA_CH_PUSH_DENIED | User denied the push | Yes (medium) |
AUTH_MFA_CH_NUMBER_MISMATCH | 3-digit match failed — possible phishing | Yes (high) |
AUTH_MFA_CH_BIOMETRIC_REQUIRED | Push approved without biometric on a role-≥4 account | Yes (medium) |
AUTH_MFA_CH_BINDING_FAILURE | Session-binding token missing or mismatched — possible AiTM relay | Yes (high) |
AUTH_MFA_CH_TOTP_VERIFIED | TOTP verified, with the algo_version that matched | — |
AUTH_MFA_CH_TOTP_VERIFIED_LEGACY | Legacy SHA-1 TOTP verified — migration to sha256-v1 recommended | — |
AUTH_MFA_CH_TOTP_REPLAY | TOTP code reuse rejected by the atomic replay marker | Yes (medium) |
AUTH_MFA_CH_DEVICE_REVOKED | Device removed from the account | — |
AUTH_MFA_CH_DENY_REPORTED | User flagged a login attempt as unauthorized — IP auto-blocked 24h | Yes (critical) |
AUTH_PASSKEY_REGISTERED | New WebAuthn credential bound to the account | — |
AUTH_PASSKEY_FAILED | Passkey assertion verification failed | Yes (medium) |
AUTH_MFA_SMS_CHALLENGE_SENT | SMS code dispatched (with email fallback if SMS path is down) | — |
AUTH_LOGIN_SUCCESS | Full sign-in completed, including which factor verified | — |
Phishing resistance
Two layers, so a relay never pays out.
Origin binding (WebAuthn). The browser refuses to release a passkey assertion to any origin other than the one the credential was created against. Even a pixel-perfect adversary-in-the-middle proxy with a valid TLS certificate cannot harvest a passkey assertion — the browser will simply refuse to sign. This is the protocol-level defense; it does not depend on user vigilance.
Session binding (non-passkey paths). For push, SMS, and TOTP, the server issues a short-lived session_binding_token at the start of the MFA challenge. The browser presents that token on verify. A relay attacker who proxies the legitimate user's MFA approval does not have the legitimate browser's token, so the verify endpoint refuses to release a session — even though the phone approved.
Both layers chain-stamp the failure (AUTH_PASSKEY_FAILED, AUTH_MFA_CH_BINDING_FAILURE) so the SOC sees the attempt within seconds of it happening.
Architecture
Where each piece lives, in plain file paths.
Open source where the algorithms are open standards; internal where the routing is operationally sensitive. Auditors and security researchers can request a read-only walk-through of the closed pieces.
| Concern | File / module |
|---|---|
| Brand strings (single source of truth) | backend/app/branding.py |
| In-house TOTP (RFC 6238, self-tested) | backend/app/security/totp.py |
| Session-binding token issuance + verification | backend/app/security/mfa_session_binding.py |
| APNs / FCM HTTP/2 push delivery | backend/app/services/push_delivery.py |
| CH Authenticator service (enroll / push / TOTP / EPCS / dual-auth) | backend/app/services/ch_authenticator.py |
Authenticator HTTP routes (/auth/authenticator/*) | backend/app/routes/authenticator.py |
WebAuthn / passkey HTTP routes (/auth/passkey/*) | backend/app/routes/auth_passkey.py |
SMS + email MFA HTTP routes (/auth/mfa-*) | backend/app/routes/auth_mfa_otp.py |
| HMAC chain audit logger | backend/app/security/audit_logger.py |
| Crypto-agility schema migration | backend/migrations/2026_05_26_ch_authenticator_crypto_agility.sql |
| Corp Command Center sign-in (passkey-first picker) | /var/www/ch-v2/auth/corp-signin.html |
Receipts
Today's identity-stack milestone, chain-stamped.
The audit chain is append-only and HMAC-signed. Every row below is verifiable via the public /api/v1/proof/verify-chain endpoint. The sequence numbers will not change; the entry hashes will not change.
Stale duplicate CEO-tier account archived at
audit_logs #24814. Postgres credential rotated and all 13 backend services restarted clean at #24845. CH Authenticator deployed with all P0/P1 audit findings closed (commit bf5220ae) and chain-stamped at #24847. Crypto-agility schema migration applied to authenticator_enrollments, authentication_challenges, and users. Passkey support landed on the Command Center sign-in page (commit def4255) at #24904. Visual polish on the MFA picker (commit 7c3efc2) at #24930.
Adoption
For other healthcare networks that want the same posture.
Every piece of this stack uses an open standard. Nothing here is a Conceptual Health proprietary protocol — WebAuthn / FIDO2 is W3C, RFC 6238 TOTP is IETF, FIPS 140 is NIST, the audit chain is HMAC with a documented signature input format. Other healthcare networks can adopt the same architecture without a license fee, an SDK download, or a vendor lock-in.
What we publish in this repo for adopters: the migration SQL, the algorithm dispatch pattern, the chain coverage event-type list, the role-tier policy. What we keep internal: routing details, secret material, and SOC-integration paths that are specific to our infrastructure.
If you operate a healthcare network and want to compare notes, the contact below is the right starting point.
Standards alignment
What we claim and to whom.
| Standard | Scope | Status |
|---|---|---|
| W3C WebAuthn L3 | Passkey ceremonies, RP ID binding | Implemented |
| FIDO Alliance CTAP2 | Wire protocol with hardware authenticators | Implemented via browser |
| NIST 800-63B — AAL2 | Daily login for non-admin roles | Met |
| NIST 800-63B — AAL3 | Role-5 daily login + CHTR ceremonies | Architected; enforcement in flight |
| RFC 6238 — TOTP | HMAC-SHA-256 codes, 30-second period, 6 digits | Implemented (in-house) |
| RFC 4226 — HOTP | Underlying primitive for TOTP | Implemented (in-house) |
| FIPS 140-2 | Apple Secure Enclave (T2 / Apple Silicon) — covers current Macs | Inherited from Apple |
| FIPS 140-3 | Hardware tokens (e.g. YubiKey 5C NFC FIPS) when validation lands Q2 2026 | Procurement scheduled |
| HIPAA 45 CFR 164.312(b) | Audit controls — record and examine activity | Met — chain coverage |
| HIPAA 45 CFR 164.312(d) | Person or entity authentication | Met |
| DEA 21 CFR 1311 | EPCS two-factor with biometric | Implemented — number-match + biometric |
Roadmap · published before it ships
Where the stack is heading — from a person signing in to every device, name, and record.
Everything above is live in production today. Below is what we are building next: the layers that extend hardware-rooted identity beyond the login box to the whole sovereign healthcare network. Each item is a filed invention you can read in full — click the CH-IP number to open the claim on the public chain. We publish the intent before the code so the record stays honest about what is shipped versus what is planned.
| Layer | What it adds | Invention | Status |
|---|---|---|---|
| VPA · Virtual Private Authentication | The login path runs in its own isolated plane — a one-time, ratcheting chain key per sign-in, user vaults sealed with envelope encryption, identity held separate from transport and data. | CH-IP-049 | In development |
| Sovereign DNS · trust + resolution | Our own ground-up DNS resolves every address on the network — phone, messaging, email, and authentication — instead of leaning on outside resolvers. Split-horizon, DNSSEC / DANE, internal certificate authority. | CH-IP-051 | In development |
| Device admission + addressing | A device gets no routable address until it presents a hardware-attested identity recorded to the chain — so the address itself self-authenticates. Built for medical and implantable devices, with a fail-safe rule that the security layer can never compromise a life-sustaining device’s primary function. | CH-IP-052 | Filed · design |
| Document-level provenance | Authentication and authorization down to a single record — e.g. a prescription refill from doctor to patient — chain-stamped so nothing can be forged or modified, with validators on other systems of the network for redundancy. | CH-IP-050 | In flight |
| Tenant-tagged VPN · transport | The private healthcare transport every other layer rides on; each organization’s traffic is isolated and tagged end to end. | CH-IP-044 | In flight |
Status is current and honest: Shipped = in production today · In flight = partially built · In development = designed and being built · Filed · design = invention filed and design set, build pending. The full set of inventions is listed at /trust/patents/.
Out of scope · Contribute · Contact
Honest about what this page does not cover.
This page documents the identity stack — the layer that proves a person is who they say they are. It does not cover authorization (what they're allowed to do once authenticated), data-at-rest encryption (covered in the security whitepaper), the master-key custody protocol (covered at CHTR-P1), or the audit chain mechanics themselves (covered at Proof).
Researchers, auditors, regulators, and peer healthcare networks: write security@conceptualhealth.com. Trust bugs get the same priority as code bugs.