Coding Directives

Coding Directives

Overview

Apply these directives when editing or reviewing caddy-security code. Prefer small, idiomatic Go changes that preserve Caddy module boundaries, delegate auth logic to go-authcrunch, and keep parser behavior covered by focused tests and fixtures.

The testing contract governs test selection and coverage. Automation ownership covers Make targets, generated artifacts, and dependency/replacement workflows.

After code changes, review and update the relevant repo-local skills and linked references in the same change so implementation and operational guidance match the final behavior. This is part of completing the code work; follow keeping skills current for scope, evidence, and cases where existing guidance remains accurate. Do not add Markdown documentation to docs/ or assets/docs/; follow the skill-authoring ownership guidance for documentation ownership and placement.

Repository Scope

Keep source changes inside caddy-security. Sibling repositories such as ../go-authcrunch are read-only references and are updated separately.

The sole sibling-write exception is ../xcaddy-caddy-security, the integrated xcaddy build workspace. Creating, updating, building in, and cleaning that workspace is allowed when needed for the xcaddy workflow. The exception does not permit changes to sibling source modules referenced by the build, including go-authcrunch. No other sibling directory is a permitted write destination.

This boundary covers creating, editing, deleting, restoring, staging, and committing files, including code, tests, fixtures, dependency files, skills, generated artifacts, and Git metadata. Outside the named xcaddy workspace, do not run sibling build, test, formatting, generation, license, dependency, or cleanup commands, or change those repositories' Git state through fetch, pull, checkout, reset, tag, or other Git mutations.

Before a mutating command, confirm its repository root and working directory, inspect the invoked script's side effects, and resolve its output paths. A command launched from this repository can still write elsewhere. Do not bypass the boundary through symlinks, linked worktrees sharing a sibling's Git metadata, module replacement paths, or output-directory flags. Keep task files and chosen build/report destinations in this checkout's working areas, such as tmp/, bin/, and .coverage/, except for the named xcaddy build workspace. Resolve that workspace's physical path before cleanup so a symlink cannot redirect the exception into another sibling repository.

Reading sibling source, skills, versions, and history is allowed. References to upstream APIs, tests, and integration wiring are context, not instructions to modify or run that project. A local Go replacement may select existing sibling source for tests of this module; it does not authorize sibling changes. If a fix requires an upstream change, document the affected contract and separate work needed, complete the work possible here, and state any validation blocker. Do not patch the sibling, duplicate its runtime here to avoid the boundary, or request to expand the current task into that repository.

Architecture

Treat security as the top-level Caddy app. Keep shared authcrunch configuration, provisioned portals, gatekeepers, identity stores, messaging, credentials, registration, and secrets managers owned by App.

Treat authenticate and authorize as HTTP-facing integrations that attach to Caddy routes and resolve named runtime objects from the provisioned security app. Do not duplicate portal or gatekeeper behavior in the Caddy plugins when go-authcrunch already owns it.

Keep the root package focused on Caddy app/plugin wiring and Caddyfile parsing. Use pkg/util only for small reusable helpers that are truly package-external or shared across multiple root-package files.

Caddy Modules

For runtime construction, ownership, request draining, reload, or cleanup work, read Runtime lifecycle. It traces Caddy's host ordering, the app's disposal contract, identity-file ownership restrictions, and the unit/E2E tests that verify those behaviors.

Register Caddy modules and Caddyfile directives in init functions near the module implementation. Provide a CaddyModule method with the correct public Caddy module ID and New constructor.

Add interface guards for Caddy contracts such as caddy.Module, caddy.Provisioner, caddy.Validator, caddy.App, caddyfile.Unmarshaler, caddyhttp.MiddlewareHandler, and caddyauth.Authenticator when a type is expected to satisfy them.

Keep exported configuration fields serializable with consistent struct tags. For HTTP middleware config fields, preserve matching json, xml, and yaml tags unless the surrounding type intentionally differs. Keep runtime-only fields unexported and untagged.

In Provision, resolve the security app through Caddy context, validate app/config cases, apply Caddy replacer substitutions where needed, and validate named declarations. The default in-memory app can provide runtime objects during provisioning; persistent state defers root construction until App.Start owns storage. A declared portal or policy can therefore be valid before its runtime pointer exists. Preserve deferred lookup and request admission checks; do not reject persistent candidates merely because Provision has no runtime object. The lifecycle contract owns the ordering.

Caddyfile Parsers

Use configuration-authentication-cross-device to implement or review cross-device directive aggregation, delegated parsing, approval boundaries and host/browser acceptance tests.

Follow the existing parser shape:

func parseCaddyfileSurface(d *caddyfile.Dispenser, cfg *authcrunch.Config) error

Use d.RemainingArgs() to validate directive arguments, d.Nesting() with d.NextBlock(nesting) for blocks, and small helper functions for nested subdirectives. Use mkcp or the local directive-prefix pattern to build clear directive paths such as security.authentication.portal.cookie.

Return d.ArgErr() for malformed top-level argument counts. Use h.Errf or d.Errf for Caddyfile parse errors that should include source locations. Use go-authcrunch/pkg/errors helpers where the surrounding parser already uses them for malformed directive values.

Keep syntax comments above parser functions current when adding or changing directives or updating a dependency that owns delegated grammar. Document headers, body scope, argument counts, aliases, repetition, and the parser that owns deeper validation. Keep restricted forms visible with an explicit status; do not delete documented syntax merely because a shared validator rejects it. Update runnable examples and the owning configuration skill in the same change. Follow the syntax maintenance workflow for the source inventory and validation boundaries.

Explain behavior alongside the syntax when a setting's name is insufficient. Include units/defaults, the meaning of omission/zero/disabled values, the scope of limits (per user, session, portal or process), inheritance and precedence, and consequential interactions or failure behavior. Explain the operational reason for a restriction or tradeoff when supported by the implementation: for example, whether a timeout slides, what consumes a session slot, or why native body transport requires explicit opt-in. Verify these details against the selected parser and runtime; field names alone do not establish them. Keep the grammar easy to scan, follow it with focused explanatory paragraphs, and link to the owning feature reference for longer protocol examples. Scale the detail to the feature instead of repeating a checklist for trivial options.

When mapping Caddyfile input, prefer authcrunch config constructors and Add* methods over duplicating validation in this repository. Use cfgutil.EncodeArgs for raw instruction strings that authcrunch later decodes. Use map[string]interface{} only where authcrunch expects flexible parameter maps.

Preserve exact error wording when tests assert it. Many parser tests compare err.Error() strings, including Caddy-added file and line suffixes.

Runtime Config

Keep Caddy replacer behavior centralized through util.FindReplace, util.FindReplaceAll, and ResolveRuntimeAppConfig. Add new replacement paths there when adapted JSON can contain {env.*} or secret placeholders that need runtime resolution.

Treat secrets:<manager-id>:<key> values as sensitive. Resolve them through SecretsManager methods and avoid logging secret values, credentials, tokens, passwords, API keys, or private keys.

Pass context.Context first when adding helpers that can touch secrets, external state, Caddy context, or request-scoped work.