tapimo 0.7.1 → 0.8.0

package/src/internal/EdgeCache.test.ts

@@ -37,18 +37,18 @@ describe('middleware', () => {
     expect(second.headers.get('vary')).toMatchInlineSnapshot(`"Accept-Encoding"`)
   })
 
-  test('serves authenticated requests from the same shared cache entry', async () => {
+  test('bypasses the cache for credential headers', async () => {
     const { app, store, downstreamCalls } = createApp()
 
-    // An authenticated request warms the cache; subsequent requests — whether
-    // authenticated (with any key) or anonymous — are all served from the one
-    // shared entry without re-running downstream auth/rate-limiting.
     await app.request('/cached', { headers: { authorization: 'Bearer one' } })
+    await app.request('/cached', { headers: { authorization: 'Basic malformed' } })
+    await app.request('/cached', { headers: { authorization: 'Payment paid' } })
     await app.request('/cached', { headers: { 'tempo-api-key': 'two' } })
-    await app.request('/cached')
+    await app.request('/cached', { headers: { 'x-api-key': 'three' } })
 
-    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
-    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(downstreamCalls()).toMatchInlineSnapshot(`5`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
   test('bypasses the cache for query API key credentials', async () => {
@@ -179,6 +179,23 @@ describe('middleware', () => {
     expect(store.gets).toMatchInlineSnapshot(`1`)
   })
 
+  test('bypasses the cache when its route key cannot be generated', async () => {
+    const { app, store, downstreamCalls } = createApp({
+      key: () => {
+        throw new Error('invalid query')
+      },
+    })
+
+    const first = await app.request('/cached')
+    const second = await app.request('/cached')
+
+    expect(first.status).toMatchInlineSnapshot(`200`)
+    expect(second.status).toMatchInlineSnapshot(`200`)
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
   test('answers conditional requests from a cached ETag with 304', async () => {
     const { app } = createApp()
 
@@ -277,6 +294,7 @@ function memoryStore() {
 function createApp(
   options: {
     eligibility?: readonly ((c: Context<Environment>) => boolean)[] | undefined
+    key?: ((c: Context<Environment>) => Promise<string> | string) | undefined
     store?: Store.Store | undefined
   } = {},
 ) {
@@ -294,6 +312,7 @@ function createApp(
   // routes do; unmarked routes must skip the lookup entirely.
   const cacheable_marked = EdgeCache.markCacheable(
     createMiddleware<Environment>(async (_c, next) => next()),
+    { key: options.key as (c: Context) => Promise<string> | string },
   )
   for (const predicate of options.eligibility ?? [])
     EdgeCache.setEligibility(cacheable_marked, predicate)

package/src/internal/EdgeCache.ts

@@ -48,8 +48,8 @@ const volatileHeaders = [
 /**
  * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
  * run, so cache hits skip the per-request store round-trips that dominate
- * latency — for every caller, authenticated or not. Place this ahead of the
- * auth middleware.
+ * latency. Credential-bearing requests bypass this layer so per-key policy
+ * enforcement always runs. Place this ahead of the auth middleware.
  *
  * Only 2xx responses from routes that opted into caching (via `Cache.response`,
  * which publishes the `edgeCache` policy) are stored, and the policy is only
@@ -84,10 +84,16 @@ export function middleware<environment extends Env>(
       store !== undefined &&
       c.req.method === 'GET' &&
       !c.req.raw.headers.has('range') &&
-      // Query credentials must reach auth and never enter cache keys.
-      !new URL(c.req.url).searchParams.has('key') &&
+      // Credential-bearing requests must reach auth for per-key policy enforcement.
+      !hasCredential(c.req.raw) &&
       isCacheableRoute(c)
-    const key = eligible ? cacheKey(c.req.url) : undefined
+    const key = eligible
+      ? await routeCacheKey(c).catch(() => {
+          // Key generators may parse request input before route validation runs.
+          // Bypass caching so the validation middleware can return its response.
+          return undefined
+        })
+      : undefined
 
     // Honor the standard request `Cache-Control` directives so a caller can
     // refresh a stale entry on the colo serving them without any out-of-band
@@ -138,10 +144,20 @@ export function middleware<environment extends Env>(
   }
 }
 
+function hasCredential(request: Request): boolean {
+  return (
+    request.headers.has('tempo-api-key') ||
+    request.headers.has('x-api-key') ||
+    request.headers.has('authorization') ||
+    new URL(request.url).searchParams.has('key')
+  )
+}
+
 // Marks handlers whose route publishes an edge-cache policy; the middleware
 // pays the store lookup only when a matched handler carries it.
 const cacheableSymbol = Symbol('tempoApi.edgeCacheable')
 const eligibility = new WeakMap<object, (c: Context) => boolean>()
+const keys = new WeakMap<object, (c: Context) => Promise<string> | string>()
 
 /**
  * Marks a route handler/middleware as publishing an edge-cache policy, so
@@ -150,10 +166,20 @@ const eligibility = new WeakMap<object, (c: Context) => boolean>()
  */
 export function markCacheable<const handler extends (...args: never[]) => unknown>(
   handler: handler,
+  options: markCacheable.Options = {},
 ): handler {
+  if (options.key) keys.set(handler, options.key)
   return Object.assign(handler, { [cacheableSymbol]: true })
 }
 
+export declare namespace markCacheable {
+  /** Options for marking a route as edge-cacheable. */
+  type Options = {
+    /** Cache key generator. Defaults to the request URL. */
+    key?: ((c: Context) => Promise<string> | string) | undefined
+  }
+}
+
 /** Adds a request eligibility check; every check must permit caching. */
 export function setEligibility<const handler extends (...args: never[]) => unknown>(
   handler: handler,
@@ -176,6 +202,16 @@ function isCacheableRoute(c: Context): boolean {
   return cacheable
 }
 
+async function routeCacheKey(c: Context) {
+  let requestUrl = c.req.url
+  for (const route of matchedRoutes(c)) {
+    if (!(cacheableSymbol in route.handler)) continue
+    const key = keys.get(route.handler)
+    if (key) requestUrl = await key(c)
+  }
+  return cacheKey(requestUrl)
+}
+
 export declare namespace middleware {
   /** Options for the edge-cache middleware. */
   type Options = {
@@ -222,7 +258,7 @@ function serveHit(ifNoneMatch: string | undefined, value: string): Response {
   const { body, encoding, headers, status } = JSON.parse(value) as Stored
   const responseHeaders = new Headers(headers)
   const etag = responseHeaders.get('etag')
-  if (etag && ifNoneMatch && etagMatches(etag, ifNoneMatch)) {
+  if (Etag.matches(etag, ifNoneMatch)) {
     const notModified = new Headers()
     for (const name of ['Cache-Control', 'ETag', 'Vary']) {
       const header = responseHeaders.get(name)
@@ -271,9 +307,12 @@ function getWaitUntil(c: { executionCtx?: { waitUntil(promise: Promise<unknown>)
   }
 }
 
-function etagMatches(etag: string, ifNoneMatch: string) {
-  const strip = (tag: string) => tag.trim().replace(/^W\//, '')
-  return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag))
+namespace Etag {
+  export function matches(etag: string | null, ifNoneMatch: string | undefined) {
+    if (!etag || !ifNoneMatch) return false
+    const strip = (tag: string) => tag.trim().replace(/^W\//, '')
+    return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag))
+  }
 }
 
 /**

package/src/internal/Id.ts

@@ -22,3 +22,17 @@ export function generate(prefix: string): string {
 export function random(): string {
   return segment()
 }
+
+/**
+ * Generates a time-prefixed resource id (`{prefix}_{epoch ms}_{24 base62
+ * chars}`). The epoch-ms is zero-padded to 15 digits (headroom past the year
+ * 5138) so lexical id order is chronological, letting newest-first lists page
+ * by keyset on the id alone.
+ *
+ * @param prefix - The resource-type prefix (e.g. `wh`, `ftr`).
+ * @param now - The timestamp to embed.
+ * @returns The generated id.
+ */
+export function generateSortable(prefix: string, now: Date = new Date()): string {
+  return `${prefix}_${now.getTime().toString().padStart(15, '0')}_${random()}`
+}

package/src/internal/Idempotency.test.ts

@@ -0,0 +1,109 @@
+import { Hash, Hex } from 'ox'
+
+import * as Idempotency from './Idempotency.js'
+import * as Store from './Store.js'
+import * as Ttl from './Ttl.js'
+
+const identity = {
+  apiKeyId: 'key_test',
+  idempotencyKey: 'req_01j3j1k2l3m4n5p6q7r8s9t0u',
+  inputHash: `0x${'11'.repeat(32)}`,
+}
+
+function coordinator(namespace = 'test:v1') {
+  return Idempotency.create<{ id: string }>({
+    namespace,
+    pendingTtl: Ttl.minutes(1),
+    receiptTtl: Ttl.days(1),
+  })
+}
+
+describe('inputHash', () => {
+  test('binds semantic content instead of JSON property order', () => {
+    expect(Idempotency.inputHash({ a: 1, b: [{ d: 2, c: 3 }] })).toBe(
+      Idempotency.inputHash({ b: [{ c: 3, d: 2 }], a: 1 }),
+    )
+    expect(Idempotency.inputHash({ a: 1 })).not.toBe(Idempotency.inputHash({ a: 2 }))
+  })
+
+  test('rejects values JSON cannot represent', () => {
+    expect(() => Idempotency.inputHash({ callback: () => {} })).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Idempotency inputs must be JSON values.]`,
+    )
+    expect(() =>
+      Idempotency.inputHash({ values: [Number.NaN, Number.POSITIVE_INFINITY] }),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Idempotency inputs must be JSON values.]`)
+  })
+})
+
+describe('create', () => {
+  test('claims, blocks parallel requests, and replays the completed response', async () => {
+    const state = Store.memory()
+    const requests = coordinator()
+
+    const claimed = await requests.claim({ identity, state })
+    expect(claimed.type).toBe('claimed')
+    if (claimed.type !== 'claimed') return
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+    await expect(
+      requests.claim({ identity: { ...identity, inputHash: `0x${'22'.repeat(32)}` }, state }),
+    ).resolves.toEqual({ type: 'mismatch' })
+
+    await requests.complete({ identity, response: { id: 'ftr_test' }, state, token: claimed.token })
+    await expect(requests.claim({ identity, state })).resolves.toEqual({
+      response: { id: 'ftr_test' },
+      type: 'replay',
+    })
+  })
+
+  test('fences completion and release by claim token', async () => {
+    const state = Store.memory()
+    const requests = coordinator()
+    const claimed = await requests.claim({ identity, state })
+    if (claimed.type !== 'claimed') throw new Error('Expected a claimed request.')
+
+    // A stale token can neither complete nor release the live claim.
+    await requests.complete({ identity, response: { id: 'stale' }, state, token: 'stale-token' })
+    await requests.release({ identity, state, token: 'stale-token' })
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+
+    await requests.release({ identity, state, token: claimed.token })
+    await expect(requests.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+  })
+
+  test('rejects responses JSON cannot represent before completing', async () => {
+    const state = Store.memory()
+    const requests = Idempotency.create<void>({
+      namespace: 'test:v1',
+      pendingTtl: Ttl.minutes(1),
+      receiptTtl: Ttl.days(1),
+    })
+    const claimed = await requests.claim({ identity, state })
+    if (claimed.type !== 'claimed') throw new Error('Expected a claimed request.')
+
+    await expect(
+      requests.complete({ identity, response: undefined, state, token: claimed.token }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Idempotency responses must be JSON values.]`,
+    )
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+  })
+
+  test('isolates coordinators by namespace over one store', async () => {
+    const state = Store.memory()
+    const first = coordinator('first:v1')
+    const second = coordinator('second:v1')
+
+    await expect(first.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+    await expect(second.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+  })
+
+  test('preserves the durable key format consumers already stored', async () => {
+    const state = Store.memory()
+    await coordinator('mpp:relay:v1').claim({ identity, state })
+    const digest = Hash.sha256(Hex.fromString(identity.idempotencyKey)).slice(2)
+    expect((await state.list()).keys.map((key) => key.name)).toEqual([
+      `mpp:relay:v1:${identity.apiKeyId}:${digest}`,
+    ])
+  })
+})

package/src/internal/Idempotency.ts

@@ -0,0 +1,237 @@
+import { Hash, Hex } from 'ox'
+
+import * as Store from './Store.js'
+
+/**
+ * API-level retry coordination for idempotent write endpoints, letting a
+ * caller recover a successful response after a transport timeout.
+ *
+ * A key moves from missing to pending to complete. Only the claim token may
+ * finish or release pending state, preventing an older request from
+ * overwriting a newer owner.
+ */
+
+/** Identity for one caller-supplied idempotent request. */
+export type Identity = {
+  /** API key that submitted the request. */
+  apiKeyId: string
+  /** Opaque caller-supplied idempotency key. */
+  idempotencyKey: string
+  /** Hash of the request content bound to this idempotency key. */
+  inputHash: string
+}
+
+/** Returns a stable digest without retaining request contents in durable state. */
+export function inputHash(input: unknown): string {
+  return Hash.sha256(Hex.fromString(canonicalJson(input)))
+}
+
+/** Creates an idempotency coordinator over one durable-store key namespace. */
+export function create<response>(options: create.Options) {
+  const { namespace, pendingTtl, receiptTtl } = options
+
+  function keyFor(identity: Identity) {
+    // Scope keys to the authenticated API key so different tenants can reuse
+    // the same client-generated value. Hashing keeps that opaque value out of
+    // durable-store key names and enumeration output.
+    const digest = Hash.sha256(Hex.fromString(identity.idempotencyKey)).slice(2)
+    return `${namespace}:${identity.apiKeyId}:${digest}`
+  }
+
+  /** Claims a request or returns its current outcome. */
+  async function claim(options: claim.Options): Promise<claim.Result<response>> {
+    const { identity, state } = options
+    const token = crypto.randomUUID()
+
+    return Store.change<claim.Result<response>>(
+      state,
+      keyFor(identity),
+      (current) => {
+        const currentRecord = record<response>(current)
+        // A completed request is the only cacheable terminal outcome. Failed
+        // attempts must be retried with the same input. Legacy records lack
+        // an input hash, so cannot be safely replayed.
+        if (currentRecord && currentRecord.inputHash !== identity.inputHash)
+          return { op: 'noop', result: { type: 'mismatch' } }
+        if (currentRecord?.type === 'complete')
+          return { op: 'noop', result: { response: currentRecord.response, type: 'replay' } }
+        // A parallel request must not settle the same caller operation while
+        // the first request still owns its pending claim.
+        if (currentRecord?.type === 'pending') return { op: 'noop', result: { type: 'pending' } }
+        return {
+          op: 'set',
+          result: { token, type: 'claimed' },
+          value: encode({ inputHash: identity.inputHash, token, type: 'pending' }),
+        }
+      },
+      { ttl: pendingTtl },
+    )
+  }
+
+  /** Persists a successful response for an owned request claim. */
+  async function complete(options: complete.Options<response>): Promise<void> {
+    const { identity, response, state, token } = options
+
+    await Store.change(
+      state,
+      keyFor(identity),
+      (current) => {
+        const currentRecord = record<response>(current)
+        // Claim tokens fence delayed requests: a request cannot complete a
+        // claim it no longer owns after expiry or a later retry.
+        if (
+          currentRecord?.type !== 'pending' ||
+          currentRecord.inputHash !== identity.inputHash ||
+          currentRecord.token !== token
+        )
+          return { op: 'noop', result: undefined }
+        canonicalJson(response, 'Idempotency responses must be JSON values.')
+        return {
+          op: 'set',
+          result: undefined,
+          value: encode({ inputHash: identity.inputHash, response, type: 'complete' }),
+        }
+      },
+      { ttl: receiptTtl },
+    )
+  }
+
+  /** Releases an owned retryable request claim. */
+  async function release(options: release.Options): Promise<void> {
+    const { identity, state, token } = options
+
+    await Store.change(state, keyFor(identity), (current) => {
+      const currentRecord = record<response>(current)
+      // Never delete a newer pending claim after this request has lost
+      // ownership through expiry and another caller has retried.
+      if (
+        currentRecord?.type !== 'pending' ||
+        currentRecord.inputHash !== identity.inputHash ||
+        currentRecord.token !== token
+      )
+        return { op: 'noop', result: undefined }
+      return { op: 'delete', result: undefined }
+    })
+  }
+
+  return { claim, complete, release }
+}
+
+export declare namespace create {
+  /** Coordinator configuration bound at creation. */
+  type Options = {
+    /** Durable-store key namespace (e.g. `mpp:relay:v1`). */
+    namespace: string
+    /** How long a pending claim blocks equivalent requests, in milliseconds. */
+    pendingTtl: number
+    /** How long a completed response replays, in milliseconds. */
+    receiptTtl: number
+  }
+}
+
+export declare namespace claim {
+  /** Dependencies for claiming one idempotency key. */
+  type Options = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+  }
+
+  /** Outcome from attempting to claim an idempotency key. */
+  type Result<response> =
+    | { token: string; type: 'claimed' }
+    | { type: 'mismatch' }
+    | { response: response; type: 'replay' }
+    | { type: 'pending' }
+}
+
+export declare namespace complete {
+  /** Dependencies for persisting one terminal response. */
+  type Options<response> = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Terminal successful response to replay. */
+    response: response
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+    /** Token returned by the successful claim. */
+    token: string
+  }
+}
+
+export declare namespace release {
+  /** Dependencies for releasing one idempotency claim. */
+  type Options = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+    /** Token returned by the successful claim. */
+    token: string
+  }
+}
+
+/** A completed request whose response may be replayed until expiry. */
+type CompleteRecord<response> = {
+  inputHash?: string
+  response: response
+  type: 'complete'
+}
+
+/** An in-flight request owned by the opaque claim token. */
+type PendingRecord = {
+  inputHash?: string
+  token: string
+  type: 'pending'
+}
+
+type ParsedRecord = {
+  inputHash?: unknown
+  response?: unknown
+  token?: unknown
+  type?: unknown
+}
+
+type JsonRecord = { [key: string]: unknown }
+
+function encode(record: CompleteRecord<unknown> | PendingRecord) {
+  return JSON.stringify(record)
+}
+
+function canonicalJson(
+  value: unknown,
+  errorMessage = 'Idempotency inputs must be JSON values.',
+): string {
+  if (value === null) return 'null'
+  if (typeof value === 'number' && !Number.isFinite(value)) throw new Error(errorMessage)
+  if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string')
+    return JSON.stringify(value)
+  if (Array.isArray(value))
+    return `[${value.map((item) => canonicalJson(item, errorMessage)).join(',')}]`
+  if (typeof value === 'object') {
+    const record = value as JsonRecord
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], errorMessage)}`)
+      .join(',')}}`
+  }
+  throw new Error(errorMessage)
+}
+
+function record<response>(
+  value: null | string,
+): CompleteRecord<response> | PendingRecord | undefined {
+  if (value === null) return undefined
+
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!parsed || typeof parsed !== 'object') return undefined
+    const candidate = parsed as ParsedRecord
+    if (candidate.type === 'pending' && typeof candidate.token === 'string')
+      return candidate as PendingRecord
+    if (candidate.type === 'complete' && candidate.response !== undefined)
+      return candidate as CompleteRecord<response>
+  } catch {}
+  return undefined
+}

package/src/internal/IpAllowlist.test.ts

@@ -0,0 +1,52 @@
+import { Hono } from 'hono'
+
+import * as IpAllowlist from './IpAllowlist.js'
+
+describe('isRule', () => {
+  test.each([
+    ['203.0.113.7', true],
+    ['0.0.0.0/0', true],
+    ['203.0.113.0/24', true],
+    ['203.0.113.7/32', true],
+    ['2001:db8::7', true],
+    ['::/0', true],
+    ['2001:db8::/32', true],
+    ['2001:db8::7/128', true],
+    ['::ffff:192.0.2.1', true],
+    ['203.0.113.0/33', false],
+    ['2001:db8::/129', false],
+    ['203.0.113.0/-1', false],
+    ['203.0.113.999', false],
+    ['2001:db8::1%eth0', false],
+    ['203.0.113.0/24/1', false],
+    [' 203.0.113.7', false],
+    ['203.0.113.7 ', false],
+    ['*', false],
+    ['', false],
+  ])('%s -> %s', (rule, expected) => {
+    expect(IpAllowlist.isRule(rule)).toBe(expected)
+  })
+})
+
+describe('allows', () => {
+  test.each([
+    ['203.0.113.7', ['203.0.113.7'], true],
+    ['203.0.113.7', ['0.0.0.0/0'], true],
+    ['203.0.113.7', ['203.0.113.0/24'], true],
+    ['203.0.113.0', ['203.0.113.0/24'], true],
+    ['203.0.113.255', ['203.0.113.0/24'], true],
+    ['203.0.114.7', ['203.0.113.0/24'], false],
+    ['2001:db8:1::7', ['2001:db8::/32'], true],
+    ['2001:db8::7', ['2001:db8::7/128'], true],
+    ['2001:db8::8', ['2001:db8::7/128'], false],
+    ['2001:db9::7', ['2001:db8::/32'], false],
+    ['203.0.113.7', ['2001:db8::/32'], false],
+    ['::ffff:192.0.2.1', ['::ffff:192.0.2.1'], true],
+    ['not-an-ip', ['203.0.113.0/24'], false],
+  ])('%s in %j -> %s', async (address, rules, expected) => {
+    const app = new Hono().get('/', async (c) =>
+      c.json({ allowed: await IpAllowlist.allows(c, { address, rules }) }),
+    )
+    expect(await (await app.request('/')).json()).toEqual({ allowed: expected })
+  })
+})

package/src/internal/IpAllowlist.ts

@@ -0,0 +1,39 @@
+import type { Context } from 'hono'
+import { ipRestriction } from 'hono/ip-restriction'
+
+/** Returns whether a value is an IPv4/IPv6 address or CIDR range. */
+export function isRule(value: string): boolean {
+  if (value === '*' || value.trim() !== value || value.split('/').length > 2) return false
+  try {
+    ipRestriction(() => '', { allowList: [value] })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Returns whether the client address matches at least one allowlist rule. */
+export async function allows(c: Context, options: allows.Options): Promise<boolean> {
+  const { address, rules } = options
+  if (!address) return false
+  try {
+    const denied = await ipRestriction(
+      () => address,
+      { allowList: [...rules] },
+      () => new Response(null, { status: 403 }),
+    )(c, async () => {})
+    return denied === undefined
+  } catch {
+    return false
+  }
+}
+
+export declare namespace allows {
+  /** Inputs used to check a client address. */
+  type Options = {
+    /** Trusted client IP address. */
+    address?: string | undefined
+    /** Exact IP and CIDR rules to match. */
+    rules: readonly string[]
+  }
+}