Local Unix Domain Socket Authentication — a request/response protocol by which a process that must make an authentication decision defers that decision to another process on the same machine, over a unix domain socket.
The protocol is deliberately backend-agnostic. It says nothing about what a credential is or how it is checked; a conforming daemon may validate JWTs, query a directory, or read a flat file.
Status: nothing here is implemented yet. This repository currently holds the specification and nothing else.
SPEC.mdis draft v0.1 and protocol version 1 is not frozen — field tags may still be renumbered. Do not build against it expecting stability.
A PAM module runs inside its host — for PostgreSQL, that means inside a database backend, pre-authentication, where a crash restarts the entire cluster. Parsing untrusted credentials there is the thing you want least.
LUDSA moves the decision out. The component that parses untrusted input gets its own uid, filesystem, resource limits and security context, can be written in a memory-safe language, and its crashes take down nothing but itself. What remains in the host is a thin client that speaks a bounded, fixed-size, tag-length-value protocol over a socket.
The motivating case is authenticating a Kubernetes workload to PostgreSQL using its projected service-account token instead of a long-lived password, with no changes to PostgreSQL itself. That backend lives in a separate repository; none of it is in scope here.
Several of the rules exist to close specific failure modes, and are easy to discard as fussy if you do not know which:
- Odd tags are critical, even tags are skippable. Skip-unknown is a fail-open evolution mode, which is unacceptable in an authentication protocol. A future field meaning "the audience check was not performed" takes an odd tag, so an older peer refuses rather than reading a qualified answer as approval.
- Version mismatch is rejected outright. No negotiation, no compatibility shim. The two ends ship as separate images on separate cadences, so skew is normal — and failing immediately beats misparsing into a wrong verdict.
- Nothing is passed by reference. No field may carry a path, a file descriptor, or a shared-memory identifier, now or in any later version. Client and daemon in separate containers share no filesystem beyond the socket.
- Deterministic encoding. Ascending tag order, each tag at most once, absent fields omitted rather than sent empty — so conformance vectors compare byte-exact.
- A denial is not an error. "The credential is bad" and "I could not tell you" are different answers with different consequences, and stay distinct through the protocol, the C API and the Go API alike.
None of this exists yet. Listed so the shape of the repository is legible:
SPEC.md the protocol (present, draft)
testdata/ hand-authored vectors, language-neutral
go/wire/ codec: framing, TLV, tag skipping
go/client/ Go client
go/server/ listener, SO_PEERCRED, dispatch
cmd/ludsa-probe/ operator CLI: ping, status, auth, selftest
cmd/ludsa-mockd/ test-only server that misbehaves on demand
c/libludsa/ C client library, static, no allocation
c/pam_ludsa/ PAM module
c/ludsa-file/ reference daemon, flat file backend
c/ludsa-conformance/ malformed-message test driver
Test vectors are hand-authored from the specification and must never be generated by dumping an implementation's output — otherwise the implementation, and its bugs, become the specification.
Apache 2.0 — see LICENSE. Chosen for the explicit patent grant,
which matters to corporate adopters of authentication infrastructure.