@hellocoop/api

This npm package is a TypeScript implementation of the Hellō Web Client API that is used by:

• @hellocoop/express
• @hellocoop/fastify
• @hellocoop/nextjs
• @hellocoop/cdk-client

Hellō Web Client API

The API is a single route, that by default is /api/hellocoop. Having a single route simplifies integration into an application. The endpoint handles the API as well as being the protocol endpoint for the OpenID Connect redirect_uri and third party initiated login.

The web client calls the API by passing the op query command set to one of the operations (auth|login|logout|invite)

router.ts routes the commands to the different modules

auth

Returns the auth object:

    {
        "isLoggedIn": false
    }

    {
        "isLoggedIn": true,
        "sub": "sub_vvCgtpv35lDgQpHtxmpvmnxK_2nZ",
        "iat": 1699234659,
        "name": "Dick Hardt",
        "picture": "https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png",
        "email": "[e-mail]"
    }

Implemented in auth.ts

login

The client loads /api/hellocoop?op=login to start a login flow.

Optional parameters described in Web Client API

This will:

1. discover the redirect_uri if not configured by bouncing a page to the browser to learn the full URL for the endpoint
2. generate a PKCE code_verifier and code_challenge
3. generate a nonce
4. encrypt and store the redirect_uri, code_verifier, and nonce in the hello_oidc cookie
5. create an authorization request and return a 302 redirect to that URL

Implemented in login.ts

logout

The client loads /api/hellocoop?op=logout to clear the auth cookie and log the user out.

Optional parameters described in Web Client API

Implemented in logout.ts

invite

The client loads /api/hellocoop?op=invite to start the invite flow.

See the Invite API for details.

Implemented in invite.ts

OpenID Connect Protocol

Authorization Response

The API endpoint is the redirect_uri and is where the user is redirected after interacting with their Hellō Wallet.

If a successful login at Hellō, the endpoint receives an authorization code query parameter (code). It then will:

1. retrieve and decrypt the redirect_uri, code_verifier, and nonce from the hello_oidc cookie
2. exchange the code, redirect_uri, code_verifier for the id_token at the Hellō token endpoint (`https://wallet.hello.coop/)
3. verify the id_token contains the nonce and perform standard id_token verification
4. call the loginSync function if configured
5. set the hellocoop_auth cookie
6. redirect the user to the target_uri

If the user is an administrator of the Hellō application and it is running at a dynamic endpoint and the wildcard_console parameter is returned, an intermediate page is generated by wildcard.ts and presented to the developer to simplify configuration of their application.

If the log in was unsuccessful or canceled, the endpoint receives an error query parameter and the user is redirected to an error page.

Implemented in callback.ts

Third Party Initiated Login

This allows a user to log in to an application by clicking a link in a dashboard or loading a bookmark. The endpoint is passed the iss query parameter, which must be the Hellō issuer, https://issuer.hello.coop. login_hint or domain_hint can optionally be provided.

Implemented in initiateLogin.ts