docs: 466/hash-verification

docs/astro.config.mjs

@@ -69,15 +69,30 @@ export default defineConfig({
             },
             {
               label: 'Grant negotiation and authorization',
-              link: '/introduction/grants/'
-            },
-            {
-              label: 'Client keys',
-              link: '/introduction/client-keys/'
-            },
-            {
-              label: 'HTTP message signatures',
-              link: '/introduction/http-signatures/'
+              collapsed: true,
+
+              items: [
+                {
+                  label: 'Overview',
+                  link: '/introduction/grants/'
+                },
+                {
+                  label: 'Identity providers',
+                  link: '/introduction/idp/'
+                },
+                {
+                  label: 'Client keys',
+                  link: '/introduction/client-keys/'
+                },
+                {
+                  label: 'HTTP message signatures',
+                  link: '/introduction/http-signatures/'
+                },
+                {
+                  label: 'Hash verification',
+                  link: '/introduction/hash-verification/'
+                }
+              ]
             }
           ]
         },

docs/src/content/docs/introduction/grants.mdx

@@ -93,15 +93,3 @@ Operations on the APIs by a client require the client to have a valid access tok
 :::note
 An open-source implementation of an Open Payments resource server, called <LinkOut href='https://rafiki.dev'>Rafiki</LinkOut>, is currently in development.
 :::
-
-## Identity providers
-
-An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. Open Payments requires any AS that issues <Tooltip content="A grant requiring explicit interaction/consent from the resource owner before an access token can be issued" client:load><span>interactive grants</span></Tooltip> be integrated with an IdP.
-
-After an interactive grant request is initiated and the AS sets the session, the AS provides the client with the IdP URI to redirect the end-user to.
-
-<Interactive />
-
-:::tip[Reference implementation]
-Rafiki provides a reference <LinkOut href='https://github.com/interledger/rafiki/tree/main/packages/auth'>authorization service</LinkOut> implementation that includes support for integration with an IdP.
-:::

docs/src/content/docs/introduction/hash-verification.mdx

@@ -0,0 +1,45 @@
+---
+title: Hash verification
+---
+
+import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
+
+Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redeirect the RO's [identify provider (IdP)](/introduction/idp/) to the finish URI. In order to secure this communication and verify that the redirect indeed emanated from the AS, the AS will provide a hash parameter in the request to the client's callback URI. The client **_must_** verify this hash.
+
+## Hashing method
+
+The hash base is generated by concatentating the following values in sequence using a single newline (0x0A) character to separate them:
+
+1. `nonce` value sent by the client in the initial request.
+2. `nonce` value sent by the AS from the interaction finish response.
+3. `interact_ref` returned from the AS in the interaction finish method.
+4. The grant endpoint `uri` the client used to make its initial request.
+
+The following example shows the four aforementioned components that make up the hash base. There is no padding or whitespace before or after each line and no trailing newline character.
+
+<CodeBlock title="Example hash base">
+
+```http
+VJLO6A4CATR0KRO
+MBDOFXG4Y5CVJCX821LH
+4IFWWIKYB2PQ6U56NL1
+https://server.example.com/tx
+```
+
+</CodeBlock>
+
+The ASCII encoding of this string is hashed with the algorithm specified in the `hash_method` parameter under the `finish` key of the interaction finish request. The byte array from the hash function is then encoded using URL-Safe Base64 with no padding. The resultant string is the hash value.
+
+Unless specified by the client in the initial request, the `hash_method` will default to `sha-256`. If the client specifies the `hash_method`, the `hash_method` **_must_** be one of the hash name strings defined in the <LinkOut href='https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg'>IANA Named Information Hash Algorithm Registry</LinkOut>.
+
+Using our hash base string example above, the following is the `sha-256` encoded hash that uses the 256-bit SHA2 algorithm.
+
+<CodeBlock title="SHA2 256-bit hash example">
+
+```http
+x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY
+```
+
+</CodeBlock>
+
+For more information refer to the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-20#name-calculating-the-interaction'> "Calculating the interaction hash"</LinkOut> section of the GNAP specification.

docs/src/content/docs/introduction/idp.mdx

@@ -0,0 +1,22 @@
+---
+title: Identity providers
+---
+
+import {
+  CodeBlock,
+  LinkOut,
+  Tooltip,
+  Mermaid,
+  MermaidWrapper
+} from '@interledger/docs-design-system'
+import Interactive from '/src/partials/diagram-interactive-grant.mdx'
+
+An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. Open Payments requires any authorization server (AS) that issues <Tooltip content="A grant requiring explicit interaction/consent from the resource owner before an access token can be issued" client:load><span>interactive grants</span></Tooltip> be integrated with an IdP.
+
+After an interactive grant request is initiated and the AS sets the session, the AS provides the client with the IdP URI to redirect the end-user to.
+
+<Interactive />
+
+:::tip[Reference implementation]
+Rafiki provides a reference <LinkOut href='https://github.com/interledger/rafiki/tree/main/packages/auth'>authorization service</LinkOut> implementation that includes support for integration with an IdP.
+:::

docs/src/content/docs/introduction/op-flow.mdx

@@ -149,7 +149,7 @@ Similarly, the client can provide the end-user with details about a specific <Li
 
 This diagram brings the aforementioned concepts together, except for getting transaction history, to present a full transaction sequence without delving too deeply into the contents of each request and response. A link to view a larger version of the diagram is provided at the bottom of the page.
 
-As shown below, both the sender and the recipient's ASEs must operate their own authorization and resource servers. Grant requests for incoming payment and quote resources are typically non-interactive. A grant request for an outgoing payment resource requires explicit consent from the sender (e.g., the client's end user), which is obtained through the sender's [identity provider](/introduction/grants#identity-providers).
+As shown below, both the sender and the recipient's ASEs must operate their own authorization and resource servers. Grant requests for incoming payment and quote resources are typically non-interactive. A grant request for an outgoing payment resource requires explicit consent from the sender (e.g., the client's end user), which is obtained through the sender's [identity provider](/introduction/idp/).
 
 More information about grant interaction flows can be found in the [Grant negotiation and authorization](/introduction/grants) page.
 

docs/src/content/docs/resources/glossary.mdx

@@ -30,7 +30,7 @@ Open Payments is an open RESTful API and an API standard that enables clients to
 
 ## Outgoing payment resource
 
-An [outgoing payment resource](/introduction/op-concepts/#outgoing-payment) is an object created by the sender's ASE, on their resource server, that represents a payment being sent by an entity. This resource contains information about the outgoing payment, such as the amount, currency, receiver's wallet address, and payment status. Outgoing payment resources require explicit [consent](/introduction/grants/#identity-providers) from the sender before the resource can be created.
+An [outgoing payment resource](/introduction/op-concepts/#outgoing-payment) is an object created by the sender's ASE, on their resource server, that represents a payment being sent by an entity. This resource contains information about the outgoing payment, such as the amount, currency, receiver's wallet address, and payment status. Outgoing payment resources require explicit [consent](/introduction/idp/) from the sender before the resource can be created.
 
 ## Quote resource