mcp-authz 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+import { a as Policy, c as Rule, d as definePolicy, f as reconcile, h as Identity, i as PermissionOf, l as createPrincipal, m as DenialReason, n as Match, o as PolicySpec, p as AccessDeniedError, r as PermissionCatalog, s as Principal, u as definePermissions } from "./policy-CnQj53Hq.js";
+import { AuthInfo, CallToolResult, GetPromptResult, Icon, Implementation, InboundClassificationOutcome, McpServer, OAuthMetadata, OAuthTokenVerifier, ReadResourceResult, ResourceMetadata, ResourceTemplate, ServerOptions as ServerOptions$1, StandardSchemaV1, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+//#region src/discovery.d.ts
+type DiscoverOptions = {
+  /** Swap in for tests, or to add a timeout or proxy. Defaults to global fetch. */
+  fetch?: typeof globalThis.fetch;
+};
+declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
+//#endregion
+//#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. */
+type AuditEvent = {
+  issuer: string;
+  sub: string;
+  email?: string;
+  kind: Capability;
+  /** 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';
+  phase: 'attempt' | 'success' | 'failure';
+  at: string;
+  durationMs?: number;
+  error?: string;
+};
+type AuditSink = (event: AuditEvent) => unknown | Promise<unknown>;
+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;
+};
+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;
+  register: (server: McpServer, principal: Principal<P>, context: C, onAudit?: AuditSink) => void;
+};
+type ServerOptions = Implementation & {
+  /** Called on every permitted invocation. The one record tying a person to an action. */
+  onAudit?: AuditSink;
+  /** Pass-through SDK options; declared gated capabilities are merged in. */
+  mcp?: ServerOptions$1;
+};
+/**
+ * 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;
+};
+/**
+ * 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) => 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
+//#region src/gate.d.ts
+/**
+ * Gate a server somebody else builds.
+ *
+ * `authz(policy)` is for tools you write. This is for the ones you already
+ * have: an MCP server from another package, or one you are not ready to change,
+ * whose tools were never declared with a permission.
+ *
+ * It cannot read a built server's tool list — the SDK keeps that private, and
+ * no library can filter what it never saw. So this wraps the server *before*
+ * registration and gates each call as it happens, which needs one hook from
+ * whoever builds it:
+ *
+ * ```ts
+ * // in their builder
+ * const server = options.wrap ? options.wrap(new McpServer(info, opts)) : new McpServer(info, opts);
+ *
+ * // in your connector
+ * buildServer(config, { wrap: (server) => gate(server, principal, PERMISSIONS) })
+ * ```
+ *
+ * Unpermitted registrations are registered and immediately disabled rather than
+ * skipped, so the caller still gets the handle its own code expects, and the
+ * SDK does the list-filtering and the refusal.
+ */
+type GateOptions = {
+  /** Same event as `authz`, for tools this package did not define. */
+  onAudit?: AuditSink;
+  /**
+   * Name the thing a call touched, keyed by the same label as `permissions`.
+   * Their tool, your domain knowledge.
+   */
+  audit?: Readonly<Record<string, (args: never) => string | undefined>>;
+};
+/** Bare name for a tool, `prompt:`/`resource:` prefixed for the rest. */
+type PermissionMap<P extends string> = Readonly<Record<string, P>> | ReadonlyMap<string, P>;
+declare function gate<P extends string>(server: McpServer, principal: Principal<P>, permissions: PermissionMap<P>, options?: GateOptions): McpServer;
+//#endregion
+//#region src/routing.d.ts
+type TrustedMcpRoute = {
+  kind: 'modern';
+  body: unknown;
+  outcome: Extract<InboundClassificationOutcome, {
+    kind: 'modern';
+  }>;
+  method: string;
+  name?: string;
+};
+//#endregion
+//#region src/scopes.d.ts
+/**
+ * Helpers for deriving required OAuth scopes from Streamable HTTP headers
+ * (SEP-2243). Use with `createMcpFetch({ scopesForRequest })`.
+ */
+type ScopeRequirement = string | readonly string[];
+type ToolScopeMap = Readonly<Record<string, ScopeRequirement>>;
+type CapabilityScopeMap = ToolScopeMap;
+/**
+ * Tools use their bare name (or `tool:name`); prompts use `prompt:name`; and
+ * resources use `resource:<uri>`. Everything else needs only the baseline.
+ */
+declare function scopesFromMcpHeaders(request: Request, toolScopes: ToolScopeMap, baseline?: string): string[];
+/** Select scopes from an already validated MCP method/name pair. */
+declare function scopesForCapability(method: string | undefined, name: string | undefined, capabilityScopes: CapabilityScopeMap, baseline?: string): string[];
+/** Decode SEP-2243's optional Base64 sentinel without accepting non-canonical input. */
+declare function decodeMcpNameHeader(value: string): string | undefined;
+//#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;
+};
+/**
+ * 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
+//#region src/handler.d.ts
+type AuthorizationDecisionEvent = {
+  issuer: string;
+  sub: string;
+  email?: string;
+  decision: 'allow' | 'deny';
+  roles: readonly string[];
+  permissions: readonly string[];
+  reason?: string;
+  at: string;
+};
+type AuthorizationDecisionSink = (event: AuthorizationDecisionEvent) => unknown | Promise<unknown>;
+/**
+ * An MCP Streamable HTTP resource server (2026-07-28) with
+ * each person's own Google login in front of a per-request server factory.
+ *
+ * Three parties, and it matters which does what:
+ *
+ *   Claude          runs the OAuth flow and presents a bearer token
+ *   your AS         registers Claude (CIMD preferred; DCR deprecated), logs
+ *                   the human in with Google, and mints a token bound to
+ *                   THIS server's URL
+ *   this file       verifies that token, maps the identity to context, and
+ *                   builds a server for that request
+ *
+ * We are a resource server and nothing more.
+ */
+type McpFetchOptions<TContext, P extends string = string> = {
+  /** This server's public URL, e.g. `https://mcp.acme.com/mcp`. */
+  resourceServerUrl: URL;
+  /** RFC 8414 metadata for the authorization server in front of us. */
+  oauthMetadata: OAuthMetadata;
+  /**
+   * Token verification. The SDK verifies no tokens of its own, so this is the
+   * security boundary, but every field has a sound default.
+   *
+   * `issuer` and `resource` come from `oauthMetadata.issuer` and
+   * `resourceServerUrl`, which is what they have to be: a verifier trusting a
+   * different issuer, or checking the audience against a URL this server does
+   * not answer on, refuses every valid token and says only "invalid token".
+   * `jwksUri` comes from `oauthMetadata.jwks_uri` when discovery supplied it,
+   * so this whole block is optional.
+   */
+  verifier?: Partial<VerifierOptions>;
+  /**
+   * Bring any SDK-compatible verifier, including RFC 7662 introspection for
+   * opaque tokens. Mutually exclusive with the built-in `verifier` options.
+   */
+  tokenVerifier?: OAuthTokenVerifier;
+  /** Map a custom verifier's AuthInfo into the identity consumed by policy. */
+  identityFromAuth?: (auth: AuthInfo) => Identity;
+  /**
+   * Baseline scopes every request must carry. Keep it to one small scope
+   * (`mcp` by default); use `scopesForRequest` for per-tool step-up.
+   */
+  requiredScopes?: string[];
+  /** All scopes advertised in protected-resource metadata. */
+  supportedScopes?: string[];
+  /** Declarative per-tool step-up. Mutually exclusive with `scopesForRequest`. */
+  toolScopes?: ToolScopeMap;
+  /** Tools, prompts and resource URIs mapped to scope requirements. */
+  capabilityScopes?: CapabilityScopeMap;
+  /**
+   * Map a request to the scopes it needs. The second argument is the trusted,
+   * body-validated and Base64-decoded MCP route; use it instead of reading raw
+   * `Mcp-Method` / `Mcp-Name` values yourself. Returning more than the token
+   * holds produces HTTP 403 with actionable `insufficient_scope` step-up.
+   *
+   * Omit to demand only `requiredScopes` on every call.
+   */
+  scopesForRequest?: (request: Request, route: TrustedMcpRoute) => string[];
+  /**
+   * Who may connect and what they may do. Supply this and the per-request
+   * context is the `Principal`; a caller matching no rule is refused.
+   *
+   * Paired with a `toolServer`, the tools' permissions are reconciled against
+   * the policy at startup, so a tool no role can reach fails the boot rather
+   * than sitting there looking live.
+   */
+  policy?: Policy<P>;
+  /**
+   * Async alternative to `policy`, for roles and permissions stored in an IdP,
+   * database or policy service. Return a principal with `createPrincipal`.
+   */
+  authorize?: (identity: Identity) => Promise<Principal<P>> | Principal<P>;
+  /** Awaited access-decision sink. A rejection fails closed. */
+  onDecision?: AuthorizationDecisionSink;
+  /**
+   * After auth: map the verified identity to backend context, or throw
+   * `AccessDeniedError` for an actionable 403. Omit to use `policy` alone.
+   *
+   * Supply both when the context needs more than the principal — a tenant, a
+   * connection, a downstream credential. The policy still runs first and still
+   * refuses anyone it grants nothing, so this enriches the context rather than
+   * taking over the decision, and the boot-time reconciliation stays honest.
+   */
+  resolve?: (identity: Identity, principal: Principal<P> | undefined) => Promise<TContext> | TContext;
+  /** Per-request MCP server factory. `toolServer` builds one from a tool set. */
+  createServer: ((context: TContext) => McpServer) & {
+    /** Tool name to required permission, when the factory knows its own tools. */
+    permissions?: ReadonlyMap<string, string>;
+    /** Protocol route to permission, used to distinguish policy denial from scope step-up. */
+    routePermissions?: ReadonlyMap<string, string>;
+    /** Resolve exact and templated protocol routes to their declared permission. */
+    permissionForRoute?: (kind: 'tool' | 'prompt' | 'resource', name: string) => string | undefined;
+  };
+  /**
+   * The same map, when your own factory wraps a `toolServer` and hides it —
+   * which a richer `TContext` than the principal forces you to do. Pass
+   * `toolServer(...).permissions` here and the boot-time check still runs.
+   */
+  permissions?: ReadonlyMap<string, string>;
+  /** Key under `authInfo.extra` for the resolved context. */
+  contextExtraKey?: string;
+  /** Health check path. Defaults to `/health`. */
+  healthPath?: string;
+  /** Reject 2025-era requests by default; opt in only when legacy clients are required. */
+  legacy?: 'reject' | 'stateless';
+  /**
+   * Cap on a body read before authentication, which only the declarative scope
+   * path does. Defaults to 1 MiB; over it is a 413.
+   */
+  maxRequestBytes?: number;
+};
+/**
+ * With a `policy`, the principal reaching `resolve` is never undefined: the
+ * policy ran first and already refused anyone it grants nothing. Saying so here
+ * saves every caller the same non-null assertion.
+ */
+declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+  policy: Policy<P>;
+  authorize?: never;
+  resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
+}): (request: Request) => Promise<Response>;
+declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+  policy?: never;
+  authorize: (identity: Identity) => Promise<Principal<P>> | Principal<P>;
+  resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
+}): (request: Request) => Promise<Response>;
+declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+  policy?: never;
+  authorize?: never;
+  resolve: (identity: Identity, principal: undefined) => Promise<TContext> | TContext;
+}): (request: Request) => Promise<Response>;
+//#endregion
+export { AccessDeniedError, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type GateOptions, type Identity, type Match, type McpFetchOptions, type PermissionCatalog, type PermissionMap, type PermissionOf, type Policy, type PolicySpec, type Principal, type PromptConfig, type ResourceConfig, type Rule, type ScopeRequirement, type ServerOptions, type ToolConfig, type ToolScopeMap, type TrustedMcpRoute, type VerifierOptions, authz, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };