@hadoku/worker-utils 1.6.20 → 1.7.0

package/dist/identity.d.ts

@@ -161,7 +161,33 @@ interface KeyRegistryRecord {
      * SESSIONS_KV binding.
      */
     repo?: string | null;
+    /**
+     * The PERSON holding this credential (added 2026-10-31, service grants):
+     * their own userId, while `userId` above stays the service identity's. A
+     * row with `heldBy` was minted for that person alone, so revoking them
+     * retires their rows and leaves every other holder of the identity working.
+     * Absent on a row from before grants, and on human sign-in keys.
+     */
+    heldBy?: string;
+    /**
+     * ms epoch after which the key authenticates nothing (added 2026-10-31).
+     * Every grant and fleet credential carries one (7 days from mint). Liveness
+     * is {@link isLiveKey}, never a bare `retiredAt` read; a sweep later stamps
+     * `retiredAt = expiresAt` so bookkeeping readers agree.
+     */
+    expiresAt?: number;
+    /** How a `heldBy` row was minted: a person under a grant, or fleet automation. */
+    via?: 'grant' | 'fleet';
 }
+/**
+ * Does this row authenticate right now? Not retired, and not past `expiresAt`.
+ *
+ * THE liveness test. A path that decides whether a presented key is accepted
+ * must call this, never read `retiredAt` alone: an expired credential carries
+ * no `retiredAt` until the sweep reaches it, so a bare read would keep it
+ * working for up to a day past its expiry.
+ */
+declare function isLiveKey(record: Pick<Partial<KeyRegistryRecord>, 'retiredAt' | 'expiresAt'> | null | undefined, now?: number): boolean;
 /** The minimum SESSIONS_KV surface this module uses. Read-only, by construction.
  *
  * `list` declares the PAGINATION fields, not just `keys`. Omitting them was not
@@ -273,6 +299,9 @@ interface RegistryRowMetadata {
     repo?: string | null;
     /** Present only as `true`, on a sign-up key (KeyRegistryRecord.internal). */
     internal?: true;
+    heldBy?: string;
+    expiresAt?: number;
+    via?: 'grant' | 'fleet';
 }
 /** Workers KV's ceiling on serialized list metadata, in bytes. */
 declare const REGISTRY_METADATA_MAX_BYTES = 1024;
@@ -474,4 +503,4 @@ declare function resolveGrantee(env: RegistryEnv, input: {
     key?: string;
 }): Promise<IdentityResult>;
 
-export { type EdgeIdentityBinding, type EdgeIdentityCall, type IdentityError, type IdentityResult, type KeyRegistryRecord, type KeyTier, MIN_SEARCH_QUERY_LENGTH, NO_REGISTRY, NO_USER_ID, REGISTRY_METADATA_MAX_BYTES, type RegistryEnv, type RegistryKvNamespace, type RegistryRowMetadata, type ResolvedIdentity, answersToName, isIdentityError, isRegistryNameTaken, liveRowsByName, readLiveRows, recordFromRegistryMetadata, registryNameMap, registryRowMetadata, resolveGrantee, resolveGranteeVia, resolveRegistryName, searchRegistryNames };
+export { type EdgeIdentityBinding, type EdgeIdentityCall, type IdentityError, type IdentityResult, type KeyRegistryRecord, type KeyTier, MIN_SEARCH_QUERY_LENGTH, NO_REGISTRY, NO_USER_ID, REGISTRY_METADATA_MAX_BYTES, type RegistryEnv, type RegistryKvNamespace, type RegistryRowMetadata, type ResolvedIdentity, answersToName, isIdentityError, isLiveKey, isRegistryNameTaken, liveRowsByName, readLiveRows, recordFromRegistryMetadata, registryNameMap, registryRowMetadata, resolveGrantee, resolveGranteeVia, resolveRegistryName, searchRegistryNames };

package/dist/identity.js

@@ -1,4 +1,8 @@
 // identity.ts
+function isLiveKey(record, now = Date.now()) {
+  if (!record || record.retiredAt) return false;
+  return record.expiresAt === void 0 || record.expiresAt > now;
+}
 function isIdentityError(result) {
   return "error" in result;
 }
@@ -36,6 +40,9 @@ function registryRowMetadata(record) {
   if (typeof record.retiredAt === "number") meta.retiredAt = record.retiredAt;
   if (typeof record.repo === "string" || record.repo === null) meta.repo = record.repo;
   if (record.internal === true) meta.internal = true;
+  if (typeof record.heldBy === "string") meta.heldBy = record.heldBy;
+  if (typeof record.expiresAt === "number") meta.expiresAt = record.expiresAt;
+  if (record.via === "grant" || record.via === "fleet") meta.via = record.via;
   const bytes = new TextEncoder().encode(JSON.stringify(meta)).length;
   return bytes <= REGISTRY_METADATA_MAX_BYTES ? meta : void 0;
 }
@@ -47,8 +54,10 @@ function recordFromRegistryMetadata(raw) {
   const out = { name: m.name };
   const str = (k) => m[k] === void 0 || typeof m[k] === "string";
   const num = (k) => m[k] === void 0 || typeof m[k] === "number";
-  if (!str("tier") || !str("userId")) return null;
-  if (!num("createdAt") || !num("lastSeenAt") || !num("retiredAt")) return null;
+  if (!str("tier") || !str("userId") || !str("heldBy")) return null;
+  if (!num("createdAt") || !num("lastSeenAt") || !num("retiredAt") || !num("expiresAt"))
+    return null;
+  if (m.via !== void 0 && m.via !== "grant" && m.via !== "fleet") return null;
   if (m.repo !== void 0 && m.repo !== null && typeof m.repo !== "string") return null;
   if (m.internal !== void 0 && m.internal !== true) return null;
   if (m.tier !== void 0) out.tier = m.tier;
@@ -58,6 +67,9 @@ function recordFromRegistryMetadata(raw) {
   if (m.retiredAt !== void 0) out.retiredAt = m.retiredAt;
   if (m.repo !== void 0) out.repo = m.repo;
   if (m.internal === true) out.internal = true;
+  if (m.heldBy !== void 0) out.heldBy = m.heldBy;
+  if (m.expiresAt !== void 0) out.expiresAt = m.expiresAt;
+  if (m.via !== void 0) out.via = m.via;
   return out;
 }
 function registryKv(env) {
@@ -93,7 +105,7 @@ async function scanRegistry(env) {
 async function readLiveRows(env) {
   const rows = [];
   for (const { record } of await scanRegistry(env)) {
-    if (record.retiredAt || !record.userId) continue;
+    if (!isLiveKey(record) || !record.userId) continue;
     rows.push({ userId: record.userId, name: record.name ?? null, tier: record.tier });
   }
   return rows;
@@ -104,7 +116,7 @@ async function isRegistryNameTaken(env, name, exclude) {
   const excludeEntry = `${KEY_PREFIX}${exclude.rawKey}`;
   for (const { entry, record } of await scanRegistry(env)) {
     if (entry === excludeEntry) continue;
-    if (record.retiredAt) continue;
+    if (!isLiveKey(record)) continue;
     if (exclude.userId && record.userId === exclude.userId) continue;
     if (record.name && foldName(record.name) === target) return true;
   }
@@ -119,7 +131,7 @@ async function resolveRegistryName(env, name) {
   const target = foldName(name);
   if (!target) return null;
   for (const { record } of await scanRegistry(env)) {
-    if (record.retiredAt || !answersToName(record.tier)) continue;
+    if (!isLiveKey(record) || !answersToName(record.tier)) continue;
     if (record.name && foldName(record.name) === target) {
       return { name: record.name, userId: record.userId ?? null, tier: record.tier };
     }
@@ -226,6 +238,7 @@ export {
   REGISTRY_METADATA_MAX_BYTES,
   answersToName,
   isIdentityError,
+  isLiveKey,
   isRegistryNameTaken,
   liveRowsByName,
   readLiveRows,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadoku/worker-utils",
-  "version": "1.6.20",
+  "version": "1.7.0",
   "license": "ISC",
   "description": "Shared utilities for Cloudflare Workers",
   "repository": {