nucleus-core-ts 0.9.708 → 0.9.710

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

@@ -1,4 +1,14 @@
-import type { HttpProxyConfig } from './types';
+import type { HttpProxyConfig, TokenRefreshConfig } from './types';
+interface RefreshResult {
+    accessToken: string;
+    setCookieHeaders: string[];
+}
+export declare function deduplicatedRefresh(refreshConfig: TokenRefreshConfig, refreshToken: string, logger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}, originalCookieHeader?: string | null): Promise<RefreshResult | null>;
 export declare function createHttpProxyHandler(config: HttpProxyConfig): {
     handle(req: Request, clientIp?: string): Promise<Response | null>;
 };
+export {};

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

@@ -1,4 +1,4 @@
-import { evaluateAccess, ManifestCache, resolveClaimsFromRoles, RoleClaimsCache, verifyJwtHS256 } from './authz';
+import { evaluateAccess, ManifestCache, RoleClaimsCache, resolveClaimsFromRoles, verifyJwtHS256 } from './authz';
 import { createProxyLogger, matchPath, parseCookies, rewritePath } from './utils';
 const pendingRefreshes = new Map();
 function extractAccessTokenFromSetCookie(setCookieHeaders, accessCookieName) {
@@ -89,7 +89,7 @@ async function performTokenRefresh(refreshConfig, refreshToken, logger, original
         return null;
     }
 }
-function deduplicatedRefresh(refreshConfig, refreshToken, logger, originalCookieHeader) {
+export function deduplicatedRefresh(refreshConfig, refreshToken, logger, originalCookieHeader) {
     const dedupeKey = refreshToken.slice(-16);
     const existing = pendingRefreshes.get(dedupeKey);
     if (existing) {

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

@@ -39,7 +39,7 @@ export async function createProxyServer(config) {
         async fetch (req, server) {
             if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
                 if (wsHandler) {
-                    const result = wsHandler.upgrade(req, server);
+                    const result = await wsHandler.upgrade(req, server);
                     if (result === true) {
                         return undefined;
                     }

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

@@ -8,6 +8,16 @@ export interface WsProxyTarget {
         queryParam?: string;
         headerName?: string;
     };
+    /**
+     * Proactively refresh the access token before injecting it into the handshake.
+     * A WS handshake bearer MUST be the short-lived access token (the backend verifies
+     * it with the access-token secret) — a `refresh_token`/`session_token` fallback is
+     * signed with a DIFFERENT secret and always fails verification, producing a 4001
+     * reconnect storm once the access-token cookie ages out (e.g. after 30m idle on a
+     * sibling subdomain). When set, if the access cookie is missing/expiring and a
+     * refresh cookie is present, exchange it for a fresh access token and inject THAT.
+     */
+    tokenRefresh?: TokenRefreshConfig;
     headers?: Record<string, string>;
     changeOrigin?: boolean;
     secure?: boolean;

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

@@ -5,7 +5,7 @@ export declare function createWsProxyHandler(config: WsProxyConfig): {
         upgrade: (req: Request, options: {
             data: WsProxyState;
         }) => boolean;
-    }): boolean | Response;
+    }): Promise<boolean | Response>;
     websocket: {
         open(ws: ServerWebSocket<WsProxyState>): void;
         message(ws: ServerWebSocket<WsProxyState>, message: string | Buffer): void;

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

@@ -1,4 +1,21 @@
+import { deduplicatedRefresh } from './httpProxy';
 import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, rewritePath } from './utils';
+/**
+ * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
+ * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
+ * to pre-emptively refresh before the WS handshake.
+ */ function accessTokenExpiringSoon(token, skewMs = 60000) {
+    if (!token) return true;
+    try {
+        const part = token.split('.')[1];
+        if (!part) return true;
+        const json = JSON.parse(Buffer.from(part.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+        if (typeof json.exp !== 'number') return false;
+        return json.exp * 1000 - Date.now() < skewMs;
+    } catch  {
+        return true;
+    }
+}
 export function createWsProxyHandler(config) {
     const logger = createProxyLogger('WS Proxy', config.debug ?? false);
     const pingIntervalMs = config.pingIntervalMs ?? 0;
@@ -10,7 +27,7 @@ export function createWsProxyHandler(config) {
         }
         return null;
     }
-    function buildBackendUrl(path, target, cookies, query) {
+    async function buildBackendUrl(path, target, cookies, query) {
         let baseUrl = target.url.replace(/\/$/, '');
         if (baseUrl.startsWith('http')) {
             baseUrl = httpToWs(baseUrl);
@@ -40,6 +57,25 @@ export function createWsProxyHandler(config) {
             } else {
                 let token = cookies[target.injectTokenFromCookie.cookieName];
                 let tokenSource = target.injectTokenFromCookie.cookieName;
+                // A WS handshake bearer MUST be the short-lived access token. If it's missing or
+                // about to expire and a refresh is configured, exchange the refresh cookie for a
+                // FRESH access token and inject that — NEVER fall through to a refresh/session
+                // cookie, which is signed with a different secret and guarantees a 4001 storm.
+                const refreshConfig = target.tokenRefresh;
+                const refreshToken = cookies[refreshConfig?.refreshCookieName ?? 'refresh_token'];
+                if (refreshConfig?.enabled && refreshToken && accessTokenExpiringSoon(token)) {
+                    const cookieHeader = Object.entries(cookies).map(([k, v])=>`${k}=${v}`).join('; ');
+                    const refreshed = await deduplicatedRefresh(refreshConfig, refreshToken, logger, cookieHeader);
+                    if (refreshed?.accessToken) {
+                        token = refreshed.accessToken;
+                        tokenSource = 'refreshed access_token';
+                        refreshConfig.onRefreshSuccess?.(path);
+                    } else {
+                        refreshConfig.onRefreshFailure?.(path, 'WS pre-handshake refresh failed');
+                    }
+                }
+                // Legacy fallback — reached only when refresh is NOT configured. Prefer configuring
+                // tokenRefresh: a refresh/session cookie here is not a valid handshake bearer.
                 if (!token && target.injectTokenFromCookie.fallbackCookieNames) {
                     for (const fallback of target.injectTokenFromCookie.fallbackCookieNames){
                         if (cookies[fallback]) {
@@ -60,7 +96,7 @@ export function createWsProxyHandler(config) {
         return url;
     }
     return {
-        upgrade (req, server) {
+        async upgrade (req, server) {
             const url = new URL(req.url);
             const path = url.pathname;
             if (config.allowHmr !== false && path.startsWith('/_next/webpack-hmr')) {
@@ -78,7 +114,7 @@ export function createWsProxyHandler(config) {
                 return false;
             }
             const cookies = parseCookies(req.headers.get('cookie'));
-            const backendUrl = buildBackendUrl(path, target, cookies, url.searchParams);
+            const backendUrl = await buildBackendUrl(path, target, cookies, url.searchParams);
             logger.info(`Upgrading: ${path} -> ${backendUrl}`);
             // Extract original request headers to forward to backend
             const originalHeaders = {};
@@ -224,8 +260,8 @@ export function startWsProxyServer(config) {
     const server = Bun.serve({
         port,
         hostname,
-        fetch (req, server) {
-            const result = handler.upgrade(req, server);
+        async fetch (req, server) {
+            const result = await handler.upgrade(req, server);
             if (result === true) {
                 return undefined;
             }

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

@@ -10,6 +10,12 @@ export interface AuthorizationRoutesConfig {
     discovery: EndpointDiscoveryConfig & {
         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.
+     */
+    readCounters?: (keys: string[]) => Promise<number[]>;
 }
 /**
  * Endpoint-discovery admin + manifest routes.

package/dist/src/Managers/Redis/index.d.ts

@@ -27,6 +27,12 @@ export declare class RedisManager {
     update<T>(key: string, value: T, preserveTtl?: boolean): Promise<RedisResult<'OK'>>;
     remove(key: string): Promise<RedisResult<number>>;
     exists(key: string): Promise<RedisResult<boolean>>;
+    /**
+     * Read a batch of integer counter keys (missing / non-numeric → 0). Works in both
+     * direct and Dapr modes via the state-store abstraction. Used by the quota evaluator to
+     * gate usage; the counters themselves are maintained (INCR'd) by the spender.
+     */
+    readCounters(keys: string[]): Promise<number[]>;
     /**
      * Returns the underlying ioredis client when running in direct mode.
      * Returns null in Dapr mode — raw Redis commands (INFO, KEYS, …) are not

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+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/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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`.
+     */
+    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;
+}
+export interface QuotaContext {
+    userId: string;
+    tenant?: string;
+    now: Date;
+}
+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[]>;

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

@@ -0,0 +1,11 @@
+import type { QuotaContext, QuotaPolicy, QuotaWindow } from './types';
+/**
+ * The yyyy-mm-dd daily buckets a window spans, most-recent first, or `null` for `total`
+ * (which is a single cumulative counter with no date bucket). Rolling windows include today.
+ */
+export declare function bucketDatesForWindow(window: QuotaWindow, now: Date): string[] | null;
+/**
+ * Concrete Redis counter keys for a policy + context. Substitutes `{userId}`/`{tenant}`,
+ * then `{date}` per bucket (or none for `total`). The spender maintains these; nucleus reads them.
+ */
+export declare function buildQuotaKeys(policy: QuotaPolicy, ctx: QuotaContext): string[];

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

@@ -10,6 +10,12 @@ type SeedConfig = {
         path: string;
         method: string;
         description?: string;
+        /**
+         * Optional generic policy dictionary (jsonb) — e.g. a QUOTA policy
+         * (`{ kind:'quota', metric, window, keyTemplate, ... }`). Reconciled on
+         * drift like `scope`, so editing a seeded quota claim's policy takes effect.
+         */
+        policy?: Record<string, unknown> | null;
     }>;
     roleClaimAssignments?: Array<{
         role: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.708",
+	"version": "0.9.710",
 	"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/src/system.tables.json

@@ -209,6 +209,10 @@
           "type": "varchar",
           "length": 10,
           "notNull": true
+        },
+        {
+          "name": "policy",
+          "type": "jsonb"
         }
       ],
       "indexes": [