@countersig/verify 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# @countersig/verify
+
+Countersig A2A token verification library. Verify agent-to-agent authentication tokens issued by the Countersig platform.
+
+## Installation
+
+```bash
+npm install @countersig/verify
+```
+
+For remote verification (no shared secret), also install axios:
+
+```bash
+npm install axios
+```
+
+## Usage
+
+### Local Verification (with shared secret)
+
+Fastest method — no network call required.
+
+```javascript
+const { CountersigVerifier } = require('@countersig/verify');
+
+const verifier = new CountersigVerifier({
+  secret: process.env.A2A_TOKEN_SECRET
+});
+
+const payload = verifier.verifyLocal(token);
+console.log(payload.sub);    // Agent ID
+console.log(payload.caps);   // Agent capabilities
+console.log(payload.score);  // BAGS reputation score
+```
+
+### Remote Verification (via Countersig API)
+
+No shared secret needed — the Countersig API verifies the token server-side.
+
+```javascript
+const { CountersigVerifier } = require('@countersig/verify');
+
+const verifier = new CountersigVerifier({
+  apiUrl: 'https://api.countersig.com'
+});
+
+const payload = await verifier.verifyRemote(token);
+console.log(payload.sub);    // Agent ID
+console.log(payload.name);   // Agent name
+```
+
+### Auto-Detect Verification Method
+
+Uses local verification when a secret is available, falls back to remote otherwise.
+
+```javascript
+const verifier = new CountersigVerifier({
+  secret: process.env.A2A_TOKEN_SECRET,          // optional
+  apiUrl: 'https://api.countersig.com'           // optional
+});
+
+const payload = await verifier.verify(token);
+```
+
+### Inspect Token (no verification)
+
+```javascript
+const decoded = verifier.decode(token);
+console.log(decoded);  // Raw payload — DO NOT trust for auth decisions
+```
+
+## Token Payload
+
+A verified A2A token contains:
+
+| Field  | Type     | Description                        |
+| ------ | -------- | ---------------------------------- |
+| `sub`  | string   | Agent ID                           |
+| `type` | 'a2a'    | Token type identifier              |
+| `name` | string   | Agent display name                 |
+| `pubkey` | string | Agent's public key                 |
+| `chain` | string  | Blockchain type (solana, ethereum) |
+| `caps` | string[] | Agent capabilities                 |
+| `score` | number  | BAGS reputation score              |
+| `iss`  | string   | Issuer (countersig.com)            |
+| `aud`  | string   | Audience (countersig-a2a)             |
+| `iat`  | number   | Issued-at timestamp                |
+| `exp`  | number   | Expiration timestamp (60s from iat)|
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,43 @@
+export interface CountersigVerifierOptions {
+  /** PEM-encoded Ed25519 public key (SPKI format) for local verification */
+  publicKey?: string;
+  /** JWK-formatted Ed25519 public key for local verification */
+  jwk?: JsonWebKey;
+  /** Countersig API URL (default: https://api.countersig.com) */
+  apiUrl?: string;
+  /** @deprecated HMAC secret — migrate to Ed25519 public key or JWKS */
+  secret?: string;
+}
+
+export interface A2ATokenPayload {
+  sub: string;
+  type: 'a2a';
+  name: string;
+  pubkey: string;
+  chain: string;
+  caps: string[];
+  score: number;
+  iss: string;
+  aud: string;
+  iat: number;
+  exp: number;
+}
+
+export declare class CountersigVerifier {
+  constructor(options?: CountersigVerifierOptions);
+  
+  /** Verify token locally using Ed25519 public key */
+  verifyLocal(token: string): Promise<A2ATokenPayload>;
+  
+  /** Verify token using JWKS fetched from Countersig API */
+  verifyWithJWKS(token: string): Promise<A2ATokenPayload>;
+  
+  /** Verify token via Countersig HTTP API */
+  verifyRemote(token: string): Promise<A2ATokenPayload>;
+  
+  /** Auto-select best verification method */
+  verify(token: string): Promise<A2ATokenPayload>;
+  
+  /** Decode token without verification */
+  decode(token: string): A2ATokenPayload;
+}

package/index.js

@@ -0,0 +1,147 @@
+/**
+ * @countersig/verify — A2A Token Verification SDK
+ * 
+ * Verifies Countersig A2A tokens using Ed25519 asymmetric cryptography.
+ * No shared secret required — only the public key or JWKS endpoint.
+ */
+
+let jose;
+function getJose() {
+  if (!jose) {
+    try {
+      jose = require('jose');
+    } catch {
+      throw new Error('@countersig/verify requires the jose library. Run: npm install jose');
+    }
+  }
+  return jose;
+}
+
+class CountersigVerifier {
+  /**
+   * @param {Object} options
+   * @param {string} [options.publicKey] - PEM-encoded Ed25519 public key (SPKI format)
+   * @param {Object} [options.jwk] - JWK-formatted Ed25519 public key
+   * @param {string} [options.apiUrl] - Countersig API URL for remote/JWKS verification
+   * @param {string} [options.secret] - DEPRECATED: HMAC secret (backward compat, dev only)
+   */
+  constructor(options = {}) {
+    this.apiUrl = options.apiUrl || 'https://api.countersig.com';
+    this.issuer = 'countersig.com';
+    this.audience = 'countersig-a2a';
+    this._publicKeyPem = options.publicKey || null;
+    this._jwk = options.jwk || null;
+    this._secret = options.secret || null;
+    this._resolvedKey = null;
+    this._jwksSet = null;
+
+    if (this._secret) {
+      console.warn('[CountersigVerifier] HMAC secret verification is deprecated. Migrate to Ed25519 public key or JWKS.');
+    }
+  }
+
+  /** Resolve the public key for local verification */
+  async _getKey() {
+    if (this._resolvedKey) return this._resolvedKey;
+    const { importSPKI, importJWK } = getJose();
+    if (this._publicKeyPem) {
+      this._resolvedKey = await importSPKI(this._publicKeyPem, 'EdDSA');
+    } else if (this._jwk) {
+      this._resolvedKey = await importJWK(this._jwk, 'EdDSA');
+    }
+    return this._resolvedKey;
+  }
+
+  /**
+   * Verify token locally using Ed25519 public key.
+   * @param {string} token - JWT token string
+   * @returns {Promise<Object>} Decoded payload
+   */
+  async verifyLocal(token) {
+    const key = await this._getKey();
+    if (!key) throw new Error('No public key configured for local verification');
+    const { jwtVerify } = getJose();
+    const { payload } = await jwtVerify(token, key, {
+      issuer: this.issuer,
+      audience: this.audience,
+    });
+    return payload;
+  }
+
+  /**
+   * Verify token using JWKS fetched from the Countersig API.
+   * @param {string} token - JWT token string
+   * @returns {Promise<Object>} Decoded payload
+   */
+  async verifyWithJWKS(token) {
+    const { createRemoteJWKSet, jwtVerify } = getJose();
+    if (!this._jwksSet) {
+      this._jwksSet = createRemoteJWKSet(new URL(`${this.apiUrl}/.well-known/jwks.json`));
+    }
+    const { payload } = await jwtVerify(token, this._jwksSet, {
+      issuer: this.issuer,
+      audience: this.audience,
+    });
+    return payload;
+  }
+
+  /**
+   * Verify token via Countersig HTTP API (POST /agents/verify-token).
+   * @param {string} token - JWT token string
+   * @returns {Promise<Object>} Decoded payload
+   */
+  async verifyRemote(token) {
+    let axios;
+    try { axios = require('axios'); } catch {
+      throw new Error('axios is required for remote verification. Run: npm install axios');
+    }
+    const response = await axios.post(
+      `${this.apiUrl}/agents/verify-token`,
+      { token },
+      { timeout: 5000 }
+    );
+    if (!response.data?.valid) {
+      throw new Error(response.data?.error || 'Token verification failed');
+    }
+    return response.data.payload;
+  }
+
+  /**
+   * Auto-select best verification method:
+   * 1. Local (if public key provided)
+   * 2. JWKS (if apiUrl configured, fetches public key automatically)
+   * 3. Remote HTTP (fallback)
+   * 
+   * DEPRECATED: HMAC secret fallback (if secret provided)
+   * @param {string} token - JWT token string
+   * @returns {Promise<Object>} Decoded payload
+   */
+  async verify(token) {
+    // Ed25519 local verification (preferred)
+    if (this._publicKeyPem || this._jwk) {
+      return this.verifyLocal(token);
+    }
+    // HMAC fallback (deprecated, dev only)
+    if (this._secret) {
+      const jwtLib = require('jsonwebtoken');
+      return jwtLib.verify(token, this._secret, {
+        issuer: this.issuer,
+        audience: this.audience,
+      });
+    }
+    // JWKS auto-fetch (recommended for production consumers)
+    return this.verifyWithJWKS(token);
+  }
+
+  /**
+   * Decode token without verification (for inspection only).
+   * @param {string} token - JWT token string
+   * @returns {Object} Decoded payload
+   */
+  decode(token) {
+    const { decodeJwt } = getJose();
+    return decodeJwt(token);
+  }
+}
+
+module.exports = { CountersigVerifier };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@countersig/verify",
+  "version": "1.0.0",
+  "description": "Countersig A2A token verification library",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "keywords": ["countersig", "a2a", "agent", "verification", "nhi", "identity"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RunTimeAdmin/AgentID-2.0-Public"
+  },
+  "dependencies": {
+    "jose": "^5.9.0"
+  },
+  "optionalDependencies": {
+    "jsonwebtoken": "^9.0.2"
+  },
+  "peerDependencies": {
+    "axios": "^1.6.0"
+  }
+}