Refactor Platform API + AI Workspace configuration and update documentation

[Thushani-Jayasekera]

Relates to: #2730

Fix Platform API and AI Workspace configuration structure

Summary

This PR is a significant restructuring of the Platform API configuration system and its downstream consumers (AI Workspace BFF, Developer Portal, integration tests, and CI). It fixes key-collision and ergonomics problems in the previous flat config layout, standardizes environment variable prefixes, changes the default authentication mode, and removes a half-finished artifact-limits feature that was never wired up to configuration.

Breaking changes

Compared to upstream/main, existing config.toml / config-template.toml files and env vars for Platform API and AI Workspace need migration:

• Default auth mode changed: auth.jwt.enabled / auth.idp.enabled / auth.file_based.enabled flags are gone, replaced by a single auth.mode selector (external_token | file | idp). The effective default flips from JWT-with-skip_validation=true (i.e. auth effectively disabled) to external_token (signature validation always on).
• auth.jwt.skip_validation removed — JWT signature validation can no longer be bypassed via config.
• Local JWT signing migrated from symmetric HMAC (HS256) to asymmetric RS256. auth.jwt.secret_key (a single shared 32-byte HMAC secret) is replaced by an RSA key pair: auth.jwt.public_key (PEM RSA public key — required in every mode, verifies signatures) and auth.jwt.private_key (PEM RSA private key — required only in file mode, signs login tokens; must match the public key). The Platform API now rejects HMAC (HS256/384/512) and unsigned (none) tokens outright, closing the public-key-as-HMAC-secret forgery class (see authentication_authorization.md GO-AUTH-002). Because PEM keys are multi-line they cannot live in an env-file value: config reads them via {{ file }} (e.g. public_key = '{{ file "/etc/platform-api/keys/jwt_public.pem" }}'), and scripts/setup.sh generates the pair as PEM files rather than writing an env var. Env vars APIP_CP_AUTH_JWT_SECRET_KEY / APIP_DP_PLATFORMAPI_JWTSECRET are gone.
• auth.file_based renamed to auth.file, and its enabled flag removed (selection is via auth.mode=file). [[auth.file_based.users]] → [[auth.file.users]].
• auth.idp.claim_mappings moved and renamed to auth.claim_mappings (now shared across all three auth modes instead of IDP-only). Field names changed: organization_claim_name→organization, org_name_claim_name→org_name, org_handle_claim_name→org_handle, user_id_claim_name→user_id, username_claim_name→username, email_claim_name→email, scope_claim_name→scope, roles_claim_path→roles (now under claim_mappings, not idp).
• auth.idp.role_mappings_file renamed to auth.idp.role_mappings.
• enable_scope_validation moved and renamed to auth.scope_validation.
• Top-level log_level / log_format moved and renamed to logging.level / logging.format under server (matched case-insensitively, lowercase canonical; env vars APIP_CP_LOGGING_LEVEL / APIP_CP_LOGGING_FORMAT).
• http / https listeners moved under server.http / server.https. Listener port fields changed type from string to int (e.g. port = "9243" → port = 9243). https.cert_dir replaced by server.https.cert_file + server.https.key_file (was a directory expected to contain cert.pem/key.pem; now two explicit file paths directly under [server.https]).
• timeouts, cors, websocket moved from the config root under server.timeouts, server.cors, server.websocket.
• websocket.max_connections_per_org removed — no longer configurable/enforced.
• webhook.gateway_type removed — no longer configurable.
• default_devportal config block removed entirely — no replacement.
• artifact_limits config block removed entirely, along with all enforcement of per-organization LLM provider/proxy, MCP proxy, and WebSub/WebBroker API count limits. Any deployment relying on these limits (even though they defaulted to unlimited) has no config-based way to reintroduce them.
• Environment variable prefix standardized to APIP_CP_ — legacy/inconsistent env var names for Platform API config are no longer recognized.
• AI Workspace config keys re-namespaced under a single top-level [ai_workspace] table — any existing AI Workspace config.toml with settings at the root (or under previous per-feature tables) needs to move under [ai_workspace].
• Removed apperror codes LLM_PROVIDER_LIMIT_REACHED, LLM_PROXY_LIMIT_REACHED, MCP_PROXY_LIMIT_REACHED, WEBSUB_API_LIMIT_REACHED, WEBBROKER_API_LIMIT_REACHED — any client code matching on these error codes will no longer see them.
• Developer Portal scripts/setup.sh no longer generates configs/config-platform-api.toml — deployments relying on that generated file must switch to configs/config-platform-api-template.toml with the new platform_api.* / platform_api.auth.file.* structure.

Platform API configuration refactor

• Nested server section: server-level settings (listeners, timeouts, deployments, etc.) are now grouped under a server table instead of living at the config root, avoiding collisions with sibling apps that share a config file.
• auth.mode-driven authentication: replaced the old per-mechanism enabled flags (auth.jwt.enabled, auth.idp.enabled, auth.file_based.enabled) with a single explicit auth.mode selector (jwt | file | idp / external_token), so exactly one mode is active at a time instead of relying on flag combinations.
  • Default mode changed from jwt to external_token.
  • auth.file_based renamed to auth.file.
  • Local JWT signing is now asymmetric RS256 instead of HMAC HS256: JWT.SecretKey → JWT.PublicKey + JWT.PrivateKey (both PEM RSA). validateJWTConfig takes a requireSigningKey flag — verify-only external_token mode needs just the public key; file mode additionally requires the private key and checks the pair matches (priv.PublicKey.Equal(pub)). internal/middleware/auth.go now verifies with jwt.WithValidMethods(["RS256","RS384","RS512"]) and rejects any non-RSA method (blocks none and the public-key-as-HMAC forgery); internal/handler/auth_login.go signs login tokens with SigningMethodRS256. internal/server/server.go parses the PEM public key once at startup and passes an *rsa.PublicKey into the middleware. Added a TODO(pqc) on the JWT struct — RS256 is quantum-vulnerable and should move to ML-DSA (FIPS 204) once a Go JWT library exposes it.
  • IDPClaimMappings fields renamed (OrganizationClaimName → Organization, OrgNameClaimName → OrgName, OrgHandleClaimName → OrgHandle, UserIDClaimName → UserID, UsernameClaimName → Username, EmailClaimName → Email, ScopeClaimName → Scope) and support dot-separated nested claim paths, not just top-level claims — internal/middleware/auth.go's extractClaimByPath/getStringClaim now resolve arbitrary nested claim paths (resolveClaimPath) instead of a single-level map lookup.
  • EnableScopeValidation moved into Auth.ScopeValidation.
• HTTP/HTTPS listeners restructured under server.http / server.https (ServerListeners), TLS cert/key paths now explicit cert_file / key_file (fields HTTPSListener.CertFile / KeyFile, directly on the HTTPS listener — no nested tls sub-table) instead of a CertDir, and listener ports are now typed as integers instead of strings. The Logging struct fields are Level / Format (keys level / format).
• Environment variable prefix standardized to APIP_CP_ across README, config template, and config loader — legacy variable names removed.
• DefaultDevPortal config block removed — dead/unused config surface.
• Artifact/resource limits removed: ArtifactLimits config, config.LimitReached, and all per-organization creation-limit enforcement (LLM providers, LLM proxies, MCP proxies, WebSub APIs, WebBroker APIs) have been deleted from internal/service/llm.go, internal/service/mcp.go, and the event-gateway plugin, along with their associated apperror codes/catalog entries (*LimitReached) and tests. This functionality was never actually configurable (limits were unlimited by default and no config surface existed to set them), so it was removed rather than fixed.
• internal/constants/constants.go: removed a stale comment referencing the deleted artifact-limits mechanism; formatting fix in PolicyManagedBy* constants.
• resources/roles.yaml: updated to match the new auth/scopes structure.
• Added internal/middleware/auth_role_extraction_test.go covering nested claim path extraction.
• internal/server/server.go, cmd/main.go: updated to build listeners/auth from the new config shape.

AI Workspace (BFF + portal) configuration refactor

• All AI Workspace settings consolidated under a single top-level [ai_workspace] table in config-template.toml / config.toml, mirroring the Platform API's nested structure and preventing key collisions when the AI Workspace and Platform API share a config file.
• BFF config loader restructured across bff/internal/config/: config.go (nested Config struct + Load/normalize/validate), a new default_config.go (defaultConfig()), settings.go (now just the koanf loader loadConfigKoanf), and runtime_config.go (browser-safe allowlist read from the koanf instance).
• BFF config loader migrated to koanf v2 (providers/file + parsers/toml/v2 + providers/confmap), matching the Gateway and Platform API; the hand-rolled stdlib TOML-subset parser (toml.go + its test) and the settings-map/get* facade were removed. config.go is now shaped like the Platform API's: a nested koanf-tagged Config mirroring the [ai_workspace.*] tables, with defaultConfig() → Unmarshal → normalize() → validate(). Logging keys renamed to [ai_workspace.logging] level / format, the listener moved to [ai_workspace.server.https] with an integer port and inline cert_file / key_file. See the cross-product review §3, §5, §7 below.
• portals/ai-workspace/src/config.env.ts, vite.config.ts: adjusted for the new config shape.
• Documentation updated across docs/ai-workspace/configuration.md, docs/ai-workspace/authentication/{README,asgardeo-setup,file-based-auth,oidc-auth}.md, portals/ai-workspace/README.md, portals/ai-workspace/distribution/README.md, and portals/ai-workspace/production/README.md to reflect the new namespacing and env var usage.
• portals/ai-workspace/Makefile, docker-compose.yaml: updated for the new config/env layout.

Developer Portal integration

• Removed the generated configs/config-platform-api.toml provisioning step from scripts/setup.sh (previously hand-rolled a Platform API config with hardcoded admin scopes and legacy [auth.jwt] / [auth.idp] / [auth.file_based] keys) in favor of the new config-platform-api-template.toml, which now uses the nested platform_api.* / platform_api.auth.file.* structure.
• scripts/setup.sh now provisions the RS256 JWT keypair (openssl genpkey → resources/keys/jwt_private.pem + jwt_public.pem, idempotent, 644 like the TLS cert) instead of generating a shared HMAC secret into api-platform.env. docker-compose.yaml mounts resources/keys into the platform-api container at /etc/platform-api/keys (on its {{ file }} allowlist), and platform-api/config/config.toml reads the pair via public_key/private_key = '{{ file "/etc/platform-api/keys/jwt_*.pem" }}'.
• docker-compose.platform-api.yaml, docker-compose.yaml, it/configs/config-platform-api-it.toml, it/docker-compose.test.{postgres,yaml}: updated to the new config structure and to support pointing at a freshly built platform-api image via PLATFORM_API_IMAGE.
• .gitignore: removed now-unnecessary entry for the deleted generated config file.

CI

• .github/workflows/devportal-integration-test.yml: added a step to build the platform-api image before running Developer Portal REST API and Cypress integration tests, and wired PLATFORM_API_IMAGE through so the tests exercise the freshly built image instead of a stale/pulled one.
• internal/integration/harness_test.go, tests/integration-e2e/platform-api-config.toml: test fixtures updated to the new nested config format (including switching to external_token auth mode).
• go.work.sum: new transitive dependencies pulled in (aws/smithy-go, coreos/go-oidc/v3, prometheus/otlptranslator, google.golang.org/genproto).

Documentation

• platform-api/README.md: substantially rewritten — documents the new auth.mode selector, local-development quickstart using config/config.toml, and the APIP_CP_ env var convention.
• platform-api/config/config.toml, config-template.toml: comments clarified and restructured to match the new nested layout.

Testing

• config/config_test.go, bff/internal/config/config_test.go, bff/internal/config/shipped_config_test.go, internal/server/server_tls_test.go, internal/handler/llm_provider_integration_test.go, bff/internal/server/composite_handlers_test.go updated for the new config shape and the removal of artifact limits.
• bff/internal/config/toml_test.go deleted along with the hand-rolled toml.go parser it covered (AI Workspace now parses TOML via koanf — see the cross-product review §7).

Notes for reviewers

• The default auth mode change (jwt → external_token) and the auth.file_based → auth.file rename are breaking changes for anyone with an existing config file — worth confirming migration guidance is adequate in the updated READMEs.
• Artifact/resource limit enforcement (LLM provider/proxy, MCP proxy, WebSub/WebBroker API counts) has been fully removed rather than made configurable; flag if this should instead be reintroduced behind real config once there's a concrete requirement.

---

Cross-Product Configuration Consistency Review

The API Platform ships four separately-deployable products that are meant to be wired together into one system:

1. Gateway — Go: gateway-controller + gateway-runtime/policy-engine + router (share one config.toml), plus the build-time gateway-builder.
2. Platform API (control plane) — Go.
3. AI Workspace — Go BFF + React/Vite SPA.
4. Developer Portal — Node.js / Express.

This section reviews how consistent their configuration systems are with each other, and where the biggest wins are for making them feel like one platform. It is descriptive of the current state of the fix-configs branch — the Platform API / AI Workspace refactor above already closes several of the gaps that used to exist (e.g. single-table namespacing, int ports, logging/TLS key alignment).

Overall consistency scorecard

Dimension	Gateway	Platform API	AI Workspace	Dev Portal	Verdict
File format	TOML	TOML	TOML	TOML	✅ Consistent
config.toml + config-template.toml pattern	✅	✅	✅	✅	✅ Consistent
Config parser / loader	koanf v2	koanf v2	koanf v2	smol-toml + JS loader	✅ All three Go services on koanf v2 (JS loader for Dev Portal)
Env var prefix	APIP_GW_	APIP_CP_	APIP_AIW_	APIP_DP_	✅ Scheme consistent (see naming note)
Env → config mechanism	automatic prefix overlay + {{ env }}	{{ env }} tokens only	{{ env }} tokens only	{{ env }} tokens only	❌ Gateway diverges
Interpolation contract ({{ env }} / {{ file }})	✅ shared Go lib	✅ shared Go lib	✅ shared Go lib	✅ JS re-impl, same contract	✅ Consistent
{{ file }} allowlist (/etc/<p>, /secrets/<p>, 1 MiB, APIP_CONFIG_FILE_SOURCE_ALLOWLIST)	✅	✅	✅	✅	✅ Consistent
Single product-scoped top-level table	❌ many roots	✅ [platform_api]	✅ [ai_workspace]	❌ bare roots	⚠️ 2/4
Logging key names	level / format	level / format	level / format	console_only (+ LOG_LEVEL env)	⚠️ Dev Portal only (fixed for PA + AIW)
Auth mode selection	enabled flags	mode selector	mode selector	implicit (empty clientId)	❌ 3 models
TLS cert/key key names	cert_path / key_path	cert_file / key_file	cert_file / key_file	cert_file / key_file	❌ Gateway diverges
DB selector / keys	type, path, user, sslmode	driver, path, user, ssl_mode	(no DB)	type, file, username, ssl.*	❌ Divergent (PA + Gateway agree on user)
Required-secret fail-closed philosophy	✅	✅	✅	✅	✅ Consistent

Bottom line: the products are strongly consistent on the outer contract (TOML, the template pattern, the {{ env }} / {{ file }} interpolation and its allowlist/size rules, the APIP_<product>_ prefix family, and fail-closed required secrets) but inconsistent on the inner details — the env-override model, top-level namespacing, and the actual key names for logging, auth, TLS, and database.

What is consistent (keep it this way)

• One file format and one template convention. Every product uses TOML with a shipped minimal config.toml plus a fully-documented config-template.toml whose defaults double as reference. This is a genuinely good shared idiom.
• Interpolation contract. {{ env "VAR" "default" }} and {{ file "/path" }} behave identically everywhere: a defaultless {{ env }} and any {{ file }} fail closed at startup; the file allowlist defaults to /etc/<product> and /secrets/<product>, caps reads at 1 MiB, guards against traversal/null-byte/symlink-TOCTOU, and is overridable via the single shared APIP_CONFIG_FILE_SOURCE_ALLOWLIST. The three Go services literally share common/configinterpolate; the Dev Portal re-implements the same contract in JS. Resolved secret values are never logged in any product.
• Env prefix family. APIP_GW_ / APIP_CP_ / APIP_AIW_ / APIP_DP_ all follow one APIP_<product>_ shape.
• Secrets are fail-closed and never inlined. Encryption keys, JWT signing secrets, OIDC client secrets, and control-plane tokens are all required via {{ env }} / {{ file }} with no insecure default.
• Platform API ↔ AI Workspace claim mappings are mirrored key-for-key (organization, org_name, org_handle, username, email, scope, roles), which is exactly right given the BFF reads back the HMAC JWT the Platform API signs in file/basic mode.

Where they diverge (and where to improve)

1. Env-override model — the sharpest inconsistency

The Gateway (koanf env.Provider) has an automatic overlay: any APIP_GW_CONTROLLER_LOGGING_LEVEL maps to controller.logging.level with no token needed in the file. The other three have no automatic overlay — an env var only takes effect where the TOML explicitly writes {{ env "NAME" }}. (The Dev Portal even removed its old APIP_DP_* auto-mapping on purpose.)

Consequence: APIP_GW_* "just works" against any key, while APIP_CP_* / APIP_AIW_* / APIP_DP_* only work for keys the template author remembered to tokenize. Two different mental models for operators of the same platform. A visible symptom: docker-compose.postgres.yaml sets APIP_DP_DATABASE_HOST/PORT/... but the shipped Dev Portal config.toml only references APIP_DP_DATABASE_FILE, so those vars are silently inert. (The old symptom where scripts/setup.sh had to write the same HMAC secret under two env names — APIP_CP_AUTH_JWT_SECRET_KEY and APIP_DP_PLATFORMAPI_JWTSECRET — is now gone with the RS256 migration: signing material is an RSA PEM key pair provisioned as mounted files, so there is no shared secret to copy between services.)

Improve: pick one model platform-wide. The token model is the more auditable/secure one (explicit, greppable, no accidental binding) and is already the majority — consider aligning the Gateway onto it (or at least documenting the Gateway's automatic overlay as a deliberate exception).

2. Top-level namespacing

Platform API ([platform_api]) and AI Workspace ([ai_workspace]) now nest everything under one product table — specifically so they can safely share one config.toml (the AI Workspace compose already mounts Platform API's own config.toml). The Gateway spreads across many roots (controller, router, policy_engine, collector, analytics, tracing, …) and the Dev Portal uses bare roots (server, tls, logging, database, idp, …). If the intent is that connected products can co-habit a config file, the two un-namespaced products break that guarantee (e.g. both define a top-level [server] / logging).

Improve: wrap Dev Portal under [developer_portal] and (longer-term) the Gateway components under a [gateway] umbrella, matching the Platform API / AI Workspace precedent.

3. Logging keys and level casing

Previously: level / format (Gateway) vs log_level / log_format (Platform API, AI Workspace) vs console_only with the actual level coming from a bare LOG_LEVEL env var (Dev Portal). Level value casing also differed: Platform API expected UPPERCASE (INFO), the others lowercase (info).

Done (this branch): Platform API and AI Workspace now use [logging] level / format — matching the Gateway's existing key names — parsed case-insensitively with lowercase as canonical (info, text). The env-var tokens moved to the path convention (APIP_CP_LOGGING_LEVEL / APIP_CP_LOGGING_FORMAT, APIP_AIW_LOGGING_LEVEL / APIP_AIW_LOGGING_FORMAT). Platform API's default dropped from INFO→info; its startup validator now reports the logging.level / logging.format key names.

Still open: the Dev Portal keeps console_only + the out-of-band LOG_LEVEL env (left for a follow-up — giving it a real logging.level key means wiring the Winston logger through the config loader).

4. Auth mode selection and vocabulary

Four different selection models: Gateway uses enabled flags, Platform API and AI Workspace use a mode selector, and the Dev Portal infers local-vs-OIDC from whether idp.clientId is empty. Worse, the two mode-based products use different words for the same pairing: Platform API file / idp / external_token vs AI Workspace basic / oidc, even though file↔basic and idp↔oidc are meant to line up. Claim-mapping keys also split: Platform API/AI Workspace share the full 7-key set, while the Dev Portal uses a different, smaller idp.claims (role, orgId, groups) and the Gateway management API uses roles_claim.

Improve: adopt one auth.mode selector everywhere with one shared vocabulary, and reconcile the Dev Portal / Gateway claim-mapping keys onto the Platform API set.

5. TLS and server-listener keys

Previously: TLS cert/key were cert_file / key_file in Platform API, AI Workspace, and Dev Portal, but cert_path / key_path in the Gateway router. Listener shapes also differed: Platform API server.http/server.https with enabled + int port (with cert/key under a nested server.https.tls); Gateway router with listener_port / https_port / https_enabled; AI Workspace a single server.port string.

Done (this branch): AI Workspace now follows the platform listener shape — [ai_workspace.server.https] with enabled + an integer port (an int field koanf unmarshals into, replacing the former string port). The nested .tls subtable was dropped on both products: cert_file / key_file now sit directly under [server.https] (there is no ambiguity to disambiguate — an HTTPS listener implies TLS), so the shape is [server.https] enabled / port / cert_file / key_file for both Platform API and AI Workspace. cert_file / key_file (not cert_path / key_path) is confirmed as the standard — it matches OpenSSL's SSL_CERT_FILE and Go's tls.LoadX509KeyPair(certFile, keyFile). Env tokens follow suit (APIP_CP_SERVER_HTTPS_CERT_FILE, APIP_AIW_SERVER_HTTPS_PORT, …).

Note on the flatten: the Gateway's own TLS blocks are not a single pattern — [controller.policy_server.tls] uses a nested .tls subtable with cert_file / key_file, while [router.downstream_tls] uses a separate table with cert_path / key_path. The flattened [server.https] cert_file/key_file here deliberately favors simplicity (an HTTPS listener implies TLS) over mirroring the Gateway's nested policy_server.tls shape.

Still open: the Gateway router (cert_path / key_path, listener_port / https_port / https_enabled — an Envoy/xDS listener) is intentionally out of scope for this branch; aligning it touches the xDS translator, validation, and existing env vars.

6. Database keys

The most scattered area. Selector: type (Gateway, Dev Portal) vs driver (Platform API). SQLite path: path (Gateway, Platform API) vs file (Dev Portal). DB name: database (Gateway) vs name (Platform API, Dev Portal). SSL: sslmode string vs ssl_mode string vs a nested ssl.enabled + ssl.caFile bool object. The DB user key is now user in both Platform API and the Gateway (Platform API's earlier username rename was reverted — user is the DB-standard name, matching the PostgreSQL DSN user= / PGUSER); the Dev Portal still uses username.

Improve: define one shared DB block schema (driver, path, host, port, name, user, password, ssl_mode, ssl_root_cert) and adopt it across the three data-storing products.

7. Config parser divergence

Previously: koanf v2 (Gateway, Platform API), a hand-rolled stdlib TOML-subset parser (AI Workspace BFF), and smol-toml (Dev Portal).

Done (this branch): the AI Workspace BFF now loads config through koanf v2 (providers/file + parsers/toml/v2 + providers/confmap), the same stack as the Gateway and Platform API, and its config.go is now structured like the Platform API's: a nested koanf-tagged Config whose shape mirrors the [ai_workspace.*] TOML tables, populated by a defaultConfig() overlaid with UnmarshalWithConf (WeaklyTypedInput + a duration decode hook), then a normalize() step for derived fields (Addr(), trimmed URLs, oidc-mode⇒enabled, cookie constants) and a validate() step for fail-closed checks. The hand-rolled parser (toml.go) and the entire settings map + get/getbool/getint/getdur facade were removed; browser-only passthrough keys (domain, gateway.*, moesif_*, …) are read straight from the parsed koanf instance in buildRuntimeConfig, preserving the file-present-only semantics of the SPA allowlist. {{ env }} / {{ file }} interpolation continues through the shared configinterpolate library. All three Go services now share one config library and the same load→default→unmarshal→validate shape; only the Dev Portal keeps a JS loader (smol-toml), which is unavoidable cross-language.

Trade-off accepted: koanf's go-toml parser is more permissive than the removed subset parser — it silently accepts arrays, arrays-of-tables, dotted/quoted keys, and duplicate keys that the old parser refused with a line-numbered error. This drops a deliberate fail-closed-on-unknown-construct property in exchange for one shared library; the AI Workspace config uses none of those constructs, so no shipped config is affected.

8. Minor / latent

• AI Workspace SPA OIDC var names are un-migrated. src/config.env.ts still reads APIP_AIW_OIDC_AUTHORITY / _CLIENT_ID / _REDIRECT_URI / _POST_LOGOUT_REDIRECT_URI, while the BFF and template use the consolidated APIP_AIW_AUTH_OIDC_* names. Since the BFF owns the OIDC handshake these SPA vars are likely vestigial, but they are a naming mismatch introduced/left on this branch — worth removing or renaming.
• Prefix semantics. Platform API's prefix is APIP_CP_ ("control plane"), not APIP_PA_/APIP_API_; harmless but a small surprise relative to the product name.

Suggested priority order

1. Unify the env-override model (§1) — highest operator-facing impact; removes the double-write secret coupling and the silently-inert-var footgun.
2. Standardize DB, logging, TLS, and auth key names (§3–§6) — a shared "config vocabulary" doc plus renames; mechanical but high-value for a connected platform. (Logging §3 and TLS/listener §5 are done for Platform API + AI Workspace on this branch; Dev Portal logging, the Gateway router listener, DB §6, and auth §4 remain.)
3. Namespace the Dev Portal (and Gateway) under a product table (§2) — needed if products are ever meant to share a config file.
4. Consolidate on koanf for all Go services (§7) — done on this branch (AI Workspace BFF migrated to koanf v2). Fix the SPA OIDC var names (§8) remains.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Platform API configuration is moved under platform_api with mode-based authentication, grouped listeners, explicit TLS paths, and expanded validation. AI Workspace configuration is scoped under ai_workspace, portal packaging uses revised config paths, and per-organization artifact quotas and related errors are removed.

Changes

Configuration and startup migration

Layer / File(s)	Summary
Configuration contracts and validation platform-api/config/*, tests/integration-e2e/*	Configuration types, defaults, loading, validation, templates, fixtures, and tests adopt namespaced authentication, database, listener, timeout, and logging models.
Startup, authentication, and TLS wiring platform-api/cmd/main.go, platform-api/internal/server/*, platform-api/internal/handler/auth_login.go	Startup consumes grouped listeners, auth selection uses auth.mode, JWT expiry uses TokenTTL, and TLS loads explicit certificate and key files.
Portal configuration and packaging platform-api/README.md, portals/developer-portal/*, portals/ai-workspace/*, docs/ai-workspace/*	Portal templates, compose files, setup scripts, distribution builds, and documentation use scoped configuration and shared or packaged Platform API config paths.
AI Workspace configuration scoping portals/ai-workspace/bff/internal/config/*, portals/ai-workspace/configs/*	AI Workspace settings and OIDC mappings move under [ai_workspace], and the BFF resolves configuration relative to that table.
Nested claim extraction platform-api/internal/middleware/*	JWT claim extraction supports dot-separated paths for nested claim objects, with table-driven coverage for missing and invalid paths.

Artifact quota removal

Layer / File(s)	Summary
Quota enforcement removal platform-api/internal/service/*, platform-api/plugins/eventgateway/*, platform-api/internal/apperror/*, platform-api/internal/constants/constants.go	LLM, MCP, WebSub, and WebBroker creation flows no longer enforce per-organization limits, and corresponding limit-reached errors and constants are removed.
Quota-related test updates platform-api/internal/handler/llm_provider_integration_test.go, platform-api/internal/service/llm_test.go	LLM test setup no longer configures artifact limits, the limit-reached integration test is removed, and provider/proxy behavior coverage is expanded.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• wso2/api-platform#2507: Both changes modify the Platform API apperror catalog and related limit-reached codes.
• wso2/api-platform#2571: Both changes modify Platform API listener and TLS startup wiring.
• wso2/api-platform#2642: Both changes modify AI Workspace configuration scoping, interpolation, and runtime configuration allowlists.

Suggested reviewers: pubudu538, malinthaprasan, renuka-fernando, krishanx92, anugayan

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed but does not follow the required template; key sections like Purpose, Goals, Approach, Security checks, and Test environment are missing.	Rewrite the PR description using the repository template and add the missing sections, including Purpose, Goals, Approach, User stories, Security checks, Samples, Related PRs, and Test environment.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 84.34% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main Platform API and AI Workspace config refactor and docs updates.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

platform-api/README.md (1)

262-278: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Remove the stale skip_validation docs from Local JWT Mode.
skip_validation is no longer plumbed through config, and the server hardcodes SkipValidation: false. The README still advertises auth.jwt.skip_validation, APIP_CP_AUTH_JWT_SKIP_VALIDATION, and the skip_validation = true example, which operators can’t actually use. Please delete those references.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@platform-api/README.md` around lines 262 - 278, Remove the stale
skip_validation documentation from the Local JWT Mode section: delete the
auth.jwt.skip_validation explanation, the APIP_CP_AUTH_JWT_SKIP_VALIDATION table
entry, and the skip_validation=true example. Preserve the remaining JWT secret
and issuer documentation and local startup instructions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@platform-api/config/config.toml`:
- Around line 15-18: Update the configuration header comment to reference the
namespaced platform_api tables for auth mode and file-based organization/users
settings, matching the sections consumed by the loader; change only the stale
section names while preserving the existing guidance and config-template
reference.

---

Outside diff comments:
In `@platform-api/README.md`:
- Around line 262-278: Remove the stale skip_validation documentation from the
Local JWT Mode section: delete the auth.jwt.skip_validation explanation, the
APIP_CP_AUTH_JWT_SKIP_VALIDATION table entry, and the skip_validation=true
example. Preserve the remaining JWT secret and issuer documentation and local
startup instructions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 56c3ad68-011c-48b9-b10e-3be164cd53e1

📥 Commits

Reviewing files that changed from the base of the PR and between e120696 and 4fa30f9.

📒 Files selected for processing (26)

• platform-api/README.md
• platform-api/cmd/main.go
• platform-api/config/config-template.toml
• platform-api/config/config.go
• platform-api/config/config.toml
• platform-api/config/config_test.go
• platform-api/config/default_config.go
• platform-api/internal/apperror/catalog.go
• platform-api/internal/apperror/codes.go
• platform-api/internal/constants/constants.go
• platform-api/internal/handler/auth_login.go
• platform-api/internal/handler/llm_provider_integration_test.go
• platform-api/internal/server/server.go
• platform-api/internal/server/server_tls_test.go
• platform-api/internal/service/llm.go
• platform-api/internal/service/llm_test.go
• platform-api/internal/service/mcp.go
• platform-api/plugins/eventgateway/plugin.go
• platform-api/plugins/eventgateway/service/webbroker_api.go
• platform-api/plugins/eventgateway/service/websub_api.go
• portals/ai-workspace/configs/config-platform-api.toml
• portals/ai-workspace/configs/config-template.toml
• portals/developer-portal/configs/config-platform-api-template.toml
• portals/developer-portal/it/configs/config-platform-api-it.toml
• portals/developer-portal/scripts/setup.sh
• tests/integration-e2e/platform-api-config.toml

💤 Files with no reviewable changes (8)

• portals/ai-workspace/configs/config-platform-api.toml
• portals/ai-workspace/configs/config-template.toml
• portals/developer-portal/configs/config-platform-api-template.toml
• platform-api/internal/service/mcp.go
• platform-api/plugins/eventgateway/service/webbroker_api.go
• platform-api/plugins/eventgateway/service/websub_api.go
• platform-api/internal/service/llm.go
• platform-api/internal/service/llm_test.go

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@platform-api/config/config.go`:
- Around line 105-130: Replace HMAC-based JWT configuration and validation with
asymmetric public/private key material, explicitly rejecting symmetric and
unsigned algorithms throughout the external_token and file authentication flows.
In platform-api/config/config.go lines 105-130, redesign Auth/JWT to reference
asymmetric keys; update platform-api/config/config.go lines 537-544 to validate
the required key material and matching pair; revise
platform-api/config/config_test.go lines 160-165 for the new requirements;
update platform-api/README.md lines 276-283 and
portals/developer-portal/README.md lines 232-235 to document asymmetric key
configuration and remove shared-secret guidance, using the required approved
signature primitive where applicable.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 314e1989-42b6-436a-ae58-ecc63a41b2e5

📥 Commits

Reviewing files that changed from the base of the PR and between 4fa30f9 and 369a38a.

⛔ Files ignored due to path filters (1)

• go.work.sum is excluded by !**/*.sum

📒 Files selected for processing (18)

• platform-api/README.md
• platform-api/config/config-template.toml
• platform-api/config/config.go
• platform-api/config/config.toml
• platform-api/config/config_test.go
• platform-api/config/default_config.go
• platform-api/internal/server/server.go
• platform-api/internal/service/llm.go
• portals/ai-workspace/Makefile
• portals/ai-workspace/README.md
• portals/ai-workspace/docker-compose.yaml
• portals/ai-workspace/production/README.md
• portals/developer-portal/.gitignore
• portals/developer-portal/Makefile
• portals/developer-portal/README.md
• portals/developer-portal/docker-compose.platform-api.yaml
• portals/developer-portal/docker-compose.yaml
• portals/developer-portal/scripts/setup.sh

💤 Files with no reviewable changes (3)

• portals/developer-portal/.gitignore
• platform-api/internal/service/llm.go
• portals/developer-portal/scripts/setup.sh

🚧 Files skipped from review as they are similar to previous changes (4)

• platform-api/config/config.toml
• platform-api/config/default_config.go
• platform-api/config/config-template.toml
• platform-api/internal/server/server.go

[Thushani-Jayasekera]

@Piumal1999
platform-api → [server.http] + [server.https] nested sections; each has enabled + port (int); both can run concurrently (Kestrel/Traefik/Quarkus pattern)

[tls].ca_file --> Keep devportal-only (used for optional mTLS in server.js). NOT added to platform-api — no mTLS on its listener; add later if mTLS lands

Replace all three enabled flags with single [auth].mode = "file" | "idp". Comment: modes are mutually exclusive by design — the current code needs validateAuthModeExclusivity purely to reject both-enabled configs. A discriminated union (mode selector + one section per mode) makes that invalid state inexpressible, same pattern as database.driver. Industry precedent: Harbor auth_mode (database|ldap_auth|oidc_auth), Vault storage stanzas. Per-provider enabled flags (Grafana, k8s API server) are for CONCURRENT providers — not our semantics

platform-api: enabled flag removed — active when auth.mode = "idp"; section stays at [auth.idp] (NOT moved to top-level [idp]). Comment: devportal's [idp] is OAuth relying-party client config (client_id, callbacks, silent SSO) — a different thing from platform-api's token-verification config; forcing one shape was surface-level unification. Claim-mapping key NAMES still align (that's where consistency pays off)

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/ai-workspace/authentication/asgardeo-setup.md (1)

119-137: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Obsolete Platform API configuration structure in documentation.

The Platform API configuration was significantly refactored to use a [platform_api] root table, a [platform_api.server.https] listener section, and a mutually exclusive mode discriminator for authentication (e.g., mode = "idp"), which replaces the individual [auth.*] enabled = ... flags. However, several AI Workspace documentation files were not updated and still show the obsolete schema for the Platform API.

Please update the following locations to reflect the new [platform_api] root table and mode configuration:

• docs/ai-workspace/authentication/asgardeo-setup.md#L119-L137: Update the TOML snippet to use [platform_api.auth] and mode = "idp".
• docs/ai-workspace/authentication/oidc-auth.md#L76-L116: Update the TOML snippets to use [platform_api.auth] and mode = "idp".
• docs/ai-workspace/configuration.md#L142-L160: Update the TOML snippet to use [platform_api.auth] and mode = "idp".
• portals/ai-workspace/distribution/README.md#L96-L101: Update the table to list the namespaced keys (e.g., [platform_api.database].driver, [platform_api.server.https], and [platform_api.auth.idp]).
• portals/ai-workspace/distribution/README.md#L135-L135: Revise the instructions that tell users to set enabled = true and [auth.file_based].enabled = false.
• portals/ai-workspace/production/README.md#L115-L124: Update the TOML snippet from [auth.idp] to [platform_api.auth.idp].
• portals/ai-workspace/README.md#L307-L309: Revise the text mentioning APIP_CP_AUTH_JWT_ENABLED=false and APIP_CP_AUTH_FILE_BASED_ENABLED=false.
• portals/ai-workspace/README.md#L319-L337: Update the TOML snippet to use [platform_api.auth] and mode = "idp".
• portals/ai-workspace/README.md#L371-L374: Revise the troubleshooting table row that references auth.jwt.enabled and APIP_CP_AUTH_JWT_ENABLED=false.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ai-workspace/authentication/asgardeo-setup.md` around lines 119 - 137,
Replace the obsolete Platform API authentication documentation with the new
[platform_api] schema: use [platform_api.auth] with mode = "idp" and namespace
nested settings under [platform_api.auth.idp], [platform_api.database], and
[platform_api.server.https] as applicable. Apply this consistently in
docs/ai-workspace/authentication/asgardeo-setup.md (119-137),
docs/ai-workspace/authentication/oidc-auth.md (76-116),
docs/ai-workspace/configuration.md (142-160),
portals/ai-workspace/distribution/README.md (96-101 and 135),
portals/ai-workspace/production/README.md (115-124), and
portals/ai-workspace/README.md (307-309, 319-337, and 371-374); revise legacy
enabled-flag and environment-variable references to describe the mode-based
configuration.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@platform-api/internal/integration/harness_test.go`:
- Line 53: Update the generated configuration in the harness test’s fmt.Fprintf
call to remove the obsolete auth.jwt enabled flag and explicitly set the
mutually exclusive [platform_api.auth] mode selector to the intended JWT mode,
while preserving the existing secret_key and encryption_key values.

---

Outside diff comments:
In `@docs/ai-workspace/authentication/asgardeo-setup.md`:
- Around line 119-137: Replace the obsolete Platform API authentication
documentation with the new [platform_api] schema: use [platform_api.auth] with
mode = "idp" and namespace nested settings under [platform_api.auth.idp],
[platform_api.database], and [platform_api.server.https] as applicable. Apply
this consistently in docs/ai-workspace/authentication/asgardeo-setup.md
(119-137), docs/ai-workspace/authentication/oidc-auth.md (76-116),
docs/ai-workspace/configuration.md (142-160),
portals/ai-workspace/distribution/README.md (96-101 and 135),
portals/ai-workspace/production/README.md (115-124), and
portals/ai-workspace/README.md (307-309, 319-337, and 371-374); revise legacy
enabled-flag and environment-variable references to describe the mode-based
configuration.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4a8627bd-da83-4a57-8d55-a6228a6a8b35

📥 Commits

Reviewing files that changed from the base of the PR and between 369a38a and 0f954c4.

⛔ Files ignored due to path filters (1)

• go.work.sum is excluded by !**/*.sum

📒 Files selected for processing (14)

• docs/ai-workspace/authentication/asgardeo-setup.md
• docs/ai-workspace/authentication/oidc-auth.md
• docs/ai-workspace/configuration.md
• platform-api/README.md
• platform-api/config/config.toml
• platform-api/internal/integration/harness_test.go
• portals/ai-workspace/README.md
• portals/ai-workspace/bff/internal/config/config_test.go
• portals/ai-workspace/bff/internal/config/settings.go
• portals/ai-workspace/bff/internal/config/shipped_config_test.go
• portals/ai-workspace/configs/config-template.toml
• portals/ai-workspace/configs/config.toml
• portals/ai-workspace/distribution/README.md
• portals/ai-workspace/production/README.md

🚧 Files skipped from review as they are similar to previous changes (2)

• platform-api/config/config.toml
• platform-api/README.md

[renuka-fernando]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

platform-api/internal/server/server.go (1)

550-559: 🔒 Security & Privacy | 🔴 Critical | 🏗️ Heavy lift

Reject symmetric JWT signature algorithms.

As per coding guidelines, you must allow only asymmetric signing methods (such as RSA-PSS or EdDSA) for JWT signature verification and explicitly reject symmetric algorithms (like HMAC) and none. The current logic explicitly enables HMAC validation and relies on a shared SecretKey.

Please update the authentication configuration and LocalJWTAuthMiddleware to enforce an asymmetric algorithm and verify tokens using a public key instead of a shared secret.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@platform-api/internal/server/server.go` around lines 550 - 559, Update the
non-IDP authentication setup in the server flow and LocalJWTAuthMiddleware
configuration to reject HMAC and none algorithms, allow only the approved
asymmetric JWT signing methods, and validate tokens with the configured public
key rather than Auth.JWT.SecretKey. Preserve issuer and skip-path settings while
ensuring unsupported algorithms are explicitly rejected.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@platform-api/internal/server/server.go`:
- Around line 550-559: Update the non-IDP authentication setup in the server
flow and LocalJWTAuthMiddleware configuration to reject HMAC and none
algorithms, allow only the approved asymmetric JWT signing methods, and validate
tokens with the configured public key rather than Auth.JWT.SecretKey. Preserve
issuer and skip-path settings while ensuring unsupported algorithms are
explicitly rejected.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a39ecc04-8d17-4ef1-be83-8ea05ef367c2

📥 Commits

Reviewing files that changed from the base of the PR and between ddd2079 and c9028d6.

📒 Files selected for processing (31)

• docs/ai-workspace/authentication/asgardeo-setup.md
• docs/ai-workspace/authentication/oidc-auth.md
• docs/ai-workspace/configuration.md
• platform-api/README.md
• platform-api/config/config-template.toml
• platform-api/config/config.go
• platform-api/config/default_config.go
• platform-api/internal/middleware/auth.go
• platform-api/internal/middleware/auth_role_extraction_test.go
• platform-api/internal/server/server.go
• platform-api/resources/roles.yaml
• portals/ai-workspace/Makefile
• portals/ai-workspace/README.md
• portals/ai-workspace/VERSION
• portals/ai-workspace/bff/internal/config/config.go
• portals/ai-workspace/bff/internal/config/config_test.go
• portals/ai-workspace/bff/internal/config/runtime_config.go
• portals/ai-workspace/bff/internal/config/settings.go
• portals/ai-workspace/bff/internal/config/shipped_config_test.go
• portals/ai-workspace/bff/internal/config/toml_test.go
• portals/ai-workspace/bff/internal/proxy/transport.go
• portals/ai-workspace/bff/internal/server/composite_handlers.go
• portals/ai-workspace/bff/internal/server/composite_handlers_test.go
• portals/ai-workspace/bff/internal/server/server.go
• portals/ai-workspace/bff/main.go
• portals/ai-workspace/configs/config-template.toml
• portals/ai-workspace/configs/config.toml
• portals/ai-workspace/distribution/README.md
• portals/ai-workspace/production/README.md
• portals/ai-workspace/src/config.env.ts
• portals/ai-workspace/vite.config.ts

🚧 Files skipped from review as they are similar to previous changes (9)

• docs/ai-workspace/authentication/oidc-auth.md
• portals/ai-workspace/production/README.md
• portals/ai-workspace/distribution/README.md
• platform-api/config/config-template.toml
• platform-api/config/default_config.go
• platform-api/README.md
• portals/ai-workspace/bff/internal/config/settings.go
• portals/ai-workspace/bff/internal/config/config_test.go
• platform-api/config/config.go

[Piumal1999]

Shall we move port to [ai_workspace.server] because it applies to both http and https?