@hadoku/worker-utils 0.0.0-stage → 1.6.19

package/dist/edge-routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Single source of truth for hadoku.me edge prefixes.
+ *
+ * Direct `'https://hadoku.me/...'` string literals outside this file are
+ * a lint error after Tier 4 of the 2026-05-14 quality refactor. Reuse
+ * these constants so a hostname migration is one diff, not a grep-replace
+ * across 8+ files.
+ *
+ * Browser fetches must hit `EDGE_BASE/{prefix}/*` per the repo invariant
+ * recorded in AGENTS.md: direct `*.hadoku.me` subdomains are reserved for
+ * service-to-service traffic only.
+ */
+declare const EDGE_BASE = "https://hadoku.me";
+declare const MGMT_BASE = "https://hadoku.me/mgmt";
+declare const MONITORING_BASE = "https://hadoku.me/health";
+declare const SCRAPER_BASE = "https://hadoku.me/scraper";
+declare const CONTACT_BASE = "https://hadoku.me/contact";
+declare const RESUME_BASE = "https://hadoku.me/resume";
+declare const DISPATCH_BASE = "https://hadoku.me/dispatch";
+declare const PREFS_BASE = "https://hadoku.me/prefs";
+declare const JOBPLATFORM_BASE = "https://hadoku.me/jobplatform";
+/**
+ * Build a `*.workers.dev` URL for a sibling worker.
+ *
+ * Used by health checks and monitoring code that needs to bypass
+ * edge-router (e.g. checking whether the worker itself is reachable
+ * independent of the edge). Browser code MUST NOT use this — go through
+ * `EDGE_BASE/{prefix}/*` instead.
+ *
+ * Callers MUST pass `subdomain` explicitly (typically from
+ * `env.CF_WORKERS_SUBDOMAIN`). No implicit env lookup — CF Workers don't
+ * have a `process` global and the binding is per-request.
+ */
+declare function workersDevUrl(workerName: string, subdomain: string | undefined): string;
+/**
+ * The vault broker's machine-to-machine paths: mgmt-api's status probe, the
+ * vault status pre-flight, and single-secret reads. Exact paths (plus the one
+ * `get/` prefix), so the rest of `/mgmt/api/*` is not caught.
+ *
+ * edge-router keeps only their FAILURES in request_logs (a success says nothing
+ * mgmt-api does not audit itself), so anything that aggregates request_logs
+ * must leave them out too: over an errors-only sample, a count, latency or
+ * error rate describes the failures and reads as the route's health.
+ */
+declare function isBrokerPlumbing(path: string): boolean;
+
+export { CONTACT_BASE, DISPATCH_BASE, EDGE_BASE, JOBPLATFORM_BASE, MGMT_BASE, MONITORING_BASE, PREFS_BASE, RESUME_BASE, SCRAPER_BASE, isBrokerPlumbing, workersDevUrl };

package/dist/edge-routes.js

@@ -0,0 +1,34 @@
+// edge-routes.ts
+var EDGE_BASE = "https://hadoku.me";
+var MGMT_BASE = `${EDGE_BASE}/mgmt`;
+var MONITORING_BASE = `${EDGE_BASE}/health`;
+var SCRAPER_BASE = `${EDGE_BASE}/scraper`;
+var CONTACT_BASE = `${EDGE_BASE}/contact`;
+var RESUME_BASE = `${EDGE_BASE}/resume`;
+var DISPATCH_BASE = `${EDGE_BASE}/dispatch`;
+var PREFS_BASE = `${EDGE_BASE}/prefs`;
+var JOBPLATFORM_BASE = `${EDGE_BASE}/jobplatform`;
+function workersDevUrl(workerName, subdomain) {
+  if (!subdomain) {
+    throw new Error(
+      `CF_WORKERS_SUBDOMAIN not configured \u2014 cannot build workers.dev URL for ${workerName}.`
+    );
+  }
+  return `https://${workerName}.${subdomain}.workers.dev`;
+}
+function isBrokerPlumbing(path) {
+  return path === "/mgmt/api/status" || path === "/mgmt/api/secrets/status" || path.startsWith("/mgmt/api/secrets/get/");
+}
+export {
+  CONTACT_BASE,
+  DISPATCH_BASE,
+  EDGE_BASE,
+  JOBPLATFORM_BASE,
+  MGMT_BASE,
+  MONITORING_BASE,
+  PREFS_BASE,
+  RESUME_BASE,
+  SCRAPER_BASE,
+  isBrokerPlumbing,
+  workersDevUrl
+};

package/dist/identity.d.ts

@@ -0,0 +1,477 @@
+/**
+ * The identity module — the single owner of "who does this row belong to".
+ *
+ * Normative contract: `docs/architecture/IDENTITY_MODEL.md` in hadoku_site.
+ * A comment could not hold this model; one already failed and took a working
+ * guard with it (the 2026-08-25 study incident, §7 there). So the rules live
+ * here, as the SHAPE OF AN API rather than as prose:
+ *
+ *   - R3/R4 — ownership is keyed on `userId`; a `name` is input only. The only
+ *     way out of this module is a resolved userId, so storing a name is not
+ *     something a caller can do by accident.
+ *   - R5 — every user reference arriving in a request body is unresolved input.
+ *     THIS MODULE EXPORTS NO FUNCTION THAT RETURNS AN UNRESOLVED IDENTIFIER.
+ *     `resolveGrantee` has no `userId` passthrough: handing it a userId is not
+ *     a way to skip the registry, because there is no such way. That is the
+ *     clause both incidents broke.
+ *   - R6 — this file is a BOUNDARY, so it validates. Code downstream of it has
+ *     been handed a resolved userId and treats it as opaque: store it, compare
+ *     it, pass it through, never parse it.
+ *   - R10 — what comes back is a BARE userId. hopper addresses its rows as
+ *     `u:{userId}`; a consumer applies its own key derivation, and this module
+ *     never assumes the column holds the raw value.
+ *
+ * Everything here READS the registry and never writes it, never stores a key,
+ * and never logs one. Minting is edge-router's and mgmt-api's alone (R2). The
+ * one thing a writer takes from here is {@link registryRowMetadata}: the shape
+ * every `key:` put must stamp so these reads can skip the per-row `get`.
+ *
+ * TWO WAYS TO READ IT, and the difference is a GRANT, not a preference:
+ *   - directly, through a `SESSIONS_KV` binding. That namespace is keyed
+ *     `key:{rawKey}`, so its KEYS ARE CREDENTIALS, and Workers KV has neither
+ *     prefix scoping nor a read-only binding mode. This file can keep the raw
+ *     key from leaving the FILE; nothing can keep it from the worker holding
+ *     the binding. So the grant an app takes on to answer one name lookup is
+ *     `list()` over every live key in the fleet, plus write.
+ *   - through `resolveGranteeVia`, over a service binding to edge-router,
+ *     which answers the one question and discloses nothing else.
+ *
+ * A worker that already resolves BY RAW KEY (a server-to-server ingest that
+ * holds credentials) needs the direct binding. A worker resolving a NAME so a
+ * human can hand a row to someone else does not, and should not have it.
+ */
+/**
+ * The tiers a KEY may hold — the registry's `tier` field.
+ *
+ * Deliberately NOT the same set as `Tier` in ./auth: `public` is the ABSENCE of
+ * a valid key, never a value stored on a row, so a row typed `public` would be
+ * a key that authenticates as nobody. Ordering lives in `TIER_RANK`; this type
+ * only enumerates what may be WRITTEN. Adding a tier means adding it in both.
+ */
+type KeyTier = 'admin' | 'wife' | 'service' | 'friend' | 'member';
+/**
+ * A row in the key registry: `key:{rawKey}` → this.
+ *
+ * THE canonical definition (G1). It used to be hand-copied into edge-router,
+ * hadoku-task and two test fixtures, which is how the same field acquired four
+ * different doc comments and one of them acquired a false example.
+ *
+ * Two views of one type, and the asymmetry is deliberate:
+ *   - a WRITER (edge-router, mgmt-api) produces a whole record, so `name`,
+ *     `tier`, `createdAt` and `lastSeenAt` are required here;
+ *   - a READER parses untrusted JSON out of KV, so it goes through
+ *     `parseRegistryRow` below and gets a `Partial<KeyRegistryRecord>`. A row
+ *     written before a field existed is a real thing that must not throw.
+ */
+interface KeyRegistryRecord {
+    /** User-provided display name. null = key issued but not yet claimed. */
+    name: string | null;
+    /**
+     * Tier resolved at the time of last write.
+     *   - admin/wife/friend: human-user keys, set on /session/create or by the
+     *     mgmt-api lifecycle broker (mint / rename / set-tier).
+     *   - service: machine-to-machine keys (PM2 wrappers, dev-vault shim, CLI).
+     *     Service keys never go through the cookie/session flow — they are
+     *     header-only (X-User-Key) and are issued exclusively via the broker.
+     *
+     * `wife` (added 2026-08-04) outranks service and sits below admin: a human
+     * tier reaching every service-gated surface without the vault / mgmt-api CLI
+     * admin that `KEY_ADMIN_*` confers.
+     */
+    tier: KeyTier;
+    /** ms epoch — first time this key was seen by the broker. Set once. */
+    createdAt: number;
+    /**
+     * ms epoch — last time this key AUTHENTICATED anything, not last login.
+     *
+     * Written by `upsertKeyRecord` (login / self-rename) and by
+     * `touchKeyLastSeen` (authGate, on any request that resolves this key,
+     * throttled). Counting only logins made the field a lie: sessions carry a
+     * 30-day sliding TTL, so a friend who signs in once and browses daily for
+     * months froze at the login date — and the same number is what an operator
+     * uses to judge whether a key is dead enough to retire.
+     */
+    lastSeenAt: number;
+    /**
+     * Stable per-user identifier, decoupled from the raw key value.
+     *
+     * A **v4 UUID**, minted lazily on first upsert/admin-set and preserved
+     * across key rotation, so per-user data survives a rotation (R2/R3). Five
+     * mint sites exist and all of them are `crypto.randomUUID()`; every live
+     * row conformed when verified against KV on 2026-08-27.
+     *
+     * It is NOT the display name. A row named `Hadoku` has a UUID userId like
+     * any other; `hadoku` is never one. A comment here once offered `hadoku` as an example userId, hadoku-study cited that when
+     * deleting a correct guard, and a display name landed in an ownership
+     * column. The two identifiers are on the same record, which is why they get
+     * confused, and why this module is the only thing allowed to turn one into
+     * the other.
+     *
+     * Downstream of a resolve, treat it as opaque — store, compare, pass
+     * through, never parse (R6). The rule that prevents the incident is not
+     * "check the shape": it is NEVER STORE AN IDENTIFIER YOU DID NOT RESOLVE.
+     * A registry lookup rejects `hadoku` AND a well-formed UUID belonging to
+     * nobody, which a regex waves through.
+     *
+     * Absent on a legacy row that has never signed in — such a row authenticates
+     * but cannot own anything, which is `NO_USER_ID` below.
+     */
+    userId?: string;
+    /**
+     * ms epoch — when this key was retired by a rotation swap. Set once, by the
+     * rotation path (mgmt-api markKeyRetired), and NEVER cleared. A retired key
+     * can no longer authenticate — but its row is deliberately KEPT so old logs
+     * (which reference masked key prefixes) still resolve back to a user via
+     * `userId`. Absent = still live. Rows with a `retiredAt` are the historical
+     * key ledger and must never be purged by inventory cleanup.
+     *
+     * The two resolution paths treat it differently, on purpose: a retired KEY
+     * still names its user (rotation preserves the userId), a retired NAME does
+     * not (names are renameable and may since have moved). See `resolveGrantee`.
+     */
+    retiredAt?: number;
+    /** The managed-identity id whose swap retired this key (forensic trail). */
+    retiredFrom?: string;
+    /**
+     * A key nobody holds (added 2026-10-29): minted by edge-router's sign-up
+     * route behind a passkey, never by the mgmt-api broker, and never shown to
+     * anyone. Set once at sign-up and never changed, so set-tier can promote the
+     * account without the key turning into something the vault should hold.
+     * Every path that accepts a PRESENTED key refuses it (a leaked copy signs in
+     * nobody), and `check-key-sync` does not expect a vault item for it.
+     */
+    internal?: true;
+    /**
+     * The GitHub repo this key belongs to, as `owner/name` (added 2026-07-29).
+     * null/absent = no repo association, which is the honest answer for a human
+     * friend key or a credential that no repo owns.
+     *
+     * WHY IT LIVES HERE. The mint path has always KNOWN the repo —
+     * `key-generate --repo PATH` takes it — and threw it away: the only durable
+     * copy was `secret_acl.source_id`, a bare directory BASENAME in a hash-keyed
+     * secrets-accounting table, which cannot tell `WolffM/foo` from
+     * `SomeoneElse/foo`. So "which identity is this repo's key" was unanswerable,
+     * and the naming convention is no substitute: three incompatible shapes are
+     * in live use (`agent-<repo>`, `<repo>-devvault`, `<repo>-e2e`) and a string
+     * heuristic would silently no-op on most repos. Authorization identity
+     * belongs on the identity row, not in vault bookkeeping.
+     *
+     * Written ONLY by the mgmt-api lifecycle broker (mint / register / set-repo).
+     * Read by `listKeysByRepo` and by task-api through its own read-only
+     * SESSIONS_KV binding.
+     */
+    repo?: string | null;
+}
+/** The minimum SESSIONS_KV surface this module uses. Read-only, by construction.
+ *
+ * `list` declares the PAGINATION fields, not just `keys`. Omitting them was not
+ * merely incomplete — it made the truncation bug untypeable: `scanRegistry`
+ * could not have followed the cursor without a type error, so the narrow shape
+ * quietly asserted that one call returns everything. It does not; Workers KV
+ * caps a page at 1000. Keep `list_complete` here so that stays impossible to
+ * write. */
+interface RegistryKvNamespace {
+    get(key: string): Promise<string | null>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+            metadata?: unknown;
+        }[];
+        list_complete?: boolean;
+        cursor?: string;
+    }>;
+}
+/** Any env carrying the read-only registry binding. */
+interface RegistryEnv {
+    SESSIONS_KV?: RegistryKvNamespace;
+}
+/** A resolved identity. Never carries key material. */
+interface ResolvedIdentity {
+    /** The stable per-user id ownership is keyed on (R3). Bare — see R10. */
+    userId: string;
+    /** Display name, echoed so a caller can confirm the identity (R4). */
+    name: string | null;
+    /** The row's tier, echoed for the same reason. */
+    tier?: string;
+}
+/** Why a resolve did not produce an identity. `status` is the HTTP code to send. */
+interface IdentityError {
+    error: string;
+    status: 400 | 404 | 409 | 503;
+    code?: 'NAME_NOT_FOUND' | 'NO_USER_ID' | 'NO_REGISTRY';
+}
+type IdentityResult = ResolvedIdentity | IdentityError;
+/** Narrow an {@link IdentityResult}. Cheaper to read than `'error' in x` at call sites. */
+declare function isIdentityError(result: IdentityResult): result is IdentityError;
+/**
+ * A row matched, but it has never signed in, so no userId has been minted for
+ * it. It can authenticate and it cannot own anything — a real state, and not
+ * the same as "no such name", which is why it gets its own code and a 409.
+ */
+declare const NO_USER_ID: IdentityError;
+/**
+ * This worker has no registry binding, so no reference can be resolved AT ALL.
+ *
+ * Not a 4xx. Every other error here is a verdict ON THE INPUT — that name does
+ * not exist, that key never signed in — and reporting an unreachable registry
+ * in the same shape tells the caller their input is wrong when it may be
+ * perfectly good. It is an OUTAGE: 503, retryable, and true.
+ *
+ * It gets a code because callers could not tell it apart otherwise, and two of
+ * the three live call sites proved it. `watchparty-stats-api` reached around
+ * this module into `env.SESSIONS_KV` to make the distinction itself — correct
+ * answer, wrong seam, and only available to a caller who already knows the
+ * binding's name. `hadoku-study` did not, and mapped it through
+ * `status === 409 ? 409 : 404`, so a transfer against a worker whose binding
+ * was missing reported "No registered key named X" — a 404 blaming a name that
+ * was never looked up.
+ *
+ * Absence must be typed, never inferred by the caller from the outside (R8).
+ */
+declare const NO_REGISTRY: IdentityError;
+/**
+ * What every `key:` row carries as KV LIST METADATA — the fields a scan needs,
+ * copied out of the row's value at write time (hadoku_site#450).
+ *
+ * WHY. `kv.list()` returns key names, and before this each one then cost its
+ * own `get`: at 872 rows (2026-10-10; 84% of them retired, growing +33/day as
+ * `keys:bulk-swap` retires one row per service identity nightly) that put a
+ * named sign-in's `isNameTaken` and the share picker's user search at 1.4–4s.
+ * Workers KV hands back up to 1,024 bytes of metadata per key inside the list
+ * page itself, so with this stamped a scan is one `list` per thousand rows and
+ * zero gets.
+ *
+ * HOW IT STAYS TRUE. Metadata is written in the SAME put as the value, so the
+ * two cannot disagree for a writer that derives one from the other — and every
+ * writer does, through this function (edge-router) or its mirror in mgmt-api's
+ * `registry-metadata.ts`, pinned equal by `registry-metadata-parity.test.ts`. A
+ * put WITHOUT metadata clears it, which is the safe direction: such a row is
+ * read with a `get`, exactly as every row was before. So a writer that forgets
+ * costs speed, never correctness. mgmt-api's nightly `keys:registry-metadata`
+ * stamps any such row and `check:key-sync` reports one whose metadata
+ * disagrees with its value.
+ *
+ * WHAT IT IS NOT. Auth. `resolveKeyTier` reads the row's VALUE and always
+ * will; metadata answers only the scans (names, search, inventory), so a stale
+ * copy can mislabel a picker entry but can never admit a key.
+ *
+ * `v` versions the shape. A reader accepts only a version it knows and falls
+ * back to the value for anything else, so changing the shape is a version bump
+ * plus a re-stamp, never a flag day.
+ */
+interface RegistryRowMetadata {
+    v: 1;
+    name: string | null;
+    tier?: string;
+    userId?: string;
+    createdAt?: number;
+    lastSeenAt?: number;
+    retiredAt?: number;
+    repo?: string | null;
+    /** Present only as `true`, on a sign-up key (KeyRegistryRecord.internal). */
+    internal?: true;
+}
+/** Workers KV's ceiling on serialized list metadata, in bytes. */
+declare const REGISTRY_METADATA_MAX_BYTES = 1024;
+/**
+ * The metadata to stamp alongside `record`, or `undefined` when it would not
+ * fit — in which case the row is written without, and read by `get`.
+ *
+ * Only fields present on the record are copied, so metadata never asserts a
+ * value the row does not hold.
+ */
+declare function registryRowMetadata(record: Partial<KeyRegistryRecord>): RegistryRowMetadata | undefined;
+/**
+ * The record a list entry's metadata describes, or null when it carries none
+ * this reader understands — the caller then reads the value.
+ *
+ * Validates every field it copies. A malformed field means the whole entry is
+ * distrusted rather than half-used: one `get` is cheap, a half-read row is not.
+ */
+declare function recordFromRegistryMetadata(raw: unknown): Partial<KeyRegistryRecord> | null;
+/**
+ * Every LIVE registry row — non-retired, and carrying a userId. Built on
+ * `scanRegistry`, so a stamped row costs no `get` at all.
+ *
+ * Rows without a userId are excluded because such a row cannot own anything.
+ * Use {@link resolveRegistryName} when you need to tell "no such name" apart
+ * from "that name has never signed in".
+ */
+declare function readLiveRows(env: RegistryEnv): Promise<ResolvedIdentity[]>;
+/**
+ * Is `name` already claimed by someone other than the caller?
+ *
+ * Lives here rather than in edge-router because it is the same scan as
+ * everything else in this file and it answers a question about IDENTITY, not
+ * about KV. Two exclusions, and both are load-bearing:
+ *
+ *   - `exclude.rawKey` — the caller's own row. Without it, re-saving your own
+ *     name reads as a collision with yourself.
+ *   - `exclude.userId` — the caller's ROTATION PAIR. One identity holds an
+ *     active key and a standby, both carrying the same name and userId; the
+ *     standby is a different `rawKey`, so only the userId exclusion catches it.
+ *
+ * Unlike {@link readLiveRows} this considers rows with NO userId. A key minted
+ * with a name but never signed in holds that name — it is "in transit", not
+ * free — and treating it as free would let a second user claim a name an
+ * operator has already handed out. That distinction is exactly why this is not
+ * built on `readLiveRows`, which drops those rows because they cannot OWN
+ * anything. Holding a name and owning a row are different questions.
+ *
+ * A raw key goes IN (the caller already holds it) and never comes out.
+ */
+declare function isRegistryNameTaken(env: RegistryEnv, name: string, exclude: {
+    rawKey: string;
+    userId?: string;
+}): Promise<boolean>;
+/**
+ * Resolve a registry DISPLAY NAME to its live row.
+ *
+ * Case-folded, retired-row-excluding — the same match `isNameTaken` makes in
+ * edge-router, so a name is exactly as unambiguous here as it is there.
+ *
+ * Returns null when no live row carries the name, and `userId: null` when a row
+ * matched but has never signed in. Null is AMBIGUOUS here — "no registry" and
+ * "no such name" both read as it — which is why this is the low-level primitive
+ * and {@link resolveGrantee} is what a request handler should call: that one
+ * separates the two as {@link NO_REGISTRY} and returns a caller nothing it has
+ * to infer from the outside.
+ */
+/**
+ * Whether a row answers to its NAME: everyone but a member. A member signed
+ * themselves up (edge-router accounts.ts) and is known to cardtable only, so
+ * a name a friend types into a picker or a grant never resolves to one. That
+ * keeps a stranger's name from shadowing a friend's in anything that hands
+ * out access by name.
+ */
+declare function answersToName(tier: string | undefined): boolean;
+declare function resolveRegistryName(env: RegistryEnv, name: string): Promise<{
+    name: string;
+    userId: string | null;
+    tier?: string;
+} | null>;
+/**
+ * Every live row keyed by LOWERCASED display name, for callers resolving many
+ * names at once. `resolveRegistryName` costs a full scan per name; a reconcile
+ * over N boards would pay that 2N times. This pays it once.
+ *
+ * A name on more than one live row is operator error (the registry treats names
+ * as unique, `isNameTaken`-style); last row wins, matching how
+ * {@link registryNameMap} resolves a duplicate userId.
+ */
+declare function liveRowsByName(env: RegistryEnv): Promise<Map<string, ResolvedIdentity>>;
+/**
+ * userId → `{ name, tier }`, in ONE scan, for annotating a list of owners.
+ *
+ * A userId legitimately appears on more than one row mid-rotation (the active
+ * key and its standby share an identity). `readLiveRows` has already dropped
+ * the retired half, so what lands in the map is the LIVE row — which is the
+ * whole point, since the retired one carries the same name anyway and the map
+ * must not depend on scan order to say so.
+ *
+ * Degrades to an empty map when there is no registry rather than throwing: an
+ * annotation failure must never cost the caller the list it was annotating.
+ */
+declare function registryNameMap(env: RegistryEnv): Promise<Map<string, {
+    name: string | null;
+    tier?: string;
+}>>;
+/**
+ * The shortest query a name search will answer.
+ *
+ * Two, not one. A single character matches most of a 113-row registry, which
+ * turns an autocomplete into a directory dump; two is still a usable prefix for
+ * a human who is typing a name they already know.
+ */
+declare const MIN_SEARCH_QUERY_LENGTH = 2;
+/**
+ * Search live display names by case-insensitive substring, for a person-picker.
+ *
+ * Display names carry no auth bearing, so returning them is safe — but the SET
+ * of them is an enumeration of the registry, so a caller must be tier-gated and
+ * `query` must be substantial. Results dedupe by name, prefix matches sort
+ * first, and the list is capped.
+ *
+ * Returns names and tiers ONLY. No userId leaves here: a person-picker has no
+ * use for one, and a selector that hands out ids invites the caller to send one
+ * back, which is exactly the shape R5 forbids.
+ */
+declare function searchRegistryNames(env: RegistryEnv, query: string, limit: number): Promise<{
+    name: string;
+    tier?: string;
+}[]>;
+/**
+ * A service binding to edge-router. Structurally a `Fetcher`, declared here so
+ * a consumer needs no `@cloudflare/workers-types` import to type its env.
+ */
+interface EdgeIdentityBinding {
+    fetch(input: Request): Promise<Response>;
+}
+/**
+ * What {@link resolveGranteeVia} needs, passed rather than read off a named env
+ * var — so the package does not get a vote on what a consumer calls its
+ * secret. jobplatform-api already holds a service-tier key as
+ * `HADOKU_SERVICE_KEY`; requiring an `EDGE_IDENTITY_KEY` would have meant
+ * provisioning a second vault item holding the same credential, and two names
+ * for one secret is how one of them goes stale.
+ */
+interface EdgeIdentityCall {
+    /** The display name to resolve. Input only — never storage (R4). */
+    name: string;
+    /** A SERVICE-tier key this worker already holds. Never logged, never stored. */
+    serviceKey: string;
+}
+/**
+ * {@link resolveGrantee}, over a service binding instead of a registry binding.
+ *
+ * SAME QUESTION, MUCH SMALLER GRANT — that is the entire reason it exists.
+ * `resolveGrantee` reads `SESSIONS_KV` directly, and that namespace is keyed
+ * `key:{rawKey}`: its KEYS are the fleet's credentials. Workers KV has no
+ * prefix scoping and no read-only binding mode, so binding it into an app to
+ * answer one name lookup hands that whole worker `list()` over every live key,
+ * and write access besides. This module can keep the raw key inside the FILE
+ * (see `scanRegistry`); it cannot keep it inside the worker. Five apps hold
+ * that grant today and each new consumer widens it.
+ *
+ * Over the binding, the caller learns one userId for one name it already knew.
+ *
+ * WHICH ONE TO USE:
+ *   - a worker that ALREADY resolves by raw key (a server-to-server ingest
+ *     holding credentials) keeps `resolveGrantee` and its registry binding —
+ *     there is no `key` branch here, deliberately: a route that says whether an
+ *     arbitrary key resolves is a credential oracle, which trades the exposure
+ *     this function exists to remove for a different one;
+ *   - anything resolving a NAME so a human can hand a row to someone else —
+ *     the transfer/assign shape — should use this.
+ *
+ * Returns the identical {@link IdentityResult}, so the two are interchangeable
+ * at a call site. A hop that fails is {@link NO_REGISTRY}: from the caller's
+ * side an unreachable resolver and an unbound registry are the same fact —
+ * identity cannot be resolved right now, the input is not at fault, retry.
+ */
+declare function resolveGranteeVia(edge: EdgeIdentityBinding | undefined, input: EdgeIdentityCall): Promise<IdentityResult>;
+/**
+ * Turn an inbound reference into an owner — THE only way to obtain one.
+ *
+ * Two ways in, and neither of them is "trust what you were sent":
+ *   - by display NAME — preferred. It is the identifier a human actually has,
+ *     and no credential changes hands.
+ *   - by raw KEY — a bearer credential, for a server-to-server ingest that
+ *     holds one. Never stored, never logged, never echoed.
+ *
+ * There is deliberately NO `userId` branch (R5). A userId in a request body is
+ * a claim: it can be a display name someone read in a doc comment, or a
+ * well-formed UUID belonging to nobody, and neither is distinguishable from a
+ * real one without asking the registry. Adding a passthrough here would make
+ * every consumer's R5 compliance optional again, which is how a display name
+ * reached `sets.owner_user_id` on 2026-08-25.
+ */
+declare function resolveGrantee(env: RegistryEnv, input: {
+    name?: string;
+    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 };