add http message creation detail & images #383

tselit · 2023-11-28T14:38:08Z

Changes proposed in this pull request

Describes the HTTP signature creation process, including diagrams.

Context

Explains, in fairly simple terms, how the OpenPaymets API has implemented part of the HTTP message signatures draft spec.

changeset-bot · 2023-11-28T14:38:12Z

⚠️ No Changeset found

Latest commit: f723c50

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2023-11-28T14:38:14Z

✅ Deploy Preview for openpayments-preview ready!

Name	Link
🔨 Latest commit	`f723c50`
🔍 Latest deploy log	https://app.netlify.com/sites/openpayments-preview/deploys/659d52170e4d820008d64a89
😎 Deploy Preview	https://deploy-preview-383--openpayments-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

sabineschaller

Do the graphics work on black and white background? I think the written part is good, but the technical writers may be able to make it even better 😉.

sabineschaller · 2023-11-29T12:06:31Z

docs/public/img/http-sig/1-original_msg.png

The Content-Digest header is not standard but part of the signature headers. I also believe that the Date header is not standard. We never use it.

I think we should also add the Authorization header.

Updated header:

removed Content-Digest and Date

added Authorization

Replaced the diagram with a codeblock titled 'Example: message before signature'.

sabineschaller · 2023-11-29T12:20:02Z

docs/public/img/http-sig/2-select_rest_of_sig_params.png

Date is not part of it. I also cannot find it in the docs.

Also, the first line (POST ...), that is split into @method and @target-uri. The HTTP version is irrelevant. I think @method is missing from your list.

And again, I'd add the Authorization header.

"content-digest" "content-length" "content-type" are also part of the signature params.

I think it's confusing to use creation_time, signing_algorithm, and key_id instead of created, alg, and keyid respectively.

Replaced image with codeblock Example: signature base.

Removed Date from header

Removed HTTP version

Included Authorization header

Added to signature params: @method; content-digest, content-length, and content-type

Renamed signature params: creation_time, signing_algorithm, and key_id

sabineschaller · 2023-11-29T12:23:37Z

docs/public/img/http-sig/3-sig_base.png

The content headers are missing. Drop date but add authorization.

Replaced image with codeblock Example: signature base

Removed Date from header

Included Authorization header

sabineschaller · 2023-11-29T12:26:06Z

docs/src/content/docs/introduction/http-signatures.mdx

-:::caution
-This section is WIP
-:::
+The [RFC8032](https://www.rfc-editor.org/rfc/rfc8032) specification permits the use of different components of an HTTP message to generate a uniquely labelled message signature. There can be multiple signatures within each HTTP message, each one generated using a different signature algorithm.


Should we link that spec or the part about signatures in the GNAP spec?

Yes, done, thank you!

sabineschaller · 2023-11-29T12:27:45Z

docs/public/img/http-sig/4-sig_creation.png

I like that one!

Update: image is now created in light mode with solid white background.

melissahenderson · 2023-11-29T13:37:55Z

If possible, please change the font used in the images. Code examples should use a monospace font (Starlight uses a system monospace font by default). For "regular" text and diagrams we should use a sans-serif font that is easier to read and doesn't look handwritten (Starlight uses a system sans-serif font by default). I believe Mermaid uses Trebuchet for its sequence diagrams, but it's not my favorite. Regular Arial would work.

melissahenderson · 2023-11-29T13:39:02Z

docs/public/img/http-sig/1-original_msg.png

Could this image be replaced w/ the code block component and a title? https://interledger.tech/shared/codeblock/

Yes indeed.
Replaced the diagram with a codeblock titled 'Example: message before signature'.

melissahenderson · 2023-11-29T13:39:27Z

docs/public/img/http-sig/3-sig_base.png

Could this image also be replaced w/ code block and title? https://interledger.tech/shared/codeblock/

Edit: Maybe not. I see now there's a light gray arrow and text referencing a line in the code.

I think you're right. I replaced the image with the Example: signature base codeblock, and then used accompanying text to add detail.

melissahenderson · 2024-01-03T12:45:01Z

Related #321

(1) added a reference to the GNAP spec (2) removed all but 1 diagram, in favour of using code blocks (3) corrected the original HTTP message header to exclude a Date, and to include Authorization (4) updated the signature params to include: Authorization; "content-digest" "content-length" "content-type"

…nto mt-http-sig-creation

…yments into mt-http-sig-creation

tselit · 2024-01-09T14:54:31Z

If possible, please change the font used in the images. Code examples should use a monospace font (Starlight uses a system monospace font by default). For "regular" text and diagrams we should use a sans-serif font that is easier to read and doesn't look handwritten (Starlight uses a system sans-serif font by default). I believe Mermaid uses Trebuchet for its sequence diagrams, but it's not my favorite. Regular Arial would work.

Cool and noted, thanks for the thoughtful points @melissahenderson.
I wanted to use Excalidraw exactly for the handwritten 'look' for images.
But if this feels like it creates inconsistency or if it's not inline with the doc style-guide, then we can definitely change it.
From what I see in the Excalidraw docs, there is currently just one alternative font available: 'Helvetica'.
For more detail, check out the Excalidraw docs here

tselit · 2024-01-09T14:59:17Z

Do the graphics work on black and white background? I think the written part is good, but the technical writers may be able to make it even better 😉.

Thanks @sabineschaller - image updated to work with white or black backgrounds.
😆 I am with you about the written part.

melissahenderson

Can you update the diagram so that it doesn't use a handwritten font? Excalidraw allows you to use what looks like Arial (in the Excalidraw UI, under font family, it's the button with an "A").

melissahenderson · 2024-01-10T16:59:01Z

docs/src/content/docs/introduction/http-signatures.mdx

+
+### Signed HTTP Message
+
+The original message gets signed by adding uniqeuly labelled signature headers to the original message: `Signature-Input` and `Signature`.


There's a typo here :) "uniqeuly"

melissahenderson · 2024-01-10T16:59:50Z

docs/src/content/docs/introduction/http-signatures.mdx

 :::

-## Use the HTTP signature Lambda function
+{/* prettier-ignore */}


If everything from here down is no longer necessary, it can be deleted.

melissahenderson · 2024-01-10T17:00:46Z

docs/src/content/docs/introduction/http-signatures.mdx

+
+</CodeBlock>
+
+:::note


When I look at this note in the preview, there's a line break between the two sentences. Can you either add a space between the lines or include them together in a single paragraph? Minor thing, I know.

Updates to this doc have been in progress for a while (see #383 ). For the sake of simplicity, I've taken the changes and am merging them using this PR instead of the original.

melissahenderson · 2024-02-13T14:50:59Z

Updates merged with #424

tselit added 2 commits November 27, 2023 12:34

add http signature creation detail & images

13004b3

add http message creation detail & images

84a8b50

tselit requested a review from sabineschaller November 28, 2023 14:39

ran the prettier command, for consistent styling

bd10445

sabineschaller reviewed Nov 29, 2023

View reviewed changes

melissahenderson reviewed Nov 29, 2023

View reviewed changes

melissahenderson mentioned this pull request Jan 3, 2024

HTTP signature docs #321

Closed

tselit added 5 commits January 8, 2024 18:03

docs: ran 'prettier' command, per the style guide

b10b696

Merge branch 'main' of https://github.com/interledger/open-payments i…

cd671ca

…nto mt-http-sig-creation

Merge branch 'mt-http-sig-creation' of github.com:interledger/open-pa…

8318b8a

…yments into mt-http-sig-creation

docs: resolve merge conflict - delete unused image

f723c50

tselit self-assigned this Jan 9, 2024

melissahenderson reviewed Jan 10, 2024

View reviewed changes

melissahenderson added a commit that referenced this pull request Feb 13, 2024

Updates to HTTP Sig doc

7d58808

Updates to this doc have been in progress for a while (see #383 ). For the sake of simplicity, I've taken the changes and am merging them using this PR instead of the original.

melissahenderson mentioned this pull request Feb 13, 2024

Updates to HTTP Sig doc #424

Merged

melissahenderson closed this Feb 13, 2024

melissahenderson deleted the mt-http-sig-creation branch February 13, 2024 14:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add http message creation detail & images #383

add http message creation detail & images #383

tselit commented Nov 28, 2023 •

edited

Loading

changeset-bot bot commented Nov 28, 2023 •

edited

Loading

netlify bot commented Nov 28, 2023 •

edited

Loading

sabineschaller left a comment

sabineschaller Nov 29, 2023

tselit Jan 9, 2024

sabineschaller Nov 29, 2023

tselit Jan 9, 2024

sabineschaller Nov 29, 2023

tselit Jan 9, 2024

sabineschaller Nov 29, 2023

tselit Jan 9, 2024

sabineschaller Nov 29, 2023

tselit Jan 9, 2024

melissahenderson commented Nov 29, 2023

melissahenderson Nov 29, 2023

tselit Jan 9, 2024

melissahenderson Nov 29, 2023 •

edited

Loading

tselit Jan 9, 2024

melissahenderson commented Jan 3, 2024

tselit commented Jan 9, 2024

tselit commented Jan 9, 2024

melissahenderson left a comment

melissahenderson Jan 10, 2024

melissahenderson Jan 10, 2024

melissahenderson Jan 10, 2024

melissahenderson commented Feb 13, 2024


		### Signed HTTP Message

		The original message gets signed by adding uniqeuly labelled signature headers to the original message: `Signature-Input` and `Signature`.


		</CodeBlock>

		:::note

add http message creation detail & images #383

add http message creation detail & images #383

Conversation

tselit commented Nov 28, 2023 • edited Loading

Changes proposed in this pull request

Context

changeset-bot bot commented Nov 28, 2023 • edited Loading

⚠️ No Changeset found

netlify bot commented Nov 28, 2023 • edited Loading

✅ Deploy Preview for openpayments-preview ready!

sabineschaller left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melissahenderson commented Nov 29, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melissahenderson Nov 29, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melissahenderson commented Jan 3, 2024

tselit commented Jan 9, 2024

tselit commented Jan 9, 2024

melissahenderson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

melissahenderson commented Feb 13, 2024

tselit commented Nov 28, 2023 •

edited

Loading

changeset-bot bot commented Nov 28, 2023 •

edited

Loading

netlify bot commented Nov 28, 2023 •

edited

Loading

melissahenderson Nov 29, 2023 •

edited

Loading