# Customer Connect Console

Angular 20 SPA for Zero Trust network access management. Enables service providers to onboard customers, manage locations, connectors, and connections through a guided setup workflow.

## Prerequisites

- **Node.js** v20.19+ or v22.12+ (use `nvm use 20.19.3` if needed)
- **npm** (ships with Node)

## Getting Started

```bash
npm install
npm start
```

The dev server starts at `http://localhost:4200`. The default configuration uses **staging** environment values.

## Environment Configurations

Each environment has its own config file under `src/environments/`. All code imports from `environment.ts` (the default); Angular's `fileReplacements` swaps in the correct file at build time.

| Environment | Config file | Dev server | Build |
|---|---|---|---|
| Default (staging) | `environment.ts` | `npm start` | `npm run build` |
| Localhost | `environment.localhost.ts` | `npm run start:localhost` | — |
| Staging | `environment.staging.ts` | `npm run start:staging` | `npm run build:staging` |
| Sandbox | `environment.sandbox.ts` | — | `npm run build:sandbox` |
| Production | `environment.production.ts` | — | `npm run build:production` |

All environment files currently contain identical staging values. Update them as each environment gets its own Auth0 tenant, gateway, and client ID.

### What's in each environment file

```ts
export const environment = {
  name: 'staging',
  auth0: {
    domain: '...',      // Auth0 tenant domain
    clientId: '...',    // Auth0 SPA application client ID
    audience: '...',    // Auth0 API audience for access tokens
  },
  gateway: {
    host: '...',        // Gateway hostname (used by the HTTP interceptor)
    baseUrl: '...',     // Gateway base URL for API calls
  },
  tenant: {
    label: '...',       // NetFoundry tenant label for authorize-initiate
    realm: '...',       // Auth0 database connection realm
  },
};
```

## Authentication Flow

Login is handled through Auth0 with a NetFoundry-specific intermediate step:

1. **`/` (LoginComponent)** — Calls the NF gateway's `authorize-initiate` endpoint to get a signed `nfToken`, then redirects to Auth0 Universal Login with the Customer Connect branded template.
2. **Auth0** — User authenticates (e.g. Google SSO). Auth0's post-login Action validates the `nfToken` and redirects to `/callback` with a signed `authToken`.
3. **`/callback` (CallbackComponent)** — Exchanges the `authToken` with the NF gateway's `/tenants/authorize` endpoint to get a tenant-scoped `nfToken2`. Fires a second (silent) Auth0 `/authorize` to obtain a standard OAuth code.
4. **`/callback` (second visit)** — Auth0 SDK processes the `?code=` param, exchanges it for tokens. Tokens are persisted in `localStorage` via `NfSessionService`. The gateway `/identities/self` endpoint is called to validate the token and fetch user metadata.
5. **Dashboard** — User lands on `/provider-dashboard`.

### Logout

Sign-out clears the local session (`NfSessionService` + Auth0 SDK cache) and redirects to Auth0's `/v2/logout` endpoint, which clears the Auth0 session cookie and returns the user to `/logout`.

### Session Persistence

Tokens are stored in `localStorage` under the key `cc.nfSession`. On page refresh, the auth guard checks this store; if valid, the app calls `/identities/self` to re-validate the token with the gateway. If the gateway rejects it (401/403), the session is cleared and the user is redirected to login.

### Bearer Token Interceptor

An HTTP interceptor (`gatewayAuthInterceptor`) automatically attaches `Authorization: Bearer <token>` to all outbound requests matching the gateway host. No manual header management is needed for gateway API calls.

## Auth0 Setup (per environment)

Each environment requires an Auth0 SPA application with:

- **Allowed Callback URLs**: `<origin>/callback`
- **Allowed Logout URLs**: `<origin>/logout`
- **Allowed Web Origins**: `<origin>`
- **Application Type**: Single Page Application
- **Token Endpoint Auth Method**: None

The NF gateway must also whitelist the app's origin as a valid `intermediateReturnUrl` for the `authorize-initiate` endpoint.

## Auth0 Universal Login Template

A unified login template lives at `auth0/login.html`. It supports two variants:

- **`netfoundry`** (default) — The existing NetFoundry production login UI. Used by all other apps in the tenant.
- **`customer-connect`** — The Customer Connect branded login. Activated when `loginVariant=customer-connect` is passed as an Auth0 `/authorize` param.

Upload this template via Auth0 Dashboard > Branding > Universal Login > Login tab > Customize Login Page.

## Project Structure

```
src/
  app/
    app.ts                    # Root component, session bootstrap
    app.config.ts             # Providers (Auth0, HTTP, routing)
    app.routes.ts             # All route definitions + auth guards
  environments/               # Per-environment configuration
  lib/
    features/
      auth/
        login.component.*     # Auth initiation + redirect
        callback.component.*  # Auth0 callback handler (two-step)
        logout.component.*    # Post-logout interstitial
      provider-dashboard/     # Provider management views
      setup-guide/            # Customer setup wizard
      dashboards/             # Location/connection dashboards
    shared/
      auth-initiate.service.ts  # Gateway auth API calls
      auth.guard.ts             # Route guard (NfSession + Auth0 SDK)
      auth.interceptor.ts       # Bearer token interceptor
      nf-session.service.ts     # Token storage (localStorage)
      setup-data.service.ts     # Application state (single source of truth)
```

## Type Checking

```bash
npx tsc --noEmit
```