[feature]: Enterprise Features

[ivicac]

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_<feature>_* 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?

---