npm - @open-mercato/enterprise - Versions diffs - 0.4.6-develop-34aa847ce6 → 0.4.6-develop-7ffc0df6e5 - Mend

@open-mercato/enterprise 0.4.6-develop-34aa847ce6 → 0.4.6-develop-7ffc0df6e5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/package.json +4 -4
package/src/modules/sso/docs/entra-id-setup.md +0 -281
package/src/modules/sso/docs/google-workspace-setup.md +0 -174
package/src/modules/sso/docs/sso-overview.md +0 -218
package/src/modules/sso/docs/sso-security-audit-2026-02-27.md +0 -118
package/src/modules/sso/docs/zitadel-setup.md +0 -195

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/enterprise",
-  "version": "0.4.6-develop-34aa847ce6",
+  "version": "0.4.6-develop-7ffc0df6e5",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -64,9 +64,9 @@
     }
   },
   "dependencies": {
-    "@open-mercato/core": "0.4.6-develop-34aa847ce6",
-    "@open-mercato/shared": "0.4.6-develop-34aa847ce6",
-    "@open-mercato/ui": "0.4.6-develop-34aa847ce6",
+    "@open-mercato/core": "0.4.6-develop-7ffc0df6e5",
+    "@open-mercato/shared": "0.4.6-develop-7ffc0df6e5",
+    "@open-mercato/ui": "0.4.6-develop-7ffc0df6e5",
     "openid-client": "^6.3.3"
   },
   "devDependencies": {

package/src/modules/sso/docs/entra-id-setup.md DELETED Viewed

@@ -1,281 +0,0 @@
-# Microsoft Entra ID Setup Guide for Open Mercato SSO + SCIM
-This guide walks through setting up Microsoft Entra ID (formerly Azure AD) as the identity provider for both OIDC login and SCIM user provisioning in Open Mercato.
-**Free tier**: Entra ID Free is included with any Azure subscription — no paid license required for basic OIDC + SCIM.
----
-## 1. Create an Azure Account + Entra ID Tenant
-1. Go to https://azure.microsoft.com/free and create a free account (or use an existing one)
-2. Navigate to https://entra.microsoft.com (the Entra admin center)
-3. You'll have a default tenant — note your **Tenant ID** from **Overview** → **Tenant ID**
-## 2. Create Test Users
-1. In the Entra admin center, go to **Identity** → **Users** → **All users**
-2. Click **+ New user** → **Create new user**
-3. Fill in:
-   - **User principal name**: e.g., `testuser@yourtenant.onmicrosoft.com`
-   - **Display name**: e.g., `Test User`
-   - **First name** / **Last name**
-   - **Password**: auto-generate or set manually
-4. Click **Create**
-5. Repeat for 2-3 test users
-## 3. Register the OIDC Application (SSO Login)
-1. In the Entra admin center, go to **Identity** → **Applications** → **App registrations**
-2. Click **+ New registration**
-3. Configure:
-| Field | Value |
-|-------|-------|
-| **Name** | `Open Mercato` |
-| **Supported account types** | `Accounts in this organizational directory only` (Single tenant) |
-| **Redirect URI** | Platform: `Web`, URI: `http://localhost:3000/api/sso/callback/oidc` |
-4. Click **Register**
-5. You'll land on the app's **Overview** page — note:
-   - **Application (client) ID** — this is your Client ID
-   - **Directory (tenant) ID** — used in the issuer URL
-### Create a Client Secret
-1. Go to **Certificates & secrets** → **Client secrets** tab
-2. Click **+ New client secret**
-3. Description: `Open Mercato Dev`, Expiry: `6 months` (or your preference)
-4. Click **Add**
-5. **Copy the secret Value immediately** — it's shown only once
-### OIDC Credentials Summary
-| Credential | Where to find it | Value |
-|------------|-----------------|-------|
-| **Issuer URL** | Computed from Tenant ID | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
-| **Client ID** | App registration → Overview | Copy from portal |
-| **Client Secret** | App registration → Certificates & secrets | Copy the **Value** (not Secret ID) |
-| **Redirect URI** | You configured this | `http://localhost:3000/api/sso/callback/oidc` |
-### Configure Token Claims
-By default, Entra ID v2.0 tokens may not include `email` in the ID token. Fix this:
-1. Go to your App registration → **Token configuration**
-2. Click **+ Add optional claim**
-3. Token type: **ID**
-4. Check: `email`, `given_name`, `family_name`
-5. Click **Add**
-6. When prompted about Microsoft Graph permissions, check the box and click **Add**
-### API Permissions
-1. Go to **API permissions**
-2. Verify these are present (they should be by default):
-   - `Microsoft Graph` → `openid` (Delegated)
-   - `Microsoft Graph` → `profile` (Delegated)
-   - `Microsoft Graph` → `email` (Delegated)
-3. If any are missing, click **+ Add a permission** → **Microsoft Graph** → **Delegated permissions** → search and add them
-4. Click **Grant admin consent for [your tenant]** (green checkmark button)
-### Assign Users to the Application
-1. Go to **Identity** → **Applications** → **Enterprise applications**
-2. Find and click **Open Mercato**
-3. Go to **Users and groups** → **+ Add user/group**
-4. Select your test users (or a group containing them)
-5. Click **Assign**
-**Important**: If "Assignment required?" is set to **Yes** (under Properties), only assigned users can log in. Set to **No** for dev if you want all tenant users to access it.
----
-## 4. 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**: `Entra ID`
-   - **Issuer URL**: `https://login.microsoftonline.com/{your-tenant-id}/v2.0`
-   - **Client ID**: (paste from Entra)
-   - **Client Secret**: (paste the secret Value from Entra)
-5. Add allowed email domains (e.g., `yourtenant.onmicrosoft.com`)
-6. Test the connection (Verify Discovery)
-7. Activate the config
-### Verify OIDC Login
-1. Open a private/incognito browser window
-2. Go to the Open Mercato login page
-3. Enter an email address belonging to one of your test users (e.g., `testuser@yourtenant.onmicrosoft.com`)
-4. The HRD check should detect SSO and redirect to Microsoft login
-5. Authenticate at Microsoft
-6. You should be redirected back to Open Mercato and logged in
----
-## 5. Configure SCIM Provisioning
-**Prerequisite**: You need a SCIM bearer token from Open Mercato. Generate one via:
-- The admin UI: SSO config → Provisioning tab → Generate Token
-- Or the API: `POST /api/sso/scim/tokens` with the SSO config ID
-### Set Up Provisioning in Entra ID
-1. Go to **Identity** → **Applications** → **Enterprise applications**
-2. Find and click **Open Mercato**
-3. Go to **Provisioning** → click **Get started**
-4. Set **Provisioning Mode** to **Automatic**
-5. In **Admin Credentials**:
-| Field | Value |
-|-------|-------|
-| **Tenant URL** | `http://localhost:3000/api/sso/scim/v2` (dev) or `https://<your-domain>/api/sso/scim/v2` (prod) |
-| **Secret Token** | Paste the SCIM bearer token from Open Mercato |
-6. Click **Test Connection** — should show "The supplied credentials are authorized to enable provisioning"
-7. Click **Save**
-### Configure Attribute Mappings
-1. Under **Mappings**, click **Provision Microsoft Entra ID Users**
-2. Verify these mappings exist:
-| Entra ID Attribute | SCIM Attribute | Notes |
-|--------------------|----------------|-------|
-| `userPrincipalName` | `userName` | Required |
-| `Switch([IsSoftDeleted]...)` | `active` | Required — Entra uses a Switch expression |
-| `givenName` | `name.givenName` | Required |
-| `surname` | `name.familyName` | Required |
-| `mail` | `emails[type eq "work"].value` | Required — user's email |
-| `displayName` | `displayName` | Optional |
-| `objectId` | `externalId` | Required — Entra's unique ID |
-3. Keep default mappings — they should work out of the box
-4. Click **Save**
-### Start Provisioning
-1. Back on the **Provisioning** page, set **Provisioning Status** to **On**
-2. Click **Save**
-3. Entra will run an initial provisioning cycle (may take up to 40 minutes for the first cycle)
-4. Check **Provisioning logs** for results
-### Provisioning Cycle Timing
-- **Initial cycle**: Processes all users in scope. Can take 20-40 minutes.
-- **Incremental cycles**: Every 40 minutes, processes changes since last cycle.
-- **On-demand provisioning**: Click **Provision on demand** to immediately provision a specific user (useful for testing).
----
-## 6. Test the Full Flow
-### Test SCIM Provisioning
-1. In Entra, go to **Enterprise applications** → **Open Mercato** → **Provisioning**
-2. Click **Provision on demand**
-3. Search for a test user and click **Provision**
-4. **Expected**: Entra sends `POST /Users` to your SCIM endpoint → user appears in Open Mercato
-5. Check the provisioning log in Open Mercato admin UI
-### Test User Update
-1. In Entra, go to **Users** → edit a test user's display name
-2. Wait for the next provisioning cycle (or use Provision on demand)
-3. **Expected**: Entra sends `PATCH /Users/{id}` → user's name updated in Open Mercato
-### Test User Deactivation
-1. In Entra, either:
-   - **Delete** the user (soft-delete moves to Deleted users)
-   - **Block sign-in** for the user (Users → select user → Edit properties → Block sign in: Yes)
-   - **Remove** the user from the application assignment
-2. **Expected**: Entra sends `PATCH /Users/{id}` with `active: false` → user deactivated in Open Mercato, all sessions revoked
-### Test OIDC + SCIM Together
-1. **Create a new user in Entra** and assign them to the Open Mercato Enterprise app
-2. **Provision on demand** (or wait for cycle)
-3. **Verify** the user exists in Open Mercato (pre-provisioned, no login needed)
-4. **Log in as that user** via OIDC (Open Mercato login → redirect to Microsoft → authenticate → redirect back)
-5. **Expected**: The SCIM-provisioned account is used (no JIT provisioning, `provisioningMethod` stays `scim`)
-6. **Block sign-in for the user in Entra**
-7. **Expected**: SCIM deactivates the user → existing sessions revoked → OIDC login no longer works
----
-## Entra ID SCIM Quirks
-When building the SCIM endpoint, account for these Entra-specific behaviors:
-| Quirk | Description | How to handle |
-|-------|-------------|---------------|
-| **PascalCase `op` in PATCH** | Entra sends `"op": "Replace"` instead of `"op": "replace"` | Case-insensitive comparison on PATCH operations |
-| **String booleans** | `active` may be sent as `"True"` / `"False"` strings | Parse with `parseBooleanToken` |
-| **Non-standard PATCH paths** | Sometimes sends `emails[type eq "work"].value` in PATCH path | Support bracket-notation in PATCH path parser |
-| **Mixed-case filter operators** | Sends `Eq` instead of `eq` in filters | Case-insensitive filter parsing |
-| **`externalId` mapping** | Maps `objectId` → `externalId` by default | Always store `externalId` from SCIM requests |
-| **Soft delete** | Uses `IsSoftDeleted` Switch expression → `active: false` | Handle as user deactivation |
----
-## Troubleshooting
-### OIDC login redirects but fails
-- Verify the Redirect URI in App Registration matches exactly: `http://localhost:3000/api/sso/callback/oidc`
-- Check that the Issuer URL includes the tenant ID: `https://login.microsoftonline.com/{tenant-id}/v2.0`
-- Verify Client ID and Client Secret (the Value, not the Secret ID)
-- Ensure `email` optional claim is added to the ID token
-- Ensure API permissions have admin consent granted
-### "AADSTS50011: The redirect URI does not match"
-The redirect URI in the authorization request doesn't match what's registered. Check:
-- `APP_URL` in `.env` matches what you registered (e.g., `http://localhost:3000`)
-- No trailing slash differences
-- Protocol matches (http vs https)
-### Users not provisioning
-- Check that users are assigned to the Enterprise application
-- Check **Provisioning logs** in Entra for error details
-- Verify the SCIM token is valid and not revoked
-- For local dev, Entra needs to reach your server — use ngrok for SCIM (even though OIDC works with localhost)
-### SCIM "Test Connection" fails
-- For local dev, Entra's provisioning service needs to reach your endpoint over the internet
-- Use ngrok: `ngrok http 3000`
-- Set Tenant URL to: `https://<id>.ngrok-free.app/api/sso/scim/v2`
-- **Note**: OIDC redirect URIs can use `localhost`, but SCIM provisioning requires a publicly reachable URL
-### email claim missing from ID token
-1. Go to App registration → **Token configuration** → **+ Add optional claim** → ID token → check `email`
-2. Go to **API permissions** → verify `email` permission → click **Grant admin consent**
----
-## Key Differences from JumpCloud
-| Aspect | Entra ID | JumpCloud |
-|--------|----------|-----------|
-| **Issuer URL** | `https://login.microsoftonline.com/{tenant-id}/v2.0` | `https://oauth.id.jumpcloud.com/` |
-| **Redirect URI** | Supports `http://localhost` for dev | Requires HTTPS |
-| **SCIM provisioning** | Enterprise App → Provisioning (automatic) | SSO App → Identity Management (SCIM API) |
-| **Provisioning cycles** | Every 40 minutes (or on-demand) | Near real-time |
-| **SCIM quirks** | PascalCase ops, string booleans, mixed-case filters | Mostly spec-compliant |
-| **Free tier** | Free with any Azure account | 10 users forever |
----
-## Reference
-- [Entra ID App Registration - OIDC](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
-- [Entra ID SCIM Provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups)
-- [Entra ID Optional Claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims)
-- [Entra ID SCIM Known Issues](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility)

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

@@ -1,174 +0,0 @@
-# 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 DELETED Viewed

@@ -1,218 +0,0 @@
-# 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 DELETED Viewed

@@ -1,118 +0,0 @@
-# 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) |

package/src/modules/sso/docs/zitadel-setup.md DELETED Viewed

@@ -1,195 +0,0 @@
-# Zitadel Setup Guide for Open Mercato SSO
-This guide walks through setting up Zitadel as the identity provider for OIDC login and SCIM user provisioning in Open Mercato.
-**Free tier**: Zitadel Cloud offers a free tier with up to 25,000 monthly active users.
----
-## 1. Create a Zitadel Instance
-1. Go to https://zitadel.com and sign up for a free account
-2. Create a new instance (or use the default one)
-3. Note your instance domain: `https://<instance>.zitadel.cloud`
-## 2. Create Test Users
-1. In the Zitadel Console, go to **Users** → **+ New**
-2. Fill in:
-   - **Username**: e.g., `testuser@yourdomain.com`
-   - **First name** / **Last name**
-   - **Email**: the user's email address
-   - **Password**: set an initial password
-3. Click **Create**
-4. Repeat for 2-3 test users
-## 3. Register the OIDC Application
-1. In the Zitadel Console, go to **Projects** → **+ New**
-2. Name the project `Open Mercato` and click **Continue**
-3. Click **+ New Application**
-4. Configure:
-| Field | Value |
-|-------|-------|
-| **Name** | `Open Mercato` |
-| **Type** | `Web` |
-| **Authentication Method** | `Code (PKCE)` |
-| **Redirect URIs** | `http://localhost:3000/api/sso/callback/oidc` |
-| **Post-Logout URIs** | `http://localhost:3000/login` |
-5. Click **Create**
-6. On the application overview, note:
-   - **Client ID**
-   - **Client Secret** (generate one if using Code flow)
-### OIDC Credentials Summary
-| Credential | Where to find it | Value |
-|------------|-----------------|-------|
-| **Issuer URL** | Instance domain | `https://<instance>.zitadel.cloud` |
-| **Client ID** | Application → General | Copy from console |
-| **Client Secret** | Application → General → Generate | Copy immediately |
-| **Redirect URI** | You configured this | `http://localhost:3000/api/sso/callback/oidc` |
-### Configure Token Claims
-Zitadel includes `email`, `given_name`, `family_name`, and `email_verified` in ID tokens by default when the `openid`, `profile`, and `email` scopes are requested. No additional configuration is needed.
-### Assign Users
-By default, all users in the organization can access the application. To restrict access:
-1. Go to your Project → **Authorizations** → **+ New**
-2. Select specific users or grant roles
-3. Enable "Require authorization" on the project settings if you want to restrict access
----
-## 4. 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**: `Zitadel`
-   - **Issuer URL**: `https://<instance>.zitadel.cloud`
-   - **Client ID**: (paste from Zitadel)
-   - **Client Secret**: (paste from Zitadel)
-5. Add allowed email domains (e.g., `yourdomain.com`)
-6. Test the connection (Verify Discovery)
-7. Activate the config
-### Verify OIDC Login
-1. Open a private/incognito browser window
-2. Go to the Open Mercato login page
-3. Enter an email address belonging to one of your test users
-4. The HRD check should detect SSO and redirect to Zitadel login
-5. Authenticate at Zitadel
-6. You should be redirected back to Open Mercato and logged in
----
-## 5. Configure SCIM Provisioning
-**Prerequisite**: Generate a SCIM bearer token from Open Mercato via the admin UI (SSO config → Provisioning tab → Generate Token).
-### Zitadel SCIM Support
-Zitadel supports outbound SCIM provisioning through its **Actions** feature (custom workflows). As of 2026, Zitadel also offers a native SCIM provisioning option:
-1. Go to your Project → **Open Mercato** application
-2. Navigate to **Provisioning** or **Actions**
-3. Configure SCIM outbound provisioning:
-| Field | Value |
-|-------|-------|
-| **SCIM Base URL** | `http://localhost:3000/api/sso/scim/v2` (dev) or `https://<your-domain>/api/sso/scim/v2` (prod) |
-| **Bearer Token** | Paste the SCIM token from Open Mercato |
-4. Test the connection
-### Alternative: Manual/API-Based Provisioning
-If Zitadel's native SCIM outbound is not available in your version, use the Zitadel Management API to sync users:
-1. Create a Service User in Zitadel with Management API access
-2. Use the Zitadel Management API to list users
-3. Push user changes to Open Mercato's SCIM endpoint
----
-## 6. Test the Full Flow
-### Test OIDC Login
-1. Navigate to Open Mercato login
-2. Enter a test user's email
-3. **Expected**: Redirect to Zitadel → authenticate → redirect back to Open Mercato
-4. Verify the user appears in the Open Mercato admin panel
-### Test JIT Provisioning
-If SCIM is not configured and JIT is enabled:
-1. Log in as a new user via OIDC
-2. **Expected**: User is automatically created in Open Mercato with `provisioningMethod: jit`
-3. Verify user profile (name, email) matches Zitadel
-### Test SCIM Provisioning (if configured)
-1. Create a new user in Zitadel
-2. Wait for provisioning cycle (or trigger manually)
-3. **Expected**: User appears in Open Mercato with `provisioningMethod: scim`
-4. Update the user in Zitadel → verify changes propagate
-5. Deactivate the user in Zitadel → verify deactivation in Open Mercato
----
-## Zitadel SCIM Quirks
-| Quirk | Description | How to handle |
-|-------|-------------|---------------|
-| **Standard-compliant** | Zitadel follows SCIM 2.0 spec closely | Standard parsing works |
-| **`email_verified` claim** | Always included in ID tokens | No special handling needed |
-| **Group claims** | Available via project roles | Configure role mappings if needed |
-| **PKCE support** | Natively supports S256 PKCE | Automatically used by Open Mercato |
----
-## Troubleshooting
-### OIDC login redirects but fails
-- Verify the Redirect URI matches exactly: `http://localhost:3000/api/sso/callback/oidc`
-- Check that the Issuer URL matches your instance: `https://<instance>.zitadel.cloud`
-- Verify Client ID and Client Secret
-- Check the Zitadel Console → **Events** for error details
-### "redirect_uri_mismatch" error
-- Ensure the redirect URI registered in Zitadel matches exactly (including protocol and port)
-- No trailing slash differences
-- For production, use HTTPS
-### Users can't log in
-- Check that users exist in the same Zitadel organization
-- If "Require authorization" is enabled on the project, ensure users have project grants
-- Check that the email domain matches the allowed domains in Open Mercato SSO config
-### SCIM connection fails
-- For local dev, Zitadel needs to reach your server over the internet
-- Use ngrok: `ngrok http 3000`
-- Update the SCIM Base URL to the ngrok URL
----
-## Reference
-- [Zitadel OIDC Documentation](https://zitadel.com/docs/guides/integrate/login/oidc)
-- [Zitadel SCIM Documentation](https://zitadel.com/docs/guides/integrate/scim)
-- [Zitadel Actions](https://zitadel.com/docs/guides/manage/customize/actions)
-- [Zitadel Cloud](https://zitadel.com/pricing)