@holo-js/security 0.3.28 → 0.4.0

package/dist/{chunk-26IYURJG.mjs → chunk-RYQLS2OO.mjs}

@@ -1,19 +1,24 @@
+import {
+  SECURITY_XSRF_HEADER
+} from "./chunk-EINZXLC2.mjs";
 import {
   SecurityCsrfError,
   SecurityRateLimitError,
-  ip,
   limit
-} from "./chunk-FQ4X7X6L.mjs";
+} from "./chunk-U25HSHLJ.mjs";
 import {
+  createForwardedRequestResolver,
   normalizeCorsConfig,
-  normalizeSecurityConfig
-} from "./chunk-WRMZRO77.mjs";
+  normalizeSecurityConfig,
+  normalizeTrustedProxies,
+  resolveForwarding
+} from "./chunk-D3ZN5MLJ.mjs";
 
-// src/csrf.ts
-import { resolveRequestUrl } from "@holo-js/kernel";
-import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+// src/proxy.ts
+import { requestUrlInternals as requestUrlInternals2 } from "@holo-js/kernel";
 
 // src/runtime.ts
+import { requestBodyInternals, requestUrlInternals } from "@holo-js/kernel";
 function getSecurityRuntimeState() {
   const runtime = globalThis;
   runtime.__holoSecurityRuntime__ ??= {};
@@ -25,11 +30,16 @@ var SecurityRuntimeNotConfiguredError = class extends Error {
   }
 };
 function configureSecurityRuntime(bindings) {
-  getSecurityRuntimeState().bindings = bindings ? Object.freeze({
-    config: normalizeSecurityConfig(bindings.config),
+  const config = bindings ? normalizeSecurityConfig(bindings.config) : void 0;
+  requestUrlInternals.configureForwardedRequestResolver(config ? createForwardedRequestResolver(config.trustedProxies) : void 0);
+  requestBodyInternals.configureMaxRequestBodyBytes(config?.maxBodyBytes);
+  requestBodyInternals.configureMaxUploadBodyBytes(config?.maxUploadBodyBytes);
+  getSecurityRuntimeState().bindings = bindings && config ? Object.freeze({
+    config,
     cors: normalizeCorsConfig(bindings.cors),
     rateLimitStore: bindings.rateLimitStore,
     csrfSigningKey: bindings.csrfSigningKey,
+    csrfSession: bindings.csrfSession,
     defaultKeyResolver: bindings.defaultKeyResolver
   }) : void 0;
 }
@@ -44,6 +54,9 @@ function getSecurityRuntimeBindings() {
   return getSecurityRuntimeState().bindings;
 }
 function resetSecurityRuntime() {
+  requestUrlInternals.configureForwardedRequestResolver(void 0);
+  requestBodyInternals.configureMaxRequestBodyBytes(void 0);
+  requestBodyInternals.configureMaxUploadBodyBytes(void 0);
   getSecurityRuntimeState().bindings = void 0;
 }
 var securityRuntimeInternals = {
@@ -51,24 +64,27 @@ var securityRuntimeInternals = {
 };
 
 // src/proxy.ts
-import { isIP } from "net";
-import { requestUrlInternals } from "@holo-js/kernel";
-function bareClientAddress(value) {
-  if (!value) return void 0;
-  if (isIP(value)) return value;
-  const bracketed = /^\[([^\]]+)\](?::\d+)?$/u.exec(value)?.[1];
-  if (bracketed && isIP(bracketed) === 6) return bracketed;
-  const ipv4 = /^([\d.]+):\d+$/u.exec(value)?.[1];
-  return ipv4 && isIP(ipv4) === 4 ? ipv4 : void 0;
-}
-function resolveTrustedClientIp(request) {
-  const trustedProxyHeaders = requestUrlInternals.resolveTrustedProxyHeaders();
-  if (trustedProxyHeaders === "forwarded") {
-    return bareClientAddress(requestUrlInternals.readForwardedParameter(request.headers, "for")) ?? "unknown";
-  }
-  return ip(request, trustedProxyHeaders === "x-forwarded");
+var SecurityClientAddressUnavailableError = class extends Error {
+  constructor() {
+    super("[@holo-js/security] The client address is unavailable because this framework does not expose the connection address, so an address or CIDR list in trustedProxies can never match. Only '*' works here, and only behind a proxy that overwrites X-Forwarded-For, such as Vercel's edge, or a reverse proxy with the Next.js server bound to localhost or a private network. Set trustedProxies in config/security.ts to '*' (scaffolded apps read it from TRUSTED_PROXIES). If the app doesn't need IP identity, pass an explicit rate-limit key instead. See https://docs.holo-js.com/basics/security/cors-and-proxies#trusted-proxies");
+    this.name = "SecurityClientAddressUnavailableError";
+  }
+};
+function ip(request) {
+  const trustedProxies = getSecurityRuntimeBindings()?.config.trustedProxies ?? normalizeTrustedProxies(void 0);
+  const { address } = resolveForwarding(
+    (name) => request.headers.get(name) ?? void 0,
+    requestUrlInternals2.currentConnectionAddress(),
+    trustedProxies
+  );
+  if (!address) throw new SecurityClientAddressUnavailableError();
+  return address;
 }
 
+// src/csrf.ts
+import { cookieEncryptionInternals, HoloRequestBodyTooLargeError, readBoundedRequestBody, resolveRequestUrl } from "@holo-js/kernel";
+import { randomBytes, timingSafeEqual } from "crypto";
+
 // src/rate-limit.ts
 function encodeBucketPart(value) {
   return encodeURIComponent(value);
@@ -107,7 +123,7 @@ async function defaultRateLimitKey(request) {
   if (typeof runtimeDefaultKey !== "undefined" && runtimeDefaultKey !== null) {
     return normalizeResolvedLimiterKey(runtimeDefaultKey, "Default rate limiter key resolver");
   }
-  return `ip:${resolveTrustedClientIp(request)}`;
+  return `ip:${ip(request)}`;
 }
 async function resolveLimiterKey(name, limiter, options) {
   if (typeof options.key === "string" && options.key.length > 0) {
@@ -185,32 +201,8 @@ var rateLimitInternals = {
 };
 
 // src/csrf.ts
-var generatedTokenCache = /* @__PURE__ */ new WeakMap();
-function parseCookieHeader(header) {
-  if (!header) {
-    return Object.freeze({});
-  }
-  const decodeCookiePart = (value) => {
-    try {
-      return decodeURIComponent(value);
-    } catch {
-      return void 0;
-    }
-  };
-  const entries = header.split(";").map((segment) => segment.trim()).filter(Boolean).map((segment) => {
-    const separator = segment.indexOf("=");
-    if (separator <= 0) {
-      return void 0;
-    }
-    const key = decodeCookiePart(segment.slice(0, separator));
-    const value = decodeCookiePart(segment.slice(separator + 1));
-    if (!key || typeof value === "undefined") {
-      return void 0;
-    }
-    return [key, value];
-  }).filter((entry) => !!entry);
-  return Object.freeze(Object.fromEntries(entries));
-}
+var requestTokenCache = /* @__PURE__ */ new WeakMap();
+var persistedTokens = /* @__PURE__ */ new WeakMap();
 function serializeCookie(name, value, options = {}) {
   const attributes = [
     `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
@@ -244,59 +236,84 @@ function isSecureRequest(request) {
 function createCsrfToken() {
   return randomBytes(32).toString("base64url");
 }
-function getCsrfSigningKey() {
-  const configured = getSecurityRuntime().csrfSigningKey?.trim();
-  if (configured) {
-    return configured;
-  }
-  throw new Error("[@holo-js/security] CSRF signing key is not configured.");
+function csrfCookieName() {
+  return getSecurityRuntime().config.csrf.cookie;
 }
-function signCsrfNonce(nonce) {
-  return createHmac("sha256", getCsrfSigningKey()).update(nonce).digest("base64url");
+function encryptCsrfToken(token2) {
+  return cookieEncryptionInternals.encryptCookieValue(csrfCookieName(), token2, getSecurityRuntime().csrfSigningKey);
 }
-function encodeCsrfToken(nonce) {
-  return `${nonce}.${signCsrfNonce(nonce)}`;
+function decryptCsrfToken(value) {
+  return cookieEncryptionInternals.decryptCookieValue(csrfCookieName(), value, getSecurityRuntime().csrfSigningKey);
 }
-function decodeCsrfToken(token2) {
-  const separator = token2.lastIndexOf(".");
-  if (separator <= 0 || separator === token2.length - 1) {
-    return null;
+function tokensMatch(expected, submitted) {
+  if (!submitted) {
+    return false;
   }
-  return Object.freeze({
-    nonce: token2.slice(0, separator),
-    signature: token2.slice(separator + 1)
-  });
+  const expectedBytes = Buffer.from(expected);
+  const submittedBytes = Buffer.from(submitted);
+  return expectedBytes.length === submittedBytes.length && timingSafeEqual(expectedBytes, submittedBytes);
 }
-function isValidSignedCsrfToken(token2) {
-  const decoded = decodeCsrfToken(token2);
-  if (!decoded) {
-    return false;
+function csrfSession() {
+  const session = getSecurityRuntime().csrfSession;
+  if (!session) {
+    throw new Error("[@holo-js/security] CSRF protection requires a session. Install and configure @holo-js/session.");
   }
-  const expected = Buffer.from(signCsrfNonce(decoded.nonce));
-  const received = Buffer.from(decoded.signature);
-  if (expected.length !== received.length) {
-    return false;
+  return session;
+}
+async function readSessionToken(request) {
+  const stored = await csrfSession().read(request);
+  if (stored) {
+    persistedTokens.set(request, stored);
   }
-  return timingSafeEqual(expected, received);
+  return stored;
 }
-function getCookieToken(request) {
-  const { cookie: cookie2 } = getSecurityRuntime().config.csrf;
-  return parseCookieHeader(request.headers.get("cookie"))[cookie2];
+async function getSessionToken(request) {
+  return persistedTokens.get(request) ?? requestTokenCache.get(request) ?? await readSessionToken(request);
 }
 function getHeaderToken(request) {
   const { header } = getSecurityRuntime().config.csrf;
+  if (header.toLowerCase() === SECURITY_XSRF_HEADER.toLowerCase()) {
+    return void 0;
+  }
   return request.headers.get(header)?.trim() || void 0;
 }
-async function readFormToken(request) {
-  const { field: field2 } = getSecurityRuntime().config.csrf;
+function getXsrfHeaderToken(request) {
+  const value = request.headers.get(SECURITY_XSRF_HEADER)?.trim();
+  return value ? decryptCsrfToken(value) : void 0;
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+async function readBodyBytes(request) {
   try {
-    const formData = await request.clone().formData();
-    const value = formData.get(field2);
-    return typeof value === "string" ? value : void 0;
+    return await readBoundedRequestBody(request.clone());
+  } catch (error) {
+    if (error instanceof HoloRequestBodyTooLargeError) throw error;
+    return void 0;
+  }
+}
+async function readBodyToken(request, field2) {
+  const contentType = request.headers.get("content-type") ?? "";
+  const bytes = await readBodyBytes(request);
+  if (!bytes) return void 0;
+  try {
+    if (/[/+]json\b/i.test(contentType)) {
+      const body = JSON.parse(new TextDecoder().decode(bytes));
+      return body && typeof body === "object" && !Array.isArray(body) && Object.hasOwn(body, field2) ? nonEmptyString(body[field2]) : void 0;
+    }
+    return nonEmptyString((await new Response(bytes, { headers: { "content-type": contentType } }).formData()).get(field2));
   } catch {
     return void 0;
   }
 }
+async function readInputToken(request) {
+  const { field: field2 } = getSecurityRuntime().config.csrf;
+  return await readBodyToken(request, field2) ?? nonEmptyString(new URL(request.url).searchParams.get(field2));
+}
+async function getSubmittedToken(request) {
+  const token2 = await readInputToken(request) ?? getHeaderToken(request);
+  return token2 ? decryptCsrfToken(token2) ?? token2 : getXsrfHeaderToken(request);
+}
 async function verifyRequest(request, options) {
   if (isSafeMethod(request.method)) {
     return;
@@ -304,21 +321,21 @@ async function verifyRequest(request, options) {
   if (options.allowExcludedPath && isExcludedPath(request)) {
     return;
   }
-  const cookieToken = getCookieToken(request);
-  if (!cookieToken || !isValidSignedCsrfToken(cookieToken)) {
+  const sessionToken = await getSessionToken(request);
+  if (!sessionToken || !tokensMatch(sessionToken, await getSubmittedToken(request))) {
     throw new SecurityCsrfError();
   }
-  const headerToken = getHeaderToken(request);
-  if (headerToken) {
-    if (headerToken !== cookieToken) {
-      throw new SecurityCsrfError();
-    }
-    return;
-  }
-  const requestToken = await readFormToken(request);
-  if (requestToken !== cookieToken) {
-    throw new SecurityCsrfError();
+}
+async function ensureSessionToken(request) {
+  const stored = persistedTokens.get(request) ?? await readSessionToken(request);
+  if (stored) {
+    return { token: stored, sessionCookies: [] };
   }
+  const token2 = requestTokenCache.get(request) ?? createCsrfToken();
+  const written = await csrfSession().write(request, token2);
+  requestTokenCache.set(request, written.token);
+  persistedTokens.set(request, written.token);
+  return { token: written.token, sessionCookies: written.cookies };
 }
 function resolveShouldProtect(request, options = {}) {
   if (options.csrf === false) {
@@ -340,16 +357,12 @@ function resolveShouldProtect(request, options = {}) {
   return true;
 }
 async function token(request) {
-  const cookieToken = getCookieToken(request);
-  if (cookieToken && isValidSignedCsrfToken(cookieToken)) {
-    return cookieToken;
+  const sessionToken = await getSessionToken(request);
+  if (sessionToken) {
+    return sessionToken;
   }
-  const cached = generatedTokenCache.get(request);
-  if (cached) {
-    return cached;
-  }
-  const created = encodeCsrfToken(createCsrfToken());
-  generatedTokenCache.set(request, created);
+  const created = createCsrfToken();
+  requestTokenCache.set(request, created);
   return created;
 }
 async function field(request) {
@@ -367,10 +380,11 @@ async function input(request) {
     value: csrfField.value
   });
 }
+async function encryptedToken(request, explicitToken) {
+  return encryptCsrfToken(explicitToken || await token(request));
+}
 async function cookie(request, explicitToken) {
-  const config = getSecurityRuntime().config.csrf;
-  const value = explicitToken ? isValidSignedCsrfToken(explicitToken) ? explicitToken : encodeCsrfToken(explicitToken) : await token(request);
-  return serializeCookie(config.cookie, value, {
+  return serializeCookie(csrfCookieName(), await encryptedToken(request, explicitToken), {
     secure: isSecureRequest(request)
   });
 }
@@ -394,22 +408,24 @@ var csrf = Object.freeze({
   cookie,
   verify
 });
+function rememberSessionToken(request, token2) {
+  persistedTokens.set(request, token2);
+}
 var csrfInternals = {
   createCsrfToken,
-  generatedTokenCache,
-  getCookieToken,
+  rememberSessionToken,
+  ensureSessionToken,
+  requestTokenCache,
   getHeaderToken,
+  getXsrfHeaderToken,
   isSecureRequest,
-  readFormToken,
+  readInputToken,
   isExcludedPath,
   isSafeMethod,
   matchesPathPattern,
-  parseCookieHeader,
   serializeCookie,
-  decodeCsrfToken,
-  encodeCsrfToken,
-  getCsrfSigningKey,
-  isValidSignedCsrfToken
+  decryptCsrfToken,
+  encryptCsrfToken
 };
 
 // src/cors.ts
@@ -465,7 +481,7 @@ function resolveAllowedOrigin(config, origin) {
     return origin;
   }
   if (config.origins.includes("*")) {
-    return config.credentials ? origin : "*";
+    return "*";
   }
   return void 0;
 }
@@ -552,30 +568,37 @@ import { resolve } from "path";
 
 // src/drivers/file.ts
 import { createHash, randomUUID } from "crypto";
-import { mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "fs/promises";
+import { mkdir, opendir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "fs/promises";
 import { dirname, join } from "path";
+import { reportError } from "@holo-js/kernel/error-reporting";
 var LOCK_OWNER_FILE = "owner";
 var BUCKETS_DIRECTORY = "buckets";
+var PRUNE_INTERVAL_MS = 6e4;
+var SWEEP_BATCH_SIZE = 1e3;
 function createBucketHash(key) {
   return createHash("sha256").update(key).digest("hex");
 }
-function createBucketNamespace(key) {
-  const separatorIndex = key.indexOf("|");
-  return separatorIndex >= 0 ? key.slice(0, separatorIndex + 1) : key;
-}
-function createBucketNamespaceHash(key) {
-  return createBucketHash(createBucketNamespace(key));
-}
-function createBucketPrefixHashes(key) {
+function hashBucketKey(key, keyHash) {
+  const hash = createHash("sha256");
   const prefixHashes = [];
-  for (let index = 1; index <= key.length; index += 1) {
-    prefixHashes.push(createBucketHash(key.slice(0, index)));
+  let namespaceHash;
+  let prefixLength = 0;
+  for (const character of key) {
+    hash.update(character);
+    prefixLength += character.length;
+    const prefixHash = prefixLength === key.length ? keyHash : hash.copy().digest("hex");
+    prefixHashes.push(prefixHash);
+    if (namespaceHash === void 0 && character === "|") {
+      namespaceHash = prefixHash;
+    }
   }
-  return prefixHashes;
+  return Object.freeze({
+    namespaceHash: namespaceHash ?? keyHash,
+    prefixHashes: Object.freeze(prefixHashes)
+  });
 }
-function getBucketPath(root, key) {
-  const hash = createBucketHash(key);
-  return join(root, BUCKETS_DIRECTORY, hash.slice(0, 2), hash.slice(2, 4), `${hash}.json`);
+function getBucketPathForKeyHash(root, keyHash) {
+  return join(root, BUCKETS_DIRECTORY, keyHash.slice(0, 2), keyHash.slice(2, 4), `${keyHash}.json`);
 }
 function serializeBucket(bucket) {
   return JSON.stringify({
@@ -727,12 +750,42 @@ async function acquireBucketLock(lockPath, options) {
         continue;
       }
       if (Date.now() >= deadline) {
-        throw new Error(`[@holo-js/security] Timed out waiting for file rate-limit lock "${lockPath}".`);
+        throw new Error(`[@holo-js/security] Timed out waiting for file rate-limit lock "${lockPath}".`, { cause: error });
       }
       await sleep(options.retryDelayMs);
     }
   }
 }
+async function withBucketLockIfFree(path, options, operation) {
+  const lockPath = getBucketLockPath(path);
+  await mkdir(dirname(lockPath), { recursive: true });
+  let lock;
+  try {
+    lock = await tryCreateBucketLock(lockPath);
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+    if (!await isBucketLockStale(lockPath, options.timeoutMs) || !await reclaimStaleBucketLock(lockPath, options.timeoutMs)) {
+      return void 0;
+    }
+    try {
+      lock = await tryCreateBucketLock(lockPath);
+    } catch (retryError) {
+      if (retryError.code === "EEXIST") {
+        return void 0;
+      }
+      throw retryError;
+    }
+  }
+  const heartbeat = startLockHeartbeat(lockPath, options.timeoutMs);
+  try {
+    return await operation();
+  } finally {
+    clearInterval(heartbeat);
+    await removeOwnedBucketLock(lock);
+  }
+}
 async function withBucketLock(path, options, operation) {
   const lockPath = getBucketLockPath(path);
   await mkdir(dirname(lockPath), { recursive: true });
@@ -745,21 +798,92 @@ async function withBucketLock(path, options, operation) {
     await removeOwnedBucketLock(acquiredLock);
   }
 }
-async function listBucketPaths(root) {
-  const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+var UNIT_STEP = { kind: "unit" };
+function* chargeUnits(count) {
+  for (let index = 0; index < count; index += 1) {
+    yield UNIT_STEP;
+  }
+}
+async function readShardEntries(directory, onUnreadable) {
+  try {
+    return await readdir(directory, { withFileTypes: true });
+  } catch (error) {
     if (error.code === "ENOENT") {
-      return [];
+      return void 0;
     }
-    throw error;
-  });
-  const nested = await Promise.all(entries.map(async (entry) => {
-    const entryPath = join(root, entry.name);
-    if (entry.isDirectory()) {
-      return await listBucketPaths(entryPath);
+    if (!onUnreadable) {
+      throw error;
+    }
+    onUnreadable(directory, error);
+    return void 0;
+  }
+}
+async function* readShardListing(directory, onUnreadable) {
+  yield UNIT_STEP;
+  const entries = await readShardEntries(directory, onUnreadable);
+  yield* chargeUnits(entries?.length ?? 0);
+  yield UNIT_STEP;
+  if (!entries) {
+    return void 0;
+  }
+  return {
+    names: entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort()
+  };
+}
+async function openShard(directory, onUnreadable) {
+  try {
+    return await opendir(directory);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    if (!onUnreadable) {
+      throw error;
+    }
+    onUnreadable(directory, error);
+    return void 0;
+  }
+}
+async function readShardEntry(handle, directory, onUnreadable) {
+  try {
+    return await handle.read();
+  } catch (error) {
+    if (!onUnreadable) {
+      throw error;
     }
-    return entry.name.endsWith(".json") ? [entryPath] : [];
-  }));
-  return nested.flat();
+    onUnreadable(directory, error);
+    return null;
+  }
+}
+async function* walkBucketTree(bucketsRoot, onUnreadable) {
+  const tops = yield* readShardListing(bucketsRoot, onUnreadable);
+  for (const top of tops?.names ?? []) {
+    const topPath = join(bucketsRoot, top);
+    const middles = yield* readShardListing(topPath, onUnreadable);
+    for (const middle of middles?.names ?? []) {
+      const leaf = join(topPath, middle);
+      yield UNIT_STEP;
+      const handle = await openShard(leaf, onUnreadable);
+      if (!handle) {
+        continue;
+      }
+      try {
+        for (let entry = await readShardEntry(handle, leaf, onUnreadable); entry !== null; entry = await readShardEntry(handle, leaf, onUnreadable)) {
+          yield entry.isFile() && entry.name.endsWith(".json") ? { kind: "bucket", path: join(leaf, entry.name) } : UNIT_STEP;
+        }
+      } finally {
+        await handle.close().catch(() => void 0);
+      }
+      yield UNIT_STEP;
+    }
+  }
+}
+async function* bucketFilePaths(bucketsRoot) {
+  for await (const step of walkBucketTree(bucketsRoot)) {
+    if (step.kind === "bucket") {
+      yield step.path;
+    }
+  }
 }
 function createSnapshot(key, bucket, maxAttempts) {
   const expiresAt = new Date(bucket.expiresAt.getTime());
@@ -776,16 +900,96 @@ function createFileRateLimitStore(root, options = {}) {
   const resolveNow = options.now ?? (() => /* @__PURE__ */ new Date());
   const lockRetryDelayMs = options.lockRetryDelayMs ?? 5;
   const lockTimeoutMs = options.lockTimeoutMs ?? 2e3;
-  return {
+  const lockOptions = {
+    retryDelayMs: lockRetryDelayMs,
+    timeoutMs: lockTimeoutMs
+  };
+  const bucketsRoot = join(root, BUCKETS_DIRECTORY);
+  let cycleStartedAt;
+  let cursor;
+  let inFlight;
+  let closed = false;
+  const reportSweepError = (error) => {
+    reportError(error, { capability: "security", operation: "rate-limit expired-bucket sweep" });
+  };
+  const reportedUnreadable = /* @__PURE__ */ new Set();
+  const reportUnreadable = (directory, error) => {
+    if (reportedUnreadable.has(directory)) {
+      return;
+    }
+    reportedUnreadable.add(directory);
+    reportSweepError(error);
+  };
+  const sweepBucket = async (path, now) => {
+    try {
+      const candidate = await readBucket(path);
+      if (!candidate || !isExpired(candidate, now)) {
+        return;
+      }
+      await withBucketLockIfFree(path, { timeoutMs: lockTimeoutMs }, async () => {
+        const bucket = await readBucket(path);
+        if (bucket && isExpired(bucket, now)) {
+          await deleteBucket(path);
+        }
+      });
+    } catch (error) {
+      reportSweepError(error);
+    }
+  };
+  const closeCursor = async () => {
+    const current = cursor;
+    cursor = void 0;
+    await current?.return(void 0);
+  };
+  const runSweep = async (now) => {
+    let units = 0;
+    let finished = false;
+    try {
+      cursor ??= walkBucketTree(bucketsRoot, reportUnreadable);
+      while (units < SWEEP_BATCH_SIZE && !closed) {
+        const next = await cursor.next();
+        if (next.done) {
+          finished = true;
+          break;
+        }
+        units += 1;
+        if (next.value.kind === "bucket") {
+          await sweepBucket(next.value.path, now);
+        }
+      }
+    } catch (error) {
+      reportSweepError(error);
+      finished = true;
+    } finally {
+      if (finished || closed) {
+        await closeCursor();
+      }
+    }
+  };
+  const startSweepIfDue = (now) => {
+    if (closed || inFlight !== void 0) {
+      return;
+    }
+    if (cursor === void 0) {
+      if (cycleStartedAt !== void 0 && now.getTime() - cycleStartedAt < PRUNE_INTERVAL_MS) {
+        return;
+      }
+      cycleStartedAt = now.getTime();
+    }
+    inFlight = runSweep(now).finally(() => {
+      inFlight = void 0;
+    });
+  };
+  const store = {
     async hit(key, hitOptions) {
-      const now = resolveNow();
-      const path = getBucketPath(root, key);
-      return await withBucketLock(path, {
-        retryDelayMs: lockRetryDelayMs,
-        timeoutMs: lockTimeoutMs
-      }, async () => {
+      const sweepNow = resolveNow();
+      const keyHash = createBucketHash(key);
+      const path = getBucketPathForKeyHash(root, keyHash);
+      startSweepIfDue(sweepNow);
+      return await withBucketLock(path, lockOptions, async () => {
         const existing = await readBucket(path);
-        if (existing && existing.keyHash !== createBucketHash(key)) {
+        const now = resolveNow();
+        if (existing && existing.keyHash !== keyHash) {
           throw new Error(`[@holo-js/security] File rate-limit bucket hash collision detected for stored bucket ${existing.keyHash}.`);
         }
         if (existing && isExpired(existing, now)) {
@@ -795,9 +999,8 @@ function createFileRateLimitStore(root, options = {}) {
           ...existing,
           attempts: existing.attempts + 1
         } : {
-          namespaceHash: createBucketNamespaceHash(key),
-          keyHash: createBucketHash(key),
-          prefixHashes: Object.freeze(createBucketPrefixHashes(key)),
+          ...hashBucketKey(key, keyHash),
+          keyHash,
           attempts: 1,
           expiresAt: new Date(now.getTime() + hitOptions.decaySeconds * 1e3)
         };
@@ -810,13 +1013,11 @@ function createFileRateLimitStore(root, options = {}) {
       });
     },
     async clear(key) {
-      const path = getBucketPath(root, key);
-      return await withBucketLock(path, {
-        retryDelayMs: lockRetryDelayMs,
-        timeoutMs: lockTimeoutMs
-      }, async () => {
+      const keyHash = createBucketHash(key);
+      const path = getBucketPathForKeyHash(root, keyHash);
+      return await withBucketLock(path, lockOptions, async () => {
         const existing = await readBucket(path);
-        if (!existing || existing.keyHash !== createBucketHash(key)) {
+        if (!existing || existing.keyHash !== keyHash) {
           return false;
         }
         await deleteBucket(path);
@@ -826,12 +1027,9 @@ function createFileRateLimitStore(root, options = {}) {
     async clearByPrefix(prefix) {
       let cleared = 0;
       const now = resolveNow();
-      const paths = await listBucketPaths(root);
-      for (const path of paths) {
-        const removed = await withBucketLock(path, {
-          retryDelayMs: lockRetryDelayMs,
-          timeoutMs: lockTimeoutMs
-        }, async () => {
+      const prefixHash = createBucketHash(prefix);
+      for await (const path of bucketFilePaths(bucketsRoot)) {
+        const removed = await withBucketLock(path, lockOptions, async () => {
           const bucket = await readBucket(path);
           if (!bucket) {
             return false;
@@ -840,7 +1038,7 @@ function createFileRateLimitStore(root, options = {}) {
             await deleteBucket(path);
             return false;
           }
-          if (!bucket.prefixHashes.includes(createBucketHash(prefix))) {
+          if (!bucket.prefixHashes.includes(prefixHash)) {
             return false;
           }
           await deleteBucket(path);
@@ -853,13 +1051,9 @@ function createFileRateLimitStore(root, options = {}) {
       return cleared;
     },
     async clearAll() {
-      const paths = await listBucketPaths(root);
       let cleared = 0;
-      for (const path of paths) {
-        const removed = await withBucketLock(path, {
-          retryDelayMs: lockRetryDelayMs,
-          timeoutMs: lockTimeoutMs
-        }, async () => {
+      for await (const path of bucketFilePaths(bucketsRoot)) {
+        const removed = await withBucketLock(path, lockOptions, async () => {
           const bucket = await readBucket(path);
           if (!bucket) {
             return false;
@@ -872,29 +1066,19 @@ function createFileRateLimitStore(root, options = {}) {
         }
       }
       return cleared;
+    },
+    async close() {
+      closed = true;
+      await inFlight;
+      await closeCursor();
     }
   };
+  return store;
 }
-var fileRateLimitDriverInternals = {
-  createBucketHash,
-  createSnapshot,
-  deleteBucket,
-  deserializeBucket,
-  getBucketPath,
-  isExpired,
-  listBucketPaths,
-  readBucket,
-  serializeBucket,
-  sleep,
-  getBucketLockPath,
-  acquireBucketLock,
-  reclaimStaleBucketLock,
-  removeOwnedBucketLock,
-  withBucketLock,
-  writeBucket
-};
 
 // src/drivers/memory.ts
+import { reportError as reportError2 } from "@holo-js/kernel/error-reporting";
+var DEFAULT_MEMORY_MAX_BUCKETS = 1e4;
 function createSnapshot2(key, bucket, maxAttempts) {
   const expiresAt = new Date(bucket.expiresAt.getTime());
   return Object.freeze({
@@ -912,27 +1096,41 @@ function isExpired2(bucket, now) {
 function createMemoryRateLimitStore(options = {}) {
   const buckets = /* @__PURE__ */ new Map();
   const resolveNow = options.now ?? (() => /* @__PURE__ */ new Date());
-  const maxBuckets = options.maxBuckets;
-  if (typeof maxBuckets !== "undefined" && (!Number.isInteger(maxBuckets) || maxBuckets < 1)) {
+  const maxBuckets = options.maxBuckets ?? DEFAULT_MEMORY_MAX_BUCKETS;
+  if (!Number.isInteger(maxBuckets) || maxBuckets < 1) {
     throw new TypeError("[@holo-js/security] Memory rate-limit store maxBuckets must be an integer greater than or equal to 1.");
   }
   const pruneIntervalMs = typeof options.pruneIntervalMs === "number" ? options.pruneIntervalMs : 6e4;
   if (!Number.isInteger(pruneIntervalMs) || pruneIntervalMs < 1) {
     throw new TypeError("[@holo-js/security] Memory rate-limit store pruneIntervalMs must be an integer greater than or equal to 1.");
   }
-  const pruneExpiredBuckets = () => {
-    const now = resolveNow();
+  let nextExpiryAt = Number.POSITIVE_INFINITY;
+  const refreshNextExpiry = () => {
+    nextExpiryAt = Number.POSITIVE_INFINITY;
+    for (const bucket of buckets.values()) {
+      nextExpiryAt = Math.min(nextExpiryAt, bucket.expiresAt.getTime());
+    }
+  };
+  const pruneExpiredBuckets = (now) => {
     for (const [key, bucket] of buckets) {
       if (isExpired2(bucket, now)) {
         buckets.delete(key);
       }
     }
+    refreshNextExpiry();
   };
-  const pruneTimer = setInterval(pruneExpiredBuckets, pruneIntervalMs);
+  const pruneTimer = setInterval(() => pruneExpiredBuckets(resolveNow()), pruneIntervalMs);
   pruneTimer.unref?.();
-  const evictOldestBucket = () => {
-    const oldestKey = buckets.keys().next().value;
-    buckets.delete(oldestKey);
+  let capacityReportedFor;
+  const reportCapacity = (freesAt) => {
+    if (capacityReportedFor === freesAt) {
+      return;
+    }
+    capacityReportedFor = freesAt;
+    reportError2(
+      new Error(`[@holo-js/security] Memory rate-limit store is at capacity (${maxBuckets} keys). New keys are limited until buckets expire. Use the redis or file rate-limit driver for high-cardinality limiters.`),
+      { capability: "security", operation: "rate-limit memory store at capacity" }
+    );
   };
   return {
     async hit(key, hitOptions) {
@@ -950,15 +1148,29 @@ function createMemoryRateLimitStore(options = {}) {
         attempts: 1,
         expiresAt: new Date(now.getTime() + hitOptions.decaySeconds * 1e3)
       };
-      if (!active && typeof maxBuckets === "number") {
-        while (buckets.size >= maxBuckets) {
-          evictOldestBucket();
+      if (!active && buckets.size >= maxBuckets) {
+        if (now.getTime() >= nextExpiryAt) {
+          pruneExpiredBuckets(now);
+        }
+        if (buckets.size >= maxBuckets) {
+          const freesAt = nextExpiryAt;
+          reportCapacity(freesAt);
+          return Object.freeze({
+            limited: true,
+            snapshot: createSnapshot2(key, {
+              key,
+              attempts: hitOptions.maxAttempts + 1,
+              expiresAt: new Date(freesAt)
+            }, hitOptions.maxAttempts),
+            retryAfterSeconds: Math.max(0, Math.ceil((freesAt - now.getTime()) / 1e3))
+          });
         }
       }
       if (active) {
         buckets.delete(key);
       }
       buckets.set(key, bucket);
+      nextExpiryAt = Math.min(nextExpiryAt, bucket.expiresAt.getTime());
       return Object.freeze({
         limited: bucket.attempts > hitOptions.maxAttempts,
         snapshot: createSnapshot2(key, bucket, hitOptions.maxAttempts),
@@ -966,7 +1178,9 @@ function createMemoryRateLimitStore(options = {}) {
       });
     },
     async clear(key) {
-      return buckets.delete(key);
+      const deleted = buckets.delete(key);
+      refreshNextExpiry();
+      return deleted;
     },
     async clearByPrefix(prefix) {
       let cleared = 0;
@@ -977,11 +1191,13 @@ function createMemoryRateLimitStore(options = {}) {
         buckets.delete(key);
         cleared += 1;
       }
+      refreshNextExpiry();
       return cleared;
     },
     async clearAll() {
       const cleared = buckets.size;
       buckets.clear();
+      refreshNextExpiry();
       return cleared;
     },
     async close() {
@@ -1087,7 +1303,7 @@ var securityStoreInternals = {
 };
 
 // src/signed-tokens.ts
-import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createHmac, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var MAX_SIGNED_TOKEN_DEPTH = 32;
 var MAX_SIGNED_TOKEN_BODY_BYTES = 64 * 1024;
 var MAX_SIGNED_TOKEN_CHARACTERS = Math.ceil(MAX_SIGNED_TOKEN_BODY_BYTES * 4 / 3) + 44;
@@ -1139,7 +1355,7 @@ function assertPayload(payload) {
   }
 }
 function signature(body, purpose) {
-  return createHmac2("sha256", signingKey()).update("holo-signed-token-v1\0").update(purpose).update("\0").update(body).digest();
+  return createHmac("sha256", signingKey()).update("holo-signed-token-v1\0").update(purpose).update("\0").update(body).digest();
 }
 function decodeEnvelope(body) {
   try {
@@ -1215,6 +1431,7 @@ export {
   getSecurityRuntimeBindings,
   resetSecurityRuntime,
   securityRuntimeInternals,
+  ip,
   defaultRateLimitKey,
   rateLimit,
   clearRateLimit,
@@ -1223,6 +1440,7 @@ export {
   token,
   field,
   input,
+  encryptedToken,
   cookie,
   verify,
   protect,
@@ -1234,7 +1452,6 @@ export {
   cors,
   corsInternals,
   createFileRateLimitStore,
-  fileRateLimitDriverInternals,
   createMemoryRateLimitStore,
   memoryRateLimitDriverInternals,
   createRedisRateLimitStore,