openapi: 3.0.3
info:
  title: Shoehorn Users & Directory API
  description: |
    User directory, authentication status, group management, and role mappings.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  # --- Authentication ---
  /auth/cli/status:
    get:
      summary: Get authentication status
      description: Returns the current authentication state for CLI sessions.
      tags: [Authentication]
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated: { type: boolean }
                  user:
                    type: object
                    properties:
                      email: { type: string }
                      name: { type: string }
                      tenant_id: { type: string }
                  expires_at: { type: string, format: date-time }

  # --- Current User ---
  /me:
    get:
      summary: Get current user profile
      description: Returns the authenticated user's profile, team memberships, and group claims.
      tags: [Users]
      responses:
        '200':
          description: Current user profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string, format: uuid }
                  email: { type: string }
                  name: { type: string }
                  picture: { type: string }
                  tenant_id: { type: string }
                  teams:
                    type: array
                    items: { type: string }
                    description: Team slugs the user belongs to
                  groups:
                    type: array
                    items: { type: string }
                    description: IdP group names from JWT claims
                  roles:
                    type: array
                    items: { type: string }

  # --- Users Directory ---
  /users:
    get:
      summary: List users
      description: Returns all users in the tenant directory.
      tags: [Users]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 50, maximum: 200 }
        - name: cursor
          in: query
          schema: { type: string }
        - name: search
          in: query
          schema: { type: string, description: Search by name or email }
      responses:
        '200':
          description: User directory
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items: { $ref: '#/components/schemas/User' }

  /users/{id}:
    get:
      summary: Get user by ID
      description: Returns a user's profile including group memberships and roles.
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserDetail' }
        '404':
          description: User not found

  # --- Groups ---
  /groups:
    get:
      summary: List IdP groups
      description: Returns all identity provider groups known to the system.
      tags: [Groups]
      responses:
        '200':
          description: IdP groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items: { $ref: '#/components/schemas/Group' }

  /groups/{groupName}/roles:
    get:
      summary: Get group role mappings
      description: Returns roles assigned to a specific IdP group.
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Roles mapped to this group
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items: { type: string }

    post:
      summary: Assign role to group
      description: Maps a role to an IdP group. All users in the group receive this role.
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role: { type: string }
      responses:
        '201':
          description: Role assigned to group

  /groups/{groupName}/roles/{roleName}:
    delete:
      summary: Remove role from group
      tags: [Groups]
      parameters:
        - name: groupName
          in: path
          required: true
          schema: { type: string }
        - name: roleName
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Role removed from group

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string, format: uuid }
        email: { type: string }
        name: { type: string }
        picture: { type: string }
        last_login: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    UserDetail:
      type: object
      properties:
        id: { type: string, format: uuid }
        email: { type: string }
        name: { type: string }
        picture: { type: string }
        tenant_id: { type: string }
        teams:
          type: array
          items: { type: string }
        groups:
          type: array
          items: { type: string }
        roles:
          type: array
          items: { type: string }
        last_login: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    Group:
      type: object
      properties:
        name: { type: string }
        provider: { type: string, enum: [zitadel, okta, entra-id, keycloak] }
        member_count: { type: integer }
        roles:
          type: array
          items: { type: string }
