forgejo-mcp/openspec/specs/stateless-http-auth/spec.md

stateless-http-auth

Purpose

Enable per-request authentication for the HTTP and SSE transports by extracting a token from the Authorization header and constructing a request-scoped Forgejo client, while preserving the pre-existing global-token (singleton) behavior for the stdio transport. This allows a single server process to serve multiple distinct Forgejo identities concurrently without leaking credentials across requests.

Requirements

Requirement: HTTP transport extracts per-request token from Authorization header

When the server is started with --transport http, every incoming MCP request SHALL be inspected for an Authorization header. The header SHALL be parsed for one of two schemes, case-insensitively:

1. token <X> — Forgejo's native token scheme.
2. Bearer <X> — OAuth2-style bearer transport.

When a recognized scheme is present, the parsed token value SHALL be injected into the request context.Context via forgejo.WithToken(ctx, token). The MCP handler invoked for that request receives the augmented context.

When the Authorization header is absent, empty, or carries an unrecognized scheme, the request context.Context SHALL NOT carry a token. Downstream code falls back to the global singleton client (see "Token-aware client factory" below).

The transport MUST NOT accept tokens without a scheme prefix; a header value that does not match one of the two named schemes SHALL be treated as if no header were present.

Scenario: Request with token scheme injects the token

• WHEN an HTTP request arrives with header Authorization: token abc123
• THEN the system SHALL inject abc123 into the request context via forgejo.WithToken
• AND the MCP handler SHALL see that token via forgejo.Client(ctx)

Scenario: Request with Bearer scheme injects the token

• WHEN an HTTP request arrives with header Authorization: Bearer abc123
• THEN the system SHALL inject abc123 into the request context

Scenario: Scheme matching is case-insensitive

• WHEN an HTTP request arrives with header Authorization: bearer abc123 (lowercase)
• OR with header Authorization: TOKEN abc123 (uppercase)
• THEN the system SHALL inject abc123 into the request context the same as it would for the canonical-case form

Scenario: Absent header falls through to global client

• WHEN an HTTP request arrives with no Authorization header
• THEN the request context SHALL NOT carry a token
• AND forgejo.Client(ctx) SHALL return the process-wide singleton initialized from the --token flag

Scenario: Bare token (no scheme) is rejected

• WHEN an HTTP request arrives with header Authorization: abc123 (no scheme prefix)
• THEN the system SHALL treat the request as if no Authorization header were present
• AND the system SHALL fall through to the global singleton client

Requirement: SSE transport extracts per-request token from Authorization header

When the server is started with --transport sse, the SSE server SHALL apply the same Authorization-header extraction rules as the HTTP transport (above), via the SDK's WithSSEContextFunc. All scheme-matching scenarios apply identically.

Scenario: SSE request with Bearer scheme injects the token

• WHEN an SSE request arrives with header Authorization: Bearer abc123
• THEN the system SHALL inject abc123 into the request context the same as the HTTP transport would

Requirement: Token-aware client factory selects ephemeral or singleton client

The function forgejo.Client(ctx context.Context) *forgejo.Client SHALL be the single entry point used by every tool handler to obtain a Forgejo SDK client.

When the supplied ctx carries a non-empty token (set via forgejo.WithToken), Client SHALL construct a fresh, request-scoped SDK client via forgejo.NewClient(flag.URL, forgejo.SetToken(token)) and return it. This client SHALL NOT be cached, shared, or reused across requests.

When the supplied ctx carries no token, Client SHALL return the process-wide singleton client. The singleton SHALL be initialized lazily on first call via sync.Once, using flag.Token as the credential. This preserves the pre-existing stdio behavior verbatim.

Scenario: Context with token returns ephemeral client

• WHEN forgejo.Client(ctx) is called with a context that carries token=abc123
• THEN the system SHALL return a freshly constructed *forgejo.Client configured with abc123
• AND the returned client SHALL NOT be the package singleton

Scenario: Context without token returns singleton

• WHEN forgejo.Client(ctx) is called with a context that carries no token
• THEN the system SHALL return the package singleton constructed from flag.Token
• AND consecutive calls SHALL return the same pointer

Requirement: Failed ephemeral construction MUST NOT fall through to the singleton

When forgejo.Client(ctx) is called with a context that carries a token, but the SDK call forgejo.NewClient(...) returns an error (e.g. the SDK's server-version probe fails on a network error, slow response, or HTTP 5xx from Forgejo), the function MUST NOT return the package singleton. Returning the singleton would silently authenticate the request as the startup --token identity instead of the requested per-request identity — a silent identity downgrade with privilege-escalation implications.

Instead, the function SHALL surface the failure to the caller. The implementation MAY accomplish this by changing the function signature to return (*forgejo.Client, error), or by returning nil and logging an error at Error level. The chosen mechanism MUST cause the calling tool handler to fail the MCP request rather than silently process it under the wrong identity.

Scenario: Ephemeral construction failure surfaces an error

• WHEN forgejo.Client(ctx) is called with ctx carrying token abc123
• AND the underlying forgejo.NewClient(...) call returns an error
• THEN the system SHALL NOT return the package singleton
• AND the system SHALL surface the error such that the calling tool handler fails the request

Scenario: Ephemeral construction failure does NOT log the token

• WHEN the failure scenario above occurs
• THEN any logged error message or wrapped error chain SHALL NOT contain the value of abc123

Requirement: Per-request clients are isolated across concurrent requests

Two concurrent requests carrying distinct tokens T_A and T_B SHALL produce two distinct, independent SDK clients. Outbound HTTP requests made by request A's handler SHALL carry Authorization: token T_A; outbound requests made by request B's handler SHALL carry Authorization: token T_B. Under no circumstances SHALL request A's client carry T_B, or vice versa, or the global --token value when a per-request token was supplied.

Scenario: Two concurrent requests produce two distinct identities at Forgejo

• GIVEN two goroutines, each obtaining a client via forgejo.Client(ctx) with distinct context tokens T_A and T_B
• WHEN each goroutine makes an outbound SDK call concurrently
• THEN the request originating from goroutine A SHALL arrive at Forgejo carrying Authorization: token T_A
• AND the request originating from goroutine B SHALL arrive carrying Authorization: token T_B

Requirement: Raw HTTP path respects per-request token

The pkg/forgejo/rawhttp.go helper used for attachment upload and download SHALL read the request token from ctx (via tokenFromContext) and prefer it over the global flag.Token value when setting the Authorization header on outbound raw HTTP calls. When no token is present in ctx, the helper SHALL fall back to flag.Token.

Attachment tool handlers in operation/attachment/ SHALL pass their request ctx into this helper so per-request identity is honored for binary operations.

Scenario: Attachment upload uses per-request token

• WHEN an HTTP MCP request with Authorization: token abc123 invokes create_issue_attachment
• THEN the outbound HTTP POST to Forgejo's attachment endpoint SHALL carry Authorization: token abc123 in its headers, not the global --token value

Requirement: Stdio transport preserves pre-existing global-token behavior

When the server is started with --transport stdio, no Authorization extraction SHALL be performed. Tool handlers under stdio receive a context that carries no token; forgejo.Client(ctx) returns the package singleton initialized from --token. All pre-existing stdio behavior, including tests, SHALL remain valid.

Scenario: Stdio handler receives global-token client

• WHEN the server is run with --transport stdio --token xyz789
• AND a tool handler invokes forgejo.Client(ctx)
• THEN the system SHALL return the package singleton client constructed from xyz789
• AND consecutive calls within and across handlers SHALL return the same client pointer