parc

.netrc support for clojure

This library implements a parser to turn .netrc files into idiomatic clojure data structures.

It also bundles some utilities functions, like ring utilities.

Background

• What is ring
• What is netrc

The problem

Many providers, like AWS, create custom credentials files, custom formats, etc, to store its credentials.

These credentials are all stored at our home folder.

This is a problem to manage access, do backups, etc.

The solution

One standard credentials description format, many implementations.

The .netrc file tries to addess this issue in a unix way.

A few, but relevant, clients like curl, GNU Inetutils, heroku-cli support it.

Using netrc file, you can specify credentials for multiple domains, and any client can use it with any transport protocol (http, ftp, etc...).

You can also encrypt your .netrc file with gnupg, avoiding writing credentials in plaintext (not implemented, yet).

Usage

Add to your deps.edn file:

br.dev.zz/parc {:git/url "https://github.com/souenzzo/parc"
                :git/sha "..."}

Default namespaces for the examples

(require '[br.dev.zz.parc :as parc]
          [br.dev.zz.parc.ring :as parc.ring])

You can add the credentials to a ring-request using parc.ring/with

By default, it will search in your ~/.netrc file. If it find a machine that matches with your server-name, it will add the Authorization header.

(parc.ring/with {:server-name "example.com"})
=> {:server-name "example.com",
    :headers     {"Authorization" "Basic ZGFuaWVsOnF3ZXJ0eQ=="}}

You can also specify a custom netrc file if you want to.

(parc.ring/with (io/file "custom.netrc") {:server-name "example.com"})
=> {:server-name "example.com",
    :headers     {"Authorization" "Basic ZGFuaWVsOnF3ZXJ0eQ=="}}

A custom netrc file should look like this:

machine api.example.com
  login my-username
  password my-password

You can also parse the netrc file.

(parc/parse (io/file "my-netrc"))
=> [{:machine  "api.example.com"
     :login    "my-username"
     :password "my-password"}]

Usage with hato

hato is a http client for clojure that implements ring

Just call parc.ring/with in the request map, before pass it to hato/request

(-> {:server-name "example.com"
     :scheme      :https
     :server-port 8080}
  ;; `with` will try to find `machine example.com` in your ~/.netrc
  ;; if it exists, it will add the credentials to the headers.
  parc.ring/with
  hato/request) 

references

• inetutils
• curl
• netrc
• go
• ruby
• javascript
• javascript (node)
• haskell
• man page

credentials file

See this xkcd comic about standards

• aws
• gcp
• azure

TODO

• Final API with better names
• Check java.net.Authenticator API
• cljc support
• Support clj-http
• Support clj-http.lite
• Support comments
• Support macros
• Support gpg