[plan] Phase 4: Add AuthDefinition and RequestShape for provider-owned auth and request shaping

[github-actions]

Objective

Add AuthDefinition and RequestShape to EngineDefinition so that non-standard backends (OAuth client-credentials, custom headers, path templates, body injection) can be declared in data rather than requiring new hard-coded Go engine implementations.

Context

Issue #20416 Phase 4: support providers with non-standard auth and request semantics. The motivating example from the issue is a backend that requires:

• OAuth client-credentials token exchange before calling the model API
• Token sent as api-key header (not Authorization)
• Custom URL path template with api-version query parameter
• JSON body injection of an appKey field

Without this, each such backend requires a new bespoke engine implementation in Go.

Prerequisite: Phase 1 (EngineDefinition/EngineCatalog), Phase 2 (single source of truth), and Phase 3 (inline/catalog engine parsing) must be merged first.

Approach

1. Define AuthDefinition in pkg/workflow/engine_definition.go

type AuthStrategy string
const (
    AuthStrategyAPIKey          AuthStrategy = "api-key"
    AuthStrategyOAuthClientCreds AuthStrategy = "oauth-client-credentials"
    AuthStrategyBearer          AuthStrategy = "bearer"
)

type AuthDefinition struct {
    Strategy    AuthStrategy
    Secret      string           // env var name for direct auth
    TokenURL    string           // for oauth-client-credentials
    ClientIDRef string           // template reference
    ClientSecretRef string
    TokenField  string           // field to extract from token response
    HeaderName  string           // header to inject token into
}

2. Define RequestShape in pkg/workflow/engine_definition.go

type RequestShape struct {
    PathTemplate string            // e.g. "/openai/deployments/{model}/chat/completions"
    Query        map[string]string // static or template values
    BodyInject   map[string]string // key → template value to inject into request body
}

3. Extend ProviderSelection to include AuthDefinition and RequestShape

4. Extend schema and parser

In pkg/parser/schemas/main_workflow_schema.json, add schema for:

• auth.strategy enum
• auth.tokenUrl, auth.clientId, auth.clientSecret, auth.tokenField, auth.headerName
• request.pathTemplate, request.query, request.bodyInject

5. Add validation

• oauth-client-credentials requires tokenUrl, clientId, clientSecret
• headerName required when strategy is not bearer
• Template references (e.g. {clientId}) must refer to declared provider secrets
• Invalid/unknown auth strategy → clear error

6. Update strict-mode and secret validation

In pkg/workflow/strict_mode_validation.go and pkg/cli/engine_secrets.go, ensure that auth bindings from AuthDefinition are treated as required secrets (same as current hardcoded secret requirements).

7. Add tests

• OAuth client-credentials definition validates correctly
• Missing tokenUrl produces a helpful error
• Template references to undeclared secrets produce validation error
• Strict mode includes auth-binding secrets in required secret list
• Existing built-in auth flows unchanged (regression)

Files to Modify

• Modify: pkg/workflow/engine_definition.go — add AuthDefinition, RequestShape
• Modify: pkg/parser/schemas/main_workflow_schema.json — add auth/request schemas
• Modify: pkg/workflow/strict_mode_validation.go — include auth-binding secrets
• Modify: pkg/cli/engine_secrets.go — derive required secrets from AuthDefinition
• Create: pkg/workflow/engine_auth_test.go
• Run: make build && make agent-finish

Acceptance Criteria

• AuthDefinition and RequestShape types defined
• Schema validates oauth-client-credentials auth fields
• Missing required auth fields produce clear validation errors
• Template references to undeclared secrets are caught at validation time
• Strict mode includes auth-binding secrets in required secret checks
• Existing built-in engine auth (Anthropic key, OpenAI key, Copilot token) still works (regression tests pass)
• make test-unit passes
  Related to GitHub Agentic Workflow Engine Enhancement Proposal #20416

Generated by Plan Command for issue #20416 · ◷

• expires on Mar 13, 2026, 2:45 AM UTC