394c46ebfcOptional metadata or restamp builds the same commit history as node-red. A call that omits both stays digest-only with restamp false. Local and shared stamps reject metadata.
394 lines
12 KiB
YAML
394 lines
12 KiB
YAML
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
|