@hasna/domains 0.0.47 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/domains
 
-Domain portfolio, registrar, marketplace, and DNS management for AI agents. The package ships a CLI, MCP server, authenticated HTTP API, generated SDK, and library exports. CLI workflows use local SQLite by default and can use the shared HTTP API in cloud mode; `domains-serve` connects directly to cloud Postgres.
+Domain portfolio, registrar, marketplace, and DNS management for AI agents. The package ships a CLI, MCP server, authenticated HTTP API, generated SDK, and library exports. Every client surface resolves its credential and authority through the one shared `@hasna/contracts` resolver (macOS Keychain, `~/.hasna/domains/config/credentials`, or `HASNA_DOMAINS_API_KEY`, with the fleet gateway `https://api.hasna.com/domains` as the default authority), and data commands fail closed when no credential resolves: local SQLite path settings are rejected; `domains-serve` connects directly to cloud Postgres.
 
 ## Features
 
@@ -33,7 +33,7 @@ Domain portfolio, registrar, marketplace, and DNS management for AI agents. The
 npm install -g @hasna/domains
 ```
 
-Data is stored in the local domains data directory. The home is resolved through `@hasna/paths` (XDG / macOS home layout, honoring `HASNA_*_HOME` overrides). The legacy `~/.hasna/domains` default stays the effective home until the XDG data home is adopted — the operator sets `HASNA_DATA_HOME`, or the store is physically migrated there (`domains.db` exists at the resolver home) — so an existing local store never becomes invisible on upgrade. `HASNA_DOMAINS_HOME` / `DOMAINS_HOME` / `HASNA_DOMAINS_DIR` / `DOMAINS_DIR` are exact-app overrides that win unconditionally; override the db file itself with `DOMAINS_DB_PATH` / `HASNA_DOMAINS_DB_PATH`.
+All normal clients use the shared account API. Saved credentials live in the macOS Keychain or `~/.hasna/domains/config/credentials`; `HASNA_HOME` and `HASNA_CONFIG_HOME` can select the credential root. Existing SQLite files are preserved for verified migration and are never opened by the CLI, MCP or SDK factory.
 
 ## Optional Command Groups
 
@@ -232,14 +232,21 @@ Route 53 sync imports registered domains when the selected AWS account permits `
 
 ## Storage
 
-The CLI and library use local SQLite by default. The client selects the hosted HTTP API when both `HASNA_DOMAINS_API_URL` and `HASNA_DOMAINS_API_KEY` are set — a database DSN is never exposed to clients.
+Every client surface — the CLI, the MCP server and the `./sdk` — resolves its credential and authority through the ONE shared `@hasna/contracts` resolver, fresh on every call:
 
-```bash
-export HASNA_DOMAINS_API_URL=https://domains.example.com
-export HASNA_DOMAINS_API_KEY=dom_...
-```
+1. an explicit `--api-key` / `--profile` argument (code-level)
+2. a deliberate env pointer — `HASNA_DOMAINS_API_KEY_OVERRIDE`, `HASNA_PROFILE`, `HASNA_DOMAINS_API_KEY_REF`
+3. the macOS Keychain — item `hasna.credentials.domains.api-key` / `.api-url`, account `HASNA_STATION`, else the short hostname, else `$USER`
+4. disk, read at call time — `~/.hasna/domains/config/credentials` (owner-only 0600; `HASNA_HOME` / `HASNA_CONFIG_HOME` override the root)
+5. `HASNA_DOMAINS_API_KEY` in the process env — a legitimate tier
+
+The authority follows the same ladder — `HASNA_DOMAINS_API_URL`, the Keychain `api-url` item, the credentials file — and **defaults to the fleet gateway `https://api.hasna.com/domains`** once a credential resolves, so a key alone is a complete configuration. The unprefixed `DOMAINS_API_URL` / `DOMAINS_API_KEY` aliases are accepted by the resolver for one release; the canonical `HASNA_DOMAINS_*` names always win. Retired locations (`~/.hasna/fleet-env`, the cloud dirs under `~/.hasna`, `~/.config/hasna`, `$XDG_CONFIG_HOME`) are never read, and no `*_MODE` / `*_STORAGE_MODE` variable selects anything.
 
-The unprefixed `DOMAINS_API_URL` and `DOMAINS_API_KEY` aliases are also accepted. When only one of URL and key is set, the client refuses to start (fail-closed). The standalone `domains-serve` process is the server side: it connects directly to PostgreSQL using `HASNA_DOMAINS_DATABASE_URL` (SQLite when unset) and requires `HASNA_DOMAINS_API_SIGNING_KEY`. Apply owner-role migrations first with `domains db migrate`.
+**Fail closed.** A hosted run with no credential exits non-zero naming the canonical env pair — never a silent fallback to SQLite, never a `*-local-fallback` event. A database DSN is never exposed to clients.
+
+**SQLite client selection is retired.** Unset `HASNA_DOMAINS_DB_PATH`, `DOMAINS_DB_PATH`, `HASNA_DOMAINS_DIR` and `DOMAINS_DIR` before using normal clients. These settings are rejected even when no API key is configured. Preserve existing databases until all records have been reconciled and verified in the shared account; removing a path setting does not migrate data.
+
+`domains serve` and `domains-serve` start the same authenticated PostgreSQL service. Both require a server database DSN (`HASNA_DOMAINS_DATABASE_URL`) and signing key (`HASNA_DOMAINS_API_SIGNING_KEY`); a client API key cannot authorize a listener. Data routes use `/v1` and validate each caller's key and revocation state. Apply owner-role migrations first with `domains db migrate`.
 
 ## MCP Server
 
@@ -297,10 +304,12 @@ Safe mode registers only read-only/list/check/export tools. Mutating tools such
 ```bash
 domains-serve --host 0.0.0.0 --port 8080
 curl http://127.0.0.1:8080/health
-curl -H "x-api-key: $DOMAINS_API_KEY" http://127.0.0.1:8080/v1/domains
+curl -H "x-api-key: $HASNA_DOMAINS_API_KEY" http://127.0.0.1:8080/v1/domains
 ```
 
-The package also exports the generated client:
+The package also exports the generated client, wired to the same shared
+resolver the CLI and MCP server use — fresh on every request, so a key rotation
+heals a long-lived client:
 
 ```ts
 import { createDomainsClientFromEnv } from "@hasna/domains/sdk";
@@ -309,25 +318,34 @@ const domains = createDomainsClientFromEnv();
 const portfolio = await domains.listDomains({ status: "active" });
 ```
 
-`domains serve` is a separate, unauthenticated local-development server over the local store. Use `domains-serve` for the cloud Postgres API.
+An explicit `baseUrl` with no `apiKey` builds a client pinned to that authority
+that never picks up an ambient fleet key; without a resolvable credential the
+SDK throws — it never degrades to an anonymous client or to local data.
+
+`domains serve` is an alias for the authenticated server runtime, preserving its CLI host/port defaults. Its account data routes are `/v1/*`; the former unauthenticated `/domains` proxy has been removed.
 
 ## Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `DOMAINS_DB_PATH` | Override database file path |
-| `HASNA_DOMAINS_DB_PATH` | Override database file path |
-| `DOMAINS_CONFIG_PATH` | Override config file path |
-| `DOMAINS_CONFIG_DIR` | Override config directory |
-| `HASNA_DOMAINS_DIR` | Override database directory |
-| `DOMAINS_DIR` | Override database directory fallback |
+| `HASNA_DOMAINS_API_KEY` | Hosted API key (canonical env tier of the shared resolver; below the Keychain and the credential file) |
+| `HASNA_DOMAINS_API_URL` | Optional hosted API base URL — defaults to the fleet gateway `https://api.hasna.com/domains` once a key resolves |
+| `HASNA_DOMAINS_API_KEY_OVERRIDE` | Deliberate per-run key override that outranks every other tier |
+| `HASNA_DOMAINS_API_KEY_REF` | Deliberate secrets-vault pointer resolved through the `@hasna/secrets` SDK at request time |
+| `HASNA_PROFILE` | Global identity profile pointer (`credentials-<profile>` beside the credential file) |
+| `HASNA_HOME` | Shared root override — `<HASNA_HOME>/domains/` for local data, `<HASNA_HOME>/domains/config/credentials` for the credential file |
+| `HASNA_CONFIG_HOME` | Config-root override for the resolver's credential file |
+| `HASNA_DOMAINS_DB_PATH` | Retired client setting; migrate and verify existing data before removal |
+| `DOMAINS_DB_PATH` | Retired legacy client setting; rejected |
+| `HASNA_DOMAINS_DIR` | Retired client setting; rejected |
+| `DOMAINS_DIR` | Retired legacy client setting; rejected |
+| `HASNA_DOMAINS_HOME`, `DOMAINS_HOME` | Exact-app home overrides (canonical name wins over the alias) |
+| `HASNA_DOMAINS_CONFIG_PATH`, `DOMAINS_CONFIG_PATH` | Override the settings config file path |
+| `DOMAINS_CONFIG_DIR` | Override the settings config directory |
 | `DOMAINS_COMMAND_GROUPS` | Comma-separated optional command groups to load, or `all` |
 | `DOMAINS_ENABLE_EXTRAS` | Set to `1` to load all optional command groups |
 | `DOMAINS_MCP_SAFE_MODE` | Set to `1` to expose only read-only MCP tools |
-| `HASNA_DOMAINS_API_URL`, `DOMAINS_API_URL` | Hosted HTTP API base URL for the CLI/library store (set together with the key) |
-| `HASNA_DOMAINS_API_KEY`, `DOMAINS_API_KEY` | Hosted HTTP API key for the CLI/library store and SDK (set together with the URL) |
-| `HASNA_DOMAINS_ALLOW_CLOUD_WITH_LOCAL_PATH` | Set to `1` to keep the hosted store even though a local path variable is set. Without it that combination is a hard error — see below |
-| `HASNA_DOMAINS_DATABASE_URL` | Server-side PostgreSQL DSN used by `domains-serve` and DB migrations; SQLite backend when unset |
+| `HASNA_DOMAINS_DATABASE_URL` | Server-side PostgreSQL DSN used by `domains-serve` and DB migrations; required for server storage |
 | `HASNA_DOMAINS_API_SIGNING_KEY` | HMAC signing secret used by `domains-serve` to verify API keys |
 | `AWS_PROFILE` | AWS profile for Route 53 Domains and hosted zones |
 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | AWS credential fallback |
@@ -344,27 +362,33 @@ const portfolio = await domains.listDomains({ status: "active" });
 | `BRANDSIGHT_DEMO_STUBS`, `BRANDSIGHT_ALLOW_STUBS` | Set either to `1` to allow demo stub responses when the Brandsight API is unreachable |
 | `SEDO_PARTNER_ID`, `SEDO_API_KEY`, `SEDO_USERNAME`, `SEDO_PASSWORD` | Sedo marketplace API credentials |
 
-### Picking a store: a local path and cloud credentials are mutually exclusive
+### Picking a store: a local path and a configured credential are mutually exclusive
 
-`DOMAINS_DB_PATH`, `HASNA_DOMAINS_DB_PATH`, `DOMAINS_DIR` and `HASNA_DOMAINS_DIR` all name a
-**local sqlite file**. Only the local store has one. So setting any of them while
-`HASNA_DOMAINS_API_URL` + `HASNA_DOMAINS_API_KEY` are also set asks for two different stores at
-once, and `getStore()` **refuses to start** rather than pick one for you.
+`HASNA_DOMAINS_DB_PATH`, `DOMAINS_DB_PATH`, `HASNA_DOMAINS_DIR`, `DOMAINS_DIR` and
+`HASNA_DOMAINS_HOME` all name a **local sqlite file or directory**. Only the local store
+has one. So setting any of them while the environment also configures a hosted
+authority or credential (`HASNA_DOMAINS_API_URL`, `HASNA_DOMAINS_API_KEY`, the
+deliberate pointers, `HASNA_PROFILE`, or a Keychain / credential-file entry)
+asks for two different stores at once, and **`getStore()` refuses to start**
+rather than pick one for you. Local mode applies only when the environment
+configures nothing at all.
 
-This is deliberate. Before it, the combination silently resolved to the cloud store: a script
-that set `DOMAINS_DB_PATH` created no sqlite file, wrote to the remote portfolio, and printed
-success. Nothing on any surface said which store it had used.
+This is deliberate. Before it, the combination silently resolved to the cloud
+store: a script that set `DOMAINS_DB_PATH` created no sqlite file, wrote to the
+remote portfolio, and printed success. Nothing on any surface said which store
+it had used.
 
 To resolve it, say which you meant:
 
 ```sh
-unset HASNA_DOMAINS_API_URL HASNA_DOMAINS_API_KEY   # use the sqlite file the path variable names
-unset DOMAINS_DB_PATH                                # use the hosted store
-HASNA_DOMAINS_ALLOW_CLOUD_WITH_LOCAL_PATH=1          # keep the hosted store with the variable present
+unset HASNA_DOMAINS_DB_PATH DOMAINS_DB_PATH HASNA_DOMAINS_DIR DOMAINS_DIR HASNA_DOMAINS_HOME   # use the hosted store
+unset HASNA_DOMAINS_API_URL HASNA_DOMAINS_API_KEY HASNA_DOMAINS_API_KEY_OVERRIDE HASNA_DOMAINS_API_KEY_REF HASNA_PROFILE   # use the sqlite file the path variable names
 ```
 
-`domains doctor` names the store it resolved, in its `Store` section, before any other check
-runs. Run it whenever you are unsure which dataset a command is about to touch.
+`domains doctor` names the store it resolved, in its `Store` section — including
+where the URL and key came from and which tier supplied the key — before any
+other check runs. Run it whenever you are unsure which dataset a command is
+about to touch.
 
 ## License
 

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

@@ -1 +1 @@
-{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAa1E,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,aAA4D,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACjE,OAAO,EAAE,CAAC,EAAE,GACX;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAW7C;AAyBD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAA;CAAO,GAC5D,IAAI,CAsYN"}
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAa1E,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,aAA4D,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACjE,OAAO,EAAE,CAAC,EAAE,GACX;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAW7C;AAyBD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAA;CAAO,GAC5D,IAAI,CA4ZN"}

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2I5D"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuI5D"}

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

@@ -1,3 +1,4 @@
 import type { Command } from "commander";
+/** Run the canonical authenticated service, never an account-key proxy. */
 export declare function registerServeCommand(program: Command): void;
 //# sourceMappingURL=serve.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuG3D"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAS3D"}