Express SDK

Setup

Following are the steps required to setup this package:

1. Package Installation

npm i @hellocoop/express

Hellō Quickstart will perform steps 2 - 4 for you

npx @hellocoop/quickstart@latest --nextjs

2. HELLO_COOKIE_SECRET

The environment variable HELLO_COOKIE_SECRET must be set to 64 char (32 byte) random hex string is required to encrypt cookies used by this package. This can be in .env for local development.

You can generate new values with:

node -e "console.log(crypto.randomBytes(32).toString('hex'))"

Remember to set a unique HELLO_COOKIE_SECRET in each of your deployed environments.

See Environment Vars for additional values that can be set.

The .env file should not be checked into your repository, and should be in your .gitignore file.

3. client_id

If your did not use Hellō Quickstart, you will need to create an application at the Hellō Developer Console (opens in a new tab) and get a client_id.

4. hello.config.js

The convention is to create a hello.config.js file in the root of your project for configuration. This file is imported into the hellocoop.js file and passed to the pageAuth() function for configuration. Below is a basic configuration file. See hello.config.js for additional configuration.

const config = {
    client_id: 'your-client_id-here'
}
module.exports = config

This file should be checked into your repository.

See hello.config.js for additional configuration.

5. API Route

In your main server file add the following code:

helloAuth() will add the /api/hellocoop endpoint which will process the Hellō authorization response, and the Web Client login, logout, and auth operations.

Your server should now be fully configured to work with Hellõ.

API

helloAuth()

Configures the SDK and adds the /api/hellocoop route. See 5. Api Route for usage.

req.getAuth()

Decrypts the hellocoop_auth cookie, sets auth to the value, and returns the result. If no cookie, sets auth to:

isLoggedIn: false

req.auth

Returns the auth object if req.getAuth() has been called, or setAuth Middleware has been processed. Here is an example with the default scopes:

isLoggedIn: true,
sub: 'sub_vvCgtpv35lDgQpHtxmpvmnxK_2nZ',
iat: '1699234659',
name: 'Dick Hardt',
picture: 'https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png',
email: 'dick.hardt@hello.coop'

res.logout()

Clears the hellocoop_auth cookie.

Middleware

import { redirect, unauthorized, setAuth } from '@hellocoop/express/middleware'

redirect()

Will redirect to the passed path if isLoggedIn=false.

Example:

app.get('/dashboard', redirect('/'), dashboard)`

unauthorized

Will return a 401 status code if isLoggedIn=false

Example:

app.use('/api', unauthorized )

Would return a 401 for any unauthenticated call to /api/*.

setAuth

Middleware that reads and decrypts the hellocoop_auth cookie and sets req.auth.

Example:

app.use('/profiles', setAuth )

Would set req.auth for all profile pages.