Initial commit

docs/api/api-specification.yaml

@@ -0,0 +1,469 @@
+openapi: 3.0.3
+info:
+  title: SMOA API Specification
+  description: |
+    API specification for Secure Mobile Operations Application (SMOA).
+    This specification documents all internal and external APIs.
+  version: 1.0.0
+  contact:
+    name: SMOA Development Team
+    email: smoa-dev@example.com
+  license:
+    name: Proprietary - Government Use Only
+
+servers:
+  - url: https://api.smoa.example.com/v1
+    description: Production server
+  - url: https://api-dev.smoa.example.com/v1
+    description: Development server
+
+tags:
+  - name: Authentication
+    description: Authentication and authorization endpoints
+  - name: Credentials
+    description: Digital credential management
+  - name: Orders
+    description: Orders management
+  - name: Evidence
+    description: Evidence chain of custody
+  - name: Reports
+    description: Report generation
+  - name: Communications
+    description: Secure communications
+  - name: Directory
+    description: Internal directory
+
+security:
+  - BearerAuth: []
+  - ApiKeyAuth: []
+
+paths:
+  /auth/login:
+    post:
+      tags:
+        - Authentication
+      summary: Authenticate user
+      description: |
+        Authenticate user with multi-factor authentication (PIN + Biometric).
+        Returns authentication token on success.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LoginRequest'
+      responses:
+        '200':
+          description: Authentication successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LoginResponse'
+        '401':
+          description: Authentication failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: Too many login attempts
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /auth/logout:
+    post:
+      tags:
+        - Authentication
+      summary: Logout user
+      description: Invalidates current session
+      responses:
+        '200':
+          description: Logout successful
+        '401':
+          description: Unauthorized
+
+  /credentials:
+    get:
+      tags:
+        - Credentials
+      summary: List user credentials
+      description: Returns list of credentials available to the authenticated user
+      parameters:
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [id, badge, license, permit, other]
+          description: Filter by credential type
+      responses:
+        '200':
+          description: List of credentials
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Credential'
+        '401':
+          description: Unauthorized
+
+    post:
+      tags:
+        - Credentials
+      summary: Create new credential
+      description: Creates a new digital credential
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CredentialCreate'
+      responses:
+        '201':
+          description: Credential created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Credential'
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+
+  /credentials/{id}:
+    get:
+      tags:
+        - Credentials
+      summary: Get credential by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Credential ID
+      responses:
+        '200':
+          description: Credential details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Credential'
+        '404':
+          description: Credential not found
+        '401':
+          description: Unauthorized
+
+  /orders:
+    get:
+      tags:
+        - Orders
+      summary: List orders
+      description: Returns list of orders available to the authenticated user
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [draft, pending_approval, approved, issued, executed, expired, revoked]
+          description: Filter by order status
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [authorization, assignment, search_warrant, arrest_warrant, court_order, administrative]
+          description: Filter by order type
+      responses:
+        '200':
+          description: List of orders
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+        '401':
+          description: Unauthorized
+
+    post:
+      tags:
+        - Orders
+      summary: Create new order
+      description: Creates a new order
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderCreate'
+      responses:
+        '201':
+          description: Order created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+
+  /orders/{id}:
+    get:
+      tags:
+        - Orders
+      summary: Get order by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Order ID
+      responses:
+        '200':
+          description: Order details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '404':
+          description: Order not found
+        '401':
+          description: Unauthorized
+
+  /evidence:
+    get:
+      tags:
+        - Evidence
+      summary: List evidence items
+      description: Returns list of evidence items
+      responses:
+        '200':
+          description: List of evidence items
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Evidence'
+        '401':
+          description: Unauthorized
+
+  /reports:
+    post:
+      tags:
+        - Reports
+      summary: Generate report
+      description: Generates a report in the specified format
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReportRequest'
+      responses:
+        '200':
+          description: Report generated
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+            application/json:
+              schema:
+                type: string
+            application/xml:
+              schema:
+                type: string
+            text/csv:
+              schema:
+                type: string
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+
+  schemas:
+    LoginRequest:
+      type: object
+      required:
+        - pin
+        - biometricToken
+      properties:
+        pin:
+          type: string
+          description: User PIN
+          minLength: 6
+          maxLength: 12
+        biometricToken:
+          type: string
+          description: Biometric authentication token
+
+    LoginResponse:
+      type: object
+      properties:
+        token:
+          type: string
+          description: Authentication token
+        expiresIn:
+          type: integer
+          description: Token expiration time in seconds
+        user:
+          $ref: '#/components/schemas/User'
+
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        username:
+          type: string
+        roles:
+          type: array
+          items:
+            type: string
+
+    Credential:
+      type: object
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [id, badge, license, permit, other]
+        title:
+          type: string
+        issuer:
+          type: string
+        issueDate:
+          type: string
+          format: date
+        expirationDate:
+          type: string
+          format: date
+        status:
+          type: string
+          enum: [active, expired, revoked]
+        barcode:
+          type: string
+          description: PDF417 barcode data
+
+    CredentialCreate:
+      type: object
+      required:
+        - type
+        - title
+        - issuer
+      properties:
+        type:
+          type: string
+        title:
+          type: string
+        issuer:
+          type: string
+        issueDate:
+          type: string
+          format: date
+        expirationDate:
+          type: string
+          format: date
+
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [authorization, assignment, search_warrant, arrest_warrant, court_order, administrative]
+        title:
+          type: string
+        status:
+          type: string
+          enum: [draft, pending_approval, approved, issued, executed, expired, revoked]
+        issuedBy:
+          type: string
+        issueDate:
+          type: string
+          format: date-time
+        expirationDate:
+          type: string
+          format: date-time
+
+    OrderCreate:
+      type: object
+      required:
+        - type
+        - title
+      properties:
+        type:
+          type: string
+        title:
+          type: string
+        content:
+          type: string
+        expirationDate:
+          type: string
+          format: date-time
+
+    Evidence:
+      type: object
+      properties:
+        id:
+          type: string
+        caseNumber:
+          type: string
+        description:
+          type: string
+        type:
+          type: string
+          enum: [physical, digital, biological, chemical, firearm, document]
+        collectionDate:
+          type: string
+          format: date-time
+        currentCustodian:
+          type: string
+
+    ReportRequest:
+      type: object
+      required:
+        - template
+        - format
+      properties:
+        template:
+          type: string
+          description: Report template name
+        format:
+          type: string
+          enum: [pdf, xml, json, csv]
+        parameters:
+          type: object
+          description: Template parameters
+
+    ErrorResponse:
+      type: object
+      properties:
+        error:
+          type: string
+        message:
+          type: string
+        code:
+          type: string
+        timestamp:
+          type: string
+          format: date-time
+