Native .netrc support for authenticated package and module resolution

[ayashjorden]

Hi everyone,

Following up on the challenges discussed in #431 regarding authenticated resource loading, I want to pitch a native, zero-configuration solution for enterprise environments that enforce authentication on internal artifact registries (e.g., private Artifactory, Nexus) or private Git hosting platforms.

The Problem

In many corporate settings, anonymous access to configuration schemas is strictly prohibited. Currently, teams are forced to either run local authenticating sidecar proxies (like pkl-proxy) or implement complex SPICE-0009 external readers just to supply Basic Auth credentials.

As noted by @holzensp in #431, we cannot interpolate credentials into static string literal imports (e.g., import "https://\(Token)@..."), and hardcoding credentials in source files is a non-starter. We need a way for Pkl to read ambient host credentials without altering the static nature of the import graph.

Proposed Approach: Ambient .netrc Resolution

I am proposing that Pkl's core networking layer (pkl-core) adds native support for evaluating industry-standard .netrc (and Windows _netrc) files during package/module resolution.

When Pkl makes an outbound HTTPS request (HttpResourceReader or PackageResolver), it would:

1. Extract the target host from the URI.
2. Look up the host within a local .netrc file.
3. If matched, automatically inject the standard Authorization: Basic <base64> header.

How It Addresses Previous Concerns:

• No Syntax Changes: Import paths remain pristine, completely static string literals.
• Universal Platform Support: Because major version control and artifact platforms support HTTPS Basic Auth via Personal Access Tokens or App Passwords, this single addition natively unlocks secure access to private GitHub, GitLab, Bitbucket, and Artifactory repositories without provider-specific code.
• Environment Precedence & CI/CD Synergy: To support both local workstations and containerized runners seamlessly, the file lookup path would respect the NETRC environment variable first, falling back to standard home directory locations (~/.netrc or %USERPROFILE%\_netrc). This ensures perfect compatibility with standard CI/CD workflow steps—such as the extractions/netrc GitHub Action—allowing pipelines to seamlessly pass authenticated contexts to Pkl without custom shell bootstrapping.
• Strict Security Boundaries: Credentials would only be injected on https:// schemas, never plain http://. We could also match curl's behavior and reject or warn if file permissions are laxer than 0600 on POSIX systems.

I am highly interested in contributing this on my personal time and would love to hear thoughts from the maintainers and community on this direction. If there is alignment on the approach, I have a formal SPICE design document ready to submit to apple/pkl-evolution to iron out the implementation details.

What do you think?

[HT154]

Hi there!

Personally, I'm skeptical that this is something that Pkl should do implicitly by default, but I'm open to discuss this in more depth. I'd encourage you to join us in our biweekly community call and/or the pkl.community Discord (not maintained by us) if you'd like to discuss this in a more synchronous venue.

All that said, you can achieve this pretty simply now with the support for generalized HTTP headers that was recently released with Pkl 0.32. You can place this in your Pkl settings file (~/.pkl/settings.pkl):

amends "pkl:settings"

http {
  // Attempt to read netrc file from env-specified path, falling back to ~/.netrc
  // Windows support left as an exercise to the reader (hint: import "pkl:platform")
  local netrc = read?(read?("env:NETRC") ??  "\(read("env:HOME"))/.netrc")

  headers {
    when (netrc != null) {
      for (entry in parseNetrc(netrc)) {
        [entry.globPattern] {
          ["Authorization"] = entry.authorizationHeader
        }
      }
    }
  }
}

// Implementation left as an exercise for the reader
const local function parseNetrc(input: Resource): List<NetrcEntry> = TODO()

local class NetrcEntry {
  machine: String
  login: String
  password: String

  fixed globPattern: String = "https://\(machine)/**"
  fixed authorizationHeader: String = "Basic \("\(login):\(password)".base64)"
}

(this ^ is freehanded, so it may need tweaking!)

This configuration appears to address every concern you've enumerated, with the exception of checking for hardened .netrc file permissions. As an alternative to the machine-global settings file, the same can also be achieved in a PklProject file's evaluatorSettings.

[ayashjorden]

Hi @HT154 ,
Thank you for the quick reply and suggestions.

While the above provides a way to support adding auth headers, I'm thinking from an ergonomics angle that

1. This code will be common for every project that needs Pkl to access authenticated (and probably authorized?) package repositories.
2. Developers will have the above logic repeated (or in the optimistic case, exported as a Pkl package on an anonymous access endpoint (which would have to be trusted by dev/users/company).
3. Baking it into pkl-commons and pkl-core (netrc parser, and auth-header-handling respectively) will save lines-of-code and will standardize the pattern.

I believe we have until 7/22/2026@9am PT to continue here, and decide if we want to add this to the agenda of that meeting.

Thanks!

[bioball]

We chatted about possibly adding an API to settings.pkl that loads from your netrc; maybe something like:

amends "pkl:settings"

http = super.http |> withNetRc

I think we're unlikely to make this a default, but it might make sense to make this easier for users to configure their machine for.

[ayashjorden]

Thank you for driving the discussion.

Do you think this is something I can pick up?

[HT154]

I'm in agreement with @bioball on the form this should take. We would definitely welcome a contribution here. I would advocate for withNetrc to be an external property of the settings module so that it can be implemented in Java with the same file permissions check that curl uses.

[bioball]

Feel free to submit a PR for this, @ayashjorden

[ayashjorden]

Feel free to submit a PR for this, @ayashjorden

@bioball #1817