docs: design proposals for issues #2, #3, #4, #5 #9

Open

plat wants to merge 1 commit from docs/design-proposals into main

plat commented

2026-06-23 20:29:02 +00:00

Owner

Design proposals for the four larger / greenfield issues — #2 (Vault secrets), #3 (custom domains), #4 (BYO IdP), #5 (repo-migration auto-port) — to review and approve before implementation. (The two tractable enhancements, #6 observability and #7 platform agent-work, shipped as implementation PRs.)

Each proposal under docs/proposals/ is:

Anchored in real code — concrete file:line for every seam (verified, not guessed: e.g. domains.ts:parseDomainRegistry, server.ts:resolveAppHost:1767, dispatcher.ts:WEBHOOK_EVENTS, the app-auth extraEnvFrom mount).
Concrete — actual manifests, tool signatures, and code shapes you could build from.
Validated where possible — the Vault proposal helm templates its chart (hashicorp/vault 0.33.0, vault-secrets-operator 1.4.0 confirmed to exist).
Honest — explicit hard parts, tradeoffs/alternatives, and Open questions per doc.

The four

#2 self-serve secrets (Vault) — per-app env vars via Vault alongside sops (replacing sops would rewrite the whole fork-sealing sovereignty invariant). The crux is single-node unseal without cloud KMS: a concrete strategy (Shamir keys sealed into the existing sops trust root, replayed by an unseal Job) with dev-mode/transit/cloud-KMS all rejected and why. VSO syncs Vault KV → a k8s Secret onto the existing extraEnvFrom seam, so _app-template needs no change.
#3 self-serve domains — most plumbing exists (registry, resolver, per-host cert, create_app(domain:)); the gap is self-serve granting + DNS ownership verification (the Vercel-style crux) + public ACME TLS (the internal CA can't sign public domains).
#4 bring your IdP — mitosis up IdP env → Forgejo as OAuth2 relying party → IdP groups mapped to Forgejo orgs/teams; mcp authz already keys off Forgejo membership, so synced identities flow through unchanged. Notes the agents QA-login coupling.
#5 repo migration — a new agent "port" role conforms a migrated repo onto the template via create_app; trigger via webhook (HMAC vs PAT discussed — none exists today), bulk via the sweep with a concurrency guard + ported idempotency state. Flags the non-Node-source limitation.

How to use

Comment on the Open questions in each, then approve (or steer) the approach. Each proposal lays its build out as phased, per-repo PRs — approval turns it into the plan.

Design proposals for the four larger / greenfield issues — **#2 (Vault secrets)**, **#3 (custom domains)**, **#4 (BYO IdP)**, **#5 (repo-migration auto-port)** — to review and approve **before** implementation. (The two tractable enhancements, #6 observability and #7 platform agent-work, shipped as implementation PRs.) Each proposal under `docs/proposals/` is: - **Anchored in real code** — concrete `file:line` for every seam (verified, not guessed: e.g. `domains.ts:parseDomainRegistry`, `server.ts:resolveAppHost:1767`, `dispatcher.ts:WEBHOOK_EVENTS`, the app-auth `extraEnvFrom` mount). - **Concrete** — actual manifests, tool signatures, and code shapes you could build from. - **Validated where possible** — the Vault proposal `helm template`s its chart (hashicorp/vault 0.33.0, vault-secrets-operator 1.4.0 confirmed to exist). - **Honest** — explicit hard parts, tradeoffs/alternatives, and Open questions per doc. ## The four - **#2 self-serve secrets (Vault)** — per-app env vars via Vault **alongside** sops (replacing sops would rewrite the whole fork-sealing sovereignty invariant). The crux is **single-node unseal without cloud KMS**: a concrete strategy (Shamir keys sealed into the existing sops trust root, replayed by an unseal Job) with dev-mode/transit/cloud-KMS all rejected and why. VSO syncs Vault KV → a k8s Secret onto the **existing** `extraEnvFrom` seam, so `_app-template` needs no change. - **#3 self-serve domains** — most plumbing exists (registry, resolver, per-host cert, `create_app(domain:)`); the gap is self-serve **granting** + **DNS ownership verification** (the Vercel-style crux) + **public ACME TLS** (the internal CA can't sign public domains). - **#4 bring your IdP** — `mitosis up` IdP env → Forgejo as OAuth2 relying party → IdP groups mapped to Forgejo orgs/teams; mcp authz already keys off Forgejo membership, so synced identities flow through unchanged. Notes the agents QA-login coupling. - **#5 repo migration** — a new agent **"port"** role conforms a migrated repo onto the template via `create_app`; trigger via webhook (HMAC vs PAT discussed — none exists today), bulk via the sweep with a concurrency guard + `ported` idempotency state. Flags the non-Node-source limitation. ## How to use Comment on the **Open questions** in each, then approve (or steer) the approach. Each proposal lays its build out as phased, per-repo PRs — approval turns it into the plan.

plat added 1 commit

2026-06-23 20:29:02 +00:00

docs: design proposals for issues #2 , #3 , #4 , #5 7c1a8492a7

Add docs/proposals/ — from-first-principles design proposals for the larger /
greenfield issues, to be reviewed and approved before implementation. Each is
anchored in the real code (concrete file:line for every seam), shows the actual
manifests / tool signatures it would add, validates what it can (the Vault
proposal helm-templates its chart), and is explicit about hard parts, tradeoffs,
and open questions.

- self-serve-secrets-vault.md  (#2) — per-app env vars via HashiCorp Vault
  ALONGSIDE sops (not replacing the fork-sealing invariant); a concrete,
  honest strategy for single-node unseal without cloud KMS (Shamir keys sealed
  into the existing sops trust root, replayed by an unseal Job) + VSO sync onto
  the existing extraEnvFrom seam (no app-template change).
- self-serve-custom-domains.md (#3) — Vercel-style BYO domains: self-serve
  granting + DNS ownership verification + public (ACME) TLS, on top of the
  domains registry / resolver that already exists.
- byo-identity-provider-entra-oidc-forgejo.md (#4) — BYO upstream IdP at
  `mitosis up`, with Forgejo as the identity hub and IdP groups -> Forgejo
  orgs/teams sync (mcp authz keys off Forgejo membership, so it flows through).
- repo-migration-auto-port.md (#5) — a Forgejo migration triggers a new agent
  "port" role that conforms the repo onto the app-template via create_app;
  bulk via the sweep with a concurrency guard + idempotency state.

The two tractable enhancements (#6 observability, #7 platform agent-work)
shipped as implementation PRs rather than proposals.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>