@chipallen2/snazi 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# snazi — message gate CLI (iMessage today)
+
+> "No messages for you."
+
+The **local gate**. An on-demand CLI that reads your messages through pluggable
+**channel adapters** so an AI agent can be told *who* messaged without being able
+to read *what* they said — unless the sender is on the server's approved list.
+iMessage is the first channel; the architecture is built for more (Gmail,
+Outlook, …). The CLI itself runs on macOS, Windows, and Linux (Node 18+); each
+channel works wherever its adapter does (iMessage is macOS-only).
+
+The base CLI runs **on demand** — no launchd job, no background process. The
+agent invokes it when needed. It stores nothing locally and the server stores no
+message content. Message text is read live from the channel's local store (for
+iMessage, `~/Library/Messages/chat.db`) and printed only when the gate opens.
+
+**Optional serve mode** (`snazi serve` or `snazi serve --install-daemon`) runs a
+long-lived HTTP gate for remote agents over a private tailnet. See **Serve mode**
+below.
+
+## How the gate works
+
+```
+agent wants to know what's new
+        │
+        ▼
+  snazi list-new            ──►  reveals WHO + status + label (approved/denied/unknown)
+        │                         (never the message text)
+        │  unknown sender? agent asks you: "approve +1555…?"
+        │  you approve in the dashboard, or by tapping a /decide link
+        ▼
+  snazi read <sender>       ──►  CLI asks server: is this sender approved?
+                                   ├─ approved → prints message text
+                                   └─ otherwise → "No messages for you."
+```
+
+The approval decision lives entirely on the server (Supabase-backed,
+per-account list). The CLI only *checks* it with a **read-only token** — it
+cannot approve a sender or reveal content for a non-approved one.
+
+## Install
+
+> **Not on npm yet.** Install from source (below). Once published,
+> `npm install -g snazi` becomes the one-liner.
+
+### From source (works today)
+
+macOS, Windows, or Linux (Node 18+):
+
+```bash
+git clone https://github.com/chipallen2/snazi.git
+cd snazi/packages/snazi
+./install.sh        # npm install + build, links `snazi` onto your PATH
+```
+
+On Windows (no bash), run this instead of `./install.sh`:
+
+```bash
+npm install && npm run build && npm link
+```
+
+Then configure and verify — no hand-edited JSON:
+
+```bash
+snazi init          # writes ~/.snazi/config.json (deployment URL + READ token)
+snazi doctor        # checks Node, config, connectivity, and channel access
+```
+
+`snazi init` asks for two things: your **deployment URL** (default
+`https://snazi.dev`) and your **account READ token** (sign up at `/signup`, then
+copy it from the `/account` page). There is **no admin key** — approvals happen
+in the dashboard or via a signed `/decide` link. For agents/CI, skip the prompts:
+
+```bash
+snazi init --api-url https://snazi.dev --token <READ_TOKEN> --yes
+```
+
+**macOS only — Full Disk Access.** To read iMessage, grant Full Disk Access to
+your terminal (or the `node` binary) in System Settings → Privacy & Security →
+Full Disk Access. `snazi doctor` flags it if missing.
+
+### Once published to npm
+
+```bash
+npm install -g snazi
+snazi init && snazi doctor
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `snazi init [--api-url <url>] [--token <tok>] [--channel <id>]` | Create or update `~/.snazi/config.json`. |
+| `snazi doctor` | Diagnose Node, config, connectivity, and channel access. |
+| `snazi list-new [--channel <id>] [--since <min>] [--fresh]` | Distinct inbound senders, counts, timestamps, approval status, and display label. **No text.** Default window 60 min. |
+| `snazi read <sender> [--channel <id>] [--since <min>] [--fresh]` | Message text for one sender — **only if approved**. Otherwise errors with `No messages for you.` |
+| `snazi check <sender> --channel <id> [--fresh]` | One sender's approval status and display label (`approved`/`denied`/`unknown`). |
+| `snazi channels list` | Configured channels plus adapter availability on this machine. |
+| `snazi channels add <channel>` | Add a channel (e.g. `snazi channels add imessage`). |
+| `snazi cache clear` | Drop cached approval statuses (force fresh checks after a revocation). |
+| `snazi status` | Config path, apiUrl, masked read token, channels, server reachability. |
+| `snazi serve [--bind <ip>] [--port <n>]` | Start the read-only HTTP gate (see **Serve mode** below). |
+| `snazi serve --install-daemon [--bind <ip>] [--port <n>]` | Install the launchd LaunchAgent for serve mode (macOS only). |
+| `snazi remote-status` | Probe a remote serve's `/health` (`remoteUrl`). |
+| `snazi remote-list-new [--channel <id>] [--since <min>]` | WHO messaged on the remote host + status + label. |
+| `snazi remote-check <sender> --channel <id>` | One sender's status and label, via remote serve. |
+| `snazi remote-read <sender> [--channel <id>] [--since <min>]` | Message text via remote serve — only if approved. |
+| `snazi remote-resolve [<name>] --channel <id>` | Resolve a name → sender address(es). Empty name = full address book. |
+| `snazi remote-label <sender> --name <name> --channel <id>` | Set a sender's display label (UPDATE-only; cannot open the gate). |
+
+All output is JSON. Approval status is cached on disk for a short TTL (default 5
+min; set `checkCacheTtlMs` in config or `SNAZI_CHECK_CACHE_TTL_MS`). Pass
+`--fresh` on read/check/list-new to bypass the cache, or run `snazi cache clear`
+right after you revoke someone.
+
+### Examples
+
+```bash
+snazi list-new --since 180
+# [
+#   { "sender": "+15551234567", "message_count": 3,
+#     "latest_at": "2026-06-23T22:10:04.000Z", "status": "unknown", "label": null }
+# ]
+
+snazi read "+15551234567"
+# { "error": "Sender not approved. No messages for you.", "status": "unknown" }
+
+# Approve in the dashboard, or mint a one-tap /decide link with your read token:
+curl -s -H "x-api-key: $READ_TOKEN" \
+  "https://snazi.dev/api/decide-link?channel=imessage&sender=%2B15551234567&label=Mom"
+# { "url": "https://snazi.dev/decide?owner=…&channel=imessage&sender=%2B15551234567&exp=…&sig=…", … }
+# Tap Allow on that link, then:
+
+snazi read "+15551234567"
+# { "sender": "+15551234567", "status": "approved", "since_minutes": 60,
+#   "messages": [ { "date": "...", "text": "hey are we still on for lunch?" } ] }
+```
+
+## Serve mode — least-privilege HTTP gate over a tailnet
+
+Sometimes the agent that wants to triage messages runs on a *different* machine
+than the one signed into iMessage. SSH would work, but SSH grants a **full shell** —
+far more than "let me read approved messages." `snazi serve` exposes **only** the
+gated, read-only operations over HTTP so a remote trusted agent gets least
+privilege.
+
+```
+  Agent host (remote client)                     Serve host (iMessage Mac)
+  ┌────────────────────┐   Tailscale tailnet   ┌──────────────────────┐
+  │ snazi remote-read   │ ───── HTTP ─────────► │ snazi serve           │
+  │   (bearer token)    │   100.x:8787          │  /health  (no auth)   │
+  └────────────────────┘                       │  /list-new  (bearer)  │
+                                                │  /check     (bearer)  │
+                                                │  /read      (bearer)  │
+                                                │  /resolve   (bearer)  │
+                                                │  POST /label (bearer) │
+                                                │     │                 │
+                                                │     ▼ same gate (api)  │
+                                                │  approved? → text      │
+                                                │  else     → "No        │
+                                                │             messages   │
+                                                │             for you."  │
+                                                └──────────────────────┘
+```
+
+### Endpoints (all JSON)
+
+| Method + path | Auth | Returns |
+| --- | --- | --- |
+| `GET /health` | none | `{ ok: true, version }` — connectivity probe only, no data. |
+| `GET /list-new?channel=imessage&since=<min>` | bearer | `{ channel, since_minutes, senders: [{ sender, message_count, latest_at, status, label }] }`. On check failure: `status` is `unknown` and an `error` field describes the failure. **Never message text.** |
+| `GET /check?sender=<addr>&channel=imessage` | bearer | `{ channel, sender, status, label }`. On check failure: HTTP 502 with `{ error }`. |
+| `GET /read?sender=<addr>&channel=imessage&since=<min>` | bearer | `{ sender, channel, status, since_minutes, messages }` **only if approved**; otherwise `403 { error: "Sender not approved. No messages for you.", status }`. On check failure: HTTP 502 with `{ error }`. |
+| `GET /resolve?name=<q>&channel=imessage` | bearer | `{ channel, query, matches: [{ sender_address, label, status }] }`. Empty/omitted `name` returns every labelled sender. **Never message text.** |
+| `POST /label` body `{ sender, channel, name }` | bearer | Set a sender's display label via an UPDATE-only web endpoint. **Cannot create a row or change `status`**, so it cannot open the gate. 404 if the sender is not on the list yet. |
+
+There is **no `approve`/`deny` over HTTP**. Approvals stay dashboard/`/decide`-only.
+`POST /label` is the only write — label metadata only. Unknown path → `404`. Bad
+params → `400`. Unsupported methods → `405`.
+
+### Security model
+
+- **Tailnet-only.** Default bind is this host's Tailscale IP (`100.64.0.0/10`) if
+  present, else `127.0.0.1`. It **never** binds `0.0.0.0` — `--bind 0.0.0.0` is
+  refused. For loopback bind, front it with `tailscale serve` to reach it on the
+  tailnet over HTTPS.
+- **Bearer token required** on every endpoint except `/health`. The token is
+  `serveToken` in config; comparison is constant-time (SHA-256 + `timingSafeEqual`)
+  and the token is never logged.
+- **Read-only surface.** No shell, no arbitrary file reads, no path traversal —
+  only the same channel adapters the CLI uses. Params are validated
+  (`channel`/`sender` charset-checked, `since` clamped to ≤ 7 days).
+- **Same gate.** `/read` calls the server list API (`api.ts`) *before* touching
+  any text — identical to `snazi read`. The gate is the product; it is not
+  bypassed.
+- **No storage.** Content is read live from `chat.db` and returned in the
+  response only. Nothing is persisted on either side.
+
+### Config keys
+
+Add to `~/.snazi/config.json` on the **serve host**:
+
+```json
+{
+  "serveToken": "<openssl rand -hex 32>",
+  "serveBind": "100.64.0.10",   // optional; default = tailnet IP else 127.0.0.1
+  "servePort": 8787              // optional; default 8787
+}
+```
+
+And on the **agent host** (remote client):
+
+```json
+{
+  "remoteUrl": "http://100.64.0.10:8787",
+  "remoteToken": "<same value as serveToken on the serve host>"
+}
+```
+
+### Run it
+
+```bash
+# Foreground (binds tailnet 100.x if present, else 127.0.0.1):
+snazi serve
+
+# Explicit bind/port:
+snazi serve --bind 100.64.0.10 --port 8787
+```
+
+### Run as a launchd service
+
+```bash
+snazi serve --install-daemon            # writes ~/Library/LaunchAgents/com.soup-nazi.snazi-serve.plist
+launchctl load -w ~/Library/LaunchAgents/com.soup-nazi.snazi-serve.plist   # start (RunAtLoad + KeepAlive)
+launchctl unload -w ~/Library/LaunchAgents/com.soup-nazi.snazi-serve.plist # stop
+```
+
+**Full Disk Access (required).** A launchd LaunchAgent runs in a context that
+cannot read `~/Library/Messages/chat.db` unless the **node binary** has Full
+Disk Access. `--install-daemon` prints the exact node path; add **that binary**
+(not just Terminal) in **System Settings → Privacy & Security → Full Disk
+Access**, then reload the agent. Without FDA, `/list-new` and `/read` return an
+FDA error — the gate still holds; you just get no data.
+
+### Calling it
+
+From the remote agent, either use the thin client subcommands:
+
+```bash
+snazi remote-status
+snazi remote-list-new --since 120
+snazi remote-check "+15551234567" --channel imessage
+snazi remote-read  "+15551234567"
+snazi remote-resolve "Dan" --channel imessage
+snazi remote-label "+15551234567" --name "Dan" --channel imessage
+```
+
+…or plain `curl` (bearer token in the header, never logged server-side):
+
+```bash
+TOKEN=...   # the serveToken
+BASE=http://100.64.0.10:8787
+
+curl -s "$BASE/health"
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/list-new?channel=imessage&since=120"
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/check?sender=%2B15551234567&channel=imessage"
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/read?sender=%2B15551234567&channel=imessage"
+curl -s -H "Authorization: Bearer $TOKEN" "$BASE/resolve?name=Dan&channel=imessage"
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"sender":"+15551234567","channel":"imessage","name":"Dan"}' "$BASE/label"
+# Unknown/denied sender on /read → 403 { "error": "Sender not approved. No messages for you.", ... }
+```
+
+## Why this design
+
+- **No prompt-injection surface from strangers.** The agent never sees content
+  from unknown senders, so a malicious text can't smuggle instructions to it.
+- **No message storage anywhere.** Cheap and private. The server is a list, not
+  an inbox.
+- **Extensible.** The same server list API works for other channels (e.g.
+  Gmail) — just add a channel and a new wrapper that calls `/api/senders/check`.

package/com.soup-nazi.snazi-serve.plist

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  snazi serve — launchd LaunchAgent.
+
+  This is a TEMPLATE. `snazi serve --install-daemon` substitutes the node
+  binary, CLI path, bind IP, port, and log dir, then writes the result to
+  ~/Library/LaunchAgents/com.soup-nazi.snazi-serve.plist.
+
+  IMPORTANT — Full Disk Access:
+    launchd starts this as YOU, but reading ~/Library/Messages/chat.db requires
+    Full Disk Access. Grant FDA to the node binary referenced below in
+    System Settings > Privacy & Security > Full Disk Access. Without it,
+    /list-new and /read return an FDA error (the gate still holds).
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.soup-nazi.snazi-serve</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__NODE__</string>
+        <string>__CLI__</string>
+        <string>serve</string>
+        <string>--bind</string>
+        <string>__BIND__</string>
+        <string>--port</string>
+        <string>__PORT__</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>ProcessType</key>
+    <string>Background</string>
+
+    <key>StandardOutPath</key>
+    <string>__LOGDIR__/snazi-serve.out.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__LOGDIR__/snazi-serve.err.log</string>
+</dict>
+</plist>

package/dist/address.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAddress = normalizeAddress;
+/**
+ * Normalize a sender address so the SAME person resolves to the SAME row
+ * whether they were added via the dashboard, a /decide link, the CLI, or read
+ * straight out of chat.db.
+ *
+ * THIS FILE IS KEPT BYTE-FOR-BYTE IN SYNC with packages/web/src/lib/address.ts.
+ * Writes (dashboard/decide) and checks (CLI/serve) MUST key on identical
+ * strings, so if you change one copy, change the other to match.
+ *
+ * Rules (deterministic — applied identically on write AND on check):
+ *   - Email (contains '@'): trimmed + lowercased.
+ *   - Phone: reduced to E.164 ("+" + country code + national digits).
+ *       * Anything starting with "+" is treated as E.164: "+1 (555) 123-4567"
+ *         -> "+15551234567".
+ *       * A bare national number is promoted to E.164 using a default country
+ *         calling code (SNAZI_DEFAULT_COUNTRY_CODE, default "1" / NANP). chat.db
+ *         hands us E.164 ("+1…"), but a human often types "(555) 123-4567";
+ *         without promotion the two never match -> "approved but gate shut".
+ *         A 10-digit number gets "+<cc>"; a number already prefixed with the CC
+ *         (e.g. "1 555 123 4567") just gets the "+".
+ *       * Numbers we can't confidently internationalize are left digit-only
+ *         (no worse than before) rather than mis-prefixed.
+ *
+ * A literal "+" in a query string decodes to a space, so an E.164 number can
+ * arrive as " 15551234567"; we restore the leading "+" in that case.
+ *
+ * The default country code is operator-configurable because guessing it is
+ * locale-specific; international users should enter full "+" E.164 numbers.
+ */
+function normalizeAddress(raw) {
+    const original = String(raw ?? '');
+    const s = original.trim();
+    if (s === '')
+        return '';
+    if (s.includes('@'))
+        return s.toLowerCase();
+    let plus = s.startsWith('+');
+    // A leading space (with no "+") means a literal "+" was decoded away.
+    if (!plus && /^\s\d/.test(original))
+        plus = true;
+    const digits = s.replace(/\D/g, '');
+    if (digits === '')
+        return s; // not phone-like; return trimmed original
+    if (plus)
+        return `+${digits}`;
+    // Bare national number → promote to E.164 with the default country code.
+    const cc = defaultCountryCode();
+    if (digits.length === 10)
+        return `+${cc}${digits}`;
+    if (cc && digits.length === 10 + cc.length && digits.startsWith(cc)) {
+        return `+${digits}`;
+    }
+    return digits; // can't confidently internationalize; leave digit-only
+}
+/** Default country calling code (digits only) used to promote bare numbers. */
+function defaultCountryCode() {
+    return (process.env.SNAZI_DEFAULT_COUNTRY_CODE ?? '1').replace(/\D/g, '');
+}

package/dist/api.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSender = checkSender;
+exports.listSenders = listSenders;
+exports.buildLabelMap = buildLabelMap;
+exports.setLabel = setLabel;
+exports.ping = ping;
+const address_1 = require("./address");
+// Force every request to bypass any HTTP/runtime cache. Typed loosely because
+// some @types/node versions omit `cache` from RequestInit.
+const NO_STORE = { cache: 'no-store' };
+/**
+ * Ask the server whether a sender is approved/denied/unknown.
+ * This is the gate: callers MUST check before revealing any content.
+ */
+async function checkSender(cfg, channel, address) {
+    const url = `${cfg.apiUrl}/api/senders/check?channel=${encodeURIComponent(channel)}&address=${encodeURIComponent(address)}`;
+    const res = await fetch(url, {
+        headers: { 'x-api-key': cfg.apiKey },
+        ...NO_STORE,
+    });
+    if (!res.ok) {
+        throw new Error(`check failed: HTTP ${res.status} ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return json.status ?? 'unknown';
+}
+/**
+ * Fetch the FULL sender list (address + label + status) for a channel using the
+ * READ key. Used by `snazi serve` to attach `label` to list-new/check results
+ * and to power /resolve. Reveals only the same address+label+status surface the
+ * dashboard read key already exposes — never message content.
+ */
+async function listSenders(cfg, channel) {
+    const url = `${cfg.apiUrl}/api/senders?channel=${encodeURIComponent(channel)}`;
+    const res = await fetch(url, {
+        headers: { 'x-api-key': cfg.apiKey },
+        ...NO_STORE,
+    });
+    if (!res.ok) {
+        throw new Error(`list senders failed: HTTP ${res.status} ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return Array.isArray(json.senders) ? json.senders : [];
+}
+/**
+ * Fetch the full sender list once and build an address→label map.
+ * Best-effort: on failure returns an empty map so labels show as null rather
+ * than breaking the (security-critical) status path.
+ */
+async function buildLabelMap(cfg, channel) {
+    const map = new Map();
+    try {
+        const senders = await listSenders(cfg, channel);
+        for (const s of senders) {
+            map.set((0, address_1.normalizeAddress)(s.sender_address), s.label ?? null);
+        }
+    }
+    catch {
+        // Swallow: labels are non-critical display metadata.
+    }
+    return map;
+}
+/**
+ * Set (overwrite) a sender's display label using the READ key.
+ *
+ * This calls the web PATCH /api/senders/label endpoint, which performs an
+ * UPDATE only — it can NEVER insert a new row or change `status`. It is the
+ * single non-privileged write the read path can make: a label is display
+ * metadata and cannot open the gate. If the sender is not already on the list,
+ * the web endpoint returns 404 and this throws.
+ */
+async function setLabel(cfg, channel, address, label) {
+    const res = await fetch(`${cfg.apiUrl}/api/senders/label`, {
+        method: 'PATCH',
+        headers: { 'content-type': 'application/json', 'x-api-key': cfg.apiKey },
+        body: JSON.stringify({
+            channel_id: channel,
+            sender_address: address,
+            label,
+        }),
+        ...NO_STORE,
+    });
+    if (!res.ok) {
+        throw new Error(`label failed: HTTP ${res.status} ${await res.text()}`);
+    }
+    return res.json();
+}
+/** Lightweight connectivity probe for `status`. */
+async function ping(cfg) {
+    try {
+        const res = await fetch(`${cfg.apiUrl}/api/senders?channel=imessage`, {
+            headers: { 'x-api-key': cfg.apiKey },
+            ...NO_STORE,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cache.js

@@ -0,0 +1,173 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheTtlMs = cacheTtlMs;
+exports.getCachedStatus = getCachedStatus;
+exports.setCachedStatus = setCachedStatus;
+exports.clearCache = clearCache;
+exports.checkSenderCached = checkSenderCached;
+/**
+ * Short-lived, on-disk cache for sender approval STATUS (never message text).
+ *
+ * Why disk and not memory: the CLI runs on demand and exits, so an in-memory
+ * cache would be empty on every invocation. A small JSON file in ~/.snazi lets
+ * repeated `read`/`check`/`list-new` calls (and a long-running `serve`) reuse a
+ * recent decision instead of hitting the API every time.
+ *
+ * What it caches: only DECIDED states (approved/denied), which reflect an
+ * explicit human decision that rarely flips. 'unknown' is NEVER cached, so a
+ * brand-new approval takes effect on the very next call.
+ *
+ * The trade-off (deliberate): a REVOCATION can take up to `ttl` to be seen by
+ * the agent. That is the whole point of the cache — approvals are sticky, and a
+ * few minutes of staleness on the rare "I just blocked them" case is acceptable.
+ * Use `fresh: true` (CLI `--fresh`) or `snazi cache clear` to force a live check
+ * the instant you revoke someone.
+ *
+ * Safe degradation: any cache read/write error falls back to a live server check.
+ * The cache can only skip a round-trip — it never fabricates an approval.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const api_1 = require("./api");
+const address_1 = require("./address");
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/** Cache file path. SNAZI_CACHE_FILE overrides it (used by tests). */
+function cacheFilePath() {
+    const override = process.env.SNAZI_CACHE_FILE;
+    if (override && override.trim() !== '')
+        return override;
+    return path.join(os.homedir(), '.snazi', 'check-cache.json');
+}
+/**
+ * Resolve the cache TTL in ms: env SNAZI_CHECK_CACHE_TTL_MS wins, then
+ * config.checkCacheTtlMs, then a 5-minute default. 0 (or negative) disables
+ * caching entirely (every check goes live).
+ */
+function cacheTtlMs(cfg) {
+    const env = process.env.SNAZI_CHECK_CACHE_TTL_MS;
+    if (env !== undefined && env !== '') {
+        const n = Number(env);
+        if (Number.isFinite(n))
+            return Math.max(0, Math.floor(n));
+    }
+    if (typeof cfg.checkCacheTtlMs === 'number' && Number.isFinite(cfg.checkCacheTtlMs)) {
+        return Math.max(0, Math.floor(cfg.checkCacheTtlMs));
+    }
+    return DEFAULT_TTL_MS;
+}
+/** Cache key: normalized so "(555) 123-4567" and "+15551234567" share an entry. */
+function cacheKey(channel, address) {
+    return `${channel}|${(0, address_1.normalizeAddress)(address)}`;
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(cacheFilePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {}; // missing/corrupt/unreadable -> treat as empty
+    }
+}
+function writeCache(data) {
+    try {
+        const file = cacheFilePath();
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        // Atomic: write a temp file then rename so readers never see a partial file.
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Best-effort: a write failure must never break the gate.
+    }
+}
+/** Cached status if present AND unexpired, else undefined. */
+function getCachedStatus(channel, address) {
+    const entry = readCache()[cacheKey(channel, address)];
+    if (!entry)
+        return undefined;
+    if (Date.now() >= entry.expiresAt)
+        return undefined;
+    return entry.status;
+}
+/** Store a status for `ttlMs`. Prunes expired entries. No-op when ttlMs <= 0. */
+function setCachedStatus(channel, address, status, ttlMs) {
+    if (ttlMs <= 0)
+        return;
+    const data = readCache();
+    const now = Date.now();
+    for (const k of Object.keys(data)) {
+        if (now >= data[k].expiresAt)
+            delete data[k];
+    }
+    data[cacheKey(channel, address)] = { status, expiresAt: now + ttlMs };
+    writeCache(data);
+}
+/** Wipe the whole cache (used by `snazi cache clear`). */
+function clearCache() {
+    try {
+        const file = cacheFilePath();
+        if (fs.existsSync(file))
+            fs.unlinkSync(file);
+    }
+    catch {
+        // Nothing to clear / not removable -> ignore.
+    }
+}
+/**
+ * Approval check with the short-lived cache in front of the live server gate.
+ *
+ * Reads a cached decided status when fresh; otherwise checks the server and
+ * caches approved/denied results. `unknown` is never cached. Pass `fresh: true`
+ * to bypass the cache for this call (and refresh it from the server).
+ */
+async function checkSenderCached(cfg, channel, address, opts = {}) {
+    const ttl = cacheTtlMs(cfg);
+    if (!opts.fresh && ttl > 0) {
+        const hit = getCachedStatus(channel, address);
+        if (hit)
+            return hit;
+    }
+    const status = await (0, api_1.checkSender)(cfg, channel, address);
+    if (status === 'approved' || status === 'denied') {
+        setCachedStatus(channel, address, status, ttl);
+    }
+    return status;
+}