plugin overview
diff --git a/docs/dta-plugins/d-ta-plugins.md b/docs/dta-plugins/d-ta-plugins.md
new file mode 100644
index 0000000..610d89b
--- /dev/null
+++ b/docs/dta-plugins/d-ta-plugins.md
@@ -0,0 +1,52 @@
+---
+id: plugins-overview
+title: D-TA Plugins Overview
+sidebar_label: Plugins Overview
+---
+
+Out of the box Milagro D-TA doesn't do much: a Principal gets a public key from a Master Fiduciary and at a later date can request the corresponding secret key. (Although it does this in a highly secure, and fully auditable way). However this basic capability unlocks a huge range of potential uses cases, some of which related to the Prinicpal - what the keys can be used for, and some relate to the Master Fiduciary - how the seret key is kept safe (a.k.a. custody). Open source "vanilla" Milagro is an attempt to engage a wider community to make the communication between these parties as robust as possible, the plugin framework enables developers to extend Milagro's core capability an apply it to solve real world problems.
+
+Out of the box Milagro comes with two plugins:
+1. Encrypter - allows the principal to use the public key to encrypt a string, then get the secret key back from the Master Fiduciary D-TA and decrypt it
+2. BitCoin Address - uses the public key to genarates a Bitcoin address and the constructs the corresponding secret key only when it is needed (this is a neat trick using eliptic curve magic).
+
+## This is Not Secure
+The point of these plugins is to show you how the framework works and encourage you to develop your own, they do not (out of the box) provide a secure way to store your secret keys becasue the key pair seed is stored only in the Master Fiduciaries database.
+
+## Approach
+The Milagro D-TA plugin framework has been designed with the following constrains:
+* **One-at-a-Time**
+
+ Each Milagro server can only run one plugin at a time. We considered how to allow multiple plugins to interoperate but this produces significant operational and security concerns - so it doesn't do that! (We'd really appreciate you thoughts about that). Ofcourse if you run a pair of servers as Principal and Master Fiduciary then they can each run different plugins
+* **No New Endpoints**
+
+ You can only write plugins to support the [Standard Endpoints](http://localhost:3000/swagger/). This probably seems quite restrictive but we think it is important that Milagro D-TA operates within a defined scope and in a predictable way. Milagro D-TA is about the distributed management of key pairs, we are concerned that if the plugin framework allowed developers to add endpoints such as *GET fastfood/burger?orderby=mostTasty* the Milagro would just become a cool implementation of [Go kit](https://gokit.io/). It would be difficult for users and integrators to know what it was going to do. **However**
+ * **Let's Talk** As a community we're excited to add new features to Milagro D-TA. Propose your new end point as a feature (or even submit a PR) and we'll collectively consider adding it
+ * **Let's Fork** Go ahead and fork the Milagro D-TA. (But remember that Milagro D-TA is basically a communication protcol so keep it compatible with other Milagro users)
+
+* **Extensions**
+
+ Although we restrict what endpoints Milagro provides we give you a highly flexible way to define what data each endpoint accepts and returns via the **extensions** JSON prop. For example the encryptAThing plugin extends the POST /order endpoint like this:
+ ```
+ POST /order
+
+ Request
+ {
+ "beneficiaryIDDocumentCID" : "IPFSAddress",
+ "extensions":{
+ "plainText":"encryptme"
+ }
+ }
+
+ Response
+ {
+ "OrderPart1CID" : "IPFSAddress",
+ "OrderPart2CID" : "IPFSAddress",
+ "Commitment" : "IPFSAddress",
+ "CreatedAt" : 1563982017,
+ "extensions" : {
+ "cyphertext":"iAmEncrypted"
+ }
+ }
+ ```
+
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..48e341a
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,3 @@
+{
+ "lockfileVersion": 1
+}
diff --git a/website/sidebars.json b/website/sidebars.json
index 3eb2f13..aa6ad78 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -30,6 +30,12 @@
"ids":["api-details/configuration",
"api-details/authentication",
"api-details/api"]
+ },
+ {
+ "type":"subcategory",
+ "label":"D-TA Plugins",
+ "ids":["dta-plugins/plugins-overview"
+ ]
}
],
"ZKP-MFA Clients/Servers": [
diff --git a/website/static/swagger/index.html b/website/static/swagger/index.html
index 9a4cfb4..f38264e 100755
--- a/website/static/swagger/index.html
+++ b/website/static/swagger/index.html
@@ -39,7 +39,8 @@
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
- url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/master/open-api.yaml",
+ // url: "https://raw.githubusercontent.com/apache/incubator-milagro-dta/master/open-api.yaml",
+ url: "./open-api.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
diff --git a/website/static/swagger/open-api.yaml b/website/static/swagger/open-api.yaml
new file mode 100644
index 0000000..380ef94
--- /dev/null
+++ b/website/static/swagger/open-api.yaml
@@ -0,0 +1,381 @@
+openapi: 3.0.0
+info:
+ description: Milagro Secure - distributed / decentralized core security services.
+ title: Apache Milagro Server
+ contact:
+ email: howard@qredo.com
+ license:
+ name: Apache Milagro
+ version: 0.0.1
+paths:
+ /identity:
+ post:
+ summary: Create an identity document
+ tags:
+ - identity
+ operationId: createIdentity
+ # security:
+ # - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ required: true
+ type: string
+ x-go-name: Name
+ example: thisNode
+ responses:
+ '200':
+ description: Successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Identity'
+ get:
+ summary: Get a list of identities
+ tags:
+ - identity
+ operationId: getIdentities
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: page
+ in: query
+ description: current page
+ schema:
+ type: integer
+ default: 0
+ - name: perPage
+ in: query
+ description: number of items to show
+ schema:
+ type: integer
+ default: 10
+ - name: sortBy
+ in: query
+ description: Sort By field. Prefix with "-" for descending
+ schema:
+ type: string
+ enum:
+ - dateCreatedAsc
+ - dateCreatedDesc
+ responses:
+ '200':
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/IdentityList'
+ /identity/{idDocAddress}:
+ get:
+ tags:
+ - identity
+ summary: Get a single identity
+ description: Use a known idDocumentAddress to access a single ID document
+ operationId: getIdentityByID
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: idDocAddress
+ in: path
+ description: IPFS hash address of user id doc
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Successful Operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Identity'
+ /order:
+ post:
+ summary: Create an order for a new secret
+ tags:
+ - order
+ operationId: createsafe
+ # security:
+ # - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ BeneficiaryIDDocumentCID:
+ type: string
+ x-go-name: BeneficiaryIDDocumentCID
+ example: '"kjhdhdjd"'
+ coin:
+ type: integer
+ format: int64
+ x-go-name: Coin
+ example: 2
+ x-go-name: Body
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ get:
+ summary: Get a list of secrets
+ tags:
+ - order
+ operationId: getsafes
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: page
+ in: query
+ description: current page
+ schema:
+ type: integer
+ default: 0
+ - name: perPage
+ in: query
+ description: number of items to show
+ schema:
+ type: integer
+ default: 10
+ - name: sortBy
+ in: query
+ description: Sort By field. Prefix with "-" for descending
+ schema:
+ type: string
+ enum:
+ - dateCreated
+ - dateModified
+ - -dateCreated
+ - -dateModified
+ responses:
+ '200':
+ description: Successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Arrayofsafesecrets'
+ /order/{orderAddress}:
+ get:
+ summary: Get details of a secret in custody
+ tags:
+ - order
+ operationId: getsafe
+ security:
+ - bearerAuth: []
+ parameters:
+ - name: safesecretAddress
+ in: path
+ description: IPFS hash address of safe secret doc
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ /order/secret:
+ post:
+ summary: Release secret
+ tags:
+ - order
+ operationId: createkey
+ # security:
+ # - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ OrderPart2CID:
+ type: string
+ example: QmYXqQnEFHD3eRUAuMx6oTQb4ybAdWMnmhgUjuZ9QoAYMr
+ BeneficiaryIDDocumentCID:
+ type: string
+ example: QmYDqFaJvjHYsypfPXahyV4TayGoLWuzS8ZcD73jtT2Hkv
+ responses:
+ '200':
+ $ref: '#/components/schemas/keysecret'
+ /order/pairing:
+ post:
+ summary: Generate and issue a type-3 pairing key
+ tags:
+ - order
+ operationId: createsafe
+ # security:
+ # - bearerAuth: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ beneficiaryIDDOC:
+ type: string
+ x-go-name: BeneficiaryIDDOC
+ example: '"kjhdhdjd"'
+ coin:
+ type: integer
+ format: int64
+ x-go-name: Coin
+ example: 2
+ x-go-name: Body
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ /fulfill/order:
+ post:
+ summary: Create Public Address
+ tags:
+ - fulfill
+ operationId: fulfillsafe
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ safeDocAddress:
+ type: string
+ x-go-name: safeDocAddress
+ example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+ x-go-name: Body
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ /fulfill/order/secret:
+ post:
+ summary: Return Private Key
+ tags:
+ - fulfill
+ operationId: fulfillkey
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ safeDocAddress:
+ type: string
+ x-go-name: keyDocAddress
+ example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+ x-go-name: Body
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ /fulfill/order/pairing:
+ post:
+ summary: Return mPIN Key
+ tags:
+ - fulfill
+ operationId: fulfillkey
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ safeDocAddress:
+ type: string
+ x-go-name: keyDocAddress
+ example: Qme5S5xVfGYF46oftiLQDevPAGSKy1aggdtrZvvEdiXuqM
+ x-go-name: Body
+ responses:
+ '200':
+ $ref: '#/components/schemas/safesecret'
+ /status:
+ get:
+ description: Test Server Health
+ tags:
+ - system
+ operationId: healthcheck
+ responses:
+ '200':
+ description: Successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SystemHealth'
+servers:
+ - url: 'http://localhost:5555'
+ - url: 'http://localhost:5556'
+# security:
+# - bearerAuth: []
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ bearerFormat: JWT
+ schemas:
+ Identity:
+ type: object
+ properties:
+ idDocumentAddress:
+ type: string
+ AuthenticationReference:
+ type: string
+ BenListenerWalletAddress:
+ type: string
+ BenSASPubKey:
+ type: string
+ BenECAddPubKey:
+ type: string
+ SikePublicKey:
+ type: string
+ PicnicPublicKey:
+ type: string
+ Handle:
+ type: string
+ Email:
+ type: string
+ Username:
+ type: string
+ Timestamp:
+ type: integer
+ IdentityList:
+ type: object
+ items:
+ $ref: '#/components/schemas/IdentityArray'
+ IdentityArray:
+ type: array
+ items:
+ $ref: '#/components/schemas/Identity'
+ safesecret:
+ type: object
+ properties:
+ safesecretAddress:
+ type: string
+ Arrayofsafesecrets:
+ type: array
+ items:
+ $ref: '#/components/schemas/safesecret'
+ keysecret:
+ type: object
+ properties:
+ secretDocAddress:
+ type: string
+ SystemHealth:
+ type: object
+ properties:
+ timeStamp:
+ type: string
+ testString:
+ type: string
+tags:
+ - name: identity
+ description: Actors in the system
+ externalDocs:
+ url: 'https://milagro.apache.org/docs/milagro-intro/'
+ description: Apache Milagro Docs
+ - name: order
+ description: Send Requests to Principal Node
+ externalDocs:
+ url: 'https://milagro.apache.org/docs/milagro-intro/'
+ description: Apache Milagro Docs
+ - name: fulfill
+ description: Actions performed by the Fiduciary node
+ externalDocs:
+ url: 'https://milagro.apache.org/docs/milagro-intro/'
+ description: Apache Milagro Docs
\ No newline at end of file
