Work-package charter#
- Task ID:
AUTH-001 - Owner: Agentic Studio, shared HTTP-client, and Oshun runtime security maintainers; implementation owner: Codex
- Accountable product: V1 through V9 Oshun portfolio agent runtimes
- Priority: P0
- Target milestone: 2026-07-15 SOTA gap-closure program
- Risk tier: Critical delegated-tool, credential, tenant-isolation, SSRF, secret-exfiltration, and sandbox risk
- Dependencies: RUN-001 through RUN-005 and HITL-001 through HITL-005
- Affected runtime: Portfolio tool-authority policy plane in
@oshun/agentic-studio - Rollback strategy: Revert the source commit. The broker is a new exported policy boundary and does not migrate or reinterpret an existing persistent grant store.
- Evidence-pack location: This file
One composing broker#
PortfolioCapabilityBroker is the portfolio policy boundary. It composes the
existing Agentic Studio grant resolver, revocation cascade, handoff subset
semantics, tool-isolation rules, and the shared two-phase SSRF guard. It does
not introduce a second executed route; AUTH-002 owns binding this broker at
every tool boundary in the V1 route.
The broker is exported from @oshun/agentic-studio and the canonical SSRF
module is available through the narrow @oshun/http-client/ssrf-guard package
subpath. This keeps consumers from loading unrelated HTTP-client modules merely
to enforce network authority.
Least-privilege grant dimensions#
Every use is matched simultaneously on:
| Dimension | Enforced comparison |
|---|---|
| Agent | Exact agentId |
| Actor | Exact accountable actorId |
| Tenant | Exact tenantId |
| Run/scope | Canonical specificity order: per-run, pipeline instance, session, user, then tenant |
| Tool | Exact toolId |
| Purpose | Exact declared purpose |
| Resource | Membership in the explicit resource-ID set |
| Action | Membership in the explicit action set |
| Content trust | Explicit source and target trust-zone membership |
| Risk | Requested tier cannot exceed the grant's ceiling |
| Time | Expiry must be strictly later than the boundary check; revoked grants are never live |
After the rich dimensions are filtered, the existing resolveGrant selects the
most-specific live scope, with newest grant time as the same-scope tie-breaker.
The focused test proves that a per-run grant wins over a tenant grant and that a
different run falls back only to the explicit tenant grant. Agent, actor,
tenant, purpose, resource, action, trust-zone, and risk mismatches fail closed.
Grant request, policy, approval, and delegation#
Grant creation is a staged workflow:
- The accountable actor submits an exact proposal and rationale.
- A same-tenant operator or platform operator makes the policy decision.
- Low/medium authority may declare no human approval; high risk requires one operator approval; critical risk requires two distinct operator approvals.
- The requester cannot approve their own request. Duplicate approval IDs and repeat approvers do not count.
- Authority becomes resolvable only after policy and required approvals pass.
A child grant names its parent. Before activation the broker proves that tenant, actor, tool, purpose, scope specificity, lifetime, resources, actions, source and target trust zones, risk ceiling, approval strength, modifiers, secret IDs, credential binding, egress rules, and sandbox policy are subsets. It rejects a broader scope, changed same-scope reference, longer expiry, higher risk, weaker approval, new resource/action/secret, broader egress, sandbox widening, or credential audience/TTL widening.
Revoking a parent breadth-first revokes every delegated descendant. The broker
also invokes the existing active-run revocation cascade, so affected runs and
their sub-runs receive typed ToolRevokedEvent records. Every later use
re-resolves current state, distinguishing expired, revoked, and absent grants.
Credentials and secret isolation#
The broker recursively rejects caller arguments containing credential-bearing keys such as authorization, cookies, access/refresh/ID tokens, API keys, passwords, client secrets, and raw credentials. Argument values never enter the audit trail.
Credentials come only from an injected SecureCredentialProvider. The broker
passes a secure-storage secret reference plus tenant, agent, actor, run, tool,
audience, resource, issue time, and expiry. Returned authority is an opaque
handle, not a provider token. The handle must retain the requested audience and
resource and expire no later than the grant, the declared credential TTL, and
the hard five-minute ceiling. A missing provider, issuance failure, empty
handle, changed audience/resource, or invalid lifetime fails closed.
Every requested or credential-backing secret must appear in both the winning
grant and the canonical SecretScopeRule; tenant, agent, and tool are rechecked
through checkSecretAccess. The adversarial suite proves cross-tenant,
wrong-agent/tool, and ungranted secret access cannot reach the provider.
Egress, DNS pinning, and SSRF#
Network authority has two mandatory phases:
- The Agentic Studio allowlist verifies exact/wildcard host, scheme, and HTTP method while rejecting normalized encoded internal literals.
- The shared HTTP-client guard rejects credentials in URLs, unsafe schemes and ports, metadata hosts, bare unsafe IPs, and every unsafe DNS answer. All returned addresses are validated and pinned in a short-lived network permit.
Immediately before connection, revalidateNetworkConnection requires the exact
authorized normalized URL and method, rejects unapproved redirects, rechecks the
actual socket IP against SSRF policy, and requires it to be one of the pinned
DNS answers. A public-but-unpinned IP is reported as DNS rebinding;
private/link-local/metadata addresses are rejected before the pin comparison.
The tests cover integer-encoded loopback, a private DNS answer, an unapproved cross-host redirect, public-IP rebinding, and metadata-IP rebinding. No live network is used; injected deterministic DNS answers exercise the real policy code.
Sandbox and content trust enforcement#
Every grant carries a sandbox ceiling:
- filesystem reads and writes must resolve inside explicit absolute roots;
- sibling-prefix paths and
..traversal cannot escape a root; - process executables are exact allowlist entries;
- child spawning is separately disabled or enabled;
- network is either absent or constrained to an authorized egress permit.
Delegation can only narrow these ceilings. The adversarial suite rejects read
traversal, sibling-prefix write escape, /bin/sh, child-process spawning, and
network use under a network-disabled grant.
Content uses declare both source and target trust zones. Each must be granted.
Moving content into trusted from another zone additionally requires explicit
promotion authority, preventing an untrusted artifact from becoming trusted
merely because a tool can read and write both zones.
Immutable authority audit#
The append-only audit vocabulary is exactly:
grant-request, policy-decision, approval, use, result, denial,
revocation, and attempted-bypass.
Each event contains a monotonic sequence, prior hash, canonical details digest, and event hash. External readers receive clones. Snapshot restore verifies the entire chain—including event identity and every details digest—before accepting grant or request state. Result bodies and rationales are represented by SHA-256 where retention of clear text is unnecessary. The test constructs all eight event kinds, round-trips the snapshot, proves a raw token never appears in the audit, and proves a one-field tamper is rejected.
Adversarial verification matrix#
| Required scenario | Executed proof |
|---|---|
| Direct | Exact fully matching request selects the per-run grant and records use/result. |
| Confused deputy | Correct agent/tool with an undeclared resource/purpose is denied. |
| Cross tenant | Correct agent/tool cannot reuse a grant under another tenant. |
| Expired | Boundary time equal to expiry returns all-matches-expired. |
| Revoked | Parent and child become unusable and active-run cascades are emitted. |
| Encoded | Integer loopback 2130706433 normalizes to loopback and is denied. |
| Redirect | A changed URL cannot reuse an existing network permit. |
| DNS rebinding | A safe but unpinned address and a metadata address are both denied. |
| Secret exfiltration | Raw authorization/access-token arguments, ungranted secrets, and wrong secret scope are denied before dispatch. |
| Sandbox escape | Traversal, sibling-prefix, shell, child-process, and network escape attempts are denied. |
Automated verification#
- Focused portfolio-broker adversarial suite: 12/12 passing.
- Complete Agentic Studio regression: 323/323 across 22/22 files.
- Complete shared HTTP-client regression: 95/95 across 2/2 files, including 45/45 shared SSRF guard cases.
- Official Agentic Studio Nx typecheck: passing after repairing six existing test-harness diagnostics that had prevented the package gate from running cleanly. The source and spec projects both report zero errors.
- Shared HTTP-client production and spec TypeScript checks: zero errors.
- Dependency-aware Agentic Studio Nx build: successful for Agentic Studio and all six required dependency tasks, including contracts and HTTP-client.
- Agentic Studio package lint: successful; its 12 existing warnings are in unchanged files. Exact changed-file lint reports zero errors and zero warnings. Shared HTTP-client package lint reports all files clean.
- Changed-file Prettier check, lockfile YAML/importer validation, and
git diff --check: successful.
Artifact identity#
| Artifact | SHA-256 |
|---|---|
libs/oshun/agentic-studio/src/grants/portfolio-capability-broker.ts |
1ac4c573af279d8da60b3898c386ecabc255af9e856c6cc4cd5b886d87347c70 |
libs/oshun/agentic-studio/src/grants/portfolio-capability-broker.test.ts |
d5e3592d059c639caae731c59feb49393301187d8c05b96cd85dd227bc8b8ef0 |
libs/oshun/agentic-studio/src/grants/resolver.ts |
18890ba081c66c8cbda6781596aeba9fa9ff5f88b0c162a64ae56aa47efa1dbd |
libs/oshun/agentic-studio/src/capabilities/tool-isolation.ts |
6c268cf0f4cd45c25848d64e8944eb74659ea737495f04e8216f2e9602657670 |
libs/oshun/agentic-studio/src/handoff/handoff-protocol.ts |
0dc1077ea0e6b87686ba2b5df9d08fcef7684a6b32e1eed19aa3987576c18302 |
libs/shared/http-client/src/ssrf-guard.ts |
fb9d1b681e09d50555333197de3042762195c97343030d980efa5cf25a47d318 |
Resource-safe verification#
The verification gate reported 15 GiB RAM, 31 GiB swap, 38 GiB free disk, and 13
GiB available memory before the package regression. Vitest used one worker. Nx
targets used --parallel=1; the largest observed graph worker was about 0.9 GiB
RSS while 12 GiB remained available. Package tests, typechecks, lints, and
builds ran sequentially. No full-workspace run-many, Next, Expo, Tauri, or
native release build was attempted.
Scope and negative proof#
- This package changes backend policy and security primitives, not rendered web, PWA, admin, mobile, or Unreal UI. The frontend skill, Playwright UI automation, mobile automation, and Unreal validation are therefore inapplicable to AUTH-001.
- The broker validates sandbox requests and returns network/credential permits; it is not an operating-system container runtime. AUTH-002 owns invoking the broker and the corresponding isolated dispatcher at every V1 tool boundary.
- The secure credential provider is an injected deployment boundary. Tests use an in-memory provider to prove exact binding and expiry, not a production vault or live provider token.
- The HTTP-client suite emits warnings for pre-existing checked-in JavaScript source-map references whose map files are absent; both test files and all 95 assertions nevertheless pass. AUTH-001 does not claim those stale maps were regenerated.
Publication identity#
- Portfolio broker source commit:
f85485f3266720454243e01e312eb0e0c7954937 - Closure evidence commit:
cf8f5590b83e68da9e8dde4d9252de66c1412ec2