garcard Public

Notifications Fork 0 Star 0
v0.1.0-rc1
Branches trunk Tags v0.1.0-rc1
1 Branches 1 Tags
Go to file T
Code
mfwolffe Finalize ga gate documentation
57d75fe 82 Commits
config Add garcard config scaffold
docs Finalize ga gate documentation
examples Mark sprint 08 parity matrix as pass
garcard Infer retention options from action policy
garcard-ipc Expose authority health in status surface
garcardctl Add diagnostics command and remediation hints
specs Add garcard RPM spec
.gitignore seed sprint one scaffold
Cargo.lock add gartk prompt path timeout handling
Cargo.toml add gartk prompt path timeout handling
README.md Record sprint 08 validation baseline report
RELEASE_NOTES.md Finalize ga gate documentation
garcard.service seed sprint one scaffold

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.