Class EnrollmentCoordinator

java.lang.Object
zeroecho.pki.server.enrollment.EnrollmentCoordinator
All Implemented Interfaces:
AutoCloseable
public final class EnrollmentCoordinator extends Object implements AutoCloseable
Realm-owned durable enrollment admission, independent approval and exact signing continuation. Thread-safe under the realm control-store monitor. Domain parsing, provider work and signing occur outside that monitor. Startup makes one O(N) snapshot pass and retains counters rather than a transaction mirror; each active invocation retains only its bounded request and record. Unknown mutations fence this instance until reopening and authoritative reconciliation.

  • Constructor Details

    • EnrollmentCoordinator

      public EnrollmentCoordinator(ServerControlStore control, ServerRealmConfiguration realm, PkiSession session, EnrollmentEndpointRegistry endpoints, EnrollmentProfileService profiles, AcmeControlStore acme, EnrollmentRuntime runtime, EnrollmentIdentityAliases aliases, Clock clock)
      Validates retained references and rebuilds bounded counters before readiness. The realm must not publish this instance until construction completes.
      Parameters:
      control - sole realm control authority
      realm - immutable realm policy
      session - lifecycle-owned domain session
      endpoints - durable protocol registry
      profiles - durable enrollment policies
      acme - durable ACME registry
      runtime - installed enrollment budgets and credential custody
      aliases - trusted configured administrative mapping exclusions
      clock - authoritative clock

  • Method Details

    • storeAcmeAccount

      public AcmeState.Account storeAcmeAccount(Optional<AcmeState.Account> prior, AcmeState.Account proposed)
      Creates or atomically replaces an ACME account while retaining all observed requester keys and aliases. Shares the enrollment retention budget and control-store monitor with approval decisions; no authentication is granted.
      Parameters:
      prior - expected previous account, empty only for creation
      proposed - authenticated account update
      Returns:
      durably sealed account with append-only exclusion history

    • findCmp

      public Optional<CmpTransaction> findCmp(String label, String transactionSha256)
      Finds a wire reservation by stable coordinates. This lookup grants no authentication; callers must verify the retained requester before use.
      Parameters:
      label - endpoint label
      transactionSha256 - exact transaction identifier commitment
      Returns:
      immutable retained manifest, if present

    • reserveCmp

      public CmpTransaction reserveCmp(CmpTransaction.Frozen supplied)
      Reserves one logical transaction and its full response capacity before any domain side effect. Repeating a reservation requires the identical frozen coordinates. Unknown persistence outcomes fence the whole coordinator.
      Parameters:
      supplied - authenticated, bounded original request and credential selection
      Returns:
      durably reserved manifest including all currently known requester aliases

    • requireCmpCurrentSource

      public void requireCmpCurrentSource(CmpTransaction expected)
      Revalidates a reserved non-enrollment transaction before a fresh protocol effect. The exact manifest, endpoint policy, authority and frozen credential must remain usable; rotating the active credential alone does not invalidate its retained predecessor. This read-only check creates no durable claim and does not order a later domain effect atomically against policy changes. Already committed effects and exact response replay do not require it.
      Parameters:
      expected - exact previously observed non-enrollment manifest

    • cmpResponse

      public byte[] cmpResponse(CmpTransaction expected)
      Returns a complete committed response from a consistent manifest/slot view. Authentication and replay-nonce validation remain the adapter's obligation.
      Parameters:
      expected - exact previously observed manifest
      Returns:
      defensive response bytes, empty only before the first response

    • storeCmpResponse

      public CmpTransaction storeCmpResponse(CmpTransaction expected, byte[] response, CmpTransaction.Response metadata)
      Publishes protected bytes, nonce metadata and all fixed slots atomically. A stale computation fails without emitting its response; callers may return bytes only after this method acknowledges their persistence.
      Parameters:
      expected - full expected manifest commitment
      response - bounded complete protected response
      metadata - exact response and triggering request commitments
      Returns:
      acknowledged next manifest

    • admit

      public EnrollmentTransaction admit(EnrollmentCoordinator.Admission admission)
      Stores the exact verified request before publishing its durable approval reference. Identical retries reuse the retained result; transaction reuse with different request, operation or requester evidence fails closed.
      Parameters:
      admission - authenticated protocol input
      Returns:
      durable transaction, including retained terminal results

    • admit

      public EnrollmentTransaction admit(EnrollmentCoordinator.Admission admission, String expectedEndpointCommitment)
      Admits verified protocol input against the exact endpoint context used for protocol authentication, preventing a policy replacement between verification and durable admission. Retried requests use their frozen source commitment.
      Parameters:
      admission - authenticated protocol input
      expectedEndpointCommitment - exact previously observed source commitment
      Returns:
      durable transaction or retained identical result

    • admitCmp

      public EnrollmentTransaction admitCmp(EnrollmentCoordinator.Admission admission, CmpTransaction expected)
      Attaches an exact authenticated original CRMF to its reserved CMP manifest. Domain storage precedes one atomic manifest/enrollment publication. No second logical transaction is charged; request and future decision bytes are reserved before storing the domain request. Retry bytes never replace published data.
      Parameters:
      admission - authenticated original issuance or replacement request
      expected - exact unlinked or identically linked wire manifest
      Returns:
      durable linked enrollment transaction

    • findKeygen

      public Optional<EnrollmentKeygenArtifact> findKeygen(EnrollmentCoordinator.Admission admission)
      Finds the stable server-keygen replay descriptor and checks the exact original template and authenticated recipient. Lookup reconciles expired delivery and releases eligible ciphertext; it does not generate keys or dispatch.
      Parameters:
      admission - original EST server-keygen template and authenticated evidence
      Returns:
      retained descriptor, including terminal tombstones

    • beginKeygen

      public EnrollmentCoordinator.KeygenGeneration beginKeygen(EnrollmentCoordinator.Admission admission, X509Certificate recipient)
      Reserves all descriptor, CSR, approval, ciphertext and generation capacity before returning permission to generate one key. The original template is stored before the durable reservation is published. A borrower must close its generation handle after attachment or failure; interrupted reservations become terminal failures on recovery and never regenerate.
      Parameters:
      admission - exact verified EST server-keygen template
      recipient - actual authenticated mTLS recipient certificate
      Returns:
      exclusive bounded generation handle

    • keygenDelivery

      public EnrollmentCoordinator.KeygenDelivery keygenDelivery(EnrollmentCoordinator.Admission admission)
      Opens a bounded ciphertext lease only for the exact authenticated template after its correlated certificate is durably issued. Transport success does not consume the artifact; retries remain available until durable expiry.
      Parameters:
      admission - original template and authenticated recipient
      Returns:
      owned ciphertext lease

    • find

      public Optional<EnrollmentTransaction> find(String id)
      Finds the exact retained transaction without changing its state.
      Parameters:
      id - durable enrollment identity
      Returns:
      exact retained record or empty

    • find

      public Optional<EnrollmentTransaction> find(EnrollmentTransaction.Protocol protocol, String label, IssuanceExecutionEvidence.ActorType actorType, String actorId, String transactionId, EnrollmentTransaction.Operation operation)
      Finds a retained transaction by stable authenticated protocol coordinates. This grants no authentication or authorization and does not consult mutable endpoint policy; adapters must cross-check the returned frozen binding.
      Parameters:
      protocol - exact protocol family
      label - stable endpoint label or ACME directory alias
      actorType - authenticated protocol identity kind
      actorId - authenticated stable actor identity
      transactionId - exact protocol transaction SHA-256
      operation - exact operation replay domain
      Returns:
      retained transaction or empty

    • issuanceBinding

      public RetainedIssuanceBinding issuanceBinding(String id)
      Projects the actual domain correlation for a retained issuance request. Uses its exact stored payload and frozen intent; creates no signing work.
      Parameters:
      id - retained ISSUE transaction identity
      Returns:
      exact domain issuance binding

    • list

      public ServerControlStore.Page<EnrollmentTransaction> list(int offset, int limit)
      Reads a bounded deterministic page for the authoritative administrative projection. Authorization filters are applied by the gateway before disclosure.
      Parameters:
      offset - nonnegative offset
      limit - page size, at most 256
      Returns:
      immutable retained transaction page

    • inspectIdentity

      public ParsedCertificationRequest inspectIdentity(String id)
      Re-parses the exact retained request for authorized administrative inspection. Callers must authorize the persisted scope before disclosing the result and project only intended public identity fields, not its original byte attributes.
      Parameters:
      id - durable enrollment identity
      Returns:
      bounded authoritative request parse

    • decide

      public EnrollmentTransaction decide(String id, String expectedCommitment, AdministrativeDecisionActor actor, ApprovalService.Choice choice, String justification)
      Persists an independently authenticated, currently eligible decision before acknowledgement. One mathematical key can supply at most one vote.
      Parameters:
      id - exact retained request identity
      expectedCommitment - exact record reviewed by the administrator
      actor - trusted administrative end-client evidence
      choice - approval or rejection
      justification - bounded operator explanation
      Returns:
      durably updated record

    • dispatch

      public EnrollmentTransaction dispatch(String id)
      Dispatches or reconciles one approved request. Durable DISPATCHING is the admission boundary; suspension after that claim does not revoke admission. Provider preparation and acceptance never hold the global control monitor.
      Parameters:
      id - retained enrollment identity
      Returns:
      latest durable state, including an explicit uncertain outcome

    • dispatch

      public EnrollmentTransaction dispatch(String id, CancellationSignal cancellation)
      Dispatches with cooperative cancellation before the durable claim. Once admitted, exact receipt reconciliation owns the outcome despite cancellation.
      Parameters:
      id - retained enrollment identity
      cancellation - caller cancellation signal
      Returns:
      latest durable transaction state

    • dispatch

      public EnrollmentTransaction dispatch(String id, CancellationSignal cancellation, Runnable beforeClaim)
      Dispatches with a transport-owned last pre-claim validation. The validator runs outside the control monitor before preparation and immediately before a fresh claim, including a retry proven not accepted. It does not run for reconciliation of already admitted work. Failure after preparation discards the candidate. This is not atomic ordering against external status changes.
      Parameters:
      id - retained enrollment identity
      cancellation - caller cancellation signal
      beforeClaim - validator that throws on loss of transport authorization
      Returns:
      latest durable transaction state

    • scope

      public static Permission.Scope scope(EnrollmentTransaction value)
      Derives administrative scope solely from the retained authoritative request.
      Parameters:
      value - durable enrollment record
      Returns:
      exact realm, authority, issuer and certificate-profile scope

    • close

      public void close()
      Fences new work; active callers must drain before realm dependencies close.
      Specified by:
      close in interface AutoCloseable