feat(openapi): select conditional security alternatives

Author: saltbo

docs/design/045-conditional-operation-security.md

@@ -0,0 +1,45 @@
+# Conditional Operation Security
+
+## Status
+
+Accepted for the v2 development line.
+
+## Problem
+
+OpenAPI security can express alternatives and conjunctions, but it cannot make
+one alternative conditional on the concrete value of a path parameter. Some
+transparent APIs need exactly that behavior. Publishing all sets as ordinary
+alternatives loses the condition, so a client can request too little authority
+and discover the missing requirement only after the server rejects the request.
+
+## Decision
+
+Restish supports the additive operation extension
+`x-restish-security-alternatives`. It is an ordered list of rules:
+
+```yaml
+x-restish-security-alternatives:
+  - when:
+      pathParameter: path
+      prefix: .github/workflows/
+    alternatives: [1]
+```
+
+`alternatives` contains zero-based indexes into that operation's standard
+OpenAPI `security` array. After the concrete request path is known, Restish
+extracts and percent-decodes the named path parameter. The first matching rule
+replaces the candidate list with the indexed alternatives. When no rule matches,
+standard OpenAPI selection is unchanged.
+
+The extension only narrows standard alternatives; it cannot create a scheme,
+scope, or conjunction. Invalid parameter names, empty predicates, repeated
+indexes, and out-of-range indexes fail specification loading. Authority remains
+visible to ordinary OpenAPI tooling and the extension cannot silently widen it.
+
+## Compatibility
+
+The extension is optional. Existing specifications and clients continue to see
+the complete standard OpenAPI security alternatives. Inspection, help, and
+configuration retain the complete static view because no concrete path value
+exists at those stages. Generated commands and generic requests both apply the
+predicate immediately before operation authentication planning.

docs/design/README.md

@@ -144,6 +144,7 @@ were a recurring source of remediation work.
 - [007-api-command-generation.md](./007-api-command-generation.md) - Config-backed API registration, OpenAPI-to-command mapping, naming, parameter handling, and compatibility aliases.
 - [033-openapi-operation-security.md](./033-openapi-operation-security.md) - Operation-specific OpenAPI security policy, credential bindings, setup UX, and compatibility rules.
 - [044-dpop-credential-sources.md](./044-dpop-credential-sources.md) - Native RFC 9449 credential custody with provider-neutral token-source plugins.
+- [045-conditional-operation-security.md](./045-conditional-operation-security.md) - Request-path predicates that narrow standard OpenAPI security alternatives at execution time.
 - [034-openapi-implementation-contract.md](./034-openapi-implementation-contract.md) - Implementation-grade OpenAPI 3.x behavior matrix for loading, command generation, parameters, servers, schemas, auth, media types, caching, and tests.
 - [008-shorthand-input.md](./008-shorthand-input.md) - Building request bodies from CLI arguments and stdin using shorthand syntax.
 - [029-request-execution-pipeline.md](./029-request-execution-pipeline.md) - End-to-end request planning, execution order, cancellation, transport layering, normalization, filtering, and rendering.

internal/cli/generated.go

@@ -491,7 +491,7 @@ func (c *CLI) buildOperationCommand(apiName, examplePrefix string, op spec.Opera
 			}
 			acceptOverride := c.generatedOperationAcceptHeader(op.ResponseMediaTypes, op.ResponseMediaType)
 			rawBinaryBody := op.Help.Request != nil && op.Help.Request.RawBinary
-			return c.runGeneratedOp(cmd, apiName, op.Path, op.OperationServer, op.Method, op.RequestMediaType, acceptOverride, op.RequestMultipartContentTypes, op.Help, op.BodyRequired, rawBinaryBody, op.NoAuth, op.OptionalAuth, op.CredentialAlternatives, required, optional, args)
+			return c.runGeneratedOp(cmd, apiName, op.Path, op.OperationServer, op.Method, op.RequestMediaType, acceptOverride, op.RequestMultipartContentTypes, op.Help, op.BodyRequired, rawBinaryBody, op.NoAuth, op.OptionalAuth, op.CredentialAlternatives, op.ConditionalSecurity, required, optional, args)
 		},
 	}
 	if candidates := authOverrideCandidates(op.OptionalAuth, op.CredentialAlternatives); len(candidates) > 0 {
@@ -1382,6 +1382,7 @@ func (c *CLI) runGeneratedOp(
 	noAuth bool,
 	optionalAuth bool,
 	credentialAlternatives []spec.CredentialAlternative,
+	conditionalSecurity []spec.ConditionalSecurityRule,
 	required, optional []*paramInfo,
 	args []string,
 ) error {
@@ -1511,6 +1512,8 @@ func (c *CLI) runGeneratedOp(
 			OptionalAuth:           optionalAuth,
 			NoAuth:                 noAuth,
 			CredentialAlternatives: credentialAlternatives,
+			OperationPath:          opPath,
+			ConditionalSecurity:    conditionalSecurity,
 			Override:               gf.Auth,
 		},
 	})

internal/cli/operation_auth.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"fmt"
 	"net/http"
+	"net/url"
+	"regexp"
 	"sort"
 	"strings"
 
@@ -21,6 +23,8 @@ type operationAuthPolicy struct {
 	OptionalAuth           bool
 	NoAuth                 bool
 	CredentialAlternatives []spec.CredentialAlternative
+	OperationPath          string
+	ConditionalSecurity    []spec.ConditionalSecurityRule
 	Override               string
 	Transport              request.Options
 }
@@ -34,6 +38,13 @@ type selectedOperationAuth struct {
 }
 
 func (c *CLI) planOperationAuth(apiName, profileName string, prof *config.ProfileConfig, policy *operationAuthPolicy) ([]selectedOperationAuth, bool, error) {
+	if policy != nil {
+		resolved, err := conditionalOperationAuthPolicy(*policy)
+		if err != nil {
+			return nil, false, err
+		}
+		policy = &resolved
+	}
 	if policy != nil && strings.TrimSpace(policy.Override) != "" {
 		return c.planOperationAuthOverride(apiName, profileName, prof, policy)
 	}
@@ -146,6 +157,61 @@ func (c *CLI) planOperationAuth(apiName, profileName string, prof *config.Profil
 	return nil, false, fmt.Errorf("profile %q of API %q is missing credential bindings for this operation: %s%s%s; %s", profileName, apiName, strings.Join(uniqueStrings(missing), ", "), securityIssueSuffix, operationAuthConfiguredOverrideHint(prof, policy.CredentialAlternatives), operationAuthSetupHint(apiName, profileName))
 }
 
+func conditionalOperationAuthPolicy(policy operationAuthPolicy) (operationAuthPolicy, error) {
+	if len(policy.ConditionalSecurity) == 0 || policy.URL == "" {
+		return policy, nil
+	}
+	u, err := url.Parse(policy.URL)
+	if err != nil {
+		return operationAuthPolicy{}, fmt.Errorf("conditional operation security: parse request URL: %w", err)
+	}
+	for _, rule := range policy.ConditionalSecurity {
+		value, ok := operationPathParameter(policy.OperationPath, u.EscapedPath(), rule.When.PathParameter)
+		if !ok || !strings.HasPrefix(value, rule.When.Prefix) {
+			continue
+		}
+		alternatives := make([]spec.CredentialAlternative, 0, len(rule.Alternatives))
+		for _, index := range rule.Alternatives {
+			if index < 0 || index >= len(policy.CredentialAlternatives) {
+				return operationAuthPolicy{}, fmt.Errorf("conditional operation security selects unavailable alternative %d", index)
+			}
+			alternatives = append(alternatives, policy.CredentialAlternatives[index])
+		}
+		policy.CredentialAlternatives = alternatives
+		return policy, nil
+	}
+	return policy, nil
+}
+
+func operationPathParameter(template, escapedRequestPath, name string) (string, bool) {
+	var source strings.Builder
+	source.WriteString(`^.*`)
+	index := 0
+	found := false
+	for _, match := range regexp.MustCompile(`\{([^}]+)\}`).FindAllStringSubmatchIndex(template, -1) {
+		source.WriteString(regexp.QuoteMeta(template[index:match[0]]))
+		parameterName := template[match[2]:match[3]]
+		if parameterName == name {
+			source.WriteString(`(.+)`)
+			found = true
+		} else {
+			source.WriteString(`[^/]+`)
+		}
+		index = match[1]
+	}
+	if !found {
+		return "", false
+	}
+	source.WriteString(regexp.QuoteMeta(template[index:]))
+	source.WriteString(`$`)
+	match := regexp.MustCompile(source.String()).FindStringSubmatch(escapedRequestPath)
+	if len(match) != 2 {
+		return "", false
+	}
+	value, err := url.PathUnescape(match[1])
+	return value, err == nil
+}
+
 func (c *CLI) planOperationAuthOverride(apiName, profileName string, prof *config.ProfileConfig, policy *operationAuthPolicy) ([]selectedOperationAuth, bool, error) {
 	override := strings.TrimSpace(policy.Override)
 	if strings.EqualFold(override, "anonymous") {

internal/cli/operation_auth_test.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"context"
 	"net/http"
+	"reflect"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -79,6 +80,44 @@ func TestPlanOperationAuthDerivesSatisfiesFromAuthProfileScopes(t *testing.T) {
 	}
 }
 
+func TestPlanOperationAuthSelectsConditionalAlternativeFromConcretePath(t *testing.T) {
+	c := &CLI{}
+	prof := &config.ProfileConfig{Credentials: map[string]*config.CredentialConfig{
+		"provider": {
+			Auth:      &config.AuthConfig{Type: "api-key", Params: map[string]string{"in": "header", "name": "Authorization", "value": "token"}},
+			Satisfies: []string{"contents:write", "workflows:write"},
+		},
+	}}
+	policy := operationAuthPolicy{
+		URL:           "https://adapter.example.com/github/repos/acme/widgets/contents/.github/workflows/release.yml",
+		OperationPath: "/repos/{owner}/{repo}/contents/{path}",
+		CredentialAlternatives: []spec.CredentialAlternative{
+			{{ID: "provider", Needs: []string{"contents:write"}}},
+			{{ID: "provider", Needs: []string{"contents:write", "workflows:write"}}},
+		},
+		ConditionalSecurity: []spec.ConditionalSecurityRule{{
+			When:         spec.ConditionalSecurityPredicate{PathParameter: "path", Prefix: ".github/workflows/"},
+			Alternatives: []int{1},
+		}},
+	}
+	selected, handled, err := c.planOperationAuth("github", "default", prof, &policy)
+	if err != nil {
+		t.Fatalf("planOperationAuth: %v", err)
+	}
+	if !handled || len(selected) != 1 || !reflect.DeepEqual(selected[0].requirement.Needs, []string{"contents:write", "workflows:write"}) {
+		t.Fatalf("selected = %#v handled=%v, want workflow conjunction", selected, handled)
+	}
+
+	policy.URL = "https://adapter.example.com/github/repos/acme/widgets/contents/README.md"
+	selected, handled, err = c.planOperationAuth("github", "default", prof, &policy)
+	if err != nil {
+		t.Fatalf("planOperationAuth ordinary path: %v", err)
+	}
+	if !handled || len(selected) != 1 || !reflect.DeepEqual(selected[0].requirement.Needs, []string{"contents:write"}) {
+		t.Fatalf("selected = %#v handled=%v, want ordinary contents authority", selected, handled)
+	}
+}
+
 func TestPlanOperationAuthHandlesAnonymousOnlySecurity(t *testing.T) {
 	c := &CLI{}
 	prof := &config.ProfileConfig{

internal/cli/operation_route_auth.go

@@ -44,7 +44,7 @@ func (c *CLI) operationAuthForGenericRequest(ctx context.Context, method, rawURL
 		if !ok {
 			continue
 		}
-		score, ok := routeTemplateMatchScore(routePath, requestPath)
+		score, ok := routeTemplateMatchScore(routePath, requestPath, conditionalSecurityPathParameters(op.ConditionalSecurity))
 		if !ok || score < bestScore {
 			continue
 		}
@@ -69,6 +69,8 @@ func (c *CLI) operationAuthForGenericRequest(ctx context.Context, method, rawURL
 		policy: &operationAuthPolicy{
 			OptionalAuth:           best.OptionalAuth,
 			CredentialAlternatives: best.CredentialAlternatives,
+			OperationPath:          best.Path,
+			ConditionalSecurity:    best.ConditionalSecurity,
 		},
 	}, true
 }
@@ -112,20 +114,33 @@ func operationRoutePath(apiCfg *config.APIConfig, profileName, opPath string) (s
 	return urlpath.Clean(path), true
 }
 
-func routeTemplateMatchScore(templatePath, requestPath string) (int, bool) {
+func routeTemplateMatchScore(templatePath, requestPath string, greedyParameters map[string]bool) (int, bool) {
 	templatePath = urlpath.Clean(templatePath)
 	requestPath = urlpath.Clean(requestPath)
 	if templatePath == requestPath && !strings.Contains(templatePath, "{") {
 		return len(templatePath) * 4, true
 	}
 	templateSegments := splitCleanPath(templatePath)
 	requestSegments := splitCleanPath(requestPath)
-	if len(templateSegments) != len(requestSegments) {
+	greedyName := ""
+	if len(templateSegments) > 0 {
+		last := templateSegments[len(templateSegments)-1]
+		if strings.HasPrefix(last, "{") && strings.HasSuffix(last, "}") {
+			name := strings.TrimSuffix(strings.TrimPrefix(last, "{"), "}")
+			if greedyParameters[name] {
+				greedyName = name
+			}
+		}
+	}
+	if len(templateSegments) != len(requestSegments) && (greedyName == "" || len(requestSegments) < len(templateSegments)) {
 		return 0, false
 	}
 	score := 0
 	for i, templateSegment := range templateSegments {
 		requestSegment := requestSegments[i]
+		if i == len(templateSegments)-1 && greedyName != "" {
+			requestSegment = strings.Join(requestSegments[i:], "/")
+		}
 		if strings.Contains(templateSegment, "{") && strings.Contains(templateSegment, "}") {
 			if requestSegment == "" {
 				return 0, false
@@ -141,6 +156,14 @@ func routeTemplateMatchScore(templatePath, requestPath string) (int, bool) {
 	return score, true
 }
 
+func conditionalSecurityPathParameters(rules []spec.ConditionalSecurityRule) map[string]bool {
+	parameters := map[string]bool{}
+	for _, rule := range rules {
+		parameters[rule.When.PathParameter] = true
+	}
+	return parameters
+}
+
 func splitCleanPath(p string) []string {
 	p = strings.Trim(urlpath.Clean(p), "/")
 	if p == "" {

internal/cli/operation_route_auth_test.go

@@ -0,0 +1,23 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/rest-sh/restish/v2/internal/spec"
+)
+
+func TestConditionalSecurityPathParameterMatchesSlashContainingGenericRequest(t *testing.T) {
+	rules := []spec.ConditionalSecurityRule{{
+		When:         spec.ConditionalSecurityPredicate{PathParameter: "path", Prefix: ".github/workflows/"},
+		Alternatives: []int{1},
+	}}
+	template := "/github/repos/{owner}/{repo}/contents/{path}"
+	requestPath := "/github/repos/acme/widgets/contents/.github/workflows/release.yml"
+
+	if _, ok := routeTemplateMatchScore(template, requestPath, conditionalSecurityPathParameters(rules)); !ok {
+		t.Fatal("conditional path parameter did not consume the remaining generic request path")
+	}
+	if _, ok := routeTemplateMatchScore(template, requestPath, nil); ok {
+		t.Fatal("ordinary OpenAPI path parameters must still consume exactly one segment")
+	}
+}