Code flow (#90)

linkinator.config.json

@@ -4,6 +4,7 @@
         "www.linkedin.com",
         "/js/script.hash.js",
         "github.com/hellocoop/hello.dev/*",
-        "http://localhost:3000"
+        "http://localhost:3000",
+        "https://blog.hello.dev/*"
     ]
   }

pages/docs/mockin.mdx

@@ -35,7 +35,7 @@ npx @hellocoop/mockin
 
 `docker run  -d -p 3333:3333 hellocoop/mockin:latest`
 
-If you are running Mockin with `docker-compose` or `Kubernetes`, you will need to set the environment variables for the Mockin service to the hostname the service is running at, and similarly will need to configure your app to redirect to that service when the the `[ ō Continue with Hellō ]` button is pressed. See https://github.com/hellocoop/packages/tree/main/tests for a `docker-compose` example using Playwright.
+If you are running Mockin with `docker-compose` or `Kubernetes`, you will need to set the environment variables for the Mockin service to the hostname the service is running at, and similarly will need to configure your app to redirect to that service when the the `[ ō Continue with Hellō ]` button is pressed. See https://github.com/hellocoop/packages-js/tree/main/express/tests for a `docker-compose` example using Playwright.
 
 ## Playing with Mockin
 You can use Mocking with the [Hellō Playground](https://playground.hello.dev). Run Mockin with either: 

pages/docs/oidc/_meta.json

@@ -1,6 +1,7 @@
 {
     "request": "Auth Request",
     "response": "Auth Response",
+    "device": "Device Code Flow",
     "verification": "Verification",
     "token": "ID Token",
     "config": "Configuration",

pages/docs/oidc/device.mdx

@@ -0,0 +1,58 @@
+import { Callout } from 'nextra/components'
+
+# Device Auth Grant
+
+Hellō supports using the [Device Authorization Grant (RFC8628)](https://datatracker.ietf.org/doc/html/rfc8628) to obtain an ID Token for a user. This enables the user to log into internet connected devices that do not support a browser. In addition to the `client_id` and `scope` parameters, Hellō supports the `nonce`, `prompt`, `login_hint`, `domain_hint`, and `provider_hint`.
+
+## Device Auth Request
+
+To start the process, do an HTTP POST to the Hellō `device_authorization_endpoint`, `https://wallet.hello.coop/oauth/device/code`, with the `Content-Type` of `application/x-www-form-urlencoded` and the following parameters:
+
+|Parameters|Description|
+|---|---|
+|`client_id`<br/>*required*|The `client_id` for your app from [console.hello.coop](https://console.hello.coop).|
+|`scope`<br/>*required*|The `openid` scope and zero or more space delimited scopes listed at [Hellō Claims](/docs/scopes).|
+|`nonce`<br/>*required*|A unique string that will be included in the signed ID Token. This links the ID Token to your request.|
+|`login_hint`<br/>*optional*|A hint (`email` or `sub`) for which user account to use.<br/>Valid formats:<br/>- `login_hint=name@domain.example`<br/>- `login_hint=mailto:name@domain.example`<br/>- `login_hint=sub_01234567abcdefghABCDEFGH_XXX`|
+|`prompt`<br/>*optional*|A space delimited list. Accepted values include:|
+|                   | - `login` will require the user to re-authenticate at their login provider|
+|                   | - `consent` will require the user to review, and potentially change, released claims|
+
+|Hellō Parameters|Description|
+|---|---|
+|`provider_hint`<br/>*optional*| See [Wallet API \| provider_hint](/docs/apis/wallet/#provider_hint) for details. |
+|`domain_hint`<br/>*optional*|A hint for which domain or type of account: |
+| | - `domain.example` to request the user logs in with a specific managed account |
+| | - `managed` to request a managed account |
+| | - `personal` to request a personal (non-managed) account |
+
+
+## Device Authorization Response
+
+If the request is accepted, a JSON response will be provided per [RFC 8628 3.2](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2). Here is a sample response:
+
+```json
+{
+  "device_code": "bde3a264c27b79cfc0e838e098bd193f571cf01de45a871dd228ab889d519878",
+  "user_code": "228-457-485",
+  "verification_uri": "https://wallet.hello.coop/device",
+  "verification_uri_complete": "https://wallet.hello.coop/device?user_code=228-457-485",
+  "expires_in": 300000
+}
+``` 
+
+## User Interaction
+
+Instruct the user to load the `verification_uri` and enter the `user_code` value, or load the `verification_uri_complete`, which could be presented to the user as a QR code they can scan to start the login. 
+
+## Device Access Token Request
+
+Do an HTTP POST with the `Content-Type` of `application/x-www-form-urlencoded` to the Hellō `token_endpoint`, `https://wallet.hello.coop/oauth/token` per [RFC 8628 3.1](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1) passing `grant_type` with a value of `urn:ietf:params:oauth:grant-type:device_code` and the `device_code` and `client_id`. Here is a sample request:
+
+```
+grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&
+device_code=bde3a264c27b79cfc0e838e098bd193f571cf01de45a871dd228ab889d519878&
+client_id=app_exampleapplication_cid
+```
+
+The response will usually be the `token_endpoint` response.