@agent-native/core 0.201.0-nightly-20261005153421 → 0.201.0

package/dist/mcp/oauth-route.js

@@ -3,9 +3,12 @@ import { getHeader, getMethod, getQuery, setResponseStatus } from "h3";
 import { getOrgDomain } from "../org/context.js";
 import { getConfiguredLoginHtml, getSession } from "../server/auth.js";
 import { getAuthSecret } from "../server/better-auth-instance.js";
+import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../server/credential-membership-unavailable.js";
+import { getOrigin } from "../server/google-oauth.js";
 import { readBody } from "../server/h3-helpers.js";
+import { McpCredentialIssuanceError, withMcpCredentialIssuance, } from "./credential-issuance.js";
 import { applicationTypeForRedirectUris, isAllowedOAuthRedirectUri, isUrlBasedOAuthClientId, matchesRegisteredRedirectUri, resolveOAuthClientMetadataDocument, } from "./oauth-client-metadata.js";
-import { createOAuthCode, createOAuthRefreshToken, consumeOAuthCode, generateOpaqueToken, getOAuthClient, getOAuthCode, getOAuthRefreshToken, registerOAuthClient, touchOAuthRefreshToken, } from "./oauth-store.js";
+import { createOAuthCode, createOAuthRefreshToken, consumeOAuthCode, ensureOAuthTables, generateOpaqueToken, getOAuthClient, getOAuthCode, getOAuthRefreshToken, registerOAuthClient, revokeOAuthRefreshToken, touchOAuthRefreshToken, } from "./oauth-store.js";
 import { MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS, MCP_OAUTH_SCOPES, normalizeOAuthScope, signMcpOAuthAccessToken, } from "./oauth-token.js";
 import { resolveMcpOrgChoices } from "./org-choice.js";
 import { MCP_DIRECTORY_ROUTE_PREFIX, MCP_LEGACY_ROUTE_PREFIX, MCP_PUBLIC_ROUTE_PREFIX, MCP_ROUTE_PREFIXES, } from "./route-paths.js";
@@ -700,17 +703,37 @@ async function handleAuthorize(event, options) {
     const orgDomain = selectedOrganization
         ? await resolveOrgDomain(selectedOrganization.id)
         : undefined;
-    const code = await createOAuthCode({
-        clientId,
-        redirectUri,
-        codeChallenge: params.code_challenge,
-        codeChallengeMethod: "S256",
-        ownerEmail: session.email,
-        orgId: selectedOrganization?.id ?? null,
-        orgDomain: orgDomain ?? null,
-        scope,
-        resource,
-    });
+    let code;
+    try {
+        await ensureOAuthTables();
+        code = await withMcpCredentialIssuance({
+            email: session.email,
+            orgId: selectedOrganization?.id ?? null,
+            requestOrigin: getOrigin(event),
+        }, (tx) => createOAuthCode({
+            clientId,
+            redirectUri,
+            codeChallenge: params.code_challenge,
+            codeChallengeMethod: "S256",
+            ownerEmail: session.email,
+            orgId: selectedOrganization?.id ?? null,
+            orgDomain: orgDomain ?? null,
+            scope,
+            resource,
+        }, tx));
+    }
+    catch (error) {
+        if (error instanceof McpCredentialIssuanceError &&
+            error.reason === "not-member") {
+            return redirectWithOAuthError({
+                redirectUri,
+                issuer,
+                state,
+                error: "access_denied",
+            });
+        }
+        return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+    }
     let isDeepLinkRedirect = false;
     try {
         const protocol = new URL(redirectUri).protocol;
@@ -741,7 +764,7 @@ async function handleAuthorize(event, options) {
         code: code.code,
     });
 }
-async function issueTokenSet(params) {
+async function issueTokenSet(params, tx) {
     const refreshToken = generateOpaqueToken();
     await createOAuthRefreshToken({
         refreshToken,
@@ -751,7 +774,7 @@ async function issueTokenSet(params) {
         orgDomain: params.orgDomain ?? null,
         scope: params.scope,
         resource: params.resource,
-    });
+    }, tx);
     const accessToken = await signMcpOAuthAccessToken(params);
     return {
         access_token: accessToken,
@@ -761,6 +784,13 @@ async function issueTokenSet(params) {
         scope: params.scope,
     };
 }
+const NOT_A_MEMBER_DESCRIPTION = "The user is no longer a member of the organization this grant was issued for";
+/** Retryable: the client must keep its refresh token, not start over. */
+function grantUnavailableError(description) {
+    const response = oauthError("temporarily_unavailable", description, 503);
+    response.headers.set("Retry-After", "5");
+    return response;
+}
 async function handleAuthorizationCodeGrant(event, body) {
     const code = body.code;
     const clientId = body.client_id;
@@ -769,7 +799,14 @@ async function handleAuthorizationCodeGrant(event, body) {
     if (!code || !clientId || !redirectUri || !isValidCodeVerifier(verifier)) {
         return oauthError("invalid_request", "Missing authorization-code fields");
     }
-    const row = await getOAuthCode(code);
+    let row;
+    try {
+        await ensureOAuthTables();
+        row = await getOAuthCode(code);
+    }
+    catch {
+        return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+    }
     if (!row)
         return oauthError("invalid_grant", "Invalid or expired code");
     if (row.clientId !== clientId || row.redirectUri !== redirectUri) {
@@ -779,21 +816,42 @@ async function handleAuthorizationCodeGrant(event, body) {
     if (!safeEqual(expectedChallenge, row.codeChallenge)) {
         return oauthError("invalid_grant", "PKCE verification failed");
     }
-    const consumed = await consumeOAuthCode(code);
-    if (!consumed)
-        return oauthError("invalid_grant", "Invalid or expired code");
     const issuer = getMcpOAuthIssuer(event);
     if (!issuer)
         return oauthError("server_error", "Unable to derive issuer", 500);
-    return json(await issueTokenSet({
-        ownerEmail: row.ownerEmail,
-        orgId: row.orgId,
-        orgDomain: row.orgDomain,
-        clientId,
-        scope: row.scope,
-        resource: row.resource,
-        issuer,
-    }));
+    try {
+        return await withMcpCredentialIssuance({
+            email: row.ownerEmail,
+            orgId: row.orgId,
+            requestOrigin: getOrigin(event),
+        }, async (tx) => {
+            const consumed = await consumeOAuthCode(code, row.ownerEmail, tx);
+            if (!consumed)
+                return oauthError("invalid_grant", "Invalid or expired code");
+            return json(await issueTokenSet({
+                ownerEmail: consumed.ownerEmail,
+                orgId: consumed.orgId,
+                orgDomain: consumed.orgDomain,
+                clientId,
+                scope: consumed.scope,
+                resource: consumed.resource,
+                issuer,
+            }, tx));
+        });
+    }
+    catch (error) {
+        if (error instanceof McpCredentialIssuanceError &&
+            error.reason === "not-member") {
+            try {
+                await consumeOAuthCode(code, row.ownerEmail);
+            }
+            catch {
+                return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+            }
+            return oauthError("invalid_grant", NOT_A_MEMBER_DESCRIPTION);
+        }
+        return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+    }
 }
 async function handleRefreshTokenGrant(event, body) {
     const refreshToken = body.refresh_token;
@@ -804,32 +862,62 @@ async function handleRefreshTokenGrant(event, body) {
     if (!clientId) {
         return oauthError("invalid_request", "client_id is required");
     }
-    const existing = await getOAuthRefreshToken(refreshToken);
+    let existing;
+    try {
+        await ensureOAuthTables();
+        existing = await getOAuthRefreshToken(refreshToken);
+    }
+    catch {
+        return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+    }
     if (!existing)
         return oauthError("invalid_grant", "Invalid refresh token");
     if (existing.clientId !== clientId) {
         return oauthError("invalid_grant", "Refresh token belongs to another client");
     }
-    await touchOAuthRefreshToken(refreshToken).catch(() => undefined);
     const issuer = getMcpOAuthIssuer(event);
     if (!issuer)
         return oauthError("server_error", "Unable to derive issuer", 500);
-    const accessToken = await signMcpOAuthAccessToken({
-        ownerEmail: existing.ownerEmail,
-        orgId: existing.orgId,
-        orgDomain: existing.orgDomain,
-        clientId: existing.clientId,
-        scope: existing.scope,
-        resource: existing.resource,
-        issuer,
-    });
-    return json({
-        access_token: accessToken,
-        token_type: "Bearer",
-        expires_in: MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS,
-        refresh_token: refreshToken,
-        scope: existing.scope,
-    });
+    try {
+        return await withMcpCredentialIssuance({
+            email: existing.ownerEmail,
+            orgId: existing.orgId,
+            requestOrigin: getOrigin(event),
+        }, async (tx) => {
+            const renewal = await touchOAuthRefreshToken(refreshToken, existing.ownerEmail, tx);
+            if (renewal !== "renewed")
+                return oauthError("invalid_grant", "Invalid refresh token");
+            const accessToken = await signMcpOAuthAccessToken({
+                ownerEmail: existing.ownerEmail,
+                orgId: existing.orgId,
+                orgDomain: existing.orgDomain,
+                clientId: existing.clientId,
+                scope: existing.scope,
+                resource: existing.resource,
+                issuer,
+            });
+            return json({
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS,
+                refresh_token: refreshToken,
+                scope: existing.scope,
+            });
+        });
+    }
+    catch (error) {
+        if (error instanceof McpCredentialIssuanceError &&
+            error.reason === "not-member") {
+            try {
+                await revokeOAuthRefreshToken(refreshToken, existing.ownerEmail);
+            }
+            catch {
+                return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+            }
+            return oauthError("invalid_grant", NOT_A_MEMBER_DESCRIPTION);
+        }
+        return grantUnavailableError(CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE);
+    }
 }
 async function handleToken(event) {
     if (getMethod(event) !== "POST") {

package/dist/mcp/oauth-store.d.ts

@@ -5,6 +5,7 @@
  * short-lived authorization codes, and hashed refresh tokens. Access tokens
  * are signed JWTs and are never persisted.
  */
+import { type DbExec } from "../db/client.js";
 export declare const MCP_OAUTH_CODE_TTL_MS: number;
 export declare const MCP_OAUTH_ACCESS_TOKEN_TTL: string;
 export declare const MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS: number;
@@ -12,6 +13,7 @@ export declare const MCP_OAUTH_REFRESH_TOKEN_TTL_MS: number;
 export declare const MCP_OAUTH_REGISTER_MAX = 60;
 export declare const MCP_OAUTH_REGISTER_WINDOW_MS = 60000;
 export declare function ensureTable(): Promise<void>;
+export declare const ensureOAuthTables: typeof ensureTable;
 export interface OAuthClientRow {
     clientId: string;
     clientName: string | null;
@@ -29,6 +31,7 @@ export interface OAuthCodeRow {
     codeChallenge: string;
     codeChallengeMethod: string;
     ownerEmail: string;
+    issuedForEmail: string | null;
     orgId: string | null;
     orgDomain: string | null;
     scope: string;
@@ -42,6 +45,7 @@ export interface OAuthRefreshTokenRow {
     tokenHash: string;
     clientId: string;
     ownerEmail: string;
+    issuedForEmail: string | null;
     orgId: string | null;
     orgDomain: string | null;
     scope: string;
@@ -73,9 +77,9 @@ export declare function createOAuthCode(params: {
     orgDomain?: string | null;
     scope: string;
     resource: string;
-}): Promise<OAuthCodeRow>;
+}, db?: DbExec): Promise<OAuthCodeRow>;
 export declare function getOAuthCode(code: string): Promise<OAuthCodeRow | null>;
-export declare function consumeOAuthCode(code: string): Promise<OAuthCodeRow | null>;
+export declare function consumeOAuthCode(code: string, expectedOwnerEmail?: string, db?: DbExec): Promise<OAuthCodeRow | null>;
 export declare function createOAuthRefreshToken(params: {
     refreshToken: string;
     clientId: string;
@@ -84,15 +88,21 @@ export declare function createOAuthRefreshToken(params: {
     orgDomain?: string | null;
     scope: string;
     resource: string;
-}): Promise<OAuthRefreshTokenRow>;
+}, db?: DbExec): Promise<OAuthRefreshTokenRow>;
 export declare function rotateOAuthRefreshToken(params: {
     oldRefreshToken: string;
     newRefreshToken: string;
-}): Promise<OAuthRefreshTokenRow | null>;
+}, db?: DbExec): Promise<OAuthRefreshTokenRow | null>;
 export declare function getOAuthRefreshToken(refreshToken: string): Promise<OAuthRefreshTokenRow | null>;
 /**
  * Slide the refresh-token's expiry window on each successful use so that active
  * users never hit the TTL. Records `last_used_at` and extends `expires_at` to
  * `now + MCP_OAUTH_REFRESH_TOKEN_TTL_MS`.
+ * The caller supplies the owner whose membership it verified.
  */
-export declare function touchOAuthRefreshToken(refreshToken: string): Promise<void>;
+export declare function touchOAuthRefreshToken(refreshToken: string, expectedOwnerEmail: string, db?: DbExec): Promise<"renewed" | "invalid">;
+/**
+ * Revoke one refresh token so it can never mint another access token.
+ * Idempotent: an already-revoked token keeps its first timestamp.
+ */
+export declare function revokeOAuthRefreshToken(refreshToken: string, expectedOwnerEmail?: string): Promise<void>;

package/dist/mcp/oauth-store.js

@@ -75,6 +75,7 @@ export async function ensureTable() {
           code_challenge TEXT NOT NULL,
           code_challenge_method TEXT NOT NULL,
           owner_email TEXT NOT NULL,
+          issued_for_email TEXT,
           org_id TEXT,
           org_domain TEXT,
           scope TEXT NOT NULL,
@@ -90,6 +91,7 @@ export async function ensureTable() {
           token_hash TEXT UNIQUE NOT NULL,
           client_id TEXT NOT NULL,
           owner_email TEXT NOT NULL,
+          issued_for_email TEXT,
           org_id TEXT,
           org_domain TEXT,
           scope TEXT NOT NULL,
@@ -104,7 +106,10 @@ export async function ensureTable() {
             await ensureTableExists("mcp_oauth_clients", createClientsSql);
             await ensureColumnExists("mcp_oauth_clients", "application_type", `ALTER TABLE mcp_oauth_clients ADD COLUMN IF NOT EXISTS application_type TEXT`);
             await ensureTableExists("mcp_oauth_codes", createCodesSql);
+            // Legacy owners may already have been transferred; leave their bindings unset.
+            await ensureColumnExists("mcp_oauth_codes", "issued_for_email", `ALTER TABLE mcp_oauth_codes ADD COLUMN IF NOT EXISTS issued_for_email TEXT`);
             await ensureTableExists("mcp_oauth_refresh_tokens", createRefreshTokensSql);
+            await ensureColumnExists("mcp_oauth_refresh_tokens", "issued_for_email", `ALTER TABLE mcp_oauth_refresh_tokens ADD COLUMN IF NOT EXISTS issued_for_email TEXT`);
         })().catch((err) => {
             _initPromise = undefined;
             throw err;
@@ -112,6 +117,7 @@ export async function ensureTable() {
     }
     return _initPromise;
 }
+export const ensureOAuthTables = ensureTable;
 export function generateOpaqueToken() {
     return randomBytes(32).toString("base64url");
 }
@@ -164,6 +170,7 @@ function mapCodeRow(row) {
         codeChallenge: row.code_challenge ?? row.codeChallenge,
         codeChallengeMethod: row.code_challenge_method ?? row.codeChallengeMethod,
         ownerEmail: row.owner_email ?? row.ownerEmail,
+        issuedForEmail: row.issued_for_email ?? row.issuedForEmail ?? null,
         orgId: row.org_id ?? row.orgId ?? null,
         orgDomain: row.org_domain ?? row.orgDomain ?? null,
         scope: row.scope,
@@ -179,6 +186,7 @@ function mapRefreshRow(row) {
         tokenHash: row.token_hash ?? row.tokenHash,
         clientId: row.client_id ?? row.clientId,
         ownerEmail: row.owner_email ?? row.ownerEmail,
+        issuedForEmail: row.issued_for_email ?? row.issuedForEmail ?? null,
         orgId: row.org_id ?? row.orgId ?? null,
         orgDomain: row.org_domain ?? row.orgDomain ?? null,
         scope: row.scope,
@@ -190,6 +198,11 @@ function mapRefreshRow(row) {
         replacedByHash: row.replaced_by_hash ?? row.replacedByHash ?? null,
     };
 }
+function hasIssuanceOwner(row) {
+    return (typeof row.issuedForEmail === "string" &&
+        row.issuedForEmail.trim().length > 0 &&
+        row.issuedForEmail === row.ownerEmail);
+}
 export async function registerOAuthClient(params) {
     await ensureTable();
     const client = getDbExec();
@@ -259,14 +272,15 @@ export async function getOAuthClient(clientId) {
         throw err;
     }
 }
-export async function createOAuthCode(params) {
-    await ensureTable();
-    const client = getDbExec();
+export async function createOAuthCode(params, db) {
+    if (!db)
+        await ensureTable();
+    const client = db ?? getDbExec();
     const code = generateOpaqueToken();
     const now = Date.now();
     const expiresAt = now + MCP_OAUTH_CODE_TTL_MS;
-    await client.execute({
-        sql: `INSERT INTO mcp_oauth_codes (code, client_id, redirect_uri, code_challenge, code_challenge_method, owner_email, org_id, org_domain, scope, resource, created_at, expires_at, consumed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    const result = await client.execute({
+        sql: `INSERT INTO mcp_oauth_codes (code, client_id, redirect_uri, code_challenge, code_challenge_method, owner_email, issued_for_email, org_id, org_domain, scope, resource, created_at, expires_at, consumed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         args: [
             code,
             params.clientId,
@@ -274,6 +288,7 @@ export async function createOAuthCode(params) {
             params.codeChallenge,
             params.codeChallengeMethod,
             params.ownerEmail,
+            params.ownerEmail,
             params.orgId ?? null,
             params.orgDomain ?? null,
             params.scope,
@@ -283,6 +298,9 @@ export async function createOAuthCode(params) {
             null,
         ],
     });
+    if (result.rowsAffected !== 1) {
+        throw new Error("Authorization-code creation returned an invalid row count");
+    }
     return {
         code,
         clientId: params.clientId,
@@ -290,6 +308,7 @@ export async function createOAuthCode(params) {
         codeChallenge: params.codeChallenge,
         codeChallengeMethod: params.codeChallengeMethod,
         ownerEmail: params.ownerEmail,
+        issuedForEmail: params.ownerEmail,
         orgId: params.orgId ?? null,
         orgDomain: params.orgDomain ?? null,
         scope: params.scope,
@@ -309,14 +328,17 @@ export async function getOAuthCode(code) {
     if (rows.length === 0)
         return null;
     const row = mapCodeRow(rows[0]);
-    if (row.consumedAt != null || (row.expiresAt ?? 0) < Date.now()) {
+    if (!hasIssuanceOwner(row) ||
+        row.consumedAt != null ||
+        (row.expiresAt ?? 0) < Date.now()) {
         return null;
     }
     return row;
 }
-export async function consumeOAuthCode(code) {
-    await ensureTable();
-    const client = getDbExec();
+export async function consumeOAuthCode(code, expectedOwnerEmail, db) {
+    if (!db)
+        await ensureTable();
+    const client = db ?? getDbExec();
     const { rows } = await client.execute({
         sql: `SELECT * FROM mcp_oauth_codes WHERE code = ?`,
         args: [code],
@@ -324,24 +346,35 @@ export async function consumeOAuthCode(code) {
     if (rows.length === 0)
         return null;
     const row = mapCodeRow(rows[0]);
-    if (row.consumedAt != null || (row.expiresAt ?? 0) < Date.now()) {
+    const now = Date.now();
+    if (!hasIssuanceOwner(row) ||
+        (expectedOwnerEmail !== undefined &&
+            row.ownerEmail !== expectedOwnerEmail) ||
+        row.consumedAt != null ||
+        (row.expiresAt ?? 0) < now) {
         return null;
     }
     const result = await client.execute({
-        sql: `UPDATE mcp_oauth_codes SET consumed_at = ? WHERE code = ? AND consumed_at IS NULL`,
-        args: [Date.now(), code],
+        sql: `UPDATE mcp_oauth_codes SET consumed_at = ? WHERE code = ? AND consumed_at IS NULL AND expires_at >= ? AND owner_email = ? AND issued_for_email = ?`,
+        args: [now, code, now, row.ownerEmail, row.issuedForEmail],
     });
-    return result.rowsAffected > 0 ? row : null;
+    if (result.rowsAffected === 0)
+        return null;
+    if (result.rowsAffected === 1)
+        return row;
+    throw new Error("Authorization-code consumption returned an invalid row count");
 }
-export async function createOAuthRefreshToken(params) {
-    await ensureTable();
-    const client = getDbExec();
+export async function createOAuthRefreshToken(params, db) {
+    if (!db)
+        await ensureTable();
+    const client = db ?? getDbExec();
     const now = Date.now();
     const row = {
         id: randomUUID(),
         tokenHash: hashOAuthToken(params.refreshToken),
         clientId: params.clientId,
         ownerEmail: params.ownerEmail,
+        issuedForEmail: params.ownerEmail,
         orgId: params.orgId ?? null,
         orgDomain: params.orgDomain ?? null,
         scope: params.scope,
@@ -352,13 +385,14 @@ export async function createOAuthRefreshToken(params) {
         revokedAt: null,
         replacedByHash: null,
     };
-    await client.execute({
-        sql: `INSERT INTO mcp_oauth_refresh_tokens (id, token_hash, client_id, owner_email, org_id, org_domain, scope, resource, created_at, expires_at, last_used_at, revoked_at, replaced_by_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    const result = await client.execute({
+        sql: `INSERT INTO mcp_oauth_refresh_tokens (id, token_hash, client_id, owner_email, issued_for_email, org_id, org_domain, scope, resource, created_at, expires_at, last_used_at, revoked_at, replaced_by_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         args: [
             row.id,
             row.tokenHash,
             row.clientId,
             row.ownerEmail,
+            row.issuedForEmail,
             row.orgId,
             row.orgDomain,
             row.scope,
@@ -370,11 +404,15 @@ export async function createOAuthRefreshToken(params) {
             row.replacedByHash,
         ],
     });
+    if (result.rowsAffected !== 1) {
+        throw new Error("Refresh-token creation returned an invalid row count");
+    }
     return row;
 }
-export async function rotateOAuthRefreshToken(params) {
-    await ensureTable();
-    const client = getDbExec();
+export async function rotateOAuthRefreshToken(params, db) {
+    if (!db)
+        await ensureTable();
+    const client = db ?? getDbExec();
     const oldHash = hashOAuthToken(params.oldRefreshToken);
     const newHash = hashOAuthToken(params.newRefreshToken);
     const { rows } = await client.execute({
@@ -384,15 +422,20 @@ export async function rotateOAuthRefreshToken(params) {
     if (rows.length === 0)
         return null;
     const old = mapRefreshRow(rows[0]);
-    if (old.revokedAt != null || (old.expiresAt ?? 0) < Date.now())
-        return null;
     const now = Date.now();
+    if (!hasIssuanceOwner(old) ||
+        old.revokedAt != null ||
+        (old.expiresAt ?? 0) < now)
+        return null;
     const update = await client.execute({
-        sql: `UPDATE mcp_oauth_refresh_tokens SET revoked_at = ?, last_used_at = ?, replaced_by_hash = ? WHERE token_hash = ? AND revoked_at IS NULL`,
-        args: [now, now, newHash, oldHash],
+        sql: `UPDATE mcp_oauth_refresh_tokens SET revoked_at = ?, last_used_at = ?, replaced_by_hash = ? WHERE token_hash = ? AND revoked_at IS NULL AND expires_at >= ? AND owner_email = ? AND issued_for_email = ?`,
+        args: [now, now, newHash, oldHash, now, old.ownerEmail, old.issuedForEmail],
     });
     if (update.rowsAffected === 0)
         return null;
+    if (update.rowsAffected !== 1) {
+        throw new Error("Refresh-token rotation returned an invalid row count");
+    }
     const next = {
         ...old,
         id: randomUUID(),
@@ -403,13 +446,14 @@ export async function rotateOAuthRefreshToken(params) {
         revokedAt: null,
         replacedByHash: null,
     };
-    await client.execute({
-        sql: `INSERT INTO mcp_oauth_refresh_tokens (id, token_hash, client_id, owner_email, org_id, org_domain, scope, resource, created_at, expires_at, last_used_at, revoked_at, replaced_by_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    const insert = await client.execute({
+        sql: `INSERT INTO mcp_oauth_refresh_tokens (id, token_hash, client_id, owner_email, issued_for_email, org_id, org_domain, scope, resource, created_at, expires_at, last_used_at, revoked_at, replaced_by_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         args: [
             next.id,
             next.tokenHash,
             next.clientId,
             next.ownerEmail,
+            next.issuedForEmail,
             next.orgId,
             next.orgDomain,
             next.scope,
@@ -421,6 +465,9 @@ export async function rotateOAuthRefreshToken(params) {
             next.replacedByHash,
         ],
     });
+    if (insert.rowsAffected !== 1) {
+        throw new Error("Refresh-token rotation returned an invalid row count");
+    }
     return next;
 }
 export async function getOAuthRefreshToken(refreshToken) {
@@ -434,7 +481,9 @@ export async function getOAuthRefreshToken(refreshToken) {
     if (rows.length === 0)
         return null;
     const row = mapRefreshRow(rows[0]);
-    if (row.revokedAt != null || (row.expiresAt ?? 0) < Date.now()) {
+    if (!hasIssuanceOwner(row) ||
+        row.revokedAt != null ||
+        (row.expiresAt ?? 0) < Date.now()) {
         return null;
     }
     return row;
@@ -443,14 +492,50 @@ export async function getOAuthRefreshToken(refreshToken) {
  * Slide the refresh-token's expiry window on each successful use so that active
  * users never hit the TTL. Records `last_used_at` and extends `expires_at` to
  * `now + MCP_OAUTH_REFRESH_TOKEN_TTL_MS`.
+ * The caller supplies the owner whose membership it verified.
  */
-export async function touchOAuthRefreshToken(refreshToken) {
-    await ensureTable();
-    const client = getDbExec();
+export async function touchOAuthRefreshToken(refreshToken, expectedOwnerEmail, db) {
+    if (!db)
+        await ensureTable();
+    const client = db ?? getDbExec();
     const tokenHash = hashOAuthToken(refreshToken);
     const now = Date.now();
-    await client.execute({
-        sql: `UPDATE mcp_oauth_refresh_tokens SET last_used_at = ?, expires_at = ? WHERE token_hash = ? AND revoked_at IS NULL`,
-        args: [now, now + MCP_OAUTH_REFRESH_TOKEN_TTL_MS, tokenHash],
+    const result = await client.execute({
+        sql: `UPDATE mcp_oauth_refresh_tokens SET last_used_at = ?, expires_at = ? WHERE token_hash = ? AND revoked_at IS NULL AND expires_at >= ? AND owner_email = ? AND issued_for_email = ? AND BTRIM(issued_for_email) <> ''`,
+        args: [
+            now,
+            now + MCP_OAUTH_REFRESH_TOKEN_TTL_MS,
+            tokenHash,
+            now,
+            expectedOwnerEmail,
+            expectedOwnerEmail,
+        ],
+    });
+    if (result.rowsAffected === 0)
+        return "invalid";
+    if (result.rowsAffected === 1)
+        return "renewed";
+    throw new Error("Refresh-token renewal returned an invalid row count");
+}
+/**
+ * Revoke one refresh token so it can never mint another access token.
+ * Idempotent: an already-revoked token keeps its first timestamp.
+ */
+export async function revokeOAuthRefreshToken(refreshToken, expectedOwnerEmail) {
+    await ensureTable();
+    const client = getDbExec();
+    const result = await client.execute({
+        sql: `UPDATE mcp_oauth_refresh_tokens SET revoked_at = ? WHERE token_hash = ? AND revoked_at IS NULL${expectedOwnerEmail !== undefined
+            ? " AND owner_email = ? AND issued_for_email = ?"
+            : ""}`,
+        args: [
+            Date.now(),
+            hashOAuthToken(refreshToken),
+            ...(expectedOwnerEmail !== undefined
+                ? [expectedOwnerEmail, expectedOwnerEmail]
+                : []),
+        ],
     });
+    if (result.rowsAffected !== 0 && result.rowsAffected !== 1)
+        throw new Error("Refresh-token revocation returned an invalid row count");
 }

package/dist/mcp/oauth-token.d.ts

@@ -2,6 +2,7 @@ import { MCP_OAUTH_ACCESS_TOKEN_TTL, MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS } from "
 export { MCP_OAUTH_ACCESS_TOKEN_TTL, MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS };
 export declare const MCP_OAUTH_SCOPES: readonly ["mcp:read", "mcp:write", "mcp:apps", "offline_access"];
 export declare const MCP_OAUTH_DEFAULT_SCOPE: string;
+declare const MCP_OAUTH_CREDENTIAL_VERSION = 2;
 export interface McpOAuthAccessTokenClaims {
     sub: string;
     org_id?: string | null;
@@ -11,6 +12,7 @@ export interface McpOAuthAccessTokenClaims {
     resource: string;
     jti?: string;
     typ: "agent-native-mcp-oauth";
+    credential_version: typeof MCP_OAUTH_CREDENTIAL_VERSION;
 }
 export declare function normalizeOAuthScope(input: unknown): string | null;
 export declare function scopeList(scope: string | undefined): string[];
@@ -38,4 +40,6 @@ export declare function verifyMcpOAuthAccessToken(token: string, resource: strin
     clientId: string;
     jti?: string;
     catalogScope?: "full";
+    /** `iat`, in seconds. */
+    issuedAt?: number;
 } | null>;