gardesk/garcard / 649608a

+## 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`

+

+

+## 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`

+

+## 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.

+# garcard 0.1.0-rc1

+

+## Highlights

+1. Polkit authentication agent backend with queue-aware auth state tracking.

+2. Built-in gartk prompt path with timeout/cancel behavior and ask-password fallback.

+3. Daemon health/reconnect loop with forced reconnect support (`SIGHUP` + maintenance pass).

+4. `garcardctl` operational commands: `ping`, `status`, `version`, `auth-summary`, `quit`.

+

+## Hardening Included In Sprint 04

+1. Same-UID enforcement for local IPC control clients.

+2. Reduced panic surface in prompt color setup paths.

+3. Best-effort scrubbing of helper prompt response buffers after use.

+

+## Validation Coverage

+1. Sprint 02 live callback and reconnect validation:

+   - `examples/sprint-02-validation-report-2026-02-18.md`

+2. Sprint 03 ecosystem + runtime probes:

+   - `examples/sprint-03-validation-report-2026-02-18.md`

+3. Sprint 04 reliability harness/checklist:

+   - `examples/validate-sprint-04.sh`

+   - `examples/sprint-04-validation.md`

+

+## Known Limitations

+1. Challenge prompting depends on host polkit policy; some actions may auto-authorize.

+2. Scope is logged-in user sessions (X11), not greeter/session-manager flows.

+3. Full panel controls in `gargears` remain limited to discovery/visibility for now.

+# Sprint 04 Validation Report (2026-02-20)

+

+## Scope

+1. Hardening regression checks after Sprint 04 code changes.

+2. Automated reliability checks for daemon restart resilience.

+

+## Commands

+1. `cargo test --workspace`

+2. `./examples/validate-sprint-04.sh` (executed with default `stub` backend)

+

+## Results

+1. Workspace tests passed (`39` garcard tests + workspace crates).

+2. `validate-sprint-04.sh` passed baseline and restart loop checks:

+   - daemon reachable via `ping`/`status`

+   - restart loop completed (`3` stop/start iterations)

+   - post-restart status and auth summary remained healthy (`idle`)

+3. Optional interactive `pkcheck` loop was intentionally skipped in this run:

+   - requires live polkit challenge flow and operator interaction.

+

+## Hardening Outcomes Confirmed

+1. IPC control path now validates same-UID peer credentials.

+2. Prompt UI runtime path no longer relies on panic/`expect` for color parsing.

+3. Helper response buffers are scrubbed after sending to helper socket.

+

+## Remaining Manual Sprint 04 Checks

+1. Daemon restart during an active prompt in polkit mode.

+2. Session shutdown/logout race while prompt is active.

+# Sprint 04 Validation Checklist

+

+Run these checks from an active X11 user session.

+

+## Automated Baseline

+1. `cargo test --workspace`

+2. `./examples/validate-sprint-04.sh`

+

+Expected:

+1. All tests pass.

+2. Daemon survives restart loop and remains reachable over IPC.

+

+## Interactive Challenge Loop

+1. `GARCARD_SPRINT04_BACKEND=polkit ./examples/validate-sprint-04.sh`

+2. Complete two `pkcheck` prompts (cancel/deny/success combinations).

+

+Expected:

+1. Prompt appears for challenge actions.

+2. `garcardctl auth-summary` updates and remains responsive across iterations.

+

+## Daemon Restart During Active Prompt

+1. Start daemon in one terminal:

+   - `RUST_LOG=garcard=debug GARCARD_AGENT_BACKEND=polkit cargo run -p garcard -- daemon`

+2. Trigger challenge in another terminal:

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

+3. While prompt is visible, restart daemon:

+   - `cargo run -q -p garcardctl -- quit`

+   - relaunch daemon command from step 1.

+4. Re-run the same `pkcheck` command.

+

+Expected:

+1. Active prompt interruption does not wedge daemon state.

+2. Relaunched daemon accepts new requests with clean `auth-summary`.

+

+## Session Shutdown/Logout Race

+1. Start daemon with debug logs.

+2. Trigger an auth prompt.

+3. Send `SIGTERM` to daemon PID while request is active.

+4. Relaunch daemon and run `garcardctl status`.

+

+Expected:

+1. Daemon exits cleanly without stale socket.

+2. Relaunch succeeds without manual socket cleanup.

+

+## Security Spot Checks

+1. Verify secret response handling does not log plaintext values.

+2. Confirm IPC control socket mode remains owner-only in production (`600`).

+3. Validate only same-UID peers can control daemon IPC.

+#!/usr/bin/env bash

+set -euo pipefail

+

+SOCKET_PATH="${GARCARD_SPRINT04_SOCKET:-${PWD}/target/garcard-sprint04.sock}"

+BACKEND="${GARCARD_SPRINT04_BACKEND:-stub}"

+RESTART_LOOPS="${GARCARD_SPRINT04_RESTART_LOOPS:-3}"

+PKCHECK_LOOPS="${GARCARD_SPRINT04_PKCHECK_LOOPS:-2}"

+ACTION_ID="${GARCARD_SPRINT04_ACTION_ID:-com.mesonbuild.install.run}"

+LOG_FILE="${GARCARD_SPRINT04_LOG:-${PWD}/target/garcard-sprint04.log}"

+

+if command -v garcard >/dev/null 2>&1; then

+  DAEMON_CMD=(garcard daemon)

+else

+  DAEMON_CMD=(cargo run -q -p garcard -- daemon)

+fi

+

+if command -v garcardctl >/dev/null 2>&1; then

+  CTL_CMD=(garcardctl)

+else

+  CTL_CMD=(cargo run -q -p garcardctl --)

+fi

+

+DAEMON_PID=0

+

+run_ctl() {

+  GARCARD_SOCKET="${SOCKET_PATH}" "${CTL_CMD[@]}" "$@"

+}

+

+wait_for_daemon() {

+  local tries=100

+  while (( tries > 0 )); do

+    if run_ctl ping >/dev/null 2>&1; then

+      return 0

+    fi

+    sleep 0.2

+    tries=$((tries - 1))

+  done

+  echo "daemon did not become ready in time"

+  return 1

+}

+

+start_daemon() {

+  GARCARD_SOCKET="${SOCKET_PATH}" \

+    GARCARD_AGENT_BACKEND="${BACKEND}" \

+    "${DAEMON_CMD[@]}" >>"${LOG_FILE}" 2>&1 &

+  DAEMON_PID=$!

+  wait_for_daemon

+}

+

+stop_daemon() {

+  if [[ "${DAEMON_PID}" -gt 0 ]] && kill -0 "${DAEMON_PID}" 2>/dev/null; then

+    run_ctl quit >/dev/null 2>&1 || true

+    wait "${DAEMON_PID}" 2>/dev/null || true

+  fi

+  DAEMON_PID=0

+}

+

+cleanup() {

+  stop_daemon

+  rm -f "${SOCKET_PATH}"

+}

+trap cleanup EXIT

+

+echo "Sprint 04 validation"

+echo "  socket: ${SOCKET_PATH}"

+echo "  backend: ${BACKEND}"

+echo "  log: ${LOG_FILE}"

+

+mkdir -p "$(dirname "${SOCKET_PATH}")"

+mkdir -p "$(dirname "${LOG_FILE}")"

+rm -f "${SOCKET_PATH}" "${LOG_FILE}"

+start_daemon

+

+echo "[1/4] Baseline daemon health"

+run_ctl ping

+run_ctl status

+run_ctl auth-summary

+

+echo "[2/4] Restart resilience loop (${RESTART_LOOPS} iterations)"

+for i in $(seq 1 "${RESTART_LOOPS}"); do

+  echo "  iteration ${i}: stop/start daemon"

+  run_ctl quit >/dev/null

+  wait "${DAEMON_PID}" 2>/dev/null || true

+  DAEMON_PID=0

+  start_daemon

+  run_ctl ping >/dev/null

+done

+

+echo "[3/4] Post-restart health"

+run_ctl status

+run_ctl auth-summary

+

+echo "[4/4] Optional interactive auth loop"

+if [[ "${BACKEND}" == "polkit" ]] && command -v pkcheck >/dev/null 2>&1; then

+  echo "  running ${PKCHECK_LOOPS} pkcheck attempts for action ${ACTION_ID}"

+  for i in $(seq 1 "${PKCHECK_LOOPS}"); do

+    set +e

+    pkcheck --allow-user-interaction --process "$$" --action-id "${ACTION_ID}"

+    rc=$?

+    set -e

+    echo "  pkcheck[${i}] rc=${rc}"

+    run_ctl auth-summary || true

+  done

+else

+  echo "  skipped (requires BACKEND=polkit and pkcheck installed)"

+fi

+

+echo "Validation complete. Log output:"

+echo "  ${LOG_FILE}"