@nxgt/janus 0.17.2 → 0.19.0

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * `@nxgt/janus/conformance` fails an adapter that breaks it.
  */
 export * from './auth/index';
-export { CredentialError, type CredentialRefusal, InvalidCursorError, type Issue, JanusError, type JanusErrorCode, type JanusErrorOptions, type JanusErrorStatus, NotFoundError, PermissionDepthError, SecondFactorError, StepUpRequiredError, StoreConflict, StoreFailure, statusOf, TokenError, UnsupportedError, UserInactiveError, UserInvalidError, } from './errors/janus-error';
+export { CredentialError, type CredentialRefusal, InvalidCursorError, type Issue, JanusError, type JanusErrorCode, type JanusErrorOptions, type JanusErrorStatus, MailThrottledError, NotFoundError, PermissionDepthError, SecondFactorError, StepUpRequiredError, StoreConflict, StoreFailure, statusOf, TokenError, UnsupportedError, UserInactiveError, UserInvalidError, } from './errors/janus-error';
 export { type Id, isId, mintedAt, mintId, } from './ids/id';
 export { type CursorPage, DEFAULT_PAGE_SIZE, invalidCursor, MAX_PAGE_SIZE, pageLimit, } from './pagination/cursor-page';
 export { formatEntity, formatSubject, formatTuple, parseSubject, parseTuple, } from './subjects/notation';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,cAAc,CAAC;AAC7B,OAAO,EACN,eAAe,EACf,KAAK,iBAAiB,EACtB,kBAAkB,EAClB,KAAK,KAAK,EACV,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,KAAK,EAAE,EACP,IAAI,EACJ,QAAQ,EACR,MAAM,GACN,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,KAAK,UAAU,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,SAAS,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,MAAM,EACX,OAAO,EACP,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,EACL,SAAS,GACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,cAAc,CAAC;AAC7B,OAAO,EACN,eAAe,EACf,KAAK,iBAAiB,EACtB,kBAAkB,EAClB,KAAK,KAAK,EACV,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,KAAK,EAAE,EACP,IAAI,EACJ,QAAQ,EACR,MAAM,GACN,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,KAAK,UAAU,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,SAAS,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,MAAM,EACX,OAAO,EACP,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,EACL,SAAS,GACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -7,13 +7,13 @@ import {
   MAX_PAGE_SIZE2,
   pageLimit2,
   invalidCursor2
-} from "./chunks/index-6fxq0kzf.js";
+} from "./chunks/index-4khsm7mw.js";
 import {
   mintId2,
   isId2,
   mintedAt2,
   createMemoryStores2
-} from "./chunks/index-7xe5x3eg.js";
+} from "./chunks/index-6bjfv4xv.js";
 import {
   JanusError2,
   UserInvalidError2,
@@ -22,6 +22,7 @@ import {
   TokenError2,
   SecondFactorError2,
   StepUpRequiredError2,
+  MailThrottledError2,
   InvalidCursorError2,
   UnsupportedError2,
   PermissionDepthError2,
@@ -38,7 +39,7 @@ import {
   formatTuple2,
   parseTuple2,
   parseSubject2
-} from "./chunks/index-ztng6018.js";
+} from "./chunks/index-kppkcbn5.js";
 
 // src/auth/hashers.ts
 import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
@@ -303,25 +304,32 @@ function resolveSecondFactor(config, where) {
   };
 }
 
-// src/auth/config/resolve-sign-in.ts
+// src/auth/config/resolve-throttle.ts
 function resolveSignInThrottle(config, where) {
+  return resolveThrottle(config, { option: "signIn", attempts: 10, window: "15m" }, where);
+}
+function resolveMailThrottle(config, where) {
+  return resolveThrottle(config, { option: "mail", attempts: 5, window: "10m" }, where);
+}
+function resolveThrottle(config, defaults, where) {
+  const { option } = defaults;
   if (config !== undefined && (typeof config !== "object" || config === null)) {
-    throw new TypeError(`${where}: signIn must be an object — { throttle }`);
+    throw new TypeError(`${where}: ${option} must be an object — { throttle }`);
   }
   const throttle = config?.throttle ?? {};
   if (throttle === false)
     return null;
-  const at = `${where}: signIn.throttle`;
+  const at = `${where}: ${option}.throttle`;
   if (typeof throttle !== "object" || throttle === null) {
     throw new TypeError(`${at} must be { attempts, window }, or false to count nothing`);
   }
-  const attempts = throttle.attempts ?? 10;
+  const attempts = throttle.attempts ?? defaults.attempts;
   if (!Number.isSafeInteger(attempts) || attempts < 1) {
     throw new TypeError(`${at}.attempts must be a whole number above zero`);
   }
   return {
     attempts,
-    windowMs: parseDuration(throttle.window ?? "15m", `${at}.window`)
+    windowMs: parseDuration(throttle.window ?? defaults.window, `${at}.window`)
   };
 }
 
@@ -372,6 +380,7 @@ function resolveConfig(config, where) {
     tokenTtlMs: resolveTokenTtls(config, where),
     cookie: resolveCookie(config.cookie ?? {}, where),
     signInThrottle: resolveSignInThrottle(config.signIn, where),
+    mailThrottle: resolveMailThrottle(config.mail, where),
     secondFactor: resolveSecondFactor(config.secondFactor, where),
     devices: resolveDevices(config.devices, where)
   };
@@ -419,6 +428,46 @@ function resolveTokenTtls(config, where) {
     stepUp: parseDuration(config.tokens?.stepUp ?? "10m", `${where}: tokens.stepUp`)
   };
 }
+// src/auth/config/warn-throttle-window.ts
+var FLOWS = [
+  "magicLink",
+  "signInCode",
+  "resetPassword",
+  "verifyEmail",
+  "stepUp"
+];
+var UNITS2 = [
+  ["d", 86400000],
+  ["h", 3600000],
+  ["m", 60000],
+  ["s", 1000]
+];
+function show(ms) {
+  const unit = UNITS2.find(([, size]) => ms % size === 0);
+  return unit === undefined ? `${ms}ms` : `${ms / unit[1]}${unit[0]}`;
+}
+function throttleWindowMessage(resolved, where) {
+  const throttle = resolved.mailThrottle;
+  if (throttle === null)
+    return null;
+  const window = show(throttle.windowMs);
+  const shorter = FLOWS.filter((flow) => resolved.tokenTtlMs[flow] < throttle.windowMs);
+  if (shorter.length === 0)
+    return null;
+  const shortest = Math.min(...shorter.map((flow) => resolved.tokenTtlMs[flow]));
+  const parts = shorter.map((flow) => `tokens.${flow} is ${show(resolved.tokenTtlMs[flow])}, shorter than mail.throttle.window, ${window}`);
+  return `${where}: ${parts.join("; ")} — past the limit the last ${shorter.length === 1 ? "token" : "tokens"} sent can expire before the refusal ends. Set mail.throttle.window to ${show(shortest)} or less, or raise ${shorter.map((flow) => `tokens.${flow}`).join(", ")} to ${window} or more.`;
+}
+function warnThrottleWindow(resolved, where) {
+  const message = throttleWindowMessage(resolved, where);
+  if (message === null)
+    return;
+  if (typeof process === "undefined" || typeof process.emitWarning !== "function") {
+    return;
+  }
+  process.emitWarning(message, { code: "JANUS_THROTTLE_WINDOW" });
+}
+
 // src/auth/context/create-context.ts
 function createContext(config, store, relations, capabilities, clock, hasher, verifiers, events = null) {
   let dummy = null;
@@ -725,12 +774,18 @@ function assertStores(stores, where) {
       }
     }
   }
-  const sessions = stores.sessions;
-  const collect = sessions["deleteExpiredSessions"];
-  if (collect !== undefined && typeof collect !== "function") {
-    throw new TypeError(`${where}: store.sessions.deleteExpiredSessions must be a function or absent`);
+  const slots = stores;
+  return {
+    collectExpired: optional(slots, "sessions", "deleteExpiredSessions", where),
+    findUsers: optional(slots, "users", "findUsers", where)
+  };
+}
+function optional(stores, slot, method, where) {
+  const found = stores[slot][method];
+  if (found !== undefined && typeof found !== "function") {
+    throw new TypeError(`${where}: store.${slot}.${method} must be a function or absent`);
   }
-  return { collectExpired: collect !== undefined };
+  return found !== undefined;
 }
 
 // src/auth/devices/token.ts
@@ -1008,6 +1063,13 @@ function sharedApi(context) {
     types: [...config.types.keys()]
   };
 }
+// src/auth/counter-key.ts
+function counterKey(context, purpose) {
+  const sealer = context.config.secondFactor?.sealer;
+  return sealer === undefined ? Buffer.from(purpose) : derivedKey(sealer, purpose);
+}
+var keyed = (key, parts) => keyedHash(key, parts).toString("base64url");
+
 // src/auth/one-time/codes.ts
 import { timingSafeEqual as timingSafeEqual3 } from "node:crypto";
 
@@ -1173,6 +1235,38 @@ async function insertLink(links, tokenHash) {
     return inserted;
   throw links.counting.vanished();
 }
+// src/auth/mail-requests.ts
+var PURPOSE2 = "janus/mail/requests/v1";
+async function countMailByAddress(context, type, flow, email, where) {
+  await countMail(context, type, flow, { address: normalizeEmail(email) }, where);
+}
+async function countMailByUser(context, type, flow, userId, where) {
+  await countMail(context, type, flow, { userId }, where);
+}
+async function countMail(context, type, flow, counted, where) {
+  const throttle = context.config.mailThrottle;
+  if (throttle === null)
+    return;
+  const key = counterKey(context, PURPOSE2);
+  const subject = "address" in counted ? keyed(key, [flow, "address", counted.address]) : keyed(key, [flow, "user", counted.userId]);
+  const { attempts, endsAt } = await countInWindow(context, {
+    windowMs: throttle.windowMs,
+    spent: "carry",
+    userId: subject,
+    linkHash: (window, link) => hashSecret(keyed(key, [subject, String(window), String(link)])),
+    vanished: () => new StoreFailure2(`${where}: the store dropped the requests it had just counted`, { slot: "tokens", operation: "countAttempt" })
+  });
+  if (attempts <= throttle.attempts)
+    return;
+  const now = context.clock.now().getTime();
+  const byUser = "userId" in counted;
+  throw new MailThrottledError2(`${where}: too many e-mails asked for this ${byUser ? "user" : "address"} — the last one sent still works; use it, or wait for the next window`, {
+    userType: type.name,
+    ...byUser ? { userId: counted.userId } : {},
+    retryAfter: Math.max(1, Math.ceil((endsAt - now) / 1000))
+  });
+}
+
 // src/auth/password-written.ts
 async function endWhatThePasswordOpened(context, userId) {
   const now = context.clock.now();
@@ -1234,6 +1328,7 @@ function resetPasswordFlows(context, type, at) {
     async request(email) {
       const where = at("resetPassword.request");
       passwordRule(type, where);
+      await countMailByAddress(context, type, "resetPassword", String(email), where);
       const record = await holderOfEmail(context, type, String(email));
       if (record === null)
         return null;
@@ -1278,6 +1373,7 @@ function verifyEmailFlows(context, type, at) {
     async send(user) {
       const where = at("verifyEmail.send");
       const record = await getRecord(context, idOf(user), type.name, where);
+      await countMailByUser(context, type, "verifyEmail", record.id, where);
       return issueEmailToken(context, type, "verifyEmail", record, where);
     },
     async confirm(secret) {
@@ -1465,7 +1561,7 @@ async function finishEmailSignIn(context, type, finish, signIn) {
 function magicLinkFlows(context, type, at, finish) {
   return {
     async request(email) {
-      return requestLink(context, type, String(email));
+      return requestLink(context, type, String(email), at("magicLink.request"));
     },
     async confirm(token, options) {
       const where = at("magicLink.confirm");
@@ -1474,7 +1570,8 @@ function magicLinkFlows(context, type, at, finish) {
     }
   };
 }
-async function requestLink(context, type, email) {
+async function requestLink(context, type, email, where) {
+  await countMailByAddress(context, type, "magicLink", email, where);
   const record = await signInHolder(context, type, email);
   if (record === null)
     return null;
@@ -1500,18 +1597,12 @@ async function confirmLink(context, type, finish, secret, where, device) {
 }
 
 // src/auth/sign-in-attempts.ts
-var PURPOSE2 = "janus/sign-in/attempts/v1";
-var UNSEALED = Buffer.from(PURPOSE2);
-function counterKey(context) {
-  const sealer = context.config.secondFactor?.sealer;
-  return sealer === undefined ? UNSEALED : derivedKey(sealer, PURPOSE2);
-}
-var keyed = (key, parts) => keyedHash(key, parts).toString("base64url");
+var PURPOSE3 = "janus/sign-in/attempts/v1";
 async function countLogin(context, type, login, where) {
   const throttle = context.config.signInThrottle;
   if (throttle === null)
     return null;
-  const key = counterKey(context);
+  const key = counterKey(context, PURPOSE3);
   const loginKey = keyed(key, [type.name, login]);
   return countInWindow(context, {
     windowMs: throttle.windowMs,
@@ -1634,7 +1725,7 @@ var RECOVERY_CODES = 10;
 var ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
 var LENGTH = 10;
 var SHAPE = /^[0-9a-hjkmnp-tv-z]{10}$/;
-var PURPOSE3 = "janus/second-factor/recovery-codes/v1";
+var PURPOSE4 = "janus/second-factor/recovery-codes/v1";
 function mintRecoveryCodes() {
   return Array.from({ length: RECOVERY_CODES }, () => {
     let code = "";
@@ -1648,7 +1739,7 @@ function readRecoveryCode(typed) {
   const code = typed.toLowerCase().replace(/[\s-]/g, "").replace(/o/g, "0").replace(/[il]/g, "1");
   return SHAPE.test(code) ? code : null;
 }
-var macKey = (sealer, keyId) => derivedKey(sealer, PURPOSE3, keyId);
+var macKey = (sealer, keyId) => derivedKey(sealer, PURPOSE4, keyId);
 var mac = (key, userId, code) => keyedHash(key, [userId, code]);
 function hashRecoveryCode(sealer, userId, code) {
   const read = readRecoveryCode(code) ?? code;
@@ -1759,7 +1850,7 @@ function accountOf(type, record, where) {
 // src/auth/second-factor/app-code-attempts.ts
 var APP_CODE_WINDOW_MS = 15 * 60000;
 var WINDOW_MINUTES = APP_CODE_WINDOW_MS / 60000;
-var PURPOSE4 = "janus/second-factor/regenerate-attempts/v1";
+var PURPOSE5 = "janus/second-factor/regenerate-attempts/v1";
 function linkHash(sealer, record, window, link) {
   const parts = [
     record.id,
@@ -1767,7 +1858,7 @@ function linkHash(sealer, record, window, link) {
     String(record.secondFactor?.lastStep ?? ""),
     String(link)
   ];
-  const key = derivedKey(sealer, PURPOSE4);
+  const key = derivedKey(sealer, PURPOSE5);
   return hashSecret(keyedHash(key, parts).toString("base64url"));
 }
 async function countAppCodeAttempt(context, sealer, record, where) {
@@ -1883,14 +1974,15 @@ function secondFactorFlows(context, type, at) {
 function signInCodeFlows(context, type, at, finish) {
   return {
     async request(email) {
-      return requestCode(context, type, String(email));
+      return requestCode(context, type, String(email), at("signInCode.request"));
     },
     async confirm(challenge, code, options) {
       return confirmCode(context, type, finish, { challenge, code, options }, at);
     }
   };
 }
-async function requestCode(context, type, email) {
+async function requestCode(context, type, email, where) {
+  await countMailByAddress(context, type, "signInCode", email, where);
   const record = await signInHolder(context, type, email);
   if (record === null)
     return null;
@@ -2028,6 +2120,7 @@ async function byEmail(context, type, record, where) {
       operation: where
     });
   }
+  await countMailByUser(context, type, "stepUp", record.id, where);
   const { secret, code, expiresAt } = await issueCode(context, {
     kind: "stepUp",
     userId: record.id,
@@ -2230,6 +2323,48 @@ async function deleteUser(context, type, user) {
   return deleted;
 }
 
+// src/auth/users/find-many.ts
+var FIND_MANY_BATCH = 100;
+var FIND_MANY_CONCURRENCY = 10;
+async function findManyRecords(context, ids, type, where) {
+  if (!Array.isArray(ids)) {
+    throw new TypeError(`${where}: ids must be an array of user ids`);
+  }
+  const wanted = [
+    ...new Set(ids.filter((id) => typeof id === "string" && isId2(id)))
+  ];
+  const found = new Map;
+  for (let start = 0;start < wanted.length; start += FIND_MANY_BATCH) {
+    const batch = wanted.slice(start, start + FIND_MANY_BATCH);
+    for (const record of await readBatch(context, batch)) {
+      if (record.type === type)
+        found.set(record.id, record);
+    }
+  }
+  return wanted.flatMap((id) => {
+    const record = found.get(id);
+    return record === undefined ? [] : [record];
+  });
+}
+async function readBatch(context, ids) {
+  const { users } = context.store;
+  if (context.capabilities.findUsers && users.findUsers !== undefined) {
+    const answer = await users.findUsers(ids);
+    if (!Array.isArray(answer)) {
+      throw new StoreFailure2("users.findUsers answered no list: an absence is a shorter list, so this store forgot to answer", { slot: "users", operation: "findUsers" });
+    }
+    return answer;
+  }
+  const records = [];
+  for (let start = 0;start < ids.length; start += FIND_MANY_CONCURRENCY) {
+    const answers = await Promise.all(ids.slice(start, start + FIND_MANY_CONCURRENCY).map((id) => users.findUser(id)));
+    for (const record of answers)
+      if (record !== null)
+        records.push(record);
+  }
+  return records;
+}
+
 // src/auth/users/fields-patch.ts
 var normalized = (email) => email === null ? null : normalizeEmail(email);
 function emailChanged(type, before, after) {
@@ -2272,6 +2407,10 @@ function recordFlows(context, type, at) {
       const record = await findRecord(context, id, type.name);
       return record === null ? null : toUser(record);
     },
+    async findMany(ids) {
+      const records = await findManyRecords(context, ids, type.name, at("findMany"));
+      return records.map(toUser);
+    },
     async get(id) {
       return toUser(await getRecord(context, id, type.name, at("get")));
     },
@@ -2320,6 +2459,7 @@ function typeApi(context, type) {
 function janus(config) {
   const where = "janus";
   const resolved = resolveConfig(config, where);
+  warnThrottleWindow(resolved, where);
   const capabilities = assertStores(config.store, where);
   const hasher = config.hasher ?? null;
   const verifiers = [
@@ -2363,6 +2503,7 @@ export {
   InvalidCursorError2 as InvalidCursorError,
   JanusError2 as JanusError,
   MAX_PAGE_SIZE2 as MAX_PAGE_SIZE,
+  MailThrottledError2 as MailThrottledError,
   NotFoundError2 as NotFoundError,
   PermissionDepthError2 as PermissionDepthError,
   SecondFactorError2 as SecondFactorError,
@@ -2399,5 +2540,5 @@ export {
   systemClock
 };
 
-//# debugId=AA27B9CD21C48F3A64756E2164756E21
+//# debugId=22ACDB89AAF4B56564756E2164756E21
 //# sourceMappingURL=index.js.map