openapi: 3.1.0
info:
  title: Hara Exchange HaraGate Admin API
  version: 0.3.0
  description: |
    Stable REST surface that any Information System (IS) talks to via its local
    HaraGate. SDKs for TypeScript / Python / Java / Kotlin / Go / Rust are
    auto-generated from this spec.

    The full Hara Exchange protocol is documented in `docs/haraxchange-product-guidelines-v3.md`
    and the `did:hara:` method spec at `docs/did-hara-method-spec-v0.9.md`.
servers:
  - url: http://localhost:8443
    description: Local development HaraGate (Bank BRI)

paths:
  /health:
    get:
      summary: Liveness probe
      responses: { '200': { description: ok } }

  /admin/info:
    get:
      summary: Identity, key fingerprints, contracts, configuration of this node
      responses: { '200': { description: ok } }

  /admin/log:
    get:
      summary: Recent message log entries with the current Merkle root
      parameters:
        - { in: query, name: limit, schema: { type: integer, default: 50 } }
      responses: { '200': { description: ok } }

  /admin/refresh:
    post:
      summary: Hot-refresh the on-chain MemberRegistry cache
      responses: { '200': { description: refreshed } }

  /admin/exchange:
    post:
      summary: Initiate an outbound exchange to a peer HaraGate
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExchangeRequest' }
      responses:
        '200': { description: ok, content: { application/json: { schema: { $ref: '#/components/schemas/ExchangeResponse' } } } }
        '403': { description: refused (consent / access / compliance) }

  /hx/v1/incoming:
    post:
      summary: Inbound peer-to-peer envelope (called only by other HaraGates)
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SignedEnvelope' }
      responses: { '200': { description: ok }, '403': { description: refused } }

  /metrics:
    get:
      summary: Prometheus metrics
      responses: { '200': { description: ok } }

components:
  schemas:
    ExchangeRequest:
      type: object
      required: [providerDid, service, subject, purpose]
      properties:
        providerDid: { type: string, example: 'did:hara:org:dev-hara' }
        service:     { type: string, example: 'did:hara:service:hara-farmer-profile-v2' }
        subject:     { type: string, example: 'did:hara:person:dev-ahmad-fauzi' }
        purpose:     { type: string, example: 'credit_assessment' }
        body:        { type: object, additionalProperties: true }
    ExchangeResponse:
      type: object
      properties:
        _hx:
          type: object
          properties:
            exchangeId: { type: string }
            consentId:  { type: string }
            durationMs: { type: integer }
        # provider-specific keys flow alongside _hx
      additionalProperties: true
    SignedEnvelope:
      type: object
      required: [sender, receiver, issuedAt, nonce, service, subject, purpose]
      properties:
        sender:    { type: string }
        receiver:  { type: string }
        issuedAt:  { type: integer }
        nonce:     { type: string }
        service:   { type: string }
        subject:   { type: string }
        purpose:   { type: string }
        body:      { type: object, additionalProperties: true }
        sig:       { type: string, description: 'hex(ed25519 || ml-dsa-65)' }