# Require approval for managed unlock

Approval groups let an admin require a human decision before matching devices
can complete a Panocrypt-managed unlock.

Use them when a device should not unlock only because its source network and
device state are allowed. The source allowlist still runs first. Approval
groups add a manual gate for the devices whose tags match the group.

## What approval groups do

An approval group connects three things:

- **Required tags**: the device tags that decide which devices are covered.
- **Approvers**: the members or User Groups allowed to decide unlock requests.
- **Manual unlock requests**: the pending requests created when a covered
  device tries to unlock.

When a covered device attempts a managed unlock, Panocrypt pauses the recovery
exchange and creates a request in **Manual unlock**. An approver can approve,
deny, or defer the request.

Approval groups do not store disk keys, release recovery passphrases, or unlock
a running host. They control whether Panocrypt participates in a future
network-bound unlock request for the covered device.

## How matching works

A device is covered when its current tags match all required tags in an
approval group. Changes take effect immediately: changing a device tag or
editing a group can change which devices require manual unlock approval.

If multiple approval groups match the same device, their approvers are combined.
The requirements do not stack. Any one effective approver from any matching
group can decide the request.

Use narrow tags for sensitive systems, such as `env=production` or
`role=database`. A broad tag can put more devices behind manual approval than
intended.

## How requests reach approvers

When a covered device tries to unlock:

1. Panocrypt checks the normal device state and source allowlist.
2. If those checks pass and the device is covered by an approval group,
   Panocrypt creates a manual unlock request.
3. Panocrypt notifies the effective approvers for the matching group or groups.
4. The request appears in **Manual unlock** with the device, requesting IP,
   current status, and recorded decisions.

Panocrypt records the approvers for each request when the request is created.
Later User Group changes affect new requests; Panocrypt still checks that the
approver has access before accepting a decision.

## Approve, deny, or defer

Approvers have three actions:

- **Approve** permits the device to complete the next successful managed unlock
  attempt for that request.
- **Deny** blocks unlock requests from that requesting IP for the device for a
  limited time.
- **Defer** leaves the request pending so another approver can decide, or so
  the same approver can return and approve or deny while the request is still
  pending.

Use **Deny** when the IP, timing, or device context does not look right. Use
**Defer** when another approver has better context.

## Approval is single-use

An approval is single-use. It permits one successful recovery exchange for the
approved request. A later reboot, another source IP, or another unlock attempt
after the approval is spent needs a new request and a new decision.

After approval, Panocrypt briefly allows the retrying Clevis client to collect
the approved response. It is not a general auto-allow window.

## Operational limits

Approval groups are useful, but they are not a substitute for the rest of your
unlock policy.

- Keep source allowlists accurate. Manual approval does not replace source
  admission.
- Keep at least one reachable approver for every group.
- Use User Groups for reusable approver sets, but remember that User Groups are
  org-local and do not nest.
- Do not treat approval groups as a multi-person quorum. Any one effective
  approver from a matching group can resolve the request.
- Do not rely on manual approval as data recovery. Customers still need local
  LUKS recovery material in customer-controlled systems.
- Test on a non-critical device or test volume before putting production
  systems behind manual approval.

## Manage approval groups

Admins manage groups in **Maintain → Approval groups**.

Approvers review pending requests in **Maintain → Manual unlock**.

Device detail shows whether the device is covered by manual unlock and which
groups currently match it.