@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/src/auth/jwt.validator.ts

@@ -0,0 +1,63 @@
+import { createRemoteJWKSet, jwtVerify, errors, type JWTVerifyGetKey } from "jose";
+import { AuthError, type IAccessTokenClaims, type ITokenValidator } from "./auth.types";
+
+/**
+ * Options for {@link JwtTokenValidator}. `jwksUri` points at the authorization
+ * server's JWKS endpoint; `issuer` (when set) is checked against the token `iss`.
+ */
+export interface IJwtValidatorOptions {
+    /** URL of the authorization server's JWKS document. */
+    jwksUri: string;
+    /** Expected token issuer(s). When omitted, the `iss` claim is not checked. */
+    issuer?: string | string[];
+    /** Leeway in seconds for `exp`/`nbf` checks. Defaults to jose's `0`. */
+    clockToleranceSec?: number;
+}
+
+/**
+ * An {@link ITokenValidator} that verifies JWT access tokens **statelessly** by
+ * checking the signature against the authorization server's JWKS and validating
+ * the standard claims. This is the default validator for a public deployment:
+ * no per-request round-trip to the AS, no shared introspection secret.
+ *
+ * Audience binding (RFC 8707) is enforced by passing the per-request canonical
+ * resource URI as the required `audience`, so a token minted for another slot ,
+ * or another service, is rejected.
+ *
+ * The JWKS is fetched lazily and cached (with rotation/cooldown) by
+ * `jose.createRemoteJWKSet`.
+ */
+export class JwtTokenValidator implements ITokenValidator {
+    private readonly _jwks: JWTVerifyGetKey;
+    private readonly _issuer?: string | string[];
+    private readonly _clockTolerance: number;
+
+    constructor(options: IJwtValidatorOptions) {
+        this._jwks = createRemoteJWKSet(new URL(options.jwksUri));
+        this._issuer = options.issuer;
+        this._clockTolerance = options.clockToleranceSec ?? 0;
+    }
+
+    async validate(token: string, resource: string): Promise<IAccessTokenClaims> {
+        try {
+            const { payload } = await jwtVerify(token, this._jwks, {
+                audience: resource,
+                issuer: this._issuer,
+                clockTolerance: this._clockTolerance,
+            });
+            return payload as IAccessTokenClaims;
+        } catch (err) {
+            // Token-level failures (bad signature, wrong audience/issuer, expired,
+            // no matching key) are JOSEError subclasses ⇒ a genuine 401. Anything
+            // else (JWKS endpoint unreachable, malformed config) is infrastructure:
+            // rethrow so the caller surfaces a 500 instead of a misleading 401.
+            if (err instanceof errors.JOSEError) {
+                throw new AuthError(401, "invalid_token", err.message);
+            }
+            throw err;
+        }
+    }
+}
+
+/** @deprecated Use {@link IJwtValidatorOptions}. */
+export type JwtValidatorOptions = IJwtValidatorOptions;

package/src/auth/provider.auth.ts

@@ -0,0 +1,114 @@
+import { timingSafeEqual } from "crypto";
+import type { IncomingMessage } from "http";
+import { ResourcePath, ResourcePathPattern } from "../authorization/index";
+
+export interface IProviderPrincipal {
+    readonly id: string;
+    readonly subjects?: readonly string[];
+    readonly allowedResources?: readonly string[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export type ProviderAuthenticationResult = { readonly authenticated: true; readonly principal: IProviderPrincipal } | { readonly authenticated: false; readonly reason?: string };
+
+export type ProviderAuthenticatorReturn = boolean | ProviderAuthenticationResult;
+
+/**
+ * Authenticates a **provider** (the engine that connects _into_ the broker to
+ * serve a slot) at the WebSocket upgrade handshake. This is a distinct concern
+ * from the OAuth 2.1 resource-server layer that guards *clients*: a provider is
+ * not an OAuth client acting for a resource owner, it is the backend claiming a
+ * slot. Authenticating it is what stops a stranger from occupying a free slot
+ * (`ws://host/provider/<slot>`) and impersonating the real engine.
+ */
+export interface IProviderAuthenticator {
+    /**
+     * Returns a structured result, or a legacy boolean for backward
+     * compatibility. `slot` is the dedicated slot name for
+     * `/provider/<slot>`, or `undefined` for the multiplexed `/providers`
+     * socket, which is authenticated before any provider name is known.
+     */
+    authenticate(req: IncomingMessage, slot: string | undefined): ProviderAuthenticatorReturn | Promise<ProviderAuthenticatorReturn>;
+}
+
+export function normalizeProviderAuthentication(result: ProviderAuthenticatorReturn, fallbackId = "legacy-provider"): ProviderAuthenticationResult {
+    if (typeof result === "boolean") {
+        return result ? { authenticated: true, principal: { id: fallbackId, allowedResources: ["**"] } } : { authenticated: false };
+    }
+    if (!result.authenticated) return result;
+    if (!result.principal.id) return { authenticated: false, reason: "provider principal id is empty" };
+    return result;
+}
+
+export function providerMayPublish(principal: IProviderPrincipal, resource: ResourcePath): boolean {
+    const allowed = principal.allowedResources;
+    if (allowed === undefined) return true;
+    if (allowed.length === 0) return false;
+    try {
+        const patterns = allowed.map((pattern) => ResourcePathPattern.parse(pattern));
+        return patterns.some((pattern) => pattern.matches(resource));
+    } catch {
+        return false;
+    }
+}
+
+/** Constant-time string comparison; `false` on any length mismatch. */
+function safeEqual(a: string, b: string): boolean {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length) return false;
+    return timingSafeEqual(ab, bb);
+}
+
+/**
+ * Reads the secret a provider presents, from either the `X-Provider-Token`
+ * header or an `Authorization: Bearer <secret>` header.
+ */
+function presentedSecret(req: IncomingMessage): string | null {
+    const xheader = req.headers["x-provider-token"];
+    if (typeof xheader === "string" && xheader.trim()) return xheader.trim();
+
+    const auth = req.headers["authorization"];
+    if (typeof auth === "string") {
+        const match = /^Bearer\s+(.+)$/i.exec(auth.trim());
+        if (match) return match[1].trim();
+    }
+    return null;
+}
+
+/**
+ * The default {@link IProviderAuthenticator}: every provider connection must
+ * present a single shared secret (via `X-Provider-Token` or `Authorization:
+ * Bearer`). Compared in constant time. Suitable when the broker and its
+ * providers are operated by the same party; swap in a custom authenticator for
+ * per-slot secrets, mTLS, or a signed handshake.
+ */
+export class SharedSecretProviderAuthenticator implements IProviderAuthenticator {
+    private readonly _secret: string;
+
+    constructor(secret: string) {
+        if (!secret) {
+            throw new Error("provider auth: a non-empty shared secret is required.");
+        }
+        this._secret = secret;
+    }
+
+    authenticate(req: IncomingMessage): ProviderAuthenticationResult {
+        const presented = presentedSecret(req);
+        if (!presented || !safeEqual(presented, this._secret)) {
+            return { authenticated: false };
+        }
+        return {
+            authenticated: true,
+            principal: {
+                id: "shared-secret",
+                allowedResources: ["**"],
+            },
+        };
+    }
+}
+
+/** @deprecated Use {@link IProviderPrincipal}. */
+export type ProviderPrincipal = IProviderPrincipal;
+/** @deprecated Use {@link IProviderAuthenticator}. */
+export type ProviderAuthenticator = IProviderAuthenticator;

package/src/auth/resource.metadata.ts

@@ -0,0 +1,34 @@
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728).
+ *
+ * Each slot exposed over HTTP is an independent resource server; its metadata
+ * document tells an MCP client which authorization server(s) issue tokens for
+ * that slot and which bearer methods it accepts. Served (unauthenticated, it is
+ * public discovery data) at
+ * `<publicBaseUrl>/.well-known/oauth-protected-resource/<slot>/<mcp>`.
+ */
+
+import { buildProtectedResourceMetadata, type IProtectedResourceMetadata } from "@cyanmycelium/mcp-core";
+
+/** The RFC 9728 metadata document for a single protected resource. */
+export type { IProtectedResourceMetadata } from "@cyanmycelium/mcp-core";
+
+/**
+ * Builds the RFC 9728 metadata document for one slot.
+ *
+ * The document itself is shaped by `mcp-core`: it is defined by the MCP
+ * specification, identically for every server. What is broker-specific is only
+ * which resource a slot maps to, and that is decided by the caller.
+ * `bearer_methods_supported` comes out fixed to `["header"]`, matching the
+ * broker's refusal to read a token from anywhere but the header (OAuth 2.1 §5).
+ */
+export function buildResourceMetadata(params: { resource: string; authorizationServers: string[]; scopesSupported?: string[] }): IProtectedResourceMetadata {
+    return buildProtectedResourceMetadata({
+        resource: params.resource,
+        authorizationServers: params.authorizationServers,
+        scopesSupported: params.scopesSupported,
+    });
+}
+
+/** @deprecated Use {@link IProtectedResourceMetadata}. */
+export type ProtectedResourceMetadata = IProtectedResourceMetadata;

package/src/authorization/audit.ts

@@ -0,0 +1,35 @@
+import type { IAuthorizationAuditEvent, IAuthorizationDecision, IAuthorizationSubject } from "./policy.types";
+import type { ResourcePath } from "./resource.path";
+
+export interface IAuditContext {
+    readonly subject: IAuthorizationSubject;
+    readonly slot: string;
+    readonly resource?: ResourcePath;
+    readonly capability?: string;
+    readonly provider?: string;
+    readonly tool?: string;
+}
+
+export function makeAuthorizationAuditEvent(context: IAuditContext, decision: IAuthorizationDecision): IAuthorizationAuditEvent {
+    const clientId = context.subject.ids.find((id) => id.startsWith("client:"))?.slice("client:".length);
+    return {
+        timestamp: new Date().toISOString(),
+        allowed: decision.allowed,
+        subjectIds: context.subject.ids,
+        clientId,
+        slot: context.slot,
+        resource: context.resource?.value,
+        capability: context.capability,
+        provider: context.provider,
+        tool: context.tool,
+        reason: decision.reason,
+        matchedPolicies: decision.matchedPolicies,
+    };
+}
+
+export function writeAuthorizationAuditEvent(event: IAuthorizationAuditEvent): void {
+    console.error(`[broker] authorization ${JSON.stringify(event)}`);
+}
+
+/** @deprecated Use {@link IAuditContext}. */
+export type AuditContext = IAuditContext;

package/src/authorization/capability.classifier.ts

@@ -0,0 +1,114 @@
+import { ResourcePath, ResourcePathPattern } from "./resource.path";
+
+export interface IMcpOperation {
+    readonly method?: string;
+    readonly params?: unknown;
+}
+
+export interface IClassifiedCapability {
+    readonly capability: string;
+    readonly tool?: string;
+}
+
+export interface ICapabilityClassifier {
+    classify(operation: IMcpOperation, resource: ResourcePath, provider?: string): IClassifiedCapability | undefined;
+}
+
+interface IProviderMapping {
+    readonly pattern: ResourcePathPattern;
+    readonly tools: Readonly<Record<string, string>>;
+}
+
+const STATIC_CAPABILITIES: Readonly<Record<string, string>> = {
+    "resources/list": "mcp.resources.read",
+    "resources/read": "mcp.resources.read",
+    "tools/list": "mcp.tools.list",
+    "prompts/list": "mcp.prompts.read",
+    "prompts/get": "mcp.prompts.read",
+    "completion/complete": "mcp.completion.use",
+    "notifications/resources/list_changed": "mcp.resources.read",
+    "notifications/resources/updated": "mcp.resources.read",
+    "notifications/tools/list_changed": "mcp.tools.list",
+    "notifications/prompts/list_changed": "mcp.prompts.read",
+};
+
+const BROKER_READ_TOOLS = new Set(["broker_info", "providers_list", "provider_status"]);
+
+function toolNameFrom(params: unknown): string | undefined {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) return undefined;
+    const name = (params as Readonly<Record<string, unknown>>)["name"];
+    return typeof name === "string" && name ? name : undefined;
+}
+
+export function validateCapability(capability: string, label = "capability"): void {
+    if (typeof capability !== "string" || (capability !== "*" && !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(capability))) {
+        throw new Error(`authorization ${label}: "${capability}" is malformed.`);
+    }
+}
+
+/**
+ * Classifies MCP methods without deriving privilege from arbitrary tool names.
+ * Provider-qualified mappings win over global mappings, then tools/call falls
+ * back to `mcp.tools.call`.
+ */
+export class ConfiguredCapabilityClassifier implements ICapabilityClassifier {
+    private readonly _globalTools: Readonly<Record<string, string>>;
+    private readonly _providerMappings: readonly IProviderMapping[];
+
+    constructor(toolCapabilities: Readonly<Record<string, string>> = {}, providerToolCapabilities: Readonly<Record<string, Readonly<Record<string, string>>>> = {}) {
+        for (const [tool, capability] of Object.entries(toolCapabilities)) {
+            if (!tool) throw new Error("authorization toolCapabilities: tool names must not be empty.");
+            validateCapability(capability, `toolCapabilities["${tool}"]`);
+        }
+        this._globalTools = Object.freeze({ ...toolCapabilities });
+
+        const mappings: IProviderMapping[] = [];
+        for (const [patternValue, tools] of Object.entries(providerToolCapabilities)) {
+            const pattern = ResourcePathPattern.parse(patternValue);
+            for (const [tool, capability] of Object.entries(tools)) {
+                if (!tool) throw new Error(`authorization providerToolCapabilities["${patternValue}"]: tool names must not be empty.`);
+                validateCapability(capability, `providerToolCapabilities["${patternValue}"]["${tool}"]`);
+            }
+            mappings.push({ pattern, tools: Object.freeze({ ...tools }) });
+        }
+        mappings.sort((left, right) => right.pattern.specificity - left.pattern.specificity || left.pattern.value.localeCompare(right.pattern.value));
+        this._providerMappings = Object.freeze(mappings);
+    }
+
+    classify(operation: IMcpOperation, resource: ResourcePath, provider?: string): IClassifiedCapability | undefined {
+        const method = operation.method;
+        if (!method) return undefined;
+
+        if (provider === "_broker") {
+            if (method === "tools/list" || method === "resources/list" || method === "resources/read") {
+                return { capability: "broker.providers.read" };
+            }
+            if (method === "tools/call") {
+                const tool = toolNameFrom(operation.params);
+                if (tool && BROKER_READ_TOOLS.has(tool)) return { capability: "broker.providers.read", tool };
+            }
+        }
+
+        if (method !== "tools/call") {
+            const capability = STATIC_CAPABILITIES[method];
+            return capability ? { capability } : undefined;
+        }
+
+        const tool = toolNameFrom(operation.params);
+        if (!tool) return { capability: "mcp.tools.call" };
+        for (const mapping of this._providerMappings) {
+            if (mapping.pattern.matches(resource)) {
+                const capability = mapping.tools[tool];
+                if (capability) return { capability, tool };
+            }
+        }
+        return { capability: this._globalTools[tool] ?? "mcp.tools.call", tool };
+    }
+}
+
+/** @deprecated Use {@link IMcpOperation}. */
+export type McpOperation = IMcpOperation;
+/** @deprecated Use {@link IClassifiedCapability}. */
+export type ClassifiedCapability = IClassifiedCapability;
+/** @deprecated Use {@link ICapabilityClassifier}. */
+export type CapabilityClassifier = ICapabilityClassifier;

package/src/authorization/index.ts

@@ -0,0 +1,37 @@
+export { ResourcePath, ResourcePathPattern } from "./resource.path";
+export { ConfiguredCapabilityClassifier, validateCapability } from "./capability.classifier";
+export type { CapabilityClassifier, ClassifiedCapability, ICapabilityClassifier, IClassifiedCapability, IMcpOperation, McpOperation } from "./capability.classifier";
+export { ConfigPolicyEngine } from "./policy.engine";
+export { JwtSubjectMapper, SubjectMappingError } from "./subject.mapper";
+export type { ISubjectMapper, SubjectMapper } from "./subject.mapper";
+export { DefaultSlotResourceResolver } from "./slot.resource";
+export type { ISlotResourceResolver, SlotResourceResolver } from "./slot.resource";
+export { authorizationWithEngine, compileAuthorizationPolicy, hasAuthorizationPolicies } from "./runtime";
+export type { IPolicyAuthorization, PolicyAuthorization } from "./runtime";
+export { makeAuthorizationAuditEvent, writeAuthorizationAuditEvent } from "./audit";
+export type { AuditContext, IAuditContext } from "./audit";
+export type {
+    AuthorizationAuditConfig,
+    AuthorizationAuditEvent,
+    AuthorizationDecision,
+    AuthorizationDecisionReason,
+    AuthorizationPolicyConfig,
+    AuthorizationRequest,
+    AuthorizationSubject,
+    DenyPolicy,
+    IAuthorizationAuditConfig,
+    IAuthorizationAuditEvent,
+    IAuthorizationDecision,
+    IAuthorizationPolicyConfig,
+    IAuthorizationRequest,
+    IAuthorizationSubject,
+    IDenyPolicy,
+    IPolicyAssignment,
+    IPolicyEngine,
+    IRoleDefinition,
+    ISubjectMappingConfig,
+    PolicyAssignment,
+    PolicyEngine,
+    RoleDefinition,
+    SubjectMappingConfig,
+} from "./policy.types";

package/src/authorization/policy.engine.ts

@@ -0,0 +1,212 @@
+import { validateCapability } from "./capability.classifier";
+import type { IAuthorizationDecision, IAuthorizationRequest, IDenyPolicy, IPolicyAssignment, IPolicyEngine, IRoleDefinition } from "./policy.types";
+import { ResourcePathPattern } from "./resource.path";
+
+interface ICompiledAssignment {
+    readonly id: string;
+    readonly subject: string;
+    readonly capabilities: ReadonlySet<string>;
+    readonly resource: ResourcePathPattern;
+}
+
+interface ICompiledDeny {
+    readonly id: string;
+    readonly subject: string;
+    readonly capabilities: ReadonlySet<string>;
+    readonly resource: ResourcePathPattern;
+}
+
+function validateName(value: string, label: string): void {
+    if (typeof value !== "string" || !value || value.trim() !== value || value.includes("/")) {
+        throw new Error(`authorization ${label}: "${value}" is invalid.`);
+    }
+}
+
+function validateSubject(subject: string, label: string): void {
+    if (typeof subject !== "string" || !/^[A-Za-z][A-Za-z0-9_-]*:.+$/.test(subject)) {
+        throw new Error(`authorization ${label}: subject "${subject}" must use a non-empty extensible prefix such as "user:alice".`);
+    }
+}
+
+function validatePolicyId(id: string, label: string): void {
+    if (typeof id !== "string" || !id || id.trim() !== id) {
+        throw new Error(`authorization ${label}: policy ids must be non-empty and must not contain surrounding whitespace.`);
+    }
+}
+
+function expandRoles(roles: Readonly<Record<string, IRoleDefinition>>): ReadonlyMap<string, ReadonlySet<string>> {
+    const expanded = new Map<string, ReadonlySet<string>>();
+    const visiting: string[] = [];
+
+    for (const [name, role] of Object.entries(roles)) {
+        validateName(name, "role");
+        for (const key of Object.keys(role)) {
+            if (key !== "inherits" && key !== "capabilities") {
+                throw new Error(`authorization role "${name}": unsupported field "${key}"; roles contain capabilities, not resource paths.`);
+            }
+        }
+        if (!Array.isArray(role.capabilities)) {
+            throw new Error(`authorization role "${name}": capabilities must be an array.`);
+        }
+        if (role.inherits !== undefined && !Array.isArray(role.inherits)) {
+            throw new Error(`authorization role "${name}": inherits must be an array.`);
+        }
+        for (const capability of role.capabilities) validateCapability(capability, `role "${name}" capability`);
+        for (const inherited of role.inherits ?? []) {
+            validateName(inherited, `role "${name}" inheritance`);
+            if (!roles[inherited]) {
+                throw new Error(`authorization role "${name}": inherited role "${inherited}" is not defined.`);
+            }
+        }
+    }
+
+    const visit = (name: string): ReadonlySet<string> => {
+        const cached = expanded.get(name);
+        if (cached) return cached;
+
+        const cycleStart = visiting.indexOf(name);
+        if (cycleStart >= 0) {
+            const cycle = [...visiting.slice(cycleStart), name].join(" -> ");
+            throw new Error(`authorization roles: inheritance cycle detected: ${cycle}.`);
+        }
+
+        const role = roles[name];
+        if (!role) throw new Error(`authorization roles: role "${name}" is not defined.`);
+        visiting.push(name);
+        const capabilities = new Set<string>();
+        for (const inherited of role.inherits ?? []) {
+            for (const capability of visit(inherited)) capabilities.add(capability);
+        }
+        for (const capability of role.capabilities) capabilities.add(capability);
+        visiting.pop();
+        const frozen = Object.freeze(capabilities);
+        expanded.set(name, frozen);
+        return frozen;
+    };
+
+    for (const name of Object.keys(roles)) visit(name);
+    return expanded;
+}
+
+function indexBySubject<T extends { readonly subject: string }>(entries: readonly T[]): ReadonlyMap<string, readonly T[]> {
+    const mutable = new Map<string, T[]>();
+    for (const entry of entries) {
+        const bucket = mutable.get(entry.subject);
+        if (bucket) bucket.push(entry);
+        else mutable.set(entry.subject, [entry]);
+    }
+    const result = new Map<string, readonly T[]>();
+    for (const [subject, bucket] of mutable) result.set(subject, Object.freeze(bucket));
+    return result;
+}
+
+function grants(capabilities: ReadonlySet<string>, requested: string): boolean {
+    return capabilities.has("*") || capabilities.has(requested);
+}
+
+/**
+ * Immutable, indexed in-memory policy engine. Role inheritance and resource
+ * expressions are fully compiled in the constructor.
+ */
+export class ConfigPolicyEngine implements IPolicyEngine {
+    private readonly _assignmentsBySubject: ReadonlyMap<string, readonly ICompiledAssignment[]>;
+    private readonly _deniesBySubject: ReadonlyMap<string, readonly ICompiledDeny[]>;
+
+    constructor(roles: Readonly<Record<string, IRoleDefinition>>, assignments: readonly IPolicyAssignment[], denies: readonly IDenyPolicy[]) {
+        const expandedRoles = expandRoles(roles);
+        const policyIds = new Set<string>();
+
+        const reserveId = (id: string, label: string): void => {
+            validatePolicyId(id, label);
+            if (policyIds.has(id)) throw new Error(`authorization policies: duplicate policy id "${id}".`);
+            policyIds.add(id);
+        };
+
+        const compiledAssignments = assignments.map((assignment, index): ICompiledAssignment => {
+            const id = assignment.id ?? `assignment:${index}`;
+            reserveId(id, `assignment ${index}`);
+            validateSubject(assignment.subject, `assignment "${id}"`);
+            validateName(assignment.role, `assignment "${id}" role`);
+            const capabilities = expandedRoles.get(assignment.role);
+            if (!capabilities) {
+                throw new Error(`authorization assignment "${id}": role "${assignment.role}" is not defined.`);
+            }
+            if (!assignment.resource) throw new Error(`authorization assignment "${id}": resource must not be empty.`);
+            return {
+                id,
+                subject: assignment.subject,
+                capabilities,
+                resource: ResourcePathPattern.parse(assignment.resource),
+            };
+        });
+
+        const compiledDenies = denies.map((deny, index): ICompiledDeny => {
+            const id = deny.id ?? `deny:${index}`;
+            reserveId(id, `deny ${index}`);
+            validateSubject(deny.subject, `deny "${id}"`);
+            if (deny.effect !== undefined && deny.effect !== "deny") {
+                throw new Error(`authorization deny "${id}": effect must be "deny".`);
+            }
+            if (!Array.isArray(deny.capabilities) || deny.capabilities.length === 0) {
+                throw new Error(`authorization deny "${id}": at least one capability is required.`);
+            }
+            const capabilities = new Set<string>();
+            for (const capability of deny.capabilities) {
+                validateCapability(capability, `deny "${id}" capability`);
+                capabilities.add(capability);
+            }
+            if (!deny.resource) throw new Error(`authorization deny "${id}": resource must not be empty.`);
+            return {
+                id,
+                subject: deny.subject,
+                capabilities: Object.freeze(capabilities),
+                resource: ResourcePathPattern.parse(deny.resource),
+            };
+        });
+
+        this._assignmentsBySubject = indexBySubject(compiledAssignments);
+        this._deniesBySubject = indexBySubject(compiledDenies);
+    }
+
+    authorize(request: IAuthorizationRequest): IAuthorizationDecision {
+        if (!request.resource) return { allowed: false, reason: "invalid-resource" };
+        try {
+            validateCapability(request.capability, "request capability");
+        } catch {
+            return { allowed: false, reason: "no-matching-grant" };
+        }
+
+        const matchingDenies = new Set<string>();
+        for (const subject of request.subject.ids) {
+            for (const deny of this._deniesBySubject.get(subject) ?? []) {
+                if (deny.resource.matches(request.resource) && grants(deny.capabilities, request.capability)) {
+                    matchingDenies.add(deny.id);
+                }
+            }
+        }
+        if (matchingDenies.size > 0) {
+            return {
+                allowed: false,
+                reason: "explicit-deny",
+                matchedPolicies: Object.freeze([...matchingDenies].sort()),
+            };
+        }
+
+        const matchingGrants = new Set<string>();
+        for (const subject of request.subject.ids) {
+            for (const assignment of this._assignmentsBySubject.get(subject) ?? []) {
+                if (assignment.resource.matches(request.resource) && grants(assignment.capabilities, request.capability)) {
+                    matchingGrants.add(assignment.id);
+                }
+            }
+        }
+        if (matchingGrants.size > 0) {
+            return {
+                allowed: true,
+                reason: "role-grant",
+                matchedPolicies: Object.freeze([...matchingGrants].sort()),
+            };
+        }
+        return { allowed: false, reason: "no-matching-grant" };
+    }
+}