@astrasyncai/verification-gateway 1.0.0

package/dist/types-CS6v75-d.d.ts

@@ -0,0 +1,359 @@
+/**
+ * AstraSync Universal Verification Gateway Types
+ *
+ * TypeScript type definitions for agent verification across all counterparty types.
+ */
+/**
+ * Trust levels assigned to agents based on their composite trust score
+ */
+type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
+/**
+ * Access levels granted based on verification result
+ * - none: No credentials provided, show guidance
+ * - guidance: Commerce Shield overlay with registration info
+ * - read-only: Can browse, no mutations
+ * - standard: Normal access per PDLSS
+ * - full: Full access for high-trust agents
+ * - internal: Internal org access (same organization)
+ */
+type AccessLevel = 'none' | 'guidance' | 'read-only' | 'standard' | 'full' | 'internal';
+/**
+ * Types of counterparties that can integrate the gateway
+ */
+type CounterpartyType = 'agent' | 'api' | 'mcp_server' | 'website' | 'other';
+/**
+ * Agent credentials extracted from request
+ */
+interface AgentCredentials {
+    /** ASTRA-xxx identifier */
+    astraId?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** JWT token */
+    jwt?: string;
+    /** Raw authorization header */
+    authorizationHeader?: string;
+}
+/**
+ * Configuration options for the verification gateway
+ */
+interface GatewayConfig {
+    /** AstraSync API base URL */
+    apiBaseUrl: string;
+    /** API key for authenticating with AstraSync (optional for public endpoints) */
+    apiKey?: string;
+    /** Default access level for unverified requests */
+    defaultAccessLevel?: AccessLevel;
+    /** Minimum trust score required for standard access */
+    minTrustScore?: number;
+    /** Minimum trust score required for full access */
+    minTrustScoreForFull?: number;
+    /** Cache verification results (TTL in seconds) */
+    cacheTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom headers to send with verification requests */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * Verified agent information
+ */
+interface VerifiedAgent {
+    /** ASTRA-xxx identifier */
+    astraId: string;
+    /** Agent display name */
+    name: string;
+    /** Composite trust score (0-100) */
+    trustScore: number;
+    /** Trust level tier */
+    trustLevel: TrustLevel;
+    /** Whether agent is blockchain-verified */
+    blockchainVerified: boolean;
+    /** Agent status */
+    status: 'active' | 'inactive' | 'suspended' | 'migrating' | 'terminated' | 'retired';
+}
+/**
+ * Verified developer (KYD) information
+ */
+interface VerifiedDeveloper {
+    /** ASTRAD-xxx identifier */
+    astradId: string;
+    /** Developer name */
+    name?: string;
+    /** Developer trust score */
+    trustScore: number;
+    /** Whether developer identity is verified */
+    verified: boolean;
+}
+/**
+ * Verified organization (KYO) information
+ */
+interface VerifiedOrganization {
+    /** Organization name */
+    name: string;
+    /** Whether organization is verified */
+    verified: boolean;
+    /** Organization trust score */
+    trustScore: number;
+}
+/**
+ * PDLSS policy information returned with verification
+ */
+interface PDLSSInfo {
+    /** Whether purpose was allowed */
+    purposeAllowed: boolean;
+    /** Whether within duration constraints */
+    withinDuration: boolean;
+    /** Whether within limits */
+    withinLimits: boolean;
+    /** Whether scope is allowed */
+    scopeAllowed: boolean;
+    /** Whether self-instantiation is allowed (if applicable) */
+    selfInstantiationAllowed: boolean;
+    /** Allowed purpose categories */
+    allowedPurposes?: string[];
+    /** Transaction limits */
+    limits?: Record<string, number>;
+    /** Allowed scope/resources */
+    scope?: string[];
+    /** Applied policy details */
+    appliedPolicy?: {
+        boundaryId: string;
+        boundaryName: string;
+        policyId: string;
+        policyVersion: string;
+    };
+}
+/**
+ * Guidance information for unverified agents
+ */
+interface GuidanceInfo {
+    /** Human-readable guidance message */
+    message: string;
+    /** URL to register for AstraSync */
+    registrationUrl: string;
+    /** URL to documentation */
+    documentationUrl: string;
+    /** Steps to get verified */
+    steps?: string[];
+}
+/**
+ * Complete verification result
+ */
+interface VerificationResult {
+    /** Whether the agent is verified */
+    verified: boolean;
+    /** Access level granted */
+    accessLevel: AccessLevel;
+    /** Verified agent info (if verified) */
+    agent?: VerifiedAgent;
+    /** Developer info (if available) */
+    developer?: VerifiedDeveloper;
+    /** Organization info (if available) */
+    organization?: VerifiedOrganization;
+    /** PDLSS policy info (if verified) */
+    pdlss?: PDLSSInfo;
+    /** Guidance for unverified agents */
+    guidance?: GuidanceInfo;
+    /** Reasons for denial (if not allowed) */
+    denialReasons?: string[];
+    /** Whether step-up authentication is required */
+    requiresStepUp?: boolean;
+    /** Whether approval is required */
+    requiresApproval?: boolean;
+    /** Timestamp of verification */
+    verifiedAt: Date;
+    /** TTL for this result (seconds) */
+    cacheTtl?: number;
+}
+/**
+ * Request context for verification
+ */
+interface VerificationRequest {
+    /** Agent credentials */
+    credentials: AgentCredentials;
+    /** Purpose of the access request */
+    purpose?: string;
+    /** Specific action being performed */
+    action?: string;
+    /** Type of resource being accessed */
+    resourceType?: string;
+    /** Specific resource identifier */
+    resource?: string;
+    /** Jurisdiction for the request */
+    jurisdiction?: string;
+    /** Transaction value (if applicable) */
+    transactionValue?: number;
+    /** Currency for transaction value */
+    currency?: string;
+    /** Whether this is a sub-agent request */
+    isSubAgentRequest?: boolean;
+    /** Parent agent ID for sub-agent requests */
+    parentAgentId?: string;
+    /** Depth of sub-agent chain */
+    subAgentDepth?: number;
+    /** Client IP address */
+    clientIp?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Enable runtime challenge for this request */
+    enableRuntimeChallenge?: boolean;
+    /** Create a verification session (returns sessionId) */
+    createSession?: boolean;
+    /** Counterparty type */
+    counterpartyType?: CounterpartyType;
+    /** Runtime challenge options */
+    runtimeChallengeOptions?: {
+        timeoutOverride?: number;
+    };
+}
+/**
+ * Route-specific access configuration
+ */
+interface RouteAccessConfig {
+    /** Route pattern (supports wildcards) */
+    pattern: string;
+    /** HTTP method (or * for all) */
+    method: string | '*';
+    /** Minimum access level required */
+    minAccessLevel: AccessLevel;
+    /** Minimum trust score required (optional) */
+    minTrustScore?: number;
+    /** Required purposes (optional) */
+    requiredPurposes?: string[];
+}
+/**
+ * Express middleware options
+ */
+interface ExpressMiddlewareOptions extends GatewayConfig {
+    /** Route access configurations */
+    routes?: RouteAccessConfig[];
+    /** Function to extract credentials from request */
+    extractCredentials?: (req: unknown) => AgentCredentials;
+    /** Function to extract purpose from request */
+    extractPurpose?: (req: unknown) => string | undefined;
+    /** Skip verification for certain paths */
+    skipPaths?: string[];
+    /** Custom response for denied requests */
+    onDenied?: (result: VerificationResult, req: unknown, res: unknown) => void;
+}
+/**
+ * Next.js middleware options
+ */
+interface NextJsMiddlewareOptions extends GatewayConfig {
+    /** Route access configurations */
+    routes?: RouteAccessConfig[];
+    /** Paths to skip verification */
+    skipPaths?: string[];
+    /** Whether to show Commerce Shield overlay for unverified */
+    showCommerceShield?: boolean;
+    /** Commerce Shield configuration */
+    commerceShield?: {
+        title?: string;
+        message?: string;
+        allowGuestAccess?: boolean;
+        guestAccessLevel?: AccessLevel;
+    };
+}
+/**
+ * SDK function options
+ */
+interface SDKOptions extends GatewayConfig {
+    /** Timeout for verification requests (ms) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+}
+/**
+ * Token guidance returned from verify-access
+ */
+interface TokenGuidance {
+    recommendedScopes: string[];
+    recommendedTtlSeconds: number;
+    recommendedRateLimit?: {
+        requestsPerMinute: number;
+        maxTransactionValue?: number;
+        currency?: string;
+    };
+    jurisdictionConstraints?: string[];
+    delegationAllowed: boolean;
+    maxDelegationDepth?: number;
+    safetyDefaults: {
+        writePrivilegesRequested: boolean;
+        shortLivedTokenRecommended: boolean;
+        scopeConvention: 'astrasync-canonical';
+    };
+}
+/**
+ * Runtime challenge result
+ */
+interface RuntimeChallengeResult {
+    status: 'passed' | 'failed' | 'skipped' | 'timeout' | 'not_supported';
+    challengeId?: string;
+    challengeSentAt?: string;
+    responseReceivedAt?: string;
+    latencyMs?: number;
+    reason?: string;
+}
+/**
+ * Enhanced verification result (extends existing VerificationResult)
+ */
+interface EnhancedVerificationResult extends VerificationResult {
+    sessionId?: string;
+    runtimeChallenge?: RuntimeChallengeResult;
+    tokenGuidance?: TokenGuidance;
+    recommendation?: 'grant' | 'deny' | 'step_up_required';
+    recommendationReasons?: string[];
+}
+/**
+ * Cross-protocol credential config
+ */
+interface AstraSyncCredentials {
+    agentId: string;
+    verifyUrl?: string;
+    challengeUrl?: string;
+    pdlss?: {
+        purpose?: {
+            category: string;
+            action?: string;
+        };
+        duration?: {
+            maxSessionDuration?: number;
+        };
+        scope?: {
+            jurisdiction?: string;
+        };
+    };
+}
+/**
+ * Protocol transport type
+ */
+type ProtocolTransport = 'http' | 'a2a' | 'mcp';
+/**
+ * Commerce Shield UI props
+ */
+interface CommerceShieldProps {
+    /** Whether the shield is visible */
+    visible: boolean;
+    /** Verification result (if any) */
+    result?: VerificationResult;
+    /** Callback when user chooses to register */
+    onRegister?: () => void;
+    /** Callback when user chooses guest access */
+    onGuestAccess?: () => void;
+    /** Callback when user dismisses */
+    onDismiss?: () => void;
+    /** Custom title */
+    title?: string;
+    /** Custom message */
+    message?: string;
+    /** Whether guest access is allowed */
+    allowGuestAccess?: boolean;
+    /** Custom styles */
+    className?: string;
+}
+
+export type { AgentCredentials as A, CommerceShieldProps as C, EnhancedVerificationResult as E, GatewayConfig as G, NextJsMiddlewareOptions as N, ProtocolTransport as P, RouteAccessConfig as R, SDKOptions as S, TokenGuidance as T, VerificationRequest as V, AccessLevel as a, VerificationResult as b, AstraSyncCredentials as c, CounterpartyType as d, ExpressMiddlewareOptions as e, GuidanceInfo as f, PDLSSInfo as g, RuntimeChallengeResult as h, TrustLevel as i, VerifiedAgent as j, VerifiedDeveloper as k, VerifiedOrganization as l };

package/dist/ui/index.d.mts

@@ -0,0 +1,140 @@
+import { C as CommerceShieldProps, b as VerificationResult, A as AgentCredentials, f as GuidanceInfo, i as TrustLevel } from '../types-CS6v75-d.mjs';
+
+/**
+ * AstraSync Commerce Shield Component
+ *
+ * A React component that displays a verification overlay for unverified agents.
+ * Shows guidance on how to register and get verified access.
+ */
+
+/**
+ * Commerce Shield overlay component
+ */
+declare function CommerceShield({ visible, result, onRegister, onGuestAccess, onDismiss, title, message, allowGuestAccess, className, }: CommerceShieldProps): JSX.Element | null;
+/**
+ * Hook to manage Commerce Shield visibility
+ */
+declare function useCommerceShield(verificationResult: VerificationResult | null): {
+    visible: boolean;
+    dismiss: () => void;
+    reset: () => void;
+    result: VerificationResult | null;
+};
+
+/**
+ * AstraSync Credential Prompt Component
+ *
+ * A React component for prompting users to enter their agent credentials.
+ * Useful for single-page applications where agents may provide credentials interactively.
+ */
+
+/**
+ * Credential prompt props
+ */
+interface CredentialPromptProps {
+    /** Whether the prompt is visible */
+    visible: boolean;
+    /** Callback when credentials are submitted */
+    onSubmit: (credentials: AgentCredentials) => void;
+    /** Callback when prompt is dismissed */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Description text */
+    description?: string;
+    /** Whether to show API key input */
+    showApiKey?: boolean;
+    /** Whether to show JWT input */
+    showJwt?: boolean;
+    /** Loading state */
+    loading?: boolean;
+    /** Error message to display */
+    error?: string;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Credential prompt component
+ */
+declare function CredentialPrompt({ visible, onSubmit, onDismiss, title, description, showApiKey, showJwt, loading, error, className, }: CredentialPromptProps): JSX.Element | null;
+/**
+ * Hook to manage credential prompt state
+ */
+declare function useCredentialPrompt(): {
+    visible: boolean;
+    credentials: AgentCredentials | null;
+    loading: boolean;
+    error: string | null;
+    show: () => void;
+    hide: () => void;
+    submit: (creds: AgentCredentials) => void;
+    setError: (err: string) => void;
+    complete: () => void;
+};
+
+/**
+ * AstraSync Guidance Components
+ *
+ * React components for displaying guidance information to unverified agents.
+ * Provides helpful information on how to register and get verified.
+ */
+
+/**
+ * Guidance card props
+ */
+interface GuidanceCardProps {
+    /** Guidance information */
+    guidance: GuidanceInfo;
+    /** Card title */
+    title?: string;
+    /** Whether to show as compact inline */
+    compact?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Trust level badge props
+ */
+interface TrustLevelBadgeProps {
+    /** Trust level */
+    level: TrustLevel;
+    /** Trust score */
+    score?: number;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Access level indicator props
+ */
+interface AccessLevelIndicatorProps {
+    /** Current access level */
+    accessLevel: string;
+    /** Required access level */
+    requiredLevel?: string;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Guidance card component
+ */
+declare function GuidanceCard({ guidance, title, compact, className, }: GuidanceCardProps): JSX.Element;
+/**
+ * Trust level badge component
+ */
+declare function TrustLevelBadge({ level, score, size, className, }: TrustLevelBadgeProps): JSX.Element;
+/**
+ * Access level indicator component
+ */
+declare function AccessLevelIndicator({ accessLevel, requiredLevel, className, }: AccessLevelIndicatorProps): JSX.Element;
+/**
+ * Denial reasons list component
+ */
+interface DenialReasonsProps {
+    reasons: string[];
+    className?: string;
+}
+declare function DenialReasons({ reasons, className }: DenialReasonsProps): JSX.Element;
+
+export { AccessLevelIndicator, type AccessLevelIndicatorProps, CommerceShield, CredentialPrompt, type CredentialPromptProps, DenialReasons, type DenialReasonsProps, GuidanceCard, type GuidanceCardProps, TrustLevelBadge, type TrustLevelBadgeProps, useCommerceShield, useCredentialPrompt };

package/dist/ui/index.d.ts

@@ -0,0 +1,140 @@
+import { C as CommerceShieldProps, b as VerificationResult, A as AgentCredentials, f as GuidanceInfo, i as TrustLevel } from '../types-CS6v75-d.js';
+
+/**
+ * AstraSync Commerce Shield Component
+ *
+ * A React component that displays a verification overlay for unverified agents.
+ * Shows guidance on how to register and get verified access.
+ */
+
+/**
+ * Commerce Shield overlay component
+ */
+declare function CommerceShield({ visible, result, onRegister, onGuestAccess, onDismiss, title, message, allowGuestAccess, className, }: CommerceShieldProps): JSX.Element | null;
+/**
+ * Hook to manage Commerce Shield visibility
+ */
+declare function useCommerceShield(verificationResult: VerificationResult | null): {
+    visible: boolean;
+    dismiss: () => void;
+    reset: () => void;
+    result: VerificationResult | null;
+};
+
+/**
+ * AstraSync Credential Prompt Component
+ *
+ * A React component for prompting users to enter their agent credentials.
+ * Useful for single-page applications where agents may provide credentials interactively.
+ */
+
+/**
+ * Credential prompt props
+ */
+interface CredentialPromptProps {
+    /** Whether the prompt is visible */
+    visible: boolean;
+    /** Callback when credentials are submitted */
+    onSubmit: (credentials: AgentCredentials) => void;
+    /** Callback when prompt is dismissed */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Description text */
+    description?: string;
+    /** Whether to show API key input */
+    showApiKey?: boolean;
+    /** Whether to show JWT input */
+    showJwt?: boolean;
+    /** Loading state */
+    loading?: boolean;
+    /** Error message to display */
+    error?: string;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Credential prompt component
+ */
+declare function CredentialPrompt({ visible, onSubmit, onDismiss, title, description, showApiKey, showJwt, loading, error, className, }: CredentialPromptProps): JSX.Element | null;
+/**
+ * Hook to manage credential prompt state
+ */
+declare function useCredentialPrompt(): {
+    visible: boolean;
+    credentials: AgentCredentials | null;
+    loading: boolean;
+    error: string | null;
+    show: () => void;
+    hide: () => void;
+    submit: (creds: AgentCredentials) => void;
+    setError: (err: string) => void;
+    complete: () => void;
+};
+
+/**
+ * AstraSync Guidance Components
+ *
+ * React components for displaying guidance information to unverified agents.
+ * Provides helpful information on how to register and get verified.
+ */
+
+/**
+ * Guidance card props
+ */
+interface GuidanceCardProps {
+    /** Guidance information */
+    guidance: GuidanceInfo;
+    /** Card title */
+    title?: string;
+    /** Whether to show as compact inline */
+    compact?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Trust level badge props
+ */
+interface TrustLevelBadgeProps {
+    /** Trust level */
+    level: TrustLevel;
+    /** Trust score */
+    score?: number;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Access level indicator props
+ */
+interface AccessLevelIndicatorProps {
+    /** Current access level */
+    accessLevel: string;
+    /** Required access level */
+    requiredLevel?: string;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Guidance card component
+ */
+declare function GuidanceCard({ guidance, title, compact, className, }: GuidanceCardProps): JSX.Element;
+/**
+ * Trust level badge component
+ */
+declare function TrustLevelBadge({ level, score, size, className, }: TrustLevelBadgeProps): JSX.Element;
+/**
+ * Access level indicator component
+ */
+declare function AccessLevelIndicator({ accessLevel, requiredLevel, className, }: AccessLevelIndicatorProps): JSX.Element;
+/**
+ * Denial reasons list component
+ */
+interface DenialReasonsProps {
+    reasons: string[];
+    className?: string;
+}
+declare function DenialReasons({ reasons, className }: DenialReasonsProps): JSX.Element;
+
+export { AccessLevelIndicator, type AccessLevelIndicatorProps, CommerceShield, CredentialPrompt, type CredentialPromptProps, DenialReasons, type DenialReasonsProps, GuidanceCard, type GuidanceCardProps, TrustLevelBadge, type TrustLevelBadgeProps, useCommerceShield, useCredentialPrompt };