refactoring ausdigital/ausdigital.github.io#33

docs/1.0/index.md

@@ -0,0 +1,49 @@
+ * Spec ID: ausdigital.org/ausdigital-tap/1.0
+ * ![raw](http://rfc.unprotocols.org/spec:2/COSS/raw.svg)
+ * Editor: the Digital Business Council (Council)
+ * Contributors: 
+
+## AusDigital Transaction Access Point (TAP) 1.0 Specification
+
+This document describes a protocol for exchanging formal documents (such as invoices) between businesses. TAP is a secure, decentralised, peer to peer architecture where gateways are optional and minimally trusted.
+
+## Overview
+
+The Access Point Implementation Guide defines the standards for delivering and receiving of digital business documents within the Council’s Interoperability Framework (Framework). The Framework defines the following components:
+* Access Point: A sender or receiver of digital business documents;
+* Digital Capability Locator: A service for looking up the location of the Digital Capability Publisher for a Participant. (Digital Business Council, 2016a);
+* Digital Capability Publisher: A service for Participants to store details of their capabilities, and includes what scenarios they can process, the data formats they support and the delivery address for their eInvoices. (Digital Business Council, 2016b); and
+* Electronic Business Documents: A digital representation of a business document, e.g. an eInvoice.
+
+![Figure 1: Context of Access Points within the Interoperability Framework](./tap_business_context_diagram.png "Figure 1: Context of Access Points within the Interoperability Framework")
+
+Figure 1: Context of Access Points within the Interoperability Framework
+
+The messaging protocol described in this document is business process and business document agnostic. The underlying OASIS ebMS3 standard has been designed to be flexible and support a large number of use cases. This implementation guide reduces complexity by focusing on the exchange of business documents regardless of their type or the process in which they are used.
+
+The context diagram Figure 1 shows the components included in the Interoperability Framework and where the Access Point (AP) sits. The Digital Capability Publisher and Digital Capability Locator are used by the Access Points and enable the eInvoicing process.
+
+The components of the framework are used in a four-corner model (see Figure 2: Four Corner Model). End users, or participants, don’t directly exchange electronic information but connect through a network of Access Points. The digital address for a receiving Access Point is dynamically discovered using the Digital Capability Locator (DCL) and Digital Capability Publisher(DCP) components of the Framework. Access Points may also update a participant’s digital endpoint in the DCP.
+
+![Figure 2: Four Corner Model](./tap_four_corner_model.png "Figure 2: Four Corner Model")
+
+Figure 2: Four Corner Model
+
+See the complete [Access Point Implementation Guide](./https://github.com/ausdigital/ausdigital-syn-v1/blob/master/Access_Point_Implementation_Guide_v1.0.pdf) for further details.
+
+## Licence
+
+Copyright (c) 2016 the Editor and Contributors. All rights reserved.
+
+This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+## Change Process
+
+This document is governed by the [2/COSS](http://rfc.unprotocols.org/spec:2/COSS/) (COSS).
+
+
+## Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
+"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
+RFC 2119.

docs/tap_details.md → docs/2.0/index.md

@@ -1,3 +1,116 @@
+ * Spec ID: ausdigital.org/ausdigital-tap/2.0
+ * ![raw](http://rfc.unprotocols.org/spec:2/COSS/raw.svg)
+ * Editor: Chris Gough
+ * Contributors: Steve Capell
+
+## AusDigtial Transaction Access Point (TAP) 2.0 Specification
+
+## Glossary:
+
+phrase | Definition
+------------ | -------------
+ausdigital-tap/2 | Version 2 of the [AusDigtial](http://ausdigital.org) [TAP](http://ausdigital-tap.readthedocs.io/) specification
+ausdigital-tapgw/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [TAPGW](http://ausdigital-tap-gw.readthedocs.io/) specification
+ausdigital-bill/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [BILL](http://ausdigital-bill.readthedocs.io/) specification
+ausdigital-dcl/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [DCL](http://ausdigital-dcl.readthedocs.io/) specification
+ausdigital-dcp/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [DCP](http://ausdigital-dcp.readthedocs.io/) specification
+ausdigital-nry/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [NRY](http://ausdigital-nry.readthedocs.io/) specification
+ausdigital-idp/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [IDP](http://ausdigital-idp.readthedocs.io/) specification
+
+This document describes a protocol for exchanging formal documents (such as invoices)
+between businesses. TAP is a secure, decentralised, peer to peer architecture where gateways
+are optional and minimally trusted.
+
+This specification aims to support the Australian Digital Business Council
+[eInvoicing initiative](https://ausdigital.org), and is under active development
+at [https://github.com/ausdigital/ausdigital-tap](https://github.com/ausdigital/ausdigital-tap).
+
+
+## Licence
+
+Copyright (c) 2016 the Editor and Contributors. All rights reserved.
+
+This Specification is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software Foundation; 
+either version 3 of the License, or (at your option) any later version.
+
+This Specification is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program;
+if not, see [http://www.gnu.org/licenses](http://www.gnu.org/licenses).
+
+
+## Change Process
+
+This document is governed by the [2/COSS](http://rfc.unprotocols.org/spec:2/COSS/) (COSS).
+
+
+## Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
+"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
+RFC 2119.
+
+
+# Introduction
+
+The Transaction Access Point (TAP) is a persistently connected "peer" capable of sending and
+receiving business documents, such as invoices. It interacts with other TAPs following the
+protocol specified in this document. The TAP is an autonomous agent in business-to-business
+document exchange.
+
+A TAP might be provided by a commercial ledger service, or maintained as part of an
+independent business system. 
+
+The TAP specification has two parts. The main part (ausdigital-tap/2) defines the protocol all peers
+must follow (and interfaces they must provide) to send and receive business documents. The
+second part is an optional gateway specification (ausdigital-tapgw/1), which defines a client-server
+protocol for trusted business system components (e.g. ledger services) to interact with independent TAP service providers in a generic way.
+
+
+## Dependencies
+
+The messages sent between TAPs carry semantic payloads. Currently, these include
+ausdigital-bill/1.
+That specification is maintained independently in the
+[https://github.com/ausdigital/ausdigital-bill](https://github.com/ausdigital/ausdigital-bill)
+repository. Future semantic payloads may be supported without change to the protocol.
+
+All TAPs depend on the following Services:
+
+ * ausdigital-dcl/1 
+ * ausdigital-dcp/1 
+ * ausdigital-nry/1 
+
+TAPGW providers also depend on the
+ausdigital-idp/1. TAPs do not need to
+authenticate when they interact with each other, due to use of well known cryprograpic keys
+and service endpoint addresses.
+
+
+## TAP Protocol Overview
+
+In this protocol, a Transaction Access Point (TAP) is a business system component that sends and receives business messages. The TAP Protocol describes how one TAP sends the message, and how the other TAP responds when a message is received.
+
+The message is sent to the receiving TAP using HTTP POST operation, with a `Content-Type: multipart/form-data` body. This body contains two parts, `message` and `signature`.
+
+The `message` part is a mixture of cleartext metadata (used by TAPs) and enciphered payload (used by trusted business system components). The cleartext metadata does not contain sensitive business information, whereas access to the business-sensitive information within the payload is not necessary for participating in the TAP protocol.
+
+The `signature` part is created by a business system component trusted by the sender (with access to the sender's private key material). The signature can be used as a unique identifier of the message contents (e.g. transmitted document id).
+
+![Illustration of POST body](./tap_overview_post.png "Business document sent to TAP")
+
+Receiving TAPs may also use the signature as a filter (messages with invalid signatures MAY be dropped by receiving TAPs, rather than delivered). This allows TAPs to buffer trusted components from anonymous denial of service attacks.
+
+When a valid message is received, the TAP issues an HTTP 200 status and returns a response body with `Content-Type: text/json`, containing a HATEOS-style list of callback URLs.
+
+![Illustration of HTTP 200 response](./tap_overview_response.png "Response 200 OK")
+
+See the TAP Protocol Details chapter for more information.
+
+
 # TAP Protocol Details
 
 The TAP Protocol is a very simple REST API. One business sends a message directly to another business' TAP endpoint (discovered via the SMP):
@@ -208,3 +321,41 @@ TODO:
  * explain callback URLs
  * explain callback semantic URLs
  * define error responses.
+
+
+# Security
+
+This chapter is TODO.
+
+
+Deployment Model and Operator Experience
+
+
+Protocol Elements
+
+ * HTTPS Requests
+ * ...
+ * Errors
+ * Replay protection ?
+
+
+Identity Management
+
+ * Resources
+ * Directory
+
+
+Security Considerations
+
+ * Threat model
+ * LAPGW: Integrity of Authorizations
+ * LAPGW: Preventing Authorization Hijacking
+ * Denial-of-Service Considerations
+ * ...other policy/controls
+
+
+References
+
+ * Normative References
+ * Informative References
+

docs/index.md

@@ -1,57 +1,3 @@
-**[Back to AusDigital.org](http://ausdigital.org/)**
-
-# 1/TAP
-
-## ADBC Transaction Access Point (TAP) Specification
-
- * ![raw](http://rfc.unprotocols.org/spec:2/COSS/raw.svg)
- * Editor: Chris Gough
- * Contributors: Steve Capell
-
-##Glossary:
-
-phrase | Definition
------------- | -------------
-ausdigital-tap/2 | Version 2 of the [AusDigtial](http://ausdigital.org) [TAP](http://ausdigital-tap.readthedocs.io/) specification
-ausdigital-tapgw/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [TAPGW](http://ausdigital-tap-gw.readthedocs.io/) specification
-ausdigital-bill/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [BILL](http://ausdigital-bill.readthedocs.io/) specification
-ausdigital-dcl/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [DCL](http://ausdigital-dcl.readthedocs.io/) specification
-ausdigital-dcp/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [DCP](http://ausdigital-dcp.readthedocs.io/) specification
-ausdigital-nry/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [NRY](http://ausdigital-nry.readthedocs.io/) specification
-ausdigital-idp/1 | Version 1 of the [AusDigtial](http://ausdigital.org) [IDP](http://ausdigital-idp.readthedocs.io/) specification
-
-This document describes a protocol for exchanging formal documents (such as invoices)
-between businesses. TAP is a secure, decentralised, peer to peer architecture where gateways
-are optional and minimally trusted.
-
-This specification aims to support the Australian Digital Business Council
-[eInvoicing initiative](https://ausdigital.github.io), and is under active development
-at [https://github.com/ausdigital/ausdigital-tap](https://github.com/ausdigital/ausdigital-tap).
-
-
-## Licence
-
-Copyright (c) 2016 the Editor and Contributors. All rights reserved.
-
-This Specification is free software; you can redistribute it and/or modify it under the
-terms of the GNU General Public License as published by the Free Software Foundation; 
-either version 3 of the License, or (at your option) any later version.
-
-This Specification is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
-PURPOSE. See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with this program;
-if not, see [http://www.gnu.org/licenses](http://www.gnu.org/licenses).
-
-
-## Change Process
-
-This document is governed by the [2/COSS](http://rfc.unprotocols.org/spec:2/COSS/) (COSS).
-
-
-## Language
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
-"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in
-RFC 2119.
+# AusDigital Transaction Access Point Specification
+ * [Version 1.0](/docs/1.0/index.md)
+ * [Version 2.0](/docs/2.0/index.md)