Skip to Content
This project is in active development. Features and behaviors may change without notice.
DocumentationQuick Start

Tutorial Guide

Implementing SAuthBase in a Hono + TypeScript App

This tutorial demonstrates how to build a basic authentication feature using Hono  and TypeScript .

Setting Up Hono

The easiest way to create a new Hono app is to use create-hono. This will automatically set up everything. To create a project, run the following:

In this tutorial, we will use the directory name my-app. Please change it as needed.

terminal
npm create hono@latest

When installing, you will see the following prompts:

terminal
1. Target directory (my-app)
2. Which template do you want to use? nodejs
3. Do you want to install project dependencies? Yes / No
  1. Specify the directory

Specify the path for the directory to be created. If you leave it blank, it will default to my-app.

  1. Choose a template

You can navigate with arrow keys or search by typing characters. For this tutorial, select nodejs.

  1. Install dependencies

You will need to install dependencies eventually, so either choice is fine. (Yes is recommended)

Move to the Hono app you just created.

Replace my-app with the path to your created Hono app.

terminal
cd my-app

Confirm that your current file structure looks like this:

      • index.ts
    • .gitignore
    • package.json
    • README.md
    • tsconfig.json

Install SAuthBase

terminal
npm i sauthbase

Sample Working File

We will implement the functionality in this file.

TypeScript
import {  } from "hono";
import {  } from "@hono/node-server";
 
const  = new ();
 
.("/", () => {
  return .("Hello Hono!");
});
 
(
  {
    : .,
    : 3000,
  },
  () => {
    .(`Server is running on http://localhost:${.}`);
  }
);

Initialize SAuthBase

sauthbase requires initialization once before using it in your project. It is recommended to initialize it in a root file such as src/index.ts.

TypeScript
const  = .({
  : "************************************",
  : "http://localhost:3000/auth",
});

Create Login Endpoint

Accessing /login will redirect you to the Scratch Auth authentication page.

src/index.ts
.("/login", () => {
  const  = .();
  if (.) {
    return .(.);
  } else {
    return .();
  }
});

Create Session Verification Endpoint

At /auth, the user session is verified.

The Scratch Auth service appends a query parameter called privateCode to the redirect URL. You retrieve this code and pass it to verifySession to verify the session. If verification succeeds, an encrypted token is generated.

src/index.ts
.("/auth", async () => {
  const  = ..("privateCode");
  const  = await .();
  if (.) {
    return .();
  } else {
    return .();
  }
});

Create Token Verification Endpoint

At /verify, the encrypted token is verified.

Verify the encrypted token and retrieve the username.

src/index.ts
.("/verify", async () => {
  const  = ..("token");
  const  = await .();
  if (.) {
    return .();
  } else {
    return .();
  }
});

Full Example Code

src/index.ts
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { sauthbase } from "sauthbase";
 
const app = new Hono();
const sab = sauthbase.init({
  secretKey: "**************************************************",
  redirect_url: "http://localhost:3000/auth",
});
 
app.get("/", (c) => {
  return c.text("Hello Hono!");
});
 
app.get("/login", (c) => {
  const response = sab.generationAuthPageUrl();
  if (response.success) {
    return c.redirect(response.data);
  } else {
    return c.json(response);
  }
});
 
app.get("/auth", async (c) => {
  const session = c.req.query("privateCode");
  const response = await sab.verifySession(session);
  if (response.success) {
    return c.json(response);
  } else {
    return c.json(response);
  }
});
 
app.get("/verify", async (c) => {
  const token = c.req.query("token");
  const response = await sab.extractUserWithVerify(token);
  if (response.success) {
    return c.json(response);
  } else {
    return c.json(response);
  }
});
 
serve(
  {
    fetch: app.fetch,
    port: 3000,
  },
  (info) => {
    console.log(`Server is running on http://localhost:${info.port}`);
  }
);

Test the Application

Great job! You have now completed a basic authentication feature. Let’s test it out.

terminal
npm run dev

When the server starts successfully, you will see the following log. Try accessing the link.

terminal
Server is running on http://localhost:3000

Access /login

Try accessing /login!

If you are redirected to a URL like the following, it’s successful. If you don’t have an account to sign in with, please link your Scratch Auth and Scratch accounts before trying again.

Once ready to sign in, select the account you want to use and sign in.

https://auth.itinerary.eu.org/auth?redirect=*****&name=*****

Access /auth

If you are redirected to a URL like the following, it’s successful.

http://localhost:3000/auth?privateCode=*********

If the success field in the JSON response is true, authentication succeeded. The generated token is in data.token.

Response
{
  "success": true,
  "data": {
    "token": "********************************************************,
    "payload": {
      "valid": true,
      "username": "*************",
      "type": "instant",
      "redirect": "http://localhost:3000/auth"
    }
  }
}

Access /verify to Verify Token

Set the token query parameter with the token generated earlier and access this endpoint.

If the success field in the JSON response is true, verification succeeded. The username is in data.

Response
{
  "success": true,
  "data": "*********"
}

Conclusion

This concludes the “SAuthBase, Hono, TypeScript Tutorial Guide”. Thank you for your hard work.

Last updated on
InstallationUsage
Quick Start - SAuthBase