Database hooks

import { createTheAuth } from "@glinr/theauth";

const theauth = await createTheAuth({
  database: { provider: "sqlite", url: "theauth.db" },
  auth: { session: { secret: process.env.SESSION_SECRET! } },
  databaseHooks: {
    user: {
      create: {
        // Runs before the row is written.
        before: async (user) => {
          if (!user.email.endsWith("@example.com")) return false; // abort
          return { data: { name: user.name ?? "New user" } }; // replace fields
        },
        // Runs after the row is committed.
        after: async (user) => {
          await sendWelcomeEmail(user.email);
        },
      },
    },
    session: {
      create: {
        before: async (session) => ({
          data: { expiresAt: new Date(session.expiresAt.getTime() - 60_000) },
        }),
      },
    },
  },
});

​

What a hook can return

​

Where hooks fire

​

What does not fire hooks

• Bookkeeping. The idle activity stamp on a session, a pending OAuth row that has no user yet, the forcePasswordReset flag cleared by a completed password change, and revocation deletes.
• GDPR erasure. gdpr.deleteUser (and admin.deleteUser, which calls it) and the erasure marker and tombstone rows it writes. An erasure request has to complete, so a hook can neither veto it nor rewrite what it leaves behind. Hard deletes are not hook operations in any path, including a SCIM DELETE with autoDeactivateUsers off.
• Importers. theauth migrate and the importer stores insert and update users directly, in bulk, with the ids of the source system. They do not call hooks. If you need a check on imported users, run it over the table afterwards.
• Dev tooling. theauth dev and the demo server seed users directly.

​

Failure behavior

​

Single-use claims stay atomic

• A before hook runs ahead of the write it guards. If it aborts, nothing else was changed: a session before abort does not evict another session when maxConcurrent is set, and a refresh that is aborted leaves the old session usable.
• An after hook fires only for the caller that won. A refresh fires session.create.after once the old session has been claimed, so a refresh that loses the race fires nothing.
• A before hook that aborts a sign-up that already consumed a code (for example an OTP verify that creates the user) leaves that code consumed. The user retries with a new code. This is deliberate: the claim has to happen first so that only one caller can win, and putting the hook ahead of it would let a slow or hostile hook hold a code open for a second guess. Under concurrent verifies of one code, the hook runs once, for the caller that won the claim.
• A SCIM request or billing webhook stopped by a before hook changes nothing. SCIM answers 403. A Stripe or Polar webhook answers 500, so the provider retries the event until your hook lets it through.

​

Handling an abort

import { DatabaseHookError } from "@glinr/theauth";

try {
  await theauth.user.create({ email: "someone@other.test" });
} catch (err) {
  if (err instanceof DatabaseHookError && err.code === "DATABASE_HOOK_ABORTED") {
    // err.model is "user", err.operation is "create"
  }
}