authz

type Config struct {
	Driver   string
	Resource string
	Issuer   string
	// Scopes are advertised as supported in protected-resource metadata. Each
	// value must be a non-empty RFC 6749 scope-token other than offline_access.
	Scopes []string
	// RequiredScopes are required on every protected MCP operation and follow
	// the same syntax restrictions as Scopes.
	RequiredScopes []string
	DriverConfig   any
	// ContinuationKey authenticates framework-owned MRTR continuation state.
	// It must contain at least 32 bytes and is never exposed on the wire.
	ContinuationKey []byte
	// ExposeRawToken makes the validated inbound bearer token retrievable from
	// the handler context via RawTokenFromContext, for the sole purpose of
	// presenting it as an RFC 8693 subject_token to a trusted token-exchange
	// endpoint. Default false: the token is discarded after validation (D-201).
	//
	// Enable only when the server performs delegated token exchange. The token
	// is exposed ONLY after full validation (signature, issuer, resource,
	// subject, required scopes). It is request-scoped, never persisted, never
	// placed in durable Task or MRTR continuation state, and must never be
	// logged or forwarded to any endpoint other than the trusted exchange.
	ExposeRawToken bool
	// UnauthenticatedHandshake serves the MCP lifecycle and discovery methods
	// WITHOUT requiring a token, and requires a valid token only on invocation
	// methods. The exempt set is a Dockyard-owned, deny-by-default allowlist —
	// lifecycle (initialize, notifications/initialized, ping, server/discover)
	// and discovery (tools/list, resources/list, resources/templates/list,
	// prompts/list), plus the transport-lifecycle GET (SSE stream-open) and
	// DELETE (session teardown). Every other method — tools/call, resources/read,
	// resources/subscribe, resources/unsubscribe, prompts/get, completion/complete,
	// logging/setLevel, tasks/*, any notification other than initialized, and any
	// unknown or future method — still requires a valid token (deny-by-default),
	// so an invocation can never be accidentally exposed. Default false: every
	// method is protected (the current behavior).
	//
	// A token presented on an exempt method is still validated for identity
	// (signature, issuer, resource, subject) and its principal populated (so
	// tools/list can be identity-filtered); RequiredScopes are NOT enforced on an
	// exempt method (they gate invocation, not discovery), a token's ABSENCE is
	// not an error, and an invalid token is still rejected. Invocation methods
	// missing a valid token receive 401 + the Bearer challenge exactly as today.
	// A JSON-RPC batch is exempt only when every element is an exempt method; any
	// invocation element requires a valid token for the whole batch.
	//
	// This is the Stowage/D-152 posture: discovery is public, invocation is
	// protected. It makes tool names, schemas, and descriptions discoverable
	// without a token — the intended trade for a multi-user runtime that opens
	// one shared connection and only holds a per-user token at tool-call time
	// (D-202). Off by default; existing servers are unaffected.
	UnauthenticatedHandshake bool
}

type Factory func(context.Context, Config) (Validator, error)

type Principal struct {
	Issuer   string
	Subject  string
	Resource string
	Scopes   []string
}

type ProtectedResourceMetadata struct {
	Resource               string   `json:"resource"`
	AuthorizationServers   []string `json:"authorization_servers"`
	ScopesSupported        []string `json:"scopes_supported,omitempty"`
	BearerMethodsSupported []string `json:"bearer_methods_supported"`
}

type Validator interface {
	Validate(context.Context, string) (Principal, error)
}