Skip to content

feat: add resource resolver for URL-referenced harness resources - #1623

Merged
ggallen merged 1 commit into
mainfrom
feat/resource-resolver
Jun 1, 2026
Merged

ggallen merged 1 commit into
mainfrom
feat/resource-resolver

Conversation

@ggallen

@ggallen ggallen commented May 27, 2026

Copy link
Copy Markdown
Member

Summary

  • Adds internal/resolve/ package that orchestrates fetch, cache, validation, and audit logging for URL-referenced declarative harness fields (agent, policy, skills)
  • Exports FetchPolicy.TLSConfig and SkipIPCheck fields for cross-package test use
  • Fixes ResolveRelativeTo to skip URL-valued fields (resolves TODO(PR 7))

Test plan

  • 13 new tests in internal/resolve/resolve_test.go: local pass-through, URL fetch+cache, cache hit, hash mismatch, allowlist rejection, missing hash, offline miss/hit, mixed harness, audit entries, multiple skills, policy URL, empty fields
  • New test TestResolveRelativeTo_URLsUnchanged in internal/harness/harness_test.go
  • go test ./... passes
  • go vet ./... clean

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented May 27, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://204eb7fa-site.fullsend-ai.workers.dev

Commit: b8fe5690a6680435e8a602ec1174db0117a37716

@fullsend-ai-review

fullsend-ai-review Bot commented May 27, 2026 •

Copy link
Copy Markdown

Review

Findings

No findings.

Previous run

Review

Reason: stale-head

The review agent reviewed commit 799682ee39183256e8d16c6291be2e376d3005a5 but the PR HEAD is now b8fe5690a6680435e8a602ec1174db0117a37716. This review was discarded to avoid approving unreviewed code.

Previous run (2)

Review

Findings

Low

  • [platform-security] internal/fetch/fetch.go:53 — NewTestPolicy is exported, giving any importing package a way to construct a FetchPolicy with skipIPCheck: true (SSRF bypass). The NewTest naming convention and doc comment clearly signal test-only use, and the underlying fields remain unexported, so the risk is low. Consider a build-tag guard if the package gains external consumers.

  • [documentation-currency] docs/plans/universal-harness-access.md:940 — Code examples in the design doc still show the old ResolvedHarness struct and old ResolveHarness signature (lines ~940–957, 1138, 1241). A note was added at line ~924 clarifying the implementation differs, which is sufficient for a design doc, but readers may still be confused by the stale examples.

Previous run (3)

Review

Findings

Medium

  • [allowlist-fragment-coupling] internal/resolve/resolve.go:68 — MatchingAllowedPrefix receives the raw URL including the #sha256=... fragment before ParseIntegrityHash strips it. This works today because normalizeURLPath preserves fragments in parsed.String(), so prefix matching succeeds. However, this couples allowlist validation to the fragment-handling behavior of url.Parse. If normalizeURLPath is ever refactored to strip or ignore fragments (a reasonable change), allowlist matching would silently break — every URL would fail the allowlist check even when its base URL is permitted.
    Remediation: Call ParseIntegrityHash first to get the clean URL, then pass the clean URL to MatchingAllowedPrefix. This also makes the data flow clearer — allowlist checks operate on the canonical URL, not a URL with an integrity tag appended.

Low

  • [test-helper-in-prod] internal/fetch/fetch.go:57 — NewTestPolicy is exported in production code (fetch.go) rather than in an export_test.go or test-only file. It bypasses SSRF IP-check protections (skipIPCheck: true). The internal/ package boundary limits exposure to within the module, but placing it in production code means any in-module caller could use it outside tests without compiler enforcement. The standard Go pattern for cross-package test helpers is an export_test.go file, though that only works within the same package's test binary.
    Remediation: Consider adding a // Testing only. doc comment at minimum. If feasible, restructure to use a test-only export pattern.

  • [missing-edge-case-test] internal/resolve/resolve_test.go — No test covers a URL with a non-sha256 fragment (e.g., #section-heading) that passes the allowlist check but fails ParseIntegrityHash. The code handles this correctly (returns "must include #sha256=..." error), but a test would document the interaction between fragment-bearing URLs and the integrity requirement.

  • [stale-plan-doc] docs/plans/universal-harness-access-implementation.md:145 — The PR 7 section describes ResolvedHarness struct, ResolveOpts with OrgAllowlist, and ResolveHarness returning (*ResolvedHarness, error). The actual implementation returns ([]Dependency, error) with in-place harness mutation. As a planning document, divergence is expected, but updating it would help future readers.

  • [stale-design-doc] docs/plans/universal-harness-access.md:310 — Design document describes ResolveHarness returning (*ResolvedHarness, error) with a wrapper struct. Actual implementation simplified to in-place mutation. Adding a note about the implemented API would improve accuracy.

Previous run (4)

Review

Findings

Low

  • [platform-security] internal/fetch/fetch.go:44-50 — Exporting TLSConfig and SkipIPCheck widens the API surface for SSRF-hardening bypass. Any caller can now set SkipIPCheck: true to disable internal-IP validation or inject a custom TLSConfig. The doc comments warn against production use and the fetchtest.NewTestPolicy helper provides the sanctioned path, but there is no compile-time enforcement preventing misuse in production code.
    Remediation: Consider keeping these fields unexported and providing a WithTestOverrides functional option or a build-tag-gated constructor that only compiles in test binaries.

Info

  • [correctness] internal/resolve/resolve.go:34 — The implementation plan (docs/plans/universal-harness-access-implementation.md:151) specifies InputPipeline security scanning of fetched remote content before use (with stricter thresholds for remote resources). The current implementation defers this step, as noted by the "Phase 1" comment. This is acceptable for incremental delivery but should be tracked — without scanning, fetched content is used based solely on hash pinning and domain allowlisting.
Previous run (5)

Review

Findings

Low

  • [test-coverage] internal/harness/harness.go — MatchingAllowedPrefix (the new string-returning variant) has no direct unit test in harness_test.go. It is exercised transitively through resolve package tests, but a dedicated test verifying the returned prefix string would guard against regressions if the resolve tests change.

Info

  • [docs-currency] docs/plans/universal-harness-access-implementation.md:145-148 — The PR 7 section describes a ResolvedHarness wrapper struct and a ResolveHarness signature returning (*ResolvedHarness, error). The actual implementation takes a simpler approach: modifying the harness in-place and returning ([]Dependency, error). The design doc (universal-harness-access.md:956) similarly shows the older signature. Since these are plan documents (not reference docs), minor divergence is expected, but updating them would prevent confusion for future contributors.

  • [style] internal/fetch/fetch.go — Exporting TLSConfig and SkipIPCheck on FetchPolicy is a standard Go pattern for cross-package test configuration, and the doc comments clearly mark them as test-only. The secure-by-default zero values (nil/false) and the fetchtest.NewTestPolicy helper provide adequate guardrails. No action needed.

Previous run (6)

Review

Findings

Low

  • [platform-security] internal/fetch/fetch.go:44-51 — Exporting TLSConfig and SkipIPCheck widens the public API surface for security-sensitive fields. Any package can now disable SSRF internal-IP validation by setting SkipIPCheck: true. Mitigated by: (1) DefaultPolicy has safe zero values, (2) comments document test-only intent, (3) fetchtest.NewTestPolicy provides the canonical test construction path. No action required — this is standard Go practice for cross-package test support, but worth noting for future audits.

  • [style] internal/resolve/resolve.go:66,115 — resolveURL calls h.MatchesAllowedPrefix(rawURL) for the boolean guard (line 66), then later calls h.MatchingAllowedPrefix(rawURL) for the audit AllowedBy value (line 115). Since MatchesAllowedPrefix now delegates to MatchingAllowedPrefix, this performs URL normalization and prefix matching twice. Could save the result from a single MatchingAllowedPrefix call and check for empty string.

Previous run (7)

Review

Findings

No findings.

Previous run (8)

Review

Findings

Low

  • [correctness] internal/resolve/resolve.go:136-143 — matchingPrefix uses simple case-insensitive strings.HasPrefix to find the AllowedBy value for audit logging, while the security-critical MatchesAllowedPrefix in harness.go normalizes URL paths (percent-decoding, dot-segment resolution) before prefix matching. When a URL matches only after normalization (e.g., contains encoded characters or // segments), matchingPrefix returns "" — producing a misleading allowed_by: "" in the audit log even though the URL was legitimately allowed. No security impact (the actual enforcement in MatchesAllowedPrefix is correct), but the audit trail becomes unreliable for incident investigation.
    Remediation: Reuse harness.MatchesAllowedPrefix logic or call normalizeURLPath in matchingPrefix to align matching semantics, or return all matching prefixes from MatchesAllowedPrefix directly.

Info

  • [correctness] internal/resolve/resolve.go — The implementation plan (PR 7 spec in docs/plans/universal-harness-access-implementation.md) describes a security scan step after fetch ("security scan (InputPipeline, remote threshold)") that is not present in this implementation. Since content is integrity-verified via SHA256 (the hash is pre-committed in the harness), the content is deterministic and known at configuration time, making fetch-time scanning less critical. Worth confirming this is an intentional Phase 1 deferral.
Previous run (9)

Review

Findings

Medium

  • [platform-security] internal/fetch/fetch.go:47-51 — Exporting TLSConfig and SkipIPCheck widens the API surface for SSRF bypass. These fields were deliberately unexported with comments noting they are "used in tests." Any internal/ consumer can now construct a FetchPolicy with SkipIPCheck: true (disabling internal-IP validation) or a permissive TLSConfig. While the resolve package legitimately needs cross-package access and these are internal/ (not public API), consider an alternative such as a TestPolicy() constructor or a WithTestOverrides() option to keep the safe-by-default surface intact.
    Remediation: Introduce an unexported fetchOpts struct or a NewTestPolicy() helper that bundles TLS and IP-check overrides, keeping the FetchPolicy struct's exported fields safe-by-default.

Low

  • [correctness] internal/resolve/resolve.go:28 — OrgAllowlist field in ResolveOpts is declared but never referenced in ResolveHarness or resolveURL. This is dead code that may confuse future maintainers about where org-level allowlist enforcement happens (it's in harness.ValidateAllowedRemoteResources, not here).
    Remediation: Remove OrgAllowlist from ResolveOpts or add a TODO comment explaining planned Phase 2 usage.

  • [correctness] internal/resolve/resolve.go:127 — The audit write error is silently discarded (_ = fetch.AppendFetchAudit(...)). While best-effort logging is reasonable, a persistent filesystem issue (permissions, disk full) would go unnoticed across all resource resolutions in a run.
    Remediation: Log the error at warn/debug level rather than discarding, or return it as a non-fatal warning in the Dependency struct.

@fullsend-ai-review fullsend-ai-review Bot added the requires-manual-review Review requires human judgment label May 27, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from 02d981c to 837c49a Compare May 27, 2026 21:36
@ggallen

ggallen commented May 27, 2026

Copy link
Copy Markdown
Member Author

All three findings addressed in 837c49a:

  • Medium [platform-security]: Reverted TLSConfig and SkipIPCheck back to unexported fields. Added NewTestPolicy(tlsConfig, allowedDomains, allowedPorts) constructor that bundles the test-only overrides behind a single entry point, keeping the default FetchPolicy surface safe-by-default. Updated fetch_test.go and resolve_test.go to use the new constructor.

  • Low [correctness] — dead OrgAllowlist: Removed OrgAllowlist from ResolveOpts. Org-level allowlist enforcement is handled by harness.ValidateAllowedRemoteResources (called from the CLI layer in PR 8), not by the resolver.

  • Low [correctness] — silent audit error: Audit write errors are now logged via log.Printf at warning level instead of being silently discarded.

Comment thread internal/resolve/resolve.go Resolved
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed requires-manual-review Review requires human judgment labels May 27, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from 837c49a to b0f0a31 Compare May 27, 2026 21:49
@ggallen

ggallen commented May 27, 2026

Copy link
Copy Markdown
Member Author

All findings from the latest review addressed in b0f0a31:

  • Low [correctness] matchingPrefix normalization mismatch: Fixed. Extracted MatchingAllowedPrefix from MatchesAllowedPrefix in the harness package — returns the matching prefix string with full URL normalization. matchingPrefix in resolve.go is removed; audit logging now calls h.MatchingAllowedPrefix(rawURL) directly.

  • Info [correctness] InputPipeline scanning not present: Intentional Phase 1 deferral. Hash-pinned integrity verification ensures content hasn't been tampered with; the sandbox bootstrap layer will scan content at execution time.

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels May 27, 2026

@maruiz93 maruiz93 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found three minor issue but I think they are worth to address

Comment thread internal/resolve/resolve.go Resolved
Comment thread internal/resolve/resolve.go Resolved
Comment thread internal/fetch/fetch.go Resolved
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels May 29, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from 2504856 to 6782efd Compare May 29, 2026 17:31
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels May 29, 2026
Comment thread internal/fetch/fetch.go Resolved
Comment thread internal/resolve/resolve.go Resolved
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels May 29, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from b6aef4e to 7a548f0 Compare May 29, 2026 22:25
@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment and removed ready-for-merge All reviewers approved — ready to merge labels May 29, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from 7a548f0 to 06fa05d Compare June 1, 2026 10:48
Comment thread internal/fetch/fetch.go Resolved
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed requires-manual-review Review requires human judgment labels Jun 1, 2026
@ggallen
ggallen force-pushed the feat/resource-resolver branch from 06fa05d to 799682e Compare June 1, 2026 10:58
Introduces internal/resolve package that orchestrates fetch, cache,
validation, and audit logging for URL-referenced declarative harness
fields (agent, policy, skills). Modifies the harness in place,
replacing URLs with local cache paths. Phase 1: single-level only.

Moves NewTestPolicy to internal/fetch/fetchtest/ package for safe
cross-package test use, and fixes ResolveRelativeTo to skip
URL-valued fields.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Greg Allen <gallen@redhat.com>
@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels Jun 1, 2026
@ggallen
ggallen requested a review from maruiz93 June 1, 2026 11:21
@ggallen
ggallen added this pull request to the merge queue Jun 1, 2026
Merged via the queue into main with commit 793ff92 Jun 1, 2026
12 checks passed
@ggallen
ggallen deleted the feat/resource-resolver branch June 1, 2026 16:20

This branch was successfully deployed

1 active deployment
site-preview — b8fe5690 Deployed Jun 1, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-merge All reviewers approved — ready to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants