nucleus-core-ts 0.9.706 → 0.9.708

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

@@ -21,12 +21,18 @@ export interface AccessDecision {
     reason: string;
     action: string | null;
 }
-/** Pure authorization decision (mode-independent). */
+/**
+ * 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;
-    payload: Record<string, unknown> | null;
+    authenticated: boolean;
+    roles: string[];
+    claims: string[];
     onUnmapped: 'allow' | 'deny';
     publicPaths?: string[];
     godminRole: string;
@@ -46,3 +52,23 @@ export declare class ManifestCache {
     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

@@ -66,8 +66,12 @@ function matchesGlob(path, patterns) {
     }
     return false;
 }
-/** Pure authorization decision (mode-independent). */ export function evaluateAccess(args) {
-    const { manifest, method, path, payload, onUnmapped, publicPaths, godminRole } = args;
+/**
+ * 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',
@@ -81,18 +85,16 @@ function matchesGlob(path, patterns) {
             action: null
         };
     }
-    if (!payload) return {
+    if (!authenticated) return {
         decision: 'deny',
         reason: 'no-valid-token',
         action
     };
-    const roles = Array.isArray(payload.roles) ? payload.roles : [];
     if (roles.includes(godminRole)) return {
         decision: 'allow',
         reason: 'godmin',
         action
     };
-    const claims = Array.isArray(payload.claims) ? payload.claims : [];
     if (claimSatisfies(claims, action)) return {
         decision: 'allow',
         reason: 'claim',
@@ -148,3 +150,53 @@ function matchesGlob(path, patterns) {
         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.js

@@ -1,6 +1,6 @@
 import { createHmac } from 'node:crypto';
 import { describe, expect, it } from 'bun:test';
-import { claimSatisfies, evaluateAccess, findRequiredAction, verifyJwtHS256 } from './authz';
+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({
@@ -98,18 +98,17 @@ describe('evaluateAccess', ()=>{
     const base = {
         manifest: MANIFEST,
         onUnmapped: 'deny',
-        godminRole: 'godmin'
+        godminRole: 'godmin',
+        authenticated: true,
+        roles: [],
+        claims: []
     };
-    const payload = (claims, roles = [])=>({
-            claims,
-            roles
-        });
     it('allows a public path without a claim', ()=>{
         const d = evaluateAccess({
             ...base,
             method: 'GET',
             path: '/health',
-            payload: null,
+            authenticated: false,
             publicPaths: [
                 '/health'
             ]
@@ -120,8 +119,7 @@ describe('evaluateAccess', ()=>{
         const d = evaluateAccess({
             ...base,
             method: 'GET',
-            path: '/api/v1/unknown',
-            payload: payload([])
+            path: '/api/v1/unknown'
         });
         expect(d.decision).toBe('deny');
     });
@@ -130,8 +128,7 @@ describe('evaluateAccess', ()=>{
             ...base,
             onUnmapped: 'allow',
             method: 'GET',
-            path: '/api/v1/unknown',
-            payload: payload([])
+            path: '/api/v1/unknown'
         });
         expect(d.decision).toBe('allow');
     });
@@ -140,7 +137,7 @@ describe('evaluateAccess', ()=>{
             ...base,
             method: 'GET',
             path: '/api/v1/templates',
-            payload: null
+            authenticated: false
         });
         expect(d).toMatchObject({
             decision: 'deny',
@@ -152,9 +149,9 @@ describe('evaluateAccess', ()=>{
             ...base,
             method: 'DELETE',
             path: '/api/v1/templates/1',
-            payload: payload([], [
+            roles: [
                 'godmin'
-            ])
+            ]
         });
         expect(d).toMatchObject({
             decision: 'allow',
@@ -166,9 +163,9 @@ describe('evaluateAccess', ()=>{
             ...base,
             method: 'GET',
             path: '/api/v1/templates',
-            payload: payload([
+            claims: [
                 'agent.templates'
-            ])
+            ]
         });
         expect(d).toMatchObject({
             decision: 'allow',
@@ -180,9 +177,9 @@ describe('evaluateAccess', ()=>{
             ...base,
             method: 'DELETE',
             path: '/api/v1/templates/1',
-            payload: payload([
+            claims: [
                 'agent.templates.list'
-            ])
+            ]
         });
         expect(d).toMatchObject({
             decision: 'deny',
@@ -190,3 +187,49 @@ describe('evaluateAccess', ()=>{
         });
     });
 });
+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,4 +1,4 @@
-import { evaluateAccess, ManifestCache, verifyJwtHS256 } from './authz';
+import { evaluateAccess, ManifestCache, resolveClaimsFromRoles, RoleClaimsCache, verifyJwtHS256 } from './authz';
 import { createProxyLogger, matchPath, parseCookies, rewritePath } from './utils';
 const pendingRefreshes = new Map();
 function extractAccessTokenFromSetCookie(setCookieHeaders, accessCookieName) {
@@ -135,12 +135,21 @@ 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));
+            }
         }
     }
     /**
@@ -157,11 +166,24 @@ export function createHttpProxyHandler(config) {
         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,
-            payload,
+            authenticated: payload !== null,
+            roles,
+            claims,
             onUnmapped: az.onUnmapped ?? 'deny',
             publicPaths: az.publicPaths,
             godminRole: az.godminRole ?? 'godmin'

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

@@ -46,7 +46,13 @@ export interface ManifestRoute {
 export interface ProxyAuthorizeConfig {
     serviceId: string;
     manifest: {
+        /** Route→action manifest URL (GET /authorization/route-manifest). */
         url: string;
+        /**
+         * Role→claim-actions manifest URL (GET /authorization/role-claims-manifest),
+         * REQUIRED when claimsMode is 'resolve' (JWT carries roles, not claims).
+         */
+        roleClaimsUrl?: string;
         token?: string;
         refreshSec?: number;
     };
@@ -55,6 +61,12 @@ export interface ProxyAuthorizeConfig {
         cookieName?: string;
         headerName?: string;
     };
+    /**
+     * How the caller's claims are obtained. 'embed' (default): read from the JWT's
+     * `claims`. 'resolve': the JWT carries only `roles`; resolve them to claims via
+     * the role-claims manifest (matches the IDP's jwtClaimsMode: 'resolve').
+     */
+    claimsMode?: 'embed' | 'resolve';
     mode?: 'audit' | 'enforce';
     onUnmapped?: 'allow' | 'deny';
     publicPaths?: string[];

package/dist/src/Services/Authorization/EndpointDiscovery/seed.d.ts

@@ -50,4 +50,11 @@ export declare function getRouteManifest(db: NodePgDatabase, claimsTable: PgTabl
     path: string;
     method: string;
 }>>;
+/**
+ * Build the role→claim-actions manifest a reverse proxy consumes in RESOLVE mode
+ * (where the JWT carries roles but not claims). Returns each role's claim actions
+ * scoped to a service (`{serviceId}.` prefix, plus the bare `{serviceId}` grant),
+ * so the proxy can resolve a user's roles → claim set locally. Active rows only.
+ */
+export declare function getRoleClaimsManifest(db: NodePgDatabase, schemaTables: Record<string, unknown>, serviceId: string): Promise<Record<string, string[]>>;
 export {};

package/dist/src/Services/Authorization/EndpointDiscovery/seed.test.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.706",
+	"version": "0.9.708",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",