# Dev SSO tooling

Local-only helpers for exercising the native **mobile SSO bridge** without a real
OAuth provider. Dev environments have no IdP configured, so `GET /auth/providers`
returns `[]`, the app renders no SSO buttons, and the flow can't be tested. These
scripts stand up a stub IdP, register it, and verify the full bridge headlessly.

> **DEV ONLY.** `stub-idp.js` performs no credential checks and will sign in anyone.
> Never run it against a shared/production database or expose it publicly.

## Files

| File | Role |
|---|---|
| `stub-idp.js` | Dependency-free stub OAuth2/OIDC IdP: `GET /authorize` (account picker), `POST /token`, `GET /userinfo`. |
| `seed-sso-provider.js` | Registers an `auth_providers` row (`devstub`) pointing at the stub and pre-links each principal's `sub` to a dev account (SSO is link-only). Reads DB creds from `server/.env`. |
| `sso-bridge-smoketest.js` | Drives the whole app flow headless: PKCE → `/auth/mobile/sso/start` → stub → website callback → `runicgateway://auth/callback` deep link → `/auth/mobile/sso/exchange`. |

## Usage (host / headless)

```bash
# 1. seed the provider + linked identities (one-time; idempotent)
node scripts/dev/seed-sso-provider.js

# 2. run the stub IdP (leave running)
node scripts/dev/stub-idp.js

# 3. run the website with the callback origin pointed at the API port, so the
#    whole flow is same-origin (dev default APP_BASE_URL is the Vite client :5173)
cd server && APP_BASE_URL=http://127.0.0.1:3000 npm start

# 4. verify the bridge (from the website root)
node scripts/dev/sso-bridge-smoketest.js stub-colby   # or stub-admin
```

A pass prints the resolved user, an access token, and a present refresh token.

## Usage (Android emulator)

The **authorize** URL is followed by the device browser (Custom Tab); **token** and
**userinfo** are called server-side by the website. On an emulator the host is
`10.0.2.2`, so seed with split URLs:

```bash
STUB_IDP_PUBLIC_URL=http://10.0.2.2:9099 \
STUB_IDP_INTERNAL_URL=http://127.0.0.1:9099 \
  node scripts/dev/seed-sso-provider.js
```

Point the app's server at `http://10.0.2.2:3000`, and run the website with
`APP_BASE_URL=http://10.0.2.2:3000` so the IdP callback returns to a device-reachable
origin.

## Principals

`stub-admin` → dev user `admin` (role admin) · `stub-colby` → dev user `colby`
(role player). Keep the `sub` list in sync between `stub-idp.js` and
`seed-sso-provider.js`.