@newtype-ai/nit-sdk 0.2.3 → 0.3.1

package/README.md

@@ -14,14 +14,19 @@ npm install @newtype-ai/nit-sdk
 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);
+const result = await verifyAgent(payload, {
+  policy: { max_identities_per_machine: 10, min_age_seconds: 3600 }
+});
 
-if (result.verified) {
+if (result.verified && result.admitted) {
   // result.agent_id — the agent's permanent UUID
   // result.card — the agent's card for your domain (skills, description, etc.)
   // result.wallet — { solana, evm } chain addresses
+  // result.identity — registration time, machine/IP identity counts, login history
   // result.readToken — for fetching updated cards later
   console.log(`Welcome, ${result.card?.name}`);
+} else if (result.verified && !result.admitted) {
+  console.log('Identity verified but does not meet trust policy');
 } else {
   console.log(`Verification failed: ${result.error}`);
 }
@@ -31,10 +36,10 @@ if (result.verified) {
 
 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, branch, wallet, readToken }` or `{ verified: false, error }`
+3. Your app calls `verifyAgent(payload, { policy })` — this hits `api.newtype-ai.org/agent-card/verify`
+4. You get back `{ verified, admitted, agent_id, card, identity, attestation, ... }` or `{ verified: false, error }`
 
-That's it. The server verifies the Ed25519 signature against the agent's registered public key.
+The server acts as an **identity registry** — it stores identity metadata, evaluates your trust policy, and returns a decision alongside raw signals. Like Stripe Radar: evaluates rules server-side for convenience, returns metadata for transparency.
 
 ## API
 
@@ -44,12 +49,34 @@ That's it. The server verifies the Ed25519 signature against the agent's registe
 |-----------|------|-------------|
 | `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, branch, wallet, readToken }` or `{ verified: false, error }`.
+| `options.policy` | `VerifyPolicy` | Trust rules the server evaluates (all optional) |
+
+**Policy fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `max_identities_per_ip` | `number` | Reject if too many identities from same registration IP |
+| `max_identities_per_machine` | `number` | Reject if too many identities from same machine |
+| `min_age_seconds` | `number` | Reject identities younger than this (default: 5) |
+| `max_login_rate_per_hour` | `number` | Reject if login rate is too high |
+
+**Returns** `Promise<VerifyResult>`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `verified` | `boolean` | Ed25519 signature is valid |
+| `admitted` | `boolean` | Identity meets your policy (`true` if no policy specified) |
+| `agent_id` | `string` | Agent's permanent UUID |
+| `card` | `AgentCard` | Agent's card for your domain |
+| `branch` | `string` | Which branch the card came from (domain or `"main"`) |
+| `wallet` | `{ solana, evm }` | Chain addresses |
+| `readToken` | `string` | For fetching updated cards (30-day expiry) |
+| `identity` | `IdentityMetadata` | Registration time, machine/IP counts, login history |
+| `attestation` | `ServerAttestation` | Server's Ed25519 signature over the result |
 
 ## 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.
+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.
 
 ## License
 

package/dist/index.d.ts

@@ -10,6 +10,8 @@ interface LoginPayload {
     domain: string;
     timestamp: number;
     signature: string;
+    /** Agent's public key. Present in nit >= 0.6.0. */
+    public_key?: string;
 }
 /** A skill listed in an agent's card. */
 interface AgentCardSkill {
@@ -43,9 +45,33 @@ interface AgentCard {
     iconUrl?: string;
     documentationUrl?: string;
 }
+/** Identity metadata returned by the server. */
+interface IdentityMetadata {
+    registration_timestamp: number | null;
+    machine_identity_count: number;
+    ip_identity_count: number;
+    total_logins: number;
+    last_login_timestamp: number | null;
+    unique_domains: number;
+}
+/** App-defined trust policy. Server evaluates and returns admitted: true/false. */
+interface VerifyPolicy {
+    max_identities_per_ip?: number;
+    max_identities_per_machine?: number;
+    min_age_seconds?: number;
+    max_login_rate_per_hour?: number;
+}
+/** Server attestation proving the server endorsed this verification. */
+interface ServerAttestation {
+    server_signature: string;
+    server_url: string;
+    server_public_key: string;
+}
 /** Successful verification result. */
 interface VerifySuccess {
     verified: true;
+    /** Whether the identity meets the app's policy. True if no policy were specified. */
+    admitted: boolean;
     agent_id: string;
     domain: string;
     card: AgentCard | null;
@@ -58,6 +84,10 @@ interface VerifySuccess {
     } | null;
     /** HMAC-signed read token for fetching the agent's domain branch card. 30-day expiry. */
     readToken: string;
+    /** Identity metadata — registration time, login count, machine/IP grouping, etc. */
+    identity?: IdentityMetadata;
+    /** Server attestation (if server signing key is configured). */
+    attestation?: ServerAttestation;
 }
 /** Failed verification result. */
 interface VerifyFailure {
@@ -68,6 +98,8 @@ type VerifyResult = VerifySuccess | VerifyFailure;
 interface VerifyOptions {
     /** Override the API base URL. Defaults to https://api.newtype-ai.org */
     apiUrl?: string;
+    /** App-defined trust policy. Server evaluates and returns admitted: true/false. */
+    policy?: VerifyPolicy;
 }
 interface FetchCardOptions {
     /** Override the base URL for agent card hosting. Defaults to https://agent-{agent_id}.newtype-ai.org */
@@ -107,4 +139,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 LoginPayload, type VerifyFailure, type VerifyOptions, type VerifyResult, type VerifySuccess, fetchAgentCard, verifyAgent };
+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 };

package/dist/index.js

@@ -9,7 +9,8 @@ async function verifyAgent(payload, options) {
       agent_id: payload.agent_id,
       domain: payload.domain,
       timestamp: payload.timestamp,
-      signature: payload.signature
+      signature: payload.signature,
+      ...options?.policy ? { policy: options.policy } : {}
     })
   });
   return res.json();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newtype-ai/nit-sdk",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Verify agent identity with one function call",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "prepublishOnly": "npm run build"