README
¶
comfylib
Shared Go packages for the Comfyware apps, Imvault and Witmoot.
It holds the security-sensitive plumbing both apps need and should get right once: Bubblewrap confinement, systemd and OpenRC configuration lookup, SMTP sending, key files, tokens, client addresses behind trusted proxies, and reverse-proxy configuration. Application policy, storage schemas, and user interfaces stay in each app.
comfylib uses only the Go standard library, so it adds no further modules to either app's dependency tree. It is versioned as v0 while its API settles; each app pins an exact version.
Packages
| Package | What it does |
|---|---|
clientip |
Finds the client address behind trusted reverse proxies, groups IPv6 clients by /64 for rate limits, and tells whether the original request used HTTPS. |
keyfile |
Loads a key from its own file, creating it atomically on first use, in raw or hex form. |
proxyconfig |
Prints a validated Caddy, nginx or Apache site configuration from an app's own examples. |
proxyconfig/proxytest |
Runs those configurations in real nginx and Apache servers for an app's integration tests. |
smtp |
Sends transactional mail through a relay with required TLS, header-injection checks, and no logging of message bodies. |
token |
Mints random tokens, hashes them for storage, and compares them in constant time. |
The sandbox, service-configuration and privilege-dropping packages arrive separately.
Checks
make check runs formatting, vet, cyclomatic complexity, golangci-lint, the
race-enabled tests, the mutation engine's self-test, and every mutation table
under mutations/. make test-sandbox needs a working bwrap;
make test-proxies needs nginx and Apache; make fuzz-smoke runs every fuzz
target briefly. CI runs all of them.
tools/mutate.py applies each mutation in a table to a throwaway copy of the
tree and requires the named tests to fail. The apps keep their own tables and
a synced copy of the script.
Developing alongside an app
Use a go.work file in the app's worktree rather than a replace directive:
go work init . ../comfylib
go.work is ignored by git. Never commit a replace directive or a go.work
file in an app; release builds, the Gentoo ebuilds, and Docker images all
resolve comfylib through the Go module proxy.
Licensed under AGPL-3.0-or-later. See LICENSE.
Documentation
¶
Overview ¶
Package comfylib holds the code Imvault and Witmoot share: service confinement, service configuration, mail sending, key files, tokens, client addresses behind proxies, and reverse-proxy configuration. Each subpackage uses only the standard library and never imports application code.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package clientip finds the address of the person behind a request, believing forwarding headers only from proxies the operator named.
|
Package clientip finds the address of the person behind a request, believing forwarding headers only from proxies the operator named. |
|
Package keyfile keeps a random key in a file of its own, creating it on first use.
|
Package keyfile keeps a random key in a file of its own, creating it on first use. |
|
oidc
module
|
|
|
Package privdrop re-runs an administrative command as the installed service's account when an operator starts it as root, for example with sudo.
|
Package privdrop re-runs an administrative command as the installed service's account when an operator starts it as root, for example with sudo. |
|
Package proxyconfig prints a reverse-proxy site configuration for an app, generated from the example files the app ships in its packages.
|
Package proxyconfig prints a reverse-proxy site configuration for an app, generated from the example files the app ships in its packages. |
|
proxytest
Package proxytest runs an app's generated nginx and Apache configurations in real servers and checks what reaches the app through them.
|
Package proxytest runs an app's generated nginx and Apache configurations in real servers and checks what reaches the app through them. |
|
Package sandbox constructs explicit Bubblewrap policies.
|
Package sandbox constructs explicit Bubblewrap policies. |
|
Package smtp sends the small number of transactional messages the apps need, such as password reset links, through an SMTP relay.
|
Package smtp sends the small number of transactional messages the apps need, such as password reset links, through an SMTP relay. |
|
Package svcconfig reads an installed service's settings the way its service manager would pass them, so that a command an operator runs by hand acts on the same instance as the running service.
|
Package svcconfig reads an installed service's settings the way its service manager would pass them, so that a command an operator runs by hand acts on the same instance as the running service. |
|
Package token mints opaque secrets and hashes them for storage.
|
Package token mints opaque secrets and hashes them for storage. |