@newtype-ai/nit-sdk 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 newtype-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @newtype-ai/nit-sdk
+
+Verify AI agent identity with one function call. No crypto, no OAuth, no secrets needed.
+
+## Install
+
+```bash
+npm install @newtype-ai/nit-sdk
+```
+
+## Usage
+
+```typescript
+import { verifyAgent } 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);
+
+if (result.verified) {
+  // result.agent_id — the agent's permanent UUID
+  // result.card — the agent's public profile (name, skills, etc.)
+  // result.solanaAddress — the agent's Solana wallet address
+  console.log(`Welcome, ${result.card?.name}`);
+} else {
+  console.log(`Verification failed: ${result.error}`);
+}
+```
+
+## How It Works
+
+1. The agent runs `nit sign --login your-app.com` to generate a signed login payload
+2. The agent sends the payload to your app
+3. Your app calls `verifyAgent(payload)` — this hits `api.newtype-ai.org/agent-card/verify`
+4. You get back `{ verified: true, agent_id, card }` or `{ verified: false, error }`
+
+That's it. The server verifies the Ed25519 signature against the agent's registered public key.
+
+## API
+
+### `verifyAgent(payload, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `payload` | `LoginPayload` | `{ agent_id, domain, timestamp, signature }` from the agent |
+| `options.apiUrl` | `string` | Override API URL (default: `https://api.newtype-ai.org`) |
+
+Returns `Promise<VerifyResult>` — either `{ verified: true, agent_id, domain, card, solanaAddress }` or `{ verified: false, error }`.
+
+## Full Integration Guide
+
+See [app-integration.md](https://github.com/newtype-ai/newtype-ai/blob/main/docs/app-integration.md) for the complete flow, endpoint spec, and examples in multiple languages.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @newtype-ai/nit-sdk — Verify agent identity with one function call.
+ *
+ * Apps receive a login payload from an agent (via nit) and call
+ * verifyAgent() to confirm the agent's identity. No crypto needed.
+ */
+/** The login payload an agent sends to your app. */
+interface LoginPayload {
+    agent_id: string;
+    domain: string;
+    timestamp: number;
+    signature: string;
+}
+/** A skill listed in an agent's card. */
+interface AgentCardSkill {
+    id: string;
+    name?: string;
+    description?: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+/** The agent's public identity card (A2A-compliant). */
+interface AgentCard {
+    protocolVersion: string;
+    name: string;
+    description: string;
+    version: string;
+    url: string;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    skills: AgentCardSkill[];
+    publicKey?: string;
+    iconUrl?: string;
+    documentationUrl?: string;
+}
+/** Successful verification result. */
+interface VerifySuccess {
+    verified: true;
+    agent_id: string;
+    domain: string;
+    card: AgentCard | null;
+    /** Which branch the card came from — the domain branch if pushed, otherwise 'main'. */
+    branch: string;
+    /** Solana wallet address derived from the agent's Ed25519 public key. */
+    solanaAddress?: string;
+    /** HMAC-signed read token for fetching the agent's domain branch card. 30-day expiry. */
+    readToken: string;
+}
+/** Failed verification result. */
+interface VerifyFailure {
+    verified: false;
+    error: string;
+}
+type VerifyResult = VerifySuccess | VerifyFailure;
+interface VerifyOptions {
+    /** Override the API base URL. Defaults to https://api.newtype-ai.org */
+    apiUrl?: string;
+}
+interface FetchCardOptions {
+    /** Override the base URL for agent card hosting. Defaults to https://agent-{agent_id}.newtype-ai.org */
+    baseUrl?: string;
+}
+/**
+ * Verify an agent's login payload against the newtype-ai.org server.
+ *
+ * @example
+ * ```ts
+ * import { verifyAgent } from '@newtype-ai/nit-sdk';
+ *
+ * const result = await verifyAgent(payload);
+ * if (result.verified) {
+ *   console.log(`Agent ${result.agent_id} verified`);
+ *   console.log(`Card:`, result.card);
+ * }
+ * ```
+ */
+declare function verifyAgent(payload: LoginPayload, options?: VerifyOptions): Promise<VerifyResult>;
+/**
+ * Fetch an agent's domain branch card using a read token.
+ *
+ * The read token is returned by verifyAgent() on successful verification.
+ * It is scoped to a specific agent_id + domain and expires after 30 days.
+ *
+ * @example
+ * ```ts
+ * import { verifyAgent, fetchAgentCard } from '@newtype-ai/nit-sdk';
+ *
+ * const result = await verifyAgent(payload);
+ * if (result.verified) {
+ *   // Later, fetch the latest card:
+ *   const card = await fetchAgentCard(result.agent_id, result.domain, result.readToken);
+ * }
+ * ```
+ */
+declare function fetchAgentCard(agentId: string, domain: string, readToken: string, options?: FetchCardOptions): Promise<AgentCard | null>;
+
+export { type AgentCard, type AgentCardSkill, type FetchCardOptions, type LoginPayload, type VerifyFailure, type VerifyOptions, type VerifyResult, type VerifySuccess, fetchAgentCard, verifyAgent };

package/dist/index.js

@@ -0,0 +1,29 @@
+// src/index.ts
+var DEFAULT_API_URL = "https://api.newtype-ai.org";
+async function verifyAgent(payload, options) {
+  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
+    })
+  });
+  return res.json();
+}
+async function fetchAgentCard(agentId, domain, readToken, options) {
+  const baseUrl = options?.baseUrl ?? `https://agent-${agentId}.newtype-ai.org`;
+  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();
+}
+export {
+  fetchAgentCard,
+  verifyAgent
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@newtype-ai/nit-sdk",
+  "version": "0.2.1",
+  "description": "Verify agent identity with one function call",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newtype-ai/nit-sdk"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}