@hasna/contacts 0.6.36 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/contacts
 
-Contact management for AI coding agents — CLI + MCP + Web
+Contact management for AI coding agents — CLI + MCP + authenticated HTTP API
 
 [![npm](https://img.shields.io/npm/v/@hasna/contacts)](https://www.npmjs.com/package/@hasna/contacts)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -11,12 +11,92 @@ Contact management for AI coding agents — CLI + MCP + Web
 npm install -g @hasna/contacts
 ```
 
+## Configure the client
+
+Every CLI, MCP, and package data operation uses one authenticated HTTPS `/v1`
+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"
+export HASNA_CONTACTS_API_KEY="…"     # or configure the Keychain/disk tiers
+contacts connection --json
+```
+
+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, resolved /v1 authority + sources, storage mode, record counts
+contacts status --json
 contacts --help
 ```
 
+`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
 
 Audience segments implement the `hasna.audience.v1` contract (distribution
@@ -50,6 +130,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):
@@ -63,7 +159,7 @@ MCP_HTTP=1 contacts-mcp
 - Health: `GET http://127.0.0.1:8809/health`
 - MCP: `http://127.0.0.1:8809/mcp`
 
-The REST server (`contacts-serve`) also exposes `/health` and `/mcp` when running.
+The REST server is a separate authenticated `/v1` surface.
 
 ## REST API
 
@@ -72,83 +168,41 @@ contacts-serve
 ```
 
 `contacts-serve` binds to `127.0.0.1` by default. Use `--host <host>` or
-`CONTACTS_HOST=<host>` only when intentionally exposing it beyond loopback.
-Shared binds still fail closed unless a valid contacts token is configured and
-sent with the request. The unauthenticated local development fallback is disabled
-by default and only activates when all of the following are true:
-
-- no contacts API token environment variable is configured
-- `CONTACTS_ALLOW_UNAUTHENTICATED_LOOPBACK=1`
-- the server is explicitly bound to a loopback host
-
-The fallback does not trust the HTTP `Host` header.
+`CONTACTS_HOST=<host>` only when intentionally exposing it beyond loopback. The
+server requires PostgreSQL configuration and API-key signing configuration;
+readiness fails closed when either is unavailable.
 
-## Storage
+## Storage and legacy data
 
-Contacts owns its local SQLite storage directly. It does not depend on shared
-cloud runtime commands or MCP tools.
+The client never opens SQLite or PostgreSQL. The server owns PostgreSQL and all
+authoritative data remains server-side. Inspect the value-free connection state
+with:
 
 ```bash
-contacts storage status
-contacts storage status --json
-contacts storage push --tables contacts,companies
-contacts storage pull --tables contacts,companies
-contacts storage sync
+contacts connection --json
 ```
 
-Optional cross-machine sync uses contacts-owned PostgreSQL storage. Set one of:
+Retired local databases are never auto-adopted or silently ignored. The
+explicit migration aid only inspects and copies them; it never opens, changes,
+deletes, or selects one as the live store:
 
 ```bash
-export HASNA_CONTACTS_POSTGRES_URL="postgres://..."
-# or OPEN_CONTACTS_POSTGRES_URL / CONTACTS_POSTGRES_URL
+contacts legacy inspect --json
+contacts legacy preserve --source /exact/path/contacts.db \
+  --output /existing/directory/contacts.db.pre-https.20260901
 ```
 
-Remote PostgreSQL connections require verified TLS for non-local hosts. Local
-PostgreSQL development URLs can disable TLS explicitly.
-
-By default, remote sync covers contacts, companies, tags, and the other
-non-sensitive relationship tables. `webhooks`, `contact_documents`, and
-`contact_health` are excluded until explicitly requested with `--tables` and
-`HASNA_CONTACTS_ALLOW_SENSITIVE_SYNC=1`. Sync inserts or updates rows with
-timestamp conflict protection. Deletes for `contacts`, `companies`, and `tags`
-write `_contacts_tombstones`; push/pull sync carries those tombstones and pull
-applies them unless the local row has a newer `updated_at`.
-
-Shared REST/dashboard deployments must set one of
-`HASNA_CONTACTS_API_TOKENS`, `OPEN_CONTACTS_API_TOKENS`, or
-`CONTACTS_API_TOKENS`. Values are comma-separated `token=scope scope` records.
-Supported scopes include `contacts:read`, `contacts:write`,
-`contacts:import`, `contacts:export`, `contacts:export:full`,
-`documents:read`, `images:read`, `images:write`, `companies:*`, `tags:*`,
-`stats:read`, `dashboard:read`, and `mcp:access`. Loopback-only development
-without configured tokens remains allowed; shared hosts fail closed.
-
-Server exports are redacted by default: email addresses, phone numbers,
-addresses, notes, birthdays, social profiles, and custom fields are withheld.
-Full exports require both `contacts:export` and `contacts:export:full`. Export,
-import, document file read, image mutation, contact mutation, company mutation,
-and tag mutation routes write audit entries. Document attachments are served
-only from the managed contacts documents directory and use private `no-store`
-cache headers.
-
-`contacts cloud status`, `contacts cloud push`, `contacts cloud pull`, and
-`contacts cloud sync` remain compatibility aliases for the contacts-owned
-storage commands. They do not load or depend on the deprecated shared cloud
-runtime. `contacts cloud feedback` saves feedback locally in the contacts
-database.
-
-## Data Directory
-
-On-box data resolves through the XDG dirs per `@hasna/paths`:
-
-- documents, the SQLite store, `config.json` and the vault config live in the
-  **XDG data root**: `~/.local/share/hasna/contacts/` (or `$HASNA_DATA_HOME/contacts`).
-- the vault session state lives in the **XDG state root**:
-  `~/.local/state/hasna/contacts/` (or `$HASNA_STATE_HOME/contacts`).
-
-The legacy `~/.hasna/contacts/` home is never written to; on first use any
-pre-existing legacy store is adopted into the XDG roots (never clobbering an
-existing XDG store).
+If a SQLite WAL, journal, or shared-memory sidecar is present, preservation
+refuses to proceed until every legacy process is stopped and the old client has checkpointed the database. To move
+portable contact records, use a legacy release against the preserved copy to
+export JSON, then run `contacts import exported.json` with the HTTPS client
+configured. Existing files are never overwritten.
+
+Preservation rejects source, ancestor, or output replacement races and verifies
+the copied bytes with SHA-256 and stable output metadata before success. If a copy
+fails after output creation, any private partial output is left untouched and
+reported as unverified for manual inspection; the command never deletes a
+pathname that another process might have replaced.
 
 ## License
 

package/dist/cli/commands/advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAs5B/D"}
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/advanced.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAq5B/D"}

package/dist/cli/commands/core.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from "commander";
-export declare function registerCoreCommands(program: Command): void;
+export declare function registerCoreCommands(program: Command, version: string): void;
 //# sourceMappingURL=core.d.ts.map

package/dist/cli/commands/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA87B3D"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/core.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAu5B5E"}

package/dist/cli/commands/crm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAm+B1D"}
+{"version":3,"file":"crm.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/crm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAi+B1D"}