@gatekeepr/supabase

Gatekeepr helpers for Supabase Auth abuse protection.

The package is designed for the Supabase Auth before-user-created HTTP hook. It extracts the pending user's email and request IP, checks them with Gatekeepr, and returns the hook response Supabase expects.

Install

yarn add @gatekeepr/supabase

Supabase Edge Function

import { createBeforeUserCreatedHook } from "npm:@gatekeepr/[email protected]"

const handler = createBeforeUserCreatedHook({
	gatekeeprApiKey: Deno.env.get("GATEKEEPR_API_KEY"),
	hookSecret: Deno.env.get("SUPABASE_AUTH_HOOK_SECRET")
})

Deno.serve(handler)

Deploy the function without JWT verification, then configure it as a Supabase Auth before-user-created hook:

supabase functions deploy gatekeepr-before-user-created --no-verify-jwt

The hook secret should be the value generated by Supabase Auth Hooks. Values in the v1,whsec_... format are supported directly.

Decisions

By default, the hook rejects only Gatekeepr block decisions. Gatekeepr challenge decisions are allowed because Supabase's signup hook can only allow or reject the signup.

Reject both block and challenge decisions when you want a stricter signup gate:

const handler = createBeforeUserCreatedHook({
	gatekeeprApiKey: Deno.env.get("GATEKEEPR_API_KEY"),
	hookSecret: Deno.env.get("SUPABASE_AUTH_HOOK_SECRET"),
	rejectStatuses: ["block", "challenge"]
})

Customize the visible Supabase Auth error:

const handler = createBeforeUserCreatedHook({
	gatekeeprApiKey: Deno.env.get("GATEKEEPR_API_KEY"),
	hookSecret: Deno.env.get("SUPABASE_AUTH_HOOK_SECRET"),
	blockMessage: (gatekeepr) => `Signup blocked: ${gatekeepr.threats.join(", ")}`
})

Lower-Level Usage

import {
	createGatekeeprClient,
	evaluateSupabaseAuthEvent
} from "@gatekeepr/supabase"

const client = createGatekeeprClient({
	apiKey: process.env.GATEKEEPR_API_KEY
})

const decision = await evaluateSupabaseAuthEvent(event, { client })

decision.supabase.body is {} when signup should proceed, or an error object when Supabase should reject the signup.