dendritic/.github/instructions/step-ssh-host.instructions.md

description, name, applyTo

description	name	applyTo
Use when modifying modules/services/step-ca/ssh-host.nix. Covers Step SSH host certificate wiring, secret key contract, and host-side expectations required by consumers.	Step SSH Host Module Instructions	modules/services/step-ca/ssh-host.nix

Step SSH Host Module Instructions

Use this instruction when changing the shared NixOS module in modules/services/step-ca/ssh-host.nix.

Module Contract

• Keep this module reusable across hosts; do not hard-code host-local file paths beyond SSH system paths under /etc/ssh.
• Preserve the option interface unless the task explicitly changes it:
  • ssh-certs.hostname (required host identity used for cert principals)
  • ssh-certs.provisioner (default: "admin")
• Keep imports = [ inputs.self.modules.nixos.ssh ] so OpenSSH host certificate settings stay composed through the shared SSH module.

Secret Key Contract

• This module currently consumes config.sops.secrets."janus/admin_jwk" as the Step provisioner password file.
• Treat janus/admin_jwk as a public contract key name for current consumers. If you rename it, update all consumers and host secret files in the same change.
• Keep secret permissions strict (root ownership and 0400 mode).
• Do not assume a local sops file path in this module. The consuming host must define sops.defaultSopsFile.

Host Expectations

When this module is enabled by a host, the host is expected to provide:

• A working Step trust/bootstrap path (for example via janus-ca or equivalent trust material).
• sops.defaultSopsFile containing janus.admin_jwk (or equivalent if contract is intentionally changed everywhere).
• ssh-certs.hostname matching deployed host identity and DNS naming expectations.

SSH Certificate Paths And Principals

• Preserve the default host key path contract at /etc/ssh/ssh_host_ed25519_key unless task scope requires coordinated changes.
• Keep host certificate path aligned to ${sshKeyPath}-cert.pub.
• Keep principal issuance based on hostname and hostname.john-stream.com unless domain policy is intentionally migrated.
• If changing key/cert filenames or principal naming, update modules/services/ssh.nix integration and host rollout notes in the same change.

Renewal Behavior

• Maintain timer/service cadence unless explicitly requested:
  • timer OnUnitActiveSec = 4h
  • randomized delay enabled
• Keep explicit handling for step ssh needs-renewal return codes to avoid silent failures.
• If changing renewal semantics, document whether the service now only checks state or also performs certificate issuance.

Validation Checklist

After editing this module, validate at least one consuming host with:

1. nix eval .#nixosConfigurations.janus.config.system.build.toplevel.drvPath
2. nix build .#nixosConfigurations.janus.config.system.build.toplevel --no-link --dry-run