gardesk/garcard / a8becdc

+## Runbooks

+1. `docs/runbooks/migrate-from-external-agent.md`

+2. `docs/runbooks/incident-triage.md`

+3. `docs/runbooks/garcardctl-cookbook.md`

+

+# Garcardctl Operator Cookbook

+

+## Reachability And Runtime

+1. Ping daemon:

+   - `garcardctl ping`

+2. Runtime status and health surface:

+   - `garcardctl status`

+3. Extended diagnostics and remediation hints:

+   - `garcardctl diagnose`

+4. Version/protocol handshake:

+   - `garcardctl version`

+

+## Auth Lifecycle

+1. Inspect current auth state:

+   - `garcardctl auth-summary`

+2. Trigger policy challenge manually:

+   - `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run`

+

+## Temporary Authorization Controls

+1. List temporary authorizations:

+   - `garcardctl temp-list`

+2. Revoke one authorization by id:

+   - `garcardctl temp-revoke <authorization-id>`

+3. Revoke all temporary authorizations:

+   - `garcardctl temp-revoke-all`

+

+## Service Control

+1. Request daemon shutdown:

+   - `garcardctl quit`

+2. Start daemon (workspace run):

+   - `cargo run -p garcard -- daemon`

+3. Restart user service deployment:

+   - `systemctl --user restart garcard.service`

+

+## Standard Troubleshooting Sequence

+1. `garcardctl ping`

+2. `garcardctl status`

+3. `garcardctl diagnose`

+4. `garcardctl auth-summary`

+5. `garcardctl temp-list`

+

+## Operational Notes

+1. IPC controls are same-UID restricted.

+2. `status` now includes authority and subject health fields for control-surface consumers.

+3. `diagnose` includes remediation hints for no-agent and denied-flow scenarios.

+# Incident Triage Playbook

+

+## 1) No Agent Available

+Symptom:

+1. `pkcheck` returns: `Authorization requires authentication but no agent is available.`

+

+Checklist:

+1. Verify daemon socket/control path:

+   - `garcardctl ping`

+   - `garcardctl status`

+2. Check diagnostics:

+   - `garcardctl diagnose`

+3. If daemon is down, start/restart:

+   - `systemctl --user restart garcard.service`

+4. If polkit was restarted, restart garcard after polkit recovery:

+   - `garcardctl quit`

+   - relaunch daemon/service

+

+Escalate if:

+1. `diagnose.authority_connected` remains `false` after daemon restart.

+

+## 2) Repeated Denied Authentication

+Symptom:

+1. Prompt loops with denied results despite retries.

+

+Checklist:

+1. Inspect last outcome and phase:

+   - `garcardctl auth-summary`

+2. Verify operator account authorization policy (wheel/admin membership and action policy rules).

+3. Trigger a controlled challenge and inspect logs:

+   - `RUST_LOG=garcard=debug garcard daemon`

+   - `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run`

+4. Confirm deny path vs transport failure in logs (`FAILURE` vs transport errors).

+

+Escalate if:

+1. Correct credentials consistently map to denied outcomes across multiple actions.

+

+## 3) Authority Disconnect / DBus Errors

+Symptom:

+1. `diagnose` reports authority connectivity errors.

+2. Temp-authorization commands fail with dbus/authority errors.

+

+Checklist:

+1. Check diagnostics:

+   - `garcardctl diagnose`

+2. Restart daemon:

+   - `garcardctl quit`

+   - relaunch daemon/service

+3. Re-check:

+   - `garcardctl status`

+   - `garcardctl temp-list`

+4. If still failing, restart polkit (system policy permitting) and restart daemon.

+

+Escalate if:

+1. Authority connectivity remains down after polkit + daemon restart.

+

+## Evidence To Capture For Any Incident

+1. `garcardctl status`

+2. `garcardctl auth-summary`

+3. `garcardctl diagnose`

+4. Relevant daemon logs with timestamps

+5. Exact `pkcheck` command and stderr/stdout

+# Migration Runbook: External Agent To Garcard

+

+## Scope

+Move from another desktop polkit agent (for example `polkit-kde-agent-1`, `lxqt-policykit-agent`, `mate-polkit`) to `garcard`.

+

+## Preconditions

+1. `garcard` and `garcardctl` are installed or runnable from this workspace.

+2. You have a user session with access to polkit prompts.

+3. Existing external polkit agent service is known.

+

+## Steps

+1. Stop and disable the existing agent for the user session.

+   - Example:

+     - `systemctl --user disable --now lxqt-policykit-agent.service`

+     - `systemctl --user disable --now polkit-kde-authentication-agent-1.service`

+2. Install and enable `garcard` user service.

+   - `install -Dm644 garcard.service ~/.config/systemd/user/garcard.service`

+   - `systemctl --user daemon-reload`

+   - `systemctl --user enable --now garcard.service`

+3. Verify control plane reachability.

+   - `garcardctl ping`

+   - `garcardctl status`

+   - `garcardctl diagnose`

+4. Trigger an auth challenge.

+   - `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run`

+5. Validate lifecycle controls.

+   - `garcardctl auth-summary`

+   - `garcardctl temp-list`

+   - `garcardctl temp-revoke-all`

+

+## Success Criteria

+1. Only garcard owns the active auth-agent role in session.

+2. Prompt appears and accepts valid credentials.

+3. `garcardctl` lifecycle commands respond without permission/socket errors.

+

+## Rollback

+1. Disable garcard user service:

+   - `systemctl --user disable --now garcard.service`

+2. Re-enable prior agent service:

+   - `systemctl --user enable --now <previous-agent>.service`

+3. Re-run `pkcheck --allow-user-interaction ...` to confirm prior behavior is restored.