📄️ gRPC API overview
This document summarizes the gRPC API of the zero-trust control plane: a single gRPC server, all services and their main RPCs, and how callers use it (backend in-process, frontend via Next.js API routes). For auth, sessions, policy, and other topics, see the linked backend docs.
📄️ Auth
This document describes the authentication implementation for the zero-trust control plane backend: architecture, API surface, security measures, flows, and configuration. The canonical proto is internal/proto/auth/auth.proto; business logic lives in internal/identity/service/authservice.go; the gRPC server is implemented in internal/identity/handler/grpc.go.
📄️ Audit
This document describes the audit logging system for the zero-trust control plane backend: purpose, what is logged, how to query, and behavior. The canonical proto is proto/audit/audit.proto; the write path is implemented in internal/server/interceptors/audit.go; the read path is in internal/audit/handler/grpc.go. For interceptor order and identity in context, see auth.md. For the audit_logs table and schema, see database.md.
📄️ Database
This document describes the current PostgreSQL schema for the zero-trust control plane backend. The canonical schema is maintained in internal/db/sqlc/schema/001schema.sql and applied via internal/db/migrations/. For MFA and device-trust behavior (when MFA is required, policy evaluation, OTP flow), see mfa.md and device-trust.md.
📄️ Device Trust
This document describes device-trust logic in the zero-trust control plane backend: how devices are identifiable, revocable, and time-bound; policy evaluation (OPA/Rego) that decides when MFA is required and when to register or refresh trust; and configuration. For MFA flows (Login MFA branch, Refresh MFA branch, VerifyMFA, challenge/OTP, API), see mfa.md. Business logic lives in internal/identity/service/authservice.go; policy evaluation is in internal/policy/engine/.
📄️ Health
The backend exposes a readiness health check via the gRPC HealthService.HealthCheck RPC. It is used by Kubernetes, load balancers, and CI to determine whether the server is ready to accept traffic.
📄️ MFA
This document describes the risk-based MFA logic in the zero-trust control plane backend: when MFA is required, MFA challenge and OTP flow, API surface, and configuration. Device trust (identifiable, revocable, time-bound) influences whether MFA is required; see device-trust.md. The canonical proto for auth is proto/auth/auth.proto; business logic lives in internal/identity/service/authservice.go.
📄️ Org Policy Config
This document describes the OrgPolicyConfigService: per-org structured policy configuration with five sections, Get/Update API, storage in orgpolicyconfig, and sync of Auth & MFA and Device Trust sections to orgmfasettings. The canonical proto is orgpolicyconfig/orgpolicyconfig.proto; the handler is internal/orgpolicyconfig/handler/grpc.go.
📄️ Organization and membership
This document describes organizations (tenants) and membership (users in orgs with roles): OrganizationService and MembershipService, protos, handlers, and how they relate to the dashboard and RBAC. For auth and session behavior, see auth and sessions.
📄️ Policy engine
This document describes the policy engine in the zero-trust control plane backend: OPA/Rego integration, policy structure (database, domain, API, Rego contract), default policy, and the full evaluation flow. The policy engine is used only for device-trust / MFA decisions (when to require MFA, whether to register trust after MFA, and trust TTL in days). For device-trust semantics and MFA flows, see device-trust.md and mfa.md.
📄️ Sessions
This document describes the SessionService: listing and revoking sessions for an organization, and how revocation invalidates both refresh and access tokens. The canonical proto is session/session.proto; the handler is internal/session/handler/grpc.go.
📄️ Session lifecycle
This document describes the session lifecycle in the zero-trust control plane: when and how sessions are created, how heartbeats (lastseenat) work, how sessions end (revocation), and how clients behave (proactive refresh, 401 handling, logout). For SessionService RPCs and token invalidation details, see sessions.md.
📄️ Telemetry
The telemetry system provides observability for the gRPC API and custom application events: traces for request flow and latency, metrics for rates and duration, and logs for explicit events emitted via the TelemetryService. All signals are produced by the gRPC server using the OpenTelemetry SDK, exported over OTLP to an OpenTelemetry Collector, which fans out to Loki (logs), Prometheus (metrics), and Tempo (traces) for querying and dashboards in Grafana.
📄️ Testing
This document describes the comprehensive test suite for the zero-trust control plane backend. All tests use Go's standard testing package and follow consistent patterns for mocking dependencies and testing both success and error scenarios.