[markscott-ms]

Description

Part 1 of 4 of the CALM Hub extensions framework design for #3396. #3520 had all of this in one PR. It is now a stack of PRs, so that each part gets a better review.

Stack (merge in this order):

1. docs(calm-hub): propose extension runtime and security ADRs #3579 ADRs 0009–0012: runtime and security ← this PR
2. docs(calm-hub): propose extension UI, CLI and MCP ADRs #3580 ADRs 0013–0014: UI, CLI and MCP
3. docs(calm-hub): propose architecture validation and store write seam ADRs #3581 ADRs 0015–0016: validation and write seam
4. docs(calm-hub): model the CALM Hub extensions design in CALM #3582 CALM architecture

These ADRs keep the main points that the #3396 thread agreed: operator-only install, a proxy-only backend, one hubApi version, and a Hub-signed identity assertion.

ADR	Decision
0009	Extensions are external HTTP services behind a Hub proxy. Hub loads no extension code
0010	Hub sends a short-lived, request-bound assertion, never the user's token. An extension calls Hub with its own service account (Q4, Q5)
0011	Proxy rules: a scope on each route, the read-only exemption, host pinning, header allow-lists, a sandbox CSP, refusal to start with auth off (Q1, Q2)
0012	Manifest shape with route ids, vertx-json-schema validation, hubApi versioning, configuration by extension id (Q6)

Finding that changes the plan: the proof of concept builds the backend URI from a string. With a path from the caller, this permits SSRF.

Not yet verified: a step-0 spike must test JWT signing and vertx-json-schema in a native image, and streaming on RESTEasy Classic. The ADRs give the fallback for each.

0009 links to ADR 0015 and 0011 links to ADRs 0013 and 0014. Those links work when the later PRs in the stack merge.

All ADRs are Proposed. @rocketstack-matt, please review them against your proof of concept.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Lab (calm-lab/)
• CALM Models (calm-models/)
• CALM Server (calm-server/)
• CALM Studio (calm-studio/)
• CALM Widgets (calm-widgets/)
• CALMGuard (calm-guard/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Commit Message Format ✅

docs(calm-hub): propose extension runtime and security ADRs

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

This PR adds documentation only. It changes no code.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

[rocketstack-matt]

I'm good with all these decisions