openapi: 3.1.0
info:
  title: EDUT Governance Installer API
  version: 1.0.0
  description: |
    Deterministic governance install authorization and package metadata retrieval.
servers:
  - url: https://api.edut.ai
security:
  - WalletSession: []
paths:
  /governance/install/token:
    post:
      summary: Authorize governance install for ownership wallet.
      operationId: createGovernanceInstallToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallTokenRequest'
      responses:
        '200':
          description: Install authorization token and signed package metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallTokenResponse'
        '403':
          description: Membership or governance entitlement inactive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /governance/install/confirm:
    post:
      summary: Confirm successful local install evidence.
      operationId: confirmGovernanceInstall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallConfirmRequest'
      responses:
        '200':
          description: Install confirmed and runtime activation allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallConfirmResponse'
        '409':
          description: Policy mismatch or stale install token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /governance/install/status:
    get:
      summary: Resolve governance activation eligibility and latest runtime package for wallet.
      operationId: getGovernanceInstallStatus
      parameters:
        - in: query
          name: wallet
          required: true
          schema:
            type: string
        - in: query
          name: device_id
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Current governance install and entitlement status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallStatusResponse'
  /governance/lease/heartbeat:
    post:
      summary: Refresh connected-class availability lease for org boundary.
      operationId: refreshGovernanceLeaseHeartbeat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseHeartbeatRequest'
      responses:
        '200':
          description: Lease refreshed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseHeartbeatResponse'
        '403':
          description: Boundary or entitlement invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /governance/lease/offline-renew:
    post:
      summary: Apply signed offline renewal package for sovereign class.
      operationId: applyOfflineRenewalPackage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfflineRenewRequest'
      responses:
        '200':
          description: Offline renewal accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineRenewResponse'
        '409':
          description: Renewal package invalid or stale.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    WalletSession:
      type: http
      scheme: bearer
      bearerFormat: EDUT-WALLET-SESSION
  schemas:
    InstallTokenRequest:
      type: object
      required:
        - wallet
        - device_id
        - launcher_version
        - platform
      properties:
        wallet:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        device_id:
          type: string
        launcher_version:
          type: string
        platform:
          type: string
          enum: [macos, windows, linux]
        current_runtime_version:
          type: string
    InstallTokenResponse:
      type: object
      required:
        - install_token
        - install_token_expires_at
        - wallet
        - entitlement_id
        - package
      properties:
        install_token:
          type: string
        install_token_expires_at:
          type: string
          format: date-time
        wallet:
          type: string
        entitlement_id:
          type: string
        package:
          $ref: '#/components/schemas/GovernancePackage'
    GovernancePackage:
      type: object
      required:
        - runtime_version
        - package_url
        - package_hash
        - signature
        - signer_key_id
        - policy_hash
      properties:
        runtime_version:
          type: string
        package_url:
          type: string
          format: uri
        package_hash:
          type: string
        signature:
          type: string
        signer_key_id:
          type: string
        policy_hash:
          type: string
        rollout_channel:
          type: string
          enum: [stable, canary]
          default: stable
    InstallConfirmRequest:
      type: object
      required:
        - install_token
        - wallet
        - device_id
        - entitlement_id
        - package_hash
        - runtime_version
        - installed_at
      properties:
        install_token:
          type: string
        wallet:
          type: string
        device_id:
          type: string
        entitlement_id:
          type: string
        package_hash:
          type: string
        runtime_version:
          type: string
        installed_at:
          type: string
          format: date-time
        launcher_receipt_hash:
          type: string
    InstallConfirmResponse:
      type: object
      required:
        - status
        - wallet
        - device_id
        - entitlement_id
        - runtime_version
        - activated_at
      properties:
        status:
          type: string
          enum: [governance_active]
        wallet:
          type: string
        device_id:
          type: string
        entitlement_id:
          type: string
        runtime_version:
          type: string
        activated_at:
          type: string
          format: date-time
    InstallStatusResponse:
      type: object
      required:
        - wallet
        - membership_status
        - identity_assurance_level
        - entitlement_status
        - activation_status
      properties:
        wallet:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        membership_status:
          type: string
          enum: [active, none, suspended, revoked, unknown]
        identity_assurance_level:
          type: string
          enum: [none, crypto_direct_unattested, sponsored_unattested, onramp_attested]
        entitlement_status:
          type: string
          enum: [active, none, suspended, revoked, unknown]
        access_class:
          type: string
          enum: [connected, sovereign, unknown]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked, unknown]
        activation_status:
          type: string
          enum: [not_installed, pending, active, blocked]
        latest_runtime_version:
          type: string
        policy_hash:
          type: string
        reason:
          type: string
    LeaseHeartbeatRequest:
      type: object
      required:
        - wallet
        - org_root_id
        - principal_id
        - device_id
      properties:
        wallet:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        device_id:
          type: string
    LeaseHeartbeatResponse:
      type: object
      required:
        - status
        - availability_state
        - lease_expires_at
      properties:
        status:
          type: string
          enum: [lease_refreshed]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked]
        lease_expires_at:
          type: string
          format: date-time
    OfflineRenewRequest:
      type: object
      required:
        - wallet
        - org_root_id
        - principal_id
        - renewal_bundle
      properties:
        wallet:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        renewal_bundle:
          type: object
          additionalProperties: true
    OfflineRenewResponse:
      type: object
      required:
        - status
        - availability_state
        - renewed_until
      properties:
        status:
          type: string
          enum: [renewal_applied]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked]
        renewed_until:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
        code:
          type: string
        correlation_id:
          type: string