Custom session fields

The customSession plugin lets you store application-specific data on a session without adding database columns. Fields live in session.metadata.custom, and you read and update them with the module or the REST endpoints below.

defaultFields and onSessionCreate are registered as a plugin onSessionCreate hook, but theAuth’s session managers and sign-in modules do not currently invoke plugin hooks. Creating a session through theauth.auth.session.create(...) does not populate metadata.custom by itself. Until that wiring exists, write the initial fields yourself with updateSessionFields right after you create the session.

Install

The plugin ships inside @glinr/theauth/auth, no extra packages needed.

Setup

import { createTheAuth } from '@glinr/theauth';
import { customSession } from '@glinr/theauth/auth';

const theauth = await createTheAuth({
  database: { provider: 'sqlite', url: 'theauth.db' },
  auth: {
    session: { secret: process.env.SESSION_SECRET! },
  },
  plugins: [
    customSession({
      // Merged into every session automatically
      defaultFields: { theme: 'system', beta: false },
      // Called once per session creation to compute dynamic fields
      onSessionCreate: async (userId) => ({
        createdAt: Date.now(),
        plan: await fetchUserPlan(userId),
      }),
    }),
  ],
});

Reading and writing fields

After setup, access the module through the plugin context (it is not a property of the instance):

import type { CustomSessionModule } from '@glinr/theauth/auth';

const mod = theauth.plugins.getContext().customSession as CustomSessionModule;

// Read custom fields (null when the session is missing or has none)
const fields = await mod.getSessionFields(session.id);
// => { theme: 'system', beta: false, createdAt: 1234567890, plan: 'pro' }

// Update fields on an existing session
await mod.updateSessionFields(session.id, { beta: true, lastPage: '/dashboard' });

updateSessionFields merges with existing data. Keys not in the update are left untouched. It throws when the session does not exist.

Hook behaviour

The plugin declares an onSessionCreate hook that merges defaultFields and the result of your onSessionCreate callback (callback wins on a key clash) into { custom: ... }. The hook is collected into the plugin registry, but theAuth does not call it when sessions are created today (see the warning above). Treat defaultFields and onSessionCreate as inert until it is wired up.

REST endpoints

Method	Path	Description
`GET`	`/auth/session/fields?sessionId=<id>`	Read custom fields for a session
`PATCH`	`/auth/session/fields`	Update custom fields on a session

GET example

GET /auth/session/fields?sessionId=sess_abc123

{ "fields": { "theme": "dark", "plan": "pro" } }

PATCH example

PATCH /auth/session/fields
Content-Type: application/json

{
  "sessionId": "sess_abc123",
  "fields": { "theme": "light" }
}

{ "updated": true }

Returns 404 when the session does not exist. Both endpoints require an authenticated user, but they do not check that the sessionId belongs to that user, so any signed-in caller who knows a session ID can read or change its custom fields. Treat session IDs as private, or put your own ownership check in front of these routes.

Config reference

interface CustomSessionConfig {
  defaultFields?: Record<string, unknown>;
  onSessionCreate?: (userId: string, request?: Request) => Promise<Record<string, unknown>>;
}

Option	Type	Description
`defaultFields`	`Record<string, unknown>`	Fields intended to be merged into every new session (see the warning above).
`onSessionCreate`	`async (userId, request?) => Record`	Async callback; return value is intended to be merged over `defaultFields`.

Storage

No migrations required. Custom data is stored in the metadata JSON column of theauth_sessions under the custom key. Existing metadata keys (such as those written by other plugins) are not affected.

Sessions

Core session model: cookie sessions, JWT tokens, and lifecycle management.

Additional fields

Attach custom columns to users instead of sessions.

Hooks

Lifecycle hooks you can attach to your instance.

Cookie options

Cookie attributes for cross-subdomain and production setups.

Compliance and security

Lifecycle

Identity primitives

Standards

Custom session fields

Install

Setup

Reading and writing fields

Hook behaviour

REST endpoints

GET example

PATCH example

Config reference

Storage

Sessions

Additional fields

Hooks

Cookie options

​Install

​Setup

​Reading and writing fields

​Hook behaviour

​REST endpoints

​GET example

​PATCH example

​Config reference

​Storage

​Related

Sessions

Additional fields

Hooks

Cookie options

Install

Setup

Reading and writing fields

Hook behaviour

REST endpoints

GET example

PATCH example

Config reference

Storage

Related