Skip to content

Latest commit

 

History

History
246 lines (152 loc) · 6.98 KB

README-hatter.md

File metadata and controls

246 lines (152 loc) · 6.98 KB

Project: Brainiac Hatter

Building an internal documentation website or knowledge base.

Suppose we are building a documentation website for a fictional company: WonderWorks (wonderworks.example).

We call its employees brainiacs, after their founder Hatter the Brainiac.

Branding

Naming

Brainiac Hatter.

Hatter conceived the whole thing.

As in, "His geegantic brain conceived the whole thing, and I tell you it's a corker." -- Alice in Blunderland

Hatter, hats, meaning different job titles, roles, and/or tasks.

Quote

Tone: friendly, whimsical, encouraging.

Options:

  • Only a few find the way, some don't recognize it when they do - some... don't ever want to. Want to log in?

  • A very little key will open a very heavy door. Do login!

  • Who in the world am I? Ah, that's the great puzzle. Ready to solve it? Login!

  • Why, sometimes I've believed as many as six impossible things before breakfast. How about you? Login!

Original quotes:

  • "Only a few find the way, some don't recognize it when they do - some... don't ever want to." -- American McGee's Alice

  • "A very little key will open a very heavy door" -- Charles Dickens, Hunted Down

Possible concerns

  • Employee leaves the company.

  • Vendor lock-in or some features we depend on (i.e. Vercel Edge Middle) getting changed.

Technicalities

Requirements:

  • Req1: Markdown-based
  • Req2: Content is framework-agnostic (viewable on GitHub Pages or VSCode. This mainly means that assets like images are stored alongside pages).
  • Req3 Authentication (GitHub, Google, Discord, or whatever).

Preferences:

  • Vue or React.
  • It's fine if it uses/requires YAML frontmatter.

How it works

See Sequences.

Assumptions

  • Every member has a Google account (Gmail).

Source of truth

  • Discord is the source of truth when it comes to members and their assigned roles.

  • (Notion? Google Sheets?) There is an external source that maps a Discord user ID to the employee's email and name.

  • Our Discord users and roles are upserted to Auth0.

  • Auth0 allows importing and exporting data (e.g. users with roles and other metadata) programmatically.

  • Our Auth0 app contains a predefined list of users and roles.

  • Auth0 is configured to:

    • Support sign-in with Google.
    • Issue access tokens with lifetime = 2 hours.
    • Issue (rotating?) refresh tokens with lifetime = 3 months.
    • Before refreshing a token, we can check that the user is not blocked and still has the required roles.

Middleware

Validate the auth token; otherwise, return the login page.

Choosing

TLDR:

  • GitHub repo as CMS to write content in markdown.
  • VitePress to render markdown as a website.
  • Vercel to serve the static website.
  • Vercel Edge Middleware to restrict access by verifying access tokens.
  • Auth0 to provide and revoke access to the website.
    • Login with Google.
    • Access tokens have a short lifetime for access tokens (say, 2 hours).
    • Refresh tokens have a long lifetime (say, 3 months).
    • Users (e.g. employees who leave the company) are blocked via the Auth0 Dashboard.

See tests:

Writing

Options:

Hosting platform

GitBook, Vercel, and Netlify require a pro plan to enable protection and SSO login. We can use Vercel Edge Middleware to implement login logic ourselves.

Options:

Authentication providers

Auth0

The following script was tested with Google as an identity provider ("Login with Google").

Login action script:

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  const DEV_ROLE = 'DEV';
  const hasDevRole = (/** @type {Event} */ e) => e.authorization?.roles.includes(DEV_ROLE);
  const isBrainiac = (/** @type {string} */ x) => x.endsWith('@wonderworks.example');
  const isDreamski = (/** @type {string} */ x) => x === '[email protected]';

  const email = event.user.email ?? '';
  const isAllowed = isBrainiac(email) || isDreamski(email) || hasDevRole(event);
  if (!isAllowed) {
    api.access.deny(`Access to ${event.client.name} is not allowed.`);
  }
};

Bot

Task: Sync from Discord

  • Discord is the source of truth.

  • Discord get members, get roles.

  • Auth0 get users, get roles, set roles, get is banned.

    • About Google as an Identity Provider: Since Auth0 is federated, so we don't need to publish our app or register test users to use OAuth and stuff.

  • Vercel Redis, Postgres, Config Service: Update blacklist.

  • Netlify supports Vercel/Nextjs Middle (middleware.ts).

Middleware

If not Vercel Edge Middleware, we could use of these are the alternatives:

END.