@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': patch
+'@objectstack/plugin-auth': patch
+'@objectstack/runtime': patch
+---
+
+fix(auth): an MCP access token is recorded as used only once the MCP door admits the call, so a banned person's refused calls no longer show their AI assistant as used
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+`IAuthService` gains one optional member, `recordMcpAccessTokenUse(principal)`. Verifying a token is not admitting the call: the MCP door (`@objectstack/runtime`) refuses a banned subject after `verifyMcpAccessToken` answers, and a call whose authorization store cannot be read is a 503. Before this change `AuthManager.verifyMcpAccessToken` itself scheduled the coarse last-use stamp (`sys_oauth_consent.last_used_at`), so an administrator reading `GET /admin/authorized-clients?userId=` for a banned person saw the assistant as used in an hour when every call was refused.
+
+Now `verifyMcpAccessToken` records nothing. The door calls `recordMcpAccessTokenUse` once, after its ban read and after the request context resolves, with the very object the verifier returned; `AuthManager` stamps only a principal object its own verifier returned, once, so a hand-built principal or a copy records nothing. The member returns nothing and never throws. The stamp's bound is unchanged: at most one write per consent per hour in each process.
+
+A custom `IAuthService` needs nothing: the member is optional, and a door whose auth service lacks it admits the call exactly as before. A host that calls `AuthManager.verifyMcpAccessToken` itself and wants the call shown as used calls `recordMcpAccessTokenUse(principal)` with the verifier's result once it has admitted the call.
@@ -41,6 +41,9 @@ export interface IAuthService {
   /** Verify an OAuth 2.1 access token from the embedded AS (MCP surface); the optional `organizationId` is the organization the user's OAuth consent bound, absent for a token minted before consents bound an organization. Optional. */
   verifyMcpAccessToken?(token: string): Promise<{ userId: string; scopes: string[]; clientId?: string; organizationId?: string } | undefined>;
 
+  /** Record that the caller admitted a call made with a verified MCP access token: called once, after the caller's last refusal, with the object `verifyMcpAccessToken` returned; a principal the provider did not return records nothing. Never throws. Optional. */
+  recordMcpAccessTokenUse?(principal: { userId: string; scopes: string[]; clientId?: string; organizationId?: string }): void;
+
   /** The MCP resource identifier (RFC 8707 `resource` / token `aud`). Optional. */
   getMcpResourceUrl?(): string;
 
@@ -51,10 +54,11 @@ export interface IAuthService {
 
 The two required members are the core: it follows the Dependency Inversion Principle so that plugins depend on the contract rather than a concrete provider. Concrete implementations (better-auth, custom, LDAP, etc.) supply the actual logic, and `handleRequest` works directly with the standard `Request`/`Response` types.
 
-Everything after `verify` is optional, and each optional member describes a capability a provider may or may not have — a caller must probe before use. Two pairs are worth reading together:
+Everything after `verify` is optional, and each optional member describes a capability a provider may or may not have — a caller must probe before use. Three pairs are worth reading together:
 
 - **`api` and `getApi()`** are the same session handle by two routes. `api` is the legacy direct mount; `getApi()` is the lazy accessor, and it is the one to prefer — the shipped `plugin-auth` registers an `AuthManager`, which has **no `api` member at all**, so a caller that reads only `api` gets `undefined` on every current deployment. Read `api ?? await getApi?.()`.
 - **`getMcpResourceUrl()` and `getMcpResourceMetadataUrl()`** both describe the MCP OAuth surface; the second returns `null` (rather than being absent) when the OAuth track is off for the deployment.
+- **`verifyMcpAccessToken()` and `recordMcpAccessTokenUse()`** split verifying a token from admitting the call. The MCP door verifies first, then applies its own refusals (a banned subject, an authorization store it could not read), and only for a call it admits hands the verified principal back to `recordMcpAccessTokenUse()`. So a refused call is never recorded as a use of the grant (the coarse "last used" time the authorized-clients reads show). Admitting is the decision about who calls, not every later verdict: a refusal of what the admitted principal then asks for (a 403 `insufficient_scope` for a token that grants none of the MCP tool families, a tool or an action its scopes do not reach) is still a use, and is recorded.
 
 ---
 
 
@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Auth, BetterAuthOptions } from 'better-auth';
-import { decodeJwt, type JSONWebKeySet } from 'jose';
+import type { JSONWebKeySet } from 'jose';
 import type { SCIMIdentityState, SCIMTransactionContext } from '@better-auth/scim';
 // better-auth value imports (betterAuth + plugins) are deferred via dynamic
 // import() in getOrCreateAuth() / buildPluginList() so that disabled plugins
@@ -225,7 +225,7 @@ import {
   type McpAccessTokenHost,
 } from './auth-manager-mcp-access-token.js';
 // [#30918] The coarse last-use stamp a verified MCP call writes on its consent.
-import { McpClientLastUseStamper, mcpClientLastUseStoreFor } from './mcp-client-last-use.js';
+import { McpClientLastUseStamper, mcpClientLastUseStoreFor, issuedAtOf } from './mcp-client-last-use.js';
 import { runAfterResponse } from './run-after-response.js';
 // [objectstack-ai/cloud#3606, ruling A] `/oauth2/revoke` for an MCP access
 // token: the answer `handleRequest` gives after the provider's, through
@@ -4632,13 +4632,12 @@ export class AuthManager {
    * organization (`vetOrganizationClaim`, `@objectstack/core`), as the
    * `IAuthService` contract states.
    *
-   * [#30918] A token that verifies also schedules, AFTER the verdict and off
-   * the request's path, the coarse last-use stamp on the consent it was minted
-   * under (`mcp-client-last-use.ts`): at most one write per consent per hour
-   * in each process, from this verified token and the server's clock, and
-   * only on the consent that admitted it (the consent read above, by the same
-   * rule). The stamp reads and writes nothing the verdict depends on, and its
-   * failure is never this method's failure.
+   * [#30918 · #31211] Verifying is not admitting: this method records NO use.
+   * The door that resolves the principal can still refuse the call (a banned
+   * subject, an authorization store it could not read), and a refused call is
+   * not a use. It remembers the principal object it returns, and the door
+   * hands that object back to {@link recordMcpAccessTokenUse} once it has
+   * admitted the call.
    */
   verifyMcpAccessToken(
     token: string,
@@ -4652,18 +4651,48 @@ export class AuthManager {
       rereadKeyringForUnknownKey: (...a) => this.rereadKeyringForUnknownKey(...a),
       getAuthContext: (...a) => this.getAuthContext(...a),
     };
-    // [#30918] A token that verified is a verified MCP call: its consent's
-    // coarse last-use stamp is settled after the response, never awaited here,
-    // and from the verified token only (`mcp-client-last-use.ts`). The
-    // verifier has just admitted the token by its consent (#30879,
-    // `mcpConsentAdmits`), so a revoked consent refuses the call and stamps
-    // nothing; the stamp picks its consent by the same rule.
+    // [#31211] Remember the object this verifier answered, with the `iat` of
+    // the token it verified, so only that object can later be recorded as
+    // used. The token has just verified, so its payload is the one the
+    // signature covers: its `iat` is what the verifier admitted the consent
+    // against (#30879, `mcpConsentAdmits`).
     return verifyMcpAccessToken.call(host, token).then((principal) => {
-      if (principal) this.scheduleMcpClientLastUse(principal, token);
+      if (principal) this.verifiedMcpPrincipals.set(principal, { issuedAt: issuedAtOf(token) });
       return principal;
     });
   }
 
+  /**
+   * [#31211] The principal objects {@link verifyMcpAccessToken} answered and
+   * nobody has recorded yet, each with its token's `iat`. Weak, so a principal
+   * whose call was refused (never recorded) is dropped with the request.
+   */
+  private readonly verifiedMcpPrincipals = new WeakMap<object, { issuedAt?: number }>();
+
+  /**
+   * [#31211] `IAuthService.recordMcpAccessTokenUse`: the MCP door admitted a
+   * call made with a token {@link verifyMcpAccessToken} verified, so the
+   * consent that token was minted under gets its coarse last-use stamp
+   * (`mcp-client-last-use.ts`, #30918), after the response and never awaited
+   * here: at most one write per consent per hour in each process, from the
+   * verified token and the server's clock, and only on the consent that
+   * admitted it.
+   *
+   * Only an object this manager's verifier returned is recorded, and only
+   * once; a hand-built principal, a copy, or the same object again records
+   * nothing. Never throws: the stamp's failure is never the call's failure.
+   */
+  recordMcpAccessTokenUse(principal: { userId: string; scopes: string[]; clientId?: string; organizationId?: string }): void {
+    try {
+      const verified = principal !== null && typeof principal === 'object' ? this.verifiedMcpPrincipals.get(principal) : undefined;
+      if (!verified) return;
+      this.verifiedMcpPrincipals.delete(principal);
+      this.scheduleMcpClientLastUse(principal, verified.issuedAt);
+    } catch {
+      // Bookkeeping only: an admitted call is never refused for it.
+    }
+  }
+
   /** [#30918] The per-manager stamper, built on first use. */
   private mcpClientLastUse?: McpClientLastUseStamper;
 
@@ -4679,18 +4708,9 @@ export class AuthManager {
    */
   private scheduleMcpClientLastUse(
     principal: { userId: string; clientId?: string; organizationId?: string },
-    token: string,
+    issuedAt: number | undefined,
   ): void {
     if (!principal.clientId) return;
-    // The token has just verified, so its payload is the one the signature
-    // covers: its `iat` is what the verifier admitted the consent against.
-    let issuedAt: number | undefined;
-    try {
-      const iat = decodeJwt(token).iat;
-      issuedAt = typeof iat === 'number' ? iat : undefined;
-    } catch {
-      issuedAt = undefined;
-    }
     const stamper = (this.mcpClientLastUse ??= new McpClientLastUseStamper(
       mcpClientLastUseStoreFor(() => this.getDataEngine()),
       {