# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

SSH Certificate Authority and credential issuance for the ops fleet — signs short-lived
certificates for `adm`/`agt`/`atm` actors; provides the `cert_command` interface consumed
by ops-bridge and other tooling.

---

## Core Idea

Implements `wiki/AccessManagementDirective.md` §§1–5. Owns the CA key, actor identity
inventory, signing logic, and scorecard. Two backends: `local` (ssh-keygen, for labs /
non-Vault use) and `vault` (HashiCorp Vault SSH engine, for production). Both expose the
same CLI surface and the same `cert_command` interface — callers never need to know which
backend is in use.

---

## In Scope

- Local CA backend (`ssh-keygen -s`) — fully functional without Vault
- Vault SSH engine backend — production-grade signing via Vault API
- Actor identity registry (`inventory.yaml`) — maps actors to principals and TTL policy
- `cert_command` interface: `warden sign <actor> --pubkey <path>` → cert text on stdout
- TTL policy enforcement per `ActorType` (`adm` 48 h, `agt` 24 h, `atm` 8 h)
- Certificate status inspection (`warden status`)
- Stale-cert cleanup and scorecard checks (cert-side; see §5 of directive)
- `warden issue` — generate keypair + sign in one step (for `agt`/`atm` actors)
- `ops-ssh-wrapper` script — wraps SSH commands with automatic cert acquisition

---

## Out of Scope

- Tunnel lifecycle management → `ops-bridge`
- Host-side principal deployment (`/etc/ssh/auth_principals/`) → `railiance-infra` Ansible
- SSH key generation for human admins (self-service: `ssh-keygen`)
- Vault cluster setup, HA, or PKI secrets engine
- Session recording, SIEM forwarding, audit log aggregation
- SSO / Teleport integration (trigger when §6.2 scale thresholds are hit)
- Host-side scorecard checks (password auth disabled, root login disabled) → `railiance-infra`

---

## Relevant When

- Issuing or refreshing a cert for any `adm`/`agt`/`atm` actor
- Checking cert validity or running the compliance scorecard
- `ops-bridge` needs a `cert_command` to be defined for a tunnel
- Adding a new actor to the principals inventory
- Bootstrapping the CA for a new environment

---

## Not Relevant When

- Managing tunnel lifecycle (→ `ops-bridge`)
- Deploying SSH principal config to hosts (→ `railiance-infra`)
- All access is via static keys with no TTL (ops-bridge static key mode handles this)
- Human admins manually managing their own certificates

---

## Current State

- Status: planned — WARDEN-WP-0001 not yet started
- Implementation: scaffolding only (models, config, CA, inventory, scorecard, CLI stubs)

---

## How It Fits

- Upstream: CA key (file or Vault); actor inventory in Git
- Downstream consumers: `ops-bridge` calls `warden sign` via `cert_command`; any other
  tool needing short-lived SSH certs can use the same interface
- Often used with: `ops-bridge` (primary consumer), `railiance-infra` (host-side principal sync)

---

## Terminology

- `ActorType`: `adm` (human operator), `agt` (LLM agent), `atm` (deterministic automation)
- `cert_command`: shell command that a caller (e.g. ops-bridge) runs to obtain a cert
- `CertSpec`: signing request (actor name, pubkey path, TTL, principals)
- `CertRecord`: result of signing (identity, valid_before, cert_path, signed_at)
- `principals`: SSH roles embedded in the cert, matched against `/etc/ssh/auth_principals/%u`
- `inventory.yaml`: authoritative registry of actor → principals + TTL policy
- `LocalCA`: file-based CA backend using `ssh-keygen -s`
- `VaultCA`: Vault SSH engine backend

---

## Related / Overlapping Repositories

- `ops-bridge` — primary consumer; calls `warden sign` via `cert_command` in tunnel config
- `railiance-infra` — owns host-side principal deployment and host-side scorecard checks
- `the-custodian/state-hub` — domain/workstream registry

---

## Provided Capabilities

```capability
type: security
title: SSH certificate issuance
description: Issues short-lived CA-signed SSH certificates for adm/agt/atm actors via a
  pluggable cert_command interface; supports local CA (ssh-keygen) and Vault SSH engine backends.
keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, vault]
```

---

## Getting Oriented

- Start with: `SCOPE.md` (this file), then `wiki/AccessManagementDirective.md`
- Config reference: `wiki/OpsWardenConfig.md`
- cert_command contract: `wiki/CertCommandInterface.md`
- Config files: `~/.config/warden/warden.yaml`, `~/.config/warden/inventory.yaml`
- State: `~/.local/state/warden/` (certs, generated keypairs)
- Entry point: `warden --help`
- Workplan: `workplans/WARDEN-WP-0001-initial-implementation.md`