@digilogiclabs/platform-core 1.23.0 → 1.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/auth.d.mts CHANGED
@@ -468,6 +468,20 @@ interface SecureRateLimitResult {
468
468
  current?: number;
469
469
  resetMs?: number;
470
470
  }
471
+ /**
472
+ * Allowed-with-state return shape from `rateLimiter.enforce`. When the
473
+ * rate-limiter returns this, the factory automatically injects the
474
+ * standard `X-RateLimit-*` headers onto the success response. Opt-in —
475
+ * existing rate-limiters returning `Response | null` see no change.
476
+ */
477
+ interface SecureRateLimitInfo {
478
+ /** Maximum requests allowed in the window. */
479
+ limit: number;
480
+ /** Requests remaining in the current window (post-this-request). */
481
+ remaining: number;
482
+ /** Milliseconds-since-epoch when the window resets. */
483
+ resetMs: number;
484
+ }
471
485
  /** Minimal logger interface */
472
486
  interface SecureLogger {
473
487
  info(message: string, meta?: Record<string, unknown>): void;
@@ -484,8 +498,24 @@ interface SecureHandlerFactoryConfig<TSession extends SecureSession = SecureSess
484
498
  hasAnyRole?: (session: TSession | null, roles: string[]) => boolean;
485
499
  /** Rate limiting integration */
486
500
  rateLimiter?: {
487
- /** Check and enforce rate limit — return response if blocked, null if allowed */
488
- enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null>;
501
+ /**
502
+ * Check and enforce rate limit. Return value semantics:
503
+ *
504
+ * - `Response` — request was BLOCKED; the response (typically 429)
505
+ * is returned to the client unchanged. Implementer is responsible
506
+ * for including its own `X-RateLimit-*` headers on the blocked
507
+ * response.
508
+ * - `null` — request ALLOWED. Back-compat shape; no state is
509
+ * surfaced and the factory does not inject rate-limit headers
510
+ * onto the eventual success response.
511
+ * - `SecureRateLimitInfo` — request ALLOWED, with current state
512
+ * (limit/remaining/resetMs). The factory automatically injects
513
+ * the standard `X-RateLimit-Limit` / `-Remaining` / `-Reset`
514
+ * response headers onto the success response. Opt-in per
515
+ * rate-limiter implementation — existing implementations
516
+ * returning `Response | null` are unaffected.
517
+ */
518
+ enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null | SecureRateLimitInfo>;
489
519
  /** Default preset for public APIs */
490
520
  publicDefault?: TPresetKey;
491
521
  /** Default preset for authenticated APIs */
@@ -1262,4 +1292,4 @@ interface AppCache {
1262
1292
  */
1263
1293
  declare function createAppCache(cache: ICache, options?: AppCacheOptions): AppCache;
1264
1294
 
1265
- export { type AppCache, type AppCacheOptions, CacheTTL, type CacheTTLValue, type CreateHealthRouteOptions, type EnsureUserClaimDelta, type EnsureUserConfig, type EnsureUserFn, type EnsureUserRow, type FederatedLogoutConfig, type HealthCheck, type HealthProbeResult, type HealthProbeStatus, type HealthRouteResponse, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SafeRedirectOptions, type SecureAuditConfig, type SecureAuthMethod, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, type SecureTimedAudit, type SignTokenOptions, type VerifyTokenOptions, type VerifyTokenResult, addRateLimitHeaders, buildFederatedLogoutHandler, createAppCache, createEnsureUser, createHealthRoute, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isHoneypotFilled, isValidBearerToken, rateLimitResponse, safeRedirect, safeValidate, signToken, verifyCronAuth, verifyToken, zodErrorResponse };
1295
+ export { type AppCache, type AppCacheOptions, CacheTTL, type CacheTTLValue, type CreateHealthRouteOptions, type EnsureUserClaimDelta, type EnsureUserConfig, type EnsureUserFn, type EnsureUserRow, type FederatedLogoutConfig, type HealthCheck, type HealthProbeResult, type HealthProbeStatus, type HealthRouteResponse, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SafeRedirectOptions, type SecureAuditConfig, type SecureAuthMethod, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitInfo, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, type SecureTimedAudit, type SignTokenOptions, type VerifyTokenOptions, type VerifyTokenResult, addRateLimitHeaders, buildFederatedLogoutHandler, createAppCache, createEnsureUser, createHealthRoute, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isHoneypotFilled, isValidBearerToken, rateLimitResponse, safeRedirect, safeValidate, signToken, verifyCronAuth, verifyToken, zodErrorResponse };
package/dist/auth.d.ts CHANGED
@@ -468,6 +468,20 @@ interface SecureRateLimitResult {
468
468
  current?: number;
469
469
  resetMs?: number;
470
470
  }
471
+ /**
472
+ * Allowed-with-state return shape from `rateLimiter.enforce`. When the
473
+ * rate-limiter returns this, the factory automatically injects the
474
+ * standard `X-RateLimit-*` headers onto the success response. Opt-in —
475
+ * existing rate-limiters returning `Response | null` see no change.
476
+ */
477
+ interface SecureRateLimitInfo {
478
+ /** Maximum requests allowed in the window. */
479
+ limit: number;
480
+ /** Requests remaining in the current window (post-this-request). */
481
+ remaining: number;
482
+ /** Milliseconds-since-epoch when the window resets. */
483
+ resetMs: number;
484
+ }
471
485
  /** Minimal logger interface */
472
486
  interface SecureLogger {
473
487
  info(message: string, meta?: Record<string, unknown>): void;
@@ -484,8 +498,24 @@ interface SecureHandlerFactoryConfig<TSession extends SecureSession = SecureSess
484
498
  hasAnyRole?: (session: TSession | null, roles: string[]) => boolean;
485
499
  /** Rate limiting integration */
486
500
  rateLimiter?: {
487
- /** Check and enforce rate limit — return response if blocked, null if allowed */
488
- enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null>;
501
+ /**
502
+ * Check and enforce rate limit. Return value semantics:
503
+ *
504
+ * - `Response` — request was BLOCKED; the response (typically 429)
505
+ * is returned to the client unchanged. Implementer is responsible
506
+ * for including its own `X-RateLimit-*` headers on the blocked
507
+ * response.
508
+ * - `null` — request ALLOWED. Back-compat shape; no state is
509
+ * surfaced and the factory does not inject rate-limit headers
510
+ * onto the eventual success response.
511
+ * - `SecureRateLimitInfo` — request ALLOWED, with current state
512
+ * (limit/remaining/resetMs). The factory automatically injects
513
+ * the standard `X-RateLimit-Limit` / `-Remaining` / `-Reset`
514
+ * response headers onto the success response. Opt-in per
515
+ * rate-limiter implementation — existing implementations
516
+ * returning `Response | null` are unaffected.
517
+ */
518
+ enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null | SecureRateLimitInfo>;
489
519
  /** Default preset for public APIs */
490
520
  publicDefault?: TPresetKey;
491
521
  /** Default preset for authenticated APIs */
@@ -1262,4 +1292,4 @@ interface AppCache {
1262
1292
  */
1263
1293
  declare function createAppCache(cache: ICache, options?: AppCacheOptions): AppCache;
1264
1294
 
1265
- export { type AppCache, type AppCacheOptions, CacheTTL, type CacheTTLValue, type CreateHealthRouteOptions, type EnsureUserClaimDelta, type EnsureUserConfig, type EnsureUserFn, type EnsureUserRow, type FederatedLogoutConfig, type HealthCheck, type HealthProbeResult, type HealthProbeStatus, type HealthRouteResponse, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SafeRedirectOptions, type SecureAuditConfig, type SecureAuthMethod, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, type SecureTimedAudit, type SignTokenOptions, type VerifyTokenOptions, type VerifyTokenResult, addRateLimitHeaders, buildFederatedLogoutHandler, createAppCache, createEnsureUser, createHealthRoute, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isHoneypotFilled, isValidBearerToken, rateLimitResponse, safeRedirect, safeValidate, signToken, verifyCronAuth, verifyToken, zodErrorResponse };
1295
+ export { type AppCache, type AppCacheOptions, CacheTTL, type CacheTTLValue, type CreateHealthRouteOptions, type EnsureUserClaimDelta, type EnsureUserConfig, type EnsureUserFn, type EnsureUserRow, type FederatedLogoutConfig, type HealthCheck, type HealthProbeResult, type HealthProbeStatus, type HealthRouteResponse, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SafeRedirectOptions, type SecureAuditConfig, type SecureAuthMethod, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitInfo, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, type SecureTimedAudit, type SignTokenOptions, type VerifyTokenOptions, type VerifyTokenResult, addRateLimitHeaders, buildFederatedLogoutHandler, createAppCache, createEnsureUser, createHealthRoute, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isHoneypotFilled, isValidBearerToken, rateLimitResponse, safeRedirect, safeValidate, signToken, verifyCronAuth, verifyToken, zodErrorResponse };
package/dist/auth.js CHANGED
@@ -1731,15 +1731,21 @@ function createSecureHandlerFactory(factoryConfig) {
1731
1731
  );
1732
1732
  }
1733
1733
  }
1734
+ let rateLimitInfo = null;
1734
1735
  if (!routeConfig.skipRateLimit && routeConfig.rateLimit && factoryConfig.rateLimiter) {
1735
1736
  const userId = session?.user?.id ?? void 0;
1736
- const blocked = await factoryConfig.rateLimiter.enforce(
1737
+ const result = await factoryConfig.rateLimiter.enforce(
1737
1738
  request,
1738
1739
  operation,
1739
1740
  routeConfig.rateLimit,
1740
1741
  userId
1741
1742
  );
1742
- if (blocked) return blocked;
1743
+ if (result instanceof Response) {
1744
+ return result;
1745
+ }
1746
+ if (result !== null && typeof result === "object") {
1747
+ rateLimitInfo = result;
1748
+ }
1743
1749
  }
1744
1750
  let validated = {};
1745
1751
  if (routeConfig.validate) {
@@ -1805,6 +1811,20 @@ function createSecureHandlerFactory(factoryConfig) {
1805
1811
  };
1806
1812
  const response = await handler(request, ctx);
1807
1813
  response.headers.set("X-Request-ID", requestId);
1814
+ if (rateLimitInfo) {
1815
+ response.headers.set(
1816
+ "X-RateLimit-Limit",
1817
+ String(rateLimitInfo.limit)
1818
+ );
1819
+ response.headers.set(
1820
+ "X-RateLimit-Remaining",
1821
+ String(rateLimitInfo.remaining)
1822
+ );
1823
+ response.headers.set(
1824
+ "X-RateLimit-Reset",
1825
+ String(rateLimitInfo.resetMs)
1826
+ );
1827
+ }
1808
1828
  if (resolvedAuditAction && factoryConfig.auditLog && !timedAudit) {
1809
1829
  await factoryConfig.auditLog({
1810
1830
  actor: {