DEV Community: Smitter

Building my portfolio like it's infinity gauntlet

Smitter — Sat, 31 Jan 2026 19:23:24 +0000

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

Hi there! I'm Zacky, a Fullstack Developer enthusiastic about building applications that solve real-world "people problems".

I work across the stack to bring ideas to life, primarily utilizing JavaScript, Node.js, PHP, PostgreSQL, and MySQL. Recently, I've also been diving deep into the world of Rust.

My development philosophy centers on creating tools that help others. For example, I created and maintain RLI, an open-source React component library of elegant loading indicators that has a growing popularity on NPM.

I built this portfolio to showcase not just my projects, but my ability to blend technical "how-to" with creative, interactive design.

Portfolio

(Note: If the embed above doesn't work, you can view the live site here: zacky.dev)

How I Built It

For this portfolio, I wanted a tech stack that offered the speed of a Single Page Application (SPA) with the security and robustness of a backend.

The Stack & Tools

Framework: Remix.js (Fullstack React framework)
Noteworthy Libraries Three.js, Material UI
Language: TypeScript
Deployment: Google Cloud Run
Code Editor: Antigravity

Design Decisions

Hybrid Architecture: Using Remix allowed me to keep the user experience snappy (SPA feel) while securely handling sensitive credentials and logic on the server side.
Performance: I implemented lazy loading for pages to ensure the initial load time is instant, fetching resources only when the user needs them.
Accessibility & UX: The site features a meticulously designed Dark and Light mode, giving users control over their viewing preference. The UI was designed to be visually appealing and modern without sacrificing intuitiveness to finding information without clutter.
SEO: Sever Side Rendering enable the website to load rendered pages to help boost SEO ranking.

The AI Assistant

I utilized Google Gemini 3.0 and Antigravity code Editor throughout the development process. Gemini was a personal tutor throughout the development process.
When I was stuck on complex logic, Gemini broke down the deep concepts, allowing me to understand the "why" before I patched up the "how."

What I'm Most Proud Of

1. Successful GCP Deployment

I am extremely proud of the successful deployment of this portfolio to Google Cloud Run. It was a significant achievement for me, as it demonstrated my ability to deploy a full-stack application to the cloud. The deployment process was smooth and seamless, and I was able to find information I needed from the Docs.

2. The 3D Interactive Experience

I am extremely excited about the 3D interactive page. I wanted to move beyond standard web layouts, so I decided to write custom shaders to render 3D animations directly in the browser. I used ThreeJS to achieve this.

This was a steep learning curve. Gemini 3.0 was instrumental here; it helped me bridge the gap between my JavaScript knowledge and the complex math required for shader languages. The result is a fluid, interactive visual that I think really shines spotlight on the portfolio.

3. Fully responsive design

Responsive design is important for any website, and I'm proud to have implemented it in this portfolio. I used a combination of CSS media queries and JavaScript to ensure that the website is accessible on all devices.

4. Solving Problems (The RLI Library)

I'm also proud to feature my open-source work directly on the site. Showcasing RLI (React Loading Indicators) demonstrates that I don't just build websites; I build solutions that other developers rely on. Seeing that project pull traction on NPM is a huge motivator for me to keep shipping open-source code.

Thank you very much for reading this far. Your thoughts and feedback are much appreciated.

I built Zeet. A Git-like version Control System

Smitter — Mon, 13 Jan 2025 06:52:00 +0000

🚀 Source Code

You can find the source code for Zeet on GitHub.

🎬 DEMO

Motivation

Some time back, my curiosity about the inner workings of Git led me on an exciting journey. I sifted through various resources(though not Git’s source code) to understand how Git works. Inspired, I wrote an article summarizing my findings. What stook with me from git-scm book:

The major difference between Git and any other VCS (Subversion and friends included) is the way Git thinks about its data.

Conceptually, most other systems store information as a list of file-based changes.

Git doesn’t think of or store its data this way. Instead, Git thinks of its data more like a series of snapshots of a miniature filesystem.

That insight stayed with me, but I didn't do much with it—until I stumbled upon a challenge to build a Version Control System (VCS). I embraced it eagerly, seeing it as an opportunity to transform my theoretical knowledge into a tangible project. And so, I worked on Zeet—a lightweight, Git-inspired VCS built with Node.js.

How Zeet Works

Much like Git, Zeet manages repository versions as snapshots. It uses a .zeet directory to store all its data locally, but unlike Git, the snapshots are not compressed.

The process involves three main areas:

Working Directory: Where you edit files.
Staging Area: Files added here are prepared for commits.
Local Database: Stores snapshots of committed changes.

Zeet captures the essence of Git while offering simplicity for educational and hobbyist purposes.

Features of Zeet

🛠️ What Zeet Can Do

Repository Initialization: Create a Zeet repository with a .zeet subdirectory.
Staging Files: Add files to the staging area before committing.
Committing Changes: Save staged files to the local database with descriptive messages.
Branching: Work on parallel branches and switch between them effortlessly.
Merging: Merge branches intelligently using fast-forward or 3-way merges.
Conflict Detection and Resolution: Detect conflicts during merges, mark them with symbols (<<<<<<<, =======, >>>>>>>), and resolve them manually.
File Ignoring: Specify files to ignore using .zeetignore or .gitignore.
Commit History: View detailed and colorized logs of commit histories.
Diffs: Compare changes between commits, branches, or files.

🛑 What Zeet Cannot Do (Yet)

Show the repository status beyond staged, untracked, or deleted files.
Clone remote repositories.
Perform rebase merges.

How to use Zeet

Install Zeet globally via npm:

`npm i -g zeet`

Requirements:

Node.js v20+

A basic understanding of CLI tools

Core Commands

See usage
```
zeet --help
```
Initialize Repository
```
zeet init
```

Stage Files

zeet add <file1> <file2> ...

To stage all files:

zeet add .

Commit changes
```
zeet commit -m "Your Commit message"
```
View commit history
```
zeet log
```

Branch Management:

Create a branch:
```
zeet branch <branch-name>
```
Switch branches:
```
zeet switch <branch-name>
```

Merge branches
```
zeet merge <branch-name>
```
Merge conflicts will be detected and marked for manual resolution.
View diffs
```
zeet diff <commit-hash>
```
Compares two commits:
```
zeet diff <commit-hash1> <commit-hash2>
```
In place of <commit-hash>, you can alternatively specify branch or path to a file under repository.

Final toughts

Zeet is a hobby project that distills the essence of Git into a minimal yet functional version control system. While it’s not as robust as Git, it showcases the core principles of version control, making it a great tool for learning and experimenting.

Want to contribute? Head over to the Zeet repository on GitHub.

We could make Zeet even better.

Git things right🟢✔️ using rebase workflow in a software team

Smitter — Mon, 21 Aug 2023 11:19:24 +0000

Git has many powers and one of them is flexibility. Different approaches(workflows) can be leveraged to efficiently build software collaboratively, and teams can pick their best fit. Common in a Git team, branching is a godsent technique used to build new features in isolation without impacting stability in main branch. Later when a feature is complete, it's branch is merged into main, and that branch becomes obsolete and perhaps deleted.

It is odd how people treat git rebase like a plague to avoid when working on public branches i.e, branches other team members have pulled down from remote into their devices/local repos. That is okay. They are people. Coming from this article you shouldn't be one of them but a git user who doesn't have to sweat over using git rebase again.
We'll discuss why Git rebase workflow in a Git team, is an exciting thing you are missing while still clutched to the Git merge workflow.

Note: To better relate with the rest of the article, you need to be at least familiar with creating branches in Git and merging them. By the way, it is super easy.

To breakdown matters into chunks you can digest, let's assume of a company called "XYZ", that has a wonderful software product 😎️.

This company uses a Gitflow workflow to build its software. Ideally, its branching strategy comprises of the following:

main - This is the name given to a main branch that holds production ready code. Or call it stable version.
develop - This is also a main branch that contains newly integrated features (that are not yet ready to be released to production). The unstable version.
release- Branch that helps prepare a new stable release. Usually stemmed off the develop branch, for testing, documentation generation, bugfixes and other related preparations. It must be merged back to both develop and main.
hotfix- Branch that fixes bug discovered in production release(main branch). It must be fixed. And after being fixed, it is merged back to both main and develop.
feature - Branch that developers work on when building new features that come up. Collectively reffered to as feature/topic branch.

Note: You could choose your own name conventions. Importantly, the branches should still hold their purpose and usecase.

The main and develop branches are considered main branches, i.e they are long-lived branches, while the rest are supporting branches that aid parallel development, usually short-lived.

For elaborating the Git rebase workflow, we will focus on activity done on develop branch.

Scenario

Let's narrow down the persona to you, a developer working in this "XYZ" company .

Several features have come up, that need to be built and integrated into the company's software product. And you have been assigned one of them. The rest is distributed to other developers.

So for example, you need to build a new feature in the software that allows a user to locate gas stations nearby.

To go about this, you start off with git checkout develop. Then perform a git pull to integrate latest changes that may be in the remote but not in you local develop branch. And you branch off from develop. The new branch is feature branch, where you work on your assigned task.

After you are done, you are ready to merge your changes back into develop branch.

Please note that at this time, other developers who finished working on their assigned features earlier than you, have already integrated their work into develop branch. So, develop branch has evolved and after another git pull from it, commit history in your local repository can be visualized into this:

Merging policy

This company has its own take and philosophies about their project's commit history.

develop branch commit history should be linear, replaying thoughtful commits that happened in feature branch incorporated into it. No squash merging of feature branch. To reason out: In real world features can be complex, so it is important to maintain feature commits to explain how we arrived at point B coming from point A.
main branch should have one commit per each release. Practically, a squash merge. Meaning it will have a diminished project history. A good commit message should tell the features incorporated at the time of that release.
release and hotfix - These branches add improvements to codebase in main branches. After improvements are made, they are squash merged into main and develop. Good commit message is important too.

The problem with Git merge workflow

Now that we know how this company desires commit history of its project to be organized, let's look at one way one could decide to integrate work.

Suppose you use git merge to incorporate work from one branch into another, you do the following steps:

git checkout develop # Check out public branch
git pull origin develop # Pull in latest commits from the remote copy
git merge feature # Incorporate work from feature branch
git push # Share your changes to the remote

That is the Git merge workflow. And it is legendary at being easy to pickup, that it builds a striking adoption by most Git users.

The branch's history tree looks like this:

Tip: Commit history tree can be observed on the left edge when you run git log --graph --oneline.

A merge commit is generated which combines two branch histories. The commit history in develop becomes non-linear. That is to say, the commit history is not straight since it breaks from an evolving main line and later rejoins. Already, a non-linear project history is not what the company wants on this branch.

Aside from this company's preferences, the following are the cons of using a Git merge workflow:

Git merge workflow does not enforce an individual developer to build, test and work out code differences while at the feature branch level before merging to main.
This workflow generates merge commits that can really clutter the commit history. A disaster class history can happen especially if you team with committers that are relatively new to Git or are using GUI that hides the actual results from them.
If you need to review work for whatever reason, it is very difficult to do so with a cluttered history filled with noise jamming the radar.
Merge commits created, can result in duplication of old commits because someone merged in a branch that branched off at a far away older commit. This maybe an old branch or the developer did not branch off at the right spot.
A project's history can aid in debugging, e.g when finding a commit that introduced a bug. Git merge workflow can confuse things with merge commits, e.g when using git bisect.

An ideal linear project history desired on the develop branch looks like this:

All commits from feature branch are placed on top of develop branch and in order they occured. Also, there is no extraneous merge commit.

Git rebase workflow for a linear commit history

git rebase can achieve the desired commit history like shown in the above image.

A gotcha about git rebase is that it does its work by rewriting history, which can cause chaos when performed on a public branch other developers have based their work on; like in our case, the develop branch.

To avoid rewriting history, we need to ensure that when work from a separate branch is incorporated into develop, it is fast-forwaded. That is to mean commits made on the separate branch, are appended on top of existing history of current branch. Thereby avoiding rewrite on existing history.

To make git perform a fast-forward when integrating work from separate branches, we have to prepare commit history between them, especially when they have both evolved.

For instance, when feature branch was first created:

git checkout develop
git checkout -b feature # Create feature branch and switch to it

Commit history in feature started off on a base commit(c2) which is the latest commit on develop branch at that time. More work committed from the branch, evolved the history with new commits(c3...c5) on top of the base commit.

Now at this time, enough work has been done on feature branch and we are ready to integrate these changes back into develop. However, the starting base commit of the feature branch is no longer the latest commit/tip of the develop branch:

In other words, develop branch has evolved with newer commits by other team members since the last time feature was created off from it.

Therefore if we need a fast-forward merge to be possible, we have to update the base of feature branch so it is anchored onto the latest commit(c7) that is the tip of develop branch. Then changes that were committed in feature are freshly committed onto the top of the updated base in the order they occured(c3'...c5'), hence the nomenclature and internal working of git rebase:

Note: c3'...c5' are new commits with same changes like in c3...c5(before rebasing). Rebasing changes their commit IDs.

After we rebase feature branch, we head into develop branch and traffic lights should be "green 🟢" for us to integrate new work in which Git will fast-forward. This is so because the base commit in feature branch is reachable as most recent commit on current branch(develop).

Typically, these are the steps in a git rebase workflow in your local repository:

git checkout develop # Checkout public branch
git pull origin develop # Get and incorporate latest changes
git checkout -b feature # Create feature branch and switch to it
    # Work on the new feature, make commits, test... Until you are done!
git fetch origin # Refresh local repo store of remote copies
git rebase origin/develop # Rebase to update feature branch base with latest develop branch commits
git checkout develop # Head back to public branch
git pull origin develop # Integrate latest commits from remote copy
git rebase feature # Bring in commits of feature branch onto the top
git push # Share the changes to remote copy

To reiterate, the 2^nd last command: git rebase feature, does not rewrite history. Git checks and sees that history of the checked out branch(develop), forms the base/ancestor of feature branch. So to include work done in the separate branch, it just appends commits done in feature branch onto the top of develop's history. In git parlance, this is a fast-forward, where Git simplifies work and just moves the develop branch to point to the same commit the feature branch is pointing.

So develop branch and feature branch are pointing to the same commit.

The result is a linear history same for both branches. The project history is as illustrated:

Alternatively, at the 2^nd last command, instead of git rebase feature, you could use git merge feature and still the result is a fast-forward; merge commit is not generated in a fast-forward. Also, you could use git merge feature --ff-only to merge two lines of work only if fast-forward is possible. This can help mitigate risk of rewriting history on public branch; when a step on the workflow is missed or out of order. But anyway, Git will warn if you try to push a rewritten history.

Should you use a Git rebase workflow?

The choice between git merge and git rebase workflows can seem so pointless 🤷‍♂️. Because, in a nutshell, they both introduce changes from one branch into another. At least, this is the case for a Git user solely concerned about the final work.

Beyond the surface, the choice between the two comes down to maintainance of a project's commit history. Decision on a project's history can be based on two philosophies:

Commit history is a record of what actually transpired and should be preserved.
Commit history is a publication and it should be presented in high quality.

If a project gravitates to keeping a record of what actually transpired in its doing(regardless of organization), Git merge workflow is better suited. On the other hand, if a project should maintain a chronological and accessible history to tell a coherent story of how a project evolved, Git rebase workflow should be the choice.
There are far more advantages to keeping a high quality history that is clean and linear, for example:

It helps understand the story of how a solution was implemented.
There is clear snapshots of development stages of a project that can be referenced or used as starting points in future.
Cherry-picks, rollbacks and other versioning intentions become easier when history is orderly.
It outlines the evolution of the project in an easy to follow manner.
It allows to make simple compares when regressions are detected.

Overally why a Git rebase workflow is better than Git merge workflow is: Git rebase workflow is an outright ambassador for a linear commit history. The way it does this is by avoiding a merge commit while replaying the commits of a feature branch onto the tip of main. Also, Git rebase workflow allows you to resolve conflicts from feature branch before merging to main.

Git rebase workflow can be ideal in open-source contributions where you rebase a feature branch and create a pull request.

Final words

Thanks for reading. I hope I cleared your doubts. And now you can make informed decision about history of your project.

Follow me here on Dev so you can be first to know of new nuggets that drop.

SmitterFollow

💻Software Engineer ・ 🐧Fervent linux user ・🦀Learning Rust https://npmjs.com/package/react-loading-indicators

I have an X(formerly twitter) account. We can connect 🤝.

You also need to hear this🙂: I maintain an open source library. See it in Github. I appreciate your star⭐ should you like the work(DEMO). I use a rebase workflow with it. Finally, explore my creativity practiced on my personal website.

13 CSS Tricks that will give you an adrenaline rush🤯

Smitter — Mon, 17 Jul 2023 09:13:07 +0000

CSS is gaining powers with recent web evolution. And it is very clever with tricks that were long existing or that have emerged. Perhaps tricks shared here will school you with CSS tricks from the depths you were yet to explore.

Let's dive in.

Draw a triangle using border

It can be an overkill to load images in cases where you need simple triangles e.g when adding an arrow pointer to a tooltip.

Using only CSS, you can create a triangle using borders.

It is quite an old trick. Ideally, on an element with zero width and height, you set borders on it. All border colors are transparent except the one that will form an arrow. To create an arrow pointing upwards, for example, the bottom border is colored while the left and right are transparent. No need to include the top border. The border width determines size of the arrow:
```
.upwards-arrow {
    width: 0;
    height: 0;
    border-left: 20px solid transparent;
    border-right: 20px solid transparent;

    border-bottom: 20px solid crimson;
}
```
This creates an arrow pointing upwards like shown below:

You can see this codepen that visualizes the concept should it be tricky to create a mental picture.
Interchange background of an element

z-index property arranges how an element is stacked onto other positioned elements. At times you may set a z-index property on a child element to be lower and it ends up hiding behind the background of its parent. To prevent this, you can cause a new stacking context on the parent element to prevent child elements from going behind it. One way way to create a stacking context is to use isolation: isolate css style declaration.

We can use this stacking context technique to create hover effect that interchanges a button's background. For example:
```
button.join-now {
    cursor: pointer;
    border: none;
    outline: none;
    padding: 10px 15px;

    position: relative;
    background-color: #5dbea3;
    isolation: isolate; /* If ommitted, child pseudo element will be stacked behind */
}

button.join-now::before {
    content: "";
    position: absolute;
    background-color: #33b249;
    top: 0;
    left: 100%;
    right: 0;
    bottom: 0;
    transition: left 500ms ease-out;

    z-index: -1;
}

button.join-now:hover::before {
    left: 0;
}
```
The code above interchanges the background of the button when hovered. The background changes without interfering with the text on the foreground, as seen in the gif below:
Center an element

Probably, you already know how to center an element using display: flex; and display: grid;. Yet another unpopular way to center an element on the x axis is to use text-align CSS property. This property works out of the box when centering text. To also center other elements in the DOM, a child element needs to have a display of inline. It could be inline-block or any other inline...
```
div.parent {
    text-align: center;
}

div.child {
    display: inline-block;
}
```
Pill 💊 shape button

You can make buttons that are pill-shaped by setting the border-radius of a button to be a very high value. Certainly, the border-radius should be higher than the height of the button.
```
button.btn {
    border-radius: 80px; /* value higher than height of the button */
    padding: 20px 30px;
    background-color: #fdd835;
    border: none;
    color: black;
    font-size: 20px;
}
```
result:

Height of the button may increase with design changes. Hence you will often find it convenient to set border-radius with a very high value so that your css keeps working regardless if the button grows.
Easily add beautiful loading indicator to your website

As it is with developers, it is often a boring task to divert your focus to creating a beautiful loading indicator for your website. This focus is better utilized building other important parts of a project that deserve attention.

As you are reading, odds are high you also find this an annoying hurdle. That is why i took the time to take away this hurdle away from you and prepare nicely done loading indicators packaged in a library so you can "plug 'n play" from your dream project. It is a whole collection and you just need to pick the one that pulls the spark 💖 on you. Just see the simple usage of this library, with the source available on Github. Don't forget to leave a star ⭐.
Easy dark or light mode

You only require a few lines of CSS to enable a dark/light mode on your website. You just need to let browsers know that your website can display correctly in system dark/light mode:
```
html {
    color-scheme: light dark;
}
```
Note: color-scheme property can be set on any DOM element other than html.

Then set variables that control background color and text color through your website, making it even more bullet proof by checking for browser support:
```
html {
    --bg-color: #ffffff;
    --txt-color: #000000;
}

@supports (background-color: Canvas) and (color: CanvasText) {
    :root {
        --bg-color: Canvas;
        --txt-color: CanvasText;
    }
}
```
Note: If you don't set background-color on an element, it will inherit the browser-defined system color for the dark/light theme matched. These system colors can be different between different browsers.

Setting background-color explicitly can be useful in combination with prefers-color-scheme to give a different shade of color different from the default that the browser sets.

Below is the dark/light mode in action. User's preference is simulated between dark and light mode.

Website reactive to system dark/light mode
Truncate overflowing text with an ellipsis(...)

This trick has been around for a while to aesthetically trim long text. But you may still have missed it.

All you need is the following CSS:
```
p.intro {
    width: 300px;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}
```
Just implement these rules:
- Explicit width, so bounds for clipping will ever be reached.
- Browser wraps below long text that do not fit within an element's width. So you need to prevent that: white-space: nowrap;.
- Content that overflows should be clipped: overflow: hidden;.
- Pad a string with an ellipsis(...) when text is about to be clipped: text-overflow: ellipsis;.
Result looks like this:

Truncate long text to a number of lines

This is slightly different from the trick above. This time, text is clipped limiting content to a number of lines.

p.intro {
    width: 300px;
    display: -webkit-box;
    -webkit-box-orient: vertical;
    -webkit-line-clamp: 3; /* Truncate when no. of lines exceed 3 */
    overflow: hidden;
}

Output looks like this:

Stop overworking yourself writing top, right, bottom, left

When working with positioned elements, you often write code like this:
```
.some-element {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
}
```
This can be simplified using an inset propety:
```
.some-element {
    position: absolute;
    inset: 0;
}
```
Or if you have different values for top, right, bottom and left, you can set them respectively in the order like: inset: -10px 0px -10px 0px. This shorthand works the same way as margin.
Serve optimized images

Try throttling to a slow internet in the browser Dev tools and visit a website made up of HD images like unsplash. That's how to experience the pain of your website visitors trying to enjoy your high HD content from geographical areas with slow internet.

But you can provide a rescue especially with the image-set CSS trick.

You can give options to a browser to let it decide the most appropriate image that suits a user's device. For instance:
```
.banner {
    background-image: url("elephant.png"),
    background-image: -webkit-image-set(
        url("elephant.webp") type("image/webp") 1x,
        url("elephantHD.webp") type("image/webp") 2x,
        url("elephant.png") type("image/png") 1x,
        url("elephantHD.png") type("image/png") 2x
    );
}
```
The code above will set the background image of an element.

If -webkit-image-set is supported, then background image will be an optimized image, i.e an image of supported MIME type and that better suits the resolution power of the user's device.

For example: Since a higher quality image is directly proportional to a larger size, a user who has a high resolution device but in a poor network, will prompt the browser to decide on serving a supported image with lower resolution. Ii is logical not to make a user wait for the HD image to load.

Note: An image that the browser decides as the best fit, is what is downloaded

Counters

You don't have to get stuck on how the browser renders a numbered list. You can implement your own design utilizing counters(). Here's how:

ul {
    margin: 0;
    font-family: sans-serif;

    /* Define & Initialize Counter */
    counter-reset: list 0;
}

ul li {
    list-style: none;
}

ul li:before {
    padding: 5px;
    margin: 0 8px 5px 0px;
    display: inline-block;
    background: skyblue;
    border-radius: 50%;
    font-weight: 100;
    font-size: 0.75rem;

    /* Increment counter by 1 */
    counter-increment: list 1;
    /* Show incremented count padded with `.` */
    content: counter(list) ".";
}

Output looks like this:

This works for any other DOM element apart from <ul> and <ol>.

Form validation visual cues

With only CSS, you can display helping visual cues to users regarding the validity of input entered in the forms. We can use :valid and :invalid CSS pseudo classes on form elements to apply appropriate styles when their contents validate successfully or not.

Consider the following HTML page structure:

<!-- Regex in pattern attribute means input can accept `firstName Lastname` (whitespace sepearated names) -->
<!-- And invalidates any other symbols like `*` -->
<input
    type="text"
    pattern="([a-zA-Z0-9]\s?)+"
    placeholder="Enter full name"
    required
/>
<span></span>

<span> will be used to show validation results.

And the CSS below styles an input regarding its validation result:

input + span {
    position: relative;
}

input + span::before {
    position: absolute;
    right: -20px;
    bottom: 0;
}

input:not(:placeholder-shown):invalid {
    border: 2px solid red;
}

input:not(:placeholder-shown):invalid + span::before {
    content: "✖";
    color: red;
}

input:not(:placeholder-shown):valid + span::before {
    content: "✓";
    color: green;
}

So we have achieved interactivity without consulting any javascript. A full codepen implementing this technique is shown below:

Select text with one click

This trick is inclined towards improving copy and paste experience for website users. Using user-select: all, you can enable easy text selection with one click. All text node below that element is selected.

On the other hand, you can disable text selection with user-select: none;. Alternative way to disable text selection is placing text inside content: ''; property of ::before or ::after CSS pseudo element.

Thanks for reading. See you in the next article. Follow me here on Dev to be notified.

SmitterFollow

💻Software Engineer ・ 🐧Fervent linux user ・🦀Learning Rust https://npmjs.com/package/react-loading-indicators

Also connect with me on twitter.

Uncanny visual symbols of a git conflict explained

Smitter — Tue, 20 Jun 2023 13:24:37 +0000

Git is such a popular Version Control System. It needs no introduction.

Software development is a collaborative task where git helps track and versions the changes made. When working in a team setting, conflicts are frequent visitors. I am not refferring to people coming to blows, but Git encountering lines in files that have received edits from two branches during a merge operation.

Therefore a git conflict arises when two separate branches have made edits to the same line in a file, or when a file has been deleted in one branch but edited in the other.

When you inspect an affected file in a merge conflict, there are strange symbols that appear in the lines where the conflict has occured. Ideally when git encounters a conflict during a merge, it will edit the content of the affected files with visual indicators that mark edits received from both sides of the involved branches.

These symbols are <<<<<<<, ======= and >>>>>>>, like in the example illustration below of a merge conflict:

What these symbols mean

Its simple.

======= is a symbol that separates edits recived from both branches. The content above and enclosed between <<<<<<<, and ======= is the receiving branch. More specifically the branch that is currently checked out and receiving work from another branch.

And the content below =======, enclosed between ======= and >>>>>>>, is the merging branch.

It is helpful to search a project for these symbols during a merge to find where conflicts need to be resolved.

To fix a conflict, you as a developer has to decide which either side of the ======= symbol you want to stick with. Once decided, you can replace the symbols with the content you have chosen. Once you are certain you have fixed all the conflicts pointed out by Git, you can mark resolved by runnig git add on the file(s) and finally git commit to complete the merge operation.

If somehow later this merge turns to be a mistake, you might want to equip yourself with git techniques to undo. I wrote an article that teaches exactly that: how to undo mistakes in Git.

Thanks for reading.

How to calculate CSS specificity of your style rules

Smitter — Tue, 06 Jun 2023 13:16:15 +0000

In this article, you will learn how to calculate CSS specificity of the styles you write by computing a compound number to measure specificity weight by CSS selector.

First off,

Specificity is the algorithm browsers use to establish the CSS declarations that will get applied to an element, when it is referenced by two or more style rules.

Specificity algorithm calculates weight of CSS selector, and among competing selectors targetting one element, the selector with the greatest weight will win to apply CSS declarations to that element.

Visual definition of CSS terms

The 3-column value

The specificity algorithm bases weight calculation around a three-column compound number. Each column represents weight that correspond to the three types of CSS selectors, i.e ID, CLASS and TYPE. This three-column compound number starts off with zeroes looking like:

ID column - Includes only ID selectors, such as #app. For each ID in a matching selector, add [1, 0, 0] to the weight value.
CLASS column - Includes class selectors, such as .myInput, attribute selectors e.g [type="password"], and pseudo-classes such as :hover, :first-of-type, e.t.c. For each class, attribute selector, or pseudo-class in a matching selector, add [0, 1, 0] to the weight value.
TYPE column - Includes type selectors, such as p, h2, and a, and pseudo-elements like ::before, ::placeholder, and all other selectors with double-colon(::) notation. For each type or pseudo-element in a matching selector, add [0, 0, 1] to the weight value.

Specificity comparison

Let's look at the following rule, which is composed of 7 selectors to target a span element:

#app #navigation #list .sub-list .item p span {
    /* declarations here */
}

There are 3 ID selectors(#app, #navigation, #list). So the three-column value becomes [3, 0, 0].

Then 2 class selectors(.sub-list, .item). The three-column value compounds to [3, 2, 0].

Then 2 type selectors(p, span). The three-column value compounds to [3, 2, 2].

Now provided the number in each column is 9 or less, we can concatenate the numbers in each column to get a base10 number as the resultant specificity weight. So in this case we have a calculated specificity weight as 322.

Disclaimer: This is not how specificity is calculated by CSS processor inside browsers, but only a blue print. Normally in browsers, the specificity is not calculated in base 10 number system, but in a larger number, often unspecified.

Suppose we have another rule styling the same span element looking like this:

#navigation #list .sub-list .item .wrapper p span {
    /* declarations here */
}

Likewise in the style rule above, 7 selectors are used to target the span element. Difference being that we have 2 ID selectors and 3 class selectors, which results in the three-column value [2, 3, 2]. Hence a specificity weight 232. Because 322 is greater than 232, the former has precedence over the latter. Therefore, the former style rule will be processed to style the span element.

Selectors that add no weight to specificity calculation

The universal selector * and the pseudo-class :where() with its parameters do not add onto specificity weight so their weight is [0, 0, 0]; but they do match elements.

Combinators, such as +,>, ~, " ", and ||, may make a selector more specific in what is selected but they don't add any weight to specificity.

:not(), :has() and :is() pseudo classes add no weight by themselves. However their parameters do impact weight in specificity calculation. Therefore, the weight calculated from the selectors, is inclusive of the weight from the parameters of these pseudo-classes.

Incase of a parameter list, weight by the parameters with the highest specificity is used. For example:

/* 
<span id="intro" class="lead">...</span> 
*/

span:is(.lead, #intro) {
    /* calculated specificity - [1, 0, 1] */
}

In the above snippet, inside the :is() parameter list, #intro has higher weight ([1, 0, 0]) than .lead ([0, 1, 0]) . Hence weight by #intro is used to sum up with weight by the span selector resulting to [1, 0, 1].

Example

Consider the following HTML:

<html>
    <head>
        ...
    </head>
    <body>
        <main id="myElement">
            <input type="password" required class="myInput" />
        </main>
    </body>
</html>

In the below CSS, three rules are targeting <input /> element to set a color. For a given input, color value is applied should its selectors specificity weight have precedence over the other matching selectors.

/* FIRST RULE */
#myElement input.myInput {
    color: red;
} /* [1, 1, 1] */

/* SECOND RULE */
input[type="password"]:required {
    color: blue;
} /* [0, 2, 1] */

/* THIRD RULE */
html body main input {
    color: green;
} /* [0, 0, 4] */

All the above rules have selectors matching the same and only <input /> element on our HTML. The input will have a color red because the first rule has the highest specificity weight, i.e 111 is the greatest number from the weights of 111, 021 and 004.

The last rule has 4 type selctors(html, body, main, input). Increasing even more type selctors will still result in <input /> being color red since specificity weight by type selector is always lower than ID selector.

Excercise

Consider the same html to deduce the result of the below CSS:

.myInput {
    border: 0;
}

:is(input.myInput) {
    border: 1px solid black;
}

:where(#myElement input[type="password"]) {
    border: 4px solid blue;
}

What will happen to border on the <input /> element?

Share your answer in the comments👍️.

A Column number that is greater than `9`

I had mentioned earlier that to get the specificity weight you concatenate the column values to get a number like 322. This is because for less than 10 selectors of a type(either ID, Class or Type), we can calculate the specificity in the base 10. Hence concatenating, we can get a number in the base10 number system.

This is not the case when we have 10 and above selectors of a type. High number of selectors can occur when using nesting feature of css preprocessors like sass to generate css. You can end up with three-column value like [11, 7, 19]. You can't concatenate the numbers to obtain a decimal specificity weight in this case.

But instead you can convert the column numbers to a higher base.

For example, lets say we have a three-column value of [11, 7, 19]. To calculate the weight, we can pick a base number that is larger than the largest column number in the three-column value.

Let's pick a base number 20 which is bigger than 19(largest number in [11, 7, 19]). Then multiply out the three columns starting rightmost working to the left. And add the results, like shown:

(20) * 19       =     380
(20*20) * 7     =   2 800
(20*20*20) * 11 =  88 000
-------------------------
Total in decimal = 91 180

Doing this will also require you to use that base number to calculate specificity weight for the other competing selectors. Thankfully, CSS processor handles all this for you. so you just have to understand "why a certain style has been applied and not the other".

Equivalent weights

Where 2 or more style rules have exactly the same specificity weight, the most recent rule will take precedence. However you can force a rule to a higher precedence over other equivalent rules using !important keyword like:

p {
    color: #00ff00 !important;
}

When you do this, all previous style rules with equivalent weight are overridden(including ones using !important) and any equivalent rules that are processed will be ignored.

For example:

p {
    color: #00ff00 !important;
} /* [0, 0, 1] */
p {
    color: #ff0000;
} /* [0, 0, 1] */

Both rules have the same weight but the first rule will take precedence because of use of !important keyword. Otherwise, the second rule would have taken precendence.

Conclusion

CSS has a simple syntax with alot happening behind scenes with the CSS processor. We have talked about specificity in this article, but specificity only comes to play after browser has determined cascade origin and importance. You can explore more which is beyond scope of this article.

In a nutshell, knowing specificity of your styles helps you construct rules and understand what precedence they will have.

We have not talked about inline styles, which are the most specific, meaning that when an inline style is applied, it has the highest specificty overriding any style in the style sheet. The only way to override an inline style from a style sheet is to use !important keyword.

Meet me aside on

I periodically share useful content you may not want to miss.

Build a Robust JWT Auth System in Node.js: Access and Refresh Token Strategy

Smitter — Tue, 30 May 2023 12:39:05 +0000

part 5

Summary: This article walks you through how to implement JSON Web Token(JWT) Authentication to create solid user login feature for web appllications. Tricky concepts on access token and refresh token are demystified on how they add up to securing endpoints.

Note 🔔:

You can jump ahead to the final work, the complete API and front-end can be found on Github✩.

The Common Misconception

The most common advice is do not waste time implementing login. Now as years go by and you climb the career ladder, it is important to understand how the whole system works to elevate yourself as an architect and make more educated design decisions. Authentication is one of the areas you need to understand how it consolidates into a system. More reasons why you should know authentication is listed in this blog.

When thinking about authentication, the common mental picture people have is a login HTML page submitting data to a backend API that cross checks submitted data with what is in the DB. While that is true for the bare bones of an authentication system, there is finer details that need to be done right which we would discuss in the rest of the blog.

Table of Contents

Getting started
- Dependencies used
- What we will do
- Directory structure
What we will do
- Declare environment variables
- Create User database model
- Add email service
- Create validators
- Create authentication middleware
- Create controller functions
- Create application routes
- Register routes
Conclusion

Getting Started

This is a coding tutorial. And to save length of the article better spent on the "fun stuff", there is a starting repo from Github to base your work on. Change into server directory which is what we need in this blog.

Note: This article assumes you already have NodeJS installed in your computer.

Project Dependencies

The following third-party dependencies are used:

Express - A web framework hosted on NodeJS runtime, to handling requests coming to our server.
Express Validator - To run server-side validation.
Bcryptjs - To crumble plain text into irreversible hashes.
Cookie Parser - To parse cookies in incoming HTTP request.
Cors - To configure our backend to understand CORS protocol.
Dotenv - To load variables declared in .env file into the project's environment.
Jsonwebtoken - To facilitate token-based authentication, i.e access and refresh token.
Mongoose - An object modelling tool for MongoDB to enforce a specific mongoDB schema.
Nodemailer - To send emails from NodeJs application.
Nodemon - To restart server app whenever file changes occur.

These dependencies are already listed in package.json of the starter repo. To include them in your project, ensure you are in server directory root and run npm install from the terminal.

Starter repository has some steps covered:

Database integration (in part 2)
Cross Origin Resource Sharing (in part 3)
Express.js error handling (in part 4)

What we will do

An overview outline:

Declare environment variables in .env file that will be loaded into application environment.
Create User database model to represent a user in our application.
Add email service to send emails from our application.
Create validators to validate data coming from client.
Create authentication middleware to check for authentication on protected routes.
Create controller functions to handle HTTP request and process a response for a matched route.
Create routes. So a specific functionality is provided at each route.
Register routes, So internal routing mechanism can match HTTP request to a route.

Directory structure

Final directory structure we will have:

📂server/
    ├── 📄.env
    └── 📂src/
        ├── 📄index.js
+       ├── 📂models/ 📄User.js
+       ├── 📂services/
+       │   └── 📂email/
+       │       ├── 📄email.js
+       │       └── 📄sendEmail.js
+       ├── 📂validators/
+       │   ├── 📄index.js
+       │   ├── 📄auth-validators.js
+       │   └── 📄user-validators.js
+       ├── 📂middlewares/ 📄authCheck.js
+       ├── 📂controllers/
+       │   └── 📂user/
+       │       ├── 📄index.js
+       │       ├── 📄auth.controller.js
+       │       └── 📄user.controller.js
+       ├── 📂routes/
+       │   ├── 📄index.js
+       │   └── 📄user.routes.js
        ├── 📂config/
        │   └── ...
        └── 📂dbConn/
             └── ...

Let's dive in

Declare environment variables

Environment variables are key-value pairs that the operating system provides to applications at runtime. They store configuration data, such as database credentials or API keys, allowing applications to adapt to different environments (e.g., development, testing, production) without altering the code. These variables are kept in the system's memory (RAM) and away from application code so running applications can access them securely and efficiently.

We'll make use of environment variables to store configuration variables that are sensitive or personal or both.

Let's declare environment variables.

Create .env file at server directory root, i.e server/(refer above). Declare the variables as follows:
```
AUTH_REFRESH_TOKEN_SECRET=2Kp6BjSKl3boT6+Zf3D0tw
AUTH_REFRESH_TOKEN_EXPIRY=1d
AUTH_ACCESS_TOKEN_SECRET=bkZaWfqssqzE0fg1TMCHqQ
AUTH_ACCESS_TOKEN_EXPIRY=120s
RESET_PASSWORD_TOKEN_EXPIRY_MINS=15
```
For the "xxx_TOKEN_SECRET"s, you can input any value. Random characters is ideal. NodeJs can help generate random characters on the fly; In your terminal run: node -e "console.log(crypto.randomBytes(32).toString('base64'))".

Realize how we set expiration time of our authentication tokens i.e Refresh Token expiration time(AUTH_REFRESH_TOKEN_EXPIRY) is longer than Access Token's (AUTH_ACCESS_TOKEN_EXPIRY). Also, the Access Token expiration time is reasonably short.

AUTH_REFRESH_TOKEN_SECRET - Holds value of the secret to sign JWT Refresh Token.

AUTH_REFRESH_TOKEN_EXPIRY - Holds value of the expiration time of the JWT Refresh Token.

AUTH_ACCESS_TOKEN_SECRET - Holds value of the secret to sign JWT Access Token.

AUTH_ACCESS_TOKEN_EXPIRY - Holds value of the expiration time of the JWT Access Token.

RESET_PASSWORD_TOKEN_EXPIRY_MINS - Expiry time of the password reset link.

Note: .env file declares environment variables in plain text(it does not load them into OS environment). We will use dotenv library to read variables in .env file and actually load them into our application's environment(OS). Also be sure to add .env file to your .gitignore to avoid sharing your .env variables.

Create `User` database model

A database model, is an interface for interacting with the database to query for operations like reading, creating, updating and deleting records.

User model will represent a user of our application. This is the only model we will need for this tutorial. We'll use Mongoose to create this model.

Create a file User.js at the path: server/src/models/(refer). Paste the following code in this file:

const mongoose = require("mongoose");
const bcrypt = require("bcryptjs");
const jwt = require("jsonwebtoken");
const crypto = require("crypto");

// 👇 Created in part 4
const CustomError = require("../config/errors/CustomError");

// Pull in Environment variables
const ACCESS_TOKEN = {
    secret: process.env.AUTH_ACCESS_TOKEN_SECRET,
    expiry: process.env.AUTH_ACCESS_TOKEN_EXPIRY,
};
const REFRESH_TOKEN = {
    secret: process.env.AUTH_REFRESH_TOKEN_SECRET,
    expiry: process.env.AUTH_REFRESH_TOKEN_EXPIRY,
};
const RESET_PASSWORD_TOKEN = {
    expiry: process.env.RESET_PASSWORD_TOKEN_EXPIRY_MINS,
};

/*
1. CREATE USER SCHEMA
*/

/*
2. SET SCHEMA OPTION
*/

/*
3. ATTACH MIDDLEWARE
*/

/*
4. ATTACH CUSTOM STATIC METHODS
*/

/*
5. ATTACH CUSTOM INSTANCE METHODS
*/

/*
6. COMPILE MODEL FROM SCHEMA
*/

module.exports = UserModel;

The snippet above imports dependencies we will use. We have pulled in environment variables, available in process.env and assigned them to constants for ease of access. We have 6 parts(commented) in the code snippet above.

Under the 1^st part(1. CREATE USER SCHEMA), add the following code:

const User = mongoose.Schema;
const UserSchema = new User({
    firstName: { type: String, required: [true, "First name is required"] },
    lastName: { type: String, required: [true, "Last name is required"] },
    email: {
        type: String,
        required: [true, "Email is required"],
        unique: true,
    },
    password: {
        type: String,
        required: true,
    },
    tokens: [
        {
            token: { required: true, type: String },
        },
    ],
    resetpasswordtoken: String,
    resetpasswordtokenexpiry: Date,
});

We have defined the schema for a user in our application. In other words, the attributes a user entity will have. Hence users stored in the database will be expected to each have these attributes. Some are optional while others are required.

Note that we have defined tokens in the database schema where we will store refresh tokens generated for a user.

In the 2^nd part(2. SET SCHEMA OPTION), add the following code:

UserSchema.set("toJSON", {
    virtuals: true,
    transform: function (doc, ret, options) {
        const { firstName, lastName, email } = ret;

        return { firstName, lastName, email }; // return fields we need
    },
});

This ensures that every time a document is retrieved from the User model, only the relevant data intended for the API response is returned.

In the 3^rd part(3. ATTACH MIDDLEWARE), add the following code:

UserSchema.pre("save", async function (next) {
    try {
        if (this.isModified("password")) {
            const salt = await bcrypt.genSalt(10);
            this.password = await bcrypt.hash(this.password, salt);
        }
        next();
    } catch (error) {
        next(error);
    }
});

This is a mongoose middleware that runs before a document is saved to the database. And it ensures that password attribute of a user is hashed if it was modified. Therefore, when a user is newly created, password of the user is hashed. The next time it is hashed once again is only when a user's password attribute is changed. Probably when a user has updated their password.

In the following parts, we have custom methods we are setting on the UserSchema. They will be available on the User model and are helpful in avoiding redundant code from the controllers.

Under the 4^th part(4. ATTACH CUSTOM STATIC METHODS), add the following code:

UserSchema.statics.findByCredentials = async (email, password) => {
    const user = await UserModel.findOne({ email });
    if (!user)
        throw new CustomError(
            "Wrong credentials!",
            400,
            "Email or password is wrong!"
        );
    const passwdMatch = await bcrypt.compare(password, user.password);
    if (!passwdMatch)
        throw new CustomError(
            "Wrong credentials!!",
            400,
            "Email or password is wrong!"
        );
    return user;
};

We have created a static method that is invokable directly on User model rather than its instance, enabled by the statics property on the UserSchema. This method simply finds a user by email and password. It throws an exception if the find is not successful.

Note how we generate user-defined exception using custom error constructor(throw new CustomError(...)). That is explained in Express.js error handling. Otherwise you can use the in-built new Error().

In the 5^th part(5. ATTACH CUSTOM INSTANCE METHODS), we will add three instance methods that will be invokable on the User model instance:

Add the first instance method:

UserSchema.methods.generateAcessToken = function () {
    const user = this;

    // Create signed access token
    const accessToken = jwt.sign(
        {
            _id: user._id.toString(),
            fullName: `${user.firstName} ${user.lastName}`,
            email: user.email,
        },
        ACCESS_TOKEN.secret,
        {
            expiresIn: ACCESS_TOKEN.expiry,
        }
    );

    return accessToken;
};

This instance method generates an access token. The access token is a signed jwt embedded with user instance data.

Note: We use traditional functions because they have this binding. Using arrow functions will not produce expected results.

Add the second instance method:

UserSchema.methods.generateRefreshToken = async function () {
    const user = this;

    // Create signed refresh token
    const refreshToken = jwt.sign(
        {
            _id: user._id.toString(),
        },
        REFRESH_TOKEN.secret,
        {
            expiresIn: REFRESH_TOKEN.expiry,
        }
    );

    // Create a 'refresh token hash' from 'refresh token'
    const rTknHash = crypto
        .createHmac("sha256", REFRESH_TOKEN.secret)
        .update(refreshToken)
        .digest("hex");

    // Save 'refresh token hash' to database
    user.tokens.push({ token: rTknHash });
    await user.save();

    return refreshToken;
};

Similar to first instance method, this method generates a refresh token which is a signed jwt embedded with user instance data. We store the refresh token in the DB. It will be useful in implementing a log out from all devices feature as seen later in the blog.

Note: We store a hashed version of the refresh token in the database which is a security practice to prevent changing users' password should the database be compromised.

Add the third instance method:

UserSchema.methods.generateResetToken = async function () {
    const resetTokenValue = crypto.randomBytes(20).toString("base64url");
    const resetTokenSecret = crypto.randomBytes(10).toString("hex");
    const user = this;

    // Separator of `+` because generated base64url characters doesn't include this character
    const resetToken = `${resetTokenValue}+${resetTokenSecret}`;

    // Create a hash
    const resetTokenHash = crypto
        .createHmac("sha256", resetTokenSecret)
        .update(resetTokenValue)
        .digest("hex");

    user.resetpasswordtoken = resetTokenHash;
    user.resetpasswordtokenexpiry =
        Date.now() + (RESET_PASSWORD_TOKEN.expiry || 5) * 60 * 1000; // Sets expiration age

    await user.save();

    return resetToken;
};

This instance method creates a reset token and a reset token hash. We use NodeJs native crypto module to create resetTokenValue and resetTokenSecret. A resetToken is obtained by concatenating these parts. We also create a resetTokenHash from these parts. We return plaintext resetToken while resetTokenHash is saved to the database. In the database, we also set an expiry to the reset token so that it is expired after a duration or after use.

The first part(resetTokenValue) is created with base64url encoding. The second part(resetTokenSecret) is created with hex encoding. These encodings allow to concatenate the two parts, to form a resultant resetToken. A plus(+) separator is specially used; since both of these encodings will never generate the + character.

hex encoding may be straight forward, i.e represented by only 16 symbols(0-9 and A-F). Learn more about base64url encoding here.

In the 6^th part(6. COMPILE MODEL FROM SCHEMA): we compile a model from the schema integrated with additional definitions outlined in previous parts:

const UserModel = mongoose.model("User", UserSchema);

Add email service

Our application needs to send emails, an example usecase is sending password reset link to a user.
We will use nodemailer as a Mail User Agent(MUA) to send emails from our NodeJs application; by connecting to an SMTP server.

We will use Mailtrap as our SMTP server, responsible to deliver emails.

Mailtrap can be used for email delivery. Apart from that, it offers a feature great for testing, that is, it can be used as fake SMTP server. This means we can use Mailtrap's SMTP server to receive emails from our NodeJs application and emulate sending without actual delivery. This service is ideal to test and view emails we send without spamming real recipients or flooding your own inboxes.

When you're ready to send emails to real inboxes, you can upgrade your Mailtrap account to enable actual email delivery. Alternatively, you can configure Nodemailer to work with a different provider such as Sendgrid or Brevo.

You will need to get credentials from mailtrap to use their SMTP service. Follow this guide to get necessary credentials for SMTP integration.

Once you've completed the guide, you should have the following credentials ready:
1. Host
2. Port
3. Username
4. Password
We'll directly add the Host and Port to the Nodemailer configuration options. To protect sensitive information, we'll store the Username and Password in environment variables.

Open .env file located at server/ directory root(refer above). Append new variables:
```
AUTH_EMAIL_USERNAME=<Username>
AUTH_EMAIL_PASSWORD=<Password>
EMAIL_FROM=<Email sender>
```
EMAIL_FROM is the sender in an email delivery. You can fill with your own email.

Create the file: email.js. According to the directory structure for this tutorial(refer above), it should be at the path: server/src/services/email/.

Paste in the following code:
```
const nodemailer = require("nodemailer");

// Pull in Environments variables
const EMAIL = {
    authUser: process.env.AUTH_EMAIL_USERNAME,
    authPass: process.env.AUTH_EMAIL_PASSWORD,
};

async function main(mailOptions) {
    // Create reusable transporter object using the default SMTP transport
    const transporter = nodemailer.createTransport({
        host: "smtp.mailtrap.io",
        port: 2525,
        auth: {
            user: EMAIL.authUser,
            pass: EMAIL.authPass,
        },
    });

    // Send mail with defined transport object
    const info = await transporter.sendMail({
        from: mailOptions?.from,
        to: mailOptions?.to,
        subject: mailOptions?.subject,
        text: mailOptions?.text,
        html: mailOptions?.html,
    });

    return info;
}

module.exports = main;
```
In above snippet we have exported a main() function that connects our application to Mailtrap SMTP server facilitated with nodemailer's createTransport(...). Emails from our application are forwarded to SMTP server for actual sending using nodemailer's transporter.sendMail(...). An info object is returned containing the delivery information.

Open/create a second file sendEmail.js. It should be located at server/src/services/email/, beside email.js(refer above).

Paste in the following code:
```
const main = require("./email.js");

const fixedMailOptions = {
    from: process.env.EMAIL_FROM,
};

function sendEmail(options = {}) {
    const mailOptions = Object.assign({}, options, fixedMailOptions);
    return main(mailOptions);
}

module.exports.sendEmail = sendEmail;
```
Short and sweet ✔. We are calling imported main() function and passing to it mailOptions to run email sending. We then export the sendEmail() that will be used in our application.

Create validators

Form data submitted from client to server cannot be trusted. We need to enforce validation rules for these data before we can start processing them in our server.

For server-side validation, we'll use express-validator which according to the docs:

express-validator is a set of express.js middlewares that wraps validator.js validator and sanitizer functions.

Being wrapped in express.js middlewares, means it would be easy to work with in an express.js application.

Let's create our first set of validators.

Create a file auth-validators.js located at server/src/validators/(refer above). Add the following code in it:

const { body, param } = require("express-validator");

const User = require("../models/User");

module.exports.loginValidator = [
    body("email")
        .trim()
        .notEmpty()
        .withMessage("Email CANNOT be empty")
        .bail()
        .isEmail()
        .withMessage("Email is invalid"),
    body("password").notEmpty().withMessage("Password CANNOT be empty"),
];

module.exports.signupValidator = [
    body("firstName")
        .trim()
        .notEmpty()
        .withMessage("Firstname CANNOT be empty"),
    body("lastName")
        .trim()
        .notEmpty()
        .withMessage("Lastname CANNOT be empty"),
    body("email")
        .trim()
        .notEmpty()
        .withMessage("Email CANNOT be empty")
        .bail()
        .isEmail()
        .withMessage("Email is invalid")
        .bail()
        .custom(async (email) => {
            // Finding if email exists in Database
            const emailExists = await User.findOne({ email });
            if (emailExists) {
                throw new Error("E-mail already in use");
            }
        }),
    body("password")
        .notEmpty()
        .withMessage("Password CANNOT be empty")
        .bail()
        .isLength({ min: 4 })
        .withMessage("Password MUST be at least 4 characters long"),
];

module.exports.forgotPasswordValidator = [
    body("email")
        .trim()
        .notEmpty()
        .withMessage("Email CANNOT be empty")
        .bail()
        .isEmail()
        .withMessage("Email is invalid"),
];

module.exports.resetPasswordValidator = [
    param("resetToken").notEmpty().withMessage("Reset token missing"),
    body("password")
        .notEmpty()
        .withMessage("Password CANNOT be empty")
        .bail()
        .isLength({ min: 4 })
        .withMessage("Password MUST be at least 4 characters long"),
    body("passwordConfirm").custom((value, { req }) => {
        if (value !== req.body.password) {
            throw new Error("Passwords DO NOT match");
        }

        return true;
    }),
];

The code snippet above exports validation rules to be used on requests carrying data received from client-side forms. These are rules about a user's authentication.

For the second set of validators, create user-validators.js located at server/src/validators/(refer above).

And paste in the following code:

const { param } = require("express-validator");

module.exports.fetchUserProfileValidator = [
    param("id").notEmpty().withMessage("User id missing"),
];

The above snippet exports validation rule(s) that act on user object in our application.

Lastly, we would like to export all the validation rules from a single file.

Create index.js at server/src/validators/(refer above). And paste in:

const authValidators = require("./auth-validators");
const userValidators = require("./user-validators");

module.exports = {
    ...authValidators,
    ...userValidators,
};

Simply, we are combining all validation rules and exporting as a single object.

Create authentication middleware

An authentication middleware will intercept HTTP requests to check for authentication.

A request is allowed to proceed to a resource after it has passed authentication check.

Let's create this middleware. So create authCheck.js. According to directory structure(refer above), it should be at the path: server/src/middlewares/.

Paste in the following code:

const jwt = require("jsonwebtoken");

const AuthorizationError = require("../config/errors/AuthorizationError.js");

// Pull in Environment variables
const ACCESS_TOKEN = {
    secret: process.env.AUTH_ACCESS_TOKEN_SECRET,
};

module.exports.requireAuthentication = async (req, res, next) => {
    try {
        const authHeader = req.header("Authorization");
        if (!authHeader?.startsWith("Bearer "))
            throw new AuthorizationError(
                "Authentication Error",
                undefined,
                "You are unauthenticated!",
                {
                    error: "invalid_access_token",
                    error_description: "unknown authentication scheme",
                }
            );

        const accessTokenParts = authHeader.split(" ");
        const aTkn = accessTokenParts[1];

        const decoded = jwt.verify(aTkn, ACCESS_TOKEN.secret);

        // Attach authenticated user and Access Token to request object
        req.userId = decoded._id;
        req.token = aTkn;
        next();
    } catch (err) {
        // Authentication check didn't go well
        console.log(err);

        const expParams = {
            error: "expired_access_token",
            error_description: "access token is expired",
        };
        if (err.name === "TokenExpiredError")
            return next(
                new AuthorizationError(
                    "Authentication Error",
                    undefined,
                    "Token lifetime exceeded!",
                    expParams
                )
            );

        next(err);
    }
};

Above snippet is an express middleware that checks if a request is authenticated in the following steps:

The request has an access token present in the Authorization header. A Bearer token is expected, so we use the split function to get everything after the space. Any errors thrown here will end up in the catch block.
Verify if the access token is valid.

A request is considered authenticated if all goes well in the above steps. It would then be allowed to proceed to a protected resource.

Otherwise, an exception is thrown with a custom error constructor AuthorizationError() which would return an authentication failure response regarding the HTTP specs for returning unauthorized/unauthenticated error.

Create controller functions

In this part we write controllers; the program logic for routes in our application. In express, they are also known as route handlers.

Typically in a routing mechanism, a controller registered for a particular path/route will be run when that route matches. Below are routes in our application. We will write controllers for these routes.

/api/users/login - User login.
/api/users/signup - User signup.
/api/users/logout - User logout.
/api/users/master-logout - User logout from all devices.
/api/users/reauth - Refresh Access Token.
/api/users/forgotpass - Forgot password.
/api/users/resetpass - Reset password.
/api/users/me - Get profile of logged in user.
/api/users/:id - Get profile of user by Id.

So let's get started with creating controllers.

Create auth.controller.js. It should be at the path: server/src/controllers/user/(refer above).

This file will contain controllers that alter user's authentication.

Paste the following code inside the file:

const { validationResult } = require("express-validator");
const jwt = require("jsonwebtoken");
const crypto = require("crypto");

const User = require("../../models/User");
const { sendEmail } = require("../../services/email/sendEmail");
// 👇Were created in part 4
const CustomError = require("../../config/errors/CustomError");
const AuthorizationError = require("../../config/errors/AuthorizationError");

// Top-level constants
const REFRESH_TOKEN = {
    secret: process.env.AUTH_REFRESH_TOKEN_SECRET,
    cookie: {
        name: "refreshTkn",
        options: {
            sameSite: "None",
            secure: true,
            httpOnly: true,
            maxAge: 24 * 60 * 60 * 1000,
        },
    },
};
const ACCESS_TOKEN = {
    secret: process.env.AUTH_ACCESS_TOKEN_SECRET,
};
const RESET_PASSWORD_TOKEN = {
    expiry: process.env.RESET_PASSWORD_TOKEN_EXPIRY_MINS,
};

/*
  1. LOGIN USER
*/

/*
  2. SIGN UP USER 
*/

/*
  3. LOGOUT USER
*/

/*
  4. LOGOUT USER FROM ALL DEVICES
*/

/*
  5. REGENERATE NEW ACCESS TOKEN
*/

/*
  6. FORGOT PASSWORD
*/

/*
  7. RESET PASSWORD
*/

The snippet above has imported modules/dependencies to aid writing logic in controller functions. Global scoped constants which are objects, are also declared. They store environment variables.

Moreover, const REFRESH_TOKEN constant holds cookie configurations in cookie property we will use to set cookie(s) on a HTTP response.

WHAT YOU NEED TO KNOW ABOUT COOKIES in decoupled applications communicating to each other via an API:

By default, browsers will not send cookies in cross-origin requests. Since we are building an API that we intend to consume from client-side sitting on a different origin, we have to set some configurations on the cookie to store in a user's browser. These configurations will allow the cookie to be sent back when cross-site request to our server is made.

These configurations are what are contained in cookie property of const REFRESH_TOKEN object. More specifically in the options property:

const REFRESH_TOKEN = {
    // ...
    cookie: {
        name: "refreshTkn",
        options: {
            sameSite: "None",
            secure: true,
            httpOnly: true,
            maxAge: 24 * 60 * 60 * 1000,
        },
    },
};

We have set sameSite property to "None" which in a cookie context means that the browser can send the cookie with cross site requests.

However, setting a SameSite attribute to None will also require you to set Secure attribute, implying a cookie is only sent in an encrypted request over the HTTPS protocol. Hence in cookie configurations above, we also set secure to true. Localhost is not a https protocol but it is treated special i.e cookie should still be sent even with secure=true. You can learn more about cookie sameSite attribute here.

Another property is httpOnly set to true. In cookie context, a cookie with httponly attribute stored in the browser is inaccessible to scripts running on the browser.

maxAge property sets the age of the cookie to expire in browser.

In the snippet above; where we shared code for auth.controller.js, we have 7 parts numbered each in a multiline comment. We will write controller functions in parts.

In the 1^st part(1. LOGIN USER), Add the following code:

module.exports.login = async (req, res, next) => {
    try {
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
            throw new CustomError(
                errors.array(),
                422,
                errors.array()[0]?.msg
            );
        }

        const { email, password } = req.body;

        /* Custom methods on user are defined in User model */
        const user = await User.findByCredentials(email, password); // Identify and retrieve user by credentials
        const accessToken = await user.generateAcessToken(); // Create Access Token
        const refreshToken = await user.generateRefreshToken(); // Create Refresh Token

        // SET refresh Token cookie in response
        res.cookie(
            REFRESH_TOKEN.cookie.name,
            refreshToken,
            REFRESH_TOKEN.cookie.options
        );

        // Send Response on successful Login
        res.json({
            success: true,
            user,
            accessToken,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

Notice🕵 that we create controllers with the signature of an express middleware, i.e (req, res, next) => {...}. Creating this way will allow us to use next() to pass error encountered here to the error handling midleware configured earlier on.

You'll see this piece of code frequently:

// ...
const errors = validationResult(req);
if (!errors.isEmpty()) {
    throw new CustomError(errors.array(), 422, errors.array()[0]?.msg);
}
// ...

It captures validation errors on the request object. Validators are route level middlewares added before controllers that need user data validation in a route. They enforce validation rules on data in request object. Validation result including errors are aggregated on the request object, hence validation result is available in request object from our controllers. We throw an error using a CustomError constructor if data validation errors are found in request object.

Aside from data validation, the exported controller shared above stipulates control flow for a user login:

Identify user by login credentials received.
Generate Access and Refresh Tokens for the identified user.
Set a cookie in response with Refresh Token as its value.
Send response with Access Token in the body.

In the 2^nd part(2. SIGN UP USER), Add the following code:

module.exports.signup = async (req, res, next) => {
    try {
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
            throw new CustomError(
                errors.array(),
                422,
                errors.array()[0]?.msg
            );
        }
        const { firstName, lastName, email, password } = req.body;

        /* Custom methods on newUser are defined in User model */
        const newUser = new User({ firstName, lastName, email, password });
        await newUser.save(); // Save new User to DB
        const accessToken = await newUser.generateAcessToken(); // Create Access Token
        const refreshToken = await newUser.generateRefreshToken(); // Create Refresh Token

        // SET refresh Token cookie in response
        res.cookie(
            REFRESH_TOKEN.cookie.name,
            refreshToken,
            REFRESH_TOKEN.cookie.options
        );

        // Send Response on successful Sign Up
        res.status(201).json({
            success: true,
            user: newUser,
            accessToken,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

The flow of user sign up:

Save new user with user data from request body.
Generate Access and Refresh Tokens for the new user.
Set a cookie in response with Refresh Token as its value.
Send response with Access Token included in the body.

We include authentication tokens in response because presumably after a successful sign up, the frontend would want to automatically login a user.

In the 3^rd part(3. LOGOUT USER), Add the following code:

module.exports.logout = async (req, res, next) => {
    try {
        // Authenticated user ID attached on `req` by authentication middleware
        const userId = req.userId;
        const user = await User.findById(userId);

        const cookies = req.cookies;
        const refreshToken = cookies[REFRESH_TOKEN.cookie.name];
        // Create a refresh token hash
        const rTknHash = crypto
            .createHmac("sha256", REFRESH_TOKEN.secret)
            .update(refreshToken)
            .digest("hex");
        user.tokens = user.tokens.filter(
            (tokenObj) => tokenObj.token !== rTknHash
        );
        await user.save();

        // Set cookie expiry option to past date so it is destroyed
        const expireCookieOptions = Object.assign(
            {},
            REFRESH_TOKEN.cookie.options,
            {
                expires: new Date(1),
            }
        );

        // Destroy refresh token cookie with `expireCookieOptions` containing a past date
        res.cookie(REFRESH_TOKEN.cookie.name, "", expireCookieOptions);
        res.status(205).json({
            success: true,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

To logout a user:

We obtain refresh token from cookie in incoming request.
Create a hash of the retrieved refresh token to match it with the hashed version stored in the database.
Remove the corresponding hashed refresh token from the list of tokens associated with the user’s record in the database.
Set the refresh token's cookie expiration date to a past time, ensuring that browsers delete it immediately upon receipt.

Note 🔔:

How we have handled logout is designed to preserve the stateless nature of JWTs. By destroying refresh token, it prevents a user from refreshing(renewing) their access token.

However, we do not implement a blocklist to immediately invalidate the current access token, meaning it remains valid until it expires.

While a blocklist could be integrated into the authentication middleware to invalidate Access Tokens instantly, maintaining such a list would contradict the stateless principles of JWTs, even though it effectively ensures immediate Access Token invalidation upon logout.

In the 4^th part(4. LOGOUT USER FROM ALL DEVICES), Add the following code:

module.exports.logoutAllDevices = async (req, res, next) => {
    try {
        // Authenticated user ID attached on `req` by authentication middleware
        const userId = req.userId;
        const user = await User.findById(userId);

        user.tokens = undefined;
        await user.save();

        // Set cookie expiry to past date to mark for destruction
        const expireCookieOptions = Object.assign(
            {},
            REFRESH_TOKEN.cookie.options,
            {
                expires: new Date(1),
            }
        );

        // Destroy refresh token cookie
        res.cookie(REFRESH_TOKEN.cookie.name, "", expireCookieOptions);
        res.status(205).json({
            success: true,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

It is the same concept as logout controller. Only that this time, we destroy all tokens in a user's record, with the line of code: user.tokens = undefined;.

In the 5^th part(5. REGENERATE NEW ACCESS TOKEN), Add the following code:

module.exports.refreshAccessToken = async (req, res, next) => {
    try {
        const cookies = req.cookies;
        const refreshToken = cookies[REFRESH_TOKEN.cookie.name];

        if (!refreshToken) {
            throw new AuthorizationError(
                "Authentication error!",
                undefined,
                "You are unauthenticated",
                {
                    realm: "Obtain new Access Token",
                    error: "no_rft",
                    error_description: "Refresh Token is missing!",
                }
            );
        }

        const decodedRefreshTkn = jwt.verify(
            refreshToken,
            REFRESH_TOKEN.secret
        );
        const rTknHash = crypto
            .createHmac("sha256", REFRESH_TOKEN.secret)
            .update(refreshToken)
            .digest("hex");
        const userWithRefreshTkn = await User.findOne({
            _id: decodedRefreshTkn._id,
            "tokens.token": rTknHash,
        });
        if (!userWithRefreshTkn)
            throw new AuthorizationError(
                "Authentication Error",
                undefined,
                "You are unauthenticated!",
                {
                    realm: "Obtain new Access Token",
                }
            );

        // GENERATE NEW ACCESSTOKEN
        const newAtkn = await userWithRefreshTkn.generateAcessToken();

        res.status(201);
        res.set({ "Cache-Control": "no-store", Pragma: "no-cache" });

        // Send response with NEW accessToken
        res.json({
            success: true,
            accessToken: newAtkn,
        });
    } catch (error) {
        if (error?.name === "JsonWebTokenError") {
            next(
                new AuthorizationError(
                    error,
                    undefined,
                    "You are unauthenticated",
                    {
                        realm: "Obtain new Access Token",
                        error_description: "token error",
                    }
                )
            );
            return;
        }
        next(error);
    }
};

The refreshAccessToken controller:

Extracts refresh token from the incoming HTTP request's cookies.
Decodes the extracted refresh token to access its payload.
Generates a hash of the original (encoded) refresh token extracted from the cookies.
Query the database to find a user that matches two criteria:
1. The user's _id matches the one stored in the decoded refresh token payload.
2. The user's stored refresh token hash matches the hash generated in step 3.
If a matching user is found, generate a new Access Token containing embedded relevant user data retrieved from the database.
Send HTTP response containing the newly generated Access Token.

In the 6^th part(6. FORGOT PASSWORD), Add the following code:

module.exports.forgotPassword = async (req, res, next) => {
    const MSG = `If ${
        req.body?.email || "__"
    } is found with us, we've sent an email to it with instructions to reset your password.`;

    try {
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
            throw new CustomError(errors.array(), 422);
        }

        const email = req.body.email;

        const user = await User.findOne({ email });
        // If email is not found, we throw an exception BUT with 200 status code
        // because it is a security vulnerability to inform users
        // that the Email is not found.
        // To avoid username enumeration attacks, no extra response data is provided when an email is successfully sent. (The same response is provided when the username is invalid.)
        if (!user) throw new CustomError("Reset link sent", 200, MSG);

        let resetToken = await user.generateResetToken();
        resetToken = encodeURIComponent(resetToken);

        const resetPath = req.header("X-reset-base");
        const origin = req.header("Origin");

        const resetUrl = resetPath
            ? `${resetPath}/${resetToken}`
            : `${origin}/resetpass/${resetToken}`;
        console.log("Password reset URL: %s", resetUrl);

        const emailMessage = `
                <h1>You have requested to change your password</h1>
                <p>You are receiving this because someone(hopefully you) has requested to reset password for your account.<br/>
                Please click on the following link, or paste in your browser to complete the password reset.
                </p>
                <p>
                <a href=${resetUrl} clicktracking=off>${resetUrl}</a>
                </p>
                <p>
                <em>
                    If you did not request this, you can safely ignore this email and your password will remain unchanged.
                </em>
                </p>
                <p>
                <strong>DO NOT share this link with anyone else!</strong><br />
                <small>
                    <em>
                    This password reset link will <strong>expire after ${
                        RESET_PASSWORD_TOKEN.expiry || 5
                    } minutes.</strong>
                    </em>
                <small/>
                </p>
            `;

        try {
            await sendEmail({
                to: user.email,
                html: emailMessage,
                subject: "Reset password",
            });

            res.json({
                message: "Reset link sent",
                feedback: MSG,
                success: true,
            });
        } catch (error) {
            user.resetpasswordtoken = undefined;
            user.resetpasswordtokenexpiry = undefined;
            await user.save();

            console.log(error.message);
            throw new CustomError(
                "Internal issues standing in the way",
                500
            );
        }
    } catch (err) {
        next(err);
    }
};

The code above implements a forgot password handler that:

Queries the database to retrieve a user account associated with the email address provided in the incoming HTTP request.
Generates and sends an email to the identified user, containing a secure link for password reset.

This is a sample email sent to a user:

Password reset email

In the 7^th part(7. RESET PASSWORD), Add the following code:

module.exports.resetPassword = async (req, res, next) => {
    try {
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
            throw new CustomError(errors.array(), 422);
        }

        const resetToken = new String(req.params.resetToken);

        const [tokenValue, tokenSecret] =
            decodeURIComponent(resetToken).split("+");

        // Recreate the reset Token hash
        const resetTokenHash = crypto
            .createHmac("sha256", tokenSecret)
            .update(tokenValue)
            .digest("hex");

        const user = await User.findOne({
            resetpasswordtoken: resetTokenHash,
            resetpasswordtokenexpiry: { $gt: Date.now() },
        });
        if (!user) throw new CustomError("The reset link is invalid", 400);

        user.password = req.body.password; // Will be hashed by mongoose middleware
        user.resetpasswordtoken = undefined;
        user.resetpasswordtokenexpiry = undefined;

        await user.save();

        // Email to notify owner of the account
        const message = `<h3>This is a confirmation that you have changed Password for your account.</h3>`;
        // No need to await
        sendEmail({
            to: user.email,
            html: message,
            subject: "Password changed",
        });

        res.json({
            message: "Password reset successful",
            success: true,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

The code snippet implements a password reset handler that follows these steps:

Extract the reset token from the incoming HTTP request.
Decode the URI-encoded reset token using decodeURIComponent() to restore its original character representation.
Parse the decoded reset token, which is composed of two parts—a reset token value and a reset token secret—separated by a + symbol.
Generate a reset token hash using the parsed components, as the database stores reset tokens in hashed form for security.
Query the database for a user record that meets two criteria:
1. The stored reset password token matches the generated reset token hash.
2. The token's expiry time has not yet passed.
If a matching user is found, update their password with the new password provided in the request body.
Asynchronously send an email notification to the user confirming the password change, while simultaneously returning a success HTTP response to the client.

So we have created the first set of controller functions that control user's auth in auth.controller.js.

Next we need to create the second set of controller functions that act on user object in our application.

Open/create user.controller.js. According to the directory structure for this tutorial, it should be at the path: server/src/controllers/user/(refer above). Create the constituent directories if you do not have.

This file will contain controllers that act on user object in our application.

Paste in the below code inside this file:

const { validationResult } = require("express-validator");

const CustomError = require("../../config/errors/CustomError");
const User = require("../../models/User");

/* 
  1. FETCH USER PROFILE BY ID
*/
module.exports.fetchUserProfile = async (req, res, next) => {
    try {
        const errors = validationResult(req);
        if (!errors.isEmpty()) {
            throw new CustomError(
                errors.array(),
                422,
                errors.array()[0]?.msg
            );
        }

        const userId = req.params.id;
        const retrievedUser = await User.findById(userId);

        res.json({
            success: true,
            user: retrievedUser,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

/* 
  2. FETCH PROFILE OF AUTHENTICATED USER
*/
module.exports.fetchAuthUserProfile = async (req, res, next) => {
    try {
        const userId = req.userId;
        const user = await User.findById(userId);

        res.json({
            success: true,
            user,
        });
    } catch (error) {
        console.log(error);
        next(error);
    }
};

This is straight forward. We have two functions that fetch user profile. The first one fetchUserProfile(), fetches a user by ID provided in URL. And the second one fetchAuthUserProfile, fetches a user by ID gotten from authentication middleware as req.userId.

We have so far created and exported controller functions in separate files. Let's export all these controllers from a single file so that we could import them in other modules with one import statement.

For this, open/create a third file index.js, at the location server/src/controllers/user/(refer above).

Add the code below in this file:

module.exports = {
    ...require("./auth.controller"),
    ...require("./user.controller"),
};

We export one object that includes all exports from the imported files.

Create application routes

So far, we have written models and controllers. Now we need to create routes in our application. Basically, we will specify route paths and the controller to execute program logic at that path.

For this, open/create user.routes.js, at the location server/src/routes/(refer above). Create the constituent directories if you do not have.

Add the code below in this file:

const express = require("express");

const validators = require("../validators");
const userControllers = require("../controllers/user");
const { requireAuthentication } = require("../middlewares/authCheck");

const router = express.Router();

// User Login
router.post("/login", validators.loginValidator, userControllers.login);

// User Signup
router.post("/signup", validators.signupValidator, userControllers.signup);

// User Logout
router.post("/logout", requireAuthentication, userControllers.logout);

// User Logout from all devices
router.post(
    "/master-logout",
    requireAuthentication,
    userControllers.logoutAllDevices
);

// Refresh Access Token
router.post("/reauth", userControllers.refreshAccessToken);

// Forgot password
router.post(
    "/forgotpass",
    validators.forgotPasswordValidator,
    userControllers.forgotPassword
);

// Reset password
router.patch(
    "/resetpass/:resetToken",
    validators.resetPasswordValidator,
    userControllers.resetPassword
);

// Authenticated user profile
router.get(
    "/me",
    requireAuthentication,
    userControllers.fetchAuthUserProfile
);

// Get user by ID
router.get(
    "/:id",
    requireAuthentication,
    validators.fetchUserProfileValidator,
    userControllers.fetchUserProfile
);

module.exports = router;

The code above contains the routes our application will have. We used express.Router() to organize application routes into a separate file.

Using the classic router object, we define routes in the order of HTTP Method, route path and controller, i.e router.METHOD("PATH", CONTROLLER). In between route path and controller, we can add middleware(s) that intercept a request for earlier processing.

For instance, from the snippet above, Authentication middleware(requireAuthentication) and validators(validators.x) are middlewares that intercept a request before it is processed in controller(userControllers.x). Authentication middleware ensures request is authenticated and validators apply validation rules on data within a request.

Since the routes we have defined are all concerned with the user object in our application, let's define a base path for these routes.

Open/create index.js, at the location server/src/routes/(refer above).

Add the code below in this file:

const express = require("express");
const router = express.Router();

const userRoutes = require("./user.routes");

router.use("/users", userRoutes);

module.exports = router;

The snippet above makes userRoutes available on /users base path. With this pattern, if your application has another user type e.g admin, you can create another base path for it.

We then export router object created here.

Register routes

We need to register routes we have created so that web traffic can be chanelled to them.

Therefore we need to include these routes in the entry file of our application. Open this file, index.js located at server directory root, i.e server/(refer above).

Edit the 3^rd part of this file like shown below:
```
const routes = require("./routes"); // import the modular routes at the top

// ...
/* 
3. APPLICATION ROUTES 🛣️
*/
app.use("/api", routes); // register modular routes
// ...
```
We have imported the routes and regisered them on a base path, "/api". Therefore in the long run, user routes will be available on a path /api/users/.... For example to access login route, the path is /api/users/login.

Conclusion

Cheers🥂, we have reached the end. This article has been an extensive exploration, packed with valuable information🤯 to elevate your technical prowess; perhaps the divine touch you needed. Through this process, we've successfully engineered a backend system complete with robust user registration and authentication features.

It's often observed that newcomers to web development struggle to grasp the intricacies of implementing JWT-based authentication correctly. Moreover, many find it challenging to incorporate essential security practices when working with JWTs.

Security is an expansive and mission-critical topic. In this article we have have implemented crucial security practices to consider when using JWTs for authentication, i.e access tokens and refresh tokens. For example:

An access token is short-lived unlike the refresh token.
Access token can be included in HTTP response body while refresh token is set in httpOnly response cookie.
Secure token storage in databases, i.e in hashed form, crucial to minimize security risk should the database be compromised.
A secure process is implemented to refresh Access Tokens using Refresh Tokens.
Token clean-up on user logout:
- Clear specific token to destroy a specific login session(single log-out)
- Clear all tokens to destroy all login sessions(log out from all devices)

Building an authentication API is a superb feat. However, I understand that integrating it into a frontend can still feel overwhelming for many. If you're unsure how to piece it all together to create a seamless authentication experience, don’t worry. Let me know in the comments if you would like to see the next sections, where we walk through building the frontend with React, making the process clear and straightforward.

Let's connect @x. Till then...peace✌.

The history of HTTPS

Smitter — Tue, 02 May 2023 13:46:26 +0000

Two computers follow a series of agreed-upon steps to establish a communication tunnel with each other. A protocol outlines these compulsory steps. HTTP protocol is the protocol that clients and web servers use to communicate with each other.

HTTP was developed by Tim Berners-Lee and his team between 1989-1991 while he was working at CERN. It was intended to exchange files between the multiple computers at the laboratory. It was a clear text protocol.
Other computers outside of CERN adopted the protocol in their internet usage. As internet evolved, sensitive information were being shared via this protocol.
However, since HTTP transfers data between client and server as plain text, it posed a problem. A malicious intruder that intercepts the network segment between you(the client) and the server, is able to view sensitive information such as passwords and credit card numbers. Or the intruder could intercept a client's request and serve back malicious files pretending to be the server.

Therefore, adding an encryption layer to the HTTP protocol was necessary.

TLS is an acronym for Transport Layer Security. And it is an encryption layer added to the HTTP protocol to stop malicious intruders from snooping sensitive and restricted data happening in between client and the server. HTTP protocol that includes an encryption layer upgrades to the acronym of HTTPS(HyperText Transfer Protocol Secure). Hence sensitive information shared via HTTPS protocol can reliably be considered as safe and confidential from eavesdropping attacks.

TLS was not formed outright as the step of trial and error had not to be skipped. TLS is a successor of SSL(Secure Sockets Layer).

SSL developments

As mentioned above, TLS is a successor of SSL.

SSL was a cryptographic protocol developed by Netscape. SSL version 1.0 was developed in 1994. But it was never publicly released because it was discovered to have serious flaws. In February 1995, version 2.0, was developed and released to the public. However it was quickly discovered to contain a number of security and usability flaws.
Microsoft released the first version of its PCT(Private Communication Technology) protocol, designed to address the security flaws in SSL Version 2. PCT never gained traction outside Microsoft products and was later on superseded with SSL version 3.

Back at Netscape, the critical security issues in version 2 necessitated the complete redesign of the protocol from the ground up. SSL version 3.0 was then released in 1996.

Birth and timeline of TLS

In 1996, a working group was formed at IETF(Internet Engineering Task Force) to standardize SSL. This is after an agreement where both Netscape and Microsoft would support the IETF taking over the protocol and standardizing it in an open process.

Three years later(in 1999), the 1^st upgrade to SSL version 3.0 was published as TLS 1.0 in RFC 2246. TLS 1.0 had minor changes to SSL 3.0 as stated in the RFC:

differences between this protocol and SSL 3.0 are not dramatic, but they are significant enough that TLS 1.0 and SSL 3.0 do not interoperate

Tiem Dierks, an editor in RFC 2246, later on says in his blog:

As a part of the horsetrading, we had to make some changes to SSL 3.0 (so it wouldn't look the IETF was just rubberstamping Netscape's protocol), and we had to rename the protocol (for the same reason). And thus was born TLS 1.0 (which was really SSL 3.1).

TLS was born as from version 1.0 and today it is still being used as the standard encryption layer on HTTP protocol. Countable TLS vesions have being released since then i.e TLS 1.0, TLS 1.2 and TLS 1.3. The most recent version(as of 2023) is TLS 1.3 which was released in August 2018.

Earlier versions of TLS have been overshadowed with the recent and more bullet-proof versions. In October 2018, Apple, Google, Microsoft, and Mozilla jointly announced they would deprecate TLS 1.0 and 1.1 in March 2020. TLS 1.0 and 1.1 were formally deprecated in RFC 8996 in March 2021.

SSL has never received an update since its SSL 3.0 release in 1996 and hence new vulnerabilities have been found with the evolved cyber security attacks. SSL 3.0 was deprecated in June 2015 in RFC 7568.

Here is the encryption protocol layer history summarized in a table:

protocol	published	status
SSL 1.0	unpublished	unpublished
SSL 2.0	1995	Deprecated in 2011 (RFC 6176)
SSL 3.0	1996	Deprecated in 2015 (RFC 7568)
TLS 1.0	1999	Deprecated in 2021 (RFC 8996)
TLS 1.1	2006	Deprecated in 2021 (RFC 8996)
TLS 1.2	2008	In use since 2008
TLS 1.3	2018	In use since 2018

Despite that SSL was replaced more than 20 years ago by TLS, many people still use the term SSL when they mean TLS.

Let's connect on twitter.

Deftly🦅 Handle exceptions in Node/Express Application

Smitter — Fri, 31 Mar 2023 09:39:27 +0000

Welcome to part 4. Follow along this series to build a 3-tier Login System implementing core features required of an effective and usable authentication system.

Summary: In this tutorial, you will learn to create user-defined exceptions and handle these exceptions (or other unexpected events) as they occur through proper error handling in express.

Note 🔔:

If you would like to jump ahead to the finally built authentication system, the complete Git Repo can be found on Github✩.

With how Javascript engine works, when a runtime error occurs, execution will stop and an error is generated. In technical parlance, a runtime error causes new Error object to be created and thrown. In such an event, the rest of code is not executed.

Well, that is how Javascripts handles itself when you write bad code. Likewise, the application you are building needs to handle itself when it receives bad input. Or when other unexpected events occur, including a runtime error.

For example, division by zero is not an error in Javascript. But logic in your application requires that it should be. The throw keyword allows you to stop javascript execution whilst generating a custom defined exception. As you generate exception, you should handle it and communicate back to the user with succinct information about what went wrong.

Table of Contents

What we will do
1. Create custom error constructors
2. Create error/exception handlers
3. Configure error handlers in express application
4. Error Handling in action
Final thoughts

Outline of what we will do:

Create custom error constructors.
Create error/exception handlers.
Configure express application to use custom error handlers.
Error Handling in action.

In an error flow control, we will throw using a custom error constructor, to generate a user-defined exception. The generated exception will be processed in error handler.

Directory structure

📂server/
└── 📂src/
    ├── 📄index.js
    └── 📂config/
+       ├── 📂errors/
+       │   ├── 📄AuthorizationError.js
+       │   └── 📄CustomError.js
+       └── 📂exceptionHandlers/
+           └── 📄handler.js

This is the structure in regard to the src directory that contains our code. We will update these files with code to provide the logic we want to achieve. You can always double check to create these files in their correct locations.

1. Create custom error constructors

Certainly you may be familiar with the in-built Error constructor, i.e new Error(), which actually creates an Error object.

Let's create custom error constructor which is a superset of the in-built Error, by which we will be able to add more properties to the created Error Object we will need later.

First, open the file: CustomError.js. According to the directory structure for this tutorial(refer above), it should be at the path: server/src/config/errors/. Create the constituent directories if you do not have.

Inside the opened file, paste in the following code:

class CustomError extends Error {
    /**
     * Custom Error Constructor
     * @param {any} [message] - Optional error payload
     * @param {number} [statusCode] - Optional error http status code
     * @param {string} [feedback=""] - Optional feedback message you want to provide
     */
    constructor(message, statusCode, feedback = "") {
        super(message);
        this.name = "CustomError";
        this.status = statusCode;
        this.cause = message;
        this.feedback = String(feedback);
    }
}

module.exports = CustomError;

The snippet above simply creates a class that extends base Error class that is in-built to javascript. We define a constructor that passes message as first argument to the base class(By calling super(message)), and adds additional properties to the result Error Object when the class is instantiated.

To cause a user-defined exception in our application, we will throw CustomError(). Arguments can be passed to define properties on created Error object.

Second, open/create the file: AuthorizationError.js. Expected to be at the path: server/src/config/errors/(refer above).

Paste the following code in the file:

const CustomError = require("./CustomError");

class AuthorizationError extends CustomError {
    /**
     * Authorization Error Constructor
     * @param {any} [message] - Error payload
     * @param {number} [statusCode] - Status code. Defaults to `401`
     * @param {string} [feedback=""] - Feedback message
     * @param {object} [authParams] - Authorization Parameters to set in `WWW-Authenticate` header
     */
    constructor(message, statusCode, feedback, authParams) {
        super(message, statusCode || 401, feedback); // Call parent constructor with args
        this.authorizationError = true;
        this.authParams = authParams || {};
        this.authHeaders = {
            "WWW-Authenticate": `Bearer ${this.#stringifyAuthParams()}`,
        };
    }

    // Private Method to convert object `key: value` to string `key=value`
    #stringifyAuthParams() {
        let str = "";

        let { realm, ...others } = this.authParams;

        realm = realm ? realm : "apps";

        str = `realm=${realm}`;

        const otherParams = Object.keys(others);
        if (otherParams.length < 1) return str;

        otherParams.forEach((authParam, index, array) => {
            // Delete other `realm(s)` if exists
            if (authParam.toLowerCase() === "realm") {
                delete others[authParam];
            }

            let comma = ",";
            // If is last Item then no comma
            if (array.length - 1 === index) comma = "";

            str = str + ` ${authParam}=${this.authParams[authParam]}${comma}`;
        });

        return str;
    }
}

module.exports = AuthorizationError;

AuthorizationError is an error intended to be generated due to insufficient authentication.

It is extends the CustomError class adding extra properties as well. Majorly, the constructor for this error class has a statusCode that defaults to 401 which is passed to base class(CustomError) when calling super().

Also, we have defined #stringifyAuthParams() private method to convert authParams object parameter to a list of comma separated strings of format key=value. The formatted string is used to generate value for the authheaders property.

New to private methods in javascript classes? Read more here.

Error object created using this class will be processed by error handler to produce a 401 - Unauthorized Error response that observes the web specifications, which require a response due to failed authentication include a WWW-Authenticate header. Learn more here.

2. Create error/exception handlers

Here we will create handlers for unexpected events that occur in our application. These handlers are important to prevent a running program from shutting down unceremoniously to its users. Furthermore they provide concise information to the user about what went wrong.

We will create two error handlers:

404 case handler i.e handler called when http request on a path that does not exist hits our server.
General exception handler i.e handler called when exceptions are generated from anywhere in our application.

Open the file: handler.js. According to the directory structure for this tutorial(refer above), it should be at the path: server/src/config/exceptionHandlers/. Create the constituent directories if you do not have.

Paste the following code inside the file:

// 404 Error Handler
function LostErrorHandler(req, res, next) {
    res.status(404);

    res.json({
        error: "Resource not found",
    });
}

// Exception Handler
function AppErrorHandler(err, req, res, next) {
    res.status(err.status || 500);

    if (err.authorizationError === true) {
        // Sets headers available in Authorization Error object
        res.set(err.authHeaders);
    }

    // `cause` is a custom property on error object
    // that may contain any data type
    const error = err?.cause || err?.message;
    const providedFeedback = err?.feedback;

    // respond with error and conditionally include feedback if provided
    res.json({
        error,
        ...(providedFeedback && { feedback: providedFeedback }),
    });
}

module.exports = { LostErrorHandler, AppErrorHandler };

We have defined two functions here taking the signature of express middleware.

The first one, LostErrorHandler() function is the 404 case handler. Importantly, it sets a 404 status code on the response(res).

And the second one, AppErrorHandler() function has 4 parameters which distinguishes it as an express error middleware. This is the General exception handler.

Properties are available on the err parameter of the AppErrorHandler() function depending on error constructor that created the Error object. For example we see this line:

// ...
if (err.authorizationError === true) {
    res.set(err.authHeaders);
}
// ...

We know err is an authorization error object when we throw an exception using the custom AuthorizationError constructor, like:

throw new AuthorizationError();

This will create an Error object that contains authorizationError property set to true. Also includes authHeaders property e.t.c.

3. Configure express application to use custom error handlers.

The last step is to configure the express application to use error handlers we have created. For this, open index.js which is the entrypoint to our application. This file should be located at server/src/.

Add the following code to this file:

const express = require("express");

const {
    AppErrorHandler,
    LostErrorHandler,
} = require("./config/exceptionHandlers/handler.js");

/* 
  1. INITIALIZE EXPRESS APPLICATION 🏁
*/
const app = express();
const PORT = process.env.PORT || 8000;

/* 
  2. APPLICATION MIDDLEWARES AND CUSTOMIZATIONS 🪛
*/
// ...

/* 
  3. APPLICATION ROUTES 🛣️
*/
// Test route
app.get("/", function (req, res) {
    res.send("Hello Welcome to API🙃 !!");
});

/* 
  4. APPLICATION ERROR HANDLING 🚔
*/
// Handle unregistered route for all HTTP Methods
app.all("*", function (req, res, next) {
    // Forward to next closest middleware
    next();
});
app.use(LostErrorHandler); // 404 error handler middleware
app.use(AppErrorHandler); // General app error handler

/* 
  5. APPLICATION BOOT UP 🖥️
*/
app.listen(PORT, () => {
    console.log(`App running on port ${PORT}`);
});

In the fourth part of the snippet above, we have configured our app to handle 404 error case and general errors that may occur from anywhere in the application.

A few vital things to note:

We have added error handling at part4 after routes for the application have been registered at part3. This way, incase of incoming request requiring resource on non-existent path, a 404 error handler will catch and process this error. And it is called only after no route has been matched in the routes registered at part3.
We have added General error handler middleware as the last-most middleware in the express middleware chain. It is important to declare it last so that any unhandled errors that occur before it, can be captured and handled.

Hence when it comes to effective error handling in express, order of placement of the error handlers is important.

Cheers!🥂. Up to this point, your program should be equipped to gracefully handle unexpected errors that may occur in route handlers and middlewares.

Infact, let us test run by introducing error in our application.

4. Error Handling in action

To test Error Handling in our application, let's add another test route. So once again, open index.js file which should be found at the path: server/src/.

Edit part 3 this file to add a new route, like shown:

const CustomError = require("./config/errors/CustomError.js");

// ...

/* 
  3. APPLICATION ROUTES 🛣️
*/
// ...
// Test Crash route
app.get("/boom", function (req, res, next) {
    try {
        throw new CustomError("Oops! matters are chaotic💥", 400);
    } catch (error) {
        next(error);
    }
});

// ...

We have added a new route,(/boom) and its route handler.

Note: The route handler is written with the signature of express middleware, i.e it takes three parameters. Writing as an express middleware enables us to pass any errors generated here to the application's error handler we have configured using the next() function, which is available as the third parameter in the route handler.

This route handler throws an error inside a try...catch construct, using our predefined CustomError class. We have passed a string message and a number for the HTTP status code we would like to return in the response. This will create an error object that will be caught by catch(). Inside the catch(){...} block, we simply forward the caught error to our configured error handling middleware with a single line of code: next(error). And that is it🦸.

Run the program. And when you run it, open your browser or any other client you prefer e.g postman. Then navigate to the route that throws an error, i.e http://localhost:8000/boom.

You should see that the error thrown in our application was handled deftly by error handler configured. And of course, our application is still running. It did not shut down.

Notice that the string message and HTTP status code passed to CustomError constructor are included in the response body and header respectively:

HTTP request/response made with curl

Final thoughts

Well that is how you handle exceptions that can occur while running route handlers and middlewares in express. Possibly this is a compelling way since it reduces boiler plate code you need to write in the catch(){...} block, especially in the route handlers. Additionally, "regular code" in route handlers is separated from "error handling code".

Using Custom Error constructors to create Error objects when we throw is important for providing additional properties to the Error generated. The error handler can then obtain the properties on an error and respond to a user with concise information about what went wrong.

In the example where we test to see error-handling in action, we wrapped logic for the route handler inside try...catch construct. If all we are going to write is synchronous code only, then we do not need to explicitly call next(error) function with the error caught which is the case inside catch(){...} block. Therefore we can throw without the try...catch construct and Express will automatically pass the error to error-handling middleware. But it is worthy to avoid writing code that is magical🪄.

However if you write asynchronous operations, you must call next(error) function with the error returned, so it may be caught by the error-handling middleware. For example we may write a route handler that has asynchronous operation like this:

app.get("/boom", async function (req, res, next) {
    const iAlwaysReject = new Promise((resolve, reject) => {
        setTimeout(() => reject("Operation failed!"), 2000);
    });
    try {
        await iAlwaysReject(); // Asynchronous OP
    } catch (error) {
        next(error); // Explicitly call next
    }
});

Note: In Express 5 and above, asynchronous operations that reject or throw an error will call next(error) function automatically with the thrown error or the rejected value. If no rejected value is provided, next will be called with a default Error object provided by the Express router. With above example, it means you can await without wrapping in try...catch construct nor calling next(error) explicitly. But why write code that is magical? 🤷‍♂️

Express ships with a default error handler. Of course it is not feature rich as you may want to create your own. I guess it is good enough to get you started.

Do you have other opinions? Drop them in the comment section🕳🤾. Meanwhile, I hope you found the article useful and...peace✌️.

Follow me @twitter. I share content that may be helpful to you😃.

Keep cors error under control⚒️

Smitter — Sun, 19 Mar 2023 09:19:11 +0000

Welcome to part 3. Follow along this series to develop a feature-packed 3-tier Authentication System outlined in successive parts.

Summary: In this article we will learn to configure an express backend application to understand CORS Protocol.

Note 🔔:

If you would like to jump ahead to the final Authentication System put together, the complete Git Repo can be found on Github✩.

Let's start here with an example case.

You have built a stunning user interface 😎. Now you are ready to pull data from external API and inject in the UI for display. You have scripts that make HTTP requests to API. But something is standing in the way 🛑. The console blazes fiery red and ranting🗣️:

Tellingly, you have run into CORS error.

Table of Contents

Why CORS Error?
What is CORS?
Enable CORS
Enable CORS for credentialed requests
Conclusion

Why CORS Error?

Using the example above, this error occurs because UI is loaded on a different port, i.e http://localhost:3000 and the scripts in it are requesting to a different port i.e http://localhost:8000. So scripts are making cross-origin requests. Well, Same-origin policy is violated! And therefore the browser blocks such a request 👊.

Note: Two URLs have the same origin if the protocol, port (if specified), and host are the same for both.

It is a security motive that browsers restrict cross-origin HTTP requests initiated from scripts. "XMLHttpRequest" and "Fetch" are browser APIs that adhere to same-origin policy. This means that a web application using these APIs can only request resources from the same origin the application was loaded from. In layman's language, scripts in a web page can "peacefully" request to the URL shown in the address bar without being hurled with confrontations by the browser. This way, the nightmarish CORS error is well tucked out of sight.

But with special configurations, cross-origin requests can succeed. However, these configurations need to be done on the backend rather than the frontend. These configurations are what we will be looking at in this article.

So,

What is CORS?

CORS is an abbreviation for Cross-Origin Resource Sharing.

It is a standard that allows a server to moderate same-origin policy in browsers, so cross-site requests made to it can be allowed. And this involves sending appropriate CORS headers that will be verified in the browser.

Ultimately this means that if you run into a CORS error, the fix lies in backend configuration.

Getting started

This is how we organize the nodejs project.

Start by creating a server directory and change into it:

d="server" && mkdir $d && cd $d

Inside server directory, run npm init -y to create a package.json file. Add/edit the package.json file to include the following script:

// ...
"scripts": {
    "start": "node src/index.js",
}
// ...

Run npm install express --save to install express web framework.

Then create src directory(mkdir src) inside this server directory. Below is the overall directory structure.

Directory structure

📂server/
    ├── 📄package.json
    └── 📂src/
        ├── 📄index.js
+       └── 📂config/
+            └── 📂cors/
+                └── 📄cors.js

This is the structure with focus on the src directory. The src directory will contain files with code we write for our project. We will add code in these files as we progress through the article. You can always double check to create these files in their correct locations.

Enable CORS

We are going to configure CORS protocol on our express backend. The CORS protocol simply consists of a set of headers that indicates whether a response can be shared with the origin that requested.

The set of headers that can be set on response to a CORS request are listed here.

To reduce the work of setting these headers manually, we will use an npm library called cors. So be sure to install it:

npm install cors --save

Then open the entry point of our application file, i.e index.js, located at server/src/(refer). Add the cors middleware as shown in section 2:

const express = require("express");
const cors = require("cors");

/* 
   1. INITIALIZE EXPRESS APPLICATION 🏁
*/
const app = express();
const PORT = process.env.PORT || 8000;

/* 
   2. APPLICATION MIDDLEWARES AND CUSTOMIZATIONS 🪛
*/
app.use(cors()); // Enable Cross Origin Resource Sharing

/* 
   3. APPLICATION ROUTES 🛣️
*/

/* 
   4. APPLICATION ERROR HANDLING 🚔
*/

/* 
   5. APPLICATION BOOT UP 🖥️
*/
app.listen(PORT, () => console.log("App listening on port " + PORT));

Note: The file index.js has commented sections that are numbered. Some sections have logic defined in other parts of the series.

Yes, dead simple as that. The CORS headers will be set on HTTP response by the cors() middleware when the browser sends a preflight request and the actual request.

By default, cors library sets Access-Control-Allow-Origin header with a wildcard(*) value on the actual response.

While this configuration of cors library works, it will fail for Cross-Orign requests that include credentials. Because a request that includes credentials(e.g Cookie header), requires additional headers configured and that the headers are set explicitly(not wildcarded). Therefore a header including a wildcard(*) value will fail.

Credentials are cookies, authorization headers, or TLS client certificates.

Below is an example of a failure message when a request with credentials receives a response with Access-Control-Allow-Origin header set with a wildcard(*):

CORS error when Access-Control-Allow-Origin header is a wildcard

cors library needs additional configuration to set CORS headers appropriately for requests including credentials.

Enable CORS for credentialed requests

Like said earlier, credentialed requests are requests that include credentials, i.e cookies,authorization headers or TLS client certificates.

The Authentication System we are building in this series will make use of cookies, so it's important to configure our backend to understand CORS protocol for credentialed requests.

Open the file cors.js which should be available at path server/src/config/cors/(refer). Create the constituent directories if you do not have.

Paste the following code inside cors.js file:

const allowlist = ["http://localhost:3000", "http://localhost:8000"];
const corsOptions = {
    origin: function (origin, callback) {
        if (allowlist.includes(origin)) {
            callback(null, true);
        } else {
            callback(new Error("Not allowed by CORS"));
        }
    },
    credentials: true,
    exposedHeaders: ["WWW-Authenticate"],
};

module.exports = corsOptions;

We are allowing an origin that is in allowlist to access our API. Anything else is locked out; represented by passing a first argument to the callback function: callback(new Error("Not allowed by CORS"));.

This cors option will explicitly set Access-Control-Allow-Origin response header to the value of origin that has been cross-checked to exist in the allowlist.

The next property option is:

credentials: true,

This cors option will set Access-Control-Allow-Credentials response header to true, which basically gives an okay that our server will accept cookies from a cross-origin request(Client application). The browser requires that this header exists in response to preflight request and before setting a cookie in client device as directed by Set-cookie header of a response received.

Then we have:

exposedHeaders: ["WWW-Authenticate"],

This cors option will set Access-Control-Expose-Headers response header to WWW-Authenticate.
This is not mandatory but if you need to access this header(or any other) with scripts running in the browser, then you need to set it.

You may set other options you may need. The options we have set here should be able to understand the CORS protocol for credentialed requests.

What is remaining, is to include these options to the CORS middleware from the entry file of our application. Therefore open index.js found at server/src/(refer) and include these options in cors middleware as shown:

const corsOptions = require("./config/cors/cors.js");

// ...

/* 
  2. APPLICATION MIDDLEWARES AND CUSTOMIZATIONS 🪛
*/
app.use(cors(corsOptions)); // Enable Cross Origin Resource Sharing
// ...

Congrats! This is the way! Now you can seamlessly make cross-site requests to your backend. Whether the request include credentials or not, CORS error should not intrude.

Conclusion

We have looked at how to solve the CORS error you may run into, why it happens and what it really is. CORS error happens because the browser is reminding you to implement security in your application. We have seen how to we can configure CORS in an application that intends to work with requests that include credentials such as cookies.

If you can control the backend, then you can fix CORS error, otherwise the fix is out of your control. You still may opt for hacky workarounds such as proxying requests.

Fixing CORS error generally implies setting response headers.

These specific headers can be set using third-party libraries like cors which is well battle-tested and effective in its job. However, you can still set the headers manually(which creates room for errors 🤕).

Did I leave out something? You can put it in the comments section.

We can connect @twitter and share ideas.

Database integration🪢 in node/express - A maintainable approach

Smitter — Mon, 13 Mar 2023 06:00:00 +0000

Welcome to part 2. Follow along this series to develop a feature-packed 3-tier Authentication System outlined in successive parts.

Summary: In this article, we learn to integrate a node application with a database using a promise-based ODM/ORM in a maintainable approach.

Note 🔔:

A complete Repo of this series can be found on Github✩. Drop a star💫️ if you found it useful.

Table of Contents

Directory Structure
Create package.json
Create .env file
Install dependencies
Set up database connection
Run database connection in application
Conclusion

Directory structure

📂server/
  ├── 📄package.json
  ├── 📄.env
  └── 📂src/
      ├── 📄index.js
      └── 📂dbConn/
           └── 📂mongoose/
               └── index.js

This is the structure with focus on the src directory. The src directory will contain files with code we write to run our application. We will add code in these files as we progress through the article. You can always double check to create these files in their correct locations.

Create `package.json`

From the root level of server directory, run the command npm init -y.

This command will generate a package.json file inside our server folder. Then edit the package.json file to look like this:

{
    "name": "api",
    "version": "1.0.0",
    "description": "",
    "private": "true",
    "main": "src/index.js",
    "scripts": {
        "start": "node src/index.js",
        "dev": "nodemon src/index.js",
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "keywords": [],
    "author": "hane-smitter",
    "license": "MIT"
}

Importantly, change the main property to point to "src/index.js" which will be the entry file to our application. And also add "start" and "dev" scripts:

// ...
"scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
}
// ...

Create `.env` file

A .env or dotenv file is a key-value text configuration file for defining application's environment constants.

Let's create environment variables our application will use.

To do this, create a .env file at the server directory root(refer) and add the following variable(s):

MONGODB_URI=

MONGODB_URI is the MongoDB database connection string. It is currently empty but we will assign a value to it later on.

Note: Remember to include .env file to your .gitignore, should you initialize a git project. .env file is meant to be private to you and should not be shared outside of your local repository.

Install dependencies

We have initialized our project with package.json file. We can now add dependencies from the npm registry that we will need in this project.

We will use the following dependencies:

Express - A web framework written in JavaScript and hosted within the Node.js runtime environment, to generally help us handle requests coming to our server.
Mongoose - An object modelling tool for MongoDB to allow us to enforce a specific mongoDB schema from our application.
Dotenv - To load environment variables declared in .env file.
Nodemon - To restart our server after file changes.

Therefore install the dependencies with terminal opened from the root of server directory by running the command:

npm install mongoose express dotenv --save

Then install nodemon as a development dependency, which means that we only need nodemon during development time of our application:

npm install nodemon --save-dev

Set up database connection

In this step, we will connect to a MongoDB database hosted in the cloud, i.e MongoDB Atlas. If you do not have MongoDB installed locally on your machine, you can still hit the ground running with the hosted version👍.

First, you will need a connection string connecting to MongoDB as a cloud service. Create MongoDB Atlas account or login if you already have one. Then follow this guide to obtain your connection string.

Once you have your connection string, open the .env file and set the MONGODB_URI like shown:

MONGODB_URI=mongodb+srv://<user>:<password>@sample.host/<db_name>?retryWrites=true&w=majority

You can as well substitute with URI of local mongoDB installation. In this case your connection URI will look like: mongodb://127.0.0.1:27017/<dbname>.

Then, open terminal at server directory root, create src directory and change into it:

mkdir src
cd src

src is where code we write for our backend will reside.

We will start by creating a file for our MongoDB connection.

Open/create index.js file located at server/src/dbConn/mongoose/(refer). Paste the following code in it:

const mongoose = require("mongoose");

// Pull in environment variable
const connURI = process.env.MONGODB_URI;

mongoose.set("strictQuery", false);
mongoose.set("bufferCommands", false); // Disable buffering

// Connect to MongoDB and store connection in variable
const db = mongoose.connect(connURI);

db.catch((err) => {
    if (err.message.code === "ETIMEDOUT") {
        console.log(`----${err.message.code}----`);
        // console.log(err);
        mongoose.connect(connURI);
    }
    console.log(`----${err.message}----`);
});

module.exports = db;

The code above is straight-forward where we get connection string to our MongoDB database from the environment variable: const connURI = process.env.MONGODB_URI;. We connect to it and store the conection in db variable. We chain catch() to handle error that may occur during the connection. Though we don't handle the "fulfilled" case here. And if a timeout error occurs, we retry to connect. Otherwise we just log the error to the terminal.

Finally we default export the mongoose connection stored in db variable.

Run database connection in application

Here we need to include database connection in our entry file where it will be actually run on application start-up. And we synchronize the successful database connection to server listening on Tcp port.

Open/create the entry file to our application. This file should be index.js located at server/src/(refer). Remember that this is the file referenced by the "main" property in our package.json file.

Add the following code inside this file:

require("dotenv").config();
const express = require("express");

const dbConnection = require("./dbConn/mongoose");

/* 
   1. INITIALIZE EXPRESS APPLICATION 🏁
 */
const app = express();
const PORT = process.env.PORT || 8000;

/* 
   2. APPLICATION MIDDLEWARES AND CUSTOMIZATIONS 🪛
 */

/* 
   3. APPLICATION ROUTES 🛣️
 */
// Test route
app.get("/", function (req, res) {
    res.send("Hello Welcome to API🙃 !!");
});

/* 
   4. APPLICATION ERROR HANDLING 🚔
 */

/* 
   5. APPLICATION BOOT UP 🖥️
 */
app.on("ready", () => {
    app.listen(PORT, () => {
        console.log(`App running on port ${PORT}`);
    });
});
dbConnection.then(() => {
    console.log("---Database is connected !!---");
    app.emit("ready");
});

Note: The file index.js has commented sections that are numbered. Each section will have its logic added in other parts of the series.

In the snippet above, we have imported dotenv at the very top to load variables from .env file into the environment of the Operating System as early as possible.

On the 5th section, we connect to the database and once successfully connected, we emit app's "ready" event that will inturn launch our application listening on a Tcp PORT.

Therefore our Nodejs Server will start listening for requests after we are certain a successful database connection has been established.

We can test to see our app running on PORT. Open terminal at the server root and run:

npm run dev

If successful, you should see a terminal output like this:

Output of npm run dev command

Open your browser and browse to http://localhost:8000/ to send first request to server. And...🫰, you should see TEST ROUTE has responded:

TEST ROUTE response

So we can draw a conclusion that we connected to our database and server then started listening on TCP port. You can mess with the MongoDB connection string to see how err influences what happens next.

Conclusion

Well that is how you can perform database integration in NodeJs application. Mongoose is a promise-based Object Document Mapper(ODM). It let's us connect and run database operation on MongoDB using an object-oriented paradigm. We have approached database integration in a maintainable fashion. You can change to a different database flavour using another promise-based ORM/ODM, while having little to refactor on the entry file. Also the logic that connects to a database is placed in a separate module that contains everything necessary to execute one functionality i.e connecting to a database.

MongoDB has "almost" zero data validation. A database is mostly useful if it has some data validation, at least when we want to work with structured data. Using an ODM like mongoose will help to validate data before we put it in the DB e.g enforcing column types. MySQL is quite a legendary with a legion of in-built data validation. Nonetheless generally ORM/ODM help working with database a bit easier with its abstraction layer. Hence simplifies development.

So this is how we connect to database in this series. Check out the next part where we learn how to win at CORS battleground. Yes, how to fix that irritating CORS error.

You wanna say something? Light up💡 the comment section 🕳🤾.

Thanks for reading. Let's connect @twitter. You may want to be part of the ideas I share.

3-tier authentication - understand and conceptualize📸🤯 the process

Smitter — Mon, 06 Mar 2023 06:00:00 +0000

Welcome to part 1. Follow along this series to develop a feature-packed 3-tier Authentication System outlined in successive parts.

Summary: In this article, we explore token-based authentication process in a three-tier web architecture plus the bare minimum security practices to emulate.

Table of Contents

Intro
What is this tier thing?
Authentication in three-tier architecture
How it works
- Log in
- Accessing protected resources
- Refreshing Access Token
Security practices
Run down

Intro

User authentication and authorization are core information security processes in building secure systems. Authentication verifies the identity of a user or service before they can proceed to access protected resources. Authorization determines what access level is required to access protected resources, even after you are authenticated.

Modern software is built in parts, a design commonly reffered to as N-tier web architecture. Also called Multi-tier architecture. A common form of N-tier architecture is the Three-tier architecture. The name N-tier is coined because systems do not have to be restricted to three tiers, for example. As complexity increases, it is common to have more tiers.

What is this tier thing?

I hope my guess is right. You may be wondering what is a tier?

Well, probably you have heard of MERN if not MEAN, MEVN, ... These are just a combination of technologies(that somehow became popular). What is not coming out clearly is that we have layers when building software systems. Infact, we are reffering to tiers...not layers.

For instance, let us elaborate using the MERN stack.

You have a front-end built using Reactjs. A combination of Nodejs and Expressjs to build a backend that is using MongoDB as database storage. Typically your architecture here is a Three-tier architecture with the following tiers:

Presentation tier - The UI/front-end. (Reactjs)
Application tier - Also called the logic tier or middle tier. Where business logic for your app lies. (Node/Express)
Data tier - Sometimes called database tier. Where information processed in the application tier is stored/managed. (MongoDB)

You should see that tier is like a layer. But it is called a tier because: "layer" is only a functional division of software, while a "tier" refers to a functional division of a software that runs on infrastructure separate from the other divisions. For example MongoDB runs on a separate infrastructure from Node/Express.

Authentication in three-tier architecture

Whether you want to increase your internal security, improve consumer acquisition or provide a better user experience for your site visitors, it's essential to know how user authentication fits into the equation.

It's fairly easy to get the ball rolling using bold tech-stacks like MERN. An outright challenge is the topic of authentication. It can be daunting to put together authentication for such a project; considering that it has parts running in separate infrastructure yet they have to work together to achieve a common goal. Moreso being unopinionated.

A bullet-proof authentication is critical about incorporating best secure practices regularly replacing the phased-out ones. This gives a solid reason one may opt for authentication providers e.g Auth0, Cognito, Firebase Auth, who have specialized in the authentication domain to fast-track security vulnerabilities.

However, there are justifiable reasons to implement your own Authentication, for example:

You want to know how authentication works(not only using it).
You want user data to remain within your application.
You want a bespoke authentication solution that integrates with infrastructure component that is unique to your bussiness.
Your application has a low-security risk.
You want to avoid/reduce vendor licensing fees.
You do not want to induce points of failure with less control over it when you should be able to deal with such issues.
If the third party service at the core of your architecture decided to shut you down or compete with you or shut down themselves, then you become grounded.
Not all users are comfortable with trusting a third party in order to use your application.

In this article we are considering a bespoke Authentication solution. We articulate a conceptual flow of a typical authentication process.

The type of authentication conceptualized here is Token-based authentication using Json Web Tokens. This is a popular authentication protocol between Single Page Applications(SPAs) and REST APIs.

How it works

In Token-based authentication, the server application generates authentication tokens, i.e access token and refresh token pair after login credentials have been successfully verified. Then clients requesting to protected resources on the server are required to include access token in every HTTP request.

Access token: Is a Json Web Token issued to a correctly logged-in user. It contains insensitive user information embedded in it. This token needs to be provided when accessing a protected resource on the server.

Refresh token: Is a Json Web Token also issued after successful login. HTTP request may need to get a new access token since a server will reject an access token that is expired/invalid. A refresh token needs to be included on such a request before the server can process it to provide a new access token.

We'll look at the following processes in a Token-based authentication:

Log in
Accesing protected resource
Refreshing access token

Let's reflect on the login process.

Log In

Below is a visualization of a login flow.

In a nutshell, the purpose of login is to request to be authenticated, facilitated by an access token being sent back after successful login verification. This token is what you need in every HTTP request to gain access on protected resources on the server. Including a valid access token renders a HTTP request as authenticated.

The flow of login control would be like:

The client submits "username" and "password" to the server.
The server receives login credentials and verifies them against a database.
Once a match is found, signed access & refresh tokens are generated. These tokens are embedded with insensitive information from the match found.
The server returns a response including the access token and refresh token.

Note: In the visual illustration above, access token is returned in the response body while refresh token is returned in the response header. The assumption is that the client is in browser environment and refresh token is set onto the HTTP only cookie to help with secure storage of the credentials(access & refresh token) from the client-side.

Accessing protected resources

Probably we have already stressed that accessing a protected resource on the server requires that you provide an access token sent along with the HTTP request. Like shown below:

Protected Resource Access flow

To access a protected resource, the flow would be:

Client attaches access token on Authorization header of a HTTP request.
Server checks for the credential(access token) in the Authorization header.
Validation and verification is run on the access token.
Once successfully verified, server allows protected resource to be served.

A step that fails will make the server to respond with an unauthenticated error commonly depicted with a 401 HTTP status code.

Refreshing Access Token

We have not talked much about refresh token. It is a big player when we want to refresh/renew access token. The rule of the thumb about Token-based authentication is that generated token pair should expire. Access token should have the shorter time to expiry than refresh token.

Without a refresh token, a user would be interrupted to "log in" again with username/password to obtain a new access token whenever the current one becomes invalid or expired. That rude interruption is an annoying experience to a user considering that access token is short-lived.

With a refresh token, client can obtain a new access token without another manual "log in". And for a better user experience, a client will automatically obtain a NEW access token in the background whenever a server rejects the access token in HTTP request because it is invalid or expired. The rejected request can then be retried with the NEW access token. All these is automated by a client without a user's intervention.

This process is as visualized below:

Refresh Access token overview

Procedurally:

A client includes access token in Authorization header of HTTP request.
This is a protected resource, so the server checks for access token in Authorization header.
Server authenticates the request and detects access token is expired(or invalid).
Server ends the request with an unauthenticated error response.
Client detects that the request failed due to unauthentication.
Client triggers a HTTP request to renew access token and includes refresh token in cookie header.
Server verifies the refresh token.
Once refresh token is verified, a NEW access token is generated and returned in response body.
Client receives the NEW access token.
Client uses the NEW access token to retry the initial request that had failed with an unauthenticated error.

Note: Maximum retries should be implemented on the client-side to avoid an infinite loop.

Security practices

The stateless principle of Token-based authentication is advantagious to give your application the performance boost you just needed. This is because there is no database look-ups when authenticating requests. Access tokens are stored on the client-side. Same is the case for refresh tokens.

However since these tokens are as sensitive as "passwords", they need to be stored securely from the client-side. You should consider implementing the following best practices:

Do not embed sensitive data in the tokens.
Give tokens an expiration.
Access tokens should be short-lived(within minutes). While maintaining the stateless characteristic, access tokens do not have a way to be revoked. A short life span will allow for minimal duration of usage incase an access token lands in the hands of "evil" user.
Refresh tokens should be revocable. Since there is no way to revoke access tokens, then at least refresh tokens should. If a refresh token is reported as leaked, the token can be revoked such that refresh requests using the revoked refresh token will fail. Possibly you could think of an evil user using a stolen access token and next time they want to renew the token, the server will lock them out.
Incase client is in a browser environment, refresh tokens could be stored in HTTP-only cookie and access token kept in-memory without persisting anywhere.

Run down

We have discussed the process of authentication and the steps involved in a typical "Three-tier web architecture". To quickly recap, we have discussed the following:

Modern software is built in parts with different infrastructure(tiers).
Token-based authentication is common among N-tier architectured applications.
Login is a request to get authentication tokens.
Access token and refresh token are issued after successful login.
Authentication tokens issued are stored in the client-side. And they should be stored securely.
Requests to protected resources on the server need to include access token e.g in Authorization header.
Refresh token is used to renew access token.

And that's a wrap. Thanks for reading this far. Are you one that wants the concepts shared here translated into working solution? If it sounds like you, this series just serves you right. Check ou the next parts.

Something is not clear enough? Don't hesitate to bomb💣 the comment section👇️. The explosion effect can clear your mysteries. Also reach out @twitter. I'll be happy to help 😊.

DEV Community: Smitter

Building my portfolio like it's infinity gauntlet

About Me

Portfolio

How I Built It

The Stack & Tools

Design Decisions

The AI Assistant

What I'm Most Proud Of

1. Successful GCP Deployment

2. The 3D Interactive Experience

3. Fully responsive design

4. Solving Problems (The RLI Library)

I built Zeet. A Git-like version Control System

🚀 Source Code

🎬 DEMO

Motivation

How Zeet Works

Features of Zeet

🛠️ What Zeet Can Do

🛑 What Zeet Cannot Do (Yet)

How to use Zeet

Core Commands

Final toughts

Git things right🟢✔️ using rebase workflow in a software team

Scenario

Merging policy

The problem with Git merge workflow

Git rebase workflow for a linear commit history

Should you use a Git rebase workflow?

Final words

SmitterFollow

13 CSS Tricks that will give you an adrenaline rush🤯

Draw a triangle using border

Interchange background of an element

Center an element

Pill 💊 shape button

Easily add beautiful loading indicator to your website

Easy dark or light mode

Truncate overflowing text with an ellipsis(...)

Truncate long text to a number of lines

Stop overworking yourself writing top, right, bottom, left

Serve optimized images

Counters

Form validation visual cues

Select text with one click

SmitterFollow

Uncanny visual symbols of a git conflict explained

What these symbols mean

How to calculate CSS specificity of your style rules

Visual definition of CSS terms

The 3-column value

Specificity comparison

Selectors that add no weight to specificity calculation

Example

Excercise

A Column number that is greater than 9

Equivalent weights

Conclusion

Build a Robust JWT Auth System in Node.js: Access and Refresh Token Strategy

The Common Misconception

Getting Started

Project Dependencies

What we will do

Directory structure

Declare environment variables

Create User database model

Add email service

Create validators

Create authentication middleware

Create controller functions

Create application routes

Register routes

Conclusion

The history of HTTPS

SSL developments

Birth and timeline of TLS

Deftly🦅 Handle exceptions in Node/Express Application

Directory structure

1. Create custom error constructors

Truncate overflowing text with an ellipsis(`...`)

Stop overworking yourself writing `top`, `right`, `bottom`, `left`

A Column number that is greater than `9`

Create `User` database model

Create `package.json`

Create `.env` file