Winix.MkAuth 0.4.0

mkauth

Compute HTTP Authorization headers (OAuth 1.0a, JWT, Basic, Bearer, Azure Storage) for curl and scripts. Single native binary, no runtime, cross-platform.

mkauth is a pure, stateless calculator — it prints one header line to stdout and exits. Use it in command substitution with curl -H "$(mkauth …)":

curl -H "$(mkauth oauth1 --method GET --url https://api.example.com/v1/thing \
              --consumer-key abc --consumer-secret 'vault:api/consumer' \
              --token def --token-secret 'vault:api/token')" \
     https://api.example.com/v1/thing

Install

Scoop (Windows)

scoop bucket add winix https://github.com/Yortw/winix
scoop install winix/mkauth

Winget (Windows, stable releases)

winget install Winix.MkAuth

.NET Tool (cross-platform)

dotnet tool install -g Winix.MkAuth

Direct Download

Download native binaries from GitHub Releases.

Usage

mkauth basic     --user NAME --password REF [options]
mkauth bearer    --token REF [options]
mkauth oauth1    --method VERB --url URL --consumer-key K --consumer-secret REF [options]
mkauth jwt       --alg ALG --key REF [claim flags] [options]
mkauth azure-storage --account NAME --key REF --method VERB --url URL [options]

All flags are listed in mkauth --help; per-subcommand flags are documented in the tables below.

The computed header is written to stdout as a Name: Value line, suitable for curl -H "$(…)". --show-base-string debug output goes to stderr. Warnings (literal-secret exposure, PLAINTEXT over non-HTTPS) go to stderr.

secret references

Every secret-bearing flag takes a secret reference — a string with a scheme prefix. Secrets are never required as bare values on argv (which would expose them in shell history and ps output).

Whitespace trimming: every reference-resolved source (env:, file:, vault:, stdin) has all surrounding whitespace stripped (leading and trailing, including trailing newlines), so the same key signs the same way regardless of how it is delivered. Only literal: is used verbatim.

Empty secrets: a secret resolved from env:/file:/vault:/stdin that is empty (or whitespace-only, which trims to empty) is an error (exit 126) naming the source — signing with an empty key produces a silently-wrong header. To send an empty secret deliberately (e.g. an RFC 7617 empty password), use an explicit empty literal:.

F6 note: vault:NS/KEY splits on the first /. A namespace cannot contain /; a key may contain / characters after the first slash.

basic — Basic authentication

Computes Authorization: Basic base64(user:password) per RFC 7617.

# Hardcoded user, password from environment variable
mkauth basic --user alice --password env:API_PASSWORD

# Both from the OS keychain
mkauth basic --user alice --password 'vault:api/password'

# Feed to curl
curl -H "$(mkauth basic --user alice --password env:API_PASSWORD)" https://api.example.com/data

basic options

bearer — Bearer token

Outputs Authorization: Bearer <token> per RFC 6750. Pure passthrough — the resolved token value is used as-is.

# Token from environment variable
mkauth bearer --token env:ACCESS_TOKEN

# Token from keychain
mkauth bearer --token 'vault:myapp/token'

# Feed to curl
curl -H "$(mkauth bearer --token env:ACCESS_TOKEN)" https://api.example.com/data

bearer options

oauth1 — OAuth 1.0a signed header (flagship)

Computes the full OAuth 1.0a Authorization header (RFC 5849) including the percent-encoded signature base string, signing key, and HMAC or PLAINTEXT signature.

Scope note: mkauth oauth1 signs a request given credentials. It does not perform the OAuth 1.0a 3-legged request-token→authorize→access-token dance. Token acquisition is a separate flow, out of scope for this tool.

# 2-legged (no token) with HMAC-SHA1
mkauth oauth1 --method POST --url https://api.example.com/data \
              --consumer-key mykey --consumer-secret 'vault:myapp/consumer-secret'

# 3-legged with HMAC-SHA256
mkauth oauth1 --method GET --url 'https://api.example.com/timeline?count=10' \
              --consumer-key mykey --consumer-secret env:CONSUMER_SECRET \
              --token mytoken --token-secret env:TOKEN_SECRET \
              --signature-method HMAC-SHA256

# Include body params in signature (application/x-www-form-urlencoded bodies)
mkauth oauth1 --method POST --url https://api.example.com/post \
              --consumer-key k --consumer-secret env:CS \
              --param "status=Hello World" --param "source=myapp"

# Show the computed signature base string (debug)
mkauth oauth1 --method GET --url https://api.example.com/thing \
              --consumer-key k --consumer-secret env:CS \
              --show-base-string

# Feed to curl
curl -H "$(mkauth oauth1 --method GET --url https://api.example.com/v1/me \
              --consumer-key abc --consumer-secret 'vault:api/consumer' \
              --token def --token-secret 'vault:api/token')" \
     https://api.example.com/v1/me

oauth1 options

Signature algorithm

The signature base string is METHOD & pct(base_url) & pct(normalized_params), where:

• base_url = scheme + authority + path (scheme/host lowercased, default port dropped, no query/fragment)
• normalized_params = RFC 3986 percent-encoded, lexicographically-sorted, &-joined merge of URL query params + --param params + oauth_* params (excluding realm and oauth_signature)
• Signing key = pct(consumer_secret) & pct(token_secret)

PLAINTEXT warning: PLAINTEXT sends the signing key as the signature. mkauth warns to stderr if the URL scheme is not https.

jwt — JWT minting and signing

Mints a JSON Web Token (RFC 7519) and wraps it as Authorization: Bearer <jwt>. Useful for service-account auth (Google service accounts, GitHub Apps) that require a freshly signed JWT per call.

# HS256 with a shared secret
mkauth jwt --alg HS256 --key 'vault:myapp/jwt-secret' \
           --iss myapp --sub user123 --exp 1h

# RS256 with a PEM private key file
mkauth jwt --alg RS256 --key file:/path/to/private.pem \
           --iss myapp@project.iam.gserviceaccount.com --sub api@example.com \
           --aud https://api.example.com/ --exp 1h --iat

# ES256 with key from keychain
mkauth jwt --alg ES256 --key 'vault:apps/jwt-key' \
           --claim scope=read:data --claim-num priority=1 \
           --kid my-key-id

# Arbitrary claims from a JSON file
mkauth jwt --alg HS256 --key env:JWT_SECRET \
           --claims-file /path/to/claims.json --exp 15m

# Header value only: strips the 'Authorization:' name but KEEPS the 'Bearer ' prefix -> 'Bearer <jwt>'
mkauth jwt --alg HS256 --key env:JWT_SECRET --sub user --exp 1h --value-only

# Feed to curl
curl -H "$(mkauth jwt --alg RS256 --key file:private.pem \
              --iss svc@project.iam.gserviceaccount.com \
              --aud https://api.example.com/ --exp 1h --iat)" \
     https://api.example.com/data

jwt options

ES curve requirement: an ES* algorithm fixes the EC curve (RFC 7518 §3.4). The supplied PEM key must use the matching curve, or signing fails with a runtime error (exit 126):

azure-storage — Azure Storage SharedKey

Computes the Authorization: SharedKey account:signature header for Azure Storage REST API requests (Blob, Queue, and File services).

# Sign a Blob GET request
mkauth azure-storage --account mystorageacct \
                     --key env:STORAGE_ACCOUNT_KEY \
                     --method GET \
                     --url 'https://mystorageacct.blob.core.windows.net/mycontainer/myblob' \
                     --x-ms-version 2023-11-03

# Show the StringToSign (debug)
mkauth azure-storage --account mystorageacct --key env:STORAGE_KEY \
                     --method PUT --url 'https://mystorageacct.blob.core.windows.net/c/b' \
                     --header 'Content-Type: application/octet-stream' \
                     --show-base-string

# Feed to curl (note: x-ms-date and x-ms-version must match the headers you send)
DATE=$(date -u '+%a, %d %b %Y %H:%M:%S GMT')
curl -H "x-ms-date: $DATE" \
     -H "x-ms-version: 2023-11-03" \
     -H "$(mkauth azure-storage --account mystorageacct --key env:STORAGE_KEY \
               --method GET --url 'https://mystorageacct.blob.core.windows.net/c/b' \
               --x-ms-date "$DATE" --x-ms-version 2023-11-03)" \
     'https://mystorageacct.blob.core.windows.net/c/b'

azure-storage options

Common flags (all subcommands)

Composability with curl

The primary use pattern — command substitution feeding curl -H:

# OAuth 1.0a
curl -H "$(mkauth oauth1 --method POST --url https://api.example.com/data \
              --consumer-key k --consumer-secret env:CS \
              --token t --token-secret env:TS)" \
     -d '{"key":"value"}' https://api.example.com/data

# JWT service account
curl -H "$(mkauth jwt --alg RS256 --key file:service-account.pem \
              --iss svc@project.iam.gserviceaccount.com \
              --aud https://api.example.com/ --exp 1h --iat)" \
     https://api.example.com/data

# Basic auth (keep password out of shell history)
curl -H "$(mkauth basic --user alice --password 'vault:myapp/password')" \
     https://api.example.com/protected

# Bearer token from keychain
curl -H "$(mkauth bearer --token 'vault:myapp/access-token')" \
     https://api.example.com/api

For other HMAC schemes, use digest

mkauth handles OAuth 1.0a, JWT, Basic, Bearer, and Azure SharedKey. For other body-based HMAC schemes (Stripe webhooks, GitHub webhooks, generic timestamp.body patterns), use digest --hmac directly:

# Generic HMAC-SHA256 of a body (Stripe / GitHub style)
printf '%s.%s' "$ts" "$body" | digest --hmac sha256 --key-env WEBHOOK_SECRET --base64

# Stripe webhook signature
echo -n "${ts}.${payload}" | digest --hmac sha256 --key-env STRIPE_WEBHOOK_SECRET --base64

# HMAC over a file
digest --hmac sha256 --key-file signing.key payload.json

AWS SigV4 is covered by curl --aws-sigv4 (built in to curl). mkauth does not duplicate it.

Storing secrets in the keychain

Use envvault to store secrets in the OS keychain and pass them to mkauth via vault: references:

# Store once
envvault set myapp consumer-secret "my-consumer-secret-value"

# Use in mkauth (secret never touches argv or shell history)
mkauth oauth1 --method GET --url https://api.example.com/me \
              --consumer-key mykey --consumer-secret 'vault:myapp/consumer-secret'

Exit Codes

Colour

mkauth output is plain (no coloured output). The --color and --no-color flags are accepted for suite consistency. NO_COLOR is respected.

Related Tools

• envvault — store secrets in the OS keychain and inject them as env vars: vault:NS/KEY references in mkauth read from the same store
• digest — HMAC and cryptographic hashing for body/payload signing schemes
• mksecret — generate HMAC signing keys, API keys, and other secrets

See Also

• man mkauth (after winix install man)
• mkauth --describe for JSON metadata