[seanspeaks]

Summary

Stacked on #686. Today the v2 entity proxy (ADR-052) joins a request path onto one base URL per module. Google's APIs live on several hosts (www.googleapis.com, docs., sheets., analyticsdata., googleads.). One Google entity therefore can't reach Docs, Sheets, GA Data or Ads, even when its token carries the scopes.

This PR lets a module declare several named bases, and lets a proxy request pick one by name.

• Module config. A module can declare proxy.baseUrls: { default, docs, sheets, … }.
  • Values are https strings, checked at load: no credentials, query or fragment.
  • Names match ^[a-z][a-z0-9-]*$.
  • proxy.baseUrl still works and means { default: baseUrl }. Declaring both is a load error.
• Request. The proxy request takes an optional base, which is a name and never a URL or host. When omitted it means default.
  • A value shaped like a URL or host, such as https://evil.example, evil.example, ../x or docs:8080, gets 400 INVALID_PROXY_REQUEST.
  • A name the module doesn't declare gets 400 PROXY_UNKNOWN_BASE.
  • Either way nothing goes out, and the host still comes only from the module.
• Allow rules. Module- and app-level allow rules take an optional base (default default) and match only that base. Redirects are re-checked against the same base.
• Load errors. The app refuses to start if a rule names a base the module doesn't declare, or if a rule has no base on a module that has no default.
• No fallback. A declared base never falls back to the requester's host. A legacy baseUrl function that returns nothing now gets 501 PROXY_NOT_CONFIGURED.
• Single-base modules. The PROXY_NOT_ALLOWED message is byte-identical to before. The base is named only when a module declares more than one. details.base is always present, and the audit record carries the base.
• Kept in step: the OpenAPI v2 request schema and errors, api-proxy.schema.json, api-module-definition.schema.json, app-definition.schema.json and types/modules/index.d.ts.
• Docs. docs/architecture-decisions/052-amendment-1-named-proxy-bases.md is a dated amendment. ADR-052 itself lives on adr/052-053-management-api and is not copied here. The base usage is also documented in docs/reference/api-reference.md.

Test plan

• New use-case suite. It runs the real use case over a real Requester, with only fetch faked, and asserts the outbound URL.
  • base: 'docs' reaches the docs host, and an omitted base reaches default.
  • Allow rules match per base, in both directions.
  • The SSRF set is refused with no fetch.
  • Legacy baseUrl behaves as before.
  • A redirect is checked against the same base.
• Load errors, both in proxy-bases.test.js and through the real app-definition loader.
• Schema tests for both definition schemas and the proxy request schema (packages/schemas, 235/235).
• Mutation checks. 21 mutations killed across the two rounds, plus 12 run by an independent reviewer, with no survivors.
• Core jest. The same 14 failing suites and 61 failing tests as the base branch, compared by name. These are the existing mongodb-memory-server and environment failures. Total tests rose from 4272 to 4340.
• eslint: no errors.

Part of the Left Hook internal-MCP work (ADR 0016). frigg-internal will move to this PR's canary so its Google module can reach Sheets, Docs, GA and Ads.

---

Generated by Claude Code

---

Note

Medium Risk
Touches the security-sensitive entity proxy (host selection, allow-lists, redirects) and changes query serialization for [] keys, which may break callers that relied on comma-joined values.

Overview
Adds named proxy base URLs so one entity credential can reach multiple upstream hosts (e.g. Google Drive vs Docs) while keeping hosts module-controlled for SSRF safety.

Modules may declare proxy.baseUrls (or keep proxy.baseUrl as { default: … }). Proxy requests accept an optional base name (never a URL); unknown names return 400 PROXY_UNKNOWN_BASE. Module and app allow rules gain optional base and only match that host; redirects are re-checked on the same base. Invalid baseUrls or rules referencing undeclared bases fail at app load via assertProxyConfig (ProxyConfigError).

Query encoding change: array values under keys ending in [] are sent as repeated query pairs instead of comma-separated (documented as a beta proxy contract change). OpenAPI, JSON schemas, types, and API reference are updated accordingly.

^{Reviewed by Cursor Bugbot for commit 08cd07e. Bugbot is set up for automated code reviews on this repo. Configure here.}

📦 Published PR as canary version: 2.0.0--canary.690.08cd07e.0

✨ Test out this PR locally via:

npm install @friggframework/admin-scripts@2.0.0--canary.690.08cd07e.0
npm install @friggframework/core@2.0.0--canary.690.08cd07e.0
npm install @friggframework/devtools@2.0.0--canary.690.08cd07e.0
npm install @friggframework/eslint-config@2.0.0--canary.690.08cd07e.0
npm install @friggframework/extension-db-credentials@2.0.0--canary.690.08cd07e.0
npm install @friggframework/prettier-config@2.0.0--canary.690.08cd07e.0
npm install @friggframework/provider-aws@2.0.0--canary.690.08cd07e.0
npm install @friggframework/provider-netlify@2.0.0--canary.690.08cd07e.0
npm install @friggframework/schemas@2.0.0--canary.690.08cd07e.0
npm install @friggframework/serverless-plugin@2.0.0--canary.690.08cd07e.0
npm install @friggframework/test@2.0.0--canary.690.08cd07e.0
npm install @friggframework/ui@2.0.0--canary.690.08cd07e.0
# or 
yarn add @friggframework/admin-scripts@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/core@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/devtools@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/eslint-config@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/extension-db-credentials@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/prettier-config@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/provider-aws@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/provider-netlify@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/schemas@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/serverless-plugin@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/test@2.0.0--canary.690.08cd07e.0
yarn add @friggframework/ui@2.0.0--canary.690.08cd07e.0

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[seanspeaks]

build (22.x) is red, but the failures are not from this PR. The same check fails identically on the base branch, #686 (job 116839383474).

I compared the two runs suite by suite:

• Same failures. Both runs fail the same 33 suites and the same 119 tests.
• Where they are. All the failures are in devtools: frigg-cli commands, infrastructure/integration and infrastructure/domains/health, and the management-ui repository and button tests.
• Nothing new. No suite or test fails here that passes on feat: Netlify provider on the v2 stack (port of #545) (F7) #686.
• What changed. The only difference is in packages/schemas: one new passing suite (proxy-named-bases.test.js), taking it from 9 suites / 212 tests to 10 / 235.

There is no fix for those devtools failures anywhere in this stack yet, so there is nothing to port into this PR. They predate the internal-MCP stack, and I haven't re-run the job because it would fail the same way.

---

Generated by Claude Code

[seanspeaks]

ADR reconciliation needed after Stack A/B — drafted with Claude Code at Sean's request

Severity: must-reconcile (text placement and status; the design keeps ADR-052's SSRF property).

• Single base URL rule. ADR-052 §4 (docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668) says "The upstream URL is always module base URL + normalised path", meaning one base. 052-amendment-1-named-proxy-bases.md changes §4 and §5, and that is sound: base is a name, never a URL; strings only; each base has its own allow-list; redirects stay within the base. But ADR-052 itself is still Proposed on unmerged docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668, so the amendment cannot be Accepted ahead of it (ADR-043, docs(adr): ADR-043 — ADR lifecycle, one register, no RFC tier #646: Accepted = the ADR PR merges).
• Proposed: fold the amendment into ADR-052 §4/§5 on docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668 before it merges ("a module declares proxy.baseUrl or named proxy.baseUrls; the request names a base…"), and delete the separate file. If separate amendment files are wanted as a convention, decide that in ADR-043 (docs(adr): ADR-043 — ADR lifecycle, one register, no RFC tier #646). Also check the ADR-014/043 number check: a second file with the 052- prefix may count as a second claim on 052.
• Module instances (ADR-059 / "ADR-062"). Named bases (several hosts, one credential), ADR-059's open question on named registry entries (one module, several app-level entries), and ADR-063's unwritten "ADR-062 per-app module instances" are three axes of "more than one of a module". Add a sentence that separates them, so a later instance ADR does not reuse base for a different meaning.
• ADR-051 (feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666): managementApi.proxy.modules.<module>.allow[].base and module proxy.baseUrls must be in the validated schemas. The load-time errors ("rule names a base the module does not declare") should also come out of frigg validate, not only app load.
• ADR-053: the route is unchanged (POST /api/v2/entities/:id/proxy, beta), with an additive base field, which is fine for a beta route. Note it in the OpenAPI changelog.

Merge order: #668 (052 with named bases folded in) → #671 → … → #685 → this PR.

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[seanspeaks]

Reply to the ADR-reconciliation review (comment 6276667428), in e76e497f. #686's changes are merged forward in 33ca4351.

The amendment and ADR-052

• Where docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668 stands: ADR-052 on docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668 (adr/052-053-management-api) still describes one base URL per module in §4/§5. So the amendment can't be deleted yet.
• Status: it is now Proposed, not Accepted, and opens with "to be folded into ADR-052 §4/§5 on docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668 and then deleted".
• Location: it moved to docs/architecture-decisions/pending/adr-052-amendment-1-named-proxy-bases.md.
• Number check: I ran the ADR number-check logic locally (adr-number-check.yml, which exists only on docs/adr-register-reconciliation). The old 052-… filename counted as a second claim on 052 and failed the heading rule. After the move, this PR claims no ADR number.
• Next step: once the text is folded into docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668, I'll delete the file here. I'm not pushing to docs(adr): ADR-052 entity proxy security, ADR-053 Management API versioning #668.

Three meanings of "more than one of a module". Added to the amendment, and it should carry into ADR-052 when folded:

• base means several hosts behind one credential and one entity.
• ADR-059's open question is something else: one module as several named registry entries.
• The future per-app module-instances ADR is a third thing: several configured instances of one module.
• Each of the other two needs its own term; neither should reuse base.

frigg validate (ADR-051)

• The command lives on feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666 and is not on this branch.
• What the schemas already catch:
  • module proxy.baseUrls: name pattern, https only, at least one entry, and not alongside baseUrl;
  • managementApi.proxy.modules.<m>.allow[].base.
• What no schema can catch (two definitions at once): a rule naming a base the module doesn't declare, and a rule without base on a module with no default. The loader checks both in assertProxyConfig(), in packages/core/modules/proxy/proxy-bases.js.
• For feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666: frigg validate should call assertProxyConfig(), or resolveAppDefinition, rather than copy the rules. That will need a core export.

OpenAPI changelog. There's no OpenAPI changelog file, so I added "Entity proxy changes" under "Entity proxy (beta)" in docs/reference/api-reference.md:

• POST /api/v2/entities/:entityId/proxy gains an optional, additive base (omitted = default) and a new 400 PROXY_UNKNOWN_BASE;
• []-suffixed query keys are now sent once per value (30e64517).

Tests

• schemas: 253/253; provider-netlify: 138/138; db-credentials: 17/17.
• Core after the merge: the same 14 suites / 61 tests fail as on feat: Netlify provider on the v2 stack (port of #545) (F7) #686, all already failing before. build (22.x) shows the same devtools failures I described in my comment above.

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud