@hasna/contacts 0.7.0 → 0.8.1

package/dist/mcp/startup-gate.d.ts

@@ -0,0 +1,48 @@
+import { type CredentialChainOptions, type ResolvedCredential } from "@hasna/contracts/client";
+import { type Env } from "../cloud/resolver-inputs.js";
+/**
+ * The fail-closed startup gate for `contacts-mcp` (hasna/apps#1720 validation,
+ * round 2).
+ *
+ * A hosted-only client with no credential must fail LOUD before it serves:
+ * non-zero exit before the stdio transport is connected or the HTTP port is
+ * bound, so an agent that registered `contacts-mcp` on a station without the
+ * fleet credential sees the refusal at startup instead of an `initialize`
+ * answered by a server whose every tool call would fail. Previously main()
+ * built the server and connected the transport without ever resolving the
+ * credential: the negative control (empty HASNA_HOME, absent Keychain
+ * account, no env key) printed "running on stdio", answered `initialize`,
+ * and exited 0.
+ *
+ * The gate is ONE pass down the same @hasna/contracts chain the tools resolve
+ * through per call (`resolveContactsClientTransport`): the live process
+ * environment keeps its ambient Keychain/disk tiers, a caller-built env is the
+ * hermetic seam. A DELIBERATE tier that cannot produce a key is a refusal,
+ * never resolved around: `HASNA_PROFILE` naming a missing profile file, an
+ * unsafe credentials file, a Keychain item that exists but cannot be read, and
+ * the secrets-vault pointer `HASNA_CONTACTS_API_KEY_REF`. The chain validates
+ * only the pointer's SHAPE, so the gate dereferences it once through the vault
+ * exactly as the transport does at request time; a pointer that cannot be
+ * completed (SDK absent, vault unconfigured or unreachable, item missing or
+ * empty) refuses the start instead of answering `initialize` with a server
+ * whose every call would fail.
+ *
+ * Nothing here opens, reads or creates a local store, and the message names
+ * WHERE the credential should live (an item reference, a file path, an env key
+ * name) — never a value. A dereferenced key is dropped on the spot: every tool
+ * still re-resolves per call.
+ */
+export type McpStartupGate = {
+    ok: true;
+    apiUrlSource: string | null;
+    apiKeySource: string | null;
+} | {
+    ok: false;
+    message: string;
+};
+/** The vault dereference, injectable so the pointer path is testable without a vault. */
+export interface McpStartupGateOptions {
+    completePointer?: (name: string, pointer: ResolvedCredential, env: Env) => Promise<ResolvedCredential>;
+}
+export declare function resolveMcpStartupGate(env?: Env, credentials?: CredentialChainOptions, options?: McpStartupGateOptions): Promise<McpStartupGate>;
+//# sourceMappingURL=startup-gate.d.ts.map

package/dist/mcp/startup-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-gate.d.ts","sourceRoot":"","sources":["../../src/mcp/startup-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAA+B,KAAK,GAAG,EAAE,MAAM,6BAA6B,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACtE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACxG;AAOD,wBAAsB,qBAAqB,CACzC,GAAG,GAAE,GAAiB,EACtB,WAAW,GAAE,sBAA2B,EACxC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,cAAc,CAAC,CAmCzB"}

package/dist/sdk/index.d.ts

@@ -1,10 +1,37 @@
-/** @hasna/contacts SDK — explicit authenticated HTTPS `/v1` client. */
+/**
+ * @hasna/contacts SDK — the hosted `/v1` client surface.
+ *
+ * Two constructors, one rule (hasna/apps#1720, #1794):
+ *
+ * - `new ContactsV1Client({ baseUrl, apiKey })` is the EXPLICIT pin: a
+ *   caller-supplied authority is a deliberate selection, it always requires a
+ *   caller-supplied key, and the ambient fleet credential is never attached to
+ *   it.
+ * - `createContactsClient()` goes through the ONE fleet resolver in
+ *   `@hasna/contracts/client`, exactly like the CLI and the MCP server: the
+ *   credential comes from an explicit argument, the deliberate env pointers
+ *   (`HASNA_CONTACTS_API_KEY_OVERRIDE`, `HASNA_PROFILE`,
+ *   `HASNA_CONTACTS_API_KEY_REF`), the macOS Keychain item
+ *   `hasna.credentials.contacts.api-key`, `~/.hasna/contacts/config/credentials`
+ *   (owner-only 0400/0600), then `HASNA_CONTACTS_API_KEY`; the authority follows
+ *   `HASNA_CONTACTS_API_URL`, the Keychain `api-url` item, the credentials
+ *   file, and defaults to the fleet gateway `https://api.hasna.com/contacts`
+ *   once a credential resolves. The KEY is re-resolved on every request (a
+ *   rotation heals a long-lived agent); the AUTHORITY is pinned for the life
+ *   of the client, so a credential written for one service is never sent to
+ *   another. Nothing resolving THROWS — there is no local fallback and no
+ *   unauthenticated client.
+ */
+import { type KeychainTierOptions } from "@hasna/contracts/client";
+import { ContactsClientConfigurationError } from "../cloud/http-storage.js";
+import { type Env } from "../cloud/resolver-inputs.js";
 import { ContactsV1Client as GeneratedContactsV1Client, ApiError, type ContactsV1ClientOptions as GeneratedContactsV1ClientOptions } from "./v1.generated.js";
 export interface ContactsV1ClientOptions extends Omit<GeneratedContactsV1ClientOptions, "baseUrl" | "apiKey"> {
     /** Explicit HTTPS service authority. No default is composed. */
     baseUrl: string;
-    /** API key sent to the configured authority. Required and never logged. */
-    apiKey: string;
+    /** API key sent to the configured authority. Required and never logged.
+     * An explicit baseUrl never falls back to an ambient fleet key (#1794). */
+    apiKey?: string;
 }
 /**
  * Validated wrapper around the generated API surface. Redirects are never
@@ -13,6 +40,46 @@ export interface ContactsV1ClientOptions extends Omit<GeneratedContactsV1ClientO
 export declare class ContactsV1Client extends GeneratedContactsV1Client {
     constructor(options: ContactsV1ClientOptions);
 }
+/** The app slug the shared client seam resolves credentials and authority for. */
+export declare const CONTACTS_APP_NAME: "contacts";
+/** Options for {@link createContactsClient}. */
+export interface CreateContactsClientOptions extends Omit<GeneratedContactsV1ClientOptions, "baseUrl" | "apiKey"> {
+    /**
+     * Explicit HTTPS authority — a deliberate pin. Requires `apiKey`; the ambient
+     * chain is never consulted on its behalf (#1794).
+     */
+    baseUrl?: string;
+    /**
+     * Explicit API key (tier 1). With `baseUrl` it is the whole configuration;
+     * alone, the authority still resolves through the chain.
+     */
+    apiKey?: string;
+    /** The environment to resolve through instead of `process.env` — the hermetic seam. */
+    env?: Env;
+    /** Tier-1 identity selection (`--profile`), passed through to the chain. */
+    profile?: string;
+    /**
+     * Tier-3 controls: a fake `security` runner in tests, an opt-out on a CI
+     * Mac. Production callers pass nothing — the tier is ambient for
+     * `process.env` and off for a caller-built env.
+     */
+    keychain?: KeychainTierOptions;
+}
+/** The SDK's refusal for an explicit authority without an explicit key (#1794). */
+export declare function contactsSdkAuthorityPinMessage(): string;
+/**
+ * Build a ContactsV1Client through the fleet resolver.
+ *
+ * - explicit `baseUrl` + `apiKey` → a deliberate pin, used verbatim; the
+ *   ambient chain is never consulted (hasna/apps#1794).
+ * - explicit `baseUrl` without `apiKey` → throws (no ambient key attach).
+ * - otherwise the @hasna/contracts chain resolves credential + authority, and
+ *   every request re-resolves the KEY on a fresh snapshot while the AUTHORITY
+ *   stays pinned (a changed authority is a new client, never a key sent to the
+ *   wrong server). Any refusal throws — there is no local fallback.
+ */
+export declare function createContactsClient(options?: CreateContactsClientOptions): ContactsV1Client;
+export { ContactsClientConfigurationError };
 export { ApiError as ContactsV1ApiError };
 export type { Contact as ContactsV1Contact, Company as ContactsV1Company, Tag as ContactsV1Tag, CreateContactInput as ContactsV1CreateContactInput, UpdateContactInput as ContactsV1UpdateContactInput, CreateCompanyInput as ContactsV1CreateCompanyInput, UpdateCompanyInput as ContactsV1UpdateCompanyInput, CreateTagInput as ContactsV1CreateTagInput, UpdateTagInput as ContactsV1UpdateTagInput, ProjectIdsInput as ContactsV1ProjectIdsInput, ContactProjectMembershipSnapshot as ContactsV1ProjectMembershipSnapshot, ContactProjectMembershipMutationInput as ContactsV1ProjectMembershipMutationInput, ContactProjectMembershipMutationResult as ContactsV1ProjectMembershipMutationResult, ContactProjectMembershipListResult as ContactsV1ProjectMembershipListResult, } from "./v1.generated.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,OAAO,EACL,gBAAgB,IAAI,yBAAyB,EAC7C,QAAQ,EACR,KAAK,uBAAuB,IAAI,gCAAgC,EACjE,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBACf,SAAQ,IAAI,CAAC,gCAAgC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpE,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AA8BD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,yBAAyB;gBACjD,OAAO,EAAE,uBAAuB;CAS7C;AAED,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,CAAC;AAC1C,YAAY,EACV,OAAO,IAAI,iBAAiB,EAC5B,OAAO,IAAI,iBAAiB,EAC5B,GAAG,IAAI,aAAa,EACpB,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,cAAc,IAAI,wBAAwB,EAC1C,cAAc,IAAI,wBAAwB,EAC1C,eAAe,IAAI,yBAAyB,EAC5C,gCAAgC,IAAI,mCAAmC,EACvE,qCAAqC,IAAI,wCAAwC,EACjF,sCAAsC,IAAI,yCAAyC,EACnF,kCAAkC,IAAI,qCAAqC,GAC5E,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAkD,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnH,OAAO,EAAE,gCAAgC,EAAkC,MAAM,0BAA0B,CAAC;AAC5G,OAAO,EAA+B,KAAK,GAAG,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EACL,gBAAgB,IAAI,yBAAyB,EAC7C,QAAQ,EACR,KAAK,uBAAuB,IAAI,gCAAgC,EACjE,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,uBACf,SAAQ,IAAI,CAAC,gCAAgC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpE,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB;+EAC2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4BD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,yBAAyB;gBACjD,OAAO,EAAE,uBAAuB;CAS7C;AAED,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,EAAG,UAAmB,CAAC;AAErD,gDAAgD;AAChD,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,gCAAgC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpE;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,IAAI,MAAM,CAMvD;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,gBAAgB,CAiDhG;AAED,OAAO,EAAE,gCAAgC,EAAE,CAAC;AAC5C,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,CAAC;AAC1C,YAAY,EACV,OAAO,IAAI,iBAAiB,EAC5B,OAAO,IAAI,iBAAiB,EAC5B,GAAG,IAAI,aAAa,EACpB,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,kBAAkB,IAAI,4BAA4B,EAClD,cAAc,IAAI,wBAAwB,EAC1C,cAAc,IAAI,wBAAwB,EAC1C,eAAe,IAAI,yBAAyB,EAC5C,gCAAgC,IAAI,mCAAmC,EACvE,qCAAqC,IAAI,wCAAwC,EACjF,sCAAsC,IAAI,yCAAyC,EACnF,kCAAkC,IAAI,qCAAqC,GAC5E,MAAM,mBAAmB,CAAC"}