# auth.stormtrust.net

`auth.stormtrust.net` is the first-party StormTrust identity service. It proves who a user is. The gateway decides what that user may enter.

## User journey

```txt
Open Dashboard
      ↓
Sign in or create an account
      ↓
Verify email
      ↓
Return to the original StormTrust page
      ↓
Gateway applies the user's role and route policy
```

The interface presents one primary task at a time, preserves the requested destination through verification, and uses the same StormTrust brand system as the public applications. Email and password are available. External identity providers remain disabled until StormTrust configures their credentials and callbacks.

## Trust boundaries

| Concern                                                                                      | Owner                                |
| -------------------------------------------------------------------------------------------- | ------------------------------------ |
| Registration, credentials, verified email, sessions, recovery, and two-factor authentication | Auth                                 |
| PKCE authorization codes and first-party identity claims                                     | Auth                                 |
| Baseline member provisioning, platform roles, and permissions                                | Gateway                              |
| Tenant, record, and action authorization                                                     | Destination service                  |
| Operator entry to monitor.auth.stormtrust.net                                                | Cloudflare Access and the monitor UI |

Auth does not store StormTrust product roles. A verified user receives the gateway's baseline `member` role once. Removing that role does not cause a later sign-in to recreate it. Operator and administrator assignments require an explicit trusted change.

## Local sign-in

Use [Run the local application stack](/stormtrust/engineering/operations/local-development/) for gateway sign-in with preview email. Use [Test email delivery locally](/stormtrust/engineering/operations/local-email/) for the optional real-inbox test and its remote side effects.

## Runtime

The application separates public rendering, security state, providers, mail, and operations into bounded Workers:

| Worker                     | Entry                           | Responsibility                                                   |
| -------------------------- | ------------------------------- | ---------------------------------------------------------------- |
| stormtrust-auth-web        | Gateway service binding         | Browser routes, views, static assets, and cookies                |
| stormtrust-auth            | Private RPC                     | Identity, sessions, authorization codes, D1, and Durable Objects |
| stormtrust-auth-socialite  | Private RPC                     | GitHub redirects, callbacks, and account linking                 |
| stormtrust-auth-mail       | Queue consumers and private RPC | Transactional mail and delivery lifecycle                        |
| stormtrust-auth-tail       | Tail consumer                   | Runtime telemetry                                                |
| stormtrust-auth-monitor    | Scheduled and private RPC       | Health snapshots and alert state                                 |
| stormtrust-auth-monitor-ui | Gateway and Cloudflare Access   | Private operator interface                                       |

The stack uses D1, Durable Objects, Queues, Email Service, Turnstile, Analytics Engine, and Workers Static Assets. It does not need KV or R2\. Authentication state requires strongly consistent reads or coordinated state, and the application has no large object-storage workload.

## First-party handoff

The website client uses authorization code with Proof Key for Code Exchange (PKCE). The exact production contract is:

| Property     | Value                                |
| ------------ | ------------------------------------ |
| Issuer       | https://auth.stormtrust.net          |
| Client ID    | stormtrust-web                       |
| Audience     | stormtrust.net                       |
| Redirect URI | https://stormtrust.net/auth/callback |

The gateway creates a short-lived transaction, redirects the browser to auth, exchanges the one-time code through a private service binding, and stores only an opaque host-only session cookie. Auth refuses to issue a code for an unverified email.

## Provisioned resources

Terraform owns the Zero Trust organization, seven Worker identities, the auth D1 database, three mail queues, and the Cloudflare Access application and email-domain policy for the monitor UI. The retained import block records the organization adoption. Wrangler owns Worker code, bindings, routes, static assets, migrations, schedules, and observability.

Turnstile is bootstrapped by the trusted deployment outside Terraform because Cloudflare generates its secret and secret values must not enter Terraform state. The deployment finds or creates one managed widget named `stormtrust-auth`, restricts it to ` auth.stormtrust.net`, and fetches its detail through the Cloudflare API. The site key enters generated Wrangler configuration; the secret passes through a runner-temporary ` 0600` file into the core Worker and is never stored in GitHub, Terraform state, or an artifact.

The trusted workflow discovers generated resource identifiers after Terraform applies. It then:

1. Reconciles and validates the named Turnstile widget.
2. Stores required secrets and any configured optional secrets on only the Workers that consume them.
3. Applies D1 migrations.
4. Deploys Tail, core, Socialite, mail, monitor, web, and monitor UI in dependency order.
5. Creates or updates the Email Sending lifecycle subscription for all six delivery events.
6. Verifies auth health and Access protection.

Do not run production migrations or deployments from a workstation.

## Deployment credentials

The Cloudflare deployment token needs the narrow permissions required by the resources it reconciles: Workers Scripts, Workers Routes, D1, Queues, Access applications and policies, Email Sending, and Turnstile Sites Read and Write. Scope it to the StormTrust account and `stormtrust.net` zone. Monitoring uses separate read or notification tokens stored as Worker secrets.

The job requires these selected StormTrust organization secrets in the `app-auth-production` GitHub environment:

- `AUTH_APP_KEY_CURRENT`
- `AUTH_APP_KEYS_PREVIOUS`

The following secrets are optional. Add them when StormTrust turns on the matching provider or monitoring capability:

- `AUTH_GITHUB_CLIENT_ID`
- `AUTH_GITHUB_CLIENT_SECRET`
- `CLOUDFLARE_MONITORING_API_TOKEN`
- `CLOUDFLARE_ZONE_ANALYTICS_API_TOKEN`
- `CLOUDFLARE_ALERTS_API_TOKEN`

Terraform owns environment policy, not secret values.

## Verification

Run the local verification contract from the repository root:

```sh
make app-verify APP=auth
```

After a trusted deployment, `GET https://auth.stormtrust.net/health` must report a healthy database. Requests to ` monitor.auth.stormtrust.net` without an Access identity must redirect to Access or return ` 403`.

## Operational guides

Use the shared [validation and deployment guides](/stormtrust/engineering/operations/) and [health evidence by app](/stormtrust/engineering/operations/health/#evidence-by-application). For a failed release, follow [recovery procedures](/stormtrust/engineering/operations/recover/) with this application's state and access boundaries.