investigate hero_proxy OAuth-access-token pass-through for zero-setup cockpit→Forge calls (Option 3 polish over D-22 BYO) #2

New issue

Open

opened 2026-05-22 01:19:13 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-05-22 01:19:13 +00:00

Owner

Investigate hero_proxy OAuth-access-token pass-through so cockpit can reuse front-door session for Forge API calls (zero-setup BYO)

Context

Demo VMs provisioned via hero_os_tfgrid_deployer are reached via Forge-OAuth-gated public URLs (per hero_os_tfgrid_deployer#2 goal): user clicks VM URL → hero_proxy intercepts → OAuth redirect to forge.ourworld.tf → user authenticates → bounce back to cockpit. From the user's perspective they're already authenticated against Forge by the time cockpit loads.

s140 / D-22 locked BYO as the v1 wire path for cockpit→Forge calls (feedback submission per hero_os_tfgrid_deployer#1 §9): user mints their own scoped token (Settings → Applications → New Token, write:issue) at forge.ourworld.tf and pastes into cockpit Settings, where it lands at cockpit/USER_FORGE_TOKEN per D-16. ~30s user-side detour because they're already on the page.

This issue tracks a polish path that could drop that 30s to zero: if hero_proxy passes the OAuth access token from the front-door handshake through to backend cockpit calls, cockpit can use it directly for Forge API operations as the user, without the BYO Settings paste step.

Goal

Investigate whether hero_proxy currently exposes the Forge OAuth access token to backend services, and if not, scope what it would take. If viable, ship as a transparent upgrade behind a feature flag — cockpit detects the pass-through token first, falls back to BYO cockpit/USER_FORGE_TOKEN if absent. Forward-compatible with D-22; the D-16 storage slot stays valid as fallback for operations OAuth scopes don't cover.

Investigation checklist

Does hero_proxy's existing Forge OAuth flow request write:issue scope (and any others cockpit needs)? If not, what's the config / flow change?
Does hero_proxy expose the OAuth access token to backend services today — e.g. via X-Hero-Forge-Token header, session cookie, or hero_proxy's own RPC?
If yes: what's the token lifetime + refresh-token handling? Does cockpit need to handle 401-on-expiry + trigger re-auth, or does hero_proxy refresh silently?
If no: scope adding pass-through. Probably ~1 day of hero_proxy work + ~half-day of cockpit consumption. Confirm Casper / Despiegk are OK with the upstream change.
Security review: per-request token disclosure (header) vs per-session disclosure (cookie) vs RPC fetch-on-demand. Pick the model with the smallest TCB.
Confirm OAuth scope upgrade isn't a breaking change for existing demo users — i.e. they need to re-consent with new scope. UX implication on first cockpit load after the upgrade lands.

Acceptance (if shipped)

Cockpit's cockpit.feedback_submit (and future cockpit→Forge calls as the user) read the OAuth access token from hero_proxy's pass-through first; fall back to cockpit/USER_FORGE_TOKEN if absent.
BYO Settings paste-field stays in place — it's the fallback for offline operations, operations needing scopes OAuth doesn't grant, or operators who disabled OAuth pass-through.
New cockpit users on a deployer-provisioned VM never see the BYO prompt for the v1 feedback flow.

Not in scope

Replacing cockpit/USER_FORGE_TOKEN (D-16 slot stays).
Changing the deployer's user-creation flow (D-22's CreateUserOutput { user_id, forge_username, initial_password } is unchanged).
Cockpit features requiring scopes OAuth doesn't grant (still BYO).

References

Decision: workspace decisions/D-22-deployer-forge-token-namespacing-and-byo-landing.md (Validation section explicitly flags this as the polish path).
D-16 (BYO storage slot): workspace decisions/D-16-cockpit-byok-user-forge-token-namespacing.md.
Probe + spec walk-through: memory/investigation_forge_admin_token_mint_2026_05_21.md.
Front-door OAuth gating: hero_os_tfgrid_deployer#2 goal.
Cockpit feedback flow spec: hero_cockpit#1 §3.4 (Feedback page) + meeting minutes hero_os_tfgrid_deployer#1 §9.

Signed-by: mik-tf mik-tf@noreply.invalid

## Investigate hero_proxy OAuth-access-token pass-through so cockpit can reuse front-door session for Forge API calls (zero-setup BYO) ### Context Demo VMs provisioned via `hero_os_tfgrid_deployer` are reached via Forge-OAuth-gated public URLs (per [hero_os_tfgrid_deployer#2 goal](https://forge.ourworld.tf/lhumina_code/hero_os_tfgrid_deployer/issues/2)): user clicks VM URL → hero_proxy intercepts → OAuth redirect to `forge.ourworld.tf` → user authenticates → bounce back to cockpit. From the user's perspective they're already authenticated against Forge by the time cockpit loads. s140 / [D-22](https://forge.ourworld.tf/lhumina_code/hero_os_tfgrid_deployer/issues/4#issuecomment-35866) locked **BYO** as the v1 wire path for cockpit→Forge calls (feedback submission per [hero_os_tfgrid_deployer#1 §9](https://forge.ourworld.tf/lhumina_code/hero_os_tfgrid_deployer/issues/1)): user mints their own scoped token (Settings → Applications → New Token, `write:issue`) at forge.ourworld.tf and pastes into cockpit Settings, where it lands at `cockpit/USER_FORGE_TOKEN` per [D-16](../decisions/D-16-cockpit-byok-user-forge-token-namespacing.md). ~30s user-side detour because they're already on the page. This issue tracks a polish path that could drop that 30s to **zero**: if hero_proxy passes the OAuth access token from the front-door handshake through to backend cockpit calls, cockpit can use it directly for Forge API operations as the user, without the BYO Settings paste step. ### Goal Investigate whether hero_proxy currently exposes the Forge OAuth access token to backend services, and if not, scope what it would take. If viable, ship as a transparent upgrade behind a feature flag — cockpit detects the pass-through token first, falls back to BYO `cockpit/USER_FORGE_TOKEN` if absent. Forward-compatible with D-22; the D-16 storage slot stays valid as fallback for operations OAuth scopes don't cover. ### Investigation checklist - [ ] Does hero_proxy's existing Forge OAuth flow request `write:issue` scope (and any others cockpit needs)? If not, what's the config / flow change? - [ ] Does hero_proxy expose the OAuth access token to backend services today — e.g. via `X-Hero-Forge-Token` header, session cookie, or hero_proxy's own RPC? - [ ] If yes: what's the token lifetime + refresh-token handling? Does cockpit need to handle 401-on-expiry + trigger re-auth, or does hero_proxy refresh silently? - [ ] If no: scope adding pass-through. Probably ~1 day of hero_proxy work + ~half-day of cockpit consumption. Confirm Casper / Despiegk are OK with the upstream change. - [ ] Security review: per-request token disclosure (header) vs per-session disclosure (cookie) vs RPC fetch-on-demand. Pick the model with the smallest TCB. - [ ] Confirm OAuth scope upgrade isn't a breaking change for existing demo users — i.e. they need to re-consent with new scope. UX implication on first cockpit load after the upgrade lands. ### Acceptance (if shipped) - Cockpit's `cockpit.feedback_submit` (and future cockpit→Forge calls as the user) read the OAuth access token from hero_proxy's pass-through first; fall back to `cockpit/USER_FORGE_TOKEN` if absent. - BYO Settings paste-field stays in place — it's the fallback for offline operations, operations needing scopes OAuth doesn't grant, or operators who disabled OAuth pass-through. - New cockpit users on a deployer-provisioned VM never see the BYO prompt for the v1 feedback flow. ### Not in scope - Replacing `cockpit/USER_FORGE_TOKEN` (D-16 slot stays). - Changing the deployer's user-creation flow (D-22's `CreateUserOutput { user_id, forge_username, initial_password }` is unchanged). - Cockpit features requiring scopes OAuth doesn't grant (still BYO). ### References - Decision: workspace `decisions/D-22-deployer-forge-token-namespacing-and-byo-landing.md` (Validation section explicitly flags this as the polish path). - D-16 (BYO storage slot): workspace `decisions/D-16-cockpit-byok-user-forge-token-namespacing.md`. - Probe + spec walk-through: `memory/investigation_forge_admin_token_mint_2026_05_21.md`. - Front-door OAuth gating: [hero_os_tfgrid_deployer#2 goal](https://forge.ourworld.tf/lhumina_code/hero_os_tfgrid_deployer/issues/2). - Cockpit feedback flow spec: [hero_cockpit#1 §3.4](https://forge.ourworld.tf/lhumina_code/hero_cockpit/issues/1) (Feedback page) + meeting minutes [hero_os_tfgrid_deployer#1 §9](https://forge.ourworld.tf/lhumina_code/hero_os_tfgrid_deployer/issues/1). Signed-by: mik-tf <mik-tf@noreply.invalid>