@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/internal/RateLimit.ts

@@ -0,0 +1,259 @@
+/**
+ * Rate limits through the Workers Rate Limiting bindings that `Limits` names. Each Cloudflare
+ * location counts on its own, and counts converge eventually, so a limit bounds abuse rather than
+ * counting exactly. Better Auth bounds the guesses at each sign-in code exactly.
+ * @module
+ */
+import type { Context } from 'hono'
+import { Bytes, Hash } from 'ox'
+import type { Env } from './Env.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Limits from './Limits.js'
+import * as Log from './Log.js'
+import * as Timing from './Timing.js'
+
+/** A request exceeded one of Tempo ID's rate limits. */
+export class LimitedError extends ErrorResponse.define('rate_limited') {
+  override readonly name = 'RateLimit.LimitedError'
+
+  constructor(options: LimitedError.Options) {
+    super({
+      error_description: `Too many requests. Retry after ${options.retryAfter} seconds.`,
+    })
+  }
+}
+
+export declare namespace LimitedError {
+  type Options = {
+    /** Seconds until a retry can succeed. */
+    retryAfter: number
+  }
+}
+
+/**
+ * The address Cloudflare gives every Worker subrequest from another zone, whatever Worker sends it.
+ * Cloudflare names the calling zone in `cf-worker` instead.
+ */
+const workers = '2a06:98c0:3600::103'
+
+/** A Workers Rate Limiting binding, as the app calls it. */
+export type Limiter = {
+  /** Counts a request for `key`, and reports whether the key has requests left. */
+  limit(options: {
+    /** The counter's key. */
+    key: string
+  }): Promise<{
+    /** Whether the request is within the limit. */
+    success: boolean
+  }>
+}
+
+// Void types a page's `c.env` from this global interface. `void.config.ts` declares the limiters.
+declare global {
+  interface VoidGeneratedEnvBindings extends Record<Limits.Limit, Limiter> {}
+}
+
+/**
+ * A limit as the RateLimit header fields of draft-ietf-httpapi-ratelimit-headers describe it, in
+ * `RateLimit-Policy` and `RateLimit`.
+ */
+export type Policy = {
+  /** The policy's name, such as `sign-in-ip`. */
+  name: string
+  /** The requests a key may make within `window`. */
+  quota: number
+  /** The window, in seconds. */
+  window: number
+}
+
+/** The response headers a rate-limited route may send, which cross-origin callers need exposed. */
+export const headers = ['RateLimit', 'RateLimit-Policy', 'Retry-After'] as const
+
+/**
+ * Counts the request against each limit in order, and returns a 429 response with `Retry-After` at
+ * the first one spent, or `undefined`. A limit without a key is skipped, and so is an
+ * {@link Limits.optional} limit without a binding, with a warning. The limits after a refusal are not
+ * counted, so a refused caller spends no narrower quota, such as an address's. The response
+ * is the same for every limit, so it reveals nothing about the key, such as whether an account
+ * exists. Every limit with a key adds its {@link policy} to `RateLimit-Policy`.
+ */
+export async function check(c: Context<Env>, options: check.Options) {
+  // A deployment whose Wrangler config predates an optional limit has no binding for it. Any other
+  // missing binding throws below, so a misconfigured deployment fails closed.
+  const bindings: Partial<Record<Limits.Limit, Limiter>> = c.env
+  const limits = options.limits.flatMap((limit) => {
+    if (limit.key === undefined) return []
+    if (!bindings[limit.binding] && Limits.optional.includes(limit.binding)) {
+      Log.warn(c, {
+        fields: { binding: limit.binding },
+        message: 'A rate limit has no binding, so the request is not counted.',
+      })
+      return []
+    }
+    return [
+      {
+        ...limit,
+        key: limit.key,
+        policy: policy({ binding: limit.binding }),
+      },
+    ]
+  })
+  for (const limit of limits) describe(c, { policy: limit.policy })
+
+  for (const limit of limits) {
+    const outcome = await Timing.measure(
+      c,
+      c.env[limit.binding].limit({ key: limit.key }),
+      'ratelimit.limit',
+    )
+    // The binding reports no reset, and every counter restarts once a window passes.
+    if (!outcome.success)
+      return refuse(c, {
+        policy: limit.policy,
+        retryAfter: limit.policy.window,
+      })
+  }
+  return undefined
+}
+
+export declare namespace check {
+  type Options = {
+    /** The counters the request counts against, broadest first. */
+    limits: readonly {
+      /** The limiter's binding name, which sets the limit. */
+      binding: Limits.Limit
+      /** The counter's key, or `undefined` to skip it. Keys never hold secrets, codes, or tokens. */
+      key: string | undefined
+    }[]
+  }
+}
+
+export namespace check {
+  /** The refusal `check` returns. */
+  export const errors = [LimitedError] as const
+}
+
+/**
+ * Adds `policy` to the response's `RateLimit-Policy`, as `"<name>";q=<quota>;w=<window>`. A
+ * response that counts against several policies lists each once. It reads no binding, so a page
+ * loader's context can call it too.
+ */
+export function describe(c: Context, options: describe.Options) {
+  const { policy } = options
+  c.header(
+    'ratelimit-policy',
+    `"${policy.name}";q=${policy.quota};w=${policy.window}`,
+    { append: true },
+  )
+}
+
+export declare namespace describe {
+  type Options = {
+    /** The policy the request counts against. */
+    policy: Policy
+  }
+}
+
+/**
+ * Returns the key for a normalized email address: its SHA-256 hash, so the counters hold no
+ * address.
+ */
+export function email(options: email.Options) {
+  return Hash.sha256(Bytes.fromString(options.email), { as: 'Hex' })
+}
+
+export declare namespace email {
+  type Options = {
+    /** The trimmed, lowercased address. */
+    email: string
+  }
+}
+
+/** Instantiates a {@link Policy}. */
+export function from(policy: Policy): Policy {
+  return policy
+}
+
+/**
+ * Returns the client's key from `cf-connecting-ip`, or `undefined` for a request without one, such
+ * as an in-process call. An IPv6 address keys on its /64 prefix, since one subscriber usually holds
+ * the whole prefix and could otherwise rotate addresses within it. A Worker in another zone keys on
+ * that zone, since every such Worker arrives from the same address.
+ */
+export function ip(c: ip.Context) {
+  const address = c.req.header('cf-connecting-ip')
+  // Only Cloudflare sends from this address, so `cf-worker` names the calling zone and is not the
+  // caller's to choose.
+  if (address === workers) return `worker:${c.req.header('cf-worker') ?? ''}`
+
+  // An IPv4 address, or an IPv6 address that embeds one, keys whole.
+  if (!address?.includes(':') || address.includes('.')) return address
+
+  const [head, tail] = address.toLowerCase().split('::')
+  const left = head ? head.split(':') : []
+  const right = tail ? tail.split(':') : []
+  const groups =
+    tail === undefined
+      ? left
+      : [
+          ...left,
+          ...Array(Math.max(0, 8 - left.length - right.length)).fill('0'),
+          ...right,
+        ]
+  return `${groups
+    .slice(0, 4)
+    .map((group) => group.replace(/^0+(?=.)/, ''))
+    .join(':')}::/64`
+}
+
+export declare namespace ip {
+  /** The request context, of which `ip` reads only the headers. */
+  type Context = { req: { header: (name: string) => string | undefined } }
+}
+
+/**
+ * Returns a binding's {@link Policy}: its limit and period from `Limits`. The policy's name is the
+ * binding's name without its `_LIMIT` suffix, in kebab case, such as `sign-in-ip` for
+ * `SIGN_IN_IP_LIMIT`.
+ */
+export function policy(options: policy.Options) {
+  const { binding } = options
+  const config = Limits.limits[binding]
+  return from({
+    name: binding
+      .replace(/_LIMIT$/, '')
+      .toLowerCase()
+      .replaceAll('_', '-'),
+    quota: config.limit,
+    window: config.period,
+  })
+}
+
+export declare namespace policy {
+  type Options = {
+    /** The limiter's binding name. */
+    binding: Limits.Limit
+  }
+}
+
+/**
+ * Returns a 429 response with `Retry-After`, and `RateLimit` naming the spent `policy` with no
+ * quota left (`r=0`) for `retryAfter` seconds (`t`). The body names no key or limit, so it reveals
+ * nothing about the key, such as whether an account exists. It reads no binding, so a page
+ * loader's context can call it too.
+ */
+export function refuse(c: Context, options: refuse.Options) {
+  const { policy, retryAfter } = options
+  c.header('ratelimit', `"${policy.name}";r=0;t=${retryAfter}`)
+  c.header('retry-after', String(retryAfter))
+  return ErrorResponse.json(c, new LimitedError({ retryAfter }))
+}
+
+export declare namespace refuse {
+  type Options = {
+    /** The spent policy. */
+    policy: Policy
+    /** Seconds until a retry can succeed, at most the policy's window. */
+    retryAfter: number
+  }
+}