mcp-authz 0.1.0

package/dist/node.d.ts

@@ -0,0 +1,16 @@
+import { Server } from "node:http";
+//#region src/node.d.ts
+type ListenMcpOptions = {
+  port: number;
+  /** Log label. Defaults to `mcp-authz`. */
+  name?: string;
+  /** Extra lines logged after the listen banner. */
+  info?: Record<string, string | undefined>;
+};
+/**
+ * Bind a `createMcpFetch` handler to every interface. Safe because the
+ * bearer gate is the security boundary, not the bind address.
+ */
+declare function listenMcp(fetch: (request: Request) => Promise<Response>, options: ListenMcpOptions): Promise<Server>;
+//#endregion
+export { ListenMcpOptions, listenMcp };

package/dist/node.js

@@ -0,0 +1,46 @@
+import { createServer } from "node:http";
+import { toNodeHandler } from "@modelcontextprotocol/node";
+//#region src/node.ts
+/**
+* Bind a `createMcpFetch` handler to every interface. Safe because the
+* bearer gate is the security boundary, not the bind address.
+*/
+async function listenMcp(fetch, options) {
+	const { port, name = "mcp-authz", info = {} } = options;
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`PORT must be an integer between 1 and 65535; received ${port}.`);
+	const nodeHandler = toNodeHandler({ fetch });
+	const server = createServer((request, response) => {
+		response.setHeader("X-Content-Type-Options", "nosniff");
+		response.setHeader("Referrer-Policy", "no-referrer");
+		Promise.resolve(nodeHandler(request, response)).catch((error) => {
+			console.error(`[${name}]`, error);
+			if (!response.headersSent) response.writeHead(500);
+			response.end("Internal Server Error");
+		});
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	console.log(`${name} on :${port}`);
+	for (const [key, value] of Object.entries(info)) if (value) console.log(`  ${key.padEnd(10)} ${value}`);
+	let stopping = false;
+	function shutdown(signal) {
+		if (stopping) return;
+		stopping = true;
+		console.error(`[${name}] ${signal}; draining connections`);
+		server.close((error) => {
+			if (error) console.error(`[${name}] shutdown failed`, error);
+			process.exitCode = error ? 1 : 0;
+		});
+		setTimeout(() => server.closeAllConnections(), 1e4).unref();
+	}
+	process.once("SIGINT", () => shutdown("SIGINT"));
+	process.once("SIGTERM", () => shutdown("SIGTERM"));
+	return server;
+}
+//#endregion
+export { listenMcp };

package/dist/policy-CnQj53Hq.d.ts

@@ -0,0 +1,144 @@
+//#region src/identity.d.ts
+/**
+ * What the token verifier proved about the caller.
+ *
+ * Its own file because everything downstream depends on it and nothing it
+ * depends on is vendor-specific.
+ */
+type Identity = {
+  /** Exact token issuer. Stable identity is the pair `(issuer, sub)`. */
+  issuer: string;
+  /**
+   * The token's `sub`. Stable across an email change and across a rename, which
+   * is why policy should prefer it for anything durable.
+   */
+  sub: string;
+  /** Email asserted by the issuer, when present. Never a client-supplied header. */
+  email?: string;
+  /** Whether the verifier proved the email claim. */
+  emailVerified: boolean;
+  /** Google Workspace domain (the `hd` claim), when the AS passes it through. */
+  domain?: string;
+  /**
+   * The remaining verified claims, so policy can match on groups an IdP already
+   * maintains rather than a list somebody has to keep in step by hand.
+   */
+  claims: Record<string, unknown>;
+};
+/** Why a verified caller was refused. */
+type DenialReason = 'not_permitted' | 'no_credential';
+declare class AccessDeniedError extends Error {
+  readonly email: string;
+  readonly reason: DenialReason;
+  constructor(email: string, reason: DenialReason, message: string);
+  static notPermitted(email: string, policyHint?: string): AccessDeniedError;
+  static noCredential(email: string, credentialHint?: string): AccessDeniedError;
+}
+//#endregion
+//#region src/policy.d.ts
+/**
+ * Permissions are the authorization primitive. Roles are only a convenient name
+ * for a set of them, which is why nothing downstream ever asks what role
+ * somebody holds.
+ *
+ * Nothing in this file imports MCP: an identity in, a principal out. The same
+ * policy gates any tool-calling surface, and MCP is one of them.
+ */
+type Principal<P extends string = string> = {
+  issuer: string;
+  /** Stable subject from the token. Prefer it to email for anything durable. */
+  sub: string;
+  email?: string;
+  domain?: string;
+  roles: string[];
+  permissions: string[];
+  /** A method rather than an array check because it honours a `*` grant. */
+  can: (permission: P) => boolean;
+};
+/** Everything a rule can match on. All present fields must match. */
+type Match = {
+  issuer?: string;
+  sub?: string;
+  email?: string;
+  domain?: string;
+  /**
+   * A claim name, or a dotted path into a nested one (`org.id`). A namespaced
+   * name containing dots is matched literally first, so Auth0's
+   * `https://acme.com/groups` works as written. A scalar claim must equal the
+   * value; an array claim must contain it, which is how group lists match.
+   */
+  claim?: Record<string, string>;
+};
+type Rule<R extends string = string> = {
+  /** Omit to match every authenticated caller. */
+  match?: Match;
+  role?: R | readonly R[];
+  /** Matched by a deny rule and the principal gets nothing, whatever else says. */
+  deny?: boolean;
+};
+type PolicySpec = {
+  /**
+   * Optional source-of-truth permission catalogue. Required for a policy whose
+   * roles grant only `*`; otherwise TypeScript has no literal names to infer.
+   */
+  permissions?: readonly string[];
+  roles: Record<string, readonly string[]>;
+  rules: readonly Rule[];
+};
+type Policy<P extends string = string> = ((identity: Identity) => Principal<P>) & {
+  /** Role name to the permissions it grants. Reconciled against the tools at boot. */
+  readonly roles: ReadonlyMap<string, readonly string[]>;
+  /** Concrete permission vocabulary carried for builders and diagnostics. */
+  readonly permissions: readonly P[];
+};
+type PermissionCatalog<P extends string = string> = {
+  readonly permissions: readonly P[];
+};
+/** The permissions a policy can grant, as a union of string literals. */
+type PermissionOf<T> = T extends Policy<infer P> ? P : never;
+type RolesIn<T extends PolicySpec> = keyof T['roles'] & string;
+type PermissionsIn<T extends PolicySpec> = T extends {
+  readonly permissions: readonly string[];
+} ? T['permissions'][number] : Exclude<T['roles'][keyof T['roles']][number], '*'>;
+/**
+ * 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.
+ */
+declare function definePolicy<const T extends PolicySpec>(spec: T & {
+  rules: readonly Rule<RolesIn<T>>[];
+}): Policy<PermissionsIn<T>>;
+/** A typed permission vocabulary for async authorizers that do not use a static policy. */
+declare function definePermissions<const P extends readonly string[]>(permissions: P): PermissionCatalog<P[number]>;
+/** Build a sound principal from an external entitlement decision. */
+declare function createPrincipal<P extends string>(identity: Identity, roles: readonly string[], permissions: readonly (P | '*')[]): Principal<P>;
+type Drift = {
+  /** A capability no role can reach. Fatal: it is dead code that looks live. */
+  error?: string;
+  /**
+   * A permission no capability requires. A warning rather than a failure, because
+   * granting a role ahead of the tool that uses it is how a staged rollout
+   * works, and failing the boot on it just teaches people to add dummy tools.
+   */
+  warning?: string;
+};
+/**
+ * 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.
+ */
+declare function reconcile(roles: ReadonlyMap<string, readonly string[]>, required: ReadonlyMap<string, string>): Drift;
+//#endregion
+export { Policy as a, Rule as c, definePolicy as d, reconcile as f, Identity as h, PermissionOf as i, createPrincipal as l, DenialReason as m, Match as n, PolicySpec as o, AccessDeniedError as p, PermissionCatalog as r, Principal as s, Drift as t, definePermissions as u };

package/dist/policy.d.ts

@@ -0,0 +1,2 @@
+import { a as Policy, c as Rule, d as definePolicy, f as reconcile, h as Identity, i as PermissionOf, l as createPrincipal, n as Match, o as PolicySpec, r as PermissionCatalog, s as Principal, t as Drift, u as definePermissions } from "./policy-CnQj53Hq.js";
+export { Drift, type Identity, Match, PermissionCatalog, PermissionOf, Policy, PolicySpec, Principal, Rule, createPrincipal, definePermissions, definePolicy, reconcile };

package/dist/policy.js

@@ -0,0 +1,203 @@
+//#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
+export { createPrincipal, definePermissions, definePolicy, reconcile };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "mcp-authz",
+  "version": "0.1.0",
+  "description": "Authorization for MCP servers: OAuth 2.1 resource server, roles/permissions policy, permission-gated tools (2026-07-28)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/mcp-authz",
+    "directory": "packages/mcp-authz"
+  },
+  "homepage": "https://github.com/jagreehal/mcp-authz#readme",
+  "bugs": {
+    "url": "https://github.com/jagreehal/mcp-authz/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "oauth",
+    "authorization",
+    "resource-server",
+    "rbac"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "jose": "^6.0.11"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/node": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@types/node": "^26.1.2",
+    "executable-stories-vitest": "8.6.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run && prettier --write docs/stories.md",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}