mcp-authz 0.1.0 → 0.3.0

package/dist/testing.js

@@ -0,0 +1,176 @@
+import { InMemoryTransport } from "@modelcontextprotocol/server";
+import { createHash } from "node:crypto";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+//#region src/permissions-module.ts
+/**
+* A permission map to start from, priced so it cannot be forgotten.
+*
+* Every capability gets a placeholder no role grants, which `reconcile` reports
+* as unreachable and the boot refuses. The scaffold is deliberately useless
+* until a person has decided what each capability costs — that decision is the
+* whole point of the file, and a default would quietly make it for them.
+*
+* Returned as source rather than written, so the caller chooses where it lands.
+*/
+const UNASSIGNED = "TODO:unassigned";
+function toPermissionsModule(record) {
+	return [
+		"// Generated from a recorded catalogue. Replace every TODO with a real permission.",
+		"",
+		"export const PERMISSIONS = {",
+		...record.names.map((label) => `  ${quote(label)}: ${literal(UNASSIGNED)},`),
+		"} as const;",
+		"",
+		"export type Permission = (typeof PERMISSIONS)[keyof typeof PERMISSIONS];",
+		...fingerprintLines(record),
+		...resourceUriLines(record.resourceUris ?? {}),
+		""
+	].join("\n");
+}
+/**
+* Only emitted when the recorder could produce digests. An OpenAPI document is
+* already a file in the repository, diffed on the pull request by whoever
+* changed it, so there is nothing for a second baseline to catch.
+*/
+function fingerprintLines(record) {
+	const fingerprints = record.fingerprints ?? {};
+	if (Object.keys(fingerprints).length === 0) return [];
+	return [
+		"",
+		"// What each capability looked like when this was recorded. A separate export",
+		"// because gate() takes the flat map above; this is the baseline CI compares.",
+		"export const FINGERPRINTS = {",
+		...record.names.map((label) => `  ${quote(label)}: ${literal(fingerprints[label] ?? "")},`),
+		"} as const;"
+	];
+}
+/**
+* Only emitted when the server has resources, so a tools-only map stays a map.
+* `createMcpProxy` needs this to price a read, which names a URI and never a
+* label; `gate()` never sees it.
+*/
+function resourceUriLines(resourceUris) {
+	const labels = Object.keys(resourceUris).sort();
+	if (labels.length === 0) return [];
+	return [
+		"",
+		"// Where each resource answers. createMcpProxy() matches a read against these,",
+		"// templates included, because a resources/read carries a URI and not a label.",
+		"export const RESOURCE_URIS = {",
+		...labels.map((label) => `  ${quote(label)}: ${literal(resourceUris[label] ?? "")},`),
+		"} as const;"
+	];
+}
+/**
+* Bare where it is a valid identifier, quoted where the label carries a prefix.
+*
+* `__proto__` gets neither. In an object literal it sets the prototype instead
+* of creating a property — as an identifier *and* as a string key — so a
+* capability by that name would silently vanish from the map that prices it.
+* Only a computed key makes an own property.
+*/
+function quote(label) {
+	if (label === "__proto__") return `[${literal(label)}]`;
+	return /^[A-Za-z_$][\w$]*$/.test(label) ? label : literal(label);
+}
+/**
+* A string literal, escaped.
+*
+* Names and URIs come from the server being recorded, not from us. A quote or a
+* backslash in either one would otherwise close the literal early and emit a
+* module that does not parse — or, worse, one that parses into something else.
+*/
+function literal(value) {
+	return JSON.stringify(value);
+}
+//#endregion
+//#region src/testing.ts
+function digest(parts) {
+	return createHash("sha256").update(JSON.stringify(canonical(parts))).digest("hex").slice(0, 16);
+}
+/**
+* Key order is an accident of how a value was built, so sort it away. Without
+* this an SDK that emitted the same definition in a different order would churn
+* every fingerprint in a snapshot and teach people to ignore the diff.
+*/
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, inner]) => [key, canonical(inner)]));
+	return value;
+}
+async function recordCapabilities(factory) {
+	const server = await factory();
+	const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+	await server.connect(serverTransport);
+	const client = new Client({
+		name: "mcp-authz-record-capabilities",
+		version: "1.0.0"
+	});
+	await client.connect(clientTransport);
+	try {
+		return await listFrom(client);
+	} finally {
+		await client.close();
+		await server.close();
+	}
+}
+/**
+* Record a server you can only reach by URL.
+*
+* The objection that rules out listing a *gated* server does not apply here: an
+* upstream reached with a service credential answers with everything it has, so
+* the map is complete. Pass `fetch` to drive a handler directly instead of a
+* socket.
+*/
+async function recordUpstream(url, options = {}) {
+	const transport = new StreamableHTTPClientTransport(new URL(url), {
+		...options.fetch ? { fetch: options.fetch } : {},
+		...options.bearer ? { authProvider: { token: async () => options.bearer } } : {}
+	});
+	const client = new Client({
+		name: "mcp-authz-record-capabilities",
+		version: "1.0.0"
+	});
+	await client.connect(transport);
+	try {
+		return await listFrom(client);
+	} finally {
+		await client.close();
+	}
+}
+async function listFrom(client) {
+	{
+		const advertised = client.getServerCapabilities() ?? {};
+		const none = {
+			tools: [],
+			prompts: [],
+			resources: [],
+			resourceTemplates: []
+		};
+		const [tools, prompts, resources, templates] = await Promise.all([
+			advertised.tools ? client.listTools() : none,
+			advertised.prompts ? client.listPrompts() : none,
+			advertised.resources ? client.listResources() : none,
+			advertised.resources ? client.listResourceTemplates() : none
+		]);
+		const labelled = [
+			...tools.tools.map((tool) => [tool.name, tool]),
+			...prompts.prompts.map((prompt) => [`prompt:${prompt.name}`, prompt]),
+			...resources.resources.map((resource) => [`resource:${resource.name}`, resource]),
+			...templates.resourceTemplates.map((template) => [`resource:${template.name}`, template])
+		];
+		const resourceUris = Object.fromEntries([...resources.resources.map((resource) => [`resource:${resource.name}`, resource.uri]), ...templates.resourceTemplates.map((template) => [`resource:${template.name}`, template.uriTemplate])]);
+		const names = labelled.map(([label]) => label).sort();
+		const byLabel = new Map(labelled);
+		return {
+			names,
+			fingerprints: Object.fromEntries(names.map((label) => [label, digest({
+				label,
+				definition: byLabel.get(label)
+			})])),
+			resourceUris
+		};
+	}
+}
+//#endregion
+export { UNASSIGNED, recordCapabilities, recordUpstream, toPermissionsModule };

package/dist/tools-BQE1O-7P.d.ts

@@ -0,0 +1,271 @@
+import { a as PermissionCatalog, l as Principal, s as Policy } from "./policy-DuZbwrKf.js";
+import { CallToolResult, GetPromptResult, Icon, Implementation, McpServer, ReadResourceResult, ResourceMetadata, ResourceTemplate, ServerOptions, StandardSchemaV1, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+//#region src/tools.d.ts
+/**
+ * Tools, prompts and resources that carry the permission they require.
+ *
+ * Declaring it here rather than in a separate rules file is the whole point: it
+ * is checked against the policy by the compiler, reconciled against the policy
+ * at boot, and it cannot drift when somebody renames the tool.
+ *
+ * MCP exposes three things a caller can reach, so gating only tools leaves two
+ * doors open. All three register the same way: check the permission, skip the
+ * registration when the caller lacks it, audit what they do reach.
+ */
+/** Which of the three a caller reached. */
+type Capability = 'tool' | 'prompt' | 'resource';
+/** What actually happened, for the audit log the downstream API cannot write. */
+/**
+ * What happened, and who it was.
+ *
+ * `issuer` and `sub` are required because every path that reaches here is
+ * downstream of a verified bearer token — they come from a `Principal`, which
+ * cannot exist without one. That is what makes this an audit trail rather than
+ * a log of claims somebody sent.
+ *
+ * If a mode ever forwards traffic without verifying identity, **it must omit
+ * identity from its events rather than fill these in from decoded token
+ * claims.** Decoded claims are attacker-controlled, and putting them in a field
+ * named `sub` presents low-integrity data in a high-trust schema: the failure
+ * mode is that it reads exactly like evidence. Give that mode its own event
+ * type, tagged with whether the identity was verified, rather than widening
+ * this one.
+ */
+/**
+ * What an audit record can be about.
+ *
+ * Wider than `Capability` because `mcp-authz/openapi` gates HTTP operations
+ * through the same events, and an auditor reading one store wants one shape.
+ * The definition types stay narrow: an MCP tool cannot declare itself an
+ * `operation`, because there is no such thing to declare.
+ */
+type AuditedKind = Capability | 'operation';
+type AuditEvent = {
+  /**
+   * What this record is, and which shape it is in.
+   *
+   * These events leave the process for somebody's log store and are kept for
+   * years, next to `mcp_authz.decision.v1` records that share half their
+   * fields. A query that tells them apart by guessing which fields are present
+   * breaks the first time either one grows a field.
+   *
+   * A new optional field does not move the `v1`. Changing what an existing
+   * field means does, because a stored query cannot tell that apart.
+   */
+  type: 'mcp_authz.audit.v1';
+  /**
+   * The two events of one call, under one id.
+   *
+   * `attempt` and its terminal event are separate rows in whatever store they
+   * land in, and correlating them by identity and timestamp breaks under
+   * exactly the concurrency that makes the question worth asking.
+   */
+  callId: string;
+  issuer: string;
+  sub: string;
+  email?: string;
+  /**
+   * Verified Workspace domain, when the AS passes `hd` through.
+   *
+   * The nearest thing to an organisation this library can prove. Key one by
+   * `(issuer, domain)`: an issuer alone is right when each customer brings its
+   * own authorization server, and wrong when one server serves them all.
+   */
+  domain?: string;
+  /** Which deployment emitted this, when you named it. */
+  emitter?: string;
+  kind: AuditedKind;
+  /** The registered name, e.g. `update_case`. */
+  name: string;
+  permission: string;
+  /** Whatever the definition's own `audit` said the call touched, e.g. `case:C1234`. */
+  resource?: string;
+  decision: 'allow' | 'deny';
+  phase: 'attempt' | 'success' | 'failure' | 'refused';
+  /** Who approved it, when the capability asked for a second person. */
+  approvedBy?: string;
+  at: string;
+  durationMs?: number;
+  error?: string;
+};
+type AuditSink = (event: AuditEvent) => unknown | Promise<unknown>;
+type AuditDeliveryFailure = {
+  error: unknown;
+  event: AuditEvent;
+};
+type AuditErrorSink = (failure: AuditDeliveryFailure) => unknown | Promise<unknown>;
+/**
+ * What a human is being asked to approve, before it happens.
+ *
+ * Everything here was proved rather than claimed: the identity came off a
+ * verified token and the permission was already checked, so the question left
+ * for a person is only whether this particular call should happen.
+ */
+type ApprovalRequest<A = unknown> = {
+  issuer: string;
+  sub: string;
+  email?: string;
+  kind: Capability;
+  name: string;
+  permission: string;
+  /** The arguments the call would run with, so the message can name them. */
+  arguments: A;
+  /** Whatever the definition's own `audit` said the call touches. */
+  resource?: string;
+  at: string;
+};
+/**
+ * Approving anonymously is not a second pair of eyes, so `by` is required on
+ * the approving branch and the compiler will not let you omit it.
+ */
+type ApprovalDecision = {
+  approved: true;
+  by: string;
+  reason?: string;
+} | {
+  approved: false;
+  by?: string;
+  reason?: string;
+};
+type ApprovalSink = (request: ApprovalRequest) => ApprovalDecision | Promise<ApprovalDecision>;
+/** Thrown into the handler's place when a person said no, or said nothing in time. */
+declare class ApprovalRefusedError extends Error {
+  readonly capability: string;
+  readonly by?: string;
+  constructor(capability: string, reason: string, by?: string);
+}
+type InferArgs<S> = S extends StandardSchemaV1<unknown, infer Output> ? Output : undefined;
+/** Shared by all three: what it costs, and what the call touched. */
+type Gated<P extends string, A> = {
+  /** Required to reach it. Typed to the policy's permissions, so a typo is a build error. */
+  permission: P;
+  /**
+   * Name the thing the call touched, for the audit event. The library cannot
+   * know that `{ caseId: 'C1234' }` means a case; the application always does.
+   */
+  audit?: (args: A) => string | undefined;
+  /**
+   * Ask a person before this runs. `true` for every call, or a predicate when
+   * only some arguments warrant it — a refund over a threshold, a delete that
+   * names production.
+   *
+   * This is not the permission check repeated. The caller already holds the
+   * permission; approval is for actions that want a second person anyway.
+   */
+  approval?: boolean | ((args: A) => boolean);
+};
+type ToolConfig<P extends string, S> = Gated<P, InferArgs<S>> & {
+  title?: string;
+  description?: string;
+  inputSchema?: S;
+  outputSchema?: StandardSchemaWithJSON;
+  annotations?: ToolAnnotations;
+  icons?: Icon[];
+};
+type PromptConfig<P extends string, S> = Gated<P, InferArgs<S>> & {
+  title?: string;
+  description?: string;
+  argsSchema?: S;
+  icons?: Icon[];
+};
+type ResourceConfig<P extends string> = Gated<P, URL> & ResourceMetadata & {
+  /** The URI clients read, or a template for a family of them. */
+  uri: string | ResourceTemplate;
+};
+/**
+ * Erased once built, so a server registers every capability the same way
+ * whatever it accepts.
+ */
+type Definition<P extends string, C = Principal<P>> = {
+  /**
+   * Unique key for the boot-time check. Bare for a tool, prefixed otherwise, so
+   * a prompt sharing a tool's name stays a separate entry rather than shadowing
+   * it.
+   */
+  label: string;
+  kind: Capability;
+  /** Exact protocol name used to refuse an unpermitted direct invocation before scope step-up. */
+  routeName?: string;
+  routeMatches?: (name: string) => boolean;
+  permission: P;
+  /** Whether this definition can ask for a person, so boot can check a sink exists. */
+  approval?: boolean;
+  register: (server: McpServer, principal: Principal<P>, context: C, guards: Guards<unknown>) => void;
+};
+/** What every registration needs to record and, sometimes, to ask. */
+type Guards<A> = {
+  onAudit?: AuditSink;
+  onAuditError?: AuditErrorSink;
+  /** Names this deployment on every event it emits. */
+  emitter?: string;
+  onApproval?: ApprovalSink;
+  approvalTimeoutMs: number;
+  /** Present only when this capability declared one. */
+  needsApproval?: (args: A) => boolean;
+};
+type ServerOptions$1 = Implementation & {
+  /** Called on every permitted invocation. The one record tying a person to an action. */
+  onAudit?: AuditSink;
+  /**
+   * Names this deployment on every event it emits.
+   *
+   * Set the same value in every entry point of one deployment — a dashboard
+   * reading several of them cannot otherwise tell which server a call reached.
+   * Left unset, the field is absent rather than guessed.
+   */
+  emitter?: string;
+  /** Receives a failed terminal audit write without changing the completed action's result. */
+  onAuditError?: AuditErrorSink;
+  /**
+   * Ask a person. Awaited while the caller's request stays open, so this holds
+   * a connection for as long as it takes to answer — required as soon as any
+   * capability declares `approval`, and refused at boot when one does and this
+   * is missing.
+   */
+  onApproval?: ApprovalSink;
+  /**
+   * How long to wait before treating silence as a refusal. Defaults to 45s,
+   * which is under the 60s idle timeout most proxies ship with. Raise it only
+   * as far as whatever sits in front of this server will actually hold.
+   */
+  approvalTimeoutMs?: number;
+  /** Pass-through SDK options; declared gated capabilities are merged in. */
+  mcp?: ServerOptions;
+};
+/**
+ * A per-request server factory over a fixed set of capabilities, plus the
+ * label-to-permission map that `createMcpFetch` reconciles against the policy
+ * at boot.
+ */
+type ServerFactory<C> = ((context: C) => McpServer) & {
+  permissions: ReadonlyMap<string, string>;
+  routePermissions: ReadonlyMap<string, string>;
+  permissionForRoute: (kind: Capability, name: string) => string | undefined;
+  /** The registered route name a concrete request name resolves to, template included. */
+  routeNameFor: (kind: Capability, name: string) => string | undefined;
+};
+/**
+ * Everything bound to one policy: `permission` accepts only what that policy can
+ * grant, in all four places, from one call.
+ *
+ * The policy is a type carrier here and is never invoked. Authorization happens
+ * once per request when the principal is resolved, not once per definition.
+ *
+ * ```ts
+ * const { tool, prompt, resource, server } = authz(policy);
+ * ```
+ */
+declare function bindAuthz<P extends string, C, H>(_permissions: Policy<P> | PermissionCatalog<P>, principalOf: (context: C) => Principal<P>, handlerContext: (context: C, principal: Principal<P>) => H): {
+  tool: <S extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: ToolConfig<P, S>, handler: (args: InferArgs<S>, context: H) => CallToolResult | Promise<CallToolResult>) => Definition<P, C>;
+  prompt: <S extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: PromptConfig<P, S>, handler: (args: InferArgs<S>, context: H) => GetPromptResult | Promise<GetPromptResult>) => Definition<P, C>;
+  resource: (name: string, config: ResourceConfig<P>, handler: (uri: URL, context: H) => ReadResourceResult | Promise<ReadResourceResult>) => Definition<P, C>;
+  server: (definitions: readonly Definition<P, C>[], options: ServerOptions$1) => ServerFactory<C>;
+};
+declare function authz<P extends string>(policy: Policy<P> | PermissionCatalog<P>): ReturnType<typeof bindAuthz<P, Principal<P>, {
+  principal: Principal<P>;
+}>>;
+declare function authz<P extends string, C>(policy: Policy<P> | PermissionCatalog<P>, options: {
+  principal: (context: C) => Principal<P>;
+}): ReturnType<typeof bindAuthz<P, C, C>>;
+//#endregion
+export { AuditDeliveryFailure as a, AuditSink as c, PromptConfig as d, ResourceConfig as f, authz as h, ApprovalSink as i, Capability as l, ToolConfig as m, ApprovalRefusedError as n, AuditErrorSink as o, ServerOptions$1 as p, ApprovalRequest as r, AuditEvent as s, ApprovalDecision as t, Definition as u };

package/dist/verifier-D6VIAYuT.js

@@ -0,0 +1,152 @@
+import { OAuthError, OAuthErrorCode } from "@modelcontextprotocol/server";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+//#region src/identity.ts
+var AccessDeniedError = class AccessDeniedError extends Error {
+	email;
+	reason;
+	constructor(email, reason, message) {
+		super(message);
+		this.name = "AccessDeniedError";
+		this.email = email;
+		this.reason = reason;
+	}
+	static notPermitted(email, policyHint = "the access policy") {
+		return new AccessDeniedError(email, "not_permitted", `${email} matches no rule in ${policyHint}, so they hold no permissions. Ask an administrator to grant them a role.`);
+	}
+	static noCredential(email, credentialHint = "a backend credential") {
+		return new AccessDeniedError(email, "no_credential", `${email} is permitted but has no ${credentialHint}, and no shared account is configured.`);
+	}
+};
+//#endregion
+//#region src/decision.ts
+function policyDenied(error) {
+	return Response.json({
+		error: "forbidden",
+		reason: "policy_denied",
+		error_description: error.message
+	}, { status: 403 });
+}
+async function emitDecision(sink, principal, decision, reason, emitter) {
+	if (!principal) return;
+	await sink?.({
+		type: "mcp_authz.decision.v1",
+		issuer: principal.issuer,
+		sub: principal.sub,
+		email: principal.email,
+		domain: principal.domain,
+		...emitter ? { emitter } : {},
+		decision,
+		roles: principal.roles,
+		permissions: principal.permissions,
+		...reason ? { reason } : {},
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+function principalLabel(principal) {
+	return principal.email ?? `${principal.issuer}#${principal.sub}`;
+}
+//#endregion
+//#region src/verifier.ts
+const invalidToken = (message) => new OAuthError(OAuthErrorCode.InvalidToken, message);
+/**
+* A JWKS-backed verifier. Keys are fetched once and cached by `jose`, which
+* also handles rotation, so a key roll at the AS does not need a redeploy.
+*/
+function jwksVerifier(options) {
+	const jwks = createRemoteJWKSet(new URL(options.jwksUri));
+	const emailClaim = options.emailClaim ?? "email";
+	const emailVerifiedClaim = options.emailVerifiedClaim ?? "email_verified";
+	const expectedResource = new URL(options.resource.href).href.split("#")[0];
+	return {
+		async verifyAccessToken(token) {
+			let payload;
+			try {
+				payload = (await jwtVerify(token, jwks, {
+					issuer: options.issuer,
+					audience: expectedResource
+				})).payload;
+			} catch (error) {
+				throw invalidToken(`Token rejected: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			if (typeof payload.exp !== "number") throw invalidToken("Token has no `exp` claim.");
+			const claimed = payload[emailClaim];
+			const email = typeof claimed === "string" && claimed ? claimed : void 0;
+			if (!email && (options.requireEmail ?? true)) throw invalidToken(`Token carries no '${emailClaim}' claim, so there is no identity to map.`);
+			if (email && (options.requireEmailVerified ?? true) && payload[emailVerifiedClaim] !== true) throw invalidToken(`Token does not prove '${emailClaim}' with '${emailVerifiedClaim}: true'.`);
+			const sub = payload.sub;
+			if (typeof sub !== "string" || !sub) throw invalidToken("Token has no `sub` claim, so there is no stable subject to bind to.");
+			const domain = typeof payload.hd === "string" ? payload.hd : void 0;
+			if (options.allowedDomain && domain?.toLowerCase() !== options.allowedDomain.toLowerCase()) throw invalidToken(`Token is for ${domain ?? "an unknown domain"}, not ${options.allowedDomain}.`);
+			return {
+				token,
+				clientId: typeof payload.client_id === "string" ? payload.client_id : typeof payload.azp === "string" ? payload.azp : sub,
+				scopes: scopesOf(payload.scope),
+				expiresAt: payload.exp,
+				resource: options.resource,
+				extra: {
+					issuer: options.issuer,
+					sub,
+					email,
+					emailVerified: email !== void 0 && (options.requireEmailVerified === false || payload[emailVerifiedClaim] === true),
+					domain,
+					claims: payload
+				}
+			};
+		},
+		identityOf: identityFromAuth
+	};
+}
+/**
+* The verifier a resource server ends up with, however it was configured.
+*
+* Every entry point here faces the same three choices — bring your own
+* verifier, configure the built-in one, or say nothing and let discovery fill
+* it in — and has to refuse the same contradiction between the first two. Doing
+* that in one place is what stops two entry points disagreeing about which
+* issuer a token is checked against, or which audience it must carry.
+*/
+function verifierFor(options) {
+	if (options.tokenVerifier && options.verifier) throw new Error("Pass either `tokenVerifier` or built-in `verifier` options, not both.");
+	if (options.tokenVerifier) return {
+		tokenVerifier: options.tokenVerifier,
+		mapIdentity: options.identityFromAuth ?? identityFromAuth
+	};
+	const published = typeof options.oauthMetadata.jwks_uri === "string" ? options.oauthMetadata.jwks_uri : void 0;
+	const jwksUri = options.verifier?.jwksUri ?? published;
+	if (!jwksUri) throw new Error("No JWKS to verify tokens against. Set `verifier.jwksUri`, use a custom `tokenVerifier`, or use `discoverOAuth(issuer)`, whose metadata carries `jwks_uri`.");
+	const builtIn = jwksVerifier({
+		...options.verifier,
+		jwksUri,
+		issuer: options.verifier?.issuer ?? options.oauthMetadata.issuer,
+		resource: options.verifier?.resource ?? options.resourceServerUrl
+	});
+	return {
+		tokenVerifier: builtIn,
+		mapIdentity: options.identityFromAuth ?? builtIn.identityOf
+	};
+}
+/** Default identity mapper for custom verifiers using `AuthInfo.extra`. */
+function identityFromAuth(auth) {
+	const { issuer, sub, email, emailVerified, domain, claims } = auth.extra ?? {};
+	if (typeof issuer !== "string" || !issuer || typeof sub !== "string" || !sub) throw invalidToken("Verified token carried no issuer or subject.");
+	if (email !== void 0 && (typeof email !== "string" || !email)) throw invalidToken("Verified token carried an invalid email.");
+	return {
+		issuer,
+		sub,
+		email: typeof email === "string" ? email : void 0,
+		emailVerified: emailVerified === true,
+		domain: typeof domain === "string" ? domain : void 0,
+		claims: isRecord(claims) ? claims : {}
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** OAuth scope is a space-delimited string; some servers send an array anyway. */
+function scopesOf(scope) {
+	if (Array.isArray(scope)) return scope.filter((s) => typeof s === "string");
+	if (typeof scope === "string") return scope.split(" ").filter(Boolean);
+	return [];
+}
+//#endregion
+export { policyDenied as a, emitDecision as i, jwksVerifier as n, principalLabel as o, verifierFor as r, AccessDeniedError as s, identityFromAuth as t };

package/dist/verifier-DF6gUMQ6.d.ts

@@ -0,0 +1,84 @@
+import { _ as Identity } from "./policy-DuZbwrKf.js";
+import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
+//#region src/decision.d.ts
+/**
+ * The access decision and how it is reported, with nothing protocol-shaped
+ * attached.
+ *
+ * Its own module for the bundle rather than for tidiness: this rides in every
+ * enforcement path, while the rest of the ladder is MCP route classification
+ * and scope step-up. Left there, an OpenAPI deployment shipped the MCP wire
+ * format it never calls.
+ */
+type AuthorizationDecisionEvent = {
+  /** See `AuditEvent['type']`: same contract, its own shape and version. */
+  type: 'mcp_authz.decision.v1';
+  issuer: string;
+  sub: string;
+  email?: string;
+  /** See `AuditEvent['domain']`: the nearest thing to an organisation. */
+  domain?: string;
+  /** Which deployment emitted this, when you named it. */
+  emitter?: string;
+  decision: 'allow' | 'deny';
+  roles: readonly string[];
+  permissions: readonly string[];
+  reason?: string;
+  at: string;
+};
+type AuthorizationDecisionSink = (event: AuthorizationDecisionEvent) => unknown | Promise<unknown>;
+//#endregion
+//#region src/verifier.d.ts
+/**
+ * Token verification, the one thing the SDK deliberately leaves to you.
+ *
+ * `authInfo` is strictly pass-through in the SDK: it is never derived from
+ * request headers, and no token is checked unless we check it. So this file is
+ * the security boundary of the whole server.
+ *
+ * The authorization server is something that already exists (WorkOS, Stytch,
+ * Auth0) doing dynamic client registration / CIMD and Google Workspace login.
+ * Google cannot play that role itself: it has no DCR/CIMD, and it will not
+ * mint a token whose audience is this server.
+ */
+type VerifierOptions = {
+  /** The AS issuer, e.g. `https://auth.acme.com`. Must match the token's `iss`. */
+  issuer: string;
+  /** Where the AS publishes its signing keys. */
+  jwksUri: string;
+  /**
+   * This server's public URL. A token minted for a different resource is
+   * refused even when its signature is valid (RFC 8707).
+   */
+  resource: URL;
+  /**
+   * Restrict to one Google Workspace domain, checked against the `hd` claim
+   * the AS passes through. Omit to accept any domain the AS admits.
+   */
+  allowedDomain?: string;
+  /** Claim carrying the verified email. Auth0 and WorkOS both use `email`. */
+  emailClaim?: string;
+  /** Claim proving the email was verified. Defaults to `email_verified`. */
+  emailVerifiedClaim?: string;
+  /** Require an explicit `true` verified-email claim. Defaults to true. */
+  requireEmailVerified?: boolean;
+  /**
+   * Require an email in every token. Defaults to true. Set false to accept an
+   * agent that signs in as itself, such as an OAuth client-credentials token:
+   * its identity is its `sub`, which a policy rule names. Email and domain
+   * rules never match it, and neither does `allowedDomain`; a rule with no
+   * `match` does. A token that does carry an email is checked as before.
+   */
+  requireEmail?: boolean;
+};
+/**
+ * A JWKS-backed verifier. Keys are fetched once and cached by `jose`, which
+ * also handles rotation, so a key roll at the AS does not need a redeploy.
+ */
+declare function jwksVerifier(options: VerifierOptions): OAuthTokenVerifier & {
+  identityOf: (auth: AuthInfo) => Identity;
+};
+/** Default identity mapper for custom verifiers using `AuthInfo.extra`. */
+declare function identityFromAuth(auth: AuthInfo): Identity;
+//#endregion
+export { AuthorizationDecisionSink as a, AuthorizationDecisionEvent as i, identityFromAuth as n, jwksVerifier as r, VerifierOptions as t };