Auth Architecture

Steel Notes — Authentication Architecture

**Multi-provider auth** supporting CLI (email/password) and frontend (Sign in with Apple, future OAuth providers), with account linking so one user can have multiple sign-in methods.

Design Principles

1. CLI is a first-class citizen. You can sign up, sign in, and use every feature from the terminal — no browser redirect required.

2. Provider-agnostic core. The server issues its own JWTs regardless of how the user authenticated. All protected endpoints see a user_id, never a provider-specific token.

3. One user, many providers. A user who signs up via CLI with email/password can later link their Apple ID from the iOS app (and vice versa). All providers attach to the same user record.

4. Passwords never leave the server. Argon2id hashing, no plaintext storage, no password in JWTs.

Database Schema

```sql

-- Core user identity (provider-independent)

CREATE TABLE users (

id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

email TEXT UNIQUE, -- nullable: Apple "hide my email" users may not share it

display_name TEXT,

created_at TIMESTAMPTZ NOT NULL DEFAULT now(),

vault_size BIGINT NOT NULL DEFAULT 0 -- total bytes in S3

);

-- One row per auth method a user has linked

CREATE TABLE auth_providers (

id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,

provider TEXT NOT NULL, -- 'email' | 'apple' | 'google' | 'github'

provider_id TEXT NOT NULL, -- email (for 'email'), sub claim (for OAuth)

password_hash TEXT, -- only for provider='email', Argon2id

created_at TIMESTAMPTZ NOT NULL DEFAULT now(),

UNIQUE(provider, provider_id)

);

CREATE INDEX idx_auth_providers_user ON auth_providers(user_id);

-- Refresh tokens (one per device session)

CREATE TABLE refresh_tokens (

id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,

token_hash TEXT NOT NULL UNIQUE, -- SHA-256 of the opaque token

device_id UUID REFERENCES devices(id) ON DELETE SET NULL,

expires_at TIMESTAMPTZ NOT NULL,

created_at TIMESTAMPTZ NOT NULL DEFAULT now()

);

-- Devices (unchanged from SYNC_ARCHITECTURE.md)

CREATE TABLE devices (

id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,

device_name TEXT NOT NULL,

platform TEXT NOT NULL, -- 'ios' | 'macos' | 'android' | 'cli'

push_token TEXT, -- APNs/FCM token (null for CLI)

last_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),

created_at TIMESTAMPTZ NOT NULL DEFAULT now()

);

```

Why separate auth_providers from users?

A user is a person with a vault. How they prove their identity is a separate concern. This lets us:

Auth Flows

1. CLI: Email/Password Registration

```

Client Server

```

2. CLI: Email/Password Login

```

Client Server

```

3. iOS/macOS: Sign in with Apple

```

Client Server

```

4. Token Refresh (all clients)

```

Client Server

```

Refresh token rotation: every use of a refresh token invalidates it and issues a new one. If a stolen token is used after the legitimate client has already refreshed, the stolen token is dead.

5. Account Linking (authenticated)

```

Client Server

```

This lets a CLI user later open the iOS app and link their Apple ID, or vice versa. Both sign-in methods now resolve to the same user and vault.

Unified Login Endpoint

POST /auth/login uses a grant_type discriminator:

```json

// Email/password

{

"grant_type": "email",

"email": "user@example.com",

"password": "...",

"device_name": "Ethan's Terminal"

}

// Sign in with Apple

{

"grant_type": "apple",

"identity_token": "<JWT from Apple>",

"device_name": "Ethan's iPhone"

}

// Google (future)

{

"grant_type": "google",

"identity_token": "<JWT from Google>",

"device_name": "Ethan's Pixel"

}

```

Response (all grant types):

```json

{

"access_token": "<JWT, 1hr TTL>",

"refresh_token": "<opaque, 30-day TTL>",

"user_id": "uuid",

"device_id": "uuid"

}

```

JWT Structure

```json

{

"sub": "<user_id UUID>",

"iat": 1711234567,

"exp": 1711238167,

"device_id": "<device_id UUID>"

}

```

Token Storage by Platform

CLI auth file format

```json

{

"api_url": "https://api.steelnotes.app",

"access_token": "eyJ...",

"refresh_token": "opaque-token-here",

"user_id": "uuid",

"device_id": "uuid"

}

```

The CLI reads this file on every command. If the access token is expired, it auto-refreshes before proceeding. If refresh fails, it prompts the user to steel auth login⧉ again.

CLI Commands

```bash

steel auth register # interactive: prompts for email + password

steel auth register --email e@x.com --password '...' # non-interactive

steel auth login # interactive: prompts for email + password

steel auth login --email e@x.com --password '...' # non-interactive

steel auth status # shows current user, email, linked providers, device

steel auth logout # deletes local tokens + calls server to revoke refresh token

```

Server Implementation (Rust / Axum)

Route structure

```

src/

routes/

auth.rs # POST /auth/register, /auth/login, /auth/refresh, /auth/link

auth/

password.rs # Argon2id hash + verify (argon2 crate)

apple.rs # Fetch JWKS, validate Apple identity tokens (jsonwebtoken crate)

jwt.rs # Sign + verify our JWTs

middleware.rs # Tower layer: extract Bearer token → inject UserId into request

```

Password hashing

```rust

// Using the argon2 crate with default Argon2id params

use argon2::{Argon2, PasswordHasher, PasswordVerifier};

```

Adding a new OAuth provider

To add a new provider (e.g., Google, GitHub):

1. Add a validation function in src/auth/{provider}.rs that takes an identity token and returns (provider_id, email)

2. Add the grant_type variant to the login endpoint match

3. No schema changes — auth_providers.provider is a text field, not an enum

Security Considerations