Imported from docs/coding-standards.md in the go-loose repository. --- # Coding standards ## Go - Use the standard library unless a dependency clearly reduces security or protocol risk. - Keep public APIs small, documented, and backward compatible. - Pass `context.Context` through I/O boundaries and always bound network calls with timeouts. - Wrap errors with the operation; never log secrets, cookies, authorization headers, or full API keys. - Return explicit errors. Runtime authorization must fail closed. - Keep SQL tenant-aware: management queries must join through membership, and writes must enforce role in the query or transaction. - Derive authorization from the database role and permission tables instead of hardcoding role names. Resolve a member's capabilities by joining `role_permissions`, render controls from the capability lists the server returns, and keep `internal/role` limited to the permission vocabulary shared with the migrations. - Use cryptographically secure randomness for credentials and constant-time comparison for signatures. - Format with `gofmt`; run `go test -race ./...`, `go vet ./...`, and `go build ./...`. ## HTTP API - Routes are versioned under `/api/v1`; health and authentication routes are infrastructure exceptions. - JSON handlers reject unknown fields, extra JSON values, and oversized bodies. - Errors use `{"error":"human-readable message"}` without internal implementation details. - Use `401` for absent/unusable authentication, `403` for authenticated credentials outside policy, `404` when existence must not disclose access, and `422` for semantically invalid contracts. - Any management mutation requires a valid user session and same-origin browser request. - Update `web/openapi.json` whenever endpoint behavior changes. ## Database - Use UUID primary keys for tenant data and UTC `timestamptz` timestamps. - Foreign keys declare deletion behavior; frequently queried authorization fields get explicit indexes. - Applied migrations are immutable and forward-compatible. - Multi-step writes use transactions. Do not add application-side checks that can race when a database constraint can enforce the invariant. ## Frontend - Preserve keyboard access, semantic elements, visible focus, responsive layout, and sufficient contrast in every theme. - Escape all server-provided strings before assigning HTML. Prefer `textContent` for new dynamic surfaces. - Store only visual preferences in local storage; authentication remains in HTTP-only cookies. - Keep the console dependency-free unless complexity justifies a reviewed build tool decision. ## Tests and reviews - New domain behavior needs table-driven unit tests and negative cases. - Security boundaries need explicit tests for missing, malformed, expired, cross-tenant, and unauthorized inputs. - Integration tests that need PostgreSQL should use a disposable database and never shared developer data. - Reviews prioritize tenant isolation, fail-closed behavior, migration compatibility, secret handling, and error visibility. ## Commit style Use focused commits with imperative subjects, for example `Add scoped API key authorization`. Do not mix unrelated refactors with behavior changes. Explain migration and security implications in the commit body.