@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/RateLimit.ts

@@ -0,0 +1,346 @@
+/**
+ * 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, and
+ * {@link countCode} bounds an address's codes across every location in the database.
+ * @module
+ */
+import { and, eq, gt, sql } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { Bytes, Hash } from 'ox'
+import * as Schema from '../app/db/schema.js'
+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 type * as Realm from './Realm.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. Try again in ${ErrorResponse.wait({ seconds: options.retryAfter })}.`,
+      meta: { retryAfter: options.retryAfter },
+    })
+  }
+}
+
+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 sign-in codes that one address receives in an hour, across every Cloudflare location. Each
+ * code takes three guesses, so an address takes at most 30 guesses an hour.
+ */
+export const codePolicy = from({
+  name: 'sign-in-codes',
+  quota: 10,
+  window: 60 * 60,
+})
+
+/** 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 admitted = await count(c, { binding: limit.binding, key: limit.key })
+    // The binding reports no reset, and every counter restarts once a window passes.
+    if (!admitted)
+      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
+}
+
+/**
+ * Counts the request against the counter of `binding` for `key` once, and returns whether the key
+ * has requests left. Later calls in the request for the same counter share the first outcome, so a
+ * request that reads a user's accounts in several steps, such as a sign-in's account step and its
+ * first account, counts once.
+ */
+export function count(
+  c: Context<Env>,
+  options: count.Options,
+): Promise<boolean> {
+  const counted = c.var.counted ?? new Map<string, Promise<boolean>>()
+  if (!c.var.counted) c.set('counted', counted)
+  const id = JSON.stringify([options.binding, options.key])
+  const outcome =
+    counted.get(id) ??
+    Timing.measure(
+      c,
+      c.env[options.binding].limit({ key: options.key }),
+      'ratelimit.limit',
+    ).then((result) => result.success)
+  counted.set(id, outcome)
+  return outcome
+}
+
+export declare namespace count {
+  type Options = {
+    /** The limiter's binding name, which sets the limit. */
+    binding: Limits.Limit
+    /** The counter's key. Keys never hold secrets, codes, or tokens. */
+    key: string
+  }
+}
+
+/**
+ * Counts a sign-in code for `email` in the database, and returns whether the address is within
+ * {@link codePolicy}. The Workers limits count each location on its own, so only this count bounds
+ * the guesses at one address across every location. Each count is a `verification` row that expires
+ * with the window, and a refused count deletes its row.
+ */
+export async function countCode(
+  db: Realm.Database,
+  options: countCode.Options,
+) {
+  const identifier = `sign-in-codes:${email(options)}`
+  const now = Date.now()
+  const id = crypto.randomUUID()
+
+  // The insert comes before the count, so of concurrent requests at most the quota passes.
+  await db.insert(Schema.verification).values({
+    expiresAt: new Date(now + codePolicy.window * 1000),
+    id,
+    identifier,
+    value: '',
+  })
+  const [row] = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(Schema.verification)
+    .where(
+      and(
+        eq(Schema.verification.identifier, identifier),
+        gt(Schema.verification.expiresAt, new Date(now)),
+      ),
+    )
+  if ((row?.count ?? 0) <= codePolicy.quota) return true
+
+  await db.delete(Schema.verification).where(eq(Schema.verification.id, id))
+  return false
+}
+
+export declare namespace countCode {
+  type Options = {
+    /** The trimmed, lowercased address. */
+    email: string
+  }
+}
+
+/**
+ * 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 `meta: { retryAfter }`, 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
+  }
+}