From b655392893b465143bac0d0921d99ad98b5e1220 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 20 Sep 2026 22:05:01 +0200
Subject: [PATCH] fix: name SCARD_W_SECURITY_VIOLATION and point at the polkit
 rule

Seen on the first Arch field test: pcscd up, but polkit denied the
user, and the CLI only printed the raw 0x8010006A.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md                   | 18 +++++++++++++++---
 src/boltcard_writer/pcsc.py |  7 +++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index eff9be0..43241c9 100644
--- a/README.md
+++ b/README.md
@@ -171,9 +171,21 @@ changes travel encrypted).
 | `card already looks provisioned` | it has SDM on or non-zero key versions; wipe first (`--force` only if you know k0 is zero) |
 | `this is not an NTAG 424 DNA` | wrong tag; Bolt Cards need NTAG 424 DNA |
 
-If the user cannot access the reader (permission errors from pcscd), Arch's
-pcsclite uses polkit: the session must be a local active login, or add a rule
-for `org.debian.pcsc-lite.access_pcsc` / `access_card`.
+| `SCARD_W_SECURITY_VIOLATION` (0x8010006A) | polkit refused your user access to pcscd. Arch's pcsclite only auto-allows local *active* logins, so SSH sessions and some Wayland setups are denied. Grant it explicitly (below) |
+
+```sh
+sudo tee /etc/polkit-1/rules.d/50-pcscd.rules >/dev/null <<'EOF'
+polkit.addRule(function(action, subject) {
+  if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
+       action.id == "org.debian.pcsc-lite.access_card") &&
+      subject.isInGroup("wheel")) {
+    return polkit.Result.YES;
+  }
+});
+EOF
+```
+
+Takes effect immediately, no restart.
 
 ## Nix / NixOS
 
diff --git a/src/boltcard_writer/pcsc.py b/src/boltcard_writer/pcsc.py
index b724e4c..e4cf978 100644
--- a/src/boltcard_writer/pcsc.py
+++ b/src/boltcard_writer/pcsc.py
@@ -51,6 +51,7 @@ SCARD_E_COMM_DATA_LOST = 0x8010002F
 SCARD_W_UNRESPONSIVE_CARD = 0x80100066
 SCARD_W_UNPOWERED_CARD = 0x80100067
 SCARD_W_REMOVED_CARD = 0x80100069
+SCARD_W_SECURITY_VIOLATION = 0x8010006A
 
 ERROR_NAMES = {
     SCARD_E_INVALID_HANDLE: "SCARD_E_INVALID_HANDLE",
@@ -69,6 +70,7 @@ ERROR_NAMES = {
     SCARD_W_UNRESPONSIVE_CARD: "SCARD_W_UNRESPONSIVE_CARD",
     SCARD_W_UNPOWERED_CARD: "SCARD_W_UNPOWERED_CARD",
     SCARD_W_REMOVED_CARD: "SCARD_W_REMOVED_CARD",
+    SCARD_W_SECURITY_VIOLATION: "SCARD_W_SECURITY_VIOLATION",
 }
 
 HINTS = {
@@ -80,6 +82,11 @@ HINTS = {
     ),
     SCARD_E_SHARING_VIOLATION: ("another program holds the reader (pcsc_scan, another writer instance?)"),
     SCARD_E_READER_UNAVAILABLE: "the reader was unplugged",
+    SCARD_W_SECURITY_VIOLATION: (
+        "polkit denied this user access to pcscd (happens over SSH or when the desktop "
+        "session is not active in logind). Add a rule, see README > Troubleshooting, "
+        "or run once with sudo to confirm the reader works."
+    ),
 }
 
 # Card temporarily absent / not ready: keep polling.