bundle-server: introduce '--auth-config' web server option

Add an '--auth-config' flag to specify the path to a JSON file containing
information used to configure bundle server auth, as well as a function for
parsing the config. For now, no modes are configured, so attempting to pass
a value to the option will fail.

Update the 'git-bundle-web-server' manpage to describe the auth config and
its usage. Also add 'auth-config.md' technical documentation with more
detail around the schema of the auth config file. These will be updated as
new modes are introduced.

Signed-off-by: Victoria Dye <vdye@github.com>

Author: vdye

cmd/git-bundle-server/web-server.go

@@ -77,7 +77,11 @@ func (w *webServerCmd) startServer(ctx context.Context, args []string) error {
 	parser.Visit(func(f *flag.Flag) {
 		if webServerFlags.Lookup(f.Name) != nil {
 			value := f.Value.String()
-			if f.Name == "cert" || f.Name == "key" || f.Name == "client-ca" {
+			if f.Name == "cert" ||
+				f.Name == "key" ||
+				f.Name == "client-ca" ||
+				f.Name == "auth-config" {
+
 				// Need the absolute value of the path
 				value, err = filepath.Abs(value)
 				if err != nil {

cmd/git-bundle-web-server/main.go

@@ -2,15 +2,43 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"flag"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/git-ecosystem/git-bundle-server/cmd/utils"
 	"github.com/git-ecosystem/git-bundle-server/internal/argparse"
 	"github.com/git-ecosystem/git-bundle-server/internal/log"
+	"github.com/git-ecosystem/git-bundle-server/pkg/auth"
 )
 
+func parseAuthConfig(configPath string) (auth.AuthMiddleware, error) {
+	var config authConfig
+	fileBytes, err := os.ReadFile(configPath)
+	if err != nil {
+		return nil, err
+	}
+
+	err = json.Unmarshal(fileBytes, &config)
+	if err != nil {
+		return nil, err
+	}
+
+	switch strings.ToLower(config.AuthMode) {
+	default:
+		return nil, fmt.Errorf("unrecognized auth mode '%s'", config.AuthMode)
+	}
+}
+
+type authConfig struct {
+	AuthMode string `json:"mode"`
+
+	// Per-middleware custom config
+	Parameters json.RawMessage `json:"parameters,omitempty"`
+}
+
 func main() {
 	log.WithTraceLogger(context.Background(), func(ctx context.Context, logger log.TraceLogger) {
 		parser := argparse.NewArgParser(logger, "git-bundle-web-server [--port <port>] [--cert <filename> --key <filename>]")
@@ -28,9 +56,27 @@ func main() {
 		key := utils.GetFlagValue[string](parser, "key")
 		tlsMinVersion := utils.GetFlagValue[uint16](parser, "tls-version")
 		clientCA := utils.GetFlagValue[string](parser, "client-ca")
+		authConfig := utils.GetFlagValue[string](parser, "auth-config")
 
 		// Configure auth
+		var err error
 		middlewareAuthorize := authFunc(nil)
+		if authConfig != "" {
+			middleware, err := parseAuthConfig(authConfig)
+			if err != nil {
+				logger.Fatalf(ctx, "Invalid auth config: %w", err)
+			}
+			if middleware == nil {
+				// Up until this point, everything indicates that a user intends
+				// to use - and has properly configured - custom auth. However,
+				// despite there being no error from the initializer, the
+				// middleware was empty. This is almost certainly incorrect, so
+				// we exit.
+				logger.Fatalf(ctx, "Middleware is nil, but no error was returned from initializer. "+
+					"If no middleware is desired, remove the --auth-config option.")
+			}
+			middlewareAuthorize = middleware.Authorize
+		}
 
 		// Configure the server
 		bundleServer, err := NewBundleWebServer(logger,

cmd/utils/common-args.go

@@ -86,6 +86,7 @@ func WebServerFlags(parser argParser) (*flag.FlagSet, func(context.Context)) {
 	tlsVersion := tlsVersionValue(tls.VersionTLS12)
 	f.Var(&tlsVersion, "tls-version", "The minimum TLS version the server will accept")
 	f.String("client-ca", "", "The path to the client authentication certificate authority PEM")
+	f.String("auth-config", "", "File containing the configuration for server auth middleware")
 
 	// Function to call for additional arg validation (may exit with 'Usage()')
 	validationFunc := func(ctx context.Context) {

docs/man/git-bundle-web-server.adoc

@@ -27,6 +27,24 @@ web-server* for managing the web server process on their systems.
 
 include::server-options.asc[]
 
+== CONFIGURING AUTH
+
+The *--auth-config* option configures authentication middleware for the server,
+either using a built-in mode or with a custom plugin. The auth config specified
+by that option is a JSON file that identifies the type of access control
+requested and information needed to configure it.
+
+=== Schema
+
+The auth config JSON contains the following fields:
+
+*mode* (string)::
+  The auth mode to use. Not case-sensitive.
+
+*parameters* (object)::
+  A structure containing mode-specific key-value configuration fields, if
+  applicable. May be optional, depending on *mode*.
+
 == SEE ALSO
 
 man:git-bundle-server[1], man:git-bundle[1], man:git-fetch[1]

docs/man/server-options.asc

@@ -29,3 +29,7 @@ configured for TLS, this option is a no-op.
   Require that requests to the bundle server include a client certificate that
   can be validated by the certificate authority file at the specified _path_.
   No-op if *--cert* and *--key* are not configured.
+
+*--auth-config* _path_:::
+  Use the JSON contents of the specified file to configure
+  authentication/authorization for requests to the web server.

docs/technical/auth-config.md

@@ -0,0 +1,37 @@
+# Configuring access control
+
+User access to web server endpoints on the bundle server is configured via the
+`--auth-config` option to `git-bundle-web-server` and/or `git-bundle-server
+web-server`. The auth config is a JSON file that identifies the type of access
+control requested and information needed to configure it.
+
+## Schema
+
+The JSON file contains the following fields:
+
+ <table>
+    <thead>
+        <tr>
+            <th>Field</th>
+            <th>Type</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td><code>mode</code></td>
+            <td>string</td>
+            <td>
+                The auth mode to use. Not case-sensitive.
+            </td>
+        </tr>
+        <tr>
+            <td><code>parameters</code></td>
+            <td>object</td>
+            <td>
+                A structure containing mode-specific key-value configuration
+                fields, if applicable.
+            </td>
+        </tr>
+    </tbody>
+</table>

pkg/auth/middleware.go

@@ -0,0 +1,20 @@
+package auth
+
+import (
+	"net/http"
+)
+
+// AuthMiddleware provides custom authN/authZ functionality to validate requests
+// to the bundle web server.
+//
+// BE CAREFUL! Accesses to the loaded AuthMiddleware instance will *not* be
+// thread-safe. Custom implementations should ensure any writes to any common
+// state are properly locked.
+type AuthMiddleware interface {
+	// Authorize interprets the contents of a bundle server request of a valid
+	// format (i.e., /<owner>/<repo>[/<bundle>]) and returns an AuthResult
+	// indicating whether the request should be allowed or denied. If the
+	// AuthResult is invalid (not created with Allow() or Deny()), the server
+	// will respond with a 500 status.
+	Authorize(r *http.Request, owner string, repo string) AuthResult
+}