1.1About this documentation

This guide describes how to install Spiryra, connect the certificate authority you already operate, and use every feature in the console: certificate lifecycle, agents and clientless deployment, orchestration, identity, monitoring, service accounts and operations. Spiryra is published by Nacreon Security at nacreonsecurity.com.

Nacreon Security ships the Nacreon suite, of which Spiryra is the certificate lifecycle product. The suite, its documentation and the support policy are published at nacreonsecurity.com; this guide is the manual for one product in it.

Who this is for

Platform and security engineers who run the Docker host, PKI administrators who own the external CA, and operators who issue, deploy and renew certificates day to day. Installation chapters assume shell access to the Docker host; feature chapters assume a signed-in administrator.

How the chapters are arranged

Conventions

• Monospaced text is a console label, file path, environment variable or literal value.
• Code blocks run on the Docker host from the repository root unless the heading says otherwise.
• /api/… paths are API routes; most have an equivalent screen in the console.
• Commands that change data or delete volumes are marked destructive.

Callout styles

1.2Edition comparison and release status

Both editions use the same images and application code. They differ only in runtime configuration, data volume, ports and safeguards.

What “development preview” means

The Rust API and console build, the test stack runs, and the verification described in 14.1 was executed. It does not mean the product is certified for production certificate management. The release gate deliberately blocks until live EST/SCEP and public ACME runs and an independent security review are complete; the WinRM orchestration steps have since run on a real Windows endpoint (WINDOWS_LIVE_WINRM_E2E.md).

Source-of-truth documents

1.3Deployment architecture

The console and API run in separate containers. The browser never reaches the API container directly: nginx serves the single-page console and proxies /api/ to the API over the internal network.

Runtime boundaries

• Web container: nginx on port 8080, bound to 127.0.0.1 by default. In production your proxy publishes HTTPS.
• API container: internal port 9080, health-checked, never published.
• Data: one Compose volume per profile holding SQLite databases, the optional keyring, the ACME webroot and deployment evidence.
• Secrets: deploy/<profile>.env, mode 0600, never committed.
• Vault: AES-256-GCM wrapping for connector credentials, retained leaf keys, SSH keys, WinRM passwords and notification secrets.

What the API talks to

1.4Supported platforms and prerequisites

Docker host

Managed targets

Certificate authorities

Browsers

The console is a single-page application tested in current Chromium-based browsers and Firefox. It requires JavaScript and secure cookies in the production profile.

2.1Install the test profile

The test profile is the recommended first install. It deploys Spiryra with an optional disposable EJBCA Community CA, so you can exercise the whole lifecycle without touching a real authority.

Run the wizard

./scripts/deploy-test.sh

The wizard asks for the bind address, port and administrator username, then writes deploy/test.env with mode 0600, starts the stack, waits for health and prints the console URL and administrator credential.

What it creates

• Spiryra on HTTP, loopback by default, or one explicit --bind address.
• A disposable EJBCA Community CA from compose.test-ca.yaml, when enabled.
• EJBCA client certificate, private key and ManagementCA bundle in deploy/test-ejbca/ (secrets mode 0600).
• A paste-ready deploy/test-ejbca/connector-paste-values.txt for the Connectors screen.
• A reusable deploy/test.env carrying SPIRYRA_TEST_CA=true, so later profile commands keep the CA container in the same lifecycle.

Flags

The test credential

Sign in as admin with Testing123 unless you overrode it. The password is reapplied after every test deployment, and deploy-production.sh refuses it. To reset a running stack without redeploying:

SPIRYRA_TEST_ADMIN_PASSWORD=Testing123 ./scripts/reset-test-admin-password.sh

2.2Install the production profile

The production profile deploys Spiryra only. It never starts a CA and never seeds demo data; you connect the organization's existing CA after sign-in.

./scripts/deploy-production.sh \
  --origin https://spiryra.example.com

# preflight only, no containers touched
./scripts/deploy-production.sh --check

The origin must be an exact public HTTPS DNS origin: no path, query, IP address or localhost. The wizard generates a unique bootstrap administrator credential and prints it once.

What the preflight refuses

• SPIRYRA_DEPLOYMENT_PROFILE not set to production.
• A loopback, IP-address or non-HTTPS SPIRYRA_PUBLIC_ORIGIN.
• SPIRYRA_LAB_INSECURE_HTTP_COOKIE=true, or any SPIRYRA_LAB_ALLOW_* switch.
• The TLS-verification opt-outs SPIRYRA_ADCS_WEB_INSECURE=true or SPIRYRA_AGENTLESS_WINRM_INSECURE=true (also refused as 1).
• SPIRYRA_METRICS_TOKEN missing, shorter than 32 characters, or still a template placeholder.
• An env file readable or writable by group or world.
• Migration tokens or a vault key shorter than 32 characters, or values that are not distinct.
• The lab default password Testing123.
• An API that advertises a local-ca kind or demoAvailable: true, or a Compose file such as compose.test-ca.yaml.

After the stack is healthy

1. Put TLS in front of the console. Proxy your public origin to http://127.0.0.1:8080; see 2.4.
2. Sign in with the bootstrap credential and change it immediately.
3. Connect the existing CA under Connectors and test it before issuing anything.
4. Review policy under Settings: expiry windows, default validity, key rules, SAN policy, session length.
5. Configure notifications and run a backup; confirm /readyz is ready.

2.3Manual environment installation

Use this when you own the env file instead of letting the wizard generate it — for example when secrets come from your secret manager.

1. Create the env file and lock it down.

   cp deploy/test.env.example deploy/test.env
   chmod 600 deploy/test.env

2. Generate secrets. Three distinct migration tokens and one vault key:

   openssl rand -hex 32   # run three times for the migration tokens
   openssl rand -hex 32   # once for SPIRYRA_VAULT_KEY

3. Generate the administrator hash.

   python3 scripts/create-lab-admin.py

   Paste the complete single-quoted SPIRYRA_LOCAL_ADMIN_ARGON2_HASH=… line it prints.
4. Replace every remaining placeholder (REPLACE_WITH…) in the env file.
5. Validate and start.

   ./scripts/deploy-profile.sh test check
   ./scripts/deploy-profile.sh test up
   ./scripts/deploy-profile.sh test status

Production follows the same pattern with deploy/production.env and the production profile. production check fails closed until the origin, cookies, tokens and vault key are valid.

Profile commands

./scripts/deploy-profile.sh <test|production> check
./scripts/deploy-profile.sh <test|production> up
./scripts/deploy-profile.sh <test|production> status
./scripts/deploy-profile.sh <test|production> digest
./scripts/deploy-profile.sh <test|production> down

start is accepted as an alias for up; both go through the same checks.

Stale images are refused, not served

A profile runs whatever images it was started from, and a container keeps its name and its Up (healthy) status while the sources move on. Each image is therefore stamped at build time with a SHA-256 over the files it is built from — the Dockerfile, the manifests, the sources, and for the API the agent binaries it serves — and the stamp is compared with the tree whenever someone asks.

status and doctor print the verdict after the container table and exit non-zero on drift; digest reports it on demand. up refuses to start images built from a different tree, because starting them is how the drift becomes serving, and up --allow-stale overrides that deliberately. An image built before the stamp existed cannot be compared at all, so it warns and starts instead of blocking an installation that predates the check.

./scripts/deploy-profile.sh production status   # non-zero when the images drifted
./scripts/deploy-profile.sh production build
./scripts/deploy-profile.sh production up      # refuses a drifted image

Generated material

2.4Reverse proxy and TLS

The web container serves HTTP on loopback. Your proxy terminates TLS for the public origin and forwards to it, preserving the browser's Host header.

Checklist

• Terminate HTTPS for the exact SPIRYRA_PUBLIC_ORIGIN.
• Proxy to http://127.0.0.1:8080; never publish that port.
• Preserve Host (including a non-default port) and send X-Forwarded-Proto: https.
• Forward /.well-known/acme-challenge/ on port 80 to the web container for public ACME HTTP-01.
• Allow request bodies large enough for certificate imports and workflow payloads (a few MB is sufficient).

nginx example

server {
  listen 443 ssl;
  server_name spiryra.example.com;
  ssl_certificate     /etc/ssl/certs/spiryra.pem;
  ssl_certificate_key /etc/ssl/private/spiryra.key;

  location / {
    proxy_pass         http://127.0.0.1:8080;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-Proto https;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Real-IP         $remote_addr;
  }
}

# ACME HTTP-01 only
server {
  listen 80;
  server_name spiryra.example.com;
  location /.well-known/acme-challenge/ { proxy_pass http://127.0.0.1:8080; }
  location / { return 301 https://$host$request_uri; }
}

TLS to external systems

Connector and webhook TLS is verified with the trust bundle you configure. Redirects are refused, embedded credentials in URLs are rejected, and no “skip verification” switch exists. Place private roots in deploy/ca/, mounted read-only at /etc/spiryra/ca, and reference the file by absolute path.

2.5Environment variable reference

All variables live in deploy/<profile>.env and are passed to the API container by Compose. Values marked secret are never printed by the console.

Core

Connectors

Agent plane

2.6Upgrade an installation

1. Read the change notes for the release, then back up the profile:

   ./scripts/backup-profile.sh production

2. Check out the new source on the Docker host (same repository, same profile env file).
3. Validate the configuration before replacing containers:

   ./scripts/deploy-profile.sh production check

4. Deploy. The stack recreates the API and web containers; schema migrations run on startup.

   ./scripts/deploy-profile.sh production up

5. Confirm readiness, then sign in and spot-check inventory, a connector test and one deployment target.

Agent upgrades are separate

Agent binaries are upgraded through the signed release catalog, not by redeploying the control plane. See 6.4. An agent that is offline keeps its job queued; deployments do not replay automatically.

Rolling back an application upgrade

Redeploy the previous source revision. If a migration changed the schema, restore the pre-upgrade backup instead of downgrading binaries:

./scripts/restore-profile.sh production backups/production-20261031T020304Z --yes

2.7Remove a profile

./scripts/deploy-profile.sh test down
./scripts/deploy-profile.sh test down --volumes --yes   # destructive

down stops containers and keeps the data volume. Adding --volumes --yes removes the profile's containers and volume — all certificates, accounts, audit history and sealed credentials for that profile.

For the test profile, ./scripts/deploy-test.sh --fresh also removes the disposable EJBCA containers and the ejbca-data volume. Production never has a test CA to remove, and profile commands never touch the other profile's data.

3.1Bootstrap credentials and sign-in

Sign-in flow

• POST /api/auth/login returns a session cookie plus a CSRF token bound to that session.
• Every browser-origin write must send the CSRF token; a missing or wrong value returns 403.
• Bearer credentials — migration tokens, agents and API service accounts — are not subject to the browser CSRF rule.
• Session lifetime follows the configured policy (sessionHours in Settings).

First actions

1. Change the bootstrap password under your account menu.
2. Create one administrator account per person; stop sharing the bootstrap credential.
3. Configure the CA connector, then policy, then notifications.
4. Run a backup and store the vault key in your secret manager.

3.2First-run checklist

Work through this list in order. The first issued and deployed certificate is the fastest proof that the connector, policy, target and verification path all agree.

1. Sign in and change the bootstrap credential (3.1).
2. Connect the external CA under Connectors and press Test. Do not issue until the test passes (4.1).
3. Set policy under Settings: expiry warning and critical windows, default validity, key rules, SAN policy, session length (5.7).
4. Issue or import the first certificate and confirm it appears in inventory with the expected issuer and SANs (5.2).
5. Register a deployment target — enrolled agent, SSH host or WinRM host — and confirm it is ready (6.1).
6. Deploy the certificate to an absolute path with an optional approved reload and TLS endpoint (6.3).
7. Verify presentation: the deployment only becomes verified when the fingerprint the socket serves matches the file (6.3).
8. Close the loop: notifications, escalation, a profile backup and a green /readyz (10 Notifications, 11.2).

3.3Password policy and account recovery

Policy

• Local passwords are stored as Argon2id hashes; sessions store only a SHA-256 digest of the session token.
• Policy covers minimum length and complexity, history, maximum age and lockout after repeated failures.
• Policy is stored in the database and read by the sign-in path — a failed account-schema migration reports 503 instead of silently breaking sign-in.
• Changing a password revokes existing sessions; an expired password is changed through the dedicated expired-password route.

Self-service recovery

Recovery requires an SMTP relay and a recovery email on the account. The administrator issues a one-time token, the user receives a link, and the token is single-use with a short expiry.

POST /api/auth/password/recover
POST /api/auth/password/change
POST /api/auth/password/change-expired
GET  /api/auth/password/policy

Administrators with the users.manage action can also reset a password directly, which is the fallback when mail is unavailable.

4.1Connector model and the credential vault

Spiryra is an interface to the certificate authorities you already operate. It never hosts an issuing CA in production. A connector is the configured, tested, audited path to one authority.

How a connector works

• Non-secret settings (URLs, CA names, profiles, usernames) are stored as connector configuration and returned by the API.
• Secrets — private keys, tokens, passwords, trust bundles — are sealed into one AES-256-GCM document bound to the connector id. The API returns only the names of stored secret fields, never the values.
• Tests are explicit. A connector is not “working” until Test succeeds; the console shows the outcome and the audit log records it.
• Issuance stays authoritative at the CA. Spiryra generates the key and CSR, then validates what comes back before anything enters inventory.

Add and test a connector

1. Open Connectors → Add connector and choose the type. The form fields come from the connector specification (GET /api/connectors/specs).
2. Fill the non-secret settings and paste or upload the secrets.
3. Save, then press Test. The test authenticates, reads the CA, and reports what it found — for example the issuing CA and the available templates.
4. Optionally run Pull profiles from EJBCA (or the equivalent discovery for that connector) to import the authority's template list for the issue form and CA policy.

Returned-certificate validation

Before a certificate is stored, Spiryra checks: the subject CN matches the request, every requested SAN is present, the public key matches the key that generated the CSR, the certificate is not expired, and the signature verifies against your configured trust bundle. The chain is ordered with the issuing CA first.

Housekeeping

• Rotate connector credentials after vault rotation (11.3) and after any suspicion of exposure.
• Disable rather than delete a connector that has issuance history; disabled connectors stay in audit records.
• Every CA-side rejection is surfaced as an HTTP error with the CA message; the inventory is only updated after the CA confirms.

4.2EJBCA REST connector

EJBCA is reached over its REST API with mutual TLS, a bearer token or basic authentication. Spiryra generates the key and PKCS#10 request locally and calls /certificate/pkcs10enroll.

Configuration

Required EJBCA role rules

The API identity needs at least: /ca/<issuing-CA>/, /ca_functionality/create_certificate/, /ca_functionality/view_ca/, /ca_functionality/view_certificate/, /ca_functionality/view_certificate_profiles/, /ra_functionality/create_end_entity/, /ra_functionality/view_end_entity/, /ra_functionality/revoke_end_entity/, and the matching create_end_entity, view_end_entity and revoke_end_entity rules for the chosen end-entity profile.

Lifecycle behaviour

• Test: authenticates to /ejbca/ejbca-rest-api/v1/ca and confirms the configured CA name is present.
• Issue: generates key and CSR locally, posts to /certificate/pkcs10enroll, then validates the returned certificate.
• Renew: same path, with the retained key (reuseKey) or a fresh key; the previous certificate becomes replaced.
• Revoke: parses the real issuer DN and calls PUT /certificate/<issuerDN>/<serial>/revoke?reason=…. Inventory changes only after EJBCA accepts.
• Templates: discovery reads the Certificate Profiles admin page with the connector's own credential and stores profiles of type End Entity.

Lab verification

cd rust-backend
python3 ../scripts/verify-ejbca-connector-e2e.sh

In the test profile the wizard already generated a paste-ready configuration at deploy/test-ejbca/connector-paste-values.txt. Treat that identity as disposable.

4.3HashiCorp Vault PKI connector

Signs a locally generated CSR through a Vault PKI role, verifies the returned chain, and revokes through the PKI engine. Lab-verified against Vault 1.18.5.

Configuration

Minimum Vault setup

vault secrets enable pki
vault write pki/root/generate/internal common_name="Lab Issuing CA" ttl=87600h
vault write pki/roles/spiryra allowed_domains="example.com" \
  allow_subdomains=true max_ttl=720h key_type=ec

Grant the Spiryra identity read access to <mount>/ca/pem and <mount>/roles/<role> and update access to <mount>/sign/<role> and <mount>/revoke.

Lifecycle behaviour

• Test: resolves a token (or performs an AppRole login), reads the CA, and reads the role to prove it exists and report its allowed domains.
• Issue: POST /v1/<mount>/sign/<role> with the CSR, CN, DNS/IP SANs, requested TTL and format=pem.
• Renew: same path with a new key by default; reuseKey: true when a retained key exists.
• Revoke: POST /v1/<mount>/revoke; the serial appears in the Vault CRL.

4.4ACME v2 connector (HTTP-01, DNS-01, EAB)

Full ACME v2 lifecycle: account registration with a locally generated P-256 account key, order, authorization, finalize, download, chain verification, renewal and revocation.

Configuration

Presets are provided for Let's Encrypt staging and production, ZeroSSL, Google Trust Services and SSL.com. A preset fills the directory URL and a known profile only.

HTTP-01

Used when no DNS zone is configured. Spiryra writes <token>.<account-key-thumbprint> to $SPIRYRA_ACME_WEBROOT/.well-known/acme-challenge/<token> and removes it when the authorization completes. nginx serves that path from the same shared volume.

1. Every requested name must resolve to this Spiryra deployment.
2. The public proxy must forward port 80 requests for /.well-known/acme-challenge/ to the web container.
3. Wildcards require DNS-01; a wildcard order on an HTTP-01-only connector is refused with an explicit error.

DNS-01

With a DNS zone configured, Spiryra creates a TXT record for each identifier, waits for propagation, completes the challenge, then removes the record. Cleanup failures are reported rather than hidden, and a journal entry is kept. If the API is killed mid-order, startup recovery removes the orphaned record after restart.

4.5Microsoft AD CS connector

Spiryra talks to AD CS without installing anything on the CA. Two clientless transports are supported, and CA work is never queued to an enrolled agent.

Setup with WinRM

1. Register the CA host as a WinRM server target with a sealed credential (see 6.6).
2. Create the connector with transport winrm, select the registered target, the CA name and a certificate template.
3. Press Test. The response names the CA it reached and lists the templates available on it.
4. Issue a certificate and confirm it appears in inventory with the CA as issuer.

WinRM and Web Enrollment never receive the CA private key or a CA administrator credential from the console.

Setup with Web Enrollment

1. Install the Web Enrollment role on the CA and confirm https://<ca>/certsrv answers.
2. Create the connector with transport web, the Web Enrollment URL, the template and — optionally — basic credentials. Set caPem to trust the site certificate.
3. Confirm the account is allowed to enroll against the template: a local account on a workgroup CA, a domain account on a domain CA.
4. Press Test, then issue.

The transport posts the CSR to /certsrv/certfnsh.asp with Mode=newreq, the base64 DER request, CertAttrib=CertificateTemplate:<template>, TargetStoreFlags=0 and SaveCert=yes, then downloads the returned certificate. Absolute and cross-origin certificate links are rejected.

4.6EST connector

RFC 7030 enrolment over HTTPS with a locally generated key and CSR. EST is opt-in per deployment, because the API must be told which hosts it may contact.

Enable EST

1. Add the EST host to SPIRYRA_EST_ALLOWED_HOSTS in the profile env (comma-separated). An empty value keeps EST unavailable.
2. Place the EST server's trust anchor in deploy/ca/ — it is mounted read-only at /etc/spiryra/ca — and reference it by absolute path.
3. Redeploy the profile so the API picks up the new environment.
4. Create the EST connector with the enrolment URL and trust anchor, then press Test.

Operations

4.7SCEP connector

RFC 8894 SCEP enrolment through the packaged CMS exchange, pinned to the CA you configure. SCEP is opt-in, like EST.

Enable SCEP

1. Add the SCEP host to SPIRYRA_SCEP_ALLOWED_HOSTS (comma-separated).
2. Place the SCEP CA certificate and any intermediate chain in deploy/ca/.
3. Redeploy, then create the SCEP connector with the service URL and the challenge password, and press Test.

Operations

4.8CA policy, templates and testing

Template discovery

Where the authority exposes them, Spiryra can pull the certificate profile list and store it for the issue form and policy checks. The result is visible under Connectors and in Permissions → CA policy.

GET  /api/connectors/{id}/templates
POST /api/connectors/{id}/templates/sync
GET  /api/ca/templates

CA policy

CA policy records which templates and profiles a deployment may use, and what key and validity constraints apply. Administrators manage it under Permissions → CA policy:

GET    /api/access/ca-policy
POST   /api/access/ca-policy
PATCH  /api/access/ca-policy/{id}

Testing discipline

• Test after any credential rotation, CA upgrade or network change.
• Keep a connector that issues only to a non-production template for smoke tests, then delete that connector when it is no longer needed.
• Treat a CA-side rejection as an authority policy decision: read the returned message before changing anything in Spiryra.

5.1Import certificates

Importing brings an existing certificate and its chain into inventory so expiry tracking, ownership, deployment and reporting cover it.

1. Open Issue & Import and choose Import.
2. Paste or upload the PEM certificate. Add the chain when you want a full-chain bundle for deployment.
3. Fill the operational metadata: owner team, application, business and technical contact.
4. Save and confirm the parsed subject, SANs, key algorithm, issuer and expiry look correct.

POST /api/certificates/import

What import does and does not do

• It stores the certificate, chain and metadata; it does not obtain a private key.
• An imported certificate can be deployed to targets as a file — useful when the key is generated and held elsewhere.
• Rows that came from discovery or a legacy source may be metadata-only; policy findings only assess fields that were actually recorded.

5.2Issue certificates

Issuance always goes through a configured connector. Spiryra generates the private key locally, builds the PKCS#10 request, and validates the returned certificate before it enters inventory.

Issue from the console

1. Choose the CA: pick a connector from the issuer list.
2. Enter the common name and the SANs (DNS and IP). The SAN policy in Settings decides what the console allows.
3. Choose key algorithm and size, requested validity and whether the key is retained in the vault.
4. Optionally reference an existing deployment workflow. This screen attaches workflows that already exist in Orchestration and never creates one; the workflow's steps decide which files are written (leaf, chain, full-chain bundle).
5. Submit and confirm the certificate in inventory.

POST /api/certificates/issue

Issue from your own CSR

If the key must never leave the requesting system, choose I have my own CSR and paste a PKCS#10 request. The CSR is validated (signature, key size, subject and SAN agreement) before it is sent to the CA.

POST /api/certificates/csr/sign

5.3Renew certificates

Renew on demand

1. Open the certificate and choose Renew.
2. Keep the same common name, SANs and issuer; decide whether to reuse the retained key or generate a new one.
3. Submit. The new certificate is stored first; the previous one is then marked replaced.

POST /api/certificates/{id}/renew
POST /api/renewals/{certId}/retry

Scheduled renewal

The renewal scheduler opens work when a certificate enters the configured window, retries failures with backoff, and escalates a repeated-failure streak at most once per streak. Administrators can trigger a sweep:

GET  /api/renewals
POST /api/renewals/run

Renewal plus deployment

A renewal can carry its deployment forward: the referenced workflow runs again — target, destination path, approved service reload and TLS check — and the deployment becomes verified only after the file readback and the presented fingerprint agree.

5.4Revoke certificates

1. Open the certificate and choose Revoke.
2. Choose the reason. The dialog repeats the subject and serial so you can confirm you are revoking the right certificate.
3. Confirm. Spiryra asks the CA to revoke and updates inventory only after the CA accepts.

POST /api/certificates/{id}/revoke

What happens next

• The record is marked revoked with the reason and the CA's confirmation.
• If a retained key exists for that certificate, it is destroyed.
• The first revoked result seen by the revocation worker also writes a certificate.ca_revoked audit event and queues one ca_revocation notification.
• A CA-side revocation also reconciles inventory: the certificate stops reading as valid and is marked revoked once, with a certificate.ca_revocation_reconciled audit event. Only the state changes — the retained key is kept so the revocation can be investigated (an explicit revoke afterwards still destroys it), a certificate that was already replaced keeps that history, and replacing the certificate or rolling back a deployment stays an operator decision.

5.5Retained keys and downloads

Key retention

When retention is enabled at issue or import, the private key is written into the vault under the certificate id, sealed with AES-256-GCM using SPIRYRA_VAULT_KEY. Retention is what makes reuseKey renewal possible.

Downloads

Rotation and rewrap

Rotating the vault key rewraps retained leaf keys along with connector credentials and other sealed values (11.3). If a value cannot be opened, nothing is changed and the response names the affected table.

5.6Inventory, owners and expiry

What inventory holds

• Common name, SANs, key algorithm and size, issuer and issuer kind.
• Status: active, expiring, expired, revoked or replaced, with days remaining.
• Ownership: owner team, application, business and technical contact.
• Source: managed (issued through a connector), imported, or discovered from a target.
• Linkage to deployments and to orchestration runs that touched it.

Working with the list

• Filter by status, issuer, owner and expiry window; the expiring view includes already-expired certificates and those inside 90 days.
• Open a row for the chain, retained-key state, deployment history and audit trail.
• Assign or change the owner team where you have certificates.manage_owners (administrator-only by design).
• Export the current view for reporting; expiry and ownership reports page through the full record set.

Scoped visibility

An account with assigned scope only sees certificates it holds a grant for, and never sees another team's rows. Owners always see their own certificates.

5.7Certificate policy settings

Policy settings are what make the console refuse a request that would produce a certificate you cannot manage. Review them before the first issue.

GET   /api/settings
PATCH /api/settings
GET   /api/selftest

6.1Deployment paths and the target model

There are three ways to deliver a certificate to a server. All three write the same artifact set, record the same evidence and refuse to claim success without reading the file back.

Objects

• Server — a registered host: an enrolled agent, an SSH target or a WinRM target, with its sealed credential.
• Installation (deployment target) — a certificate bound to a server and a destination: absolute path, optional service, optional TLS endpoint/SNI, and a 1–30 second probe timeout.
• Deployment attempt — one dispatch. It stores the expected SHA-256, queues the job, and only becomes active when the host reads the file back and reports a matching fingerprint.

Register a target

1. Open Servers and choose the transport.
2. For an agent, enroll it (6.2) and wait for its first poll. For SSH or WinRM, enter the host, port, user and credential — the credential is sealed immediately.
3. Confirm the target shows ready: the agent is online, or the SSH/WinRM connection test passed.

Edit a target later

Service, TLS endpoint, SNI and timeout can be changed without detaching the target; the agent, destination, verified certificate and deployment history stay intact.

POST   /api/installations
PATCH  /api/installations/{id}
POST   /api/installations/{id}/deploy
POST   /api/installations/{id}/rollback

6.2Install and enroll the native agent

The agent is a standalone Go executable. It needs no Node.js, npm or JavaScript runtime, and it never listens on a port.

Download

Open Agent Downloads in the console and pick the platform, or fetch directly:

/downloads/agents/spiryra-agent-linux-amd64
/downloads/agents/spiryra-agent-linux-arm64
/downloads/agents/spiryra-agent-windows-amd64.exe

These paths serve allowlisted filenames without authentication, so a host can fetch its own binary before it holds a credential. Checksum or sign the file in your own pipeline if you need supply-chain proof.

Enroll one host

1. Open Agent Fleet & Enrollment → Enroll agent. The console returns a one-time credential, shown once.
2. Write it to a restricted file on the host (mode 0600, or an ACL-limited path on Windows).
3. Set the environment and start the agent.

# Linux
export SPIRYRA_URL='https://spiryra.example.com'
export SPIRYRA_TOKEN_FILE='$HOME/.config/spiryra/agent-token'
export SPIRYRA_RESULT_OUTBOX_DIR='$HOME/.config/spiryra/result-outbox'
export SPIRYRA_ENROLLMENT_TOKEN_FILE='/secure/path/to/bootstrap-token'
chmod +x ./spiryra-agent-linux-amd64
./spiryra-agent-linux-amd64

# Windows (PowerShell)
$env:SPIRYRA_URL='https://spiryra.example.com'
$env:SPIRYRA_TOKEN_FILE="$env:ProgramData\Spiryra\agent-token"
$env:SPIRYRA_RESULT_OUTBOX_DIR="$env:ProgramData\Spiryra\result-outbox"
$env:SPIRYRA_ENROLLMENT_TOKEN_FILE='C:\secure\bootstrap-token'
.\spiryra-agent-windows-amd64.exe

The Windows .exe is the agent runtime; PowerShell only launches or installs it.

Bulk rollout with a campaign token

Instead of a per-host credential, set SPIRYRA_AGENT_ENROLLMENT_TOKEN (at least 32 characters) on the control plane and point each host's SPIRYRA_ENROLLMENT_TOKEN_FILE at that campaign secret. The host self-enrolls and receives its own identity. A campaign token is a shared secret for the duration of the rollout — rotate it afterwards.

A campaign token carries no principal, so on a deployment that hosts more than one tenant set SPIRYRA_AGENT_CAMPAIGN_TENANT to the tenant the campaign belongs to. Every credential it hands out, and therefore every finding those hosts report, is filed there; leave it empty to use the default tenant, which is correct for a single-tenant installation. A value that is not a tenant identifier refuses enrollment instead of falling back, so a typo cannot put a fleet's evidence into an estate that does not own those hosts.

Credential lifecycle

• The agent persists its credential, commits it, then polls /api/agent/jobs?version=… every 15 seconds.
• Every SPIRYRA_ROTATE_DAYS (default 30) it prepares a new token, persists it, then commits. Both tokens stay valid until commit finishes, so a crash cannot lock the host out.
• Removing an agent revokes its credential immediately and clears any pending rotation.

Choose the agent's capabilities

Enrollment asks which job kinds this host may receive. A credential is only handed the jobs its capabilities cover; a queued job for anything else is failed with a denial instead of being delivered later.

Change them later from Agent Fleet & Enrollment → Scopes (PATCH /api/agents/{id}/scopes). Narrowing applies to the next poll, and a job that was already dispatched is refused when the capability it needs has been removed. New enrollments start with every capability, so an existing host keeps working until you narrow it.

Optional: bind the credential to a client certificate

By default the token is the only thing an agent presents, so anyone who copies the file can poll that host's feed. Bind the credential to one client certificate and the token alone stops working: the request has to arrive through a TLS terminator that verified that exact certificate, and a different certificate is refused. The binding is per agent and optional, so an existing fleet keeps working until you enable it host by host.

1. Terminate TLS in front of the API with client-certificate verification enabled. The shipped nginx configuration uses ssl_verify_client optional; the API speaks plain HTTP behind it and never sees the certificate itself.
2. Forward what the terminator verified as x-client-cert-pem (nginx $ssl_client_escaped_cert), x-client-cert-fingerprint (SHA-256 of the DER, what Envoy's %DOWNSTREAM_PEER_FINGERPRINT_256% produces), or both, plus x-client-cert-verify with SUCCESS. The terminator must overwrite those headers; nginx does for the ones it sets.
3. Bind the certificate when you enroll the host (mtlsFingerprint) or later with PATCH /api/agents/{id}/mtls. Upper case and colon separators are normalised to the stored lower-case digest.
4. If the API is reachable without going through that terminator, set SPIRYRA_AGENT_MTLS_PROXY_SECRET on the control plane and have the terminator send it as x-spiryra-proxy-secret. The certificate headers are then ignored unless the secret matches, so a direct client cannot forge them.
5. DELETE /api/agents/{id}/mtls clears the binding, and the same token works again with no certificate.

6.3Agent jobs, readback, reload and TLS verification

A deployment is a small pipeline on the host: write the file, read it back, reload the service, then probe what the socket actually presents. Each stage is recorded.

What the Linux agent needs before it installs anything

Certificate-file installation is gated twice on the host, and both gates are off by default. Until the lab opt-in and a usable recovery key are in place, an install job fails with a named error; the agent does not fall back to writing the file.

The recovery key is a durable host secret, not a per-run value: the journal sealed with it before the write must still be readable after a restart. Generate one with openssl rand 32, keep it outside the certificate directories, and back it up separately — a lost key leaves an interrupted deployment with no rollback path. Set SPIRYRA_RECOVER_ON_STARTUP=1 to replay an unfinished journal at boot; the agent then refuses to start, instead of serving jobs, when the key or the journal directory is missing.

The script the agent enforces

1. Write the certificate material to the destination path, inside SPIRYRA_INSTALL_ROOTS. A path outside those roots is refused.
2. Read back the file and report its SHA-256. The deployment fails if it differs from the expected fingerprint.
3. Reload the named service, but only when it appears in SPIRYRA_APPROVED_SERVICES. A service outside the list is not touched.
4. Probe the TLS endpoint, only if it appears in SPIRYRA_TLS_PROBE_ALLOWLIST; an empty list denies every probe. The requested timeout is capped by SPIRYRA_TLS_PROBE_MAX_TIMEOUT_SECS before any file is written.
5. Report the leaf certificate actually served — fingerprint, subject and expiry — plus the effective timeout and reload result.

What the control plane requires

• A timeout and a matching presented fingerprint before a deployment is marked verified.
• Both the requested and the effective timeout are stored, and audit events carry the effective value.
• A mismatch fails closed and queues an automatic rollback when the key did not change.
• Results are delivered from a durable local outbox, so a brief network failure does not lose evidence.

A deployment is a workflow you build and test in Orchestration, then reference from the issue or import screen. Those screens only attach an existing workflow — they never generate one — so the artifact list, reload and verification steps are the same for a first issue and for every renewal.

6.4Agent fleet and signed upgrades

Fleet view

GET    /api/agents
GET    /api/agents/fleet
POST   /api/agents
POST   /api/agents/bulk
DELETE /api/agents/{id}

The list shows total, online, outdated and never-connected counts, each agent's build label and last poll, and the last 25 jobs. Bulk enrollment creates one identity and one token per host — revoking one agent never disturbs the rest.

How an upgrade works

1. Publish a release entry in SPIRYRA_AGENT_RELEASE_CATALOG as local JSON: { "releases": [ { "version", "os", "arch", "sha256", "url", "signature" } ] }.
2. The agent stages a release only when SPIRYRA_AGENT_UPGRADES_ENABLED=1, a pinned SPIRYRA_UPDATE_SIGNING_PUBLIC_KEY exists, and the stage and intent directories are absolute paths.
3. The Linux package already installs the supervisor, its timer and a root-owned /etc/spiryra-agent/supervisor.env; fill in that file and enable spiryra-upgrade-supervisor.timer. For a hand-managed install use scripts/install-upgrade-supervisor-linux.sh (root) or scripts/install-upgrade-supervisor-windows.ps1 (elevated). Set SPIRYRA_AGENT_EXECUTABLE to the installed agent binary, never to the supervisor.
4. Create a rollout, dispatch it, and watch outcomes. Agent completion means staged, not installed.

POST /api/agent-upgrades/rollouts
POST /api/agent-upgrades/rollouts/{id}/approve
POST /api/agent-upgrades/rollouts/{id}/dispatch
GET  /api/agent-upgrades/rollouts/{id}/outcomes
POST /api/agent-upgrades/rollouts/{id}/cancel

Installing the agent

scripts/package-agent.sh builds the installable artifacts from one source tree:

• spiryra-agent_<version>_amd64.deb and _arm64.deb for Debian and Ubuntu.
• spiryra-agent-<version>-1.x86_64.rpm and .aarch64.rpm for RHEL, Rocky, Alma and SUSE.
• spiryra-agent-<version>-windows-amd64.zip: the executable, both installer scripts and INSTALL.txt.
• SHA256SUMS, plus SHA256SUMS.sig when SPIRYRA_PACKAGE_SIGNING_KEY names a key.

A package installs the agent at /usr/local/bin/spiryra-agent, a separate supervisor copy at /usr/local/libexec/spiryra-upgrade-supervisor, the three systemd units, and 0600 root-owned configuration. It does not start anything: the agent has no control-plane URL or credential until you set SPIRYRA_URL and enable spiryra-agent.service.

The gate's agent-packages stage builds these artifacts and installs them in throwaway Debian and EL9 containers, so a package that installs with the wrong file mode, lands a unit where the distribution does not read it, or fails to remove cleanly fails the release.

6.5Clientless SSH delivery

No agent is installed. The control plane connects with a sealed SSH key, writes the public certificate, reloads an approved service and verifies the file and the TLS endpoint.

Prerequisites on the target

• SSH reachable from the API container on TCP 22.
• A user with write access to the certificate path and permission to reload the service.
• A host key recorded when you register the server — the connection is pinned to it.

Register and deploy

1. Servers → Add server → SSH. Enter host, port and user, then paste the private key (and an OpenSSH user certificate if your estate requires one).
2. Save. The credential is sealed with the vault key and never returned.
3. Create the deployment target: absolute certificate path, optional file mode, optional service reload, optional TLS endpoint.
4. Deploy. The API writes the file, reloads the approved service, reads the file back and probes the endpoint.

Safety properties

• The command executed for a reload is fixed by the target configuration, not composed from user input.
• A failed write leaves the previous file in place; the deployment records the failure instead of retrying silently.
• Rollback reinstalls the previous certificate with a fresh verification and marks the original deployment restored.

6.6Clientless WinRM delivery

Windows targets are reached over WinRM with a sealed password. Certificate files are written, services restarted, and the presented certificate reported — all without installing Spiryra on the host.

Prerequisites

• WinRM enabled. Production should use HTTPS on 5986 with a listener certificate the API trusts.
• Basic authentication enabled on the listener. Windows disables it by default and refuses every Spiryra request with WinRM authentication failed until it is on. In an elevated PowerShell on the target:
  Set-Item WSMan:\localhost\Service\Auth\Basic -Value $true
  For a lab listener on 5985, unencrypted traffic must be allowed as well: Set-Item WSMan:\localhost\Service\AllowUnencrypted -Value $true and Restart-Service WinRM. Do not enable AllowUnencrypted on a host reachable outside its management network; use 5986 there.
• An account that can write the destination path and restart the named service.
• SPIRYRA_AGENTLESS_WINRM_ALLOW_HTTP=true only for a lab using 5985.

Register and deploy

1. Servers → Add server → WinRM: host, port, user and password (sealed immediately).
2. Create the deployment target with the Windows path, the service to restart and the TLS endpoint to probe.
3. Deploy. The API writes the file, restarts the service, then reads the certificate the socket serves and compares its fingerprint.

Script behaviour

6.7Windows PFX store, service-account ACL and IIS

Some Windows services need the certificate in the machine store rather than a file. The agent imports the PFX, binds the private key to the service identity that must read it, and can move — or create — an IIS HTTPS binding for the imported certificate in the same job.

How the import works

1. Stage the PFX and a DPAPI-protected password file locally on the target. A user-scope blob (ConvertFrom-SecureString) works when the staging account also imports; a machine-scope blob is accepted as well, and is what you need when a service account, WinRM or SYSTEM does the import. The API payload has no password field.
2. The agent imports into LocalMachine/My with the machine key set; the recorded evidence includes the store, hasPrivateKey and the key method (cng or capi).
3. Set SPIRYRA_WINDOWS_PFX_SERVICE_ACCOUNT to the SAM or UPN identity that reads the key. A bare local name is machine-qualified before use.
4. The agent writes an Allow-Read ACE on the key container (Microsoft\Crypto\Keys for CNG, Microsoft\Crypto\RSA\MachineKeys for CAPI), reads it back, and fails the job if it could not be written.

Set SPIRYRA_WINDOWS_PFX_REQUIRE_SERVICE_ACCOUNT=true to fail closed when no identity is configured. The account is host configuration only, so a control-plane caller cannot choose which identity receives private-key access. The control plane also rejects a succeeded result whose ACL evidence is partial.

IIS certificate changeout

IIS serves TLS through HTTP.sys, which accepts only a certificate that is in LocalMachine\My with its private key. A file deployment of the public PEM therefore cannot renew an IIS binding; the rebind belongs to the PFX import that put the key there.

1. Open Installations → Windows IIS changeout and choose the channel: a Windows agent that already holds the staged PFX, or a registered WinRM server with no agent.
2. Name the staged PFX and DPAPI password files and give the certificate's public SHA-256 fingerprint.
3. Set the IIS site and its HTTPS binding, for example Default Web Site and *:443:www.example.test. Supply both or neither.
4. The transport imports the certificate, then matches the site's HTTPS bindings: exactly one match is moved to the new thumbprint with the previous one recorded, and a site that has none gets the binding created for this job. The HTTP.sys registration is read back before success is reported.
5. Optionally name an application pool (agent channel only) to have the job recycle it once the binding is confirmed, so the worker that has to pick up the new key restarts without you. It runs after the bind, outside the rollback path: a failed restart reports the reason and leaves the certificate serving.
6. The row appears under Windows store imports with the store, private-key ACL, IIS site/binding, requested pool and recycle evidence, previous and applied thumbprints, or the rejection reason.

Agent or WinRM

Binding the key to an identity grants use of it, not only an entry in a list. On a live Windows Server 2025 host the agent's import binds NT AUTHORITY\NETWORK SERVICE with the same Set-Acl call it uses in production, and a probe running as that identity signs a payload with the key; an identity without the ACE is refused, and the control leg binds that second identity and has it sign, which shows the refusal came from the grant. Run it with scripts/verify-windows-pfx-identity-e2e.py; it removes the certificate, the probe and any task it created.

A script that does not fit one WS-Man command line is uploaded to the target's temp directory in bounded chunks and run from that file. Sent inline, WS-Man answers The command line is too long and runs nothing, so the control plane never sends the import inline.

POST /api/installations/windows-pfx
{"id":"job_pfx_000001","agentId":"agent_00001",
 "pfxName":"tls-server.pfx","passwordName":"tls-server.dpapi",
 "expectedSha256":"<64 hex digits>",
 "iisSite":"Default Web Site","iisBinding":"*:443:www.example.test"}

# after a confirmed bind, recycle every pool that has to load the new key
{"id":"job_pfx_000002","agentId":"agent_00001",
 "pfxName":"tls-server.pfx","passwordName":"tls-server.dpapi",
 "expectedSha256":"<64 hex digits>",
 "iisSite":"Default Web Site","iisBinding":"*:443:www.example.test",
 "iisAppPools":["DefaultAppPool","Reports Pool"]}

Binding rules and evidence

6.8Deployment rollback and recovery

Single deployment rollback

1. Open the certificate's deployment history and choose Rollback on the active deployment.
2. The previous certificate is reinstalled, read back and verified.
3. The original deployment is marked restored and the rollback is recorded with its own evidence.

POST /api/installations/{id}/rollback

When a write succeeds but verification fails

If the file matches but the presented fingerprint does not, the deployment fails and — when the key did not change — an automatic rollback is queued. If the key did change, the old certificate cannot restore the service, so the failure is surfaced for an operator instead of pretending to fix it.

Recovery ledger

Actions with no automatic inverse stay visible: run commands and external API calls in a batch rollback are written to a recovery ledger with the command or call to review. The deployment detail lists what was reloaded, what needs manual action and who should review it.

7.1Orchestration concepts

Orchestration turns a repeatable certificate operation into a durable, auditable run: write files, reload services, verify endpoints, wait, ask for approval, call an API.

Step kinds

Placeholders

Steps can reference the run's certificate and target: {{cert.pem}}, {{cert.pemEscaped}}, {{cert.chain}}, {{cert.fullchain}}, {{cert.commonName}}, {{cert.serial}}, {{cert.fingerprint}}, {{target.name}}, {{target.host}}, {{target.platform}}, {{target.fileStem}}, {{workflow.name}} and {{run.id}}.

GET  /api/orchestration/meta
GET  /api/workflows
GET  /api/runs
GET  /api/runs/{id}

7.2Build a workflow

1. Open Orchestration → New workflow and name it for the operation, not the environment.
2. Bind the certificate and the targets. A target must already be registered (6.1).
3. Drag steps from the palette onto the canvas and order them. Host steps need an agent, SSH or WinRM transport that the target supports.
4. Fill each step: destination path and file mode for copy_file; the approved service for reload_service; host, port and SNI for verify; URL, method and body for api_call.
5. Save, then run against one target first. Batches come after a single run succeeds.

Design rules that keep runs debuggable

• Keep copy_file → reload_service → verify contiguous. That is the sequence that produces usable evidence.
• Put an approval_gate before anything that reaches a customer-facing service.
• Prefer several small workflows to one long chain: a failure then leaves a shorter, clearer state to reason about.
• Use delay only where a real convergence window exists, not as a substitute for verification.

7.3Host step safety and conditions

Allowlists decide, not the workflow

A workflow that asks for something outside these lists fails at the host with a clear error. Widening an allowlist is a host-side change, made deliberately on that server — never a control-plane setting.

Allowlists for clientless SSH steps

When a step runs over SSH instead of through an agent, the same model is enforced from the API process, with its own lists so a server does not inherit another path's grants. These are API-host environment variables, and an empty list denies the operation.

A clientless write accepts certificate PEM blocks only, verifies the digest after the move, and records backup: none — there is no sealed journal on the API side, so a failed batch lists the write for operator review instead of claiming it restored the file.

Allowlists for clientless WinRM steps

A server registered with the winrm transport runs the same four host steps from the API process, over the sealed password and the same HTTPS listener a clientless deployment uses. The lists are separate from SSH's, so a Windows fleet never inherits a Linux path grant. An empty list denies the operation.

Windows has no service reload, so a reload_service step restarts the service and its evidence records mode: reload next to applied: restart — the run says what happened rather than implying a graceful reload. A WinRM write accepts certificate PEM blocks only, checks the digest before the move and after reading the file back, and also records backup: none.

Conditions

A step can carry a condition over the run's state, so a chain can branch on what actually happened: proceed only when the certificate is active, skip an API call when verification failed, or stop before a reload when the file digest already matches. Conditions are evaluated against recorded step output, not against assumptions.

7.4Approval gates

An approval_gate stops the run before the next step. The run waits in Orchestration → Approvals, where an administrator approves or denies it with a reason.

GET  /api/orchestration/approvals
POST /api/runs/{id}/approval

7.5Parallel groups and multi-target batches

Parallel groups

A workflow may contain bounded, contiguous, read-only groups that run concurrently — for example discovery or verification across several endpoints. Write steps never run in parallel: a reload or a file write stays sequential so the evidence order is unambiguous.

Batches

• Batch creation is atomic: every target gets a run, or none does.
• A failed target halts its siblings before their next step, so a broken certificate does not spread across the estate.
• Approved service reloads inside a batch are re-issued after restores, so the service ends up running against the files that are actually on disk.
• Batch detail shows per-target state, plus what was restored, what was reloaded and what needs review.

POST /api/runs
GET  /api/runs/{id}
POST /api/workflows/{id}/run-batch

7.6Batch rollback and the recovery ledger

A failed batch compensates every succeeded step, not just file writes. The plan is built in reverse completion order and each part is recorded.

1. Restore files. Sealed per-step backups are restored first, so the host holds the previous certificate material.
2. Re-issue reloads. Each approved service reload is issued again so the service runs against the restored files.
3. Record the irreversible. Steps with no automatic inverse — run_command, api_call and any future kind — are written to the recovery ledger with the kind, reason and the command or call to review.

The batch detail carries reloaded, manual, manualSteps and operatorReview; the audit event stays batch.rolled_back at warning level while listing what an operator must finish.

Restart behaviour

On startup the API resumes queued and running runs, preserves succeeded steps, reattaches host steps to their existing agent job and fails in-flight control-plane steps closed. A database lease prevents two API replicas from driving the same run.

8.1Server inventory and findings

Discovery finds the certificates already on your servers, so they can be tracked, corrected or promoted into inventory — before they expire in a place nobody is watching.

Run a discovery

1. Open Servers and choose a ready agent, SSH or WinRM target.
2. Run discovery. The agent inventories certificate files inside its install roots; SSH and WinRM targets follow the same allowlisted paths.
3. Review the findings: path, subject, issuer, expiry and the fields that could not be read.
4. Promote a verified public certificate into inventory, or correct the finding state so it stops appearing as new.

GET   /api/findings
PATCH /api/findings/{id}/state
POST  /api/findings/{id}/import
GET   /api/installations

What discovery does not do

• It does not read or exfiltrate private keys. Findings are certificate metadata.
• It does not scan arbitrary paths outside the agent's install roots.
• It does not merge duplicates silently — a promoted finding becomes a certificate row with its own source.

8.2TLS presentation monitoring

Deployment verification proves what a socket served at one moment. Continuous monitoring proves it kept serving the right certificate afterwards.

Create a monitor

1. Open Monitoring → Add endpoint and enter host, port and — when the service needs it — SNI.
2. Choose the expected certificate, or let the monitor record the first observed leaf as its baseline.
3. Save and run a scan to confirm the endpoint is reachable from the API.

GET  /api/monitor/tls
POST /api/monitor/tls
GET  /api/monitor/tls/{id}/history
POST /api/monitor/scan

What each check records

Alerts are raised on change and on expiry thresholds, and can be acknowledged per endpoint. History is retained so you can answer “when did this change?” rather than only “is it wrong now?”.

8.3Revocation checks (OCSP and CRL)

For active certificates, the revocation worker polls the authority's OCSP responder or CRL endpoints and records what it finds. This closes the gap between “Spiryra thinks it is active” and “the CA says it was revoked”.

What happens on a revoked result

1. The certificate's recorded revocation state is updated from the CA answer.
2. On the first revoked result, a certificate.ca_revoked audit event is written.
3. One ca_revocation notification is queued to the owner and configured channels — once per certificate, not on every poll.
4. Inventory state is reconciled to revoked once, with a certificate.ca_revocation_reconciled event. Replacing the certificate and rolling back a deployment remain operator decisions, and the retained key is kept for investigation.

Status and limits

• A real Google Trust Services CRL was checked in the lab.
• OCSP runs against a real OpenSSL responder in the test suite (revocation::tests::a_live_responder_reports_good_and_revoked): one certificate it reports good and one revoked, through the same request path the worker uses. The responder is generated by the test, so no external service is needed.
• A CA that publishes neither OCSP nor CRL cannot be checked — record that as a known gap for that issuer.

8.4Alerts and acknowledgement

Alerts are derived from certificate expiry and monitoring observations, then acknowledged or resolved by operators. The alert row is the alert's own record, not a copy of the certificate: it keeps the last observation (severity, message, threshold, common name, expiry and days remaining, as seen at the last scan), the alert lifetime (createdAt, lastSeenAt) and the operator status. The list is the live expiry projection merged with those rows, so history survives a certificate leaving the warning window. A scan reopens an alert whose condition returns and reopens an acknowledged alert that becomes critical; a resolved alert stays readable under ?status=resolved.

GET  /api/alerts
POST /api/alerts/{id}/ack
POST /api/alerts/{id}/resolve

9.1Local accounts and roles

Roles

Manage accounts

GET    /api/users
POST   /api/users
PATCH  /api/users/{id}
DELETE /api/users/{id}

Administrators create accounts, change roles, reset passwords, disable and delete. The last active administrator cannot be disabled or deleted — the console refuses rather than locking the deployment out.

Durability

• Accounts live in clm_users as Argon2id hashes; sessions live in clm_sessions as SHA-256 digests.
• Sessions survive an API restart until they expire.
• Disabling an account revokes its sessions immediately.
• The environment bootstrap administrator exists to create the first real accounts — it is not a shared operational login.

9.2Teams, ownership and grants

Roles say what kind of action you may take. Teams, ownership and grants say which resources you may take it on.

Three layers

• Role — viewer, operator or administrator.
• Scope — all (every resource) or assigned (only explicit grants). Existing installations default to all, so enabling grants does not silently remove access.
• Grant — one row binding an account to a certificate or connector with read or manage.

Owners always see and manage their own certificates, even on an assigned account. A write additionally requires an operator-or-higher role and a manage grant.

Configure access

1. Open Permissions and create or select a team.
2. Set the account's scope to assigned when it should be limited.
3. Add grants: choose the certificate or connector and the permission level.
4. Use Preview to ask what the account would be allowed to do before you save.

GET   /api/access/summary
GET   /api/access/catalog
POST  /api/access/teams
POST  /api/access/owners
GET   /api/access/preview
GET   /api/access/audit

What filtering actually does

• Inventory, detail, orders and connector reads are filtered by grant; a row is visible when its server or its certificate is granted.
• Writes outside a grant are refused with 403, not silently dropped.
• A hidden resource is indistinguishable from a missing one, so grants do not leak existence.

9.3OpenID Connect

OIDC sign-in uses the authorization-code flow with PKCE, nonce, state and return-path handling, and validates the ID token signature, issuer, audience, expiry and nonce before a session is created.

Configuration

Set it up

1. Register the application at the provider with the exact redirect URI above.
2. In Settings → Identity providers, enter the issuer and client values and save.
3. Use the built-in Check action: discovery, JWKS reachability, issuer and client consistency are reported per check.
4. Sign in through the provider in a private window and confirm the resulting role and team.

GET  /api/auth/providers
GET  /api/auth/oidc/login
GET  /api/auth/oidc/callback

Signing in once a provider is configured

The provider becomes the default. Opening the console signed out redirects to it after a four-second hold, so somebody who only knows the site address never chooses a method. The hold is deliberate: the same page carries the escape hatch, and a redirect nobody can interrupt is a redirect that locks you out when the identity provider is down.

• Bypass SSO on the sign-in page stops the redirect and opens the local sign-in address.
• /login/local reaches the same screen directly, with no redirect. This is the address to bookmark and to keep in a runbook. GET /api/auth/providers returns it as localLoginUrl, and the console reads that value instead of hardcoding a path.
• Local (break-glass) accounts sign in with username and password, exactly as they did before federation was configured. Password expiry, the administrator recovery token and the expired-password change all work there.
• API key signs in as a scoped service account. Paste the token issued on Settings → Service Accounts; the console presents it as a bearer credential, so the session shows only the resource types and actions that token was scoped for, and never becomes an administrator session. Revoking the token ends the session as soon as the next request is made, and the key is held in the tab's session storage rather than a cookie.

9.4SAML 2.0

SAML sign-in uses SP-initiated AuthnRequests with signed assertions, replay protection and strict issuer matching. Once it is configured it is the default sign-in method; the break-glass address is /login/local (see 9.3).

Configuration

Exchange metadata

1. Download /api/auth/saml/metadata and give it to the IdP administrator, or copy the entity ID and ACS URL.
2. Map the IdP's user identifier to the account email used in Spiryra.
3. Paste the IdP certificate and SSO URL here, then save.
4. Sign in through the IdP in a private window and confirm the role.

GET  /api/auth/saml/metadata
GET  /api/auth/saml/login
POST /api/auth/saml/acs

9.5SCIM 2.0 provisioning

SCIM lets your identity provider create, update, deactivate and group users automatically. Spiryra exposes the standard Users and Groups resources plus discovery documents.

Endpoints

GET    /scim/v2/ServiceProviderConfig
GET    /scim/v2/ResourceTypes
GET    /scim/v2/Users          POST /scim/v2/Users
GET    /scim/v2/Users/{id}     PUT  /scim/v2/Users/{id}
PATCH  /scim/v2/Users/{id}     DELETE /scim/v2/Users/{id}
GET    /scim/v2/Groups         POST /scim/v2/Groups
GET    /scim/v2/Groups/{id}    PUT  /scim/v2/Groups/{id}
PATCH  /scim/v2/Groups/{id}    DELETE /scim/v2/Groups/{id}

Connect the provider

1. In Settings → Identity providers → SCIM, generate a SCIM token. It is shown once.
2. Configure the provider with the base URL https://spiryra.example.com/scim/v2 and that token.
3. Map IdP groups to Spiryra roles or teams under Permissions.
4. Provision one test user and confirm they appear with the expected role before enabling the full directory sync.

Fail-closed behaviour

• A SCIM-managed account is always evaluated against custom policies; its legacy scope never widens access.
• Removing the last group-to-role mapping narrows the account instead of leaving it with its previous role.
• Deactivating a user removes access immediately; deleting a user preserves the audit trail.

9.6API service accounts

Machine credentials for automation that should not sign in as a person. A token carries an explicit allow-list drawn from the console's permission catalogue. It can be a bearer secret, or a certificate credential with no secret at all.

Credential shape

Authorization: Bearer csa.<token id>.<secret>

The secret is 32 random bytes, base64url, 43 characters. Only its SHA-256 digest is stored, the plaintext is returned once at creation, and listing never returns the digest or the credential.

Certificate credential (no secret)

Issue a token with clientCertificate set to the PEM of the certificate the automation host will present, and no secret is created or returned: the response carries authMethod: "mtls" and the bound fingerprint instead. From then on the API accepts that certificate — forwarded by the TLS terminator in x-client-cert-fingerprint (or x-client-cert-pem) with x-client-cert-verify: SUCCESS — as the credential. A stolen bearer token cannot exist because there is none, and one certificate backs one active credential.

curl -sS -X POST https://spiryra.example.com/api/service-accounts/svc_…/tokens \
  -H "Authorization: Bearer $SPIRYRA_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\":\"api client\",\"scopes\":[\"certificates.read\"],\"clientCertificate\":\"$(cat client.pem)\"}"

The terminator must overwrite those headers; set SPIRYRA_AGENT_MTLS_PROXY_SECRET to require a shared proxy secret when it cannot.

Create an account and token

curl -sS -X POST https://spiryra.example.com/api/service-accounts \
  -H "Authorization: Bearer $SPIRYRA_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"inventory sync","description":"nightly report"}'

curl -sS -X POST https://spiryra.example.com/api/service-accounts/svc_…/tokens \
  -H "Authorization: Bearer $SPIRYRA_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"report","scopes":["certificates.read","servers.read"],"expiresInDays":90}'

How a token is authorized

1. Administrator-only paths and methods are refused outright.
2. The route is mapped to the action it performs; an unclassified route is refused.
3. That action must appear in the token's scopes. Scopes match exactly — certificates.read cannot issue, renew or revoke.

Team-scoped accounts

An account without a team is instance-wide: a certificates.read token sees every certificate, which suits inventory export and reporting. Bind the account to an owner team instead and the same token reaches only the certificates, servers, workflows, connectors and agents that team owns — the action scope still applies, but the object scope is the team. A certificate owned by another team answers 404, exactly as it does for a scoped person. The team must already exist under Roles & Permissions; a misspelt id is refused rather than quietly narrowing the account to nothing.

Manage tokens in the console

Settings → Service Accounts (administrator only) manages the same API: an account list with its team scope, live-token counts and a Disable action that revokes every live token, a token list with scope summary, authentication method, expiry, last use and state, and an issue dialog. The dialog takes a name and lifetime, optionally binds a client certificate instead of issuing a secret, and shows scopes as checkboxes grouped by resource, built from the same permission catalogue the Roles page uses. Actions whose handlers require an administrator session are shown disabled with the reason, because a token can never reach those surfaces. A bearer plaintext appears once after issue, with a copy button; a certificate credential shows its fingerprint and no secret.

Full detail, including the credential format and the test coverage, is in SERVICE_ACCOUNTS.md.

9.7The administrator boundary

A set of surfaces is administrator-only no matter what grants or scopes an account holds. The boundary is explicit, method-scoped and audited by a static check.

Administrator-only prefixes

/api/access/     /api/users        /api/settings     /api/notifications
/api/selftest    /api/agent-upgrades/                /api/agentless/
/api/connectors/scep/   /api/connectors/est/          /api/connectors/adcs/
/api/demo/       /api/enterprise/deployment/          /api/migration/
/api/service-accounts

Plus exact method/path pairs such as POST /api/renewals/run, POST /api/monitor/scan and GET /api/orchestration/approvals, and suffix rules such as /api/runs/{id}/approval.

Deliberate exceptions

• GET /api/notifications — an owner reads their own delivery history.
• GET /api/agent-upgrades/rollouts — read-only rollout status.
• GET /api/enterprise/deployment/recovery — read-only recovery state.
• POST /api/agentless/certificates/execute — scoped clientless delivery.
• Migration reconcile routes — method-scoped so a sibling verb cannot inherit the exception.

Why it is trustworthy

• Exceptions are listed per HTTP method, so adding a method to the same path does not widen access.
• An unclassified API route is refused for non-administrators instead of falling through.
• scripts/audit-rust-authorization.py fails the release gate if a route is not classified. It currently reports 219 route-method pairs with 0 needing classification.

10.1SMTP email

Configure the relay

1. Open Settings → Notifications (or the Notifications page) and select SMTP.
2. Enter host, port, TLS mode, sender address and the public console URL used in links.
3. Enter the username and password. The password is sealed and never returned.
4. Send a test message to an address you control.

Console settings take precedence over environment variables, so the relay can be changed without a restart. Password recovery (3.3) uses the same saved relay.

GET   /api/notifications/settings
PATCH /api/notifications/settings
POST  /api/notifications/test

10.2Webhook channels

Channels deliver the same events as email: expiry warnings, deployment failures, revocation notices and escalation. Slack, Teams, PagerDuty v2 and a generic JSON channel are supported.

Add a channel

1. Open Notifications → Channels → Add and choose the type.
2. Paste the webhook URL or routing key. Secrets are sealed and never returned.
3. Choose which events the channel receives.
4. Send a test and confirm the message in the target system.

GET    /api/notifications/channels
POST   /api/notifications/channels
POST   /api/notifications/channels/{id}/test
DELETE /api/notifications/channels/{id}

Transport rules

• HTTPS only; redirects are refused.
• Private and loopback targets are blocked unless explicitly enabled.
• Delivery retries are recorded in the same history as email, with the last error preserved.

10.3Escalation and delivery history

Escalation

When a renewal or deployment keeps failing, escalation ensures a human is told. Configure a failure threshold and a fallback recipient list; when the threshold is crossed, the owner and fallback recipients are notified.

• Automatic renewal opens at most one escalation per failed renewal streak.
• A deployment episode escalates once, not on every retry.
• Revocation notice from the CA is a one-time event per certificate (8.3).

Delivery history

GET  /api/notifications
POST /api/notifications/{id}/retry

Each entry records the channel, event, attempt count, outcome and last error. A failed delivery can be retried without re-running the triggering operation.

11.1Health and readiness

Readiness checks

• data-volume — the data directory is writable and present.
• database — SQLite opens and passes quick_check.
• schema — the database version is not newer than this binary. An older database is upgraded in place; a newer one reports 503 with the found and supported versions, because an old API must not read a row shape it does not know.
• identity — the account schema and password policy load. A failed migration reports 503 instead of leaving sign-in broken behind a healthy process.
• connectors — at least one CA connector is configured and reachable; a fresh install is degraded here, which is expected.

A fresh install therefore answers 200 degraded until a CA is connected. A failure in any check returns 503 — that is the signal to stop traffic, not to restart blindly.

Metrics

GET /metrics answers in Prometheus text format from the API process. The web container does not proxy it, so it is reachable from the container network and from whatever scrapes the API directly. Set SPIRYRA_METRICS_TOKEN to require Authorization: Bearer <token>; the production profile requires it, and without a token the endpoint answers anyone who can reach the API port.

11.2Backup and restore

Back up a running profile

./scripts/backup-profile.sh test
./scripts/backup-profile.sh production

The script uses SQLite's online backup API for every *.sqlite file, verifies each snapshot with PRAGMA integrity_check, copies the remaining data-volume files, and writes a checksummed manifest.json. Default destination:

backups/<profile>-<UTC timestamp>/

Restore

./scripts/restore-profile.sh test backups/test-20261029T010203Z --yes

1. Verify the manifest and every checksum.
2. Take a fresh pre-restore backup automatically.
3. Stop the API, replace the database files, restore ownership.
4. Start the API and wait for /healthz.

Rehearse the production path

./scripts/verify-production-deploy.sh --check
./scripts/verify-production-deploy.sh --backup-only
./scripts/verify-production-deploy.sh --restore-drill --yes

The drill takes a backup, verifies checksums, restores the same archive, checks health and compares certificate and account counts. It causes a short outage and keeps the pre-restore backup.

11.3Vault key rotation

Changing SPIRYRA_VAULT_KEY on its own makes every sealed value unreadable. Rotate in three steps instead.

1. Introduce the new key alongside the old. Set the new value in SPIRYRA_VAULT_KEY and put the old value in SPIRYRA_VAULT_KEY_PREVIOUS (comma-separate several), then redeploy. Reads and new writes keep working.
2. Re-wrap. As an administrator open Settings → General → Vault key rotation and confirm Re-wrap sealed values. One transaction decrypts and re-encrypts retained leaf keys, connector credentials, registered-server SSH keys, WinRM passwords, notification secrets, the SMTP password and the OIDC client secret. If any value cannot be opened, nothing changes and the response names the affected table.
3. Retire the old key. Remove SPIRYRA_VAULT_KEY_PREVIOUS, redeploy, and back up the new key separately.

11.4Background workers and leases

Renewal scheduling, revocation checks, TLS monitoring, deployment dispatch and orchestration all run inside the API process. Work is claimed through database leases so two replicas do not do the same job twice.

• Orchestration runs hold a lease while a replica drives them; a second replica cannot pick up the same run.
• Two API replicas were exercised and split background work into distinct leases.
• On startup a replica resumes queued and running runs, reattaches host steps to their existing agent jobs and fails in-flight control-plane steps closed.
• An offline agent leaves its deployment queued — there is no automatic replay, so a queued job is a visible state, not a silent retry loop.

11.5Audit log and events

Every security-relevant action is written to an append-only audit log with actor, action, severity, summary and structured detail. The console reads it as an event stream.

GET /api/events
GET /api/access/audit

Representative actions

What audit never stores

• Private keys, tokens, passwords or sealed values.
• ACME account keys and DNS API tokens.
• Full certificate bodies beyond what the record needs.

11.6Logging and diagnostics

Container logs

docker compose -p spiryra-production logs -f api
docker compose -p spiryra-production logs -f web

On startup the API prints the readiness summary and each check's detail. Connector and deployment errors appear with the CA or host message included.

What to collect before asking for help

1. The output of /readyz and /api/meta.
2. The failing request's status code and the JSON body — errors carry a message, and authorization failures carry a code.
3. The relevant container log lines, with secrets redacted.
4. For deployment failures: the deployment detail, including reload result and presented fingerprint.
5. For connector failures: the connector Test output, not just the issue error.

12.1Security model

Trust boundaries

• The Docker host is trusted: it holds the env file and the vault key.
• The CA is authoritative for policy and validity; Spiryra validates what comes back but does not overrule it.
• The target host is semi-trusted: it enforces its own allowlists and reports what it did.
• The browser is untrusted: every write is authorized server-side, and tokens never reach JavaScript beyond the CSRF value.

12.2Hardening checklist

1. Use the production profile with an exact HTTPS public origin and secure cookies.
2. Keep port 8080 on loopback; only the TLS proxy is reachable.
3. Lock the env file to mode 0600 and store the vault key in your secret manager separately from backups.
4. Replace the bootstrap administrator with named accounts; keep one local administrator for IdP outages.
5. Use HTTPS for WinRM (5986) and keep SPIRYRA_AGENTLESS_WINRM_ALLOW_HTTP unset.
6. Set agent allowlists explicitly and leave them empty where the capability is not needed.
7. Scope tokens narrowly: service accounts get read scopes unless they must write, plus an expiry.
8. Turn on notifications and escalation so expiry and failures reach a person.
9. Rehearse restore and vault rotation before you need them.
10. Run the release gate (14.3) before each production change window.

12.3Known limits

13.1API authentication and CSRF

Credential types

Sign in

POST /api/auth/login
{ "username": "admin", "password": "…" }

200 OK
Set-Cookie: spiryra_session=…; HttpOnly; SameSite=Strict
Set-Cookie: spiryra_csrf=…; SameSite=Strict
{ "user": { "username": "admin", "role": "admin" }, "csrfToken": "…" }

Write requests from a browser

POST /api/certificates/issue
Cookie: spiryra_session=…
X-CSRF-Token: <value from the csrfToken field or the spiryra_csrf cookie>

• A missing or wrong CSRF token returns 403.
• The request Origin must match the request Host; a mismatch returns 403.
• Bearer credentials — migration tokens, agents and service accounts — are not subject to the browser CSRF rule.

POST /api/auth/logout
GET  /api/auth/me
GET  /api/auth/providers

13.2Endpoint reference

Representative routes grouped by capability. Every console screen uses these; the authorization gate classifies each route-method pair before a handler runs.

Certificates

GET    /api/certificates
GET    /api/certificates/{id}
POST   /api/certificates/issue
POST   /api/certificates/csr/sign
POST   /api/certificates/import
POST   /api/certificates/{id}/renew
POST   /api/certificates/{id}/revoke
GET    /api/certificates/{id}/download[?part=chain|key]
GET    /api/certificates/{id}/installations
GET    /api/certificates/{id}/automation

Connectors and CA policy

GET    /api/connectors
GET    /api/connectors/specs
POST   /api/connectors
PATCH  /api/connectors/{id}
POST   /api/connectors/{id}/test
GET    /api/connectors/{id}/templates
POST   /api/connectors/{id}/templates/sync
POST   /api/connectors/est/inspect      POST /api/connectors/est/enroll
POST   /api/connectors/scep/inspect     POST /api/connectors/scep/pki-operation
GET    /api/ca/templates

Deployment and fleet

GET    /api/installations               POST /api/installations
PATCH  /api/installations/{id}
POST   /api/installations/{id}/deploy
POST   /api/installations/{id}/rollback
GET    /api/agents                      POST /api/agents
POST   /api/agents/bulk                 GET  /api/agents/fleet
DELETE /api/agents/{id}
GET    /api/agent/jobs                  POST /api/agent/jobs/{id}/result
POST   /api/agent-bootstrap/enroll
POST   /api/agent/token/prepare         POST /api/agent/token/commit
GET    /api/agent-upgrades/rollouts
POST   /api/agent-upgrades/rollouts/{id}/dispatch
POST   /api/agent-upgrades/rollouts/{id}/approve
POST   /api/agent-upgrades/rollouts/{id}/cancel
GET    /api/agent-upgrades/rollouts/{id}/outcomes

Orchestration

GET    /api/orchestration/meta
GET    /api/orchestration/approvals
GET    /api/workflows                  POST /api/workflows
GET    /api/runs                       POST /api/runs
GET    /api/runs/{id}
POST   /api/runs/{id}/approval

Discovery, monitoring and alerts

GET    /api/findings                   PATCH /api/findings/{id}/state
POST   /api/findings/{id}/import
GET    /api/monitor/tls                POST /api/monitor/tls
GET    /api/monitor/tls/{id}/history   POST /api/monitor/scan
GET    /api/monitor/tls/alerts         POST /api/monitor/tls/alerts/{id}/acknowledge
GET    /api/alerts
POST   /api/alerts/{id}/ack            POST /api/alerts/{id}/resolve

Identity and access

GET    /api/users                      POST /api/users
PATCH  /api/users/{id}                 DELETE /api/users/{id}
GET    /api/access/summary             GET  /api/access/catalog
GET    /api/access/directory           GET  /api/access/preview
POST   /api/access/teams               POST /api/access/owners
POST   /api/access/roles               POST /api/access/group-roles
GET    /api/access/ca-policy           POST /api/access/ca-policy
GET    /api/access/audit
GET    /api/service-accounts           POST /api/service-accounts
PATCH  /api/service-accounts/{id}
POST   /api/service-accounts/{id}/tokens
DELETE /api/service-accounts/{id}/tokens/{token_id}

Operations and settings

GET    /api/meta                       GET  /api/dashboard
GET    /api/settings                   PATCH /api/settings
GET    /api/selftest
GET    /api/events
GET    /api/notifications              GET  /api/notifications/settings
PATCH  /api/notifications/settings     POST /api/notifications/test
GET    /api/notifications/channels     POST /api/notifications/channels
POST   /api/notifications/channels/{id}/test
POST   /api/notifications/{id}/retry
GET    /api/renewals                   POST /api/renewals/run
POST   /api/renewals/{certId}/retry
GET    /api/orders                     POST /api/orders/{id}/continue
GET    /api/enterprise/deployment/backups
POST   /api/enterprise/deployment/backups
GET    /api/enterprise/deployment/recovery

13.3Errors and status codes

Errors are JSON. Most carry a message; authorization failures also carry a code.

{ "code": "RBAC_DENIED", "message": "The role or owner team does not grant access to this operation" }
{ "message": "Unknown scope: certificates.superuser" }

14.1What is verified

Everything below was executed against this source tree or a recorded lab environment. Anything not listed here is covered in 14.2 — treat it as unproven.

14.2What still needs your environment

14.3Release gate

# staging gate: tests, builds, source manifest, optional signature
bash scripts/release-gate.sh

# production gate: also requires a separately signed independent review
bash scripts/release-gate.sh --production

python3 scripts/verify-release.py
npm run typecheck
npm run verify:settings-route

What the stages check

verify:settings-route is a Playwright check for the canonical Identity Providers route and the legacy redirect. It needs a running test profile and either local administrator sign-in or the deployment migration admin token.

15.1Installation and sign-in problems

15.2Connector problems

15.3Deployment problems

15.4Orchestration problems

15.5Diagnostic commands

# Stack state and logs
./scripts/deploy-profile.sh production status
docker compose -p spiryra-production ps
docker compose -p spiryra-production logs --tail=200 api

# Liveness and readiness
curl -fsS https://spiryra.example.com/healthz
curl -sS -i https://spiryra.example.com/readyz
curl -sS https://spiryra.example.com/api/meta | head -c 400

# Backups
./scripts/backup-profile.sh production
ls -1 backups/ | tail -3

# Recovery rehearsal (short outage)
./scripts/verify-production-deploy.sh --restore-drill --yes

# Authorization and parity audits
python3 scripts/audit-rust-authorization.py
python3 scripts/audit-api-parity.py

16Glossary

ACME — Automatic Certificate Management Environment (RFC 8555). Spiryra supports HTTP-01 and DNS-01, including wildcards, with optional External Account Binding.

Agent — the native Go executable installed on a managed server. It polls the control plane, writes certificate files, reloads approved services and reports the certificate a socket presents.

Agentless (clientless) — delivery over SSH or WinRM with no Spiryra software on the target.

Allowlist (agent) — host-side lists that decide what a deployment may write, run, reload or probe. The control plane cannot widen them.

Approval gate — a workflow step that stops a run until an administrator approves or denies it.

Batch — one workflow run across several targets, created atomically.

CA policy — the record of which templates and key/validity constraints a deployment may use.

Connector — the configured path to an external authority (EJBCA, Vault PKI, ACME, AD CS, EST, SCEP), with sealed credentials.

CSRF token — a per-session value required on browser-originated writes (X-CSRF-Token).

Deployment target (installation) — a certificate bound to a server and destination path, with optional service reload and TLS endpoint.

EAB — External Account Binding, an ACME mechanism binding an account to a provider-issued key identifier and HMAC key.

EST — Enrolment over Secure Transport (RFC 7030).

Fingerprint — the SHA-256 digest of a certificate (or file), used to prove what was written and what is served.

Grant — a per-resource permission binding an account to a certificate or connector with read or manage rights.

Installation roots — the directories an agent may write into (SPIRYRA_INSTALL_ROOTS).

OCSP / CRL — the two revocation status mechanisms the worker polls for active certificates.

PFX / PKCS#12 — the Windows certificate container the agent can import into the machine store.

Readiness — /readyz: whether the deployment can actually do its job, not merely whether the process is alive.

Recovery ledger — the record of batch actions that have no automatic inverse, kept for operator follow-up.

Retained key — a private key stored sealed in the vault, enabling key-reuse renewal and administrator-gated download. Never deployed.

Run — one workflow execution against one target, with per-step state and evidence.

SCEP — Simple Certificate Enrolment Protocol (RFC 8894). One common name per request, no revocation.

Scope (account) — all or assigned; combined with grants to decide which resources an account may act on.

Scope (service account) — an action from the permission catalogue granted to a machine token; matched exactly.

Sealed value — a secret encrypted with AES-256-GCM under SPIRYRA_VAULT_KEY.

Vault key — the wrapping key for every sealed value. Back it up separately from data backups.

Workflow — the ordered definition of steps, targets and conditions that a run executes.

17Document index

Every claim in this guide is backed by a repository document. Start with the first two rows for status and deployment.