commit 70ac81103523d83f490eab72d54737f051b4aeba
parent 12cf81fa0954c3331cddae561dd9d3055955f914
Author: Yannick Rehberger <yr@ityreh.de>
Date: Thu, 30 Apr 2026 19:24:32 +0200
do not ignore openapi output
Diffstat:
2 files changed, 387 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,3 @@
taler-mailbox
config.status
Makefile
-doc/swagger.json
diff --git a/doc/swagger.json b/doc/swagger.json
@@ -0,0 +1,386 @@
+{
+ "components": {
+ "schemas": {
+ "mailbox.MailboxMetadata": {
+ "description": "Keys to add/update for a mailbox.",
+ "properties": {
+ "encryption_key": {
+ "description": "The mailbox encryption key.\nThis is an HPKE public key\nin the X25519 format for use\nin a X25519-DHKEM (RFC 9180).\nBase32 crockford-encoded.",
+ "type": "string"
+ },
+ "encryption_key_type": {
+ "description": "Type of key.\nOptional, as currently only\nX25519 keys are supported.",
+ "type": "string"
+ },
+ "expiration": {
+ "$ref": "#/components/schemas/mailbox.Timestamp"
+ },
+ "info": {
+ "description": "Info field (e.g for Keyoxide claim proof)",
+ "type": "string"
+ },
+ "signing_key": {
+ "description": "The mailbox signing key.\nNote that $H_MAILBOX == H(singingKey).\nNote also how this key cannot be updated\nas it identifies the mailbox.",
+ "type": "string"
+ },
+ "signing_key_type": {
+ "description": "Type of key.\nOptional, as currently only\nEdDSA keys are supported.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "mailbox.MailboxRegistrationRequest": {
+ "properties": {
+ "mailbox_metadata": {
+ "$ref": "#/components/schemas/mailbox.MailboxMetadata"
+ },
+ "signature": {
+ "description": "Signature by the mailbox's signing key affirming\nthe update of keys, of purpose\nTALER_SIGNATURE_WALLET_MAILBOX_KEYS_UPDATE.\nThe signature is created over the SHA-512 hash\nof (encryptionKeyType||encryptionKey||expiration)",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "mailbox.RelativeTime": {
+ "description": "How long will the service store a message\nbefore giving up",
+ "properties": {
+ "d_us": {
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "mailbox.Timestamp": {
+ "description": "Expiration of this mapping (UNIX Epoch seconds).",
+ "properties": {
+ "t_s": {
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "mailbox.VersionResponse": {
+ "properties": {
+ "delivery_period": {
+ "$ref": "#/components/schemas/mailbox.RelativeTime"
+ },
+ "free_message_quota": {
+ "description": "How many messages can be send and\nare stored by the service for free.\nAfter the quota is reached, the\nregular message_fee applies.\nMay be 0 for no free quota.",
+ "type": "string"
+ },
+ "message_body_bytes": {
+ "description": "Fixed size of message bodies",
+ "type": "integer"
+ },
+ "message_fee": {
+ "description": "How much is the cost to send a single\nmessage to a mailbox.\nMay be 0 for free message sending.",
+ "type": "string"
+ },
+ "message_response_limit": {
+ "description": "How many messages will a single response\ncontain at maximum.",
+ "type": "integer"
+ },
+ "monthly_fee": {
+ "description": "How much is the cost of a single\nregistration period (30 days) of a mailbox\nMay be 0 for a free registration.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Name of the protocol.",
+ "type": "string"
+ },
+ "registration_update_fee": {
+ "description": "How much is the cost of a single\nregistration (update) of a mailbox\nMay be 0 for a free update/registration.",
+ "type": "string"
+ },
+ "version": {
+ "description": "libtool-style representation of the Mailbox protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "info": {
+ "contact": {
+ "url": "https://taler.net"
+ },
+ "description": "The Taler Mailbox service provides encrypted message delivery to wallets identified by their public key.",
+ "license": {
+ "name": "AGPL-3.0-or-later",
+ "url": "https://www.gnu.org/licenses/agpl-3.0.html"
+ },
+ "title": "Taler Mailbox API",
+ "version": ""
+ },
+ "externalDocs": {
+ "description": "",
+ "url": ""
+ },
+ "paths": {
+ "/config": {
+ "get": {
+ "description": "Returns service metadata including fees, message size limits, and delivery period.",
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/mailbox.VersionResponse"
+ }
+ }
+ },
+ "description": "OK"
+ }
+ },
+ "summary": "Get service configuration",
+ "tags": [
+ "config"
+ ]
+ }
+ },
+ "/info/{h_mailbox}": {
+ "get": {
+ "description": "Returns the signing and encryption key metadata for the given mailbox.",
+ "parameters": [
+ {
+ "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
+ "in": "path",
+ "name": "h_mailbox",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/mailbox.MailboxMetadata"
+ }
+ }
+ },
+ "description": "OK"
+ },
+ "404": {
+ "description": "Mailbox not found or expired"
+ }
+ },
+ "summary": "Get mailbox info",
+ "tags": [
+ "mailbox"
+ ]
+ }
+ },
+ "/register": {
+ "post": {
+ "description": "Registers a new mailbox or updates the keys/expiration of an existing one.\nA valid EdDSA signature over the key material must be provided.",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "oneOf": [
+ {
+ "type": "object"
+ },
+ {
+ "$ref": "#/components/schemas/mailbox.MailboxRegistrationRequest",
+ "summary": "body",
+ "description": "Registration request"
+ }
+ ]
+ }
+ }
+ },
+ "description": "Registration request",
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Registration confirmed"
+ },
+ "304": {
+ "description": "Nothing changed"
+ },
+ "400": {
+ "description": "Invalid request body or signature"
+ },
+ "402": {
+ "description": "Payment required"
+ },
+ "500": {
+ "description": "Internal Server Error"
+ }
+ },
+ "summary": "Register or update mailbox",
+ "tags": [
+ "mailbox"
+ ]
+ }
+ },
+ "/{h_mailbox}": {
+ "get": {
+ "description": "Returns up to MessageResponseLimit encrypted message bodies for the given mailbox.\nThe ETag response header contains the serial number of the first message.",
+ "parameters": [
+ {
+ "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
+ "in": "path",
+ "name": "h_mailbox",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "format": "binary",
+ "type": "string"
+ }
+ }
+ },
+ "description": "One or more message bodies concatenated"
+ },
+ "204": {
+ "description": "No messages available"
+ },
+ "404": {
+ "description": "Mailbox not found"
+ }
+ },
+ "summary": "Retrieve messages",
+ "tags": [
+ "mailbox"
+ ]
+ },
+ "post": {
+ "description": "Stores an encrypted message body for the given mailbox. The body must be\nexactly MessageBodyBytes in size.",
+ "parameters": [
+ {
+ "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
+ "in": "path",
+ "name": "h_mailbox",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "format": "binary",
+ "type": "string"
+ }
+ },
+ "text/plain": {
+ "schema": {
+ "title": "body",
+ "type": "string"
+ }
+ }
+ },
+ "description": "Encrypted message body (fixed size)",
+ "required": true
+ },
+ "responses": {
+ "204": {
+ "description": "Message stored"
+ },
+ "304": {
+ "description": "Identical message already stored"
+ },
+ "400": {
+ "description": "Missing or wrong-size body"
+ },
+ "402": {
+ "description": "Payment required (free quota exceeded)"
+ },
+ "500": {
+ "description": "Internal Server Error"
+ }
+ },
+ "summary": "Send a message",
+ "tags": [
+ "mailbox"
+ ]
+ }
+ },
+ "/{mailbox}": {
+ "delete": {
+ "description": "Deletes one or more messages starting from the serial given in the If-Match header.\nRequires a valid EdDSA signature in the Taler-Mailbox-Delete-Signature header.",
+ "parameters": [
+ {
+ "description": "Crockford base32-encoded EdDSA public key of the mailbox",
+ "in": "path",
+ "name": "mailbox",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "description": "Number of messages to delete (default: 1)",
+ "in": "query",
+ "name": "count",
+ "schema": {
+ "type": "integer"
+ }
+ },
+ {
+ "description": "Serial number of the first message to delete",
+ "in": "header",
+ "name": "If-Match",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "description": "EdDSA signature authorising the deletion",
+ "in": "header",
+ "name": "Taler-Mailbox-Delete-Signature",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "Messages deleted"
+ },
+ "400": {
+ "description": "Missing or malformed headers/parameters"
+ },
+ "403": {
+ "description": "Signature invalid"
+ },
+ "404": {
+ "description": "Message with given serial not found"
+ },
+ "500": {
+ "description": "Internal Server Error"
+ }
+ },
+ "summary": "Delete messages",
+ "tags": [
+ "mailbox"
+ ]
+ }
+ }
+ },
+ "openapi": "3.1.0",
+ "servers": [
+ {
+ "url": "/"
+ }
+ ]
+}
+\ No newline at end of file
