@ultimat3/auth 23.0.0 → 24.0.0

package/src/oauth-registry.ts

@@ -5,9 +5,24 @@
 // account linking with it. The three built-ins register through the same call an app uses, so the
 // opening does not create a second path.
 
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
 import type { OAuthProvider } from './oauth';
 import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
-import { oauthProviderDuplicate, oauthProviderUnknown } from './oauth-errors';
+import { oauthProviderUnknown } from './oauth-errors';
+
+/**
+ * Two `registerOAuthProvider` calls claiming one id. A silent replacement would let whichever
+ * module imported second decide where every login for that id goes — including which `issuers`
+ * an id token may claim — so the second registration refuses at boot instead.
+ */
+export const oauthProviderDuplicate = (provider: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_DUPLICATE',
+    cause: `an oauth provider is already registered as ${renderCauseValue(provider)}, so the second registration would silently replace the first`,
+    fix: `give one of them a different id, or delete the duplicate registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) call`,
+    meta: { provider },
+  });
 
 const registry = new Map<string, OAuthProvider>();
 

package/src/oauth-route.ts

@@ -10,16 +10,20 @@
 
 import {
   type Clock,
+  EnvMissingError,
   isUltimateError,
   logger,
+  renderCauseValue,
+  renderFixShellArg,
   renderThrowable,
   type UltimateError,
 } from '@ultimat3/core';
 import type { Auth, LoginResult } from './auth';
+import { AuthError } from './errors';
 import { beginOAuth, type OAuthProviderId } from './oauth';
 import { BUILTIN_OAUTH_PROVIDER_IDS } from './oauth-builtins';
 import { clearHandshakeCookie, handshakeCookie, readHandshakeCookie } from './oauth-cookie';
-import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './oauth-errors';
+import { oauthExchangeFailed, oauthProviderUnknown, restartAt } from './oauth-errors';
 import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
 import { oauthCredentials } from './oauth-exchange';
 import { completeOAuthLogin, type ResolveOAuthGrants } from './oauth-login';
@@ -30,6 +34,30 @@ import {
 } from './oauth-paths';
 import { hasOAuthProvider } from './oauth-registry';
 
+/**
+ * The provider came back with `error=` and no code — almost always the user pressing Cancel.
+ * A separate code from `X_OAUTH_EXCHANGE_FAILED` on purpose: nothing was exchanged, nothing is
+ * misconfigured, and folding the single commonest non-success outcome of a login into the code
+ * that means "the client secret is wrong" makes both unreadable in a log and pages the wrong person.
+ */
+export const oauthDenied = (
+  provider: string,
+  reason: string,
+  description: string | null,
+): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_DENIED',
+    // `reason` and `description` are query parameters off the callback URL — whatever the browser
+    // was redirected with, newlines and quotes included. `renderCauseValue` renders them as JSON
+    // string literals, so a forged `error_description` cannot forge a second log line or break the
+    // sentence around it. Both are already `string` by type: this is escaping, not throw-safety.
+    cause: `${provider} declined the authorization: ${renderCauseValue(reason)}${
+      description === null ? '' : ` (${renderCauseValue(description)})`
+    }`,
+    fix: `${restartAt(provider)} and approve the ${provider} consent screen`,
+    meta: { provider, reason },
+  });
+
 /**
  * What a router needs to mount one of these. Structural, like `RequestLike` in `session.ts`:
  * `@ultimat3/http` binds to this shape, this package never binds to `@ultimat3/http`.
@@ -52,9 +80,9 @@ export interface OAuthLoginRoutes {
 
 export interface OAuthLoginOptions {
   /**
-   * The origin the provider redirects back to. Defaults to `APP_URL`, then to the request's own
-   * origin — which is the `Host` header, so it is preferred last: a forged one only ever produces
-   * a `redirect_uri` the provider refuses, but naming the canonical origin costs nothing.
+   * The origin the provider redirects back to. Defaults to `APP_URL`; with neither, the start leg
+   * refuses (`X_ENV_MISSING`). Never the request's own origin: that is the `Host` header, which
+   * the caller writes.
    */
   readonly baseUrl?: string | undefined;
   /** Defaults to the two env vars in the provider table, read per request, never at import. */
@@ -125,34 +153,44 @@ export function oauthRouteStatus(code: string): number {
   return Object.hasOwn(OAUTH_ROUTE_STATUS, code) ? (OAUTH_ROUTE_STATUS[code] ?? 502) : 502;
 }
 
+/** The one sentence every refusal carries outward. The event name is where the rest went. */
+const PUBLIC_CAUSE =
+  'the sign-in was refused; its cause and its fix are in this server\u2019s log under auth.oauth.refused';
+
+/** A code this framework would have minted — the only kind spliced into a command. */
+const FRAMEWORK_CODE = /^X_[A-Z0-9_]+$/;
+
 /**
- * What an anonymous caller is allowed to read. `UltimateError.toJSON()` carries `meta` and `stack`
- * — a developer's fields — and BOTH legs of this flow are public by definition, so serialising it
- * whole published a stack trace and whatever a factory put in `meta` to whoever typed the URL. Four
- * fields, the same four on every code: no per-code judgement about which `meta` key is safe today.
+ * What an anonymous caller is allowed to read: the code, its registered title and docs link, and
+ * one fixed sentence. Both legs are public by definition, and an authored `cause`/`fix` is written
+ * for the developer — it names env vars, endpoints and what a provider answered — so neither is
+ * served, on any code: no per-code judgement about which sentence is safe today.
  */
 const publicBody = (coded: UltimateError): Record<string, string> => ({
   code: coded.code,
   title: coded.title,
-  cause: coded.cause,
-  fix: coded.fix,
+  cause: PUBLIC_CAUSE,
+  fix: FRAMEWORK_CODE.test(coded.code)
+    ? `x errors explain ${renderFixShellArg(coded.code, '<CODE>')} --json`
+    : 'x errors list --json',
   docs: coded.docs,
 });
 
 /**
- * Failure is JSON, never a redirect to a login page carrying `?error=`. A callback is the one
- * request in the flow whose failure the developer has to read, and a redirect that drops the code
- * and the fix line is exactly how three dead `fix:` strings survived a whole release. An app that
- * wants a rendered page wraps these two descriptors; the framework ships the debuggable answer.
+ * Failure is JSON, never a redirect to a login page carrying `?error=`: the status and the code
+ * are the answer a client branches on. The developer's half — the cause and the fix line — is
+ * logged as `auth.oauth.refused`, where only an operator reads it. An app that wants a rendered
+ * page wraps these two descriptors.
  */
 function problem(error: unknown, extraCookies: readonly string[]): Response {
   const coded = isUltimateError(error) ? error : uncoded(error);
+  const status = oauthRouteStatus(coded.code);
+  const fields = { code: coded.code, status, cause: coded.cause, fix: coded.fix };
+  if (status >= 500) logger.error('auth.oauth.refused', fields);
+  else logger.info('auth.oauth.refused', fields);
   const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' });
   for (const cookie of extraCookies) headers.append('set-cookie', cookie);
-  return new Response(JSON.stringify(publicBody(coded)), {
-    status: oauthRouteStatus(coded.code),
-    headers,
-  });
+  return new Response(JSON.stringify(publicBody(coded)), { status, headers });
 }
 
 /**
@@ -244,10 +282,22 @@ function credentialsFor(
   }
 }
 
-function originFor(request: Request, options: OAuthLoginOptions): string {
+/**
+ * The declared origin, or a refusal. The request's own origin is the `Host` header, so a
+ * `redirect_uri` built from it is one the caller chose.
+ */
+function declaredOrigin(options: OAuthLoginOptions): string {
   const env = options.env ?? Bun.env;
-  const declared = options.baseUrl ?? env['APP_URL']?.trim() ?? '';
-  return declared === '' ? new URL(request.url).origin : declared.replace(/\/+$/, '');
+  const declared = (options.baseUrl ?? env['APP_URL'] ?? '').trim();
+  if (declared === '') {
+    throw new EnvMissingError({
+      cause:
+        'APP_URL is not set and oauthLogin() was given no baseUrl, so there is no declared origin to build the provider redirect_uri from',
+      fix: 'export APP_URL=http://localhost:3000   # the origin this app is served from',
+      meta: { key: 'APP_URL' },
+    });
+  }
+  return declared.replace(/\/+$/, '');
 }
 
 /** The handshake's own options, assembled once so both legs seal and open it identically. */
@@ -265,12 +315,15 @@ async function startHandler(
   request: Request,
 ): Promise<Response> {
   try {
+    // Before the provider is looked at: asked after, a missing origin answered 500 for a provider
+    // this app enabled and 404 for one it did not.
+    const origin = declaredOrigin(options);
     const provider = assertEnabled(auth, providerSegment(request, 'start'));
     const credentials = credentialsFor(provider, options);
     const handshake = beginOAuth({
       provider,
       clientId: credentials.clientId,
-      redirectUri: `${originFor(request, options)}${oauthCallbackPath(provider)}`,
+      redirectUri: `${origin}${oauthCallbackPath(provider)}`,
       scopes: options.scopes,
     });
     return new Response(null, {

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,9 +1,6 @@
-// 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';
@@ -28,6 +25,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 +43,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,23 +56,30 @@ 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 };
+  const issued =
+    own !== undefined && auth.sessions.policy.rotateOnPrivilegeChange
+      ? await rotateSession(auth.sessions, own)
+      : undefined;
+  let sessionsRevoked = 0;
+  if (credentialChanged) {
+    const keep = issued?.session.id ?? own?.id;
+    sessionsRevoked =
+      keep === undefined
+        ? await auth.adapter.deleteSessionsForUser(userId)
+        : await auth.adapter.deleteOtherSessions(userId, keep);
   }
-
-  const issued = await rotateSession(auth.sessions, session);
+  if (issued === undefined) return { user, changed, sessionsRevoked };
   return {
     user,
     changed,
+    sessionsRevoked,
     session: issued,
     cookie: sessionCookie(issued.token, auth.sessions.policy),
   };

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> {