Library evidence URLs

Design References

Contract

EvidenceURLResolver resolves evidence artifact paths for open, download, or preview operations. Resolver output is a safe same-origin or host-resolved URL plus optional expiry and content-type metadata. Evidence IDs, provider path lookup, authorization, and filesystem access belong to the product module or host adapter that calls the helper.

Input fields:

Field Required Behavior
Endpoint yes for built-in resolvers Safe same-origin evidence endpoint.
Path yes Raw relative artifact path; segments are escaped by the helper.
Operation no open, download, or preview; defaults to open.
ContentType no MIME hint carried as metadata.
ExpiresAt no Optional RFC 3339 expiry metadata.
APIResolver no module, portal, same-origin, or a host-named resolver.

Output fields:

Field Required Behavior
URL yes on success Same-origin path or host-resolved HTTPS URL.
ExpiresAt no RFC 3339 expiry timestamp.
ContentType no Normalized MIME type returned by the resolver.
Reason yes on denial Public denial reason such as unauthorized, expired, missing, not_found, unsafe_path, unsupported, or unregistered_resolver.

Denial returns no URL and one Reason. Named resolvers are the boundary for external evidence origins and provider-specific authorization decisions. The shared helper validates endpoint shape, artifact path shape, operation tokens, metadata, and returned href safety.

resolved, err := uikit.ResolveEvidenceURL(uikit.EvidenceURLResolverProps{
	Endpoint:  "/api/evidence",
	Path:      "receipts/2026-04-18.pdf",
	Operation: uikit.EvidenceOperationOpen,
})
if err != nil {
	return uikit.EvidenceURLResult{}, err
}
if resolved.Reason != "" || resolved.URL == "" {
	return resolved, nil
}

Consequence

Evidence URL resolution is deterministic in bus-ui while provider authority stays with the host or product module.

UI framework index

Sources