@hadoku/worker-utils 0.0.0-stage → 1.6.20

package/dist/identity.js

@@ -0,0 +1,239 @@
+// identity.ts
+function isIdentityError(result) {
+  return "error" in result;
+}
+var NO_USER_ID = {
+  error: "That key has never signed in, so it has no id yet.",
+  status: 409,
+  code: "NO_USER_ID"
+};
+var NO_REGISTRY = {
+  error: "Identity resolution is unavailable: this worker has no key registry.",
+  status: 503,
+  code: "NO_REGISTRY"
+};
+var KEY_PREFIX = "key:";
+function parseRegistryRow(raw) {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+var REGISTRY_METADATA_MAX_BYTES = 1024;
+function registryRowMetadata(record) {
+  const meta = {
+    v: 1,
+    name: typeof record.name === "string" ? record.name : null
+  };
+  if (typeof record.tier === "string") meta.tier = record.tier;
+  if (typeof record.userId === "string") meta.userId = record.userId;
+  if (typeof record.createdAt === "number") meta.createdAt = record.createdAt;
+  if (typeof record.lastSeenAt === "number") meta.lastSeenAt = record.lastSeenAt;
+  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;
+  const bytes = new TextEncoder().encode(JSON.stringify(meta)).length;
+  return bytes <= REGISTRY_METADATA_MAX_BYTES ? meta : void 0;
+}
+function recordFromRegistryMetadata(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const m = raw;
+  if (m.v !== 1) return null;
+  if (m.name !== null && typeof m.name !== "string") return null;
+  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 (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;
+  if (m.userId !== void 0) out.userId = m.userId;
+  if (m.createdAt !== void 0) out.createdAt = m.createdAt;
+  if (m.lastSeenAt !== void 0) out.lastSeenAt = m.lastSeenAt;
+  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;
+  return out;
+}
+function registryKv(env) {
+  const kv = env.SESSIONS_KV;
+  if (!kv || typeof kv.list !== "function" || typeof kv.get !== "function") return null;
+  return kv;
+}
+function foldName(name) {
+  return name.trim().toLowerCase();
+}
+async function scanRegistry(env) {
+  const kv = registryKv(env);
+  if (!kv) return [];
+  const entries = [];
+  let cursor;
+  for (; ; ) {
+    const page = await kv.list({ prefix: KEY_PREFIX, ...cursor ? { cursor } : {} });
+    for (const e of page.keys) entries.push(e);
+    if (page.list_complete) break;
+    cursor = page.cursor;
+    if (!cursor) break;
+  }
+  const rows = await Promise.all(
+    entries.map(async (e) => ({
+      entry: e.name,
+      record: recordFromRegistryMetadata(e.metadata) ?? parseRegistryRow(await kv.get(e.name))
+    }))
+  );
+  return rows.filter(
+    (r) => r.record !== null
+  );
+}
+async function readLiveRows(env) {
+  const rows = [];
+  for (const { record } of await scanRegistry(env)) {
+    if (record.retiredAt || !record.userId) continue;
+    rows.push({ userId: record.userId, name: record.name ?? null, tier: record.tier });
+  }
+  return rows;
+}
+async function isRegistryNameTaken(env, name, exclude) {
+  const target = foldName(name);
+  if (!target) return false;
+  const excludeEntry = `${KEY_PREFIX}${exclude.rawKey}`;
+  for (const { entry, record } of await scanRegistry(env)) {
+    if (entry === excludeEntry) continue;
+    if (record.retiredAt) continue;
+    if (exclude.userId && record.userId === exclude.userId) continue;
+    if (record.name && foldName(record.name) === target) return true;
+  }
+  return false;
+}
+function answersToName(tier) {
+  return tier !== MEMBER_TIER;
+}
+var MEMBER_TIER = "member";
+async function resolveRegistryName(env, name) {
+  if (!registryKv(env)) return null;
+  const target = foldName(name);
+  if (!target) return null;
+  for (const { record } of await scanRegistry(env)) {
+    if (record.retiredAt || !answersToName(record.tier)) continue;
+    if (record.name && foldName(record.name) === target) {
+      return { name: record.name, userId: record.userId ?? null, tier: record.tier };
+    }
+  }
+  return null;
+}
+async function liveRowsByName(env) {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of await readLiveRows(env)) {
+    if (row.name && answersToName(row.tier)) map.set(foldName(row.name), row);
+  }
+  return map;
+}
+async function registryNameMap(env) {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of await readLiveRows(env)) {
+    map.set(row.userId, { name: row.name, tier: row.tier });
+  }
+  return map;
+}
+var MIN_SEARCH_QUERY_LENGTH = 2;
+async function searchRegistryNames(env, query, limit) {
+  const q = foldName(query);
+  if (q.length < MIN_SEARCH_QUERY_LENGTH) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const row of await readLiveRows(env)) {
+    if (!row.name || !answersToName(row.tier)) continue;
+    const lower = foldName(row.name);
+    if (!lower.includes(q) || seen.has(lower)) continue;
+    seen.add(lower);
+    out.push({ name: row.name, tier: row.tier });
+  }
+  out.sort((a, b) => {
+    const ap = foldName(a.name).startsWith(q) ? 0 : 1;
+    const bp = foldName(b.name).startsWith(q) ? 0 : 1;
+    return ap - bp || a.name.localeCompare(b.name);
+  });
+  return out.slice(0, Math.max(0, limit));
+}
+async function resolveGranteeVia(edge, input) {
+  if (!edge || typeof edge.fetch !== "function" || !input.serviceKey) return NO_REGISTRY;
+  if (!input.name.trim()) return { error: "`name` is empty.", status: 400 };
+  const url = `https://hadoku.me/session/identity/resolve?name=${encodeURIComponent(input.name)}`;
+  let res;
+  try {
+    res = await edge.fetch(new Request(url, { headers: { "X-User-Key": input.serviceKey } }));
+  } catch {
+    return NO_REGISTRY;
+  }
+  if (res.status === 401 || res.status === 403) {
+    return NO_REGISTRY;
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return NO_REGISTRY;
+  }
+  if (!body || typeof body !== "object") return NO_REGISTRY;
+  if (res.ok) {
+    const row = body;
+    if (typeof row.userId !== "string" || !row.userId) return NO_REGISTRY;
+    return { userId: row.userId, name: row.name ?? null, tier: row.tier };
+  }
+  const err = body;
+  const status = res.status === 404 ? 404 : res.status === 409 ? 409 : res.status === 503 ? 503 : 400;
+  return {
+    error: typeof err.error === "string" ? err.error : "Identity resolution failed.",
+    status,
+    ...typeof err.code === "string" ? { code: err.code } : {}
+  };
+}
+async function resolveGrantee(env, input) {
+  if (input.name) {
+    if (!registryKv(env)) {
+      return NO_REGISTRY;
+    }
+    if (!input.name.trim()) return { error: "`name` is empty.", status: 400 };
+    const row = await resolveRegistryName(env, input.name);
+    if (!row) {
+      return {
+        error: `No registered key named "${input.name}".`,
+        status: 404,
+        code: "NAME_NOT_FOUND"
+      };
+    }
+    if (!row.userId) return NO_USER_ID;
+    return { userId: row.userId, name: row.name, tier: row.tier };
+  }
+  const key = input.key;
+  if (!key) return { error: "Provide `name` or `key`.", status: 400 };
+  const kv = registryKv(env);
+  if (!kv) return NO_REGISTRY;
+  const rec = parseRegistryRow(await kv.get(`${KEY_PREFIX}${key}`));
+  if (!rec) return { error: "That key is not registered.", status: 400 };
+  if (!rec.userId) return NO_USER_ID;
+  return { userId: rec.userId, name: rec.name ?? null, tier: rec.tier };
+}
+export {
+  MIN_SEARCH_QUERY_LENGTH,
+  NO_REGISTRY,
+  NO_USER_ID,
+  REGISTRY_METADATA_MAX_BYTES,
+  answersToName,
+  isIdentityError,
+  isRegistryNameTaken,
+  liveRowsByName,
+  readLiveRows,
+  recordFromRegistryMetadata,
+  registryNameMap,
+  registryRowMetadata,
+  resolveGrantee,
+  resolveGranteeVia,
+  resolveRegistryName,
+  searchRegistryNames
+};

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { HadokuAuthContext, HadokuAuthOptions } from './auth.js';
+export { TIER_RANK, Tier, getAuthContext, requireMinTier, tierAtLeast } from './auth.js';
+export { DEFAULT_CONTENT_LEVEL, MAX_CONTENT_LEVEL_BY_TIER, maxContentLevelForTier } from './content-level.js';
+import { MiddlewareHandler, Context } from 'hono';
+export { extractContext, extractField, getRequestMetadata, parseBody } from './context.js';
+export { CommonRules, isNonEmptyString, requireFields, validateFields } from './validation.js';
+export { CORSPresets, DEFAULT_HADOKU_ORIGINS, createCorsMiddleware, createHadokuCors, getCorsHeaders, isOriginAllowed, matchOrigin } from './cors.js';
+export { SENSITIVE_FIELDS, createLogger, createRequestLogger, formatError, logError, logRequest, loggerMiddleware, redactFields, startTimer } from './cloudflareWorkerLogger.js';
+export { RateLimitConfig, RateLimitResult, checkRateLimit, recordRequest, resetRateLimit } from './rate-limit.js';
+export { MASKING, maskEmail, maskIpAddress, maskKey, maskSessionId } from './masking.js';
+export { badRequest, created, healthCheck, notFound, ok, serverError, validationError } from './responses.js';
+export { AuthConfig, AuthContext, CORSConfig, ContextExtractionConfig, ErrorResponse, HealthCheckResponse, LogEntry, LogLevel, LoggerConfig, SuccessResponse, UserType, ValidationResult, ValidationRule } from './types.js';
+export { DetailedErrorResponseSchema, ErrorResponseSchema, PromptApiHealthResponseSchema, SimpleErrorResponseSchema, TaskApiHealthResponseSchema, ThrottleErrorResponseSchema, ValidationErrorResponseSchema, createDeleteResponseSchema, createHealthResponseSchema, createSuccessResponseSchema, createWrappedHealthResponseSchema } from './openapi-schemas.js';
+export { CommonTags, ErrorResponseFormat, badRequestWrapped, createErrorHandlers, createOpenAPIDocConfig, createValidationHook, createdWrapped, notFoundWrapped, okWrapped, serverErrorWrapped, simpleValidationHook, wrappedValidationHook } from './openapi-config.js';
+import '@wolffm/logger/worker';
+import '@hono/zod-openapi';
+import 'hono/utils/types';
+
+/**
+ * Edge-auth verification — the backend half of the centralized auth channel.
+ *
+ * edge-router (hadoku.me) resolves the caller's tier once, then stamps every
+ * proxied request with:
+ *   - `X-Edge-Auth: <EDGE_AUTH_SECRET>`  — provenance (proves it came via edge)
+ *   - `X-Hadoku-Tier: public|friend|service|wife|admin` — edge-resolved tier
+ *   - `X-User-Key: <key>`                — the resolved key (for audit trails)
+ *
+ * A backend worker calls `verifyEdgeAuth` / `createEdgeAuth` instead of
+ * resolving the key itself — only edge-router touches the key registry.
+ *
+ * DEGRADE-TO-PUBLIC, not refuse. Workers are reachable directly at
+ * `*.workers.dev` bypassing edge — and some of those direct hits are
+ * legitimate and PUBLIC (the monitoring probe hits `/…/health` directly with
+ * no auth header). So a request without valid `X-Edge-Auth` is treated as
+ * `public`, NOT refused: the edge-stamped `X-Hadoku-Tier` is only trusted when
+ * provenance checks out. This blocks tier-forgery (you can't send
+ * `X-Hadoku-Tier: admin` directly and be believed) while keeping public routes
+ * reachable. Protected routes still gate via `requireMinTier`, which 403s a
+ * public caller — so the provenance check effectively gates tier ELEVATION,
+ * not request admission.
+ *
+ * IDENTITY IS THE KEY'S, AND ONLY THE EDGE SAYS WHOSE KEY IT IS. edge-router
+ * resolves the caller's key against the registry and stamps `X-User-Id` /
+ * `X-User-Name` from that record (stripping any client copy first). On a direct
+ * hit nothing did that, so those headers are whatever the caller typed — and
+ * until 2026-10-09 they reached the app anyway: this middleware downgraded the
+ * TIER but left the identity headers on the request, and task and study read
+ * `X-User-Id` straight off it. Anyone could name any userId and act as that
+ * person. Now an unverified request has every edge-stamped identity header
+ * REMOVED before any handler runs (`c.req.raw` is replaced with a scrubbed
+ * copy), so code that reads the header directly — the common shape — sees no
+ * identity at all rather than a forged one. Verified requests are untouched,
+ * and their identity is also on `authContext.userId` / `.userName`, which is
+ * where new code should read it.
+ *
+ * `createEdgeAuth` is a drop-in for `createHadokuAuth`: it sets the same
+ * `authContext` ({ userType, credential }) and supports the same `extend`
+ * option, so a worker migrates by swapping the factory name. Keep the route's
+ * `requireMinTier(...)` gate — it's the backstop that turns "public direct
+ * hit" into a 403 on protected routes.
+ */
+
+/** Environment shape required by edge-auth — just the shared secret. */
+interface EdgeAuthEnv {
+    EDGE_AUTH_SECRET?: string;
+}
+type EdgeAuthResult = {
+    ok: true;
+    userType: HadokuAuthContext['userType'];
+    credential: string | null;
+    userId: string | null;
+    userName: string | null;
+} | {
+    ok: false;
+    reason: 'misconfigured' | 'bad-provenance';
+};
+/**
+ * Verify a request arrived via edge-router and extract the edge-resolved tier.
+ *
+ * - `misconfigured`: the worker has no EDGE_AUTH_SECRET bound — fail CLOSED.
+ *   (Every worker got the secret in Step 1; a missing one is a deploy fault,
+ *   and degrading to public would be a security hole.)
+ * - `bad-provenance`: X-Edge-Auth absent or mismatched — a direct
+ *   *.workers.dev hit, not edge traffic.
+ *
+ * On success, `userType` comes from X-Hadoku-Tier (defaults to 'public' if the
+ * header is absent/garbage but provenance is valid — e.g. an edge route that
+ * stamps auth but resolved an anonymous caller).
+ */
+declare function verifyEdgeAuth(c: Context, env: EdgeAuthEnv): EdgeAuthResult;
+/**
+ * Drop-in replacement for `createHadokuAuth`. Sets `authContext` to
+ * `{ userType, credential }` (+ any `extend` fields). When provenance is
+ * valid, the tier comes from the edge-stamped header; otherwise it degrades to
+ * `public` (see the module header — never refuses, never trusts an unverified
+ * tier). Never short-circuits: routes gate via `requireMinTier`.
+ *
+ * @example
+ * ```typescript
+ * // Before: app.use('*', createHadokuAuth<Env, Extra>({ extend }));
+ * // After:  app.use('*', createEdgeAuth<Env, Extra>({ extend }));
+ * ```
+ */
+declare function createEdgeAuth<TExtra extends Record<string, unknown> = Record<string, never>>(options?: HadokuAuthOptions<TExtra> & {
+    contextKey?: string;
+}): MiddlewareHandler;
+
+export { type EdgeAuthEnv, type EdgeAuthResult, HadokuAuthContext, HadokuAuthOptions, createEdgeAuth, verifyEdgeAuth };