HydraIssues

Self-service experience management for external creators (Cyborn / Gallo-Romeins) via hydramancer

Synthesis of three investigations (hydramancer lens #488, library lens #487, authz lens #489). This is the consolidated, decisive findings + implementation plan.

1. Summary

The Cyborn pipeline now works end to end: Cyborn submits a build to Perforce, hydraperforcewatcher zips and publishes it to the mirror, POST /api/v1/builds/notify fires, and hydraexperiencelibrary registers it as a development build against the gallo-romeins-museum experience. What Cyborn still cannot do is see their experience's state or drive its lifecycle (stage, promote, rollback, pause). Today an operator does every one of those steps with the library's admin token. This work gives Cyborn a self-service, org-scoped view and a scoped set of lifecycle controls, delivered through the existing hydramancer creator portal — reusing the exact sign-in + privileged-proxy pattern already shipped for the "Get Perforce access" panel. Now is the moment because the plumbing is proven and the only missing piece is a safe, org-scoped control surface.

2. What already exists to leverage

hydramancer (the creator portal) already has the whole front half:

• iamnim sign-in wired on /experience: GET /experience/login -> iamnim /login?redirect_uri=.../experience/authed; GET /experience/authed stores the token in the iamnim_session cookie (HttpOnly/Secure/Lax/24h); GET /experience/logout clears it. Session read by iamnimSession() from cookie / X-Iamnim-Session header / ?token=. Files: internal/api/handlers_experience.go:14-50, handlers_provision.go:59-67.
• Identity + memberships via internal/iamnim/client.go: Me(session) (GET /api/me), Memberships(session) (GET /api/me/memberships -> {organization_slug, organization_name}).
• The exact proxy pattern to copy — the Perforce panel: POST /api/v1/provision/perforce (server.go:50) -> handleProvisionPerforce (handlers_provision.go:16-55): require session, forward downstream as X-Iamnim-Session, portal holds no privileged creds, upstream status/body streamed back. Upstream URL from config (config.go:17-20, env HYDRAMANCER_PROVISION_PERFORCE_URL); empty URL disables the panel.
• The panel UI is data-driven: experience.html:148-171 gated on .CanProvision, backed by experienceData{SignedIn,Email,Orgs,CanProvision} (server.go:71-94), with fetch+render JS at experience.html:445-480.

hydraexperiencelibrary already has the whole back half — a full lifecycle API and admin UI:

• JSON API (all requireAuth, server.go:124-155): GET /api/v1/experiences, GET /api/v1/experiences/{name}, GET .../builds, PUT, POST .../promote ({"to":"staging"|"production"}, empty = auto-detect, handlers.go:197-274), .../rollback (288-320), .../pause / .../resume / .../retire (322-371), .../stream, POST /api/v1/builds/notify.
• Rich build state via GET /pipeline/health?experience= (handlers_pipeline.go:264-326, last 10 builds) and GET /experiences/{name}/builds (handlers.go:453-474). The Experience record carries only int pointers DevelopmentBuild/StagingBuild/ProductionBuild/PreviousBuild (store.go:25-28); build detail lives in a separate builds.yaml store (build.go).
• Admin web UI (all RequireWebAuth cookie session, server.go:99-109): GET /admin, GET /admin/experiences/{name}, POST /admin/experiences/{name}/{promote,rollback,pause,resume,retire,stream}.
• The org tie is already in the data: Experience.Developer and Experience.Owner (store.go:17-43); gallo-romeins-museum has developer="cyborn", owner="gallo-romeins-museum".

3. The authorization gap and the decision

The gap. The library API authorizes on a single shared admin bearer token (middleware.go:10-24) — all-or-nothing, no org/tenant awareness anywhere. handleListExperiences (handlers.go:17-24) returns the entire catalog unfiltered. The admin web UI is the same token behind a cookie. There is no per-developer/owner code path in the library at all.

Decision: Option A — enforce org scoping in a hydramancer proxy that holds the library admin token, mirroring handleProvisionPerforce. Leave the library API unchanged for the initial rollout. This is unanimous across all three lenses. Rationale:

• It reuses a proven, already-deployed pattern (the Perforce proxy) and keeps the privileged token server-side in the portal, never in the browser.
• It touches only hydramancer (a low-risk portal), not the live experience-library scale that sits behind Traefik and drives real venues.
• Option B (make the library itself org-aware via a forwarded X-Iamnim-Session, exactly like hydraperforceprovision) is the correct durable end state and should be the follow-up once a second creator org exists — but it is a larger change to a live service and is not justified for a single-tenant MVP.

The one inversion that makes this harder than Perforce — and the scoping rule. In the Perforce proxy the client names its own org and receives a depot named after it, so naming a foreign org buys the caller nothing (hydraperforceprovision/internal/api/handlers.go:21-92, IsMember exact-match at internal/iamnim/client.go:63-75). With experiences, the request names an experience {name}, and the owning org is a property of the stored record, not of the request. Therefore the proxy must never trust any org field from the client. The rule:

Which experiences may this creator touch = experiences whose developer (control) — or owner (read-only candidate) — org field is one of the caller's iamnim membership slugs.

Concretely, every action path is: (1) authenticate the session with Me() (fail closed on error); (2) resolve the caller's membership slugs via Memberships(); (3) load the target experience from the library first and read its developer; (4) allow only if that org is in the caller's slug set; (5) only then forward to the library with the admin token. List views filter the full catalog down to the caller's orgs — they never return it whole.

Making org identifiers match reliably (a real correctness risk, not cosmetic). experience.developer is free-text operator-set YAML compared against Pantheon slugs. The known mismatch: the experience carries developer="cyborn" and owner="gallo-romeins-museum", while the Perforce/depot normalization uses galloromeinsmuseum (see memory: Gallo-Romeins depot galloromeinsmuseum, user koen). For the MVP the control field is developer="cyborn" and the iamnim org slug is cyborn — these match exactly, so Cyborn works today. But before scoping is enabled for any second org, we must: (a) apply one canonical normalization (lowercase, strip non-alphanumerics) on both the membership slug and the experience org field before comparison, and (b) add a startup validation that every experience's developer/owner resolves to a known org slug, logging mismatches. Treat experience.developer == iamnim organization_slug as a documented invariant until (b) enforces it.

4. Scope: what a creator can do

Read (MVP): list the experiences their org owns/develops; per-experience status and build state (draft/development/staging/live, the DevelopmentBuild/StagingBuild/ProductionBuild pointers, and recent build history via pipeline/health?experience=).

Lifecycle actions to expose (Phase 2), all org-scoped:

• promote -> staging (POST .../promote {"to":"staging"}) — staging nodes only, safe.
• rollback (POST .../rollback) — reverts to the previous build, safe and reversible.
• pause / resume (POST .../pause / .../resume) — safe operational toggles.

Gated / operator-only:

• promote -> PRODUCTION ({"to":"production"}) invokes reprovisionProduction, which pushes to live public venues (handlers.go:246-263). Keep this operator-gated for the MVP; a later phase may allow it behind an explicit typed confirmation + audit entry. Justification: production promotion changes what the public sees in a venue; a self-service creator should not trigger that unsupervised on first release.
• retire — near-terminal; operator-only.
• create / PUT / DELETE — these set the boundary fields themselves (developer, owner, districts, watch_name, auto_promote, exe_path, release_path). A creator editing them could re-point scoping or change what gets executed. Hard out of scope.

Explicitly out of scope: creating or deleting experiences; editing exe_path / release_path / watch_name / districts / auto_promote; any cross-org visibility.

5. Implementation plan (mirrors the Perforce panel)

hydramancer — config

• Add an ExperienceLibrary{ base_url, admin_token } block to config.go, with env overrides HYDRAMANCER_EXPERIENCE_LIBRARY_URL and HYDRAMANCER_EXPERIENCE_LIBRARY_TOKEN. Empty base_url disables the panel (same convention as HYDRAMANCER_PROVISION_PERFORCE_URL). Token is server-side only, never rendered.

hydramancer — iamnim client

• Add IsMember(session, orgSlug) to internal/iamnim/client.go (copy the exact-match scan from hydraperforceprovision/internal/iamnim/client.go:63-75) plus a normalized-compare helper.

hydramancer — proxy routes + scoping middleware (handlers_experiences.go)

• GET /api/v1/experiences (scoped): require session -> Memberships() -> call library GET /api/v1/experiences with the admin token -> filter to experiences whose normalized developer/owner is in the caller's slug set -> return the filtered list (+ status/build fields).
• GET /api/v1/experiences/{name} (scoped): load from library, org-check on the record, return or 403.
• POST /api/v1/experiences/{name}/{action} where action ∈ {promote-staging, rollback, pause, resume}: require session -> load the experience from the library first -> derive the authorizing org from experience.developer (never from the request body) -> IsMember check -> forward to the matching library route with the admin token -> stream status/body back. Reject any action not in the allow-list (this is what keeps production-promote / retire / PUT out). Reuse iamnimSession() and writeProvisionError().
• Fail closed on any iamnim or library error (deny, do not default-allow).
• Add an audit log line per privileged forward (who, which experience, which action).

hydramancer — UI

• Add a "Manage your experiences" panel to experience.html, data-driven exactly like the Perforce panel (a CanManageExperiences flag on experienceData, populated when the library config is present and the user has ≥1 experience). List the org's experiences with status + build info and the scoped action buttons; production-promote and retire are absent (not merely disabled). Reuse the existing fetch/render JS shape at experience.html:445-480.

Optional library-side hardening (Phase 3, Option-B-lite): add a developer= query filter to the library's GET /api/v1/experiences as a defense-in-depth second fence, so even a proxy bug cannot list foreign experiences. This is additive and does not change the auth model.

Tests + docs: unit tests for the scoping middleware (member allowed, non-member 403, unlisted experience filtered out, foreign org name in body ignored, iamnim error -> deny); a runbook in hydramancer documenting the config, the scoping invariant, and the developer == org slug normalization rule (memory requires a runbook to back any operational memory entry).

6. Risks & mitigations

• Authorization boundary (top risk). Always resolve the authorizing org from the stored experience record, never the request. List views filter; they never return the full catalog. Unit-tested member/non-member/foreign-body cases. This is the single most important correctness property.
• Slug/name mismatch. experience.developer is free-text YAML vs Pantheon slugs; gallo-romeins-museum/galloromeinsmuseum vs cyborn. Mitigation: one canonical normalization on both sides + startup validation that every experience org resolves to a known slug; document developer == org slug as an invariant. Cyborn's developer="cyborn" matches the slug cyborn today, so the MVP is safe.
• Admin-token blast radius. The proxy holds a full-privilege token. Mitigation: server-side only, per-experience scoping on every path, explicit action allow-list, audit log, empty-config disables the panel.
• Promoting untested builds. A creator could promote a broken development build to staging. Mitigation: staging is the safe target by design (staging nodes, not public venues); rollback is one click; production stays operator-gated.
• exe_path / packaging. Promotion assumes the build's exe_path/release_path are correct — creator-visible but creator-uneditable (operator-only fields). If a build is mis-packaged, promotion to staging surfaces it safely before any operator touches production.
• watch_name fan-out. builds/notify keys on watch_name via FindByWatchName (store.go:221-229) and fans one build to every experience sharing it. This is inbound-only and unchanged by this work, but reinforces that watch_name must stay operator-only (it is, under "out of scope").
• Fail-open on identity errors. Any iamnim/membership/library failure must deny, never default-allow.

7. Effort estimate and phasing

Estimate: ~2-3 engineering days for Phases 1-2 (the pattern is copy-adapt from the Perforce proxy; the library needs no changes), plus ~1 day for tests, runbook, and the optional library developer= filter.

• Phase 1 (MVP) — read-only. Config block + iamnim IsMember; GET /api/v1/experiences (scoped, filtered) and GET .../{name}; the "Manage your experiences" panel showing each experience's status and build state. No mutations. Ships Cyborn immediate visibility with near-zero blast radius.
• Phase 2 — scoped actions. Add POST .../{name}/{promote-staging,rollback,pause,resume} behind the action allow-list and org check, with the audit log. Production-promote and retire stay operator-only.
• Phase 3 — hardening / durability. Optional library-side developer= filter (defense in depth); startup org-slug validation; and, once a second creator org exists, migrate to Option B (library-side iamnim auth via forwarded X-Iamnim-Session, mirroring hydraperforceprovision) as the long-term auth model.

Related: this synthesizes and supersedes the per-lens issues #487, #488, #489. No code, deploy, or live-state change was made.