README
¶
comfylib
Shared Go packages for the Comfyware apps, Imvault and Witmoot, plus Songstead.
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 |
|---|---|
brandimage |
Bounds and normalizes uploaded PNG, JPEG and GIF branding images. |
password |
Reads confirmed passwords through an app-supplied hidden terminal reader. |
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. |
privdrop |
Re-runs administrative commands as the service account, refusing to run them as root. |
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. |
reference |
Validates web addresses and prepares explicit browser discussion drafts without networking or automatic posting. |
sandbox |
Confines a service and its child processes with Bubblewrap, and reaps orphans when the service is PID 1. |
smtp |
Sends transactional mail through a relay with required TLS, header-injection checks, and no logging of message bodies. |
svcconfig |
Reads a service's settings, data directory and account the way OpenRC and systemd pass them. |
token |
Mints random tokens, hashes them for storage, and compares them in constant time, and derives session-bound CSRF tokens. |
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.
Discussion references (v0.1.1)
reference.URL, reference.Draft, reference.Handoff and reference.Read
validate ordinary web addresses and prepare an explicit Witmoot browser draft.
Songstead and Imvault use the same URL and text limits; Witmoot validates the
handoff again and requires its normal posting flow. No networking, tokens,
service discovery or plugin machinery is added. Do not put private notes or
private album metadata in a handoff. The exported API golden records the
additive package. v0.1.1
is published and used by Songstead, Witmoot and Imvault.
The same release adds token.SessionCSRF(session, purpose). It
preserves the existing Witmoot and Imvault HMAC-SHA256 outputs for their
application purpose strings and rejects empty inputs. No existing exported
API is removed, and the library still uses only the Go standard library.
Shared administration helpers (v0.1.2)
password.Confirm handles two labeled password prompts and propagates reader
and writer failures without printing secrets. Applications keep terminal echo
control and their own password strength policy.
brandimage.Normalize accepts PNG, JPEG and GIF uploads up to 2 MiB and
2048 by 2048 pixels. It validates dimensions before decoding and emits one PNG,
preserving transparency while removing animation and metadata. Songstead,
Imvault and Witmoot use the same normalization policy.
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 brandimage validates small uploaded PNG, JPEG and GIF images and converts them to a single PNG without metadata or animation.
|
Package brandimage validates small uploaded PNG, JPEG and GIF images and converts them to a single PNG without metadata or animation. |
|
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 password provides confirmed password prompting.
|
Package password provides confirmed password prompting. |
|
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 reference provides browser-only Comfyware discussion handoffs.
|
Package reference provides browser-only Comfyware discussion handoffs. |
|
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. |