Workspace settings and entitlements

Tenant Configuration & Feature Entitlements

When to Use

Use when implementing workspace-level settings, tenant feature flags, plan limits/entitlements, custom domains/branding, or tenant-owned third-party integrations (Slack, GitHub, Jira, SSO, webhooks, custom LLM keys).

Layered Configuration Resolution Hierarchy

Resolve workspace settings through a deterministic, traceable precedence chain so every effective value can explain where it came from:

1. Hard System Safety Ceiling (Non-overridable platform security/resource limits, e.g., max upload size ceiling, mandatory rate limits).
2. Tenant / Workspace Override (Explicit admin-configured setting or custom enterprise contract override on the workspace).
3. Plan / Tier Default (Default limit or feature entitlement from the workspace's active subscription tier: Free, Pro, Enterprise).
4. System Default (Codebase fallback constant when no tier or tenant override exists).

Always validate tenant configuration payloads against a strict schema (e.g., Zod / JSON Schema) before saving so a malformed setting in one workspace cannot crash workers or UI rendering.

Separating Plan Entitlements from User Permissions & Runtime Config

• Plan Entitlements (Feature Entitlements & Quotas): Attach entitlements to the workspace / organization (never to an individual user).
• Graceful Plan Downgrade Behavior:
  • When a workspace downgrades from Pro to Free (or a trial expires), define explicit behavior for existing configurations and data that exceed the lower tier's limits (e.g., existing 8 projects remain read-only or accessible while creating project #9 is blocked; premium webhook/SSO settings are disabled cleanly rather than crashing or silently deleting user data).

Tenant-Owned Integration Credentials & Secrets (BYOK / OAuth)

• Strict Tenant Binding: OAuth tokens, webhook signing secrets, SMTP credentials, and Bring-Your-Own-Key (BYOK) API keys must be bound to workspace_id (separate from any user's personal OAuth login connection).
• Envelope Encryption with Tenant AAD:
  • Encrypt tenant secrets at rest (AES-256-GCM / KMS envelope encryption) and bind workspace_id into the Additional Authenticated Data (AAD / encryption context).
  • Binding workspace_id in AAD guarantees that even if an attacker or buggy query copies an encrypted ciphertext blob from Workspace B's row into Workspace A's row, decryption under Workspace A's context fails cryptographically!
• Never Leak Secrets to Frontend or Logs: Return only masked indicators (sk-...9f2a, configured: true, updatedAt) to browser clients.

Config Cache Invalidation & Version Stamps

• Namespace cached workspace settings strictly by tenant:${workspaceId}:config.
• Increment a config_version / updated_at stamp on update and invalidate or publish a cache-bust event immediately so all app nodes and background workers observe security-critical config changes (e.g., IP allowlist, SSO enforcement, revoked integration) without stale-cache delay.