Skip to content

docs: OTP within secure enclaves — new security page + updated activity types#583

Open
turnkeyintern wants to merge 1 commit intotkhq:mainfrom
turnkeyintern:feat/otp-enclave-security-docs
Open

docs: OTP within secure enclaves — new security page + updated activity types#583
turnkeyintern wants to merge 1 commit intotkhq:mainfrom
turnkeyintern:feat/otp-enclave-security-docs

Conversation

@turnkeyintern
Copy link

@turnkeyintern turnkeyintern commented Mar 9, 2026

Summary

Adds documentation for the new enclave-based OTP architecture released in SDK v2026.2.8.

What changed

New file: security/otp-enclave.mdx
A dedicated security page covering:

  • Overview of the two OTP use cases (contact verification vs. login) and which enclave flow each uses
  • The key invariant: coordinator never sees plaintext OTP in INIT_OTP_V3
  • Full sequence flow for INIT_OTP_V3 (enclave-generated), INIT_OTP_AUTH_V3 (coordinator-generated, legacy), and VERIFY_OTP_V2
  • Token consumption (OTP_LOGIN_V2, signup)
  • Security controls: bundle signature verification, HPKE encryption of OTP attempt, constant-time comparison, brute-force protection, inflight limits, TTL
  • Client-side SDK changes table (publicKey required, verifyEnclaveSignature, HPKE replaces quorumKeyEncrypt, etc.)
  • Error codes

Updated: authentication/email.mdx

  • New callout card at the top of Core Mechanism section linking to the security page, with a summary of the v2026.2.8 client-side security improvements
  • Activity type references updated: INIT_OTPINIT_OTP_V3, VERIFY_OTPVERIFY_OTP_V2, OTP_LOGINOTP_LOGIN_V2
  • Breaking Change warning expanded to include VERIFY_OTP_V2 and OTP_LOGIN_V2 version progressions
  • Authorization section updated to show both enclave (V3) and legacy auth (V3) paths

Updated: authentication/sms.mdx

  • How It Works section updated to use V3/V2 activity types with brief enclave note
  • Sandbox section references updated
  • Note linking to the security page added

Updated: docs.json

  • security/otp-enclave added to the Security tab navigation (after enclave-secure-channels)

- Add security/otp-enclave.mdx: comprehensive doc covering the enclave-first
  OTP architecture (INIT_OTP_V3, VERIFY_OTP_V2, OTP_LOGIN_V2), including
  sequence flows, key invariants, client-side security changes from SDK v2026.2.8,
  and security controls (bundle sig verification, HPKE encryption, brute-force
  protection, inflight limits)

- Update authentication/email.mdx:
  - Add callout card linking to new security page with summary of SDK v2026.2.8
    client-side security improvements
  - Update activity type references: INIT_OTP → INIT_OTP_V3, VERIFY_OTP →
    VERIFY_OTP_V2, OTP_LOGIN → OTP_LOGIN_V2
  - Expand Breaking Change policy table with VERIFY_OTP_V2 and OTP_LOGIN_V2
    version progression
  - Update Authorization section to list both enclave (V3) and legacy auth (V3)
    paths with correct activity types

- Update authentication/sms.mdx:
  - Update How it Works activity types to V3/V2 equivalents
  - Add note linking to OTP enclave security page
  - Fix sandbox verify/login activity type references

- Update docs.json: add security/otp-enclave to Security tab navigation

References: tkhq/sdk#1220, tkhq/sdk#1221
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant