- Invite acceptance deletes the invite in its transaction (query.TakeInvite, DELETE ... RETURNING) and grants from the deleted row: a withdrawn or already accepted invite grants nothing, a re-issued one grants its current role, and an email mismatch, an expired invite or a failed grant rolls the delete back. - CaDb.RegisterIssuer requires the anchor of a root issuer and refuses one for any other issuer; the service always builds it for a root. - The OAuth response is merged into the query of a redirect URI that has one, and replaces its fragment in fragment mode. - The codemap describes the transactions of RegisterOrg and the invite acceptance. Co-Authored-By: Claude Opus 5.5 <[email protected]>
132 KiB
Code map
Navigation index: concept → owning file → entry points → invariants. Read the
matching concept row and package section, then the source and its tests.
Paths are repository-relative; a bare file name shares the directory of the
path before it, and files in a package section are in that package. Use
codebase-memory-mcp (search_graph, trace_path, get_code_snippet) for
symbols and callers, with project="trustyca" (see MCP.md);
check the index status and coverage before treating a miss as absence.
- AGENTS.md: contribution rules and validation commands.
- README.md: build targets, local setup and client config.
- ROADMAP.md: planned work.
FINDINGS.md: local list of known defects. It is gitignored in this public repository; committed files do not reference its IDs.- design/DESIGN.md: scope, tenancy and authorization, domain model, issuers, profiles, signing, revocation and APIs.
- PLAN.md: implementation phases of DESIGN.md; phase 1 (orgs,
projects, members, authorization) is done, phase 2 has its DB layer and
the CA library (
internal/ca: issuer registry, keys, bootstrap), phase 3 the CA service: issuers, profiles, roots, signing, certificates, revocation and the current CRL, and phase 4 CRL publishing (the publisher ofinternal/ca,PublishCrls, thecrl_renewaltask) and thecert_statustask, phase 5 the CIS service (server/service/cis: the JSON and gRPC API for authenticated callers), phase 6 the operator tooling (internal/ctl/admin: thecacommands oftrustycactland the onboarding of an org, the support lists ofprivpb.Admin, the CIS commands oftrustyca), phase 7 the hardening, phase 8 the AIA service (server/service/aia: the public AIA, CRL and OCSP routes of the issued certificates on a plain HTTP listener), and phase 9 the signing plane (privpb.Backendon the backend listener, the CA of the service identities with an explicit org;pb.CAon the wfe, the CA of the tenants with the org of the token, forwarding every call; named service clients), and phase 10 the Web UI sessions (the cookie session andPOST /v1/auth/org, thelocalidentity provider, token revocation, the container integration tests oftests/integration). Completed phases keep a one-line summary there; open work is listed after them. Documentation/api/,Documentation/cli/: generated bymake docs; do not edit or use for source discovery.
Module layout
cmd/ trustyca (public CLI), trustycactl (admin CLI), trustycasvc (service)
api/ public CLI, clients, protobuf contracts and version
privpb/ private Admin protobuf contracts
internal/ authorization, CA core (issuer registry, keys, bootstrap) and its API conversions (pbconv), configuration, persistence, admin CTL, metrics
server/ application/container wiring, HTTP/gRPC services and tasks
sql/trustycadb/ migrations and local database bootstrap scripts
mocks/, tests/ generated mocks (gitignored), shared fixtures, container builders, the load tool (tests/load) and the container integration tests (tests/integration)
etc/ service configuration, CA bootstrap and development certificates
Concept index
| Concept | Owning file(s) | Entry points / read next |
|---|---|---|
| Application startup, DI and cleanup | server/app/app.go, server/appcontainer/appcontainer.go, server/appcontainer/closer.go |
NewApp, App.Run, NewContainerFactory, CreateContainerWithDependencies, Closer.Close |
| Service YAML, host overrides and secrets | internal/config/config.go, internal/config/loader.go |
Configuration, Service.IsLocal (EnvironmentLocal, ClusterLocal), CA (ca: section), CryptoProv, Load, LoadForHostName, LoadWithOverride; etc/dev/trustyca-config.yaml, trustyca-config.yaml.hostmap, trustyca-config.citest.yaml (the integration test stack) |
| Named service clients of a process | api/client/factory.go, internal/config/config.go |
Config, NewFactory, Factory.BackendClient, ClientNameCA, ClientNameAIA; clients in the YAML; DESIGN.md §2.2 |
| Listeners, middleware and interceptors per server | server/app/app.go, server/service/service.go |
App.Run (wfe, backend, aia), Factories; servers.*.services in the YAML; DESIGN.md §2.2 for the listeners of each pod role |
| Token claims and the request's tenant context | internal/authctx/ctx.go |
TrustyCtx, NewTrustyCtx, FromContext, Handler, NewAuthUnaryBackendInterceptor (forwarded callers of trustyca-peer), PeerRoleName, ClaimOrg, ClaimScope |
| Roles, grants and API key scopes | internal/authctx/roles.go, grants.go, scopes.go |
CanAssumeRoles, GrantsFromMemberships, Grants.HighestRole, CanGrantOrgRole, ParseScopes, HasScopes; DESIGN.md §3 |
| Method authorization (allowed_roles, scopes, service roles) | internal/authctx/authz.go, authorizer.go, allowed.go |
CheckAccess, NewAuthUnaryInterceptor, NewAuthorizer, Authorizer.CheckRole, GetAllowedMethods, GetCallerScope |
| OAuth login, DPoP and code exchange | server/service/auth/authorize.go, callback.go |
AuthorizeHandler, CallbackHandler, handleToken, writeOauthResponse, ExchangeCode; the local provider (local+ addresses): localEmailPrefix, localUserInfo, AuthProviderForEmail |
| Org selection, token revocation and auth cookies | server/service/auth/tenant.go, userinfo.go, cookies.go |
initialOrg, SelectOrg, selectOrgToken, AuthOrgHandler (POST /v1/auth/org, the org switch of a cookie session), omitCookieAccessToken, RevokeToken, RevokeTokenHandler, RemoveCookieHandler, setAuthCookie; token revocation: provideJwt (server/appcontainer) |
| API keys: issue and authenticate | server/service/orgs/apikey.go, server/service/auth/apikey.go, internal/db/pgsql/apikey.go |
CreateAPIKey, AuthenticateAPIKey, AuthenticateAPIKeyHandler, validateHMAC, UseAPIKey |
| Orgs, projects, members and invites APIs | server/service/orgs/org.go, projects.go, members.go |
RegisterOrg, RegisterProject, AddMember, ChangeMemberRole, DeleteMember, checkLastOwner |
| Refusals the org's state causes: HTTP 409, gRPC FailedPrecondition | server/service/orgs/org.go |
preconditionFailed; precondition_test.go |
| CA API: issuers, roots, profiles, certificates, CRL, signing | server/service/backend/backend_service.go, signer.go, issuer.go, profile.go, root.go, cert.go, crl.go, scope.go |
backend.Service (privpb.Backend, every CA method with an explicit OrgID): SignCertificate, SignOCSP, resolve, RegisterIssuer, ImportIssuer, ActivateIssuer, UpdateIssuer, GetIssuer, RegisterProfile, RegisterRoot, GetCertificate, ListCertificates, UpdateCertificateLabel, RevokeCertificate, ListRevokedCertificates, GetCRL, PublishCrls, tenantScope, findCertificate |
| CA of the tenants: the token's org, forwarded to the backend | server/service/ca/forward.go, ca_service.go, server/service/shared/backend.go, internal/authctx/ctx.go |
ca.Service (pb.CA, a proxy), forward, counterpart, forwardedError, shared.BackendLocator, NewAuthUnaryBackendInterceptor; DESIGN.md §2.1, PLAN.md phase 9 |
| Tenant scope and row authorization of the CA requests | server/service/backend/scope.go, request.go |
tenantScope (Org, Project, RequestProject, RowAccess, ListProjects, Issuer, VisibleIssuer, Profile), preconditionFailed, EventSource |
| Issuer and profile resolution per tenant scope, issuer cache | internal/ca/registry.go, errors.go |
Registry, NewRegistry, Options, Resolve, Resolution, FindProfile, FindIssuer, Issuer, IssuerBySKID, IssuerByKeyHash, InvalidateIssuer, InvalidateProfile; DESIGN.md §5.1, §6 |
| CRL signing and publishing (service and renewal task) | internal/ca/crl.go, server/service/backend/crl.go, server/tasks/crlrenewal/crlrenewal.go |
CrlPublisher, NewCrlPublisher, PublishCrlsRequest, PublishCrl, PublishCrls, CrlDue, ErrIssuerExpired, Backend.PublishCrls, crlrenewal.Task.Run; DESIGN.md §8 |
| Certificate expiry and retention | server/tasks/certstatus/certstatus.go, internal/db/pgsql/certificate.go |
certstatus.Task.Run, BatchSize, MaxBatches, ExpireCertificates, DeleteExpiredCertificates, config.Retention (ca.retention.expired_after); idx_certificate_notafter |
| Issuer keys: generation, wrapping, loading, destruction | internal/ca/keys.go |
Keys, NewKeys, DisableSoftwareKeys, ErrSoftwareKeysDisabled, KeyRef, KeySpec, KeyLabel, IsKeyURI, Generate, Signer, ImportKey, Destroy, SubjectKeyID, SoftwareKeyProvider |
| Creating, importing and activating issuers | internal/ca/issuer.go |
IssuerRequest, NewRootIssuer, NewSignedIssuer, NewPendingIssuer, ImportRequest, ImportIssuer, ActivatedIssuer, IsSelfSigned |
| Profile and issuer settings conversion | internal/ca/pbconv/profile.go, config.go |
ProfileFromPb, ProfileToPb, ExtensionsFromPb, IssuerConfigFromPb, IssuerConfigToPb, ExpandIssuerURL |
| Platform bootstrap of a ca-config into the CA tables | internal/ca/bootstrap.go, server/appcontainer/appcontainer.go |
LoadBootstrapConfig, Registry.Bootstrap, BootstrapResult, provideCA; etc/dev/ca-config.local.yaml (trusty.l1, the intermediate that signs the issuing CAs of the orgs with tenant_ca) |
| Certificate information: roots, issuers, certificates, status, CRLs | server/service/cis/cis_service.go, cis.go |
New, Factory, RegisterRoute, RegisterGRPC, GetRoots, GetIssuer, GetCertificate, GetCertificateStatus, GetCRL, issuedIssuer, findCertificate; PLAN.md phases 5 and 8 |
| AIA routes: issuer certificate, CRL Distribution Point, OCSP responder | server/service/aia/aia_service.go, aia.go, cache.go |
New, Factory, RegisterRoute, IssuerHandler, CRLHandler, GetOcspHandler, OCSPHandler, ocspResponse, writeCacheable, signer, ocspCache; PLAN.md phase 8 |
| Admin API | server/service/admin/admin_service.go, orgs.go, projects.go, issuers.go, certificates.go, scope.go, privpb/protos/admin.proto |
ListOrgs, ListProjects, ListIssuers, ListCertificates (the support lists across orgs), parseListScope; trustyca-admin role |
| DB interfaces and the PostgreSQL provider | internal/db/trustycadb.go, internal/db/pgsql/provider.go, errors.go |
OrgsReadonlyDb, OrgsDb, CaReadonlyDb, CaDb, Provider, New, ErrAlreadyRevoked, ErrStaleCrlNumber, ErrRootConflict, IsUniqueViolation, UniqueIssuerLabel, UniqueIssuerSkid, UniqueCertificatePrefix |
| Query builders, request structs, scope filters and pagination | internal/db/pgsql/query/common.go, scope.go, cursor.go, member.go, org.go |
BuildQueryFunc, setOrgScope, setProjectScope, setVisibleProjects, setTenancy, Cursor, ParseCursor, EncodeCursor, setPage, ListMembershipsRequest.QueryParams |
| SQL migrations, models and schema generation | internal/db/model/model.gen.go, internal/db/schema/schema.gen.go, internal/db/schema/typesmap.yaml |
sql/trustycadb/migrations/N_*.{up,down}.sql; make gen-sql-schema; jsonb config columns map to model.JSON; do not edit generated files |
| Audit events: build, emit and store | internal/events/events.go, internal/db/pgsql/event.go |
events.New, Event.Emit, Recorder, TryCreateEvent, CreateEvent, ListEvents; emitters in server/service/auth and orgs |
| Issuers: register, activate, update, find by scope or SKID | internal/db/pgsql/issuer.go, internal/db/model/issuer.go, internal/db/pgsql/query/issuer.go |
RegisterIssuer, UpdateIssuer, ActivateIssuer, FindIssuer, GetIssuerBySKID, ListIssuers (scope, parent, label, status, type), Issuer.SetCertificate, Issuer.SetConfig |
| Trust anchors (root certificates) | internal/db/pgsql/root.go, internal/db/model/root.go, internal/db/pgsql/query/root.go |
RegisterRoot, ListRoots, DeleteRoot, NewRootCertificate, ErrRootConflict |
| Certificate profiles: upsert by scope and label | internal/db/pgsql/profile.go, internal/db/model/profile.go, internal/db/pgsql/query/profile.go |
RegisterProfile, FindProfile, ListProfiles, NewCertificateProfile, CertificateProfile.Pb, CertificateProfile.Definition, AnyIssuerLabel |
| Certificates: issuance records, lookups and lists | internal/db/pgsql/certificate.go, internal/db/model/certificate.go, internal/db/pgsql/query/certificate.go |
RegisterCertificate, UpdateCertificate, GetCertificateByIssuerSerial, GetCertificateBySha256, ListCertificates, ExpireCertificates, DeleteExpiredCertificates, NewCertificate |
| Revocation, CRL entries and the revoked certificate view | internal/db/pgsql/revoked.go, internal/db/model/revoked.go, sql/trustycadb/migrations/2_revoked_view.up.sql, 3_revoked_index.up.sql |
RevokeCertificate, GetRevoked (GetRevokedRequest: certificate ID, or IKID and serial), ListRevoked, ListRevokedCertificates (vw_revoked_certificate), NewRevokedCertificate, ErrAlreadyRevoked |
| CRL storage and the issuer CRL number | internal/db/pgsql/crl.go, internal/db/model/crl.go, internal/db/pgsql/query/crl.go |
PublishCrl, GetCrl, ListCrls, DeleteCrl, SetIssuerCrlNumber, ErrStaleCrlNumber |
| Test certificates and chains | tests/testutils/certs.go |
NewTestCA, TestCA.Issue, TestCA.ChainPEM, TestCA.Root, CertPEM |
| Metrics descriptors | internal/metricskey/metricskey.go |
Metrics, PerfDbOperation, PerfTaskRun, LoginCount, CACertIssued, CASignLatency, CACertRevoked, CACrlPublished, CAFailPublishCrl, CAOcspSigned, AIACacheHit |
| Public/private API contracts and generated output | api/pb/protos/*.proto, privpb/protos/admin.proto, privpb/protos/backend.proto |
pb.Auth, pb.Orgs, pb.CA, pb.CIS, pb.Status, privpb.Admin, privpb.Backend; make proto |
| Public CLI / admin CTL command trees | api/cli/cli.go, api/cli/command/command.go, internal/ctl/ctl.go, internal/ctl/admin/admin.go |
Cli (CISClient, CAClient), App; cmd/trustyca/main.go, cmd/trustycactl/main.go |
Operator CA commands and org onboarding (trustycactl ca) |
internal/ctl/admin/ca.go, issuer.go, profile.go, root.go, cert.go, crl.go, bootstrap.go |
CACmd, OrgScope, IssuerSettings, SubjectFlags, KeyFlags, IssuerCmd, ProfileCmd, LoadProfile, LoadProfiles, RootCmd, CertCmd, CrlCmd, CAOrgCmd, OrgBootstrapCmd; etc/dev/profiles; PLAN.md phase 6 |
| Certificate information commands of the public CLI | api/cli/command/cis.go |
CertCmd, CertSelector, IssuerCmd, CrlCmd, RootCmd; Cli.CISClient |
| CLI login: browser, local listener, --no-browser | api/cli/command/auth.go |
LoginCmd.Run, svcState.waitForLogin, loginHandler; auth_internal_test.go |
| CLI test suites and golden output | api/cli/clisuite/suite_http.go, internal/ctl/ctlsuite/suite_http.go, tests/testutils/golden.go |
CapturePrint, CheckGolden; TRUSTYCA_UPDATE_GOLDEN=1 go test ./api/cli/command rewrites testdata/prints_.txt |
| Test setup, ports and container fixtures | tests/testutils/testutils.go, tests/mockappcontainer/builder.go |
LoadConfig, CreateURL, CreateBindAddr, NewBuilder; etc/dev/trustyca-config.unittest.yaml |
| Container integration tests (CLI and cookie sessions of the console) | tests/integration/setup.sh, docker-compose.tester.yml, tests/integration/tests/lib.sh, Dockerfile |
make docker-citest, docker-build; login, trustyca_as, browser_login, console_rest, console_grpcweb; test_status.sh, test_auth.sh, test_cookies.sh; tests/integration/README.md |
| Load test of the CA tables and the query plans at volume | tests/load/main.go |
go run ./tests/load -load -explain -sign; Documentation/perf/load-certificates.md; DESIGN.md §4.5 |
| Role matrix of the listeners and the access check of every CA method | server/app/authz_test.go, server/service/backend/access_test.go, logging_test.go, server/service/ca/forward_test.go, forward_e2e_test.go |
Test_Authz_CAMethods, TestService_EveryMethod_Access, TestService_KeyMaterialNeverLogged, TestRequests_Counterparts, TestService_ForwardOverMTLS |
| Scheduled tasks | server/tasks/tasks.go, server/tasks/crlrenewal, server/tasks/certstatus, server/app/app.go |
Factories (crl_renewal, cert_status), Factory, App.scheduleTasks; tasks: of etc/dev/trustyca-config.yaml |
Internal dependency direction
Arrows run from importer to imported; runtime composition is
cmd → server/app → server/appcontainer → services/providers. The table
lists direct production imports within the module (no test imports). Do not
add reverse imports to reuse a helper; use an interface at the caller's
boundary. internal/authctx imports internal/db/model and
internal/db/pgsql/query for row types only: the DB layer never imports
authorization code.
| Package | Direct module imports |
|---|---|
| api/cli | api/pb, api/pb/proxypb, api/version |
| api/cli/clisuite | api/cli, api/pb, api/pb/mockpb, api/version, tests/testutils |
| api/cli/command | api/cli/command/uname, api/client, api/pb |
| api/cli/command/uname | none |
| api/client | api/pb, api/pb/proxypb, privpb, privpb/proxypb |
| api/pb | none |
| api/pb/httppb | api/pb |
| api/pb/mockpb | api/pb |
| api/pb/modelpb | none |
| api/pb/proxypb | api/pb |
| api/version | none |
| cmd/trustyca | api/cli, api/cli/command, api/version |
| cmd/trustycactl | api/cli/command, api/version, internal/ctl, internal/ctl/admin |
| cmd/trustycasvc | server/app |
| internal/authctx | api/pb, internal/db/model, internal/db/pgsql/query, privpb |
| internal/ca | api/pb, internal/ca/pbconv, internal/db, internal/db/model, internal/db/pgsql/query, internal/metricskey |
| internal/ca/pbconv | api/pb |
| internal/config | api/client |
| internal/ctl | api/pb, api/pb/proxypb, api/version, privpb, privpb/proxypb |
| internal/ctl/admin | api/pb, internal/ca/pbconv, internal/db/model, privpb |
| internal/ctl/ctlsuite | api/pb, api/pb/mockpb, api/version, internal/ctl, privpb, privpb/mockpb, tests/testutils |
| internal/db | internal/db/model, internal/db/pgsql, internal/db/pgsql/query |
| internal/db/model | api/pb, internal/db/schema |
| internal/db/pgsql | api/pb, internal/db/model, internal/db/pgsql/query, internal/db/schema, internal/metricskey |
| internal/db/pgsql/query | api/pb, internal/db/schema |
| internal/db/schema | none |
| internal/events | api/pb, internal/authctx, internal/db/model |
| internal/metricskey | none |
| mocks/mockclient | api/client, api/pb, privpb |
| mocks/mockpb | api/pb |
| mocks/mocktrustycadb | internal/db/model, internal/db/pgsql/query |
| privpb | api/pb |
| privpb/httppb | privpb |
| privpb/mockpb | api/pb, privpb |
| privpb/proxypb | api/pb, privpb |
| server/app | api/version, internal/authctx, internal/config, internal/db, internal/metricskey, server/appcontainer, server/service, server/tasks |
| server/appcontainer | api/client, internal/authctx, internal/ca, internal/config, internal/db |
| server/service | server/service/admin, server/service/aia, server/service/auth, server/service/backend, server/service/ca, server/service/cis, server/service/orgs, server/service/status, server/service/ui |
| server/service/admin | api/pb, internal/db, internal/db/pgsql/query, privpb, privpb/httppb |
| server/service/aia | api/client, api/pb, internal/config, internal/db, internal/db/model, internal/metricskey, privpb, server/service/shared |
| server/service/auth | api/pb, api/pb/httppb, internal/authctx, internal/config, internal/db, internal/db/model, internal/events, internal/metricskey |
| server/service/backend | api/pb, internal/authctx, internal/ca, internal/ca/pbconv, internal/db, internal/db/model, internal/db/pgsql/query, internal/events, internal/metricskey, privpb |
| server/service/ca | api/client, api/pb, internal/authctx, internal/config, privpb, server/service/shared |
| server/service/cis | api/pb, api/pb/httppb, internal/ca/pbconv, internal/db, internal/db/model, internal/db/pgsql/query |
| server/service/orgs | api/pb, api/pb/httppb, internal/authctx, internal/config, internal/db, internal/db/model, internal/db/pgsql/query, internal/events |
| server/service/shared | api/client, privpb |
| server/service/status | api/pb, api/version |
| server/service/ui | api/pb, internal/config |
| server/tasks | server/tasks/certstatus, server/tasks/crlrenewal |
| server/tasks/certstatus | internal/config, internal/db, internal/db/pgsql/query, internal/metricskey |
| server/tasks/crlrenewal | api/pb, internal/ca, internal/db, internal/events, internal/metricskey |
| tests/load | api/pb, internal/db, internal/db/model, internal/db/pgsql/query |
| tests/mockappcontainer | internal/config |
| tests/testutils | internal/authctx, internal/config |
Packages
Tests live beside the source (<file>_test.go, fixtures in testdata/);
read them before expanding scope. Test notes below list only what is not
discoverable from file names. Not every package has a doc.go yet: the ones
that do are api/cli, api/cli/clisuite, api/client, internal/ca,
internal/ca/pbconv, internal/ctl/ctlsuite, internal/db, internal/db/model,
internal/db/pgsql, internal/db/pgsql/query, internal/db/schema,
internal/events, server/service/aia, server/service/backend,
server/service/ca, server/service/cis, server/service/shared,
server/tasks, server/tasks/certstatus, server/tasks/crlrenewal, tests/load
and tests/testutils. Add one when you change a package.
api/cli
Public trustyca command, client connections and output formatting.
- cli.go: Cli, Context, IsJSON, Reader, AfterApply, RPCClient, HTTPClient, AuthClient, OrgsClient, CISClient (the public CIS, no token)
Invariant: Cli.AfterApply changes process-wide xlog and time formatting, so CLIs are never parsed concurrently in one process: the CLI test suites do not call t.Parallel. A missing config file is created from defaultConfig under --storage, TRUSTYCA_STORAGE or DefaultStoragePath. A client that authenticates (RPCClient(false), HTTPClient(false)) sends TRUSTYCA_AUTH_TOKEN when the variable is not empty, else the token of the storage folder, and fails with unable to load auth token without either, for every server: a host of the config file only selects the storage folder and the trusted CA (TestRPCClient_StoredToken). StatusClient and CISClient dial without a token.
api/cli/clisuite
CLI test suites with fixture-backed HTTP servers and gRPC mocks.
- suite_grpc.go: TestSuiteGrpc (MockAuth, MockStatus, MockOrgs, MockCIS), SetupSuite, SetupMockGRPC, SetupTest
- suite_http.go: TestSuite, CapturePrint, HasNoText, SetupSuite, TearDownSuite
Invariant: CapturePrint records output with the mock server address replaced by {server}; TearDownSuite compares it with the suite's golden file, testdata/prints_.txt (testutils.CheckGolden), and rewrites the file only with TRUSTYCA_UPDATE_GOLDEN=1. The gRPC suite listens on an ephemeral port and replaces format.NowFunc per test. Suites share CLI globals, so they are not parallel.
api/cli/command
Public trustyca commands: auth, org, project, member, API key, status, and the certificate information of the CIS (cert, issuer, crl, root).
- apikey.go: APIKeyCmd, APIKeyCreateCmd, APIKeyListCmd, APIKeyDeleteCmd
- auth.go: AuthCmd, LoginCmd, SelectOrgCmd, RevokeCmd, AllowedCmd, ScopeCmd, UserinfoCmd, UICmd
- cis.go: CertCmd, CertSelector, CertGetCmd, CertStatusCmd, IssuerCmd, IssuerGetCmd, CrlCmd, CrlGetCmd, RootCmd, RootListCmd
- command.go: App
- member.go: MemberCmd, MembersListCmd, MemberAddCmd, MemberChangeRoleCmd, MemberDeleteCmd, InviteDeleteCmd
- org.go: OrgCmd, OrgCreateCmd, OrgListCmd, OrgGetCmd, OrgUpdateCmd, OrgDeleteCmd, OrgAccessCmd
- project.go: ProjectCmd, ProjectCreateCmd, ProjectListCmd, ProjectMemberCmd
- status.go: VersionCmd, ServerCmd, CallerCmd, CallerPingCmd
Invariants:
- Commands get clients from App; tenant operations use the org selected in the token. The CIS commands (cis.go) read the public Certificate Information Service through CISClient without a token, over gRPC or HTTP (
-H): every lookup names a certificate (ID, SKID, thumbprint, or issuer and serial) or an issuer, androot listthe platform or one org. - LoginCmd serves the OAuth redirect on a local listener with its own mux and waits for Serve to exit before returning. With
--no-browserthere is no listener: the flow ends on the server's/authenticatedpage with the token in the URL fragment (response_mode=fragment), never in a query string.
Tests: suite_test.go runs TestSuite (HTTP fixtures from api/cli/testdata) and TestRpc (gRPC mocks, the CIS commands included); their golden files are testdata/prints_TestSuite.txt and testdata/prints_TestRpc.txt. auth_internal_test.go drives the login listener directly.
api/cli/command/uname
Operating-system information for the CLI user agent.
- uname_linux.go, uname_darwin.go, uname_windows.go: Info, GenInfo
Invariant: One source file per OS; GenInfo returns system-call errors.
api/client
Named service clients and HTTP status requests.
- api_status.go: HTTPStatusClient, NewHTTPStatusClient, Version, Status, AuthURL
- factory.go: Config, Factory, Option, NewFactory, WithTLS, WithCallerIdentity, WithAgent, UserAgentWfe, ClientNameDefault, ClientNameAIA, ClientNameCA
Invariant: NewFactory takes the clients list of the configuration and refuses a client without a name or a duplicate name; every Factory method takes the client name and the listener name (server_url key) and returns Status, Orgs, CA, CIS or Backend clients (proxypb over the gRPC connection); callers close the returned connection. The TLS configuration of a WithTLS option is the one the client dials with; without it, an https server gets one built from the client's TLS files (NewClientTLSFromFiles), and an http server dials in plaintext. The gRPC client blocks until the connection is ready for dial_timeout, so a service creates its clients lazily (server/service/shared.BackendLocator). go:generate owns mocks/mockclient.
api/pb
Public protobuf API with handwritten conversion, print helpers and REST paths.
- pb.go: IDPFromString, IDPFromSlice, FindKVPair, MapFromKVPair, FlatMap; go:generate for mocks/mockpb
- print.go: RegisterPrintOnce, PrintKVPairs, PrintMembers, PrintMethodAccesses, Print methods (an issuer, profile, anchor, certificate, revocation, CRL or CIS view prints a key/value table and then its PEM, the CSR of a Pending issuer; a list prints a table and the cursor or offset of its next page, printNextPage)
- rest.go: PathFor* routes (PathForAuthOrg is the org switch of a cookie session; PathForCIS is the JSON API of the CIS; PathForCert, PathForCRL and the OCSP paths are the routes of the AIA service), OAuthResponseType* values, the OAuth error parameters and codes (OAuthParamError, OAuthParamErrorDescription, OAuthError*) the callback answers and the CLI listener reads; the AIA binary routes keep the paths of the issuer AIA and CDP templates (
/v1/cert/:ikid,/v1/crl/:ikid), OCSP by issuer is under/v1/ocspi, and the request of an OCSP GET is a catch-all segment (/v1/ocsp/*body,/v1/ocspi/:ikid/*body), since the URL-encoded base64 has '/' in it and Go decodes the path before routing
Invariant: Edit protos/, then make proto. Methods declare minimum roles with (es.api.allowed_roles) and API key scopes with (es.api.scopes); the generated allocator.pb.go (GetMethodInfo) is what authctx.CheckAccess reads. RegisterPrintOnce registers process-wide printers once.
api/pb/httppb
Generated HTTP handlers for api/pb services; regenerate with make proto. The handler runs the access check with the request's context before dispatching.
api/pb/mockpb
Generated api/pb service mocks; regenerate with make proto.
api/pb/modelpb
Generated protobuf model helpers; regenerate from api/pb/protos with make proto.
api/pb/proxypb
Generated in-process client/server adapters for api/pb; regenerate with make proto.
api/version
Build version and commit information for binaries and status endpoints.
- current.go: Current
- versioninfo.go: Info, PopulateFromBuild, String, GreaterOrEqual, Float
Invariant: current.go is generated (and gitignored) by make version from current.template; versioninfo.go owns parsing and comparison.
cmd/trustyca
Public trustyca CLI. main.go: main parses api/cli.Cli and runs its Kong context. TestHelp parses the whole command tree with --help.
cmd/trustycactl
Administrative CLI. main.go: realMain uses internal/ctl.Cli, binds command.App and adds the internal/ctl/admin commands (dpop-key, org, project, ca). TestHelp parses the whole command tree with --help: kong expands ${...} in help text, so a placeholder in a help string is written $${...}.
cmd/trustycasvc
Service process. main.go: main loads configuration and starts server/app; --dry-run opens the DB provider, which runs the migrations, and exits.
internal/authctx
Tenant context, grants, roles, scopes and API authorization.
- allowed.go: GetAllowedMethods, GetCallerScope, ProjectFromRequest
- authorizer.go: GrantsProvider, Authorizer, NewAuthorizer, ErrInsufficientRole, ErrAccessDenied, ErrOrgNotSelected
- authz.go: OrgRequester, ProjectRequester, ServiceRolePrefix, NewAuthUnaryInterceptor, CheckAccess
- ctx.go: TrustyCtx, Claim*, Handler, FromContext, FromRequest, NewTrustyCtx, NewAuthUnaryBackendInterceptor
- grants.go: Grants, GrantsFromMemberships, ResolvedOrgRole, Roles, HighestRole, CanGrantOrgRole, CanGrantProjectRole
- roles.go: CanAssumeRoles, ParseRole, CanAssumeRole, AllowsRole, OrgRoles, ProjectRoles
- scopes.go: Scope* constants, DefaultAPIKeyScopes, ParseScopes, HasScope, HasScopes, IsKnownScope
Invariants:
- The org comes from the token, never from the request: an explicit OrgID that differs from the token is refused, except from a
trustyca-*service role, which passes tenant scope explicitly. - Permissions are resolved from DB grants at request time; the org role claim is informational. Grants and projects are cached for 3 minutes; membership and project mutations call InvalidateUser / InvalidateProject. provideAuthorizer gives the app one Authorizer, so a service's invalidation clears the interceptor's cache.
- An inactive project, a project of another org and an unknown project are all ErrAccessDenied, so project existence does not leak across orgs.
- privpb.Admin accepts
trustyca-*service roles only (trustyca-viewer: Get, List and SupportTenant); pb.Status accepts any caller, and pb.Auth is gated by the server authz config only. API keys are checked against their scopes, never memberships, and only on methods whose allowed roles include APIKey. - NewAuthUnaryBackendInterceptor(authorizer) (the backend listener) builds the TrustyCtx from the identity the listener authenticated, so a service caller over mTLS (RA, AIA, the operator) acts under its own role. Only
trustyca-peer(PeerRoleName, the WFE) may forward its caller's context in thex-trustyca-contextmetadata that NewTrustyCtx adds to every outgoing call: the call then runs as that caller after CheckAccess authorizes it again, a/privpb.Backend/method with the roles and scopes of the/pb.CA/method of the same name. A forwarded context from another role is ignored (logged), and one that does not parse fails the call with Unauthenticated. The backend runs no CheckAccess for its service callers: the server authz config restricts its paths to service roles (backend_test.go).
Tests: an xdb.ID caches its string form without synchronization, so parallel tests build their own IDs (the fixture constructors in authctx_test.go, specRows in roles_test.go) rather than share one.
internal/ca
CA core: tenant-scoped resolution of issuers and profiles, the issuer cache, key handling, issuer creation and the platform bootstrap. Imported as core by server/service/ca, whose package is also named ca. The conversions between the API messages and the authority configuration are in internal/ca/pbconv.
- doc.go: package overview and a resolution example
- bootstrap.go: LoadBootstrapConfig, Registry.Bootstrap, BootstrapResult
- crl.go: CrlPEMType, CrlPublisher, NewCrlPublisher, PublishCrlsRequest, PublishCrlsResult, PublishCrls, PublishCrl, CrlDue
- errors.go: ErrProfileNotFound, ErrIssuerNotFound, ErrIssuerNotActive, ErrIssuerLabelRequired, ErrIssuerMismatch, ErrProfileNotAllowed, ErrIssuerExpired, ErrSoftwareKeysDisabled
- issuer.go: IssuerRequest, NewRootIssuer, NewSignedIssuer, NewPendingIssuer, ImportRequest, ImportIssuer, ActivatedIssuer, IsSelfSigned
- keys.go: SoftwareKeyProvider, DefaultKeyAlgo, DefaultKeySize, KeySpec, KeyLabel, IsKeyURI, KeyRef, Keys, NewKeys, DisableSoftwareKeys, Provider, Generate, KeyRefFromExport, ProtectKey, Signer, ImportKey, Destroy, PublicKeysEqual, SubjectKeyID
- registry.go: DefaultCacheTTL, DefaultCacheSize, Options, Registry, NewRegistry, ResolveRequest, Resolution, Resolve, FindProfile, FindIssuer, Issuer, IssuerBySKID, IssuerByKeyHash, IssuerByNameHash, InvalidateIssuer, InvalidateProfile, Purge, Len, AuthorityProfile
Invariants:
- Every lookup names its tenant scope: a label resolves in the project, then in the org, never in the platform or in another org; the platform scope (zero org) resolves only platform rows. An inactive profile is not found and does not fall back. Issuers of any status are found,
Resolveneeds Active,IssuerBySKID(OCSP, CRL) accepts Active and Archived. Failed resolutions are not cached. - The built
authority.Issueris cached by row ID (unique across orgs), the resolutions by(org, project, label)of the request, both inexpirableLRUs with the TTL and size of Options (DefaultCacheTTL5 minutes,DefaultCacheSize1000 issuers; the label caches hold four times the issuers).InvalidateIssuerdrops the issuer and its label;InvalidateProfilewith a zero project drops the label in every project of the org. A row newer than the built one (updated_at) rebuilds the issuer; an older row does not replace it. One issuer is built at a time under a lock striped by ID. - A profile is registered on the issuer under
{profile ID}@{updated_at ms}, the name the service passes incsr.SignRequest.Profile; the issuer keeps old versions until it is rebuilt. The delegated OCSP profile of an issuer is resolved in the issuer's scope at build time and registered under its label, and must bind to the issuer; a missing or unbound one fails the build with a plain error, neverErrProfileNotFound, since the profile of the request exists and the service reports a build failure as Internal. authority.Issuer.SignandSignOCSPare shared across requests;createIssuerbuilds a self-signed certificate without chain or roots, as xpki does for roots, because the bundler refuses a self-signed leaf under trust roots.- Keys: a provider key is referenced by its
pkcs11:key URI inkey_id(manufacturer inkey_provider) and loaded withcryptoprov.Crypto.NewSignerFromPEM; a software key is wrapped by the data protection provider intokey_protected(base64url ofProtect), withkey_provider = inmemand the key label inkey_id.KeyRefFromExporttells them apart by thepkcs11:prefix, since AWS KMS exports its URI as bytes too. Software keys are allowed by default and refused withErrSoftwareKeysDisabledafterDisableSoftwareKeys(every key that would be stored wrapped: the export of the inmem provider, the PEM of an import, a bootstrap key file; the wrapped keys of existing rows still load), which the container applies unlessca.allow_software_keysis set, and a prod environment refuses the setting at the start (provideCA).Provider(name)matchesmanufacturerormanufacturer/model, the default first. A Pending issuer'sskidisSubjectKeyIDof its key.Destroyneeds acryptoprov.KeyManager; software keys are destroyed by the row. - Rows:
chain_pemholds the CA certificates between the issuer and the root (parent.Issuer.PEM()for a signed issuer,bundle.CACertsPEMfor an import or activation),root_pemthe root, and a self-signed issuer is its own root; stored PEM comes fromcertutil.EncodeToPEMStringand has no trailing newline.NewSignedIssuerneeds a CA profile (CAConstraint.IsCA) resolved in the parent's scope and refusesType = Rootbefore it generates a key: a Root is self-signed, and only a self-signed certificate becomes a trust anchor (NewRootIssuer,ImportIssuer). It also checks the path length before the key (checkPathLength): every ancestor of the parent with a pathLenConstraint, walked by issuer through the parent's bundle, must allow one more CA, and the profile'smax_path_lenmust not exceed what the chain leaves (RFC 5280 section 4.2.1.9); xpki's own check is commented out. The error strings carry thedisallowsandexceedsmarkers, so the service answers InvalidArgument. Registry.Bootstrapis idempotent, and safe when several instances start against one fresh DB at once (the service instances, the test packages ofmake test): an issuer insert that loses the race to another instance (db.IsUniqueViolationof the label or key) continues with the row that instance registered, after the same key check as a lookup that finds it; self-signed certificates of the root bundle become private platform anchors; a registered issuer with the same SKID has its settings refreshed when they differ (UpdateIssuerwith the config, nevercrl_number); a certificate for another key is an error; the parent of a file issuer is set when its IKID is a registered platform issuer; profiles are upserted by label, with*for a profile without an issuer label; every profile is validated. Adisabledentry archives its registered Active issuer (BootstrapResult.Archived), so that it stops signing on every instance; an entry enabled again makes its Archived issuer Active in the same update as the settings; a Destroyed or Pending one is an error. A new root issuer is registered with its anchor in one transaction (RegisterIssuerwith the anchor); the anchor of a registered root issuer is registered again on every start from its stored certificate (RegisterRootis an upsert), so a deleted or missing anchor is repaired. After the profiles, every enabled issuer is built through the cache: a key that does not unprotect or a delegated OCSP profile that does not bind fails the start, not the first request. File URL templates must use:ISSUER_ID: the loader (authority.LoadConfig) expands${...}and$...as environment variables in every value, so LoadBootstrapConfig, which provideCA calls, reads the file without expansion first and refuses an issuer whose AIA, CRL or OCSP template has${ISSUER_ID}or$ISSUER_ID.- Rows shared between goroutines are never formatted with
xdb.ID.StringorUnderscoreString, which cache without synchronization: the package usesidString(xdb.IDString(id.UInt64())), andAuthorityProfileconverts a cached profile row throughmodel.CertificateProfile.Definition, neverPb.NewSignedIssuercopies the parent's ID by value into the new row. - CRLs (crl.go, DESIGN.md section 8):
CrlPublishertakes the write-capabledb.CaDbnext to the registry and is shared by the service and thecrl_renewaltask.PublishCrltakes an Active or Archived row read from the DB (itscrl_numberis the current one; another status isErrIssuerNotActive, an expired certificateErrIssuerExpired), reads the current CRL (db.GetCrl) and signs when it is due (CrlDue: no current CRL, ornext_updatenot after now plus theCrlRenewalof the row settings, read bycrlRenewalas the registry configures the issuer) or forced; otherwise it returns the current CRL with false. The issuer and its key are loaded through the registry only when a CRL is signed. The entries are the revocations of the IKID across every org whose certificate is valid now (ListRevokedwithAllOrgs,IKID,ValidAfter, paged by cursor), with their reason codes;ThisUpdateis now truncated to the second,NextUpdatenow plusCrlExpiry, capped at the issuer certificate'sNotAfter; the number iscrl_number + 1, stored bydb.PublishCrlwith the number in one transaction. Ondb.ErrStaleCrlNumberthe row and the current CRL are read again and the CRL signed once more (publishAttempts), unless the other publisher's CRL is not due and the publish is not forced. The PEM comes frompem.EncodeToMemory(trailing newline).PublishCrlslists the Active, then the Archived issuers of the scope (ListIssuersby status,issuerPageSizeper cursor page), reads the current CRLs of each page in one query (db.GetCrls, never a lookup per issuer) and counts the skipped (not due, or expired certificate) and failed issuers; a failure is logged at ERROR with the issuer and never stops the run; only a failure to list the issuers or to read their CRLs is returned, with the CRLs published before it in the result. Metrics:CACrlPublishedandCAFailPublishCrlby issuer label. - Tests (
ca_test) use a map-backed fakedb.CaDb(fake_test.go: issuers, profiles, roots, revocations and CRLs, withStaleto make the next publishes lose to another publisher andRaceto make the next issuer insert lose to another instance), theinmemprovider and a symmetric data protection provider (fixture_test.go), and create every issuer through the package; crl_test.go verifies the signed CRLs withx509.ParseRevocationList; bench_test.go measures the warm and cold resolution against a singleauthority.Authority(PLAN.md phase 2a).
internal/ca/pbconv
Conversions between the CA API messages and the xpki authority configuration, shared by the CA core, the CA and CIS services and the administrative CLI. A leaf package (api/pb only), so the CLI parses profile files without the DB driver.
- doc.go: package overview and a profile file example
- profile.go: ProfileFromPb, ProfileToPb, ExtensionsFromPb, ExtensionsToPb
- config.go: IssuerConfigFromPb, IssuerConfigToPb, IssuerIDVariable, IssuerIDPlaceholder, ExpandIssuerURL (the
${ISSUER_ID}and:ISSUER_IDplaceholders of the URL templates, replaced with the SKID as xpki does)
Invariant: ProfileFromPb validates with authority.CertProfile.Validate (expiry, usages, extensions, policies, name patterns) and drops the identity fields of a definition (ID, scope, status, timestamps); ProfileToPb takes a profile in the YAML shape of a ca-config file (authority.CertProfile) under a label, as the bootstrap and trustycactl ca profile register do. IssuerConfigFromPb always sets an AIA section, so the CRL and OCSP timings fall back to the authority defaults; IssuerConfigToPb keeps the AIA section, the allowed profiles and the extension policy of a file issuer, never its file locations. Tests (pbconv_test) round-trip a full profile and the settings.
internal/config
Service YAML, overrides and secret-backed configuration.
- config.go: Configuration (
Clients: the named service clients), Service, Service.IsLocal, Auth, Cache, Task, Orgs, CryptoProv, CA, AIA, WFEServerName, BackendServerName, AIAServerName, EnvironmentProd, EnvironmentDev, EnvironmentLocal, ClusterLocal - loader.go: ConfigFileName, DefaultFactory, Load, LoadForHostName, LoadWithOverride
- sql.go: SQL
Invariant: Environment variables use the TRUSTYCA_ prefix; host overrides come from trustyca-config.yaml.hostmap (UNIT_TEST loads trustyca-config.unittest.yaml over the base file), and --cfg-override merges a file key by key (trustyca-config.citest.yaml, the integration test stack: compose network names, env://TRUSTYCA_SQL_CONN, the KMS emulator, no tasks; TestLoadCitestOverride). Service.IsLocal is service.environment: local in service.cluster: local, the dev configuration (a developer machine, the unit tests, the integration test stack): it offers the local identity provider; every other environment and cluster fails closed. The wfe CORS admits the console in bearer mode (http://localhost:4200) and in cookie mode (https://app.local.trustyca.io:4200, a host under identity_map.cookies.domain .local.trustyca.io, so its script reads the CSRF cookie); gRPC-Web checks the same allowed_origins and exposes the response headers itself, and rs/cors accepts a preflight only with the requested headers lower-case and sorted, as browsers send them. crypto_provider names the key providers and ca the CA section: bootstrap_config (the platform ca-config, empty disables the bootstrap), issuer_cache_ttl and issuer_cache_size (zero takes the internal/ca defaults), retention, and allow_software_keys (off by default; on in the dev config for the platform key files; refused with service.environment: prod, EnvironmentProd). The backend and aia listeners list no root path under authz.allow_any, so a path without a rule is refused to every identity (server/app Test_Authz_CAMethods checks the role matrix of the three listeners); the wfe keeps / public for the UI index page. The backend listener of etc/dev/trustyca-config.yaml (services status, admin, backend; no pb.CA, whose requests take the org of a token) is the only one with a TLS identity map: it maps spiffe://trustyca/{peer,client,admin,ra,aia} to the trustyca-* roles (identity_map.tls.enabled: true: porto maps no identity, and every caller is a guest, unless the method is enabled) and allows /privpb.Admin to trustyca-admin and trustyca-peer, /privpb.Backend to trustyca-peer, trustyca-ra and trustyca-admin, and /privpb.Backend/SignOCSP to trustyca-aia as well, repeating the others, because porto authz takes the roles of the deepest matching path; it verifies a client certificate when given (client_cert_auth: false) so that probes reach the status routes. The wfe (client_cert_auth: false, so browsers connect) maps no TLS identity, so no service role is reachable there; it lists /pb.CIS and /pb.CA under authz.allow_any_role (an authenticated caller of any role; no CIS or CA path is under identity_map.skip_auth). aia is the AIA section (AIA; the CIS has none): ocsp_cache_size (zero takes the service default). clients lists the named service clients (client.Config): default, ca (the WFE to the backend with trustyca_peer) and aia (the AIA to the backend with trustyca_aia, which .project/gen_certs.sh --aia generates with --ra, both in make gen_test_certs); server_url names the listeners each client dials. The aia listener (servers.aia, plain HTTP, no identity_map, so every caller is a guest) lists the AIA routes (/v1/cert, /v1/crl, /v1/ocsp, /v1/ocspi) and the status routes under authz.allow_any and nothing else.
internal/ctl
Administrative CLI and its authenticated clients.
- ctl.go: Cli, Context, IsJSON, AfterApply, RPCClient, HTTPClient, AuthClient, OrgsClient, CISClient, AdminClient, BackendClient, Resolve
Invariant: AfterApply changes global logging and time formatting, as api/cli does. Admin commands use privpb. AdminClient and BackendClient (privpb.Backend, the CA of the service identities) are gRPC only, the backend listener; a client certificate (--cert, --cert-key) is the identity of a backend caller (the trustyca-admin role), so RPCClient tolerates a missing auth token when one is configured and fails without either.
internal/ctl/admin
Administrative commands: the org and project lists, DPoP keys, and the ca tree: the issuers, profiles, trust anchors, certificates and CRLs of an org through privpb.Backend, the support lists across orgs through privpb.Admin, and the onboarding of an org.
- admin.go: App
- ca.go: CACmd, OrgScope, PageFlags, IssuerSettings, SubjectFlags, KeyFlags, readPEM, parseIssuerStatus, parseAuthorityType, parseCertificateStatus, isID
- issuer.go: IssuerCmd, IssuerListCmd, IssuerGetCmd, IssuerRegisterCmd, IssuerImportCmd, IssuerActivateCmd, IssuerArchiveCmd, IssuerDestroyCmd, updateIssuerStatus
- profile.go: ProfileCmd, ProfileListCmd, ProfileGetCmd, ProfileRegisterCmd, ProfileDeleteCmd, ProfileFileExtensions, LoadProfile, LoadProfiles
- root.go: RootCmd, RootListCmd, RootRegisterCmd
- cert.go: CertCmd, CertListCmd, CertSelector, CertGetCmd, CertRevokeCmd
- crl.go: CrlCmd, CrlGetCmd, CrlPublishCmd
- bootstrap.go: CAOrgCmd, OrgBootstrapCmd
- dpop_keys.go: DpopKeysCmd, DpopKeyGenCmd, DpopKeyListCmd, KeyInfo, NewKeyInfo, PrintKeys
- org.go: OrgCmd, OrgListCmd
- project.go: ProjectCmd, ProjectListCmd
Invariants:
- App supplies the clients and the input/output. The CA of the operator is privpb.Backend (App.BackendClient), served by the backend listener to the trustyca-admin identity of the client certificate, which names the org of every request in OrgID (
--org, OrgScope, with--projectfor the rows of a project);ca issuer listandca cert listare the support views of privpb.Admin (ListAllIssuersRequest, ListAllCertificatesRequest: every org and the platform,--platform, or--org), the other lists and reads use privpb.Backend (ca root listandca crl getwithout an org read the platform anchors and any CRL). A PEM argument is a file (readPEM,~expanded); a key file is sent to ImportIssuer as PEM and never printed or logged.ca issuer archiveanddestroyare the Archived and Destroyed transitions of UpdateIssuer. - A profile file is one profile in the YAML shape of the profiles of a ca-config file (authority.CertProfile), labelled by
--labelor the file name without its extension (LoadProfile), converted and validated with internal/ca/pbconv before anything is sent;--issuerreplaces its issuer_label, which is required. ca org bootstrap(OrgBootstrapCmd, DESIGN.md section 6): the parent is a platform issuer named by ID, or by label through the support list (Active, exactly one); the issuing CA is registered first, signed with the CA profile of the parent (--profile, defaulttenant_ca, which the parent must allow), then the template profiles of the directory (LoadProfiles, file name order): a template without an issuer label is bound to the new issuer, one bound to any issuer (*) is kept and listed in the allowed profiles of the issuer unless--allowed-profilesnames them. The command is not idempotent for the issuer (its label is taken: AlreadyExists), profiles are upserts; a failed profile leaves the issuer in place and names the profile to register by hand.- Tests: ca_test.go runs every command over the suite's MockBackend and MockAdmin with the dev templates (
etc/dev/profiles) and temporary PEM files, capturing the table and JSON output in testdata/prints_TestRpc.txt; e2e_test.go (not parallel) runs the backend and Admin services of the app container over the configured DB behind a TCP gRPC server whose interceptor sets the trustyca-admin identity, and drives them with the commands: it onboards a new org undertrusty.l1with the dev templates, signs a certificate through the API with a copied profile, then lists, reads, revokes, checks OCSP through the delegated responder of theocsptemplate, publishes and reads the CRL, and archives and destroys the issuer.
internal/ctl/ctlsuite
Admin CLI test suites with HTTP fixtures and gRPC mocks.
- suite_grpc.go: TestSuiteGrpc (MockAuth, MockStatus, MockOrgs, MockBackend, MockAdmin), SetupSuite, SetupMockGRPC, SetupTest
- suite_http.go: TestSuite, CapturePrint, HasNoText, SetupSuite, TearDownSuite
Invariant: As api/cli/clisuite: CapturePrint output, with the mock server address replaced by {server}, is compared with testdata/prints_.txt (testutils.CheckGolden) and rewritten only with TRUSTYCA_UPDATE_GOLDEN=1. A suite that captures nothing has no golden file. AfterApply changes global formatting, so suites are not parallel.
internal/db
Database interfaces and the PostgreSQL provider constructor.
- doc.go: package overview and a construction example
- trustycadb.go: OrgsReadonlyDb, OrgsDb, CaReadonlyDb, CaDb, Provider, New, ErrAlreadyRevoked, ErrStaleCrlNumber, ErrRootConflict, ErrOrgScopeRequired, IsUniqueViolation, UniqueIssuerLabel, UniqueIssuerSkid, UniqueCertificatePrefix
Invariant: OrgsReadonlyDb owns reads, OrgsDb mutations. New runs the migrations of sql.migrations_dir. go:generate owns mocks/mocktrustycadb. CaReadonlyDb owns the CA reads and CaDb the mutations (issuers, roots, profiles, certificates, revocations, CRLs, and the bulk ExpireCertificates and DeleteExpiredCertificates of the certificate status task); Provider implements both. GetCrls returns the current CRLs of the IKIDs it is given, bounded by the caller's page of issuers and unpaginated. CA rows with a zero OrgID are the platform's (org_id IS NULL). Tenancy fails closed in the DB layer: a List names its org scope (OrgID, Platform or AllOrgs) or fails with ErrOrgScopeRequired, and every mutation of an existing row (Update, Activate, Revoke, Delete, the FOR UPDATE read of RevokeCertificate) matches the exact org scope with org_id IS NOT DISTINCT FROM the org, so another org's row is not found or not deleted; a Get by ID returns the row of any scope and the caller verifies its org and project. Lifecycle transitions of an issuer are not enforced by the DB layer. The CA sentinel errors are re-exported from pgsql and query, so services compare them with errors.Is without importing those packages; IsUniqueViolation (pgsql/errors.go) tells a unique violation of a named constraint prefix by the driver's SQLSTATE and constraint name, or by the driver's message for the fakes of the tests, so a service maps a conflict (AlreadyExists) and the bootstrap a lost insert race without parsing messages.
internal/db/model
Database rows and their conversion to public API messages.
- apikey.go: Validate, IsExpired, Pb, NextPage
- certificate.go: NewCertificate, Validate, IsExpired, Pb, NextPage
- crl.go: Validate, Pb, NextPage
- doc.go: package overview
- event.go: Validate, Pb, NextPage
- invite.go: Validate
- issuer.go: Validate, SetCertificate, SetConfig, GetConfig, Pb, NextPage
- json.go: JSON, MarshalJSONValue, JSON.Unmarshal
- member.go: ScopeOf, Validate, Scope, Pb, FindMemberByUserID, FilterByOrg, OrgIDs, CountOrgRole, Invite.IsExpired
- org.go: Validate, Pb, NextPage
- profile.go: AnyIssuerLabel, NewCertificateProfile, Validate, SetConfig, Definition, Pb, NextPage
- project.go: ProjectAliasPrefix, Validate, Pb, NextPage
- records.go: RecordsResult, Pb
- revoked.go: Validate, NewRevokedCertificate, RevokedCertificate.Certificate, Pb, NextPage
- root.go: NewRootCertificate, Validate, Pb, NextPage
- tenancy.go: MaxLenForLabel, MaxLenForName, MaxLenForSha256, validateTenancy, validateLength
- user.go: User.Pb, Login.Pb, Validate, NewUser, FindLoginByID
Invariant: model.gen.go is schema-generated; handwritten files own validation and conversion. A membership or invite is org-wide when ProjectID is zero, project-scoped otherwise (ScopeOf). A CA row with a zero OrgID is the platform's and a project needs an org (validateTenancy). model.JSON is the raw value of the jsonb config columns of issuer and certificate_profile (typesmap.yaml): it writes an empty value as {} because the columns are NOT NULL, and PostgreSQL normalizes the stored document, so compare configs parsed (GetConfig, Pb), not as text. CertificateProfile.SetConfig strips the identity columns (ID, scope, labels, status, timestamps) from the stored definition and Pb restores them from the row; Definition restores the labels, status and timestamps only, for a row a cache shares between goroutines, since xdb.ID formats itself into an unsynchronized cache; Issuer.Pb, CertificateProfile.Pb and Definition return an error because they parse the config. RevokedCertificate is the vw_revoked_certificate row, whose id is the revocation and certificate_id the certificate; NewRevokedCertificate composes it from the two rows. Tests compare xdb.ID values with UInt64(): the ID caches its string form, so assert.Equal on two IDs depends on which was printed.
internal/db/pgsql
PostgreSQL queries for users, logins, orgs, projects, members, invites, API keys, events and the CA tables.
- apikey.go: RegisterAPIKey, ListAPIKeys, GetAPIKey, UseAPIKey, DeleteAPIKey
- certificate.go: RegisterCertificate, UpdateCertificate, GetCertificate, GetCertificateBySha256, GetCertificateByIssuerSerial, ListCertificates, DeleteCertificate, ExpireCertificates, DeleteExpiredCertificates
- crl.go: ErrStaleCrlNumber, PublishCrl, GetCrl, GetCrls, ListCrls, DeleteCrl
- errors.go: UniqueIssuerLabel, UniqueIssuerSkid, UniqueCertificatePrefix, IsUniqueViolation
- doc.go: package overview and the transaction pattern
- event.go: TryCreateEvent, CreateEvent, ListEvents, GetEvent
- invite.go: DefaultInviteExpiry, CreateInvite, GetInvite, GetOrgInvites, AcceptInvite, AcceptInvites, acceptInvite, takeInvite
- issuer.go: RegisterIssuer, registerIssuer, UpdateIssuer, ActivateIssuer, GetIssuer, FindIssuer, GetIssuerBySKID, ListIssuers, DeleteIssuer
- member.go: AddMember, UpdateMemberRole, GetUserMemberships, ListMemberships, DeleteMember
- org.go: RegisterOrg, UpdateOrg, ListOrgs, GetOrg, FindOrg, GetUserOrgs, DeleteOrg
- profile.go: RegisterProfile, GetProfile, FindProfile, ListProfiles, DeleteProfile
- project.go: RegisterProject, UpdateProject, GetProject, FindProject, ListProjects
- provider.go: Provider, New, BeginTx, Tx, NextID, DbMeasureSince, CheckErrIDConflict, NewNotificationsListener, listRows
- revoked.go: ErrAlreadyRevoked, RevokeCertificate, GetRevoked, ListRevoked, ListRevokedCertificates
- root.go: ErrRootConflict, RegisterRoot, GetRoot, ListRoots, DeleteRoot
- user.go: LoginUser, GetUser, GetUserByEmail, UpdateUser, DeleteUser, ListLogins
Invariant: TryCreateEvent writes on its own goroutine with a background context and only logs failures. The metadata jsonb columns of event and certificate are NOT NULL and xdb.Metadata writes an empty map as NULL, so CreateEvent and RegisterCertificate pass query.MetadataArg, which writes {}, and query.LocationsArg does the same for the NOT NULL varchar[] locations columns. A method that writes more than one row opens a transaction with BeginTx and must run every statement on the returned provider. RegisterOrg inserts the org and, with an owner, its Owner membership in one transaction. AcceptInvite and AcceptInvites (one transaction per invite, returning the grants it created) delete the invite first with query.TakeInvite (DELETE ... RETURNING), which locks the row, and add the grant from the deleted row: a re-issued invite grants its current role, a withdrawn or already accepted one is not found and grants nothing, and an email mismatch, an expired invite or a failed grant rolls the delete back. LoginUser inserts a new login and user under one ID, so only a new user's first login returns both with the same ID. RegisterCertificate with an event inserts the certificate and the event (referencing the certificate) in one transaction. RegisterIssuer of a root requires its anchor, and inserts the issuer and upserts the anchor as RegisterRoot does in one transaction; the anchor must be the issuer's certificate (sha256) in its org, an anchor of another scope fails both with ErrRootConflict, and any other issuer takes no anchor. GetRevoked takes a GetRevokedRequest: the certificate ID, or the IKID and serial number as OCSP asks (migration 3 adds the unique index on them); both must match when both are given. RevokeCertificate locks the certificate (FOR UPDATE), inserts the revocation copied from the certificate row and sets the status in one transaction; a Revoked certificate fails with ErrAlreadyRevoked. PublishCrl sets issuer.crl_number to the CRL's number only on the issuer whose SKID is the CRL's IKID and only when the number is greater (query.SetIssuerCrlNumber, which does not touch updated_at), copies the tenancy and issuer name from that issuer row, and upserts the crl row by IKID in the same transaction; a mismatched IKID is an error, a number that is not greater fails with ErrStaleCrlNumber, and in both cases nothing is stored. UpdateIssuer validates the config as a pb.IssuerConfig document and with Destroyed clears key_protected; ActivateIssuer matches status = Pending, so another status is not found. RegisterRoot upserts only within the same org scope: the conditional ON CONFLICT update returns no row for another scope, which is mapped to ErrRootConflict. listRows runs a list with ExecuteQueryWithCursor when the request carries a Cursor, else ExecuteQueryWithPagination; xdb reports a next page when a page is full, so the page after an exact multiple of the limit can be empty. ExpireCertificates and DeleteExpiredCertificates change one batch per call, the lowest IDs of the rows that match (id IN (SELECT id ... ORDER BY id LIMIT ?)), across every org: a changed row leaves the set, so the caller repeats the call without an offset until a batch is smaller than its limit; both return the rows affected and are served by idx_certificate_notafter. ExpireCertificates repeats the Active status outside the batch subquery (WHERE status = ? AND id IN (...)): the subquery is evaluated on the snapshot the statement started with, and PostgreSQL rechecks only the outer predicate on the current version of a row the statement waited for, so a certificate RevokeCertificate revokes meanwhile keeps Revoked. Tests need the configured PostgreSQL database (provider_test.go TestMain); the CA tests build certificates with tests/testutils.NewTestCA and give platform rows random labels (ca_test.go); Test_Certificate_Expiry uses validity periods decades ago, so the bulk statements touch its rows only, and Test_Certificate_Expiry_Revoked holds the row lock in a transaction, polls pg_stat_activity for the waiting expiry statement, then revokes and commits.
internal/db/pgsql/query
SQL and query parameters for the PostgreSQL provider.
- apikey.go: RegisterAPIKey, ListAPIKeysRequest, GetAPIKey, UseAPIKey, DeleteAPIKey
- certificate.go: RegisterCertificate, UpdateCertificateRequest, UpdateCertificateStatus, GetCertificateForUpdate, GetCertificateBySha256, GetCertificateByIssuerSerial, ListCertificatesRequest, ExpireCertificatesRequest, ExpireCertificates, DeleteExpiredCertificatesRequest, DeleteExpiredCertificates
- common.go: BuildQueryFunc, GetRowByID, GetRowByColumn, DeleteRowByID, DeleteRowByOrgAndID, ListAllColumns
- crl.go: PublishCrl, GetCrlByIKID, GetCrlsByIKIDs, DeleteCrl, ListCrlsRequest
- cursor.go: InitialCursor, Cursor, ParseCursor, NewCursor, Cursor.IsSet, Cursor.LastID, EncodeCursor, setPage, pageByID
- doc.go: package overview
- event.go: CreateEvent, ListEventsRequest, ListEvents
- invite.go: CreateInvite, GetInviteRequest, TakeInvite, DeleteInviteRequest, GetOrgInvites, GetUserInvites
- issuer.go: RegisterIssuer, UpdateIssuerRequest, ActivateIssuer, SetIssuerCrlNumber, FindIssuerRequest, GetIssuerBySKID, ListIssuersRequest (org scope, project, visible projects, parent, label, status, type)
- member.go: AddMember, UpdateMemberRoleRequest, ListMembershipsRequest, DeleteMemberRequest
- org.go: RegisterOrg, UpdateOrgRequest, ListOrgsRequest, GetUserOrgs
- profile.go: RegisterProfile, FindProfileRequest, ListProfilesRequest
- project.go: RegisterProject, UpdateProjectRequest, ListProjectsRequest, GetProjectByAlias
- revoked.go: RevokeCertificateRequest, RegisterRevoked, GetRevokedRequest, GetRevoked, ListRevokedRequest, ListRevokedCertificatesRequest
- root.go: RegisterRoot, ListRootsRequest
- scope.go: ErrOrgScopeRequired, OrgArg, MetadataArg, LocationsArg, checkListScope, setProjectScope, setVisibleProjects, whereProjectScope, setOrgScope, whereOrgScope, setTenancy, whereTenancy, whereOrgIs
- user.go: RegisterLogin, RegisterUser, UpdateUser, GetUserBy, GetLoginBy
Invariant: Request structs own QueryParams and pagination; a query is built through xsql GetOrCreateQuery under a stable name, and its SQL is cached by name. Table definitions come from internal/db/schema. Scope filters (scope.go): the project is project_id = ?, IS NULL (Scope Org) or IS NOT NULL (Scope Project) by setProjectScope, or (project_id IS NULL OR project_id = ANY(?)) by setVisibleProjects for a list limited to the org-wide rows and the caller's projects (ListIssuersRequest.ProjectIDs, ListProfilesRequest.ProjectIDs, ListCertificatesRequest.ProjectIDs, ListRevokedCertificatesRequest.ProjectIDs; nil is no filter, an empty list the org-wide rows only; an exact project scope takes precedence), marked by a query flag so that the SQL is cached under another name; the org of a CA table is org_id = ?, IS NULL (Platform) or, only with AllOrgs, unfiltered by setOrgScope (each List request's Validate returns ErrOrgScopeRequired otherwise); Find requests use setTenancy, where a zero ID is NULL, and mutations match org_id IS NOT DISTINCT FROM ? with OrgArg (whereOrgIs, DeleteRowByOrgAndID). The SQL literals Now(), '' and NULL are the expr* constants of common.go. IS NULL predicates are recorded as null columns of the QueryParams, which the query name hashes, and the WHERE clauses of a builder follow the order of the Set calls of its request, because the positional arguments do. CA lists order by id DESC and page with setPage/pageByID (cursor.go), served by the org-led indexes of the certificate table ((org_id, id DESC), (org_id, project_id, id DESC), (org_id, ikid, id DESC); DESIGN.md section 4.5, the 10M-row load test), so a tenant list never walks the table for a small org and a list by a foreign IKID finds nothing without a scan: an offset page adds LIMIT and OFFSET, a cursor page id < ? and LIMIT with the last ID of the previous page, which EncodeCursor encodes as a string id. setPage is the last call of a QueryParams, because xdb refuses positional arguments after the limit. GetRowByColumn caches per table and column.
internal/db/schema
Generated table and column metadata for query builders.
- schema.go: init
Invariant: make gen-sql-schema generates schema.gen.go and model/model.gen.go from a recreated local database (--view vw_membership_info --view vw_revoked_certificate); typesmap.yaml controls type conversion, maps the jsonb config columns to the handwritten model.JSON and the text columns of the views to string. xdb's TableInfo.AllColumns caches its result without a lock, so init warms every table of TrustycadbTables while the process is single-threaded.
internal/events
Audit event builder for org, project, member, user and API key actions.
- events.go: Recorder, Event, New, Org, Project, Reference, Email, Description, Meta, Model, Emit, ParseTimeRange
Invariants:
- New takes the event type, a static title and the source, the name of the emitting service (
auth,orgs); the actor email comes from the authctx caller unless Email overrides it, as flows without a token (OAuth callback, API key sign-in) do. Meta skips empty values. - Emit hands the event to a Recorder (db.OrgsDb.TryCreateEvent), which writes it in the background and only logs a failure: emit after the action succeeded, never inside a transaction.
- ref_id follows the action: the org, project or API key acted on, the user for member, sign-up, sign-in and sign-out events, and the invite for an invitation.
internal/metricskey
Process-wide DB, task, method, login, CA, AIA download and CIS cache metric descriptors (metricskey.go).
Invariant: Descriptors are registered through Metrics at startup (appinit.Metrics); metric names and label sets are dashboard contracts (DESIGN.md section 11). The CA emits ca_cert_issued and ca_fail_sign_cert by issuer, profile and org, the ca_sign_latency sample by issuer and profile (SignCertificate, from the signature to the registered certificate), ca_cert_revoked by IKID, ca_ocsp_signed by IKID and status, ca_crl_published and ca_fail_publish_crl by issuer; the AIA aia_cache_hit/aia_cache_miss by type and the aia_download_* counters.
mocks/mockclient
Generated gomock for api/client; regenerate with make generate. The mocks/ tree is gitignored.
mocks/mockpb
Generated gomock for api/pb services (auth, status, orgs, ca, cis); regenerate with make generate (go:generate in api/pb/pb.go).
mocks/mocktrustycadb
Generated gomock for internal/db; regenerate with make generate.
privpb
Private protobuf APIs of the backend listener: privpb.Admin (support views across orgs) and privpb.Backend (the CA of the service identities and the signing plane, DESIGN.md section 2.1).
- print.go: Print helpers
- privepb.go: GetAdminMethodsInfo
Invariant: Edit protos/admin.proto or protos/backend.proto, then make proto (make proto-priv); never edit generated files. privpb.Backend has every method of pb.CA: its requests are copies of the pb.CA requests with OrgID as field 1 (which the public requests reserve) and every other field under the same name and number, since the CA service converts a public request by its encoding (server/service/ca TestRequests_Counterparts); SignOCSP takes pb.OCSPRequest, and the responses are the pb messages. A new CA method or field goes into both protos. The Admin support lists across orgs take ListAllIssuersRequest and ListAllCertificatesRequest. privpb.Backend is gRPC only: no listener registers its generated HTTP handler.
privpb/httppb
Generated HTTP handlers for privpb.Admin and privpb.Backend; regenerate with make proto. The admin service serves the Admin handler; the Backend one is not registered.
privpb/mockpb
Generated privpb.Admin and privpb.Backend mocks; regenerate with make proto.
privpb/proxypb
Generated in-process client/server adapters for privpb.Admin and privpb.Backend; regenerate with make proto. client.Factory.BackendClient wraps the gRPC connection with NewBackendClient.
server/app
Loads, starts and shuts down configured servers and tasks.
- app.go: App, NewApp, WithConfiguration, WithContainerFactory, Run, Close, Server
Tests: authz_test.go (Test_Authz_CAMethods) evaluates the authz rules of the dev configuration with porto's interceptor for every method of pb.CA, privpb.Backend, pb.CIS and privpb.Admin and every backend identity, on the three listeners: on the backend the peer, the RA and the admin reach every backend method and the AIA identity Backend.SignOCSP only, no pb.CA method is reachable, the Admin API admits the admin and the peer, a path without a rule is refused to everyone; the wfe maps no TLS identity, does not require a client certificate, serves the CA and the CIS to any authenticated role but no guest, and admits the admin only to the Admin API; the aia listener opens its routes and the status routes to a guest and refuses every other path. app_test.go passes a listen URL for each of the three listeners (--wfe-listen-url, --backend-listen-url, --aia-listen-url) so the tests bind no fixed port; Test_AppInstance_WebRole starts a web pod (backend none, no tasks) under a crypto provider and bootstrap that do not exist, and checks that a process with the backend fails on them; Test_App_ClientCertFlags checks the refused client certificate flags.
Invariant: Run starts each enabled server of servers with service.Factories; the names are wfe, backend and aia (config.*ServerName), and a server name the app does not know fails the start. --wfe-listen-url, --backend-listen-url and --aia-listen-url replace the listen URLs of a server (none disables it). The wfe server adds authctx.Handler and NewAuthUnaryInterceptor (user tokens, grants); the backend server uses NewAuthUnaryBackendInterceptor with the Authorizer (mTLS service identities, and the callers the WFE forwards, authorized again); aia has no interceptor: the aia listener has no identity map, so every caller is a guest and its authz rules list its public routes only. porto's --client-cert, --client-key and --client-trusted-ca fail the start: a process dials with the named clients of clients, each with its own certificate. A task named in tasks must exist in server/tasks.Factories, or startup fails. Only the backend service and the crl_renewal task depend on the issuer registry, so a process without them builds no registry, loads no crypto provider and runs no bootstrap (DESIGN.md section 2.2).
server/appcontainer
Service dependency graph and ordered resource cleanup.
- appcontainer.go: ContainerFactory, NewContainerFactory, With*Provider, CreateContainerWithDependencies
- closer.go: Closer, NewCloser, OnClose, Close
Invariant: The container provides configuration, discovery, scheduler, JWT (accesstoken over dataprotection, with porto's revocation over the cache: a token revoked by Auth.RevokeToken is refused at once by the process that revoked it and by the others after their snapshot of the revoked IDs expires, 5 minutes; every token parse reads that snapshot, so a process that parses tokens needs the cache), DB, the client factory (client.NewFactory of clients; an unnamed or duplicate client fails it), dataprotection, cache, one Authorizer, OAuth2 clients, the crypto providers (cryptoprov.Load of crypto_provider) and the CA issuer registry (*ca.Registry, provideCA), all resolved lazily by dig, which also runs Registry.Bootstrap on ca.bootstrap_config when it is set (read with ca.LoadBootstrapConfig, which refuses an issuer URL template with ${ISSUER_ID}); the bootstrap loads every enabled platform issuer, so one whose key does not unprotect (another data protection seed) or whose delegated OCSP profile does not bind fails the start. provideDp fails without TRUSTYCA_DP_SEED. The cache root key is /trustyca. Closer runs cleanup in reverse order. TestAppContainer (devContainer) resolves the registry against the local stack, and TestBootstrap_ConcurrentStart bootstraps one new platform issuer from several goroutines at once (every bootstrap succeeds, the issuer is registered once), so they bootstrap the dev platform issuers into the dev DB under the data protection seed of the environment, testseed when none is set (testutils.SetDataProtectionSeed, the rule of the Makefile), as server/app's Test_AppInstance_StartStop and the CA e2e test do: a platform key wrapped under another seed fails the start with a message that points at the seed (Keys.Signer, which loads tenant and imported keys too and so advises nothing about the row).
server/service
Service factories and helpers shared by the HTTP and gRPC services.
- service.go: Factories, GetPublicServerURL
Invariant: Factories registers admin, aia, auth, ca, cis, orgs, status and ui. GetPublicServerURL trusts X-Forwarded-Proto; forwarded headers and caller identity stay untrusted unless the server configures them.
server/service/admin
Private Admin API: the support views across orgs.
- admin_service.go: Service, Factory, AdminHTTPHandler, RegisterRoute
- orgs.go: ListOrgs
- projects.go: ListProjects
- issuers.go: ListIssuers
- certificates.go: ListCertificates
- scope.go: listScope, parseListScope, listCursor, parseTime
Invariant: Factory registers privpb.Admin and POST /privpb.Admin/:action; authctx.CheckAccess restricts it to trustyca-* service roles, and the authz config of the listeners to trustyca-admin. The service reads the CA tables through db.CaReadonlyDb and holds no keys. ListIssuers and ListCertificates list the org the request names (with its project; a project needs an org), the platform rows (Platform without an org), else every org and the platform (query AllOrgs), newest first, with the filters of the tenant lists (label, status and type; IKID, profile, status and ExpiringBefore) and without the redaction of the CIS, since the callers are support staff; a stored issuer config that does not parse is logged and answered as Internal. A certificate list by IKID without an org resolves the org of the issuer first (GetIssuerBySKID), so the list is served by the org-led index; an IKID of no registered issuer keeps the list across orgs, since a deleted issuer keeps the certificates it issued. Tests run the methods over gomock DBs and assert the query requests.
server/service/aia
The Authority Information Access service (DESIGN.md section 9.4): the binary routes the issued certificates point at, served over the plain HTTP aia listener to any caller, REST only (no gRPC API): the issuer certificate (AIA caIssuers), the current CRL (CDP) and the OCSP responder, which forwards to the backend service (privpb.Backend.SignOCSP).
- doc.go: package overview and a wiring example
- aia_service.go: ServiceName, Service, Factory, New, RegisterRoute, signer
- aia.go: IssuerHandler, CRLHandler, GetOcspHandler, OCSPHandler, issuedIssuer, ocspResponse, writeOCSPError, writeCacheable, derOf
- cache.go: ocspCache, newOcspCache, keyOf, etagOf
Invariants:
- The service reads
db.CaReadonlyDb(GetIssuerBySKID,GetCrl) and holds no issuer keys; every lookup is by the key identifier in the path or by the OCSP request itself, and nothing is listed. There is no authentication: theaialistener has no identity map, every caller is a guest, and itsauthz.allow_anylists the AIA and status routes only, so a path without a rule is refused (server/app Test_Authz_CAMethods). A Pending issuer, which has no certificate, is not found (issuedIssuer). New(cfg, caDb, backend)takes the shared.BackendLocator of the backend the OCSP requests are forwarded to; without one every OCSP request answers tryLater. The Factory builds it over the server's discovery and the container's client factory: the backend service of the same process when it runs one, else a client ofconfig.BackendServerNamewith theaiaservice client (thetrustyca-aiaidentity, allowedBackend.SignOCSPonly), created on the first OCSP request, never at startup, because porto's gRPC client blocks until the backend is reachable and the listeners start in any order; a failure answers tryLater and the next request tries again; the client is kept and closed with the service. The forwarded call is bounded bycaCallTimeout.- OCSP (
ocspResponse, RFC 6960): the request of a GET is the URL-encoded base64 in the path of/v1/ocsp/*bodyand/v1/ocspi/:ikid/*body(the issuer segment is not used: the request carries the issuer, ROADMAP RM-003), the request of a POST is the body, bounded bymaxOCSPRequestSizewhatever the request declares. A request that does not parse is malformedRequest with 400 before anything is forwarded. The signed responses are cached by the SHA-256 of the DER request (ocspCache, an LRU ofaia.ocsp_cache_size, default 10000) until theNextUpdatethe CA signed, which the cache checks on every hit, so a request with a nonce is never answered from another's entry, and a revocation reaches the AIA when the cachedgoodanswer expires (ocsp_expiryof the issuer) or the entry is evicted; a response already past itsNextUpdate, or one that does not parse, is passed through withno-storeand not cached. A failure of the CA is an OCSP error response with the HTTP status of the porto error: 400 malformedRequest, 404 unauthorized (an issuer the CA does not serve), 503 tryLater (unavailable, a timeout, throttling, or no client), else 500 internalError; errors are never cached. Metrics:AIACacheHit/AIACacheMisswith typeocsp,AIADownloadSuccessOCSP/AIADownloadFailOCSP. - The binary routes serve DER (
derOf, the first PEM block): the issuer certificate of/v1/cert/:ikid(application/pkix-cert, cached forcertMaxAge, a day, since a key identifier never changes certificate) and the current CRL of/v1/crl/:ikid(application/pkix-crl).writeCacheablesetsCache-Control: public, no-transform, must-revalidate, max-age=until the expiry (NextUpdateof a CRL or OCSP response),Last-Modified(ThisUpdate, or the start of the certificate's validity),Expiresand anETag(the quoted SHA-256 of the body, answered with 304 toIf-None-Match); a body already expired is served withno-store. A missing row is a JSON not-found error (marshal.WriteJSON) and counts inAIADownloadFail*. - Tests (
aia_test, service_test.go):newTestEnvbuilds the service withNewover a gomockCaReadonlyDbwhose two reads serve atestStore(an issuer with its chain, a Pending issuer, a CRL signed withx509.CreateRevocationList, a failure that every read returns) and afakeCA(privpb.UnimplementedBackendServerthat signs OCSP with the key of the issuing test CA for the serials it knows, counts the calls, and returns a configured failure, a zero validity or bytes that are not a response); the routes run throughrestserver.NewRouter. aia_test.go covers the Factory, rest_test.go the routes (TestRoutes, including that the JSON API is not served), the AIA and CRL handlers with their headers and conditional requests, the OCSP matrix (good, revoked, unknown, another issuer, the cache by route, the error mapping, the uncached cases) and the lazy backend client overmockclient.MockFactory(TestOCSPHandler_Backend); cache_test.go (package aia) the expiry, eviction and a concurrent run. e2e_test.go (not parallel) builds the app container over the configured DB under the data protection seed of the environment, starts the backend service and the AIA over plain HTTP with the backend wired through a bufconnprivpb/proxypbclient under thetrustyca-aiaidentity (the RA is a privpb.Backend client), registers a root whose URL templates point at the AIA listener, and follows the AIA, CDP and OCSP URLs of the certificates it signs (the issuer certificate, the CRL with the revoked entry, OCSP by POST and by GET from the cache; the JSON API is not served), then runsopenssl verify -crl_checkwhen openssl is installed.
server/service/auth
OAuth login, code exchange, org selection, API key authentication, token revocation and the cookie session of the Web UI.
- apikey.go: AuthenticateAPIKeyHandler, AuthenticateAPIKey, validateHMAC, findAPIKey
- auth_service.go: Service, Factory, RegisterRoute, Protect, Unprotect, SetAuthProvider, AuthProviderForEmail, isLocal
- authorize.go: AuthorizeHandler, Request, State, OTCState, localEmailPrefix, localAuthCode
- callback.go: GetProviders, AuthProvidersHandler, CallbackHandler, GetUserInfo, ExchangeCode, writeOauthError, oauthErrorCode, idpClient, claimProvider, tokenProvider, localUser, localUserInfo
- cookies.go: RemoveCookieHandler, setAuthCookie, resetAuthCookie
- tenant.go: SelectOrg, selectOrgToken, AuthOrgHandler, omitCookieAccessToken, initialOrg, selectOrg, setOrgClaims
- userinfo.go: UserinfoHandler, GetUserToken, Caller, RevokeToken, RevokeTokenHandler, GetAllowedMethods, GetCallerScope
Invariants:
- OAuth state is protected with dataprotection (Protect/Unprotect); DPoP-bound logins get the DPoP audience. The callback answers in the requested response mode: query, fragment or form_post. A failure after the state is decoded (an IdP error, an expired state, the code exchange, the user info, the email check, the login) lands on the redirect URI of the client in that mode with
erroranderror_description(writeOauthError, pb.OAuthParamError and the pb.OAuthError* codes of RFC 6749 section 4.1.2.1): an error that carries one of those codes keeps it, any other is mapped by its HTTP status (401 and 403 access_denied, 503 temporarily_unavailable, other 5xx server_error, else invalid_request); a server-side failure is described by its status text only, and the cause is logged (reasonlogin_failed). Without a decoded state the redirect URI is unknown, and the error is JSON on the API host. GetUserInfo answers a user it cannot sign in (no verified email, no name) PermissionDenied and a failed call to the IdP Unavailable, with the answer of the IdP in the cause only; every call to an IdP (exchange, user info, GitHub emails) takes the request context and idpClient (10 s timeout). - A login selects the first accessible org, or creates the configured default org and project for a user without grants (initialOrg). Tokens carry the selected org, the resolved role for display and scopes; permissions come from authctx at request time. The
providerclaim (claimProvider) is the name of the pb.IDP_Enum value of the login; tokenProvider reads it with pb.IDPFromString, which also takes the number older tokens carry, forToken.Providerof SelectOrg and GetUserToken. An API key token hasapikeythere, and AuthenticateAPIKey answers Provider Undefined. - The
localprovider exists only whereconfig.Service.IsLocalholds andoauth2_clientslistslocal: AuthorizeHandler and handleToken refuse it elsewhere (unsupported IDP,unsupported provider). It has no IdP: AuthorizeHandler redirects to the callback on the public host of the authorize request (?code=local), never to the configured auth_url, so the cookies of a cookie session are set for that host. AuthProviderForEmail maps an address withlocal+to it, with no invitation; elsewherelocal+is part of an ordinary address. The flow signs in the address without the prefix (localUserInfo: the email is the login's external ID, the name its local part), or localUser without one. - Cookie session (
response_type=cookie): the callback sets the auth cookie (the token, HttpOnly) and the CSRF cookie (32 random characters, readable by a script), both Secure, SameSite=None, Path=/, onidentity_map.cookies.domain, until the token expires withremember_me, else for the browser session, and lands on the redirect URI withcookie_set=true&csrf=<CSRF cookie name>&expires_in, never the token. porto maps the cookie to the identity (MethodJWTCookie) only with the CSRF double submit: theX-CSRF-Tokenheader (x-csrf-tokenmetadata) equal to the CSRF cookie on every gRPC and gRPC-Web call and on unsafe REST methods; otherwise the caller is a guest, never an error. GetUserToken, SelectOrg and AuthOrgHandler omit AccessToken for a cookie session (omitCookieAccessToken). - SelectOrg (gRPC,
POST /pb.Auth/SelectOrg) returns a new token with the original expiry and cannot set a cookie; AuthOrgHandler (POST /v1/auth/org, pb.PathForAuthOrg) runs the same selectOrgToken and, for a cookie session without an Authorization header, writes the token into the auth cookie with a new CSRF cookie (persistent with RememberMe), so the console re-reads the CSRF cookie after it. A caller with Authorization gets the token and keeps its cookies. - RevokeToken refuses a caller without a token (Unauthenticated
no token to revoke), answers Unimplemented without a revocation, and records UserSignedOut, or TokenRevoked for an API key token. RevokeTokenHandler (DELETE/pb.Auth/RevokeTokenonly: a GET would sign a cookie session out without the CSRF check) removes both cookies first, whatever the outcome, and writes the sanitized error of revoke. RemoveCookieHandler (DELETE /v1/auth/removecookie, skip_auth) removes them without revoking. - No route renders a token: a client receives it on its own redirect URI (the CLI with
response_mode=fragmenton/authenticated). - Events (internal/events, source
auth): the callback records UserSignup for a new user's first login (LoginUser returns the login and user with one ID), OrgMemberAccepted / ProjectMemberAccepted for each accepted invite, OrgCreated and ProjectCreated for the default org and project (initialOrg), and UserSignedIn once the token is issued; selectOrgToken records UserSignedIn in the org; RevokeToken records UserSignedOut, or TokenRevoked for an API key token; AuthenticateAPIKey records APIKeyLogin after it signs the token.
Tests: auth_service_test.go TestMain starts one auth service over the configured database and Redis, with the cookies of the dev wfe (testCookies), and exposes its DB, data protection and configuration as testDb, testDp and testCfg. A test that changes its BaseURL or testCfg, registers a provider with SetAuthProvider or replaces the parser's revocation is not parallel. local_test.go drives the local provider through AuthorizeHandler and CallbackHandler on the cookie-domain host (token and cookie modes) and its refusal outside a local instance, which lands on the redirect URI; callback_test.go covers GetUserInfo and the error redirects of the callback in the three response modes (TestCallbackHandler_ErrorRedirect), callback_internal_test.go the OAuth code of an error and the description of a server-side failure; session_test.go covers the cookie session: AuthOrgHandler (cookie, browser-session cookie, bearer, refusals), SelectOrg, the sign-out against the container's revocation, the cookies of RevokeTokenHandler and RemoveCookieHandler and the routes. events_test.go reads the recorded events back with ListEvents under require.Eventually, since TryCreateEvent writes in the background; its OAuth stub signs in the email passed as the code, as the GitLab provider. The container suite of tests/integration runs the same flows against the service image.
server/service/ca
pb.CA, the CA API of the tenants on the wfe: the org of a request is the org of the token, and the requests carry no OrgID. A proxy of the backend service (DESIGN.md section 2.1).
- doc.go: package overview and a wiring example
- ca_service.go: ServiceName, Service, Factory, New, RegisterGRPC
- forward.go: every pb.CA method, forward, counterpart, backendServer, forwardedError
Invariant: Service holds no registry, loads no crypto provider and reads no CA table: its Factory takes the client.Factory and builds a shared.BackendLocator over the server's discovery and the ca service client (config.BackendServerName). Every method encodes the public request, decodes it into its privpb counterpart (the same fields under the same numbers, OrgID as field 1, which the public request reserves), sets OrgID to the org of the caller's token (authctx.FromContext), clears unknown fields, and calls the privpb.Backend method of the same name with the caller's context, so a value the caller encodes in field 1 never reaches the backend; SignOCSP sends pb.OCSPRequest as is, and a nil request stays nil. Without a locator every method is Unavailable CA is not configured, with a backend that cannot be reached Unavailable CA is not available; a FailedPrecondition from a remote backend is HTTP 409 conflict again (forwardedError), since porto converts it to 400. Tests: forward_test.go checks every pair of requests (TestRequests_Counterparts: names, numbers, kinds, OrgID and the reserved field), calls every method with every field set over a gRPC backend that records the requests and the forwarded context (TestService_Forward), the org of the token against field 1, a nil request and the errors; forward_e2e_test.go (TestService_ForwardOverMTLS, package ca_test, not parallel) runs the Service of a web process against the backend listener of the dev configuration on its own port over mTLS: the ca client (trustyca-peer) forwards an Owner, whose root, refusal (409) and signature the backend authorizes with the DB grants and records with the Owner as the event actor, a user without a role is refused, and the aia client reaches SignOCSP and not SignCertificate.
server/service/backend
privpb.Backend, the CA of the service identities and the signing plane (DESIGN.md section 2.1): every method of pb.CA with the org of the request named explicitly. Imports internal/ca as core.
- doc.go: package overview and an example
- backend_service.go: ServiceName, Service, Factory, New, RegisterGRPC, requireCA
- signer.go: SignCertificate, SignOCSP, resolve, ocspIssuer, requestPEM, subjectOf, isSignRequestError
- issuer.go: RegisterIssuer, ImportIssuer, ActivateIssuer, UpdateIssuer, GetIssuer, ListIssuers, parentIssuer, caProfile, issuerError, registerIssuer, issuerTransitions
- profile.go: RegisterProfile, GetProfile, ListProfiles, DeleteProfile, invalidateProfile
- root.go: RegisterRoot, ListRoots
- cert.go: GetCertificate, ListCertificates, UpdateCertificateLabel, RevokeCertificate, ListRevokedCertificates, certificateSelector, findCertificate, certificateBySKID
- crl.go: GetCRL, PublishCrls
- scope.go: tenantScope, newTenantScope, Org, Project, RequestProject, RowAccess, ListProjects, Issuer, VisibleIssuer, IssuerByLabel, Profile, ProfileByLabel
- request.go: EventSource, preconditionFailed, parseID, parseTime, issuerPb
- list.go: listCursor, listLimit
Invariant: The Factory takes *ca.Registry (so a process that lists the service builds the registry, loads the crypto providers and runs the bootstrap) and builds the core.CrlPublisher over it and the CA DB; the methods that sign or change an issuer fail with Unavailable without the registry (requireCA). Discovery finds it by privpb.BackendServer, which the proxy CA service does not implement. Its methods run as their caller: the caller of the CA service in the same process, the caller the backend interceptor builds from a forwarded context, or the service identity that calls it (the RA and the operator name the org; the AIA calls SignOCSP); they record their events with the source ca (EventSource). Every issuer and profile mutation runs here and drops the entries of the issuer registry at once (another backend instance sees it after ca.issuer_cache_ttl). tenantScope reads the CA tables and the orgs only (db.CaReadonlyDb, db.OrgsReadonlyDb) and the Authorizer.
The authorization of the CA methods: the org of a request is the token's, and an explicit OrgID (the one the CA service sets from the token) must match it; a trusted service caller (trustyca-* role, no org in its identity) names the org explicitly and tenantScope.Org verifies it through db.OrgsDb (an inactive org is preconditionFailed); a project is verified with authorizer.Project and reported as not found when it is another org's or inactive; a row of another org or of the platform read by ID, label or IKID is not found. The interceptor authorizes the scope the request names, so a row resolved by ID, IKID, thumbprint, SKID or issuer and serial (GetIssuer, GetProfile, UpdateIssuer, ActivateIssuer, DeleteProfile, GetCertificate, UpdateCertificateLabel, RevokeCertificate, GetCRL) is authorized again against its own project with tenantScope.RowAccess, using the method's allowed roles from pb.GetMethodInfo: a trusted service caller passes; an API key must be org-wide or restricted to that project, and a key restricted to a project reads an org-wide row as the derived org Viewer but may not change it (only a method that allows Viewer passes); a user needs a role at the row's project (an org-wide role is inherited, an org-wide row needs the role at the org, which a member with project grants only holds as Viewer); a project the caller cannot read is not found, one it can read but not act on is PermissionDenied. A list without a project (ListIssuers, ListProfiles, ListCertificates, ListRevokedCertificates) covers the org-wide rows and the projects of the caller's grants for a member with project grants only (tenantScope.ListProjects, query ProjectIDs); an org-wide role, a service caller and an org-wide API key list every project. SignCertificate resolves the issuer and profile with Registry.Resolve in the scope of the request and maps its errors: profile or issuer not found are NotFound, a required or mismatched issuer label and a profile the issuer does not allow are InvalidArgument, an issuer that is not Active is preconditionFailed, an issuer that does not load is Internal; it signs with the versioned profile name of the resolution, registers the certificate and its CertificateIssued event in one transaction (db.RegisterCertificate with the event), maps a signing error the request causes (isSignRequestError markers) to InvalidArgument and a unique*certificate violation to AlreadyExists (HTTP 409 conflict). SignOCSP finds the issuer with IssuerByKeyHash or IssuerByNameHash and answers good for a registered certificate, revoked with the reason and time from GetRevoked (by certificate ID), unknown for a serial the issuer never registered, and Internal when a Revoked certificate has no revocation row. RegisterIssuer validates the request before it touches a key provider (a Root with a ParentID is InvalidArgument: a Root is self-signed), resolves the parent (an Active issuer visible from the scope of the new issuer, org-wide or of the same project, or a platform issuer whose AllowedProfiles name the profile, PermissionDenied otherwise; an issuer of another org or project is not found) with its CA profile in the parent's scope (caProfile converts the registry's row with core.AuthorityProfile, never Pb), builds the row with internal/ca (root, signed or pending), registers it, with the anchor of a root in the same transaction (RegisterIssuer with the anchor: an anchor that cannot be written fails the request and stores nothing), and invalidates the registry; unique violations and an anchor registered in another scope (ErrRootConflict) are AlreadyExists. UpdateIssuer allows Active to Archived and Archived to Destroyed only, destroys a provider key best effort, and invalidates the registry; ActivateIssuer requires Pending; RegisterProfile validates with ProfileFromPb and invalidates the profile label; every mutation emits its event through db.OrgsDb. ListRoots serves the platform anchors to a service caller that names no org. The certificate methods resolve the row with findCertificate (certificateSelector: ID, issuer and serial, thumbprint, or SKID, in that precedence; a certificate of another org or of the platform is not found) and GetCertificate by SKID returns the newest certificate of the key among the org-wide rows and the projects the caller may read (certificateBySKID lists with ProjectIDs and the project of a restricted API key), since a renewed key keeps its SKID. UpdateCertificateLabel and RevokeCertificate take an optional ProjectID, the scope the interceptor authorizes for a member whose role is granted in the project only (tenantScope.RequestProject verifies it like tenantScope.Project without the API key default); the certificate must belong to it, else not found. UpdateCertificateLabel always replaces the label and replaces the metadata only when the request carries a map (an empty map clears it; a gRPC client cannot send an empty map, so it clears through JSON only); it records no event, because EventType has none for it, and logs the change. RevokeCertificate validates the reason against ReasonCode and refuses RemoveFromCRL (hold removal is not a revocation), refuses a Revoked row and db.ErrAlreadyRevoked with preconditionFailed (HTTP 409), writes the revocation and the status in the one transaction of db.RevokeCertificate, and records CertificateRevoked (referencing the certificate) after it, so a failed revocation records nothing. GetCRL reads by IKID: a tenant gets the CRLs of its org, authorized against the CRL's project with tenantScope.RowAccess (a platform CRL is not found: CIS serves it), and a trusted service caller that names no org gets any CRL. PublishCrls (Admin,Security,APIKey with ca:write: the interceptor authorizes a project Admin and a restricted API key at the ProjectID of the request, TestService_PublishCrls_CheckAccess) publishes through core.CrlPublisher: with an IKID, the one issuer, found by SKID, not found when the request names another project than the issuer's (tenantScope.RequestProject) and authorized with tenantScope.VisibleIssuer (another org's or a platform issuer is not found for a tenant), refused with preconditionFailed when it is not Active or Archived (issuer is pending) or its certificate has expired (core.ErrIssuerExpired), published when due or forced; without, the Active and Archived issuers of the project of the request or of a restricted API key (tenantScope.Project), else of the org-wide scope and the projects of tenantScope.ListProjects, and for a trusted service caller that names no org and no project every org and the platform (as the crl_renewal task). Every published CRL records CrlPublished (referencing the CRL row, which keeps its ID across publishes) before the response; a scope run with failed issuers, or whose listing failed after some CRLs were published, records those events first, since a retry finds those CRLs fresh, then fails with Internal (the count of failed issuers, or failed to publish CRLs), so the published CRLs are only visible through GetCRL.
Tests: they call the Service with the privpb requests. They build the CA through internal/ca with the inmem provider over a gomock CaDb whose reads serve in-memory rows (caRows) and whose mutations each test expects (service_test.go); tca.service() is the Service over that CA and tca.noCA() one without a registry (the key methods are Unavailable); the fake authorizer grants user 42 an org-wide Admin, 77 a Viewer and 78 an Admin of project 201 only, and apiKeyCtx makes an API key token; the package-level org ID of the tests is a function and caRows re-creates the scope IDs of a stored row (ownID), because parallel tests must not share an xdb.ID; TestService_SignCertificate_Concurrent signs from many goroutines under the race detector; bench_test.go measures SignCertificate and SignOCSP. cert_test.go serves the certificate reads and mutations from an in-memory certStore that each test registers on the mock (newTestCA registers none, so a test may still expect exact calls), and TestService_CertificateMutations_CheckAccess runs authctx.CheckAccess on the two mutations with and without ProjectID; crl_test.go does the same with a crlStore (CRLs, revocations, ListIssuers over caRows) and verifies the published CRLs with x509.ParseRevocationList; TestService_SignOCSP_Delegated covers an issuer with a delegated OCSP profile. e2e_test.go (package ca_test, not parallel) builds the app container over the configured DB under the data protection seed of the environment (testutils.SetDataProtectionSeed), starts the CA and backend services with gserver.Start (the CA finds the backend through discovery) and calls the CA over a bufconn gRPC connection whose interceptor sets a trustyca-ra identity: the bootstrap trusty.svc issuer signs OCSP for the dev client certificate (unknown), and a new org registers a root with a key in the default (KMS emulator) provider, signs, reads, lists, relabels and revokes a certificate, checks OCSP, publishes and reads the CRL of the root (signature, number, the revoked entry, the number after a forced publish); the test destroys the key through UpdateIssuer and deletes its rows, and the CRL follows the issuer.
server/service/shared
Helpers that several services use.
- doc.go: package overview and an example
- backend.go: BackendLocator, NewBackendLocator, NewStaticBackendLocator
Invariant: BackendLocator returns the backend of the CA and AIA services on the first call, under its lock: the backend service of the process when discovery finds a privpb.BackendServer (on any listener; the proxy CA service takes the public requests and is not one), called directly, else a client of the backend listener with the named service client. A failure is returned and the next call tries again; Close closes a remote client and the next call dials again (backend_test.go covers both, and concurrent lookups under the race detector).
server/service/cis
pb.CIS: the read-only certificate information service for authenticated callers (DESIGN.md section 9.3): trust anchors, issuer chains, certificate information, revocation status and CRLs, over gRPC and the JSON API of the wfe listener. Imports internal/ca/pbconv for the URL templates. The binary AIA, CRL and OCSP routes are server/service/aia.
- doc.go: package overview and a wiring example
- cis_service.go: ServiceName, Service, Factory, New, CisHTTPHandler, RegisterRoute, RegisterGRPC
- cis.go: GetRoots, GetIssuer, GetCertificate, GetCertificateStatus, GetCRL, issuedIssuer, findCertificate, certificateBySKID, publicCertificate, publicCrl
Invariants:
- The service reads
db.CaReadonlyDbonly, holds no issuer keys, calls no other service and needs no configuration (New(caDb); the Factory takes the CA DB from the container). Every lookup is by IKID, ID, SKID, thumbprint or issuer and serial, across every org and the platform: nothing of an org is listed but its trust anchors (GetRootstakes its ownGetRootsRequest, whoseOrgIDis a lookup of public anchors, not a tenant scope; without one, the platform anchors). There is no per-method access check (CisHTTPHandlerpasses nil, the methods declare no roles): the views carry no tenancy or client-owned fields (publicCertificateclears OrgID, ProjectID, Profile, Label and Metadata;publicCrlclears OrgID), and the listener decides who reaches the service, which on the wfe is any authenticated role (authz.allow_any_role: /pb.CIS, no CIS path underidentity_map.skip_auth), so a guest is refused before the handler. A Pending issuer, which has no certificate, is not found (issuedIssuer);GetIssuerexpands the AIA, CRL and OCSP templates of the issuer with its SKID (pbconv.ExpandIssuerURL);GetCertificateby SKID is the newest certificate of the key of any org (ListCertificateswithAllOrgs, limit 1);GetCertificateStatusreports an Active row whose validity has ended as Expired before thecert_statustask marks it, and a Revoked row without its revocation as Internal, likeSignOCSP. - Tests (
cis_test, service_test.go):newTestEnvbuilds the service withNewover a gomockCaReadonlyDbwhose reads serve atestStore(issuers with settings, a Pending issuer, a row whose settings do not parse, a CRL signed withx509.CreateRevocationList, Active, expired and revoked certificates, platform and org anchors, a failure that every read returns); the routes run throughrestserver.NewRouter. cis_test.go covers the JSON methods and the Factory, rest_test.go the JSON API throughhttppb(TestRoutes) and that the binary routes are not registered. e2e_test.go (not parallel) builds the app container over the configured DB under the data protection seed of the environment, starts the backend service and the CIS over HTTP with its Factory, registers a root whose URL templates name an AIA listener, signs, revokes and publishes through a bufconn privpb.Backend client astrustyca-ra, and reads the issuer with its expanded URLs, the certificate, its status, the CRL and the anchors back through the JSON API.
server/service/orgs
pb.Orgs: orgs, projects, members, invites and API keys of the org selected in the token.
- apikey.go: CreateAPIKey, ListAPIKeys, DeleteAPIKey
- members.go: GetUserOrgs, GetUserMemberships, GetMembers, AddMember, ChangeMemberRole, DeleteMember, DeleteInvite, checkLastOwner
- org.go: tokenOrg, preconditionFailed, RegisterOrg, GetOrg, UpdateOrg, DeleteOrg
- orgs_service.go: Service, Factory, OrgsHTTPHandler, RegisterRoute
- projects.go: parseOptionalID, getActiveOrg, getProject, RegisterProject, UpdateProject, GetProject, ListProjects, DeleteProject
Invariants:
- Tenant operations take the org from the token (tokenOrg) and validate project scope with the Authorizer; a project of another org is not_found.
- Grants follow authctx.Grants.CanGrantOrgRole / CanGrantProjectRole; an org always keeps an org-wide Owner (checkLastOwner). Every membership mutation invalidates the user's cached grants.
- A refusal the org's state causes (deleted org, last Owner) is preconditionFailed: HTTP 409
conflictwith the message, gRPC FailedPrecondition. Do not use NewGrpcFromCtx with FailedPrecondition: the pinned porto maps it to HTTP 400bad_request. Return the error unwrapped: httperror.Wrap with a message rebuilds it from its code. A Go client of the gRPC API (proxypb, httperror.NewFromPb) still sees a 400. - DeleteProject deactivates the project; memberships and invites are kept.
- Every successful org, project, member, invite and API key mutation records one event (internal/events, source
orgs) after the DB call; a refused or failed call records none. DeleteInvite has no event type and records nothing.
Tests: service tests use the fakeAuthorizer and fixtures in authorizer_test.go with mocktrustycadb; events_test.go captures the emitted events from the mock (recordEvents) and checks each one field by field (requireEvent, requireNone). precondition_test.go checks the 409/FailedPrecondition contract over REST and gRPC.
server/service/status
Build version, health and readiness endpoints.
- status_grpc.go: Version, Server
- status_http.go: version, serverStatus, nodeStatus
- status_service.go: Service, Factory, RegisterRoute
Invariant: Factory registers public status routes and gRPC; /pb.Status is allowed to any caller.
server/service/ui
Embedded UI pages.
- pages.go: PageHandler
- ui_service.go: Service, Factory, New, RegisterRoute
Invariant: pages.go serves the templated pages of static/ (login, authenticated, payment); authenticated.html reads the token from the fragment or query and removes it from the browser history.
server/tasks
Scheduled task factories selected by configuration.
- doc.go: package overview and the configuration shape
- tasks.go: Status, Factory, Factories
Invariant: Factories maps the task names of the tasks: configuration (crl_renewal, cert_status) to their factories; a Factory returns the function App.scheduleTasks invokes through the container, so the parameters of that function are the dependencies of the task. Scheduling uses porto/pkg/tasks, which recovers a panic of a run and never runs a task concurrently with itself; both tasks run once when scheduled (go t.Run()), then on their schedule. Status is unused.
server/tasks/crlrenewal
The crl_renewal task: the due CRLs of every org and the platform.
- doc.go: package overview and the configuration
- crlrenewal.go: TaskName, Task, New, Task.Run, Factory
Invariant: Run publishes with core.CrlPublisher (PublishCrlsRequest{AllOrgs: true}) under a new correlation ID, records a CrlPublished event per published CRL with the task name as the source and no actor, logs the counts at INFO once per run, and returns the listing error after the events. Factory needs db.CaDb, db.OrgsDb (events) and *core.Registry from the container, so the task belongs to a process that holds the issuer keys (the signing pod of DESIGN.md section 2.2): scheduling it builds the registry and loads the crypto providers; an invalid schedule fails the start. Tests build a root issuer with the inmem provider behind a gomock CaDb and run the factory under a real scheduler.
server/tasks/certstatus
The cert_status task: expiry and retention of certificates.
- doc.go: package overview and the configuration
- certstatus.go: TaskName, BatchSize, MaxBatches, Task, Result, New, Task.Run, Factory
Invariant: Run marks the Active certificates expired before now (db.ExpireCertificates) and, when ca.retention.expired_after is set, deletes the certificates expired before now minus it (db.DeleteExpiredCertificates), in batches of BatchSize repeated until a batch is not full and at most MaxBatches per run (a WARNING when the bound stops a run; the next run continues); a DB failure is logged and returned with the counts so far. Factory needs *config.Configuration and db.CaDb from the container.
tests/mockappcontainer
Dependency containers with injected values for service tests.
- builder.go: Builder, NewBuilder, Container, WithConfig, WithJwtSigner, WithJwtParser, WithDiscovery
tests/load
The load test of the CA tables (go run ./tests/load): a disposable database, synthetic certificate and revocation rows copied in batches, every query of the CA at that volume through the provider and through EXPLAIN (ANALYZE, BUFFERS), and the insert of SignCertificate with its event, as percentiles.
- doc.go: command overview
- main.go: options, run, ensureDatabase, dropDatabase, synthetic, load, copyBatch, sizes, explain, signBench, report
Invariant: The rows reuse one PEM (the queries never read it; the row width matters), the big org holds -big-org-share of the rows, every key signs three certificates, every Nth certificate is revoked, and the IDs grow as flake IDs do. The explained statements of the status task run in a transaction that is rolled back. The tool never touches trustycadb.
tests/integration
The container integration tests (not a Go package): the service image in a
compose stack with PostgreSQL, Redis and the KMS emulator, driven by the
trustyca CLI and by curl playing the browser and the console. See
tests/integration/README.md.
- setup.sh: issues the PKI of the stack under the checked-in dev root into
.citest/certs(gitignored;~/.trustyca/certsis never touched), starts the stack, creates the database, runs the suite, dumps the service log on failure, tears down unless ITEST_KEEP_UP - docker-compose.tester.yml: sql, sql-init, redis, kms, trustyca (alias api.local.trustyca.io, under the dev cookie domain; HOME=/home/nonroot with the PKI on ~/.trustyca/certs, so the TLS paths of the base config resolve;
--cfg-overrideetc/dev/trustyca-config.citest.yaml), test-runner - tests/run.sh: SUITE (test_status.sh, test_auth.sh, test_cookies.sh), sourced in order into one shell
- tests/lib.sh: assertions; login, trustyca_as, trustyca_anon (the CLI, bearer sessions, one storage per user); browser_login, console_rest, console_grpcweb, cookie_value, header_of, set_cookie_of (the console in cookie mode, one cookie jar per user)
- tests/browser/xdg-open: follows the redirects of
trustyca auth loginand posts its form_post page to the CLI listener
Invariant: users sign in through the local provider (local+<user>@trustyca.io), the way a person does, never with minted tokens. test_cookies.sh is the contract of the cookie session the console relies on: CORS of the console origin (a preflight with the headers sorted, gRPC-Web, REST), the cookie attributes, the CSRF double submit over gRPC-Web and REST (a guest is Unauthenticated: gRPC 16, HTTP 401), the org switch that replaces the cookies, and the sign-out that revokes the token.
tests/testutils
Development test configuration, request builders, JSON and golden output assertions.
- certs.go: TestCA, NewTestCA, TestCA.Issue, TestCA.ChainPEM, TestCA.Root, CertPEM
- golden.go: CheckGolden, GoldenEntry, UniqueGoldenName, GoldenUpdateEnv
- httprequest.go: CreateRequest
- populate.go: PopulateObject
- testutils.go: DataProtectionSeedEnv, DefaultDataProtectionSeed, SetDataProtectionSeed, LoadConfig, ResolveConfigFile, CreateURL, CreateURLs, CreateBindAddr, JSON, CompareJSON
Invariant: Config paths resolve against repository fixtures (etc/dev). SetDataProtectionSeed pins TRUSTYCA_DP_SEED for a test that builds the app container against the dev DB: the environment's seed, else testseed, the rule of the Makefile, so that the test, make and a server started from the same shell or IDE wrap and unwrap the platform issuer key under one seed (t.Setenv: the test is not parallel). JSON and JSONIndent intentionally swallow marshal errors; CompareJSON uses testing assertions. CreateURL, CreateURLs and CreateBindAddr never hand out one port twice in a process (a mutex-guarded set); they cannot reserve it at the OS. CheckGolden compares captured output with a golden file and writes it only with TRUSTYCA_UPDATE_GOLDEN=1 and a passing suite, refusing an output line that reads as an entry header; a run filtered with -run, -skip or -testify.m ignores, and on update keeps, the entries it did not capture.
Build, test and CI
- Go 1.27 (
go.mod).make toolsinstalls the lint, coverage, docs, PKI, schema, migrate and mock tools listed inMakefile. mocks/andapi/version/current.goare gitignored: runmake generate versionon a fresh checkout before building or testing.make buildbuildstrustyca,trustycactl,trustycasvc.make generaterunsgo generate ./...(gomock);make protogenerates public and private protobuf artifacts in Docker; runmake proto generatewhen mocks or service interfaces depend on the change.- Local fixtures:
make folders gen_test_certs start-localstack(the server and peer certificates nameTEST_CERTS_SAN, 127.0.0.1 and api.local.trustyca.io;--forcerotates the dev CA keys, so add a certificate with.project/gen_certs.shand its flag alone), thenmake drop-sql start-sqlonly for a disposable local database. The compose stack (docker-compose.trustyca.yml) supplies PostgreSQL, Redis, LocalStack and KMS; tests loadetc/dev/trustyca-config.unittest.yaml.make teststarts nothing. make testruns the tests;make testshortpasses--test.short, but package setup can still need the local stack.make test RACE=trueenables the race detector.make lintruns formatting and golangci-lint (.golangci.yml, which excludes SA1019);CI=trueskips staticcheck/unused.make vulnsruns govulncheck (install it first).make covtestwrites per-package coverage andcoverage.out;make coverageopens the HTML report (.project/gomod-project.mk)..github/workflows/build.ymlprepares generators, builds binaries and starts fixtures. Pushes runmake test; PRs runmake covtestand publish a coverage status againstMIN_TESTCOV, which the workflow does not set yet; both runmake docker-citest. Lint and race checks are local.make docker-citestbuilds the images (make docker-build docker docker-tester: the binaries link the PKCS#11 provider with cgo, so docker-build compiles them ingolang:<go.mod version>-trixiefrom the host module cache, read-only and offline, and theDockerfileruns them on Debian trixie:distroless/base-debian13for the service,debian:trixie-slimfor the test runner) and runs tests/integration in a compose stack of its own, with its own PKI and database.make docsregeneratesDocumentation/api/andDocumentation/cli/; build the CLI binaries first.go run ./tests/load -rows N -load -explain -sign 2000fills a disposable database (trustycadb_load, created with the superuser of the dev container) with synthetic certificates and prints the plans and timings of the CA queries;-dropremoves it. Documentation/perf/load-certificates.md keeps the last 10M-row run.- A
.VERSIONchange pushed to main creates a<.VERSION>.<commit count>tag throughbuild.yml.