@hellocoop/api/README.md

Client API for Hellō https://hello.dev

# @hellocoop/api

This npm package is a TypeScript implementation of the Hellō Web Client API that is used by:
- [@hellocoop/express](https://www.npmjs.com/package/@hellocoop/express)
- [@hellocoop/fastify](https://www.npmjs.com/package/@hellocoop/fastify)
- [@hellocoop/nextjs](https://www.npmjs.com/package/@hellocoop/nextjs)
- [@hellocoop/cdk-client](https://www.npmjs.com/package/@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](src/handlers/router.ts) routes the commands to the different modules

### `auth` 

Returns the `auth` object:

```json
    {
        "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": "dick.hardt@hello.coop"
    }
```


Implemented in [auth.ts](src/handlers/auth.ts)

### `login`

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

Optional parameters described in [Web Client API](https://www.hello.dev/docs/apis/web-client/#login)

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
4. create an authorization request and return a 302 redirect to that URL

Implemented in [login.ts](src/handlers/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](https://www.hello.dev/docs/apis/web-client/#logout)

Implemented in [logout.ts](src/handlers/logout.ts)


### `invite`

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

See the [Invite API](https://www.hello.dev/docs/apis/invite/) for details.

Implemented in [invite.ts](src/handlers/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](src/handlers/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](src/handlers/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](src/handlers/initiateLogin.ts)