19 KiB
RULES OF CONDUCT
This module (github.com/effective-security/trustyca) is a multi-tenant
Certification Authority service: the access layer (login, orgs, projects,
memberships, API keys) and the CA (pb.CA) and certificate information
(pb.CIS) services built on it. The repository is public.
Package boundaries and direct internal imports are listed in
Documentation/codemap.md.
NAVIGATION
- Read the matching concept row in
Documentation/codemap.md, then that package's entry points, invariants and test notes. Read only the relevant sections. - Prefer codebase-memory-mcp for code discovery when available, with
project="trustyca"(MCP.md):search_graphfor symbols,trace_pathfor callers/callees,get_code_snippetfor source,query_graphfor complex relationships, andget_architecturefor an overview. Check the index status and coverage, and paginate narrow queries; do not reindex unless asked. - Read the owning source and its tests before expanding scope. Fall back to
rgfor literals, documentation/configuration, graph coverage gaps, or a concept absent from the map; scope searches to the owning package first. Add any missing ownership or invariant to the codemap in the same change. - Read
FINDINGS.md, when you have it, before changing surprising behavior: it is the local list of known defects and is gitignored, so it may be absent.ROADMAP.mdowns active planned work.Documentation/design/DESIGN.mdis the accepted design andDocumentation/PLAN.mdits implementation phases; the CA and CIS services are still stubs. - Skip
Documentation/api/andDocumentation/cli/:make docsgenerates them. Edit source comments/protos and regenerate instead. - Preserve existing staged and unstaged work. Documentation-only work must not recreate databases, regenerate artifacts or rewrite fixtures merely to inspect them. Choose checks that exercise the changed behavior.
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,min/max, range-over-int,math/rand/v2andcrypto/rand. Prefer the stdlibslicesovergithub.com/effective-security/x/slices. Do not add calls to functions markedDeprecatedin the stdlib, ingithub.com/effective-security/x,xpki,porto, or in third-party modules;.golangci.ymlstill excludes SA1019, so check by hand (ROADMAP.md → Lint). - 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. Header and metadata names live inporto/xhttp/header, REST paths and OAuth values inapi/pb/rest.go; reuse them. - Memoize into variables; do not call functions with the same parameters more than once.
- Use
any, notinterface{}. - Search the existing
pb,model, request, query and CLI vocabulary before adding names. Avoid prefixes and suffixes the containing type already supplies; keep CLI flag names short.
SQL and Database Code
Migrations
- Every
*.up.sqlmigration that changes schema needs a matching*.down.sqlrollback. - Empty down migrations are acceptable only when the up migration is intentionally irreversible and that reason is documented.
- Do not duplicate a schema change in both a historical base migration and a new forward migration unless that is intentional and fresh DB creation has been verified.
- Keep primary key column order consistent across migration SQL, generated schema comments, and generated docs.
Tables
- New tables make tenancy explicit: nullable
(org_id, project_id)with composite foreign keys toproject (org_id, id)andUNIQUE NULLS NOT DISTINCTwhere a platform row (org_id IS NULL) and tenant rows share a key (DESIGN.md §4). - New tables should normally include
created_atandupdated_at. If rows are immutable or the table is truly global and tiny, document that. - Add useful unique constraints and indexes for expected query paths, not just a
primary key. Certificate and revocation tables grow without bound: design
indexes around the real filters (
org_id,project_id,ikid,status,not_after) and check them withEXPLAINbefore adding a list query. - Name denormalized fields after their real meaning: IKID, SKID, serial number, issuer label and profile label are distinct identifiers.
- Put DB code in the package/file that owns the domain concept, not just where the first caller happens to live.
DB APIs and Queries
- Prefer request structs with
QueryParams()over functions that take many positional arguments, and follow the existing request/query patterns. ListDB methods should be paginated and return a result with a next offset or equivalent pagination state. Do not advance an offset over a filtered set the caller is shrinking (status updates, deletes): page by the last ID seen.- If a method returns a single object or intentionally bounded unpaginated data,
name it
Get..., notList.... - Put read methods on the
...ReadonlyDbinterface and mutations on the write-capable interface. The DB layer stays plain CRUD: it never importsinternal/authctx. - A method that writes more than one row opens a transaction with
BeginTxand runs every statement on the provider it returns, not on the receiver. - Keep model, schema, query, and service naming aligned with the SQL table and relationship direction.
- Group related provider methods in a lifecycle order that is easy to review:
Register/Upsert,Get,List,Delete. - No N+1 queries in services or tasks. Use count-specific or ID-specific queries when callers only need counts or identifiers; deduplicate IDs before DB calls.
Protobuf and API Contracts
- Prefer existing
pbmessages and enums over duplicate DTOs. If a new denormalized message is necessary, document the source of truth and why an existing message is not enough. - Public proto messages, fields, and enum values need comments that describe product semantics.
- Every tenant method declares its minimum roles with
(es.api.allowed_roles)and, when API keys may call it, the required(es.api.scopes);authctx.CheckAccessenforces both from the generated method info. Tenant requests carry noOrgID: the server takes the org from the token. - Use the enum wrapper style already used in this repo, such as
repeated xxxType.Enum, instead of raw numeric or ad hoc enum fields. List...RequestandList...Responsemust include pagination fields. If the API returns a single object or bounded unpaginated data, name itGet....- Keep JSON names clean and stable. Avoid temporary review terms and redundant prefixes/suffixes unless they are part of the product contract.
- Keep CLI command annotations and public RPC naming aligned with existing CLI hierarchy.
- For parsing Enums use .Parse method on enum, for example:
if req.Type = pb.EventType_Unknown.Parse(a.Type); req.Type == pb.EventType_Unknown { return errors.Errorf("invalid event type: %s", a.Type) }
Authorization, tokens and CA keys
- The org comes from the token (
authctx.FromContext(ctx).OrgID()); onlytrustyca-*service roles (RA, CIS, jobs over mTLS) pass tenant scope explicitly, and the service must still verify that the project belongs to that org. A project of another org or an inactive project is reported as not found, so existence does not leak. - Permissions are resolved from DB grants by the shared
authctx.Authorizer; token role claims are informational. Every membership or project mutation callsInvalidateUser/InvalidateProjectafter it commits. - An org always keeps an org-wide Owner; only an Owner grants Owner.
- Private keys never leave their crypto provider and are never logged; a
software key is stored only wrapped by
dataprotection.Provider, and theinmemprovider is for tests. Key labels followtrustyca/{org}/{project}/{label}. Serial numbers come fromxpki/authority, never from a counter. - State changes that must agree are one transaction: a certificate insert and its issue event, a root issuer and its trust anchor, a revocation and the certificate status, a CRL upsert and the issuer's CRL number (which only grows).
- CIS is public and read-only, holds no issuer keys and forwards OCSP signing to the CA.
Logging
- Use the repo's structured
xlogstyle with package-level loggers andlogger.ContextKVwhen a context is available. - Use snake_case log keys, for example
project_id, not camelCase names such asProjectID. - Keep log keys stable inside a package or task. Do not switch between keys such
as
reasonandmessagefor the same concept. - Keep structured log value types stable for a given key. Do not emit an
xdb.IDin one path and a numeric ID in another path under the same key. - Prefer existing keys such as
reason,status,task,org,project,actionanderr. - Avoid per-row
INFOlogs in loops. Resolve shared values once outside loops and useDEBUGfor repetitive trace details. - Never log access tokens, API key secrets, private keys, PINs or CSRF values; log key IDs, IKIDs and serial numbers instead.
Errors
- Use
github.com/cockroachdb/errorsfor all error creation and wrapping. - Wrap external errors (filesystem, YAML/JSON, network, Redis, gRPC, KMS/HSM,
AWS SDK) 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. Errors returned to HTTP or gRPC callers go throughporto/xhttp/httperrorso status codes and codes stay consistent. - A refusal the caller can fix by changing the org's state (deleted org,
last Owner) is
preconditionFailed(HTTP 409conflict, gRPC FailedPrecondition). Do not build it withNewGrpcFromCtx(ctx, codes.FailedPrecondition, ...): the pinned porto maps that to HTTP 400bad_request, not the 409 the API documents. Return it unwrapped. - Map not-found cases explicitly when the response type already supports a not-found path. Do not collapse expected not-found errors into generic "failed to get ..." responses.
- Keep user-facing errors sanitized, but specific enough to be useful. Put internal diagnostics in server-side logs.
- Never ignore errors from serialization, filesystem, or network calls in
library paths that already return
error. Helpers that intentionally swallow errors 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,init()-time table construction and service factories given a nil server. - Every outgoing HTTP call takes a
context.Contextand a client with a timeout (http.NewRequestWithContext; no barehttp.Get). - Credentials: bearer tokens, cookies, API key secrets, private keys and
PINs are never logged in full and never put in a URL query string; token
files are written with mode
0600; random values come fromcrypto/rand; use constant-time comparison for secrets and HMACs. - Headers that carry caller identity (
X-Forwarded-For,X-Real-Ip,X-Forwarded-Proto,Authorization, DPoP) are untrusted input. Do not widen what the servers accept from them without aROADMAP.mdentry.
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. - Do not assert on source line numbers or on exact compressed bytes; both change with unrelated edits or Go releases.
- 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 come from
etc/dev/andtests/testutils. PostgreSQL, Redis, LocalStack and KMS are started bymake start-localstack; generate the certificates withmake folders gen_test_certsfirst. Initialize only a disposable local database withmake drop-sql start-sql.make testdoes not start dependencies, and-shortdoes not bypass every package setup. Tests loadetc/dev/trustyca-config.unittest.yamlthroughtestutils.LoadConfig("UNIT_TEST"). - Cover shared state with a test that actually races, and run
make test RACE=truebefore proposing a change to shared state (authorizer caches, schema metadata, port allocation, CLI globals, issuer caches). - This module uses gomock-generated interfaces under
mocks/, which is gitignored: runmake generateon a fresh checkout. Reuse the existing mocks or exercise components directly; interface changes requiremake generate. Match meaningful request fields, not onlygomock.Any(). - Add
t.Parallel()only for tests with independent state. Suites that parse CLI configuration mutate process-wide formatting, so they are never parallel. Their captured output is compared with the suite's golden file,testdata/prints_<suite test>.txt; rewrite it only on purpose, withTRUSTYCA_UPDATE_GOLDEN=1 go test ./api/cli/command, and review the diff. The auth service tests share one server: a test that changes its BaseURL or providers is not parallel. Never share anxdb.IDbetween parallel tests: its string cache is not synchronized. - Avoid
time.Sleep, userequire.Eventuallywhere appropriate.
Tools
make tools: install lint, coverage, docs, PKI, schema, migrate and mock tools listed inMakefile(govulncheck is installed separately)make generate version: regenerate the gitignored mocks andapi/version/current.gomake fmt: apply go fmt with the project rewritesmake build: buildtrustyca,trustycactlandtrustycasvcmake test: test entire project (requires the configured local stack)make testshort: tests with-test.shortmake lint: gofmt, golangci-lintmake vulns: govulncheck (install it separately)make covtest: coverage run and console reportmake covtest coverage: coverage run and HTML reportmake docs: regenerate API and CLI references underDocumentation/api/andDocumentation/cli/; runmake buildfirstmake all: clean, tools, generate, certificates, local stack, recreated SQL database, build, dry-run and test (seeMakefile)make docker-citest: build the service and test runner images and run the container integration tests oftests/integration(the CLI and the cookie session of the Web UI) in a compose stack of their own; run it when the server, the CLI or the configuration of the wfe change
If the proto changes and needs to be updated make proto for types and make proto generate for services.
If the SQL schema changes and needs to be updated, drop and recreate:
make drop-sql start-sql
make gen-sql-schema
CI (.github/workflows/build.yml) builds and prepares the local stack, runs
make test on pushes and make covtest on PRs, then make docker-citest,
and publishes a coverage status against MIN_TESTCOV (88, set in the
workflow env; raise it as the coverage improves). CI does not run make lint or the race detector; run them
locally. Pushes to main that change .VERSION create a tag
<.VERSION>.<commit count>.
Documentation
- Every new package, including commands and generated support packages,
has a handwritten
doc.gowith a package/command comment and, where the package has a non-obvious entry point, a short usage example. Most existing packages do not have one yet: add it when you change the package. - 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.mdand handwrittenDocumentation/accurate against the current API. A wrong sample is worse than no sample; compile a changed sample before committing it. - When you add a package, add
doc.goand 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
your local
FINDINGS.mdwith the next free ID. It is not committed, so committed code, comments and docs never cite a finding ID: state the constraint itself in the comment. Larger API or contract changes, and defects that need public tracking, go toROADMAP.md; do not publish an exploitable security detail there.
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 (loggers, registries, caches, default clients), locking, config file format, header or metadata names, supported auth methods, roles and scopes, key handling, goroutine/callback rules, or internal imports between packages.
- A stub replaced by an implementation (CA, CIS, tasks).
- 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.
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— build targets, local setup and client configuration.Documentation/design/DESIGN.md— accepted design: tenancy and authorization, domain model, issuers, keys, profiles, signing, revocation, CRL/OCSP and APIs.Documentation/PLAN.md— implementation phases of the design and their status.ROADMAP.md— larger planned work.FINDINGS.md— local, gitignored list of known defects. Read it before "fixing" surprising behavior: it may already be recorded, with the compatibility decision still open.MCP.md— codebase-memory-mcp project selection and usage.- Package
doc.go, where a package has one.