@exortek/apikey 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @exortek/apikey
 
+## 1.2.0
+
+### Minor Changes
+
+- d370002: - `rehashApiKey` checks the presented secret against the stored hash before replacing it (anyone knowing a key id could overwrite its hash).
+  - `verifyApiKey` compares the secret before reporting `revoked` / `expired`, and accepts only the canonical spelling of a key (lowercase / I / O variants no longer verify).
+
+### Patch Changes
+
+- 9953042: - Duration strings whose unit is the name of an `Object.prototype` member (for example `'1constructor'`) now throw instead of resolving to `NaN`.
+- 9953042: - When a record is stored again under the same id with a different owner (`userId` / `email`), the previous owner no longer lists it, and per-owner bulk revocation (`revokeAllForUser`, `revokeByEmail`) no longer reaches it.
+
 ## 1.1.3
 
 ### Patch Changes

package/dist/index.cjs

@@ -107,11 +107,13 @@ function parseDuration(input) {
   }
   const value = Number(match[1]);
   const unit = (match[2] || 'ms').toLowerCase();
-  const multiplier = UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)];
-  if (multiplier === undefined) {
+  // Own keys only: a plain lookup would resolve `constructor` (and every
+  // other Object.prototype member) to a function, turning '1constructor'
+  // into NaN instead of an error.
+  if (!Object.hasOwn(UNIT_MS, unit)) {
     throw new Error(`parseDuration: unknown time unit ${JSON.stringify(unit)}. Supported: ${SUPPORTED_UNITS}.`);
   }
-  return Math.round(value * multiplier);
+  return Math.round(value * UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)]);
 }
 
 /**
@@ -887,6 +889,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -1130,19 +1138,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -1156,6 +1160,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }
@@ -1280,6 +1291,17 @@ async function rehashApiKey(rawKey, options) {
   if (!parsed) {
     return false;
   }
+  // Prove the caller holds the real secret before replacing its hash —
+  // otherwise anyone who knows a key id (it is in every masked key) could
+  // overwrite that key's hash with one for a secret of their choosing.
+  const record = await options.store.getById(parsed.id);
+  if (!record) {
+    return false;
+  }
+  const { candidateHashes: existing } = candidateHashesFor(parsed.secret, peppers);
+  if (!existing.some(candidate => hashesMatch(candidate, record.hash))) {
+    return false;
+  }
   const { candidateHashes } = candidateHashesFor(parsed.secret, [peppers[0]]);
   const newHash = candidateHashes[0];
   const updated = await options.store.update(parsed.id, { hash: newHash, pepperVersion: 0 });

package/dist/index.mjs

@@ -105,11 +105,13 @@ function parseDuration(input) {
   }
   const value = Number(match[1]);
   const unit = (match[2] || 'ms').toLowerCase();
-  const multiplier = UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)];
-  if (multiplier === undefined) {
+  // Own keys only: a plain lookup would resolve `constructor` (and every
+  // other Object.prototype member) to a function, turning '1constructor'
+  // into NaN instead of an error.
+  if (!Object.hasOwn(UNIT_MS, unit)) {
     throw new Error(`parseDuration: unknown time unit ${JSON.stringify(unit)}. Supported: ${SUPPORTED_UNITS}.`);
   }
-  return Math.round(value * multiplier);
+  return Math.round(value * UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)]);
 }
 
 /**
@@ -885,6 +887,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -1128,19 +1136,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -1154,6 +1158,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }
@@ -1278,6 +1289,17 @@ async function rehashApiKey(rawKey, options) {
   if (!parsed) {
     return false;
   }
+  // Prove the caller holds the real secret before replacing its hash —
+  // otherwise anyone who knows a key id (it is in every masked key) could
+  // overwrite that key's hash with one for a secret of their choosing.
+  const record = await options.store.getById(parsed.id);
+  if (!record) {
+    return false;
+  }
+  const { candidateHashes: existing } = candidateHashesFor(parsed.secret, peppers);
+  if (!existing.some(candidate => hashesMatch(candidate, record.hash))) {
+    return false;
+  }
   const { candidateHashes } = candidateHashesFor(parsed.secret, [peppers[0]]);
   const newHash = candidateHashes[0];
   const updated = await options.store.update(parsed.id, { hash: newHash, pepperVersion: 0 });

package/dist/middleware/express.cjs

@@ -389,7 +389,7 @@ const ALPHABET$1 = /^[A-Za-z0-9_-]*$/;
  * @param {Buffer | Uint8Array} bytes
  * @returns {string}
  */
-function encode(bytes) {
+function encode$1(bytes) {
   if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
     throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
   }
@@ -453,6 +453,39 @@ for (const [alias, canonical] of [
   DECODE_TABLE[alias.charCodeAt(0)] = DECODE_TABLE[canonical.charCodeAt(0)];
 }
 
+/**
+ * Encode bytes as a Crockford base32 string.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} if `bytes` is not a Buffer or Uint8Array.
+ */
+function encode(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('encode: input must be a Buffer or Uint8Array.');
+  }
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  let out = '';
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(value >>> bits) & 0x1f];
+      value &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0) {
+    out += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
 /**
  * Decode a Crockford base32 string into a Buffer.
  *
@@ -612,7 +645,7 @@ function hashSecret(secretBytes, pepper) {
   const digest = pepper
     ? node_crypto.createHmac('sha256', pepper).update(secretBytes).digest()
     : node_crypto.createHash('sha256').update(secretBytes).digest();
-  return encode(digest);
+  return encode$1(digest);
 }
 
 /**
@@ -704,6 +737,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -774,19 +813,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -800,6 +835,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }

package/dist/middleware/express.mjs

@@ -387,7 +387,7 @@ const ALPHABET$1 = /^[A-Za-z0-9_-]*$/;
  * @param {Buffer | Uint8Array} bytes
  * @returns {string}
  */
-function encode(bytes) {
+function encode$1(bytes) {
   if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
     throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
   }
@@ -451,6 +451,39 @@ for (const [alias, canonical] of [
   DECODE_TABLE[alias.charCodeAt(0)] = DECODE_TABLE[canonical.charCodeAt(0)];
 }
 
+/**
+ * Encode bytes as a Crockford base32 string.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} if `bytes` is not a Buffer or Uint8Array.
+ */
+function encode(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('encode: input must be a Buffer or Uint8Array.');
+  }
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  let out = '';
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(value >>> bits) & 0x1f];
+      value &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0) {
+    out += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
 /**
  * Decode a Crockford base32 string into a Buffer.
  *
@@ -610,7 +643,7 @@ function hashSecret(secretBytes, pepper) {
   const digest = pepper
     ? createHmac('sha256', pepper).update(secretBytes).digest()
     : createHash('sha256').update(secretBytes).digest();
-  return encode(digest);
+  return encode$1(digest);
 }
 
 /**
@@ -702,6 +735,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -772,19 +811,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -798,6 +833,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }

package/dist/middleware/fastify.cjs

@@ -450,7 +450,7 @@ const ALPHABET$1 = /^[A-Za-z0-9_-]*$/;
  * @param {Buffer | Uint8Array} bytes
  * @returns {string}
  */
-function encode(bytes) {
+function encode$1(bytes) {
   if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
     throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
   }
@@ -514,6 +514,39 @@ for (const [alias, canonical] of [
   DECODE_TABLE[alias.charCodeAt(0)] = DECODE_TABLE[canonical.charCodeAt(0)];
 }
 
+/**
+ * Encode bytes as a Crockford base32 string.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} if `bytes` is not a Buffer or Uint8Array.
+ */
+function encode(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('encode: input must be a Buffer or Uint8Array.');
+  }
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  let out = '';
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(value >>> bits) & 0x1f];
+      value &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0) {
+    out += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
 /**
  * Decode a Crockford base32 string into a Buffer.
  *
@@ -673,7 +706,7 @@ function hashSecret(secretBytes, pepper) {
   const digest = pepper
     ? node_crypto.createHmac('sha256', pepper).update(secretBytes).digest()
     : node_crypto.createHash('sha256').update(secretBytes).digest();
-  return encode(digest);
+  return encode$1(digest);
 }
 
 /**
@@ -765,6 +798,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -835,19 +874,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -861,6 +896,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }

package/dist/middleware/fastify.mjs

@@ -448,7 +448,7 @@ const ALPHABET$1 = /^[A-Za-z0-9_-]*$/;
  * @param {Buffer | Uint8Array} bytes
  * @returns {string}
  */
-function encode(bytes) {
+function encode$1(bytes) {
   if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
     throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
   }
@@ -512,6 +512,39 @@ for (const [alias, canonical] of [
   DECODE_TABLE[alias.charCodeAt(0)] = DECODE_TABLE[canonical.charCodeAt(0)];
 }
 
+/**
+ * Encode bytes as a Crockford base32 string.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} if `bytes` is not a Buffer or Uint8Array.
+ */
+function encode(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('encode: input must be a Buffer or Uint8Array.');
+  }
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  let out = '';
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(value >>> bits) & 0x1f];
+      value &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0) {
+    out += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
 /**
  * Decode a Crockford base32 string into a Buffer.
  *
@@ -671,7 +704,7 @@ function hashSecret(secretBytes, pepper) {
   const digest = pepper
     ? createHmac('sha256', pepper).update(secretBytes).digest()
     : createHash('sha256').update(secretBytes).digest();
-  return encode(digest);
+  return encode$1(digest);
 }
 
 /**
@@ -763,6 +796,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -833,19 +872,15 @@ async function verifyApiKey(rawKey, options) {
   if (!record) {
     return { valid: false, reason: 'not_found' };
   }
-  const now = _now(options.now);
-  if (record.revokedAt) {
-    return { valid: false, reason: 'revoked' };
-  }
-  if (record.expiresAt && record.expiresAt <= now) {
-    return { valid: false, reason: 'expired' };
-  }
   if (parsed.prefix !== record.prefix) {
     // Someone submitted a key whose id belongs to a different prefix —
     // treat as bad, not merely 'prefix_mismatch', because the id half
     // was correct: the attacker guessed the id and swapped the prefix.
     return { valid: false, reason: 'prefix_mismatch' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -859,6 +894,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
   if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }

package/dist/stores.cjs

@@ -169,6 +169,8 @@ function detectDialect(client) {
  *   smembers: (key: string) => Promise<string[]>,
  *   setWithTTL: (key: string, value: string, ttlMs: number) => Promise<void>,
  *   setPlain: (key: string, value: string) => Promise<void>,
+ *   setKeepTTL: (key: string, value: string) => Promise<void>,
+ *   setIfAbsent: (key: string, value: string, ttlMs: number) => Promise<boolean>,
  *   parseRecord: (raw: string|object|null) => object|null,
  * }}
  */
@@ -238,6 +240,29 @@ function createRedisHelpers(client) {
       await client.set(key, value);
     },
 
+    // Overwrite a value but keep whatever expiry the key already has
+    // (Redis ≥ 6.0 `SET … KEEPTTL`). A plain SET clears the TTL, so an
+    // update to an expiring record would otherwise make it immortal.
+    async setKeepTTL(key, value) {
+      if (dialect === 'ioredis') {
+        await client.set(key, value, 'KEEPTTL');
+      } else {
+        await client.set(key, value, { KEEPTTL: true });
+      }
+    },
+
+    // Atomic claim: `SET key value PX ttl NX`. Resolves true when this call
+    // created the key, false when it already existed — a cross-process
+    // compare-and-set for "only the first caller wins".
+    async setIfAbsent(key, value, ttlMs) {
+      const px = Math.max(1, Math.ceil(ttlMs));
+      const reply =
+        dialect === 'ioredis'
+          ? await client.set(key, value, 'PX', px, 'NX')
+          : await client.set(key, value, { PX: px, NX: true });
+      return reply === 'OK';
+    },
+
     parseRecord(raw) {
       if (!raw) {
         return null;
@@ -333,8 +358,15 @@ function createMemoryRecordStore(config) {
     byIndex,
 
     async put(record) {
-      byId.set(record[idField], copy(record));
-      addIndex(record[indexField], record[idField]);
+      const id = record[idField];
+      const previous = byId.get(id);
+      // Overwriting a record under a different owner must drop the old
+      // owner's index entry, or the old owner keeps listing it.
+      if (previous && previous[indexField] !== record[indexField]) {
+        removeIndex(previous[indexField], id);
+      }
+      byId.set(id, copy(record));
+      addIndex(record[indexField], id);
     },
 
     async getById(id) {
@@ -399,7 +431,7 @@ function createMemoryRecordStore(config) {
  * @returns {{
  *   put: (record: object, ttlMs?: number) => Promise<void>,
  *   getById: (id: string) => Promise<object|null>,
- *   update: (id: string, patch: object, ttlMs?: number) => Promise<object|null>,
+ *   update: (id: string, patch: object, ttlMs?: number) => Promise<object|null>,  without `ttlMs` a TTL store keeps the key's remaining expiry
  *   listByIndex: (indexValue: string) => Promise<object[]>,
  *   readRecord: (id: string) => Promise<object|null>,
  *   writeRecord: (record: object, ttlMs?: number) => Promise<void>,
@@ -464,6 +496,16 @@ function createRedisRecordStore(client, config) {
     }
   }
 
+  // An update with no explicit TTL keeps the key's remaining expiry
+  // instead of clearing it.
+  async function rewriteRecord(record, ttlMs) {
+    if (ttl && ttlMs === undefined) {
+      await helpers.setKeepTTL(rk(record[idField]), JSON.stringify(record));
+      return;
+    }
+    await writeRecord(record, ttlMs);
+  }
+
   async function writeTombstone(id, data, ttlMs) {
     const value = JSON.stringify(data);
     if (ttl && ttlMs !== undefined) {
@@ -500,7 +542,10 @@ function createRedisRecordStore(client, config) {
       const raw = rows[i * stride];
       const rawTomb = tombstones ? rows[i * stride + 1] : null;
       const record = helpers.parseRecord(raw);
-      if (!record) {
+      // Gone, or re-put under another owner (`put` does not read the old
+      // record, so it cannot unlink the old index entry itself) — prune the
+      // stale entry and never hand the record to this owner.
+      if (!record || record[indexField] !== indexValue) {
         await indexRemove(indexValue, ids[i]);
         pairs.push([ids[i], null]);
         continue;
@@ -529,7 +574,7 @@ function createRedisRecordStore(client, config) {
       }
       const oldIndex = existing[indexField];
       const next = { ...existing, ...patch };
-      await writeRecord(next, ttlMs);
+      await rewriteRecord(next, ttlMs);
       if (!isUndefined(patch[indexField]) && patch[indexField] !== oldIndex) {
         if (isString(oldIndex)) {
           await indexRemove(oldIndex, id);

package/dist/stores.mjs

@@ -167,6 +167,8 @@ function detectDialect(client) {
  *   smembers: (key: string) => Promise<string[]>,
  *   setWithTTL: (key: string, value: string, ttlMs: number) => Promise<void>,
  *   setPlain: (key: string, value: string) => Promise<void>,
+ *   setKeepTTL: (key: string, value: string) => Promise<void>,
+ *   setIfAbsent: (key: string, value: string, ttlMs: number) => Promise<boolean>,
  *   parseRecord: (raw: string|object|null) => object|null,
  * }}
  */
@@ -236,6 +238,29 @@ function createRedisHelpers(client) {
       await client.set(key, value);
     },
 
+    // Overwrite a value but keep whatever expiry the key already has
+    // (Redis ≥ 6.0 `SET … KEEPTTL`). A plain SET clears the TTL, so an
+    // update to an expiring record would otherwise make it immortal.
+    async setKeepTTL(key, value) {
+      if (dialect === 'ioredis') {
+        await client.set(key, value, 'KEEPTTL');
+      } else {
+        await client.set(key, value, { KEEPTTL: true });
+      }
+    },
+
+    // Atomic claim: `SET key value PX ttl NX`. Resolves true when this call
+    // created the key, false when it already existed — a cross-process
+    // compare-and-set for "only the first caller wins".
+    async setIfAbsent(key, value, ttlMs) {
+      const px = Math.max(1, Math.ceil(ttlMs));
+      const reply =
+        dialect === 'ioredis'
+          ? await client.set(key, value, 'PX', px, 'NX')
+          : await client.set(key, value, { PX: px, NX: true });
+      return reply === 'OK';
+    },
+
     parseRecord(raw) {
       if (!raw) {
         return null;
@@ -331,8 +356,15 @@ function createMemoryRecordStore(config) {
     byIndex,
 
     async put(record) {
-      byId.set(record[idField], copy(record));
-      addIndex(record[indexField], record[idField]);
+      const id = record[idField];
+      const previous = byId.get(id);
+      // Overwriting a record under a different owner must drop the old
+      // owner's index entry, or the old owner keeps listing it.
+      if (previous && previous[indexField] !== record[indexField]) {
+        removeIndex(previous[indexField], id);
+      }
+      byId.set(id, copy(record));
+      addIndex(record[indexField], id);
     },
 
     async getById(id) {
@@ -397,7 +429,7 @@ function createMemoryRecordStore(config) {
  * @returns {{
  *   put: (record: object, ttlMs?: number) => Promise<void>,
  *   getById: (id: string) => Promise<object|null>,
- *   update: (id: string, patch: object, ttlMs?: number) => Promise<object|null>,
+ *   update: (id: string, patch: object, ttlMs?: number) => Promise<object|null>,  without `ttlMs` a TTL store keeps the key's remaining expiry
  *   listByIndex: (indexValue: string) => Promise<object[]>,
  *   readRecord: (id: string) => Promise<object|null>,
  *   writeRecord: (record: object, ttlMs?: number) => Promise<void>,
@@ -462,6 +494,16 @@ function createRedisRecordStore(client, config) {
     }
   }
 
+  // An update with no explicit TTL keeps the key's remaining expiry
+  // instead of clearing it.
+  async function rewriteRecord(record, ttlMs) {
+    if (ttl && ttlMs === undefined) {
+      await helpers.setKeepTTL(rk(record[idField]), JSON.stringify(record));
+      return;
+    }
+    await writeRecord(record, ttlMs);
+  }
+
   async function writeTombstone(id, data, ttlMs) {
     const value = JSON.stringify(data);
     if (ttl && ttlMs !== undefined) {
@@ -498,7 +540,10 @@ function createRedisRecordStore(client, config) {
       const raw = rows[i * stride];
       const rawTomb = tombstones ? rows[i * stride + 1] : null;
       const record = helpers.parseRecord(raw);
-      if (!record) {
+      // Gone, or re-put under another owner (`put` does not read the old
+      // record, so it cannot unlink the old index entry itself) — prune the
+      // stale entry and never hand the record to this owner.
+      if (!record || record[indexField] !== indexValue) {
         await indexRemove(indexValue, ids[i]);
         pairs.push([ids[i], null]);
         continue;
@@ -527,7 +572,7 @@ function createRedisRecordStore(client, config) {
       }
       const oldIndex = existing[indexField];
       const next = { ...existing, ...patch };
-      await writeRecord(next, ttlMs);
+      await rewriteRecord(next, ttlMs);
       if (!isUndefined(patch[indexField]) && patch[indexField] !== oldIndex) {
         if (isString(oldIndex)) {
           await indexRemove(oldIndex, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exortek/apikey",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Stripe-style prefixed API keys for Node.js — 3-segment tokens (prefix_id_secret), HMAC-SHA256 storage hash with pepper rotation, scope allowlists with wildcard match, opt-in lastUsedAt tracking, memory + Redis stores, Express + Fastify middleware. Server-only. Zero non-@exortek runtime dependencies.",
   "type": "module",
   "sideEffects": false,