@newtype-ai/nit-sdk 0.3.2 → 0.4.0

package/README.md

@@ -11,11 +11,12 @@ npm install @newtype-ai/nit-sdk
 ## Usage
 
 ```typescript
-import { verifyAgent } from '@newtype-ai/nit-sdk';
+import { verifyAgent, NitSdkError } from '@newtype-ai/nit-sdk';
 
 // The agent sends you a login payload (generated by `nit sign --login your-app.com`)
 const result = await verifyAgent(payload, {
-  policy: { max_identities_per_machine: 10, min_age_seconds: 3600 }
+  policy: { max_identities_per_machine: 10, min_age_seconds: 3600 },
+  timeoutMs: 5_000, // optional, default 10s
 });
 
 if (result.verified && result.admitted) {
@@ -50,6 +51,7 @@ The server acts as an **identity registry** — it stores identity metadata, eva
 | `payload` | `LoginPayload` | `{ agent_id, domain, timestamp, signature }` from the agent |
 | `options.apiUrl` | `string` | Override API URL (default: `https://api.newtype-ai.org`) |
 | `options.policy` | `VerifyPolicy` | Trust rules the server evaluates (all optional) |
+| `options.timeoutMs` | `number` | Fetch timeout in milliseconds (default: `10000`) |
 
 **Policy fields:**
 
@@ -74,6 +76,42 @@ The server acts as an **identity registry** — it stores identity metadata, eva
 | `identity` | `IdentityMetadata` | Registration time, machine/IP counts, login history |
 | `attestation` | `ServerAttestation` | Server's Ed25519 signature over the result |
 
+### `NitSdkError`
+
+Typed error thrown by `fetchAgentCard()` on non-404 HTTP failures and malformed responses.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message` | `string` | Human-readable error description |
+| `status` | `number` | HTTP status code (0 for shape validation failures) |
+
+```typescript
+import { fetchAgentCard, NitSdkError } from '@newtype-ai/nit-sdk';
+
+try {
+  const card = await fetchAgentCard(agentId, 'your-app.com', readToken);
+} catch (err) {
+  if (err instanceof NitSdkError) {
+    console.error(`SDK error (HTTP ${err.status}): ${err.message}`);
+  }
+}
+```
+
+### `fetchAgentCard(agentId, domain, readToken, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options.baseUrl` | `string` | Override card hosting URL (default: `https://agent-{id}.newtype-ai.org`) |
+| `options.timeoutMs` | `number` | Fetch timeout in milliseconds (default: `10000`) |
+
+Returns `Promise<AgentCard | null>` — `null` for 404, throws `NitSdkError` for other HTTP errors.
+
+## Security
+
+- **HTTPS enforcement:** Custom `apiUrl` and `baseUrl` must use `https://`. Localhost (`127.0.0.1`, `localhost`) is exempt for development. Non-HTTPS URLs throw `TypeError`.
+- **Input validation:** `verifyAgent` validates the payload before sending: `agent_id` must be a valid UUID, `domain` must be non-empty (max 253 chars), `timestamp` must be a finite positive number, `signature` must be non-empty.
+- **Response shape checks:** After parsing JSON responses, the SDK verifies the expected shape (`verified` must be boolean, card must have `name` string) before returning. Malformed responses are returned as `{ verified: false, error: '...' }`.
+
 ## Full Integration Guide
 
 See [docs/app-integration.md](docs/app-integration.md) for the complete flow, endpoint spec, code examples in multiple languages, fetching updated cards, and security notes.

package/dist/index.d.ts

@@ -4,6 +4,11 @@
  * Apps receive a login payload from an agent (via nit) and call
  * verifyAgent() to confirm the agent's identity. No crypto needed.
  */
+/** Typed error for HTTP and shape failures in the SDK. */
+declare class NitSdkError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 /** The login payload an agent sends to your app. */
 interface LoginPayload {
     agent_id: string;
@@ -100,10 +105,14 @@ interface VerifyOptions {
     apiUrl?: string;
     /** App-defined trust policy. Server evaluates and returns admitted: true/false. */
     policy?: VerifyPolicy;
+    /** Fetch timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
 }
 interface FetchCardOptions {
     /** Override the base URL for agent card hosting. Defaults to https://agent-{agent_id}.newtype-ai.org */
     baseUrl?: string;
+    /** Fetch timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
 }
 /**
  * Verify an agent's login payload against the newtype-ai.org server.
@@ -139,4 +148,4 @@ declare function verifyAgent(payload: LoginPayload, options?: VerifyOptions): Pr
  */
 declare function fetchAgentCard(agentId: string, domain: string, readToken: string, options?: FetchCardOptions): Promise<AgentCard | null>;
 
-export { type AgentCard, type AgentCardSkill, type FetchCardOptions, type IdentityMetadata, type LoginPayload, type ServerAttestation, type VerifyFailure, type VerifyOptions, type VerifyPolicy, type VerifyResult, type VerifySuccess, fetchAgentCard, verifyAgent };
+export { type AgentCard, type AgentCardSkill, type FetchCardOptions, type IdentityMetadata, type LoginPayload, NitSdkError, type ServerAttestation, type VerifyFailure, type VerifyOptions, type VerifyPolicy, type VerifyResult, type VerifySuccess, fetchAgentCard, verifyAgent };

package/dist/index.js

@@ -1,30 +1,107 @@
 // src/index.ts
+var NitSdkError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "NitSdkError";
+  }
+};
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function assertHttps(url, label) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "https:") return;
+    if (parsed.protocol === "http:" && (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1"))
+      return;
+    throw new TypeError(
+      `${label} must use HTTPS (got ${parsed.protocol}//${parsed.hostname})`
+    );
+  } catch (e) {
+    if (e instanceof TypeError) throw e;
+    throw new TypeError(`${label} is not a valid URL: ${url}`);
+  }
+}
+function validatePayload(payload) {
+  if (typeof payload.agent_id !== "string" || !UUID_RE.test(payload.agent_id)) {
+    throw new TypeError(
+      "payload.agent_id must be a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)"
+    );
+  }
+  if (typeof payload.domain !== "string" || payload.domain.length === 0 || payload.domain.length > 253) {
+    throw new TypeError(
+      "payload.domain must be a non-empty string (max 253 chars)"
+    );
+  }
+  if (typeof payload.timestamp !== "number" || !Number.isFinite(payload.timestamp) || payload.timestamp <= 0) {
+    throw new TypeError("payload.timestamp must be a finite positive number");
+  }
+  if (typeof payload.signature !== "string" || payload.signature.length === 0) {
+    throw new TypeError("payload.signature must be a non-empty string");
+  }
+}
+function fetchWithTimeout(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return fetch(url, { ...init, signal: controller.signal }).finally(
+    () => clearTimeout(timer)
+  );
+}
 var DEFAULT_API_URL = "https://api.newtype-ai.org";
 async function verifyAgent(payload, options) {
+  validatePayload(payload);
   const apiUrl = options?.apiUrl ?? DEFAULT_API_URL;
-  const res = await fetch(`${apiUrl}/agent-card/verify`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      agent_id: payload.agent_id,
-      domain: payload.domain,
-      timestamp: payload.timestamp,
-      signature: payload.signature,
-      ...options?.policy ? { policy: options.policy } : {}
-    })
-  });
-  return res.json();
+  if (options?.apiUrl) assertHttps(apiUrl, "options.apiUrl");
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const res = await fetchWithTimeout(
+    `${apiUrl}/agent-card/verify`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        agent_id: payload.agent_id,
+        domain: payload.domain,
+        timestamp: payload.timestamp,
+        signature: payload.signature,
+        ...options?.policy ? { policy: options.policy } : {}
+      })
+    },
+    timeoutMs
+  );
+  if (!res.ok) {
+    return { verified: false, error: `Server error (HTTP ${res.status})` };
+  }
+  const data = await res.json();
+  if (typeof data !== "object" || data === null || typeof data.verified !== "boolean") {
+    return { verified: false, error: "Malformed server response (missing verified field)" };
+  }
+  return data;
 }
 async function fetchAgentCard(agentId, domain, readToken, options) {
   const baseUrl = options?.baseUrl ?? `https://agent-${agentId}.newtype-ai.org`;
+  if (options?.baseUrl) assertHttps(baseUrl, "options.baseUrl");
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const url = `${baseUrl}/.well-known/agent-card.json?branch=${encodeURIComponent(domain)}`;
-  const res = await fetch(url, {
-    headers: { Authorization: `Bearer ${readToken}` }
-  });
-  if (!res.ok) return null;
-  return res.json();
+  const res = await fetchWithTimeout(
+    url,
+    { headers: { Authorization: `Bearer ${readToken}` } },
+    timeoutMs
+  );
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new NitSdkError(
+      `Failed to fetch agent card (HTTP ${res.status})`,
+      res.status
+    );
+  }
+  const data = await res.json();
+  if (typeof data !== "object" || data === null || typeof data.name !== "string") {
+    throw new NitSdkError("Malformed agent card response (missing name field)", 0);
+  }
+  return data;
 }
 export {
+  NitSdkError,
   fetchAgentCard,
   verifyAgent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newtype-ai/nit-sdk",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Verify agent identity with one function call",
   "type": "module",
   "license": "MIT",