nucleus-core-ts 0.9.714 → 0.9.716

package/dist/src/ElysiaPlugin/routes/auth/login/deviceInfo.d.ts

@@ -0,0 +1,25 @@
+import type { DeviceInfo } from 'src/Services/Auth/SessionStore/types';
+import { type ClientHints } from './utils';
+export type { ClientHints } from './utils';
+/**
+ * Extract IP + User-Agent + Client-Hints from a request, using the same header precedence as
+ * password login. Any auth path that has the `Request` can produce a consistent device context.
+ */
+export declare function deviceContextFromRequest(request: Request): {
+    ipAddress: string;
+    userAgent: string;
+    clientHints: ClientHints;
+};
+/**
+ * Idempotent device-info normalizer — the single place device fields are guaranteed.
+ *
+ * If the caller already resolved browser + OS + deviceName (password login, OAuth, the
+ * deliberate impersonation "Admin" labels) the object is returned unchanged. Otherwise the
+ * User-Agent is parsed (with optional Client-Hints) and merged, and a non-null `deviceName`
+ * is always produced. This is what fixes "Unknown on Unknown": paths that pass only a raw
+ * `{ ipAddress, userAgent }` (register / webauthn / magic-link) now get the same parsing as
+ * login — and because `saveSessionToDb` calls this, EVERY path (incl. any future one) is covered.
+ */
+export declare function ensureDeviceInfo(info: Partial<DeviceInfo> & {
+    ipAddress: string;
+}, clientHints?: ClientHints): DeviceInfo;

package/dist/src/ElysiaPlugin/routes/auth/login/deviceInfo.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/auth/login/utils.d.ts

@@ -1,6 +1,19 @@
 export declare function verifyPassword(plainPassword: string, hashedPassword: string): Promise<boolean>;
 export declare function isValidEmail(email: string): boolean;
-export declare function parseUserAgentForLogin(userAgent: string, ipAddress: string, deviceHint?: string): {
+/** Client Hints headers (`Sec-CH-UA*`) used to enrich a reduced/frozen User-Agent. */
+export interface ClientHints {
+    uaHeader?: string;
+    platformHeader?: string;
+    mobileHeader?: string;
+}
+/**
+ * Last-resort human label from a UA we couldn't classify — the first meaningful
+ * `Product/Version` token (ignoring the ubiquitous `Mozilla/5.0`), else the first alpha
+ * word (a bespoke client name). Generic: no product allow-list, works for any consumer.
+ * Returns undefined for empty/placeholder UAs so the caller can fall back to "Unknown Device".
+ */
+export declare function labelFromRawUserAgent(userAgent: string): string | undefined;
+export declare function parseUserAgentForLogin(userAgent: string, ipAddress: string, deviceHint?: string, clientHints?: ClientHints): {
     deviceName: string;
     deviceType: "unknown" | "desktop" | "mobile" | "tablet";
     browserName: string | undefined;

package/dist/src/ElysiaPlugin/routes/authorization/consume.test.d.ts

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

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

@@ -29,6 +29,18 @@ export interface AuthorizationRoutesConfig {
         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[];
 }
 /**
  * Endpoint-discovery admin + manifest routes.

package/dist/src/Services/Auth/SessionStore/types.d.ts

@@ -9,6 +9,9 @@ export type DeviceInfo = {
     ipAddress: string;
     userAgent?: string;
     deviceHint?: string;
+    /** Optional geo enrichment (set by the login path from the IP when available). */
+    locationCountry?: string;
+    locationCity?: string;
 };
 export type SessionRecord = {
     id: string;

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

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

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

@@ -2,4 +2,4 @@ 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';
+export { bucketDatesForWindow, buildCanonicalIncrementKeys, buildIncrementKeys, buildQuotaKeys, canonicalKeyTemplate, DEFAULT_CANONICAL_PREFIX, sanitizeMetric, } from './windows';

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

@@ -29,8 +29,14 @@ export interface QuotaPolicy {
      * 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;
+    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). */
@@ -51,6 +57,12 @@ 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;

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

@@ -1,4 +1,26 @@
 import type { QuotaContext, QuotaPolicy, QuotaWindow } from './types';
+/** Default prefix for canonical (metric-keyed) usage counters. Project-overridable via config. */
+export declare const DEFAULT_CANONICAL_PREFIX = "quota";
+/** A metric goes into a Redis key segment: strip `:`/whitespace so it can't split the key. */
+export declare function sanitizeMetric(metric: string): string;
+/**
+ * The canonical keyTemplate for a metric: `<prefix>:{tenant}:{userId}:<metric>:{date}`.
+ * A policy that OMITS `keyTemplate` inherits this at build time, so the keys metering WRITES
+ * (buildCanonicalIncrementKeys / buildIncrementKeys) are identical to the keys a quota READS
+ * (buildQuotaKeys). `{date}` collapses to `total` for total-windows via the build fns below.
+ * This is the load-bearing decoupling: usage is recorded per (tenant,user,metric) regardless
+ * of whether any quota claim exists, and a later-assigned quota finds the pre-existing usage.
+ */
+export declare function canonicalKeyTemplate(metric: string, prefix?: string): string;
+/**
+ * The canonical daily + total metering keys for one metric — INDEPENDENT of any policy.
+ * Used by `/consume` to ALWAYS record usage even when the user holds no quota claim. The
+ * daily bucket self-expires (~40d, outliving a rolling-30 window); the total key is permanent.
+ */
+export declare function buildCanonicalIncrementKeys(metric: string, ctx: QuotaContext, prefix?: string): Array<{
+    key: string;
+    ttlSeconds?: number;
+}>;
 /**
  * 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.

package/dist/src/Utils/headerList.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HTTP-header-safe encoding for lists of possibly-Unicode values (role names,
+ * claim actions) carried in the `x-user-roles` / `x-user-claims` headers.
+ *
+ * HTTP header values must be ISO-8859-1 (latin1). Role names are user-defined and
+ * may contain arbitrary Unicode — e.g. a Turkish role "Günlük Kısıtlı Deneme"
+ * contains `ı`/`ş`/`ğ` which are outside latin1. Passing such a value to
+ * `Headers.set` throws ("Header 'x-user-roles' has invalid value") and 500s EVERY
+ * request for any user holding that role — which silently breaks login, entity
+ * access, and impersonation enter/exit for that user.
+ *
+ * Per-item percent-encoding fixes this generically:
+ *  - ASCII values (`godmin`, `user-free`, `llm.conversations.list`) are left
+ *    byte-identical, so readers that don't decode still match them correctly.
+ *  - Unicode values become transport-safe and round-trip losslessly via decode.
+ *
+ * The comma separator is preserved (encodeURIComponent never emits `,`), so
+ * existing `header.split(',')` readers keep working.
+ */
+/** Encode a list of role/claim names into a header-safe comma-joined string. */
+export declare function encodeHeaderList(items: string[]): string;
+/**
+ * Inverse of {@link encodeHeaderList}: split a header value and restore the
+ * original (possibly Unicode) items. Tolerant of legacy/plain values —
+ * `decodeURIComponent` is the identity for un-encoded ASCII, and a malformed
+ * percent-sequence is returned verbatim rather than throwing.
+ */
+export declare function decodeHeaderList(header: string | null | undefined): string[];

package/dist/src/Utils/headerList.test.d.ts

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

package/dist/src/types.d.ts

@@ -749,6 +749,25 @@ 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.
+         */
+        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[];
+        };
     };
     audit?: {
         enabled?: boolean;

package/package.json

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