Eve library

AUTH-001 evidence pack — portfolio capability broker

Evidence

Revision 1

On this page

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:

  1. The accountable actor submits an exact proposal and rationale.
  2. A same-tenant operator or platform operator makes the policy decision.
  3. Low/medium authority may declare no human approval; high risk requires one operator approval; critical risk requires two distinct operator approvals.
  4. The requester cannot approve their own request. Duplicate approval IDs and repeat approvers do not count.
  5. 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:

  1. The Agentic Studio allowlist verifies exact/wildcard host, scheme, and HTTP method while rejecting normalized encoded internal literals.
  2. 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