nucleus-core-ts 0.9.705 → 0.9.707

package/dist/src/Client/Proxy/authz.d.ts

@@ -0,0 +1,74 @@
+import type { ManifestRoute, ProxyAuthorizeConfig, ProxyLogger } from './types';
+/**
+ * Reverse-proxy claim-gate. Enforces the discovered `{serviceId}.{tag}.{op}` claims
+ * (see nucleus endpointDiscovery) at the proxy: a request is allowed only if the
+ * VERIFIED access token holds a claim that satisfies the route's required action.
+ *
+ * Security: the token is HS256-verified with the access-token secret before its
+ * claims are trusted — decoding without verifying would let a forged token bypass
+ * the gate. Requires `jwtClaimsMode: 'embed'` on the IDP (claims travel in the JWT).
+ */
+export type { ManifestRoute, ProxyAuthorizeConfig } from './types';
+/** HS256-verify a JWT and return its payload, or null if invalid/expired/tampered. */
+export declare function verifyJwtHS256(token: string, secret: string): Record<string, unknown> | null;
+/** Hierarchical prefix match: a shorter claim grants longer actions (`agent` ⇒ `agent.x.y`). */
+export declare function claimSatisfies(userClaims: string[], required: string): boolean;
+/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */
+export declare function pathMatchesTemplate(template: string, concrete: string): boolean;
+export declare function findRequiredAction(manifest: ManifestRoute[], method: string, path: string): string | null;
+export interface AccessDecision {
+    decision: 'allow' | 'deny';
+    reason: string;
+    action: string | null;
+}
+/**
+ * Pure authorization decision. `claims`/`roles` are ALREADY resolved by the caller
+ * (from the JWT in embed mode, or via the role-claims manifest in resolve mode), so
+ * this stays mode-agnostic and easy to test.
+ */
+export declare function evaluateAccess(args: {
+    manifest: ManifestRoute[];
+    method: string;
+    path: string;
+    authenticated: boolean;
+    roles: string[];
+    claims: string[];
+    onUnmapped: 'allow' | 'deny';
+    publicPaths?: string[];
+    godminRole: string;
+}): AccessDecision;
+/** Fetches + caches a service's route manifest from the IDP. */
+export declare class ManifestCache {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly logger?;
+    private routes;
+    private fetchedAtMs;
+    private inflight;
+    constructor(cfg: ProxyAuthorizeConfig['manifest'] & {
+        serviceId: string;
+    }, fetchImpl?: typeof fetch, logger?: ProxyLogger | undefined);
+    private get ttlMs();
+    private refresh;
+    get(): Promise<ManifestRoute[]>;
+}
+/** Fetches + caches the role→claim-actions map (resolve mode) from the IDP. */
+export declare class RoleClaimsCache {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly logger?;
+    private map;
+    private fetchedAtMs;
+    private inflight;
+    constructor(cfg: {
+        url: string;
+        token?: string;
+        refreshSec?: number;
+        serviceId: string;
+    }, fetchImpl?: typeof fetch, logger?: ProxyLogger | undefined);
+    private get ttlMs();
+    private refresh;
+    get(): Promise<Record<string, string[]>>;
+}
+/** Resolve a user's roles to their claim actions using the role-claims map. */
+export declare function resolveClaimsFromRoles(roles: string[], roleClaims: Record<string, string[]>): string[];

package/dist/src/Client/Proxy/authz.js

@@ -0,0 +1,202 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** HS256-verify a JWT and return its payload, or null if invalid/expired/tampered. */ export function verifyJwtHS256(token, secret) {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const [header, payloadB64, sigB64] = parts;
+    if (!header || !payloadB64 || !sigB64) return null;
+    try {
+        const expected = createHmac('sha256', secret).update(`${header}.${payloadB64}`).digest();
+        const got = Buffer.from(sigB64, 'base64url');
+        if (expected.length !== got.length || !timingSafeEqual(expected, got)) return null;
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+        if (typeof payload.exp === 'number' && payload.exp * 1000 < Date.now()) return null;
+        return payload;
+    } catch  {
+        return null;
+    }
+}
+/** Hierarchical prefix match: a shorter claim grants longer actions (`agent` ⇒ `agent.x.y`). */ export function claimSatisfies(userClaims, required) {
+    return userClaims.some((uc)=>required === uc || required.startsWith(`${uc}.`));
+}
+/** True when a concrete request path matches a templated OpenAPI path (params = wildcards). */ export function pathMatchesTemplate(template, concrete) {
+    const t = template.replace(/\/+$/, '').split('/');
+    const c = concrete.replace(/\/+$/, '').split('/');
+    if (t.length !== c.length) return false;
+    for(let i = 0; i < t.length; i++){
+        const seg = t[i];
+        if (seg === undefined) return false;
+        if (seg.startsWith('{') && seg.endsWith('}')) continue;
+        if (seg !== c[i]) return false;
+    }
+    return true;
+}
+export function findRequiredAction(manifest, method, path) {
+    const m = method.toUpperCase();
+    for (const r of manifest){
+        if (r.method === m && pathMatchesTemplate(r.path, path)) return r.action;
+    }
+    return null;
+}
+function matchesGlob(path, patterns) {
+    if (!patterns?.length) return false;
+    for (const raw of patterns){
+        const p = raw.trim();
+        if (!p) continue;
+        if (p.endsWith('/*')) {
+            const prefix = p.slice(0, -2);
+            if (path === prefix || path.startsWith(`${prefix}/`)) return true;
+        } else if (p.endsWith('*')) {
+            if (path.startsWith(p.slice(0, -1))) return true;
+        } else if (path === p) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Pure authorization decision. `claims`/`roles` are ALREADY resolved by the caller
+ * (from the JWT in embed mode, or via the role-claims manifest in resolve mode), so
+ * this stays mode-agnostic and easy to test.
+ */ export function evaluateAccess(args) {
+    const { manifest, method, path, authenticated, roles, claims, onUnmapped, publicPaths, godminRole } = args;
+    if (matchesGlob(path, publicPaths)) return {
+        decision: 'allow',
+        reason: 'public',
+        action: null
+    };
+    const action = findRequiredAction(manifest, method, path);
+    if (action === null) {
+        return {
+            decision: onUnmapped,
+            reason: `unmapped:${onUnmapped}`,
+            action: null
+        };
+    }
+    if (!authenticated) return {
+        decision: 'deny',
+        reason: 'no-valid-token',
+        action
+    };
+    if (roles.includes(godminRole)) return {
+        decision: 'allow',
+        reason: 'godmin',
+        action
+    };
+    if (claimSatisfies(claims, action)) return {
+        decision: 'allow',
+        reason: 'claim',
+        action
+    };
+    return {
+        decision: 'deny',
+        reason: 'missing-claim',
+        action
+    };
+}
+/** Fetches + caches a service's route manifest from the IDP. */ export class ManifestCache {
+    get ttlMs() {
+        return (this.cfg.refreshSec ?? 300) * 1000;
+    }
+    async refresh() {
+        const url = `${this.cfg.url}${this.cfg.url.includes('?') ? '&' : '?'}service=${encodeURIComponent(this.cfg.serviceId)}`;
+        const headers = {};
+        if (this.cfg.token) headers['x-discovery-token'] = this.cfg.token;
+        const res = await this.fetchImpl(url, {
+            headers
+        });
+        if (!res.ok) throw new Error(`manifest fetch ${res.status}`);
+        const body = await res.json();
+        this.routes = body.data?.routes ?? [];
+        this.fetchedAtMs = Date.now();
+    }
+    async get() {
+        const stale = Date.now() - this.fetchedAtMs > this.ttlMs;
+        if (stale && !this.inflight) {
+            this.inflight = this.refresh().catch((err)=>{
+                this.logger?.warn?.(`[Proxy authz] manifest refresh failed for ${this.cfg.serviceId}: ${err instanceof Error ? err.message : String(err)}`);
+            }).finally(()=>{
+                this.inflight = null;
+            });
+        }
+        // First-ever load must block; later refreshes serve the last good copy.
+        if (this.fetchedAtMs === 0 && this.inflight) await this.inflight;
+        return this.routes;
+    }
+    constructor(cfg, fetchImpl = fetch, logger){
+        _define_property(this, "cfg", void 0);
+        _define_property(this, "fetchImpl", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "routes", void 0);
+        _define_property(this, "fetchedAtMs", void 0);
+        _define_property(this, "inflight", void 0);
+        this.cfg = cfg;
+        this.fetchImpl = fetchImpl;
+        this.logger = logger;
+        this.routes = [];
+        this.fetchedAtMs = 0;
+        this.inflight = null;
+    }
+}
+/** Fetches + caches the role→claim-actions map (resolve mode) from the IDP. */ export class RoleClaimsCache {
+    get ttlMs() {
+        return (this.cfg.refreshSec ?? 300) * 1000;
+    }
+    async refresh() {
+        const url = `${this.cfg.url}${this.cfg.url.includes('?') ? '&' : '?'}service=${encodeURIComponent(this.cfg.serviceId)}`;
+        const headers = {};
+        if (this.cfg.token) headers['x-discovery-token'] = this.cfg.token;
+        const res = await this.fetchImpl(url, {
+            headers
+        });
+        if (!res.ok) throw new Error(`role-claims manifest fetch ${res.status}`);
+        const body = await res.json();
+        this.map = body.data?.roleClaims ?? {};
+        this.fetchedAtMs = Date.now();
+    }
+    async get() {
+        const stale = Date.now() - this.fetchedAtMs > this.ttlMs;
+        if (stale && !this.inflight) {
+            this.inflight = this.refresh().catch((err)=>{
+                this.logger?.warn?.(`[Proxy authz] role-claims refresh failed for ${this.cfg.serviceId}: ${err instanceof Error ? err.message : String(err)}`);
+            }).finally(()=>{
+                this.inflight = null;
+            });
+        }
+        if (this.fetchedAtMs === 0 && this.inflight) await this.inflight;
+        return this.map;
+    }
+    constructor(cfg, fetchImpl = fetch, logger){
+        _define_property(this, "cfg", void 0);
+        _define_property(this, "fetchImpl", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "map", void 0);
+        _define_property(this, "fetchedAtMs", void 0);
+        _define_property(this, "inflight", void 0);
+        this.cfg = cfg;
+        this.fetchImpl = fetchImpl;
+        this.logger = logger;
+        this.map = {};
+        this.fetchedAtMs = 0;
+        this.inflight = null;
+    }
+}
+/** Resolve a user's roles to their claim actions using the role-claims map. */ export function resolveClaimsFromRoles(roles, roleClaims) {
+    const out = new Set();
+    for (const r of roles)for (const a of roleClaims[r] ?? [])out.add(a);
+    return [
+        ...out
+    ];
+}

package/dist/src/Client/Proxy/authz.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/Client/Proxy/authz.test.js

@@ -0,0 +1,235 @@
+import { createHmac } from 'node:crypto';
+import { describe, expect, it } from 'bun:test';
+import { claimSatisfies, evaluateAccess, findRequiredAction, resolveClaimsFromRoles, verifyJwtHS256 } from './authz';
+const b64 = (o)=>Buffer.from(JSON.stringify(o)).toString('base64url');
+function signHS256(payload, secret) {
+    const header = b64({
+        alg: 'HS256',
+        typ: 'JWT'
+    });
+    const body = b64(payload);
+    const sig = createHmac('sha256', secret).update(`${header}.${body}`).digest('base64url');
+    return `${header}.${body}.${sig}`;
+}
+const SECRET = 'test-secret';
+describe('verifyJwtHS256', ()=>{
+    it('verifies a correctly signed, unexpired token', ()=>{
+        const t = signHS256({
+            sub: 'u1',
+            claims: [
+                'agent.templates.read'
+            ]
+        }, SECRET);
+        expect(verifyJwtHS256(t, SECRET)?.sub).toBe('u1');
+    });
+    it('rejects a wrong secret', ()=>{
+        const t = signHS256({
+            sub: 'u1'
+        }, SECRET);
+        expect(verifyJwtHS256(t, 'other-secret')).toBeNull();
+    });
+    it('rejects a tampered payload (forged claims)', ()=>{
+        const t = signHS256({
+            sub: 'u1',
+            claims: []
+        }, SECRET);
+        const [h, , s] = t.split('.');
+        const forged = `${h}.${b64({
+            sub: 'u1',
+            claims: [
+                'agent.templates.delete'
+            ]
+        })}.${s}`;
+        expect(verifyJwtHS256(forged, SECRET)).toBeNull();
+    });
+    it('rejects an expired token', ()=>{
+        const t = signHS256({
+            sub: 'u1',
+            exp: Math.floor(Date.now() / 1000) - 60
+        }, SECRET);
+        expect(verifyJwtHS256(t, SECRET)).toBeNull();
+    });
+    it('rejects malformed input', ()=>{
+        expect(verifyJwtHS256('not.a.jwt.token', SECRET)).toBeNull();
+        expect(verifyJwtHS256('garbage', SECRET)).toBeNull();
+    });
+});
+describe('claimSatisfies (prefix)', ()=>{
+    it('exact + prefix grants', ()=>{
+        expect(claimSatisfies([
+            'agent.templates.read'
+        ], 'agent.templates.read')).toBe(true);
+        expect(claimSatisfies([
+            'agent.templates'
+        ], 'agent.templates.read')).toBe(true);
+        expect(claimSatisfies([
+            'agent'
+        ], 'agent.templates.read')).toBe(true);
+    });
+    it('does not over-grant across siblings', ()=>{
+        expect(claimSatisfies([
+            'agent.templates.read'
+        ], 'agent.templates.delete')).toBe(false);
+        expect(claimSatisfies([
+            'agent.templatesx'
+        ], 'agent.templates.read')).toBe(false);
+    });
+});
+const MANIFEST = [
+    {
+        action: 'agent.templates.list',
+        path: '/api/v1/templates',
+        method: 'GET'
+    },
+    {
+        action: 'agent.templates.delete',
+        path: '/api/v1/templates/{id}',
+        method: 'DELETE'
+    }
+];
+describe('findRequiredAction', ()=>{
+    it('resolves templated routes', ()=>{
+        expect(findRequiredAction(MANIFEST, 'GET', '/api/v1/templates')).toBe('agent.templates.list');
+        expect(findRequiredAction(MANIFEST, 'DELETE', '/api/v1/templates/9')).toBe('agent.templates.delete');
+        expect(findRequiredAction(MANIFEST, 'POST', '/api/v1/templates')).toBeNull();
+    });
+});
+describe('evaluateAccess', ()=>{
+    const base = {
+        manifest: MANIFEST,
+        onUnmapped: 'deny',
+        godminRole: 'godmin',
+        authenticated: true,
+        roles: [],
+        claims: []
+    };
+    it('allows a public path without a claim', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/health',
+            authenticated: false,
+            publicPaths: [
+                '/health'
+            ]
+        });
+        expect(d.decision).toBe('allow');
+    });
+    it('denies an unmapped path when onUnmapped=deny', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/unknown'
+        });
+        expect(d.decision).toBe('deny');
+    });
+    it('allows an unmapped path when onUnmapped=allow', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            onUnmapped: 'allow',
+            method: 'GET',
+            path: '/api/v1/unknown'
+        });
+        expect(d.decision).toBe('allow');
+    });
+    it('denies a mapped route with no valid token', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            authenticated: false
+        });
+        expect(d).toMatchObject({
+            decision: 'deny',
+            reason: 'no-valid-token'
+        });
+    });
+    it('allows godmin regardless of claims', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'DELETE',
+            path: '/api/v1/templates/1',
+            roles: [
+                'godmin'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'godmin'
+        });
+    });
+    it('allows when a claim satisfies the required action', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            claims: [
+                'agent.templates'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'claim'
+        });
+    });
+    it('denies when the caller lacks the required claim', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'DELETE',
+            path: '/api/v1/templates/1',
+            claims: [
+                'agent.templates.list'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'deny',
+            reason: 'missing-claim'
+        });
+    });
+});
+describe('resolveClaimsFromRoles (resolve mode)', ()=>{
+    const roleClaims = {
+        'agent-viewer': [
+            'agent.templates.list',
+            'agent.templates.get'
+        ],
+        'agent-admin': [
+            'agent'
+        ]
+    };
+    it('unions the claim actions of the caller-held roles', ()=>{
+        expect(resolveClaimsFromRoles([
+            'agent-viewer'
+        ], roleClaims).sort()).toEqual([
+            'agent.templates.get',
+            'agent.templates.list'
+        ]);
+    });
+    it('dedupes across roles and ignores unknown roles', ()=>{
+        expect(resolveClaimsFromRoles([
+            'agent-admin',
+            'nope'
+        ], roleClaims)).toEqual([
+            'agent'
+        ]);
+        // resolved claims then feed evaluateAccess: 'agent' prefix grants any agent.* action
+        const d = evaluateAccess({
+            manifest: MANIFEST,
+            method: 'DELETE',
+            path: '/api/v1/templates/1',
+            authenticated: true,
+            roles: [
+                'agent-admin'
+            ],
+            claims: resolveClaimsFromRoles([
+                'agent-admin'
+            ], roleClaims),
+            onUnmapped: 'deny',
+            godminRole: 'godmin'
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'claim'
+        });
+    });
+});

package/dist/src/Client/Proxy/httpProxy.js

@@ -1,3 +1,4 @@
+import { evaluateAccess, ManifestCache, resolveClaimsFromRoles, RoleClaimsCache, verifyJwtHS256 } from './authz';
 import { createProxyLogger, matchPath, parseCookies, rewritePath } from './utils';
 const pendingRefreshes = new Map();
 function extractAccessTokenFromSetCookie(setCookieHeaders, accessCookieName) {
@@ -132,6 +133,79 @@ function extractSubFromJwt(token) {
 }
 export function createHttpProxyHandler(config) {
     const logger = createProxyLogger('HTTP Proxy', config.debug ?? false);
+    // One manifest cache per authorize-enabled service (shared across requests).
+    const manifestCaches = new Map();
+    const roleClaimsCaches = new Map();
+    for (const t of config.targets){
+        if (t.authorize) {
+            manifestCaches.set(t.authorize.serviceId, new ManifestCache({
+                ...t.authorize.manifest,
+                serviceId: t.authorize.serviceId
+            }, fetch, logger));
+            if (t.authorize.claimsMode === 'resolve' && t.authorize.manifest.roleClaimsUrl) {
+                roleClaimsCaches.set(t.authorize.serviceId, new RoleClaimsCache({
+                    url: t.authorize.manifest.roleClaimsUrl,
+                    token: t.authorize.manifest.token,
+                    refreshSec: t.authorize.manifest.refreshSec,
+                    serviceId: t.authorize.serviceId
+                }, fetch, logger));
+            }
+        }
+    }
+    /**
+   * Claim-gate a request for a target. Returns a 403 Response to block (enforce
+   * mode), or null to allow (also null in audit mode, where a would-block is logged).
+   */ async function checkAuthorize(req, target, path) {
+        const az = target.authorize;
+        if (!az) return null;
+        const cache = manifestCaches.get(az.serviceId);
+        if (!cache) return null;
+        const manifest = await cache.get();
+        const upstreamPath = target.pathRewrite ? rewritePath(path, target.pathRewrite) : path;
+        const cookies = parseCookies(req.headers.get('cookie'));
+        const bearer = az.jwt.headerName ? (req.headers.get(az.jwt.headerName) ?? '').replace(/^Bearer\s+/i, '') : '';
+        const tokenStr = cookies[az.jwt.cookieName ?? 'access_token'] || bearer || '';
+        const payload = tokenStr ? verifyJwtHS256(tokenStr, az.jwt.secret) : null;
+        const roles = Array.isArray(payload?.roles) ? payload.roles : [];
+        // embed: claims live in the JWT. resolve: the JWT carries only roles; resolve
+        // them to claims via the role-claims manifest (matches IDP jwtClaimsMode).
+        let claims;
+        if (az.claimsMode === 'resolve') {
+            const roleClaimsCache = roleClaimsCaches.get(az.serviceId);
+            const roleClaims = roleClaimsCache ? await roleClaimsCache.get() : {};
+            claims = resolveClaimsFromRoles(roles, roleClaims);
+        } else {
+            claims = Array.isArray(payload?.claims) ? payload.claims : [];
+        }
+        const decision = evaluateAccess({
+            manifest,
+            method: req.method,
+            path: upstreamPath,
+            authenticated: payload !== null,
+            roles,
+            claims,
+            onUnmapped: az.onUnmapped ?? 'deny',
+            publicPaths: az.publicPaths,
+            godminRole: az.godminRole ?? 'godmin'
+        });
+        if (decision.decision === 'allow') return null;
+        const detail = `${req.method} ${path} (${decision.reason}${decision.action ? ` need ${decision.action}` : ''})`;
+        if ((az.mode ?? 'enforce') === 'audit') {
+            logger.warn(`[authz audit] WOULD block ${detail}`);
+            return null;
+        }
+        logger.warn(`[authz] 403 ${detail}`);
+        return new Response(JSON.stringify({
+            success: false,
+            message: 'Forbidden',
+            reason: decision.reason
+        }), {
+            status: 403,
+            headers: {
+                'content-type': 'application/json'
+            }
+        });
+    }
     function findTarget(path) {
         for (const target of config.targets){
             if (matchPath(path, target.paths)) {
@@ -178,18 +252,24 @@ export function createHttpProxyHandler(config) {
         } else {
             headers.delete('host');
         }
-        // Inject real client IP as x-forwarded-for / x-real-ip if not already present
+        // SECURITY: this proxy is the trust boundary for the client IP. A previous
+        // version APPENDED the socket IP to an existing X-Forwarded-For, so a client
+        // could send `X-Forwarded-For: <trusted-ip>` and the chain became
+        // `<trusted-ip>, <real>` — downstream allow-lists that read the LEADING entry
+        // (e.g. tenant allowedIps) then trusted the spoofed value. OVERWRITE, never
+        // append, and strip every client-supplied alternative IP header.
+        for (const h of [
+            'cf-connecting-ip',
+            'true-client-ip',
+            'x-client-ip'
+        ])headers.delete(h);
         if (clientIp) {
-            const existingXff = headers.get('x-forwarded-for');
-            if (existingXff) {
-                // Append proxy client IP to existing chain
-                headers.set('x-forwarded-for', `${existingXff}, ${clientIp}`);
-            } else {
-                headers.set('x-forwarded-for', clientIp);
-            }
-            if (!headers.has('x-real-ip')) {
-                headers.set('x-real-ip', clientIp);
-            }
+            headers.set('x-forwarded-for', clientIp);
+            headers.set('x-real-ip', clientIp);
+        } else {
+            // Couldn't resolve the socket IP — do not forward a client-controlled value.
+            headers.delete('x-forwarded-for');
+            headers.delete('x-real-ip');
         }
         if (target.headers) {
             for (const [key, value] of Object.entries(target.headers)){
@@ -237,6 +317,11 @@ export function createHttpProxyHandler(config) {
             if (!target) {
                 return null;
             }
+            // Claim-gate BEFORE forwarding: a denied request never reaches the upstream.
+            if (target.authorize) {
+                const blocked = await checkAuthorize(req, target, path);
+                if (blocked) return blocked;
+            }
             const startTime = performance.now();
             const backendUrl = buildBackendUrl(path, target);
             const finalUrl = url.search ? `${backendUrl}${url.search}` : backendUrl;