docs(approval-hub): architecture, security, release pipeline

Add ARCHITECTURE.md and SECURITY.md targeting the future public repo
(kanywst/approval-hub), plus goreleaser config and release workflow so
v0.x.x tags produce multi-platform binaries and a Homebrew tap entry.

Author: kanywst

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}

.goreleaser.yaml

@@ -0,0 +1,58 @@
+version: 2
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - id: approval-hub
+    main: ./cmd/approval-hub
+    binary: approval-hub
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - darwin
+      - linux
+    goarch:
+      - amd64
+      - arm64
+    ldflags:
+      - -s -w
+      - -X main.version={{ .Version }}
+      - -X main.commit={{ .Commit }}
+      - -X main.date={{ .Date }}
+
+archives:
+  - id: default
+    formats: [tar.gz]
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- .Os }}_
+      {{- .Arch }}
+
+checksum:
+  name_template: "checksums.txt"
+
+snapshot:
+  version_template: "{{ incpatch .Version }}-next"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^chore:"
+      - "^test:"
+
+brews:
+  - name: approval-hub
+    repository:
+      owner: kanywst
+      name: homebrew-tap
+    homepage: https://github.com/kanywst/approval-hub
+    description: Aggregate Claude Code permission prompts into one TUI.
+    license: MIT
+    install: |
+      bin.install "approval-hub"
+    test: |
+      system "#{bin}/approval-hub", "--help"

ARCHITECTURE.md

@@ -0,0 +1,112 @@
+# Architecture
+
+approval-hub is a local HTTP broker daemon plus a Bubble Tea TUI client,
+both packaged in a single Go binary (`approval-hub`). A thin Claude Code
+plugin distributed separately wires each Claude Code session's `PreToolUse`
+hook to the broker via `type: "http"`.
+
+## Process layout
+
+```text
++------------------+        +------------------+
+| claude session A |        | claude session B |
+|  PreToolUse:http |        |  PreToolUse:http |
++--------+---------+        +--------+---------+
+         |                           |
+         | POST /decide              | POST /decide
+         | Bearer <token>            | Bearer <token>
+         +-------------+-------------+
+                       v
+            +---------------------+
+            |  broker daemon      |
+            |  127.0.0.1:17456    |
+            |                     |
+            |  - decision engine  |
+            |  - matcher store    |
+            |  - pending queue    |
+            |  - SSE /events      |
+            +---------+-----------+
+                      | SSE /events
+                      v
+            +---------------------+
+            |  TUI client         |
+            |  approval-hub attach|
+            +---------------------+
+```
+
+Three processes are loosely coupled over HTTP and SSE. If the TUI or the
+daemon dies, Claude sessions keep working: the hook receives a non-2xx /
+connection error and Claude Code falls back to its built-in interactive
+prompt. This is guaranteed by Claude Code's hook semantics.
+
+## Broker daemon
+
+Single goroutine-safe HTTP server on `127.0.0.1`.
+
+- `POST /decide` — PreToolUse entry. Generates a permission-rule-syntax
+  matcher (`Bash(npm test:*)`, `Edit(/path/to/file)`, ...) from the tool
+  input, looks it up in the matcher store. Cache hit returns immediately;
+  cache miss enqueues a pending request and waits up to
+  `ui_timeout_seconds` for a TUI decision, after which it returns `defer`.
+- `GET /events` — Server-Sent Events stream. Publishes
+  `pending_added` / `pending_resolved` / `pending_expired` / `rule_added`
+  / `rule_revoked`. Slow subscribers drop events when their buffer fills.
+- `GET /pending`, `POST /pending/{id}/resolve` — list and resolve.
+- `GET /rules`, `DELETE /rules/{id}` — inspect and tombstone matchers.
+- `POST /rotate-token` — generate a new bearer token and persist it.
+
+Bearer-token middleware in front of every route. Rate limiter uses a
+per-second token bucket sized by `rate_limit_per_second`.
+
+## TUI client
+
+Bubble Tea Model with an SSE consumer goroutine. Reconnects with
+exponential backoff up to 30 s. Decisions go back to the broker as
+`POST /pending/{id}/resolve` with `scope` of `once` (no learning),
+`persist` (matcher appended to the store), or `ttl` (matcher with an
+`expires_at`).
+
+Session IDs are SHA-1 hashed to one of 8 ANSI colors so requests from
+the same session group visually.
+
+## Matcher store
+
+Append-only JSONL log at `${data_dir}/learned-rules.jsonl`. Each line is
+either a `rule_added` record (with optional `expires_at`) or a
+`rule_revoked` tombstone referencing a previous rule's ID. The broker
+reconstructs an in-memory map on startup.
+
+Matcher strings follow Claude Code's `if` field syntax so the rule set
+can be exported to `settings.json`'s `permissions.allow` list when the
+broker is uninstalled.
+
+## Failure modes
+
+- **broker not running** — hook receives connection refused → Claude
+  Code falls back to manual prompt
+- **broker crashes mid-pending** — hook hits its own `timeout` →
+  Claude Code falls back
+- **TUI client crashes** — broker keeps queueing pending; next attach
+  replays via `GET /pending` and SSE
+- **pending queue full** — broker returns 503; Claude Code falls back
+- **disk full (store)** — `AddRule` errors; resolve still returns the
+  decision in-memory
+
+## Configuration
+
+`config.json` in the OS-standard data directory
+(`~/Library/Application Support/approval-hub` on macOS,
+`~/.config/approval-hub` on Linux, or `$APPROVAL_HUB_DATA`).
+
+```json
+{
+  "port": 17456,
+  "token": "ahub_<64hex>",
+  "ui_timeout_seconds": 60,
+  "max_pending_requests": 100,
+  "rate_limit_per_second": 50
+}
+```
+
+File permissions are `0600`. The token is embedded into the Claude Code
+plugin's `hooks/hooks.json` by the `install` skill.

SECURITY.md

@@ -0,0 +1,43 @@
+# Security
+
+## Threat model
+
+approval-hub runs as the same OS user as the Claude Code session it
+brokers for, on the local machine only.
+
+### In scope
+
+- An attacker on the same network attempting to send `/decide` requests
+  to the broker → mitigated by binding only to `127.0.0.1`.
+- A passive observer on the local network → mitigated by `127.0.0.1`
+  only; no TLS is needed.
+- A program owned by a different OS user reading the token or sending
+  requests → mitigated by `0600` permissions on `config.json` and
+  `hooks/hooks.json`.
+
+### Out of scope
+
+- Other processes running as the same OS user. They can read
+  `config.json` and impersonate the broker or the TUI. Defense at this
+  layer is the OS user account itself.
+- Root-level malware. If the system is rooted, all bets are off.
+- Bugs in Claude Code itself.
+
+## Mitigations
+
+- Bind only to `127.0.0.1`; never to `0.0.0.0` or a Unix socket exposed
+  to other users.
+- Bearer token (`crypto/rand` 32 bytes, hex-encoded with `ahub_` prefix).
+- `0600` on `config.json`, `hooks/hooks.json`, `learned-rules.jsonl`,
+  and `approval-hub.pid`.
+- Constant-time token comparison (`crypto/subtle.ConstantTimeCompare`).
+- Token rotation via `approval-hub rotate` (also rewrites the plugin's
+  `hooks.json`).
+- Rate limiter (`rate_limit_per_second`) and max-pending bound
+  (`max_pending_requests`) to slow brute-force or DoS attempts even
+  from the same user.
+
+## Reporting vulnerabilities
+
+Please open a GitHub issue tagged `security` or email the maintainer
+listed in the README. Do not disclose publicly until a fix is released.