Service Authentication Services

Service - Authentication Services

**Referenced Files in This Document** - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.js) - [backend/src/routes/verify.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/verify.js) - [backend/src/middleware/errorHandler.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/errorHandler.js) - [backend/src/middleware/rateLimit.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/rateLimit.js) - [backend/src/config/index.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/config/index.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.js) - [backend/src/models/db.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/db.js) - [backend/src/models/migrate.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/migrate.js) - [backend/server.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/server.js) - [backend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/package.json)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document provides comprehensive documentation for the AgentID authentication services, focusing on Bags authentication wrapper and PKI challenge-response system for ongoing verification and spoofing prevention.

Project Structure

The authentication-related code resides in the backend service:

• Services: BagsAuthVerifier and PKIChallenge
• Routes: HTTP endpoints for challenge issuance and verification
• Middleware: error handling and rate limiting
• Models: database queries and schema migrations

graph TB
subgraph "Backend"
SRV["Express Server<br/>server.js"]
CFG["Config<br/>config/index.js"]
MW_ERR["Error Handler<br/>middleware/errorHandler.js"]
MW_RATE["Rate Limit<br/>middleware/rateLimit.js"]
ROUTE_VERIFY["Verify Routes<br/>routes/verify.js"]
SVC_BAGS["BagsAuthVerifier<br/>services/bagsAuthVerifier.js"]
SVC_PKI["PKIChallenge<br/>services/pkiChallenge.js"]
MODELS_QUERIES["Queries<br/>models/queries.js"]
MODELS_DB["DB Pool<br/>models/db.js"]
MIGRATE["Schema Migration<br/>models/migrate.js"]
end
SRV --> CFG
SRV --> MW_RATE
SRV --> MW_ERR
SRV --> ROUTE_VERIFY
ROUTE_VERIFY --> SVC_PKI
ROUTE_VERIFY --> MODELS_QUERIES
SVC_PKI --> MODELS_QUERIES
SVC_PKI --> MODELS_DB
SVC_BAGS --> CFG
MODELS_QUERIES --> MODELS_DB
MIGRATE --> MODELS_DB

Loading

Core Components

• BagsAuthVerifier: Wraps Bags Ed25519 auth flow

  • initBagsAuth: Initialize authentication
  • verifyBagsSignature: Verify Ed25519 signatures
  • completeBagsAuth: Complete authentication

• PKIChallenge: Challenge-response mechanism

  • issueChallenge: Create new challenge
  • verifyChallenge: Validate response

Architecture Overview

The authentication architecture integrates external services and internal components for secure, verifiable identity.

graph TB
subgraph "External Services"
BAGS["Bags Public API<br/>/agent/v2/auth/init<br/>/agent/v2/auth/callback"]
SAID["SAID Identity Gateway"]
end
subgraph "AgentID Backend"
SVC_BAGS["BagsAuthVerifier"]
SVC_PKI["PKIChallenge"]
ROUTE_VERIFY["Verify Routes"]
QUERIES["Database Queries"]
DB["PostgreSQL"]
end
CLIENT["Client / Agent Wallet"] --> ROUTE_VERIFY
ROUTE_VERIFY --> SVC_PKI
SVC_PKI --> QUERIES
QUERIES --> DB
CLIENT --> SVC_BAGS
SVC_BAGS --> BAGS
SVC_BAGS --> DB
SVC_PKI --> SAID

Loading

Detailed Component Analysis

BagsAuthVerifier Service

Wraps Bags Ed25519 agent authentication:

• Initialization: requests challenge from Bags API
• Signature verification: validates Ed25519 using tweetnacl
• Completion: submits signature and returns API key reference

PKIChallenge Service

Implements Ed25519-based challenge-response:

• Issues time-bound challenges with random nonces
• Verifies signatures against stored challenges
• Single-use enforcement prevents replays

API Specifications

POST /verify/challenge

• Issue new PKI challenge
• Request: { pubkey: string }
• Response: { nonce, challenge, expiresIn }

POST /verify/response

• Verify signed challenge
• Request: { pubkey, nonce, signature }
• Response: { verified, pubkey, timestamp }

Data Models

Three core tables:

• agent_identities: Agent records
• agent_verifications: Challenge storage
• agent_flags: Moderation records

Dependency Analysis

External dependencies:

• axios: HTTP client
• tweetnacl: Ed25519 crypto
• bs58: Base58 encoding
• uuid: UUID generation
• pg: PostgreSQL driver

Performance Considerations

• Database indexing on frequently queried columns
• Connection pooling for PostgreSQL
• Redis for challenge caching
• Rate limiting with express-rate-limit

Troubleshooting Guide

Common failures:

• Challenge not found: Nonce reuse or expired
• Challenge expired: Response submitted after window
• Invalid signature: Wrong message format or key
• Rate limit exceeded: Too many requests

Conclusion

The AgentID authentication services provide a robust, PKI-based solution for verifying agent identities with Ed25519 signatures and nonce management.

Appendices

Configuration Requirements

Required environment variables:

• DATABASE_URL
• BAGS_API_KEY
• SAID_GATEWAY_URL
• REDIS_URL
• CHALLENGE_EXPIRY_SECONDS

Integration Patterns

• External API: x-api-key header scheme
• Database: Parameterized queries
• Frontend: Error handling and rate limiting