Actions

exports.onExecutePostLogin = async (event, api) => {
  // event holds context about the current login.
  // api is how you affect the outcome.
}

exports.onExecutePostLogin = async (event, api) => {
  /* users */
}
exports.onExecuteClientCredentials = async (event, api) => {
  /* services */
}

event = {
  user: {
    user_id: string;
    email: string;
    email_verified: boolean;
    app_metadata: Record<string, unknown>;
    user_metadata: Record<string, unknown>;
    // …additional standard claims
  };
  client: { client_id: string; name: string };
  connection: { name: string; strategy: string };
  request: {
    ip: string;
    userAgent: string;
    // Raw Accept-Language header, e.g. "en-GB,en;q=0.9". Empty when absent.
    language: string;
    // Coarse device class parsed from the User-Agent.
    device: 'mobile' | 'desktop' | 'bot' | 'unknown';
    // true when `ip` belongs to a known datacenter / hosting / proxy range.
    ip_datacenter?: boolean;
    // How many of your currently-active blocks have seen this exact IP.
    ip_active_blocks?: number;
    // Same, widened to the IP's /24 (or /48 for IPv6). Only ever non-zero for
    // datacenter addresses, so it can never implicate a residential range.
    ip_network_active_blocks?: number;
  };
  stats: {
    // true when this login is the user's SIGNUP — the identity was created
    // by the same flow that triggered the action. Always false on `continue`
    // resumes, even if the original paused flow was a signup.
    is_new_user: boolean;
    // Age of the account in milliseconds. Undefined when it cannot be dated.
    account_age_ms?: number;
    // true when this login's primary language tag differs from the one seen
    // at the user's first login. Only ever true on a returning login.
    language_changed?: boolean;
    // How many times THIS action has already denied THIS user.
    deny_count?: number;
  };
};

api.access.deny(reason: string, opts?: {
  blockFor?: string | number   // '48h', '7d', or milliseconds
  code?: string                // short machine tag for your audit rows
  details?: Record<string, unknown>
})
  // Reject the login. Returns HTTP 401 to the client with the given reason.
  // No further actions in the chain run.
  //
  // With `blockFor`, the verdict is PERSISTED: further attempts by the same
  // user are denied for that long without re-running your code, and
  // `event.stats.deny_count` counts how often it has fired, so you can back
  // off progressively. `code` and `details` are audit-only — they land in the
  // log row, never in the message the user sees.
 
api.access.review(code: string, details?: Record<string, unknown>)
  // Let the login through, but flag it for a human. The user is unaffected;
  // the audit row is marked `review: true` with your code and details.
  //
  // Use it for rules that are worth noticing but not worth blocking on. A
  // rule you are not confident enough to enforce is still worth shipping
  // here — a flagged row you can review beats a rule you never deployed.
 
api.redirect.sendUserTo(url: string)
  // Pause the login flow and send the user's browser to `url`.
  // Faable persists state so the flow can resume via /continue once the
  // user returns.
 
api.accessToken.setCustomClaim(name: string, value: JsonValue)
api.idToken.setCustomClaim(name: string, value: JsonValue)
  // Add a custom claim to the access token / id_token this login mints.
  // Not a verdict: it composes with `review` and with a plain return. Claims
  // persist across refreshes (they travel inside the refresh token) until
  // the next login. A later `deny` discards them.
  //
  // Rules — an invalid call throws and fails the action (the login fails
  // with a reason; nothing is silently dropped):
  //   - name matches ^[A-Za-z0-9_.:/-]{1,128}$ — namespaced names such as
  //     `https://example.com/station_id` are the convention
  //   - name is not reserved: sub, iss, aud, exp, iat, nbf, jti, scope,
  //     permissions, teams, roles, client_id, azp, sid, auth_time, nonce
  //   - value is JSON-plain: string, number, boolean, null, or arrays /
  //     objects of those
  //   - at most 10 custom claims and 2 KB serialized per token

exports.onExecutePostLogin = async (event, api) => {
  if (!event.user.email_verified) {
    api.access.deny('Please verify your email before signing in.')
    return
  }
 
  const tosAccepted = event.user.app_metadata?.tos_accepted_at
  if (!tosAccepted) {
    api.redirect.sendUserTo('https://app.example.com/accept-tos')
  }
}

/**
 * @param {Event} event - The event object
 * @param {Api} api - The Faable Auth API object
 */
exports.onExecutePostLogin = async (event, api) => {
  // Only divert the user's very first login (their signup).
  if (event.stats.is_new_user) {
    api.redirect.sendUserTo('https://app.example.com/onboarding')
  }
}

// Runs on post-login
exports.onExecutePostLogin = async (event, api) => {
  const station = event.user.app_metadata?.station_id ?? 'unassigned'
  api.accessToken.setCustomClaim('https://example.com/station_id', station)
  api.idToken.setCustomClaim('https://example.com/station_id', station)
}
 
// Runs on client-credentials
// Clients carry no free-form metadata, so map them here (or fetch the
// mapping from your own config at deploy time).
const STATION_BY_CLIENT = {
  'aBcD1234…': 'station_madrid_centro',
  'eFgH5678…': 'station_valencia_norte'
}
exports.onExecuteClientCredentials = async (event, api) => {
  const station = STATION_BY_CLIENT[event.client.client_id]
  if (!station) {
    api.access.deny('This client has no station assigned', {
      code: 'station-missing'
    })
    return
  }
  api.accessToken.setCustomClaim('https://example.com/station_id', station)
}

// On your OAuth landing/callback page:
const params = new URLSearchParams(window.location.search)
if (params.get('signup') === 'true') {
  analytics.capture('user_signed_up') // your one-time conversion event
}