@hellocoop/cdk-client

A Hellō Client CDK Construct for a Lambda Function

Quickstart

npm install @hellocoop/cdk-client

import{HelloClientConstruct,Scope,ProviderHint}from'@hellocoop/cdk-client'// Create the Hello Client Lambda and functionUrlconsthelloClient=newHelloClientConstruct(this,'HelloClient',{clientID: CLIENT_ID,// required = your Hellō client_id from https://console.hello.coophostname: HOSTNAME,// recommended - public hostname // Optional parameters://cookieToken?: boolean;// - Set to true to enable if a cookie token is returned in the op=auth response// Must be true if using the authorizer for API Gateway - see belowloginSyncFunctionName?: string;// - Name of the lambda function to trigger on login - ARN is built from current region and accountloginSyncFunctionArn?: string;// - Full ARN of the lambda function to trigger on login - use if lambda is in another region or accountcommandSyncFunctionName?: string;// - Name of the lambda function to invoke on an OpenID Provider Command - ARN is built from current region and accountcommandSyncFunctionArn?: string;// - Full ARN of the lambda function to invoke on an OpenID Provider Command - use if lambda is in another region or accountcommandsSupported?: string[];// - OP Commands your commandSyncFunction supports, eg ['metadata', 'suspend', 'delete']// advertised in the metadata response; other commands are rejected with unsupported_commandproviderHints?: ProviderHint[];// - Override default providers to show to new users. See https://www.hello.dev/docs/apis/wallet/#provider_hintscopes?: Scope[];// - Override default array of scopes to request from the user. See https://www.hello.dev/docs/scopes/functionName?: string;// - Override default function name 'HelloClient'route?: string;// - Override default route (/api/hellocoop)sameSiteStrict?: boolean;// - Set to true to enable SameSite attribute to StrictlogDebug?: boolean;// - Set to true to enable debug logginghelloDomain?: string;// - Set to hello-beta.net to use the Hellō Beta service - note this is NOT stable!});// add Hello Client Lambda origin as a behavior to a Cloud Front Distributiondistribution.addBehavior(HELLO_API_ROUTE,neworigins.FunctionUrlOrigin(helloClient.functionUrl),{viewerProtocolPolicy: cf.ViewerProtocolPolicy.HTTPS_ONLY,allowedMethods: cf.AllowedMethods.ALLOW_ALL,cachePolicy: cf.CachePolicy.CACHING_DISABLED,originRequestPolicy: newcf.OriginRequestPolicy(this, 'hellocoop',{queryStringBehavior: cf.OriginRequestQueryStringBehavior.all(),cookieBehavior: cf.OriginRequestCookieBehavior.all(),}),});

loginSyncFunction

You provide this Lambda to be called on successful login. It is passed:

{
"token": "ey ... ID Token for independent verification ...",
"payload": {
"iss": "https://issuer.hello.coop",
"aud": "2000a054-aa09-45a3-9f62-26e03ee9dc76",
"nonce": "4a6fc9b2-0f47-4105-a367-b9ae0ca12784",
"jti": "jti_MUYT099WI3g0h7MDiRuVMhHA_c7g",
"sub": "66752aed-9cc2-4d17-875f-379b1a578f9a",
"name": "Dick Hardt",
"picture": "https://pictures.hello.coop/r/eebce734-44c0-4c39-8161-ba77e08091f9.jpeg",
"email": "dick.hardt@gmail.com",
"email_verified": true,
"iat": 1727210134,
"exp": 1727210434
}
}

You can then

• create a user if they don't exist
• run a policy and deny access
• change what is returned by auth
• change the path where the user will be redirected

All of the properties are optional:

{ "accessDenied": true, // will deny access"updatedAuth": { // will update what is returned by the auth operation"role":"admin"
},
"target_uri": "/new_location"// path to send user when complete
}

commandSyncFunction

You provide this Lambda to be called when Hellō sends your app an OpenID Provider Command (draft-02) — lifecycle commands such as suspend, delete, and invalidate that let you deprovision accounts when they change at Hellō.

The client Lambda's function URL is your app's command endpoint. The client Lambda verifies the command+jwt command token (signature via the OP's JWKS, typ, aud, issuer, expiry) and answers the metadata command itself, advertising your commandsSupported. Every other supported command is passed to your Lambda as the verified command token claims:

{
"iss": "https://issuer.hello.coop",
"aud": "https://app.example.com/api/hellocoop",
"client_id": "2000a054-aa09-45a3-9f62-26e03ee9dc76",
"command": "suspend",
"tenant": "personal",
"sub": "66752aed-9cc2-4d17-875f-379b1a578f9a",
"jti": "jti_MUYT099WI3g0h7MDiRuVMhHA_c7g",
"iat": 1727210134,
"exp": 1727210434
}

Your Lambda executes the command (e.g. suspends the user in your system) and returns the OPC Command Response, which is passed back to Hellō:

{
"sub": "66752aed-9cc2-4d17-875f-379b1a578f9a",
"account_state": "suspended"
}

Client Usage

See TBD for details

Login

/api/hellocoop?op=login

Logout

/api/hellocoop?op=logout

Get Auth

/api/hellocoop?op=auth

Sample

See client-sample-stack.ts in cdk-sample