Add macOS support via platform abstraction layer (#6)

* feat: add macOS terminal support via platform abstraction layer

Introduce a platform abstraction layer (bwssh.platform) that encapsulates
all OS-specific behavior behind common interfaces, enabling macOS support
with zero breaking changes to existing Linux functionality.

Changes across all 5 platform areas:
- Process credentials: LOCAL_PEERCRED/LOCAL_PEERPID on macOS (vs SO_PEERCRED)
- Process metadata: libproc/sysctl via ctypes on macOS (vs /proc filesystem)
- Authorization: socket-permission-based auth on macOS (vs D-Bus polkit)
- Service management: launchd user agents on macOS (vs systemd units)
- Sleep/wake events: NSWorkspace notifications on macOS (vs logind D-Bus)

Also adds:
- Conditional dbus-fast dependency (Linux-only via sys_platform marker)
- Optional pyobjc-framework-Cocoa extra for macOS sleep watcher
- launchd plist template and --launchd install flag
- Platform-aware runtime directory resolution
- Comprehensive platform test suite (14 pass, 5 macOS-only skip on Linux)

All 487 existing tests continue to pass unchanged.

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

* docs: add macOS terminal support implementation plan

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

* fix: resolve CI failures for macOS platform port

- Remove plan.md from repository
- Fix ruff formatting on _darwin.py and _linux.py
- Add sys_platform marker to macos-sleep extra so pyobjc is
  only required on macOS (fixes --all-extras on Linux)

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

* fix: resolve mypy errors in _darwin.py

- Cast struct.unpack result to int to fix no-any-return
- Remove unused type: ignore comments on AppKit import and SleepObserver

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

* fix: remove unused I001 noqa directive in _darwin.py

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

* docs: add macOS installation and setup instructions

- Update introduction to cover both Linux and macOS
- Add macOS setup section to installation guide (launchd, SSH_AUTH_SOCK,
  sleep-lock extra, platform notes)
- Update CLI commands reference with --launchd flag
- Add macOS examples for SSH_AUTH_SOCK and launchd
- Add macOS authorization notes to security guide

https://claude.ai/code/session_0163PhXY1cy3hnDYDPiTf3Fz

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Reidond

docs/content/1.getting-started/1.introduction.md

@@ -3,21 +3,26 @@ title: "Introduction"
 description: "What bwssh does and when to use it."
 ---
 
-bwssh is a Linux-first SSH agent that signs using keys stored in Bitwarden.
+bwssh is an SSH agent that signs using keys stored in Bitwarden.
 It exposes a Unix-domain socket compatible with OpenSSH tools such as `ssh`
-and `git`, while gating signing requests through polkit authorization.
+and `git`, while gating signing requests through polkit authorization (Linux)
+or socket permissions (macOS).
 
 ## Use bwssh when
 
 - You store SSH keys in Bitwarden and want agent-style signing.
-- You want per-request or per-connection approval prompts.
-- You want a user-level daemon managed by systemd.
+- You want per-request or per-connection approval prompts (Linux with polkit).
+- You want a user-level daemon managed by systemd (Linux) or launchd (macOS).
 
 ## Requirements
 
-- Linux with systemd user services.
-- Python 3.12+.
-- Bitwarden CLI (`bw`) installed and logged in.
+- **Linux**: systemd user services, Python 3.12+, Bitwarden CLI (`bw`).
+- **macOS**: Python 3.12+, Bitwarden CLI (`bw`).
+
+### Optional dependencies
+
+- **Linux polkit**: `dbus-fast` (installed automatically) for per-request authorization prompts.
+- **macOS sleep-lock**: `pyobjc-framework-Cocoa` (install with `pip install bwssh[macos-sleep]`) to auto-lock the agent when your Mac sleeps.
 
 ::note
 This documentation includes AI integration with an MCP server and automatic

docs/content/1.getting-started/2.installation.md

@@ -15,29 +15,95 @@ uv sync
 uv run bwssh --version
 ```
 
-## Install systemd assets
+## Prepare Bitwarden
+
+Make sure the Bitwarden CLI is available:
 
 ```bash
-uv run bwssh install --user-systemd
+bw --version
 ```
 
-## Optional: install polkit policy
+Log in and unlock as needed:
 
 ```bash
-uv run bwssh install --polkit | sudo tee /etc/polkit-1/actions/io.github.reidond.bwssh.policy
+bw login
+bw unlock --raw
 ```
 
-## Prepare Bitwarden
+## Linux setup
 
-Make sure the Bitwarden CLI is available:
+### Install systemd units
 
 ```bash
-bw --version
+bwssh install --user-systemd
+systemctl --user daemon-reload
+systemctl --user enable --now bwssh-agent.socket
 ```
 
-Log in and unlock as needed:
+### Optional: install polkit policy
 
 ```bash
-bw login
-bw unlock --raw
+bwssh install --polkit | sudo tee /usr/share/polkit-1/actions/io.github.reidond.bwssh.policy > /dev/null
+```
+
+### Point SSH at the agent socket
+
+```bash
+export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/bwssh/agent.sock"
+```
+
+Add the line above to your `~/.bashrc` or `~/.zshrc` to make it permanent.
+
+## macOS setup
+
+### Install the launchd agent
+
+```bash
+bwssh install --launchd
 ```
+
+This writes a plist to `~/Library/LaunchAgents/io.github.reidond.bwssh-agent.plist`
+and prints the `launchctl load` command to start it.
+
+### Load the agent
+
+```bash
+launchctl load ~/Library/LaunchAgents/io.github.reidond.bwssh-agent.plist
+```
+
+The agent will start automatically on login from now on.
+
+### Point SSH at the agent socket
+
+```bash
+export SSH_AUTH_SOCK="${TMPDIR}bwssh/agent.sock"
+```
+
+Add the line above to your `~/.zshrc` (or `~/.bashrc`) to make it permanent.
+
+### Optional: enable sleep-lock
+
+Install the `macos-sleep` extra so the agent locks automatically when your Mac
+goes to sleep:
+
+```bash
+uv pip install 'bwssh[macos-sleep]'
+```
+
+### Unlock and test
+
+```bash
+bwssh unlock
+ssh -T git@github.com
+```
+
+## macOS notes
+
+- **No polkit**: macOS does not have D-Bus or polkit. Authorization relies on
+  Unix socket permissions — only processes running as your user can connect to
+  the agent socket (mode `0600`). The `require_polkit` config option is ignored
+  on macOS with a warning logged.
+- **No tray icon**: The system tray (`bwssh tray`) requires AppIndicator3 and
+  is Linux-only for now.
+- **Logs**: Daemon stdout/stderr go to `/tmp/bwssh-agent.stdout.log` and
+  `/tmp/bwssh-agent.stderr.log` by default (configured in the plist).

docs/content/2.cli/2.commands.md

@@ -21,10 +21,16 @@ bwssh start
 bwssh stop
 ```
 
-## Install systemd or polkit assets
+## Install service integration
 
 ```bash
+# Linux: install systemd user units
 bwssh install --user-systemd
+
+# macOS: install launchd user agent
+bwssh install --launchd
+
+# Linux: print polkit policy to stdout
 bwssh install --polkit
 ```
 

docs/content/2.cli/3.examples.md

@@ -13,18 +13,30 @@ bwssh unlock
 ## Use with SSH
 
 ```bash
+# Linux
 export SSH_AUTH_SOCK=${XDG_RUNTIME_DIR}/bwssh/agent.sock
+
+# macOS
+export SSH_AUTH_SOCK=${TMPDIR}bwssh/agent.sock
+
 ssh -T git@github.com
 ```
 
-## Install and enable systemd socket
+## Linux: install and enable systemd socket
 
 ```bash
 bwssh install --user-systemd
 systemctl --user daemon-reload
 systemctl --user enable --now bwssh-agent.socket
 ```
 
+## macOS: install and load launchd agent
+
+```bash
+bwssh install --launchd
+launchctl load ~/Library/LaunchAgents/io.github.reidond.bwssh-agent.plist
+```
+
 ## Inspect loaded keys
 
 ```bash

docs/content/3.guide/1.configuration.md

@@ -3,7 +3,7 @@ title: "Configuration"
 description: "Configure sockets, Bitwarden, auth, and SSH behavior."
 ---
 
-Config file location:
+Config file location (same on Linux and macOS):
 
 ```
 ${XDG_CONFIG_HOME:-~/.config}/bwssh/config.toml

docs/content/3.guide/2.security.md

@@ -5,12 +5,21 @@ description: "Authorization, polkit, and forwarding policy."
 
 ## Authorization Overview
 
-bwssh supports two authorization modes:
+### Linux
+
+bwssh supports two authorization modes on Linux:
 
 1. **Disabled (default)**: All signing requests from local processes are allowed without prompts. This is suitable for personal workstations.
 
 2. **Polkit-enabled**: Each signing request triggers a desktop prompt asking you to approve. Useful for shared machines or extra security.
 
+### macOS
+
+On macOS, authorization relies on Unix socket permissions. The agent socket is
+created with mode `0600`, so only processes running as your user can connect.
+There is no polkit equivalent — the `require_polkit` config option is ignored
+on macOS (a warning is logged if set to `true`).
+
 ## Default Mode (No Prompts)
 
 By default, bwssh allows all signing requests from local processes. This means:

pyproject.toml

@@ -3,18 +3,19 @@
 [project]
 name = "bwssh"
 version = "0.1.3"
-description = "Bitwarden-backed SSH agent for Linux"
+description = "Bitwarden-backed SSH agent"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
   "click>=8.3.1",
   "cryptography>=46.0.4",
-  "dbus-fast>=4.0.0",
+  "dbus-fast>=4.0.0; sys_platform == 'linux'",
   "textual>=7.5.0",
 ]
 
 [project.optional-dependencies]
 gui = ["PyGObject>=3.42.0,<3.50"]
+macos-sleep = ["pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'"]
 
 [project.scripts]
 bwssh = "bwssh.cli:main"
@@ -85,6 +86,14 @@ ignore_missing_imports = true
 module = "gi.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "Foundation.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "AppKit.*"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]