ADR 019 password rotation (#523)

* ADR 019 Password Rotation

neo4j/auth/auth.go

@@ -21,7 +21,9 @@ package auth
 
 import (
 	"context"
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j/db"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/auth"
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/collections"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/racing"
 	"reflect"
 	"time"
@@ -51,25 +53,29 @@ type TokenManager interface {
 	// The token returned must always belong to the same identity.
 	// Switching identities using the `TokenManager` is undefined behavior.
 	GetAuthToken(ctx context.Context) (auth.Token, error)
-	// OnTokenExpired is called by the driver when the provided token expires
-	// OnTokenExpired should invalidate the current token if it matches the provided one
-	OnTokenExpired(context.Context, auth.Token) error
+
+	// HandleSecurityException is called when the server returns any `Neo.ClientError.Security.*` error.
+	// It should return true if the error was handled, in which case the driver will mark the error as retryable.
+	HandleSecurityException(context.Context, auth.Token, *db.Neo4jError) (bool, error)
 }
 
+type authTokenProvider = func(context.Context) (auth.Token, error)
+
 type authTokenWithExpirationProvider = func(context.Context) (auth.Token, *time.Time, error)
 
-type expirationBasedTokenManager struct {
-	provider   authTokenWithExpirationProvider
-	token      *auth.Token
-	expiration *time.Time
-	mutex      racing.Mutex
-	now        *func() time.Time
+type neo4jAuthTokenManager struct {
+	provider             authTokenWithExpirationProvider
+	token                *auth.Token
+	expiration           *time.Time
+	mutex                racing.Mutex
+	now                  *func() time.Time
+	handledSecurityCodes collections.Set[string]
 }
 
-func (m *expirationBasedTokenManager) GetAuthToken(ctx context.Context) (auth.Token, error) {
+func (m *neo4jAuthTokenManager) GetAuthToken(ctx context.Context) (auth.Token, error) {
 	if !m.mutex.TryLock(ctx) {
 		return auth.Token{}, racing.LockTimeoutError(
-			"could not acquire lock in time when getting token in ExpirationBasedTokenManager")
+			"could not acquire lock in time when getting token in neo4jAuthTokenManager")
 	}
 	defer m.mutex.Unlock()
 	if m.token == nil || m.expiration != nil && (*m.now)().After(*m.expiration) {
@@ -83,34 +89,78 @@ func (m *expirationBasedTokenManager) GetAuthToken(ctx context.Context) (auth.To
 	return *m.token, nil
 }
 
-func (m *expirationBasedTokenManager) OnTokenExpired(ctx context.Context, token auth.Token) error {
+func (m *neo4jAuthTokenManager) HandleSecurityException(ctx context.Context, token auth.Token, securityException *db.Neo4jError) (bool, error) {
+	if !m.handledSecurityCodes.Contains(securityException.Code) {
+		return false, nil
+	}
 	if !m.mutex.TryLock(ctx) {
-		return racing.LockTimeoutError(
-			"could not acquire lock in time when handling token expiration in ExpirationBasedTokenManager")
+		return false, racing.LockTimeoutError(
+			"could not acquire lock in time when handling security exception in neo4jAuthTokenManager")
 	}
 	defer m.mutex.Unlock()
 	if m.token != nil && reflect.DeepEqual(token.Tokens, m.token.Tokens) {
 		m.token = nil
 	}
-	return nil
+	return true, nil
 }
 
-// ExpirationBasedTokenManager creates a token manager for potentially expiring auth info.
+// BasicTokenManager generates a TokenManager to manage basic auth password rotation.
+// The provider is invoked solely when a new token instance is required, triggered by server
+// rejection of the current token due to an authentication exception.
+//
+// WARNING:
 //
-// The first and only argument is a provider function that returns auth information and an optional expiration time.
-// If the expiration time is nil, the auth info is assumed to never expire.
+// The provider function *must not* interact with the driver in any way as this can cause deadlocks and undefined
+// behaviour.
+//
+// The provider function must only ever return auth information belonging to the same identity.
+// Switching identities is undefined behavior.
+//
+// BasicTokenManager is part of the re-authentication preview feature
+// (see README on what it means in terms of support and compatibility guarantees)
+func BasicTokenManager(provider authTokenProvider) TokenManager {
+	now := time.Now
+	return &neo4jAuthTokenManager{
+		provider: wrapWithNilExpiration(provider),
+		mutex:    racing.NewMutex(),
+		now:      &now,
+		handledSecurityCodes: collections.NewSet([]string{
+			"Neo.ClientError.Security.Unauthorized",
+		}),
+	}
+}
+
+// BearerTokenManager generates a TokenManager to manage possibly expiring authentication details.
+//
+// The provider is invoked when a new token instance is required, triggered by server
+// rejection of the current token due to authentication or token expiration exceptions.
 //
 // WARNING:
 //
-//	The provider function *must not* interact with the driver in any way as this can cause deadlocks and undefined
-//	behaviour.
+// The provider function *must not* interact with the driver in any way as this can cause deadlocks and undefined
+// behaviour.
 //
-//	The provider function only ever return auth information belonging to the same identity.
-//	Switching identities is undefined behavior.
+// The provider function must only ever return auth information belonging to the same identity.
+// Switching identities is undefined behavior.
 //
-// ExpirationBasedTokenManager is part of the re-authentication preview feature
+// BearerTokenManager is part of the re-authentication preview feature
 // (see README on what it means in terms of support and compatibility guarantees)
-func ExpirationBasedTokenManager(provider authTokenWithExpirationProvider) TokenManager {
+func BearerTokenManager(provider authTokenWithExpirationProvider) TokenManager {
 	now := time.Now
-	return &expirationBasedTokenManager{provider: provider, mutex: racing.NewMutex(), now: &now}
+	return &neo4jAuthTokenManager{
+		provider: provider,
+		mutex:    racing.NewMutex(),
+		now:      &now,
+		handledSecurityCodes: collections.NewSet([]string{
+			"Neo.ClientError.Security.TokenExpired",
+			"Neo.ClientError.Security.Unauthorized",
+		}),
+	}
+}
+
+func wrapWithNilExpiration(provider authTokenProvider) authTokenWithExpirationProvider {
+	return func(ctx context.Context) (auth.Token, *time.Time, error) {
+		token, err := provider(ctx)
+		return token, nil, err
+	}
 }

neo4j/auth/auth_examples_test.go

@@ -28,23 +28,41 @@ import (
 	"time"
 )
 
-func ExampleExpirationBasedTokenManager() {
-	myProvider := func(ctx context.Context) (neo4j.AuthToken, *time.Time, error) {
-		// some way to getting a token
+func ExampleBasicTokenManager() {
+	fetchBasicAuthToken := func(ctx context.Context) (neo4j.AuthToken, error) {
+		// some way of getting basic authentication information
+		username, password, realm, err := getBasicAuth()
+		if err != nil {
+			return neo4j.AuthToken{}, err
+		}
+		// create and return a basic authentication token with provided username, password and realm
+		return neo4j.BasicAuth(username, password, realm), nil
+	}
+	// create a new driver with a basic token manager which uses provider to handle basic auth password rotation.
+	_, _ = neo4j.NewDriverWithContext(getUrl(), auth.BasicTokenManager(fetchBasicAuthToken))
+}
+
+func ExampleBearerTokenManager() {
+	fetchAuthTokenFromMyProvider := func(ctx context.Context) (neo4j.AuthToken, *time.Time, error) {
+		// some way of getting a token
 		token, err := getSsoToken(ctx)
 		if err != nil {
 			return neo4j.AuthToken{}, nil, err
 		}
 		// assume we know our tokens expire every 60 seconds
-
 		expiresIn := time.Now().Add(60 * time.Second)
 		// Include a little buffer so that we fetch a new token *before* the old one expires
 		expiresIn = expiresIn.Add(-10 * time.Second)
 		// or return nil instead of `&expiresIn` if we don't expect it to expire
 		return token, &expiresIn, nil
 	}
+	// create a new driver with a bearer token manager which uses provider to handle possibly expiring auth tokens.
+	_, _ = neo4j.NewDriverWithContext(getUrl(), auth.BearerTokenManager(fetchAuthTokenFromMyProvider))
+}
 
-	_, _ = neo4j.NewDriverWithContext(getUrl(), auth.ExpirationBasedTokenManager(myProvider))
+func getBasicAuth() (username, password, realm string, error error) {
+	username, password, realm = "username", "password", "realm"
+	return
 }
 
 func getSsoToken(context.Context) (neo4j.AuthToken, error) {

neo4j/auth/auth_testkit.go

@@ -1,3 +1,5 @@
+//go:build internal_testkit
+
 /*
  * Copyright (c) "Neo4j"
  * Neo4j Sweden AB [https://neo4j.com]
@@ -17,20 +19,18 @@
  * limitations under the License.
  */
 
-//go:build internal_testkit
-
 package auth
 
 import "time"
 
 func SetTimer(t TokenManager, timer func() time.Time) {
-	if t, ok := t.(*expirationBasedTokenManager); ok {
+	if t, ok := t.(*neo4jAuthTokenManager); ok {
 		t.now = &timer
 	}
 }
 
 func ResetTime(t TokenManager) {
-	if t, ok := t.(*expirationBasedTokenManager); ok {
+	if t, ok := t.(*neo4jAuthTokenManager); ok {
 		now := time.Now
 		t.now = &now
 	}

neo4j/db/errors.go

@@ -88,6 +88,10 @@ func (e *Neo4jError) reclassify() {
 	}
 }
 
+func (e *Neo4jError) HasSecurityCode() bool {
+	return strings.HasPrefix(e.Code, "Neo.ClientError.Security.")
+}
+
 func (e *Neo4jError) IsAuthenticationFailed() bool {
 	return e.Code == "Neo.ClientError.Security.Unauthorized"
 }

neo4j/internal/auth/auth.go

@@ -19,7 +19,10 @@
 
 package auth
 
-import "context"
+import (
+	"context"
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j/db"
+)
 
 type Token struct {
 	Tokens map[string]any
@@ -29,4 +32,6 @@ func (a Token) GetAuthToken(context.Context) (Token, error) {
 	return a, nil
 }
 
-func (a Token) OnTokenExpired(context.Context, Token) error { return nil }
+func (a Token) HandleSecurityException(context.Context, Token, *db.Neo4jError) (bool, error) {
+	return false, nil
+}

neo4j/internal/collections/set.go

@@ -73,3 +73,8 @@ func (set Set[T]) Copy() Set[T] {
 	}
 	return result
 }
+
+func (set Set[T]) Contains(value T) bool {
+	_, ok := set[value]
+	return ok
+}

neo4j/internal/collections/set_test.go

@@ -147,6 +147,28 @@ func TestSet(outer *testing.T) {
 			t.Error(err)
 		}
 	})
+
+	outer.Run("contains", func(t *testing.T) {
+		strings := collections.NewSet([]string{
+			"golang",
+			"neo4j",
+		})
+		expected := "golang"
+		if found := strings.Contains(expected); !found {
+			t.Errorf("Set should have contained %v", expected)
+		}
+	})
+
+	outer.Run("does not contain", func(t *testing.T) {
+		strings := collections.NewSet([]string{
+			"golang",
+			"neo4j",
+		})
+		expected := "foobar"
+		if found := strings.Contains(expected); found {
+			t.Errorf("Set should not have contain %v", expected)
+		}
+	})
 }
 
 func containsExactlyOnce[T comparable](values collections.Set[T], search T) bool {

neo4j/internal/pool/pool.go

@@ -27,7 +27,6 @@ import (
 	"context"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/config"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/db"
-	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/auth"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/bolt"
 	idb "github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/db"
 	"github.com/neo4j/neo4j-go-driver/v5/neo4j/internal/errorutil"
@@ -453,35 +452,36 @@ func (p *Pool) Return(ctx context.Context, c idb.Connection) {
 }
 
 func (p *Pool) OnNeo4jError(ctx context.Context, connection idb.Connection, error *db.Neo4jError) error {
-	switch error.Code {
-	case "Neo.ClientError.Security.AuthorizationExpired":
+	if error.Code == "Neo.ClientError.Security.AuthorizationExpired" {
 		serverName := connection.ServerName()
 		p.serversMut.Lock()
 		defer p.serversMut.Unlock()
 		server := p.servers[serverName]
 		server.executeForAllConnections(func(c idb.Connection) {
 			c.ResetAuth()
 		})
-	case "Neo.ClientError.Security.TokenExpired":
+	}
+	if error.Code == "Neo.TransientError.General.DatabaseUnavailable" {
+		p.deactivate(ctx, connection.ServerName())
+	}
+	if error.IsRetriableCluster() {
+		var database string
+		if dbSelector, ok := connection.(idb.DatabaseSelector); ok {
+			database = dbSelector.Database()
+		}
+		p.deactivateWriter(connection.ServerName(), database)
+	}
+	if error.HasSecurityCode() {
 		manager, token := connection.GetCurrentAuth()
 		if manager != nil {
-			if err := manager.OnTokenExpired(ctx, token); err != nil {
+			handled, err := manager.HandleSecurityException(ctx, token, error)
+			if err != nil {
 				return err
 			}
-			if _, isStaticToken := manager.(auth.Token); !isStaticToken {
+			if handled {
 				error.MarkRetriable()
 			}
 		}
-	case "Neo.TransientError.General.DatabaseUnavailable":
-		p.deactivate(ctx, connection.ServerName())
-	default:
-		if error.IsRetriableCluster() {
-			var database string
-			if dbSelector, ok := connection.(idb.DatabaseSelector); ok {
-				database = dbSelector.Database()
-			}
-			p.deactivateWriter(connection.ServerName(), database)
-		}
 	}
 
 	return nil