Plugin identity & auth: propagate principals and enable host-side token exchange

[mlund01]

Problem

Squadron plugins today take static credentials from the vault at boot and use them for every call. That's fine for solo/personal use, but breaks down for anyone running squadron as a service:

• Every call to a backend looks like one shared account — no attribution
• Static tokens can't be scoped per-mission or per-principal
• No audit trail of "who did what" through a plugin
• Enterprises have existing identity infra (Okta, Entra, SPIFFE, cloud IAM) and want plugins to use it

Design in one sentence

Squadron propagates a principal into every plugin call, and plugins that need a backend token ask squadron to mint one — using whatever identity source the operator has wired up.

Two kinds of principal

How the mission was launched	Principal	Typical token flow
Scheduler, webhook, cron (service mode)	Workload identity	Client credentials / JWT-bearer
Human via CLI or UI (personal mode)	User identity	On-behalf-of exchange (RFC 8693)

Most squadron deployments will run as services. Some users will run squadron purely as a personal automation tool. The design supports both equally — the difference is just which field on CallContext is populated.

How it works

1. Every plugin call carries a CallContext

type CallContext struct {
    Principal  Principal   // oneof: UserJWT | WorkloadToken
    MissionID  string
    TaskID     string
    RequestID  string
    Constraints map[string]string // mission-derived data-access constraints (see below)
}

Local plugins (shell, parsers, file ops) ignore it entirely.

2. Plugins that need a backend token ask the host

tok, err := host.ExchangeToken(ctx, "jira.acme.com", []string{"issues:write"})

Squadron picks the right grant based on what's in CallContext. The plugin author writes one line regardless of whether a human or a cron job is driving.

3. Plugins declare what they need in ToolInfo

RequiresIdentity: &IdentityRequirement{
  Audience: "jira.acme.com",
  Scopes:   []string{"issues:write"},
  Accepts:  []PrincipalKind{User, Workload},
}

Squadron uses this to fail fast at config load, show the trust surface in squadron plugin info, and refuse to launch a mission missing a principal the tool needs.

How operators wire it up

Because squadron is open and runs everywhere, every integration point is pluggable. There's no hardcoded IdP, no hardcoded workload-identity source, no hardcoded grant type. Squadron ships reference implementations for the common ones; anything else slots in via the same interfaces.

identity_provider {
  source = "github.com/floze/squadron-idp-oidc"
  settings = { issuer = "https://acme.okta.com" }
}

workload_identity {
  source = "github.com/floze/squadron-workload-spiffe"
  settings = { socket = "unix:///run/spire/agent.sock" }
}

The plugin-author contract doesn't change regardless of which of these the operator picks.

Mission-level data-access constraints

Beyond who is calling (Principal) and what capabilities the plugin needs (OAuth scopes), we want to constrain what slice of data a mission run can touch. Mission inputs like merchant_id should bind every applicable tool call for the lifetime of the mission, with no way for the LLM to widen them.

Naming note. "Scope" already means OAuth scope in this design (IdentityRequirement.Scopes). To avoid conflation, the data-access dimension is called constraints throughout: CallContext.Constraints, HCL constraints { ... }, ConstraintBindings. OAuth scopes name capabilities; constraints name values that filter what those capabilities can reach.

CallContext.Constraints

The Constraints field on CallContext (above) is a map[string]string populated from mission inputs that the HCL marks as data-access constraints.

HCL: constraints block on a mission

mission "merchant_report" {
  inputs = {
    merchant_id = string("Merchant", true)
  }

  constraints = {
    merchant_id = inputs.merchant_id
  }

  task "fetch" { objective = "Summarize merchant activity" }
}

Validation at config load: every key in constraints must resolve to a mission input.

Tools declare which constraint keys they consume

IdentityRequirement gains ConstraintBindings:

type IdentityRequirement struct {
    Audience           string
    Scopes             []string         // OAuth capabilities (existing)
    Accepts            []PrincipalKind
    ConstraintBindings []ConstraintBinding  // NEW: mission-input filters
}

type ConstraintBinding struct {
    Key      string  // CallContext.Constraints key, e.g. "merchant_id"
    Param    string  // tool-payload path it binds to, e.g. "filters.merchant_id"
    Required bool    // mission must supply this constraint, or the tool is unusable
}

A search_transactions tool would declare:

RequiresIdentity: &IdentityRequirement{
    Audience: "ledger.acme.com",
    Scopes:   []string{"transactions:read"},   // capability
    Accepts:  []PrincipalKind{User, Workload},
    ConstraintBindings: []ConstraintBinding{   // data filter
        {Key: "merchant_id", Param: "filters.merchant_id", Required: true},
    },
}

What the host does at call time

1. Strips bound params from the schema shown to the LLM. The model never sees filters.merchant_id as a settable field — can't be prompt-injected to widen it.
2. Auto-injects from CallContext.Constraints before unmarshal into the plugin payload.
3. Rejects unbound calls. If Required = true and Constraints[Key] is empty, the tool call returns an error before reaching the plugin.
4. Bakes constraint claims into minted tokens. When the plugin calls host.ExchangeToken(ctx, audience, scopes), the host adds CallContext.Constraints into the minted token's claims (JWT custom claims, downscoped OAuth resource indicators, etc.) so the backend can enforce too.

Two enforcement layers, made explicit

Layer	Mechanism	Defends against
Structural (always on)	hidden schema + host-side injection + override rejection	LLM hallucination, prompt injection
Cryptographic (opt-in via backend)	constraint claims baked into token, backend enforces	compromised plugin, code-level escape

The structural layer alone is useful — it stops honest mistakes and most attacks against the LLM. Real defense-in-depth needs the backend to participate, same caveat that already applies to the principal-based design.

Config-load validation

Squadron refuses to launch a mission if:

• A key referenced by mission.constraints is not in inputs
• A tool with ConstraintBindings[i].Required = true is used by the mission and mission.constraints doesn't supply that key

Same fail-fast philosophy as the existing RequiresIdentity validation.

What this means for plugin authors

Plugin type	What you do
Local tool	Nothing.
Backend with a static API key that works for your use case	Nothing. Keep reading settings from vault.
Backend behind SSO or workload-scoped auth	Declare RequiresIdentity, call host.ExchangeToken at call time.
Backend that filters by a mission-supplied dimension (tenant, merchant, region, ...)	Add ConstraintBindings so the host injects the value and the LLM can't widen it.

Explicitly not doing

• Not forcing any plugin through an IdP — opt-in per plugin, per tool
• Not replacing vault-based static credentials — still the right answer in many cases
• Not mandating SPIFFE, OPA, Okta, or any specific vendor — the interfaces are open
• Not changing agent/commander logic — this is purely below the tool-call boundary

Rollout

1. Proto change: add CallContext (including Constraints) to the plugin gRPC contract
2. Host-side ExchangeToken service exposed to plugins; bakes Constraints into minted token claims
3. ToolInfo.RequiresIdentity with ConstraintBindings + config-load validation; HCL constraints block on missions
4. Reference implementations: one IdentityProvider plugin (generic OIDC), one WorkloadIdentity plugin (static JWT to start, SPIFFE next), one end-to-end demo plugin that uses both a principal and a merchant_id constraint binding

1–3 land together. 4 is the usable demo.

Questions for early users

• Are you running squadron mostly as a service, mostly personal, or both?
• Which backends do you hit first that need real auth (Jira, GitHub, Snowflake, internal APIs)?
• Where would your principal come from — SSO provider, SPIFFE, cloud IAM, static JWT, something else?
• Do you have mission-level data-access constraints (tenant/merchant/region/customer) where the LLM should never be allowed to widen the filter?
• Is the "plugin declares what backend+scopes it needs" contract enough information for your security review process, or do you need more?

[mlund01]

Some further details on how this would actually work...

# identity for human-launched missions
identity_provider {
  source   = "github.com/floze/squadron-idp-oidc"
  settings = { issuer = "https://acme.okta.com" }
}

# identity for service-launched missions
workload_identity {
  source   = "github.com/floze/squadron-workload-spiffe"
  settings = { socket = "unix:///run/spire/agent.sock" }
}

plugin "jira" {
  source  = "github.com/floze/squadron-plugin-jira"
  version = "v0.3.0"
}

agent "triager" {
  model = models.anthropic.claude_sonnet_4
  tools = [plugins.jira.create_issue]
}

mission "file_bug_from_alert" {
  schedule { every = "15m" }       # service mode
  trigger  { webhook_path = "/alert" }
  agents = [agents.triager]
  task "file" { objective = "Open a Jira issue for any new alert" }
}

and the plugin code would look like this...

func (p *JiraPlugin) GetToolInfo(name string) *ToolInfo {
    return &ToolInfo{
        Name: "create_issue",
        RequiresIdentity: &IdentityRequirement{
            Audience: "jira.acme.com",
            Scopes:   []string{"issues:write"},
            Accepts:  []PrincipalKind{User, Workload},
        },
    }
}

func (p *JiraPlugin) Call(ctx CallContext, tool, payload string) (string, error) {
    tok, err := p.host.ExchangeToken(ctx, "jira.acme.com", []string{"issues:write"})
    if err != nil { return "", err }
    return p.jira.CreateIssue(tok, payload)
}

and the flow diagram for how everything flows...

sequenceDiagram
    participant Cron as Scheduler<br/>(cron fires)
    participant SQ as Squadron
    participant WI as Workload Identity<br/>(SPIFFE agent)
    participant AG as Agent (triager)
    participant PL as Jira plugin
    participant IDP as Okta
    participant JIRA as jira.acme.com

    Cron->>SQ: launch mission "file_bug_from_alert"
    SQ->>WI: fetch SVID for this squadron process
    WI-->>SQ: workload JWT (sub=spiffe://acme/squadron)
    Note over SQ: Principal = Workload{JWT}
    SQ->>AG: run task with CallContext{Workload}
    AG->>PL: Call(ctx, "create_issue", {...})
    PL->>SQ: ExchangeToken(ctx, "jira.acme.com", ["issues:write"])
    SQ->>IDP: JWT-bearer grant<br/>assertion=workload JWT, aud=jira.acme.com
    IDP-->>SQ: access_token (sub=spiffe://acme/squadron)
    SQ-->>PL: access_token
    PL->>JIRA: POST /issues (Bearer token)
    JIRA-->>PL: 201 Created
    PL-->>AG: result

Loading

[mlund01]

Same level of detail for the constraints layer — picking up where the previous comment left off, but for a mission whose inputs need to bind every applicable tool call to a single merchant.

plugin "ledger" {
  source  = "github.com/floze/squadron-plugin-ledger"
  version = "v0.2.0"
}

agent "reconciler" {
  model = models.anthropic.claude_sonnet_4
  tools = [plugins.ledger.search_transactions]
}

mission "reconcile_merchant" {
  inputs = {
    merchant_id = string("Merchant ID", true)
    since       = string("ISO timestamp", true)
  }

  # promoted into CallContext.Constraints for every tool call in this mission
  constraints = {
    merchant_id = inputs.merchant_id
  }

  trigger { webhook_path = "/reconcile" }
  agents = [agents.reconciler]

  task "scan" {
    objective = "List all transactions since ${inputs.since} and flag anomalies"
  }
}

and the plugin code...

func (p *LedgerPlugin) GetToolInfo(name string) *ToolInfo {
    return &ToolInfo{
        Name: "search_transactions",
        RequiresIdentity: &IdentityRequirement{
            Audience: "ledger.acme.com",
            Scopes:   []string{"transactions:read"},        // capability
            Accepts:  []PrincipalKind{User, Workload},
            ConstraintBindings: []ConstraintBinding{        // data filter
                {Key: "merchant_id", Param: "filters.merchant_id", Required: true},
            },
        },
    }
}

func (p *LedgerPlugin) Call(ctx CallContext, tool, payload string) (string, error) {
    // The host has already:
    //   1. stripped filters.merchant_id from the schema the LLM saw
    //   2. injected ctx.Constraints["merchant_id"] into payload
    //   3. rejected the call upstream if Constraints["merchant_id"] was empty
    // Plugin code stays simple — same shape as the no-constraint case.
    tok, err := p.host.ExchangeToken(ctx, "ledger.acme.com", []string{"transactions:read"})
    if err != nil { return "", err }
    return p.ledger.SearchTransactions(tok, payload)
}

and the end-to-end flow...

sequenceDiagram
    participant HK as Webhook<br/>POST /reconcile
    participant SQ as Squadron
    participant WI as Workload Identity<br/>(SPIFFE)
    participant LLM as Agent LLM
    participant PL as Ledger plugin
    participant IDP as Okta
    participant LED as ledger.acme.com

    HK->>SQ: launch "reconcile_merchant"<br/>inputs={merchant_id: "M-42", since: ...}
    Note over SQ: CallContext.Constraints<br/>= {"merchant_id": "M-42"}
    SQ->>WI: fetch SVID
    WI-->>SQ: workload JWT
    Note over SQ: tool schema sent to LLM<br/>has filters.merchant_id stripped
    SQ->>LLM: schema(search_transactions) — no merchant_id field
    LLM-->>SQ: call search_transactions({filters:{since:"..."}})
    Note over SQ: inject merchant_id="M-42"<br/>from CallContext.Constraints
    SQ->>PL: Call(ctx, "search_transactions",<br/>{filters:{merchant_id:"M-42", since:"..."}})
    PL->>SQ: ExchangeToken(ctx, "ledger.acme.com", ["transactions:read"])
    SQ->>IDP: JWT-bearer grant<br/>+ constraint claims {merchant_id:"M-42"}
    IDP-->>SQ: access_token<br/>(claim merchant_id="M-42" baked in)
    SQ-->>PL: access_token
    PL->>LED: GET /transactions?since=... (Bearer)
    Note over LED: token claim merchant_id="M-42"<br/>enforces row-level filter
    LED-->>PL: only M-42 rows
    PL-->>LLM: results

Loading

Two things worth noticing in the diagram:

1. The LLM never sees filters.merchant_id. The host strips it from the schema before the agent is even prompted, so prompt-injection attempts to widen the filter have nothing to grab onto.
2. The constraint travels twice — once in the payload, once in the token. Step 1 is structural (always on, defends against the LLM and prompt injection); step 2 is cryptographic (defends against a compromised plugin, only as strong as the backend's willingness to enforce the claim).

If a second mission fires concurrently for merchant_id="M-99", both runs share the same plugin process, but each tool call carries its own CallContext — so injection and token minting stay isolated per run.