# AUTH-001 evidence pack — portfolio capability broker

## 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`
