akanjs 3.0.0-alpha.100 → 3.0.0-alpha.101

package/common/TrustedProxy.ts

@@ -51,9 +51,14 @@ export class TrustedProxy {
   /**
    * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
    * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
+   *
+   * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
+   * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
+   * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
+   * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
    */
   static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
-    if (TrustedProxy.isTrusted(peerAddress)) {
+    if (peerAddress === null || TrustedProxy.isTrusted(peerAddress)) {
       const realIp = headers.get("x-real-ip")?.trim();
       if (realIp) return normalizeIpAddress(realIp);
       const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();

package/constant/cascadePaths.ts

@@ -6,8 +6,10 @@ import type { ConstantModelRef } from "./via";
  * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
  * document is removed; `removeWith` removes this document when what the field points at is removed. The two
  * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
+ * `removeWithAny` is `removeWith` over an owner that is unknowable at build time, and it names the whole
+ * decision in one value so the widening cannot be declared apart from the direction it widens.
  */
-export const cascadeActions = ["removeRef", "removeWith"] as const;
+export const cascadeActions = ["removeRef", "removeWith", "removeWithAny"] as const;
 export type CascadeAction = (typeof cascadeActions)[number];
 
 /** How a `removeWith` field names the owner whose removal takes this document with it. */
@@ -21,7 +23,7 @@ export interface CascadeWithPath {
   readonly typeKey: string | null;
   /** The refNames `typeKey` may hold. Empty unless the field is polymorphic over an enum. */
   readonly typeValues: readonly string[];
-  /** Set by `polymorphic: "any"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
+  /** Set by `cascade: "removeWithAny"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
   readonly anyOwner: boolean;
 }
 
@@ -35,7 +37,6 @@ export class CascadePaths {
 
   collect(fieldMap: FieldObject) {
     for (const [key, field] of Object.entries(fieldMap)) {
-      this.#assertPolymorphicIsWiredUp(key, field);
       if (!field.cascade) continue;
       this.#assertKnownAction(key, field.cascade);
       if (field.cascade === "removeRef") this.removeRef.set(key, this.#readOwnedRelation(key, field));
@@ -44,16 +45,6 @@ export class CascadePaths {
     return this;
   }
 
-  /** `polymorphic` widens one thing and nothing else, so anywhere else it is a declaration that does nothing. */
-  #assertPolymorphicIsWiredUp(key: string, field: ConstantField) {
-    if (!field.polymorphic) return;
-    if (field.cascade === "removeWith" && field.refPath) return;
-    throw new Error(
-      `Field "${key}" declares polymorphic: "${field.polymorphic}", which only widens a ` +
-        `cascade: "removeWith" field that names its owner type with refPath`,
-    );
-  }
-
   #assertKnownAction(key: string, action: CascadeAction) {
 
     if (!cascadeActions.includes(action)) {
@@ -74,7 +65,15 @@ export class CascadePaths {
 
     if (field.arrDepth > 0) throw new Error(`Cascade field "${key}" is an array and names more than one owner`);
     if (field.isMap) throw new Error(`Cascade field "${key}" is a Map and names no owner`);
-    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap);
+    const anyOwner = field.cascade === "removeWithAny";
+    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap, anyOwner);
+    
+    if (anyOwner) {
+      throw new Error(
+        `Cascade field "${key}" declares cascade: "removeWithAny" and must name the field holding the owner's ` +
+          `refName with refPath: "<typeField>"`,
+      );
+    }
     if (field.ref) {
       this.#assertHoldsId(key, field);
       return { key, modelRef: null, refName: field.ref, typeKey: null, typeValues: [], anyOwner: false };
@@ -88,18 +87,18 @@ export class CascadePaths {
     );
   }
 
-  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject, anyOwner: boolean): CascadeWithPath {
     if (field.ref) throw new Error(`Cascade field "${key}" declares both ref and refPath; keep one`);
     this.#assertHoldsId(key, field);
     const typeKey = field.refPath as string;
     const typeField = fieldMap[typeKey];
     if (!typeField) throw new Error(`Cascade field "${key}" declares refPath: "${typeKey}", which is not a field`);
-    if (field.polymorphic === "any") return this.#readAnyOwner(key, typeKey, typeField);
+    if (anyOwner) return this.#readAnyOwner(key, typeKey, typeField);
 
     if (!typeField.enum) {
       throw new Error(
         `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
-          `refNames it may hold; declare polymorphic: "any" to pay for a sweep on every removal instead`,
+          `refNames it may hold; declare cascade: "removeWithAny" to pay for a sweep on every removal instead`,
       );
     }
     const typeValues = typeField.enum.values.map((value) => String(value));
@@ -110,14 +109,15 @@ export class CascadePaths {
     
     if (typeField.enum) {
       throw new Error(
-        `Cascade field "${key}" declares polymorphic: "any" and a refPath naming an enumOf(...); keep one`,
+        `Cascade field "${key}" declares cascade: "removeWithAny" and a refPath naming an enumOf(...), which ` +
+          `already names its owners; use cascade: "removeWith"`,
       );
     }
 
     if (this.#primitiveNameOf(typeField) !== "String") {
       throw new Error(
-        `Cascade field "${key}" declares polymorphic: "any", so refPath: "${typeKey}" must be a String field ` +
-          `holding the owner's refName`,
+        `Cascade field "${key}" declares cascade: "removeWithAny", so refPath: "${typeKey}" must be a String ` +
+          `field holding the owner's refName`,
       );
     }
     return { key, modelRef: null, refName: null, typeKey, typeValues: [], anyOwner: true };

package/constant/fieldInfo.ts

@@ -106,11 +106,6 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
-  /**
-   * Widens a `cascade: "removeWith"` field whose `refPath` names a free-form `String` instead of an `enumOf`:
-   * the owner is whatever refName the row happens to hold, found by sweeping at removal time.
-   */
-  polymorphic?: "any";
   /**
    * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
    * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
@@ -209,7 +204,6 @@ interface ConstantFieldBuildProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
-  polymorphic?: "any";
   visual: boolean;
   modelRef: ConstantModelRef;
   arrDepth: number;
@@ -335,7 +329,6 @@ export class ConstantField<
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
   readonly cascade?: CascadeAction;
-  readonly polymorphic?: "any";
   readonly visual: boolean;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
@@ -369,7 +362,6 @@ export class ConstantField<
     this.validate = props.validate;
     this.text = props.text;
     this.cascade = props.cascade;
-    this.polymorphic = props.polymorphic;
     this.visual = props.visual;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
@@ -450,7 +442,6 @@ export class ConstantField<
       validate: option.validate,
       text: option.text,
       cascade: option.cascade,
-      polymorphic: option.polymorphic,
       visual: option.visual ?? false,
       modelRef,
       arrDepth: arrDepth,
@@ -498,7 +489,6 @@ export class ConstantField<
       validate: this.validate,
       text: this.text,
       cascade: this.cascade,
-      polymorphic: this.polymorphic,
       visual: this.visual,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,
@@ -523,19 +513,35 @@ export interface FieldObject {
  */
 type WithoutTextRole<Option> = Option extends unknown ? Omit<Option, "text"> : never;
 
+/**
+ * A wildcard owner is read off the row at removal time, so `removeWithAny` without a `refPath` names nothing to
+ * read it from — and the price of that action (no cascade in the app removes in one query) is one nobody should
+ * pay for a declaration that cascades nothing. Pairing the two in the option type refuses it at the call site;
+ * `CascadePaths` keeps the same refusal for the macro and bundled paths that reach it without a typecheck.
+ */
+type CascadeOption =
+  | { cascade?: "removeRef" | "removeWith"; refPath?: string }
+  | { cascade: "removeWithAny"; refPath: string };
+
+type WithCascadePair<Option> = Omit<Option, "cascade" | "refPath"> & CascadeOption;
+
 type FieldOption<
   Value extends ConstantFieldTypeInput,
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
   Metadata extends { [key: string]: any } = { [key: string]: any },
   _FieldToValue = FieldToValue<Value, MapValue> | null | undefined,
 > =
-  | Omit<
-      ConstantFieldProps<ConstantFieldKind, _FieldToValue, MapValue, Metadata>,
-      "enum" | "meta" | "nullable" | "fieldType" | "select"
+  | WithCascadePair<
+      Omit<
+        ConstantFieldProps<ConstantFieldKind, _FieldToValue, MapValue, Metadata>,
+        "enum" | "meta" | "nullable" | "fieldType" | "select"
+      >
     >
-  | Omit<
-      ConstantFieldProps<ConstantFieldKind, SingleValue<_FieldToValue>, MapValue, Metadata>,
-      "enum" | "meta" | "nullable" | "fieldType" | "select"
+  | WithCascadePair<
+      Omit<
+        ConstantFieldProps<ConstantFieldKind, SingleValue<_FieldToValue>, MapValue, Metadata>,
+        "enum" | "meta" | "nullable" | "fieldType" | "select"
+      >
     >[];
 
 export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ...infer Rest]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.100",
+  "version": "3.0.0-alpha.101",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanAppHeaders.ts

@@ -23,7 +23,7 @@ export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?:
   for (const key of HOP_BY_HOP_HEADERS) headers.delete(key);
   const forwardedFor = headers.get("x-forwarded-for");
 
-  const clientAddress = TrustedProxy.clientAddress(headers, peer?.address);
+  const clientAddress = TrustedProxy.clientAddress(headers, peer === null ? null : peer?.address);
   const host = headers.get("host");
 
   if (clientAddress) {

package/server/akanOption.ts

@@ -20,7 +20,7 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   readonly #adaptorOverrides: AdaptorOverride[] = [];
   readonly #webProxies: WebProxyRegistration[] = [];
   readonly #getLlms: ((env: Env) => LlmOption)[] = [];
-  #mcp: boolean | McpServerOption | undefined;
+  #getMcp: ((env: Env) => boolean | McpServerOption) | undefined;
   #agentAccess: GuardCls | GuardCls[] | null | undefined;
   #crossSite: CrossSiteOption | undefined;
   constructor() {
@@ -48,10 +48,11 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   /**
    * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
    * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
-   * over every library it depends on.
+   * over every library it depends on. The function form receives the server env, for a setting derived from it —
+   * a token verifier built on the app's signing secret, the issuer an authorization server publishes under.
    */
-  setMcp(mcp: boolean | McpServerOption = true) {
-    this.#mcp = mcp;
+  setMcp(mcpOrFn: boolean | McpServerOption | ((env: Env) => boolean | McpServerOption) = true) {
+    this.#getMcp = typeof mcpOrFn === "function" ? mcpOrFn : () => mcpOrFn;
     return this;
   }
   /**
@@ -91,8 +92,8 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   getWebProxies(): WebProxyRegistration[] {
     return this.#webProxies;
   }
-  getMcp(): boolean | McpServerOption | undefined {
-    return this.#mcp;
+  getMcp(env: Env): boolean | McpServerOption | undefined {
+    return this.#getMcp?.(env);
   }
   getAgentAccess(): GuardCls | GuardCls[] | null | undefined {
     return this.#agentAccess;

package/server/akanServer.ts

@@ -195,7 +195,7 @@ export class AkanServer {
     this.openapi = options?.openapi ?? this.openapi;
     
     libs.forEach((lib) => {
-      const mcp = lib.option.getMcp();
+      const mcp = lib.option.getMcp(this.env);
       if (mcp !== undefined) this.setMcp(mcp);
       const agentAccess = lib.option.getAgentAccess();
       if (agentAccess !== undefined) AgentRelayAccess.use(agentAccess);

package/server/di/utils.ts

@@ -72,7 +72,7 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
  * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
  * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
  * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
- * `polymorphic: "any"` names no module at all.
+ * `cascade: "removeWithAny"` names no module at all.
  */
 export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
   const dependencies = new Set<string>();

package/server/index.ts

@@ -7,6 +7,7 @@ export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch";
+export * from "./oauth";
 export * from "./processMetricsCollector";
 export * from "./proxy";
 

package/server/mcp/McpAuth.ts

@@ -1,12 +1,23 @@
+import type { PromiseOrObject } from "akanjs/base";
 import type { HttpRoutes } from "../types";
 
 export interface McpAuthOption {
-  /** Where a client may obtain a token, published in the metadata document for it to discover. */
+  /**
+   * Where a client may obtain a token, published in the metadata document for it to discover. Naming one also
+   * makes a credential mandatory: an MCP client begins its OAuth flow only on a 401, so a server that let an
+   * anonymous `initialize` succeed would leave it connected to the anonymous shelf and never asking.
+   */
   authorizationServers?: string[];
   /** Scopes every call must carry. Declaring any turns `insufficient_scope` enforcement on. */
   scopes?: string[];
   /** Overrides the resource identifier when the public URL differs from what the request reports. */
   resource?: string;
+  /**
+   * Verifies a bearer token's signature and returns its claims, or `null` for one this server did not mint. The
+   * framework holds no signing key, so the module that issues tokens supplies this through `option.setMcp`; without
+   * it the claims are read unverified and a forged token degrades to an anonymous caller instead of being refused.
+   */
+  verify?: (token: string) => PromiseOrObject<Record<string, unknown> | null>;
 }
 
 export interface McpAuthProps extends McpAuthOption {
@@ -48,34 +59,65 @@ export class McpAuth {
     };
   }
 
+  /**
+   * A request that carried no credential at all gets a challenge with no `error` code — RFC 6750 §3.1 reserves
+   * the code for a credential that was presented and found wanting — so a client reads it as "authenticate",
+   * not as "your token is bad".
+   */
   unauthorized(req: Request, failure?: McpAuthFailure) {
-    const { status, error, description } = failure ?? {
-      status: 401 as const,
-      error: "invalid_token" as const,
-      description: "Authentication is required to use this MCP server.",
-    };
+    const status = failure?.status ?? 401;
+    const description = failure?.description ?? "Authentication is required to use this MCP server.";
     return Response.json(
-      { error, error_description: description },
-      { status, headers: { "WWW-Authenticate": this.#challenge(req, error, description) } },
+      { ...(failure ? { error: failure.error } : {}), error_description: description },
+      { status, headers: { "WWW-Authenticate": this.#challenge(req, failure) } },
     );
   }
 
   /**
    * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
    *
-   * The claims are read **without verifying the signature**, which is sound only because every branch below can
-   * deny and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst
-   * a crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
+   * With a `verify` hook the token is checked end to end and one that fails is refused outright. Without one the
+   * claims are read **without verifying the signature**, which is sound only because every branch below can deny
+   * and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst a
+   * crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
    * foreign token otherwise degrades to an anonymous caller, and the agent is told a tool does not exist rather
    * than that it needs to authenticate.
    */
-  reject(req: Request): Response | null {
-    const claims = McpAuth.#claims(req);
-    if (!claims) return null;
+  async reject(req: Request): Promise<Response | null> {
+    const token = McpAuth.#bearer(req);
+    if (!token) return null;
+    const claims = this.#props.verify ? await this.#verified(token) : McpAuth.#claims(token);
+    if (!claims) {
+      if (!this.#props.verify) return null;
+      return this.unauthorized(req, {
+        status: 401,
+        error: "invalid_token",
+        description: "The access token could not be verified.",
+      });
+    }
     const failure = this.#failureOf(claims, req);
     return failure ? this.unauthorized(req, failure) : null;
   }
 
+  /**
+   * The 401 a credential-less request gets once an authorization server is named. A server naming none keeps
+   * anonymous access, which is what a public catalogue wants; the public tools of a server naming one are still
+   * reachable, with the token the challenge sends the client off to obtain.
+   */
+  challengeAnonymous(req: Request): Response | null {
+    if (!this.#props.authorizationServers?.length || McpAuth.#bearer(req)) return null;
+    return this.unauthorized(req);
+  }
+
+  /** A verifier that throws has said no: the token is refused, never let through as an anonymous caller. */
+  async #verified(token: string): Promise<Record<string, unknown> | null> {
+    try {
+      return (await this.#props.verify?.(token)) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   #failureOf(claims: Record<string, unknown>, req: Request): McpAuthFailure | null {
     const { exp, aud } = claims;
     if (typeof exp === "number" && exp * 1000 <= Date.now())
@@ -123,14 +165,13 @@ export class McpAuth {
     );
   }
 
-  #challenge(req: Request, error: string, description: string) {
+  #challenge(req: Request, failure?: McpAuthFailure) {
     const scopes = this.#props.scopes ?? [];
     return [
       "Bearer",
       [
         `resource_metadata="${new URL(McpAuth.wellKnownPath + this.#props.path, McpAuth.origin(req)).href}"`,
-        `error="${error}"`,
-        `error_description="${description}"`,
+        ...(failure ? [`error="${failure.error}"`, `error_description="${failure.description}"`] : []),
         ...(scopes.length ? [`scope="${scopes.join(" ")}"`] : []),
       ].join(", "),
     ].join(" ");
@@ -161,9 +202,12 @@ export class McpAuth {
     return `${forwarded("x-forwarded-proto") ?? url.protocol.replace(":", "")}://${host}`;
   }
 
-  static #claims(req: Request): Record<string, unknown> | null {
+  static #bearer(req: Request): string | null {
     const [scheme, token] = (req.headers.get("authorization") ?? "").split(" ");
-    if (scheme !== "Bearer" || !token) return null;
+    return scheme === "Bearer" && token ? token : null;
+  }
+
+  static #claims(token: string): Record<string, unknown> | null {
     const segments = token.split(".");
 
     if (segments.length !== 3) return null;

package/server/mcp/McpDispatcher.ts

@@ -1,5 +1,5 @@
 import { type BackendEnv, ENDPOINT_META } from "akanjs/base";
-import { Logger } from "akanjs/common";
+import { interpolateTranslation, Logger } from "akanjs/common";
 import { ConstantRegistry, mask } from "akanjs/constant";
 import { DictionaryLookup } from "akanjs/dictionary";
 import { NoDocumentError } from "akanjs/document";
@@ -203,13 +203,14 @@ export class McpDispatcher {
 
     if (error instanceof NoDocumentError) return `No ${refName} found for the arguments given.`;
     if (status && status < 500) {
+
+      if (status === 401 || status === 403) return "You are not permitted to perform this action.";
       const raw = error instanceof Error ? error.message : String(error);
       
       this.#lookup ??= new DictionaryLookup(this.#props.language);
       const text = this.#lookup.text(raw);
-      if (text) return text;
 
-      if (status === 401 || status === 403) return "You are not permitted to perform this action.";
+      if (text) return interpolateTranslation(text, (error as { data?: Record<string, unknown> }).data);
       return raw;
     }
 

package/server/mcp/McpRouter.ts

@@ -158,6 +158,7 @@ export class McpRouter {
         McpRouter.logger.warn(
           "MCP is enabled but published nothing. Every candidate was refused; see the reasons below.",
         );
+      this.#reportUnverifiable(tools.map((tool) => tool.name));
       for (const { key, reason } of refusals) McpRouter.logger.verbose(`MCP did not expose "${key}": ${reason}`);
       for (const { key, reason } of undescribed)
         McpRouter.logger.warn(`MCP exposed "${key}" with no description: ${reason}`);
@@ -169,6 +170,24 @@ export class McpRouter {
     }
   }
 
+  /**
+   * A guarded tool is only reachable with a credential, and this server can neither issue one nor check one unless
+   * something configured `auth`. Left silent, the shelf lists tools no client can ever call and a forged token
+   * reads as anonymous — so it is said once at boot, and said louder anywhere but a developer's machine.
+   */
+  #reportUnverifiable(toolNames: string[]) {
+    const { verify, authorizationServers } = this.#props.auth ?? {};
+    if (verify || authorizationServers?.length) return;
+    const document = this.#getDocument();
+    const guarded = toolNames.filter((name) =>
+      (document.findTool(name)?.endpoint.guards ?? []).some((guard) => guard !== "Public"),
+    ).length;
+    if (!guarded) return;
+    const line = `MCP publishes ${guarded} guarded tool(s) but no authorization server is configured: a client cannot obtain a token for them, and a bearer token's signature is not checked here. Set \`auth.verify\` and \`auth.authorizationServers\` through option.setMcp (a module that issues tokens does this), or AKAN_MCP_AUTH_SERVERS.`;
+    if (getEnv().operationMode === "local") McpRouter.logger.warn(line);
+    else McpRouter.logger.error(line);
+  }
+
   static #kb(bytes: number) {
     return bytes < 1024 ? `${bytes}B` : `${Math.round(bytes / 1024)}KB`;
   }
@@ -196,7 +215,9 @@ export class McpRouter {
 
   async #post(req: Request) {
     if (!this.#originAllowed(req)) return new Response("Forbidden", { status: 403 });
-    const rejected = this.#auth.reject(req);
+
+    req.headers.delete("cookie");
+    const rejected = this.#auth.challengeAnonymous(req) ?? (await this.#auth.reject(req));
     if (rejected) return rejected;
     let body: McpJsonRpcRequest;
     try {

package/server/oauth/OAuthAuthorize.ts

@@ -0,0 +1,84 @@
+import { OAuthErrors } from "./OAuthErrors";
+import { OAuthPkce } from "./OAuthPkce";
+import { OAuthRedirect } from "./OAuthRedirect";
+import type { OAuthAuthorizeErrorCode, OAuthAuthorizeParams, OAuthClientRecord } from "./oauthTypes";
+
+export interface OAuthAuthorizeContext {
+  /** The client the request's `client_id` resolved to, however it was registered; `null` when it resolved to nothing. */
+  client: OAuthClientRecord | null;
+  issuer: string;
+  /** The one resource this server issues tokens for — the MCP endpoint's canonical URL. */
+  resource: string;
+}
+
+export type OAuthAuthorizeResult = { ok: true; params: OAuthAuthorizeParams } | { ok: false; response: Response };
+
+export class OAuthAuthorize {
+  /**
+   * Validates in the order RFC 6749 §4.1.2.1 prescribes: the client and its redirect URI first, answered with a page
+   * because nothing may be redirected to an unverified destination; everything after that is answered through the
+   * redirect URI the client registered, with `state` and `iss` so the client can match and trust the answer.
+   */
+  static parse(url: URL, { client, issuer, resource }: OAuthAuthorizeContext): OAuthAuthorizeResult {
+    const param = (name: string) => url.searchParams.get(name) ?? undefined;
+    const clientId = param("client_id");
+    if (!clientId) return OAuthAuthorize.#page("Missing client", "The authorization request names no client_id.");
+    if (!client) return OAuthAuthorize.#page("Unknown client", `No client is registered as "${clientId}".`);
+    
+    const redirectUri =
+      param("redirect_uri") ?? (client.redirectUris.length === 1 ? client.redirectUris[0] : undefined);
+    if (!redirectUri)
+      return OAuthAuthorize.#page(
+        "Missing redirect URI",
+        "The client registered several redirect URIs and named none.",
+      );
+    if (!OAuthRedirect.matches(client.redirectUris, redirectUri))
+      return OAuthAuthorize.#page(
+        "Redirect URI not registered",
+        `"${redirectUri}" is not a redirect URI registered for this client.`,
+      );
+    const state = param("state");
+    const fail = (error: OAuthAuthorizeErrorCode, description: string): OAuthAuthorizeResult => ({
+      ok: false,
+      response: OAuthErrors.redirect(redirectUri, { error, description, state, iss: issuer }),
+    });
+    if (param("response_type") !== "code")
+      return fail("unsupported_response_type", "Only response_type=code is supported.");
+    if (!client.grantTypes.includes("authorization_code"))
+      return fail("unauthorized_client", "This client is not registered for the authorization_code grant.");
+    const codeChallenge = param("code_challenge");
+    const method = param("code_challenge_method");
+
+    if (method !== undefined && method !== OAuthPkce.method)
+      return fail("invalid_request", `code_challenge_method "${method}" is not supported; use ${OAuthPkce.method}.`);
+    if (!OAuthPkce.isChallenge(codeChallenge)) return fail("invalid_request", "A PKCE code_challenge is required.");
+    if (method === undefined)
+      return fail("invalid_request", `code_challenge_method is required and must be ${OAuthPkce.method}.`);
+    const requested = param("resource");
+    if (requested !== undefined && !OAuthAuthorize.sameResource(requested, resource))
+      return fail("invalid_target", `This server issues tokens for ${resource} only.`);
+    return {
+      ok: true,
+      params: { clientId, redirectUri, codeChallenge, state, resource, scope: param("scope") },
+    };
+  }
+
+  /** RFC 8707 §2 compares resource identifiers as URIs, so a trailing slash a client added is not another server. */
+  static sameResource(a: string, b: string): boolean {
+    return OAuthAuthorize.#canonical(a) === OAuthAuthorize.#canonical(b);
+  }
+
+  static #canonical(resource: string): string {
+    try {
+      const url = new URL(resource);
+      url.hash = "";
+      return url.href.replace(/\/$/, "");
+    } catch {
+      return resource;
+    }
+  }
+
+  static #page(title: string, detail: string): OAuthAuthorizeResult {
+    return { ok: false, response: OAuthErrors.page(400, title, detail) };
+  }
+}