coder · BobbyHo · Sep 11, 2026 · Aug 14, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -2136,6 +2136,10 @@ func (q *querier) DeleteAPIKeyByID(ctx context.Context, id string) error {
 	return deleteQ(q.log, q.auth, q.db.GetAPIKeyByID, q.db.DeleteAPIKeyByID)(ctx, id)
 }
 
+func (q *querier) DeleteAPIKeyByIDReturningRow(ctx context.Context, id string) (database.APIKey, error) {
+	return fetchAndQuery(q.log, q.auth, policy.ActionDelete, q.db.GetAPIKeyByID, q.db.DeleteAPIKeyByIDReturningRow)(ctx, id)
+}
+
 func (q *querier) DeleteAPIKeysByUserID(ctx context.Context, userID uuid.UUID) error {
 	// TODO: This is not 100% correct because it omits apikey IDs.
 	err := q.authorizeContext(ctx, policy.ActionDelete,

diff --git a/coderd/database/dbauthz/dbauthz_test.go b/coderd/database/dbauthz/dbauthz_test.go
@@ -84,6 +84,40 @@ func TestPing(t *testing.T) {
 	require.NoError(t, err, "must not error")
 }
 
+// TestSingleUseDeleteNotFound pins that a fetch-then-query wrapper whose
+// fetch finds nothing returns an error that still matches sql.ErrNoRows, and
+// never reaches the query. The OAuth2 grants rely on both to answer
+// invalid_grant when a single-use delete finds its row already gone.
+func TestSingleUseDeleteNotFound(t *testing.T) {
+	t.Parallel()
+
+	ctx := dbauthz.As(context.Background(), coderdtest.RandomRBACSubject())
+	newQuerier := func(t *testing.T) (*dbmock.MockStore, database.Store) {
+		db := dbmock.NewMockStore(gomock.NewController(t))
+		db.EXPECT().Wrappers().Return([]string{}).AnyTimes()
+		return db, dbauthz.New(db, &coderdtest.RecordingAuthorizer{}, slog.Make(), coderdtest.AccessControlStorePointer())
+	}
+
+	t.Run("DeleteAPIKeyByIDReturningRow", func(t *testing.T) {
+		t.Parallel()
+		db, q := newQuerier(t)
+		db.EXPECT().GetAPIKeyByID(gomock.Any(), "gone").Return(database.APIKey{}, sql.ErrNoRows)
+
+		_, err := q.DeleteAPIKeyByIDReturningRow(ctx, "gone")
+		require.ErrorIs(t, err, sql.ErrNoRows)
+	})
+
+	t.Run("DeleteOAuth2ProviderAppCodeByID", func(t *testing.T) {
+		t.Parallel()
+		db, q := newQuerier(t)
+		id := uuid.New()
+		db.EXPECT().GetOAuth2ProviderAppCodeByID(gomock.Any(), id).Return(database.OAuth2ProviderAppCode{}, sql.ErrNoRows)
+
+		_, err := q.DeleteOAuth2ProviderAppCodeByID(ctx, id)
+		require.ErrorIs(t, err, sql.ErrNoRows)
+	})
+}
+
 // TestInTX is not perfect, just checks that it properly checks auth.
 func TestInTX(t *testing.T) {
 	t.Parallel()
@@ -459,6 +493,12 @@ func (s *MethodTestSuite) TestAPIKey() {
 		dbm.EXPECT().DeleteAPIKeyByID(gomock.Any(), key.ID).Return(nil).AnyTimes()
 		check.Args(key.ID).Asserts(key, policy.ActionDelete).Returns()
 	}))
+	s.Run("DeleteAPIKeyByIDReturningRow", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
+		key := testutil.Fake(s.T(), faker, database.APIKey{})
+		dbm.EXPECT().GetAPIKeyByID(gomock.Any(), key.ID).Return(key, nil).AnyTimes()
+		dbm.EXPECT().DeleteAPIKeyByIDReturningRow(gomock.Any(), key.ID).Return(key, nil).AnyTimes()
+		check.Args(key.ID).Asserts(key, policy.ActionDelete).Returns(key)
+	}))
 	s.Run("DeleteExpiredAPIKeys", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
 		args := database.DeleteExpiredAPIKeysParams{
 			Before:     time.Date(2025, 11, 21, 0, 0, 0, 0, time.UTC),

diff --git a/coderd/database/dbmetrics/querymetrics.go b/coderd/database/dbmetrics/querymetrics.go
diff --git a/coderd/database/dbmock/dbmock.go b/coderd/database/dbmock/dbmock.go
diff --git a/coderd/database/querier.go b/coderd/database/querier.go
diff --git a/coderd/database/querier_test.go b/coderd/database/querier_test.go
@@ -19678,6 +19678,22 @@ func TestSingleUseDelete(t *testing.T) {
 		_, err = db.DeleteOAuth2ProviderAppCodeByID(ctx, code.ID)
 		require.ErrorIs(t, err, sql.ErrNoRows)
 	})
+
+	t.Run("APIKey", func(t *testing.T) {
+		t.Parallel()
+		db, _ := dbtestutil.NewDB(t)
+		ctx := testutil.Context(t, testutil.WaitLong)
+
+		user := dbgen.User(t, db, database.User{})
+		key, _ := dbgen.APIKey(t, db, database.APIKey{UserID: user.ID})
+
+		deleted, err := db.DeleteAPIKeyByIDReturningRow(ctx, key.ID)
+		require.NoError(t, err)
+		require.Equal(t, key, deleted)
+
+		_, err = db.DeleteAPIKeyByIDReturningRow(ctx, key.ID)
+		require.ErrorIs(t, err, sql.ErrNoRows)
+	})
 }
 
 func TestGetUnpricedAIModelsSince(t *testing.T) {

diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/apikeys.sql b/coderd/database/queries/apikeys.sql
@@ -92,6 +92,20 @@ DELETE FROM
 WHERE
 	id = $1;
 
+-- name: DeleteAPIKeyByIDReturningRow :one
+-- Returns sql.ErrNoRows when the delete removed nothing, so a caller can make
+-- this the arbiter of single use. A prior read cannot arbitrate: its result is
+-- stale the moment it returns.
+--
+-- Concurrent deletes are arbitrated at READ COMMITTED, the default isolation
+-- level: the second transaction waits for the first, then removes nothing.
+-- SERIALIZABLE would abort and retry it instead.
+DELETE FROM
+	api_keys
+WHERE
+	id = $1
+RETURNING *;
+
 -- name: DeleteApplicationConnectAPIKeysByUserID :exec
 DELETE FROM
 	api_keys

diff --git a/coderd/oauth2provider/tokens.go b/coderd/oauth2provider/tokens.go
@@ -138,7 +138,9 @@ func narrowAccessScope(ctx context.Context, logger slog.Logger, phase string, ap
 func scopeStringToAPIKeyScopes(scope string) (database.APIKeyScopes, error) {
 	names := strings.Fields(scope)
 	if len(names) == 0 {
-		return nil, xerrors.Errorf("'%s': %w", scope, errUnmintableScope)
+		// Fixed message rather than an echo: CHECK (scope <> '') admits a
+		// whitespace-only value, which names nothing worth reporting back.
+		return nil, xerrors.Errorf("the grant names no scope: %w", errUnmintableScope)
 	}
 
 	scopes := make(database.APIKeyScopes, 0, len(names))
@@ -411,6 +413,14 @@ func revokeOAuth2CodeOnPKCEFailure(ctx context.Context, db database.Store, codeI
 	}
 }
 
+// singleUseTxOptions names the isolation level the single-use deletes need.
+// At READ COMMITTED a second delete waits for the first to commit and then
+// removes nothing; higher levels raise a serialization error instead.
+// Built per call because InTx writes to the options it receives.
+func singleUseTxOptions() *database.TxOptions {
+	return &database.TxOptions{Isolation: sql.LevelReadCommitted}
+}
+
 func authorizationCodeGrant(ctx context.Context, db database.Store, logger slog.Logger, app database.OAuth2ProviderApp, lifetimes codersdk.SessionLifetime, req codersdk.OAuth2TokenRequest) (codersdk.OAuth2TokenResponse, error) {
 	// A public client has no secret to validate, and its token references
 	// none. PKCE and the dbCode.AppID check are what bind the exchange to the
@@ -585,6 +595,8 @@ func authorizationCodeGrant(ctx context.Context, db database.Store, logger slog.
 		// token, so a later failure leaves the code redeemable.
 		_, err := tx.DeleteOAuth2ProviderAppCodeByID(ctx, dbCode.ID)
 		if errors.Is(err, sql.ErrNoRows) {
+			logger.Warn(ctx, "oauth2 code redemption refused: code already used",
+				slog.F("app_id", app.ID), slog.F("code_id", dbCode.ID))
 			return errBadCode
 		}
 		if err != nil {
@@ -625,7 +637,7 @@ func authorizationCodeGrant(ctx context.Context, db database.Store, logger slog.
 			return xerrors.Errorf("insert oauth2 refresh token: %w", err)
 		}
 		return nil
-	}, nil)
+	}, singleUseTxOptions())
 	if err != nil {
 		return codersdk.OAuth2TokenResponse{}, err
 	}
@@ -687,15 +699,10 @@ func refreshTokenGrant(ctx context.Context, db database.Store, logger slog.Logge
 		return codersdk.OAuth2TokenResponse{}, err
 	}
 
-	// Grab the user roles so we can perform the refresh as the user.
-	//nolint:gocritic // OAuth2 system context, need to read the previous API key
-	prevKey, err := db.GetAPIKeyByID(dbauthz.AsSystemOAuth2(ctx), dbToken.APIKeyID)
-	if err != nil {
-		return codersdk.OAuth2TokenResponse{}, err
-	}
-
+	// The token row carries the user id, so the previous key is not read
+	// before the delete below decides which of two refreshes proceeds.
 	// ScopeAll for the same reason as in authorizationCodeGrant.
-	actor, _, err := httpmw.UserRBACSubject(ctx, db, prevKey.UserID, rbac.ScopeAll)
+	actor, _, err := httpmw.UserRBACSubject(ctx, db, dbToken.UserID, rbac.ScopeAll)
 	if err != nil {
 		return codersdk.OAuth2TokenResponse{}, xerrors.Errorf("fetch user actor: %w", err)
 	}
@@ -712,9 +719,9 @@ func refreshTokenGrant(ctx context.Context, db database.Store, logger slog.Logge
 	}
 
 	// Generate the new API key.
-	tokenName := fmt.Sprintf("%s_%s_oauth_session_token", prevKey.UserID, app.ID)
+	tokenName := fmt.Sprintf("%s_%s_oauth_session_token", dbToken.UserID, app.ID)
 	key, sessionToken, err := apikey.Generate(apikey.CreateParams{
-		UserID:          prevKey.UserID,
+		UserID:          dbToken.UserID,
 		LoginType:       database.LoginTypeOAuth2ProviderApp,
 		DefaultLifetime: lifetimes.DefaultDuration.Value(),
 		Scopes:          scopes,
@@ -735,7 +742,18 @@ func refreshTokenGrant(ctx context.Context, db database.Store, logger slog.Logge
 
 	err = db.InTx(func(tx database.Store) error {
 		ctx := dbauthz.As(ctx, actor)
-		err = tx.DeleteAPIKeyByID(ctx, prevKey.ID) // This cascades to the token.
+		// RFC 6749 §10.4: the presented refresh token is invalidated so that a
+		// second use of it can be detected. Only one of two concurrent
+		// refreshes can delete this row; the other waits for this transaction
+		// to commit, finds nothing, and is refused. A failure below rolls the
+		// delete back, so the old key stays usable.
+		_, err := tx.DeleteAPIKeyByIDReturningRow(ctx, dbToken.APIKeyID) // This cascades to the token.
+		if errors.Is(err, sql.ErrNoRows) {
+			// The one place a second use of a refresh token is visible.
+			logger.Warn(ctx, "oauth2 refresh refused: refresh token already used",
+				slog.F("app_id", app.ID), slog.F("api_key_id", dbToken.APIKeyID))
+			return errBadToken
+		}
 		if err != nil {
 			return xerrors.Errorf("delete oauth2 app token: %w", err)
 		}
@@ -766,7 +784,7 @@ func refreshTokenGrant(ctx context.Context, db database.Store, logger slog.Logge
 			return xerrors.Errorf("insert oauth2 refresh token: %w", err)
 		}
 		return nil
-	}, nil)
+	}, singleUseTxOptions())
 	if err != nil {
 		return codersdk.OAuth2TokenResponse{}, err
 	}

diff --git a/coderd/oauth2provider/tokens_internal_test.go b/coderd/oauth2provider/tokens_internal_test.go
@@ -80,12 +80,19 @@ func TestScopeStringToAPIKeyScopes(t *testing.T) {
 
 	// Unreachable through the NOT NULL column, but pinned: apikey.Generate reads
 	// an empty list as unrestricted, so anything but an error widens the grant.
+	// CHECK (scope <> '') admits every value here but the first.
 	t.Run("EmptyRejected", func(t *testing.T) {
 		t.Parallel()
 
-		for _, scope := range []string{"", "   "} {
+		var first string
+		for _, scope := range []string{"", "   ", "\t", "\n", " \t\r\n "} {
 			_, err := scopeStringToAPIKeyScopes(scope)
 			require.ErrorIs(t, err, errUnmintableScope, "scope %q", scope)
+			if first == "" {
+				first = err.Error()
+			}
+			assert.Equal(t, first, err.Error(),
+				"a scope naming nothing has nothing to echo, so the message cannot vary with it")
 		}
 	})
 }