Forem: Riccardo Perra

SpecFlow - Integrating Hanko and Supabase in a Solid.js client-side application

Riccardo Perra — Sat, 28 Oct 2023 19:22:37 +0000

Lately at work I've had the need to write technical documentation and have to generate different types of diagrams and share them.

I've always used the mermaid live editor but found it rather inconvenient, so I took advantage of hanko's hackathon to build SpecFlow: a tool which allows you to centralize all your project specs and documentation.

What's Hanko?

From their GitHub:

Hanko is an open-source authentication and user management solution with a focus on moving the login beyond passwords while being 100% deployable today.

Built for passkeys as introduced by Apple, Google, and Microsoft

Fast integration with Hanko Elements web components (login box and user profile)

API-first, small footprint, cloud-native

It's a really interesting solution and is probably now the one that allows you to integrate passkeys in the easiest/fastest way possible.

About SpecFlow

SpecFlow is an open-source tool available on GitHub and hosted on Netlify which uses Hanko for authenticate their users. Its'currently an MVP.

Repository

riccardoperra / specflow

Write markdown documentation and generate mermaid diagrams with ease - Made with Hanko, SolidJS and Supabase.

SpecFlow

Note

SpecFlow is an open-source tool (MIT License) made for the Hanko hackathon It's an MVP made in less than two weeks far away to be a complete product, born with the aim of testing integrations and interactions between new tech/libraries, and to better understand the authentication flow by also integrating passkeys.

More in detail, in this project I experiment with Hanko's authentication by integrating it with a third party system like supabase, the latter used trying to take advantage of the generated types, RLS policies, realtime and edge functions.

Furthermore, I made a small use of OpenAI API via edge functions to generate code directly from a user-defined prompt.

This project it's also a way to improve my UI Kit library based on Kobalte and Vanilla Extract that I'm working on, initially born to be the CodeImage design system.

Read the integration post:

https://dev.to/riccardoperra/specflow-integrating-hanko-and-supabase-in-a-solidjs-client-side-application-550m

💡 Features

✅…

View on GitHub

App

specflow.netlify.app

It hasn't obviously created to replace products currently existing on the market, but it's a way for me to try new technologies and see how they perform together.

SpecFlow is mainly designed to to succeed in these tasks:

✅ Secure your data so that it is only accessible if authenticated
✅ Write project notes, requirement and specifications using a Markdown-like interface.
✅ Write and export diagrams such as sequence diagrams, ER, Mind maps etc. complaint to mermaid syntax.
✅ Make a small use of AI to see how to integrate OpenAI into an application

💻 Screenshots

Login page

Passcode challenge

Dashboard

Project page - Markdown editor

Project page - Diagrams editor

Project page - Exports a diagram

Profile page

🤖 Tech stack

SpecFlow is a client-side SPA built using SolidJS as a front-end framework, Supabase for database, realtime, edge functions...and Hanko to handle the authentication.

All styles have been made with Vanilla-Extract and Tailwind integrating a design system I used for CodeImage which is a wrapper of Kobalte

To manage the editor I used CodeMirror6 and Tiptap, the latter used to preview the markdown having the chance one day to also integrate a wysiwyg editor.

For a better development experience, I also integrated MockServiceWorker in order to be able to mock the entire auth flow and develop by integrating Hanko components without disturbing the server.

🔐 Integrating Hanko in a SolidJS application

Hanko employes did a really great job regarding the documentation: everything is extremely clear and ready to use.

https://docs.hanko.io/introduction

Currently there isn't a dedicated guide for SolidJS, then I've followed a bit the documentation of react/angular docs, but the steps for Solid are almost identical.

Integrating Hanko in a SPA

First of all, we need to install the @teamhanko/hanko-elements package, which will contains the Auth and Profile web components which we will use later to manage authentication.

pnpm add @teamhanko/hanko-elements

Once installed, we should retrieve the Hanko API URL from their cloud console and place it in our .env file.

VITE_HANKO_API_URL=https://f4****-4802-49ad-8e0b-3d3****ab32.hanko.io

Next, we can integrate the auth web component by importing the register function in order to register <hanko-auth> and <hanko-profile> with the browser CustomElementRegistry.

Note that unlike react, we need to overwrite the SolidJS namespace to add hanko's custom elements.

import { onMount } from "solid-js";
import { register } from "@teamhanko/hanko-elements";

const hankoApi = import.meta.env.VITE_HANKO_API_URL;

export function HankoAuth() {
  onMount(() => {
    register(hankoApi).catch((error) => {
      // handle error
    });
  });
  return <hanko-auth />;
}

type JsxIntrinsicElements = JSX.IntrinsicElements;

declare module "solid-js" {
  namespace JSX {
    interface IntrinsicElements {
      "hanko-auth": JsxIntrinsicElements["hanko-auth"];
    }
  }
}

Once done, we are able to use our component in order to authenticate. The same steps could be done for the Profile page.

🔐 How's Hanko can be leveraged with Supabase

We have seen that in a few lines of code you can integrate Hanko into your application, but now comes the challenging part: the integration with supabase.

Supabase Database comes with a useful RLS policy which
allows to restrict the data access using custom rules (postgres policies).

In a traditional supabase application we've could used it's authentication system and make use of the Auth client of their library.

In SpecFlow, Hanko is replacing supabase auth, so we need to somehow make supabase understand who is making the requests in order to apply all related policies. For example we need that each user can view or update only the entities he own.

To authenticate these requests, we can sign our own JWT that contains the necessary info for supabase in order to apply the policies.

In the steps following we will cover the creation of a JWT that contains hanko's user_id signing it with the supabase private key, and then integration with supabase database and the UI.

1. Creating a postgres function for supabase to retrieve a `user_id` from a given jwt.

In The first step we'll create a postgres function which will extract the hanko user_id from a JWT in order to let supabase knows which user is authenticated.

create function auth.hanko_user_id() returns text as $$
select nullif(current_setting('request.jwt.claims', true)::json ->> 'userId', '')::text;
$$
language sql stable;

2. Creating a postgres policy to restrict our data

We can now define a new policy in order to restrict our data. The following example uses a todos table as an example.

CREATE POLICY "Allows all operations" ON public.todos
AS PERMISSIVE FOR ALL
TO public
-- ✅ Use our user_id function to get hanko user_id from jwt
USING ((auth.hanko_user_id() = user_id))
WITH CHECK ((auth.hanko_user_id() = user_id));

ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;

3. Writing the business logic to sign our custom JWT

The signing of the JWT must always be done server-side in order to keep our private keys safe.

Since we are using supabase we can take advantage of their edge-functions (https://supabase.com/docs/guides/functions) that runs on Deno in order to build the JWT.

Another solution would have been for example to have a custom backend or to use a full stack front-end framework like Solid Start

You can read more info about jwt here.

We've to carry out 3 steps:

Retrieves Hanko jwks configurations. JWKS is a set of keys containing the public keys used to verify any JSON Web Token
Thanks to the JWKS we can verify the Hanko JWT sent from the UI request in order to be sure it's a valid token.
Signing a new JWT valid for supabase including in the payload the hanko user_id claim.

import * as jose from "https://deno.land/x/jose@v4.9.0/index.ts";

Deno.serve(async (req) => {
  const session = ((await req.json()) ?? {}) as { jwt: string };
  const hankoApiUrl = Deno.env.get("HANKO_API_URL");

  // 1. ✅ Retrieves Hanko JWKS configuration
  const JWKS = jose.createRemoteJWKSet(
    new URL(`${hankoApiUrl}/.well-known/jwks.json`),
  );

  // 2. ✅ Verify Hanko token
  const data = await jose.jwtVerify(session.jwt, JWKS);

  const payload = {
    exp: data.payload.exp,
    userId: data.payload.sub,
  };

  // 3. ✅ Sign new token for supabase using it's private key
  const supabaseToken = Deno.env.get("PRIVATE_KEY_SUPABASE");
  const secret = new TextEncoder().encode(supabaseToken);
  const token = await jose
    .SignJWT(payload)
    .setExpirationTime(data.payload.exp)
    .setProtectedHeader({alg: "HS256"})
    .sign(secret);
  return new Response(JSON.stringify({token}))
})

Once the edge function is deployed, we intercept the event once we are authenticated.

4. Calling our API from the front-end

The Hanko package is exporting an Hanko class which is the client that allows us to retrieve the session info and listen for some specific events.

In our case we can take advantage of the onAuthFlowCompleted() event, which will be triggered once we complete the login flow.

Inside that event we must invoke our edge function passing the hanko JWT, then we should patch supabase headers in order to put the right Authorization Bearer token.

import { register, Hanko } from "@teamhanko/hanko-elements";
import {createClient} from "supabase";

const supabaseUrl = import.meta.env.VITE_CLIENT_SUPABASE_URL;
const supabaseKey = import.meta.env.VITE_CLIENT_SUPABASE_KEY;
const hankoApi = process.env.REACT_APP_HANKO_API_URL;

const supabase = createClient(supabaseUrl, supabaseKey);
const hanko = new Hanko(hankoApi);

hanko.onAuthFlowCompleted(() => {
  const session = hanko.session.get();
  supabase.functions.invoke(
    'our-function-name', 
    { jwt: session.jwt }
  ).then(result => {
    const token = result.data.token;
    patchSupabaseRestClient(token);
  })
});

export function patchSupabaseRestClient(accessToken: string | null) {
  // ✅ Set functions auth in order to put the jwt token 
  // for edge functions which need authentication
  client.functions.setAuth(accessToken ?? supabaseKey);
  if (accessToken) {
    // ✅ Patching rest headers that will be used 
    // for querying the database through rest.
    client["rest"].headers = {
      ...client.rest.headers,
      Authorization: `Bearer ${accessToken}`,
    };
  } else {
    client["rest"].headers = {
      ...client.rest.headers,
      Authorization: `Bearer ${supabaseKey}`,
    };
  }
}

It's done! Now all the calls that will use the supabase rest client to query the db will contain our token containing the user_id.

✅ The request will contains our custom jwt token
supabase.from("todos").select("*")

🖌️ Styling Hanko Elements

Hanko Elements exports two useful web components that allows to handle the auth flow and the user profile.

There are several ways to customize
them (docs).

For SpecFlow I followed two approaches:

Vanilla-Extract to verride css variables and define all styles via ::part attribute
Plain CSS to override some internal elements inside the shadow dom. This is the case for the accordion component in the profile page. Note that I didn't disable the shadow dom since the hanko authors don't recommend it

I tried to follow my UI Kit tokens in order to make something that fits good inside this application.

First, I made a solid component for each web component in order to decouple it's logic, and to extend some behaviors and
the JSX interface, since solid has its own.

Each web component will have attached the custom classes generated by vanilla-extract, and a custom <style> tag inside
the shadow dom which I add once the component is mounted to the dom.

// src/components/auth/HankoAuth.tsx
import * as styles from "./HankoAuth.css";
import {onMount} from "solid-js";
import overrides from "./hanko-auth-overrides.css?raw"; // Get the css text from the file.

export function HankoAuth() {
  let hankoAuth: HTMLElement;

  onMount(() => {
    const styleElement = document.createElement("style");
    styleElement.textContent = overrides;
    hankoAuth.shadowRoot!.appendChild(styleElement);
  });

  return (<hanko-auth ref={(ref) => (hankoAuth = ref!)} class={styles.hankoAuth}/>);
}

type JsxIntrinsicElements = JSX.IntrinsicElements;

declare module "solid-js" {
  namespace JSX {
    interface IntrinsicElements {
      "hanko-auth": JsxIntrinsicElements["hanko-auth"];
    }
  }
}

The generated class from vanilla-extract will contain all custom vars and base styles defined through a base class, and
the custom ones needed only for the auth/profile component. Basically, I made the base styles for the "Layout"
components like buttons, forms, headlines etc.

import {style} from '@vanilla-extract/css';
import { themeTokens, themeVars } from "@codeui/kit";

const [hankoTheme, hankoVars] = createTheme({
  brandColor: themeVars.brand,
  dangerColor: "#500f1c",
  buttonCriticalColor: themeVars.critical,
  containerPadding: themeTokens.spacing["6"],
  foregroundColor: themeVars.foreground,
  // Other vars...
});

export const base = style([
  hankoTheme,
  {
    vars: {
      // Overrides hanko vars
      // https://github.com/teamhanko/hanko/tree/main/frontend/elements#css-variables
      "--color": hankoVars.foregroundColor,
      "--brand-color": hankoVars.brandColor,
      // Other vars...
    },
    selectors: {
      // Base layout styles
      "&::part(error)": {
        background: hankoVars.dangerColor,
        color: hankoVars.foregroundColor,
        border: "unset",
        padding: `0 ${themeTokens.spacing["4"]}`,
        gap: themeTokens.spacing["2"],
      },
      // Button styles
      "&::part(button)": {
        border: "none",
        transition: transitions,
      },
      // Input styles
      "&::part(input text-input), &::part(input passcode-input)": {
        padding: `0 ${themeTokens.spacing["4"]}`,
      },
      // Other styles...
    }
  }
]);

export const hankoAuth = style([
  base,
  {
    // custom styles for hanko auth wc...
  }
]);

export const hankoProfile = style([
  base,
  {
    // custom styles for hanko profile wc...
  }
])

The override file will contain only some particular styles that cannot be accessed outside the shadow dom.

/* src/components/Auth/hanko-profile-overrides.css */

.hanko_paragraph:has(h2.hanko_headline) {
    color: var(--paragraph-inner-color);
}

🚀 Conclusion

In the end, Hanko was a great discovery. It's a new system that rightly doesn't have all the features yet, but it's really promising.

Integrating it and managing the entire server-side part was not complex, the documentation, I repeat, is very well done therefore it is a system accessible to anyone.

Anyway, partecipating in this hackathon reminded me of the times I worked at CodeImage, trying many new technologies and learning many new things.

If you made it this far, thank you 😊. Feedback and/or a star is always appreciated

All related code of SpecFlow it's available on GitHub.
https://github.com/riccardoperra/specflow.

My others projects:

IssueManager - A realtime kanban board made with Appwrite and Angular14

Riccardo Perra — Thu, 12 May 2022 23:53:38 +0000

Overview of My Submission

IssueManager is an application built with Angular 14 and AppWrite. It's a small kanban management tool inspired by GitHub Projects, which make use of some Appwrite features like Account, Database, Realtime, Functions, Storage and Teams.

I took the opportunity of this hackathon to create a project different from the usual clones, with the purpose of learning how Appwrite works and to try the newest Angular features in a real world application 😊.

Submission Category:

Web2 Wizards

Link to Code

riccardoperra / issue-manager

A realtime kanban management tool built with Appwrite and Angular

IssueManager

A kanban management tool made with Angular and Appwrite

⚠️ READ THIS

This project is a demo, born mainly to test Appwrite integration with Angular experimental features, and it's not ready for production! The site currently online is a test and will be discontinued soon. Once discontinued, you will need to self-host appwrite to try the application

🎯 About

IssueManager is an application built with Angular 14 and AppWrite for the AppWrite Hackathon.

It's a small kanabn management tool inspired by GitHub Projects leveraging of some AppWrite features such as Account, Database, Realtime, Functions, Storage, Teams.

🚀 Technologies

The frontend is built with Angular 14 using entirely the new Standalone Component feature. angular/angular#43784

It also includes RxAngular, a toolset focused on runtime performance and template rendering taiga-ui, an UI component library.

WYSIWYG editor is built with Lexical and a small…

View on GitHub

Additional Resources / Info

The frontend is built with Angular 14 using Standalone Components. https://github.com/angular/angular/discussions/43784

For Angular users, this mean that this application is built entirely without modules, although I had to come up with some workarounds to get all the libraries that don't fully support it work properly.

It also includes RxAngular, a toolset focused on runtime performance and template rendering, and taiga-ui, an UI component library.

WYSIWYG editor for task editing is built with Lexical and a small angular wrapper made by my-self (the repo is currently private but available to NPM).

✅ Features

Authentication

IssueManager authentication system is entirely based on Appwrite, and currently supports login and registration via Email/Password, Google and Github.

Creating a new project

Each authenticated user has the possibility to create a new project to IssueManager. A project is a kanban board where you can track your tasks.

Creating a project involves a series of processes to create the user's workspace, in fact thanks to an Appwrite function that will first craete a new Appwrite Team where the user which has created the project is the owner, next it will create a new Appwrite Storage Bucket where users can upload their files, then it will finally creates the Project entity to the database.

A project can be either public or private. When creating a public project, every user is able to view it even if it cannot update it. Private projects, on the other hand, can only be seen and updated by team members.

The Realtime feature is used to update automatically the list of available projects in the case that the project is deleted or if his visibility changes, in order to notify all users

Managing the board

After creating a new project, users can access the board and can start to manage their tasks. Thanks to Appwrite realtime, each user which is visiting the board at that time will always have the updated issues on their screen.

Users have the possibility to create, archive or re-order a new Category, then to create and move the Tasks inside just like a Kanban board. The ordering is made with JIRA LexoRanks in order to optimize the performances and database requests.

Adding new members to the board

Users which have the authorities to update the board can also invite new members and allow them to view the board. Once the user's e-mail in question has been entered, it will be sent to his mailbox and must be accepted to enable the user for the project.

Viewing and updating tasks

Each created task of the kanban board can be readed and updated. Users can manage their task updating the expiration date, priority and also the description. The WYSIWYG is made with Lexical and lexical-angular (Angular binding for lexical, which is currently a private repo in development, but already available to NPM.

Adding attachments to tasks

Thanks to Appwrite Storage, the user has the possibility to manage the attachments of a task. Attachments consists of uploaded files that can be downloaded, deleted or viewed (if the preview is
available).

🌐 Demo

A live deployment of the app is available to try it out. You must login to access the application pages but you are able to delete your account if you need to.

Some useful links:
issue-manager - Demo application
codeimage.dev - My latest project