permdock 0.6.0 → 0.8.0

package/dist/mcp/index.d.ts

@@ -1,24 +1,30 @@
-import { $n as Delegation, T as Policy, ar as Subject, rr as Principal } from "../policy-types-n0uRTsW8.js";
-import { w as Permission } from "../vocabulary-CN8H_9UF.js";
-import { m as ApprovalStore } from "../types-BdtSDbBO.js";
-import { t as ApprovalHint } from "../errors-DH5QEGXh.js";
-import { t as InstanceOptions } from "../instance-options-BsVpyGIk.js";
+import { T as Policy, Y as JwtClaims, dt as TokenVerifier, lr as Subject, rr as Delegation, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { u as Permission } from "../permission-types-CAY-GU7e.js";
+import { m as ApprovalStore } from "../types-B_tiYvk8.js";
+import { t as ApprovalHint } from "../errors-zi_4T-rx.js";
+import { t as InstanceOptions } from "../instance-options-B0KXqTrJ.js";
 import { t as RequestContext } from "../request-context-C2_1lchh.js";
-import { n as PermDockWrap } from "../wrap-C5jC6sKI.js";
-import { o as OtelWrap } from "../types-lUlG3TVd.js";
-import { n as DeniedTextEvent, t as DeniedText } from "../denied-text-CiFQNuMV.js";
-import { t as ClientNames } from "../clients-C7zLFuWT.js";
-import { U as JwtSubjectOptions } from "../types-C791HFu9.js";
+import { n as PermDockWrap } from "../wrap-DlJE3gS_.js";
+import { o as OtelWrap } from "../types-DHKPcqzr.js";
+import { n as DeniedTextEvent, t as DeniedText } from "../denied-text-CHNlVInN.js";
+import { t as ClientNames } from "../clients-C_NOET3z.js";
+import { U as JwtSubjectOptions } from "../types-DjuMBNF9.js";
 import { CacheHint, Icon, McpServer, PromptCallback, ReadResourceCallback, ReadResourceTemplateCallback, RegisteredPrompt, RegisteredResource, RegisteredResourceTemplate, RegisteredTool, ResourceMetadata, ResourceTemplate, ScopeChallengeHandler, StandardSchemaWithJSON, ToolAnnotations, ToolCallback, Variables } from "@modelcontextprotocol/server";
 //#region src/mcp/types.d.ts
-/** The verified `AuthInfo` the MCP SDK's bearer auth puts on `ctx.http.authInfo`. */
+/**
+ * The verified `AuthInfo` the MCP SDK's bearer auth puts on
+ * `ctx.http.authInfo`.
+ */
 type McpAuthInfo = {
   readonly token?: string;
   readonly clientId?: string;
   readonly scopes?: readonly string[];
   readonly expiresAt?: number;
   readonly resource?: URL;
-  /** Stamped by the SDK's bearer-auth helpers from their `resourceMetadataUrl` option. */
+  /**
+   * Stamped by the SDK's bearer-auth helpers from their `resourceMetadataUrl`
+   * option.
+   */
   readonly resourceMetadataUrl?: string;
   readonly extra?: Readonly<Record<string, unknown>>;
 };
@@ -44,9 +50,9 @@ type McpToolConfig<TInput extends StandardSchemaWithJSON | undefined = undefined
   readonly oauthScopes?: readonly string[];
   readonly _meta?: Record<string, unknown>;
   /**
-   * Decide again when the handler resolves, without consuming quota, and
-   * return the refusal instead of the result unless the call is still
-   * allowed. The re-check withholds the result; it cannot undo the work.
+   * Decide again when the handler resolves, without consuming quota, and return
+   * the refusal instead of the result unless the call is still allowed. The
+   * re-check withholds the result; it cannot undo the work.
    */
   readonly longRunning?: boolean;
 };
@@ -54,6 +60,14 @@ type McpResourceConfig<TArgs extends readonly unknown[]> = Guard<TArgs> & Resour
   readonly cacheHint?: CacheHint;
   readonly scopeChallenge?: ScopeChallengeHandler;
 };
+/**
+ * An MCP Apps view (`ui://`). Without `permission` it takes the permission of
+ * the tool whose `_meta.ui.resourceUri` names it, and denies while no tool
+ * does.
+ */
+type McpUiResourceConfig = Omit<McpResourceConfig<[uri: URL]>, "permission"> & {
+  readonly permission?: Permission;
+};
 type McpPromptConfig<TArgs extends StandardSchemaWithJSON | undefined = undefined> = Guard<[args: InputOf<TArgs>]> & {
   readonly title?: string;
   readonly description?: string;
@@ -64,44 +78,57 @@ type McpPromptConfig<TArgs extends StandardSchemaWithJSON | undefined = undefine
 };
 /** `McpServer` whose `register*` methods take a `permission` and decide first. */
 type GuardedMcpServer = Omit<McpServer, "registerTool" | "registerResource" | "registerPrompt"> & {
-  registerTool<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpToolConfig<TInput, TOutput>, handler: ToolCallback<TInput>): RegisteredTool;
-  registerResource(name: string, uri: string, config: McpResourceConfig<[uri: URL]>, read: ReadResourceCallback): RegisteredResource;
-  registerResource(name: string, template: ResourceTemplate, config: McpResourceConfig<[uri: URL, variables: Variables]>, read: ReadResourceTemplateCallback): RegisteredResourceTemplate;
-  registerPrompt<TArgs extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpPromptConfig<TArgs>, handler: PromptCallback<TArgs>): RegisteredPrompt;
+  registerTool: <TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpToolConfig<TInput, TOutput>, handler: ToolCallback<TInput>) => RegisteredTool;
+  registerResource: {
+    (name: string, uri: `ui://${string}`, config: McpUiResourceConfig, read: ReadResourceCallback): RegisteredResource;
+    (name: string, uri: string, config: McpResourceConfig<[uri: URL]>, read: ReadResourceCallback): RegisteredResource;
+    (name: string, template: ResourceTemplate, config: McpResourceConfig<[uri: URL, variables: Variables]>, read: ReadResourceTemplateCallback): RegisteredResourceTemplate;
+  };
+  registerPrompt: <TArgs extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpPromptConfig<TArgs>, handler: PromptCallback<TArgs>) => RegisteredPrompt;
 };
 /** A tool config when the tool's own procedure decides: no loader, no re-check. */
 type McpProcedureToolConfig<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined> = Omit<McpToolConfig<TInput, TOutput>, "permission" | "data" | "longRunning"> & {
   /** Overrides `permissionFor(name)`. */
   readonly permission?: Permission;
 };
-/** `GuardedMcpServer` whose tools are listed and annotated by permission but decided by the procedure they call. */
+/**
+ * `GuardedMcpServer` whose tools are listed and annotated by permission but
+ * decided by the procedure they call.
+ */
 type ProcedureMcpServer = Omit<GuardedMcpServer, "registerTool"> & {
-  registerTool<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpProcedureToolConfig<TInput, TOutput>, handler: ToolCallback<TInput>): RegisteredTool;
+  registerTool: <TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: McpProcedureToolConfig<TInput, TOutput>, handler: ToolCallback<TInput>) => RegisteredTool;
 };
 /**
- * Tools whose handler calls a procedure that already runs `protect`, such as
- * an oRPC procedure through `call()`. `tools/list` and annotations use the
+ * Tools whose handler calls a procedure that already runs `protect`, such as an
+ * oRPC procedure through `call()`. `tools/list` and annotations use the
  * permission; the call itself is not guarded, so each call decides once.
  */
 type McpProcedureEnforcement = {
   readonly enforce: "procedure";
-  /** The permission of the tool `name`; `permissionOf(procedure)` from `permdock/orpc` reads it. `undefined` throws at registration. */
+  /**
+   * The permission of the tool `name`; `permissionOf(procedure)` from
+   * `permdock/orpc` reads it. `undefined` throws at registration.
+   */
   readonly permissionFor: (name: string) => Permission | undefined;
   readonly oauthScopesFor?: (name: string) => readonly string[] | undefined;
 };
 type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
-  /** Receives the verified auth info, or `{}` on a transport without one (stdio). */
+  /**
+   * Receives the verified auth info, or `{}` on a transport without one
+   * (stdio).
+   */
   readonly subject: (authInfo: McpAuthInfo) => TUser | Promise<TUser>;
   /**
-   * The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'`
-   * when absent. `'oauth-client'` decides the token under the kind
+   * The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'` when
+   * absent. `'oauth-client'` decides the token under the kind
    * `subjectFromSupabase`, `subjectFromJwt` and `permdock/a2a` give an OAuth
    * client, so one policy delegation covers the token on every surface.
    */
   readonly actorKind?: string;
   /**
    * Replaces the actor built from `authInfo.clientId`, `actorKind` and
-   * `clients`. Read it from the verified `authInfo`, never from tool arguments.
+   * `clients`. Read it from the verified `authInfo`, never from tool
+   * arguments.
    */
   readonly actor?: (authInfo: McpAuthInfo) => unknown;
   /**
@@ -109,28 +136,36 @@ type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
    * `authInfo.extra.authorization_details`.
    */
   readonly delegation?: (authInfo: McpAuthInfo) => Delegation | undefined | Promise<Delegation | undefined>;
-  /** Names for OAuth client ids (`ClientNames`): the actor gets `client` set to the name of `authInfo.clientId`, which a policy delegation matches with `to: { kind, client }`. */
+  /**
+   * Names for OAuth client ids (`ClientNames`): the actor gets `client` set to
+   * the name of `authInfo.clientId`, which a policy delegation matches with
+   * `to: { kind, client }`.
+   */
   readonly clients?: ClientNames;
   readonly tenant?: string | ((authInfo: McpAuthInfo) => string | undefined | Promise<string | undefined>);
   /** Deny every call and list nothing when the transport carries no auth info. */
   readonly requireAuthInfo?: boolean;
   /**
    * This server's RFC 8707 resource identifier. A token whose
-   * `authInfo.resource` is absent or different is refused with `invalid_token`.
+   * `authInfo.resource` is absent or different is refused with
+   * `invalid_token`.
    */
   readonly resource?: string | URL;
   /**
-   * Where a human approves. With `at` set, `approval-required` answers a
-   * client that supports URL elicitation with an `input_required` result.
+   * Where a human approves. With `at` set, `approval-required` answers a client
+   * that supports URL elicitation with an `input_required` result.
    */
   readonly approval?: ApprovalHint;
-  /** Where the user re-authenticates; `acr_values` and `max_age` are appended to `at`. */
+  /**
+   * Where the user re-authenticates; `acr_values` and `max_age` are appended to
+   * `at`.
+   */
   readonly stepUp?: {
     readonly at: string;
   };
   /**
-   * Seals the approval token into `requestState`. Pass the codec from the
-   * SDK's `createRequestStateCodec` when the server verifies request state.
+   * Seals the approval token into `requestState`. Pass the codec from the SDK's
+   * `createRequestStateCodec` when the server verifies request state.
    */
   readonly requestState?: {
     readonly mint: (token: string, context?: never) => Promise<string>;
@@ -138,11 +173,14 @@ type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
   readonly store?: ApprovalStore;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
-  /** Wraps each instance after `otel`; build it with `wrapPermDock` to cover derived instances. */
+  /**
+   * Wraps each instance after `otel`; build it with `wrapPermDock` to cover
+   * derived instances.
+   */
   readonly wrap?: PermDockWrap;
   /**
-   * Request values merged into `subject.context`, under `policy.context`.
-   * Read them from the verified `authInfo`, never from tool arguments.
+   * Request values merged into `subject.context`, under `policy.context`. Read
+   * them from the verified `authInfo`, never from tool arguments.
    */
   readonly context?: (authInfo: McpAuthInfo) => RequestContext | undefined | Promise<RequestContext | undefined>;
   /**
@@ -152,7 +190,10 @@ type McpPermDockOptions<TUser = unknown> = InstanceOptions & {
   readonly deniedText?: DeniedText;
 };
 type McpPermDock = {
-  /** Call before registering anything: later `register*` calls must carry a `permission`. */
+  /**
+   * Call before registering anything: later `register*` calls must carry a
+   * `permission`.
+   */
   readonly protectServer: {
     (server: McpServer): GuardedMcpServer;
     (server: McpServer, options: McpProcedureEnforcement): ProcedureMcpServer;
@@ -163,24 +204,90 @@ type McpPermDock = {
 export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, given: McpPermDockOptions<TUser>): McpPermDock;
 //#endregion
 //#region src/mcp/mcp-auth.d.ts
-/** `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an approval token. */
+/**
+ * `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an
+ * approval token.
+ */
 export declare const APPROVAL_META_KEY = "dev.permdock/approval";
 //#endregion
+//#region src/mcp/resource-guard.d.ts
+type McpResourceGuardOptions = {
+  /**
+   * The MCP server's resource identifier (RFC 8707); a token's `aud` must
+   * contain it.
+   */
+  readonly resource: string | URL;
+  /**
+   * Scopes every request needs; a token without one of them gets `403
+   * insufficient_scope`.
+   */
+  readonly scopes?: readonly string[];
+  readonly verifier: TokenVerifier;
+  /**
+   * The authorization server's issuer, when the verifier does not check `iss`
+   * itself.
+   */
+  readonly issuer?: string;
+  /** `true` for a revoked token; a throw also refuses it. */
+  readonly revoked?: (claims: JwtClaims) => boolean | Promise<boolean>;
+  /**
+   * The RFC 9728 metadata URL in challenges; default
+   * `<origin>/.well-known/oauth-protected-resource<path>`.
+   */
+  readonly resourceMetadataUrl?: string;
+};
+type McpResourceGuardResult = {
+  readonly ok: true;
+  readonly authInfo: McpAuthInfo;
+} | {
+  readonly ok: false;
+  readonly response: Response;
+};
+type ProtectedResourceMetadataOptions = {
+  readonly resource: string | URL;
+  /** `authorization_servers`: the issuers whose tokens the resource accepts. */
+  readonly authorizationServers: readonly string[];
+  /**
+   * `scopes_supported`; list every permission's `scope` so clients can ask for
+   * them up front.
+   */
+  readonly scopesSupported?: readonly string[];
+  readonly resourceName?: string;
+  readonly resourceDocumentation?: string;
+};
+/**
+ * The resource-server check in front of an MCP endpoint (MCP authorization, RFC
+ * 6750, RFC 9728): reads the bearer token from `Authorization`, verifies it for
+ * `resource`, refuses a revoked one and checks `scopes`. It answers the
+ * `McpAuthInfo` the SDK's handlers read, or the `401` or `403` response with a
+ * `WWW-Authenticate` challenge naming the metadata URL. A token in the query
+ * string is never read. Never throws.
+ */
+export declare function mcpResourceGuard(options: McpResourceGuardOptions): (request: Request) => Promise<McpResourceGuardResult>;
+/**
+ * The RFC 9728 Protected Resource Metadata document as a Fetch handler, for
+ * `/.well-known/oauth-protected-resource<path>`. `bearer_methods_supported` is
+ * `header`, the only method `mcpResourceGuard` reads. Any origin may read it.
+ */
+export declare function protectedResourceMetadata(options: ProtectedResourceMetadataOptions): (request: Request) => Response;
+//#endregion
 //#region src/mcp/subject.d.ts
 type McpSubjectOptions = Pick<JwtSubjectOptions, "claims" | "groupRoles" | "schema" | "delegation"> & {
-  /** The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'` when absent. Match `createPermDock`'s `actorKind`. */
+  /**
+   * The `kind` of the actor built from `authInfo.clientId`; `'mcp-client'` when
+   * absent. Match `createPermDock`'s `actorKind`.
+   */
   readonly actorKind?: string;
   /** Names for OAuth client ids; match `createPermDock`'s `clients`. */
   readonly clients?: ClientNames;
 };
 /**
  * Maps the `AuthInfo` the MCP SDK's bearer verification produced to a
- * `Subject`: the principal from the verified claims in `extra`, the client
- * as an actor of kind `actorKind` (`mcp-client` by default), the granted
- * scopes as the delegation. Never verifies and never throws; anything
- * unusable, including an `actorKind` that is not a non-empty string, is
- * the anonymous subject.
+ * `Subject`: the principal from the verified claims in `extra`, the client as
+ * an actor of kind `actorKind` (`mcp-client` by default), the granted scopes as
+ * the delegation. Never verifies and never throws; anything unusable, including
+ * an `actorKind` that is not a non-empty string, is the anonymous subject.
  */
 export declare function subjectFromMcp(authInfo: McpAuthInfo | undefined, options?: McpSubjectOptions): Subject<McpPrincipal>;
 //#endregion
-export type { DeniedText, DeniedTextEvent, GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig, ProcedureMcpServer };
+export type { DeniedText, DeniedTextEvent, GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpResourceGuardOptions, McpResourceGuardResult, McpSubjectOptions, McpToolConfig, McpUiResourceConfig, ProcedureMcpServer, ProtectedResourceMetadataOptions };