feat: PKI module core design

Signed-off-by: Leo Galambos <lg@hq.egothor.org>

pki/src/main/java/zeroecho/pki/PkiApplication.java

@@ -0,0 +1,99 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki;
+
+import java.util.Objects;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * Minimal bootstrap entry point for the {@code pki} module.
+ *
+ * <p>
+ * This class is intentionally limited to process bootstrap concerns only:
+ * </p>
+ * <ul>
+ * <li>initializes JUL logging conventions (without leaking secrets),</li>
+ * <li>installs an uncaught-exception handler,</li>
+ * <li>emits a minimal startup/shutdown signal.</li>
+ * </ul>
+ *
+ * <p>
+ * No cryptography, persistence, or domain/business logic is performed here. The
+ * public PKI API resides under {@code zeroecho.pki.api.*} and is not modified
+ * by this bootstrap.
+ * </p>
+ */
+public final class PkiApplication {
+
+    private static final Logger LOG = Logger.getLogger(PkiApplication.class.getName());
+
+    private PkiApplication() {
+        throw new AssertionError("No instances.");
+    }
+
+    /**
+     * Starts the PKI process.
+     *
+     * <p>
+     * Security note: command-line arguments are not logged because they can contain
+     * sensitive material (paths, tokens, passphrases).
+     * </p>
+     *
+     * @param args command-line arguments (never logged)
+     */
+    public static void main(String[] args) {
+        Objects.requireNonNull(args, "args");
+
+        PkiLogging.configureIfPresent();
+        PkiLogging.installUncaughtExceptionHandler();
+
+        LOG.info("ZeroEcho PKI starting.");
+
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            Logger shutdownLogger = Logger.getLogger(PkiApplication.class.getName());
+            PkiLogging.emitShutdownMessage(shutdownLogger, "ZeroEcho PKI stopping.");
+        }, "zeroecho-pki-shutdown"));
+
+        try {
+            // Intentionally no business logic yet. Bootstrap only.
+            LOG.info("ZeroEcho PKI started (bootstrap only).");
+        } catch (RuntimeException ex) {
+            // Do not include user-provided inputs in the message; log the exception object.
+            LOG.log(Level.SEVERE, "Fatal error during PKI bootstrap.", ex);
+            throw ex;
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/PkiLogging.java

@@ -0,0 +1,180 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.lang.Thread.UncaughtExceptionHandler;
+import java.util.Objects;
+import java.util.logging.Level;
+import java.util.logging.LogManager;
+import java.util.logging.Logger;
+
+/**
+ * Internal bootstrap utilities for JUL configuration in the {@code pki} module.
+ *
+ * <p>
+ * This helper intentionally avoids logging any potentially sensitive material.
+ * In particular, it never logs:
+ * </p>
+ * <ul>
+ * <li>command-line arguments,</li>
+ * <li>key material, seeds, shared secrets,</li>
+ * <li>private configuration values (tokens, passphrases).</li>
+ * </ul>
+ *
+ * <p>
+ * Configuration strategy:
+ * </p>
+ * <ul>
+ * <li>If a {@code /zeroecho-pki-logging.properties} resource is present on the
+ * classpath, it will be loaded via
+ * {@link LogManager#readConfiguration(InputStream)}.</li>
+ * <li>If not present, JUL defaults remain in place (minimal bootstrap
+ * behavior).</li>
+ * </ul>
+ */
+final class PkiLogging {
+
+    /**
+     * Optional classpath resource for JUL configuration.
+     */
+    static final String LOGGING_PROPERTIES_RESOURCE = "/zeroecho-pki-logging.properties";
+
+    private static final Logger LOG = Logger.getLogger(PkiLogging.class.getName());
+
+    private static volatile boolean configured;
+
+    private PkiLogging() {
+        throw new AssertionError("No instances.");
+    }
+
+    /**
+     * Configures JUL from an optional classpath resource, if present.
+     *
+     * <p>
+     * This method is idempotent and safe to call multiple times.
+     * </p>
+     */
+    static void configureIfPresent() {
+        if (configured) {
+            return;
+        }
+        synchronized (PkiLogging.class) {
+            if (configured) {
+                return;
+            }
+
+            InputStream in = PkiLogging.class.getResourceAsStream(LOGGING_PROPERTIES_RESOURCE);
+            if (in == null) {
+                configured = true;
+                return;
+            }
+
+            try (InputStream is = in) {
+                LogManager.getLogManager().readConfiguration(is);
+                configured = true;
+                LOG.info("JUL configured from classpath resource.");
+            } catch (IOException ex) {
+                configured = true;
+                // Keep message generic; do not leak environment specifics.
+                LOG.log(Level.WARNING, "Failed to load JUL configuration; continuing with defaults.", ex);
+            }
+        }
+    }
+
+    /**
+     * Installs a process-wide uncaught exception handler that logs failures via
+     * JUL.
+     *
+     * <p>
+     * The handler emits a generic message and includes the throwable. It
+     * deliberately does not serialize additional contextual data that might contain
+     * secrets.
+     * </p>
+     */
+    static void installUncaughtExceptionHandler() {
+        UncaughtExceptionHandler handler = (Thread thread, Throwable throwable) -> {
+            Objects.requireNonNull(thread, "thread");
+            Objects.requireNonNull(throwable, "throwable");
+            Logger logger = Logger.getLogger(PkiApplication.class.getName());
+            logger.log(Level.SEVERE, "Uncaught exception in thread: " + thread.getName(), throwable);
+        };
+
+        Thread.setDefaultUncaughtExceptionHandler(handler);
+    }
+
+    /**
+     * Emits a shutdown message in a way that remains visible even during late JVM
+     * teardown.
+     *
+     * <p>
+     * The primary path is JUL. As a fallback, a constant message is written to
+     * {@code System.err}. This avoids logging any secrets and improves reliability
+     * in environments where JUL output may be lost during shutdown.
+     * </p>
+     *
+     * @param logger  logger to use for the primary JUL emission
+     * @param message message to emit; must not contain secrets
+     * @throws NullPointerException if {@code logger} or {@code message} is
+     *                              {@code null}
+     */
+    static void emitShutdownMessage(Logger logger, String message) {
+        Objects.requireNonNull(logger, "logger");
+        Objects.requireNonNull(message, "message");
+
+        // Primary path: JUL
+        logger.info(message);
+
+        // Flush root handlers (covers parent-handler delegation).
+        Logger root = Logger.getLogger("");
+        for (java.util.logging.Handler handler : root.getHandlers()) {
+            try {
+                handler.flush();
+            } catch (RuntimeException ignored) {
+                // Never throw during shutdown
+            }
+        }
+
+        // Fallback: direct stderr write
+        try {
+            System.err.println(message);
+            System.err.flush();
+        } catch (RuntimeException ignored) {
+            // Never throw during shutdown
+        }
+    }
+
+}

pki/src/main/java/zeroecho/pki/api/BackupService.java

@@ -0,0 +1,83 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import zeroecho.pki.api.backup.BackupArtifact;
+import zeroecho.pki.api.backup.BackupRequest;
+import zeroecho.pki.api.backup.BackupVerificationReport;
+import zeroecho.pki.api.backup.RestoreReport;
+import zeroecho.pki.api.backup.RestoreRequest;
+
+/**
+ * Backup/restore operations for PKI state.
+ *
+ * <p>
+ * Backups must not implicitly include private keys. Private keys are referenced
+ * via {@link KeyRef} and may be managed by separate components.
+ * </p>
+ */
+public interface BackupService {
+
+    /**
+     * Creates a backup of PKI state.
+     *
+     * @param request backup request
+     * @return backup artifact
+     * @throws IllegalArgumentException if {@code request} is invalid
+     * @throws PkiException             if backup creation fails
+     */
+    BackupArtifact createBackup(BackupRequest request);
+
+    /**
+     * Restores PKI state from a backup artifact.
+     *
+     * @param request restore request
+     * @return restore report
+     * @throws IllegalArgumentException if {@code request} is invalid
+     * @throws PkiException             if restore fails
+     */
+    RestoreReport restoreBackup(RestoreRequest request);
+
+    /**
+     * Verifies a backup artifact for structural validity and integrity.
+     *
+     * @param artifact backup artifact
+     * @return verification report
+     * @throws IllegalArgumentException if {@code artifact} is null
+     * @throws PkiException             if verification fails due to IO/backend
+     *                                  errors
+     */
+    BackupVerificationReport verifyBackup(BackupArtifact artifact);
+}

pki/src/main/java/zeroecho/pki/api/CaService.java

@@ -0,0 +1,172 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+
+import zeroecho.pki.api.ca.CaCreateCommand;
+import zeroecho.pki.api.ca.CaImportCommand;
+import zeroecho.pki.api.ca.CaKeyRotationCommand;
+import zeroecho.pki.api.ca.CaQuery;
+import zeroecho.pki.api.ca.CaRecord;
+import zeroecho.pki.api.ca.CaRolloverCommand;
+import zeroecho.pki.api.ca.CaState;
+import zeroecho.pki.api.ca.IntermediateCertIssueCommand;
+import zeroecho.pki.api.ca.IntermediateCreateCommand;
+import zeroecho.pki.api.credential.Credential;
+
+/**
+ * Manages Certificate Authority (CA) entities and their lifecycle.
+ *
+ * <p>
+ * A CA entity represents an administrative unit capable of issuing credentials.
+ * A CA entity may own multiple CA credentials over time to support
+ * cross-signing, rollover, and key rotation.
+ * </p>
+ *
+ * <p>
+ * Private key material is never handled directly by the PKI module; the CA key
+ * is referenced by {@link KeyRef} and resolved by runtime wiring.
+ * </p>
+ */
+public interface CaService {
+
+    /**
+     * Creates a new root CA entity and issues its initial CA credential.
+     *
+     * @param command create command defining subject/profile and optional key
+     *                reference
+     * @return created CA identifier
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if creation fails due to policy, storage, or
+     *                                  framework backend error
+     */
+    PkiId createRoot(CaCreateCommand command);
+
+    /**
+     * Imports an existing root CA into the PKI inventory.
+     *
+     * <p>
+     * This registers a CA entity, associates it with a {@link KeyRef}, and persists
+     * the existing CA credential. Import does not automatically imply trust; trust
+     * anchor selection is a consumer decision.
+     * </p>
+     *
+     * @param command import command including CA credential payload and key
+     *                reference
+     * @return imported CA identifier
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if import fails (e.g., inconsistent
+     *                                  metadata, storage failure)
+     */
+    PkiId importRoot(CaImportCommand command);
+
+    /**
+     * Creates a new intermediate CA entity and issues its initial intermediate CA
+     * credential.
+     *
+     * @param command intermediate creation command
+     * @return created intermediate CA identifier
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if creation fails
+     */
+    PkiId createIntermediate(IntermediateCreateCommand command);
+
+    /**
+     * Issues a new CA credential for an existing intermediate CA entity.
+     *
+     * <p>
+     * This operation enables cross-signing and renewal scenarios.
+     * </p>
+     *
+     * @param command issuance command specifying issuer and subject CA entity
+     * @return newly issued CA credential
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if issuance fails due to policy or backend
+     *                                  errors
+     */
+    Credential issueIntermediateCertificate(IntermediateCertIssueCommand command);
+
+    /**
+     * Performs a CA credential rollover while keeping the same key reference.
+     *
+     * @param command rollover command
+     * @return CA identifier (same CA id expected; returned for convenience)
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if rollover fails
+     */
+    PkiId rolloverCaCertificate(CaRolloverCommand command);
+
+    /**
+     * Rotates the CA key reference and issues new corresponding CA credentials.
+     *
+     * @param command key rotation command
+     * @return CA identifier (same CA id expected; returned for convenience)
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if rotation fails
+     */
+    PkiId rotateCaKey(CaKeyRotationCommand command);
+
+    /**
+     * Updates CA operational state.
+     *
+     * @param caId   CA identifier
+     * @param state  new CA state
+     * @param reason non-empty operator-readable reason suitable for audit
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if CA does not exist or update fails
+     */
+    void setCaState(PkiId caId, CaState state, String reason);
+
+    /**
+     * Retrieves a CA record.
+     *
+     * @param caId CA identifier
+     * @return CA record
+     * @throws IllegalArgumentException if {@code caId} is invalid
+     * @throws PkiException             if CA does not exist
+     */
+    CaRecord getCa(PkiId caId);
+
+    /**
+     * Lists CA records matching query constraints.
+     *
+     * @param query query constraints
+     * @return list of CA records
+     * @throws IllegalArgumentException if {@code query} is invalid
+     * @throws PkiException             if listing fails
+     */
+    List<CaRecord> listCas(CaQuery query);
+}

pki/src/main/java/zeroecho/pki/api/CertificationRequestService.java

@@ -0,0 +1,123 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.issuance.VerificationPolicy;
+import zeroecho.pki.api.request.CertificationRequest;
+import zeroecho.pki.api.request.ParsedCertificationRequest;
+import zeroecho.pki.api.request.ProofOfPossessionResult;
+import zeroecho.pki.api.request.RequestQuery;
+import zeroecho.pki.api.request.RequestStorePolicy;
+
+/**
+ * Processes certification requests (CSR-like objects) into a normalized
+ * representation.
+ *
+ * <p>
+ * This service provides request fingerprinting, parsing, proof-of-possession
+ * verification, and optional persistence for correlation and auditing. Request
+ * transport protocols such as ACME are expected to use this service as the core
+ * processing layer.
+ * </p>
+ */
+public interface CertificationRequestService {
+
+    /**
+     * Computes a stable identifier (fingerprint) for the given request payload.
+     *
+     * @param request certification request
+     * @return stable request identifier
+     * @throws IllegalArgumentException if {@code request} is null
+     * @throws PkiException             if fingerprinting fails
+     */
+    PkiId fingerprint(CertificationRequest request);
+
+    /**
+     * Parses and normalizes a certification request.
+     *
+     * @param request certification request
+     * @return parsed request
+     * @throws IllegalArgumentException if {@code request} is null
+     * @throws PkiException             if parsing fails (invalid request,
+     *                                  unsupported format, backend failure)
+     */
+    ParsedCertificationRequest parse(CertificationRequest request);
+
+    /**
+     * Verifies proof-of-possession (PoP) for the private key corresponding to the
+     * requested public key.
+     *
+     * @param parsed parsed request
+     * @param policy verification policy
+     * @return PoP verification result
+     * @throws IllegalArgumentException if inputs are null
+     * @throws PkiException             if verification fails due to backend failure
+     */
+    ProofOfPossessionResult verifyProofOfPossession(ParsedCertificationRequest parsed, VerificationPolicy policy);
+
+    /**
+     * Stores a parsed request for later correlation and audit.
+     *
+     * @param parsed parsed request
+     * @param policy storage policy
+     * @return stored request id
+     * @throws IllegalArgumentException if inputs are null
+     * @throws PkiException             if persistence fails
+     */
+    PkiId store(ParsedCertificationRequest parsed, RequestStorePolicy policy);
+
+    /**
+     * Retrieves a stored request.
+     *
+     * @param requestId request id
+     * @return parsed request if present
+     * @throws IllegalArgumentException if {@code requestId} is null
+     * @throws PkiException             if retrieval fails
+     */
+    Optional<ParsedCertificationRequest> get(PkiId requestId);
+
+    /**
+     * Searches stored requests.
+     *
+     * @param query request query
+     * @return matching requests
+     * @throws IllegalArgumentException if {@code query} is null
+     * @throws PkiException             if searching fails
+     */
+    List<ParsedCertificationRequest> search(RequestQuery query);
+}

pki/src/main/java/zeroecho/pki/api/CredentialInventoryService.java

@@ -0,0 +1,101 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.credential.Credential;
+import zeroecho.pki.api.credential.CredentialQuery;
+import zeroecho.pki.api.credential.CredentialStatus;
+
+/**
+ * Inventory and reporting service for issued credentials.
+ */
+public interface CredentialInventoryService {
+
+    /**
+     * Retrieves a credential by id.
+     *
+     * @param credentialId credential id
+     * @return credential if present
+     * @throws IllegalArgumentException if {@code credentialId} is null
+     * @throws PkiException             if retrieval fails
+     */
+    Optional<Credential> get(PkiId credentialId);
+
+    /**
+     * Finds a credential by issuer CA and serial/unique identifier.
+     *
+     * @param issuerCaId       issuer CA id
+     * @param serialOrUniqueId serial/unique id
+     * @return credential if present
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if lookup fails
+     */
+    Optional<Credential> findByIssuerSerial(PkiId issuerCaId, String serialOrUniqueId);
+
+    /**
+     * Lists credentials bound to the same public key identifier.
+     *
+     * @param publicKeyId public key id
+     * @return credentials
+     * @throws IllegalArgumentException if {@code publicKeyId} is null
+     * @throws PkiException             if lookup fails
+     */
+    List<Credential> listByPublicKeyId(PkiId publicKeyId);
+
+    /**
+     * Searches credentials by query constraints.
+     *
+     * @param query query constraints
+     * @return matching credentials
+     * @throws IllegalArgumentException if {@code query} is null
+     * @throws PkiException             if search fails
+     */
+    List<Credential> search(CredentialQuery query);
+
+    /**
+     * Computes credential status at a given time.
+     *
+     * @param credentialId credential id
+     * @param now          evaluation time
+     * @return computed status
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if evaluation fails
+     */
+    CredentialStatus computeStatus(PkiId credentialId, Instant now);
+}

pki/src/main/java/zeroecho/pki/api/EncodedObject.java

@@ -0,0 +1,72 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Immutable container for an encoded artifact.
+ *
+ * <p>
+ * This type intentionally carries only the {@link Encoding} and raw bytes. It
+ * does not carry a media type, because DER/PEM/BINARY do not uniquely determine
+ * the semantic meaning (a DER payload may represent a certificate, CSR, CRL,
+ * etc.). The semantic meaning is carried by the surrounding API context.
+ * </p>
+ *
+ * <p>
+ * Security note: implementations must never log the raw bytes in full.
+ * </p>
+ *
+ * @param encoding encoding kind
+ * @param bytes    non-empty payload bytes
+ */
+public record EncodedObject(Encoding encoding, byte[] bytes) {
+
+    /**
+     * Creates an encoded object.
+     *
+     * @param encoding encoding kind
+     * @param bytes    non-empty payload bytes
+     * @throws IllegalArgumentException if {@code encoding} is null or {@code bytes}
+     *                                  is null/empty
+     */
+    public EncodedObject {
+        if (encoding == null) {
+            throw new IllegalArgumentException("encoding must not be null");
+        }
+        if (bytes == null || bytes.length == 0) {
+            throw new IllegalArgumentException("bytes must not be null/empty");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/Encoding.java

@@ -0,0 +1,75 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Specifies the encoding of a binary artifact payload.
+ *
+ * <p>
+ * The encoding indicates how the {@code bytes} inside {@link EncodedObject}
+ * should be interpreted. The logical meaning of the payload (certificate vs CSR
+ * vs CRL vs backup) is defined by the surrounding API context and record types.
+ * </p>
+ */
+public enum Encoding {
+
+    /**
+     * ASN.1 Distinguished Encoding Rules (DER).
+     *
+     * <p>
+     * Common for X.509 certificates, CRLs, and PKCS#10 certification requests.
+     * </p>
+     */
+    DER,
+
+    /**
+     * PEM armored textual representation.
+     *
+     * <p>
+     * Typically base64-wrapped DER with header/footer lines.
+     * </p>
+     */
+    PEM,
+
+    /**
+     * Raw binary blob without implying ASN.1 DER or PEM semantics.
+     *
+     * <p>
+     * Use for non-ASN.1 frameworks (e.g., COSE/JWS) or container payloads (e.g.,
+     * backup archives).
+     * </p>
+     */
+    BINARY
+}

pki/src/main/java/zeroecho/pki/api/FormatId.java

@@ -0,0 +1,64 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Identifier of a credential framework/format handled by the PKI core.
+ *
+ * <p>
+ * Examples: {@code "x509"}, {@code "ssh"}, {@code "cose"}, {@code "jws"}.
+ * </p>
+ *
+ * <p>
+ * This identifier is used to dispatch operations to a framework backend
+ * implementation.
+ * </p>
+ *
+ * @param value non-empty format identifier string
+ */
+public record FormatId(String value) {
+
+    /**
+     * Creates a format identifier.
+     *
+     * @param value non-empty format identifier string
+     * @throws IllegalArgumentException if {@code value} is null or blank
+     */
+    public FormatId {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ImportExportService.java

@@ -0,0 +1,122 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import zeroecho.pki.api.revocation.RevokedRecord;
+import zeroecho.pki.api.transfer.ExportArtifact;
+import zeroecho.pki.api.transfer.ExportFormat;
+import zeroecho.pki.api.transfer.ExportQuery;
+import zeroecho.pki.api.transfer.ImportPolicy;
+
+/**
+ * Import and export operations for migration and interoperability.
+ *
+ * <p>
+ * Import does not imply trust; it is a controlled operation governed by policy.
+ * Import/export is expected to be auditable.
+ * </p>
+ */
+public interface ImportExportService {
+
+    /**
+     * Imports an issued credential payload into inventory.
+     *
+     * @param formatId   credential format id
+     * @param credential encoded credential payload
+     * @param policy     import policy
+     * @return imported credential id
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if import fails
+     */
+    PkiId importCredential(FormatId formatId, EncodedObject credential, ImportPolicy policy);
+
+    /**
+     * Imports a CA certificate payload into an existing CA entity's credential set.
+     *
+     * @param caId          CA entity id
+     * @param caCertificate CA certificate payload
+     * @param policy        import policy
+     * @return imported credential id
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if import fails
+     */
+    PkiId importCaCertificate(PkiId caId, EncodedObject caCertificate, ImportPolicy policy);
+
+    /**
+     * Imports a revocation record.
+     *
+     * @param record revocation record
+     * @param policy import policy
+     * @return imported revocation record id (implementation-defined)
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if import fails
+     */
+    PkiId importRevocation(RevokedRecord record, ImportPolicy policy);
+
+    /**
+     * Exports credentials matching the query constraints in the requested export
+     * format.
+     *
+     * @param query  export query
+     * @param format export format
+     * @return export artifact
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if export fails
+     */
+    ExportArtifact exportCredentials(ExportQuery query, ExportFormat format);
+
+    /**
+     * Exports revocation records matching the query constraints in the requested
+     * export format.
+     *
+     * @param query  export query
+     * @param format export format
+     * @return export artifact
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if export fails
+     */
+    ExportArtifact exportRevocations(ExportQuery query, ExportFormat format);
+
+    /**
+     * Exports CA materials for a given CA entity in the requested export format.
+     *
+     * @param caId   CA entity id
+     * @param format export format
+     * @return export artifact
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if export fails
+     */
+    ExportArtifact exportCa(PkiId caId, ExportFormat format);
+}

pki/src/main/java/zeroecho/pki/api/IssuanceService.java

@@ -0,0 +1,108 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import zeroecho.pki.api.credential.CredentialBundle;
+import zeroecho.pki.api.issuance.BundleCommand;
+import zeroecho.pki.api.issuance.IssueEndEntityCommand;
+import zeroecho.pki.api.issuance.ReissueCommand;
+import zeroecho.pki.api.issuance.RenewCommand;
+import zeroecho.pki.api.issuance.ReplaceCommand;
+
+/**
+ * Issues, renews, replaces, and reissues credentials, and builds distributable
+ * bundles.
+ *
+ * <p>
+ * This service is framework-agnostic: concrete credential formats are
+ * implemented by framework backends. The PKI runtime applies policy and profile
+ * constraints before calling issuance backends.
+ * </p>
+ */
+public interface IssuanceService {
+
+    /**
+     * Issues a new end-entity credential.
+     *
+     * @param command issuance command
+     * @return credential bundle (credential plus supporting artifacts)
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if issuance fails
+     */
+    CredentialBundle issueEndEntity(IssueEndEntityCommand command);
+
+    /**
+     * Renews an existing credential according to policy-defined continuity
+     * semantics.
+     *
+     * @param command renewal command
+     * @return renewed credential bundle
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if renewal fails
+     */
+    CredentialBundle renew(RenewCommand command);
+
+    /**
+     * Replaces an existing credential (e.g., after compromise or attribute
+     * changes).
+     *
+     * @param command replacement command
+     * @return replacement credential bundle
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if replacement fails
+     */
+    CredentialBundle replace(ReplaceCommand command);
+
+    /**
+     * Reissues based on a stored issuance record.
+     *
+     * @param command reissue command
+     * @return reissued credential bundle
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if reissue fails
+     */
+    CredentialBundle reissue(ReissueCommand command);
+
+    /**
+     * Builds a distributable bundle for an existing credential using chain
+     * selection rules.
+     *
+     * @param command bundle command
+     * @return bundle
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if bundle building fails
+     */
+    CredentialBundle buildBundle(BundleCommand command);
+}

pki/src/main/java/zeroecho/pki/api/IssuerRef.java

@@ -0,0 +1,55 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * References an issuing CA entity.
+ *
+ * @param caId identifier of the CA entity acting as issuer
+ */
+public record IssuerRef(PkiId caId) {
+
+    /**
+     * Creates an issuer reference.
+     *
+     * @param caId CA identifier
+     * @throws IllegalArgumentException if {@code caId} is null
+     */
+    public IssuerRef {
+        if (caId == null) {
+            throw new IllegalArgumentException("caId must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/KeyRef.java

@@ -0,0 +1,62 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Opaque reference to private key material.
+ *
+ * <p>
+ * The PKI module never handles private key bytes. A {@link KeyRef} is resolved
+ * by runtime wiring, e.g., by a crypto component, an HSM adapter, or a remote
+ * signer. Implementations must treat this reference as sensitive metadata and
+ * avoid logging it unnecessarily.
+ * </p>
+ *
+ * @param value non-empty key reference token
+ */
+public record KeyRef(String value) {
+
+    /**
+     * Creates a key reference.
+     *
+     * @param value non-empty key reference token
+     * @throws IllegalArgumentException if {@code value} is null or blank
+     */
+    public KeyRef {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/PkiException.java

@@ -0,0 +1,82 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Base runtime exception for PKI domain failures.
+ *
+ * <p>
+ * This exception is used to report policy violations, storage failures,
+ * framework backend errors, and other domain-level problems not representable
+ * as {@link IllegalArgumentException}.
+ * </p>
+ *
+ * <p>
+ * Security note: exception messages must not contain secrets (private keys,
+ * plaintext, shared secrets, or other sensitive cryptographic material).
+ * </p>
+ */
+public class PkiException extends RuntimeException {
+
+    private static final long serialVersionUID = 759504279718537161L;
+
+    /**
+     * Creates a PKI exception with a message.
+     *
+     * @param message non-empty message describing the failure in a non-sensitive
+     *                manner
+     */
+    public PkiException(String message) {
+        super(requireNonBlank(message, "message"));
+    }
+
+    /**
+     * Creates a PKI exception with a message and cause.
+     *
+     * @param message non-empty message describing the failure in a non-sensitive
+     *                manner
+     * @param cause   underlying cause
+     */
+    public PkiException(String message, Throwable cause) {
+        super(requireNonBlank(message, "message"), cause);
+    }
+
+    private static String requireNonBlank(String value, String name) {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException(name + " must not be null/blank");
+        }
+        return value;
+    }
+}

pki/src/main/java/zeroecho/pki/api/PkiId.java

@@ -0,0 +1,65 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Opaque identifier for PKI-managed entities.
+ *
+ * <p>
+ * Instances of this type are used as stable references for CA entities,
+ * credentials, certification requests, status objects, backups, publications,
+ * exports, and policy/audit records.
+ * </p>
+ *
+ * <p>
+ * The value must be treated as an opaque token and persisted verbatim.
+ * </p>
+ *
+ * @param value non-empty identifier string
+ */
+public record PkiId(String value) {
+
+    /**
+     * Creates an opaque PKI identifier.
+     *
+     * @param value non-empty identifier string
+     * @throws IllegalArgumentException if {@code value} is null or blank
+     */
+    public PkiId {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/PolicyService.java

@@ -0,0 +1,82 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import zeroecho.pki.api.issuance.IssuanceInputs;
+import zeroecho.pki.api.policy.PolicyDecision;
+import zeroecho.pki.api.policy.PolicyTrace;
+import zeroecho.pki.api.revocation.RevocationInputs;
+
+/**
+ * Policy evaluation and explainability.
+ *
+ * <p>
+ * Policy decisions must be deterministic, auditable, and explainable.
+ * Implementations are expected to provide traces suitable for operator
+ * troubleshooting and compliance evidence.
+ * </p>
+ */
+public interface PolicyService {
+
+    /**
+     * Evaluates an issuance request against policy and profile constraints.
+     *
+     * @param inputs normalized issuance inputs
+     * @return policy decision
+     * @throws IllegalArgumentException if {@code inputs} is null
+     * @throws PkiException             if evaluation fails
+     */
+    PolicyDecision evaluateIssuance(IssuanceInputs inputs);
+
+    /**
+     * Evaluates a revocation request against policy constraints.
+     *
+     * @param inputs normalized revocation inputs
+     * @return policy decision
+     * @throws IllegalArgumentException if {@code inputs} is null
+     * @throws PkiException             if evaluation fails
+     */
+    PolicyDecision evaluateRevocation(RevocationInputs inputs);
+
+    /**
+     * Retrieves a trace explaining a previous decision.
+     *
+     * @param decisionId decision id
+     * @return decision trace
+     * @throws IllegalArgumentException if {@code decisionId} is null
+     * @throws PkiException             if trace retrieval fails
+     */
+    PolicyTrace explain(PkiId decisionId);
+}

pki/src/main/java/zeroecho/pki/api/ProfileService.java

@@ -0,0 +1,91 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+
+import zeroecho.pki.api.profile.CertificateProfile;
+import zeroecho.pki.api.profile.ProfileQuery;
+
+/**
+ * Profile registry for credential issuance.
+ *
+ * <p>
+ * Profiles define required/optional attributes, validity limits, and other
+ * constraints used by policy and framework mapping. Profiles are referenced by
+ * id during issuance.
+ * </p>
+ */
+public interface ProfileService {
+
+    /**
+     * Registers or updates a profile.
+     *
+     * @param profile profile definition
+     * @throws IllegalArgumentException if {@code profile} is null
+     * @throws PkiException             if registration fails
+     */
+    void register(CertificateProfile profile);
+
+    /**
+     * Retrieves a profile by id.
+     *
+     * @param profileId profile id
+     * @return profile
+     * @throws IllegalArgumentException if {@code profileId} is null/blank
+     * @throws PkiException             if not found or retrieval fails
+     */
+    CertificateProfile get(String profileId);
+
+    /**
+     * Lists profiles matching query constraints.
+     *
+     * @param query query constraints
+     * @return list of profiles
+     * @throws IllegalArgumentException if {@code query} is null
+     * @throws PkiException             if listing fails
+     */
+    List<CertificateProfile> list(ProfileQuery query);
+
+    /**
+     * Retires a profile to prevent further issuance.
+     *
+     * @param profileId profile id
+     * @param reason    non-empty reason suitable for audit
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if retire fails
+     */
+    void retire(String profileId, String reason);
+}

pki/src/main/java/zeroecho/pki/api/PublicationService.java

@@ -0,0 +1,99 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+
+import zeroecho.pki.api.publication.PublicationQuery;
+import zeroecho.pki.api.publication.PublicationRecord;
+import zeroecho.pki.api.publication.PublicationResult;
+import zeroecho.pki.api.publication.PublicationTarget;
+
+/**
+ * Publication and distribution operations.
+ *
+ * <p>
+ * Publishing is an explicit operation enabling parity with established PKI
+ * systems. Implementations may publish credentials, CA materials, and status
+ * objects to configured targets such as filesystem mirrors, LDAP directories,
+ * HTTP endpoints, or object stores.
+ * </p>
+ */
+public interface PublicationService {
+
+    /**
+     * Publishes an issued credential to the specified target.
+     *
+     * @param credentialId credential id
+     * @param target       publication target
+     * @return publication result
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if publication fails
+     */
+    PublicationResult publishCredential(PkiId credentialId, PublicationTarget target);
+
+    /**
+     * Publishes CA materials (e.g., CA certificate sets) for the given CA entity to
+     * the specified target.
+     *
+     * @param caId   CA entity id
+     * @param target publication target
+     * @return publication result
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if publication fails
+     */
+    PublicationResult publishCaMaterials(PkiId caId, PublicationTarget target);
+
+    /**
+     * Publishes a status object to the specified target.
+     *
+     * @param statusObjectId status object id
+     * @param target         publication target
+     * @return publication result
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if publication fails
+     */
+    PublicationResult publishStatusObject(PkiId statusObjectId, PublicationTarget target);
+
+    /**
+     * Lists publication records matching query constraints.
+     *
+     * @param query publication query
+     * @return publication records
+     * @throws IllegalArgumentException if {@code query} is invalid
+     * @throws PkiException             if listing fails
+     */
+    List<PublicationRecord> listPublications(PublicationQuery query);
+}

pki/src/main/java/zeroecho/pki/api/RevocationService.java

@@ -0,0 +1,100 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.revocation.HoldCommand;
+import zeroecho.pki.api.revocation.RevocationQuery;
+import zeroecho.pki.api.revocation.RevokeCommand;
+import zeroecho.pki.api.revocation.RevokedRecord;
+import zeroecho.pki.api.revocation.UnholdCommand;
+
+/**
+ * Revocation operations and revocation record management.
+ */
+public interface RevocationService {
+
+    /**
+     * Revokes a credential.
+     *
+     * @param command revoke command
+     * @return revocation record
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if revocation fails
+     */
+    RevokedRecord revoke(RevokeCommand command);
+
+    /**
+     * Places a credential on hold.
+     *
+     * @param command hold command
+     * @return revocation record
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if hold fails
+     */
+    RevokedRecord hold(HoldCommand command);
+
+    /**
+     * Removes a hold from a credential.
+     *
+     * @param command unhold command
+     * @return revocation record
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if unhold fails
+     */
+    RevokedRecord unhold(UnholdCommand command);
+
+    /**
+     * Retrieves revocation record for a credential.
+     *
+     * @param credentialId credential id
+     * @return record if present
+     * @throws IllegalArgumentException if {@code credentialId} is null
+     * @throws PkiException             if retrieval fails
+     */
+    Optional<RevokedRecord> get(PkiId credentialId);
+
+    /**
+     * Searches revocation records.
+     *
+     * @param query query constraints
+     * @return matching records
+     * @throws IllegalArgumentException if {@code query} is null
+     * @throws PkiException             if search fails
+     */
+    List<RevokedRecord> search(RevocationQuery query);
+}

pki/src/main/java/zeroecho/pki/api/StatusObjectService.java

@@ -0,0 +1,85 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.status.StatusObject;
+import zeroecho.pki.api.status.StatusObjectGenerateCommand;
+import zeroecho.pki.api.status.StatusObjectQuery;
+import zeroecho.pki.api.status.StatusObjectType;
+
+/**
+ * Status object generation and retrieval.
+ *
+ * <p>
+ * Status objects include CRLs, delta CRLs, OCSP responses, or
+ * framework-specific revocation lists.
+ * </p>
+ */
+public interface StatusObjectService {
+
+    /**
+     * Generates a new status object for an issuer CA.
+     *
+     * @param command generation command
+     * @return generated status object
+     * @throws IllegalArgumentException if {@code command} is invalid
+     * @throws PkiException             if generation fails
+     */
+    StatusObject generate(StatusObjectGenerateCommand command);
+
+    /**
+     * Retrieves the latest status object of a given type for an issuer CA.
+     *
+     * @param issuerCaId issuer CA id
+     * @param type       status object type
+     * @return latest status object if present
+     * @throws IllegalArgumentException if inputs are invalid
+     * @throws PkiException             if retrieval fails
+     */
+    Optional<StatusObject> getLatest(PkiId issuerCaId, StatusObjectType type);
+
+    /**
+     * Lists status objects matching query constraints.
+     *
+     * @param query query constraints
+     * @return matching status objects
+     * @throws IllegalArgumentException if {@code query} is invalid
+     * @throws PkiException             if listing fails
+     */
+    List<StatusObject> list(StatusObjectQuery query);
+}

pki/src/main/java/zeroecho/pki/api/SubjectRef.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+/**
+ * Framework-agnostic subject identifier.
+ *
+ * <p>
+ * This identifier is used for policy evaluation, inventory queries, and audit
+ * correlation. Framework backends may map it to a distinguished name (DN), a
+ * claims subject, or a service identity, depending on the credential framework.
+ * </p>
+ *
+ * @param value non-empty subject reference
+ */
+public record SubjectRef(String value) {
+
+    /**
+     * Creates a subject reference.
+     *
+     * @param value non-empty subject reference
+     * @throws IllegalArgumentException if {@code value} is null or blank
+     */
+    public SubjectRef {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/Validity.java

@@ -0,0 +1,74 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api;
+
+import java.time.Instant;
+
+/**
+ * Validity interval for an issued credential.
+ *
+ * <p>
+ * The PKI core requires {@code notAfter} to be strictly after
+ * {@code notBefore}. Framework-specific interpretations (inclusive/exclusive)
+ * are resolved by the framework backend.
+ * </p>
+ *
+ * <p>
+ * Policy and profile constraints (maximum lifetime, not-before skew) must be
+ * enforced by the PKI runtime.
+ * </p>
+ *
+ * @param notBefore start of validity interval (inclusive)
+ * @param notAfter  end of validity interval (must be after {@code notBefore})
+ */
+public record Validity(Instant notBefore, Instant notAfter) {
+
+    /**
+     * Creates a validity interval.
+     *
+     * @param notBefore start of validity interval (inclusive)
+     * @param notAfter  end of validity interval
+     * @throws IllegalArgumentException if inputs are null or the interval is
+     *                                  invalid
+     */
+    public Validity {
+        if (notBefore == null || notAfter == null) {
+            throw new IllegalArgumentException("notBefore/notAfter must not be null");
+        }
+        if (!notAfter.isAfter(notBefore)) {
+            throw new IllegalArgumentException("notAfter must be after notBefore");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeAccessPolicy.java

@@ -0,0 +1,65 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+import java.util.Set;
+
+/**
+ * Governance hints controlling auditing and exportability of an attribute.
+ *
+ * <p>
+ * This model is intentionally minimal. Implementations may interpret it via a
+ * richer policy decision point (roles, purposes, tenants), but the presence of
+ * these hints allows consistent enforcement and auditing.
+ * </p>
+ *
+ * @param auditOnAllow  if true, successful accesses should be audited
+ * @param auditOnDeny   if true, denied accesses should be audited
+ * @param exportTargets allowed export targets
+ */
+public record AttributeAccessPolicy(boolean auditOnAllow, boolean auditOnDeny,
+        Set<AttributeExportTarget> exportTargets) {
+
+    /**
+     * Creates an access policy.
+     *
+     * @throws IllegalArgumentException if {@code exportTargets} is null
+     */
+    public AttributeAccessPolicy {
+        if (exportTargets == null) {
+            throw new IllegalArgumentException("exportTargets must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeCatalogue.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Registry/catalogue of attribute definitions.
+ *
+ * <p>
+ * The catalogue is the shared vocabulary across credential frameworks.
+ * Identifiers must never be reused with a different meaning. Definitions should
+ * be versioned under a controlled process.
+ * </p>
+ */
+public interface AttributeCatalogue {
+
+    /**
+     * Finds a definition by id.
+     *
+     * @param id attribute id
+     * @return definition if present
+     * @throws IllegalArgumentException if {@code id} is null
+     */
+    Optional<AttributeDefinition> find(AttributeId id);
+
+    /**
+     * Lists all known definitions.
+     *
+     * @return list of definitions
+     */
+    List<AttributeDefinition> listAll();
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeDefinition.java

@@ -0,0 +1,75 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Typed and governed attribute definition used across credential frameworks.
+ *
+ * <p>
+ * The definition includes a stable identifier, type information, documentation
+ * metadata, and governance hints. Frameworks map universal attributes into
+ * framework-specific fields and extensions.
+ * </p>
+ *
+ * @param id           stable attribute identifier
+ * @param displayName  human-readable name
+ * @param valueType    logical value type
+ * @param multiValued  whether multiple values are allowed
+ * @param sensitivity  sensitivity classification
+ * @param stability    lifecycle maturity
+ * @param accessPolicy governance hints
+ * @param meta         structured documentation metadata
+ */
+public record AttributeDefinition(AttributeId id, String displayName, AttributeValueType valueType, boolean multiValued,
+        AttributeSensitivity sensitivity, AttributeStability stability, AttributeAccessPolicy accessPolicy,
+        AttributeMeta meta) {
+
+    /**
+     * Creates an attribute definition.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public AttributeDefinition {
+        if (id == null) {
+            throw new IllegalArgumentException("id must not be null");
+        }
+        if (displayName == null || displayName.isBlank()) {
+            throw new IllegalArgumentException("displayName must not be null/blank");
+        }
+        if (valueType == null || sensitivity == null || stability == null || accessPolicy == null || meta == null) {
+            throw new IllegalArgumentException("non-null fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeExportTarget.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Named export targets used by governance and publication pipelines.
+ */
+public enum AttributeExportTarget {
+
+    /**
+     * Export via a programmatic API.
+     */
+    API,
+
+    /**
+     * Export for UI rendering.
+     */
+    UI,
+
+    /**
+     * Export to LDAP directory.
+     */
+    LDAP,
+
+    /**
+     * Export to backups.
+     */
+    BACKUP,
+
+    /**
+     * Export to diagnostics/debugging channels (typically heavily redacted).
+     */
+    DIAGNOSTICS
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeId.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Stable attribute identifier used by the attribute catalogue.
+ *
+ * <p>
+ * Identifiers should be globally stable (recommended as OIDs under a project or
+ * enterprise arc). Identifiers must never be reused with a different semantic
+ * meaning.
+ * </p>
+ *
+ * @param value non-empty identifier string
+ */
+public record AttributeId(String value) {
+
+    /**
+     * Creates an attribute identifier.
+     *
+     * @param value non-empty identifier string
+     * @throws IllegalArgumentException if {@code value} is null or blank
+     */
+    public AttributeId {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeMeta.java

@@ -0,0 +1,81 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Structured, human-facing documentation metadata for an attribute definition.
+ *
+ * <p>
+ * This metadata is intended to be rendered in operator tooling, APIs, and UI.
+ * It must not contain secrets.
+ * </p>
+ *
+ * @param description normative description of meaning and usage
+ * @param notes       additional guidance and security considerations
+ * @param examples    example values (must not contain secrets)
+ * @param tags        classification tags (e.g., "identity", "x509", "san")
+ * @param extra       additional annotations for future extensions
+ *                    (non-sensitive)
+ */
+public record AttributeMeta(String description, List<String> notes, List<String> examples, List<String> tags,
+        Map<String, String> extra) {
+
+    /**
+     * Creates attribute metadata.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or collections/maps
+     *                                  are null
+     */
+    public AttributeMeta {
+        if (description == null || description.isBlank()) {
+            throw new IllegalArgumentException("description must not be null/blank");
+        }
+        if (notes == null) {
+            throw new IllegalArgumentException("notes must not be null");
+        }
+        if (examples == null) {
+            throw new IllegalArgumentException("examples must not be null");
+        }
+        if (tags == null) {
+            throw new IllegalArgumentException("tags must not be null");
+        }
+        if (extra == null) {
+            throw new IllegalArgumentException("extra must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeSensitivity.java

@@ -0,0 +1,67 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Data sensitivity classification for an attribute.
+ *
+ * <p>
+ * Sensitivity influences default auditing/export/redaction behavior.
+ * Implementations must ensure that SECRET and SENSITIVE values are not exposed
+ * to logs or unauthorized channels.
+ * </p>
+ */
+public enum AttributeSensitivity {
+
+    /**
+     * Public value; can be disclosed broadly.
+     */
+    PUBLIC,
+
+    /**
+     * Internal operational value; restricted to internal components and operators.
+     */
+    INTERNAL,
+
+    /**
+     * Sensitive value; disclosure may create security or privacy risk.
+     */
+    SENSITIVE,
+
+    /**
+     * Secret value; must not be disclosed outside the strictest trust boundary.
+     */
+    SECRET
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeSet.java

@@ -0,0 +1,82 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * Immutable set of typed attributes.
+ *
+ * <p>
+ * This is a passive container. Production code is expected to mediate
+ * read/write/export/derive operations through a governance/enforcement layer
+ * that performs ACL checks and emits audit events.
+ * </p>
+ */
+public interface AttributeSet {
+
+    /**
+     * Returns all attribute identifiers present in this set.
+     *
+     * @return set of attribute ids
+     */
+    Set<AttributeId> ids();
+
+    /**
+     * Reads a single-valued attribute.
+     *
+     * <p>
+     * If the attribute is multi-valued, implementations may return empty or one
+     * chosen value; callers should prefer {@link #getAll(AttributeId)} when
+     * multi-valued is expected.
+     * </p>
+     *
+     * @param id attribute id
+     * @return attribute value if present
+     * @throws IllegalArgumentException if {@code id} is null
+     */
+    Optional<AttributeValue> get(AttributeId id);
+
+    /**
+     * Reads a potentially multi-valued attribute.
+     *
+     * @param id attribute id
+     * @return list of values (empty if absent)
+     * @throws IllegalArgumentException if {@code id} is null
+     */
+    List<AttributeValue> getAll(AttributeId id);
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeStability.java

@@ -0,0 +1,57 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Lifecycle maturity of an attribute definition.
+ */
+public enum AttributeStability {
+
+    /**
+     * Attribute is stable and recommended for general use.
+     */
+    STABLE,
+
+    /**
+     * Attribute is experimental and may change under a controlled evolution
+     * process.
+     */
+    EXPERIMENTAL,
+
+    /**
+     * Attribute is deprecated and should not be used for new profiles.
+     */
+    DEPRECATED
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeValue.java

@@ -0,0 +1,131 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+import java.time.Instant;
+
+/**
+ * Typed attribute value.
+ *
+ * <p>
+ * Values are modeled as a sealed hierarchy for type safety and deterministic
+ * mapping. Implementations must treat values as potentially sensitive and apply
+ * redaction where required.
+ * </p>
+ */
+public sealed interface AttributeValue permits AttributeValue.StringValue, AttributeValue.BooleanValue,
+        AttributeValue.IntegerValue, AttributeValue.InstantValue, AttributeValue.BytesValue {
+
+    /**
+     * String value.
+     *
+     * @param value string content (may be empty depending on attribute definition)
+     */
+    record StringValue(String value) implements AttributeValue {
+
+        /**
+         * Creates a string value.
+         *
+         * @param value string content
+         * @throws IllegalArgumentException if {@code value} is null
+         */
+        public StringValue {
+            if (value == null) {
+                throw new IllegalArgumentException("value must not be null");
+            }
+        }
+    }
+
+    /**
+     * Boolean value.
+     *
+     * @param value boolean content
+     */
+    record BooleanValue(boolean value) implements AttributeValue {
+    }
+
+    /**
+     * Integer/long value.
+     *
+     * @param value numeric content
+     */
+    record IntegerValue(long value) implements AttributeValue {
+    }
+
+    /**
+     * Instant value.
+     *
+     * @param value timestamp content
+     */
+    record InstantValue(Instant value) implements AttributeValue {
+
+        /**
+         * Creates an instant value.
+         *
+         * @param value timestamp
+         * @throws IllegalArgumentException if {@code value} is null
+         */
+        public InstantValue {
+            if (value == null) {
+                throw new IllegalArgumentException("value must not be null");
+            }
+        }
+    }
+
+    /**
+     * Byte string value.
+     *
+     * <p>
+     * Byte values should be treated as potentially sensitive. Implementations must
+     * not log full contents.
+     * </p>
+     *
+     * @param value non-empty byte array
+     */
+    record BytesValue(byte[] value) implements AttributeValue {
+
+        /**
+         * Creates a byte string value.
+         *
+         * @param value byte array (non-empty)
+         * @throws IllegalArgumentException if {@code value} is null or empty
+         */
+        public BytesValue {
+            if (value == null || value.length == 0) {
+                throw new IllegalArgumentException("value must not be null/empty");
+            }
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/attr/AttributeValueType.java

@@ -0,0 +1,98 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.attr;
+
+/**
+ * Declares the logical value type of an attribute.
+ *
+ * <p>
+ * Framework backends map these logical types into framework-specific constructs
+ * (e.g., X.509 extensions, claims, or other credential fields).
+ * </p>
+ */
+public enum AttributeValueType {
+
+    /**
+     * UTF-8 string value.
+     */
+    STRING,
+
+    /**
+     * Boolean value.
+     */
+    BOOLEAN,
+
+    /**
+     * Integer/long value.
+     */
+    INTEGER,
+
+    /**
+     * Timestamp value.
+     */
+    INSTANT,
+
+    /**
+     * Raw byte string.
+     */
+    BYTES,
+
+    /**
+     * Object identifier string.
+     */
+    OID,
+
+    /**
+     * Distinguished Name representation (string form with normalization rules
+     * defined by profile/policy).
+     */
+    DN,
+
+    /**
+     * GeneralName-like identity (DNS/IP/URI/email/etc.) represented in a canonical
+     * structured form.
+     */
+    GENERAL_NAME,
+
+    /**
+     * Public key information representation (e.g., SPKI).
+     */
+    KEY_INFO,
+
+    /**
+     * Structured composite value.
+     */
+    STRUCT
+}

pki/src/main/java/zeroecho/pki/api/attr/package-info.java

@@ -0,0 +1,62 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Attribute catalogue and attribute-level modeling.
+ *
+ * <p>
+ * This package defines a typed attribute system used across the PKI API and
+ * independent of any specific credential framework. Attributes are described
+ * through definitions and metadata and carried in structured containers to
+ * support safe reuse and deterministic mapping into concrete frameworks (e.g.,
+ * via a framework attribute mapper SPI).
+ * </p>
+ *
+ * <h2>Typical responsibilities</h2>
+ * <ul>
+ * <li>Define attribute identity and value types.</li>
+ * <li>Provide metadata needed for validation and governance (stability,
+ * sensitivity, etc.).</li>
+ * <li>Support export/import targets without binding to a certificate
+ * format.</li>
+ * </ul>
+ *
+ * <p>
+ * Access control and governance for attribute access is described in
+ * {@code zeroecho.pki.api.audit}.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.attr;

pki/src/main/java/zeroecho/pki/api/audit/AccessAction.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+/**
+ * Action performed on an attribute for access governance.
+ */
+public enum AccessAction {
+
+    /**
+     * Read an attribute value.
+     */
+    READ,
+
+    /**
+     * Write or modify an attribute value.
+     */
+    WRITE,
+
+    /**
+     * Export attribute value to an external channel (e.g., UI, LDAP, backups).
+     */
+    EXPORT,
+
+    /**
+     * Derive/computed attribute value from other sources.
+     */
+    DERIVE
+}

pki/src/main/java/zeroecho/pki/api/audit/AccessContext.java

@@ -0,0 +1,74 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Context used for attribute ACL checks and audit correlation.
+ *
+ * @param principal actor requesting access
+ * @param purpose   declared purpose of access
+ * @param objectId  optional object id being accessed (credential id, request
+ *                  id, etc.)
+ * @param formatId  optional format id relevant to the object being accessed
+ */
+public record AccessContext(Principal principal, Purpose purpose, Optional<PkiId> objectId,
+        Optional<FormatId> formatId) {
+
+    /**
+     * Creates an access context.
+     *
+     * @throws IllegalArgumentException if mandatory inputs are null or optional
+     *                                  containers are null
+     */
+    public AccessContext {
+        if (principal == null) {
+            throw new IllegalArgumentException("principal must not be null");
+        }
+        if (purpose == null) {
+            throw new IllegalArgumentException("purpose must not be null");
+        }
+        if (objectId == null) {
+            throw new IllegalArgumentException("objectId must not be null");
+        }
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/audit/AccessDecision.java

@@ -0,0 +1,51 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+/**
+ * Decision outcome of an access control check.
+ */
+public enum AccessDecision {
+
+    /**
+     * Access is allowed.
+     */
+    ALLOW,
+
+    /**
+     * Access is denied.
+     */
+    DENY
+}

pki/src/main/java/zeroecho/pki/api/audit/AttributeAccessController.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import zeroecho.pki.api.attr.AttributeDefinition;
+
+/**
+ * Policy decision point for attribute-level access control.
+ *
+ * <p>
+ * This interface decides whether an attribute action is permitted given the
+ * attribute definition and the access context. A separate enforcement layer is
+ * expected to record audit events.
+ * </p>
+ */
+@FunctionalInterface
+public interface AttributeAccessController {
+
+    /**
+     * Evaluates an access request.
+     *
+     * @param definition attribute definition
+     * @param action     access action
+     * @param context    access context
+     * @return allow/deny decision
+     * @throws IllegalArgumentException if inputs are null
+     */
+    AccessDecision decide(AttributeDefinition definition, AccessAction action, AccessContext context);
+}

pki/src/main/java/zeroecho/pki/api/audit/AttributeGovernanceService.java

@@ -0,0 +1,118 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.attr.AttributeCatalogue;
+import zeroecho.pki.api.attr.AttributeId;
+import zeroecho.pki.api.attr.AttributeSet;
+import zeroecho.pki.api.attr.AttributeValue;
+
+/**
+ * Policy enforcement point for attribute access with mandatory auditing.
+ *
+ * <p>
+ * All attribute read/write/export/derive operations should be performed through
+ * this service to ensure: (1) consistent ACL evaluation and (2) consistent
+ * audit event emission.
+ * </p>
+ */
+public interface AttributeGovernanceService {
+
+    /**
+     * Reads an attribute value after applying access control.
+     *
+     * @param catalogue attribute catalogue used to resolve definitions
+     * @param set       attribute set being accessed
+     * @param id        attribute id
+     * @param context   access context
+     * @return value if present and access is allowed; empty otherwise
+     * @throws IllegalArgumentException if inputs are null
+     */
+    Optional<AttributeValue> read(AttributeCatalogue catalogue, AttributeSet set, AttributeId id,
+            AccessContext context);
+
+    /**
+     * Writes an attribute value after applying access control.
+     *
+     * @param catalogue attribute catalogue used to resolve definitions
+     * @param set       attribute set being modified
+     * @param id        attribute id
+     * @param value     value to write
+     * @param context   access context
+     * @return new attribute set instance containing the updated value
+     * @throws IllegalArgumentException if inputs are null
+     */
+    AttributeSet write(AttributeCatalogue catalogue, AttributeSet set, AttributeId id, AttributeValue value,
+            AccessContext context);
+
+    /**
+     * Exports an attribute value after applying access control.
+     *
+     * <p>
+     * Export may imply redaction. The exact redaction rules are
+     * implementation-defined and should take attribute sensitivity and export
+     * target into account.
+     * </p>
+     *
+     * @param catalogue attribute catalogue used to resolve definitions
+     * @param set       attribute set being exported from
+     * @param id        attribute id
+     * @param context   access context
+     * @return exported value if present and allowed; empty otherwise
+     * @throws IllegalArgumentException if inputs are null
+     */
+    Optional<AttributeValue> export(AttributeCatalogue catalogue, AttributeSet set, AttributeId id,
+            AccessContext context);
+
+    /**
+     * Derives an attribute value from other inputs after applying access control.
+     *
+     * <p>
+     * Derivation may be used to compute attributes such as fingerprints or
+     * normalized identity fields.
+     * </p>
+     *
+     * @param catalogue attribute catalogue used to resolve definitions
+     * @param set       attribute set being modified
+     * @param id        attribute id
+     * @param context   access context
+     * @return new attribute set instance containing the derived value
+     *         (implementation-defined)
+     * @throws IllegalArgumentException if inputs are null
+     */
+    AttributeSet derive(AttributeCatalogue catalogue, AttributeSet set, AttributeId id, AccessContext context);
+}

pki/src/main/java/zeroecho/pki/api/audit/AuditEvent.java

@@ -0,0 +1,99 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Auditable event emitted by the PKI core.
+ *
+ * <p>
+ * Audit events may represent high-level PKI operations (issuance, revocation,
+ * publication, backup) and attribute access governance outcomes.
+ * Implementations must ensure no secrets appear in {@code details}.
+ * </p>
+ *
+ * @param time      event time (server time)
+ * @param category  non-empty category (e.g., "ISSUANCE", "REVOCATION",
+ *                  "ATTRIBUTE_ACCESS")
+ * @param action    non-empty action string (e.g., "ISSUE_END_ENTITY", "REVOKE",
+ *                  "READ")
+ * @param principal actor responsible for the event
+ * @param purpose   purpose of the operation/access
+ * @param objectId  optional subject object id (credential id, request id, etc.)
+ * @param formatId  optional format id related to the object
+ * @param details   additional non-sensitive key/value details
+ */
+public record AuditEvent(Instant time, String category, String action, Principal principal, Purpose purpose,
+        Optional<PkiId> objectId, Optional<FormatId> formatId, Map<String, String> details) {
+
+    /**
+     * Creates an audit event.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional
+     *                                  containers/maps are null
+     */
+    public AuditEvent {
+        if (time == null) {
+            throw new IllegalArgumentException("time must not be null");
+        }
+        if (category == null || category.isBlank()) {
+            throw new IllegalArgumentException("category must not be null/blank");
+        }
+        if (action == null || action.isBlank()) {
+            throw new IllegalArgumentException("action must not be null/blank");
+        }
+        if (principal == null) {
+            throw new IllegalArgumentException("principal must not be null");
+        }
+        if (purpose == null) {
+            throw new IllegalArgumentException("purpose must not be null");
+        }
+        if (objectId == null) {
+            throw new IllegalArgumentException("objectId must not be null");
+        }
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (details == null) {
+            throw new IllegalArgumentException("details must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/audit/AuditQuery.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import java.time.Instant;
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Query constraints for searching audit events.
+ *
+ * @param category      optional category filter
+ * @param action        optional action filter
+ * @param after         optional lower bound for event time
+ * @param before        optional upper bound for event time
+ * @param objectId      optional object id filter
+ * @param principalName optional principal name filter
+ */
+public record AuditQuery(Optional<String> category, Optional<String> action, Optional<Instant> after,
+        Optional<Instant> before, Optional<PkiId> objectId, Optional<String> principalName) {
+
+    /**
+     * Creates an audit query.
+     *
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public AuditQuery {
+        if (category == null || action == null || after == null || before == null || objectId == null
+                || principalName == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/audit/AuditService.java

@@ -0,0 +1,80 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Records and queries audit events for PKI operations and attribute governance.
+ *
+ * <p>
+ * Implementations must ensure sensitive data is never stored or logged in clear
+ * text.
+ * </p>
+ */
+public interface AuditService {
+
+    /**
+     * Records an audit event.
+     *
+     * @param event audit event
+     * @throws IllegalArgumentException if {@code event} is null
+     * @throws RuntimeException         if recording fails (implementation-defined)
+     */
+    void record(AuditEvent event);
+
+    /**
+     * Searches audit events by query constraints.
+     *
+     * @param query query constraints
+     * @return matching audit events
+     * @throws IllegalArgumentException if {@code query} is null
+     * @throws RuntimeException         if search fails
+     */
+    List<AuditEvent> search(AuditQuery query);
+
+    /**
+     * Retrieves an audit event by id if the implementation assigns stable ids.
+     *
+     * @param eventId event id
+     * @return audit event if present
+     * @throws IllegalArgumentException if {@code eventId} is null
+     * @throws RuntimeException         if retrieval fails
+     */
+    Optional<AuditEvent> get(PkiId eventId);
+}

pki/src/main/java/zeroecho/pki/api/audit/Principal.java

@@ -0,0 +1,63 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+/**
+ * Identifies an actor performing an operation or requesting access.
+ *
+ * <p>
+ * A principal may represent a human user, service account, subsystem component,
+ * or a scheduled job.
+ * </p>
+ *
+ * @param type principal type (e.g., "USER", "SERVICE", "COMPONENT")
+ * @param name principal name/identifier
+ */
+public record Principal(String type, String name) {
+
+    /**
+     * Creates a principal.
+     *
+     * @throws IllegalArgumentException if inputs are null/blank
+     */
+    public Principal {
+        if (type == null || type.isBlank()) {
+            throw new IllegalArgumentException("type must not be null/blank");
+        }
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("name must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/audit/Purpose.java

@@ -0,0 +1,59 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.audit;
+
+/**
+ * Declares the purpose of an operation/access for governance and auditing.
+ *
+ * <p>
+ * Examples: {@code ISSUANCE}, {@code VALIDATION}, {@code UI_RENDER},
+ * {@code BACKUP_EXPORT}, {@code LDAP_PUBLISH}.
+ * </p>
+ *
+ * @param value non-empty purpose string
+ */
+public record Purpose(String value) {
+
+    /**
+     * Creates a purpose.
+     *
+     * @throws IllegalArgumentException if {@code value} is null/blank
+     */
+    public Purpose {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("value must not be null/blank");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/audit/package-info.java

@@ -0,0 +1,59 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Audit and governance API.
+ *
+ * <p>
+ * This package defines audit events, principals, purposes, queries, and
+ * attribute-access governance abstractions used to support compliance and
+ * operational forensics.
+ * </p>
+ *
+ * <h2>Security</h2>
+ * <ul>
+ * <li>Audit events MUST NOT contain private keys, shared secrets, or plaintext
+ * sensitive content.</li>
+ * <li>Audit records should be structured and stable for long-term retention and
+ * analysis.</li>
+ * </ul>
+ *
+ * <p>
+ * The persistence and routing of audit events is an SPI concern (e.g.,
+ * {@code zeroecho.pki.spi.AuditSink}).
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.audit;

pki/src/main/java/zeroecho/pki/api/backup/BackupArtifact.java

@@ -0,0 +1,69 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.backup;
+
+import zeroecho.pki.api.BackupService;
+import zeroecho.pki.api.EncodedObject;
+import zeroecho.pki.api.Encoding;
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Opaque backup artifact produced by {@link BackupService}.
+ *
+ * <p>
+ * The payload is typically {@link Encoding#BINARY}. The internal structure is
+ * implementation-defined (e.g., tar/zip-like). Consumers should treat it as
+ * opaque.
+ * </p>
+ *
+ * @param backupId backup identifier
+ * @param payload  backup payload bytes
+ */
+public record BackupArtifact(PkiId backupId, EncodedObject payload) {
+
+    /**
+     * Creates a backup artifact.
+     *
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public BackupArtifact {
+        if (backupId == null) {
+            throw new IllegalArgumentException("backupId must not be null");
+        }
+        if (payload == null) {
+            throw new IllegalArgumentException("payload must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/backup/BackupRequest.java

@@ -0,0 +1,68 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.backup;
+
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Requests creation of a PKI backup.
+ *
+ * <p>
+ * Backups are expected to contain PKI state (CAs, credentials, requests,
+ * revocations, profiles, publication records, policy traces). Private keys are
+ * excluded and referenced via {@link KeyRef}.
+ * </p>
+ *
+ * @param label      operator-provided label for human identification
+ * @param attributes optional backup metadata (may be empty but not null)
+ */
+public record BackupRequest(String label, AttributeSet attributes) {
+
+    /**
+     * Creates a backup request.
+     *
+     * @throws IllegalArgumentException if {@code label} is null/blank or
+     *                                  {@code attributes} is null
+     */
+    public BackupRequest {
+        if (label == null || label.isBlank()) {
+            throw new IllegalArgumentException("label must not be null/blank");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/backup/BackupVerificationReport.java

@@ -0,0 +1,58 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.backup;
+
+import java.util.List;
+
+/**
+ * Verification results for a backup artifact.
+ *
+ * @param valid  true if the artifact is structurally valid and integrity checks
+ *               passed
+ * @param issues list of issues found (non-sensitive)
+ */
+public record BackupVerificationReport(boolean valid, List<String> issues) {
+
+    /**
+     * Creates a backup verification report.
+     *
+     * @throws IllegalArgumentException if {@code issues} is null
+     */
+    public BackupVerificationReport {
+        if (issues == null) {
+            throw new IllegalArgumentException("issues must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/backup/RestoreReport.java

@@ -0,0 +1,68 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.backup;
+
+import java.util.List;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Result report for a restore operation.
+ *
+ * @param restoreId restore identifier
+ * @param success   true if restore completed successfully
+ * @param warnings  operator-readable warnings (non-sensitive)
+ * @param errors    operator-readable errors (non-sensitive)
+ */
+public record RestoreReport(PkiId restoreId, boolean success, List<String> warnings, List<String> errors) {
+
+    /**
+     * Creates a restore report.
+     *
+     * @throws IllegalArgumentException if {@code restoreId} is null or lists are
+     *                                  null
+     */
+    public RestoreReport {
+        if (restoreId == null) {
+            throw new IllegalArgumentException("restoreId must not be null");
+        }
+        if (warnings == null) {
+            throw new IllegalArgumentException("warnings must not be null");
+        }
+        if (errors == null) {
+            throw new IllegalArgumentException("errors must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/backup/RestoreRequest.java

@@ -0,0 +1,60 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.backup;
+
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Requests restore of PKI state from a backup artifact.
+ *
+ * @param artifact   backup artifact
+ * @param attributes optional restore hints (may be empty but not null)
+ */
+public record RestoreRequest(BackupArtifact artifact, AttributeSet attributes) {
+
+    /**
+     * Creates a restore request.
+     *
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public RestoreRequest {
+        if (artifact == null) {
+            throw new IllegalArgumentException("artifact must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/backup/package-info.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Backup and restore domain model.
+ *
+ * <p>
+ * This package provides request/response and artifact model types used for
+ * backing up and restoring PKI state. The intent is to support offline escrow,
+ * migration, disaster recovery, and integrity verification workflows.
+ * </p>
+ *
+ * <h2>Scope</h2>
+ * <ul>
+ * <li>Backup artifacts describe exported PKI state suitable for durable
+ * storage.</li>
+ * <li>Verification reports provide evidence that backups are structurally valid
+ * and complete.</li>
+ * <li>Restore requests and reports model controlled restoration
+ * operations.</li>
+ * </ul>
+ *
+ * <p>
+ * Concrete serialization formats and transport mechanisms are handled by
+ * services and the transfer layer.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.backup;

pki/src/main/java/zeroecho/pki/api/ca/CaCreateCommand.java

@@ -0,0 +1,86 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to create a new root CA entity and issue its initial CA credential.
+ *
+ * <p>
+ * If {@code keyRef} is absent, the runtime may generate a new key pair
+ * depending on policy and runtime wiring. This command carries universal
+ * {@code attributes} used by policy and mapping.
+ * </p>
+ *
+ * @param formatId   target credential format
+ * @param subjectRef normalized CA subject reference
+ * @param profileId  profile id governing issuance and mapping
+ * @param keyRef     optional existing key reference; empty requests key
+ *                   generation
+ * @param attributes universal attributes (may be empty but not null)
+ */
+public record CaCreateCommand(FormatId formatId, SubjectRef subjectRef, String profileId, Optional<KeyRef> keyRef,
+        AttributeSet attributes) {
+
+    /**
+     * Creates a CA create command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public CaCreateCommand {
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (keyRef == null) {
+            throw new IllegalArgumentException("keyRef must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaImportCommand.java

@@ -0,0 +1,86 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import zeroecho.pki.api.EncodedObject;
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to import an existing root CA credential into PKI inventory.
+ *
+ * <p>
+ * This operation registers a CA entity and associates it with an externally
+ * managed key reference.
+ * </p>
+ *
+ * @param formatId             credential format id
+ * @param subjectRef           normalized CA subject reference
+ * @param profileId            profile id for mapping/constraints
+ * @param keyRef               reference to private key material
+ * @param existingCaCredential existing CA credential payload (certificate-like)
+ * @param attributes           universal attributes (may be empty but not null)
+ */
+public record CaImportCommand(FormatId formatId, SubjectRef subjectRef, String profileId, KeyRef keyRef,
+        EncodedObject existingCaCredential, AttributeSet attributes) {
+
+    /**
+     * Creates a CA import command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public CaImportCommand {
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (keyRef == null) {
+            throw new IllegalArgumentException("keyRef must not be null");
+        }
+        if (existingCaCredential == null) {
+            throw new IllegalArgumentException("existingCaCredential must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaKeyRotationCommand.java

@@ -0,0 +1,83 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to rotate a CA key reference and issue new corresponding CA
+ * credentials.
+ *
+ * <p>
+ * Key rotation changes the underlying key material. Historical key references
+ * and credentials must remain discoverable for audit and validation of
+ * previously issued credentials.
+ * </p>
+ *
+ * @param caId       CA entity id
+ * @param newKeyRef  optional new key reference; empty requests key generation
+ *                   via runtime wiring
+ * @param issuerCaId optional issuer CA id (required for intermediate rotation;
+ *                   empty for root depending on policy)
+ * @param attributes universal attributes (may be empty but not null)
+ */
+public record CaKeyRotationCommand(PkiId caId, Optional<KeyRef> newKeyRef, Optional<PkiId> issuerCaId,
+        AttributeSet attributes) {
+
+    /**
+     * Creates a CA key rotation command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional containers
+     *                                  are null
+     */
+    public CaKeyRotationCommand {
+        if (caId == null) {
+            throw new IllegalArgumentException("caId must not be null");
+        }
+        if (newKeyRef == null) {
+            throw new IllegalArgumentException("newKeyRef must not be null");
+        }
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaKind.java

@@ -0,0 +1,51 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+/**
+ * Classifies CA entity type.
+ */
+public enum CaKind {
+
+    /**
+     * Root CA (initial credential is typically self-issued).
+     */
+    ROOT,
+
+    /**
+     * Intermediate CA (issued by another CA).
+     */
+    INTERMEDIATE
+}

pki/src/main/java/zeroecho/pki/api/ca/CaQuery.java

@@ -0,0 +1,64 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.SubjectRef;
+
+/**
+ * Query constraints for listing CA entities.
+ *
+ * @param kind       optional CA kind filter
+ * @param state      optional state filter
+ * @param formatId   optional framework filter (implementation-defined; may map
+ *                   to CA credential format)
+ * @param subjectRef optional subject filter
+ */
+public record CaQuery(Optional<CaKind> kind, Optional<CaState> state, Optional<FormatId> formatId,
+        Optional<SubjectRef> subjectRef) {
+
+    /**
+     * Creates a CA query.
+     *
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public CaQuery {
+        if (kind == null || state == null || formatId == null || subjectRef == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaRecord.java

@@ -0,0 +1,93 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.List;
+
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.credential.Credential;
+
+/**
+ * Represents a CA entity and its issued CA credentials.
+ *
+ * <p>
+ * A CA entity may have multiple CA credentials to support:
+ * </p>
+ * <ul>
+ * <li>cross-signing (multiple issuers for the same subject key),</li>
+ * <li>credential rollover (new CA credential with the same key),</li>
+ * <li>key rotation (new CA key with a new set of credentials).</li>
+ * </ul>
+ *
+ * @param caId          CA identifier
+ * @param kind          CA kind (root or intermediate)
+ * @param state         operational state
+ * @param issuerKeyRef  key reference used for issuing operations (private key
+ *                      reference)
+ * @param subjectRef    normalized subject reference
+ * @param caCredentials CA credentials currently associated with the entity
+ *                      (historical and active)
+ */
+public record CaRecord(PkiId caId, CaKind kind, CaState state, KeyRef issuerKeyRef, SubjectRef subjectRef,
+        List<Credential> caCredentials) {
+
+    /**
+     * Creates a CA record.
+     *
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public CaRecord {
+        if (caId == null) {
+            throw new IllegalArgumentException("caId must not be null");
+        }
+        if (kind == null) {
+            throw new IllegalArgumentException("kind must not be null");
+        }
+        if (state == null) {
+            throw new IllegalArgumentException("state must not be null");
+        }
+        if (issuerKeyRef == null) {
+            throw new IllegalArgumentException("issuerKeyRef must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (caCredentials == null) {
+            throw new IllegalArgumentException("caCredentials must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaRolloverCommand.java

@@ -0,0 +1,81 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to roll over a CA credential while keeping the same key reference.
+ *
+ * <p>
+ * Rollover issues a new CA credential for the CA entity without changing the
+ * underlying key material. Historical credentials remain accessible for audit
+ * and chain selection.
+ * </p>
+ *
+ * @param caId              CA entity id
+ * @param issuerCaId        optional issuer CA id (empty for self-issued root
+ *                          rollover where applicable)
+ * @param requestedValidity optional requested validity
+ * @param attributes        universal attributes (may be empty but not null)
+ */
+public record CaRolloverCommand(PkiId caId, Optional<PkiId> issuerCaId, Optional<Validity> requestedValidity,
+        AttributeSet attributes) {
+
+    /**
+     * Creates a CA rollover command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional containers
+     *                                  are null
+     */
+    public CaRolloverCommand {
+        if (caId == null) {
+            throw new IllegalArgumentException("caId must not be null");
+        }
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (requestedValidity == null) {
+            throw new IllegalArgumentException("requestedValidity must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/CaState.java

@@ -0,0 +1,75 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+/**
+ * Operational state of a CA entity.
+ */
+public enum CaState {
+
+    /**
+     * CA is active and may issue new credentials according to policy.
+     */
+    ACTIVE,
+
+    /**
+     * CA is retired and must not issue new credentials.
+     *
+     * <p>
+     * Historical credentials remain available for validation and audit until they
+     * expire or are revoked.
+     * </p>
+     */
+    RETIRED,
+
+    /**
+     * CA is compromised and must not be used for issuance.
+     *
+     * <p>
+     * Operators should perform incident response, publish updated status objects,
+     * and rotate trust anchors.
+     * </p>
+     */
+    COMPROMISED,
+
+    /**
+     * CA is administratively disabled.
+     *
+     * <p>
+     * This state is distinct from retirement and may be reversible.
+     * </p>
+     */
+    DISABLED
+}

pki/src/main/java/zeroecho/pki/api/ca/IntermediateCertIssueCommand.java

@@ -0,0 +1,90 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to issue a new CA credential for an existing intermediate CA entity.
+ *
+ * <p>
+ * This command supports cross-signing (issuing with a different issuer CA) and
+ * renewal scenarios.
+ * </p>
+ *
+ * @param formatId          credential format id
+ * @param issuerCaId        issuer CA entity id
+ * @param subjectCaId       subject CA entity id (the intermediate being
+ *                          certified)
+ * @param profileId         profile id governing issuance
+ * @param requestedValidity optional requested validity (policy may
+ *                          override/deny)
+ * @param attributes        universal attributes (may be empty but not null)
+ */
+public record IntermediateCertIssueCommand(FormatId formatId, PkiId issuerCaId, PkiId subjectCaId, String profileId,
+        Optional<Validity> requestedValidity, AttributeSet attributes) {
+
+    /**
+     * Creates an intermediate CA credential issuance command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public IntermediateCertIssueCommand {
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (subjectCaId == null) {
+            throw new IllegalArgumentException("subjectCaId must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (requestedValidity == null) {
+            throw new IllegalArgumentException("requestedValidity must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/IntermediateCreateCommand.java

@@ -0,0 +1,86 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.ca;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.KeyRef;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to create a new intermediate CA entity and issue its initial CA
+ * credential.
+ *
+ * @param formatId   credential format id
+ * @param issuerCaId issuer CA entity id
+ * @param subjectRef normalized subject reference for the intermediate
+ * @param profileId  profile id governing issuance
+ * @param keyRef     optional existing key reference; empty requests key
+ *                   generation
+ * @param attributes universal attributes (may be empty but not null)
+ */
+public record IntermediateCreateCommand(FormatId formatId, PkiId issuerCaId, SubjectRef subjectRef, String profileId,
+        Optional<KeyRef> keyRef, AttributeSet attributes) {
+
+    /**
+     * Creates an intermediate create command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public IntermediateCreateCommand {
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (keyRef == null) {
+            throw new IllegalArgumentException("keyRef must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/ca/package-info.java

@@ -0,0 +1,60 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Certificate Authority (CA) domain model.
+ *
+ * <p>
+ * This package contains CA records, lifecycle state, CA kinds, and CA-related
+ * commands and queries. It models root and intermediate CA management,
+ * including creation, import, rollover, and key rotation operations.
+ * </p>
+ *
+ * <h2>Responsibilities</h2>
+ * <ul>
+ * <li>Represent CA identity and state through records and enums.</li>
+ * <li>Define CA management commands used by
+ * {@link zeroecho.pki.api.CaService}.</li>
+ * <li>Support intermediate CA creation and intermediate certificate
+ * issuance.</li>
+ * </ul>
+ *
+ * <p>
+ * Concrete certificate framework specifics are delegated to framework
+ * integrations.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.ca;

pki/src/main/java/zeroecho/pki/api/credential/Credential.java

@@ -0,0 +1,117 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.credential;
+
+import zeroecho.pki.api.EncodedObject;
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.IssuerRef;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Issued credential with mandatory core metadata and universal attributes.
+ *
+ * <p>
+ * The PKI core does not assume X.509 semantics. The {@code serialOrUniqueId}
+ * field maps to X.509 serial numbers when applicable, but can represent another
+ * framework's unique identifier.
+ * </p>
+ *
+ * <p>
+ * The {@code publicKeyId} is intended to group multiple credentials for the
+ * same key (e.g., cross-signing, migrations, or parallel classical/PQC chains).
+ * </p>
+ *
+ * @param credentialId     stable identifier for the credential (typically a
+ *                         fingerprint of encoded bytes)
+ * @param formatId         framework identifier
+ * @param issuerRef        issuing CA reference
+ * @param subjectRef       normalized subject reference
+ * @param validity         validity interval
+ * @param serialOrUniqueId framework-specific unique identifier (serial for
+ *                         X.509)
+ * @param publicKeyId      stable identifier derived from the subject public key
+ * @param profileId        profile governing issuance
+ * @param status           inventory status
+ * @param encoded          encoded credential bytes
+ * @param attributes       universal attribute set
+ */
+public record Credential(PkiId credentialId, FormatId formatId, IssuerRef issuerRef, SubjectRef subjectRef,
+        Validity validity, String serialOrUniqueId, PkiId publicKeyId, String profileId, CredentialStatus status,
+        EncodedObject encoded, AttributeSet attributes) {
+
+    /**
+     * Creates a credential record.
+     *
+     * @throws IllegalArgumentException if mandatory inputs are invalid
+     */
+    public Credential {
+        if (credentialId == null) {
+            throw new IllegalArgumentException("credentialId must not be null");
+        }
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (issuerRef == null) {
+            throw new IllegalArgumentException("issuerRef must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (validity == null) {
+            throw new IllegalArgumentException("validity must not be null");
+        }
+        if (serialOrUniqueId == null || serialOrUniqueId.isBlank()) {
+            throw new IllegalArgumentException("serialOrUniqueId must not be null/blank");
+        }
+        if (publicKeyId == null) {
+            throw new IllegalArgumentException("publicKeyId must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (status == null) {
+            throw new IllegalArgumentException("status must not be null");
+        }
+        if (encoded == null) {
+            throw new IllegalArgumentException("encoded must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/credential/CredentialBundle.java

@@ -0,0 +1,70 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.credential;
+
+import java.util.List;
+
+import zeroecho.pki.api.EncodedObject;
+
+/**
+ * Bundle of a primary credential and supporting objects.
+ *
+ * <p>
+ * Supporting objects enable distribution and validation. For X.509 these are
+ * typically chain certificates. Frameworks may define additional supporting
+ * artifacts.
+ * </p>
+ *
+ * @param credential        primary credential
+ * @param supportingObjects supporting artifacts (framework-defined ordering)
+ */
+public record CredentialBundle(Credential credential, List<EncodedObject> supportingObjects) {
+
+    /**
+     * Creates a bundle.
+     *
+     * @param credential        primary credential
+     * @param supportingObjects supporting artifacts (non-null, may be empty)
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public CredentialBundle {
+        if (credential == null) {
+            throw new IllegalArgumentException("credential must not be null");
+        }
+        if (supportingObjects == null) {
+            throw new IllegalArgumentException("supportingObjects must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/credential/CredentialQuery.java

@@ -0,0 +1,70 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.credential;
+
+import java.time.Instant;
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.SubjectRef;
+
+/**
+ * Query constraints for searching credentials in inventory.
+ *
+ * @param formatId    optional framework filter
+ * @param issuerCaId  optional issuer CA filter
+ * @param subjectRef  optional subject filter
+ * @param profileId   optional profile filter
+ * @param status      optional status filter
+ * @param publicKeyId optional public key grouping filter
+ * @param validAt     optional evaluation time for validity-based filtering
+ */
+public record CredentialQuery(Optional<FormatId> formatId, Optional<PkiId> issuerCaId, Optional<SubjectRef> subjectRef,
+        Optional<String> profileId, Optional<CredentialStatus> status, Optional<PkiId> publicKeyId,
+        Optional<Instant> validAt) {
+
+    /**
+     * Creates a credential query.
+     *
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public CredentialQuery {
+        if (formatId == null || issuerCaId == null || subjectRef == null || profileId == null || status == null
+                || publicKeyId == null || validAt == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/credential/CredentialStatus.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.credential;
+
+/**
+ * Status of a credential as tracked by PKI inventory.
+ *
+ * <p>
+ * Status may be computed from validity and revocation state or stored directly
+ * depending on implementation.
+ * </p>
+ */
+public enum CredentialStatus {
+
+    /**
+     * Credential is issued and not revoked. Validity may still expire later.
+     */
+    ISSUED,
+
+    /**
+     * Credential is revoked.
+     */
+    REVOKED,
+
+    /**
+     * Credential validity interval has ended.
+     */
+    EXPIRED
+}

pki/src/main/java/zeroecho/pki/api/credential/package-info.java

@@ -0,0 +1,53 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Credential inventory domain model.
+ *
+ * <p>
+ * This package defines the model types representing issued credentials and
+ * their inventory view, including status tracking and query objects. It is used
+ * by {@link zeroecho.pki.api.CredentialInventoryService}.
+ * </p>
+ *
+ * <h2>Notes</h2>
+ * <ul>
+ * <li>Credentials are treated as immutable artifacts once issued.</li>
+ * <li>Status values capture the operational lifecycle (e.g., issued, expired,
+ * revoked, on hold).</li>
+ * </ul>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.credential;

pki/src/main/java/zeroecho/pki/api/issuance/BundleCommand.java

@@ -0,0 +1,76 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Command to build a distributable bundle for an existing credential.
+ *
+ * <p>
+ * Bundles are constructed using chain selection rules, trust anchor selection,
+ * and optional compatibility profiles. This is especially relevant for
+ * cross-signing and migration scenarios.
+ * </p>
+ *
+ * @param credentialId           credential id
+ * @param preferredTrustAnchorId optional preferred trust anchor id
+ *                               (implementation-defined)
+ * @param compatibilityProfileId optional compatibility profile id influencing
+ *                               chain selection
+ */
+public record BundleCommand(PkiId credentialId, Optional<PkiId> preferredTrustAnchorId,
+        Optional<String> compatibilityProfileId) {
+
+    /**
+     * Creates a bundle command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional containers
+     *                                  are null
+     */
+    public BundleCommand {
+        if (credentialId == null) {
+            throw new IllegalArgumentException("credentialId must not be null");
+        }
+        if (preferredTrustAnchorId == null) {
+            throw new IllegalArgumentException("preferredTrustAnchorId must not be null");
+        }
+        if (compatibilityProfileId == null) {
+            throw new IllegalArgumentException("compatibilityProfileId must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/IssuanceInputs.java

@@ -0,0 +1,72 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+import zeroecho.pki.api.request.ParsedCertificationRequest;
+
+/**
+ * Normalized inputs for issuance policy evaluation.
+ *
+ * @param issuerCaId         issuer CA entity id
+ * @param request            parsed certification request
+ * @param profileId          profile id selected for issuance
+ * @param requestedOverrides user-requested overrides (may be empty but not
+ *                           null)
+ */
+public record IssuanceInputs(PkiId issuerCaId, ParsedCertificationRequest request, String profileId,
+        AttributeSet requestedOverrides) {
+
+    /**
+     * Creates issuance inputs for policy evaluation.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public IssuanceInputs {
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (request == null) {
+            throw new IllegalArgumentException("request must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (requestedOverrides == null) {
+            throw new IllegalArgumentException("requestedOverrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/IssueEndEntityCommand.java

@@ -0,0 +1,82 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+import zeroecho.pki.api.request.ParsedCertificationRequest;
+
+/**
+ * Command to issue an end-entity credential from a parsed certification
+ * request.
+ *
+ * @param issuerCaId       issuer CA entity id
+ * @param request          parsed certification request
+ * @param profileId        profile id governing issuance
+ * @param validityOverride optional requested validity override
+ *                         (policy-validated)
+ * @param overrides        additional universal attribute overrides
+ *                         (policy-validated; may be empty but not null)
+ */
+public record IssueEndEntityCommand(PkiId issuerCaId, ParsedCertificationRequest request, String profileId,
+        Optional<Validity> validityOverride, AttributeSet overrides) {
+
+    /**
+     * Creates an issuance command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public IssueEndEntityCommand {
+        if (issuerCaId == null) {
+            throw new IllegalArgumentException("issuerCaId must not be null");
+        }
+        if (request == null) {
+            throw new IllegalArgumentException("request must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (validityOverride == null) {
+            throw new IllegalArgumentException("validityOverride must not be null");
+        }
+        if (overrides == null) {
+            throw new IllegalArgumentException("overrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/ReissueCommand.java

@@ -0,0 +1,68 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to reissue based on a stored issuance record.
+ *
+ * <p>
+ * The meaning of "issuance record" is implementation-defined (it may be derived
+ * from audit/store metadata). Reissue is useful for reproducing issuance under
+ * controlled changes.
+ * </p>
+ *
+ * @param issuanceRecordId issuance record id
+ * @param overrides        universal attribute overrides (policy-validated; may
+ *                         be empty but not null)
+ */
+public record ReissueCommand(PkiId issuanceRecordId, AttributeSet overrides) {
+
+    /**
+     * Creates a reissue command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public ReissueCommand {
+        if (issuanceRecordId == null) {
+            throw new IllegalArgumentException("issuanceRecordId must not be null");
+        }
+        if (overrides == null) {
+            throw new IllegalArgumentException("overrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/RenewCommand.java

@@ -0,0 +1,76 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to renew an existing credential.
+ *
+ * <p>
+ * Renewal typically retains continuity (same identity and key constraints)
+ * under policy-defined semantics. The implementation decides what "renew" means
+ * for a given framework and profile.
+ * </p>
+ *
+ * @param existingCredentialId credential id to renew
+ * @param validityOverride     optional validity override (policy-validated)
+ * @param overrides            universal attribute overrides (policy-validated;
+ *                             may be empty but not null)
+ */
+public record RenewCommand(PkiId existingCredentialId, Optional<Validity> validityOverride, AttributeSet overrides) {
+
+    /**
+     * Creates a renewal command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public RenewCommand {
+        if (existingCredentialId == null) {
+            throw new IllegalArgumentException("existingCredentialId must not be null");
+        }
+        if (validityOverride == null) {
+            throw new IllegalArgumentException("validityOverride must not be null");
+        }
+        if (overrides == null) {
+            throw new IllegalArgumentException("overrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/ReplaceCommand.java

@@ -0,0 +1,78 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+import zeroecho.pki.api.request.ParsedCertificationRequest;
+
+/**
+ * Command to replace an existing credential.
+ *
+ * <p>
+ * Replacement is used for scenarios such as compromise or identity attribute
+ * changes. Policy determines whether replacement is permitted and what
+ * continuity constraints apply.
+ * </p>
+ *
+ * @param existingCredentialId existing credential id
+ * @param newRequest           new parsed request for the replacement credential
+ * @param profileId            profile id governing issuance
+ * @param overrides            universal attribute overrides (policy-validated;
+ *                             may be empty but not null)
+ */
+public record ReplaceCommand(PkiId existingCredentialId, ParsedCertificationRequest newRequest, String profileId,
+        AttributeSet overrides) {
+
+    /**
+     * Creates a replacement command.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public ReplaceCommand {
+        if (existingCredentialId == null) {
+            throw new IllegalArgumentException("existingCredentialId must not be null");
+        }
+        if (newRequest == null) {
+            throw new IllegalArgumentException("newRequest must not be null");
+        }
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (overrides == null) {
+            throw new IllegalArgumentException("overrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/VerificationPolicy.java

@@ -0,0 +1,65 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.issuance;
+
+import java.util.Optional;
+
+/**
+ * Constraints for certification request verification.
+ *
+ * <p>
+ * This policy controls proof-of-possession requirements and may carry
+ * framework-specific verification modes via optional hints.
+ * </p>
+ *
+ * @param requireProofOfPossession whether proof-of-possession is required
+ * @param compatibilityProfileId   optional compatibility profile hint for
+ *                                 parsers/verifiers
+ */
+public record VerificationPolicy(boolean requireProofOfPossession, Optional<String> compatibilityProfileId) {
+
+    /**
+     * Creates a verification policy.
+     *
+     * @param requireProofOfPossession PoP requirement
+     * @param compatibilityProfileId   optional compatibility profile id
+     * @throws IllegalArgumentException if {@code compatibilityProfileId} is null
+     */
+    public VerificationPolicy {
+        if (compatibilityProfileId == null) {
+            throw new IllegalArgumentException("compatibilityProfileId must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/issuance/package-info.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Credential issuance domain model.
+ *
+ * <p>
+ * This package contains command objects and input types used to issue, renew,
+ * replace, and reissue credentials, as well as optional issuance verification
+ * policies. The operations are executed through
+ * {@link zeroecho.pki.api.IssuanceService}.
+ * </p>
+ *
+ * <h2>Command-driven operations</h2>
+ * <ul>
+ * <li>Issue end-entity credentials.</li>
+ * <li>Renew existing credentials.</li>
+ * <li>Replace credentials (e.g., due to key changes).</li>
+ * <li>Reissue credentials (policy-driven reissuance).</li>
+ * </ul>
+ *
+ * <p>
+ * Requests may originate from the request domain
+ * ({@code zeroecho.pki.api.request}) and issuance outcomes may be published
+ * and/or recorded in inventory.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.issuance;

pki/src/main/java/zeroecho/pki/api/package-info.java

@@ -0,0 +1,81 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Public, framework-agnostic PKI API.
+ *
+ * <p>
+ * This package provides stable entry points and core value types for operating
+ * a PKI instance. The API is intentionally independent of any concrete
+ * certificate framework (for example X.509), allowing multiple frameworks to be
+ * integrated via SPIs in {@code zeroecho.pki.spi.*}.
+ * </p>
+ *
+ * <h2>Design principles</h2>
+ * <ul>
+ * <li><strong>Framework independence:</strong> the API models PKI concepts (CA,
+ * issuance, revocation, status objects, publication, backup/restore) without
+ * binding to a single certificate technology.</li>
+ * <li><strong>Explicit commands and queries:</strong> mutable operations are
+ * expressed as command objects and retrieval via query objects in
+ * subpackages.</li>
+ * <li><strong>Safety and auditability:</strong> security-relevant operations
+ * are designed to be auditable; sensitive data must never be exposed by API
+ * abstractions.</li>
+ * </ul>
+ *
+ * <h2>Key entry points</h2>
+ * <ul>
+ * <li>{@link zeroecho.pki.api.CaService}</li>
+ * <li>{@link zeroecho.pki.api.CertificationRequestService}</li>
+ * <li>{@link zeroecho.pki.api.IssuanceService}</li>
+ * <li>{@link zeroecho.pki.api.RevocationService}</li>
+ * <li>{@link zeroecho.pki.api.StatusObjectService}</li>
+ * <li>{@link zeroecho.pki.api.PublicationService}</li>
+ * <li>{@link zeroecho.pki.api.ProfileService}</li>
+ * <li>{@link zeroecho.pki.api.PolicyService}</li>
+ * <li>{@link zeroecho.pki.api.ImportExportService}</li>
+ * <li>{@link zeroecho.pki.api.BackupService}</li>
+ * </ul>
+ *
+ * <p>
+ * Subpackages further organize domain models: {@code ca}, {@code issuance},
+ * {@code request}, {@code revocation}, {@code status}, {@code publication},
+ * {@code profile}, {@code policy}, {@code transfer}, plus attribute and audit
+ * domains in {@code attr} and {@code audit}.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api;

pki/src/main/java/zeroecho/pki/api/policy/PolicyDecision.java

@@ -0,0 +1,80 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.policy;
+
+import java.util.List;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Policy decision including optional modifications to be applied to an
+ * operation.
+ *
+ * <p>
+ * The {@code appliedOverrides} attribute set is used to communicate
+ * policy-enforced adjustments (e.g., constrained validity, normalized
+ * attributes). It must not contain secrets.
+ * </p>
+ *
+ * @param decisionId       stable decision identifier for correlation and
+ *                         explainability
+ * @param status           decision outcome status
+ * @param messages         non-sensitive operator-readable messages
+ * @param appliedOverrides policy-enforced overrides to be applied downstream
+ */
+public record PolicyDecision(PkiId decisionId, PolicyDecisionStatus status, List<String> messages,
+        AttributeSet appliedOverrides) {
+
+    /**
+     * Creates a policy decision.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PolicyDecision {
+        if (decisionId == null) {
+            throw new IllegalArgumentException("decisionId must not be null");
+        }
+        if (status == null) {
+            throw new IllegalArgumentException("status must not be null");
+        }
+        if (messages == null) {
+            throw new IllegalArgumentException("messages must not be null");
+        }
+        if (appliedOverrides == null) {
+            throw new IllegalArgumentException("appliedOverrides must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/policy/PolicyDecisionStatus.java

@@ -0,0 +1,57 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.policy;
+
+/**
+ * Outcome status of a policy evaluation.
+ */
+public enum PolicyDecisionStatus {
+
+    /**
+     * Operation is allowed under current policy.
+     */
+    ALLOW,
+
+    /**
+     * Operation is denied under current policy.
+     */
+    DENY,
+
+    /**
+     * Operation is allowed, but policy requires modifications (e.g., validity
+     * truncation).
+     */
+    ALLOW_WITH_MODIFICATIONS
+}

pki/src/main/java/zeroecho/pki/api/policy/PolicyTrace.java

@@ -0,0 +1,62 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.policy;
+
+import java.util.List;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Explainability trace for a policy decision.
+ *
+ * @param decisionId decision id this trace explains
+ * @param steps      ordered evaluation steps
+ */
+public record PolicyTrace(PkiId decisionId, List<PolicyTraceStep> steps) {
+
+    /**
+     * Creates a policy trace.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PolicyTrace {
+        if (decisionId == null) {
+            throw new IllegalArgumentException("decisionId must not be null");
+        }
+        if (steps == null) {
+            throw new IllegalArgumentException("steps must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/policy/PolicyTraceStep.java

@@ -0,0 +1,65 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.policy;
+
+import java.util.List;
+
+/**
+ * Single evaluation step within a policy trace.
+ *
+ * @param ruleId  stable rule identifier (implementation-defined)
+ * @param outcome human-readable outcome string (e.g., "ALLOW", "DENY",
+ *                "MODIFY")
+ * @param notes   non-sensitive explanatory notes
+ */
+public record PolicyTraceStep(String ruleId, String outcome, List<String> notes) {
+
+    /**
+     * Creates a policy trace step.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PolicyTraceStep {
+        if (ruleId == null || ruleId.isBlank()) {
+            throw new IllegalArgumentException("ruleId must not be null/blank");
+        }
+        if (outcome == null || outcome.isBlank()) {
+            throw new IllegalArgumentException("outcome must not be null/blank");
+        }
+        if (notes == null) {
+            throw new IllegalArgumentException("notes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/policy/package-info.java

@@ -0,0 +1,53 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Policy decision and trace model.
+ *
+ * <p>
+ * This package defines the core policy decision objects and trace structures
+ * used to explain and audit policy evaluation outcomes. It is consumed via
+ * {@link zeroecho.pki.api.PolicyService}.
+ * </p>
+ *
+ * <h2>Explainability</h2>
+ * <p>
+ * Policy traces are intended to provide human- and machine-readable reasoning
+ * without exposing sensitive data. Trace steps must remain deterministic and
+ * stable for audit retention.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.policy;

pki/src/main/java/zeroecho/pki/api/profile/CertificateProfile.java

@@ -0,0 +1,97 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.profile;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.attr.AttributeId;
+
+/**
+ * Defines issuance constraints and mapping hints for a class of credentials.
+ *
+ * <p>
+ * A profile is referenced by {@code profileId} during issuance. It defines
+ * which universal attributes are required or allowed, and provides limits such
+ * as maximum validity. Framework backends may use the profile as a source of
+ * mapping hints when translating universal attributes into framework-specific
+ * fields/extensions.
+ * </p>
+ *
+ * <p>
+ * Profiles must not include secrets.
+ * </p>
+ *
+ * @param profileId          stable profile identifier
+ * @param formatId           framework/format supported by the profile
+ * @param displayName        human-readable name
+ * @param requiredAttributes list of required attribute identifiers
+ * @param optionalAttributes list of optional attribute identifiers
+ * @param maxValidity        optional maximum validity allowed by the profile
+ * @param active             whether the profile is active for issuance
+ */
+public record CertificateProfile(String profileId, FormatId formatId, String displayName,
+        List<AttributeId> requiredAttributes, List<AttributeId> optionalAttributes, Optional<Duration> maxValidity,
+        boolean active) {
+
+    /**
+     * Creates a certificate profile.
+     *
+     * @throws IllegalArgumentException if inputs are invalid or optional container
+     *                                  is null
+     */
+    public CertificateProfile {
+        if (profileId == null || profileId.isBlank()) {
+            throw new IllegalArgumentException("profileId must not be null/blank");
+        }
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (displayName == null || displayName.isBlank()) {
+            throw new IllegalArgumentException("displayName must not be null/blank");
+        }
+        if (requiredAttributes == null) {
+            throw new IllegalArgumentException("requiredAttributes must not be null");
+        }
+        if (optionalAttributes == null) {
+            throw new IllegalArgumentException("optionalAttributes must not be null");
+        }
+        if (maxValidity == null) {
+            throw new IllegalArgumentException("maxValidity must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/profile/ProfileQuery.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.profile;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+
+/**
+ * Query constraints for listing profiles.
+ *
+ * @param formatId   optional format filter
+ * @param profileId  optional profile id filter
+ * @param activeOnly optional filter (true -> only active profiles, false ->
+ *                   only inactive, empty -> all)
+ */
+public record ProfileQuery(Optional<FormatId> formatId, Optional<String> profileId, Optional<Boolean> activeOnly) {
+
+    /**
+     * Creates a profile query.
+     *
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public ProfileQuery {
+        if (formatId == null || profileId == null || activeOnly == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/profile/package-info.java

@@ -0,0 +1,51 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Certificate and credential profiles.
+ *
+ * <p>
+ * This package contains profile model objects and query types describing
+ * constraints and defaults used during issuance. Profiles are managed through
+ * {@link zeroecho.pki.api.ProfileService}.
+ * </p>
+ *
+ * <p>
+ * Profiles are framework-agnostic by design and are mapped into concrete
+ * framework constructs during credential creation.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.profile;

pki/src/main/java/zeroecho/pki/api/publication/PublicationQuery.java

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+import java.time.Instant;
+import java.util.Optional;
+
+/**
+ * Query constraints for listing publication records.
+ *
+ * @param targetType optional target type filter
+ * @param after      optional lower bound for time
+ * @param before     optional upper bound for time
+ * @param objectKind optional object kind filter
+ */
+public record PublicationQuery(Optional<PublicationTargetType> targetType, Optional<Instant> after,
+        Optional<Instant> before, Optional<String> objectKind) {
+
+    /**
+     * Creates a publication query.
+     *
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public PublicationQuery {
+        if (targetType == null || after == null || before == null || objectKind == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/publication/PublicationRecord.java

@@ -0,0 +1,86 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+import java.time.Instant;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Persisted record of a publication attempt.
+ *
+ * <p>
+ * Publication records support operational troubleshooting, auditability, and
+ * re-publication workflows.
+ * </p>
+ *
+ * @param publicationId publication id
+ * @param time          time when publication was attempted
+ * @param target        publication target
+ * @param objectId      published object id (credential, CA materials, status
+ *                      object)
+ * @param objectKind    non-empty logical kind string (e.g., "CREDENTIAL",
+ *                      "CA_MATERIALS", "STATUS_OBJECT")
+ * @param status        publication outcome
+ */
+public record PublicationRecord(PkiId publicationId, Instant time, PublicationTarget target, PkiId objectId,
+        String objectKind, PublicationStatus status) {
+
+    /**
+     * Creates a publication record.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PublicationRecord {
+        if (publicationId == null) {
+            throw new IllegalArgumentException("publicationId must not be null");
+        }
+        if (time == null) {
+            throw new IllegalArgumentException("time must not be null");
+        }
+        if (target == null) {
+            throw new IllegalArgumentException("target must not be null");
+        }
+        if (objectId == null) {
+            throw new IllegalArgumentException("objectId must not be null");
+        }
+        if (objectKind == null || objectKind.isBlank()) {
+            throw new IllegalArgumentException("objectKind must not be null/blank");
+        }
+        if (status == null) {
+            throw new IllegalArgumentException("status must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/publication/PublicationResult.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+import java.util.List;
+
+import zeroecho.pki.api.PkiId;
+
+/**
+ * Result of a publish operation.
+ *
+ * @param publicationId publication record id
+ * @param status        outcome status
+ * @param notes         non-sensitive operator-readable notes
+ */
+public record PublicationResult(PkiId publicationId, PublicationStatus status, List<String> notes) {
+
+    /**
+     * Creates a publication result.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PublicationResult {
+        if (publicationId == null) {
+            throw new IllegalArgumentException("publicationId must not be null");
+        }
+        if (status == null) {
+            throw new IllegalArgumentException("status must not be null");
+        }
+        if (notes == null) {
+            throw new IllegalArgumentException("notes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/publication/PublicationStatus.java

@@ -0,0 +1,57 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+/**
+ * Publication outcome status.
+ */
+public enum PublicationStatus {
+
+    /**
+     * Artifact has been published successfully.
+     */
+    PUBLISHED,
+
+    /**
+     * Publication was skipped (e.g., already published, policy decision, target not
+     * applicable).
+     */
+    SKIPPED,
+
+    /**
+     * Publication failed.
+     */
+    FAILED
+}

pki/src/main/java/zeroecho/pki/api/publication/PublicationTarget.java

@@ -0,0 +1,70 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Describes where and how to publish an artifact.
+ *
+ * <p>
+ * The {@code targetId} identifies a configured target instance. Additional
+ * configuration is carried in {@code attributes}. Secrets must not be carried
+ * in attributes intended for publication.
+ * </p>
+ *
+ * @param type       destination type
+ * @param targetId   target identifier (implementation-defined)
+ * @param attributes target configuration/hints (may be empty but not null)
+ */
+public record PublicationTarget(PublicationTargetType type, String targetId, AttributeSet attributes) {
+
+    /**
+     * Creates a publication target.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public PublicationTarget {
+        if (type == null) {
+            throw new IllegalArgumentException("type must not be null");
+        }
+        if (targetId == null || targetId.isBlank()) {
+            throw new IllegalArgumentException("targetId must not be null/blank");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/publication/PublicationTargetType.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.publication;
+
+/**
+ * Classifies the publication destination type.
+ */
+public enum PublicationTargetType {
+
+    /**
+     * Publish to a filesystem location.
+     */
+    FILESYSTEM,
+
+    /**
+     * Publish to an LDAP directory.
+     */
+    LDAP,
+
+    /**
+     * Publish via an HTTP(S) endpoint.
+     */
+    HTTP,
+
+    /**
+     * Publish to an object store (S3-like).
+     */
+    OBJECT_STORE,
+
+    /**
+     * Custom target type implemented by a publisher plugin.
+     */
+    CUSTOM
+}

pki/src/main/java/zeroecho/pki/api/publication/package-info.java

@@ -0,0 +1,53 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Publication domain model.
+ *
+ * <p>
+ * This package defines publication targets and records describing how PKI
+ * artifacts are distributed to relying parties or infrastructure components
+ * (repositories, directories, endpoints, etc.). Publication is orchestrated
+ * through {@link zeroecho.pki.api.PublicationService}.
+ * </p>
+ *
+ * <h2>Artifacts</h2>
+ * <p>
+ * Publication may include certificates, chains, status objects, and related
+ * metadata. The concrete transport is framework- and deployment-specific.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.publication;

pki/src/main/java/zeroecho/pki/api/request/CertificationRequest.java

@@ -0,0 +1,74 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+import zeroecho.pki.api.EncodedObject;
+import zeroecho.pki.api.FormatId;
+
+/**
+ * Opaque certification request container.
+ *
+ * <p>
+ * This type transports a request payload and declares the request format via
+ * {@link FormatId}. A framework backend parses and normalizes the payload into
+ * {@link ParsedCertificationRequest}.
+ * </p>
+ *
+ * <p>
+ * For X.509, the request is typically a PKCS#10 CSR. Other frameworks may
+ * define different request syntaxes.
+ * </p>
+ *
+ * @param formatId request/credential framework id
+ * @param encoded  encoded request payload
+ */
+public record CertificationRequest(FormatId formatId, EncodedObject encoded) {
+
+    /**
+     * Creates a certification request.
+     *
+     * @param formatId request format id
+     * @param encoded  encoded request payload
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public CertificationRequest {
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (encoded == null) {
+            throw new IllegalArgumentException("encoded must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/request/ParsedCertificationRequest.java

@@ -0,0 +1,114 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+import java.util.Optional;
+
+import zeroecho.pki.api.EncodedObject;
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.SubjectRef;
+import zeroecho.pki.api.Validity;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Normalized representation of a certification request.
+ *
+ * <p>
+ * This record is produced by a framework-specific request parser. It contains a
+ * minimal set of mandatory core fields required by the PKI runtime, plus a
+ * universal typed {@link AttributeSet} that carries additional request
+ * attributes in a framework-neutral manner.
+ * </p>
+ *
+ * <p>
+ * The PKI runtime is expected to apply policy and profile constraints before
+ * issuance.
+ * </p>
+ *
+ * @param requestId          stable identifier for the request (typically
+ *                           derived from the request payload fingerprint)
+ * @param formatId           framework/format identifier
+ * @param subjectRef         normalized subject reference for policy and
+ *                           inventory correlation
+ * @param publicKeyInfo      requested public key information (SPKI DER
+ *                           preferred where applicable)
+ * @param requestedValidity  optional validity requested by the subject; policy
+ *                           may override or deny
+ * @param requestedProfileId optional profile hint; policy may override or deny
+ * @param attributes         universal typed attributes extracted from the
+ *                           request
+ */
+public record ParsedCertificationRequest(PkiId requestId, FormatId formatId, SubjectRef subjectRef,
+        EncodedObject publicKeyInfo, Optional<Validity> requestedValidity, Optional<String> requestedProfileId,
+        AttributeSet attributes) {
+
+    /**
+     * Creates a parsed certification request.
+     *
+     * @param requestId          stable request id
+     * @param formatId           format id
+     * @param subjectRef         normalized subject reference
+     * @param publicKeyInfo      requested public key info
+     * @param requestedValidity  optional requested validity
+     * @param requestedProfileId optional requested profile id
+     * @param attributes         extracted attributes
+     * @throws IllegalArgumentException if mandatory inputs are null or optional
+     *                                  containers are null
+     */
+    public ParsedCertificationRequest {
+        if (requestId == null) {
+            throw new IllegalArgumentException("requestId must not be null");
+        }
+        if (formatId == null) {
+            throw new IllegalArgumentException("formatId must not be null");
+        }
+        if (subjectRef == null) {
+            throw new IllegalArgumentException("subjectRef must not be null");
+        }
+        if (publicKeyInfo == null) {
+            throw new IllegalArgumentException("publicKeyInfo must not be null");
+        }
+        if (requestedValidity == null) {
+            throw new IllegalArgumentException("requestedValidity must not be null");
+        }
+        if (requestedProfileId == null) {
+            throw new IllegalArgumentException("requestedProfileId must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/request/ProofOfPossessionResult.java

@@ -0,0 +1,67 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+import java.util.Optional;
+
+/**
+ * Result of proof-of-possession (PoP) verification.
+ *
+ * <p>
+ * The {@code details} field is intended for operator diagnostics and must not
+ * contain secrets.
+ * </p>
+ *
+ * @param status  verification outcome status
+ * @param details optional non-sensitive diagnostic information
+ */
+public record ProofOfPossessionResult(ProofOfPossessionStatus status, Optional<String> details) {
+
+    /**
+     * Creates a PoP verification result.
+     *
+     * @param status  outcome status
+     * @param details optional diagnostic details (non-sensitive)
+     * @throws IllegalArgumentException if {@code status} or {@code details} is null
+     */
+    public ProofOfPossessionResult {
+        if (status == null) {
+            throw new IllegalArgumentException("status must not be null");
+        }
+        if (details == null) {
+            throw new IllegalArgumentException("details must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/request/ProofOfPossessionStatus.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+/**
+ * Outcome of proof-of-possession (PoP) verification.
+ */
+public enum ProofOfPossessionStatus {
+
+    /**
+     * Proof-of-possession has been successfully verified.
+     */
+    VERIFIED,
+
+    /**
+     * Proof-of-possession evidence is not present.
+     *
+     * <p>
+     * This is acceptable only if policy allows it.
+     * </p>
+     */
+    NOT_PRESENT,
+
+    /**
+     * Proof-of-possession evidence is present but invalid.
+     */
+    FAILED,
+
+    /**
+     * Proof-of-possession verification is not supported for the given request type
+     * or framework.
+     */
+    NOT_SUPPORTED
+}

pki/src/main/java/zeroecho/pki/api/request/RequestQuery.java

@@ -0,0 +1,74 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+import java.time.Instant;
+import java.util.Optional;
+
+import zeroecho.pki.api.FormatId;
+import zeroecho.pki.api.SubjectRef;
+
+/**
+ * Query constraints for searching stored certification requests.
+ *
+ * @param formatId      optional framework filter
+ * @param subjectRef    optional subject filter
+ * @param createdAfter  optional lower bound (inclusive) for request creation
+ *                      time
+ * @param createdBefore optional upper bound (exclusive) for request creation
+ *                      time
+ * @param profileId     optional profile filter (requested or resolved profile
+ *                      id depending on implementation)
+ */
+public record RequestQuery(Optional<FormatId> formatId, Optional<SubjectRef> subjectRef, Optional<Instant> createdAfter,
+        Optional<Instant> createdBefore, Optional<String> profileId) {
+
+    /**
+     * Creates a request query.
+     *
+     * @param formatId      optional format filter
+     * @param subjectRef    optional subject filter
+     * @param createdAfter  optional lower time bound
+     * @param createdBefore optional upper time bound
+     * @param profileId     optional profile id filter
+     * @throws IllegalArgumentException if any optional container is null
+     */
+    public RequestQuery {
+        if (formatId == null || subjectRef == null || createdAfter == null || createdBefore == null
+                || profileId == null) {
+            throw new IllegalArgumentException("optional fields must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/request/RequestStorePolicy.java

@@ -0,0 +1,62 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.request;
+
+/**
+ * Controls whether and when parsed certification requests are persisted for
+ * correlation and audit.
+ */
+public enum RequestStorePolicy {
+
+    /**
+     * Always persist parsed requests.
+     */
+    STORE_ALWAYS,
+
+    /**
+     * Persist parsed requests only after successful issuance.
+     */
+    STORE_ON_ISSUE,
+
+    /**
+     * Do not persist parsed requests.
+     *
+     * <p>
+     * Use only when explicit request persistence is not required by operational
+     * needs.
+     * </p>
+     */
+    DO_NOT_STORE
+}

pki/src/main/java/zeroecho/pki/api/request/package-info.java

@@ -0,0 +1,54 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+/**
+ * Certification request domain model.
+ *
+ * <p>
+ * This package defines models and query types for certification requests and
+ * their parsed, normalized form. Requests are managed through
+ * {@link zeroecho.pki.api.CertificationRequestService} and may be consumed by
+ * issuance operations.
+ * </p>
+ *
+ * <h2>Proof of possession</h2>
+ * <p>
+ * The request workflow may include proof-of-possession evaluation. The request
+ * domain models the outcome and status without imposing a specific
+ * cryptographic proof mechanism.
+ * </p>
+ *
+ * @since 1.0
+ */
+package zeroecho.pki.api.request;

pki/src/main/java/zeroecho/pki/api/revocation/HoldCommand.java

@@ -0,0 +1,67 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.revocation;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Command to place a credential on hold.
+ *
+ * <p>
+ * Frameworks may map this to X.509 {@code certificateHold} or equivalent
+ * semantics.
+ * </p>
+ *
+ * @param credentialId credential identifier
+ * @param attributes   optional additional attributes (may be empty but not
+ *                     null)
+ */
+public record HoldCommand(PkiId credentialId, AttributeSet attributes) {
+
+    /**
+     * Creates a hold command.
+     *
+     * @throws IllegalArgumentException if inputs are null
+     */
+    public HoldCommand {
+        if (credentialId == null) {
+            throw new IllegalArgumentException("credentialId must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}

pki/src/main/java/zeroecho/pki/api/revocation/RevocationInputs.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright (C) 2025, Leo Galambos
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this software must
+ *    display the following acknowledgement:
+ *    This product includes software developed by the Egothor project.
+ *
+ * 4. Neither the name of the copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ ******************************************************************************/
+package zeroecho.pki.api.revocation;
+
+import zeroecho.pki.api.PkiId;
+import zeroecho.pki.api.attr.AttributeSet;
+
+/**
+ * Normalized inputs for revocation policy evaluation.
+ *
+ * @param credentialId credential id to revoke/hold/unhold
+ * @param reason       revocation reason
+ * @param attributes   additional revocation attributes (may be empty but not
+ *                     null)
+ */
+public record RevocationInputs(PkiId credentialId, RevocationReason reason, AttributeSet attributes) {
+
+    /**
+     * Creates revocation inputs.
+     *
+     * @throws IllegalArgumentException if inputs are invalid
+     */
+    public RevocationInputs {
+        if (credentialId == null) {
+            throw new IllegalArgumentException("credentialId must not be null");
+        }
+        if (reason == null) {
+            throw new IllegalArgumentException("reason must not be null");
+        }
+        if (attributes == null) {
+            throw new IllegalArgumentException("attributes must not be null");
+        }
+    }
+}