@open-mercato/enterprise 0.4.6-develop-15c18897fc → 0.4.6-develop-34aa847ce6

package/src/modules/sso/docs/google-workspace-setup.md

@@ -0,0 +1,174 @@
+# Google Workspace Setup Guide for Open Mercato SSO
+
+This guide walks through setting up Google Workspace as the identity provider for OIDC login in Open Mercato. Google Workspace supports JIT (Just-In-Time) provisioning only — SCIM push provisioning is not available.
+
+**Free tier**: Google Cloud OAuth 2.0 is free for internal Workspace applications. No paid APIs required.
+
+---
+
+## 1. Prerequisites
+
+- A Google Workspace account with admin access
+- A custom domain verified in Google Workspace (e.g., `company.com`)
+- Access to the Google Cloud Console (https://console.cloud.google.com)
+
+## 2. Create a Google Cloud Project
+
+1. Go to https://console.cloud.google.com
+2. Click the project selector in the top bar → **New Project**
+3. Name: `Open Mercato SSO` (or your preference)
+4. Click **Create**
+5. Switch to the new project in the project selector
+
+## 3. Configure the OAuth Consent Screen
+
+1. In the left sidebar, go to **APIs & Services** → **OAuth consent screen**
+2. Select **Internal** (restricts login to your Workspace organization only)
+3. Click **Create**
+4. Fill in:
+
+| Field | Value |
+|-------|-------|
+| **App name** | `Open Mercato` |
+| **User support email** | Your admin email |
+| **Authorized domains** | Your Workspace domain (e.g., `company.com`) |
+| **Developer contact email** | Your admin email |
+
+5. Click **Save and Continue**
+6. On the **Scopes** step, click **Add or Remove Scopes** and add:
+   - `openid`
+   - `email`
+   - `profile`
+7. Click **Update** → **Save and Continue**
+8. Review and click **Back to Dashboard**
+
+## 4. Create OAuth 2.0 Credentials
+
+1. Go to **APIs & Services** → **Credentials**
+2. Click **+ Create Credentials** → **OAuth client ID**
+3. Configure:
+
+| Field | Value |
+|-------|-------|
+| **Application type** | `Web application` |
+| **Name** | `Open Mercato SSO` |
+| **Authorized redirect URIs** | `http://localhost:3000/api/sso/callback/oidc` |
+
+4. Click **Create**
+5. **Copy the Client ID and Client Secret immediately** — you can also retrieve them later from the credentials list
+
+### OIDC Credentials Summary
+
+| Credential | Value |
+|------------|-------|
+| **Issuer URL** | `https://accounts.google.com` |
+| **Client ID** | Copy from Credentials page |
+| **Client Secret** | Copy from Credentials page |
+| **Redirect URI** | `http://localhost:3000/api/sso/callback/oidc` |
+
+**Note**: Google's OIDC discovery document is at `https://accounts.google.com/.well-known/openid-configuration`.
+
+## 5. Create the SSO Config in Open Mercato
+
+1. Log into Open Mercato as admin
+2. Go to **Settings** → **Single Sign-On** → **Create New**
+3. Select **OIDC** as the protocol
+4. Enter:
+   - **Name**: `Google Workspace`
+   - **Issuer URL**: `https://accounts.google.com`
+   - **Client ID**: (paste from Google Cloud Console)
+   - **Client Secret**: (paste from Google Cloud Console)
+5. Add your Workspace domain as an allowed domain (e.g., `company.com`)
+6. Enable **JIT Provisioning** (recommended — creates accounts on first login)
+7. Enable **Auto-link by email** (recommended — links existing accounts by email match)
+8. Click **Verify Discovery** to test the OIDC configuration
+9. Save and activate the configuration
+
+## 6. Verify OIDC Login
+
+1. Open a private/incognito browser window
+2. Go to the Open Mercato login page
+3. Enter an email address with your Workspace domain (e.g., `user@company.com`)
+4. The login page should detect SSO and show "Continue with SSO"
+5. Click it — you'll be redirected to Google's login page
+6. Authenticate with your Google Workspace account
+7. You should be redirected back to Open Mercato and logged in
+
+---
+
+## Google Workspace Specifics
+
+### No SCIM Provisioning
+
+Google Workspace does not support SCIM push provisioning to third-party applications. Users are provisioned via JIT on their first SSO login. The Provisioning tab in the Open Mercato admin UI will show an informational message for Google Workspace configurations.
+
+To manage user access:
+- **Provision**: Users are created automatically on first login via JIT
+- **Deprovision**: Remove the user's Workspace account or change their domain to stop SSO access
+
+### No Group Claims by Default
+
+Google's standard OIDC tokens do not include group membership claims. If you need role-based access from Google groups, you would need to configure a custom claim via Google's Directory API (advanced setup, not covered here).
+
+For most setups: leave **Role Mappings** empty in the SSO config. Users will log in with their default assigned role.
+
+### `hd` Claim
+
+Google OIDC returns a `hd` (hosted domain) claim for Workspace accounts. This identifies the user's organization domain. Open Mercato validates the user's email domain against the allowed domains configured in the SSO config.
+
+### `email_verified`
+
+Google Workspace accounts always return `email_verified: true`. Personal Gmail accounts may have unverified emails — configuring the consent screen as **Internal** prevents personal accounts from accessing the application.
+
+---
+
+## Troubleshooting
+
+### "Access blocked: Open Mercato has not completed the Google verification process"
+
+This appears when the consent screen is set to **External** without Google verification. Solution: set the consent screen to **Internal** (Workspace users only).
+
+### OIDC login redirects but fails
+
+- Verify the Redirect URI matches exactly: `http://localhost:3000/api/sso/callback/oidc`
+- Verify the Issuer URL is `https://accounts.google.com` (not a tenant-specific URL)
+- Ensure `openid`, `email`, and `profile` scopes are configured on the consent screen
+- Check that the user's email domain matches an allowed domain in the SSO config
+
+### "Error 400: redirect_uri_mismatch"
+
+The redirect URI in the authorization request doesn't match what's registered in Google Cloud Console. Check:
+- `APP_URL` in `.env` matches what you registered (e.g., `http://localhost:3000`)
+- No trailing slash differences
+- Protocol matches (http vs https)
+- The URI is listed in **Authorized redirect URIs**, not **Authorized JavaScript origins**
+
+### User gets "No roles could be resolved"
+
+This happens when **Role Mappings** are configured but Google doesn't send group claims. Solution: clear the Role Mappings section in the SSO config (leave it empty) to allow login without IdP-based role assignment.
+
+### Personal Gmail accounts can log in
+
+If you set the consent screen to **External**, any Google account can authenticate. To restrict to your organization only, set the consent screen to **Internal**.
+
+---
+
+## Key Differences from Entra ID
+
+| Aspect | Google Workspace | Entra ID |
+|--------|-----------------|----------|
+| **Issuer URL** | `https://accounts.google.com` (same for all orgs) | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
+| **SCIM provisioning** | Not supported | Enterprise App → Provisioning |
+| **Group claims** | Not in standard OIDC tokens | Via optional claims configuration |
+| **User provisioning** | JIT only (on first login) | JIT or SCIM (automatic sync) |
+| **Org restriction** | OAuth consent screen: Internal | App registration: Single tenant |
+| **Free tier** | Free with any Workspace plan | Free with any Azure account |
+| **Redirect URIs** | Supports `http://localhost` for dev | Supports `http://localhost` for dev |
+
+---
+
+## Reference
+
+- [Google Cloud OAuth 2.0 Setup](https://developers.google.com/identity/protocols/oauth2)
+- [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect)
+- [Google Workspace Admin: OAuth Apps](https://support.google.com/a/answer/7281227)

package/src/modules/sso/docs/sso-overview.md

@@ -0,0 +1,218 @@
+# SSO Module Overview
+
+Open Mercato's SSO module provides enterprise-grade Single Sign-On with OIDC and SCIM 2.0 support. This document covers architecture, configuration, and operational guidance.
+
+---
+
+## Supported Identity Providers
+
+| IdP | OIDC Login | SCIM Provisioning | JIT Provisioning | Notes |
+|-----|------------|-------------------|------------------|-------|
+| **Microsoft Entra ID** | Yes | Yes | Yes | Full OIDC + SCIM support. See [Entra ID Setup Guide](./entra-id-setup.md) |
+| **Zitadel** | Yes | Yes | Yes | OIDC + SCIM via Actions/native. See [Zitadel Setup Guide](./zitadel-setup.md) |
+| **Google Workspace** | Yes | No | Yes (recommended) | OIDC only, no SCIM push. See [Google Workspace Setup Guide](./google-workspace-setup.md) |
+
+---
+
+## Architecture
+
+### Authentication Flow (OIDC)
+
+```
+User → Login Page → HRD Check → IdP Redirect → IdP Login → Callback → Session
+```
+
+1. **Home Realm Discovery (HRD)**: User enters email, the system checks if the email domain matches an active SSO config
+2. **Authorization Request**: OIDC Authorization Code + PKCE flow initiated with encrypted state cookie
+3. **IdP Authentication**: User authenticates at the identity provider
+4. **Callback Processing**: Authorization code exchanged for tokens, ID token validated
+5. **Account Linking**: User matched to existing account (by email or SSO subject) or JIT-provisioned
+6. **Session Creation**: Auth session established, user redirected to the application
+
+### User Provisioning
+
+Two provisioning methods are supported, **mutually exclusive** per SSO config:
+
+**JIT (Just-In-Time) Provisioning**
+- Users are created automatically on first OIDC login
+- Profile data extracted from ID token claims
+- Best for: Google Workspace, small organizations, simple setups
+
+**SCIM 2.0 Provisioning**
+- Users are pre-provisioned by the IdP before first login
+- Supports create, update, deactivate, and delete operations
+- Best for: Entra ID, large organizations needing lifecycle management
+
+### Mutual Exclusivity
+
+JIT and SCIM cannot be enabled simultaneously on the same SSO config:
+- Enabling JIT blocks SCIM token creation
+- Creating SCIM tokens blocks enabling JIT
+- Switching requires disabling one before enabling the other
+
+---
+
+## Configuration
+
+### Admin Setup Steps
+
+1. **Create SSO Config**: Settings → Single Sign-On → Create New
+2. **Enter IdP Credentials**: Issuer URL, Client ID, Client Secret
+3. **Add Allowed Domains**: Email domains that should use this SSO config
+4. **Choose Provisioning**: Enable JIT or configure SCIM tokens
+5. **Test Connection**: Verify the IdP discovery endpoint is reachable
+6. **Activate**: Enable the config for production use
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/sso/config` | POST | Create SSO config |
+| `/api/sso/config` | GET | List SSO configs |
+| `/api/sso/config/:id` | GET | Get config by ID |
+| `/api/sso/config/:id` | PUT | Update config |
+| `/api/sso/config/:id` | DELETE | Delete config (must be inactive) |
+| `/api/sso/config/:id/activate` | POST | Activate/deactivate config |
+| `/api/sso/config/:id/domains` | POST | Add domain |
+| `/api/sso/config/:id/domains` | DELETE | Remove domain |
+| `/api/sso/config/:id/test` | POST | Test IdP connection |
+| `/api/sso/hrd` | POST | Home Realm Discovery lookup |
+| `/api/sso/initiate` | GET | Start SSO login flow |
+| `/api/sso/callback/oidc` | GET | OIDC callback |
+| `/api/sso/scim/tokens` | POST | Create SCIM token |
+| `/api/sso/scim/tokens` | GET | List SCIM tokens |
+| `/api/sso/scim/tokens/:id` | DELETE | Revoke SCIM token |
+| `/api/sso/scim/v2/Users` | POST | SCIM: Create user |
+| `/api/sso/scim/v2/Users` | GET | SCIM: List users |
+| `/api/sso/scim/v2/Users/:id` | GET | SCIM: Get user |
+| `/api/sso/scim/v2/Users/:id` | PATCH | SCIM: Update user |
+| `/api/sso/scim/v2/Users/:id` | DELETE | SCIM: Delete user |
+
+---
+
+## Security
+
+### OIDC Security Controls
+
+| Control | Implementation |
+|---------|---------------|
+| **PKCE** | S256 with 32-byte random code verifier |
+| **State Parameter** | AES-256-GCM encrypted state cookie with HKDF key derivation |
+| **Nonce** | 16-byte random nonce validated in ID token |
+| **State Comparison** | Timing-safe (`crypto.timingSafeEqual`) |
+| **TTL** | 5-minute state cookie lifetime |
+| **CSRF** | SameSite=Lax cookies + encrypted state parameter |
+| **Return URL** | Sanitized to prevent open redirects |
+
+### SCIM Security Controls
+
+| Control | Implementation |
+|---------|---------------|
+| **Token Format** | `omscim_` prefix + 32 random bytes (hex) |
+| **Storage** | bcrypt-hashed (cost 10), only prefix stored |
+| **One-Time Display** | Raw token returned only at creation |
+| **Timing Attack** | Dummy bcrypt hash on zero candidates |
+| **Tenant Isolation** | Organization ID derived from token, not request |
+
+### Data Protection
+
+- OIDC client secrets encrypted at rest (AES via `TenantDataEncryptionService`)
+- SCIM tokens bcrypt-hashed, never retrievable after creation
+- No PII in server logs
+- All admin endpoints require authentication + feature-based RBAC
+
+---
+
+## Provisioning Methods
+
+### JIT Provisioning
+
+When JIT is enabled on an SSO config:
+
+1. User authenticates via OIDC at the IdP
+2. If the user does not exist in Open Mercato, a new account is created
+3. Profile data (name, email) extracted from ID token claims
+4. User is assigned to the organization associated with the SSO config
+5. On subsequent logins, profile data is updated from the latest ID token
+
+**Limitations**:
+- User lifecycle not managed (no automatic deactivation)
+- No pre-provisioning (user must log in first)
+- Role assignment requires manual configuration or IdP group claims
+
+### SCIM 2.0 Provisioning
+
+When SCIM is configured:
+
+1. IdP pushes user create/update/delete operations to the SCIM endpoint
+2. Users are pre-provisioned before their first login
+3. Profile changes in the IdP are automatically synced
+4. User deactivation in the IdP triggers deactivation + session revocation
+5. On OIDC login, the existing SCIM-provisioned account is linked (no duplicate)
+
+**Supported SCIM Operations**:
+- `POST /Users` — Create user
+- `GET /Users` — List users (with `eq` filter support)
+- `GET /Users/:id` — Get user
+- `PATCH /Users/:id` — Update user (replace operations on `displayName`, `active`, `name.*`, `emails`)
+- `DELETE /Users/:id` — Delete user (soft-delete + deactivation)
+
+---
+
+## Role Mapping
+
+SSO configs support IdP group-to-application role mapping:
+
+1. Configure `appRoleMappings` on the SSO config (map IdP group names to app role names)
+2. When the IdP sends group claims in the ID token, roles are automatically assigned
+3. If no mappings are configured, role sync is skipped (user retains existing roles)
+
+**Google Workspace note**: Google does not send group claims by default. Role mapping is not available for Google OIDC without additional configuration.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SSO_STATE_SECRET` | Yes (production) | 32+ byte secret for state cookie encryption |
+| `APP_URL` / `NEXT_PUBLIC_APP_URL` | Recommended | Base URL for redirect URI construction |
+| `SSO_DEV_SEED` | No | Set to `true` to seed demo SSO config in development |
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**"State mismatch — possible CSRF attack"**
+- State cookie expired (5-minute TTL). User took too long at the IdP.
+- Browser blocking third-party cookies. Ensure SameSite=Lax cookies are allowed.
+
+**"No roles could be resolved from IdP groups"**
+- Role mappings are configured but the IdP isn't sending matching group claims.
+- Remove role mappings if not needed, or configure the IdP to send group claims.
+
+**User created with wrong provisioning method**
+- Check if both JIT and SCIM have been toggled. The system enforces mutual exclusivity.
+- Verify the `provisioningMethod` field on the user's SSO link record.
+
+**SCIM requests return 401**
+- Token may be revoked. Check token status in the admin UI.
+- Token format: must include `Authorization: Bearer omscim_...` header.
+- Check that the SSO config is active.
+
+**SCIM requests return 403**
+- The SSO config associated with the token is inactive. Activate it first.
+
+**HRD not detecting SSO for an email domain**
+- Verify the domain is added to the SSO config's allowed domains.
+- Verify the SSO config is activated (inactive configs are not returned by HRD).
+
+---
+
+## IdP-Specific Setup Guides
+
+- [Microsoft Entra ID Setup Guide](./entra-id-setup.md) — Full OIDC + SCIM setup
+- [Zitadel Setup Guide](./zitadel-setup.md) — OIDC + SCIM setup
+- [Google Workspace Setup Guide](./google-workspace-setup.md) — OIDC-only setup (JIT recommended)

package/src/modules/sso/docs/sso-security-audit-2026-02-27.md

@@ -0,0 +1,118 @@
+# SSO Module Security Audit Report
+
+**Module:** `packages/enterprise/src/modules/sso/`
+**Date:** 2026-02-27
+**Branch:** `feat/sso-support`
+
+---
+
+## Executive Summary
+
+The SSO module demonstrates strong security fundamentals: AES-256-GCM encrypted state cookies, PKCE enforcement, timing-safe state comparison, bcrypt-hashed SCIM tokens, and encrypted OIDC client secrets. The audit uncovered **2 High**, **3 Medium**, and **4 Low** severity findings. Both HIGH findings have been remediated in this milestone.
+
+---
+
+## Findings Summary
+
+| # | Finding | Severity | Status |
+|---|---------|----------|--------|
+| F1 | SCIM debug `console.log` statements dump PII to logs | **HIGH** | **FIXED** |
+| F2 | Missing org ownership check in SCIM token generation | **HIGH** | **FIXED** |
+| F3 | SCIM payloads lack string length constraints | MEDIUM | Open |
+| F4 | SCIM logs `ssoConfigId` query param not UUID-validated | MEDIUM | Open |
+| F5 | `emailVerified` defaults to `true` when claim absent | MEDIUM | Documented |
+| F6 | Domain DELETE query param not format-validated | LOW | Open |
+| F7 | SCIM v2 `startIndex`/`count` not zod-validated | LOW | Open |
+| F8 | State cookie not enforced as single-use | LOW | Accepted |
+| F9 | Host header fallback in `toAbsoluteUrl` if `APP_URL` unset | LOW | Accepted |
+
+---
+
+## 1. CSRF Protection -- PASS
+
+All admin write endpoints are protected by:
+- Cookie-based auth via `resolveSsoAdminContext()` with `requireAuth: true` and `requireFeatures` guards
+- `SameSite: lax` on auth cookies (appropriate for SSO flows that require cross-site IdP redirects)
+
+SCIM v2 endpoints use Bearer token authentication (inherently CSRF-safe).
+
+**Files verified:** All routes under `api/config/`, `api/scim/tokens/`, and `api/scim/v2/`.
+
+## 2. Replay Protection -- PASS
+
+- **State cookie:** AES-256-GCM encrypted with HKDF-SHA256 key derivation, 12-byte random IV, 16-byte auth tag
+- **TTL:** 5 minutes (checked at decryption time + cookie maxAge)
+- **PKCE:** S256 with 32-byte random code verifier stored in encrypted state cookie
+- **Nonce:** 16-byte random nonce validated by `openid-client` library against ID token
+- **State comparison:** Timing-safe (`crypto.timingSafeEqual`) with length pre-check
+- **Cleanup:** State cookie cleared after successful callback (maxAge: 0)
+
+**F8 (LOW, Accepted):** No server-side single-use enforcement on state cookie. Mitigated by IdP's single-use authorization code policy (OAuth 2.0 spec requirement).
+
+## 3. Tenant Isolation -- PASS (with F2 fixed)
+
+- **Admin endpoints:** All queries scoped by `organizationId` for non-superadmins via `resolveSsoAdminContext()`
+- **SCIM endpoints:** `organizationId` derived from verified bearer token, not from request parameters
+- **HRD:** Intentional cross-org lookup (by design) -- only exposes `hasSso`, `configId`, `protocol`
+- **F2 (FIXED):** `ScimTokenService.generateToken()` now verifies SSO config ownership before minting tokens
+
+## 4. Token Security -- PASS (with F1 fixed)
+
+- **OIDC client secrets:** Encrypted at rest via `TenantDataEncryptionService`; never exposed in API responses
+- **SCIM tokens:** bcrypt-hashed (cost 10), prefix-indexed, timing-attack resistant (dummy hash on miss), raw value returned only once at creation
+- **State cookies:** AES-256-GCM encrypted
+- **F1 (FIXED):** Removed 5 `[SCIM DEBUG]` console.log statements that serialized full SCIM payloads (PII) to logs
+
+## 5. Input Validation -- PASS (with notes)
+
+- **Admin APIs:** All write endpoints validated with zod schemas from `data/validators.ts`
+- **SCIM filter:** Strict regex parser with attribute allowlist, parameterized ORM queries
+- **Domain validation:** DNS hostname regex, max 253 chars, must contain dot, max 20 per config
+- **Return URL:** `sanitizeReturnUrl()` prevents open redirects (requires `/` prefix, rejects `//`, validates origin)
+
+### Open Validation Items
+
+- **F3 (MEDIUM):** SCIM payloads parsed via manual extraction without max-length constraints. Database column constraints provide backstop.
+- **F4 (MEDIUM):** SCIM logs `ssoConfigId` param not UUID-validated (DB rejects non-UUID values).
+- **F5 (MEDIUM, Documented):** `emailVerified` defaults to `true` when IdP omits the claim. Acceptable for enterprise IdPs (Entra, Google, Zitadel) which reliably send this claim. Domain allowlist provides mitigating control.
+
+---
+
+## Remediation Status
+
+### Completed (This Milestone)
+
+1. **F1** -- Removed all `[SCIM DEBUG]` console.log from `api/scim/v2/Users/route.ts` and `api/scim/v2/Users/[id]/route.ts`
+2. **F2** -- Added `organizationId` filter to `ScimTokenService.generateToken()` in `services/scimTokenService.ts`
+3. Removed 3 console.log statements from `lib/oidc-provider.ts` (raw ID token logging)
+
+### Future Hardening (Priority 2)
+
+4. **F3** -- Add `.slice(0, 255)` length constraints to SCIM mapper fields
+5. **F4** -- Add `z.string().uuid()` validation to SCIM logs endpoint
+6. **F5** -- Document `emailVerified` default behavior in admin guide
+
+### Accepted Risks (Priority 3)
+
+7. **F6-F9** -- Input validation consistency improvements and defense-in-depth
+
+---
+
+## Security Controls Summary
+
+| Control | Status |
+|---------|--------|
+| Admin inputs validated (zod) | PASS |
+| No hardcoded secrets | PASS |
+| Auth on all admin endpoints | PASS |
+| SCIM Bearer token auth | PASS |
+| Parameterized ORM queries | PASS |
+| HTTPS enforced (production) | PASS |
+| CSRF protection (SameSite + encrypted state) | PASS |
+| Error messages don't leak info | PASS |
+| Client secrets encrypted at rest | PASS |
+| SCIM tokens bcrypt-hashed | PASS |
+| PKCE enforced | PASS |
+| Open redirect protection | PASS |
+| No PII in server logs | PASS (after F1 fix) |
+| Org ownership on token generation | PASS (after F2 fix) |