Standalone MCP consent delivery: build authorize URL + deliver login link (#317 follow-up)

[initializ-mk]

Carved out of the #317 epic. The auth-required gate (#330 / PR #331, merged) parks a grantless type: user call and can resume it; the standalone loopback callback validates state and completes the exchange. What's missing is the Issue-side of the standalone consent loop — the part that actually builds the authorize URL and prompts the user.

Scope split (2026-07): this issue is standalone only — Forge builds the authorize URL, hosts GET /mcp/oauth/callback, and delivers the login link via the A2A auth-required artifact (task status). Forge-driven Slack (channel) delivery is now #343 and layers on top (it consumes the AuthorizeURL this issue produces).

Problem

In standalone mode (no platform), a type: user MCP call with no grant parks correctly on the auth-required gate — but nothing builds/serves the authorize URL, so it just parks until timeout. Also, type: user is currently construction-rejected without a platform block (forge-core/mcp/server.go:192), so the standalone delegated path doesn't exist yet at all.

have (merged): park on ErrNoToken → [ ??? ] → GET /mcp/oauth/callback → validate state → exchange → resume
missing:       standalone type:user resolver + build authorize URL + Issue(state) + deliver via A2A artifact + CallbackCompleter

Managed mode is unaffected — the platform delivers the prompt and hosts the callback. This is Forge, standalone only (design-tool-registry.md §18.4).

Scope

1. Standalone type: user resolver. Today type: user hard-requires platform.token_endpoint and routes to delegatedTokenSource (server.go:711). Add a standalone branch: when there is no platform block, resolve the per-subject token from a local SubjectTokenStore — Get(subject) hit → return; miss → ErrNoToken (trips the gate). The CallbackCompleter populates that store. Decide the enable signal (recommended: type: user + no platform block + grant: authorization_code).
2. Callback host config. Standalone OAuth needs the agent reachable at a public https://<host>/mcp/oauth/callback for the IdP browser redirect — no such config is wired today. Add it (forge.yaml field and/or AGENT_URL), used to build redirect_uri.
3. Build the authorize URL. Reuse buildAuthorizeURL (forge-core/mcp/oauth_flow.go:489) + oauth.GeneratePKCE() / oauth.GenerateState() + stateBinder.Issue(subject, server, session). Endpoints/client_id from explicit config or persisted registration (MCP OAuth Phase 1.5: automated discovery (RFC 9728/8414) + dynamic client registration (RFC 7591) #316, merged). Store the PKCE verifier keyed by state so the callback can complete the exchange (the current stateBinder holds {subject, server, session} but not the verifier — extend it).
4. Deliver the link via the A2A auth-required artifact. Populate the parked task's auth-required status message with the authorize URL so UI/A2A clients render a clickable "Connect <server>" link. (Channel/Slack DM delivery is Forge-driven Slack delivery of MCP consent prompts (channel-adapter ConsentDeliverer) #343.)
5. Provide the CallbackCompleter (Runner.SetCallbackCompleter): oauth.ExchangeCodeCtx(...) with the stored verifier → SubjectTokenStore.Put(subject, token, ttl) so the resumed call finds a grant.
6. Wire it in forge-cli/cmd/run.go — call SetCallbackCompleter + SetConsentDeliverer (both currently never called). Also expose the Runner.SetAuthorizeURLProvider seam Forge-driven Slack delivery of MCP consent prompts (channel-adapter ConsentDeliverer) #343 needs, whose standalone implementation is the step-3 builder.

Already in place (build on these — all merged)

• Gate + park/resume — Auth-required gate: DEFER park/resume for delegated MCP consent (#317 follow-up) #330 (authgate, mcpAuthGate).
• stateBinder (single-use/expiring/session-bound) + GET /mcp/oauth/callback + CallbackCompleter seam — forge-cli/runtime/mcp_consent_callback.go.
• SubjectTokenStore (Get/Put/Evict) — forge-core/mcp/subject_token_store.go.
• ConsentDeliverer / SetConsentDeliverer / SetCallbackCompleter seams — runner.go (defined, never called).
• OAuth machinery to reuse — buildAuthorizeURL, oauth.GeneratePKCE, oauth.GenerateState, oauth.ExchangeCodeCtx, discovery/DCR resolveOAuthConfig (MCP OAuth Phase 1.5: automated discovery (RFC 9728/8414) + dynamic client registration (RFC 7591) #316).

Security contract (already enforced — must honor)

• The callback is auth-exempt (tokenless IdP redirect) — its authenticity is the state binding.
• Issue MUST bind a non-empty session; the callback rejects empty/mismatched sessions fail-closed.
• Never resume before the grant exists — the callback resolves the gate only after the code→token exchange succeeds.

Acceptance

• A standalone type: user server (no platform block) is accepted at construction and parks a grantless call instead of being rejected.
• The parked task's A2A auth-required artifact carries a clickable authorize URL for the requesting user.
• Completing the browser flow lands on /mcp/oauth/callback, exchanges the code (with the state-bound PKCE verifier), stores the token in the in-memory SubjectTokenStore, and resumes the parked call — which now resolves a grant and proceeds.
• The issued state binds a non-empty session; cross-session/replayed/expired callbacks are rejected (already tested).
• No token on disk.

Out of scope

• Forge-driven Slack (channel) delivery — Forge-driven Slack delivery of MCP consent prompts (channel-adapter ConsentDeliverer) #343.
• Managed consent delivery — platform-side (initializ/aip/mcp-delegated-identity-broker.md).
• Session-end teardown — separate Epic: runtime per-user, ephemeral per-session MCP OAuth (interactive login via Slack / A2A UI) #317 follow-up (Per-session teardown: drop delegated MCP token + connection at session end (#317 follow-up) #333).

Related

Epic #317 · gate #330 · Slack delivery #343 · discovery/DCR #316 · AARM R10 #319 · authority design-tool-registry.md §18.4.

[initializ-mk]

Design: Forge-driven Slack consent delivery (delivery is Forge's job; platform-read is the fallback)

Expanding the "deliver the link" step (#3 in Scope) into a concrete design. Decision: Forge owns consent delivery over its existing Slack connection. The platform only reads the signal when no Slack adapter is connected. This mirrors DEFER's delivery model exactly (SetDeferralNotifier → ApprovalDeliverer.DeliverApproval), reusing the same machinery rather than inventing a parallel one.

Delivery ownership is decoupled from token custody: Forge delivering the login link over Slack is orthogonal to who hosts the callback / holds the token (standalone: Forge; managed: platform). Forge delivers whatever authorize_url it's told to; the grant still completes through GET /mcp/oauth/callback → CallbackCompleter → SubjectTokenStore.

Delivery routing (who gets the prompt, and the fallback)

The prompt must reach the user who asked (subject), not a shared channel — only they can complete their own OAuth. Resolution order:

Condition	Delivery
Request originated in Slack (origin ctx present)	Reply in the origin thread/DM — the exact conversation the user is in. Best UX.
Slack adapter active, no origin ctx (request came via UI/A2A)	DM the subject by email — users.lookupByEmail → conversations.open → chat.postMessage.
Slack adapter active but subject unresolvable (guest / no email / lookup fails)	Log + emit-only — the mcp_auth_required audit event is the backstop; platform may pick it up.
No consent-capable channel adapter active	Deliverer left nil → emit-only. Platform reads mcp_auth_required and drives its own delivery.

mcp_auth_required is emitted before delivery in mcpAuthGate.Await (already true today), so platform-read is always a backstop even when Slack delivery is wired — a Slack outage never strands the parked call.

New capability interface (mirror ApprovalDeliverer) — forge-core/channels/plugin.go

// ConsentDeliverer is an OPTIONAL capability: a channel adapter that can present
// an MCP delegated-consent login link to a specific user. Mirrors
// ApprovalDeliverer, but the resolution path differs — consent completes through
// the OAuth callback, not a button click (see SetConsentCanceler for the one
// interactive hook).
type ConsentDeliverer interface {
    DeliverConsent(ctx context.Context, req ConsentPrompt) error
    // Optional interactive "Cancel" — lets the user fail the wait fast instead
    // of idling to the deadline. nil-safe.
    SetConsentCanceler(c ConsentCanceler)
}

type ConsentPrompt struct {
    Subject      string        // the requesting user (email preferred) — who to reach
    Server       string        // MCP server name ("atlassian") — for the prompt copy
    AuthorizeURL string        // the login link the user clicks (built by the #332 front-half)
    Deadline     time.Time     // gate timeout — rendered as "expires in N min"
    Origin       *ChannelOrigin // optional: where the request came from, to reply in-thread
}

// ChannelOrigin threads the inbound message's location so consent can reply
// where the user is already talking. Populated by the channel adapter on inbound.
type ChannelOrigin struct {
    Adapter  string // "slack"
    Channel  string // Slack channel/DM id
    ThreadTS string // thread to reply in (optional)
    UserID   string // native Slack user id (skips email lookup)
}

// ConsentCanceler routes a "Cancel" click back to authgate.Engine.Resolve(
// subject, server, DecisionTimeout).
type ConsentCanceler func(ctx context.Context, subject, server string) error

Slack adapter implementation — forge-plugins/channels/slack/consent.go (new)

Reuses the existing Socket Mode connection, shared p.client, and p.botToken — no new bot, token, or connection.

• DeliverConsent(ctx, req):
  1. If req.Origin != nil && req.Origin.Adapter == "slack" → post to Origin.Channel (with thread_ts = Origin.ThreadTS when set).
  2. Else resolve the DM target: resolveUserIDByEmail(req.Subject) → users.lookupByEmail (single call, users:read.email — already used for DEFER; not paging users.list), cached; then openDMChannel(userID) → conversations.open {users}, cached.
  3. Post a Block Kit message: a URL button "Connect <server>" → AuthorizeURL (plain link-open, no resolver round-trip), a deadline line, and (optional) a "Cancel" action button.
• Interactive routing reuses the existing handleBlockAction dispatch: a "Cancel" click → p.consentCanceler(ctx, subject, server). The Connect button is a URL button, so it needs no inbound handling — the OAuth callback resolves the gate.
• Optional lifecycle updates: subscribe nothing new — on mcp_auth_resolved / mcp_auth_timeout the runtime can call an adapter update to edit the message to "✅ Connected — resuming" / "⌛ expired". (v1.1; not required for the core loop.)

New Slack scopes: chat:write (have), users:read.email (have, DEFER), im:write (net-new, for conversations.open).

Wiring — forge-cli/cmd/run.go (mirror the DEFER block ~L362)

// After activePlugins is built. Pick the first active consent-capable adapter.
var consentAdapter corechannels.ConsentDeliverer
for _, plugin := range activePlugins {
    if cd, ok := plugin.(corechannels.ConsentDeliverer); ok {
        cd.SetConsentCanceler(func(ctx context.Context, subject, server string) error {
            return postMCPConsent(ctx, agentURL, runner.AuthToken(), subject, server, false) // granted:false
        })
        consentAdapter = cd
        break
    }
}
if consentAdapter != nil {
    runner.SetConsentDeliverer(func(ctx context.Context, subject, server, taskID string, deadline time.Time) error {
        authorizeURL, err := runner.BuildConsentAuthorizeURL(ctx, subject, server) // #332 front-half: Issue(state)+PKCE+redirect
        if err != nil {
            return err // best-effort; Await logs, mcp_auth_required already emitted
        }
        return consentAdapter.DeliverConsent(ctx, corechannels.ConsentPrompt{
            Subject: subject, Server: server, AuthorizeURL: authorizeURL,
            Deadline: deadline, Origin: originFromContext(ctx),
        })
    })
}
// consentAdapter == nil → SetConsentDeliverer never called → deliverer stays nil → emit-only (platform reads).

• postMCPConsent is the consent analog of postDeferDecision — POSTs {subject, server, granted:false} to the agent's POST /mcp/consent (authenticated) for the Cancel path.
• originFromContext reads a ChannelOrigin the Slack adapter stashed on the request ctx at inbound (the one net-new plumbing item — see below).

Origin plumbing (for in-thread reply)

To reply where the user asked, the Slack adapter must stash ChannelOrigin{channel, thread_ts, user_id} on the request context when it forwards an inbound Slack message into the A2A request. That ctx already flows to mcpAuthGate.Await. If this plumbing is deferred, v1 falls back to DM-by-email (routing row 2) — fully functional, just not in-thread. Recommend shipping v1 as DM-by-email and adding origin-thread as a fast follow.

Layering (matches DEFER)

• forge-core/channels — ConsentDeliverer / ConsentPrompt / ConsentCanceler / ChannelOrigin interfaces.
• forge-plugins/channels/slack — consent.go impl (users.lookupByEmail, conversations.open, Block Kit).
• forge-cli/cmd/run.go — wiring closure + postMCPConsent + originFromContext.
• forge-cli/runtime — ConsentDeliverer func type + mcpAuthGate already call the seam; add Runner.BuildConsentAuthorizeURL (the Standalone MCP consent delivery: build authorize URL + deliver login link (#317 follow-up) #332 front-half) + inbound origin capture.
• forge-core/security/authgate — unchanged; Engine.Resolve(subject, server, decision) already fits the Cancel path.

Acceptance (adds to the existing list)

• With the Slack adapter active, a standalone type: user no-grant call delivers a "Connect <server>" login link to the requesting user — in the origin thread when the request came via Slack, else a DM resolved by email.
• With no Slack adapter active, SetConsentDeliverer is not wired; the call parks and only mcp_auth_required is emitted (platform-read path), no regression.
• A Slack delivery failure (unresolvable subject, API error) is non-fatal — the parked call still resumes via the callback, and mcp_auth_required remains the backstop.
• Optional Cancel button resolves the gate DecisionTimeout via POST /mcp/consent {granted:false}.
• Reuses the existing Socket Mode connection + bot token (no new Slack app/connection); only im:write is added.

Out of scope (unchanged + additions)

• Managed platform-side delivery (still supported via emit-only fallback; not removed).
• MS Teams / other adapters implementing ConsentDeliverer — same interface, follow-up per adapter.
• The message-lifecycle edits ("Connected/expired") — v1.1.

[initializ-mk]

Scope split: Forge-driven Slack (channel) delivery is now tracked in #343 — the detailed design comment above has moved there, refined with the key point that the delivery leg (who DMs the link) is independent of the callback leg (who receives the code / holds the refresh token), so the same Slack delivery works for both standalone (Forge-built URL) and managed (platform-supplied URL via a new SetAuthorizeURLProvider seam).

This issue (#332) now covers standalone only: build the authorize URL, host the loopback callback, and deliver the link via the A2A auth-required artifact. Body updated accordingly.