@holo-js/security 0.1.3

package/dist/chunk-3J5QRTPZ.mjs

@@ -0,0 +1,156 @@
+// src/contracts.ts
+import { normalizeSecurityConfig } from "@holo-js/config";
+var SecurityCsrfError = class extends Error {
+  status = 419;
+  constructor(message = "CSRF token mismatch.") {
+    super(message);
+    this.name = "SecurityCsrfError";
+  }
+};
+var SecurityRateLimitError = class extends Error {
+  status = 429;
+  retryAfterSeconds;
+  snapshot;
+  constructor(message = "Too many attempts. Please try again later.", options = {}) {
+    super(message);
+    this.name = "SecurityRateLimitError";
+    this.retryAfterSeconds = options.retryAfterSeconds;
+    this.snapshot = options.snapshot;
+  }
+};
+var PendingSecurityLimiterDefinition = class {
+  constructor(maxAttempts, decaySeconds) {
+    this.maxAttempts = maxAttempts;
+    this.decaySeconds = decaySeconds;
+  }
+  by(key) {
+    if (typeof key !== "function") {
+      throw new TypeError("[@holo-js/security] Rate limiter key resolvers must be functions.");
+    }
+    return Object.freeze({
+      maxAttempts: this.maxAttempts,
+      decaySeconds: this.decaySeconds,
+      key
+    });
+  }
+  define() {
+    return Object.freeze({
+      maxAttempts: this.maxAttempts,
+      decaySeconds: this.decaySeconds
+    });
+  }
+};
+function normalizeLimiterAttempts(value, label) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new TypeError(`[@holo-js/security] ${label} must be an integer greater than or equal to 1.`);
+  }
+  return value;
+}
+function normalizeLimiterWindowSeconds(value, label) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new TypeError(`[@holo-js/security] ${label} must be an integer greater than or equal to 1.`);
+  }
+  return value;
+}
+var limit = Object.freeze({
+  perMinute(maxAttempts) {
+    return new PendingSecurityLimiterDefinition(
+      normalizeLimiterAttempts(maxAttempts, "Rate limiter maxAttempts"),
+      normalizeLimiterWindowSeconds(60, "Rate limiter decaySeconds")
+    );
+  },
+  perHour(maxAttempts) {
+    return new PendingSecurityLimiterDefinition(
+      normalizeLimiterAttempts(maxAttempts, "Rate limiter maxAttempts"),
+      normalizeLimiterWindowSeconds(3600, "Rate limiter decaySeconds")
+    );
+  }
+});
+function ip(request, trustedProxy = false) {
+  if (!trustedProxy) {
+    return "unknown";
+  }
+  const forwarded = request.headers.get("x-forwarded-for")?.split(",", 1)[0]?.trim();
+  if (forwarded) {
+    return forwarded;
+  }
+  const realIp = request.headers.get("x-real-ip")?.trim();
+  if (realIp) {
+    return realIp;
+  }
+  return "unknown";
+}
+function normalizeLimiterIntegerInput(value, label) {
+  if (typeof value === "undefined") {
+    throw new TypeError(`[@holo-js/security] ${label} is required.`);
+  }
+  const normalized = typeof value === "number" ? value : (() => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return Number.NaN;
+    }
+    return Number(trimmed);
+  })();
+  if (!Number.isFinite(normalized) || !Number.isInteger(normalized)) {
+    throw new TypeError(`[@holo-js/security] ${label} must be an integer greater than or equal to 1.`);
+  }
+  if (normalized < 1) {
+    throw new TypeError(`[@holo-js/security] ${label} must be an integer greater than or equal to 1.`);
+  }
+  return normalized;
+}
+function defineRateLimiter(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError("[@holo-js/security] Rate limiter definitions must be objects.");
+  }
+  const normalizedDefinition = {
+    ...definition,
+    maxAttempts: normalizeLimiterIntegerInput(definition.maxAttempts, "Rate limiter maxAttempts"),
+    decaySeconds: normalizeLimiterIntegerInput(definition.decaySeconds, "Rate limiter decaySeconds")
+  };
+  if (normalizedDefinition.key !== void 0 && typeof normalizedDefinition.key !== "function") {
+    throw new TypeError("[@holo-js/security] Rate limiter key resolvers must be functions.");
+  }
+  return Object.freeze(normalizedDefinition);
+}
+function defineSecurityRuntimeBindings(bindings) {
+  return Object.freeze({
+    config: normalizeSecurityConfig(bindings.config),
+    rateLimitStore: bindings.rateLimitStore,
+    csrfSigningKey: bindings.csrfSigningKey,
+    defaultKeyResolver: bindings.defaultKeyResolver
+  });
+}
+function createMemoryRateLimitStoreConfig(config = {}) {
+  return Object.freeze({
+    ...config
+  });
+}
+function createFileRateLimitStoreConfig(config = {}) {
+  return Object.freeze({
+    ...config
+  });
+}
+function createRedisRateLimitStoreConfig(config = {}) {
+  return Object.freeze({
+    ...config
+  });
+}
+var securityInternals = {
+  PendingSecurityLimiterDefinition,
+  normalizeLimiterAttempts,
+  normalizeLimiterWindowSeconds
+};
+
+export {
+  SecurityCsrfError,
+  SecurityRateLimitError,
+  limit,
+  ip,
+  defineRateLimiter,
+  defineSecurityRuntimeBindings,
+  createMemoryRateLimitStoreConfig,
+  createFileRateLimitStoreConfig,
+  createRedisRateLimitStoreConfig,
+  securityInternals
+};

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { SecurityClientBindings, SecurityClientConfig } from './contracts.js';
+import '@holo-js/config';
+
+type RuntimeSecurityClientState = {
+    bindings?: SecurityClientConfig;
+};
+declare function getDefaultSecurityClientConfig(): SecurityClientConfig;
+declare function getSecurityClientState(): RuntimeSecurityClientState;
+declare function normalizeSecurityClientConfig(bindings?: SecurityClientBindings): SecurityClientConfig;
+declare function configureSecurityClient(bindings?: SecurityClientBindings): void;
+declare function getSecurityClientConfig(): SecurityClientConfig;
+declare function resetSecurityClient(): void;
+declare const securityClientInternals: {
+    getDefaultSecurityClientConfig: typeof getDefaultSecurityClientConfig;
+    getSecurityClientState: typeof getSecurityClientState;
+    normalizeSecurityClientConfig: typeof normalizeSecurityClientConfig;
+};
+
+export { SecurityClientBindings, SecurityClientConfig, configureSecurityClient, getSecurityClientConfig, resetSecurityClient, securityClientInternals };

package/dist/client.mjs

@@ -0,0 +1,47 @@
+// src/client.ts
+import { normalizeSecurityConfig } from "@holo-js/config";
+var DEFAULT_SECURITY_CONFIG = normalizeSecurityConfig({});
+var DEFAULT_SECURITY_CLIENT_CONFIG = Object.freeze({
+  csrf: Object.freeze({
+    field: DEFAULT_SECURITY_CONFIG.csrf.field,
+    cookie: DEFAULT_SECURITY_CONFIG.csrf.cookie
+  })
+});
+function getDefaultSecurityClientConfig() {
+  return DEFAULT_SECURITY_CLIENT_CONFIG;
+}
+function getSecurityClientState() {
+  const runtime = globalThis;
+  runtime.__holoSecurityClient__ ??= {};
+  return runtime.__holoSecurityClient__;
+}
+function normalizeSecurityClientConfig(bindings) {
+  const defaults = getDefaultSecurityClientConfig();
+  const csrf = Object.freeze({
+    field: bindings?.config?.csrf?.field ?? defaults.csrf.field,
+    cookie: bindings?.config?.csrf?.cookie ?? defaults.csrf.cookie
+  });
+  return Object.freeze({
+    csrf
+  });
+}
+function configureSecurityClient(bindings) {
+  getSecurityClientState().bindings = bindings ? normalizeSecurityClientConfig(bindings) : void 0;
+}
+function getSecurityClientConfig() {
+  return getSecurityClientState().bindings ?? DEFAULT_SECURITY_CLIENT_CONFIG;
+}
+function resetSecurityClient() {
+  getSecurityClientState().bindings = void 0;
+}
+var securityClientInternals = {
+  getDefaultSecurityClientConfig,
+  getSecurityClientState,
+  normalizeSecurityClientConfig
+};
+export {
+  configureSecurityClient,
+  getSecurityClientConfig,
+  resetSecurityClient,
+  securityClientInternals
+};

package/dist/contracts.d.ts

@@ -0,0 +1,137 @@
+import { HoloSecurityConfig, NormalizedHoloSecurityConfig, SecurityRateLimitFileConfig, SecurityRateLimitMemoryConfig, SecurityRateLimitRedisConfig, SecurityLimiterConfig, SecurityRateLimitKeyResolver } from '@holo-js/config';
+export { HoloSecurityConfig, HoloSecurityCsrfConfig, HoloSecurityRateLimitConfig, NormalizedHoloSecurityConfig, NormalizedHoloSecurityCsrfConfig, NormalizedHoloSecurityRateLimitConfig, NormalizedSecurityLimiterConfig, SecurityLimiterConfig, SecurityRateLimitContext, SecurityRateLimitDriver, SecurityRateLimitFileConfig, SecurityRateLimitKeyResolver, SecurityRateLimitMemoryConfig, SecurityRateLimitRedisConfig } from '@holo-js/config';
+
+interface SecurityRuntimeBindings {
+    readonly config: HoloSecurityConfig | NormalizedHoloSecurityConfig;
+    readonly rateLimitStore?: SecurityRateLimitStore;
+    readonly csrfSigningKey?: string;
+    readonly defaultKeyResolver?: SecurityDefaultRateLimitKeyResolver;
+}
+interface SecurityRuntimeFacade {
+    readonly config: NormalizedHoloSecurityConfig;
+    readonly rateLimitStore?: SecurityRateLimitStore;
+    readonly csrfSigningKey?: string;
+    readonly defaultKeyResolver?: SecurityDefaultRateLimitKeyResolver;
+}
+interface SecurityClientConfig {
+    readonly csrf: {
+        readonly field: string;
+        readonly cookie: string;
+    };
+}
+interface SecurityClientBindings {
+    readonly config?: {
+        readonly csrf?: Partial<SecurityClientConfig['csrf']>;
+    };
+}
+interface SecurityCsrfField {
+    readonly name: string;
+    readonly value: string;
+}
+interface SecurityProtectOptions {
+    readonly csrf?: boolean;
+    readonly throttle?: string;
+}
+interface SecurityRateLimitCallOptions {
+    readonly request?: Request;
+    readonly key?: string;
+    readonly values?: Readonly<Record<string, unknown>>;
+}
+interface SecurityClearRateLimitOptions {
+    readonly limiter?: string;
+    readonly key?: string;
+    readonly all?: boolean;
+}
+interface SecurityCsrfFacade {
+    token(request: Request): Promise<string>;
+    field(request: Request): Promise<SecurityCsrfField>;
+    cookie(request: Request, token?: string): Promise<string>;
+    verify(request: Request): Promise<void>;
+}
+interface SecurityRateLimitBucketSnapshot {
+    readonly limiter: string;
+    readonly key: string;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly remainingAttempts: number;
+    readonly expiresAt: Date;
+}
+interface SecurityRateLimitHitResult {
+    readonly limited: boolean;
+    readonly snapshot: SecurityRateLimitBucketSnapshot;
+    readonly retryAfterSeconds: number;
+}
+interface SecurityRateLimitStore {
+    hit(key: string, options: {
+        readonly maxAttempts: number;
+        readonly decaySeconds: number;
+    }): Promise<SecurityRateLimitHitResult>;
+    clear(key: string): Promise<boolean>;
+    clearByPrefix(prefix: string): Promise<number>;
+    clearAll(): Promise<number>;
+    close?(): Promise<void> | void;
+}
+interface SecurityDefaultRateLimitKeyResolver {
+    (request: Request): string | number | null | undefined | Promise<string | number | null | undefined>;
+}
+declare class SecurityCsrfError extends Error {
+    readonly status = 419;
+    constructor(message?: string);
+}
+declare class SecurityRateLimitError extends Error {
+    readonly status = 429;
+    readonly retryAfterSeconds?: number;
+    readonly snapshot?: SecurityRateLimitBucketSnapshot;
+    constructor(message?: string, options?: {
+        retryAfterSeconds?: number;
+        snapshot?: SecurityRateLimitBucketSnapshot;
+    });
+}
+interface SecurityRateLimitRedisDriverAdapter {
+    connect?(): Promise<void>;
+    increment(key: string, options: {
+        readonly decaySeconds: number;
+    }): Promise<{
+        readonly attempts: number;
+        readonly ttlSeconds: number;
+    }>;
+    del(key: string): Promise<number>;
+    clearByPrefix?(prefix: string): Promise<number>;
+    clearAll?(): Promise<number>;
+    close?(): Promise<void>;
+}
+interface SecurityRateLimitStoreFactoryOptions {
+    readonly projectRoot?: string;
+    readonly redisAdapter?: SecurityRateLimitRedisDriverAdapter;
+}
+declare class PendingSecurityLimiterDefinition<TValues extends Readonly<Record<string, unknown>> | undefined = Readonly<Record<string, unknown>> | undefined> {
+    readonly maxAttempts: number;
+    readonly decaySeconds: number;
+    constructor(maxAttempts: number, decaySeconds: number);
+    by(key: SecurityRateLimitKeyResolver<TValues>): SecurityLimiterConfig<TValues>;
+    define(): SecurityLimiterConfig<TValues>;
+}
+declare function normalizeLimiterAttempts(value: number, label: string): number;
+declare function normalizeLimiterWindowSeconds(value: number, label: string): number;
+declare const limit: Readonly<{
+    perMinute(maxAttempts: number): PendingSecurityLimiterDefinition<Readonly<Record<string, unknown>> | undefined>;
+    perHour(maxAttempts: number): PendingSecurityLimiterDefinition<Readonly<Record<string, unknown>> | undefined>;
+}>;
+declare function ip(request: Request, trustedProxy?: boolean): string;
+declare function defineRateLimiter<TValues extends Readonly<Record<string, unknown>> | undefined = Readonly<Record<string, unknown>> | undefined>(definition: SecurityLimiterConfig<TValues>): SecurityLimiterConfig<TValues>;
+declare function defineSecurityRuntimeBindings(bindings: SecurityRuntimeBindings): Readonly<{
+    config: NormalizedHoloSecurityConfig;
+    rateLimitStore?: SecurityRateLimitStore;
+    csrfSigningKey?: string;
+    defaultKeyResolver?: SecurityDefaultRateLimitKeyResolver;
+}>;
+declare function createMemoryRateLimitStoreConfig(config?: SecurityRateLimitMemoryConfig): Readonly<SecurityRateLimitMemoryConfig>;
+declare function createFileRateLimitStoreConfig(config?: SecurityRateLimitFileConfig): Readonly<SecurityRateLimitFileConfig>;
+declare function createRedisRateLimitStoreConfig(config?: SecurityRateLimitRedisConfig): Readonly<SecurityRateLimitRedisConfig>;
+declare const securityInternals: {
+    PendingSecurityLimiterDefinition: typeof PendingSecurityLimiterDefinition;
+    normalizeLimiterAttempts: typeof normalizeLimiterAttempts;
+    normalizeLimiterWindowSeconds: typeof normalizeLimiterWindowSeconds;
+};
+
+export { type SecurityClearRateLimitOptions, type SecurityClientBindings, type SecurityClientConfig, SecurityCsrfError, type SecurityCsrfFacade, type SecurityCsrfField, type SecurityDefaultRateLimitKeyResolver, type SecurityProtectOptions, type SecurityRateLimitBucketSnapshot, type SecurityRateLimitCallOptions, SecurityRateLimitError, type SecurityRateLimitHitResult, type SecurityRateLimitRedisDriverAdapter, type SecurityRateLimitStore, type SecurityRateLimitStoreFactoryOptions, type SecurityRuntimeBindings, type SecurityRuntimeFacade, createFileRateLimitStoreConfig, createMemoryRateLimitStoreConfig, createRedisRateLimitStoreConfig, defineRateLimiter, defineSecurityRuntimeBindings, ip, limit, securityInternals };

package/dist/contracts.mjs

@@ -0,0 +1,24 @@
+import {
+  SecurityCsrfError,
+  SecurityRateLimitError,
+  createFileRateLimitStoreConfig,
+  createMemoryRateLimitStoreConfig,
+  createRedisRateLimitStoreConfig,
+  defineRateLimiter,
+  defineSecurityRuntimeBindings,
+  ip,
+  limit,
+  securityInternals
+} from "./chunk-3J5QRTPZ.mjs";
+export {
+  SecurityCsrfError,
+  SecurityRateLimitError,
+  createFileRateLimitStoreConfig,
+  createMemoryRateLimitStoreConfig,
+  createRedisRateLimitStoreConfig,
+  defineRateLimiter,
+  defineSecurityRuntimeBindings,
+  ip,
+  limit,
+  securityInternals
+};

package/dist/drivers/redis-adapter.d.ts

@@ -0,0 +1,71 @@
+import { NormalizedSecurityRateLimitRedisConfig } from '@holo-js/config';
+import { SecurityRateLimitRedisDriverAdapter } from '../contracts.js';
+
+interface SecurityRedisAdapterOptions {
+    readonly now?: () => Date;
+}
+type RedisClientOptions = {
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly password?: string;
+    readonly username?: string;
+    readonly db?: number;
+    readonly connectionName?: string;
+    readonly lazyConnect: true;
+    readonly maxRetriesPerRequest: number;
+};
+type RedisClusterOptions = {
+    readonly redisOptions: RedisClientOptions;
+};
+type RedisClusterStartupNode = {
+    readonly host: string;
+    readonly port: number;
+    readonly tls?: Record<string, never>;
+};
+declare function isRedisConnectionTarget(value: string): boolean;
+declare function isRedisSocketConnectionTarget(value: string): boolean;
+declare function toRedisSocketPath(value: string): string;
+declare function escapeRedisGlob(value: string): string;
+declare function createRedisClientOptions(config: NormalizedSecurityRateLimitRedisConfig): RedisClientOptions;
+declare function parseClusterNodeUrl(url: string, label: string): RedisClusterStartupNode;
+declare function resolveClusterStartupNodes(config: NormalizedSecurityRateLimitRedisConfig): readonly RedisClusterStartupNode[];
+declare function createRedisClusterOptions(config: NormalizedSecurityRateLimitRedisConfig): RedisClusterOptions;
+declare class RedisSecurityAdapter implements SecurityRateLimitRedisDriverAdapter {
+    private readonly client;
+    private readonly now;
+    private readonly prefix;
+    constructor(config: NormalizedSecurityRateLimitRedisConfig, options?: SecurityRedisAdapterOptions);
+    private qualifyKey;
+    private qualifyPattern;
+    private normalizeScanResponse;
+    private clearMatchingKeys;
+    private parseOldestScore;
+    private getCommandValue;
+    connect(): Promise<void>;
+    increment(key: string, options: {
+        readonly decaySeconds: number;
+    }): Promise<{
+        readonly attempts: number;
+        readonly ttlSeconds: number;
+    }>;
+    del(key: string): Promise<number>;
+    clearByPrefix(prefix: string): Promise<number>;
+    clearAll(): Promise<number>;
+    close(): Promise<void>;
+}
+declare function createSecurityRedisAdapter(config: NormalizedSecurityRateLimitRedisConfig, options?: SecurityRedisAdapterOptions): RedisSecurityAdapter;
+declare const securityRedisAdapterInternals: {
+    REDIS_SCAN_COUNT: number;
+    RedisSecurityAdapter: typeof RedisSecurityAdapter;
+    createRedisClientOptions: typeof createRedisClientOptions;
+    createRedisClusterOptions: typeof createRedisClusterOptions;
+    escapeRedisGlob: typeof escapeRedisGlob;
+    isRedisConnectionTarget: typeof isRedisConnectionTarget;
+    isRedisSocketConnectionTarget: typeof isRedisSocketConnectionTarget;
+    parseClusterNodeUrl: typeof parseClusterNodeUrl;
+    resolveClusterStartupNodes: typeof resolveClusterStartupNodes;
+    toRedisSocketPath: typeof toRedisSocketPath;
+};
+
+export { RedisSecurityAdapter, type SecurityRedisAdapterOptions, createSecurityRedisAdapter, securityRedisAdapterInternals };

package/dist/drivers/redis-adapter.mjs

@@ -0,0 +1,212 @@
+// src/drivers/redis-adapter.ts
+import { randomUUID } from "crypto";
+import Redis from "ioredis";
+var REDIS_SCAN_COUNT = 100;
+function isRedisConnectionTarget(value) {
+  return value.startsWith("redis://") || value.startsWith("rediss://") || value.startsWith("unix://") || value.startsWith("/");
+}
+function isRedisSocketConnectionTarget(value) {
+  return value.startsWith("unix://") || value.startsWith("/");
+}
+function toRedisSocketPath(value) {
+  return value.startsWith("unix://") ? value.slice("unix://".length) : value;
+}
+function escapeRedisGlob(value) {
+  return value.replace(/[\\*?[\]]/g, (match) => `\\${match}`);
+}
+function createRedisClientOptions(config) {
+  return {
+    password: config.password,
+    username: config.username,
+    db: config.db,
+    ...typeof config.url === "undefined" && !isRedisConnectionTarget(config.connection) && !config.clusters?.length && !isRedisSocketConnectionTarget(config.host) ? {
+      host: config.host,
+      port: config.port
+    } : typeof config.url === "undefined" && isRedisSocketConnectionTarget(config.host) && !config.clusters?.length ? { path: toRedisSocketPath(config.host) } : {},
+    ...typeof config.url === "undefined" && config.connection !== "default" && !isRedisConnectionTarget(config.connection) && !config.clusters?.length ? { connectionName: config.connection } : {},
+    lazyConnect: true,
+    maxRetriesPerRequest: 3
+  };
+}
+function parseClusterNodeUrl(url, label) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+      throw new Error(`unsupported protocol "${parsed.protocol}"`);
+    }
+    if (!parsed.hostname) {
+      throw new Error("missing hostname");
+    }
+    return {
+      host: parsed.hostname,
+      port: parsed.port ? Number.parseInt(parsed.port, 10) : 6379,
+      ...parsed.protocol === "rediss:" ? { tls: {} } : {}
+    };
+  } catch (error) {
+    throw new Error(`[@holo-js/security] ${label} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function resolveClusterStartupNodes(config) {
+  return (config.clusters ?? []).map((node, index) => {
+    const label = `Security rate-limit Redis cluster node ${index + 1}`;
+    if (typeof node.url === "string") {
+      return parseClusterNodeUrl(node.url, `${label} url`);
+    }
+    if (isRedisSocketConnectionTarget(node.host)) {
+      throw new Error(`[@holo-js/security] ${label} cannot use a Unix socket path in Redis cluster mode.`);
+    }
+    return {
+      host: node.host,
+      port: node.port
+    };
+  });
+}
+function createRedisClusterOptions(config) {
+  if (typeof config.db === "number" && config.db !== 0) {
+    throw new Error("[@holo-js/security] Redis Cluster does not support selecting a non-zero database. Remove redis.db or set it to 0.");
+  }
+  const startupNodes = resolveClusterStartupNodes(config);
+  return {
+    redisOptions: {
+      password: config.password,
+      username: config.username,
+      lazyConnect: true,
+      maxRetriesPerRequest: 3,
+      ...startupNodes.some((node) => typeof node.tls !== "undefined") ? { tls: {} } : {}
+    }
+  };
+}
+var RedisSecurityAdapter = class {
+  client;
+  now;
+  prefix;
+  constructor(config, options = {}) {
+    this.prefix = config.prefix;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    const clientOptions = createRedisClientOptions(config);
+    const RedisConstructor = Redis;
+    this.client = typeof config.url === "string" ? new RedisConstructor(config.url, clientOptions) : config.clusters && config.clusters.length > 0 ? new RedisConstructor.Cluster(resolveClusterStartupNodes(config), createRedisClusterOptions(config)) : isRedisConnectionTarget(config.connection) ? new RedisConstructor(config.connection, clientOptions) : new RedisConstructor(clientOptions);
+  }
+  qualifyKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  qualifyPattern(pattern) {
+    return `${escapeRedisGlob(this.prefix)}${pattern}`;
+  }
+  normalizeScanResponse(result) {
+    if (!Array.isArray(result) || result.length < 2) {
+      throw new Error("[@holo-js/security] Redis returned an invalid scan response while clearing rate-limit buckets.");
+    }
+    const [cursor, keys] = result;
+    if (typeof cursor !== "string" || !Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
+      throw new Error("[@holo-js/security] Redis returned an invalid scan response while clearing rate-limit buckets.");
+    }
+    return {
+      cursor,
+      keys
+    };
+  }
+  async clearMatchingKeys(pattern) {
+    let cursor = "0";
+    let cleared = 0;
+    do {
+      const page = this.normalizeScanResponse(await this.client.scan(
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        REDIS_SCAN_COUNT
+      ));
+      cursor = page.cursor;
+      if (page.keys.length > 0) {
+        cleared += await this.client.del(...page.keys);
+      }
+    } while (cursor !== "0");
+    return cleared;
+  }
+  parseOldestScore(result) {
+    if (!Array.isArray(result) || result.length < 2) {
+      throw new Error("[@holo-js/security] Redis transaction failed to return the oldest rate-limit hit.");
+    }
+    const value = result[1];
+    const score = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number.NaN;
+    if (!Number.isFinite(score)) {
+      throw new Error("[@holo-js/security] Redis transaction returned an invalid oldest-hit score.");
+    }
+    return score;
+  }
+  getCommandValue(result, index, operation) {
+    const entry = result[index];
+    if (!entry) {
+      throw new Error(`[@holo-js/security] Redis transaction failed to return the ${operation}.`);
+    }
+    const [error, value] = entry;
+    if (error instanceof Error) {
+      throw error;
+    }
+    if (error) {
+      throw new Error(`[@holo-js/security] Redis transaction failed for ${operation}: ${String(error)}`);
+    }
+    return value;
+  }
+  async connect() {
+    await this.client.connect();
+  }
+  async increment(key, options) {
+    const now = this.now().getTime();
+    const ttlMs = options.decaySeconds * 1e3;
+    const qualifiedKey = this.qualifyKey(key);
+    const member = `${now}:${randomUUID()}`;
+    const result = await this.client.multi().zadd(qualifiedKey, now, member).zremrangebyscore(qualifiedKey, "-inf", now - ttlMs).zcard(qualifiedKey).zrange(qualifiedKey, 0, 0, "WITHSCORES").exec();
+    if (!result) {
+      throw new Error("[@holo-js/security] Redis transaction failed for increment.");
+    }
+    const attemptsValue = this.getCommandValue(result, 2, "attempt count");
+    if (typeof attemptsValue !== "number") {
+      throw new Error("[@holo-js/security] Redis transaction returned an invalid attempt count.");
+    }
+    const attempts = attemptsValue;
+    const oldestScore = this.parseOldestScore(this.getCommandValue(result, 3, "oldest rate-limit hit"));
+    await this.client.pexpireat(qualifiedKey, now + ttlMs);
+    const ttlSeconds = Math.max(0, Math.ceil((oldestScore + ttlMs - now) / 1e3));
+    return { attempts, ttlSeconds };
+  }
+  async del(key) {
+    return this.client.del(this.qualifyKey(key));
+  }
+  async clearByPrefix(prefix) {
+    const basePrefix = prefix.endsWith("*") ? prefix.slice(0, -1) : prefix;
+    const pattern = this.qualifyPattern(`${escapeRedisGlob(basePrefix)}*`);
+    return await this.clearMatchingKeys(pattern);
+  }
+  async clearAll() {
+    return await this.clearMatchingKeys(this.qualifyPattern("*"));
+  }
+  async close() {
+    try {
+      await this.client.quit();
+    } catch {
+      this.client.disconnect();
+    }
+  }
+};
+function createSecurityRedisAdapter(config, options) {
+  return new RedisSecurityAdapter(config, options);
+}
+var securityRedisAdapterInternals = {
+  REDIS_SCAN_COUNT,
+  RedisSecurityAdapter,
+  createRedisClientOptions,
+  createRedisClusterOptions,
+  escapeRedisGlob,
+  isRedisConnectionTarget,
+  isRedisSocketConnectionTarget,
+  parseClusterNodeUrl,
+  resolveClusterStartupNodes,
+  toRedisSocketPath
+};
+export {
+  RedisSecurityAdapter,
+  createSecurityRedisAdapter,
+  securityRedisAdapterInternals
+};