Scripts and Automation

Browser automation default

Use headless Chrome for browser automation and screenshot/network evidence. Avoid Firefox unless explicitly requested for a browser-specific task. Follow the testing browser guidance for private profiles, reproducible tool pins and strict TLS trust. Keep all downloaded browser tools and generated data in this repository's tmp/; do not install browser packages or trust roots system-wide for a test run.

Overview

Use the Makefile as the primary automation surface for this Go module. This repository builds a Caddy command binary at bin/authcrunch from cmd/authcrunch/main.go; the binary registers the security app, the authenticate and authorize integrations, Caddy standard modules, and caddy-trace.

Use configuration-authorization to issue and revoke SQLite API keys with security api-key issue|revoke, using private JSON input and private key files. Local user-store credential generation remains with the local commands below.

Use configuration-identity-stores to provision and manage SQLite password accounts with trusted offline security identity commands and private configuration/password input.

Use configuration-secrets to provision SQLite secret records with security secrets put|delete, choose private JSON inputs, and adopt changes through an explicit consumer reload.

For the independently installable cmd/caddy-authenticator, use the standalone authenticator reference. It owns profile-based portal login, private credentials/token/log storage, and the command's user guide. Its implementation reuses go-authcrunch/pkg/authclient; it does not load Caddy server modules or require the portal admin API.

Use release-and-versioning to maintain version authority, release targets, release CI, packaging, and publication. After changing commands, scripts, CI, build behavior, or selected dependencies, review and update the affected repo-local skills and references in the same change. Follow keeping skills current so documented commands, side effects, prerequisites, and validation match the resulting workflow.

Follow change-based test selection for development and final validation. Identify the affected tests before running them, and use filtered Makefile targets when reports are requested. Full-suite commands are for explicitly requested full-suite, CI-reproduction or release workflows, not an automatic follow-up to a focused fix.

Command Selection

Follow the repository scope, including its sole exception for ../xcaddy-caddy-security. Inspect working directories, script side effects, cleanup paths, and output overrides before execution. Run this module's automation; sibling source-module build, test, formatting, license, dependency, and cleanup workflows remain out of scope.

• Use go test -mod=readonly -count=1 -run '<selected-test-regex>' <affected-package> for focused validation; add -race when the changed behavior warrants it. Root-package tests use .. Unfiltered go test ./... runs the full suite.
• Use make build to validate VERSION and the authenticator fallback, compile cmd/authcrunch and cmd/caddy-authenticator into their corresponding bin/ executables with -mod=readonly -trimpath, and print both versions. It injects VERSION into the authenticator's main.appVersion linker variable.
• Use make when the user asks for the default build; it runs info and build.
• Use make test TEST='<selected-test-regex>' TEST_DIR='<affected-package>' for uncached, race-enabled Go tests and complete reports through pinned go tool tested and the resource guard. TEST is a regex, TEST_DIR accepts package patterns, and TEST_TIMEOUT is a quoted per-package duration (default 60m). MINIMUM_COVERAGE=1 checks for nonzero coverage; it is not a coverage goal. Read test resource controls for concurrency, memory, wall-time limits, cancellation, live output and resource evidence.
• Use make qtest TEST='<selected-test-regex>' for selected root-package tests, or set QUICK_TEST_DIR for another package. Reports go to .coverage/quick. Without TEST, qtest still runs every test in the selected package; it is not an automatic shortcut for focused validation.
• Use make run-reports to rebuild presentations from recorded tested evidence. It preserves failure status. make coverage is an alias for this operation; it does not rerun tests.
• Use make test-automation for verbose Python fixture tests of artifact identity, build metadata, and the real Make/tested lifecycle.
• Use make scan-codeql for a local Go scan, or set CODEQL_LANGUAGE to javascript-typescript, python or actions for the other CI languages. Use make test-codeql for real CLI regression fixtures in the selected language. Read the CodeQL workflow for CLI prerequisites, evidence, approved suppression policy, and findings review.
• Use make oidc-conformance-prepare and make oidc-conformance-test for the opt-in official Foundation plans against a fresh Caddy binary. Follow the conformance workflow for pinned local prerequisites, private evidence, strict TLS trust and preserved nonzero results. Conformance units/E2E and their artifacts are separate from regular testing; existing local OIDC regressions remain default. Set CONFORMANCE_RESULTS to a new directory below this checkout's tmp/; open its private index.html for explanations and links to all run evidence. Missing downloaded prerequisites require make oidc-conformance-prepare. Use make oidc-conformance-help for local tool locations and removal commands that preserve result bundles; it does not install or remove anything.
• Use the manual-only OIDC conformance Actions workflow for a downloadable report from a hosted runner. Its setup and artifact reference explains the readable summary, complete report after one ZIP extraction, original runner status and failed-run uploads. This never joins regular CI.
• Use make oidc-conformance-cleanup to remove all identified OIDC result bundles under tmp/, including custom destinations and top-level supplemental oidc-* logs, audits and browser reports, plus audit_oidc_*.py/check_oidc_*.py helpers. Reserve these temporary names for generated OIDC output; prefer keeping new diagnostics inside their run bundle. Cleanup retains the prepared workspace, dependencies and caches, records custom dependency locations for repeated cleanup, and refuses active runs/preparation. It does not clean ordinary .coverage/ or unrelated temporary files. See the cleanup scope.
• Use make ci-check only for an explicitly requested CI/full-gate workflow or as required by an explicitly invoked release workflow. It runs sequential version, automation, full Go test/report and build gates, including under make -j; requesting focused reports alone does not call for it.
• Hosted CI runs make ci-quality (version, automation fixtures and build) alongside make ci-prepare (guarded discovery/shared compilation without test bodies). Both must pass before parallel make ci-test-shard CI_SHARD=<name> jobs start in separate checkouts. A prerequisite failure skips the Go matrix. Read the parallel CI contract before changing shard selection, caching, failure gates or combined coverage. These are CI entry points, not shortcuts for focused local validation.
• Use make version-check for read-only version validation and make artifact-id for version/timestamp/commit identity and CI outputs. After an explicit VERSION edit, make version-sync updates the authenticator's Go install fallback without bumping or staging a release.
• Use make fmtcfg to format Caddyfile fixtures under testdata/caddyfile_adapt and assets/config; it requires an existing bin/authcrunch.
• Use make clean only when cleanup is requested; it removes generated .coverage/ and bin/ directories.

If documentation mentions make ctest, treat it as stale in this repository and choose filtered make test, filtered make qtest, or direct go test instead.

Tooling and Dependencies

Read the module's Go minimum and Caddy dependency from go.mod; inspect Makefile separately for the Caddy version used by devbuild. CI explicitly selects its Go and Node versions in the build workflow, with GOTOOLCHAIN=local; Python runs automation. The default Go suite requires Chrome/Chromium for Caddy browser refresh E2E. Set AUTHCRUNCH_TEST_BROWSER when autodetection cannot find the executable. Missing browser/Node prerequisites fail the test; no sibling UI build or npm dependency installation is needed. See browser validation.

go.mod and go.sum pin github.com/greenpau/tested and the release tool github.com/greenpau/versioned/cmd/versioned; use go tool tested and go tool versioned. make dep downloads/verifies module dependencies and resolves tested. make install-test-tools runs its version command without global installs or module edits. The other maintenance tools, such as xcaddy for devbuild and versioned for the license recipes, must already be on PATH; make dep does not install them. make license selects tracked and nonignored new Go files through Git. It must not traverse ignored tmp/, suite checkouts, tool caches or vendored modules; rewriting those files would invalidate the unmodified dependency evidence.

Module/tool downloads and xcaddy can need network access. Tests and builds do not run module tidy, license rewrites, download-link regeneration, or Caddyfile formatting. Use explicit maintenance targets when those changes are intended.

Development Builds

cmd/authcrunch and make build include the core security app and HTTP integrations. Select every optional backend explicitly in an xcaddy build with its own --with argument; see the companion mapping. The app and its companions should use the same tag or commit. The plugins/ packages are not separate Go modules. Root tests and their companion-enabled fixture commands import required companions explicitly; those fixtures do not describe default production linkage. Offline SQLite administration remains available independently of Caddy module registration.

make devbuild uses the explicitly permitted ../xcaddy-caddy-security workspace. It removes files there, changes into that directory, and runs xcaddy to build Caddy with this module, the static secrets manager, caddy-trace, and a local go-authcrunch replacement. The final binary is bin/authcrunch in this repository.

Use this target when an integrated xcaddy build is needed. Check the actual workspace and cleanup paths before running it, including whether a symlink redirects them. The exception is limited to ../xcaddy-caddy-security; overriding PLUGIN_NAME must not redirect writes to another sibling. The Makefile hard-codes the go-authcrunch replacement path in a --with ...=... argument; verify it selects the intended existing checkout, and keep that checkout read-only. Use make build when the normal Caddy wrapper meets the task.

Local go-authcrunch Development

For an explicitly requested published version, use a targeted upgrade from this repository: go get github.com/greenpau/go-authcrunch@<requested-version>, then go mod tidy and go mod verify. Inspect the dependency diff and keep the versioned replacement examples in CONTRIBUTING.md and the xcaddy argument in Makefile aligned. Do not use make upgrade for a single-module request: it updates all dependencies. make sync takes its version from the sibling's VERSION, which may differ from the requested release. Confirm the selected module's Dir and absence of an unintended Replace before validation.

For official OIDC qualification of newer committed work, select its exact published commit with go get github.com/greenpau/go-authcrunch@<commit>. The resulting immutable pseudo-version must match the intended sibling revision; the conformance harness rejects local replacements. Record the selected module checksum and origin, and keep sibling source and Git state read-only.

Development in caddy-security often connects this module to a local github.com/greenpau/go-authcrunch checkout that sits next to the caddy-security directory in the filesystem tree. If caddy-security is at <parent>/caddy-security, assume go-authcrunch is at <parent>/go-authcrunch; from this repository, that path is ../go-authcrunch.

Use a Go module replacement when the task requires consuming existing local go-authcrunch changes. Edit only this repository's go.mod and validate this module; do not develop, format, tidy, or test the sibling checkout. Read the currently required go-authcrunch version from this repository's go.mod:

go list -m -f '{{.Version}}' github.com/greenpau/go-authcrunch

Then use that required version in the replacement command:

go mod edit -replace github.com/greenpau/go-authcrunch@<go-authcrunch-version-from-go.mod>=../go-authcrunch

Keep the replacement while this module intentionally depends on existing unreleased upstream changes. Upstream implementation and publication happen as separate work. Once the required version is available, update this repository's dependency, remove its local replacement, and test here. make sync removes local go-authcrunch replacements after updating references; it must not be used as a reason to edit or release the sibling first.

After changing the selected Caddy or go-authcrunch version, audit delegated Caddyfile grammar and examples using Syntax maintenance. A dependency update can change accepted directives even when no local parser switch changes. Refresh the owning configuration skills and syntax comments.

Asset and Documentation Scripts

assets/scripts/generate_downloads.sh rewrites Caddy download links in README.md. See release-and-versioning for version inputs and regeneration requirements. It is called by make release, make minor-release, their fast- variants, and make license.

assets/scripts/update_doc_refs.sh reads ../go-authcrunch/VERSION, updates go-authcrunch references in CONTRIBUTING.md, Makefile, and go.mod, removes local go-authcrunch replace directives from go.mod, then runs go mod tidy, go mod verify, make, and make test. make sync invokes this script.

Use make sync only for an explicit go-authcrunch reference refresh. The script assumes a sibling ../go-authcrunch checkout and uses BSD/macOS sed -i '' syntax. The sibling VERSION is an input only; all reference updates, module commands, builds, and tests run in caddy-security.

Other Targets

• make upgrade runs go get -u ./... and go mod tidy; use it only for an explicit dependency upgrade.
• make license applies the repository license header to every Go file with versioned and regenerates download links; expect broad source changes.
• make logo requires GraphicsMagick gm and rewrites assets/docs/images/logo.png.
• make linter is currently a placeholder and does not run golint.

Generated Artifacts

Do not treat generated outputs as source changes unless the user explicitly asks to update or commit them.

• bin/authcrunch is produced by build/devbuild targets; make build also produces bin/caddy-authenticator.
• .coverage/ contains the tested HTML/JSON/JUnit reports, raw test output, coverage profile, stderr, run metadata, and generation manifest. Start at .coverage/index.html; see testing-and-ci for the complete evidence layout.
• .coverage/codeql/ holds local scan databases, raw and reviewed SARIF/CSV, suppression audits, logs, and retained regression fixtures. Its evidence is separate from tested's report bundle; make clean removes both. Local CodeQL does not upload or dismiss alerts.
• ../xcaddy-caddy-security is the permitted devbuild workspace. Only that sibling workspace may be created, refreshed, or cleaned for xcaddy builds.

Formatted Caddyfiles, README download links, VERSION, go.mod, and go.sum can be intentional source changes depending on the target. Review the diff before deciding whether to keep them.

COVERAGE_DIR selects the report directory. Keep overrides inside this checkout; guarded runs in one checkout are serialized by .coverage/test-resource.lock, even when output directories differ. Keep this lock in place during validation. Let tested refresh only its managed artifacts: do not recursively delete report directories in test targets. Full, quick, and custom bundles and unrelated investigation files must survive one another's runs. Whole-directory cleanup belongs to the explicitly requested make clean.

Normal coverage reports include the root test executable's E2E subprocesses through Go's native coverage merge. See subprocess coverage for the bootstrap, regression tests and limits. Keep merging before tested evaluates coverage and writes reports; never patch a finished bundle's coverage percentage.

CI Notes

The reusable .github/workflows/build.yml runs repository quality gates before starting 44 concurrent Go shards, checks source remains unchanged, and retains each shard's evidence, a standalone merged coverage report, and a separate caddy-security_combined_coverage bundle with the original shard directories. Its stable Tests and coverage check requires every gate and verifies full test selection before merging coverage. Release CI requires this same gate. The testing contract owns local reproduction; release ownership covers artifact identities and tag requirements.

The CLA workflow may update assets/cla/signatures.json through GitHub automation. Do not edit CLA signatures or consent files unless the user asks.

Security Dependency Version

Run bin/authcrunch security version to print the go-authcrunch module linked into the executable, for example go-authcrunch <module-version>. This uses runtime/debug.ReadBuildInfo and works without a config, server, credentials, Go installation or source checkout. Do not substitute the caddy-security VERSION, a working-directory go.mod, or the authdb package's version banner. bin/authcrunch version continues to report Caddy's version.

Preserve pseudo-versions and module replacements in diagnostics. A replacement prints go-authcrunch <required-version> => <replacement-path> <replacement-version>; an unversioned local replacement uses (devel), so the required release is not mistaken for the actual checkout. Missing build metadata prints go-authcrunch unknown. command_security.go owns registration and formatting; its unit tests and TestCaddySecurityVersionE2E cover the command contract.

Local OAuth Provisioning

The built binary registers the security command group through Caddy's command extension API. It is separate from adapt, validate, run, reload, and Make maintenance. Use nested command words for the domain, action, and resource, such as bin/authcrunch security oauth create application. Follow this pattern for future security commands. Use oauth init provisioning store for storage of OAuth application credentials and OIDC provider signing keys; reserve user-registration terminology for user sign-up. Use Private provisioning and activation for the private input grammar and oauth init provisioning store, oauth create application, oauth rotate secret, and oidc create signing key subcommands, explicit revision activation, and interrupted-writer recovery. Each provisioning command prints only the resulting path; it never prints client secrets or private keys.

Local User Administration

Use Local user commands for security local client configuration, login, local realm/user inspection, account creation/deletion, password resets, roles/challenges, realm reload, and offline password/API-key generation. Remote operations use the portal's admin API; generators work offline and never modify database files.

Acceptance criteria

• A normal build creates both commands with their correct version identities and leaves source unchanged; explicit maintenance is chosen for source rewrites.
• A requested dependency change selects only the requested version/module and records any replacement. A sibling VERSION does not override user intent.
• Test/report failures retain their status and original evidence. Cleanup does not happen as an incidental validation step or erase another run's bundle.
• Local administration, OAuth provisioning, standalone login, and release tasks reach their distinct owners and respect their different input/side-effect scopes.