Scoped API identities for unattended agent workloads

[jholm117]

Scoped API identities for unattended agent workloads

What problem are you trying to solve?

TrueForge supports OIDC authentication and enforces session ownership through created_by. This works well for interactive users, but API-driven and unattended workloads need a narrower authorization boundary.

For example, an ephemeral development environment may need permission to:

• create and operate only its own sessions;
• use one approved agent configuration;
• use only allowlisted models, skills, and MCP connectors;
• stay within operator-defined execution and lifetime limits;
• never enumerate or modify shared agents or settings.

Today, an authenticated non-admin user can create inline sessions and choose among tenant-configured resources. Session ownership prevents access to another user's sessions, but it does not constrain what a caller may request when creating its own session.

This makes it difficult to grant direct TrueForge API access to short-lived CI jobs, autonomous workers, or per-environment service identities without placing a trusted policy-enforcing service in front of TrueForge.

Proposed solution

Add an operator-controlled authorization seam for API-driven workloads.

The exact mechanism is open for discussion. Possible designs include:

• mapping verified OIDC claims to a server-side workload policy;
• issuing scoped service credentials;
• injecting an authorization/policy provider into session creation and resource resolution.

A workload policy could constrain:

• whether inline agent specifications are permitted;
• allowed named agents;
• allowed models, skills, and MCP servers;
• allowed MCP tools and approval policy;
• session concurrency and lifetime;
• whether shared resources may be listed;
• whether agent and settings mutation APIs are accessible.

The server should enforce these constraints rather than trusting restrictions supplied in the session's agent specification.

A minimal first version could authorize session creation against an operator-defined policy while retaining the existing created_by ownership model for subsequent session and turn operations.

We would be interested in contributing an implementation after agreeing on the preferred architecture and scope.

Alternatives considered

External policy broker

A trusted service can authenticate workloads, validate requests, and call TrueForge with a privileged credential. This works today and is our current likely approach, but every API-driven deployment must then implement session ownership mapping, request validation, lifecycle enforcement, and audit behavior independently.

Dedicated TrueForge deployment per workload

This provides strong isolation but is operationally expensive and does not fit short-lived environments.

OIDC identity per workload only

Unique sub claims provide session ownership isolation, but do not constrain inline agent specifications or access to tenant-configured resources.

Per-tool authorization

Issues #379 and #413 could control tool execution, but do not cover session creation, model/resource selection, or shared API visibility.

Additional context

Related issues:

• Add adaptive shared execution budgets across root and sub-agents #375 — shared execution budgets
• Proposal: operator-configured lifecycle hooks (observe/veto prompts and tool calls) #379 — operator-configured lifecycle hooks
• Stop the sandbox when the cancel API cancels a turn #397 — stopping sandbox execution on cancellation
• Proposal: plug in a declarative per-tool authorization backend #413 — declarative per-tool authorization
• Encrypt persisted secrets (MCP OAuth tokens, provider API keys) at rest instead of storing plaintext jsonb #419 — encryption of persisted credentials

This request is specifically about authorization at the workload/session API boundary. It is intended to complement rather than duplicate those proposals.

[harshitsaxena214]

Hi, I'd like to take this on. Proposing the "minimal first version" scope before opening a PR.

Approach: add a SessionPolicy / SessionPolicyProvider seam mirroring the existing Authorizer pattern (auth/authorizer.ts). SessionPolicy carries allow_inline_agent_spec plus optional allowlists for agent names, models, skills, and MCP servers (undefined = unrestricted). resolve(context) returns the policy for a RequestContext, same DI shape as Authorizer. Default is UnrestrictedSessionPolicyProvider, so nothing changes for existing callers out of the box. Enforced in apis/sessions.ts alongside the existing agentIfAccessible / validateAgentSpec checks, 403 on violation, wired through app.ts → main.ts the same way authorizer is.

Out of scope here: concurrency limits, lifetime limits, shared-resource-listing visibility. Those need store-level changes and feel like their own follow-up PR(s), similar to how #586 split into 3/N.

Saw #586 just merged and touches adjacent code, will rebase off latest main before starting.

Let me know if this scope/architecture works, or if you'd rather settle on the policy mechanism itself first.

[veriton-dev]

Operational note from running unattended agent workers against session APIs (CI + long-running autonomous loops):

created_by ownership ≠ capability boundary. We hit the same gap: unique OIDC sub cleanly isolates sessions, but the create-session call is still the blast radius. Once a worker can pick models/skills/MCP connectors (or paste an inline agent spec), prompt injection or a buggy planner can escalate without ever touching another user's session.

What held up in production for us:

1. Server-side workload policy at create time only (your minimal first version). Resolve policy from verified claims before accepting the agent spec. Do not trust allowlists that arrive inside the request body — those are attacker-controlled after injection.
2. Default-deny named resources. undefined = unrestricted is convenient for interactive tenants; for workload identities prefer explicit allowlists with empty = none. Interactive users can keep the unrestricted default via a separate policy class.
3. Separate “session operate” from “catalog mutate”. Even with a tight create policy, if the same token can list/update shared agents or settings, the worker becomes a tenant admin with extra steps. Split scopes: sessions:create+operate vs agents:read-selected vs agents:write / settings:*.
4. Lifetime + concurrency as hard server caps, not agent-spec hints. Ephemeral CI identities should die on wall-clock TTL even if the worker forgets to close. Cap concurrent sessions per workload id to stop fork-bombs from a stuck retry loop.
5. Inline agent specs: off for workload identities by default. Named, operator-approved agents only. If inline must exist, require a content hash allowlist of known-good specs rather than free-form YAML/JSON.
6. Audit the deny path. Log policy_id, claim keys used, and which field failed (model vs skill vs MCP vs inline). Without that, debugging “why did CI get 403” burns hours and people widen the policy instead of fixing the caller.

On architecture choice: a SessionPolicyProvider next to Authorizer is the right seam. External policy brokers work but every deployment re-implements ownership mapping + lifecycle; putting the constraint at session create is the leverage point. Per-tool auth (#379/#413) is complementary and still necessary — it does not replace create-time resource selection limits.

Happy to review a design sketch / PR for the minimal create-time policy path if useful.

[harshitsaxena214]

Hi! I've implemented the minimal SessionPolicy seam described here.

Branch: https://github.com/harshitsaxena214/trueforge/tree/feat/session-policy-seam

What it does:

Adds SessionPolicy / SessionPolicyProvider mirroring the existing Authorizer pattern
Enforced only at session creation (named-ref denials are 404, inline-spec denials are 403)
Defaults to unrestricted — zero behavior change
Operator config surface deliberately left for a follow-up
No SDK regen, no new env vars, no wire schema changes
Happy to open a formal PR once a maintainer confirms the approach is on the right track. Let me know if the direction needs adjusting!