openapi: 3.1.0
info:
  title: Verae Application Client API
  version: 0.1.0
  description: |
    Digests-only Application Client API for non-AI apps. Paths below are **logical**
    documentation identifiers for the client SDKs (Python / TypeScript); they are **not**
    deployed server routes on `mcp.verae.ai` in this phase.

    **Defaults:** MCP Streamable HTTP `https://mcp.verae.ai/mcp`; VeraeTime
    `https://api.veraetime.net`.

    **Digests only:** stamp / verify / hash_report accept SHA-256 digests. SDKs refuse
    arguments named `content`, `bytes`, `file`, `data`, `path`, `body`, `payload`,
    `blob`, or `archive`.

    **Global stamp:** VeraeTime body uses `restamp: false` and omits metadata unless
    the caller passes `metadata` or `restamp`. Those calls send a `verae-meta-git/1`
    history. Local and shared stamps reject metadata.

    ## Mapping appendix (MCP ↔ VeraeTime ↔ Application API)

    | Application op | MCP tool | VeraeTime |
    | --- | --- | --- |
    | stamp local/shared | `stamp` | — |
    | stamp global | — | `POST /api/timestamp` |
    | verify (non-global) | `verify` | — |
    | verify global | — | `POST /api/verify` |
    | hash_report (non-global) | `hash_report` | — |
    | hash_report global | — | `GET /api/hash/{sha256}` |
    | signup | (`signup` exists on MCP; apps use direct) | `POST /auth/signup` |
    | login | (`login` exists on MCP; apps use direct) | `POST /auth/login` |
    | session | (`session` exists on MCP; apps use direct) | `GET /auth/validate` |
    | create_user | (`create_user` exists on MCP; apps use direct) | `POST /auth/users` |

    Routing: `local` / `shared` stamp and non-global verify / hash_report use MCP.
    `global` / `want_scope=global` use VeraeTime directly. Verify also uses VeraeTime when
    `receipt_id` looks like an IPFS CID (`Qm…`, `bafy…`, `bafk…`). Auth ops always hit
    VeraeTime with caller-held JWTs.
servers:
  - url: https://mcp.verae.ai
    description: >
      Logical base for documentation only. Application Client SDK paths are not
      deployed HTTP routes; local/shared ops use MCP at https://mcp.verae.ai/mcp.
  - url: https://api.veraetime.net
    description: >
      VeraeTime direct HTTPS for global stamp/verify/hash_report and all auth ops.
      Application Client paths still map to /api/* and /auth/* as in the appendix.
paths:
  /stamp:
    post:
      operationId: stamp
      summary: Stamp a SHA-256 digest
      description: |
        Request a timestamp for a digest. Scope `local` or `shared` goes to MCP tool
        `stamp`; scope `global` goes to VeraeTime `POST /api/timestamp`. The default
        body is digest-only with `restamp: false`. `metadata` or `restamp` sends a
        `verae-meta-git/1` history.
      tags: [timestamping]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StampRequest"
      responses:
        "200":
          description: One or more normalized receipts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampResponse"
  /verify:
    post:
      operationId: verify
      summary: Verify a receipt
      description: |
        Verify by `receipt_id`. Routes to VeraeTime `POST /api/verify` when
        `want_scope=global` or `receipt_id` looks like an IPFS CID (`Qm…`, `bafy…`,
        `bafk…`); otherwise MCP tool `verify`.
      tags: [timestamping]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyRequest"
      responses:
        "200":
          description: Verification result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyResponse"
  /hash_report:
    post:
      operationId: hash_report
      summary: List receipts for a digest
      description: |
        History for a SHA-256 digest. `want_scope=global` uses VeraeTime
        `GET /api/hash/{sha256}`; otherwise MCP tool `hash_report`. Empty history
        is `{ "receipts": [] }`.
      tags: [timestamping]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HashReportRequest"
      responses:
        "200":
          description: Receipts for the digest (possibly empty)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HashReportResponse"
  /signup:
    post:
      operationId: signup
      summary: Create an account on VeraeTime
      description: |
        Always `POST https://api.veraetime.net/auth/signup`. Does not replace the
        stored JWT; caller must `login` for a session.
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignupRequest"
      responses:
        "200":
          description: Created user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthUserResponse"
  /login:
    post:
      operationId: login
      summary: Login and obtain caller-held JWT
      description: |
        Always `POST https://api.veraetime.net/auth/login`. SDK stores JWT in
        caller-local secure storage (`~/.verae/auth.properties` on native). JWT
        values are never logged.
      tags: [auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Authenticated user session metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthUserResponse"
  /session:
    get:
      operationId: session
      summary: Validate current session
      description: |
        Always `GET https://api.veraetime.net/auth/validate` with bearer from
        constructor, `VERAE_GLOBAL_TOKEN`, or auth.properties.
      tags: [auth]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Session validity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
  /create_user:
    post:
      operationId: create_user
      summary: Create a user (admin)
      description: |
        Always `POST https://api.veraetime.net/auth/users`. Requires admin bearer.
      tags: [auth]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "200":
          description: Created user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthUserResponse"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Caller-held VeraeTime JWT (never logged).
  schemas:
    Receipt:
      type: object
      description: Shared normalized receipt object across MCP and VeraeTime.
      required:
        - receipt_id
        - hash
        - scope
        - created_at
        - merkle
      properties:
        receipt_id:
          type: string
          description: Local id or VeraeTime certificate CID
        hash:
          type: string
          description: SHA-256 hex (64 characters)
          pattern: "^[0-9a-fA-F]{64}$"
        scope:
          type: string
          description: local, shared, or global
          enum: [local, shared, global]
        cube_id:
          type: string
          description: Optional; local metadata
        org_id:
          type: string
          description: Optional; local idempotency key; ignored by VeraeTime
        created_at:
          type: string
          description: Timestamp when available
        merkle:
          type: string
          description: Block hash / index when available
        restamp_of:
          type: string
          description: Prior certificate when restamped
    StampRequest:
      type: object
      required: [sha256]
      additionalProperties: false
      properties:
        sha256:
          type: string
          description: >
            SHA-256 digest (64 hex). Optional `sha256:` prefix is stripped by SDKs.
          minLength: 64
        scope:
          type: string
          description: Default local. global → VeraeTime. Metadata history is global only.
          enum: [local, shared, global]
          default: local
        cube_id:
          type: string
        org_id:
          type: string
        metadata:
          type: object
          description: >
            Plain object or a verae-meta-git/1 document. Blank values do not delete
            fields. Omitted on a digest-only stamp.
          additionalProperties: true
        restamp:
          type: boolean
          description: >
            When true, append metadata onto the previous global stamp for this digest.
          default: false
        message:
          type: string
          description: History commit message.
    StampResponse:
      type: object
      required: [receipts]
      properties:
        receipts:
          type: array
          items:
            $ref: "#/components/schemas/Receipt"
    VerifyRequest:
      type: object
      required: [receipt_id]
      additionalProperties: false
      properties:
        receipt_id:
          type: string
        want_scope:
          type: string
          description: >
            Set to global to force VeraeTime verify. CID-shaped receipt_id
            (Qm… / bafy… / bafk…) also uses VeraeTime without this flag.
          enum: [local, shared, global]
    VerifyResponse:
      type: object
      required: [valid, error, receipt]
      properties:
        valid:
          type: boolean
        error:
          type: string
          nullable: true
        receipt:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/Receipt"
    HashReportRequest:
      type: object
      required: [sha256]
      additionalProperties: false
      properties:
        sha256:
          type: string
          description: SHA-256 digest (64 hex; optional sha256: prefix stripped)
          minLength: 64
        org_id:
          type: string
        want_scope:
          type: string
          description: Set to global to force VeraeTime hash lookup.
          enum: [local, shared, global]
    HashReportResponse:
      type: object
      required: [receipts]
      properties:
        receipts:
          type: array
          items:
            $ref: "#/components/schemas/Receipt"
    SignupRequest:
      type: object
      required: [username, password]
      additionalProperties: false
      properties:
        username:
          type: string
        password:
          type: string
          format: password
    LoginRequest:
      type: object
      required: [username, password]
      additionalProperties: false
      properties:
        username:
          type: string
        password:
          type: string
          format: password
    AuthUserResponse:
      type: object
      required: [username, role]
      properties:
        id:
          type: string
        username:
          type: string
        role:
          type: string
        expires_at:
          type: string
    SessionResponse:
      type: object
      required: [valid]
      properties:
        valid:
          type: boolean
        username:
          type: string
        role:
          type: string
        expires_at:
          type: string
    CreateUserRequest:
      type: object
      required: [username, password, role]
      additionalProperties: false
      properties:
        username:
          type: string
        password:
          type: string
          format: password
        role:
          type: string
          enum: [user, admin]
tags:
  - name: timestamping
    description: Digests-only stamp, verify, and hash history
  - name: auth
    description: VeraeTime-direct account and session operations