Add support for 1Password secret references (#37)

* Add support for 1Password secret references

* Add more details and screenshot

* Resize screenshot

* Add test coverage for ResolveSecretReference helper function

Author: mattt

README.md

@@ -162,15 +162,51 @@ it starts a program that listens on stdin,
 outputs to stdout,
 and logs to stderr.
 
+### Authentication
+
+For APIs that require authentication,
+emcee supports several authentication methods:
+
+| Authentication Type | Example Usage | Resulting Header |
+|------------------------|---------------|----------------------------|
+| **Bearer Token** | `--bearer-auth="abc123"` | `Authorization: Bearer abc123` |
+| **Basic Auth** | `--basic-auth="user:pass"` | `Authorization: Basic dXNlcjpwYXNz` |
+| **Raw Value** | `--raw-auth="Custom xyz789"` | `Authorization: Custom xyz789` |
+
+These authentication values can be provided directly
+or as [1Password secret references][secret-reference-syntax].
+
+When using 1Password references:
+- Use the format `op://vault/item/field`
+  (e.g. `--bearer-auth="op://Shared/X/credential"`)
+- Ensure the 1Password CLI (`op`) is installed and available in your `PATH`
+- Sign in to 1Password before running `emcee` or launching Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "twitter": {
+      "command": "emcee",
+      "args": [
+        "--bearer-auth=op://shared/x/credential",
+        "https://api.twitter.com/2/openapi.json"
+      ]
+    }
+  }
+}
+```
+
+<img src="https://github.com/user-attachments/assets/d639fd7c-f3bf-477c-9eb7-229285b36f7d" alt="1Password Access Requested" width="512">
+
+### JSON-RPC
+
 You can interact directly with the provided MCP server
 by sending JSON-RPC requests.
 
 > [!NOTE]
 > emcee provides only MCP tool capabilities.
 > Other features like resources, prompts, and sampling aren't yet supported.
 
-### Example JSON-RPC Calls
-
 #### List Tools
 
 <details open>
@@ -281,3 +317,4 @@ emcee is licensed under the Apache License, Version 2.0.
 [mcp-servers]: https://modelcontextprotocol.io/examples
 [openapi]: https://openapi.org
 [releases]: https://github.com/loopwork-ai/emcee/releases
+[secret-reference-syntax]: https://developer.1password.com/docs/cli/secret-reference-syntax/

cmd/emcee/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"encoding/base64"
 	"fmt"
 	"io"
 	"log/slog"
@@ -15,8 +16,6 @@ import (
 	"github.com/spf13/cobra"
 	"golang.org/x/sync/errgroup"
 
-	"encoding/base64"
-
 	"github.com/loopwork-ai/emcee/internal"
 	"github.com/loopwork-ai/emcee/mcp"
 )
@@ -33,7 +32,14 @@ The spec-path-or-url argument can be:
 - "-" to read from stdin
 
 By default, a GET request with no additional headers is made to the spec URL to download the OpenAPI specification.
+
 If additional authentication is required to download the specification, you can first download it to a local file using your preferred HTTP client with the necessary authentication headers, and then provide the local file path to emcee.
+
+Authentication values can be provided directly or as 1Password secret references (e.g. op://vault/item/field). When using 1Password references:
+- The 1Password CLI (op) must be installed and available in your PATH
+- You must be signed in to 1Password
+- The reference must be in the format op://vault/item/field
+- The secret will be securely retrieved at runtime using the 1Password CLI
 `,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -70,18 +76,39 @@ If additional authentication is required to download the specification, you can
 
 			// Set default headers if auth is provided
 			if bearerAuth != "" {
-				opts = append(opts, mcp.WithAuth("Bearer "+bearerAuth))
+				resolvedAuth, wasSecret, err := internal.ResolveSecretReference(ctx, bearerAuth)
+				if err != nil {
+					return fmt.Errorf("error resolving bearer auth: %w", err)
+				}
+				if wasSecret {
+					logger.Debug("resolved bearer auth from 1Password")
+				}
+				opts = append(opts, mcp.WithAuth("Bearer "+resolvedAuth))
 			} else if basicAuth != "" {
+				resolvedAuth, wasSecret, err := internal.ResolveSecretReference(ctx, basicAuth)
+				if err != nil {
+					return fmt.Errorf("error resolving basic auth: %w", err)
+				}
+				if wasSecret {
+					logger.Debug("resolved basic auth from 1Password")
+				}
 				// Check if already base64 encoded
-				if strings.Contains(basicAuth, ":") {
-					encoded := base64.StdEncoding.EncodeToString([]byte(basicAuth))
+				if strings.Contains(resolvedAuth, ":") {
+					encoded := base64.StdEncoding.EncodeToString([]byte(resolvedAuth))
 					opts = append(opts, mcp.WithAuth("Basic "+encoded))
 				} else {
 					// Assume it's already base64 encoded
-					opts = append(opts, mcp.WithAuth("Basic "+basicAuth))
+					opts = append(opts, mcp.WithAuth("Basic "+resolvedAuth))
 				}
 			} else if rawAuth != "" {
-				opts = append(opts, mcp.WithAuth(rawAuth))
+				resolvedAuth, wasSecret, err := internal.ResolveSecretReference(ctx, rawAuth)
+				if err != nil {
+					return fmt.Errorf("error resolving raw auth: %w", err)
+				}
+				if wasSecret {
+					logger.Debug("resolved raw auth from 1Password")
+				}
+				opts = append(opts, mcp.WithAuth(resolvedAuth))
 			}
 
 			// Set HTTP client

internal/secret.go

@@ -0,0 +1,43 @@
+package internal
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+var (
+	// Command is a variable that allows overriding the command creation for testing
+	CommandContext = exec.CommandContext
+	// LookPath is a variable that allows overriding the lookup behavior for testing
+	LookPath = exec.LookPath
+)
+
+// ResolveSecretReference attempts to resolve a 1Password secret reference (e.g. op://vault/item/field)
+// Returns the resolved value and whether it was a secret reference
+func ResolveSecretReference(ctx context.Context, value string) (string, bool, error) {
+	if !strings.HasPrefix(value, "op://") {
+		return value, false, nil
+	}
+
+	// Check if op CLI is available
+	if _, err := LookPath("op"); err != nil {
+		return "", true, fmt.Errorf("1Password CLI (op) not found in PATH: %w", err)
+	}
+
+	// Create command to read secret
+	cmd := CommandContext(ctx, "op", "read", value)
+	output, err := cmd.Output()
+	if err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return "", true, fmt.Errorf("failed to read secret from 1Password: %s", string(exitErr.Stderr))
+		}
+		return "", true, fmt.Errorf("failed to read secret from 1Password: %w", err)
+	}
+
+	// Trim any whitespace/newlines from the output
+	return strings.TrimSpace(string(output)), true, nil
+}

internal/secret_test.go

@@ -0,0 +1,106 @@
+package internal
+
+import (
+	"context"
+	"os/exec"
+	"testing"
+)
+
+func TestResolveSecretReference(t *testing.T) {
+	// Save the original functions and restore them after the test
+	originalCommand := CommandContext
+	originalLookPath := LookPath
+	t.Cleanup(func() {
+		CommandContext = originalCommand
+		LookPath = originalLookPath
+	})
+
+	tests := []struct {
+		name               string
+		input              string
+		mockCommandContext func(ctx context.Context, name string, args ...string) *exec.Cmd
+		mockLookPath       func(string) (string, error)
+		wantValue          string
+		wantSecret         bool
+		wantErr            bool
+	}{
+		{
+			name:       "non-secret value",
+			input:      "regular-value",
+			wantValue:  "regular-value",
+			wantSecret: false,
+		},
+		{
+			name:  "successful secret resolution",
+			input: "op://vault/item/field",
+			mockLookPath: func(string) (string, error) {
+				return "/usr/local/bin/op", nil
+			},
+			mockCommandContext: func(ctx context.Context, name string, args ...string) *exec.Cmd {
+				return exec.CommandContext(ctx, "echo", "secret-value")
+			},
+			wantValue:  "secret-value",
+			wantSecret: true,
+		},
+		{
+			name:  "op CLI not found",
+			input: "op://vault/item/field",
+			mockLookPath: func(string) (string, error) {
+				return "", exec.ErrNotFound
+			},
+			wantValue:  "",
+			wantSecret: true,
+			wantErr:    true,
+		},
+		{
+			name:  "op command execution failed",
+			input: "op://vault/item/field",
+			mockLookPath: func(string) (string, error) {
+				return "/usr/local/bin/op", nil
+			},
+			mockCommandContext: func(ctx context.Context, name string, args ...string) *exec.Cmd {
+				// Return a command that will fail
+				return exec.CommandContext(ctx, "false")
+			},
+			wantValue:  "",
+			wantSecret: true,
+			wantErr:    true,
+		},
+		{
+			name:       "empty input",
+			input:      "",
+			wantValue:  "",
+			wantSecret: false,
+		},
+		{
+			name:       "malformed op reference",
+			input:      "op://invalid",
+			wantValue:  "",
+			wantSecret: true,
+			wantErr:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.mockCommandContext != nil {
+				CommandContext = tt.mockCommandContext
+			}
+			if tt.mockLookPath != nil {
+				LookPath = tt.mockLookPath
+			}
+
+			got, isSecret, err := ResolveSecretReference(context.Background(), tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ResolveSecretReference() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if got != tt.wantValue {
+				t.Errorf("ResolveSecretReference() got = %v, want %v", got, tt.wantValue)
+			}
+			if isSecret != tt.wantSecret {
+				t.Errorf("ResolveSecretReference() isSecret = %v, want %v", isSecret, tt.wantSecret)
+			}
+		})
+	}
+}