@lunora/auth 1.0.0-alpha.21 → 1.0.0-alpha.211

package/dist/store.d.ts

@@ -2,10 +2,10 @@ 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.
-*/
+ * 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 {
@@ -18,48 +18,48 @@ interface AuthQuery {
   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.
-*/
+ * 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.
-  */
+   * 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>;
   /**
-  * Atomically apply signed numeric deltas to **at most one** row in `model`
-  * matching `where`, then return the updated row (or `undefined` if the guard
-  * matched none). For each `increment` entry it applies `field = field + delta`
-  * (a negative delta decrements); the optional `set` map assigns absolute
-  * values in the same step. The `where` clause is both selector **and** guard
-  * — comparison operators are honoured, so a guard like
-  * `{ field: "count", operator: "lt", value: max }` only mutates the row while
-  * it still satisfies the predicate.
-  *
-  * Backs better-auth's durable (`storage: "database"`) rate limiter, whose
-  * counter rides these tables. Implementing it natively — one statement that
-  * guards, increments, and returns — gives the **one-winner-across-isolates**
-  * guarantee the read-then-update fallback cannot: on Workers two concurrent
-  * requests would otherwise both read `count=4` and both write `5`, letting a
-  * `max` of 5 pass 6+. Same race-closing rationale as {@link AuthStore.consumeOne}.
-  */
+   * Atomically apply signed numeric deltas to **at most one** row in `model`
+   * matching `where`, then return the updated row (or `undefined` if the guard
+   * matched none). For each `increment` entry it applies `field = field + delta`
+   * (a negative delta decrements); the optional `set` map assigns absolute
+   * values in the same step. The `where` clause is both selector **and** guard
+   * — comparison operators are honoured, so a guard like
+   * `{ field: "count", operator: "lt", value: max }` only mutates the row while
+   * it still satisfies the predicate.
+   *
+   * Backs better-auth's durable (`storage: "database"`) rate limiter, whose
+   * counter rides these tables. Implementing it natively — one statement that
+   * guards, increments, and returns — gives the **one-winner-across-isolates**
+   * guarantee the read-then-update fallback cannot: on Workers two concurrent
+   * requests would otherwise both read `count=4` and both write `5`, letting a
+   * `max` of 5 pass 6+. Same race-closing rationale as {@link AuthStore.consumeOne}.
+   */
   incrementOne: (model: string, where: ReadonlyArray<AuthWhereClause>, increment: Record<string, number>, set?: AuthRow) => Promise<AuthRow | undefined>;
   /** Read rows from `model` honouring the filter/sort/window in `query`. */
   read: (model: string, query: AuthQuery) => Promise<AuthRow[]>;
@@ -69,16 +69,34 @@ interface AuthStore {
   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.
-*/
+ * Evaluate a better-auth where clause list against a row.
+ *
+ * better-auth hands an adapter a FLAT list in which each clause carries its own
+ * `connector` (`AND` by default). Every persistent adapter it ships resolves that
+ * by PARTITIONING: `AND(and-clauses) AND OR(or-clauses)`. The OR clauses are
+ * alternatives among themselves, never an escape hatch from the AND clauses —
+ * `@better-auth/kysely-adapter` pushes each group into its own `.where()` (two
+ * `.where()` calls are ANDed), `@better-auth/drizzle-adapter` ends in
+ * `and(andClause, orClause)`, and `@better-auth/prisma-adapter` emits
+ * `{ AND: […], OR: […] }`, which Prisma also ANDs.
+ *
+ * This used to fold the list left-associatively instead, so `[A, B(OR), C(OR)]`
+ * meant `A OR B OR C` — strictly BROADER than any of them. On a credential lookup
+ * that is an authentication bypass in shape: a row failing the primary condition
+ * is still returned because a secondary one matched. `@better-auth/memory-adapter`
+ * does fold left, but it is the only one and it re-evaluates `where[0]` inside the
+ * same loop; the persistent adapters are the contract worth mirroring, and they
+ * are also what a plugin author will have tested against.
+ *
+ * An empty list matches every row, and a list with no OR clause is unaffected —
+ * which is every clause list better-auth 1.7.1 itself builds. 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).
-*/
+ * 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

@@ -1,183 +1 @@
-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 });
-    },
-    incrementOne: (model, where, increment, set) => {
-      const row = tableOf(model).find((candidate) => matchesWhere(candidate, where));
-      if (!row) {
-        return Promise.resolve(void 0);
-      }
-      for (const [field, delta] of Object.entries(increment)) {
-        row[field] = (typeof row[field] === "number" ? row[field] : 0) + delta;
-      }
-      if (set) {
-        Object.assign(row, set);
-      }
-      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 };
+const d=i=>typeof i=="string"?i:void 0,a=i=>i==null,f=(i,o,n)=>{if(n){const s=d(i),e=d(o);if(s!==void 0&&e!==void 0)return s.toLowerCase()===e.toLowerCase()}return i===o},v=(i,o,n,s)=>{const e=d(i),t=d(o);if(e===void 0||t===void 0)return!1;const[r,c]=s?[e.toLowerCase(),t.toLowerCase()]:[e,t];return n==="contains"?r.includes(c):n==="starts_with"?r.startsWith(c):r.endsWith(c)},m=(i,o)=>{const{field:n,mode:s,operator:e,value:t}=o,r=i[n],c=s==="insensitive";switch(e){case"contains":case"ends_with":case"starts_with":return v(r,t,e,c);case"gt":return!a(t)&&r>t;case"gte":return!a(t)&&r>=t;case"in":return Array.isArray(t)&&t.some(u=>f(r,u,c));case"lt":return!a(t)&&r<t;case"lte":return!a(t)&&r<=t;case"ne":return!f(r,t,c);case"not_in":return Array.isArray(t)&&!t.some(u=>f(r,u,c));default:return a(t)?a(r):f(r,t,c)}},h=(i,o)=>{if(typeof i=="string"&&typeof o=="string")return i.localeCompare(o);const n=Number(i),s=Number(o);return n<s?-1:n>s?1:0},g=(i,o)=>{const n=o.direction==="asc"?1:-1;return i.toSorted((s,e)=>{const t=s[o.field],r=e[o.field];return a(t)&&a(r)?0:a(t)?-n:a(r)?n:h(t,r)*n})},l=(i,o)=>{const n=o.filter(e=>e.connector==="OR");return o.filter(e=>e.connector!=="OR").every(e=>m(i,e))&&(n.length===0||n.some(e=>m(i,e)))},p=()=>{const i=new Map,o=n=>{const s=i.get(n);if(s)return s;const e=[];return i.set(n,e),e};return{consumeOne:(n,s)=>{const e=o(n),t=e.findIndex(c=>l(c,s));if(t===-1)return Promise.resolve(void 0);const[r]=e.splice(t,1);return Promise.resolve(r?{...r}:void 0)},count:(n,s)=>Promise.resolve(o(n).filter(e=>l(e,s)).length),create:(n,s)=>{const e={...s};return o(n).push(e),Promise.resolve({...e})},incrementOne:(n,s,e,t)=>{const r=o(n).find(c=>l(c,s));if(!r)return Promise.resolve(void 0);for(const[c,u]of Object.entries(e))r[c]=(typeof r[c]=="number"?r[c]:0)+u;return t&&Object.assign(r,t),Promise.resolve({...r})},read:(n,s)=>{let e=o(n).filter(t=>l(t,s.where));return s.sortBy&&(e=g(e,s.sortBy)),s.offset&&(e=e.slice(s.offset)),s.limit!==void 0&&(e=e.slice(0,s.limit)),Promise.resolve(e.map(t=>({...t})))},remove:(n,s)=>{const e=o(n),t=e.filter(c=>!l(c,s)),r=e.length-t.length;return e.length=0,e.push(...t),Promise.resolve(r)},update:(n,s,e)=>{const t=o(n).filter(r=>l(r,s));for(const r of t)Object.assign(r,e);return Promise.resolve(t.map(r=>({...r})))}}};export{p as createMemoryAuthStore,l as matchesWhere};

package/dist/turnstile-middleware.d.mts

@@ -2,79 +2,97 @@ 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * Selector that pulls the visitor IP off `ctx` — typically `ctx.ip`, or
+   * `ctx.args.ip` when the caller sends it (the procedure context has no raw
+   * `Headers`). 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.
-  */
+   * Selector that pulls the `cf-turnstile-response` token off `ctx`. The
+   * procedure context carries only the resolved identity, **not** the raw
+   * inbound `Headers` (see `withAuthPlugins` in `./middleware`), so the token
+   * travels in the function `args` — which the builder surfaces to middleware
+   * as `ctx.args` (validated, frozen):
+   *
+   * ```ts
+   * export const submit = mutation
+   *     .input({ message: v.string(), turnstileToken: v.string() })
+   *     .use(verifyTurnstileMiddleware({ secret: env.TURNSTILE_SECRET_KEY, token: (ctx) => ctx.args.turnstileToken }))
+   *     .mutation(async ({ args, ctx }) => { … });
+   * ```
+   */
   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).
-  */
+   * 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.
-*/
+ * 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 is passed through the function
+ * `args` and read back as `ctx.args.<field>` (the builder surfaces the
+ * VALIDATED args on the middleware context, frozen). 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 import of
+ * the error machinery from `@lunora/server`.
+ *
+ * The middleware is tagged PER-DISPATCH: a Turnstile token is single-use, so
+ * verifying one is an effect of the request that a memoized response cannot
+ * stand in for. The builder hoists the mark onto the registered function and
+ * the generated `isCacheableQuery` keeps such a query out of the reactive
+ * cache — a hit answers without running this chain, so one solved token would
+ * otherwise admit every request the memo served.
+ *
+ * **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

@@ -2,79 +2,97 @@ 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * Selector that pulls the visitor IP off `ctx` — typically `ctx.ip`, or
+   * `ctx.args.ip` when the caller sends it (the procedure context has no raw
+   * `Headers`). 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.
-  */
+   * Selector that pulls the `cf-turnstile-response` token off `ctx`. The
+   * procedure context carries only the resolved identity, **not** the raw
+   * inbound `Headers` (see `withAuthPlugins` in `./middleware`), so the token
+   * travels in the function `args` — which the builder surfaces to middleware
+   * as `ctx.args` (validated, frozen):
+   *
+   * ```ts
+   * export const submit = mutation
+   *     .input({ message: v.string(), turnstileToken: v.string() })
+   *     .use(verifyTurnstileMiddleware({ secret: env.TURNSTILE_SECRET_KEY, token: (ctx) => ctx.args.turnstileToken }))
+   *     .mutation(async ({ args, ctx }) => { … });
+   * ```
+   */
   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).
-  */
+   * 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.
-*/
+ * 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 is passed through the function
+ * `args` and read back as `ctx.args.<field>` (the builder surfaces the
+ * VALIDATED args on the middleware context, frozen). 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 import of
+ * the error machinery from `@lunora/server`.
+ *
+ * The middleware is tagged PER-DISPATCH: a Turnstile token is single-use, so
+ * verifying one is an effect of the request that a memoized response cannot
+ * stand in for. The builder hoists the mark onto the registered function and
+ * the generated `isCacheableQuery` keeps such a query out of the reactive
+ * cache — a hit answers without running this chain, so one solved token would
+ * otherwise admit every request the memo served.
+ *
+ * **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 };