donau API update

1 files changed, 75 insertions, 76 deletions

diff --git a/core/api-donau.rst b/core/api-donau.rst
index 69659eea..049ac2ef 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -28,9 +28,10 @@ defines all specific terms used in this section.
 
 .. _donau-overview:
 
-------------------------
+------------
 API Overview
-------------------------
+------------
+
 This is intended to provide a quick overview of the whole REST API. For a more detailed view of the protocol, see the protocol specification.
 
 The chapters group the families of requests frequently encountered when using the donau API:
@@ -47,16 +48,16 @@ The chapters group the families of requests frequently encountered when using th
 
 .. _donau_status:
 
---------------------------------------------
+----------------------------------------
 Donau public keys and status information
---------------------------------------------
+----------------------------------------
 
 This API is used by donors and charities to obtain global information about
-the Donau, such as online signing keys and available donation units.  This is typically the first call any Donau client makes, as it
-returns information required to process all of the other interactions with the
-Donau.  The returned information is secured by signature(s) from the Donau,
-especially the long-term offline signing key of the Donau, which clients
-should cache.
+the Donau, such as online signing keys and available donation units.  This is
+typically the first call any Donau client makes, as it returns information
+required to process all of the other interactions with the Donau.  The
+returned information is secured by signature(s) from the Donau, especially the
+long-term offline signing key of the Donau, which clients should cache.
 
 .. http:get:: /keys
 
@@ -250,9 +251,9 @@ should cache.
 
 .. _donau_issue:
 
-----------------------------------------
+--------------
 Issue receipts
-----------------------------------------
+--------------
 
 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`.
 
@@ -297,30 +298,31 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
 
     interface BDID {
       donau_pub_hash: HashCode;
-      taxid_hashed: HashCode;
-      nonce: string;
+      taxpayer_blinded_id: CoinEnvelope; // maybe copy+paste data type and rename it
+      taxid_hashed: HashCode; // NO: needs to be blinded hash: FDH_n(H(taxid,salt), nonce) * b^e mod n
+      nonce: string; // NO!
     }
 
   .. ts:def:: BSDonationReceipts
 
     interface DonationReceipts {
-      blind_signed_receipt_signatures: DonationReceiptEnvelope[];
+      blind_signed_receipt_signatures: DonationReceiptSignature[];
     }
 
-  .. ts:def:: DonationReceiptEnvelope
+  .. ts:def:: DonationReceiptSignature // FIXME: see BlindedDenominationSignature, not Envelope!!
     
-    type DonationReceiptEnvelope = RSADonationReceiptEnvelope | CSDonationReceiptEnvelope ;
+    type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ;
 
-  .. ts:def:: RSADonationReceiptEnvelope
+  .. ts:def:: RSADonationReceiptSignature
 
-    interface RSADonationReceiptEnvelope {
+    interface RSADonationReceiptSignature {
       cipher: "RSA";
       rsa_blinded_donation_receipt_sig: string;          // Crockford Base32 encoded
     }
 
-  .. ts:def:: CSDonationReceiptEnvelope
+  .. ts:def:: CSDonationReceiptSignature
 
-    interface CSDonationReceiptEnvelope {
+    interface CSDonationReceiptSignature {
       cipher: "CS";
       cs_nonce: string;      // Crockford Base32 encoded
       cs_blinded_c0: string; // Crockford Base32 encoded
@@ -352,9 +354,10 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau
 
 .. _donau_submit:
 
------------------------------
+---------------
 Submit receipts
------------------------------
+---------------
+
 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
 
 .. http:POST:: /submit
@@ -372,19 +375,22 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
   :http:statuscode:`403 Forbidden`:
     One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
-    At least one of the donation unit keys is not known to the donau. Comes with a `DonationUnitUnknownError`.
+    At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
   :http:statuscode:`409 Conflict`:
     The submit operation has failed because a unique donor id was already submitted. Comes with a `DonationReceiptDoubleSpendError`.
   :http:statuscode:`410 Gone`:
-    The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.
+    The requested donation unit key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.  FIXME: text does not match our use case well.
 
   **Details:**
 
-  .. ts:def:: SubmitRequest
+  .. ts:def:: SubmitRequest // Bad name
 
     interface SubmitRequest{
+      // hashed taxpayer ID plus salt 
       taxnr_hashed: HashCode;
+      // All donation receipts must be for this year.
       year: Integer;
+      // Receipts should be sorted by amount.
       donation_receipts: DonationReceipt[];
     }
 
@@ -393,8 +399,7 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
     interface DonationReceipt{
       donation_unit_pub_hash: HashCode;
       nonce: string;
-      taxid_hashed: HashCode;
-      donau_sig: RsaSignature | Edx25519Signature
+      donau_sig: RsaDonationSignature | CSDonationSignature; // There is a data type for this (without |), see DenoninationSignaure, better: DonationSignature
     }
 
   .. ts:def:: SubmitResponse
@@ -405,6 +410,7 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
       signature: EddsaSignature;
     }
 
+  // Consider removing, always return SubmitResponse over *accepted* total.
   .. ts:def:: DonationReceiptDoubleSpendError
 
     interface DonationReceiptDoubleSpendError{
@@ -414,16 +420,19 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`.
 
 .. _donau_charity:
 
-----------------------------------------------
+---------------------------------------------
 Charity administration and status information
-----------------------------------------------
-.. http:GET::  /charities   
-  
+---------------------------------------------
+
+.. http:GET::  /charities
+
   return all charities
 
-  **Request:** 
+  **Request:**
+
+  FIXME: Authentication header? authorization? 
 
-  **Reponse:** 
+  **Reponse:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `Charities`.  
@@ -433,17 +442,16 @@ Charity administration and status information
   .. ts:def:: Charities
 
     interface Charities{
-      charities: Charity[];
+      charities: CharitySummary[];
     }
 
-  .. ts:def:: Charity
+  .. ts:def:: CharitySummary
 
-    interface Charity{
+    interface CharitySummary{
       charity_id: Integer;
-      pub_key: RsaPublicKey;
+      name: string;
       max_per_year: Amount;
-      current_year: Amount; 
-      receipts_to_date: Integer;
+      receipts_to_date: Amount;
     }
 
 .. _donau_charity_get:
@@ -458,12 +466,26 @@ Charity administration and status information
 
   :http:statuscode:`200 OK`:
     The donau responds with a `Charity` object
-  :http:statuscode:`400 Bad request`:
-    The charity id is malformed.
   :http:statuscode:`404 Not found`:
     The charity id does not belong to a charity known to the donau.
 
-.. http:POST:: /charities
+  .. ts:def:: Charity
+
+    interface Charity {
+      name: string;
+      pub_key: EddsaPublicKey;
+      max_per_year: Amount;
+      donation_history: CharityHistoryYear[];
+    }
+
+  .. ts:def:: CharityHistoryYear
+
+    interface CharityHistoryYear {
+      year: Integer;
+      final_amout: Amount;
+    }
+
+  .. http:POST:: /charities
 
   Add a charity
 
@@ -475,16 +497,13 @@ Charity administration and status information
 
   :http:statuscode:`201 Created`:
     The request was successful, and the response is a `CharityResponse`.
-  :http:statuscode:`400 Bad request`:
-    The charity content is malformed.
 
   .. ts:def:: CharityRequest
   
     interface CharityRequest{
-      pub_key: RsaPublicKey;
+      pub_key: EddsaPublicKey;
       max_per_year: Amount;
-      current_year: Amount; 
-      receipts_to_date: Integer;
+      name: string;
     }
 
   .. ts:def:: CharityResponse
@@ -500,46 +519,26 @@ Charity administration and status information
 
   **Request:** `CharityRequest`
 
+  FIXME: Authentication...
+
   **Response:**
 
   :http:statuscode:`200 OK`:
     The request was successful.
-  :http:statuscode:`400 Bad request`:
-    The charity content is malformed.
-
-.. http:get:: /charities/$CHARITY_ID/history
 
-  Request information about the history of a charity.
 
-  **Request:**
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The Donau responds with a `CharityHistory` object; the charity was known to the Donau.
-  :http:statuscode:`400 Bad request`:
-    The charity id is malformed.
-  :http:statuscode:`404 Not found`:
-    The charity key does not belong to a charity known to the donau.
 
-  **Details:**
+.. http:DELETE:: /charities/{id}
 
-  .. ts:def:: CharityHistory
+  Delete (or deactivate) a charity.
 
-    interface CharityHistory {
-      charityHistoryYears: CharityHistoryYear[];
-      donau_sig: EddsaSignature;
-    }
+  **Request:**
 
-  .. ts:def:: CharityHistoryYear
+  FIXME: Authentication...
 
-    interface CharityHistoryYear {
-      year: Integer;
-      //pub_key: RsaPublicKey;
-      final_amout: Amount;
-      // for statistics
-      max_per_year: Amount;
-     }
+  **Response:**
 
+  :http:statuscode:`200 OK`:
+    The request was successful.