nucleus-core-ts 0.9.712 → 0.9.714

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

@@ -36,6 +36,14 @@ export declare function evaluateAccess(args: {
     onUnmapped: 'allow' | 'deny';
     publicPaths?: string[];
     godminRole: string;
+    /**
+     * Claim actions the caller has determined are currently suppressed for this user by an
+     * exceeded quota (see resolveSuppressedClaims). They are subtracted from the user's claims
+     * before the gate check; if the request would have passed on a claim that is suppressed,
+     * the decision is `deny` with reason `quota_exceeded` so a caller can enforce the usage cap
+     * even while the general claim-gate runs in audit mode. Absent/empty ⇒ classic behaviour.
+     */
+    suppressedClaims?: string[];
 }): AccessDecision;
 /** Fetches + caches a service's route manifest from the IDP. */
 export declare class ManifestCache {

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

@@ -71,7 +71,7 @@ function matchesGlob(path, patterns) {
  * (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;
+    const { manifest, method, path, authenticated, roles, claims, onUnmapped, publicPaths, godminRole, suppressedClaims } = args;
     if (matchesGlob(path, publicPaths)) return {
         decision: 'allow',
         reason: 'public',
@@ -95,11 +95,22 @@ function matchesGlob(path, patterns) {
         reason: 'godmin',
         action
     };
-    if (claimSatisfies(claims, action)) return {
+    const suppressed = suppressedClaims && suppressedClaims.length ? new Set(suppressedClaims) : null;
+    const effectiveClaims = suppressed ? claims.filter((c)=>!suppressed.has(c)) : claims;
+    if (claimSatisfies(effectiveClaims, action)) return {
         decision: 'allow',
         reason: 'claim',
         action
     };
+    // Denied. If the user actually holds a claim that grants this action but a quota suppressed
+    // it, surface that distinctly — this is a usage cap, not a missing grant.
+    if (suppressed && claimSatisfies(claims, action)) {
+        return {
+            decision: 'deny',
+            reason: 'quota_exceeded',
+            action
+        };
+    }
     return {
         decision: 'deny',
         reason: 'missing-claim',

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

@@ -186,6 +186,95 @@ describe('evaluateAccess', ()=>{
             reason: 'missing-claim'
         });
     });
+    it('denies with reason quota_exceeded when a held claim is suppressed by a quota', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            claims: [
+                'agent.templates.list'
+            ],
+            suppressedClaims: [
+                'agent.templates.list'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'deny',
+            reason: 'quota_exceeded'
+        });
+    });
+    it('still allows when a NON-suppressed claim also satisfies the action', ()=>{
+        // broad claim grants the action and is not in the suppressed set → allowed
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            claims: [
+                'agent.templates.list',
+                'agent'
+            ],
+            suppressedClaims: [
+                'agent.templates.list'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'claim'
+        });
+    });
+    it('suppression never elevates godmin denial (godmin bypasses by role)', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            roles: [
+                'godmin'
+            ],
+            claims: [
+                'agent.templates.list'
+            ],
+            suppressedClaims: [
+                'agent.templates.list'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'godmin'
+        });
+    });
+    it('a missing claim stays missing-claim (not quota_exceeded) under suppression', ()=>{
+        // the user never held the claim; an unrelated suppression must not relabel it
+        const d = evaluateAccess({
+            ...base,
+            method: 'DELETE',
+            path: '/api/v1/templates/1',
+            claims: [
+                'agent.templates.list'
+            ],
+            suppressedClaims: [
+                'something.else'
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'deny',
+            reason: 'missing-claim'
+        });
+    });
+    it('empty suppressedClaims is identical to classic behaviour', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            claims: [
+                'agent.templates.list'
+            ],
+            suppressedClaims: []
+        });
+        expect(d).toMatchObject({
+            decision: 'allow',
+            reason: 'claim'
+        });
+    });
 });
 describe('resolveClaimsFromRoles (resolve mode)', ()=>{
     const roleClaims = {

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

@@ -1,5 +1,26 @@
 import { evaluateAccess, ManifestCache, RoleClaimsCache, resolveClaimsFromRoles, verifyJwtHS256 } from './authz';
 import { createProxyLogger, matchPath, parseCookies, rewritePath } from './utils';
+/**
+ * Ask the IDP which claim actions are currently suppressed for the caller (an exceeded
+ * quota that gates them). Uses the caller's OWN cookies — no service secret. Fail-open: any
+ * error yields an empty set, so a transient IDP blip never blocks traffic (the cap is
+ * re-checked on the next request).
+ */ async function fetchSuppressedClaims(url, cookieHeader, logger) {
+    if (!cookieHeader) return [];
+    try {
+        const res = await fetch(url, {
+            headers: {
+                cookie: cookieHeader
+            }
+        });
+        if (!res.ok) return [];
+        const body = await res.json();
+        return Array.isArray(body?.data?.suppressedClaims) ? body.data.suppressedClaims : [];
+    } catch (err) {
+        logger.warn(`[authz] suppressed-claims fetch failed (fail-open): ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
 const pendingRefreshes = new Map();
 function extractAccessTokenFromSetCookie(setCookieHeaders, accessCookieName) {
     for (const header of setCookieHeaders){
@@ -177,6 +198,12 @@ export function createHttpProxyHandler(config) {
         } else {
             claims = Array.isArray(payload?.claims) ? payload.claims : [];
         }
+        // Generic quota enforcement (opt-in): subtract the caller's quota-suppressed claims.
+        // Skipped for godmin (bypasses by role) and anonymous callers (nothing to suppress).
+        let suppressedClaims;
+        if (az.quotaSuppression?.url && payload !== null && !roles.includes(az.godminRole ?? 'godmin')) {
+            suppressedClaims = await fetchSuppressedClaims(az.quotaSuppression.url, req.headers.get('cookie'), logger);
+        }
         const decision = evaluateAccess({
             manifest,
             method: req.method,
@@ -186,14 +213,34 @@ export function createHttpProxyHandler(config) {
             claims,
             onUnmapped: az.onUnmapped ?? 'deny',
             publicPaths: az.publicPaths,
-            godminRole: az.godminRole ?? 'godmin'
+            godminRole: az.godminRole ?? 'godmin',
+            suppressedClaims
         });
         if (decision.decision === 'allow') return null;
         const detail = `${req.method} ${path} (${decision.reason}${decision.action ? ` need ${decision.action}` : ''})`;
-        if ((az.mode ?? 'enforce') === 'audit') {
+        // A quota breach is a HARD usage cap: enforce it even while the general gate is auditing.
+        // Every other would-block (missing-claim, unmapped) still only logs in audit mode.
+        const isQuota = decision.reason === 'quota_exceeded';
+        if ((az.mode ?? 'enforce') === 'audit' && !isQuota) {
             logger.warn(`[authz audit] WOULD block ${detail}`);
             return null;
         }
+        if (isQuota) {
+            logger.warn(`[authz] 429 quota ${detail}`);
+            return new Response(JSON.stringify({
+                success: false,
+                error: 'quota_exceeded',
+                reason: 'quota_exceeded',
+                message: 'Quota exceeded',
+                action: decision.action
+            }), {
+                status: 429,
+                headers: {
+                    'content-type': 'application/json',
+                    'retry-after': '3600'
+                }
+            });
+        }
         logger.warn(`[authz] 403 ${detail}`);
         return new Response(JSON.stringify({
             success: false,

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

@@ -81,6 +81,21 @@ export interface ProxyAuthorizeConfig {
     onUnmapped?: 'allow' | 'deny';
     publicPaths?: string[];
     godminRole?: string;
+    /**
+     * OPTIONAL generic quota enforcement. When set, before deciding the proxy asks the IDP
+     * which claim actions are currently SUPPRESSED for the caller by an exceeded quota (GETs
+     * this URL with the caller's own cookies) and subtracts them from the caller's claims. A
+     * request that would have passed on a now-suppressed claim is denied `quota_exceeded` —
+     * and that specific denial is enforced EVEN IN `audit` mode, because a usage cap is a hard
+     * limit (all other would-blocks still just log while auditing). Fail-open on any fetch
+     * error so a transient IDP blip never breaks traffic. Nothing here names an endpoint or a
+     * metric: what a quota disables is pure data (the quota's `gates`), so the same wiring
+     * serves any project.
+     */
+    quotaSuppression?: {
+        /** GET endpoint returning `{ data: { suppressedClaims: string[] } }` for the caller. */
+        url: string;
+    };
 }
 export interface HttpProxyTarget {
     url: string;

package/dist/src/Services/Authorization/Quota/index.d.ts

@@ -1,4 +1,5 @@
 export { aggregateLimit, evaluateQuota, parseQuotaPolicy } from './evaluate';
 export { type ResolvedQuota, resolveUserQuotas } from './resolve';
+export { resolveSuppressedClaims } from './suppress';
 export type { CounterReader, QuotaAggregate, QuotaContext, QuotaEvaluation, QuotaOp, QuotaPolicy, QuotaWindow, } from './types';
 export { bucketDatesForWindow, buildIncrementKeys, buildQuotaKeys } from './windows';

package/dist/src/Services/Authorization/Quota/suppress.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedQuota } from './resolve';
+import type { CounterReader, QuotaContext } from './types';
+/**
+ * The set of claim actions a user has LOST right now because a quota that gates them is
+ * exceeded. This is the one generic hinge of quota enforcement: for every resolved quota
+ * that carries `gates`, read its live counter (reader injected — stays pure/testable) and,
+ * if it is over the limit, add its gated claim actions to the suppressed set. Callers then
+ * subtract this set from the user's effective claims, so the ordinary claim-gate denies the
+ * gated capabilities. nucleus never learns what is being metered or which endpoint is hit —
+ * a quota decides what it disables purely by the claim actions listed in its policy.
+ *
+ * Metering-only quotas (no `gates`) never suppress anything; they exist just to be reported.
+ * Returns a de-duplicated list (order not significant).
+ */
+export declare function resolveSuppressedClaims(quotas: readonly ResolvedQuota[], read: CounterReader, ctx: QuotaContext): Promise<string[]>;

package/dist/src/Services/Authorization/Quota/suppress.test.d.ts

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

package/dist/src/Services/Authorization/Quota/types.d.ts

@@ -37,6 +37,15 @@ export interface QuotaPolicy {
     aggregate?: QuotaAggregate;
     /** Optional display unit, e.g. 'tokens' | 'usd'. */
     unit?: string;
+    /**
+     * Claim actions this quota SUPPRESSES while it is exceeded. When a user is over this
+     * quota, these claim actions are removed from their effective claim set for the rest of
+     * the window, so any capability guarded by them is denied through the normal claim-gate.
+     * This is what makes enforcement generic: nucleus never names an endpoint or a metric —
+     * a project decides what a quota gates purely by listing claim actions here (data, not
+     * code). Absent/empty = a metering-only quota (reported for status, gates nothing).
+     */
+    gates?: string[];
 }
 export interface QuotaContext {
     userId: string;

package/dist/src/Services/Authorization/SeedRunner/expandClaimPatterns.test.d.ts

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

package/dist/src/Services/Authorization/SeedRunner/index.d.ts

@@ -1,5 +1,12 @@
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type { Logger } from '../../Logger';
+/**
+ * Expand claim-assignment patterns into concrete claim actions. A trailing `.*` is a PREFIX
+ * grant: it matches the prefix itself plus every action beneath it (`llm.conversations.*` →
+ * `llm.conversations.create…`, `…list…`, …). Everything else is taken literally. De-duplicated.
+ * Pure so it is unit-testable; the caller supplies the known claim actions.
+ */
+export declare function expandClaimPatterns(patterns: string[], allActions: readonly string[]): string[];
 type SeedConfig = {
     roles?: Array<{
         name: string;

package/package.json

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