feat(oauth): implement RFC 8707 Resource Indicators

[EsTharian]

Summary

Adds resource parameter support to /oauth/authorize and /oauth/token (all three grants), with persistence through the authorization code → refresh token → access token's aud claim.

Without this, dynamically-registered public clients (audience=null) were minting tokens with aud=<client_id> (a random UUID), which resource servers like majordomo's memory-mcp correctly rejected. RFC 8707 is the spec-compliant fix: the client names the resource, the AS binds the grant to it, and the issued access token's aud is the resource URI.

Changes

• Schemas: add optional resource (single URI or array, ≤10 entries, absolute URI, no fragment, ≤2048 chars) to authorizeQuerySchema, all three token grant body schemas
• DB migration 0003_rfc8707_resource_indicators.sql: adds resource jsonb NOT NULL DEFAULT '[]' to authorization_codes and refresh_tokens. Drizzle schema + snapshot regenerated
• authorize.ts: persist resource onto the auth code
• token.ts (authorization_code): read code.resource; request narrowing must be a subset (else invalid_target); use as aud; carry onto issued refresh token
• token.ts (client_credentials): accept body.resource; use as aud (overrides client.audience when present)
• token.ts (refresh_token): read storedToken.resource; request narrowing must be a subset; rotated refresh token inherits the effective (not requested) binding — we never widen across a rotation
• resolveAudience: new optional resource param precedence: resource > client.audience > clientId
• well-known: advertise resource_indicators_supported: true per RFC 8707 §3

Backward compatibility

Clients that don't send resource are unaffected — empty array falls back to client.audience / clientId as before. Pre-seeded machine clients (config/qauth/clients.json) keep working without any change.

Test plan

• authorize.test: persists resource onto the auth code row
• token.test (authorization_code): aud = resource; narrowing outside the code's binding → InvalidGrantError
• token.test (refresh_token): resource carries across rotation; narrowing outside stored binding → InvalidGrantError
• All 169 auth-server tests pass locally
• End-to-end: Claude Code's dyn-reg browser flow issues a token with aud=https://mcp.naqshi.net/mcp; memory-mcp accepts it once its EXPECTED_AUD is flipped to the resource URL (separate majordomo PR)

🤖 Generated with Claude Code

[nx-cloud]

View your CI Pipeline Execution ↗ for commit c675b66

Command	Status	Duration	Result
nx affected -t lint test build	✅ Succeeded	3s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-04-24 18:46:46 UTC

[gemini-code-assist]

Code Review

This pull request implements RFC 8707 Resource Indicators, allowing clients to specify intended audiences for access tokens. Key changes include updating authorization and token routes to persist and validate resource parameters, advertising support in discovery metadata, and performing database migrations. The review feedback identifies a security vulnerability in the client credentials grant regarding resource validation, suggests including user IDs in audit logs for better traceability, and notes that error responses must use the invalid_target code to comply with the specification.

[gemini-code-assist]

For the client_credentials grant, the requested resource must be validated against the client's pre-configured audience allowlist (client.audience). Currently, any requested resource is accepted and used as the token's audience, which could allow a machine client to escalate its access to unauthorized resource servers. If client.audience is configured, the request must be a subset of it; otherwise, it should default to the client's own ID.

  const requestedResource = body.resource ?? [];
  if (requestedResource.length > 0) {
    const allowedAudience = client.audience ?? [client.clientId];
    const extra = requestedResource.filter((r) => !allowedAudience.includes(r));
    if (extra.length > 0) {
      await fastify.repositories.auditLogs.create({
        userId: null,
        oauthClientId: client.id,
        event: 'oauth.token.exchange.failure',
        eventType: 'token',
        success: false,
        ipAddress: request.ip,
        userAgent: request.headers['user-agent'] || null,
        metadata: {
          error: 'invalid_target: resource outside the client audience allowlist',
          extra,
        },
      });
      throw new BadRequestError('invalid_target');
    }
  }

[gemini-code-assist]

The audit log for a resource indicator validation failure should include the userId associated with the authorization code to provide a complete audit trail. We already have access to authCode.userId at this point in the handler.

Suggested change

	await fastify.repositories.auditLogs.create({
	userId: null,
	oauthClientId: client.id,
	event: 'oauth.token.exchange.failure',
	eventType: 'token',
	success: false,
	ipAddress: request.ip,
	userAgent: request.headers['user-agent'] || null,
	metadata: {
	error: 'invalid_target: resource outside the authorization-code binding',
	extra,
	},
	});
	await fastify.repositories.auditLogs.create({
	userId: authCode.userId,
	oauthClientId: client.id,
	event: 'oauth.token.exchange.failure',
	eventType: 'token',
	success: false,
	ipAddress: request.ip,
	userAgent: request.headers['user-agent'] || null,
	metadata: {
	error: 'invalid_target: resource outside the authorization-code binding',
	extra,
	},
	});

[gemini-code-assist]

RFC 8707 §2.2 requires the error code invalid_target when a requested resource is invalid or unauthorized. Using InvalidGrantError will likely result in an invalid_grant error code being returned to the client, which violates the specification. Please use BadRequestError('invalid_target') or a specific error class that maps to the correct OAuth error code.

Suggested change

	throw new InvalidGrantError('invalid_target');
	throw new BadRequestError('invalid_target');

[gemini-code-assist]

Similar to the authorization code exchange, a refresh token request that fails resource indicator validation must return the invalid_target error code per RFC 8707 §2.2. InvalidGrantError typically maps to invalid_grant.

Suggested change

	throw new InvalidGrantError('invalid_target');
	throw new BadRequestError('invalid_target');