mcp-authz 0.1.0 → 0.3.0

package/dist/policy.js

@@ -1,203 +1,2 @@
-//#region src/policy.ts
-/**
-* A policy from a plain object.
-*
-* Written inline as a literal, the permission names become a string-literal
-* union, so a tool requiring `cases:wrtie` fails to compile. Handed
-* `JSON.parse(process.env.MCP_POLICY)` or a parsed YAML file the same call
-* still validates its shape and still reconciles against the tools at boot —
-* it just cannot type-check names TypeScript never sees. Nothing here reads the
-* environment or the filesystem: how an application loads configuration is the
-* application's business.
-*
-* There is deliberately no `default` setting. Matching no rule means no
-* permissions, and that is not configurable — a default that can be widened
-* eventually is, and the failure is silent.
-*/
-function definePolicy(spec) {
-	if (!isRecord(spec)) throw new Error("Policy must be an object.");
-	for (const key of Object.keys(spec)) if (![
-		"permissions",
-		"roles",
-		"rules"
-	].includes(key)) throw new Error(`Policy has unknown field '${key}'.`);
-	if (!isRecord(spec.roles)) throw new Error("Policy 'roles' must be an object.");
-	if (!Array.isArray(spec.rules)) throw new Error("Policy 'rules' must be an array.");
-	const catalogue = spec.permissions === void 0 ? void 0 : stringList(spec.permissions, "Policy 'permissions'");
-	if (catalogue?.includes("*")) throw new Error("Policy 'permissions' must name concrete permissions, not '*'.");
-	const known = catalogue ? new Set(catalogue) : void 0;
-	const roles = /* @__PURE__ */ new Map();
-	for (const [role, permissions] of Object.entries(spec.roles ?? {})) {
-		if (!role) throw new Error("Policy role names must not be empty.");
-		const validated = stringList(permissions, `Policy role '${role}'`);
-		if (validated.includes("*") && validated.length > 1) throw new Error(`Policy role '${role}' grants '*' and must not list redundant permissions.`);
-		for (const permission of validated) if (permission !== "*" && known && !known.has(permission)) throw new Error(`Policy role '${role}' grants '${permission}', which is absent from the permission catalogue.`);
-		roles.set(role, validated);
-	}
-	const rules = (spec.rules ?? []).map((rule, index) => {
-		const at = `Policy rule ${index}`;
-		if (!isRecord(rule)) throw new Error(`${at} must be an object.`);
-		for (const key of Object.keys(rule)) if (![
-			"match",
-			"role",
-			"deny"
-		].includes(key)) throw new Error(`${at} has unknown field '${key}'.`);
-		if (rule.deny !== void 0 && typeof rule.deny !== "boolean") throw new Error(`${at} 'deny' must be a boolean.`);
-		if (!rule.deny && rule.role === void 0) throw new Error(`${at} grants nothing: it needs a 'role' or 'deny: true'.`);
-		const named = roleNames(rule.role, at);
-		for (const role of named) if (!roles.has(role)) throw new Error(`${at} names role '${role}', which is not defined.`);
-		return {
-			match: validateMatch(rule.match, at),
-			deny: rule.deny === true,
-			roles: named
-		};
-	});
-	const policy = (identity) => {
-		const matched = rules.filter((rule) => matches(rule.match, identity));
-		const denied = matched.some((rule) => rule.deny);
-		const held = denied ? [] : [...new Set(matched.flatMap((rule) => rule.roles))];
-		return createPrincipal(identity, held, denied ? [] : [...new Set(held.flatMap((role) => [...roles.get(role) ?? []]))]);
-	};
-	const concrete = catalogue ?? [...new Set([...roles.values()].flat().filter((permission) => permission !== "*"))];
-	return Object.assign(policy, {
-		roles,
-		permissions: concrete
-	});
-}
-/** A typed permission vocabulary for async authorizers that do not use a static policy. */
-function definePermissions(permissions) {
-	const catalogue = stringList(permissions, "Permission catalogue");
-	if (catalogue.includes("*")) throw new Error("Permission catalogue must name concrete permissions, not '*'.");
-	return { permissions: catalogue };
-}
-/** Build a sound principal from an external entitlement decision. */
-function createPrincipal(identity, roles, permissions) {
-	if (!isRecord(identity) || typeof identity.sub !== "string" || identity.sub.length === 0) throw new Error("Principal identity needs a non-empty subject.");
-	if (typeof identity.issuer !== "string" || identity.issuer.length === 0) throw new Error("Principal identity needs a non-empty issuer.");
-	if (identity.email !== void 0 && identity.email.length === 0) throw new Error("Principal identity email must not be empty.");
-	const heldRoles = [...new Set(stringList(roles, "Principal roles"))];
-	const heldPermissions = [...new Set(stringList(permissions, "Principal permissions"))];
-	const wildcard = heldPermissions.includes("*");
-	return {
-		issuer: identity.issuer,
-		sub: identity.sub,
-		email: identity.email,
-		domain: identity.domain,
-		roles: heldRoles,
-		permissions: heldPermissions,
-		can: (permission) => wildcard || heldPermissions.includes(permission)
-	};
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function stringList(value, at) {
-	if (!Array.isArray(value)) throw new Error(`${at} must be an array of permission strings.`);
-	const result = [];
-	for (const entry of value) {
-		if (typeof entry !== "string" || entry.length === 0) throw new Error(`${at} must be an array of non-empty permission strings.`);
-		if (!result.includes(entry)) result.push(entry);
-	}
-	return result;
-}
-function roleNames(value, at) {
-	if (value === void 0) return [];
-	const values = Array.isArray(value) ? value : [value];
-	if (values.length === 0 || values.some((role) => typeof role !== "string" || role.length === 0)) throw new Error(`${at} 'role' must be a non-empty role name or array of role names.`);
-	return [...new Set(values)];
-}
-function validateMatch(value, at) {
-	if (value === void 0) return {};
-	if (!isRecord(value)) throw new Error(`${at} 'match' must be an object.`);
-	for (const key of Object.keys(value)) if (![
-		"issuer",
-		"sub",
-		"email",
-		"domain",
-		"claim"
-	].includes(key)) throw new Error(`${at} match has unknown field '${key}'.`);
-	for (const key of [
-		"issuer",
-		"sub",
-		"email",
-		"domain"
-	]) {
-		const field = value[key];
-		if (field !== void 0 && (typeof field !== "string" || field.length === 0)) throw new Error(`${at} match '${key}' must be a non-empty string.`);
-	}
-	const claim = value.claim;
-	if (claim !== void 0) {
-		if (!isRecord(claim)) throw new Error(`${at} match 'claim' must be an object.`);
-		for (const [path, expected] of Object.entries(claim)) if (!path || typeof expected !== "string" || !expected) throw new Error(`${at} match claim entries must have non-empty string names and values.`);
-	}
-	return value;
-}
-function matches(match, identity) {
-	if (match.issuer !== void 0 && match.issuer !== identity.issuer) return false;
-	if (match.sub !== void 0 && match.sub !== identity.sub) return false;
-	if (match.email !== void 0 && (!identity.emailVerified || !equalsFold(match.email, identity.email))) return false;
-	if (match.domain !== void 0 && !equalsFold(match.domain, domainOf(identity))) return false;
-	for (const [path, expected] of Object.entries(match.claim ?? {})) {
-		const actual = claimAt(identity.claims, path);
-		if (!(Array.isArray(actual) ? actual.includes(expected) : actual === expected)) return false;
-	}
-	return true;
-}
-function equalsFold(a, b) {
-	return b !== void 0 && a.toLowerCase() === b.toLowerCase();
-}
-/** The `hd` claim when the AS passes it, otherwise whatever follows the `@`. */
-function domainOf(identity) {
-	if (!identity.emailVerified || !identity.email) return void 0;
-	if (identity.domain) return identity.domain;
-	const at = identity.email.lastIndexOf("@");
-	return at === -1 ? void 0 : identity.email.slice(at + 1);
-}
-/**
-* A literal claim name wins over a dotted path, because the namespaced claims
-* an IdP actually emits are full of dots — Auth0 writes group memberships to
-* `https://acme.com/groups`, and splitting that on `.` finds nothing.
-*/
-function claimAt(claims, path) {
-	if (path in claims) return claims[path];
-	let value = claims;
-	for (const key of path.split(".")) {
-		if (typeof value !== "object" || value === null) return void 0;
-		value = value[key];
-	}
-	return value;
-}
-/**
-* Compare what the tools demand against what the roles grant.
-*
-* A gateway cannot run this check at all — it does not learn the tool list
-* until traffic arrives, and its rules were never compiled alongside the
-* implementation.
-*/
-function reconcile(roles, required) {
-	const grantedBy = /* @__PURE__ */ new Map();
-	for (const [role, permissions] of roles) for (const permission of permissions) grantedBy.set(permission, [...grantedBy.get(permission) ?? [], role]);
-	const unreachable = grantedBy.has("*") ? [] : [...required].filter(([, permission]) => !grantedBy.has(permission));
-	const unused = [...grantedBy].filter(([permission]) => permission !== "*").filter(([permission]) => ![...required.values()].includes(permission));
-	const drift = {};
-	if (unreachable.length > 0) {
-		const report = [
-			"MCP policy validation failed",
-			"",
-			"Unreachable capability:"
-		];
-		for (const [tool, permission] of unreachable) report.push(`  ${tool}`, `    requires: ${permission}`, "    granted by: no role", "");
-		drift.error = report.join("\n");
-	}
-	if (unused.length > 0) {
-		const report = ["MCP policy has unused permissions:"];
-		for (const [permission, byRoles] of unused) {
-			const by = byRoles.map((role) => `"${role}"`).join(", ");
-			report.push(`  ${permission}`, `    granted by: ${by}`, "    required by: no registered capability", "");
-		}
-		drift.warning = report.join("\n");
-	}
-	return drift;
-}
-//#endregion
+import { i as reconcile, n as definePermissions, r as definePolicy, t as createPrincipal } from "./policy-BBp3Jq6G.js";
 export { createPrincipal, definePermissions, definePolicy, reconcile };

package/dist/proxy.d.ts

@@ -0,0 +1,46 @@
+import { _ as Identity, s as Policy } from "./policy-DuZbwrKf.js";
+import { a as AuthorizationDecisionSink, t as VerifierOptions } from "./verifier-DF6gUMQ6.js";
+import { t as CapabilityScopeMap } from "./ladder-D18eJ7tD.js";
+import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
+//#region src/upstream.d.ts
+type UpstreamConfig = {
+  /** Base MCP endpoint the proxy forwards to. */
+  url: string | URL;
+  bearer: string | (() => string | Promise<string>);
+  fetch?: typeof fetch;
+};
+//#endregion
+//#region src/proxy.d.ts
+type McpProxyOptions<P extends string = string> = {
+  /** This proxy's public URL, e.g. `https://mcp.acme.com/mcp`. */
+  resourceServerUrl: URL;
+  /** RFC 8414 metadata for the authorization server in front of the proxy. */
+  oauthMetadata: OAuthMetadata;
+  verifier?: Partial<VerifierOptions>;
+  tokenVerifier?: OAuthTokenVerifier;
+  identityFromAuth?: (auth: AuthInfo) => Identity;
+  /** URL-only upstream reached with a service credential. */
+  upstream: UpstreamConfig;
+  /** Flat permission map — same labels as `gate()` and `recordCapabilities`. */
+  permissions: Readonly<Record<string, P>> | ReadonlyMap<string, P>;
+  /**
+   * `resource:<label>` to the URI or URI template it answers on.
+   *
+   * A listing names a resource; a read names a URI. Only the upstream knows
+   * which is which, so the map that prices resources has to carry both.
+   * `recordCapabilities` emits this alongside the permission map.
+   */
+  resourceUris?: Readonly<Record<string, string>>;
+  policy: Policy<P>;
+  requiredScopes?: string[];
+  supportedScopes?: string[];
+  capabilityScopes?: CapabilityScopeMap;
+  onDecision?: AuthorizationDecisionSink;
+  /** Names this deployment on every event it emits. See `McpFetchOptions`. */
+  emitter?: string;
+  healthPath?: string;
+  maxRequestBytes?: number;
+};
+declare function createMcpProxy<P extends string = string>(options: McpProxyOptions<P>): (request: Request) => Promise<Response>;
+//#endregion
+export { McpProxyOptions, createMcpProxy };