@hasna/contacts 0.7.0 → 0.9.0

package/README.md

@@ -11,36 +11,100 @@ Contact management for AI coding agents — CLI + MCP + authenticated HTTP API
 npm install -g @hasna/contacts
 ```
 
+## Chrome extension
+
+The package ships a Chrome extension that fills name, email, phone, company
+and address fields from your contacts — from the toolbar popup or from the
+Contacts badge that appears inside detected form fields. It uses the same
+hosted API and credential as the CLI. Run `contacts browser install`, load the
+printed `extensionPath` unpacked in `chrome://extensions`, and see
+[docs/chrome-autofill.md](docs/chrome-autofill.md) for how detection, the
+picker and the security boundaries work.
+
 ## Configure the client
 
 Every CLI, MCP, and package data operation uses one authenticated HTTPS `/v1`
-authority. There is no built-in hosted URL and no local database fallback.
+authority resolved by the shared `@hasna/contracts` client chain
+(hasna/apps#1720), resolved fresh on every request. There is no local database
+fallback and no per-app env chain of its own.
+
+Once a contacts API key resolves from any tier, the authority defaults to the
+fleet gateway `https://api.hasna.com/contacts` — no URL configuration is
+needed on a station. The credential tiers, in order:
+
+1. explicit arguments / deliberate pointers — `HASNA_CONTACTS_API_KEY_OVERRIDE`, `HASNA_PROFILE`, `HASNA_CONTACTS_API_KEY_REF` (secrets vault)
+2. macOS Keychain — `hasna.credentials.contacts.api-key` / `.api-url`, account `HASNA_STATION` → `hostname -s` → `$USER`
+3. disk — `~/.hasna/contacts/config/credentials` (owner-only 0400/0600, `HASNA_CONTACTS_API_KEY=…` or the `HASNA_CONTACTS_API_URL=…` alias)
+4. environment — `HASNA_CONTACTS_API_KEY`
+
+| Env var | Meaning |
+|---|---|
+| `HASNA_CONTACTS_API_URL` | Explicit API base URL (HTTPS; overrides the fleet gateway). Legacy alias: `CONTACTS_API_URL`. |
+| `HASNA_CONTACTS_API_KEY` | API key (env tier). Legacy alias: `CONTACTS_API_KEY`. |
+| `HASNA_CONTACTS_API_KEY_OVERRIDE` | Deliberate per-run override that outranks the Keychain and disk. |
+| `HASNA_CONTACTS_API_KEY_REF` | Secrets-vault pointer (`namespace/app/live/api_key`); terminal when unresolvable. |
+| `HASNA_PROFILE` | Selects which identity (`credentials-<profile>`) the disk tier reads. |
+| `HASNA_STATION` | Keychain account when set; else short hostname, then `$USER`. |
+| `HASNA_HOME` | Replaces `~` for the `~/.hasna/…` credential/disk root. |
+| `HASNA_CONFIG_HOME` | Replaces `~/.hasna/<app>/config` entirely. |
 
 ```bash
+# Fully explicit:
 export HASNA_CONTACTS_API_URL="https://contacts.example.com"
-# Provision the API key through the @hasna/contracts credential chain. For
-# example, put HASNA_CONTACTS_API_KEY in the shared fleet/config credential chain,
-# or configure HASNA_CONTACTS_API_KEY_REF for the secrets client.
+export HASNA_CONTACTS_API_KEY="…"     # or configure the Keychain/disk tiers
 contacts connection --json
 ```
 
-An absent or invalid URL/key fails closed. `HASNA_CONTACTS_STORAGE_MODE`,
-`CONTACTS_STORAGE_MODE`, contacts DB-path variables, and contacts database URLs
-are rejected in client processes. PostgreSQL URLs belong only to
-`contacts-serve` and the migration task.
+An absent URL and key fails closed: operations exit non-zero and never open a
+local store; `contacts connection` reports `transport: "unconfigured"`.
+The fail-closed message starts on the FIRST stderr line — it names what is
+missing and where the credential should live (`HASNA_CONTACTS_API_KEY`, the
+Keychain item, the credentials-file path), never a value.
+`HASNA_CONTACTS_STORAGE_MODE`, `CONTACTS_STORAGE_MODE`, contacts DB-path
+variables, and contacts database URLs are rejected in client processes.
+PostgreSQL URLs belong only to `contacts-serve` and the migration task.
 
 ## CLI Usage
 
 ```bash
-contacts status            # CLI version, API endpoint, storage mode, record counts
+contacts status            # CLI version, resolved /v1 authority + sources, storage mode, record counts
 contacts status --json
 contacts --help
 ```
 
-`contacts status` answers even on a box without an API key: an unconfigured
-client reports storage `unconfigured` (a failed request on a configured box
-reports storage `error` with the failure message) instead of crashing, so
-agents can observe the configuration drift the command exists to expose.
+`contacts status` reports the authority the shared resolver actually decided
+(`api`, the `/v1` base URL) and where each half came from — `api_url_source`,
+`api_key_source`, `api_key_tier`: an env key name, a Keychain item reference,
+a credentials-file path, or `default` for the fleet gateway; never a value.
+It answers even on a box without an API key: an unconfigured client reports
+storage `unconfigured` with the resolver's `issue` (a failed request on a
+configured box reports storage `error` with the failure message) instead of
+crashing, so agents can observe the configuration drift the command exists to
+expose. `status` and `connection` are diagnostics and exit 0 with that report;
+every data verb fails closed (non-zero exit, no local store).
+
+## SDK
+
+```ts
+import { createContactsClient, ContactsV1Client } from "@hasna/contacts/sdk";
+
+// Through the fleet resolver — the same @hasna/contracts chain the CLI and MCP
+// server use: credential and authority resolved at construction, the key
+// re-resolved on every request, the authority pinned. Nothing resolving throws.
+const client = createContactsClient();
+const { contacts } = await client.listContacts();
+
+// Explicit pin: a caller-supplied baseUrl always requires a caller-supplied
+// apiKey — the SDK never attaches an ambient credential to it.
+const pinned = new ContactsV1Client({ baseUrl: "https://contacts.example.com", apiKey: "…" });
+```
+
+`createContactsClient()` resolves the literal tiers only — an explicit
+`apiKey`, `HASNA_CONTACTS_API_KEY_OVERRIDE`, the Keychain item, the
+credentials file, `HASNA_CONTACTS_API_KEY`. The secrets-vault pointer
+`HASNA_CONTACTS_API_KEY_REF` is refused with
+`CONTACTS_CREDENTIAL_POINTER_UNSUPPORTED` (the SDK resolves synchronously per
+request and cannot complete a vault lookup); the CLI and MCP server accept it.
 
 
 ## Audiences, consent, and suppression
@@ -76,6 +140,22 @@ suppressed addresses; the audience `--policy` (`opt_in`, `opt_out`,
 contacts-mcp
 ```
 
+`contacts-mcp` fails closed at startup: with no credential resolvable through
+the chain above it exits non-zero BEFORE the stdio transport is connected or
+the HTTP port is bound — an `initialize` request is never answered by an
+unauthenticated server — and creates nothing under the app home. The first
+stderr line names where the credential should live (the Keychain item, the
+credentials-file path, `HASNA_CONTACTS_API_KEY`), never a value.
+`--help` / `--version` answer ahead of the gate; every tool still re-resolves
+the credential per request once the server is up.
+
+The deliberate tiers are honoured at the gate as well. The secrets-vault
+pointer `HASNA_CONTACTS_API_KEY_REF` is dereferenced once at startup (the
+chain alone only checks the pointer's shape): a pointer the vault cannot
+complete, a `HASNA_PROFILE` whose credentials file is missing, or an unsafe
+(not owner-only) credentials file is a one-line refusal naming the pointer,
+the file, or the item — never resolved around, never a stack trace.
+
 ## HTTP mode
 
 Long-lived Streamable HTTP transport (stateless, bind `127.0.0.1` only):

package/dist/browser/cli.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+/** `contacts browser …` — install and inspect the Chrome extension bridge. JSON output only. */
+export declare function registerBrowserCommands(program: Command): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/browser/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/browser/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsB9D"}

package/dist/browser/identity.d.ts

@@ -0,0 +1,3 @@
+export declare const EXTENSION_ID = "ceegpmbcoiomonopbhpifdalooccfgjj";
+export declare const HOST_NAME = "com.hasna.contacts";
+//# sourceMappingURL=identity.d.ts.map

package/dist/browser/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/browser/identity.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,qCAAqC,CAAC;AAC/D,eAAO,MAAM,SAAS,uBAAuB,CAAC"}

package/dist/browser/install.d.ts

@@ -0,0 +1,32 @@
+export declare function hostDirectories(home?: string, userDataDir?: string): string[];
+export interface InstallOptions {
+    userDataDir?: string;
+    /** Test seam: the home directory that owns ~/.hasna/contacts and the Chrome profiles. */
+    home?: string;
+    /** Test seam: the package root that holds extension/ and dist/. */
+    root?: string;
+    /** Test seam: the absolute runtime used in the host shebang. */
+    execPath?: string;
+}
+export declare function installBrowser(options?: InstallOptions): {
+    ok: true;
+    extensionId: string;
+    extensionPath: string;
+    nativeHost: string;
+    nativeManifests: string[];
+    next: string;
+};
+export declare function browserStatus(options?: {
+    home?: string;
+    userDataDir?: string;
+}): {
+    ok: true;
+    extensionId: string;
+    extensionInstalled: boolean;
+    nativeHostInstalled: boolean;
+    manifests: {
+        path: string;
+        present: boolean;
+    }[];
+};
+//# sourceMappingURL=install.d.ts.map

package/dist/browser/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/browser/install.ts"],"names":[],"mappings":"AAgBA,wBAAgB,eAAe,CAAC,IAAI,SAAY,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAYhF;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,cAAmB;;;;;;;EAuC1D;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;;;;;EAclF"}

package/dist/browser/native.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=native.d.ts.map

package/dist/browser/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../src/browser/native.ts"],"names":[],"mappings":""}