garcard Public

Watch 0 Fork 0 Star 0
markdown · 3353 bytes Raw Blame History

garcard

garcard is the in-progress Polkit authentication agent for the gar desktop suite.

Workspace

  1. garcard: daemon runtime
  2. garcard-ipc: shared protocol types
  3. garcardctl: control/debug CLI

Quick Start

  1. cargo run -p garcard -- daemon
  2. cargo run -p garcardctl -- status
  3. cargo run -p garcard -- prompt --mode secret --message "Validation prompt"

Lifecycle Commands

  1. cargo run -q -p garcardctl -- diagnose
  2. cargo run -q -p garcardctl -- temp-list
  3. cargo run -q -p garcardctl -- temp-revoke <authorization-id>
  4. cargo run -q -p garcardctl -- temp-revoke-all

User Service

  1. Install unit file:
    • install -Dm644 garcard.service ~/.config/systemd/user/garcard.service
  2. Enable and start:
    • systemctl --user daemon-reload
    • systemctl --user enable --now garcard
  3. Check health:
    • cargo run -q -p garcardctl -- status

Config

Default config path: ~/.config/garcard/config.toml

Environment overrides:

  1. GARCARD_SOCKET
  2. GARCARD_SOCKET_MODE
  3. GARCARD_CONFIG
  4. GARCARD_AGENT_BACKEND
  5. GARCARD_POLKIT_OBJECT_PATH
  6. GARCARD_LOCALE
  7. GARCARD_POLKIT_HELPER_SOCKET
  8. GARCARD_PROMPT_COMMAND
  9. GARCARD_PROMPT_TIMEOUT_SECS
  10. GARCARD_BACKEND_HEALTHCHECK_SECS

Default scaffold file for packaging/integration: config/garcard/config.toml

See examples/config.toml for a minimal local starter file.

GARCARD_PROMPT_COMMAND is optional. If unset, garcard runs the built-in gartk prompt path with a persistent in-process modal session and falls back to systemd-ask-password when the X11 prompt backend is unavailable.

Validation Docs

  1. examples/sprint-02-validation.md
  2. examples/sprint-03-validation-report-2026-02-18.md
  3. examples/sprint-04-validation.md
  4. examples/validate-sprint-02.sh
  5. examples/validate-sprint-03-integration.sh
  6. examples/validate-sprint-04.sh
  7. examples/validate-sprint-04-runtime.sh
  8. examples/sprint-07-validation.md
  9. examples/validate-sprint-07.sh
  10. examples/sprint-08-parity-matrix.md
  11. examples/validate-sprint-08-parity.sh
  12. examples/sprint-08-integration-certification.md
  13. examples/validate-sprint-08-integration.sh
  14. examples/sprint-08-validation-report-2026-02-26.md

Troubleshooting

  1. Authorization requires authentication but no agent is available
    • ensure daemon is running: cargo run -q -p garcardctl -- ping
    • inspect authority and subject health: cargo run -q -p garcardctl -- diagnose
    • restart daemon after polkit restart: cargo run -q -p garcardctl -- quit then relaunch
  2. failed to connect to garcard daemon ...
    • check socket path from garcardctl status
    • if using custom socket, export the same GARCARD_SOCKET for both daemon and ctl
  3. Prompt did not open in X11
    • run with debug logs: RUST_LOG=garcard=debug cargo run -p garcard -- daemon
    • verify fallback path by setting GARCARD_PROMPT_COMMAND explicitly

Runbooks

  1. docs/runbooks/migrate-from-external-agent.md
  2. docs/runbooks/incident-triage.md
  3. docs/runbooks/garcardctl-cookbook.md
  4. docs/runbooks/rollback-plan.md
  5. docs/release/ga-checklist.md

Known Limitations

  1. Policy results are host-specific; some actions may auto-authorize and not trigger prompts.
  2. Current implementation targets logged-in user sessions on X11.
View source
1 # garcard
2
3 `garcard` is the in-progress Polkit authentication agent for the gar desktop suite.
4
5 ## Workspace
6 1. `garcard`: daemon runtime
7 2. `garcard-ipc`: shared protocol types
8 3. `garcardctl`: control/debug CLI
9
10 ## Quick Start
11 1. `cargo run -p garcard -- daemon`
12 2. `cargo run -p garcardctl -- status`
13 3. `cargo run -p garcard -- prompt --mode secret --message "Validation prompt"`
14
15 ## Lifecycle Commands
16 1. `cargo run -q -p garcardctl -- diagnose`
17 2. `cargo run -q -p garcardctl -- temp-list`
18 3. `cargo run -q -p garcardctl -- temp-revoke <authorization-id>`
19 4. `cargo run -q -p garcardctl -- temp-revoke-all`
20
21 ## User Service
22 1. Install unit file:
23 - `install -Dm644 garcard.service ~/.config/systemd/user/garcard.service`
24 2. Enable and start:
25 - `systemctl --user daemon-reload`
26 - `systemctl --user enable --now garcard`
27 3. Check health:
28 - `cargo run -q -p garcardctl -- status`
29
30 ## Config
31 Default config path: `~/.config/garcard/config.toml`
32
33 Environment overrides:
34 1. `GARCARD_SOCKET`
35 2. `GARCARD_SOCKET_MODE`
36 3. `GARCARD_CONFIG`
37 4. `GARCARD_AGENT_BACKEND`
38 5. `GARCARD_POLKIT_OBJECT_PATH`
39 6. `GARCARD_LOCALE`
40 7. `GARCARD_POLKIT_HELPER_SOCKET`
41 8. `GARCARD_PROMPT_COMMAND`
42 9. `GARCARD_PROMPT_TIMEOUT_SECS`
43 10. `GARCARD_BACKEND_HEALTHCHECK_SECS`
44
45 Default scaffold file for packaging/integration: `config/garcard/config.toml`
46
47 See `examples/config.toml` for a minimal local starter file.
48
49 `GARCARD_PROMPT_COMMAND` is optional. If unset, `garcard` runs the built-in
50 gartk prompt path with a persistent in-process modal session and falls back to
51 `systemd-ask-password` when the X11 prompt backend is unavailable.
52
53 ## Validation Docs
54 1. `examples/sprint-02-validation.md`
55 2. `examples/sprint-03-validation-report-2026-02-18.md`
56 3. `examples/sprint-04-validation.md`
57 4. `examples/validate-sprint-02.sh`
58 5. `examples/validate-sprint-03-integration.sh`
59 6. `examples/validate-sprint-04.sh`
60 7. `examples/validate-sprint-04-runtime.sh`
61 8. `examples/sprint-07-validation.md`
62 9. `examples/validate-sprint-07.sh`
63 10. `examples/sprint-08-parity-matrix.md`
64 11. `examples/validate-sprint-08-parity.sh`
65 12. `examples/sprint-08-integration-certification.md`
66 13. `examples/validate-sprint-08-integration.sh`
67 14. `examples/sprint-08-validation-report-2026-02-26.md`
68
69 ## Troubleshooting
70 1. `Authorization requires authentication but no agent is available`
71 - ensure daemon is running: `cargo run -q -p garcardctl -- ping`
72 - inspect authority and subject health: `cargo run -q -p garcardctl -- diagnose`
73 - restart daemon after polkit restart: `cargo run -q -p garcardctl -- quit` then relaunch
74 2. `failed to connect to garcard daemon ...`
75 - check socket path from `garcardctl status`
76 - if using custom socket, export the same `GARCARD_SOCKET` for both daemon and ctl
77 3. Prompt did not open in X11
78 - run with debug logs: `RUST_LOG=garcard=debug cargo run -p garcard -- daemon`
79 - verify fallback path by setting `GARCARD_PROMPT_COMMAND` explicitly
80
81 ## Runbooks
82 1. `docs/runbooks/migrate-from-external-agent.md`
83 2. `docs/runbooks/incident-triage.md`
84 3. `docs/runbooks/garcardctl-cookbook.md`
85 4. `docs/runbooks/rollback-plan.md`
86 5. `docs/release/ga-checklist.md`
87
88 ## Known Limitations
89 1. Policy results are host-specific; some actions may auto-authorize and not trigger prompts.
90 2. Current implementation targets logged-in user sessions on X11.