@@ -26,15 +26,26 @@ func failedToResolveRefFragmentPart(value, what string) error {
2626
2727// Loader helps deserialize an OpenAPIv3 document
2828type Loader struct {
29- // IsExternalRefsAllowed enables visiting other files
29+ // IsExternalRefsAllowed enables visiting other files. Enforced only when
30+ // ReadFromURIFunc is nil; a custom ReadFromURIFunc bypasses this flag and
31+ // owns the access policy itself — see ReadFromURIFunc.
3032 IsExternalRefsAllowed bool
3133
3234 // IncludeOrigin enables recording the file/line/column of each OpenAPI element.
3335 // Prefer this over the package-level IncludeOrigin global, which is not safe for
3436 // concurrent use.
3537 IncludeOrigin bool
3638
37- // ReadFromURIFunc allows overriding the any file/URL reading func
39+ // ReadFromURIFunc overrides how the loader reads a referenced file or URL.
40+ //
41+ // SECURITY: when a custom ReadFromURIFunc is set, IsExternalRefsAllowed is
42+ // NOT enforced — this function alone decides which locations may be read. A
43+ // func that reads whatever URI it is handed (e.g. by delegating to
44+ // DefaultReadFromURI) resolves external $refs even when IsExternalRefsAllowed
45+ // is false, which on untrusted documents enables local file reads
46+ // (`$ref: "/etc/passwd"`) and SSRF (`$ref: "http://169.254.169.254/..."`).
47+ // A custom func must apply its own scheme/host allowlist, or re-check
48+ // IsExternalRefsAllowed, before reading.
3849 ReadFromURIFunc ReadFromURIFunc
3950
4051 // JoinFunc allows overriding how relative $ref paths are resolved against
@@ -101,9 +112,9 @@ func (loader *Loader) allowsExternalRefs(ref string) (err error) {
101112}
102113
103114func (loader * Loader ) loadSingleElementFromURI (ref string , rootPath * url.URL , element any ) (* url.URL , error ) {
104- // When a custom ReadFromURIFunc is installed, defer the external-ref decision to it;
105- // the function itself is responsible for enforcing any access policy.
106- // Otherwise enforce IsExternalRefsAllowed here before attempting any I/O .
115+ // IsExternalRefsAllowed is enforced here only when no custom ReadFromURIFunc
116+ // is installed; otherwise the custom func owns the access policy (see the
117+ // SECURITY note on the ReadFromURIFunc field) .
107118 if loader .ReadFromURIFunc == nil {
108119 if err := loader .allowsExternalRefs (ref ); err != nil {
109120 return nil , err
@@ -331,7 +342,9 @@ func (loader *Loader) resolveRefPath(ref string, path *url.URL) (*url.URL, error
331342 return path , nil
332343 }
333344
334- // When a custom ReadFromURIFunc is installed, defer the external-ref decision to it.
345+ // IsExternalRefsAllowed is enforced here only when no custom ReadFromURIFunc
346+ // is installed; otherwise the custom func owns the access policy (see the
347+ // SECURITY note on the ReadFromURIFunc field).
335348 if loader .ReadFromURIFunc == nil {
336349 if err := loader .allowsExternalRefs (ref ); err != nil {
337350 return nil , err
0 commit comments