11 KiB
RULES OF CONDUCT
This module (github.com/effective-security/xpki) is a PKI library plus two
CLIs. The library packages are cryptoprov (provider abstraction with
crypto11, awskmscrypto, gcpkmscrypto, inmemcrypto backends), csr,
authority, certutil, jwt (with dpop, accesstoken, oauth2client),
dataprotection, and helpers armor, oid, x/print, testca. The CLIs
are cmd/hsm-tool and cmd/xpki-tool. There is no service, agent loop, or
generated mock tree. Work in one package at a time unless you are changing a
documented internal dependency.
Dependency direction is one way: cryptoprov defines the Provider
interfaces and must not import a backend; backends register themselves with
cryptoprov.Register from init(). csr depends on cryptoprov;
authority depends on csr, certutil, cryptoprov; jwt depends on
cryptoprov, csr, certutil. Nothing under the library imports cmd/.
NAVIGATION
Do not start by grepping the tree.
- Open
Documentation/codemap.md. Use the concept index to find the owning file, then the package section for entry points and invariants. - Open that file (and its
_test.go) before searching elsewhere. - Grep or glob only if the concept is missing from the map. When you find it, add it to the map in the same change.
- For high-level purpose, config samples and install path, see
README.md.
CODING GUIDELINES
Style
- Target Go 1.27 (
go.mod). Use the standard library where it now covers a helper:slices.Contains,cmp.Or,maps.Copy,strings.SplitSeq,math/rand/v2,crypto/rand, range-over-int. Do not add calls to functions markedDeprecatedin the stdlib or ingithub.com/effective-security/x;golangci-lint run(staticcheck SA1019) must stay clean. - Do not use long one-liners for map or struct population; split key-value pairs on new lines for readability.
- Do not use many hardcoded strings or integers; define
constat the top of the file or in the package. - Memoize into variables; do not call functions with the same parameters more than once.
- Use
any, notinterface{}.
Errors
- Use
github.com/cockroachdb/errorsfor all error creation and wrapping. - Wrap external errors (filesystem, YAML/JSON, network, PKCS#11, KMS SDKs)
using either:
errors.WithMessage(err, "unable to read file")for static context.errors.Wrapf(err, "failed to resolve file %s", path)when context includes dynamic values.
- Errors originated from internal sentinel types must also be wrapped so
the stack is preserved. For
var ErrNotFound = errors.New("not found")do not simplyreturn ErrNotFound. - Compare errors with
errors.Is/errors.As, never==or a type assertion; wrapped PKCS#11 (pkcs11.Error) and KMS errors must still be recognised. - Never ignore errors from serialization, filesystem, or network calls in
library paths that already return
error. Helpers that intentionally swallow errors (for exampleprint.JSON) must keep that behavior documented inDocumentation/codemap.md. - Keep error strings accurate after refactors. Do not leave stale package or function names in runtime errors.
- Library code does not panic on bad input or bad configuration; it
returns an error. The only intentional panics are
Must*constructors (jwt.MustNewProvider),certutil.Random/RandomStringwhencrypto/randfails,init()-time table construction (crypto11/ecdsa.go), andtestca, which is test-only. - Every outgoing HTTP call takes a
context.Contextand a client with a timeout (http.NewRequestWithContext; no barehttp.Get). - Cryptographic material: private keys and PINs are never logged; files
holding keys are written with mode
0600; random values come fromcrypto/rand; use constant-time comparison for secrets and hashes.
Tests
- Build tests using
assertandrequirefromgithub.com/stretchr/testify; suites usetestify/suite. - Assert exact behavior, including key absence versus empty values and
the real
errfrom the call being tested. - Keep test setup and cleanup trustworthy: fixtures should match their comments, and tests should actually execute in CI.
- Prefer table tests for conversion and formatting helpers.
- Use
package foo_testfor black-box tests andpackage fooonly when a test needs unexported seams. - External fixtures: PKCS#11 tests need the SoftHSM token described by
/tmp/xpki/softhsm_unittest.json(make hsmconfig); the AWS KMS integration tests need thelocal-kmscontainers on:14555and:14556(make start-local-kms) and the dummyAWS_*variables exported by the Makefile; the AWS and GCP KMS unit tests use in-process fake KMS clients. Do not hard-code other paths; reuse the constants the packages define. - Gate only the tests that need a fixture, with
internal/testenv(for exampletestenv.RequireTCP(t, "local-kms", "localhost:14556"), ortestenv.RequireFilefor the SoftHSM config, ascrypto11'srequireP11does). An unreachable fixture skips the test unlessXPKI_INTEGRATION=required, which the Makefile exports somake test,make covtestand CI fail instead. A reachable fixture always runs the test. Keep unit tests fixture-free (inmemcrypto,testca) rather than gating them. testcagenerates throwaway keys and certificates; use it instead of checking new PEM fixtures intotestdataunless a specific encoding is under test.- Cover shared state with a test that actually races, and run
make test RACE=truebefore proposing a change to shared state (providers, key caches, JWKS refresh, session pools). - This module has no gomock-generated interfaces; do not introduce mocks unless the package under test cannot be exercised directly (KMS clients are the existing exception).
- add
t.Parallel()for tests that can run in parallel.
Tools
make tools: install golangci-lint, cov-report, govulncheck and gomarkdoc at the versions pinned inMakefile(*_VERSIONvariables); bump a pin deliberately and rerunmake tools lint covtest docsmake hsmconfig: create the SoftHSM token and test configmake start-local-kms: start the AWS KMS emulator containersmake fmt: apply go fmtmake fmt-check: fail on unformatted files without changing themmake test: test entire projectmake lint:fmt-check, go vet, govulncheck, golangci-lint (never modifies the checkout; CI runs it)make covtest coverage: coverage run and reportmake docs: regenerate gomarkdoc API docs inDocumentation/and CLI help dumps (needsmake buildfirst)make all: clean, tools, generate, hsmconfig, start-local-kms, covtest
CI (.github/workflows/unittest.yml) runs make lint, then make covtest
with SoftHSM and local-kms, checks that the build left the checkout unchanged
(git diff --exit-code), and requires more than 90% total coverage
(MIN_TESTCOV). A pull request that changes only documentation (or repeats
an already successful run) skips the job and gets a "code cov: skipped"
status instead. CI does not run the race detector; run make test RACE=true
locally.
Documentation
- Every package has a
doc.gowith a package comment and, where the package has a non-obvious entry point, a short usage example. - Document all exported types, functions, interfaces, and interface methods. Say what a symbol is for, not just what it is named.
- Keep samples in
doc.go, the rootREADME.md,cmd/*/README.mdandDocumentation/accurate against the current API and CLI--helpoutput. A wrong sample is worse than no sample; compile a changed sample before committing it. - When you add a package, add it to the package table in the root
README.md, adddoc.go, and add a section plus concept-index rows inDocumentation/codemap.md. - When you find a defect you are not fixing in the same change, add it to
FINDINGS.mdwith the next free ID and reference the ID from a code comment. Larger API or contract changes go toROADMAP.md.
Track bugs and issues status
FINDINGS.md,PLAN.mdandROADMAP.mdhold open work only. In the same change as each verified fix, remove the finding fromFINDINGS.mdand its batch and assessment rows fromPLAN.md(when present, even if it is ignored by Git), and summarize it in the release notes of the next version,Documentation/RELEASE_NOTES_<version>.md: the fix, new behavior, and what clients must change. Record the actual validation in the commit or PR. Never reuse finding IDs.- A finding spanning multiple packages is Fixed only after every linked portion is implemented and verified. Record partial progress and remaining work without closing the whole finding or batch. Record validation limits; do not describe planned or unavailable checks as passed.
Keep Documentation/codemap.md current
Update the codemap in the same change when you add functionality or make a major change, including:
- New, removed, or renamed package, subpackage, or file that owns a concept.
- New, moved, or renamed exported entry-point type, func, or interface.
- Changed invariants: panic vs error, process-global state (provider registry, OID tables), locking, config file format, key URI format, supported algorithms, goroutine/callback rules, or internal imports between packages.
- Changed test layout or fixture conventions.
The map must stay the navigation index: concept → file → entry points → invariants. If you had to grep to find something that belongs there, add the row.
For package docs, use after changes make docs
REPOSITORY MAP
Start here instead of grepping the tree.
Documentation/codemap.md— concept index, per-package files and entry points, invariants, internal dependencies, test layout, build and CI.README.md— high-level overview, package table, configuration samples and quick-start code.FINDINGS.md— open defects, referenced by ID from code comments. Read it before "fixing" surprising behavior: it may already be recorded, with the compatibility decision still open.PLAN.md, when present — remediation batches, pending work, and explicit completion status; keep it synchronized withFINDINGS.md.ROADMAP.md— larger planned work.cmd/hsm-tool/README.mdandcmd/xpki-tool/README.md— CLI usage.- Package
doc.goin each library package.
IMPORTANT
- Do not commit or ask to commit any changes unless you have explicit instructions to do so..
- Review your changes before declaring current task as DONE.