@bluefly/openstandardagents 0.2.9 → 0.3.0

package/openapi/agent-identity.yaml

@@ -0,0 +1,620 @@
+openapi: 3.1.0
+jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
+info:
+  title: OSSA Agent Identity & Authentication API
+  version: 0.3.0
+  description: |
+    # OSSA Agent Identity & Authentication API
+
+    OpenAPI specification for agent identity management and authentication following OSSA v0.3.0 standards.
+
+    ## Features
+    - Agent instance authentication with multiple credential types
+    - JWT-based token issuance and management
+    - Identity verification and retrieval
+    - Token revocation and lifecycle management
+    - Security context and authorization scopes
+
+    ## Security Patterns
+    - Bearer token authentication (JWT)
+    - API key authentication
+    - OAuth2 authorization code flow (optional)
+    - mTLS for high-security environments
+
+    ## Compliance
+    - OSSA v0.3.0 specification
+    - W3C Distributed Tracing (trace_id, span_id)
+    - FIPS 140-2 compliant encryption (optional)
+    - Comprehensive audit logging
+
+  contact:
+    name: Bluefly.io LLM Platform Team
+    url: https://github.com/blueflyio/openstandardagents
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://api.llm.bluefly.io/ossa/v1/identity
+    description: Production server
+  - url: https://api-dev.llm.bluefly.io/ossa/v1/identity
+    description: Development server
+  - url: http://localhost:3000/identity
+    description: Local development
+
+security:
+  - BearerAuth: []
+  - ApiKeyAuth: []
+
+tags:
+  - name: Authentication
+    description: Agent authentication and token management
+  - name: Identity
+    description: Agent identity verification and retrieval
+  - name: Tokens
+    description: Token lifecycle management
+
+paths:
+  /agents/{id}/authenticate:
+    post:
+      summary: Authenticate agent
+      description: |
+        Authenticate an agent instance using provided credentials and issue an access token.
+        Supports multiple authentication methods: API key, OAuth2, and mTLS.
+      tags: [Authentication]
+      operationId: authenticateAgent
+      security: []  # Authentication endpoint doesn't require auth
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthenticationRequest'
+            examples:
+              apiKeyAuth:
+                summary: API Key Authentication
+                value:
+                  agent_id: "data-processor-agent"
+                  credential:
+                    type: "api_key"
+                    api_key: "ossa_ak_1234567890abcdef1234567890abcdef"
+                  scope: ["read", "execute"]
+                  context:
+                    tenant_id: "tenant-123"
+                    user_id: "user-456"
+              oauth2Auth:
+                summary: OAuth2 Token Authentication
+                value:
+                  agent_id: "analytics-agent"
+                  credential:
+                    type: "oauth2"
+                    access_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+                    token_type: "Bearer"
+                  scope: ["read", "write", "execute"]
+              mtlsAuth:
+                summary: mTLS Certificate Authentication
+                value:
+                  agent_id: "secure-agent"
+                  credential:
+                    type: "mtls"
+                    certificate: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
+                  scope: ["admin"]
+      responses:
+        '200':
+          description: Authentication successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenResponse'
+              examples:
+                success:
+                  summary: Successful authentication
+                  value:
+                    access_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudC0xMjMiLCJpYXQiOjE2MDk0NTkyMDB9.SflKxwRJSM..."
+                    token_type: "Bearer"
+                    expires_in: 3600
+                    scope: ["read", "execute"]
+                    instance_id: "550e8400-e29b-41d4-a716-446655440000"
+                    issued_at: "2025-12-18T10:00:00Z"
+                    token_id: "650e8400-e29b-41d4-a716-446655440001"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /agents/{id}/identity:
+    get:
+      summary: Get agent identity
+      description: |
+        Retrieve complete identity information for an authenticated agent instance.
+        Includes instance metadata, status, and tracing information.
+      tags: [Identity]
+      operationId: getAgentIdentity
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+        - name: instance_id
+          in: query
+          description: Optional specific instance ID to retrieve
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Agent identity retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentIdentity'
+              examples:
+                activeAgent:
+                  summary: Active agent instance
+                  value:
+                    agent_id: "data-processor-agent"
+                    instance_id: "550e8400-e29b-41d4-a716-446655440000"
+                    version: "ossa/v0.3.0"
+                    kind: "Agent"
+                    status: "active"
+                    tenant_id: "tenant-123"
+                    user_id: "user-456"
+                    trace_id: "4bf92f3577b34da6a3ce929d0e0e4736"
+                    span_id: "00f067aa0ba902b7"
+                    created_at: "2025-12-18T09:00:00Z"
+                    updated_at: "2025-12-18T10:00:00Z"
+                    metadata:
+                      labels:
+                        environment: "production"
+                        version: "1.0.0"
+                      annotations:
+                        deployed_by: "buildkit-cli"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /agents/{id}/tokens:
+    post:
+      summary: Issue new token
+      description: |
+        Issue a new authentication token for an already authenticated agent.
+        Useful for token refresh or obtaining tokens with different scopes.
+      tags: [Tokens]
+      operationId: issueToken
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                instance_id:
+                  type: string
+                  format: uuid
+                  description: Agent instance ID
+                scope:
+                  type: array
+                  items:
+                    type: string
+                  description: Requested token scopes
+                  default: ["read", "execute"]
+                expires_in:
+                  type: integer
+                  description: Requested token lifetime in seconds (max 86400)
+                  minimum: 60
+                  maximum: 86400
+                  default: 3600
+              required:
+                - instance_id
+            examples:
+              refreshToken:
+                summary: Issue refresh token
+                value:
+                  instance_id: "550e8400-e29b-41d4-a716-446655440000"
+                  scope: ["read", "write", "execute"]
+                  expires_in: 7200
+      responses:
+        '201':
+          description: Token issued successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    get:
+      summary: List active tokens
+      description: |
+        List all active authentication tokens for the agent instance.
+        Useful for token management and audit purposes.
+      tags: [Tokens]
+      operationId: listTokens
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+        - name: instance_id
+          in: query
+          description: Filter by specific instance ID
+          schema:
+            type: string
+            format: uuid
+        - name: limit
+          in: query
+          description: Maximum number of tokens to return
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: offset
+          in: query
+          description: Offset for pagination
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: List of active tokens
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tokens:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        token_id:
+                          type: string
+                          format: uuid
+                        instance_id:
+                          type: string
+                          format: uuid
+                        scope:
+                          type: array
+                          items:
+                            type: string
+                        issued_at:
+                          type: string
+                          format: date-time
+                        expires_at:
+                          type: string
+                          format: date-time
+                        last_used:
+                          type: string
+                          format: date-time
+                  total:
+                    type: integer
+                  limit:
+                    type: integer
+                  offset:
+                    type: integer
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /agents/{id}/tokens/{tokenId}:
+    delete:
+      summary: Revoke token
+      description: |
+        Revoke a specific authentication token, immediately invalidating it.
+        Once revoked, the token cannot be used for API requests.
+      tags: [Tokens]
+      operationId: revokeToken
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+        - name: tokenId
+          in: path
+          required: true
+          description: Unique identifier of the token to revoke
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenRevocationRequest'
+            examples:
+              securityBreach:
+                summary: Revoke due to security breach
+                value:
+                  token_id: "650e8400-e29b-41d4-a716-446655440001"
+                  reason: "security_breach"
+      responses:
+        '200':
+          description: Token revoked successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenRevocationResponse'
+              examples:
+                success:
+                  summary: Successful revocation
+                  value:
+                    revoked: true
+                    token_id: "650e8400-e29b-41d4-a716-446655440001"
+                    revoked_at: "2025-12-18T11:00:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /agents/{id}/security-context:
+    get:
+      summary: Get security context
+      description: |
+        Retrieve the complete security and authorization context for an authenticated agent.
+        Includes permissions, encryption requirements, and compliance settings.
+      tags: [Identity]
+      operationId: getSecurityContext
+      parameters:
+        - $ref: '#/components/parameters/AgentId'
+      responses:
+        '200':
+          description: Security context retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SecurityContext'
+              examples:
+                fullContext:
+                  summary: Complete security context
+                  value:
+                    authenticated: true
+                    principal:
+                      agent_id: "data-processor-agent"
+                      instance_id: "550e8400-e29b-41d4-a716-446655440000"
+                      tenant_id: "tenant-123"
+                      user_id: "user-456"
+                    scopes: ["read", "write", "execute"]
+                    permissions:
+                      resources:
+                        - resource_type: "workflows"
+                          resource_id: "*"
+                          actions: ["read", "execute"]
+                        - resource_type: "data"
+                          resource_id: "dataset-123"
+                          actions: ["read", "write"]
+                      policy_version: "v1.0.0"
+                    encryption:
+                      in_transit:
+                        required: true
+                        tls_version: "1.3"
+                        mtls_required: false
+                      at_rest:
+                        required: true
+                        algorithm: "AES-256-GCM"
+                    compliance:
+                      fips_mode: false
+                      audit_level: "detailed"
+                      retention_days: 90
+                    session:
+                      session_id: "750e8400-e29b-41d4-a716-446655440002"
+                      created_at: "2025-12-18T10:00:00Z"
+                      expires_at: "2025-12-18T11:00:00Z"
+                      last_activity: "2025-12-18T10:30:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token obtained from authentication endpoint
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key for server-to-server authentication
+    OAuth2:
+      type: oauth2
+      description: OAuth2 authorization code flow (optional)
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.llm.bluefly.io/oauth/authorize
+          tokenUrl: https://auth.llm.bluefly.io/oauth/token
+          scopes:
+            read: Read access to agent resources
+            write: Write access to agent resources
+            execute: Execute agent tasks and workflows
+            admin: Administrative access
+            messaging: Agent-to-agent messaging
+
+  parameters:
+    AgentId:
+      name: id
+      in: path
+      required: true
+      description: Agent identifier from the OSSA manifest (metadata.name)
+      schema:
+        type: string
+        pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+        minLength: 1
+        maxLength: 63
+      examples:
+        dataProcessor:
+          value: "data-processor-agent"
+          summary: Data processing agent
+        analyticsAgent:
+          value: "analytics-agent"
+          summary: Analytics agent
+
+  schemas:
+    AgentIdentity:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/AgentIdentity'
+
+    AuthenticationRequest:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/AuthenticationRequest'
+
+    TokenResponse:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/TokenResponse'
+
+    SecurityContext:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/SecurityContext'
+
+    TokenRevocationRequest:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/TokenRevocationRequest'
+
+    TokenRevocationResponse:
+      $ref: 'https://openstandardagents.org/schemas/v0.3.0/identity.json#/definitions/TokenRevocationResponse'
+
+    Error:
+      type: object
+      description: Standard error response
+      required:
+        - error
+        - message
+      properties:
+        error:
+          type: string
+          description: Error code
+        message:
+          type: string
+          description: Human-readable error message
+        details:
+          type: object
+          description: Additional error details
+          additionalProperties: true
+        trace_id:
+          type: string
+          description: Trace ID for error tracking
+        timestamp:
+          type: string
+          format: date-time
+          description: Error timestamp
+
+  responses:
+    BadRequest:
+      description: Bad request - invalid input
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            invalidCredentials:
+              summary: Invalid credentials format
+              value:
+                error: "invalid_request"
+                message: "Invalid credential format"
+                details:
+                  field: "credential.api_key"
+                  reason: "Must be at least 32 characters"
+                timestamp: "2025-12-18T10:00:00Z"
+
+    Unauthorized:
+      description: Unauthorized - authentication failed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            invalidToken:
+              summary: Invalid or expired token
+              value:
+                error: "unauthorized"
+                message: "Invalid or expired authentication token"
+                timestamp: "2025-12-18T10:00:00Z"
+
+    Forbidden:
+      description: Forbidden - insufficient permissions
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            insufficientScope:
+              summary: Insufficient scope
+              value:
+                error: "forbidden"
+                message: "Insufficient permissions for requested scopes"
+                details:
+                  requested: ["admin"]
+                  granted: ["read", "execute"]
+                timestamp: "2025-12-18T10:00:00Z"
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            agentNotFound:
+              summary: Agent not found
+              value:
+                error: "not_found"
+                message: "Agent instance not found"
+                details:
+                  agent_id: "unknown-agent"
+                timestamp: "2025-12-18T10:00:00Z"
+
+    TooManyRequests:
+      description: Rate limit exceeded
+      headers:
+        X-RateLimit-Limit:
+          schema:
+            type: integer
+          description: Request limit per window
+        X-RateLimit-Remaining:
+          schema:
+            type: integer
+          description: Remaining requests in current window
+        X-RateLimit-Reset:
+          schema:
+            type: integer
+          description: Time when the rate limit resets (Unix timestamp)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            rateLimitExceeded:
+              summary: Rate limit exceeded
+              value:
+                error: "rate_limit_exceeded"
+                message: "Too many authentication requests. Please try again later."
+                details:
+                  retry_after: 60
+                timestamp: "2025-12-18T10:00:00Z"
+
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            serverError:
+              summary: Internal server error
+              value:
+                error: "internal_server_error"
+                message: "An unexpected error occurred"
+                trace_id: "4bf92f3577b34da6a3ce929d0e0e4736"
+                timestamp: "2025-12-18T10:00:00Z"