kxco-pq-network 1.0.0

package/src/config.js

@@ -0,0 +1,126 @@
+// Network configuration, and the three verification modes.
+//
+// The modes are the product boundary, so they are worth stating plainly.
+//
+//   signature      the maths, and nothing else. Works offline, forever, with
+//                  no KXCO server in the path and no licence. This is what
+//                  kxco-post-quantum and kxco-verify do, and it stays free.
+//
+//   anchored       the maths, plus proof that the envelope was written to
+//                  Armature L1: chain id 1111111 and a transaction hash inside
+//                  the envelope. Still no HTTP at verify time — the anchor is
+//                  carried by the envelope, so an air-gapped verifier can
+//                  check it. What it cannot tell you is whether the key is
+//                  still good today.
+//
+//   anchored+live  anchored, plus a live registry lookup that says whether the
+//                  signing key is still active. This is the mode that answers
+//                  "should I act on this now", and it is the one that needs a
+//                  hosted registry.
+//
+// Only the maths is free. What we sell is the answer to whether a key is still
+// allowed to sign, which is a fact about the present that no amount of
+// offline cryptography can supply.
+
+import { KxcoPqNetworkError } from './errors.js'
+
+/** Armature L1. The only chain this package will accept an anchor from. */
+export const CHAIN_ID = 1111111
+
+export const DEFAULT_REGISTRY_URL = 'https://chain.kxco.ai'
+export const DEFAULT_RELAY_URL = 'https://relay.kxco.ai'
+export const DEFAULT_REGISTRY_TTL_MS = 60_000
+
+export const VERIFY_MODES = ['signature', 'anchored', 'anchored+live']
+
+/**
+ * Normalise and validate a network configuration.
+ *
+ * A missing licence key is not an error here. It becomes one at the point of
+ * use, where the message can say what the caller was actually trying to do:
+ * "signature" needs no licence at all, and refusing to construct a config
+ * without one would break the free path.
+ *
+ * @param {object} [config]
+ * @returns {Required<Pick<object,never>> & {
+ *   chainId: number, registryUrl: string, relayUrl: string,
+ *   verifyMode: string, licenceKey: string|null, registryTtlMs: number,
+ *   fetchImpl: typeof fetch, timeoutMs: number,
+ * }}
+ */
+export function networkConfig(config = {}) {
+  if (config === null || typeof config !== 'object') {
+    throw new KxcoPqNetworkError('network config must be an object', { code: 'BAD_CONFIG' })
+  }
+
+  const {
+    chainId = CHAIN_ID,
+    registryUrl = DEFAULT_REGISTRY_URL,
+    relayUrl = DEFAULT_RELAY_URL,
+    verifyMode = 'signature',
+    licenceKey = null,
+    registryTtlMs = DEFAULT_REGISTRY_TTL_MS,
+    fetchImpl,
+    timeoutMs = 10_000,
+  } = config
+
+  // A different chain id is not a configuration option. Accepting one would
+  // mean an anchor written to some other chain could satisfy a KXCO verify,
+  // which is the whole thing the anchor is supposed to prove.
+  if (chainId !== CHAIN_ID) {
+    throw new KxcoPqNetworkError(
+      `chainId must be ${CHAIN_ID} (Armature L1), got ${chainId}`,
+      { code: 'WRONG_CHAIN' },
+    )
+  }
+
+  if (!VERIFY_MODES.includes(verifyMode)) {
+    throw new KxcoPqNetworkError(
+      `unknown verifyMode '${verifyMode}' — expected one of ${VERIFY_MODES.join(', ')}`,
+      { code: 'BAD_CONFIG' },
+    )
+  }
+
+  for (const [name, value] of [['registryUrl', registryUrl], ['relayUrl', relayUrl]]) {
+    if (typeof value !== 'string' || !/^https?:\/\//.test(value)) {
+      throw new KxcoPqNetworkError(`${name} must be an http(s) URL, got ${value}`, { code: 'BAD_CONFIG' })
+    }
+  }
+
+  if (!Number.isFinite(registryTtlMs) || registryTtlMs < 0) {
+    throw new KxcoPqNetworkError('registryTtlMs must be a non-negative number', { code: 'BAD_CONFIG' })
+  }
+
+  return {
+    chainId,
+    registryUrl: registryUrl.replace(/\/$/, ''),
+    relayUrl: relayUrl.replace(/\/$/, ''),
+    verifyMode,
+    licenceKey: licenceKey || null,
+    registryTtlMs,
+    // Captured so a test can inject a mock without touching globals, and so a
+    // caller in a runtime with a scoped fetch can pass their own.
+    fetchImpl: fetchImpl ?? globalThis.fetch,
+    timeoutMs,
+  }
+}
+
+/**
+ * Read a configuration out of the environment.
+ *
+ * This is the whole of what a customer has to set to go live, which is why it
+ * is one function and not a framework.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ * @param {object} [overrides]
+ */
+export function networkConfigFromEnv(env = process.env, overrides = {}) {
+  return networkConfig({
+    registryUrl: env.KXCO_REGISTRY_URL || undefined,
+    relayUrl: env.KXCO_RELAY_URL || undefined,
+    verifyMode: env.KXCO_VERIFY_MODE || undefined,
+    licenceKey: env.KXCO_LICENCE_KEY || env.KXCO_LICENSE_KEY || null,
+    registryTtlMs: env.KXCO_REGISTRY_TTL_MS ? Number(env.KXCO_REGISTRY_TTL_MS) : undefined,
+    ...overrides,
+  })
+}

package/src/errors.js

@@ -0,0 +1,45 @@
+// One error type, with a code a caller can branch on.
+//
+// The codes matter more than the messages here, because the two failures a
+// customer must be able to tell apart — "this signature is forged" and "we
+// could not reach the registry" — look identical in a boolean.
+
+export class KxcoPqNetworkError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, status?: number|null, cause?: unknown }} [opts]
+   */
+  constructor(message, { code = 'NETWORK_ERROR', status = null, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause })
+    this.name = 'KxcoPqNetworkError'
+    this.code = code
+    this.status = status
+  }
+}
+
+/**
+ * Reasons a verification failed. A caller that treats every one of these the
+ * same way is running a weaker check than it thinks it is.
+ */
+export const FAILURE = {
+  /** The signature does not check out. The document is not what it claims. */
+  SIGNATURE_INVALID: 'signature_invalid',
+  /** Envelope structure is wrong or a required field is missing. */
+  MALFORMED: 'malformed',
+  /** The mode requires an anchor and the envelope carries none. */
+  NOT_ANCHORED: 'not_anchored',
+  /** The anchor names a chain that is not Armature L1. */
+  WRONG_CHAIN: 'wrong_chain',
+  /** The registry says this key was revoked. */
+  KID_REVOKED: 'kid_revoked',
+  /** The registry says this key was rotated out. */
+  KID_ROTATED: 'kid_rotated',
+  /** The credential is past its on-chain expiry. Not revoked — it ran out. */
+  KID_EXPIRED: 'kid_expired',
+  /** The registry has never heard of this key. */
+  KID_UNKNOWN: 'kid_unknown',
+  /** The registry could not be reached. Fails closed — see verifyEnvelope. */
+  REGISTRY_UNREACHABLE: 'registry_unreachable',
+  /** The mode needs a licence key and none was configured. */
+  LICENCE_REQUIRED: 'licence_required',
+}

package/src/index.d.ts

@@ -0,0 +1,169 @@
+/// <reference types="node" />
+
+/** Armature L1. The only chain an anchor may name. */
+export const CHAIN_ID: 1111111
+
+export const DEFAULT_REGISTRY_URL: 'https://chain.kxco.ai'
+export const DEFAULT_RELAY_URL: 'https://relay.kxco.ai'
+export const DEFAULT_REGISTRY_TTL_MS: 60000
+
+/**
+ * - `signature`     — crypto only. Offline, free, no KXCO server in the path.
+ * - `anchored`      — crypto, plus an Armature L1 anchor carried by the
+ *                     envelope. Still no HTTP at verify time.
+ * - `anchored+live` — anchored, plus a live registry lookup. Fails closed if
+ *                     the registry is unreachable. Requires a licence key.
+ */
+export type VerifyMode = 'signature' | 'anchored' | 'anchored+live'
+
+export const VERIFY_MODES: VerifyMode[]
+
+export interface NetworkConfigInput {
+  /** Must be 1111111 if given. Any other value throws. */
+  chainId?: 1111111
+  /** Defaults to https://chain.kxco.ai */
+  registryUrl?: string
+  /** Defaults to https://relay.kxco.ai */
+  relayUrl?: string
+  /** Defaults to 'signature'. */
+  verifyMode?: VerifyMode
+  licenceKey?: string | null
+  /** Defaults to 60000. Zero disables the cache. */
+  registryTtlMs?: number
+  /** Defaults to globalThis.fetch. Inject to test, or to use a scoped fetch. */
+  fetchImpl?: typeof fetch
+  /** Defaults to 10000. */
+  timeoutMs?: number
+}
+
+export interface NetworkConfig {
+  chainId: 1111111
+  registryUrl: string
+  relayUrl: string
+  verifyMode: VerifyMode
+  licenceKey: string | null
+  registryTtlMs: number
+  fetchImpl: typeof fetch
+  timeoutMs: number
+}
+
+/** Normalise and validate a configuration. Throws on a wrong chain id or mode. */
+export function networkConfig(config?: NetworkConfigInput): NetworkConfig
+
+/**
+ * Read a configuration from the environment:
+ * `KXCO_REGISTRY_URL`, `KXCO_RELAY_URL`, `KXCO_VERIFY_MODE`,
+ * `KXCO_LICENCE_KEY` (or `KXCO_LICENSE_KEY`), `KXCO_REGISTRY_TTL_MS`.
+ */
+export function networkConfigFromEnv(
+  env?: Record<string, string | undefined>,
+  overrides?: NetworkConfigInput,
+): NetworkConfig
+
+// ── registry ────────────────────────────────────────────────────────────────
+
+export type KidStatus = 'active' | 'revoked' | 'rotated' | 'expired' | 'unknown'
+
+export const KID_STATUS: ['active', 'revoked', 'rotated', 'expired']
+
+export interface KidRecord {
+  kid: string
+  status: KidStatus
+  publicKey?: string
+  rotatedTo?: string | null
+  institutionId?: string
+  chainId: 1111111
+  asOfBlock?: number
+  /** Whether this answer came from the TTL cache. */
+  cached: boolean
+}
+
+export class KeyRegistry {
+  constructor(config: NetworkConfig)
+  /**
+   * `GET /kids/:kid`. Cached for `registryTtlMs`; concurrent lookups of the
+   * same kid share one request.
+   *
+   * A 404 resolves to `status: 'unknown'` — the registry was reached and does
+   * not know the key. Being unable to reach it throws instead, so a caller can
+   * tell "definitely not trusted" from "could not ask".
+   */
+  lookup(kid: string): Promise<KidRecord>
+  clearCache(): void
+}
+
+// ── modes ───────────────────────────────────────────────────────────────────
+
+export const FAILURE: {
+  SIGNATURE_INVALID: 'signature_invalid'
+  MALFORMED: 'malformed'
+  NOT_ANCHORED: 'not_anchored'
+  WRONG_CHAIN: 'wrong_chain'
+  KID_REVOKED: 'kid_revoked'
+  KID_ROTATED: 'kid_rotated'
+  KID_EXPIRED: 'kid_expired'
+  KID_UNKNOWN: 'kid_unknown'
+  REGISTRY_UNREACHABLE: 'registry_unreachable'
+  LICENCE_REQUIRED: 'licence_required'
+}
+
+export interface EnvelopeAnchor {
+  txHash: string
+  blockNumber?: number
+  chainId?: number
+}
+
+/** Read the anchor from either the current `anchor` shape or the legacy `chainAnchor`. */
+export function readAnchor(envelope: unknown): EnvelopeAnchor | null
+
+export interface VerifyModeResult {
+  valid: boolean
+  mode: VerifyMode
+  /** One of FAILURE's values, when invalid. */
+  reason?: string
+  /** Human-readable detail, when invalid. */
+  detail?: string
+  anchor?: EnvelopeAnchor
+  registry?: KidRecord
+}
+
+/**
+ * Apply a verification mode on top of a signature check the caller performed.
+ *
+ * This does no cryptography: each package owns its own envelope shape and
+ * signing message, and a second definition of "valid signature" here would be
+ * one definition too many.
+ */
+export function applyVerifyMode(opts: {
+  envelope: unknown
+  signatureValid: boolean
+  kid: string
+  config: NetworkConfig
+  /** Pass one to share its cache across verifications. */
+  registry?: KeyRegistry
+}): Promise<VerifyModeResult>
+
+// ── errors and metering ─────────────────────────────────────────────────────
+
+export class KxcoPqNetworkError extends Error {
+  name: 'KxcoPqNetworkError'
+  code: string
+  status: number | null
+}
+
+export const EVENTS: string[]
+
+/** First 8 characters of a licence key. Never the whole key. */
+export function licencePrefix(licenceKey: string | null | undefined): string | null
+
+export function usageEvent(
+  event: string,
+  fields?: { institutionId?: string; kid?: string; licenceKey?: string; [k: string]: unknown },
+): Record<string, unknown>
+
+/** Build and emit a usage event. Default sink is one JSON line on stdout. */
+export function meter(
+  event: string,
+  fields?: Record<string, unknown>,
+  sink?: (record: Record<string, unknown>) => void,
+): Record<string, unknown>

package/src/index.js

@@ -0,0 +1,27 @@
+// kxco-pq-network — the verification modes, and the registry behind them.
+//
+// This is the boundary between what is free and what is sold. The maths lives
+// upstream in kxco-post-quantum and kxco-verify: Apache-2.0, chain-agnostic,
+// works offline, no server. What lives here is the answer to whether a key is
+// still allowed to sign, which is a fact about the present that no offline
+// check can supply.
+//
+// Depended on by kxco-pq-sdk, kxco-pq-attest, kxco-post-quantum-webhook and
+// kxco-pq-agent. It is its own package rather than a module inside the SDK
+// because the SDK already depends on kxco-pq-attest, and putting it there
+// would make that cycle.
+
+export {
+  networkConfig,
+  networkConfigFromEnv,
+  CHAIN_ID,
+  VERIFY_MODES,
+  DEFAULT_REGISTRY_URL,
+  DEFAULT_RELAY_URL,
+  DEFAULT_REGISTRY_TTL_MS,
+} from './config.js'
+
+export { KeyRegistry, KID_STATUS } from './registry.js'
+export { applyVerifyMode, readAnchor } from './verify-mode.js'
+export { KxcoPqNetworkError, FAILURE } from './errors.js'
+export { meter, usageEvent, licencePrefix, EVENTS } from './meter.js'

package/src/meter.js

@@ -0,0 +1,65 @@
+// Structured usage events.
+//
+// Seats are priced per institution, and anchors and registry reads are
+// metered, so the code that performs them has to say so in a shape a billing
+// pipeline can read. This is the metre hook and nothing more: it emits, it
+// does not aggregate, invoice, or phone home.
+//
+// The licence key is never emitted in full. A prefix is enough to attribute an
+// event to a customer and useless to anyone who intercepts a log line, and
+// logs get shipped to places the key was never meant to reach.
+
+/** Events this package and its callers emit. */
+export const EVENTS = [
+  'anchor_written',
+  'kid_registered',
+  'kid_revoked',
+  'kid_rotated',
+  'relay_post',
+  'registry_read',
+  'verify',
+]
+
+const LICENCE_PREFIX_LENGTH = 8
+
+/** First 8 characters of a licence key, for attribution. Never the whole key. */
+export function licencePrefix(licenceKey) {
+  if (typeof licenceKey !== 'string' || licenceKey.length === 0) return null
+  return licenceKey.slice(0, LICENCE_PREFIX_LENGTH)
+}
+
+/**
+ * Build a usage event. Returns the record rather than writing it, so the
+ * caller's own logger decides where it goes.
+ *
+ * @param {string} event — one of EVENTS
+ * @param {{ institutionId?: string, kid?: string, licenceKey?: string,
+ *           [k: string]: unknown }} fields
+ */
+export function usageEvent(event, fields = {}) {
+  const { licenceKey, ...rest } = fields
+  return {
+    event,
+    at: new Date().toISOString(),
+    chainId: 1111111,
+    ...rest,
+    licencePrefix: licencePrefix(licenceKey),
+  }
+}
+
+/**
+ * Emit a usage event through a sink.
+ *
+ * The default sink is a single JSON line on stdout, because that is what every
+ * log shipper already parses. Pass your own to send it somewhere else.
+ *
+ * @param {string} event
+ * @param {object} fields
+ * @param {(record: object) => void} [sink]
+ */
+export function meter(event, fields = {}, sink) {
+  const record = usageEvent(event, fields)
+  if (sink) sink(record)
+  else console.log(JSON.stringify(record))
+  return record
+}

package/src/registry.js

@@ -0,0 +1,232 @@
+// Key registry client: GET /kids/:kid against the Armature L1 explorer.
+//
+// This answers the one question offline cryptography cannot: is this key still
+// allowed to sign, today. A signature made by a key that was revoked an hour
+// ago is still a perfectly valid signature, and a verifier that only checks
+// the maths will accept it forever.
+//
+// Two design points are load-bearing.
+//
+// It fails CLOSED. If the registry cannot be reached, "anchored+live" returns
+// invalid, not valid-with-a-warning. A mode whose whole purpose is to catch a
+// revoked key must not degrade into the mode that cannot, precisely when the
+// network is behaving oddly. Callers who would rather have the weaker answer
+// than no answer can ask for "anchored" and get it deterministically.
+//
+// It caches by kid for registryTtlMs. Revocation is therefore visible within
+// the TTL and not instantly, which is a real limit and is stated as one: at
+// the 60 second default a revoked key stays accepted for up to a minute.
+// Turning the cache off (registryTtlMs: 0) trades that for a lookup per
+// verification.
+
+import { kidEquals } from 'kxco-post-quantum'
+import { KxcoPqNetworkError } from './errors.js'
+import { CHAIN_ID } from './config.js'
+
+// Whether a response claims to be JSON. Used to tell a registry answering from
+// a web server answering, which matters most on a 404: one is a fact about a
+// key, the other is a fact about the URL.
+function isJson(response) {
+  // A content-type is a media type plus parameters. Splitting it is exact,
+  // and it avoids a regex over a header a remote server chose.
+  const type = response.headers?.get?.('content-type') ?? ''
+  const mediaType = type.split(';')[0].trim().toLowerCase()
+  return mediaType === 'application/json' || mediaType.endsWith('+json')
+}
+
+/**
+ * Statuses the registry may report. Anything else is treated as unknown.
+ *
+ * `expired` is here because the on-chain credential carries an `expiresAt` and
+ * the registry reports it. Folding it into `unknown` would still fail closed,
+ * but it would tell an operator "we have never heard of this key" about a key
+ * that is registered, was never revoked, and simply ran out — which sends them
+ * looking for the wrong problem.
+ */
+export const KID_STATUS = ['active', 'revoked', 'rotated', 'expired']
+
+export class KeyRegistry {
+  #url
+  #ttlMs
+  #fetch
+  #timeoutMs
+  #licenceKey
+  #cache = new Map() // kid -> { record, expiresAt }
+  #inflight = new Map() // kid -> Promise, so a burst is one request
+
+  /**
+   * @param {object} config — from networkConfig()
+   */
+  constructor(config) {
+    this.#url = config.registryUrl
+    this.#ttlMs = config.registryTtlMs
+    this.#fetch = config.fetchImpl
+    this.#timeoutMs = config.timeoutMs
+    this.#licenceKey = config.licenceKey
+
+    if (typeof this.#fetch !== 'function') {
+      throw new KxcoPqNetworkError(
+        'no fetch implementation available — pass fetchImpl in the network config',
+        { code: 'BAD_CONFIG' },
+      )
+    }
+  }
+
+  /** Drop everything cached. For tests, and for a caller reacting to a rotation webhook. */
+  clearCache() {
+    this.#cache.clear()
+  }
+
+  /**
+   * Look a kid up, through the cache.
+   *
+   * @param {string} kid
+   * @returns {Promise<{ kid: string, status: string, publicKey?: string,
+   *                     rotatedTo?: string|null, institutionId?: string,
+   *                     chainId?: number, asOfBlock?: number, cached: boolean }>}
+   * @throws {KxcoPqNetworkError} if the registry cannot be reached or answers badly
+   */
+  async lookup(kid) {
+    if (typeof kid !== 'string' || !/^[0-9a-f]{16}$/.test(kid)) {
+      throw new KxcoPqNetworkError(`kid must be 16 lowercase hex characters, got '${kid}'`, {
+        code: 'BAD_KID',
+      })
+    }
+
+    const now = Date.now()
+    const hit = this.#cache.get(kid)
+    if (hit && hit.expiresAt > now) return { ...hit.record, cached: true }
+
+    // Collapse a burst for the same kid into one request. Without this, a
+    // batch of envelopes from one signer opens one connection per envelope at
+    // exactly the moment the cache is cold.
+    const existing = this.#inflight.get(kid)
+    if (existing) return { ...(await existing), cached: false }
+
+    const request = this.#fetchKid(kid)
+      .then((record) => {
+        if (this.#ttlMs > 0) {
+          this.#cache.set(kid, { record, expiresAt: Date.now() + this.#ttlMs })
+        }
+        return record
+      })
+      .finally(() => this.#inflight.delete(kid))
+
+    this.#inflight.set(kid, request)
+    return { ...(await request), cached: false }
+  }
+
+  async #fetchKid(kid) {
+    const url = `${this.#url}/kids/${kid}`
+    const ac = new AbortController()
+    const tid = setTimeout(() => ac.abort(), this.#timeoutMs)
+
+    let response
+    try {
+      response = await this.#fetch(url, {
+        method: 'GET',
+        headers: {
+          accept: 'application/json',
+          // The registry read is metered per licence where one is configured.
+          // Reads without a licence are allowed, rate-limited, and are how the
+          // free path stays free.
+          ...(this.#licenceKey ? { authorization: `Bearer ${this.#licenceKey}` } : {}),
+        },
+        signal: ac.signal,
+      })
+    } catch (err) {
+      throw new KxcoPqNetworkError(
+        err.name === 'AbortError'
+          ? `registry lookup timed out after ${this.#timeoutMs}ms`
+          : `registry unreachable: ${err.message}`,
+        { code: 'REGISTRY_UNREACHABLE', cause: err },
+      )
+    } finally {
+      clearTimeout(tid)
+    }
+
+    // A 404 from the REGISTRY is an answer, not a failure: it was reached and
+    // it has never heard of this kid. That is a definite "do not trust", and
+    // it must not be confused with "we could not ask".
+    //
+    // A 404 from something that is not the registry is the opposite. Pointing
+    // registryUrl at a web app gets back that app's 404 page, and reading a
+    // page of HTML as "this key is unknown" would state a fact about a key on
+    // the strength of a misconfigured URL. Measured, not hypothetical:
+    // https://chain.kxco.ai/kids/<kid> currently serves 26KB of the marketing
+    // site's 404 page.
+    //
+    // So the content type decides which of the two this is. JSON is the
+    // registry answering; anything else is a wrong address, and a wrong
+    // address is a reason we could not ask.
+    if (response.status === 404) {
+      if (!isJson(response)) {
+        throw new KxcoPqNetworkError(
+          `registry returned a non-JSON 404 from ${url} — this is a web page, not a registry ` +
+          'answer. Check registryUrl: reading it as "kid unknown" would state a fact about a ' +
+          'key on the strength of a misconfigured URL.',
+          { code: 'REGISTRY_UNREACHABLE', status: 404 },
+        )
+      }
+      return { kid, status: 'unknown', chainId: CHAIN_ID }
+    }
+
+    if (!response.ok) {
+      throw new KxcoPqNetworkError(`registry returned ${response.status}`, {
+        code: 'REGISTRY_UNREACHABLE',
+        status: response.status,
+      })
+    }
+
+    let body
+    try {
+      body = await response.json()
+    } catch (err) {
+      throw new KxcoPqNetworkError(
+        `registry returned a non-JSON body from ${url}` +
+        (isJson(response) ? '' : ' (content-type is not JSON — check registryUrl)'),
+        { code: 'REGISTRY_UNREACHABLE', status: response.status, cause: err },
+      )
+    }
+
+    return this.#validate(kid, body)
+  }
+
+  #validate(kid, body) {
+    if (!body || typeof body !== 'object') {
+      throw new KxcoPqNetworkError('registry record is not an object', { code: 'REGISTRY_BAD_RECORD' })
+    }
+
+    // The kid is compared in constant time, and it is compared at all because
+    // a registry that answers about a different key than the one asked for is
+    // either broken or being interposed. Either way the answer is unusable.
+    if (typeof body.kid !== 'string' || !kidEquals(body.kid, kid)) {
+      throw new KxcoPqNetworkError(
+        `registry answered for kid '${body.kid}' but was asked about '${kid}'`,
+        { code: 'REGISTRY_BAD_RECORD' },
+      )
+    }
+
+    if (body.chainId !== undefined && body.chainId !== CHAIN_ID) {
+      throw new KxcoPqNetworkError(
+        `registry record names chain ${body.chainId}, expected ${CHAIN_ID}`,
+        { code: 'WRONG_CHAIN' },
+      )
+    }
+
+    // An unrecognised status becomes 'unknown' rather than being passed
+    // through. A future status this build does not understand must not fall
+    // out of the "is it active" check as though it were active.
+    const status = KID_STATUS.includes(body.status) ? body.status : 'unknown'
+
+    return {
+      kid,
+      status,
+      publicKey: body.publicKey,
+      rotatedTo: body.rotatedTo ?? null,
+      institutionId: body.institutionId,
+      chainId: CHAIN_ID,
+      asOfBlock: body.asOfBlock,
+    }
+  }
+}