feat: add local login verification

Author: stainlu

README.md

@@ -121,6 +121,7 @@ Pure Node.js builtins. No bloat.
 | `nit show [target]` | Show commit metadata and card content |
 | `nit sign "msg"` | Sign a message with your Ed25519 key |
 | `nit sign --login <domain>` | Auto-switch to domain branch + generate login payload |
+| `nit verify-login <payload.json> --card <card.json>` | Verify a login payload locally |
 | `nit remote` | Show remote URL and credential status |
 | `nit remote add <name> <url>` | Add a new remote |
 | `nit remote set-url <name> <url>` | Change a remote's URL |
@@ -161,6 +162,13 @@ With Newtype's default hosted verifier, the app sends the payload to `api.newtyp
 
 The domain is baked into the signature — a signature for `faam.io` is mathematically invalid for `discord.com`.
 
+Verify locally without calling a hosted service:
+
+```bash
+nit sign --login faam.io > login.json
+nit verify-login login.json --card agent-card.json --domain faam.io
+```
+
 ### Remote Protocol
 
 The main branch is public. Non-main branches require signed-challenge authentication:
@@ -196,7 +204,7 @@ your-project/
 ```typescript
 import {
   init, commit, checkout, branch, push, status, sign, loginPayload,
-  loadRawKeyPair, getWalletAddresses, signTx, rpcSetUrl,
+  verifyLoginPayload, loadRawKeyPair, getWalletAddresses, signTx, rpcSetUrl,
   authSet, authShow, reset, show, pull,
 } from '@newtype-ai/nit';
 
@@ -205,6 +213,9 @@ await init();
 // Log into an app (auto-creates and switches to domain branch)
 const payload = await loginPayload('faam.io');
 // → { agent_id, domain, timestamp, signature, public_key, switchedBranch, createdSkill }
+const { cardJson } = await show();
+const verified = verifyLoginPayload(payload, cardJson, { expectedDomain: 'faam.io' });
+// → { verified: true, agent_id, domain, public_key, age_seconds }
 
 // Customize card, then commit & push
 await commit('FAAM config');

docs/NIT.md

@@ -459,6 +459,7 @@ All commands run in a directory containing `agent-card.json` and `.nit/`.
 | `nit show [target]` | Show commit metadata (hash, author, date, message) and full card JSON for HEAD or a specific commit/branch |
 | `nit sign "message"` | Sign a message with the agent's Ed25519 private key, output base64 signature |
 | `nit sign --login <domain>` | Generate a JSON login payload (`agent_id`, `domain`, `timestamp`, `signature`) for app auth |
+| `nit verify-login <payload.json> --card <card.json>` | Verify a login payload locally against an agent card |
 | `nit remote` | Show remote info (URL, agent ID, auth method) |
 | `nit sign-tx --chain <c> <data>` | Sign transaction data (EVM: 32-byte keccak256 hash, Solana: message bytes) with identity key |
 | `nit broadcast --chain <c> <tx>` | Broadcast signed transaction to configured RPC endpoint |

docs/how-it-works.md

@@ -102,6 +102,8 @@ Parent is omitted for the initial commit. Timestamp is unix seconds.
    }
    ```
 
+7. **Local verify:** `nit verify-login login.json --card agent-card.json --domain sharkclaw.ai` rebuilds the same message and verifies the Ed25519 signature against the card's `publicKey`.
+
 **Domain binding — why cross-app replay is impossible:**
 
 The domain is not a secret — it's a **binding constraint** baked into the signature. Knowing another app's domain name doesn't help an attacker. Here's why:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@newtype-ai/nit",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "Version control for agent cards",
   "type": "module",
   "bin": {

package.json

@@ -6,6 +6,7 @@
 // ---------------------------------------------------------------------------
 
 import { execFileSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
 import {
   init,
   status,
@@ -33,6 +34,7 @@ import {
   reset,
   show,
   pull,
+  verifyLoginPayload,
   findNitDir,
 } from './index.js';
 import type { AuthProvider } from './types.js';
@@ -49,7 +51,7 @@ const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
 
 async function main() {
   const [, , command, ...args] = process.argv;
-  const skipUpdateCommands = new Set(['help', 'doctor', '--help', '-h', '--version', '-v', undefined]);
+  const skipUpdateCommands = new Set(['help', 'doctor', 'verify-login', '--help', '-h', '--version', '-v', undefined]);
   if (!skipUpdateCommands.has(command)) {
     // Auto-update before running mutating/network commands (CLI only, never library)
     await autoUpdate();
@@ -114,6 +116,9 @@ async function main() {
       case 'pull':
         await cmdPull(args);
         break;
+      case 'verify-login':
+        await cmdVerifyLogin(args);
+        break;
       case 'doctor':
         await cmdDoctor(args);
         break;
@@ -410,7 +415,6 @@ async function cmdSign(args: string[]) {
     if (payload.createdSkill) {
       console.error(`Created skill template '${payload.createdSkill}'`);
     }
-    console.error(`Auth: use browser profile="user" to reuse existing sessions. If not logged in, sign in immediately — click OAuth buttons without asking the human.`);
     const { switchedBranch: _s, createdSkill: _c, autoInitialized: _ai, autoPushed: _ap, ...output } = payload;
     console.log(JSON.stringify(output, null, 2));
     return;
@@ -451,6 +455,70 @@ async function cmdSignTx(args: string[]) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+async function cmdVerifyLogin(args: string[]) {
+  const payloadPath = args[0];
+  if (!payloadPath) {
+    console.error('Usage: nit verify-login <payload.json|-> [--card agent-card.json] [--domain <domain>] [--max-age <seconds>]');
+    process.exit(1);
+  }
+
+  let cardPath = 'agent-card.json';
+  let expectedDomain: string | undefined;
+  let maxAgeSeconds: number | undefined;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--card') {
+      if (!args[i + 1]) {
+        console.error('Missing value for --card');
+        process.exit(1);
+      }
+      cardPath = args[++i];
+    } else if (arg === '--domain') {
+      if (!args[i + 1]) {
+        console.error('Missing value for --domain');
+        process.exit(1);
+      }
+      expectedDomain = args[++i];
+    } else if (arg === '--max-age') {
+      if (!args[i + 1]) {
+        console.error('Missing value for --max-age');
+        process.exit(1);
+      }
+      maxAgeSeconds = Number(args[++i]);
+      if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds < 0) {
+        console.error('--max-age must be a non-negative number of seconds');
+        process.exit(1);
+      }
+    } else {
+      console.error(`Unknown flag: ${arg}`);
+      console.error('Usage: nit verify-login <payload.json|-> [--card agent-card.json] [--domain <domain>] [--max-age <seconds>]');
+      process.exit(1);
+    }
+  }
+
+  const payloadRaw = payloadPath === '-'
+    ? await readStdin()
+    : await fs.readFile(payloadPath, 'utf-8');
+  const cardRaw = await fs.readFile(cardPath, 'utf-8');
+  const payload = JSON.parse(payloadRaw) as unknown;
+  const card = JSON.parse(cardRaw) as unknown;
+
+  const result = verifyLoginPayload(payload, card, { expectedDomain, maxAgeSeconds });
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.verified) {
+    process.exit(1);
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
 async function cmdBroadcast(args: string[]) {
   const chainIndex = args.indexOf('--chain');
   if (chainIndex === -1 || !args[chainIndex + 1]) {
@@ -874,6 +942,7 @@ ${bold('Commands:')}
   show [target]      Show commit metadata and card content
   sign "message"     Sign a message with your Ed25519 key
   sign --login <dom> Switch to domain branch + generate login payload
+  verify-login <p>   Verify a login payload locally
   remote             Show remote info
   remote add <n> <u> Add a new remote
   remote set-url <n> <u>  Change remote URL

src/cli.ts

@@ -188,13 +188,11 @@ export async function signChallenge(
 }
 
 /**
- * Verify a signature against a challenge using the raw base64 public key.
- * Internal utility — not part of the public API.
- * Apps verify via POST api.newtype-ai.org/agent-card/verify instead.
+ * Verify a signature against a message using the raw base64 public key.
  */
-function verifySignature(
+export function verifySignature(
   pubBase64: string,
-  challenge: string,
+  message: string,
   signatureBase64: string,
 ): boolean {
   const xB64url = base64ToBase64url(pubBase64);
@@ -206,7 +204,7 @@ function verifySignature(
 
   return verify(
     null,
-    Buffer.from(challenge, 'utf-8'),
+    Buffer.from(message, 'utf-8'),
     publicKeyObj,
     Buffer.from(signatureBase64, 'base64'),
   );