@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

npm install @astrasyncai/verification-gateway

Quick Start

Express Middleware

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

// 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)

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:

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

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

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