@ultimat3/auth 23.0.0 → 25.0.0

package/src/policy-bridge.ts

@@ -28,7 +28,12 @@ export interface ServiceIdentity {
 /** The four `ActorKind`s, as the four things that can be holding a credential. */
 export type AuthIdentity =
   | { readonly kind: 'user'; readonly user: AuthUser; readonly session: AuthSession }
-  | { readonly kind: 'agent'; readonly apiKey: AuthApiKeyRecord }
+  | {
+      readonly kind: 'agent';
+      readonly apiKey: AuthApiKeyRecord;
+      /** What the key's owner may do — `null` for a key no user owns. See `actorFromApiKey`. */
+      readonly ownerGrants: readonly string[] | null;
+    }
   | { readonly kind: 'service'; readonly service: ServiceIdentity }
   | { readonly kind: 'anonymous' };
 
@@ -64,20 +69,58 @@ export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor
   );
 }
 
+/** `*` and `<resource>:*` — the two spellings a role uses to be granted everything. */
+export const isWildcardScope = (scope: string): boolean => scope === '*' || scope.endsWith(':*');
+
+// `@ultimat3/policy`'s own reading of a grant's resource, mirrored: same tier, so not imported.
+const resourceOf = (grant: string): string => grant.split(':')[0] ?? grant;
+
+/** Whether one of the owner's grants reaches a named permission. A grant MAY be a wildcard. */
+const covers = (grant: string, wanted: string): boolean =>
+  grant === '*' ||
+  grant === wanted ||
+  (grant.endsWith(':*') && resourceOf(grant) === resourceOf(wanted));
+
+/**
+ * What a key may carry of what it names. Two cuts, and both only ever remove:
+ *
+ * - a wildcard scope is dropped. `issueApiKey` refuses to mint one, and a row written before that
+ *   refusal (or by hand) must not keep the reach the refusal exists to deny;
+ * - a key a user OWNS keeps only the scopes that owner could exercise themselves. A key was
+ *   minted with whatever list its issuer typed, so without this a member could hold a key
+ *   reaching further than their own account — and it kept that reach after a demotion.
+ *
+ * `ownerGrants` is `null` for a key no user owns: there is nobody to be narrower than.
+ */
+export function apiKeyScopes(
+  scopes: readonly string[],
+  ownerGrants: readonly string[] | null,
+): readonly string[] {
+  return scopes.filter(
+    (scope) =>
+      !isWildcardScope(scope) &&
+      (ownerGrants === null || ownerGrants.some((grant) => covers(grant, scope))),
+  );
+}
+
 /**
- * An MCP/LLM caller. The actor's scopes are **exactly** the key's scopes — never the owning
- * user's roles, never a default set. An agent that can do more than its key says is the whole
- * failure mode this bridge exists to prevent.
+ * An MCP/LLM caller. The actor's scopes are the key's scopes cut by `apiKeyScopes` — never the
+ * owning user's roles, never a default set. An agent that can do more than its key says, or more
+ * than its owner can, is the whole failure mode this bridge exists to prevent.
  */
-export function actorFromApiKey(key: AuthApiKeyRecord): PolicyActor {
+export function actorFromApiKey(
+  key: AuthApiKeyRecord,
+  ownerGrants: readonly string[] | null,
+): PolicyActor {
+  const scopes = apiKeyScopes(key.scopes, ownerGrants);
   return withPermissions(
     agentActor({
       id: key.id,
       orgId: key.orgId ?? undefined,
       roles: [],
-      scopes: key.scopes,
+      scopes,
     }),
-    key.scopes,
+    scopes,
   );
 }
 
@@ -100,7 +143,7 @@ export function resolveActor(identity: AuthIdentity): PolicyActor {
     case 'user':
       return actorFromUser(identity.user, identity.session);
     case 'agent':
-      return actorFromApiKey(identity.apiKey);
+      return actorFromApiKey(identity.apiKey, identity.ownerGrants);
     case 'service':
       return actorFromService(identity.service);
     case 'anonymous':

package/src/privileges.ts

@@ -1,14 +1,16 @@
-// Single responsibility: changing what a user may do, and rotating the credential that was issued
-// under the old answer. `packages/auth/CLAUDE.md` has listed "rotate the session id on any
-// privilege change (`rotateSession`)" as a non-negotiable since 1.0, and
-// `SessionPolicy.rotateOnPrivilegeChange` has defaulted `true` — while `rotateSession` had no
-// caller anywhere outside its own test and the flag was read by nothing. Per axiom 3 the rule did
-// not exist. This is the caller that makes it exist.
+// Single responsibility: changing what a user may do, and ending the credentials issued under the
+// old answer — the caller's session is rotated on any privilege change, and a changed password
+// ends every other session the user holds.
 
 import type { AuthUser, UserPatch } from './adapter';
 import type { Auth } from './auth';
 import { authWriteFailed } from './errors';
-import { type IssuedSession, rotateSession, sessionCookie } from './session';
+import {
+  type IssuedSession,
+  remainingMaxAgeSeconds,
+  rotateSession,
+  sessionCookie,
+} from './session';
 
 /**
  * The fields whose change invalidates whatever the current cookie was issued under. `roles`,
@@ -28,6 +30,8 @@ export interface UpdatePrivilegesResult {
   readonly cookie?: string | undefined;
   /** Which of `PRIVILEGE_FIELDS` the patch actually named. Empty means nothing rotated. */
   readonly changed: readonly string[];
+  /** Sessions a `passwordHash` change ended. Zero for every other patch. */
+  readonly sessionsRevoked: number;
 }
 
 const changedFields = (patch: UserPatch): readonly string[] =>
@@ -44,6 +48,12 @@ const changedFields = (patch: UserPatch): readonly string[] =>
  * there is no cookie of theirs to rotate. That case wants `revokeUserSessions()` instead, and the
  * two are deliberately separate calls — silently killing an operator's own session mid-request is
  * not something a role edit should decide on its own.
+ *
+ * A `passwordHash` change is the exception, and it decides for itself: the password is what every
+ * OTHER session of this user was issued under, so they all end here. The caller's own session —
+ * passed in, and this user's — is the one that survives (rotated, or kept when rotation is off);
+ * with no session of the user's own, as in a reset or an admin's change, none survives. A changed
+ * password that left a lifted cookie working would not have changed anything for whoever holds it.
  */
 export async function updatePrivileges(
   auth: Auth,
@@ -51,24 +61,42 @@ export async function updatePrivileges(
   patch: UserPatch,
   session?: IssuedSession['session'] | undefined,
 ): Promise<UpdatePrivilegesResult> {
+  const changed = changedFields(patch);
+  const own = session !== undefined && session.userId === userId ? session : undefined;
+  const credentialChanged = changed.includes('passwordHash');
   const user = await auth.adapter.updateUser(userId, patch);
   if (user === null) throw authWriteFailed('updateUser', 'x_users');
+  if (changed.length === 0) return { user, changed, sessionsRevoked: 0 };
 
-  const changed = changedFields(patch);
-  if (
-    changed.length === 0 ||
-    session === undefined ||
-    session.userId !== userId ||
-    !auth.sessions.policy.rotateOnPrivilegeChange
-  ) {
-    return { user, changed };
+  // Every OTHER session ends BEFORE the rotation, keyed on the caller's current id (which the
+  // rotation deletes anyway). Rotation refuses a session that is already gone, and a password
+  // change must not leave the lifted cookies it was made to kill alive because of that refusal.
+  let sessionsRevoked = 0;
+  if (credentialChanged) {
+    sessionsRevoked =
+      own === undefined
+        ? await auth.adapter.deleteSessionsForUser(userId)
+        : await auth.adapter.deleteOtherSessions(userId, own.id);
   }
-
-  const issued = await rotateSession(auth.sessions, session);
+  const issued =
+    own !== undefined && auth.sessions.policy.rotateOnPrivilegeChange
+      ? await rotateSession(auth.sessions, own)
+      : undefined;
+  // And once more AFTER it: a login that landed between the early sweep and the rotation was minted
+  // under the old password too. The early sweep stays — it is what still runs when rotation
+  // refuses a session that is already gone — and this one keeps only the replacement.
+  if (credentialChanged && own !== undefined) {
+    sessionsRevoked += await auth.adapter.deleteOtherSessions(userId, issued?.session.id ?? own.id);
+  }
+  if (issued === undefined) return { user, changed, sessionsRevoked };
   return {
     user,
     changed,
+    sessionsRevoked,
     session: issued,
-    cookie: sessionCookie(issued.token, auth.sessions.policy),
+    // The rotated session keeps the old ceiling, so the cookie's `Max-Age` counts down to it too.
+    cookie: sessionCookie(issued.token, auth.sessions.policy, {
+      maxAgeSeconds: remainingMaxAgeSeconds(issued.session, auth.sessions.clock.now()),
+    }),
   };
 }

package/src/rate-limit-postgres.ts

@@ -1,104 +1,104 @@
-// The shared credential limiter: two Postgres tables, so N replicas count one spray once and a
+// The shared credential limiter: one Postgres table, so N replicas count one spray once and a
 // lockout one pod established is visible to the rest. Without it `rateLimit.scope: 'shared'` is a
 // declaration nothing can satisfy, while `x new` scaffolds `replicas: 2` — which is
 // `maxAttempts × 2` guesses per account.
-import type { Clock } from '@ultimat3/core';
-import { accountLocked } from './errors';
-import type { AuthLimiter, AuthRateLimitPolicy } from './rate-limit';
-
-/**
- * The one thing this limiter needs from the DB layer, declared structurally rather than imported.
- * `@ultimat3/action`'s `idempotency-postgres.ts` and `@ultimat3/http`'s rate-limit store declare
- * the same shape for the same reason: the connection belongs to the HOST, not to any of them, so
- * a limiter takes the pool the boot already opened instead of opening a second one against a URL
- * that was resolved once.
- *
- * **`Bun.sql` does not satisfy it** — `Bun.sql.query` is `undefined`; it is a tagged template
- * whose positional form is `unsafe`. `@ultimat3/db`'s `DbClient.query({ text, values })` does,
- * wrapped in one line, and so does a transaction handle.
- */
-export interface PgExecutor {
-  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
-}
+import type { Clock, PgExecutor } from '@ultimat3/core';
+import { accountLocked, authWriteFailed } from './errors';
+import type { AuthLimiter, AuthRateLimitPolicy, AuthReservation } from './rate-limit';
 
 /**
  * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, so
  * `x dev`, the container's `web` role and `ROLE=migrate` all install it.
  *
- * A row per FAILURE rather than a counter per key, because the window this package enforces is a
- * SLIDING one: a counter plus a window end is a fixed window, which admits `maxAttempts` at the
- * end of one window and `maxAttempts` again at the start of the next — twice the declared
- * allowance, under the same declared numbers, on the credential path.
+ * ONE row per key, holding every attempt still inside the window. The window this package enforces
+ * is a SLIDING one, so the instants are kept (a counter plus a window end is a fixed window, which
+ * admits `maxAttempts` at the end of one and `maxAttempts` again at the start of the next). They
+ * are kept IN the row because the row is what a concurrent take waits on: a count over a second
+ * table reads its statement's snapshot, and that snapshot predates the wait.
+ *
+ * The two `add column` lines are the upgrade of a table made before the reservation, on the rule
+ * `x_users` follows: additive, defaulted, idempotent, applied at every boot. The name and the
+ * first two columns are unchanged on purpose — a replica still running the previous release reads
+ * and writes this table as it always did, so a lockout holds on both sides of a rolling deploy.
  */
 export const SQL_AUTH_LIMIT_TABLES = `
-create table if not exists x_auth_failures (
-  key   text   not null,
-  at_ms bigint not null
-);
-
-create index if not exists x_auth_failures_key_idx on x_auth_failures (key, at_ms);
-
 create table if not exists x_auth_lockouts (
-  key             text   primary key,
-  locked_until_ms bigint not null
+  key             text     primary key,
+  locked_until_ms bigint   not null,
+  attempts_ms     bigint[] not null default '{}',
+  admitted        boolean  not null default true
 );
 
+alter table x_auth_lockouts add column if not exists attempts_ms bigint[] not null default '{}';
+alter table x_auth_lockouts add column if not exists admitted boolean not null default true;
+
 create index if not exists x_auth_lockouts_until_idx on x_auth_lockouts (locked_until_ms);
 `;
 
 /**
- * The per-key serializer, spelled from documented functions only: `md5` and a hex bit-string cast,
- * never `hashtext`, which is an internal with no compatibility promise.
+ * The attempts still inside the window, read off the row as it is AFTER its lock is taken. It is
+ * repeated in the statement below rather than computed once in a CTE, and the repetition is
+ * required: only a direct `x_auth_lockouts.<column>` reference inside `on conflict do update` sees
+ * what a concurrent take just committed. `$2` nowMs, `$3` windowMs.
  */
-export const SQL_AUTH_KEY_LOCK = "pg_advisory_xact_lock(('x' || md5($1))::bit(64)::bigint)";
+const LIVE =
+  'array(select at_ms from unnest(x_auth_lockouts.attempts_ms) as at_ms ' +
+  'where at_ms > $2::bigint - $3::bigint)';
+
+const LOCKED = 'x_auth_lockouts.locked_until_ms > $2::bigint';
 
 /**
- * `$1` key, `$2` nowMs — and a **transaction-scoped advisory lock on the key**, taken in the same
- * statement, before the row lands.
- *
- * `PgExecutor` accepts a transaction handle (see its doc comment), and the insert and the count
- * below are two statements. Without this lock two OUTER transactions recording a failure for one
- * account each counted only what had COMMITTED plus their own row: with `maxAttempts: 3` and one
- * failure already committed, both read two, neither locked, and both committed — three failures
- * and an open account. The lock makes the second transaction wait at the insert until the first
- * commits, so its count is taken against a snapshot that already holds the first's row.
+ * `$1` key, `$2` nowMs, `$3` windowMs, `$4` lockoutMs, `$5` maxAttempts — the reservation, in ONE
+ * statement: decide and count together, so N concurrent takes are admitted one at a time.
  *
- * Autocommit is unaffected: the lock is taken and released inside the statement's own implicit
- * transaction, which is one extra no-op per failure and no extra round trip. The guarantee is
- * READ COMMITTED, which is what `withTransaction` opens with no `isolation:` — a caller that opts
- * into `'repeatable read'` or `'serializable'` pins the count's snapshot at transaction start, and
- * no lock can make a statement see a commit its own snapshot precedes.
+ * A locked key is left untouched and answers `admitted = false`. Otherwise the attempt joins the
+ * window and, if it fills it, starts the lockout. `admitted` is persisted because `returning`
+ * cannot see the row as it was: the verdict has to be a column the statement wrote.
  *
- * `recordFailure` always locks account → ip → org (`auth.ts`), one fixed order, so two concurrent
- * sign-ins cannot take two of these locks in opposite orders and deadlock.
+ * A live lockout is never rewritten, so nothing arriving during one can shorten it. Inside a
+ * caller's own transaction the row lock is held to that commit, which is what serialises two outer
+ * transactions; `auth.ts` takes account → ip → org in that fixed order, so two sign-ins cannot
+ * hold two of these rows in opposite orders.
  */
-export const SQL_AUTH_RECORD_FAILURE = `
-with locked as (select ${SQL_AUTH_KEY_LOCK})
-insert into x_auth_failures (key, at_ms)
-select $1, $2::bigint from locked
+export const SQL_AUTH_TAKE = `
+insert into x_auth_lockouts (key, attempts_ms, locked_until_ms, admitted)
+values (
+  $1,
+  array[$2::bigint],
+  case when 1 >= $5::bigint then $2::bigint + $4::bigint else 0 end,
+  true
+)
+on conflict (key) do update
+   set attempts_ms = case when ${LOCKED} then x_auth_lockouts.attempts_ms
+                          else ${LIVE} || $2::bigint end,
+       locked_until_ms = case
+         when ${LOCKED} then x_auth_lockouts.locked_until_ms
+         when cardinality(${LIVE}) + 1 >= $5::bigint then $2::bigint + $4::bigint
+         else 0 end,
+       admitted = not (${LOCKED})
+returning admitted, locked_until_ms
 `;
 
+/** The window with the first entry equal to `$2` taken out — one reservation, never every equal one. */
+const WITHOUT =
+  '(attempts_ms[:array_position(attempts_ms, $2::bigint) - 1] || ' +
+  'attempts_ms[array_position(attempts_ms, $2::bigint) + 1:])';
+
 /**
- * `$1` key, `$2` nowMs, `$3` windowMs, `$4` lockoutMs, `$5` maxAttempts.
+ * `$1` key, `$2` the reservation's `atMs`, `$3` nowMs, `$4` windowMs, `$5` maxAttempts.
  *
- * A SECOND statement, deliberately, and not a CTE beside the insert above: every CTE in one
- * statement reads that statement's snapshot, so a `count(*)` sharing it cannot see the failure
- * being inserted beside it and the lock would fire one attempt late. Run afterwards, the count
- * sees this caller's own row and every other replica's that has committed — and, because the
- * insert holds `SQL_AUTH_KEY_LOCK`, every row a concurrent transaction on this key committed too.
- *
- * `greatest` on conflict EXTENDS a live lockout and never shortens one — a spray arriving during
- * a lockout must not be able to reset it to a nearer deadline.
+ * Gives ONE attempt back, and lifts the lockout when what is left no longer fills the window — a
+ * lockout the refunded attempt itself completed. A reservation that is no longer in the row (the
+ * key was cleared, or purged) matches nothing and changes nothing.
  */
-export const SQL_AUTH_LOCK = `
-insert into x_auth_lockouts (key, locked_until_ms)
-select $1, $2::bigint + $4::bigint
-  from x_auth_failures
- where key = $1 and at_ms > $2::bigint - $3::bigint
-having count(*) >= $5::bigint
-on conflict (key) do update
-   set locked_until_ms = greatest(x_auth_lockouts.locked_until_ms, excluded.locked_until_ms)
-returning locked_until_ms
+export const SQL_AUTH_REFUND = `
+update x_auth_lockouts
+   set attempts_ms = ${WITHOUT},
+       locked_until_ms = case
+         when (select count(*) from unnest(${WITHOUT}) as at_ms
+                where at_ms > $3::bigint - $4::bigint) < $5::bigint then 0
+         else locked_until_ms end
+ where key = $1 and array_position(attempts_ms, $2::bigint) is not null
 `;
 
 /** `$2` is the caller's clock: an expired lockout answers exactly as a missing one. */
@@ -106,30 +106,27 @@ export const SQL_AUTH_LOCKED_UNTIL = `
 select locked_until_ms from x_auth_lockouts where key = $1 and locked_until_ms > $2::bigint
 `;
 
-/** A success clears the window AND the lockout: one round trip, because both must go together. */
-export const SQL_AUTH_FORGET_KEY = `
-with cleared as (delete from x_auth_failures where key = $1 returning key)
-delete from x_auth_lockouts where key = $1
-`;
+/** A success clears the window AND the lockout: they are one row, so they go together. */
+export const SQL_AUTH_FORGET_KEY = 'delete from x_auth_lockouts where key = $1';
 
-export const SQL_AUTH_RESET = `
-with cleared as (delete from x_auth_failures returning key)
-delete from x_auth_lockouts
-`;
+export const SQL_AUTH_RESET = 'delete from x_auth_lockouts';
 
 /**
- * `$1` nowMs, `$2` windowMs — the CALLER's clock, never `now()`. Every instant in these tables is
+ * `$1` nowMs, `$2` windowMs — the CALLER's clock, never `now()`. Every instant in this table is
  * written from the caller's clock, so a purge measuring against the SERVER's would delete rows by
- * the offset between the two: failures that are still inside the window, and lockouts that are
+ * the offset between the two: attempts that are still inside the window, and lockouts that are
  * still live. The second one hands a sprayer its account back.
  */
 export const SQL_AUTH_PURGE = `
-with dropped_failures as (
-  delete from x_auth_failures where at_ms <= $1::bigint - $2::bigint returning key
-), dropped_lockouts as (
-  delete from x_auth_lockouts where locked_until_ms <= $1::bigint returning key
+with dropped as (
+  delete from x_auth_lockouts
+   where locked_until_ms <= $1::bigint
+     and not exists (
+       select 1 from unnest(attempts_ms) as at_ms where at_ms > $1::bigint - $2::bigint
+     )
+  returning key
 )
-select (select count(*) from dropped_failures) + (select count(*) from dropped_lockouts) as removed
+select count(*) as removed from dropped
 `;
 
 export interface PostgresAuthLimiterOptions {
@@ -146,9 +143,9 @@ export interface PostgresAuthLimiterOptions {
 
 export interface PostgresAuthLimiter extends AuthLimiter {
   /**
-   * Drop every failure past the window and every expired lockout, and answer how many rows went.
-   * Neither table bounds itself — `ipKey` mints one key per source address, so a spray from an
-   * IPv6 /64 is a row per attempt — and Postgres forgets nothing on its own. An app runs this
+   * Drop every key whose window has emptied and whose lockout has expired, and answer how many
+   * rows went. The table does not bound itself — `ipKey` mints one key per source address, so a
+   * spray from an IPv6 /64 is a row per attempt — and Postgres forgets nothing on its own. An app runs this
    * from a `task`; a row this deletes answers exactly as a missing one, so it changes no decision.
    */
   purgeExpired(): Promise<number>;
@@ -159,6 +156,10 @@ interface LockRow {
   readonly locked_until_ms: number | string;
 }
 
+interface TakeRow extends LockRow {
+  readonly admitted: boolean;
+}
+
 /**
  * **Install it at `defineAuth`, beside the declaration it satisfies.** Two limiters, one table:
  * the keys are prefixed (`account:`, `ip:`, `org:`) and every limit travels as a parameter, so
@@ -192,22 +193,33 @@ export function postgresAuthLimiter(options: PostgresAuthLimiterOptions): Postgr
     // bound this limiter does not enforce is the thing `assertAuthLimiterPolicy` exists to catch.
     policy: { ...policy, maxKeys: undefined, scope: 'shared' },
 
-    async assertAllowed(key): Promise<void> {
-      const until = await lockedUntilMs(key);
-      if (until === null) return;
-      throw accountLocked(key, Math.ceil((until - nowMs()) / 1000));
-    },
-
-    async recordFailure(key): Promise<void> {
+    async reserve(key): Promise<AuthReservation> {
       const at = nowMs();
-      await exec.query(SQL_AUTH_RECORD_FAILURE, [key, at]);
-      await exec.query(SQL_AUTH_LOCK, [
+      const rows = await exec.query<TakeRow>(SQL_AUTH_TAKE, [
         key,
         at,
         policy.windowMs,
         policy.lockoutMs,
         policy.maxAttempts,
       ]);
+      const row = rows[0];
+      // No row is no verdict, and no verdict is not an admission: an executor that answered
+      // nothing must not be read as "allowed" on the credential path.
+      if (row === undefined) throw authWriteFailed('reserve', 'x_auth_lockouts');
+      if (row.admitted !== true) {
+        throw accountLocked(key, Math.ceil((Number(row.locked_until_ms) - at) / 1000));
+      }
+      return { key, atMs: at };
+    },
+
+    async refund(reservation): Promise<void> {
+      await exec.query(SQL_AUTH_REFUND, [
+        reservation.key,
+        reservation.atMs,
+        nowMs(),
+        policy.windowMs,
+        policy.maxAttempts,
+      ]);
     },
 
     async recordSuccess(key): Promise<void> {

package/src/rate-limit.ts

@@ -10,6 +10,7 @@ import {
   accountLocked,
   authLimiterNotShared,
   authLimiterPolicyMismatch,
+  ORG_KEY_PREFIX,
 } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
 
@@ -65,11 +66,22 @@ export const DEFAULT_AUTH_RATE_LIMIT: AuthRateLimitPolicy = Object.freeze({
   scope: 'process',
 });
 
+/** One counted attempt, as `reserve` took it — what `refund` gives back, and nothing else. */
+export interface AuthReservation {
+  readonly key: string;
+  /** The limiter's own clock at the take. It identifies the entry inside the window. */
+  readonly atMs: number;
+}
+
 /**
  * Async on every member, so a shared implementation can exist at all: a lockout that holds across
  * replicas is a network round trip, and a synchronous signature has no way to wait for one. The
  * in-memory limiter below answers immediately — the cost is one already-settled promise per call,
  * on a path that is about to run a KDF.
+ *
+ * The allowance is RESERVED, never checked: `reserve` counts the attempt in the same step that
+ * decides whether it may run, so N concurrent guesses spend N of the allowance before any of them
+ * reaches the KDF. A check followed later by a record let every one of them pass the check.
  */
 export interface AuthLimiter {
   /**
@@ -79,23 +91,32 @@ export interface AuthLimiter {
    * operator reads and nothing enforces.
    */
   readonly policy: AuthRateLimitPolicy;
-  /** Rejects with `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
-  assertAllowed(key: string): Promise<void>;
-  recordFailure(key: string): Promise<void>;
+  /**
+   * Count one attempt against the key, atomically, BEFORE any KDF work. Rejects with
+   * `X_ACCOUNT_LOCKED` — counting nothing — while the key is inside a lockout; the attempt that
+   * fills the window is admitted and starts the lockout. A failed attempt needs no further call:
+   * the reservation IS the recorded failure.
+   */
+  reserve(key: string): Promise<AuthReservation>;
+  /**
+   * Give one reservation back — the attempt succeeded, or never reached a verdict. Removes that
+   * one entry and lifts a lockout the window no longer justifies. Never clears the key.
+   */
+  refund(reservation: AuthReservation): Promise<void>;
   /** A success clears the window: a legitimate user is not punished for a typo yesterday. */
   recordSuccess(key: string): Promise<void>;
   lockedUntil(key: string): Promise<Date | null>;
   reset(): Promise<void>;
   /**
    * Drop every expired row this limiter is keeping, and answer how many went. Optional because a
-   * limiter that bounds itself has nothing to sweep — `createAuthLimiter` evicts on write, so it
+   * limiter that bounds itself has nothing to sweep — `memoryAuthLimiter` evicts on write, so it
    * omits this and `purgeAuthLimits()` skips it. A limiter backed by a table declares it, and
    * that is what makes the framework's purge job able to reach one without knowing it is Postgres.
    */
   purgeExpired?(): Promise<number>;
 }
 
-/** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
+/** What `memoryAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
 export interface MemoryAuthLimiter extends AuthLimiter {
   readonly size: number;
 }
@@ -113,7 +134,7 @@ export const ipKey = (ip: string): string => `ip:${ip}`;
  * in `@ultimat3/http` and `@ultimat3/jobs`: three limiters that spell one tenant three ways cannot
  * be read together during an incident.
  */
-export const orgKey = (orgId: string): string => `org:${orgId}`;
+export const orgKey = (orgId: string): string => `${ORG_KEY_PREFIX}${orgId}`;
 
 /**
  * The policy the tenant limiter enforces — the same window and lockout, a wider allowance. One
@@ -153,7 +174,7 @@ const SWEEP_EVERY_MS = 60_000;
  * forgotten anyway go first: a locked account is the last key to go, so filling the table is not
  * a way to buy back attempts against one.
  */
-export function createAuthLimiter(
+export function memoryAuthLimiter(
   clock: Clock,
   policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
 ): MemoryAuthLimiter {
@@ -204,25 +225,38 @@ export function createAuthLimiter(
     get size() {
       return buckets.size;
     },
-    async assertAllowed(key) {
-      const bucket = buckets.get(key);
-      if (bucket === undefined) return;
-      const nowMs = clock.now().getTime();
-      if (bucket.lockedUntilMs <= nowMs) return;
-      throw accountLocked(key, Math.ceil((bucket.lockedUntilMs - nowMs) / 1000));
-    },
-    async recordFailure(key) {
+    // No `await` anywhere in the body: the check and the count are one synchronous step, which
+    // is the whole guarantee — concurrent callers are admitted one at a time, in order.
+    async reserve(key) {
       const nowMs = clock.now().getTime();
+      const existing = buckets.get(key);
+      if (existing !== undefined && existing.lockedUntilMs > nowMs) {
+        throw accountLocked(key, Math.ceil((existing.lockedUntilMs - nowMs) / 1000));
+      }
       const bucket = bucketFor(key);
       bucket.failures = bucket.failures.filter((at) => at > nowMs - policy.windowMs);
       bucket.failures.push(nowMs);
       if (bucket.failures.length >= policy.maxAttempts) {
         bucket.lockedUntilMs = nowMs + policy.lockoutMs;
       }
-      // The newest failure leaves the window last, so that is the earliest this entry is free —
+      // The newest attempt leaves the window last, so that is the earliest this entry is free —
       // unless a lockout outlives it. Recorded here because this is the only growth path.
       bucket.forgetAtMs = Math.max(bucket.lockedUntilMs, nowMs + policy.windowMs);
       if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
+      return { key, atMs: nowMs };
+    },
+    async refund(reservation) {
+      const bucket = buckets.get(reservation.key);
+      if (bucket === undefined) return;
+      const index = bucket.failures.indexOf(reservation.atMs);
+      if (index < 0) return;
+      bucket.failures.splice(index, 1);
+      const nowMs = clock.now().getTime();
+      const live = bucket.failures.filter((at) => at > nowMs - policy.windowMs).length;
+      // A lockout this reservation completed is not one the remaining failures justify.
+      if (live < policy.maxAttempts) bucket.lockedUntilMs = 0;
+      if (bucket.failures.length === 0 && bucket.lockedUntilMs === 0)
+        buckets.delete(reservation.key);
     },
     async recordSuccess(key) {
       buckets.delete(key);