openapi: 3.0.3
info:
  title: EDUT Secret System API
  version: v1
  description: Wallet-first designation and membership activation endpoints.
servers:
  - url: https://api.edut.ai
paths:
  /secret/wallet/intent:
    post:
      summary: Create wallet signature intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletIntentRequest'
      responses:
        '200':
          description: Intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletIntentResponse'
  /secret/wallet/verify:
    post:
      summary: Verify signed intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletVerifyRequest'
      responses:
        '200':
          description: Signature verified
          headers:
            X-Edut-Session:
              schema:
                type: string
              description: Wallet session token for follow-on wallet-scoped APIs.
            X-Edut-Session-Expires-At:
              schema:
                type: string
                format: date-time
              description: Session expiry timestamp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletVerifyResponse'
  /secret/wallet/session/refresh:
    post:
      summary: Rotate wallet session token
      description: Requires a valid wallet session token (`Authorization: Bearer` or `X-Edut-Session`).
      parameters:
        - $ref: '#/components/parameters/WalletSessionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletSessionRefreshRequest'
      responses:
        '200':
          description: Session rotated
          headers:
            X-Edut-Session:
              schema:
                type: string
            X-Edut-Session-Expires-At:
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSessionRefreshResponse'
        '401':
          description: Session missing, invalid, revoked, or expired
  /secret/wallet/session/revoke:
    post:
      summary: Revoke wallet session token
      description: Requires a valid wallet session token (`Authorization: Bearer` or `X-Edut-Session`).
      parameters:
        - $ref: '#/components/parameters/WalletSessionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletSessionRevokeRequest'
      responses:
        '200':
          description: Session revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSessionRevokeResponse'
        '401':
          description: Session missing, invalid, revoked, or expired
  /secret/membership/quote:
    post:
      summary: Get current membership mint quote
      description: Canonical technical route. Public EDUT ID alias is `/secret/id/quote`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipQuoteRequest'
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipQuoteResponse'
  /secret/membership/confirm:
    post:
      summary: Confirm membership mint transaction
      description: Canonical technical route. Public EDUT ID alias is `/secret/id/confirm`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipConfirmRequest'
      responses:
        '200':
          description: Membership active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipConfirmResponse'
  /secret/membership/status:
    get:
      summary: Resolve membership status by wallet or designation code
      description: Canonical technical route. Public EDUT ID alias is `/secret/id/status`.
      parameters:
        - in: query
          name: wallet
          required: false
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - in: query
          name: designation_code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Membership status resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipStatusResponse'
  /secret/id/quote:
    post:
      summary: Get current EDUT ID activation quote
      description: Alias of `/secret/membership/quote`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipQuoteRequest'
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipQuoteResponse'
  /secret/id/confirm:
    post:
      summary: Confirm EDUT ID activation transaction
      description: Alias of `/secret/membership/confirm`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipConfirmRequest'
      responses:
        '200':
          description: EDUT ID active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipConfirmResponse'
  /secret/id/status:
    get:
      summary: Resolve EDUT ID status by wallet or designation code
      description: Alias of `/secret/membership/status`.
      parameters:
        - in: query
          name: wallet
          required: false
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - in: query
          name: designation_code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: EDUT ID status resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipStatusResponse'
components:
  parameters:
    WalletSessionHeader:
      in: header
      name: X-Edut-Session
      required: false
      schema:
        type: string
      description: Wallet session token. `Authorization: Bearer <token>` is also accepted.
  schemas:
    WalletIntentRequest:
      type: object
      required: [address, origin, locale, chain_id]
      properties:
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        origin:
          type: string
          format: uri
        locale:
          type: string
        chain_id:
          type: integer
    WalletIntentResponse:
      type: object
      required: [intent_id, designation_code, display_token, nonce, issued_at, expires_at, chain_id]
      properties:
        intent_id:
          type: string
        designation_code:
          type: string
        display_token:
          type: string
        nonce:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        domain_name:
          type: string
        chain_id:
          type: integer
        verifying_contract:
          type: string
    WalletVerifyRequest:
      type: object
      required: [intent_id, address, chain_id, signature]
      properties:
        intent_id:
          type: string
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
        signature:
          type: string
    WalletVerifyResponse:
      type: object
      required: [status, designation_code, display_token, verified_at, session_token, session_expires_at]
      properties:
        status:
          type: string
          enum: [signature_verified]
        designation_code:
          type: string
        display_token:
          type: string
        verified_at:
          type: string
          format: date-time
        session_token:
          type: string
          description: Wallet-scoped app session token used by marketplace/member/governance APIs.
        session_expires_at:
          type: string
          format: date-time
          description: Session token expiry timestamp.
    WalletSessionRefreshRequest:
      type: object
      required: [wallet]
      properties:
        wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
    WalletSessionRefreshResponse:
      type: object
      required: [status, wallet, session_token, session_expires_at]
      properties:
        status:
          type: string
          enum: [session_refreshed]
        wallet:
          type: string
        session_token:
          type: string
        session_expires_at:
          type: string
          format: date-time
    WalletSessionRevokeRequest:
      type: object
      required: [wallet]
      properties:
        wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
    WalletSessionRevokeResponse:
      type: object
      required: [status, wallet, revoked_at]
      properties:
        status:
          type: string
          enum: [session_revoked]
        wallet:
          type: string
        revoked_at:
          type: string
          format: date-time
    MembershipQuoteRequest:
      type: object
      required: [designation_code, address, chain_id]
      properties:
        designation_code:
          type: string
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
        payer_wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        payer_proof:
          type: string
          description: Owner-signed personal-signature proof for distinct payer wallets.
        sponsor_org_root_id:
          type: string
    MembershipQuoteResponse:
      type: object
      required: [quote_id, chain_id, regulatory_profile_id, currency, amount_atomic, decimals, cost_envelope, deadline, contract_address]
      properties:
        quote_id:
          type: string
        chain_id:
          type: integer
        regulatory_profile_id:
          type: string
          enum: [us_general_2026, eu_ai_act_2026_baseline]
        currency:
          type: string
          enum: [USDC]
        amount_atomic:
          type: string
        decimals:
          type: integer
        cost_envelope:
          $ref: '#/components/schemas/QuoteCostEnvelope'
        deadline:
          type: string
          format: date-time
        contract_address:
          type: string
        method:
          type: string
        calldata:
          type: string
        value:
          type: string
        owner_wallet:
          type: string
        payer_wallet:
          type: string
        sponsorship_mode:
          type: string
          enum: [self, sponsored, sponsored_company]
        sponsor_org_root_id:
          type: string
        tx:
          type: object
          additionalProperties: true
    QuoteCostEnvelope:
      type: object
      required:
        - version
        - checkout_currency
        - checkout_decimals
        - checkout_total_atomic
        - checkout_total
        - provider_fee_policy
        - provider_fee_included
        - provider_fee_estimate_status
        - provider_fee_estimate_atomic
        - network_fee_policy
        - network_fee_currency
        - network_fee_estimate_status
        - network_fee_estimate_atomic
      properties:
        version:
          type: string
          enum: [edut.quote_cost_envelope.v1]
        checkout_currency:
          type: string
        checkout_decimals:
          type: integer
        checkout_total_atomic:
          type: string
        checkout_total:
          type: string
        provider_fee_policy:
          type: string
          enum: [edut_absorbed]
        provider_fee_included:
          type: boolean
        provider_fee_estimate_status:
          type: string
          enum: [absorbed_by_edut]
        provider_fee_estimate_atomic:
          type: string
        network_fee_policy:
          type: string
          enum: [payer_wallet_pays_chain_gas]
        network_fee_currency:
          type: string
          enum: [ETH]
        network_fee_estimate_status:
          type: string
          enum: [wallet_estimate_required]
        network_fee_estimate_atomic:
          type: string
    MembershipConfirmRequest:
      type: object
      required: [designation_code, quote_id, tx_hash, address, chain_id]
      properties:
        designation_code:
          type: string
        quote_id:
          type: string
        tx_hash:
          type: string
          pattern: '^0x[a-fA-F0-9]{64}$'
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
        identity_assurance_level:
          type: string
          enum: [crypto_direct_unattested, sponsored_unattested, onramp_attested]
        identity_attested_by:
          type: string
          description: Optional provider identifier when assurance level is onramp_attested.
        identity_attestation_id:
          type: string
          description: Optional provider attestation reference id.
    MembershipConfirmResponse:
      type: object
      required: [status, designation_code, display_token, regulatory_profile_id, tx_hash, activated_at, identity_assurance_level]
      properties:
        status:
          type: string
          enum: [membership_active]
        designation_code:
          type: string
        display_token:
          type: string
        regulatory_profile_id:
          type: string
          enum: [us_general_2026, eu_ai_act_2026_baseline]
        tx_hash:
          type: string
        activated_at:
          type: string
          format: date-time
        identity_assurance_level:
          type: string
          enum: [none, crypto_direct_unattested, sponsored_unattested, onramp_attested]
        identity_attested_by:
          type: string
        identity_attestation_id:
          type: string
    MembershipStatusResponse:
      type: object
      required: [status, regulatory_profile_id]
      properties:
        status:
          type: string
          enum: [active, none, suspended, revoked, unknown]
        wallet:
          type: string
        designation_code:
          type: string
        regulatory_profile_id:
          type: string
          enum: [us_general_2026, eu_ai_act_2026_baseline]
        identity_assurance_level:
          type: string
          enum: [none, crypto_direct_unattested, sponsored_unattested, onramp_attested]
        identity_attested_by:
          type: string
        identity_attestation_id:
          type: string