# Remediation Plan

**Date**: 2026-03-16
**Scope**: Audit findings #25–#38 from engine design review

This document provides a concrete remediation plan for each open finding. Items
are grouped by priority and ordered for efficient implementation (dependencies
first).

---

## Critical

### #37 — `adminOnlyOperations` name collision blocks user `rotate-key`

**Problem**: The `adminOnlyOperations` map in `handleEngineRequest`
(`internal/server/routes.go:265`) is a flat `map[string]bool` keyed by
operation name. The transit engine's `rotate-key` is admin-only, but the user
engine's `rotate-key` is user-self. Since the map is checked before engine
dispatch, non-admin users are blocked from calling `rotate-key` on any engine
mount — including user engine mounts where it should be allowed.

**Fix**: Replace the flat map with an engine-type-qualified lookup. Two options:

**Option A — Qualify the map key** (minimal change):

Change the map type to include the engine type prefix:

```go
var adminOnlyOperations = map[string]bool{
    "ca:import-root":          true,
    "ca:create-issuer":        true,
    "ca:delete-issuer":        true,
    "ca:revoke-cert":          true,
    "ca:delete-cert":          true,
    "transit:create-key":      true,
    "transit:delete-key":      true,
    "transit:rotate-key":      true,
    "transit:update-key-config": true,
    "transit:trim-key":        true,
    "sshca:create-profile":    true,
    "sshca:update-profile":    true,
    "sshca:delete-profile":    true,
    "sshca:revoke-cert":       true,
    "sshca:delete-cert":       true,
    "user:provision":          true,
    "user:delete-user":        true,
}
```

In `handleEngineRequest`, look up `engineType + ":" + operation` instead of
just `operation`. The `engineType` is already known from the mount registry
(the generic endpoint resolves the mount to an engine type).

**Option B — Per-engine admin operations** (cleaner but more code):

Each engine implements an `AdminOperations() []string` method. The server
queries the resolved engine for its admin operations instead of using a global
map.

**Recommendation**: Option A. It requires a one-line change to the lookup and
a mechanical update to the map keys. The generic endpoint already resolves the
mount to get the engine type.

**Files to change**:
- `internal/server/routes.go` — update map and lookup in `handleEngineRequest`
- `engines/sshca.md` — update `adminOnlyOperations` section
- `engines/transit.md` — update `adminOnlyOperations` section
- `engines/user.md` — update `adminOnlyOperations` section

**Tests**: Add test case in `internal/server/server_test.go` — non-admin user
calling `rotate-key` via generic endpoint on a user engine mount should succeed
(policy permitting). Same call on a transit mount should return 403.

---

## High

### #28 — HMAC output not versioned

**Problem**: HMAC output is raw base64 with no key version indicator. After key
rotation and `min_decryption_version` advancement, old HMACs are unverifiable
because the engine doesn't know which key version produced them.

**Fix**: Use the same versioned prefix format as ciphertext and signatures:

```
metacrypt:v{version}:{base64(mac_bytes)}
```

Update the `hmac` operation to include `key_version` in the response. Update
internal HMAC verification to parse the version prefix and select the
corresponding key version (subject to `min_decryption_version` enforcement).

**Files to change**:
- `engines/transit.md` — update HMAC section, add HMAC output format, update
  Cryptographic Details section
- Implementation: `internal/engine/transit/sign.go` (when implemented)

### #30 — `max_key_versions` vs `min_decryption_version` unclear

**Problem**: The spec doesn't define when `max_key_versions` pruning happens or
whether it respects `min_decryption_version`. Auto-pruning on rotation could
destroy versions that still have unrewrapped ciphertext.

**Fix**: Define the behavior explicitly in `engines/transit.md`:

1. `max_key_versions` pruning happens during `rotate-key`, after the new
   version is created.
2. Pruning **only** deletes versions **strictly less than**
   `min_decryption_version`. If `max_key_versions` would require deleting a
   version at or above `min_decryption_version`, the version is **retained**
   and a warning is included in the response:
   `"warning": "max_key_versions exceeded; advance min_decryption_version to enable pruning"`.
3. This means `max_key_versions` is a soft limit — it is only enforceable
   after the operator completes the rotation cycle (rotate → rewrap → advance
   min → prune happens automatically on next rotate).

This resolves the original audit finding #16 as well.

**Files to change**:
- `engines/transit.md` — add `max_key_versions` behavior to Key Rotation
  section and `rotate-key` flow
- `AUDIT.md` — mark #16 as RESOLVED with reference to the new behavior

### #33 — Auto-provision creates keys for arbitrary usernames

**Problem**: The encrypt flow auto-provisions recipients without validating
that the username exists in MCIAS. Any authenticated user can create barrier
entries for non-existent users.

**Fix**: Before auto-provisioning, validate the recipient username against
MCIAS. The engine has access to the auth system via `req.CallerInfo` context.
Add an MCIAS user lookup:

1. Add a `ValidateUsername(username string) (bool, error)` method to the auth
   client interface. This calls the MCIAS user info endpoint to check if the
   username exists.
2. In the encrypt flow, before auto-provisioning a recipient, call
   `ValidateUsername`. If the user doesn't exist in MCIAS, return an error:
   `"recipient not found: {username}"`.
3. Document this validation in the encrypt flow and security considerations.

**Alternative** (simpler, weaker): Skip MCIAS validation but add a
rate limit on auto-provisioning (e.g., max 10 new provisions per encrypt
request, max 100 total auto-provisions per hour per caller). This prevents
storage inflation but doesn't prevent phantom users.

**Recommendation**: MCIAS validation. It's the correct security boundary —
only real MCIAS users should have keypairs.

**Files to change**:
- `engines/user.md` — update encrypt flow step 2, add MCIAS validation
- `internal/auth/` — add `ValidateUsername` to auth client (when implemented)

---

## Medium

### #25 — Missing `list-certs` REST route (SSH CA)

**Fix**: Add to the REST endpoints table:

```
| GET | `/v1/sshca/{mount}/certs` | List cert records |
```

Add to the route registration code block:

```go
r.Get("/v1/sshca/{mount}/certs", s.requireAuth(s.handleSSHCAListCerts))
```

**Files to change**: `engines/sshca.md`

### #26 — KRL section type description error

**Fix**: Change the description block from:

```
Section type: KRL_SECTION_CERT_SERIAL_LIST (0x21)
```

to:

```
Section type: KRL_SECTION_CERTIFICATES (0x01)
  CA key blob: ssh.MarshalAuthorizedKey(caSigner.PublicKey())
  Subsection type: KRL_SECTION_CERT_SERIAL_LIST (0x20)
```

This matches the pseudocode comments and the OpenSSH `PROTOCOL.krl` spec.

**Files to change**: `engines/sshca.md`

### #27 — Policy check after cert construction (SSH CA)

**Fix**: Reorder the sign-host flow steps:

1. Authenticate caller.
2. Parse the supplied SSH public key.
3. Parse TTL.
4. **Policy check**: for each hostname, check policy on
   `sshca/{mount}/id/{hostname}`, action `sign`.
5. Generate serial (only after policy passes).
6. Build `ssh.Certificate`.
7. Sign, store, return.

Same reordering for sign-user.

**Files to change**: `engines/sshca.md`

### #29 — `rewrap` policy action not specified

**Fix**: Add `rewrap` as an explicit action in the `operationAction` mapping.
`rewrap` maps to `decrypt` (since it requires internal access to plaintext).
Batch variants map to the same action.

Add to the authorization section in `engines/transit.md`:

> The `rewrap` and `batch-rewrap` operations require the `decrypt` action —
> rewrap internally decrypts with the old version and re-encrypts with the
> latest, so the caller must have decrypt permission. Alternatively, a
> dedicated `rewrap` action could be added for finer-grained control, but
> `decrypt` is the safer default (granting `rewrap` without `decrypt` would be
> odd since rewrap implies decrypt capability).

**Recommendation**: Map to `decrypt`. Simpler, and anyone who should rewrap
should also be able to decrypt.

**Files to change**: `engines/transit.md`

### #31 — Missing `get-public-key` REST route (Transit)

**Fix**: Add to the REST endpoints table:

```
| GET | `/v1/transit/{mount}/keys/{name}/public-key` | Get public key |
```

Add to the route registration code block:

```go
r.Get("/v1/transit/{mount}/keys/{name}/public-key", s.requireAuth(s.handleTransitGetPublicKey))
```

**Files to change**: `engines/transit.md`

### #34 — No recipient limit on encrypt (User)

**Fix**: Add a compile-time constant `maxRecipients = 100` to the user engine.
Reject requests exceeding this limit with `400 Bad Request` / `InvalidArgument`
before any ECDH computation.

Add to the encrypt flow in `engines/user.md` after step 1:

> Validate that `len(recipients) <= maxRecipients` (100). Reject with error if
> exceeded.

Add to the security considerations section.

**Files to change**: `engines/user.md`

---

## Low

### #32 — `exportable` flag with no export operation (Transit)

**Fix**: Add an `export-key` operation to the transit engine:

- Auth: User+Policy (action `read`).
- Only succeeds if the key's `exportable` flag is `true`.
- Returns raw key material (base64-encoded) for the current version only.
- Asymmetric keys: returns private key in PKCS8 PEM.
- Symmetric keys: returns raw key bytes, base64-encoded.
- Add to HandleRequest dispatch, gRPC service, REST endpoints.

Alternatively, if key export is never intended, remove the `exportable` flag
from `create-key` to avoid dead code. Given that transit is meant to keep keys
server-side, **removing the flag** may be the better choice. Document the
decision either way.

**Recommendation**: Remove `exportable`. Transit's entire value proposition is
that keys never leave the service. If export is needed for migration, a
dedicated admin-only `export-key` can be added later with appropriate audit
logging (#7).

**Files to change**: `engines/transit.md`

### #35 — No re-encryption support for user key rotation

**Fix**: Add a `re-encrypt` operation:

- Auth: User (self) — only the envelope recipient can re-encrypt.
- Input: old envelope.
- Flow: decrypt with current key, generate new DEK, re-encrypt, return new
  envelope.
- The old key must still be valid at the time of re-encryption. Document the
  workflow: re-encrypt all stored envelopes, then rotate-key.

This is a quality-of-life improvement, not a security fix. The current design
(decrypt + encrypt separately) works but requires the caller to handle
plaintext.

**Files to change**: `engines/user.md`

### #36 — `UserKeyConfig` type undefined

**Fix**: Add the type definition to the in-memory state section:

```go
type UserKeyConfig struct {
    Algorithm       string    `json:"algorithm"`        // key exchange algorithm used
    CreatedAt       time.Time `json:"created_at"`
    AutoProvisioned bool      `json:"auto_provisioned"` // created via auto-provision
}
```

**Files to change**: `engines/user.md`

### #38 — `ZeroizeKey` prerequisite not cross-referenced

**Fix**: Add to the Implementation Steps section in both `engines/transit.md`
and `engines/user.md`:

> **Prerequisite**: `engine.ZeroizeKey` must exist in
> `internal/engine/helpers.go` (created as part of the SSH CA engine
> implementation — see `engines/sshca.md` step 1).

**Files to change**: `engines/transit.md`, `engines/user.md`

---

## Implementation Order

The remediation items should be implemented in this order to respect
dependencies:

1. **#37** — `adminOnlyOperations` qualification (critical, blocks user engine
   `rotate-key`). This is a code change to `internal/server/routes.go` plus
   spec updates. Do first because it affects all engine implementations.

2. **#28, #29, #30, #31, #32** — Transit spec fixes (can be done as a single
   spec update pass).

3. **#25, #26, #27** — SSH CA spec fixes (single spec update pass).

4. **#33, #34, #35, #36** — User spec fixes (single spec update pass).

5. **#38** — Cross-reference update (trivial, do with transit and user spec
   fixes).

Items within the same group are independent and can be done in parallel.