@astrasyncai/verification-gateway 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# @astrasyncai/verification-gateway
+
+Universal Verification Gateway for AstraSync KYA Platform - verify AI agents across any counterparty type.
+
+## Overview
+
+The Verification Gateway provides a single, universal solution for verifying AI agents. One codebase, multiple deployment targets:
+
+- **Express.js middleware** - Protect API endpoints
+- **Next.js middleware** - Protect web applications with Commerce Shield
+- **SDK functions** - Direct verification for agent-to-agent or serverless
+
+All verification flows through the same `POST /agents/verify-access` endpoint, ensuring consistent PDLSS (Permission, Duration, Limit, Scope, Self-instantiation) enforcement.
+
+## Installation
+
+```bash
+npm install @astrasyncai/verification-gateway
+```
+
+## Quick Start
+
+### Express Middleware
+
+```typescript
+import express from 'express';
+import { createMiddleware } from '@astrasyncai/verification-gateway/express';
+
+const app = express();
+
+app.use(createMiddleware({
+  apiBaseUrl: 'https://api.astrasync.ai',
+  routes: [
+    { pattern: '/api/public/*', method: '*', minAccessLevel: 'none' },
+    { pattern: '/api/data/*', method: 'GET', minAccessLevel: 'read-only' },
+    { pattern: '/api/data/*', method: '*', minAccessLevel: 'standard' },
+    { pattern: '/api/admin/*', method: '*', minAccessLevel: 'internal' },
+  ],
+}));
+```
+
+### Next.js Middleware
+
+```typescript
+// middleware.ts
+import { createMiddleware } from '@astrasyncai/verification-gateway/nextjs';
+
+export const middleware = createMiddleware({
+  apiBaseUrl: 'https://api.astrasync.ai',
+  showCommerceShield: true,
+  routes: [
+    { pattern: '/api/*', method: '*', minAccessLevel: 'standard' },
+    { pattern: '/dashboard/*', method: '*', minAccessLevel: 'read-only' },
+  ],
+});
+
+export const config = {
+  matcher: ['/api/:path*', '/dashboard/:path*'],
+};
+```
+
+### SDK (Direct Usage)
+
+```typescript
+import { createClient } from '@astrasyncai/verification-gateway/sdk';
+
+const gateway = createClient({
+  apiBaseUrl: 'https://api.astrasync.ai',
+});
+
+// Verify another agent before interacting
+const result = await gateway.verify({
+  astraId: 'ASTRA-abc123',
+  purpose: 'data-exchange',
+});
+
+if (result.verified && result.accessLevel !== 'none') {
+  // Safe to interact with this agent
+  console.log(`Trust score: ${result.agent?.trustScore}`);
+}
+```
+
+## Access Levels
+
+| Level | Description |
+|-------|-------------|
+| `none` | No credentials provided |
+| `guidance` | Commerce Shield overlay shown |
+| `read-only` | Can browse, no mutations |
+| `standard` | Normal access per PDLSS |
+| `full` | Full access for high-trust agents |
+| `internal` | Organization member access |
+
+## Trust Levels
+
+| Level | Score Range |
+|-------|-------------|
+| BRONZE | 0-39 |
+| SILVER | 40-59 |
+| GOLD | 60-79 |
+| PLATINUM | 80-100 |
+
+## UI Components
+
+The package includes React components for displaying verification status:
+
+```tsx
+import { CommerceShield, TrustLevelBadge, GuidanceCard } from '@astrasyncai/verification-gateway/ui';
+
+// Commerce Shield overlay
+<CommerceShield
+  visible={!verified}
+  result={verificationResult}
+  onRegister={() => window.location.href = '/register'}
+  allowGuestAccess={true}
+/>
+
+// Trust level badge
+<TrustLevelBadge level="GOLD" score={75} />
+
+// Guidance card
+<GuidanceCard guidance={verificationResult.guidance} />
+```
+
+## Credential Extraction
+
+Agents can provide credentials via:
+
+1. **Headers** (recommended):
+   - `X-Astra-Id`: Agent ASTRA-ID
+   - `X-Api-Key`: API key
+   - `Authorization: Bearer <jwt>`: JWT token
+
+2. **Query Parameters** (fallback):
+   - `?astraId=ASTRA-xxx`
+   - `?apiKey=xxx`
+
+## Verification Response
+
+```typescript
+interface VerificationResult {
+  verified: boolean;
+  accessLevel: 'none' | 'guidance' | 'read-only' | 'standard' | 'full' | 'internal';
+
+  agent?: {
+    astraId: string;
+    name: string;
+    trustScore: number;
+    trustLevel: 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
+    blockchainVerified: boolean;
+  };
+
+  developer?: {
+    astradId: string;
+    verified: boolean;
+  };
+
+  organization?: {
+    name: string;
+    verified: boolean;
+    trustScore: number;
+  };
+
+  pdlss?: {
+    purposeAllowed: boolean;
+    withinDuration: boolean;
+    withinLimits: boolean;
+    scopeAllowed: boolean;
+    selfInstantiationAllowed: boolean;
+  };
+
+  guidance?: {
+    message: string;
+    registrationUrl: string;
+    documentationUrl: string;
+    steps?: string[];
+  };
+
+  denialReasons?: string[];
+}
+```
+
+## Configuration
+
+```typescript
+interface GatewayConfig {
+  // Required
+  apiBaseUrl: string;
+
+  // Optional
+  apiKey?: string;              // For authenticated requests
+  defaultAccessLevel?: string;  // Default: 'guidance'
+  minTrustScore?: number;       // For 'standard' access (default: 40)
+  minTrustScoreForFull?: number; // For 'full' access (default: 70)
+  cacheTtl?: number;            // Cache duration in seconds (default: 300)
+  debug?: boolean;              // Enable debug logging
+}
+```
+
+## Commerce Shield
+
+When an unverified agent visits a protected page, the Commerce Shield overlay displays:
+
+- Registration guidance
+- Steps to get verified
+- Link to documentation
+- Optional guest access
+
+This creates a smooth experience for agents while maintaining security.
+
+## License
+
+MIT

package/dist/adapters/express.d.mts

@@ -0,0 +1,3 @@
+import 'express';
+import '../types-CS6v75-d.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-DUDYpvNZ.mjs';

package/dist/adapters/express.d.ts

@@ -0,0 +1,3 @@
+import 'express';
+import '../types-CS6v75-d.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials, r as requireAccess, v as verifyOnly } from '../express-BhD3mWsL.js';