garcard Public

Watch 0 Fork 0 Star 0
markdown · 2507 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"

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

Troubleshooting

  1. Authorization requires authentication but no agent is available
    • ensure daemon is running: cargo run -q -p garcardctl -- ping
    • 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

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 ## User Service
16 1. Install unit file:
17 - `install -Dm644 garcard.service ~/.config/systemd/user/garcard.service`
18 2. Enable and start:
19 - `systemctl --user daemon-reload`
20 - `systemctl --user enable --now garcard`
21 3. Check health:
22 - `cargo run -q -p garcardctl -- status`
23
24 ## Config
25 Default config path: `~/.config/garcard/config.toml`
26
27 Environment overrides:
28 1. `GARCARD_SOCKET`
29 2. `GARCARD_SOCKET_MODE`
30 3. `GARCARD_CONFIG`
31 4. `GARCARD_AGENT_BACKEND`
32 5. `GARCARD_POLKIT_OBJECT_PATH`
33 6. `GARCARD_LOCALE`
34 7. `GARCARD_POLKIT_HELPER_SOCKET`
35 8. `GARCARD_PROMPT_COMMAND`
36 9. `GARCARD_PROMPT_TIMEOUT_SECS`
37 10. `GARCARD_BACKEND_HEALTHCHECK_SECS`
38
39 Default scaffold file for packaging/integration: `config/garcard/config.toml`
40
41 See `examples/config.toml` for a minimal local starter file.
42
43 `GARCARD_PROMPT_COMMAND` is optional. If unset, `garcard` runs the built-in
44 gartk prompt path with a persistent in-process modal session and falls back to
45 `systemd-ask-password` when the X11 prompt backend is unavailable.
46
47 ## Validation Docs
48 1. `examples/sprint-02-validation.md`
49 2. `examples/sprint-03-validation-report-2026-02-18.md`
50 3. `examples/sprint-04-validation.md`
51 4. `examples/validate-sprint-02.sh`
52 5. `examples/validate-sprint-03-integration.sh`
53 6. `examples/validate-sprint-04.sh`
54 7. `examples/validate-sprint-04-runtime.sh`
55
56 ## Troubleshooting
57 1. `Authorization requires authentication but no agent is available`
58 - ensure daemon is running: `cargo run -q -p garcardctl -- ping`
59 - restart daemon after polkit restart: `cargo run -q -p garcardctl -- quit` then relaunch
60 2. `failed to connect to garcard daemon ...`
61 - check socket path from `garcardctl status`
62 - if using custom socket, export the same `GARCARD_SOCKET` for both daemon and ctl
63 3. Prompt did not open in X11
64 - run with debug logs: `RUST_LOG=garcard=debug cargo run -p garcard -- daemon`
65 - verify fallback path by setting `GARCARD_PROMPT_COMMAND` explicitly
66
67 ## Known Limitations
68 1. Policy results are host-specific; some actions may auto-authorize and not trigger prompts.
69 2. Current implementation targets logged-in user sessions on X11.