JavaScript / TypeScript Hooks

JavaScript / TypeScript Hooks is one of the supported hooks to receive events.

JavaScript / TypeScript Hooks are written as a ES2015 module. The module is executed by Deno.

The module MUST have a default export of a function taking 1 argument. The argument is the event. The function can either be synchronous or asynchronous.

If the Hook is registered for a blocking event, the function MUST return a value according to the specification.

The Hooks DO NOT have access to files or the environment. They only have access to the external network.

The stdout and the stderr of the Hooks are both ignored. Your hooks MUST NOT assume anything about the arguments and the stdin of the module.

Configure JavaScript / TypeScript Hooks in your Authgear project

• In the portal, go to Advanced > Hooks.

• Add your JavaScript / TypeScript Hooks handler in Blocking Events and Non-Blocking Events, depending on which event you want to listen to.

• Click Save.

Examples

Here is an example of a Hook for a blocking event.

import { HookEvent, HookResponse } from "https://deno.land/x/[email protected]/mod.ts";
export default async function(e: HookEvent): Promise<HookResponse> {
  // This hook simply allows the operation, which is identical to no-op.
  return { is_allowed: true };
}

An example to mutate a JWT token

import {HookResponse, EventOIDCJWTPreCreate } from "https://deno.land/x/[email protected]/mod.ts";

export default async function(event: EventOIDCJWTPreCreate): Promise<HookResponse> {
  return { 
    is_allowed: true,
    mutations: {
      jwt:{
        payload:{
          ...event.payload.jwt.payload, //the original payload in the jwt
          "https://myapp.com": {
            "custom_field": "custom_value"
          }
        }
      }
    }
  };
}

Here is an example of a Hook for a non-blocking event.

import { HookEvent } from "https://deno.land/x/[email protected]/mod.ts";
export default async function(e: HookEvent): Promise<void> {
  // This hook does nothing, which is identical to no-op.
}

TypeScript Definition

https://deno.land/x/authgear_deno_hook is a TypeScript definition that aids you in writing a Hook. You can see the full definition at https://deno.land/x/authgear_deno_hook/mod.ts

If you are a Visual Studio Code user, you can set up your editor to take full advantage of the definition.

Alternatively, you can edit your hook and use the Deno CLI to typecheck.

$ deno check YOUR_HOOK.ts