@arcblock/did-connect-service 4.1.18 → 4.1.20

package/dist/handlers/oauth-as-handler.js

@@ -18,7 +18,9 @@
  *   PKCE + bound userDid/instanceDid live in session.source as `oauth-code:{json}`
  *   challenge column stays the AES wrap key for the approved-user payload
  *   POST token (authorization_code) → mint instance-bound access key
- *   redirect_uri is re-checked as RFC 8252 loopback on GET, POST, and token
+ *   redirect_uri (https / RFC 8252 loopback http / private-use scheme) is
+ *   matched against the client registration on GET + POST; token binds the
+ *   presented value to the server-stored one
  *
  * Tokens are instance-bound access keys (same store / resolveAccessKeyCaller).
  *
@@ -35,12 +37,21 @@
  * loose — unregistered client_id still works. client_id grants no permissions.
  */
 import { generateAccessKey } from "../access/access-key-util.js";
+import { canGrantRole } from "../access/rbac.js";
 import { decryptAES, encryptAES } from "../crypto/aes-gcm.js";
 import { generateRefreshTokenId, hashRefreshToken } from "../identity/refresh-tokens.js";
 import { consoleLogger } from "../logger.js";
 import { buildLoginUrl } from "../login-url.js";
 import { REFRESH_TOKEN_TTL_SECONDS } from "../store/d1-store.js";
+import { fetchCimdClient, isCimdClientId, sanitizeDisplayText } from "./cimd.js";
 const SESSION_TTL_MS = 5 * 60 * 1000; // match AccessKeyConnectHandler
+/**
+ * The authorization-code session covers "redirect to login → sign in (possibly
+ * registering a passkey first) → read the consent screen → click Authorize".
+ * Five minutes was the device-poll budget and is far too tight for a
+ * first-time user, who then lands on `invalid_grant` with no way back.
+ */
+const OAUTH_AUTHORIZE_SESSION_TTL_MS = 15 * 60 * 1000;
 const POLL_INTERVAL_SEC = 5;
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 const CODE_GRANT = "authorization_code";
@@ -48,7 +59,12 @@ const REFRESH_GRANT = "refresh_token";
 const OAUTH_CODE_SOURCE_PREFIX = "oauth-code:";
 /** Unverified estimate aligned with the epic: 1 hour OAuth access TTL. */
 export const OAUTH_ACCESS_TTL_SECONDS = 60 * 60;
-/** Unverified estimate: DCR records expire after 7 days. */
+/**
+ * Grace period for an *unused* DCR registration — a drive-by or abandoned
+ * `POST /register` is swept after 7 days. Once a user actually consents to the
+ * client, {@link D1Store.clearOAuthClientExpiry} drops the TTL for good, so a
+ * connector in real use never expires out from under its owner.
+ */
 export const OAUTH_DCR_TTL_SECONDS = 7 * 24 * 60 * 60;
 /** Unverified estimate: DCR registrations per IP per window. */
 export const OAUTH_DCR_RATE_LIMIT = 20;
@@ -66,18 +82,97 @@ const PKCE_VERIFIER_RE = /^[A-Za-z0-9\-._~]{43,128}$/;
 const PKCE_CHALLENGE_RE = /^[A-Za-z0-9\-._~]{43,128}$/;
 /** RFC 8628 user_code alphabet (no ambiguous chars / vowels). */
 const USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+/** Bound so one malformed request cannot flood the log with a huge field. */
+const LOG_FIELD_MAX = 200;
+function logSafe(value) {
+    if (!value)
+        return undefined;
+    return value.length > LOG_FIELD_MAX ? `${value.slice(0, LOG_FIELD_MAX)}…` : value;
+}
 export class OAuthAsHandler {
     store;
     logger;
     auth;
     accessKeyHandler;
     dcrRateLimit;
+    cimdFetch;
     constructor(options) {
         this.store = options.store;
         this.logger = options.logger ?? consoleLogger;
         this.auth = options.auth;
         this.accessKeyHandler = options.accessKeyHandler;
         this.dcrRateLimit = options.dcrRateLimit ?? OAUTH_DCR_RATE_LIMIT;
+        this.cimdFetch = options.cimdFetch;
+    }
+    /**
+     * Deps for the CIMD path: the injectable fetch plus a document cache backed
+     * by the existing kv_cache table (spec: respect HTTP cache headers, never
+     * cache an error or a malformed document).
+     */
+    cimdDeps() {
+        return {
+            ...(this.cimdFetch ? { fetchImpl: this.cimdFetch } : {}),
+            logger: this.logger,
+            cache: {
+                get: (key) => this.store.cacheGet(key),
+                put: (key, value, ttl) => this.store.cachePut(key, value, ttl),
+            },
+        };
+    }
+    /**
+     * Durable record of an OAuth lifecycle event.
+     *
+     * Denial logs answer "why did this fail?" but roll away; this answers "who
+     * authorised which client, when, and what was minted" months later. Never
+     * carries a code, verifier, token secret, or refresh token — access key IDs
+     * are identifiers, not credentials.
+     *
+     * Audit failure must not fail the authorization it describes, but it must be
+     * visible: a silent catch here would defeat the point of having an audit.
+     */
+    async audit(input) {
+        try {
+            await this.store.createAuditLog({
+                action: input.action,
+                operatorDid: input.operatorDid,
+                ...(input.metadata ? { metadata: input.metadata } : {}),
+                ...(input.ip ? { ip: input.ip } : {}),
+                ...(input.instanceDid ? { instanceDid: input.instanceDid } : {}),
+            });
+        }
+        catch (err) {
+            this.logger.error({
+                message: "oauth-as: audit write failed",
+                mod: "oauth-as",
+                action: input.action,
+                err,
+            });
+        }
+    }
+    /**
+     * Single funnel for every rejection this handler emits. Before this existed
+     * the AS had 51 error returns and 5 log lines, so a client that stopped
+     * working ("invalid_client", "Invalid redirect_uri") left no server-side
+     * trace and had to be diagnosed by guesswork. One structured record per
+     * denial, carrying stage + error + reason + non-secret request identity.
+     *
+     * Deliberately never logs a code, code_verifier, access/refresh token, or
+     * session secret — {@link DenyContext} is the allowlist.
+     */
+    deny(stage, denial, ctx = {}) {
+        this.logger.warn({
+            message: "oauth-as denied",
+            mod: "oauth-as",
+            stage,
+            error: denial.error,
+            reason: denial.description,
+            status: denial.status,
+            ...(ctx.clientId ? { clientId: logSafe(ctx.clientId) } : {}),
+            ...(ctx.redirectUri ? { redirectUri: logSafe(ctx.redirectUri) } : {}),
+            ...(ctx.grantType ? { grantType: logSafe(ctx.grantType) } : {}),
+            ...(ctx.cause ? { cause: ctx.cause } : {}),
+        });
+        return oauthError(denial.error, denial.description, denial.status);
     }
     async fetch(request, instanceDid) {
         const url = new URL(request.url);
@@ -93,9 +188,13 @@ export class OAuthAsHandler {
         }
         if (pathname === REGISTER_PATH) {
             if (request.method !== "POST") {
-                return jsonResponse({ error: "invalid_request", error_description: "Method not allowed" }, 405);
+                return this.deny("register", {
+                    error: "invalid_request",
+                    description: "Method not allowed",
+                    status: 405,
+                });
             }
-            return this.register(request);
+            return this.register(request, instanceDid);
         }
         if (pathname === DEVICE_PATH && request.method === "POST") {
             return this.deviceAuthorization(request);
@@ -117,6 +216,8 @@ export class OAuthAsHandler {
             response_types_supported: ["code"],
             grant_types_supported: [DEVICE_GRANT, CODE_GRANT, REFRESH_GRANT],
             code_challenge_methods_supported: ["S256"],
+            // MCP: clients check this before using a URL-shaped client_id.
+            client_id_metadata_document_supported: true,
             token_endpoint_auth_methods_supported: ["none"],
             // Public clients (MCP agents); no client secret.
             scopes_supported: ["mcp"],
@@ -128,16 +229,20 @@ export class OAuthAsHandler {
      * Public client (token_endpoint_auth_method=none). Echoes the full schema;
      * a `{client_id}`-only body is a hard fail for Claude Code.
      */
-    async register(request) {
+    async register(request, instanceDid) {
         const parsed = await parseDcrRequest(request);
         if (!parsed.ok)
-            return parsed.response;
+            return this.deny("register", parsed.denial);
         const ip = clientIp(request);
         const windowStart = new Date(Date.now() - OAUTH_DCR_RATE_WINDOW_MS).toISOString();
         const recent = await this.store.listOAuthClientsByIp(ip);
         const recentCount = recent.filter((row) => row.createdAt > windowStart).length;
         if (recentCount >= this.dcrRateLimit) {
-            return jsonResponse({ error: "invalid_client_metadata", error_description: "Too many registration requests" }, 429);
+            return this.deny("register", {
+                error: "invalid_client_metadata",
+                description: "Too many registration requests",
+                status: 429,
+            });
         }
         const clientId = crypto.randomUUID();
         const expiresAt = new Date(Date.now() + OAUTH_DCR_TTL_SECONDS * 1000).toISOString();
@@ -151,6 +256,17 @@ export class OAuthAsHandler {
             createdFromIp: ip,
             expiresAt,
         });
+        await this.audit({
+            action: "oauth_as.client.register",
+            operatorDid: "system",
+            instanceDid,
+            ip,
+            metadata: {
+                clientId,
+                redirectUriHosts: parsed.redirectUris.map(redirectHostForAudit),
+                source: "dcr",
+            },
+        });
         return jsonResponse({
             client_id: clientId,
             redirect_uris: parsed.redirectUris,
@@ -166,15 +282,31 @@ export class OAuthAsHandler {
      */
     async authorizeGet(request, instanceDid) {
         const url = new URL(request.url);
-        const parsed = parseAuthorizeQuery(url.searchParams);
-        if (!parsed.ok)
-            return parsed.response;
-        const client = await resolveOAuthClient(this.store, parsed.clientId);
-        if (!client) {
-            return oauthError("invalid_client", "Unknown client_id", 400);
+        const parsed = parseAuthorizeQuery(url.searchParams, url.origin);
+        if (!parsed.ok) {
+            return this.deny("authorize_get", parsed.denial, {
+                clientId: url.searchParams.get("client_id") ?? undefined,
+                redirectUri: url.searchParams.get("redirect_uri") ?? undefined,
+            });
         }
-        if (!client.redirectUris.includes(parsed.redirectUri)) {
-            return oauthError("invalid_request", "redirect_uri is not registered for this client", 400);
+        const ctx = { clientId: parsed.clientId, redirectUri: parsed.redirectUri };
+        const client = await resolveOAuthClient(this.store, parsed.clientId, this.cimdDeps());
+        if (!client) {
+            // The #1 support question. Say which of the two causes it was: never
+            // registered, or a DCR row that aged out.
+            const known = await this.store.getOAuthClient(parsed.clientId);
+            return this.deny("authorize_get", {
+                error: "invalid_client",
+                description: "Unknown client_id",
+                status: 400,
+            }, { ...ctx, cause: known ? "expired-registration" : "no-registration" });
+        }
+        if (!redirectUriMatches(client.redirectUris, parsed.redirectUri)) {
+            return this.deny("authorize_get", {
+                error: "invalid_request",
+                description: "redirect_uri is not registered for this client",
+                status: 400,
+            }, ctx);
         }
         const caller = this.auth ? await this.auth.verifyFull(request, instanceDid) : null;
         if (!caller) {
@@ -182,11 +314,11 @@ export class OAuthAsHandler {
             return redirectResponse(login);
         }
         if (!instanceDid) {
-            return oauthError("invalid_request", "Missing instance", 400);
+            return this.deny("authorize_get", { error: "invalid_request", description: "Missing instance", status: 400 }, ctx);
         }
         const id = crypto.randomUUID();
         const challenge = randomHex(24);
-        const expiresAt = new Date(Date.now() + SESSION_TTL_MS).toISOString();
+        const expiresAt = new Date(Date.now() + OAUTH_AUTHORIZE_SESSION_TTL_MS).toISOString();
         const source = serializeOAuthCodeSource({
             client_id: parsed.clientId,
             redirect_uri: parsed.redirectUri,
@@ -195,6 +327,9 @@ export class OAuthAsHandler {
             state: parsed.state,
             userDid: caller.did,
             instanceDid,
+            ...(client.clientName ? { clientName: client.clientName } : {}),
+            trust: client.source,
+            ...(parsed.resource ? { resource: parsed.resource } : {}),
         });
         await this.store.purgeExpiredAccessKeySessions();
         await this.store.createAccessKeySession({ id, challenge, source, expiresAt });
@@ -212,49 +347,82 @@ export class OAuthAsHandler {
     async authorizePost(request, instanceDid) {
         const csrf = rejectCrossOrigin(request);
         if (csrf)
-            return csrf;
+            return this.deny("authorize_post", csrf, { cause: "cross-origin" });
         if (!this.auth) {
-            return oauthError("access_denied", "Authentication required", 401);
+            return this.deny("authorize_post", {
+                error: "access_denied",
+                description: "Authentication required",
+                status: 401,
+            });
         }
         const caller = await this.auth.verifyFull(request, instanceDid);
         if (!caller) {
-            return oauthError("access_denied", "Authentication required", 401);
+            return this.deny("authorize_post", {
+                error: "access_denied",
+                description: "Authentication required",
+                status: 401,
+            });
         }
         if (!instanceDid) {
-            return oauthError("invalid_request", "Missing instance", 400);
+            return this.deny("authorize_post", {
+                error: "invalid_request",
+                description: "Missing instance",
+                status: 400,
+            });
         }
         const params = await readParams(request);
         const sid = params.sid?.trim() ?? "";
         if (!sid) {
-            return oauthError("invalid_request", "Missing sid", 400);
+            return this.deny("authorize_post", {
+                error: "invalid_request",
+                description: "Missing sid",
+                status: 400,
+            });
         }
         const session = await this.store.getAccessKeySession(sid);
         if (!session) {
-            return oauthError("invalid_grant", "Invalid or expired authorization request", 400);
+            return this.deny("authorize_post", {
+                error: "invalid_grant",
+                description: "Invalid or expired authorization request",
+                status: 400,
+            });
         }
         const meta = parseOAuthCodeSource(session.source);
-        if (!meta || !isLoopbackRedirectUri(meta.redirect_uri)) {
-            return oauthError("invalid_request", "Invalid redirect_uri", 400);
+        if (!meta) {
+            return this.deny("authorize_post", { error: "invalid_request", description: "Invalid redirect_uri", status: 400 }, { cause: "unparseable-session-source" });
+        }
+        const ctx = { clientId: meta.client_id, redirectUri: meta.redirect_uri };
+        // Re-check against the live registration — the only thing standing between
+        // a forged/stale session source and a 302 to an attacker-controlled URI.
+        const client = await resolveOAuthClient(this.store, meta.client_id, this.cimdDeps());
+        if (!client || !redirectUriMatches(client.redirectUris, meta.redirect_uri)) {
+            return this.deny("authorize_post", { error: "invalid_request", description: "Invalid redirect_uri", status: 400 }, { ...ctx, cause: client ? "redirect-not-registered" : "client-unresolvable" });
         }
         if (meta.userDid !== caller.did || meta.instanceDid !== instanceDid) {
-            return oauthError("access_denied", "Authorization session is bound to another user or instance", 403);
+            return this.deny("authorize_post", {
+                error: "access_denied",
+                description: "Authorization session is bound to another user or instance",
+                status: 403,
+            }, ctx);
         }
         if (session.status === "completed") {
-            return oauthError("invalid_grant", "Authorization request already used", 400);
+            return this.deny("authorize_post", { error: "invalid_grant", description: "Authorization request already used", status: 400 }, ctx);
         }
         if (session.status !== "pending") {
-            this.logger.warn({
-                message: "oauth-as authorize: unexpected session status",
-                mod: "oauth-as",
-                status: session.status,
-            });
-            return oauthError("invalid_grant", "Invalid authorization state", 400);
+            return this.deny("authorize_post", { error: "invalid_grant", description: "Invalid authorization state", status: 400 }, { ...ctx, cause: `session-status:${session.status}` });
+        }
+        // Consented role: the consent page lets the user narrow the grant below
+        // their own role. Omitted → inherit it. Above it is escalation — refuse.
+        const callerRole = caller.role || "guest";
+        const requestedRole = !params.role ? callerRole : params.role;
+        if (!canGrantRole(callerRole, requestedRole)) {
+            return this.deny("authorize_post", { error: "invalid_request", description: "Invalid role", status: 400 }, { ...ctx, cause: `role-not-grantable:${logSafe(requestedRole)}` });
         }
         // Fresh one-time code — never reuse the session id the creator already knows.
         const code = crypto.randomUUID();
         const payload = {
             did: caller.did,
-            role: caller.role || "guest",
+            role: requestedRole,
             instanceDid,
         };
         const encrypted = await encryptAES(JSON.stringify(payload), session.challenge);
@@ -270,6 +438,31 @@ export class OAuthAsHandler {
             accessKeyId: "",
             accessKeySecretEncrypted: encrypted,
         });
+        // A user just consented to this client, so it is real and in use — drop its
+        // DCR TTL. Otherwise a working connector silently dies at the 7-day mark
+        // with `invalid_client` and no server-side trace. Unused registrations keep
+        // their TTL, so drive-by/spam rows still get cleaned up.
+        if (client.source === "dcr" && client.expiresAt) {
+            await this.store.clearOAuthClientExpiry(meta.client_id);
+            this.logger.info({
+                message: "oauth-as client registration confirmed by user consent; TTL cleared",
+                mod: "oauth-as",
+                clientId: logSafe(meta.client_id),
+            });
+        }
+        await this.audit({
+            action: "oauth_as.consent",
+            operatorDid: caller.did,
+            instanceDid,
+            ip: clientIp(request),
+            metadata: {
+                clientId: meta.client_id,
+                clientName: meta.clientName ?? null,
+                trust: meta.trust ?? "dcr",
+                destination: describeRedirectDestination(meta.redirect_uri).label,
+                resource: meta.resource ?? null,
+            },
+        });
         const target = new URL(meta.redirect_uri);
         target.hash = "";
         target.searchParams.set("code", code);
@@ -324,30 +517,42 @@ export class OAuthAsHandler {
             return this.refreshTokenGrant(params, instanceDid);
         }
         if (grantType !== DEVICE_GRANT) {
-            return oauthError("unsupported_grant_type", "Only device_code, authorization_code, and refresh_token grants are supported", 400);
+            return this.deny("token_device", {
+                error: "unsupported_grant_type",
+                description: "Only device_code, authorization_code, and refresh_token grants are supported",
+                status: 400,
+            }, { grantType });
         }
         const deviceCode = params.device_code?.trim() ?? "";
         if (!deviceCode) {
-            return oauthError("invalid_request", "Missing device_code", 400);
+            return this.deny("token_device", {
+                error: "invalid_request",
+                description: "Missing device_code",
+                status: 400,
+            });
         }
         const session = await this.store.getAccessKeySession(deviceCode);
         if (!session) {
             // Expired or never existed — RFC: expired_token or invalid_grant
-            return oauthError("invalid_grant", "Invalid or expired device_code", 400);
+            return this.deny("token_device", {
+                error: "invalid_grant",
+                description: "Invalid or expired device_code",
+                status: 400,
+            });
         }
         if (session.status === "pending") {
+            // Not an error: RFC 8628 polling. Logging every poll would be noise.
             return oauthError("authorization_pending", "User has not authorized the request", 400);
         }
         if (session.status !== "completed") {
-            this.logger.warn({
-                message: "oauth-as token: unexpected session status",
-                mod: "oauth-as",
-                status: session.status,
-            });
-            return oauthError("invalid_grant", "Invalid device authorization state", 400);
+            return this.deny("token_device", {
+                error: "invalid_grant",
+                description: "Invalid device authorization state",
+                status: 400,
+            }, { cause: `session-status:${session.status}` });
         }
         if (!session.access_key_secret_encrypted || !session.challenge) {
-            return oauthError("invalid_grant", "Authorization data missing", 400);
+            return this.deny("token_device", { error: "invalid_grant", description: "Authorization data missing", status: 400 }, { cause: "session-payload-missing" });
         }
         let accessToken;
         try {
@@ -359,7 +564,11 @@ export class OAuthAsHandler {
                 mod: "oauth-as",
                 err,
             });
-            return oauthError("server_error", "Failed to materialize access token", 500);
+            return this.deny("token_device", {
+                error: "server_error",
+                description: "Failed to materialize access token",
+                status: 500,
+            });
         }
         // One-time use: remove session after successful exchange
         await this.store.deleteAccessKeySession(deviceCode);
@@ -380,41 +589,63 @@ export class OAuthAsHandler {
         const verifier = params.code_verifier ?? "";
         const redirectUri = params.redirect_uri ?? "";
         const clientId = params.client_id?.trim() ?? "";
+        const ctx = { clientId, redirectUri, grantType: CODE_GRANT };
         if (!code || !verifier || !redirectUri || !clientId) {
-            return oauthError("invalid_request", "Missing code, code_verifier, redirect_uri, or client_id", 400);
+            return this.deny("token_code", {
+                error: "invalid_request",
+                description: "Missing code, code_verifier, redirect_uri, or client_id",
+                status: 400,
+            }, ctx);
         }
         if (!instanceDid) {
-            return oauthError("invalid_request", "Missing instance", 400);
+            return this.deny("token_code", { error: "invalid_request", description: "Missing instance", status: 400 }, ctx);
         }
-        if (!isLoopbackRedirectUri(redirectUri)) {
-            return oauthError("invalid_request", "Invalid redirect_uri", 400);
+        if (!isAllowedRedirectUri(redirectUri)) {
+            return this.deny("token_code", { error: "invalid_request", description: "Invalid redirect_uri", status: 400 }, ctx);
         }
         const session = await this.store.getAccessKeySession(code);
         if (!session) {
-            return oauthError("invalid_grant", "Invalid or expired code", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Invalid or expired code", status: 400 }, { ...ctx, cause: "code-unknown-or-expired" });
         }
         const meta = parseOAuthCodeSource(session.source);
-        if (!meta || !isLoopbackRedirectUri(meta.redirect_uri)) {
-            return oauthError("invalid_grant", "Invalid or expired code", 400);
+        if (!meta) {
+            return this.deny("token_code", { error: "invalid_grant", description: "Invalid or expired code", status: 400 }, { ...ctx, cause: "unparseable-session-source" });
         }
         if (session.status !== "completed") {
-            return oauthError("invalid_grant", "Authorization not completed", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Authorization not completed", status: 400 }, { ...ctx, cause: `session-status:${session.status}` });
         }
         if (meta.client_id !== clientId || meta.redirect_uri !== redirectUri) {
-            return oauthError("invalid_grant", "client_id or redirect_uri mismatch", 400);
+            return this.deny("token_code", {
+                error: "invalid_grant",
+                description: "client_id or redirect_uri mismatch",
+                status: 400,
+            }, {
+                ...ctx,
+                cause: meta.client_id !== clientId ? "client-id-mismatch" : "redirect-uri-mismatch",
+            });
         }
+        // No registration re-check here: meta is the server-stored value already
+        // matched against the registration on GET + POST, and an in-flight code
+        // must survive the client record's TTL expiry.
         if (meta.instanceDid !== instanceDid) {
-            return oauthError("invalid_grant", "instance mismatch", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "instance mismatch", status: 400 }, ctx);
+        }
+        // RFC 8707 §2: the token request may not name an audience the
+        // authorization request did not. Absent at token time means "same as
+        // authorize", which is the common client behaviour.
+        const presentedResource = params.resource?.trim();
+        if (presentedResource && presentedResource !== meta.resource) {
+            return this.deny("token_code", { error: "invalid_target", description: "resource does not match the authorization", status: 400 }, { ...ctx, cause: "resource-mismatch" });
         }
         if (meta.code_challenge_method !== "S256" || !PKCE_VERIFIER_RE.test(verifier)) {
-            return oauthError("invalid_grant", "Invalid code_verifier", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Invalid code_verifier", status: 400 }, { ...ctx, cause: "verifier-malformed" });
         }
         const computed = await s256Challenge(verifier);
         if (!timingSafeEqual(computed, meta.code_challenge)) {
-            return oauthError("invalid_grant", "Invalid code_verifier", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Invalid code_verifier", status: 400 }, { ...ctx, cause: "pkce-mismatch" });
         }
         if (!session.access_key_secret_encrypted || !session.challenge) {
-            return oauthError("invalid_grant", "Authorization data missing", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Authorization data missing", status: 400 }, { ...ctx, cause: "session-payload-missing" });
         }
         let grant;
         try {
@@ -426,13 +657,17 @@ export class OAuthAsHandler {
                 mod: "oauth-as",
                 err,
             });
-            return oauthError("invalid_grant", "Authorization data missing", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Authorization data missing", status: 400 }, { ...ctx, cause: "grant-decrypt-failed" });
         }
         if (!grant?.did || grant.did !== meta.userDid || grant.instanceDid !== instanceDid) {
-            return oauthError("invalid_grant", "Authorization data missing", 400);
+            return this.deny("token_code", { error: "invalid_grant", description: "Authorization data missing", status: 400 }, { ...ctx, cause: "grant-binding-mismatch" });
         }
         if (!this.accessKeyHandler) {
-            return oauthError("server_error", "Access key minting is not configured", 500);
+            return this.deny("token_code", {
+                error: "server_error",
+                description: "Access key minting is not configured",
+                status: 500,
+            }, ctx);
         }
         const expireAt = new Date(Date.now() + OAUTH_ACCESS_TTL_SECONDS * 1000).toISOString();
         const accessKey = await this.accessKeyHandler.createKeyInternal({
@@ -447,6 +682,18 @@ export class OAuthAsHandler {
             accessKeyId: accessKey.accessKeyId,
         });
         await this.store.deleteAccessKeySession(code);
+        await this.audit({
+            action: "oauth_as.token.issue",
+            operatorDid: grant.did,
+            instanceDid,
+            metadata: {
+                clientId: meta.client_id,
+                accessKeyId: accessKey.accessKeyId,
+                role: grant.role || "guest",
+                expiresIn: OAUTH_ACCESS_TTL_SECONDS,
+                resource: meta.resource ?? null,
+            },
+        });
         return jsonResponse({
             access_token: accessKey.accessKeySecret,
             token_type: "Bearer",
@@ -460,30 +707,35 @@ export class OAuthAsHandler {
      * Does not call rotateRefreshToken (that path is session-JWT and drops accessKeyId).
      */
     async refreshTokenGrant(params, instanceDid) {
+        // Client-facing description stays deliberately uniform ("Invalid
+        // refresh_token") so a caller cannot probe token state; `cause` carries the
+        // real reason to the operator's log instead.
+        const ctx = { grantType: REFRESH_GRANT, clientId: params.client_id?.trim() };
+        const badToken = (cause) => this.deny("token_refresh", { error: "invalid_grant", description: "Invalid refresh_token", status: 400 }, { ...ctx, cause });
         const presented = params.refresh_token?.trim() ?? "";
         if (!presented) {
-            return oauthError("invalid_request", "Missing refresh_token", 400);
+            return this.deny("token_refresh", { error: "invalid_request", description: "Missing refresh_token", status: 400 }, ctx);
         }
         if (!instanceDid) {
-            return oauthError("invalid_request", "Missing instance", 400);
+            return this.deny("token_refresh", { error: "invalid_request", description: "Missing instance", status: 400 }, ctx);
         }
         const row = await this.store.getRefreshTokenRow(presented);
         if (!row || row.revokedAt) {
-            return oauthError("invalid_grant", "Invalid refresh_token", 400);
+            return badToken(row ? "refresh-revoked" : "refresh-unknown");
         }
         if (new Date(row.expiresAt).getTime() < Date.now()) {
-            return oauthError("invalid_grant", "Invalid refresh_token", 400);
+            return badToken("refresh-expired");
         }
         // Session-JWT refresh rows have no accessKeyId — not an OAuth grant.
         if (!row.accessKeyId) {
-            return oauthError("invalid_grant", "Invalid refresh_token", 400);
+            return badToken("not-an-oauth-grant");
         }
         const oldKey = await this.store.getAccessKeyById(row.accessKeyId);
         if (!oldKey || oldKey.authType !== "oauth") {
-            return oauthError("invalid_grant", "Invalid refresh_token", 400);
+            return badToken(oldKey ? "access-key-not-oauth" : "access-key-missing");
         }
         if (oldKey.instanceDid !== instanceDid) {
-            return oauthError("invalid_grant", "instance mismatch", 400);
+            return this.deny("token_refresh", { error: "invalid_grant", description: "instance mismatch", status: 400 }, ctx);
         }
         const minted = generateAccessKey();
         const expireAt = new Date(Date.now() + OAUTH_ACCESS_TTL_SECONDS * 1000).toISOString();
@@ -516,10 +768,20 @@ export class OAuthAsHandler {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (/UNIQUE constraint/i.test(msg)) {
-                return oauthError("invalid_grant", "Invalid refresh_token", 400);
+                return badToken("rotation-race");
             }
             throw err;
         }
+        await this.audit({
+            action: "oauth_as.token.refresh",
+            operatorDid: row.userDid,
+            instanceDid,
+            metadata: {
+                previousAccessKeyId: oldKey.accessKeyId,
+                accessKeyId: minted.accessKeyId,
+                expiresIn: OAUTH_ACCESS_TTL_SECONDS,
+            },
+        });
         return jsonResponse({
             access_token: minted.accessKeySecret,
             token_type: "Bearer",
@@ -529,8 +791,18 @@ export class OAuthAsHandler {
         });
     }
 }
+/** Host (or scheme, for private-use URIs) of a redirect target, for audit rows. */
+function redirectHostForAudit(uri) {
+    try {
+        const url = new URL(uri);
+        return url.host || url.protocol.replace(/:$/, "");
+    }
+    catch {
+        return "invalid";
+    }
+}
 // ─── Authorize query / PKCE / redirect URI ─────────────────────────
-function parseAuthorizeQuery(search) {
+function parseAuthorizeQuery(search, issuerOrigin) {
     const clientId = search.get("client_id")?.trim() ?? "";
     const redirectUri = search.get("redirect_uri") ?? "";
     const responseType = search.get("response_type") ?? "";
@@ -538,33 +810,84 @@ function parseAuthorizeQuery(search) {
     const method = search.get("code_challenge_method") ?? "";
     const state = search.get("state") ?? "";
     if (!clientId) {
-        return { ok: false, response: oauthError("invalid_request", "Missing client_id", 400) };
+        return { ok: false, denial: deny400("invalid_request", "Missing client_id") };
     }
-    if (!redirectUri || !isLoopbackRedirectUri(redirectUri)) {
-        // Never redirect to an unvalidated redirect_uri (open-redirect guard).
-        return { ok: false, response: oauthError("invalid_request", "Invalid redirect_uri", 400) };
+    if (!redirectUri || !isAllowedRedirectUri(redirectUri)) {
+        // Never redirect to an unvalidated redirect_uri (open-redirect guard);
+        // registration match happens once the client is resolved.
+        return { ok: false, denial: deny400("invalid_request", "Invalid redirect_uri") };
     }
     if (responseType !== "code") {
-        return { ok: false, response: oauthError("unsupported_response_type", "Only response_type=code is supported", 400) };
+        return {
+            ok: false,
+            denial: deny400("unsupported_response_type", "Only response_type=code is supported"),
+        };
     }
     if (!codeChallenge || !PKCE_CHALLENGE_RE.test(codeChallenge)) {
-        return { ok: false, response: oauthError("invalid_request", "Missing or invalid code_challenge", 400) };
+        return { ok: false, denial: deny400("invalid_request", "Missing or invalid code_challenge") };
     }
     // Missing method is RFC 7636 "plain"; we only support S256.
     if (method !== "S256") {
-        return { ok: false, response: oauthError("invalid_request", "Only code_challenge_method=S256 is supported", 400) };
+        return {
+            ok: false,
+            denial: deny400("invalid_request", "Only code_challenge_method=S256 is supported"),
+        };
+    }
+    // RFC 8707 / MCP: the client names the MCP server the token is for. MCP
+    // clients MUST send it, but older ones do not, so absence is tolerated —
+    // a *wrong* audience is not, since that is the confused-deputy case.
+    const resource = search.get("resource") ?? "";
+    if (resource) {
+        const checked = checkResourceIndicator(resource, issuerOrigin);
+        if (!checked.ok)
+            return { ok: false, denial: checked.denial };
+        return { ok: true, clientId, redirectUri, codeChallenge, state, resource };
     }
     return { ok: true, clientId, redirectUri, codeChallenge, state };
 }
 /**
- * RFC 8252 §7.3 loopback redirect.
- * MUST: http://127.0.0.1:<any-port>/... and http://[::1]:<any-port>/...
- * MAY:  http://localhost:<any-port>/... — Claude Code DCR / CIMD use this
- * hostname (including the implicit port-80 form http://localhost/callback).
- * HTTPS loopback, userinfo, fragments, and any other host are rejected.
- * Hostname must be exactly localhost — not *.localhost or localhost.evil.test.
+ * RFC 8707 §2: an absolute URI, no fragment. MCP additionally requires it to
+ * identify this MCP server, so it must sit on our own origin — a token minted
+ * here must never be presentable as one issued for somebody else's resource.
+ */
+function checkResourceIndicator(resource, issuerOrigin) {
+    let url;
+    try {
+        url = new URL(resource);
+    }
+    catch {
+        return { ok: false, denial: deny400("invalid_target", "resource must be an absolute URI") };
+    }
+    if (url.hash) {
+        return { ok: false, denial: deny400("invalid_target", "resource must not contain a fragment") };
+    }
+    if (url.origin !== issuerOrigin) {
+        return {
+            ok: false,
+            denial: deny400("invalid_target", "resource does not identify this server"),
+        };
+    }
+    return { ok: true };
+}
+/** Most denials are 400s; this keeps the parsers readable. */
+function deny400(error, description) {
+    return { error, description, status: 400 };
+}
+/**
+ * Syntax filter for what a client may *register* as a redirect_uri. It is NOT
+ * the open-redirect guard — that is {@link redirectUriMatches} against the
+ * client's own registration, checked on authorize, confirm, and token.
+ *
+ * Accepted:
+ *   https://<host>/...      web clients (claude.ai MCP connector, hosted agents)
+ *   http://127.0.0.1|[::1]|localhost[:port]/...  RFC 8252 §7.3 native loopback
+ *   com.example.app:/...    RFC 8252 §7.1 private-use (reverse-domain) scheme
+ *
+ * Rejected: cleartext http to a non-loopback host, userinfo, fragments, and
+ * dotless custom schemes (javascript:, data:, file:, ...). Hostname must be
+ * exactly localhost — not *.localhost or localhost.evil.test.
  */
-function isLoopbackRedirectUri(value) {
+function isAllowedRedirectUri(value) {
     let url;
     try {
         url = new URL(value);
@@ -572,31 +895,102 @@ function isLoopbackRedirectUri(value) {
     catch {
         return false;
     }
-    if (url.protocol !== "http:")
-        return false;
     if (url.username || url.password)
         return false;
     if (url.hash)
         return false;
-    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (url.protocol === "https:")
+        return url.hostname !== "";
+    if (url.protocol === "http:")
+        return isLoopbackHost(url.hostname);
+    // Private-use scheme: must be reverse-domain (contains a dot), which also
+    // excludes every script-bearing scheme.
+    const scheme = url.protocol.slice(0, -1);
+    return /^[a-z][a-z0-9+-]*(\.[a-z0-9+-]+)+$/.test(scheme);
+}
+function isLoopbackHost(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "");
     return host === "127.0.0.1" || host === "::1" || host === "localhost";
 }
 /**
- * DCR table ∪ pre-registered. Expired DCR rows are treated as unknown.
- * Device grant must NOT call this (unregistered client_id stays valid).
+ * The open-redirect guard: presented redirect_uri must be one the client
+ * registered. Exact byte match, plus RFC 8252 §7.3 — for loopback the AS MUST
+ * ignore the port, because native clients bind an ephemeral port *after*
+ * registering. Everything else (scheme, host, path, query) must match exactly.
+ */
+function redirectUriMatches(registered, presented) {
+    if (registered.includes(presented))
+        return true;
+    let target;
+    try {
+        target = new URL(presented);
+    }
+    catch {
+        return false;
+    }
+    if (target.protocol !== "http:" || !isLoopbackHost(target.hostname))
+        return false;
+    return registered.some((uri) => {
+        let candidate;
+        try {
+            candidate = new URL(uri);
+        }
+        catch {
+            return false;
+        }
+        return (candidate.protocol === "http:" &&
+            candidate.hostname === target.hostname &&
+            candidate.pathname === target.pathname &&
+            candidate.search === target.search);
+    });
+}
+/**
+ * Stored row (pre-registered ∪ DCR) first, then CIMD for URL-shaped client_ids.
+ * Expired DCR rows are treated as unknown. Device grant must NOT call this
+ * (unregistered client_id stays valid there).
  */
-export async function resolveOAuthClient(store, clientId) {
+export async function resolveOAuthClient(store, clientId, deps) {
     const id = clientId.trim();
     if (!id)
         return null;
     const row = await store.getOAuthClient(id);
-    if (row && !isOAuthClientExpired(row))
-        return row;
-    return resolveCimdClient(id);
+    if (row && !isOAuthClientExpired(row)) {
+        return {
+            clientId: row.clientId,
+            redirectUris: row.redirectUris,
+            source: row.source,
+            expiresAt: row.expiresAt,
+        };
+    }
+    return resolveCimdClient(id, deps);
 }
-/** CIMD (Client ID Metadata Document) — stub only this wave. */
-export async function resolveCimdClient(_clientId) {
-    return null;
+/**
+ * CIMD (Client ID Metadata Document) — draft-ietf-oauth-client-id-metadata-document-00.
+ * The MCP spec now prefers this over DCR: the client_id is an https URL the AS
+ * fetches, so the displayed identity is bound to a domain the client controls.
+ */
+export async function resolveCimdClient(clientId, deps) {
+    if (!isCimdClientId(clientId))
+        return null;
+    const result = await fetchCimdClient(clientId, isAllowedRedirectUri, deps ?? {});
+    if (!result.ok) {
+        deps?.logger?.warn({
+            message: "cimd: client_id metadata rejected",
+            mod: "oauth-as",
+            clientId: logSafe(clientId),
+            reason: result.reason,
+        });
+        return null;
+    }
+    return {
+        clientId: result.client.clientId,
+        redirectUris: result.client.redirectUris,
+        source: "cimd",
+        expiresAt: null,
+        clientName: result.client.clientName,
+        ...(result.client.clientUri ? { clientUri: result.client.clientUri } : {}),
+        ...(result.client.logoUri ? { logoUri: result.client.logoUri } : {}),
+    };
 }
 function isOAuthClientExpired(client) {
     if (!client.expiresAt)
@@ -618,7 +1012,7 @@ async function parseDcrRequest(request) {
     if (!ct.includes("application/json")) {
         return {
             ok: false,
-            response: dcrError("invalid_client_metadata", "Content-Type must be application/json"),
+            denial: dcrError("invalid_client_metadata", "Content-Type must be application/json"),
         };
     }
     let text;
@@ -626,37 +1020,37 @@ async function parseDcrRequest(request) {
         text = await request.text();
     }
     catch {
-        return { ok: false, response: dcrError("invalid_client_metadata", "Invalid request body") };
+        return { ok: false, denial: dcrError("invalid_client_metadata", "Invalid request body") };
     }
     if (!text.trim()) {
-        return { ok: false, response: dcrError("invalid_client_metadata", "Empty request body") };
+        return { ok: false, denial: dcrError("invalid_client_metadata", "Empty request body") };
     }
     let body;
     try {
         body = JSON.parse(text);
     }
     catch {
-        return { ok: false, response: dcrError("invalid_client_metadata", "Request body must be JSON") };
+        return { ok: false, denial: dcrError("invalid_client_metadata", "Request body must be JSON") };
     }
     if (!body || typeof body !== "object" || Array.isArray(body)) {
-        return { ok: false, response: dcrError("invalid_client_metadata", "Request body must be a JSON object") };
+        return { ok: false, denial: dcrError("invalid_client_metadata", "Request body must be a JSON object") };
     }
     const rec = body;
     if (!Object.hasOwn(rec, "redirect_uris")) {
-        return { ok: false, response: dcrError("invalid_redirect_uri", "Missing redirect_uris") };
+        return { ok: false, denial: dcrError("invalid_redirect_uri", "Missing redirect_uris") };
     }
     if (!Array.isArray(rec.redirect_uris) || rec.redirect_uris.length === 0) {
-        return { ok: false, response: dcrError("invalid_redirect_uri", "redirect_uris must be a non-empty array") };
+        return { ok: false, denial: dcrError("invalid_redirect_uri", "redirect_uris must be a non-empty array") };
     }
     const redirectUris = [];
     for (const uri of rec.redirect_uris) {
         if (typeof uri !== "string" || !uri) {
-            return { ok: false, response: dcrError("invalid_redirect_uri", "redirect_uris must be strings") };
+            return { ok: false, denial: dcrError("invalid_redirect_uri", "redirect_uris must be strings") };
         }
-        if (!isLoopbackRedirectUri(uri)) {
+        if (!isAllowedRedirectUri(uri)) {
             return {
                 ok: false,
-                response: dcrError("invalid_redirect_uri", "Only RFC 8252 loopback redirect_uris are allowed"),
+                denial: dcrError("invalid_redirect_uri", "redirect_uris must be https, RFC 8252 loopback http, or a private-use scheme (no userinfo or fragment)"),
             };
         }
         redirectUris.push(uri);
@@ -664,27 +1058,27 @@ async function parseDcrRequest(request) {
     let grantTypes = [CODE_GRANT];
     if (rec.grant_types !== undefined) {
         if (!Array.isArray(rec.grant_types) || rec.grant_types.length === 0) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "grant_types must be a non-empty array") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "grant_types must be a non-empty array") };
         }
         if (rec.grant_types.some((g) => typeof g !== "string")) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "grant_types must be strings") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "grant_types must be strings") };
         }
         grantTypes = rec.grant_types;
         if (grantTypes.some((g) => !SUPPORTED_GRANT_TYPES.has(g))) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "Unsupported grant_types") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "Unsupported grant_types") };
         }
     }
     let responseTypes = ["code"];
     if (rec.response_types !== undefined) {
         if (!Array.isArray(rec.response_types) || rec.response_types.length === 0) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "response_types must be a non-empty array") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "response_types must be a non-empty array") };
         }
         if (rec.response_types.some((t) => typeof t !== "string")) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "response_types must be strings") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "response_types must be strings") };
         }
         responseTypes = rec.response_types;
         if (responseTypes.some((t) => !SUPPORTED_RESPONSE_TYPES.has(t))) {
-            return { ok: false, response: dcrError("invalid_client_metadata", "Unsupported response_types") };
+            return { ok: false, denial: dcrError("invalid_client_metadata", "Unsupported response_types") };
         }
     }
     let tokenEndpointAuthMethod = "none";
@@ -692,7 +1086,7 @@ async function parseDcrRequest(request) {
         if (rec.token_endpoint_auth_method !== "none") {
             return {
                 ok: false,
-                response: dcrError("invalid_client_metadata", "Only token_endpoint_auth_method=none is supported"),
+                denial: dcrError("invalid_client_metadata", "Only token_endpoint_auth_method=none is supported"),
             };
         }
         tokenEndpointAuthMethod = "none";
@@ -700,7 +1094,7 @@ async function parseDcrRequest(request) {
     return { ok: true, redirectUris, grantTypes, responseTypes, tokenEndpointAuthMethod };
 }
 function dcrError(error, description) {
-    return jsonResponse({ error, error_description: description }, 400);
+    return deny400(error, description);
 }
 function serializeOAuthCodeSource(meta) {
     return `${OAUTH_CODE_SOURCE_PREFIX}${JSON.stringify(meta)}`;
@@ -718,7 +1112,7 @@ function parseOAuthCodeSource(source) {
             !parsed.userDid ||
             typeof parsed.instanceDid !== "string" ||
             !parsed.instanceDid ||
-            !isLoopbackRedirectUri(parsed.redirect_uri)) {
+            !isAllowedRedirectUri(parsed.redirect_uri)) {
             return null;
         }
         return {
@@ -729,12 +1123,53 @@ function parseOAuthCodeSource(source) {
             state: typeof parsed.state === "string" ? parsed.state : "",
             userDid: parsed.userDid,
             instanceDid: parsed.instanceDid,
+            // Re-sanitised on the way out: the name reaches a consent screen, and a
+            // row could have been written by an older/looser build.
+            ...(sanitizeDisplayText(parsed.clientName)
+                ? { clientName: sanitizeDisplayText(parsed.clientName) }
+                : {}),
+            ...(typeof parsed.resource === "string" && parsed.resource
+                ? { resource: parsed.resource }
+                : {}),
+            // Unknown/absent trust degrades to the least-trusted rendering.
+            trust: parsed.trust === "cimd" || parsed.trust === "pre-registered" ? parsed.trust : "dcr",
         };
     }
     catch {
         return null;
     }
 }
+/**
+ * Build the consent-screen descriptor from a stored authorization session.
+ * Server-side only — the page must never assemble this from its query string.
+ */
+export function describeOAuthConsent(source) {
+    const meta = parseOAuthCodeSource(source);
+    if (!meta)
+        return null;
+    return {
+        ...(meta.clientName ? { clientName: meta.clientName } : {}),
+        clientId: meta.client_id,
+        destination: describeRedirectDestination(meta.redirect_uri),
+        trust: meta.trust ?? "dcr",
+    };
+}
+function describeRedirectDestination(redirectUri) {
+    try {
+        const url = new URL(redirectUri);
+        if (url.protocol === "http:" && isLoopbackHost(url.hostname)) {
+            // Loopback means the credential never leaves the user's machine, which
+            // is worth saying plainly rather than showing a scary bare IP.
+            return { kind: "device", label: url.host };
+        }
+        if (url.protocol === "https:")
+            return { kind: "web", label: url.host };
+        return { kind: "app", label: url.protocol.replace(/:$/, "") };
+    }
+    catch {
+        return { kind: "app", label: "unknown" };
+    }
+}
 /** Cookie POST must be same-origin. Missing Origin/Referer is fail-closed. */
 function rejectCrossOrigin(request) {
     const reqOrigin = new URL(request.url).origin;
@@ -747,7 +1182,7 @@ function rejectCrossOrigin(request) {
         catch {
             /* invalid Origin */
         }
-        return oauthError("access_denied", "Cross-origin request rejected", 403);
+        return { error: "access_denied", description: "Cross-origin request rejected", status: 403 };
     }
     const referer = request.headers.get("Referer");
     if (referer) {
@@ -758,9 +1193,9 @@ function rejectCrossOrigin(request) {
         catch {
             /* invalid Referer */
         }
-        return oauthError("access_denied", "Cross-origin request rejected", 403);
+        return { error: "access_denied", description: "Cross-origin request rejected", status: 403 };
     }
-    return oauthError("access_denied", "Missing Origin", 403);
+    return { error: "access_denied", description: "Missing Origin", status: 403 };
 }
 async function s256Challenge(verifier) {
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));