@lunora/auth 0.0.0 → 1.0.0-alpha.2

package/dist/store.d.ts

@@ -0,0 +1,66 @@
+import { CustomAdapter } from 'better-auth/adapters';
+/** A stored auth row — an opaque bag of columns keyed by better-auth field name. */
+type AuthRow = Record<string, unknown>;
+/**
+* One normalized better-auth where clause. Derived from {@link CustomAdapter}'s
+* own method signature (rather than re-declared) so a better-auth change to the
+* clause shape surfaces as a compile error here, not a silent mis-match.
+*/
+type AuthWhereClause = NonNullable<Parameters<CustomAdapter["findOne"]>[0]["where"]>[number];
+/** Read query handed to {@link AuthStore.read}: a where filter plus optional sort/window. */
+interface AuthQuery {
+  limit?: number;
+  offset?: number;
+  sortBy?: {
+    direction: "asc" | "desc";
+    field: string;
+  };
+  where: ReadonlyArray<AuthWhereClause>;
+}
+/**
+* The minimal table-addressed store the `lunoraAuthAdapter` drives. This is the
+* seam a Lunora runtime binds to its ORM: back each method with `ctx.db` over
+* the global (D1) auth tables that `authTables(...)` generates, and better-auth's
+* reads/writes flow through Lunora's data layer (triggers, aggregates, OCC)
+* instead of better-auth's own adapter. Field names and table (`model`) names are
+* already the database names better-auth resolved from the schema, so a store
+* passes them straight through.
+*
+* {@link createMemoryAuthStore} is a reference in-memory implementation (also
+* what the tests run better-auth against); `createSqlAuthStore` is the SQL one.
+*/
+interface AuthStore {
+  /**
+  * Atomically delete **at most one** row in `model` matching `where` and
+  * return it (or `undefined` if none matched). Backs better-auth's
+  * single-use-token consume (OTP / magic-link / email-verification /
+  * password-reset): implementing it natively — one round trip that finds and
+  * deletes in a single statement — closes the read-then-delete race the
+  * factory's `findMany` + `deleteMany` fallback would otherwise leave open.
+  */
+  consumeOne: (model: string, where: ReadonlyArray<AuthWhereClause>) => Promise<AuthRow | undefined>;
+  /** Count rows in `model` matching `where` (empty `where` = all rows). */
+  count: (model: string, where: ReadonlyArray<AuthWhereClause>) => Promise<number>;
+  /** Insert `data` into `model`; return the stored row (the adapter pre-fills `id`). */
+  create: (model: string, data: AuthRow) => Promise<AuthRow>;
+  /** Read rows from `model` honouring the filter/sort/window in `query`. */
+  read: (model: string, query: AuthQuery) => Promise<AuthRow[]>;
+  /** Delete rows in `model` matching `where`; return how many were removed. */
+  remove: (model: string, where: ReadonlyArray<AuthWhereClause>) => Promise<number>;
+  /** Patch rows in `model` matching `where` with `values`; return the updated rows. */
+  update: (model: string, where: ReadonlyArray<AuthWhereClause>, values: AuthRow) => Promise<AuthRow[]>;
+}
+/**
+* Evaluate a better-auth where clause list against a row. Clauses fold
+* left-to-right by their `connector` (`AND` by default, `OR` when set) — the
+* same precedence better-auth's own adapters use. An empty list matches every
+* row. Exported so any in-memory-style {@link AuthStore} can reuse it.
+*/
+declare const matchesWhere: (row: AuthRow, where: ReadonlyArray<AuthWhereClause>) => boolean;
+/**
+* Reference in-memory {@link AuthStore} — used to run better-auth end to end in
+* tests, and a worked example of the contract a Lunora-`ctx.db`-backed store
+* fulfils. Not for production (state is per-instance and non-durable).
+*/
+declare const createMemoryAuthStore: () => AuthStore;
+export { AuthQuery, type AuthRow, AuthStore, type AuthWhereClause, createMemoryAuthStore, matchesWhere };

package/dist/store.mjs

@@ -0,0 +1,170 @@
+const asString = (value) => typeof value === "string" ? value : void 0;
+const isNullish = (value) => value === void 0 || value === null;
+const looseEquals = (left, right, insensitive) => {
+  if (insensitive) {
+    const a = asString(left);
+    const b = asString(right);
+    if (a !== void 0 && b !== void 0) {
+      return a.toLowerCase() === b.toLowerCase();
+    }
+  }
+  return left === right;
+};
+const matchesPattern = (cell, value, operator, insensitive) => {
+  const haystack = asString(cell);
+  const needle = asString(value);
+  if (haystack === void 0 || needle === void 0) {
+    return false;
+  }
+  const [a, b] = insensitive ? [haystack.toLowerCase(), needle.toLowerCase()] : [haystack, needle];
+  if (operator === "contains") {
+    return a.includes(b);
+  }
+  return operator === "starts_with" ? a.startsWith(b) : a.endsWith(b);
+};
+const evaluateClause = (row, clause) => {
+  const { field, mode, operator, value } = clause;
+  const cell = row[field];
+  const insensitive = mode === "insensitive";
+  switch (operator) {
+    case "contains":
+    case "ends_with":
+    case "starts_with": {
+      return matchesPattern(cell, value, operator, insensitive);
+    }
+    case "gt": {
+      return !isNullish(value) && cell > value;
+    }
+    case "gte": {
+      return !isNullish(value) && cell >= value;
+    }
+    case "in": {
+      return Array.isArray(value) && value.some((entry) => looseEquals(cell, entry, insensitive));
+    }
+    case "lt": {
+      return !isNullish(value) && cell < value;
+    }
+    case "lte": {
+      return !isNullish(value) && cell <= value;
+    }
+    case "ne": {
+      return !looseEquals(cell, value, insensitive);
+    }
+    case "not_in": {
+      return Array.isArray(value) && !value.some((entry) => looseEquals(cell, entry, insensitive));
+    }
+    // "eq" and the default: null-aware equality.
+    default: {
+      return isNullish(value) ? isNullish(cell) : looseEquals(cell, value, insensitive);
+    }
+  }
+};
+const compareCells = (a, b) => {
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b);
+  }
+  const left = Number(a);
+  const right = Number(b);
+  if (left < right) {
+    return -1;
+  }
+  return left > right ? 1 : 0;
+};
+const sortRows = (rows, sortBy) => {
+  const direction = sortBy.direction === "asc" ? 1 : -1;
+  return rows.toSorted((left, right) => {
+    const a = left[sortBy.field];
+    const b = right[sortBy.field];
+    if (isNullish(a) && isNullish(b)) {
+      return 0;
+    }
+    if (isNullish(a)) {
+      return -direction;
+    }
+    if (isNullish(b)) {
+      return direction;
+    }
+    return compareCells(a, b) * direction;
+  });
+};
+const matchesWhere = (row, where) => {
+  let result = true;
+  for (const [index, clause] of where.entries()) {
+    const clauseResult = evaluateClause(row, clause);
+    if (index === 0) {
+      result = clauseResult;
+    } else if (clause.connector === "OR") {
+      result = result || clauseResult;
+    } else {
+      result = result && clauseResult;
+    }
+  }
+  return result;
+};
+const createMemoryAuthStore = () => {
+  const tables = /* @__PURE__ */ new Map();
+  const tableOf = (model) => {
+    const existing = tables.get(model);
+    if (existing) {
+      return existing;
+    }
+    const created = [];
+    tables.set(model, created);
+    return created;
+  };
+  return {
+    consumeOne: (model, where) => {
+      const table = tableOf(model);
+      const index = table.findIndex((row2) => matchesWhere(row2, where));
+      if (index === -1) {
+        return Promise.resolve(void 0);
+      }
+      const [row] = table.splice(index, 1);
+      return Promise.resolve(row ? { ...row } : void 0);
+    },
+    count: (model, where) => Promise.resolve(tableOf(model).filter((row) => matchesWhere(row, where)).length),
+    create: (model, data) => {
+      const row = { ...data };
+      tableOf(model).push(row);
+      return Promise.resolve({ ...row });
+    },
+    read: (model, query) => {
+      let rows = tableOf(model).filter((row) => matchesWhere(row, query.where));
+      if (query.sortBy) {
+        rows = sortRows(rows, query.sortBy);
+      }
+      if (query.offset) {
+        rows = rows.slice(query.offset);
+      }
+      if (query.limit !== void 0) {
+        rows = rows.slice(0, query.limit);
+      }
+      return Promise.resolve(
+        rows.map((row) => {
+          return { ...row };
+        })
+      );
+    },
+    remove: (model, where) => {
+      const table = tableOf(model);
+      const kept = table.filter((row) => !matchesWhere(row, where));
+      const removed = table.length - kept.length;
+      table.length = 0;
+      table.push(...kept);
+      return Promise.resolve(removed);
+    },
+    update: (model, where, values) => {
+      const matched = tableOf(model).filter((row) => matchesWhere(row, where));
+      for (const row of matched) {
+        Object.assign(row, values);
+      }
+      return Promise.resolve(
+        matched.map((row) => {
+          return { ...row };
+        })
+      );
+    }
+  };
+};
+
+export { createMemoryAuthStore, matchesWhere };

package/dist/turnstile-middleware.d.mts

@@ -0,0 +1,80 @@
+import { Middleware } from '@lunora/server';
+import { FetchLike, TurnstileVerifyResult } from "./turnstile.mjs";
+interface VerifyTurnstileMiddlewareOptions<Context> {
+  /**
+  * Assert the widget `action` the token was solved for (forwarded to
+  * {@link verifyTurnstile}). When set and the siteverify response's `action`
+  * does not match, the verdict is treated as a failure (403). Optional.
+  */
+  expectedAction?: string;
+  /**
+  * Assert the `hostname` the challenge was solved on (forwarded to
+  * {@link verifyTurnstile}). When set and the siteverify response's `hostname`
+  * does not match, the verdict is treated as a failure (403). Set this when a
+  * single secret/sitekey is shared across multiple domains to stop a token
+  * harvested on one origin being replayed against this procedure. Optional.
+  */
+  expectedHostname?: string;
+  /**
+  * Behavior when the siteverify call itself throws (network error, non-2xx).
+  * Defaults to `false` (**fail closed**: reject with 403). Set `true` only
+  * when degraded availability is preferable to denying traffic — a failing
+  * siteverify then admits every request. Mirrors `@lunora/ratelimit`'s
+  * `rateLimit` failure policy.
+  */
+  failOpen?: boolean;
+  /**
+  * Inject a `fetch` implementation (forwarded to {@link verifyTurnstile}).
+  * Primarily for tests.
+  */
+  fetch?: FetchLike;
+  /** Override the error message thrown on a failed verdict. */
+  message?: string;
+  /**
+  * Selector that pulls the visitor IP from `ctx` (the procedure context has
+  * no raw `Headers`, so this must come from `args`/ctx). Optional.
+  */
+  remoteip?: (context: Context) => string | undefined;
+  /** Your Turnstile secret key (the `TURNSTILE_SECRET_KEY` env var). */
+  secret: string;
+  /**
+  * Selector that pulls the `cf-turnstile-response` token from `ctx`. The
+  * procedure context carries only the resolved identity, **not** the raw
+  * inbound `Headers` (see `withAuthPlugins` in `./middleware`), so the token
+  * must travel in the function `args` and be read out here.
+  */
+  token: (context: Context) => string | undefined;
+  /**
+  * Extra predicate run on a `success: true` verdict (after the built-in
+  * `expectedHostname`/`expectedAction` checks). Return `false` to reject the
+  * request with 403 — use it for any custom replay/abuse guard that needs the
+  * full verdict (e.g. matching `cdata`, or one hostname out of an allow-list).
+  */
+  validate?: (result: TurnstileVerifyResult) => boolean;
+}
+/**
+* Procedure middleware that enforces a Turnstile (CAPTCHA) check before the
+* handler runs. Attach it with `.use()`. It reads the token (and optional IP)
+* from `ctx` via the provided selectors — because the procedure context does
+* not carry raw request headers, the token must be passed through the function
+* `args`. To gate the better-auth sign-in/sign-up flow itself, prefer
+* better-auth's native `captcha` plugin (re-exported from `@lunora/auth/plugins`)
+* — this middleware is for non-auth Lunora procedures.
+*
+* On a `success: false` verdict (or a missing token) it throws a structural
+* `LunoraError` (`{ name: "LunoraError", code: "FORBIDDEN", status: 403 }`) —
+* the runtime maps it to the matching RPC/HTTP status without any runtime
+* import of `@lunora/server` (the `Middleware` import is type-only).
+*
+* **Failure policy:** if the siteverify call itself throws, the middleware
+* **fails closed by default** (logs and rejects with 403). Pass
+* `failOpen: true` to admit the request instead — mirrors `@lunora/ratelimit`.
+*
+* **Cross-origin replay:** a token solved on one origin can be replayed against
+* a different endpoint when a single secret/sitekey is shared across multiple
+* domains. Pass `expectedHostname` (and optionally `expectedAction`, or a custom
+* `validate(result)` predicate) to assert the siteverify response's `hostname`
+* /`action` and reject mismatches with 403.
+*/
+declare const verifyTurnstileMiddleware: <Context>(options: VerifyTurnstileMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type VerifyTurnstileMiddlewareOptions, verifyTurnstileMiddleware };

package/dist/turnstile-middleware.d.ts

@@ -0,0 +1,80 @@
+import { Middleware } from '@lunora/server';
+import { FetchLike, TurnstileVerifyResult } from "./turnstile.js";
+interface VerifyTurnstileMiddlewareOptions<Context> {
+  /**
+  * Assert the widget `action` the token was solved for (forwarded to
+  * {@link verifyTurnstile}). When set and the siteverify response's `action`
+  * does not match, the verdict is treated as a failure (403). Optional.
+  */
+  expectedAction?: string;
+  /**
+  * Assert the `hostname` the challenge was solved on (forwarded to
+  * {@link verifyTurnstile}). When set and the siteverify response's `hostname`
+  * does not match, the verdict is treated as a failure (403). Set this when a
+  * single secret/sitekey is shared across multiple domains to stop a token
+  * harvested on one origin being replayed against this procedure. Optional.
+  */
+  expectedHostname?: string;
+  /**
+  * Behavior when the siteverify call itself throws (network error, non-2xx).
+  * Defaults to `false` (**fail closed**: reject with 403). Set `true` only
+  * when degraded availability is preferable to denying traffic — a failing
+  * siteverify then admits every request. Mirrors `@lunora/ratelimit`'s
+  * `rateLimit` failure policy.
+  */
+  failOpen?: boolean;
+  /**
+  * Inject a `fetch` implementation (forwarded to {@link verifyTurnstile}).
+  * Primarily for tests.
+  */
+  fetch?: FetchLike;
+  /** Override the error message thrown on a failed verdict. */
+  message?: string;
+  /**
+  * Selector that pulls the visitor IP from `ctx` (the procedure context has
+  * no raw `Headers`, so this must come from `args`/ctx). Optional.
+  */
+  remoteip?: (context: Context) => string | undefined;
+  /** Your Turnstile secret key (the `TURNSTILE_SECRET_KEY` env var). */
+  secret: string;
+  /**
+  * Selector that pulls the `cf-turnstile-response` token from `ctx`. The
+  * procedure context carries only the resolved identity, **not** the raw
+  * inbound `Headers` (see `withAuthPlugins` in `./middleware`), so the token
+  * must travel in the function `args` and be read out here.
+  */
+  token: (context: Context) => string | undefined;
+  /**
+  * Extra predicate run on a `success: true` verdict (after the built-in
+  * `expectedHostname`/`expectedAction` checks). Return `false` to reject the
+  * request with 403 — use it for any custom replay/abuse guard that needs the
+  * full verdict (e.g. matching `cdata`, or one hostname out of an allow-list).
+  */
+  validate?: (result: TurnstileVerifyResult) => boolean;
+}
+/**
+* Procedure middleware that enforces a Turnstile (CAPTCHA) check before the
+* handler runs. Attach it with `.use()`. It reads the token (and optional IP)
+* from `ctx` via the provided selectors — because the procedure context does
+* not carry raw request headers, the token must be passed through the function
+* `args`. To gate the better-auth sign-in/sign-up flow itself, prefer
+* better-auth's native `captcha` plugin (re-exported from `@lunora/auth/plugins`)
+* — this middleware is for non-auth Lunora procedures.
+*
+* On a `success: false` verdict (or a missing token) it throws a structural
+* `LunoraError` (`{ name: "LunoraError", code: "FORBIDDEN", status: 403 }`) —
+* the runtime maps it to the matching RPC/HTTP status without any runtime
+* import of `@lunora/server` (the `Middleware` import is type-only).
+*
+* **Failure policy:** if the siteverify call itself throws, the middleware
+* **fails closed by default** (logs and rejects with 403). Pass
+* `failOpen: true` to admit the request instead — mirrors `@lunora/ratelimit`.
+*
+* **Cross-origin replay:** a token solved on one origin can be replayed against
+* a different endpoint when a single secret/sitekey is shared across multiple
+* domains. Pass `expectedHostname` (and optionally `expectedAction`, or a custom
+* `validate(result)` predicate) to assert the siteverify response's `hostname`
+* /`action` and reject mismatches with 403.
+*/
+declare const verifyTurnstileMiddleware: <Context>(options: VerifyTurnstileMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type VerifyTurnstileMiddlewareOptions, verifyTurnstileMiddleware };

package/dist/turnstile-middleware.mjs

@@ -0,0 +1,45 @@
+import { verifyTurnstile } from './turnstile.mjs';
+
+const verifyTurnstileMiddleware = (options) => async ({ ctx, next }) => {
+  const token = options.token(ctx);
+  if (token === void 0 || token === "") {
+    throw Object.assign(new Error(options.message ?? "turnstile token missing"), {
+      code: "FORBIDDEN",
+      name: "LunoraError",
+      status: 403
+    });
+  }
+  let result;
+  try {
+    result = await verifyTurnstile({
+      expectedAction: options.expectedAction,
+      expectedHostname: options.expectedHostname,
+      fetch: options.fetch,
+      remoteip: options.remoteip?.(ctx),
+      secret: options.secret,
+      token
+    });
+  } catch (error) {
+    console.error(`@lunora/auth: verifyTurnstileMiddleware siteverify threw; ${options.failOpen ? "failing open" : "failing closed"}`, error);
+    if (options.failOpen) {
+      return next();
+    }
+    throw Object.assign(new Error(options.message ?? "turnstile verification unavailable"), {
+      cause: error,
+      code: "FORBIDDEN",
+      name: "LunoraError",
+      status: 403
+    });
+  }
+  if (!result.success || options.validate !== void 0 && !options.validate(result)) {
+    throw Object.assign(new Error(options.message ?? "turnstile verification failed"), {
+      code: "FORBIDDEN",
+      errorCodes: result.errorCodes,
+      name: "LunoraError",
+      status: 403
+    });
+  }
+  return next();
+};
+
+export { verifyTurnstileMiddleware };

package/dist/turnstile.d.mts

@@ -0,0 +1,98 @@
+/**
+* Cloudflare Turnstile server-side verification.
+*
+* Turnstile has **no Cloudflare binding** — verification is a single HTTPS POST
+* to the public `siteverify` endpoint with your secret key. The secret lives in
+* a plain env var / `.dev.vars` (conventionally `TURNSTILE_SECRET_KEY`), not in
+* `wrangler.jsonc`. This module is therefore pure, transport-agnostic, and
+* usable from any mutation/action — not just the auth flow.
+* @see https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
+*/
+/** Cloudflare's public Turnstile `siteverify` endpoint. */
+declare const TURNSTILE_VERIFY_ENDPOINT = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/** Minimal `fetch` shape we depend on, so callers can inject a stub in tests. */
+type FetchLike = (input: string, init?: {
+  body?: BodyInit;
+  headers?: Record<string, string>;
+  method?: string;
+}) => Promise<Response>;
+interface VerifyTurnstileOptions {
+  /**
+  * Assert the widget `action` the token was solved for. Cloudflare echoes the
+  * customer-supplied `action` back in the siteverify response; when this is
+  * set and the returned `action` does not match, the verdict is downgraded to
+  * `success: false` (with error code `action-mismatch`). Leave unset to skip
+  * the check.
+  */
+  expectedAction?: string;
+  /**
+  * Assert the `hostname` the challenge was solved on. Cloudflare returns the
+  * solving hostname in the siteverify response; when this is set and the
+  * returned `hostname` does not match, the verdict is downgraded to
+  * `success: false` (with error code `hostname-mismatch`). Set this when a
+  * single secret/sitekey is shared across multiple domains to stop a token
+  * harvested on one origin from being replayed against another. Leave unset
+  * to skip the check.
+  */
+  expectedHostname?: string;
+  /**
+  * Inject a `fetch` implementation. Defaults to `globalThis.fetch`. Primarily
+  * for unit tests — production callers can omit it.
+  */
+  fetch?: FetchLike;
+  /**
+  * The visitor's IP address, if known. Optional; Cloudflare uses it as an
+  * extra signal but verification works without it.
+  */
+  remoteip?: string;
+  /** Your Turnstile secret key (the `TURNSTILE_SECRET_KEY` env var). */
+  secret: string;
+  /** The `cf-turnstile-response` token produced by the widget on the client. */
+  token: string;
+}
+/**
+* The normalized result of a Turnstile verification. Snake-cased fields from
+* Cloudflare (`error-codes`, `challenge_ts`) are mapped to camelCase.
+*
+* A `success: false` verdict is a **bot/invalid-token** outcome, not an error —
+* it is returned, never thrown. `verifyTurnstile` only throws on transport
+* failure (network error, non-2xx response).
+*/
+interface TurnstileVerifyResult {
+  /** The customer-supplied `action` the widget was rendered with, if any. */
+  action?: string;
+  /** Customer data passed through the widget (`cData`), if any. */
+  cdata?: string;
+  /** ISO timestamp of the challenge, if Cloudflare returned one. */
+  challengeTs?: string;
+  /**
+  * Cloudflare error codes for a failed verification (e.g.
+  * `"invalid-input-response"`, `"timeout-or-duplicate"`). Empty on success.
+  */
+  errorCodes: string[];
+  /** Hostname the challenge was solved on, if Cloudflare returned one. */
+  hostname?: string;
+  /** Whether Cloudflare considers the token valid. */
+  success: boolean;
+}
+/**
+* Verify a Turnstile token against Cloudflare's `siteverify` endpoint.
+*
+* POSTs `application/x-www-form-urlencoded` (`secret`, `response`=token, and an
+* optional `remoteip`) and returns the parsed verdict. A `success: false`
+* outcome (bot / invalid / expired token) is **returned**, not thrown — callers
+* decide how to react. The function throws a structural `LunoraError`-shaped
+* error (`{ name: "LunoraError", code: "SERVICE_UNAVAILABLE", status: 503 }`)
+* only when the siteverify call itself fails (network error or non-2xx), so a
+* "siteverify is down" failure is distinguishable from a "this is a bot"
+* verdict.
+*/
+declare const verifyTurnstile: ({
+  expectedAction,
+  expectedHostname,
+  fetch,
+  remoteip,
+  secret,
+  token
+}: VerifyTurnstileOptions) => Promise<TurnstileVerifyResult>;
+export { type FetchLike, TURNSTILE_VERIFY_ENDPOINT, type TurnstileVerifyResult, type VerifyTurnstileOptions, verifyTurnstile };

package/dist/turnstile.d.ts

@@ -0,0 +1,98 @@
+/**
+* Cloudflare Turnstile server-side verification.
+*
+* Turnstile has **no Cloudflare binding** — verification is a single HTTPS POST
+* to the public `siteverify` endpoint with your secret key. The secret lives in
+* a plain env var / `.dev.vars` (conventionally `TURNSTILE_SECRET_KEY`), not in
+* `wrangler.jsonc`. This module is therefore pure, transport-agnostic, and
+* usable from any mutation/action — not just the auth flow.
+* @see https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
+*/
+/** Cloudflare's public Turnstile `siteverify` endpoint. */
+declare const TURNSTILE_VERIFY_ENDPOINT = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/** Minimal `fetch` shape we depend on, so callers can inject a stub in tests. */
+type FetchLike = (input: string, init?: {
+  body?: BodyInit;
+  headers?: Record<string, string>;
+  method?: string;
+}) => Promise<Response>;
+interface VerifyTurnstileOptions {
+  /**
+  * Assert the widget `action` the token was solved for. Cloudflare echoes the
+  * customer-supplied `action` back in the siteverify response; when this is
+  * set and the returned `action` does not match, the verdict is downgraded to
+  * `success: false` (with error code `action-mismatch`). Leave unset to skip
+  * the check.
+  */
+  expectedAction?: string;
+  /**
+  * Assert the `hostname` the challenge was solved on. Cloudflare returns the
+  * solving hostname in the siteverify response; when this is set and the
+  * returned `hostname` does not match, the verdict is downgraded to
+  * `success: false` (with error code `hostname-mismatch`). Set this when a
+  * single secret/sitekey is shared across multiple domains to stop a token
+  * harvested on one origin from being replayed against another. Leave unset
+  * to skip the check.
+  */
+  expectedHostname?: string;
+  /**
+  * Inject a `fetch` implementation. Defaults to `globalThis.fetch`. Primarily
+  * for unit tests — production callers can omit it.
+  */
+  fetch?: FetchLike;
+  /**
+  * The visitor's IP address, if known. Optional; Cloudflare uses it as an
+  * extra signal but verification works without it.
+  */
+  remoteip?: string;
+  /** Your Turnstile secret key (the `TURNSTILE_SECRET_KEY` env var). */
+  secret: string;
+  /** The `cf-turnstile-response` token produced by the widget on the client. */
+  token: string;
+}
+/**
+* The normalized result of a Turnstile verification. Snake-cased fields from
+* Cloudflare (`error-codes`, `challenge_ts`) are mapped to camelCase.
+*
+* A `success: false` verdict is a **bot/invalid-token** outcome, not an error —
+* it is returned, never thrown. `verifyTurnstile` only throws on transport
+* failure (network error, non-2xx response).
+*/
+interface TurnstileVerifyResult {
+  /** The customer-supplied `action` the widget was rendered with, if any. */
+  action?: string;
+  /** Customer data passed through the widget (`cData`), if any. */
+  cdata?: string;
+  /** ISO timestamp of the challenge, if Cloudflare returned one. */
+  challengeTs?: string;
+  /**
+  * Cloudflare error codes for a failed verification (e.g.
+  * `"invalid-input-response"`, `"timeout-or-duplicate"`). Empty on success.
+  */
+  errorCodes: string[];
+  /** Hostname the challenge was solved on, if Cloudflare returned one. */
+  hostname?: string;
+  /** Whether Cloudflare considers the token valid. */
+  success: boolean;
+}
+/**
+* Verify a Turnstile token against Cloudflare's `siteverify` endpoint.
+*
+* POSTs `application/x-www-form-urlencoded` (`secret`, `response`=token, and an
+* optional `remoteip`) and returns the parsed verdict. A `success: false`
+* outcome (bot / invalid / expired token) is **returned**, not thrown — callers
+* decide how to react. The function throws a structural `LunoraError`-shaped
+* error (`{ name: "LunoraError", code: "SERVICE_UNAVAILABLE", status: 503 }`)
+* only when the siteverify call itself fails (network error or non-2xx), so a
+* "siteverify is down" failure is distinguishable from a "this is a bot"
+* verdict.
+*/
+declare const verifyTurnstile: ({
+  expectedAction,
+  expectedHostname,
+  fetch,
+  remoteip,
+  secret,
+  token
+}: VerifyTurnstileOptions) => Promise<TurnstileVerifyResult>;
+export { type FetchLike, TURNSTILE_VERIFY_ENDPOINT, type TurnstileVerifyResult, type VerifyTurnstileOptions, verifyTurnstile };