permdock 0.0.0 → 0.2.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,159 @@
+import { C as Policy, Nr as Principal, Pr as Subject } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as ApprovalHint } from "../errors-DAqevpNk.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
+import { t as ClientNames } from "../clients-C7zLFuWT.js";
+import { u as JwtSubjectOptions } from "../types-9AWO9EGt.js";
+import { o as OtelWrap } from "../types-vNSDF7Dq.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`. */
+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. */
+  readonly resourceMetadataUrl?: string;
+  readonly extra?: Readonly<Record<string, unknown>>;
+};
+/** Base principal `subjectFromMcp` returns. */
+type McpPrincipal = Principal & {
+  readonly issuer?: string;
+  readonly claims?: Readonly<Record<string, unknown>>;
+};
+type InputOf<TInput> = TInput extends StandardSchemaWithJSON ? StandardSchemaWithJSON.InferOutput<TInput> : undefined;
+type Guard<TArgs extends readonly unknown[]> = {
+  readonly permission: Permission;
+  /** Loads the row to decide on; `null` or a throw denies. */
+  readonly data?: (...args: TArgs) => unknown;
+};
+type McpToolConfig<TInput extends StandardSchemaWithJSON | undefined = undefined, TOutput extends StandardSchemaWithJSON | undefined = undefined> = Guard<[args: InputOf<TInput>]> & {
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: TInput;
+  readonly outputSchema?: TOutput;
+  readonly annotations?: ToolAnnotations;
+  readonly icons?: Icon[];
+  readonly scopeChallenge?: ScopeChallengeHandler;
+  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.
+   */
+  readonly longRunning?: boolean;
+};
+type McpResourceConfig<TArgs extends readonly unknown[]> = Guard<TArgs> & ResourceMetadata & {
+  readonly cacheHint?: CacheHint;
+  readonly scopeChallenge?: ScopeChallengeHandler;
+};
+type McpPromptConfig<TArgs extends StandardSchemaWithJSON | undefined = undefined> = Guard<[args: InputOf<TArgs>]> & {
+  readonly title?: string;
+  readonly description?: string;
+  readonly argsSchema?: TArgs;
+  readonly icons?: Icon[];
+  readonly scopeChallenge?: ScopeChallengeHandler;
+  readonly _meta?: Record<string, unknown>;
+};
+/** `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;
+};
+/** 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. */
+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;
+};
+/**
+ * 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. */
+  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). */
+  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
+   * `subjectFromSupabase`, `subjectFromJwt` and `permdock/a2a` give an OAuth
+   * client, so one policy delegation covers the token on every surface.
+   */
+  readonly actorKind?: string;
+  /** 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`.
+   */
+  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.
+   */
+  readonly approval?: ApprovalHint;
+  /** 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.
+   */
+  readonly requestState?: {
+    readonly mint: (token: string, context?: never) => Promise<string>;
+  };
+  readonly store?: ApprovalStore;
+  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
+  readonly otel?: OtelWrap;
+};
+type McpPermDock = {
+  /** Call before registering anything: later `register*` calls must carry a `permission`. */
+  readonly protectServer: {
+    (server: McpServer): GuardedMcpServer;
+    (server: McpServer, options: McpProcedureEnforcement): ProcedureMcpServer;
+  };
+};
+//#endregion
+//#region src/mcp/create.d.ts
+/** `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an approval token. */
+export declare const APPROVAL_META_KEY = "dev.permdock/approval";
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: McpPermDockOptions<TUser>): McpPermDock;
+//#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`. */
+  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.
+ */
+export declare function subjectFromMcp(authInfo: McpAuthInfo | undefined, options?: McpSubjectOptions): Subject<McpPrincipal>;
+//#endregion
+export type { GuardedMcpServer, McpAuthInfo, McpPermDock, McpPermDockOptions, McpPrincipal, McpProcedureEnforcement, McpProcedureToolConfig, McpPromptConfig, McpResourceConfig, McpSubjectOptions, McpToolConfig, ProcedureMcpServer };