@cauthyhq/node 0.0.0 → 1.1.0

package/dist/mcp.d.mts

@@ -0,0 +1,151 @@
+import { JWTVerifyGetKey } from 'jose';
+
+/** The person an agent acts for, and what they allowed it. */
+interface AgentIdentity {
+    /** The person. */
+    userId: string;
+    tenantId: string;
+    email?: string;
+    /** The person's roles in the workspace. */
+    roles: string[];
+    /** What the person allowed the agent to do here. */
+    scopes: string[];
+    /** The agent (its client_id at Cauthy). */
+    clientId: string;
+    /** UTC, ISO 8601. */
+    expiresAt: string;
+    /** The token as it arrived. */
+    token: string;
+    /**
+     * Set when the token came by token exchange: the server that called this
+     * one for the person (the `act` claim's subject).
+     */
+    actor?: string;
+}
+interface McpAuthOptions {
+    /** This server's address, as registered in Cauthy. Default: `CAUTHY_MCP_RESOURCE`. */
+    resource?: string;
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** Scopes every call needs. Default: none. */
+    scopes?: string[];
+    /** The scopes this server understands, to tell agents (`scopes_supported`). Default: `scopes`. */
+    scopesSupported?: string[];
+    /** A name for the server, shown by some agents. */
+    resourceName?: string;
+    /** Cauthy's keys. Default: fetched from the issuer and cached. */
+    jwks?: JWTVerifyGetKey;
+    /** The moment to verify at. Default: now. */
+    now?: () => Date;
+    /**
+     * Ask Cauthy, besides checking the token here, whether the person still
+     * allows the agent (RFC 7662). Then an agent is cut off the moment it is
+     * disconnected, not when its token runs out, at the price of a call to
+     * Cauthy per token every `cacheSeconds` (default 30). Default: off.
+     */
+    introspect?: boolean | {
+        cacheSeconds?: number;
+    };
+    /** The fetch to call Cauthy with. Default: the global one. */
+    fetch?: typeof fetch;
+    /** How long a call to Cauthy (introspection, token exchange) may take, in milliseconds. Default: 5000. */
+    timeoutMs?: number;
+    /**
+     * This server's client_id and secret at Cauthy, for token exchange (AI
+     * agents → the server → Server credentials). Defaults:
+     * `CAUTHY_MCP_CLIENT_ID`, `CAUTHY_MCP_CLIENT_SECRET`.
+     */
+    clientId?: string;
+    clientSecret?: string;
+}
+/** What a token exchange answers. */
+interface ExchangedToken {
+    /** The token for the other server, as the person. Send it as `Authorization: Bearer`. */
+    accessToken: string;
+    /** What it allows there. */
+    scopes: string[];
+    /** UTC, ISO 8601. Never later than the agent's own token. */
+    expiresAt: string;
+}
+/** A token exchange Cauthy refused, with the OAuth error it answered. */
+declare class CauthyExchangeError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly description: string;
+    constructor(status: number, code: string, description: string);
+}
+/** A token refused: `status` is 401 (no token, or not a good one) or 403 (a scope missing). */
+declare class McpAuthError extends Error {
+    readonly status: 401 | 403;
+    readonly code: 'invalid_request' | 'invalid_token' | 'insufficient_scope';
+    readonly description: string;
+    constructor(status: 401 | 403, code: 'invalid_request' | 'invalid_token' | 'insufficient_scope', description: string);
+}
+/** What the MCP TypeScript SDK reads from `req.auth` (its AuthInfo). */
+interface McpAuthInfo {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    /** Seconds since the epoch. */
+    expiresAt: number;
+    resource: URL;
+    extra: {
+        userId: string;
+        tenantId: string;
+        email?: string;
+        roles: string[];
+    };
+}
+interface McpAuth {
+    /** This server's address, in the form Cauthy compares it in. */
+    resource: string;
+    /** Where the protected resource metadata is served. */
+    metadataUrl: string;
+    /** The protected resource metadata (RFC 9728). */
+    metadata(): Record<string, unknown>;
+    /** The metadata's paths: `/.well-known/oauth-protected-resource` plus this server's path. */
+    metadataPaths: string[];
+    /** Verifies the `Authorization: Bearer` of a request (or a token). Throws `McpAuthError`. */
+    verify(from: string | Request | Headers, needs?: string[]): Promise<AgentIdentity>;
+    /** The answer to a refused token: 401 or 403, with the `WWW-Authenticate` that points an agent at Cauthy. */
+    challenge(error?: McpAuthError): Response;
+    /** The metadata, when the request asks for it; `null` otherwise. */
+    handleMetadata(request: Request): Response | null;
+    /** Wraps a fetch-style handler: serves the metadata, refuses what has no good token, passes the rest with who it is. */
+    protect(handler: (request: Request, agent: AgentIdentity) => Response | Promise<Response>, needs?: string[]): (request: Request) => Promise<Response>;
+    /**
+     * Connect-style middleware (Express, Node's http): serves the metadata,
+     * refuses what has no good token, and sets `req.agent` and `req.auth` —
+     * what the MCP TypeScript SDK's transport hands its tools as `authInfo`.
+     */
+    middleware(needs?: string[]): (req: NodeRequest, res: NodeResponse, next: (err?: unknown) => void) => void;
+    /**
+     * Trades the agent's token this server received for one for another of the
+     * workspace's servers, to call it for the person (RFC 8693). Needs this
+     * server's `clientId` and `clientSecret`. Answers are kept until shortly
+     * before they expire. Throws `CauthyExchangeError` when Cauthy refuses.
+     */
+    exchange(from: string | AgentIdentity, target: string, scopes?: string[]): Promise<ExchangedToken>;
+}
+interface NodeRequest {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    auth?: McpAuthInfo;
+    agent?: AgentIdentity;
+}
+interface NodeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+/**
+ * The address in the one form Cauthy keeps it: scheme and host in lower case,
+ * no default port, no trailing slash, no query, no fragment.
+ */
+declare function canonicalResource(raw: string): string;
+/** Protects an MCP server with Cauthy. */
+declare function mcpAuth(options?: McpAuthOptions): McpAuth;
+
+export { type AgentIdentity, CauthyExchangeError, type ExchangedToken, type McpAuth, McpAuthError, type McpAuthInfo, type McpAuthOptions, canonicalResource, mcpAuth };

package/dist/mcp.d.ts

@@ -0,0 +1,151 @@
+import { JWTVerifyGetKey } from 'jose';
+
+/** The person an agent acts for, and what they allowed it. */
+interface AgentIdentity {
+    /** The person. */
+    userId: string;
+    tenantId: string;
+    email?: string;
+    /** The person's roles in the workspace. */
+    roles: string[];
+    /** What the person allowed the agent to do here. */
+    scopes: string[];
+    /** The agent (its client_id at Cauthy). */
+    clientId: string;
+    /** UTC, ISO 8601. */
+    expiresAt: string;
+    /** The token as it arrived. */
+    token: string;
+    /**
+     * Set when the token came by token exchange: the server that called this
+     * one for the person (the `act` claim's subject).
+     */
+    actor?: string;
+}
+interface McpAuthOptions {
+    /** This server's address, as registered in Cauthy. Default: `CAUTHY_MCP_RESOURCE`. */
+    resource?: string;
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** Scopes every call needs. Default: none. */
+    scopes?: string[];
+    /** The scopes this server understands, to tell agents (`scopes_supported`). Default: `scopes`. */
+    scopesSupported?: string[];
+    /** A name for the server, shown by some agents. */
+    resourceName?: string;
+    /** Cauthy's keys. Default: fetched from the issuer and cached. */
+    jwks?: JWTVerifyGetKey;
+    /** The moment to verify at. Default: now. */
+    now?: () => Date;
+    /**
+     * Ask Cauthy, besides checking the token here, whether the person still
+     * allows the agent (RFC 7662). Then an agent is cut off the moment it is
+     * disconnected, not when its token runs out, at the price of a call to
+     * Cauthy per token every `cacheSeconds` (default 30). Default: off.
+     */
+    introspect?: boolean | {
+        cacheSeconds?: number;
+    };
+    /** The fetch to call Cauthy with. Default: the global one. */
+    fetch?: typeof fetch;
+    /** How long a call to Cauthy (introspection, token exchange) may take, in milliseconds. Default: 5000. */
+    timeoutMs?: number;
+    /**
+     * This server's client_id and secret at Cauthy, for token exchange (AI
+     * agents → the server → Server credentials). Defaults:
+     * `CAUTHY_MCP_CLIENT_ID`, `CAUTHY_MCP_CLIENT_SECRET`.
+     */
+    clientId?: string;
+    clientSecret?: string;
+}
+/** What a token exchange answers. */
+interface ExchangedToken {
+    /** The token for the other server, as the person. Send it as `Authorization: Bearer`. */
+    accessToken: string;
+    /** What it allows there. */
+    scopes: string[];
+    /** UTC, ISO 8601. Never later than the agent's own token. */
+    expiresAt: string;
+}
+/** A token exchange Cauthy refused, with the OAuth error it answered. */
+declare class CauthyExchangeError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly description: string;
+    constructor(status: number, code: string, description: string);
+}
+/** A token refused: `status` is 401 (no token, or not a good one) or 403 (a scope missing). */
+declare class McpAuthError extends Error {
+    readonly status: 401 | 403;
+    readonly code: 'invalid_request' | 'invalid_token' | 'insufficient_scope';
+    readonly description: string;
+    constructor(status: 401 | 403, code: 'invalid_request' | 'invalid_token' | 'insufficient_scope', description: string);
+}
+/** What the MCP TypeScript SDK reads from `req.auth` (its AuthInfo). */
+interface McpAuthInfo {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    /** Seconds since the epoch. */
+    expiresAt: number;
+    resource: URL;
+    extra: {
+        userId: string;
+        tenantId: string;
+        email?: string;
+        roles: string[];
+    };
+}
+interface McpAuth {
+    /** This server's address, in the form Cauthy compares it in. */
+    resource: string;
+    /** Where the protected resource metadata is served. */
+    metadataUrl: string;
+    /** The protected resource metadata (RFC 9728). */
+    metadata(): Record<string, unknown>;
+    /** The metadata's paths: `/.well-known/oauth-protected-resource` plus this server's path. */
+    metadataPaths: string[];
+    /** Verifies the `Authorization: Bearer` of a request (or a token). Throws `McpAuthError`. */
+    verify(from: string | Request | Headers, needs?: string[]): Promise<AgentIdentity>;
+    /** The answer to a refused token: 401 or 403, with the `WWW-Authenticate` that points an agent at Cauthy. */
+    challenge(error?: McpAuthError): Response;
+    /** The metadata, when the request asks for it; `null` otherwise. */
+    handleMetadata(request: Request): Response | null;
+    /** Wraps a fetch-style handler: serves the metadata, refuses what has no good token, passes the rest with who it is. */
+    protect(handler: (request: Request, agent: AgentIdentity) => Response | Promise<Response>, needs?: string[]): (request: Request) => Promise<Response>;
+    /**
+     * Connect-style middleware (Express, Node's http): serves the metadata,
+     * refuses what has no good token, and sets `req.agent` and `req.auth` —
+     * what the MCP TypeScript SDK's transport hands its tools as `authInfo`.
+     */
+    middleware(needs?: string[]): (req: NodeRequest, res: NodeResponse, next: (err?: unknown) => void) => void;
+    /**
+     * Trades the agent's token this server received for one for another of the
+     * workspace's servers, to call it for the person (RFC 8693). Needs this
+     * server's `clientId` and `clientSecret`. Answers are kept until shortly
+     * before they expire. Throws `CauthyExchangeError` when Cauthy refuses.
+     */
+    exchange(from: string | AgentIdentity, target: string, scopes?: string[]): Promise<ExchangedToken>;
+}
+interface NodeRequest {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    auth?: McpAuthInfo;
+    agent?: AgentIdentity;
+}
+interface NodeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+/**
+ * The address in the one form Cauthy keeps it: scheme and host in lower case,
+ * no default port, no trailing slash, no query, no fragment.
+ */
+declare function canonicalResource(raw: string): string;
+/** Protects an MCP server with Cauthy. */
+declare function mcpAuth(options?: McpAuthOptions): McpAuth;
+
+export { type AgentIdentity, CauthyExchangeError, type ExchangedToken, type McpAuth, McpAuthError, type McpAuthInfo, type McpAuthOptions, canonicalResource, mcpAuth };