nucleus-core-ts 0.9.716 → 0.9.718

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

@@ -20,6 +20,9 @@ export interface AccessDecision {
     decision: 'allow' | 'deny';
     reason: string;
     action: string | null;
+    /** When a ClaimGuard caused the denial, the guard's action (e.g. `token_spent_today`) so the
+     *  client can render a human-readable message. */
+    guard?: string;
 }
 /**
  * Pure authorization decision. `claims`/`roles` are ALREADY resolved by the caller
@@ -37,13 +40,20 @@ export declare function evaluateAccess(args: {
     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.
+     * Claim actions currently invalidated for this user by a ClaimGuard whose condition holds
+     * (see resolveClaimGuards). They are subtracted from the user's claims before the gate check;
+     * if the request would have passed on a claim that is invalidated, the decision is `deny`
+     * with reason `claim_guard`, naming the firing guard. Absent/empty ⇒ classic behaviour.
      */
     suppressedClaims?: string[];
+    /**
+     * Guards that fired for this user (from /suppressed-claims), used to NAME the guard in a
+     * denial. Each guard's `invalidates` are the claim actions it removed.
+     */
+    firedGuards?: ReadonlyArray<{
+        action: string;
+        invalidates: 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, suppressedClaims } = args;
+    const { manifest, method, path, authenticated, roles, claims, onUnmapped, publicPaths, godminRole, suppressedClaims, firedGuards } = args;
     if (matchesGlob(path, publicPaths)) return {
         decision: 'allow',
         reason: 'public',
@@ -102,13 +102,16 @@ function matchesGlob(path, patterns) {
         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.
+    // Denied. If the user actually holds a claim that grants this action but a ClaimGuard
+    // invalidated it, surface that distinctly (a live condition, not a missing grant) and name
+    // the firing guard so the client can render a human-readable message.
     if (suppressed && claimSatisfies(claims, action)) {
+        const guard = firedGuards?.find((g)=>g.invalidates.some((iv)=>iv === action || action.startsWith(`${iv}.`)))?.action;
         return {
             decision: 'deny',
-            reason: 'quota_exceeded',
-            action
+            reason: 'claim_guard',
+            action,
+            guard
         };
     }
     return {

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

@@ -186,7 +186,33 @@ describe('evaluateAccess', ()=>{
             reason: 'missing-claim'
         });
     });
-    it('denies with reason quota_exceeded when a held claim is suppressed by a quota', ()=>{
+    it('denies with reason claim_guard, naming the firing guard, when a held claim is invalidated', ()=>{
+        const d = evaluateAccess({
+            ...base,
+            method: 'GET',
+            path: '/api/v1/templates',
+            claims: [
+                'agent.templates.list'
+            ],
+            suppressedClaims: [
+                'agent.templates.list'
+            ],
+            firedGuards: [
+                {
+                    action: 'token_spent_today',
+                    invalidates: [
+                        'agent.templates.list'
+                    ]
+                }
+            ]
+        });
+        expect(d).toMatchObject({
+            decision: 'deny',
+            reason: 'claim_guard',
+            guard: 'token_spent_today'
+        });
+    });
+    it('claim_guard denial still works (guard undefined) when firedGuards is not supplied', ()=>{
         const d = evaluateAccess({
             ...base,
             method: 'GET',
@@ -200,8 +226,9 @@ describe('evaluateAccess', ()=>{
         });
         expect(d).toMatchObject({
             decision: 'deny',
-            reason: 'quota_exceeded'
+            reason: 'claim_guard'
         });
+        expect(d.guard).toBeUndefined();
     });
     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

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

@@ -1,24 +1,29 @@
 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 [];
+async function fetchSuppressedClaims(url, cookieHeader, logger) {
+    const empty = {
+        suppressedClaims: [],
+        firedGuards: []
+    };
+    if (!cookieHeader) return empty;
     try {
         const res = await fetch(url, {
             headers: {
                 cookie: cookieHeader
             }
         });
-        if (!res.ok) return [];
+        if (!res.ok) return empty;
         const body = await res.json();
-        return Array.isArray(body?.data?.suppressedClaims) ? body.data.suppressedClaims : [];
+        return {
+            suppressedClaims: Array.isArray(body?.data?.suppressedClaims) ? body.data.suppressedClaims : [],
+            firedGuards: Array.isArray(body?.data?.firedGuards) ? body.data.firedGuards.map((g)=>({
+                    action: String(g?.action ?? ''),
+                    invalidates: Array.isArray(g?.invalidates) ? g.invalidates : []
+                })) : []
+        };
     } catch (err) {
         logger.warn(`[authz] suppressed-claims fetch failed (fail-open): ${err instanceof Error ? err.message : String(err)}`);
-        return [];
+        return empty;
     }
 }
 const pendingRefreshes = new Map();
@@ -198,11 +203,11 @@ 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;
+        // Generic ClaimGuard enforcement (opt-in): subtract the caller's guard-invalidated claims.
+        // Skipped for godmin (bypasses by role) and anonymous callers (nothing to invalidate).
+        let suppression;
         if (az.quotaSuppression?.url && payload !== null && !roles.includes(az.godminRole ?? 'godmin')) {
-            suppressedClaims = await fetchSuppressedClaims(az.quotaSuppression.url, req.headers.get('cookie'), logger);
+            suppression = await fetchSuppressedClaims(az.quotaSuppression.url, req.headers.get('cookie'), logger);
         }
         const decision = evaluateAccess({
             manifest,
@@ -214,24 +219,27 @@ export function createHttpProxyHandler(config) {
             onUnmapped: az.onUnmapped ?? 'deny',
             publicPaths: az.publicPaths,
             godminRole: az.godminRole ?? 'godmin',
-            suppressedClaims
+            suppressedClaims: suppression?.suppressedClaims,
+            firedGuards: suppression?.firedGuards
         });
         if (decision.decision === 'allow') return null;
-        const detail = `${req.method} ${path} (${decision.reason}${decision.action ? ` need ${decision.action}` : ''})`;
-        // 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) {
+        const detail = `${req.method} ${path} (${decision.reason}${decision.guard ? ` guard=${decision.guard}` : ''}${decision.action ? ` need ${decision.action}` : ''})`;
+        // A ClaimGuard block is a HARD, live condition: enforce it even while the general gate is
+        // auditing. Every other would-block (missing-claim, unmapped) still only logs in audit mode.
+        const isGuard = decision.reason === 'claim_guard';
+        if ((az.mode ?? 'enforce') === 'audit' && !isGuard) {
             logger.warn(`[authz audit] WOULD block ${detail}`);
             return null;
         }
-        if (isQuota) {
-            logger.warn(`[authz] 429 quota ${detail}`);
+        if (isGuard) {
+            logger.warn(`[authz] 429 claim_guard ${detail}`);
             return new Response(JSON.stringify({
                 success: false,
-                error: 'quota_exceeded',
-                reason: 'quota_exceeded',
-                message: 'Quota exceeded',
+                error: 'claim_guard',
+                reason: 'claim_guard',
+                // Name the firing guard so the client can render a human-readable message.
+                guard: decision.guard ?? null,
+                message: decision.guard ? `Blocked by guard: ${decision.guard}` : 'Blocked by a usage guard',
                 action: decision.action
             }), {
                 status: 429,

package/dist/src/ElysiaPlugin/routes/authorization/index.d.ts

@@ -11,36 +11,11 @@ export interface AuthorizationRoutesConfig {
         token?: string;
     };
     /**
-     * Reads integer usage counters (missing → 0) for the quota endpoint. Wired to
-     * RedisManager.readCounters when Redis is configured; when absent, `/authorization/quotas`
-     * still returns effective LIMITS but omits live usage.
+     * Reads one raw value from the shared state store (the app writes ClaimGuard keys there).
+     * Wired to RedisManager.read (Dapr state) when configured; when absent, guards can't be
+     * evaluated so NOTHING is suppressed (fail-open, never over-block).
      */
-    readCounters?: (keys: string[]) => Promise<number[]>;
-    /**
-     * Increments usage counters for the quota `/consume` (metering) endpoint. Wired to
-     * RedisManager.incrementCounter; when absent, `/consume` returns 503. Each item carries an
-     * optional TTL (rolling daily buckets self-expire; the `total` counter is permanent).
-     */
-    incrementCounters?: (items: Array<{
-        key: string;
-        delta: number;
-        ttlSeconds?: number;
-    }>) => Promise<Array<{
-        key: string;
-        value: number;
-    }>>;
-    /**
-     * Prefix for canonical (metric-keyed) usage counters written by `/consume` and read by a
-     * quota that omits `keyTemplate`. Default `'quota'`. Must match the spender's prefix so
-     * metering keys and read keys agree across the deployment.
-     */
-    canonicalPrefix?: string;
-    /**
-     * Optional allowlist of metric names `/consume` will record. When set, any metric NOT in
-     * the list is ignored (bounds Redis key cardinality against arbitrary metric names).
-     * Undefined = meter every metric present in the usage payload (default, fully generic).
-     */
-    allowedMetrics?: string[];
+    readState?: (key: string) => Promise<unknown>;
 }
 /**
  * Endpoint-discovery admin + manifest routes.

package/dist/src/ElysiaPlugin/routes/shared/adminGuard.d.ts

@@ -20,6 +20,22 @@ export interface AdminGuardDeps {
  * fallback) — e.g. the payment plugin.
  */
 export declare function hasGodminRole(request: Request): boolean;
+/**
+ * Authoritative godmin check via the DB `user_roles`→`roles` join.
+ *
+ * Unlike the header-only {@link hasGodminRole}, this does not depend on the
+ * `x-user-roles` header being fresh. The header is populated from the JWT
+ * `roles` claim, which can lag the DB after a token refresh — a header-only
+ * gate would then lock a REAL godmin out of RBAC management (assigning,
+ * patching, or removing role_claims) with a spurious 403, even though the DB
+ * still records the godmin role. Use as a fallback when the header check fails.
+ *
+ * Best-effort: returns false (never throws) when the DB/tables are missing or
+ * the query fails, so it can only ever GRANT access to a genuine godmin — never
+ * deny a real request on infrastructure hiccups beyond the header path already
+ * having failed.
+ */
+export declare function userHasGodminRoleInDb(db: NodePgDatabase | null | undefined, schemaTables: Record<string, unknown>, userId: string | null | undefined, logger: Logger): Promise<boolean>;
 /**
  * Returns true when the request is made by a godmin user.
  *

package/dist/src/Services/Authorization/ClaimGuard/evaluate.d.ts

@@ -0,0 +1,36 @@
+import { type ClaimGuardCatalogEntry, type GuardCondition, type GuardPolicy, type GuardValueType } from './types';
+/** The claim action a catalog entry seeds: the `name` up to the first `{`, trailing `:` stripped. */
+export declare function guardActionFromName(name: string): string;
+/**
+ * Parse one config `claimGuards` entry into the claim action + the `policy` jsonb to store on the
+ * seeded claim. Returns null for a malformed entry (missing name or unknown value type).
+ */
+export declare function parseGuardCatalogEntry(entry: unknown): {
+    action: string;
+    policy: GuardPolicy;
+} | null;
+/** Parse a claim's `policy` jsonb into a GuardPolicy, or null if it isn't a guard. */
+export declare function parseGuardPolicy(raw: unknown): GuardPolicy | null;
+/** Substitute `{userId}` / `{tenant}` in a key template. Tenant defaults to `default`. */
+export declare function resolveGuardKey(keyTemplate: string, ctx: {
+    userId: string;
+    tenant?: string;
+}): string;
+/**
+ * Parse the assignment condition (JSON stored in `role_claims.scope`) for a guard-claim of the
+ * given value type. Validates the operator is allowed for the type and the threshold fits the
+ * type. Returns null when the scope isn't a valid guard condition (so a plain scope string on a
+ * non-guard claim is simply ignored by the guard resolver).
+ */
+export declare function parseGuardCondition(scope: unknown, valueType: GuardValueType): GuardCondition | null;
+/**
+ * Evaluate a guard: does the condition HOLD for the current state value? `true` ⇒ invalidate the
+ * condition's claims. Absent/unparseable state ⇒ `false` (fail-open — never invalidate on missing
+ * data). Comparison is done in the declared type.
+ */
+export declare function guardConditionHolds(rawValue: unknown, valueType: GuardValueType, condition: GuardCondition): boolean;
+/** Convenience: parse a config `claimGuards` array into catalog entries (invalid entries dropped). */
+export declare function parseClaimGuardCatalog(entries: readonly ClaimGuardCatalogEntry[] | undefined): Array<{
+    action: string;
+    policy: GuardPolicy;
+}>;

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

@@ -0,0 +1,4 @@
+export { guardActionFromName, guardConditionHolds, parseClaimGuardCatalog, parseGuardCatalogEntry, parseGuardCondition, parseGuardPolicy, resolveGuardKey, } from './evaluate';
+export { type GuardResolution, resolveClaimGuards } from './resolve';
+export { seedClaimGuards } from './seed';
+export { type ClaimGuardCatalogEntry, type FiredGuard, type GuardCondition, type GuardOp, type GuardPolicy, type GuardValueType, OPS_BY_TYPE, type StateReader, } from './types';

package/dist/src/Services/Authorization/ClaimGuard/resolve.d.ts

@@ -0,0 +1,37 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { FiredGuard, GuardOp, GuardValueType, StateReader } from './types';
+/** One fully-evaluated guard assignment for a user — powers both enforcement and display. */
+export interface EvaluatedGuard {
+    /** Guard claim action, e.g. `token_spent_today`. */
+    action: string;
+    /** Resolved state key that was read. */
+    key: string;
+    valueType: GuardValueType;
+    op: GuardOp;
+    /** The threshold from the assignment condition. */
+    threshold: number | boolean | string;
+    /** Current value read from state (null when absent — fail-open). */
+    current: number | boolean | string | null;
+    /** Claim actions this guard invalidates when it holds. */
+    invalidates: string[];
+    /** Whether the condition currently holds (⇒ the claims are invalidated). */
+    holds: boolean;
+}
+export interface GuardResolution {
+    /** Every evaluated guard assignment (for the display endpoint). */
+    guards: EvaluatedGuard[];
+    /** Claim actions to remove from the user's effective claims right now (union over holding guards). */
+    suppressedClaims: string[];
+    /** The guards that fired (for a denial that names the guard). */
+    firedGuards: FiredGuard[];
+}
+/**
+ * Resolve which of a user's claims are invalidated RIGHT NOW by ClaimGuards. For every
+ * guard-claim the user holds (via any active role), read its state key from the shared store,
+ * evaluate the assignment's condition, and if it holds, invalidate that assignment's claim list.
+ * Reads whole small authz tables and filters in-memory, mirroring the manifest/quota resolvers.
+ * The state reader is injected so this stays testable and store-agnostic.
+ */
+export declare function resolveClaimGuards(db: NodePgDatabase, schemaTables: Record<string, unknown>, userId: string, read: StateReader, ctx?: {
+    tenant?: string;
+}): Promise<GuardResolution>;

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

@@ -0,0 +1,16 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { Logger } from 'src/Services/Logger';
+import type { ClaimGuardCatalogEntry } from './types';
+interface SeedGuardResult {
+    created: number;
+    updated: number;
+    deactivated: number;
+}
+/**
+ * Seed a claim per config `claimGuards` entry (action = name up to the first `{`, with the guard
+ * `policy` jsonb `{kind:'guard',keyTemplate,valueType}`). Idempotent + reconciling: an entry
+ * whose policy drifted is updated; a guard-claim no longer in config is deactivated (never
+ * deleted, mirroring endpoint-discovery reconcile). Non-guard claims are left untouched.
+ */
+export declare function seedClaimGuards(db: NodePgDatabase, schemaTables: Record<string, unknown>, claimGuards: readonly ClaimGuardCatalogEntry[] | undefined, logger?: Logger): Promise<SeedGuardResult>;
+export {};

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

@@ -0,0 +1,52 @@
+/**
+ * ClaimGuard — a generic, config-driven claim-invalidation primitive. A project defines a
+ * catalog of comparable keys (config `authorization.claimGuards`); godmin attaches a condition
+ * to a guard-claim and a list of claims to invalidate when the condition holds; at runtime
+ * nucleus reads the key from the shared Redis/Dapr state, evaluates the condition, and removes
+ * the listed claims from the user's effective set. nucleus names no metric/endpoint/window —
+ * quota is just one instantiation (see docs/specs/2026-07-04-claim-guards-design.md).
+ */
+/** The value type of a guard key, declared in config; drives parsing + which operators are valid. */
+export type GuardValueType = 'int' | 'boolean' | 'string';
+export type GuardOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'ne';
+/** Which operators are valid for each declared value type (int is ordered; bool/string are equality only). */
+export declare const OPS_BY_TYPE: Record<GuardValueType, readonly GuardOp[]>;
+/**
+ * The policy stored on a guard CLAIM (seeded from a config `claimGuards` entry). `keyTemplate`
+ * is the full config `name` (e.g. `token_spent_today:{userId}`); `{userId}`/`{tenant}` are
+ * resolved per request. `valueType` flows from config so nothing is hand-typed per claim.
+ */
+export interface GuardPolicy {
+    kind: 'guard';
+    keyTemplate: string;
+    valueType: GuardValueType;
+}
+/**
+ * The condition stored on a role_claim ASSIGNMENT (as JSON in `role_claims.scope`). Set when a
+ * guard-claim is attached to a role, e.g. `token_spent_today ?gt: 100000` + selected claims.
+ * `invalidates` are the claim actions removed from the user's effective claims when the
+ * condition HOLDS — regardless of which role granted them.
+ */
+export interface GuardCondition {
+    op: GuardOp;
+    value: number | boolean | string;
+    invalidates: string[];
+}
+/** One catalog entry as it appears in config `authorization.claimGuards`. */
+export interface ClaimGuardCatalogEntry {
+    /** Full key template, e.g. `token_spent_today:{userId}` or a global `example_other_key`. */
+    name: string;
+    /** Declared value type. Accepts the string form used in config. */
+    value: GuardValueType;
+}
+/** Reads a raw value from the shared state store (Dapr/Redis). Injected so the resolver stays testable. */
+export type StateReader = (key: string) => Promise<unknown>;
+/** A guard that fired for a user this request — surfaced so a denial can name the guard. */
+export interface FiredGuard {
+    /** The guard claim action, e.g. `token_spent_today`. */
+    action: string;
+    /** The resolved key that was read. */
+    key: string;
+    /** The claim actions this guard invalidated. */
+    invalidates: string[];
+}

package/dist/src/types.d.ts

@@ -750,24 +750,20 @@ export interface NucleusConfigOptions {
             token?: string;
         };
         /**
-         * Usage-quota metering settings. Metering is decoupled from quota existence: the
-         * `/authorization/quotas/consume` endpoint records usage into canonical
-         * `<prefix>:{tenant}:{userId}:<metric>:{date|total}` counters for EVERY reported metric,
-         * so usage accumulates even when a user holds no quota claim, and a quota assigned later
-         * (which omits `keyTemplate`) reads those same counters.
+         * ClaimGuards — generic, config-driven claim invalidation. Each entry defines a comparable
+         * key in the shared Redis/Dapr state and seeds a claim (action = the name up to the first
+         * `{`). At assignment time godmin attaches a condition to the guard-claim and selects the
+         * claims to invalidate when it holds (`role_claims.scope` JSON `{op,value,invalidates}`); at
+         * runtime nucleus reads the key, evaluates the condition, and drops the listed claims. The
+         * APP writes the key values. nucleus names no metric/endpoint/window — in Vorion this
+         * surfaces as a quota. See docs/specs/2026-07-04-claim-guards-design.md.
          */
-        quota?: {
-            /**
-             * Prefix for the canonical usage counters. Default `'quota'`. Must match the prefix the
-             * spender meters under so read keys and metering keys agree.
-             */
-            canonicalPrefix?: string;
-            /**
-             * Optional allowlist of metric names `/consume` will record. When set, metrics not in
-             * the list are ignored (bounds Redis key cardinality). Undefined = meter every metric.
-             */
-            allowedMetrics?: string[];
-        };
+        claimGuards?: Array<{
+            /** Key template, e.g. `token_spent_today:{userId}` or a global `feature_flag_x`. */
+            name: string;
+            /** Declared value type: drives parsing, valid operators, and threshold parsing. */
+            value: 'int' | 'boolean' | 'string';
+        }>;
     };
     audit?: {
         enabled?: boolean;

package/package.json

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

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

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

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

@@ -1,15 +0,0 @@
-import type { CounterReader, QuotaAggregate, QuotaContext, QuotaEvaluation, QuotaPolicy } from './types';
-/** Parse+validate a raw `claims.policy` jsonb value into a QuotaPolicy, or null if it isn't one. */
-export declare function parseQuotaPolicy(raw: unknown): QuotaPolicy | null;
-/**
- * Combine the per-role limits a user holds for one quota claim into a single effective limit.
- * `max` (default) = tier model (best role wins); `min` = strictest; `sum` = additive.
- * Non-numeric scopes are ignored. Returns null when no numeric limit is present.
- */
-export declare function aggregateLimit(scopes: readonly string[], mode: QuotaAggregate): number | null;
-/**
- * Read the current usage for a quota policy and compare it to the effective limit. Pure:
- * the counter reader is injected. Enforcement decision is the caller's — for a spend of
- * cost C, a HARD cap allows it iff `current + C <= limit` (lte) / `< limit` (lt).
- */
-export declare function evaluateQuota(policy: QuotaPolicy, ctx: QuotaContext, limit: number, read: CounterReader): Promise<QuotaEvaluation>;

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

@@ -1,5 +0,0 @@
-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, buildCanonicalIncrementKeys, buildIncrementKeys, buildQuotaKeys, canonicalKeyTemplate, DEFAULT_CANONICAL_PREFIX, sanitizeMetric, } from './windows';

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

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

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

@@ -1,16 +0,0 @@
-import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import type { QuotaPolicy } from './types';
-export interface ResolvedQuota {
-    action: string;
-    policy: QuotaPolicy;
-    /** effective limit after aggregating the per-role scopes for this claim */
-    limit: number;
-}
-/**
- * Resolve a user's effective quota limits. For every QUOTA claim (`claims.policy.kind==='quota'`)
- * granted through any of the user's roles, aggregate the per-role limits — each carried in that
- * assignment's `role_claims.scope` — using the policy's `aggregate` rule (default `max`, the tier
- * model). Active rows only. Reads whole small authz tables and filters in-memory, mirroring the
- * existing manifest resolver (no dynamic-column WHERE).
- */
-export declare function resolveUserQuotas(db: NodePgDatabase, schemaTables: Record<string, unknown>, userId: string): Promise<ResolvedQuota[]>;

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

@@ -1,15 +0,0 @@
-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

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

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

@@ -1,80 +0,0 @@
-/**
- * Generic usage-quota primitive. A quota is expressed as a CLAIM whose `policy` jsonb
- * column carries this shape; the per-role LIMIT lives in the `role_claims.scope` of each
- * assignment (so the same claim can be granted at different limits to different roles, and
- * a user's effective limit is an aggregation across their roles). The counter itself is
- * maintained by whoever does the spending (e.g. the LLM service) under the key described
- * here — nucleus only READS it to gate. Deliberately not spend-specific: `metric` is
- * free-form, so the same engine covers tokens, dollars, request counts, storage, etc.
- */
-export type QuotaOp = 'lte' | 'lt';
-/** How a user's per-role limits combine when they hold the claim via multiple roles. */
-export type QuotaAggregate = 'max' | 'min' | 'sum';
-export type QuotaWindow = {
-    type: 'rolling';
-    days: number;
-} | {
-    type: 'calendar_day';
-} | {
-    type: 'total';
-};
-export interface QuotaPolicy {
-    kind: 'quota';
-    source: 'redis';
-    /** Free-form metric label, e.g. 'tokens' | 'cost_usd' | 'requests'. */
-    metric: string;
-    window: QuotaWindow;
-    /**
-     * Redis counter key template. Placeholders: `{userId}`, `{tenant}`, `{date}`.
-     * Bucketed windows (rolling / calendar_day) substitute `{date}` (yyyy-mm-dd, UTC) once
-     * per bucket. `total` uses the template as-is (must not contain `{date}`).
-     * e.g. `usage:{tenant}:{userId}:tokens:{date}` or `usage:{tenant}:{userId}:tokens:total`.
-     *
-     * OPTIONAL: omit it to INHERIT the canonical per-metric template
-     * `<prefix>:{tenant}:{userId}:<metric>:{date}` (see canonicalKeyTemplate). Omitting is
-     * preferred for new quotas — it makes the keys this quota READS identical to the keys the
-     * `/consume` metering endpoint WRITES for the same metric, so a quota assigned mid-window
-     * already reflects the usage recorded before it existed.
-     */
-    keyTemplate?: string;
-    /** Comparison for a HARD cap. `lte`: usage may reach the limit; `lt`: must stay below. Default `lte`. */
-    op?: QuotaOp;
-    /** Multi-role limit resolution. Default `max` (tier model: the most generous role wins). */
-    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;
-    tenant?: string;
-    now: Date;
-    /**
-     * Prefix used to derive the canonical counter template when a policy omits `keyTemplate`.
-     * Must match the prefix the spender meters under (default `'quota'`). Set from
-     * `authorization.quota.canonicalPrefix` so read keys == metering keys across the deployment.
-     */
-    canonicalPrefix?: string;
-}
-export interface QuotaEvaluation {
-    metric: string;
-    window: QuotaWindow;
-    limit: number;
-    current: number;
-    /** limit − current; negative when already over. */
-    remaining: number;
-    /** true when the cap is already reached (no room for another unit under `op`). */
-    over: boolean;
-    /** the concrete counter keys that were summed (for debugging / the status endpoint). */
-    keys: string[];
-}
-/** Reads integer counter values for a set of keys (missing → 0). Injected so the evaluator stays pure. */
-export type CounterReader = (keys: string[]) => Promise<number[]>;