hello.config.js

This file contains the configuration for the Express, Fastify, and Next.js SDKs. It is used by the hellocoop.js file that provides the Hellō endpoint.

A sample:

const loginSync = require('./path-to-your-callback-function')
const logoutSync = require('./path-to-your-logout-callback-function')
 
const config = {
    client_id: 'YOUR_CLIENT_ID',
    scope: ['openid','name','email'], // default - openid name email picture
    provider_hint: ['github'],         
    routes: {
        loggedIn:  '/dashboard', // defaults to '/'
        loggedOut: '/logout',    // defaults to '/'
        error:     '/error'      // defaults to built in error page
    },
    cookieDomain: '.example.com', // optional - enables auth cookies across subdomains
    sameSiteStrict: true, // optional - enables strict SameSite cookies
    cookieToken: false, // optional - include encrypted cookie in auth response
    logConfig: false, // optional - log configuration on startup
    apiRoute: '/api/hellocoop', // optional - custom API route path
    loginSync,  // (params: LoginSyncParams) => Promise<LoginSyncResponse>
                // defaults to undefined
    logoutSync, // (params: LogoutSyncParams) => Promise<LogoutSyncResponse>
}
module.exports = config

client_id

• required unless provided by a the HELLO_CLIENT_ID environment variable

scope

• override default scope request (openid name email picture), see Hellō Scopes for options

provider_hint

• override providers recommended to users, see API Reference | provider_hint

routes

• override routes to redirect user on log in, log out, and error

cookieDomain

• optional domain for auth cookies (e.g., .example.com for subdomains). Enables authentication cookies to work across all subdomains. If not set, cookies are restricted to the current host only. Can also be set via HELLO_COOKIE_DOMAIN environment variable.

sameSiteStrict

• optional boolean to enable strict SameSite cookies for enhanced security. Can also be set via HELLO_SAME_SITE_STRICT environment variable.

cookieToken

• optional boolean to include encrypted cookie in auth response. Can also be set via HELLO_COOKIE_TOKEN environment variable.

logConfig

• optional boolean to log configuration details on startup for debugging.

apiRoute

• optional custom API route path (default: /api/hellocoop). Can also be set via HELLO_API_ROUTE environment variable.

loginSync

• optional function called on each successful login

logoutSync

• optional function called on logout

Here is how your loginSync function will be called if provided:

const {accessDenied, target_uri, updatedAuth} = await loginSync( { token, payload, target_uri, req, res } )

Parameters:

• token - the ID Token in compact format
• payload - the full payload of the ID Token
• target_uri - the original target URI from the login request
• req - Express/Fastify request object
• res - Express/Fastify response object

Return values:

• accessDenied - optional boolean returned if the user should not be logged in
• target_uri - optional URL to override where to redirect the user
• updatedAuth - an optional object that will extend the auth object stored in the encrypted cookie. Use this to set roles or groups or other app specific user properties you want readily available. You cannot change the iat, sub, or isLoggedIn values

Request/Response methods:

• req.headers - returns the request headers
• res.setHeader( name, value | [value] ) - will set a response header
• res.setCookie( name, value, options ) - will set a cookie value with options per cookie (opens in a new tab) serialize

Here is how your logoutSync function will be called if provided:

await logoutSync( { req, res } )

Parameters:

• req - Express/Fastify request object
• res - Express/Fastify response object

Request/Response methods:

• req.headers - returns the request headers
• res.setHeader( name, value | [value] ) - will set a response header
• res.setCookie( name, value, options ) - will set a cookie value with options per cookie (opens in a new tab) serialize

Configuration Validation

The SDK validates your configuration on startup and will log errors for:

• Missing client_id or HELLO_CLIENT_ID
• Missing HELLO_COOKIE_SECRET
• Invalid HELLO_COOKIE_SECRET format (must be 32 hex characters)
• Invalid route paths (must start with /)

TypeScript Support

For TypeScript projects, you can import the configuration types:

import type { Config } from '@hellocoop/express'
 
const config: Config = {
    client_id: 'your-client-id',
    scope: ['openid', 'name', 'email'],
    // ... other options
}