Class ServerRealmContext

java.lang.Object
zeroecho.pki.server.ServerRealmContext
All Implemented Interfaces:
AutoCloseable
public final class ServerRealmContext extends Object implements AutoCloseable
Lifecycle owner for one server realm, one long-lived PKI session, and one dedicated durable server-control authority.

The context is transport-neutral and synchronous. It creates no execution lane, queue, thread, scheduler, retry loop, HTTP type, or ACME object. A future transport can retain one instance for its process lifetime and submit existing typed operations through gateway().

  • Method Details

    • open

      public static ServerRealmContext open(ServerRealmConfiguration configuration, PkiSessionRuntimeDependencies dependencies)
      Opens one production realm using explicit process-local capabilities.
      Parameters:
      configuration - validated immutable realm configuration
      dependencies - key-access capabilities, never secret values
      Returns:
      fully recovered realm context
      Throws:
      IllegalArgumentException - if a restore coordinator exists and server-control storage is nested inside the replaceable PKI root

    • enrollmentRuntime

      public Optional<EnrollmentRuntime> enrollmentRuntime()
      Returns explicitly installed enrollment custody and resource limits.
      Returns:
      empty when the server has no enrollment companion

    • enrollmentCoordinator

      public Optional<EnrollmentCoordinator> enrollmentCoordinator()
      Returns the coordinator installed for this realm's enrollment services.
      Returns:
      installed durable coordinator, empty for deployments without enrollment

    • backupTransferConfiguration

      public Optional<BackupTransferConfiguration> backupTransferConfiguration()
      Returns explicitly installed binary transfer settings.
      Returns:
      empty when remote backup transfer is disabled

    • configuration

      public ServerRealmConfiguration configuration()
      Returns exact realm configuration without rendering provider values.
      Returns:
      exact realm configuration without rendering provider values

    • session

      public PkiSession session()
      Returns the one long-lived PKI session.
      Returns:
      the one long-lived PKI session

    • roleTemplates

      public RoleTemplateCatalog roleTemplates()
      Returns immutable built-in role template catalog.
      Returns:
      immutable built-in role template catalog

    • authorization

      public AuthorizationEngine authorization()
      Returns deterministic authorization engine.
      Returns:
      deterministic authorization engine

    • approvals

      public ApprovalService approvals()
      Returns durable approval service.
      Returns:
      durable approval service

    • breakGlass

      public BreakGlassService breakGlass()
      Returns durable break-glass service.
      Returns:
      durable break-glass service

    • disclosure

      public DisclosureService disclosure()
      Returns durable disclosure decision service.
      Returns:
      durable disclosure decision service

    • credentialPublication

      public CredentialPublicationGate credentialPublication()
      Returns synchronous authoritative credential publication gate.
      Returns:
      synchronous authoritative credential publication gate

    • repositoryAliases

      public RepositoryAliasService repositoryAliases()
      Returns durable non-authoritative public repository alias service.
      Returns:
      durable non-authoritative public repository alias service

    • acmeControl

      public AcmeControlStore acmeControl()
      Returns typed ACME records in the realm's sole durable control authority.
      Returns:
      typed ACME records in the realm's sole durable control authority

    • ocspResponders

      public OcspResponderService ocspResponders()
      Returns durable exact OCSP responder bindings.
      Returns:
      durable exact OCSP responder bindings

    • publicRepository

      public PublicRepositoryGateway publicRepository()
      Returns read-only disclosed public repository gateway.
      Returns:
      read-only disclosed public repository gateway

    • auditorViews

      public AuditorViews auditorViews()
      Returns explicit auditor projection service.
      Returns:
      explicit auditor projection service

    • gateway

      public ServerOperationGateway gateway()
      Returns authorized typed-operation gateway.
      Returns:
      authorized typed-operation gateway

    • enrollmentEndpoints

      public EnrollmentEndpointRegistry enrollmentEndpoints()
      Returns the realm-owned durable enrollment endpoint authority.
      Returns:
      shared thread-safe registry, usable only while this realm is open

    • enrollmentProfiles

      public EnrollmentProfileService enrollmentProfiles()
      Returns the realm-owned durable enrollment policy authority.
      Returns:
      shared thread-safe policy registry, usable only while this realm is open

    • principal

      public SecurityPrincipal principal(String principalId)
      Resolves one persisted principal for transport authentication.
      Parameters:
      principalId - canonical principal identity
      Returns:
      persisted identity metadata without credentials or grants
      Throws:
      IllegalArgumentException - when the principal is unavailable
      IllegalStateException - when this realm is not open

    • authorizeOcspQuery

      public AuthorizationEngine.Decision authorizeOcspQuery(String principalId, OcspResponderService.Responder responder)
      Evaluates the protocol-only OCSP query permission for one exact responder and issuer generation. The signed-request identity remains independent of administrative and transport authentication.
      Parameters:
      principalId - cryptographically mapped requester principal
      responder - exact active responder binding
      Returns:
      default-deny authorization decision

    • auditTransport

      public void auditTransport(String action, String principalId, Map<String,String> safeDetails)
      Records one transport-safe lifecycle or request classification through the shared realm audit authority.
      Parameters:
      action - stable transport action
      principalId - authenticated principal or system
      safeDetails - finite pre-redacted details

    • recordAdminRequest

      public void recordAdminRequest()
      Records an administrative HTTP request upon handler entry, including rejected requests.

    • state

      public ServerRealmContext.State state()
      Returns current lifecycle state.
      Returns:
      current lifecycle state

    • createPrincipal

      public void createPrincipal(SecurityPrincipal principal, String actorPrincipalId)
      Creates a principal and records only safe administrative audit metadata.
      Parameters:
      principal - validated principal to create
      actorPrincipalId - authenticated administrative actor

    • setPrincipalEnabled

      public SecurityPrincipal setPrincipalEnabled(String principalId, boolean enabled, String actorPrincipalId)
      Changes only the enabled state of an existing principal.
      Parameters:
      principalId - stable principal identifier
      enabled - desired enabled state
      actorPrincipalId - authenticated administrative actor
      Returns:
      durably updated principal

    • assignRole

      public void assignRole(RoleTemplateCatalog.Assignment assignment, String actorPrincipalId)
      Creates one scoped role assignment; templates remain non-authoritative alone.
      Parameters:
      assignment - validated scoped role assignment
      actorPrincipalId - authenticated administrative actor

    • grant

      public void grant(Permission.Grant grant, String actorPrincipalId)
      Creates one explicit scoped direct grant.
      Parameters:
      grant - validated scoped permission grant
      actorPrincipalId - authenticated administrative actor

    • close

      public void close() throws IOException
      Quiesces the realm and releases resources through one retryable shared attempt. Checked failures retain their original cause and suppression when translated to I/O failures; I/O and unchecked identities are unchanged. Interruption is restored for each caller, and incomplete shutdown may be retried.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if checked resource closure fails