insforge 0.3.1

package/openapi/auth.yaml

@@ -0,0 +1,563 @@
+openapi: 3.0.3
+info:
+  title: Insforge Authentication API
+  version: 2.0.0
+  description: Authentication endpoints with separated auth and profile tables
+
+paths:
+  /api/auth/users:
+    post:
+      summary: Register new user
+      description: Creates a new user account
+      tags:
+          - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                  example: user@example.com
+                password:
+                  type: string
+                  minLength: 8
+                  example: securepassword123
+                name:
+                  type: string
+                  example: John Doe
+      responses:
+        '201':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                      email:
+                        type: string
+                      name:
+                        type: string
+                      emailVerified:
+                        type: boolean
+                      createdAt:
+                        type: string
+                        format: date-time
+                      updatedAt:
+                        type: string
+                        format: date-time
+                  accessToken:
+                    type: string
+                    description: JWT authentication token
+        '400':
+          description: Invalid request
+        '409':
+          description: User already exists
+
+    get:
+      summary: List all users (admin only)
+      description: Returns paginated list of users
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 10
+        - name: search
+          in: query
+          schema:
+            type: string
+        - name: role
+          in: query
+          schema:
+            type: string
+            enum: [user, admin]
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        email:
+                          type: string
+                        name:
+                          type: string
+                        role:
+                          type: string
+                        created_at:
+                          type: string
+                          format: date-time
+                  pagination:
+                    type: object
+                    properties:
+                      offset:
+                        type: integer
+                      limit:
+                        type: integer
+                      total:
+                        type: integer
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+    delete:
+      summary: Delete users (admin only)
+      description: Delete multiple users by their IDs
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                userIds:
+                  type: array
+                  items:
+                    type: string
+              required:
+                - userIds
+      responses:
+        '200':
+          description: Users deleted successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  deletedCount:
+                    type: integer
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+  /api/auth/sessions:
+    post:
+      summary: User login
+      description: Authenticates user and returns access token
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+      responses:
+        '200':
+          description: Login successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                      email:
+                        type: string
+                      name:
+                        type: string
+                      emailVerified:
+                        type: boolean
+                      createdAt:
+                        type: string
+                        format: date-time
+                      updatedAt:
+                        type: string
+                        format: date-time
+                  accessToken:
+                    type: string
+        '401':
+          description: Invalid credentials
+
+  /api/auth/sessions/current:
+    get:
+      summary: Get current user
+      description: Returns the currently authenticated user
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Current user info
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      email:
+                        type: string
+                      name:
+                        type: string
+                      role:
+                        type: string
+        '401':
+          description: Unauthorized
+
+  /api/auth/admin/sessions:
+    post:
+      summary: Admin login
+      description: Authenticates admin user for dashboard access
+      tags:
+        - Admin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+      responses:
+        '200':
+          description: Admin login successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accessToken:
+                    type: string
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      email:
+                        type: string
+                      name:
+                        type: string
+                      role:
+                        type: string
+                        enum: [admin]
+        '401':
+          description: Invalid credentials
+        '403':
+          description: User is not an admin
+
+  /api/auth/admin/sessions/exchange:
+    post:
+      summary: Exchange cloud provider authorization code for admin session
+      description: Verifies an authorization code/JWT from from Insforge Cloud platform and issues an internal admin session token with project_admin role
+      tags:
+        - Admin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - code
+              properties:
+                code:
+                  type: string
+                  description: Authorization code or JWT from the Insforge
+                  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+      responses:
+        '200':
+          description: Cloud authorization verified, admin session created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accessToken:
+                    type: string
+                    description: Internal JWT for admin authentication
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                      email:
+                        type: string
+                      name:
+                        type: string
+                        example: Administrator
+                      emailVerified:
+                        type: boolean
+                      createdAt:
+                        type: string
+                        format: date-time
+                      updatedAt:
+                        type: string
+                        format: date-time
+        '400':
+          description: Invalid authorization code or JWT verification failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/auth/tokens/anon:
+    post:
+      summary: Generate anonymous token
+      description: Generate a non-expiring anonymous JWT token for public API access (admin only)
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Anonymous token generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accessToken:
+                    type: string
+                    description: Non-expiring anonymous JWT token
+                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+                  message:
+                    type: string
+                    description: Success message
+                    example: "Anonymous token generated successfully (never expires)"
+        '401':
+          description: Unauthorized - requires authentication
+        '403':
+          description: Forbidden - admin access required
+
+  /api/auth/oauth/google:
+    get:
+      summary: Initiate Google OAuth flow
+      tags:
+        - Client
+      parameters:
+        - name: redirect_uri
+          in: query
+          schema:
+            type: string
+            format: uri
+          description: URL to redirect after authentication
+      responses:
+        '302':
+          description: Redirect to Google OAuth
+        '500':
+          description: OAuth not configured
+
+  /api/auth/oauth/github:
+    get:
+      summary: Initiate GitHub OAuth flow
+      tags:
+        - Client
+      parameters:
+        - name: redirect_uri
+          in: query
+          schema:
+            type: string
+            format: uri
+          description: URL to redirect after authentication
+      responses:
+        '302':
+          description: Redirect to GitHub OAuth
+        '500':
+          description: OAuth not configured
+
+  /api/auth/oauth/shared/callback:
+    get:
+      summary: Shared OAuth callback handler
+      description: Handles OAuth callbacks from all providers
+      tags:
+        - Client
+      parameters:
+        - name: code
+          in: query
+          schema:
+            type: string
+          description: Authorization code from OAuth provider
+        - name: state
+          in: query
+          schema:
+            type: string
+          description: JWT encoded state with provider and redirect URL
+        - name: token
+          in: query
+          schema:
+            type: string
+          description: Direct ID token (for Google)
+      responses:
+        '302':
+          description: Redirect with access token and user info in query params
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+
+  /api/auth/oauth/{provider}/callback:
+    get:
+      summary: Provider-specific OAuth callback
+      description: Alternative callback endpoint for specific providers
+      tags:
+        - Client
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github]
+        - name: code
+          in: query
+          schema:
+            type: string
+        - name: state
+          in: query
+          schema:
+            type: string
+        - name: token
+          in: query
+          schema:
+            type: string
+      responses:
+        '302':
+          description: Redirect with access token
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    apiKey:
+      type: apiKey
+      in: header
+      name: x-api-key
+  
+  schemas:
+    AuthRecord:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        passwordHash:
+          type: string
+          description: SHA256 hash of password
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    
+    ProfileRecord:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        authId:
+          type: string
+          format: uuid
+          description: Foreign key to auth table
+        name:
+          type: string
+        avatar_url:
+          type: string
+          nullable: true
+        bio:
+          type: string
+          nullable: true
+        metadata:
+          type: object
+          description: JSONB field for flexible data
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    
+    ErrorResponse:
+      type: object
+      required:
+        - error
+        - message
+        - statusCode
+      properties:
+        error:
+          type: string
+          description: Error code for programmatic handling
+          example: "VALIDATION_ERROR"
+        message:
+          type: string
+          description: Human-readable error message
+          example: "Email is already in use"
+        statusCode:
+          type: integer
+          description: HTTP status code
+          example: 400
+        nextActions:
+          type: string
+          description: Suggested action to resolve the error
+          example: "Please use a different email address"