chore: add experimental documentation

Signed-off-by: Arjun Raja Yogidas <arjunry@amazon.com>

Author: coderbirju

.github/workflows/ci.yaml

@@ -110,7 +110,7 @@ jobs:
       - name: Set Rego file path
         run: echo "REGO_FILE_PATH=${{ github.workspace }}/docs/sample-rego-policies/example.rego" >> $GITHUB_ENV
       - name: Start finch-daemon with opa Authz
-        run: sudo bin/finch-daemon --debug --enable-opa-middleware --rego-file ${{ github.workspace }}/docs/sample-rego-policies/example.rego --skip-rego-perm-check --socket-owner $UID --socket-addr /run/finch.sock --pidfile /run/finch.pid &
+        run: sudo bin/finch-daemon --debug --experimental --rego-file ${{ github.workspace }}/docs/sample-rego-policies/example.rego --skip-rego-perm-check --socket-owner $UID --socket-addr /run/finch.sock --pidfile /run/finch.pid &
       - name: Run opa e2e tests
         run: sudo -E make test-e2e-opa
       - name: Clean up Daemon socket

README.md

@@ -35,6 +35,32 @@ Getting started with Finch Daemon on Linux only requires a few steps:
 5. Test any changes with `make test-unit` and `sudo make test-e2e`
 
 
+## Experimental Features
+
+Finch Daemon includes experimental features that can be enabled using the `--experimental` flag. These features are under development and may change in future releases.
+
+### Using Experimental Features
+
+To enable experimental features, use the `--experimental` flag when starting the daemon:
+
+```bash
+sudo bin/finch-daemon --debug --socket-owner $UID --experimental
+```
+
+### Current Experimental Features
+
+#### OPA Authorization Middleware
+
+The OPA (Open Policy Agent) middleware allows you to define authorization policies for API requests using Rego policy language. This feature requires both the `--experimental` flag and the `--rego-file` flag to be set.
+
+Example usage:
+```bash
+sudo bin/finch-daemon --debug --socket-owner $UID --experimental --rego-file /path/to/policy.rego
+```
+
+For detailed documentation on the OPA middleware, see [opa-middleware.md](docs/opa-middleware.md).
+
+
 ## Creating a systemd service
 If you want finch-daemon to be managed as a systemd service, for benefits like automatic
 restart if it gets killed, you can configure it as a systemd service on Linux by

api/router/router.go

@@ -111,7 +111,7 @@ func VersionMiddleware(next http.Handler) http.Handler {
 }
 
 // CreateRegoMiddleware dynamically parses the rego file at the path specified in options
-// and allows or denies the request based on the policy.
+// and return a function that allows or denies the request based on the policy.
 // Will return a nil function and an error if the given file path is blank or invalid.
 func CreateRegoMiddleware(regoFilePath string, logger *flog.Logrus) (func(next http.Handler) http.Handler, error) {
 	if regoFilePath == "" {

cmd/finch-daemon/main.go

@@ -43,15 +43,15 @@ const (
 )
 
 type DaemonOptions struct {
-	debug               bool
-	socketAddr          string
-	socketOwner         int
-	debugAddress        string
-	configPath          string
-	pidFile             string
-	regoFilePath        string
-	enableOPAMiddleware bool
-	skipRegoPermCheck   bool
+	debug              bool
+	socketAddr         string
+	socketOwner        int
+	debugAddress       string
+	configPath         string
+	pidFile            string
+	regoFilePath       string
+	enableExperimental bool
+	skipRegoPermCheck  bool
 }
 
 var options = new(DaemonOptions)
@@ -70,9 +70,9 @@ func main() {
 	rootCmd.Flags().StringVar(&options.debugAddress, "debug-addr", "", "")
 	rootCmd.Flags().StringVar(&options.configPath, "config-file", defaultConfigPath, "Daemon Config Path")
 	rootCmd.Flags().StringVar(&options.pidFile, "pidfile", defaultPidFile, "pid file location")
-	rootCmd.Flags().StringVar(&options.regoFilePath, "rego-file", "", "Rego Policy Path")
-	rootCmd.Flags().BoolVar(&options.enableOPAMiddleware, "enable-opa-middleware", false, "turn on OPA middleware for allowlisting")
+	rootCmd.Flags().StringVar(&options.regoFilePath, "rego-file", "", "Rego Policy Path (requires --experimental flag)")
 	rootCmd.Flags().BoolVar(&options.skipRegoPermCheck, "skip-rego-perm-check", false, "skip the rego file permission check (allows permissions more permissive than 0600)")
+	rootCmd.Flags().BoolVar(&options.enableExperimental, "experimental", false, "enable experimental features")
 
 	if err := rootCmd.Execute(); err != nil {
 		log.Printf("got error: %v", err)
@@ -223,11 +223,18 @@ func newRouter(options *DaemonOptions, logger *flog.Logrus) (http.Handler, error
 	}
 
 	var regoFilePath string
-	if options.enableOPAMiddleware {
+
+	if options.regoFilePath != "" {
+		if !options.enableExperimental {
+			return nil, fmt.Errorf("rego file provided without experimental flag - OPA middleware is an experimental feature, please enable it with '--experimental' flag")
+		}
 		regoFilePath, err = checkRegoFileValidity(options, logger)
 		if err != nil {
 			return nil, err
 		}
+	} else if options.enableExperimental {
+		// Only experimental flag set
+		logger.Info("experimental flag passed, but no experimental features enabled")
 	}
 
 	opts := createRouterOptions(conf, clientWrapper, ncWrapper, logger, regoFilePath)

docs/opa-middleware.md

@@ -1,6 +1,20 @@
-# Applying OPA authz policies
+# OPA Authorization Middleware (Experimental)
 
-This guide provides instructions for setting up [OPA](https://github.com/open-policy-agent/opa) authz policies with the finch-daemon. Authz policies allow users to allowlist or deny certain resources based on policy rules.
+> ⚠️ **Experimental Feature**: The OPA authorization middleware is being introduced as an experimental feature.
+
+This guide provides instructions for setting up [OPA](https://github.com/open-policy-agent/opa) authorization policies with the finch-daemon. These policies allow users to allowlist or deny certain resources based on policy rules.
+
+## Experimental Status
+
+This feature is being released as experimental because:
+- Integration patterns and best practices are still being established
+- Performance characteristics are being evaluated
+
+As an experimental feature:
+- Breaking changes may occur in any release
+- Long-term backward compatibility is not guaranteed
+- Documentation and examples may evolve substantially
+- Production use is not recommended at this stage
 
 ## What Is OPA Authz implementation
 Open Policy Agent (OPA) is an open-source, general-purpose policy engine that enables unified, context-aware policy enforcement across the entire stack. OPA provides a high-level declarative language, Rego, for specifying policy as code and simple APIs to offload policy decision-making from your software.
@@ -34,24 +48,26 @@ Use the [Rego playground](https://play.openpolicyagent.org/) to fine tune your r
 
 ## Enable OPA Middleware
 
-Once you are ready with your policy document, use the `--enable-opa-middleware` flag to tell the finch-daemon to enable the OPA middleware. The daemon will then look for the policy document provided by the `--rego-file` flag.
+Once you are ready with your policy document, use the `--experimental` flag to enable experimental features including OPA middleware. The daemon will then look for the policy document provided by the `--rego-file` flag.
 
-Note: The `--rego-file` flag is required when `--enable-opa-middleware` is set.
+Note: Since OPA middleware is an experimental feature, the `--experimental` flag is required when using `--rego-file`.
 
 The daemon enforces strict permissions (0600 or more restrictive) on the Rego policy file to prevent unauthorized modifications. You can bypass this check using the `--skip-rego-perm-check` flag.
 
 Examples:
 
 Standard secure usage:
 ```bash
-sudo bin/finch-daemon --debug --socket-owner $UID --socket-addr /run/finch-test.sock --pidfile /run/finch-test.pid --enable-opa-middleware --rego-file /path/to/policy.rego
+sudo bin/finch-daemon --debug --socket-owner $UID --socket-addr /run/finch-test.sock --pidfile /run/finch-test.pid --experimental --rego-file /path/to/policy.rego
 ```
 
 With permission check bypassed:
 ```bash
-sudo bin/finch-daemon --debug --socket-owner $UID --socket-addr /run/finch-test.sock --pidfile /run/finch-test.pid --enable-opa-middleware --rego-file /path/to/policy.rego --skip-rego-perm-check
+sudo bin/finch-daemon --debug --socket-owner $UID --socket-addr /run/finch-test.sock --pidfile /run/finch-test.pid --experimental --rego-file /path/to/policy.rego --skip-rego-perm-check
 ```
 
+Note: If you enable experimental features with `--experimental` but don't provide a `--rego-file`, the daemon will run without OPA policy evaluation.
+
 
 # Best practices for secure rego policies
 

docs/sample-rego-policies/example.rego

@@ -1,3 +1,8 @@
+# This is an experimental preview policy example.
+# As this feature is under active development:
+# - Breaking changes may occur without notice
+# - Production use is not recommended
+
 package finch.authz
 
 import future.keywords.if

e2e/tests/opa_middleware.go

@@ -126,7 +126,7 @@ func OpaMiddlewareTest(opt *option.Option) {
 				"--socket-addr", "/run/test.sock",
 				"--pidfile", "/run/test.pid",
 				"--rego-file", regoPath,
-				"--enable-opa-middleware")
+				"--experimental")
 			err = cmd.Run()
 
 			// Should fail due to permissions
@@ -137,7 +137,7 @@ func OpaMiddlewareTest(opt *option.Option) {
 				"--socket-addr", "/run/test.sock",
 				"--pidfile", "/run/test.pid",
 				"--rego-file", regoPath,
-				"--enable-opa-middleware",
+				"--experimental",
 				"--skip-rego-perm-check")
 
 			// Start the process in background