[feature]: Enterprise Features

## Summary

Define the ByteChef Enterprise Edition (EE) feature set across **six epics**. Each epic is sized to spawn its own detailed design spec under `docs/superpowers/specs/` before implementation.

The goal is **parity on enterprise governance surface area** with leading automation platforms. Where ByteChef already has infrastructure (EE microservices, connection visibility, audit aspects, `ai-gateway-app`), this ticket extends it rather than rebuilding.

**Design spec (authoritative):** `docs/superpowers/specs/2026-04-21-enterprise-features-spec.md`

---

## Current EE baseline (what already exists)

- **EE microservices** — `server/ee/apps/` (api-gateway, ai-gateway, ai-copilot, config-server, configuration, connection, coordinator, execution, scheduler, webhook, worker, runtime-job)
- **Connection visibility** — `PRIVATE | WORKSPACE | PROJECT | ORGANIZATION` enforced in `ConnectionFacadeImpl.create()`
- **Audit infrastructure** — `platform-audit-service` with `PermissionAuditAspect` and `ConnectionAuditAspect`; emission exists but no viewer/export/retention yet
- **AI routing** — `ai-gateway-app` routes model traffic; policy/BYOK/proxy not yet bolted on
- **Metrics** — Micrometer `MeterRegistry` pattern via `ObjectProvider` (`bytechef_connection_create` with `visibility` tag)
- **EE gating** — `@ConditionalOnEEVersion` + remote-client stub pattern

---

## Epic 1 — Identity, Access & Directory Sync

- **SSO** — SAML 2.0 + OIDC; Okta, Entra ID, Google Workspace, JumpCloud, Ping Identity, generic. SP-initiated. Dedicated org login URL. JIT account provisioning.
- **SCIM 2.0** — phase 1: Okta + Entra ID. Bearer-token auth, 15-min scheduled sync + manual trigger. Group→permission-group mapping.
- **Permission Groups** — one group per user; four axes: feature restrictions, per-group rate limits, OAuth scope allowlists, component denylist.
- **Domain-restricted org signup** — orthogonal to OAuth domain restrictions (Epic 3).
- **Admin API** — CRUD for orgs/workspaces/members/groups for infra-as-code setups.

**Modules:** new `platform-identity-sso`, `platform-identity-scim`; extend `platform-rbac` and `api-gateway-app`.

---

## Epic 2 — Audit Logging & Organization Data Export

- **Event categories:** Authentication, Credentials, Teams, Organization, Permissions, Workflows, Files.
- **Schema:** `audit_event(id, occurred_at, event_type, actor_user_id, actor_ip, session_id, org_id, workspace_id, target_entity_type, target_entity_id, action_data JSONB, correlation_id)` — built on existing `platform-audit`.
- **Retention:** default 1y, configurable; hot (Postgres) + cold (S3).
- **Access:** admin-only phase 1.
- **API:** `GET /api/v1/audit-logs` REST + GraphQL; SIEM pull via same endpoint (push deferred).
- **Data export:** three types (executions, workflow/agent configs, billing/usage); CSV; async via `atlas-coordinator`; presigned S3 URLs.

**Modules:** extend `platform-audit-service`; new `platform-audit-rest`, `platform-org-export`.

---

## Epic 3 — App Policies (Governance)

Introduces a **fail-closed policy evaluation pipeline** at every tool/connector invocation.

- **App Rules** — `BLOCK` or `TAG`; `PRE_EXECUTION` and `POST_EXECUTION` phases; targeting org → group → user → agent → specific tool; CEL condition DSL (open question: CEL vs Jexl — see below). Precedence: priority order, first BLOCK wins, all TAGs additive. Enforcement at `ComponentHandler#performAction` in `atlas-worker`.
- **App Claims** — admin OAuths to claim provider workspace; blocks other orgs' OAuth to the same workspace. Requires new `workspaceIdExtractor` SPI on `ConnectionDefinition`.
- **Domain Restrictions (OAuth-level)** — per-app email domain allowlist; rejects OAuth mismatches; applies only to new connections; needs new `emailExtractor` SPI.

**Modules:** new `platform-app-policy`, `platform-app-policy-rest`, `platform-app-policy-cel`; extend `platform-component-api`.

---

## Epic 4 — AI Model Control

- **Allow/deny list** — per org, provider-level bulk + individual model. Fallback model rewrites blocked requests.
- **Org API keys (BYOK)** — override user/workspace keys; OpenAI, Anthropic, Google, Azure OpenAI, DeepSeek, Grok, Bedrock, local (Ollama/vLLM). Encrypted at rest.
- **Proxy routing** — per-org proxy URL per provider for EU routing, egress proxies, model-name mapping.
- **Audit** — admin changes emit audit events; per-call routing via existing ai-gateway observability.

**Modules:** extend `ai-gateway-app`; new `platform-ai-policy`.

---

## Epic 5 — Organization Analytics

- **Metrics:** execution count/duration/cost per workflow/user/project/connection; DAU/WAU/MAU; cost by provider & model; error rate per workflow.
- **Granularity:** per-user, per-workflow, per-project, per-agent, per-connection. Default 90-day window.
- **Surfaces:** React dashboard under `client/`; CSV export; conversational query via `ai-copilot-app`.
- **Access:** admin org-wide; non-admin sees own activity only.

**Modules:** new `platform-analytics`; extend `client/` and `ai-copilot-app`.

---

## Epic 6 — Deployment, Branding & Data Residency

- **On-prem** — existing Docker Compose + Helm; gap: air-gapped bundle target (no runtime registry fetches).
- **Whitelabeling** — env-var-driven branding (`BYTECHEF_BRAND_*`); hide attribution toggle (EE-only).
- **Feature toggles** — per-epic env vars: `BYTECHEF_SSO_ENABLED`, `BYTECHEF_SCIM_ENABLED`, `BYTECHEF_AUDIT_LOGS_ENABLED`, `BYTECHEF_APP_POLICIES_ENABLED`, `BYTECHEF_AI_MODEL_CONTROL_ENABLED`, `BYTECHEF_ANALYTICS_ENABLED`, `BYTECHEF_ORGANIZATIONS_ENABLED`, `BYTECHEF_WHITELABELING_ENABLED`. Each guarded by `@ConditionalOnProperty`.
- **Data residency** — self-hosted = customer responsibility; Cloud EE = regional deployments (US + EU), per-org pinned region, no cross-region movement.
- **Compliance** — SOC 2 Type II control mapping; GDPR right-to-be-forgotten (partially covered by SCIM deprovision).

**Modules:** extend `client/` + Helm charts; add `@ConditionalOnProperty` guards across EE beans.

---

## Cross-cutting

- Every EE feature ships with at least one `bytechef__*` Micrometer counter.
- Every new SPI on a platform module needs a matching `@ConditionalOnEEVersion` stub in the `*-remote-client` module.
- EE license header + `@version ee` Javadoc on every file under `server/ee/`.

---

## Proposed sequencing

1. **Epic 2 (Audit + Export)** — foundation; other epics emit events here.
2. **Epic 1 (IAM)** — unblocks enterprise pilots; SSO is table stakes.
3. **Epic 4 (AI Model Control)** — quick win; extends existing `ai-gateway-app`.
4. **Epic 5 (Analytics)** — depends on §4.6 data pipeline.
5. **Epic 3 (App Policies)** — largest scope; new CEL runtime + SPI extensions.
6. **Epic 6 (Whitelabel + Residency)** — mostly existing infra + config.

---

## Out of scope

- Billing/metering infrastructure (credit system itself).
- Per-region PostgreSQL backup/restore (infra concern).
- Multi-tenant cell isolation (separate security track).
- Mobile clients / mobile SSO.

---

## Open questions

1. **Permission groups — single vs multi:** does ByteChef RBAC already support multi-group membership, or should we enforce one group per user?
2. **App Rules DSL — CEL vs Jexl:** `core-evaluator` already ships Jexl. Build on that or introduce CEL?
3. **Audit retention cold storage:** S3-only or also Postgres partitioned-by-month?
4. **BYOK scope:** "org overrides user" for AI keys only, or all connector credentials?
5. **App Claims offboarding:** who owns the workspace ID record after contract termination?

---