@chipallen2/snazi 0.1.1 → 0.2.0

package/README.md

@@ -81,10 +81,10 @@ snazi init && snazi doctor
 | --- | --- |
 | `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 list-new [--channel <id>] [--since <min>] [--fresh]` | Distinct inbound senders, counts, timestamps, approval status, display label, and local Contacts `contact_name`. **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 send <recipient> --text <message> [--channel <id>]` | Send a message. **Never gated** — you can always send to anyone. |
-| `snazi check <sender> --channel <id> [--fresh]` | One sender's approval status and display label (`approved`/`denied`/`unknown`). |
+| `snazi check <sender> --channel <id> [--fresh]` | One sender's approval status, display label, and local Contacts `contact_name` (`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). |
@@ -110,7 +110,8 @@ right after you revoke someone.
 snazi list-new --since 180
 # [
 #   { "sender": "+15551234567", "message_count": 3,
-#     "latest_at": "2026-06-23T22:10:04.000Z", "status": "unknown", "label": null }
+#     "latest_at": "2026-06-23T22:10:04.000Z", "status": "unknown",
+#     "label": null, "contact_name": "Jenny Tutone" }
 # ]
 
 snazi read "+15551234567"
@@ -163,17 +164,42 @@ privilege.
 | 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 /list-new?channel=imessage&since=<min>` | bearer | `{ channel, since_minutes, senders: [{ sender, message_count, latest_at, status, label, contact_name }] }`. 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, contact_name }`. On check failure: HTTP 502 with `{ error }`. |
+| `GET /read?sender=<addr>&channel=imessage&since=<min>` | bearer | `{ sender, channel, status, since_minutes, contact_name, messages }` **only if approved**; otherwise `403 { error: "Sender not approved. No messages for you.", status }`. On check failure: HTTP 502 with `{ error }`. |
 | `POST /send` body `{ recipient, channel, text }` | bearer | Send an outbound message. **Never gated** — you can always send to anyone. Returns `{ ok: true, channel, recipient }` on success. |
-| `GET /resolve?name=<q>&channel=imessage` | bearer | `{ channel, query, matches: [{ sender_address, label, status }] }`. Empty/omitted `name` returns every labelled sender. **Never message text.** |
+| `GET /resolve?name=<q>&channel=imessage` | bearer | `{ channel, query, matches: [{ sender_address, label, status, contact_name }] }`. 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`.
 
+### `contact_name` — local macOS Contacts enrichment (display only)
+
+`/list-new`, `/check`, `/resolve` (and the `200` body of `/read`) include a
+`contact_name` for each sender: the matching name from the serve host's **local
+macOS Contacts** (AddressBook), looked up by phone/email. It is attached for
+**every** sender **regardless of approval status**, so you can see *who* an
+`unknown`/`denied` caller is without reading their messages.
+
+- **Display-only, never a gate.** `contact_name` **never** affects `status`,
+  approval, or the read gate. Reading is still allowed **solely** when
+  `status === 'approved'` — a known contact name does **not** open the gate.
+- **Separate from `label`.** `label` = the name you set on your snazi.dev
+  account (privileged). `contact_name` = read locally from macOS Contacts. Both
+  fields are kept separate in the JSON; `null` when there's no match.
+- **Untrusted text.** A contact name is stripped of control characters and
+  length-capped (≤64) before it's ever returned — it can't carry a
+  terminal/log-injection payload.
+- **Degrades silently.** If Contacts is unreadable (no permission, non-macOS,
+  native module missing), `contact_name` is simply `null` and nothing breaks.
+
+**Contacts access on the serve host.** Reading the AddressBook DB needs the node
+binary to have **Contacts** access (or **Full Disk Access**, which already
+covers the AddressBook database). Full Disk Access is the simplest option since
+you already grant it for iMessage; without it `contact_name` just stays `null`.
+
 ### Security model
 
 - **Tailnet-only.** Default bind is this host's Tailscale IP (`100.64.0.0/10`) if

package/dist/cli.js

@@ -34,6 +34,7 @@ const address_1 = require("./address");
 const api_1 = require("./api");
 const cache_1 = require("./cache");
 const channels_1 = require("./channels");
+const contacts_1 = require("./contacts");
 const server_1 = require("./server");
 const client_1 = require("./client");
 const daemon_1 = require("./daemon");
@@ -85,6 +86,8 @@ async function cmdListNew(args) {
     }
     const senders = adapter.listInboundSenders(since);
     const labels = await (0, api_1.buildLabelMap)(cfg, channel);
+    // Local macOS Contacts enrichment (display-only; best-effort, empty on fail).
+    const contacts = (0, contacts_1.buildContactIndex)();
     const results = [];
     for (const s of senders) {
         let status = 'unknown';
@@ -100,7 +103,10 @@ async function cmdListNew(args) {
             message_count: s.message_count,
             latest_at: s.latest_at,
             status,
+            // `label` = snazi.dev account name; `contact_name` = local Contacts name.
+            // Both kept as SEPARATE fields; contact_name never affects the gate.
             label: labels.get((0, address_1.normalizeAddress)(s.sender)) ?? null,
+            contact_name: contacts.get(s.sender),
         };
         if (checkError)
             entry.error = checkError;
@@ -158,7 +164,9 @@ async function cmdCheck(args) {
         const status = await (0, cache_1.checkSenderCached)(cfg, channel, target, { fresh });
         const labels = await (0, api_1.buildLabelMap)(cfg, channel);
         const label = labels.get(target) ?? null;
-        out({ channel, sender: target, status, label });
+        // Display-only Contacts name; separate field, never gates reading.
+        const contact_name = (0, contacts_1.buildContactIndex)().get(target);
+        out({ channel, sender: target, status, label, contact_name });
         return 0;
     }
     catch (e) {

package/dist/contacts.js

@@ -0,0 +1,337 @@
+"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.sanitizeContactName = sanitizeContactName;
+exports.addressBookDbPaths = addressBookDbPaths;
+exports.buildContactIndex = buildContactIndex;
+exports.probeContacts = probeContacts;
+/**
+ * macOS Contacts (AddressBook) name enrichment — DISPLAY METADATA ONLY.
+ *
+ * Reads the local macOS AddressBook SQLite DB(s) read-only to build a
+ * Map<normalizedAddress, displayName> so the serve host can attach a
+ * `contact_name` to each sender it reports. This is purely cosmetic.
+ *
+ * SECURITY INVARIANTS (must hold everywhere this module is used):
+ *   1. `contact_name` is DISPLAY-ONLY. It MUST NEVER influence approval
+ *      status, the read gate, or routing. Reading message text stays gated
+ *      solely by `status === 'approved'` over in server.ts/handleRead.
+ *   2. A contact name is UNTRUSTED display text: every name is stripped of
+ *      control characters and length-capped (see sanitizeContactName) exactly
+ *      like the server's parseName/NAME_CTRL_RE handling, so it can never carry
+ *      a terminal/log-injection payload. It is never executed or interpreted.
+ *   3. If Contacts is unavailable (no DB, no permission, better-sqlite3
+ *      missing, or non-macOS) every export DEGRADES to "empty" and NEVER
+ *      throws. The gate keeps working with zero Contacts access.
+ *
+ * This mirrors chatdb.ts: better-sqlite3 (a native module) is required LAZILY
+ * inside functions, and the DB path honors env overrides so tests can point at
+ * a synthetic AddressBook:
+ *   - SNAZI_ADDRESSBOOK_DB  : a single .abcddb file (used directly; tests).
+ *   - SNAZI_ADDRESSBOOK_DIR : base AddressBook dir to scan (defaults to the
+ *                             real ~/Library/Application Support/AddressBook).
+ */
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const address_1 = require("./address");
+// Keep in sync with server.ts MAX_NAME_LEN / parseName: a contact name is the
+// same kind of untrusted, length-capped, control-char-free display text.
+const MAX_CONTACT_NAME_LEN = 64;
+// eslint-disable-next-line no-control-regex
+const NAME_CTRL_RE = /[\u0000-\u001f\u007f]/g;
+/**
+ * Sanitize a raw Contacts name into safe display text, or null if there is
+ * nothing usable left. Strips ALL control chars (defends terminal/log
+ * injection) and hard-caps the length. Mirrors the server's name handling —
+ * the difference is we STRIP rather than reject, so one weird contact never
+ * breaks enrichment for everyone else.
+ */
+function sanitizeContactName(raw) {
+    if (raw == null)
+        return null;
+    // Remove control chars first, then collapse surrounding whitespace.
+    const stripped = String(raw).replace(NAME_CTRL_RE, '').trim();
+    if (stripped === '')
+        return null;
+    const capped = stripped.slice(0, MAX_CONTACT_NAME_LEN).trim();
+    return capped === '' ? null : capped;
+}
+/** Default macOS AddressBook base directory. */
+function defaultAddressBookDir() {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'AddressBook');
+}
+/**
+ * Resolve every AddressBook .abcddb file to union across. Honors env overrides.
+ * Never throws — returns [] on any filesystem hiccup.
+ *
+ * Real layout (any/all may exist):
+ *   <base>/AddressBook-v22.abcddb
+ *   <base>/Sources/<UUID>/AddressBook-v22.abcddb   (one per account/source)
+ */
+function addressBookDbPaths() {
+    try {
+        const single = process.env.SNAZI_ADDRESSBOOK_DB;
+        if (single && single.trim() !== '') {
+            return fs.existsSync(single) ? [single] : [];
+        }
+        const base = process.env.SNAZI_ADDRESSBOOK_DIR &&
+            process.env.SNAZI_ADDRESSBOOK_DIR.trim() !== ''
+            ? process.env.SNAZI_ADDRESSBOOK_DIR
+            : defaultAddressBookDir();
+        const found = [];
+        const topLevel = path.join(base, 'AddressBook-v22.abcddb');
+        if (fs.existsSync(topLevel))
+            found.push(topLevel);
+        const sourcesDir = path.join(base, 'Sources');
+        let sources = [];
+        try {
+            sources = fs.readdirSync(sourcesDir);
+        }
+        catch {
+            sources = [];
+        }
+        for (const sub of sources) {
+            const p = path.join(sourcesDir, sub, 'AddressBook-v22.abcddb');
+            if (fs.existsSync(p))
+                found.push(p);
+        }
+        // Deterministic union order so "first non-empty name wins" is stable.
+        return [...new Set(found)].sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Lazy native require — only loaded when we actually touch Contacts. */
+function loadSqlite() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require('better-sqlite3');
+}
+/** Last 10 digits of an address, or '' if it isn't a >=10-digit phone. */
+function last10(address) {
+    const digits = address.replace(/\D/g, '');
+    return digits.length >= 10 ? digits.slice(-10) : '';
+}
+/** Empty index used on every failure/degradation path. */
+const EMPTY_INDEX = {
+    size: 0,
+    get() {
+        return null;
+    },
+};
+function makeIndex(byNorm, byLast10) {
+    return {
+        size: byNorm.size,
+        get(address) {
+            const norm = (0, address_1.normalizeAddress)(address);
+            if (norm === '')
+                return null;
+            const exact = byNorm.get(norm);
+            if (exact)
+                return exact;
+            // Phone fallback: match by trailing 10 digits. This MUST be restricted to
+            // phone-like inputs: an email such as "john5551234567@gmail.com" still
+            // contains >=10 digits, and without this guard it would false-match a
+            // phone contact's trailing-10 key — attaching a TRUSTED contact name to an
+            // UNTRUSTED email address (a decide-time display-spoofing vector). Emails
+            // resolve by exact normalized address ONLY.
+            if (norm.includes('@'))
+                return null;
+            const tail = last10(norm);
+            if (tail !== '') {
+                const byTail = byLast10.get(tail);
+                if (byTail)
+                    return byTail;
+            }
+            return null;
+        },
+    };
+}
+/** Compose a record's display name: "First Last" -> nickname -> organization. */
+function recordDisplayName(r) {
+    const first = (r.ZFIRSTNAME ?? '').trim();
+    const last = (r.ZLASTNAME ?? '').trim();
+    const full = `${first} ${last}`.trim();
+    if (full !== '')
+        return full;
+    const nick = (r.ZNICKNAME ?? '').trim();
+    if (nick !== '')
+        return nick;
+    const org = (r.ZORGANIZATION ?? '').trim();
+    if (org !== '')
+        return org;
+    return null;
+}
+/**
+ * Index one AddressBook DB into the provided maps. "First non-empty name wins":
+ * we never overwrite an existing key, so union order (sorted db paths, then
+ * Z_PK order) is deterministic. Best-effort: any failure on a single DB is
+ * swallowed so the rest still contribute.
+ */
+function indexOneDb(dbPath, byNorm, byLast10) {
+    const Database = loadSqlite();
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        const records = db
+            .prepare('SELECT Z_PK, ZFIRSTNAME, ZLASTNAME, ZORGANIZATION, ZNICKNAME FROM ZABCDRECORD')
+            .all();
+        const nameByPk = new Map();
+        for (const r of records) {
+            const name = sanitizeContactName(recordDisplayName(r));
+            if (name)
+                nameByPk.set(r.Z_PK, name);
+        }
+        const addKey = (map, key, name) => {
+            if (key === '')
+                return;
+            if (!map.has(key))
+                map.set(key, name); // first non-empty wins
+        };
+        // Phones — normalize, plus a last-10 fallback key.
+        const phones = db
+            .prepare('SELECT ZOWNER, ZFULLNUMBER FROM ZABCDPHONENUMBER WHERE ZFULLNUMBER IS NOT NULL')
+            .all();
+        for (const p of phones) {
+            if (p.ZOWNER == null)
+                continue;
+            const name = nameByPk.get(p.ZOWNER);
+            if (!name)
+                continue;
+            const norm = (0, address_1.normalizeAddress)(p.ZFULLNUMBER);
+            addKey(byNorm, norm, name);
+            addKey(byLast10, last10(norm), name);
+        }
+        // Emails — normalize (trim+lowercase).
+        const emails = db
+            .prepare('SELECT ZOWNER, ZADDRESS FROM ZABCDEMAILADDRESS WHERE ZADDRESS IS NOT NULL')
+            .all();
+        for (const e of emails) {
+            if (e.ZOWNER == null)
+                continue;
+            const name = nameByPk.get(e.ZOWNER);
+            if (!name)
+                continue;
+            addKey(byNorm, (0, address_1.normalizeAddress)(e.ZADDRESS), name);
+        }
+    }
+    catch {
+        // Schema variance, locked DB, missing permission — skip this source.
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // ignore close errors
+        }
+    }
+}
+/**
+ * Build a ContactIndex from every available local AddressBook DB.
+ * NEVER throws — returns an empty index when Contacts can't be read for ANY
+ * reason (non-macOS, no DB, no permission, better-sqlite3 missing). Callers
+ * should treat a miss as `contact_name: null` and carry on.
+ */
+function buildContactIndex() {
+    try {
+        const paths = addressBookDbPaths();
+        if (paths.length === 0)
+            return EMPTY_INDEX;
+        const byNorm = new Map();
+        const byLast10 = new Map();
+        for (const p of paths)
+            indexOneDb(p, byNorm, byLast10);
+        if (byNorm.size === 0)
+            return EMPTY_INDEX;
+        return makeIndex(byNorm, byLast10);
+    }
+    catch {
+        return EMPTY_INDEX;
+    }
+}
+/**
+ * Non-throwing readability probe (mirrors chatdb.probeChatDb). Reports whether
+ * at least one AddressBook DB exists and can be opened+queried read-only.
+ * Purely diagnostic — enrichment itself always degrades silently.
+ */
+function probeContacts() {
+    try {
+        const paths = addressBookDbPaths();
+        if (paths.length === 0) {
+            return { ok: false, reason: 'No macOS AddressBook database found.' };
+        }
+        let Database;
+        try {
+            Database = loadSqlite();
+        }
+        catch (e) {
+            return {
+                ok: false,
+                reason: `better-sqlite3 unavailable: ${String(e instanceof Error ? e.message : e)}`,
+            };
+        }
+        for (const p of paths) {
+            let db;
+            try {
+                db = new Database(p, { readonly: true, fileMustExist: true });
+                db.prepare('SELECT 1 FROM ZABCDRECORD LIMIT 1').get();
+                return { ok: true };
+            }
+            catch {
+                // try the next source
+            }
+            finally {
+                try {
+                    db?.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        return {
+            ok: false,
+            reason: 'AddressBook database(s) present but not readable (grant Contacts / Full Disk Access).',
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `Contacts probe failed: ${String(e instanceof Error ? e.message : e)}`,
+        };
+    }
+}

package/dist/server.js

@@ -70,6 +70,25 @@ const cache_1 = require("./cache");
 const channels_1 = require("./channels");
 const address_1 = require("./address");
 const imessage_send_1 = require("./imessage-send");
+const contacts_1 = require("./contacts");
+/**
+ * Build the macOS Contacts index for ONE request, best-effort. NEVER throws:
+ * any failure (no DB, no permission, non-macOS, better-sqlite3 missing) yields
+ * an empty index so enrichment degrades to `contact_name: null` and the gate
+ * keeps working with zero Contacts access.
+ *
+ * SECURITY: the returned name is DISPLAY-ONLY. It is never consulted by the
+ * read gate (handleRead checks `status === 'approved'` and nothing else) and
+ * is already sanitized (control-char-stripped + length-capped) by contacts.ts.
+ */
+function contactIndexForRequest() {
+    try {
+        return (0, contacts_1.buildContactIndex)();
+    }
+    catch {
+        return { size: 0, get: () => null };
+    }
+}
 // Read version without importing JSON at compile time (keeps build simple).
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const VERSION = (() => {
@@ -261,6 +280,8 @@ async function handleListNew(cfg, url) {
     const senders = adapter.listInboundSenders(since);
     // One list fetch -> address->label map (best-effort; null on any failure).
     const labels = await (0, api_1.buildLabelMap)(cfg, channel);
+    // Build the Contacts index ONCE per request (best-effort, empty on failure).
+    const contacts = contactIndexForRequest();
     const results = [];
     for (const s of senders) {
         let status = 'unknown';
@@ -276,7 +297,12 @@ async function handleListNew(cfg, url) {
             message_count: s.message_count,
             latest_at: s.latest_at,
             status,
+            // `label` = user's snazi.dev account-set name (privileged display).
             label: labels.get((0, address_1.normalizeAddress)(s.sender)) ?? null,
+            // `contact_name` = local macOS Contacts name (display-only metadata).
+            // Kept SEPARATE from `label`; included regardless of approval status.
+            // It NEVER affects `status` or the read gate.
+            contact_name: contacts.get(s.sender),
         };
         if (checkError)
             entry.error = checkError;
@@ -305,15 +331,20 @@ async function handleRead(cfg, url) {
         };
     }
     if (status !== 'approved') {
+        // GATE: reading is denied SOLELY on approval status. `contact_name` is
+        // deliberately NOT consulted here — a known Contacts name must never open
+        // the gate. We don't even compute it on the denied path.
         return {
             status: 403,
             body: { error: 'Sender not approved. No messages for you.', status },
         };
     }
     const messages = adapter.readMessagesFrom(sender, since);
+    // Gate already passed; attach display-only Contacts name (best-effort).
+    const contact_name = contactIndexForRequest().get(sender);
     return {
         status: 200,
-        body: { sender, channel, status, since_minutes: since, messages },
+        body: { sender, channel, status, since_minutes: since, contact_name, messages },
     };
 }
 async function handleCheck(cfg, url) {
@@ -332,7 +363,10 @@ async function handleCheck(cfg, url) {
     // Best-effort label lookup for this one address (display only).
     const labels = await (0, api_1.buildLabelMap)(cfg, channel);
     const label = labels.get(sender) ?? null;
-    return { status: 200, body: { channel, sender, status, label } };
+    // Display-only Contacts name. Kept separate from `label`; included no matter
+    // the approval status. It does NOT (and must not) affect `status`.
+    const contact_name = contactIndexForRequest().get(sender);
+    return { status: 200, body: { channel, sender, status, label, contact_name } };
 }
 /**
  * GET /resolve?name=<q>&channel=<id>
@@ -346,6 +380,8 @@ async function handleResolve(cfg, url) {
     const query = parseName(url.searchParams.get('name'), true);
     const needle = query.toLowerCase();
     const senders = await (0, api_1.listSenders)(cfg, channel);
+    // Build the Contacts index ONCE for this request (best-effort, empty on fail).
+    const contacts = contactIndexForRequest();
     const matches = senders
         .filter((s) => {
         if (s.label == null || s.label === '')
@@ -358,6 +394,8 @@ async function handleResolve(cfg, url) {
         sender_address: s.sender_address,
         label: s.label,
         status: s.status,
+        // Display-only macOS Contacts name; separate from `label`, never gates.
+        contact_name: contacts.get(s.sender_address),
     }));
     return { status: 200, body: { channel, query, matches } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chipallen2/snazi",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "On-demand local gate for your messages. Reveals WHO contacted you; only reveals WHAT for approved senders. iMessage today, pluggable channels next.",
   "license": "MIT",
   "homepage": "https://snazi.dev",
@@ -39,10 +39,10 @@
     "build": "tsc",
     "start": "node dist/cli.js",
     "prepare": "npm run build",
-    "test": "npm run build && node test/address.test.cjs && node test/cache.test.cjs && node test/both-sides.test.cjs && node test/serve-names.test.cjs && node test/channels.test.cjs && node test/send.test.cjs",
-    "release:patch": "npm version patch -m \"release: v%s\" && git push --follow-tags",
-    "release:minor": "npm version minor -m \"release: v%s\" && git push --follow-tags",
-    "release:major": "npm version major -m \"release: v%s\" && git push --follow-tags"
+    "test": "npm run build && node test/address.test.cjs && node test/cache.test.cjs && node test/both-sides.test.cjs && node test/serve-names.test.cjs && node test/channels.test.cjs && node test/send.test.cjs && node test/contacts.test.cjs && node test/serve-contacts.test.cjs",
+    "release:patch": "bash scripts/release.sh patch",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major"
   },
   "optionalDependencies": {
     "better-sqlite3": "^11.3.0"