README documentation and assets

README.md

@@ -1,41 +1,75 @@
-# Ably Labs Template Repo
+# Netlify Identity & JWT authentication
 
----
 
-// This is a template repository to be used for all Ably Labs demos, tools & proof of concepts. Follow these steps to so this repo is easy to use for visitors & maintainers.
+![Netlify + JWT + Ably](./assets/netlify-ably-jwt.png)
 
-1. Update the description of this repo.
-2. Add [topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) to this repo to clarify the language, tech stack and use case.
-3. Update the [.gitignore](.gitignore) file with one of the [standard templates from GitHub](https://github.com/github/gitignore).
-4. Update [dependabot.yml](.github/dependabot.yml) with the [configuration for your project](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates).
-5. Replace `https://github.com/ably-labs/ably-labs-template-repo/issues` with the actual link of the repo in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
-6. Update this README so it provides enough information for people to understand how it works, how to run it locally and how it can be deployed to the cloud (see [GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)).
-7. Add a GitHub workflow to build/test/deploy your application. Use the [Ably Control API GitHub action](https://github.com/ably-labs/ably-control-api-action) to avoid creating Ably apps/API keys manually.
-8. Add this repository to the [selected repositories in the Ably Labs org](https://github.com/organizations/ably-labs/settings/actions) that are allowed to run GitHub Actions.
+- [ ] Add this repository to the [selected repositories in the Ably Labs org](https://github.com/organizations/ably-labs/settings/actions) that are allowed to run GitHub Actions.
+- [ ] Add (e.g. just subscribe on a single channel like {"my-channel": ["subscribe"]}) to docs
 
-Once you're done, remove this section from the README. Good luck! 💪
 
----
+## Description
 
-![Place eye candy header image here](https://placekitten.com/640/360)
+// Explanation of the contents of the repository. Describe the use case.
 
-*// Place eye candy header image here ⬆️*
 
-## Description
+## What you'll need
 
-// Explanation of the contents of the repository. Describe the use case.
+1. An Ably API Key, sign up for a [free account](https://ably.com/sign-up)
+1. A [Netlify](https://netlify.com) account to host and manage your registered users.
+1. A [Github](https://github.com) account is required to link Netlify to the repository.
+
+# Overview of architecture
+
+This is the overview of our app. Our user experience requires a new user to register and confirm their email address to activate themselves with our app before they can log-in. When they login we validate them with Netlify Identity and check that they have not been flagged as Banned. Bad actors are not issued with a JWT token. Valid users are issued a token, to authenticate with Ably, and the authentication URL carries the user's unique ID.
+
+![](./assets/user-experience-netily-functions.png)
+
+The Netlify Identity allows us to administer users by editing metadata associated with their account, flagging a bad actor is a matter of assigning them a role via the Netlify dashboard.
+
+## Initial steps
+1. Fork this repository
+1. Use Netlify dashboard to create a new project, and select your fork as the source.
+1. Activate the Netlify identity serverices on the Identity section.
+1. Add the environment variables to the new Netlify app from the site settings section, under `Build & deploy`
+1. Deploy the website, visit the homepage and sign-up as a new user.
+1. Log-in with the confirmed user and you'll be able to connect to Ably realtime
 
-## Tech stack
+## Environment variables
 
-![A high level architecture diagram tells more than a 1000 words](https://placekitten.com/480/240)
+![](assets/netlify-environment-vars.png)
 
-*// A high level architecture diagram tells more than a 1000 words ⬆️*
+## Register a new user to your app
+
+At this point your setup is complete, and you can start adding users. Open the
+website and use the sign-up link to add a user. This will trigger an email
+confirmation and when that is complete your new user will be able to login
+and connect to the Ably realtime network.
+
+
+## Banning a User from connecting
+
+Lets us pretend that one of your registered users needs to be banned. We can do
+this by modifiying their account metadata, and assigning a role of `Banned`
+
+1. Log-in to the Netlify dashboard for your app.
+1. Go to the `Identity` section, and select a User account.
+1. Edit the User metadata, and add the string `Banned` to the role and save.
+1. Then return to the website, login as that user and click connect.
+
+This will cause the next authentication attempt by that user to fail,
+the JWT will not be issued to that User and display an error message.
+
+Conversely you can revese the bann by clearing the assigned role.
+
+![netlify-user-metadata](./assets/netlify-user-metadata.png)
+
+## Running localhost
+
+The majority of the Netlify functionality can be reproduced locally by using the Netlify CLI tool.
+However the Identity features will not behave as expected when using local development server.
+This is a known constraint and Identity functionality requires the production server.
 
-The project uses the following components:
 
-- [X](), brief explanation of the component
-- [Y](), brief explanation of the component
-- [Ably](https://ably.com/), for realtime messaging at scale.
 
 ## Building & running locally
 
@@ -66,26 +100,4 @@ We have a [contributing guide](CONTRIBUTING.md) that explains how to contribute
 - [Ably.com](https://ably.com)
 
 ---
-<svg width="108" height="32" viewBox="0 0 108 32" xmlns="http://www.w3.org/2000/svg">
-    <path d="M62.922 24.9786V4.08813H66.6933V11.6512C67.9709 10.435 69.6164 9.76044 71.3538 9.76044C75.4318 9.76044 79.0498 12.8674 79.0498 17.5484C79.0498 22.2293 75.4318 25.3465 71.3538 25.3465C69.5244 25.3465 67.7971 24.6209 66.5094 23.3024V24.9786H62.922ZM75.2785 17.5484C75.2785 14.932 73.4183 13.1025 70.9859 13.1025C68.6148 13.1025 66.7853 14.84 66.6933 17.3644V17.5484C66.6933 20.1648 68.5534 21.9942 70.9859 21.9942C73.4183 21.9942 75.2785 20.1648 75.2785 17.5484ZM80.7975 24.9786V4.08813H84.5688V24.9786H80.7975ZM89.8425 30.3954L92.0399 25.1523L86.0712 10.1284H90.1491L93.9511 20.6247L97.8144 10.1284H101.954L93.8591 30.4056H89.8425V30.3954ZM56.9329 10.1284V12.0191C55.6247 10.5883 53.7952 9.77066 51.9147 9.77066C47.8367 9.77066 44.2187 12.8777 44.2187 17.5586C44.2187 22.2497 47.8367 25.3465 51.9147 25.3465C53.8668 25.3465 55.7166 24.4982 57.0555 22.9754V24.9888H60.3465V10.1284H56.9329ZM56.5649 17.5484C56.5649 20.1341 54.7048 21.9942 52.2724 21.9942C49.8399 21.9942 47.9798 20.1341 47.9798 17.5484C47.9798 14.9626 49.8399 13.1025 52.2724 13.1025C54.6435 13.1025 56.473 14.8706 56.5649 17.3644V17.5484Z" fill="currentColor"></path>
-    <path d="M19.2858 0L3.14788 29.5369L0 27.3293L14.932 0H19.2858ZM19.5107 0L35.6487 29.5369L38.7965 27.3293L23.8646 0H19.5107Z" fill="url(#paint0_linear)"></path>
-    <path d="M35.4238 29.7107L19.3983 17.16L3.37271 29.7107L6.64323 32L19.3983 22.0147L32.1533 32L35.4238 29.7107Z" fill="url(#paint1_linear)"></path>
-    <defs>
-      <linearGradient id="paint0_linear" x1="5.47361" y1="37.4219" x2="32.4603" y2="7.45023" gradientUnits="userSpaceOnUse">
-        <stop stop-color="#FF5416"></stop>
-        <stop offset="0.2535" stop-color="#FF5115"></stop>
-        <stop offset="0.461" stop-color="#FF4712"></stop>
-        <stop offset="0.6523" stop-color="#FF350E"></stop>
-        <stop offset="0.8327" stop-color="#FF1E08"></stop>
-        <stop offset="1" stop-color="#FF0000"></stop>
-      </linearGradient>
-      <linearGradient id="paint1_linear" x1="10.7084" y1="39.3593" x2="26.6583" y2="21.6452" gradientUnits="userSpaceOnUse">
-        <stop stop-color="#FF5416"></stop>
-        <stop offset="0.2535" stop-color="#FF5115"></stop>
-        <stop offset="0.461" stop-color="#FF4712"></stop>
-        <stop offset="0.6523" stop-color="#FF350E"></stop>
-        <stop offset="0.8327" stop-color="#FF1E08"></stop>
-        <stop offset="1" stop-color="#FF0000"></stop>
-      </linearGradient>
-    </defs>
-</svg>
+