Authentication & Device Security

This document provides a security-focused overview of the authentication architecture used by the Chronolith macOS app and backend services. It is intended to explain the technical flow and the defensive controls in place without disclosing implementation details that could be used to target the system.

It covers:

• Authentication methods (password, passkey, TOTP)
• Device binding and device allowlisting
• Proof-of-possession (PoP) protections for requests and sensitive actions
• Secure local storage and recovery enrollment concepts
• Validation, rate limiting, replay protection, and operational guardrails

---

Design Goals

• Strong account security by default (multi-factor readiness, device controls).
• Minimize token theft impact through device binding and request PoP.
• Make enrollment explicit and auditable (new device enrollment requires additional proof).
• Reduce sensitive material exposure (secure storage on device; server stores hashed/derived representations where practical).
• Layered controls: rate limits, step-up requirements, replay prevention, and scoped one-time proofs.

---

Core Security Building Blocks

Server-Side Cryptography (High Level)

• Password hashing uses a modern memory-hard KDF (Argon2 family) via a well-maintained library, with parameters selected to meet contemporary security guidance and adjusted over time as needed.
• TOTP is standards-based (RFC 6238) and verified with a small tolerance window to handle clock drift.
• Public-key signatures (Ed25519) are used for identity/device proofs and request PoP verification.
• Scoped one-time tokens used for challenges and “proof” steps are derived/verified using authenticated server-side mechanisms (e.g., HMAC over canonical payloads) and include strict purpose binding and expiry.

Public note: Exact parameter values, canonical string formats, and internal validation thresholds are intentionally omitted.

---

Token Model and Session Handling

• The system uses short-lived access tokens and longer-lived refresh tokens.
• Tokens are opaque random values; the server stores only hashed/derived representations to reduce risk in case of database exposure.
• Refresh token rotation may be enabled. When rotation is active, the server detects replay and takes protective action (e.g., revoking the session and/or related sessions depending on policy).

---

Device Binding and Device Allowlisting

Chronolith treats devices as first-class security entities:

• A device is represented by a device credential/certificate that ties together:

  • an account identity key (public)
  • a device key (public)
  • issuance metadata
  • a signature proving the relationship

• Once validated, the server maintains a device allowlist for the account.

• Device-bound sessions are linked to an allowlisted device, and high-trust endpoints require device binding.

This supports:

• Preventing silent logins from unknown devices
• Detecting and blocking token use from unrecognized devices
• Clear “revoke device” actions that invalidate device-bound sessions

---

Proof-of-Possession (PoP) for Requests

To reduce the value of stolen bearer tokens, Chronolith can require request-level PoP:

• Clients attach a signed proof to requests.
• Proof binds the request to:
  • the HTTP method and path
  • a hash of the request body
  • a timestamp and nonce (for freshness and replay prevention)
  • a token-binding component so the proof is not reusable across tokens

Server-side enforcement includes:

• Timestamp skew limits
• Nonce format and entropy checks
• Signature verification
• Replay protection (nonces tracked for a limited time window)

Public note: Header names, canonicalization details, nonce persistence strategy, and exact skew/TTL values are intentionally not disclosed.

---

macOS App Security Architecture

Local Key Material

The macOS app uses OS-provided cryptographic primitives and secure storage:

• Identity and device keys use modern public-key cryptography.
• Content encryption uses an AEAD construction appropriate for local object encryption.
• Recovery data is encrypted using a passphrase-based mechanism that applies a strong KDF and authenticated encryption.

The app avoids exposing raw key material beyond what is required for cryptographic operations.

---

Secure Storage (Keychain)

Sensitive material is stored in the macOS Keychain using restrictive accessibility settings appropriate for high-security credentials.

Stored items may include:

• Identity and device key material (or seeds used to derive them)
• Content encryption material
• Session tokens (access/refresh)
• Device credential artifacts necessary for server validation

---

Recovery Bundle Concept (Public-Safe Description)

Chronolith supports a recovery bundle concept to enable controlled device enrollment and account recovery scenarios.

Key properties:

• Recovery bundles are encrypted and authenticated, and include versioned metadata for forward compatibility.
• Decryption requires a user-held secret (e.g., passphrase).
• Recovery data is designed so that importing it enables identity continuity while still requiring explicit device enrollment with the server.

---

Authentication Methods and Technical Flows

The following sections describe the sequence of operations and security controls for each major flow. Endpoint names and field-level details are generalized.

---

1) Email Verification (Signup Step)

Client

1. User submits an email address.
2. Client requests an email verification code.

Server

1. Applies rate limits and abuse controls (by IP and identifier).
2. Generates a short verification code and stores only a protected representation.
3. Enforces resend cooldowns and attempt limits.
4. Delivers the code via the configured email provider.

Client

1. User submits the code.
2. Client receives a short-lived, scoped verification artifact used only to complete signup.

Security characteristics:

• Anti-enumeration behavior is configurable.
• Verification artifacts are short-lived and purpose-bound.

---

2) Signup (First Device) — Email + Password + Device/Identity Proof

Client

1. Ensures identity and device credentials exist locally.
2. Produces a device credential that proves linkage to the account identity key.
3. Submits signup information (email, password, verification artifact) plus identity/device proofs.

Server

1. Validates the verification artifact (one-time, scoped, unexpired).
2. Hashes the password using a memory-hard scheme.
3. Verifies identity/device proofs and checks issuance freshness rules.
4. Creates the user and allowlists the initial device.
5. Issues a device-bound session. If multi-factor is required/expected, the session may start in a restricted “setup” state.

Security characteristics:

• Prevents “drive-by” signup without proving control of both email and device credentials.
• Establishes the first device as an allowlisted anchor.

---

3) TOTP Setup / Enable / Disable

Setup

• Client requests TOTP enrollment material (e.g., secret and URI) over an authenticated, device-bound channel.

Enable

• Client submits a current TOTP code to confirm configuration.
• Server verifies and upgrades the session to a higher trust level.

Disable

• Requires step-up verification (e.g., password + TOTP) to reduce risk of account takeover disabling MFA.

Security characteristics:

• MFA changes require additional proof and are auditable.
• Enable/disable operations are protected behind higher-trust checks.

---

4) Password Login (Device-Aware)

Client

1. Submits email and password.
2. Provides device identification information required to enforce allowlisting.
3. If MFA is enabled, provides the second factor.

Server

1. Rate limits login attempts and applies abuse controls.
2. Verifies password hash.
3. Verifies MFA when enabled.
4. Enforces device allowlisting:
   • Known active device: proceed.
   • Unknown device: blocked unless account policy allows a controlled bootstrap path.
5. Issues device-bound session tokens.

Security characteristics:

• Strong protection against credential stuffing and brute force via layered controls.
• Device allowlisting prevents silent access from new machines.

---

5) Passkey Login (WebAuthn)

Client

1. Initiates a passkey login and receives a challenge.
2. Uses platform passkey APIs to produce an assertion.
3. Submits the assertion plus required device identification information.

Server

1. Validates WebAuthn assertion properties (RP/origin, flags, signature).
2. Applies replay and integrity checks appropriate to WebAuthn.
3. Enforces device allowlisting (or a controlled bootstrap rule, depending on account state/policy).
4. Issues session tokens.

Security characteristics:

• Phishing-resistant authentication via WebAuthn.
• Additional device checks prevent passkey-only access from an untrusted device unless explicitly permitted by policy.

---

6) Refresh Token Flow (With PoP)

Client

1. Calls refresh using the refresh token.
2. Attaches PoP data bound to the refresh operation.

Server

1. Rate limits and performs anomaly checks.
2. Verifies refresh token validity using stored protected representations.
3. Enforces device binding and allowlisting.
4. Validates PoP proof and replay protections.
5. Optionally rotates refresh tokens and detects replay.

Security characteristics:

• Refresh is hardened because it is the gateway to long-lived access.
• Rotation and replay detection limit persistence of stolen tokens.

---

7) Logout and Logout-All

• Logout revokes the current session.
• Logout-all revokes all active sessions for the account. Device allowlisting may remain intact (policy-dependent) so users can revoke sessions without losing device trust state.

Security characteristics:

• Rapid containment after suspected compromise.

---

8) Password Change

Client

• Submits current password and new password; may request revocation of other sessions.

Server

• Verifies current password, updates stored hash, and revokes sessions according to policy.
• May send a security notification email as a best-effort signal to the user.

Security characteristics:

• Step-up required.
• Optional session revocation reduces attacker dwell time.

---

9) Passkey Registration and Revocation

Register

1. Client requests a registration challenge.
2. Passkey is created via platform APIs.
3. Client submits attestation/registration results.
4. Server validates and stores the public key and required metadata.

Revoke

• Client requests revocation of a specific passkey; server marks it revoked and updates active status.

Security characteristics:

• Registration is origin-validated and scoped.
• Revocation is immediate and supports incident response.

---

Controlled Device Enrollment (Recovery-Assisted)

Chronolith supports intentional enrollment of a new device with additional proof, typically when an account already has MFA enabled.

Enrollment Principles

• Enrollment uses a limited-scope session (reduced privileges) to bootstrap additional verification.
• The app may temporarily hold sensitive recovered materials in memory only during enrollment, and commits them to secure storage only after server confirmation.
• Enrollment requires proof that the enrolling device is acting on behalf of the account identity.

Recovery-Assisted Enrollment Flow (Generalized)

Client

1. Authenticates into a limited-scope session using a strong method (e.g., MFA-backed login or passkey-backed limited login).
2. Decrypts and validates the recovery bundle locally (staged in memory).
3. Requests an identity challenge from the server for a specific enrollment purpose.
4. Signs/answers the challenge using the recovered identity material.
5. Generates a new device credential and submits it alongside the identity proof.
6. On success, commits enrollment state to Keychain; on failure, wipes staged material.

Server

1. Issues a limited-scope session and challenge tokens bound to explicit purposes.
2. Validates identity proof, freshness, and one-time semantics.
3. Validates device credential integrity and links it to the account.
4. Allowlists the new device and revokes the limited session.
5. Issues a normal device-bound session.

Security characteristics:

• New device enrollment requires more than “just a password.”
• Proof tokens are scoped, expiring, and non-reusable.
• Staged secrets are not persisted locally until the server approves enrollment.

---

Operational Guardrails and Defensive Controls

Chronolith uses multiple layers of defense. Highlights include:

• Rate limiting for email verification, login attempts, refresh operations, and other sensitive endpoints.
• Replay resistance via nonces and bounded time windows for PoP.
• Strict input validation and canonical encoding/verification for signed objects.
• Scoped one-time proofs for identity confirmation and enrollment actions.
• Device allowlisting and device-bound sessions for higher-trust operations.
• Step-up requirements for high-impact actions (MFA disable, credential changes, enrollment).
• Revocation pathways:
  • revoke session
  • revoke all sessions
  • revoke device (also invalidates device-bound sessions)
  • revoke passkey

---

What This Document Intentionally Does Not Disclose

To keep this safe for public distribution, the following details are omitted or generalized:

• Exact endpoint paths, internal header names, and canonical string formats
• Precise TTLs, skew allowances, retry thresholds, and replay window sizes
• Internal storage keys, Keychain identifiers, and service naming
• Detailed error behaviors that could enable enumeration or tuning attacks
• Implementation quirks, parsing edge cases, or normalization specifics

---

Summary

Chronolith authentication combines:

• Standards-based factors (password hashing, TOTP, WebAuthn passkeys)
• Device trust (allowlisting + device-bound sessions)
• Request integrity (PoP + replay resistance)
• Controlled enrollment (limited sessions + scoped identity proofs)
• Secure local storage (Keychain + staged memory handling during enrollment)

This architecture is designed to remain resilient even if a single layer is degraded (e.g., token exposure), by requiring additional proof (device binding, PoP, step-up checks) before meaningful account actions are allowed.