OAuth

The IAM service accepts OAuth social login through POST /auth/OAuth/:providerName. Providers are registered in the providers array in configuration(). Each entry defines how the incoming OAuth profile is validated and mapped to the internal user schema. The service handles user creation for first-time OAuth users and token issuance for returning users, but it does not perform the OAuth authorization code exchange itself.

Route

Middleware chain:

validateContentType('application/json'), express.json({ limit: '4kb' }), canary_id check, OAuthHandler

The body limit is 4 KB (compared to 1 KB for login and signup) to accommodate the larger profile payloads returned by some OAuth providers. The canary_id cookie must be present, as it is required to look up or create the visitor record that links the user to the Bot Detector fingerprint.

See Routes for how to mount the authentication router.

Registering a provider

Providers are defined in the providers array when calling configuration(). There are two ways to define a provider: with a custom Zod schema, or with a field-type map.

Option 1: Custom Zod schema

Use a full Zod schema when you need fine-grained validation of the provider's profile response.

import { configuration } from '@riavzon/auth'
import { z } from 'zod'

configuration({
  providers: [
    {
      name: 'google',
      schema: z.object({
        sub: z.string(),
        email: z.string().email(),
        name: z.string().optional(),
        picture: z.string().url().optional(),
        email_verified: z.boolean().optional(),
      }),
    },
  ],
  // ...
})

Option 2: Field-type map

Use fields for a simpler definition when the provider returns a flat profile object with predictable types. This approach is useful for JSON-based configuration files where Zod schemas cannot be serialized. Append ? to any type to mark the field optional.

configuration({
  providers: [
    {
      name: 'github',
      useStandardProfile: true,
      fields: {
        id: 'int',
        email: 'email',
        name: 'string?',
        avatar_url: 'url?',
        login: 'safeString?',
      },
    },
  ],
})

When using fields, the service builds a Zod schema from the field-type tokens at startup. The generated schema is functionally identical to a hand-written Zod schema.

Available field types

Standard profile mapping

When useStandardProfile: true is set on a provider (or when using a custom schema that includes standard field names), the service automatically maps provider-specific field names to the internal StandardProfile interface after validation.

email is required regardless of the mapping. The service rejects profiles that do not include a valid email address. At least one of sub, id, or user_id must also be present. The schema enforces this with a Zod .refine() check.

StandardProfile interface

interface StandardProfile {
  sub?: string | number
  id?: string | number
  user_id?: string | number
  email: string
  email_verified?: boolean
  name?: string
  given_name?: string
  family_name?: string
  last_name?: string
  avatar?: URL
  locale?: any
  location?: any
}

The avatar field is resolved from whichever profile key is present, checking in order: picture, picture_url, avatar, avatar_url. Only HTTPS URLs are accepted.

The authentication pipeline

New users

When findUserByProvider returns no match, the controller calls createOauthUser(canary_id, mappedProfile, providerName). This function:

Returning users

When findUserByProvider finds an existing user row matching the provider and subject ID, the function generates a new refresh token and access token for that user without creating a new row.

Device trust

If trustUserDeviceOnAuth is true in the configuration and the Bot Detector assigned a new visitor_id for this request, the controller calls trustVisitor() to:

1. Update the user's visitor_id foreign key to point at the visitor row for the current canary_id
2. Call updateVisitors() from the Bot Detector to overwrite the fingerprint fields with the current request's geo and UA data
3. Regenerate the access token with the new visitor_id

This re-baselines the fingerprint so that the anomaly detection engine compares future requests against the device the user most recently authenticated from. This is the same device-trust logic that runs during login.

Response

Success (201)

{
  "ok": true,
  "receivedAt": "2025-01-15T10:30:00.000Z",
  "accessToken": "<signed JWT>",
  "accessIat": "1705312200000"
}

Two cookies are set alongside the JSON response:

Error responses

The OAuth request

The client calls POST /auth/OAuth/:providerName with the profile data in the JSON body. The :providerName parameter must exactly match the name registered in configuration().

// Client-side example (after exchanging the OAuth code for a profile)
await fetch('/auth/OAuth/google', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(googleProfile),
})

Body extraction

The controller extracts the profile from the request body using a fallback chain:

1. req.body.userInfo (used by some OAuth client libraries)
2. req.body.user (common in wrapper formats)
3. req.body (raw profile at the top level)

This flexibility allows different OAuth client implementations to send the profile in whichever wrapper format they use.

Library exports

When using the IAM service as a library (not the standalone service), three OAuth-related functions are exported:

createOauthUser

Creates a new user from an OAuth profile. Call this in a custom OAuth handler when you want to control the flow.

import { createOauthUser } from '@riavzon/auth'

const result = await createOauthUser(
  req.cookies.canary_id,
  {
    email: profile.email,
    sub: profile.sub,
    name: profile.name,
    avatar: profile.picture,
  },
  'google'
)

if (result.duplicate) {
  // Email already registered
}

if (result.noCanaryCookie) {
  // No visitor record for the canary_id
}

if (result.success) {
  // result.accessToken and result.refreshToken are ready
}

findUserByOauthProvider

Looks up an existing user by provider name and provider subject ID without creating a new account.

import { findUserByOauthProvider } from '@riavzon/auth'

const result = await findUserByOauthProvider('google', googleProfile.sub)

if (result.user) {
  // result.id, result.visitor_id, result.accessToken, result.refreshToken
}

configureOauthProviders

Inspects or extends the registered provider list at runtime. Returns the array of configured provider definitions.

import { configureOauthProviders } from '@riavzon/auth'

const providers = configureOauthProviders()

Rate limiter reference

All OAuth rate limiters are configurable under rate_limiters in the configuration object. The defaults are:

Configuration reference

See Configuration for the full schema reference.