- **Use helper scripts**:

- `./coderd/database/migrations/create_migration.sh "migration name"` - Creates new migration files

- `./coderd/database/migrations/fix_migration_numbers.sh` - Renumbers migrations to avoid conflicts

- `./coderd/database/migrations/create_fixture.sh "fixture name"` - Creates test fixtures for migrations

### In-Memory Database Testing

When adding new database fields:

- **CRITICAL**: Update `coderd/database/dbmem/dbmem.go` in-memory implementations

- The `Insert*` functions must include ALL new fields, not just basic ones

- Common issue: Tests pass with real database but fail with in-memory database due to missing field mappings

- Always verify in-memory database functions match the real database schema after migrations

Example pattern:

6. **RFC 8707 Resource Indicators**:

- Store resource parameters in database for server-side validation (opaque tokens)

- Validate resource consistency between authorization and token requests

- Support audience validation in refresh token flows

- Resource parameter is optional but must be consistent when provided

7. **OAuth2 tests failing but scripts working** - Check in-memory database implementations in `dbmem.go`

8. **Resource indicator validation failing** - Ensure database stores and retrieves resource parameters correctly

9. **PKCE tests failing** - Verify both authorization code storage and token exchange handle PKCE fields

Logger: options.Logger,

Logger: options.Logger,

Logger: options.Logger,

func (q *querier) GetOAuth2ProviderAppTokenByAPIKeyID(ctx context.Context, apiKeyID string) (database.OAuth2ProviderAppToken, error) {

token, err := q.db.GetOAuth2ProviderAppTokenByAPIKeyID(ctx, apiKeyID)

if err != nil {

return database.OAuth2ProviderAppToken{}, err

}

// Get the associated API key to check ownership

apiKey, err := q.db.GetAPIKeyByID(ctx, token.APIKeyID)

if err != nil {

return database.OAuth2ProviderAppToken{}, err

}

if err := q.authorizeContext(ctx, policy.ActionRead, rbac.ResourceOauth2AppCodeToken.WithOwner(apiKey.UserID.String())); err != nil {

return database.OAuth2ProviderAppToken{}, err

}

return token, nil

}

s.Run("GetOAuth2ProviderAppTokenByAPIKeyID", s.Subtest(func(db database.Store, check *expects) {

user := dbgen.User(s.T(), db, database.User{})

key, _ := dbgen.APIKey(s.T(), db, database.APIKey{

UserID: user.ID,

})

app := dbgen.OAuth2ProviderApp(s.T(), db, database.OAuth2ProviderApp{})

secret := dbgen.OAuth2ProviderAppSecret(s.T(), db, database.OAuth2ProviderAppSecret{

AppID: app.ID,

})

token := dbgen.OAuth2ProviderAppToken(s.T(), db, database.OAuth2ProviderAppToken{

AppSecretID: secret.ID,

APIKeyID: key.ID,

})

check.Args(token.APIKeyID).Asserts(rbac.ResourceOauth2AppCodeToken.WithOwner(user.ID.String()), policy.ActionRead).Returns(token)

}))

func (q *FakeQuerier) GetOAuth2ProviderAppTokenByAPIKeyID(_ context.Context, apiKeyID string) (database.OAuth2ProviderAppToken, error) {

q.mutex.Lock()

defer q.mutex.Unlock()

for _, token := range q.oauth2ProviderAppTokens {

if token.APIKeyID == apiKeyID {

return token, nil

}

}

return database.OAuth2ProviderAppToken{}, sql.ErrNoRows

}

SELECT * FROM oauth2_provider_app_tokens WHERE api_key_id = $1;

"cdr.dev/slog"

// Logger is used for logging middleware operations.

Logger slog.Logger

// Validate OAuth2 provider app token audience (RFC 8707) if applicable

if key.LoginType == database.LoginTypeOAuth2ProviderApp {

if err := validateOAuth2ProviderAppTokenAudience(ctx, cfg.DB, *key, r); err != nil {

// Log the detailed error for debugging but don't expose it to the client

cfg.Logger.Info(ctx, "oauth2 token audience validation failed", slog.Error(err))

return optionalWrite(http.StatusForbidden, codersdk.Response{

Message: "Token audience validation failed",

})

}

}

func validateOAuth2ProviderAppTokenAudience(ctx context.Context, db database.Store, key database.APIKey, r *http.Request) error {

// Get the OAuth2 provider app token to check its audience

//nolint:gocritic // System needs to access token for audience validation

token, err := db.GetOAuth2ProviderAppTokenByAPIKeyID(dbauthz.AsSystemRestricted(ctx), key.ID)

if err != nil {

return xerrors.Errorf("failed to get OAuth2 token: %w", err)

}

// If no audience is set, allow the request (for backward compatibility)

if !token.Audience.Valid || token.Audience.String == "" {

return nil

}

// Extract the expected audience from the request

expectedAudience := extractExpectedAudience(r)

// Normalize both audience values for RFC 3986 compliant comparison

normalizedTokenAudience := normalizeAudienceURI(token.Audience.String)

normalizedExpectedAudience := normalizeAudienceURI(expectedAudience)

// Validate that the token's audience matches the expected audience

if normalizedTokenAudience != normalizedExpectedAudience {

return xerrors.Errorf("token audience %q does not match expected audience %q",

token.Audience.String, expectedAudience)

}

return nil

}

func normalizeAudienceURI(audienceURI string) string {

if audienceURI == "" {

return ""

}

u, err := url.Parse(audienceURI)

if err != nil {

// If parsing fails, return as-is to avoid breaking existing functionality

return audienceURI

}

// Apply RFC 3986 syntax-based normalization:

// 1. Scheme and host are case-insensitive

u.Scheme = strings.ToLower(u.Scheme)

u.Host = strings.ToLower(u.Host)

// 2. Remove default ports for HTTP/HTTPS

if (u.Scheme == "http" && strings.HasSuffix(u.Host, ":80")) ||

(u.Scheme == "https" && strings.HasSuffix(u.Host, ":443")) {

// Extract host without default port

if idx := strings.LastIndex(u.Host, ":"); idx > 0 {

u.Host = u.Host[:idx]

}

}

// 3. Path normalization:

// - For OAuth2 audience URIs, we normalize trailing slashes for consistency

// - RFC 8707 recommends specific URIs, so trailing slash handling is important

// - According to RFC 3986, paths are case-sensitive, so we don't change case

if u.Path == "" {

// If no path is specified, use "/" for consistency with RFC 8707 examples

u.Path = "/"

}

// Remove trailing slash from paths longer than "/" to normalize

if len(u.Path) > 1 && strings.HasSuffix(u.Path, "/") {

u.Path = strings.TrimSuffix(u.Path, "/")

}

// 4. Remove fragment (OAuth2 audience should not have fragments anyway)

u.Fragment = ""

// 5. Keep query parameters as-is (rarely used in audience URIs but preserved for compatibility)

return u.String()

}

func NormalizeAudienceURIForTest(uri string) string {

return normalizeAudienceURI(uri)

}

func ExtractExpectedAudienceForTest(r *http.Request) string {

return extractExpectedAudience(r)

}

func extractExpectedAudience(r *http.Request) string {

// For MCP compliance, the audience should be the canonical URI of the resource server

// This typically matches the access URL of the Coder deployment

scheme := "https"

if r.TLS == nil {

scheme = "http"

}

// Use the Host header to construct the canonical audience URI

audience := fmt.Sprintf("%s://%s", scheme, r.Host)

// Normalize the URI according to RFC 3986 for consistent comparison

return normalizeAudienceURI(audience)

}