@iqauth/sdk 2.0.0

package/dist/server/handlers.d.mts

@@ -0,0 +1,96 @@
+/**
+ * Framework-neutral helper handlers for the auto-mounted routes added by the
+ * @iqauth/sdk framework adapters. Each handler takes the parsed request
+ * inputs and returns a structured response that the adapter renders into
+ * the framework's native Response object.
+ *
+ * Three routes are exposed:
+ *   POST /api/iqauth/callback  — exchange an OIDC authorization code for tokens
+ *                                and set the iqauth_at + iqauth_rt cookies.
+ *   POST /api/iqauth/refresh   — rotate the refresh-token cookie and return a
+ *                                fresh access token (cookie + JSON).
+ *   POST /api/iqauth/signout   — clear the auth cookies and best-effort revoke
+ *                                the session at the issuer.
+ *
+ * The handlers never mutate global state. They only return cookie + body
+ * directives; cookie writes are performed by the adapter using the host
+ * framework's cookie API. This keeps adapters trivially thin and makes the
+ * handlers pure-functionally testable.
+ */
+interface SetCookieDirective {
+    name: string;
+    value: string;
+    /** Empty string to clear. */
+    maxAge: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    path: string;
+    domain?: string;
+}
+interface HandlerResponse {
+    status: number;
+    body: Record<string, unknown>;
+    cookies: SetCookieDirective[];
+}
+interface IQAuthHelperConfig {
+    /** Required: pk_test_… or pk_live_… */
+    publishableKey: string;
+    /** Required for callback / refresh / signout against the issuer. */
+    secretKey?: string;
+    /**
+     * Override the issuer URL. Auto-discovered from the publishable key when
+     * omitted (the key encodes its own issuer host).
+     */
+    issuer?: string;
+    /** Override the access token cookie name. Defaults to `iqauth_at`. */
+    accessCookieName?: string;
+    /** Override the refresh token cookie name. Defaults to `iqauth_rt`. */
+    refreshCookieName?: string;
+    /** Cookie domain (e.g. `.example.com`). Defaults to host-only. */
+    cookieDomain?: string;
+    /** Cookie sameSite policy. Defaults to `lax`. */
+    sameSite?: "lax" | "strict" | "none";
+    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    secure?: boolean;
+    /** Cookie path. Defaults to `/`. */
+    cookiePath?: string;
+    /** Path of the OIDC token endpoint. */
+    tokenPath?: string;
+    /** Path of the auth refresh endpoint on the issuer. */
+    refreshPath?: string;
+    /** Path of the logout endpoint on the issuer. */
+    logoutPath?: string;
+    /** Optional fetch implementation override. */
+    fetchImpl?: typeof fetch;
+}
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl">> {
+    secretKey?: string;
+    cookieDomain?: string;
+    issuer: string;
+    fetchImpl: typeof fetch;
+    appId: string;
+    tenantId: string;
+}
+/**
+ * Serialize a cookie directive to a Set-Cookie header value. Adapters that
+ * lack a typed cookie API (Hono, raw Node) use this; Express / Fastify /
+ * Next prefer their native cookie setters.
+ */
+declare function serializeCookie(d: SetCookieDirective): string;
+/** POST /api/iqauth/callback — exchange an OIDC authorization code. */
+declare function handleCallback(config: IQAuthHelperConfig, input: {
+    code?: string;
+    codeVerifier?: string;
+    redirectUri?: string;
+}): Promise<HandlerResponse>;
+/** POST /api/iqauth/refresh — rotate refresh + access cookies. */
+declare function handleRefresh(config: IQAuthHelperConfig, input: {
+    refreshToken?: string;
+}): Promise<HandlerResponse>;
+/** POST /api/iqauth/signout — clear cookies and best-effort revoke at issuer. */
+declare function handleSignout(config: IQAuthHelperConfig, input: {
+    accessToken?: string;
+}): Promise<HandlerResponse>;
+
+export { type HandlerResponse, type IQAuthHelperConfig, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie };

package/dist/server/handlers.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Framework-neutral helper handlers for the auto-mounted routes added by the
+ * @iqauth/sdk framework adapters. Each handler takes the parsed request
+ * inputs and returns a structured response that the adapter renders into
+ * the framework's native Response object.
+ *
+ * Three routes are exposed:
+ *   POST /api/iqauth/callback  — exchange an OIDC authorization code for tokens
+ *                                and set the iqauth_at + iqauth_rt cookies.
+ *   POST /api/iqauth/refresh   — rotate the refresh-token cookie and return a
+ *                                fresh access token (cookie + JSON).
+ *   POST /api/iqauth/signout   — clear the auth cookies and best-effort revoke
+ *                                the session at the issuer.
+ *
+ * The handlers never mutate global state. They only return cookie + body
+ * directives; cookie writes are performed by the adapter using the host
+ * framework's cookie API. This keeps adapters trivially thin and makes the
+ * handlers pure-functionally testable.
+ */
+interface SetCookieDirective {
+    name: string;
+    value: string;
+    /** Empty string to clear. */
+    maxAge: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    path: string;
+    domain?: string;
+}
+interface HandlerResponse {
+    status: number;
+    body: Record<string, unknown>;
+    cookies: SetCookieDirective[];
+}
+interface IQAuthHelperConfig {
+    /** Required: pk_test_… or pk_live_… */
+    publishableKey: string;
+    /** Required for callback / refresh / signout against the issuer. */
+    secretKey?: string;
+    /**
+     * Override the issuer URL. Auto-discovered from the publishable key when
+     * omitted (the key encodes its own issuer host).
+     */
+    issuer?: string;
+    /** Override the access token cookie name. Defaults to `iqauth_at`. */
+    accessCookieName?: string;
+    /** Override the refresh token cookie name. Defaults to `iqauth_rt`. */
+    refreshCookieName?: string;
+    /** Cookie domain (e.g. `.example.com`). Defaults to host-only. */
+    cookieDomain?: string;
+    /** Cookie sameSite policy. Defaults to `lax`. */
+    sameSite?: "lax" | "strict" | "none";
+    /** Cookie secure flag. Defaults to true (set false for local http dev). */
+    secure?: boolean;
+    /** Cookie path. Defaults to `/`. */
+    cookiePath?: string;
+    /** Path of the OIDC token endpoint. */
+    tokenPath?: string;
+    /** Path of the auth refresh endpoint on the issuer. */
+    refreshPath?: string;
+    /** Path of the logout endpoint on the issuer. */
+    logoutPath?: string;
+    /** Optional fetch implementation override. */
+    fetchImpl?: typeof fetch;
+}
+interface ResolvedConfig extends Required<Omit<IQAuthHelperConfig, "secretKey" | "cookieDomain" | "issuer" | "fetchImpl">> {
+    secretKey?: string;
+    cookieDomain?: string;
+    issuer: string;
+    fetchImpl: typeof fetch;
+    appId: string;
+    tenantId: string;
+}
+/**
+ * Serialize a cookie directive to a Set-Cookie header value. Adapters that
+ * lack a typed cookie API (Hono, raw Node) use this; Express / Fastify /
+ * Next prefer their native cookie setters.
+ */
+declare function serializeCookie(d: SetCookieDirective): string;
+/** POST /api/iqauth/callback — exchange an OIDC authorization code. */
+declare function handleCallback(config: IQAuthHelperConfig, input: {
+    code?: string;
+    codeVerifier?: string;
+    redirectUri?: string;
+}): Promise<HandlerResponse>;
+/** POST /api/iqauth/refresh — rotate refresh + access cookies. */
+declare function handleRefresh(config: IQAuthHelperConfig, input: {
+    refreshToken?: string;
+}): Promise<HandlerResponse>;
+/** POST /api/iqauth/signout — clear cookies and best-effort revoke at issuer. */
+declare function handleSignout(config: IQAuthHelperConfig, input: {
+    accessToken?: string;
+}): Promise<HandlerResponse>;
+
+export { type HandlerResponse, type IQAuthHelperConfig, type ResolvedConfig as ResolvedIQAuthHelperConfig, type SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie };

package/dist/server/handlers.js

@@ -0,0 +1,243 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/handlers.ts
+var handlers_exports = {};
+__export(handlers_exports, {
+  handleCallback: () => handleCallback,
+  handleRefresh: () => handleRefresh,
+  handleSignout: () => handleSignout,
+  serializeCookie: () => serializeCookie
+});
+module.exports = __toCommonJS(handlers_exports);
+
+// src/publishableKey.ts
+function b64urlDecode(input) {
+  const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - input.length % 4);
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/") + pad;
+  if (typeof atob === "function") {
+    const bin = atob(normalized);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  const { Buffer: Buffer2 } = require("buffer");
+  return Buffer2.from(normalized, "base64").toString("utf8");
+}
+function parsePublishableKey(raw) {
+  if (typeof raw !== "string") return null;
+  const m = raw.match(/^pk_(test|live)_([A-Za-z0-9_-]+)$/);
+  if (!m) return null;
+  try {
+    const json = JSON.parse(b64urlDecode(m[2]));
+    if (!json || typeof json !== "object") return null;
+    if (typeof json.iss !== "string" || typeof json.appId !== "string" || typeof json.tenantId !== "string" || typeof json.kid !== "string") {
+      return null;
+    }
+    return { mode: m[1], iss: json.iss, appId: json.appId, tenantId: json.tenantId, kid: json.kid, raw };
+  } catch {
+    return null;
+  }
+}
+
+// src/server/handlers.ts
+var ACCESS_TOKEN_TTL_SECONDS = 60 * 15;
+var REFRESH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30;
+function resolve(config) {
+  const parsed = parsePublishableKey(config.publishableKey);
+  if (!parsed) {
+    throw new Error(
+      "@iqauth/sdk: invalid publishable key passed to iqAuth helpers (expected pk_test_\u2026 or pk_live_\u2026)"
+    );
+  }
+  const inferredIssuer = parsed.iss.startsWith("http") ? parsed.iss : `https://${parsed.iss}`;
+  return {
+    publishableKey: config.publishableKey,
+    secretKey: config.secretKey,
+    issuer: (config.issuer ?? inferredIssuer).replace(/\/+$/, ""),
+    accessCookieName: config.accessCookieName ?? "iqauth_at",
+    refreshCookieName: config.refreshCookieName ?? "iqauth_rt",
+    cookieDomain: config.cookieDomain,
+    sameSite: config.sameSite ?? "lax",
+    secure: config.secure ?? true,
+    cookiePath: config.cookiePath ?? "/",
+    tokenPath: config.tokenPath ?? "/oidc/token",
+    refreshPath: config.refreshPath ?? "/api/v1/auth/refresh",
+    logoutPath: config.logoutPath ?? "/api/v1/auth/logout",
+    fetchImpl: config.fetchImpl ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => {
+      throw new Error("global fetch is unavailable; pass fetchImpl");
+    })),
+    appId: parsed.appId,
+    tenantId: parsed.tenantId
+  };
+}
+function makeCookie(cfg, name, value, maxAge, httpOnly = true) {
+  return {
+    name,
+    value,
+    maxAge,
+    httpOnly,
+    secure: cfg.secure,
+    sameSite: cfg.sameSite,
+    path: cfg.cookiePath,
+    domain: cfg.cookieDomain
+  };
+}
+function clearCookies(cfg) {
+  return [
+    makeCookie(cfg, cfg.accessCookieName, "", 0),
+    makeCookie(cfg, cfg.refreshCookieName, "", 0)
+  ];
+}
+function serializeCookie(d) {
+  const parts = [`${d.name}=${encodeURIComponent(d.value)}`];
+  parts.push(`Path=${d.path}`);
+  if (d.domain) parts.push(`Domain=${d.domain}`);
+  parts.push(`Max-Age=${d.maxAge}`);
+  if (d.secure) parts.push("Secure");
+  if (d.httpOnly) parts.push("HttpOnly");
+  parts.push(`SameSite=${d.sameSite}`);
+  return parts.join("; ");
+}
+async function handleCallback(config, input) {
+  const cfg = resolve(config);
+  if (!input.code || !input.redirectUri) {
+    return {
+      status: 400,
+      body: { success: false, error: { code: "VALIDATION_ERROR", message: "code and redirectUri are required" } },
+      cookies: []
+    };
+  }
+  if (!cfg.secretKey) {
+    return {
+      status: 500,
+      body: { success: false, error: { code: "INTERNAL_ERROR", message: "secretKey is required for the callback handler" } },
+      cookies: []
+    };
+  }
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: input.code,
+    redirect_uri: input.redirectUri,
+    client_id: cfg.appId
+  });
+  if (input.codeVerifier) body.set("code_verifier", input.codeVerifier);
+  const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.tokenPath}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Authorization: `Basic ${typeof btoa === "function" ? btoa(`${cfg.appId}:${cfg.secretKey}`) : Buffer.from(`${cfg.appId}:${cfg.secretKey}`).toString("base64")}`
+    },
+    body: body.toString()
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || !json.access_token) {
+    return {
+      status: res.status || 502,
+      body: {
+        success: false,
+        error: {
+          code: json.error || "OIDC_EXCHANGE_FAILED",
+          message: json.error_description || "Authorization code exchange failed"
+        }
+      },
+      cookies: []
+    };
+  }
+  const cookies = [];
+  cookies.push(
+    makeCookie(cfg, cfg.accessCookieName, json.access_token, json.expires_in ?? ACCESS_TOKEN_TTL_SECONDS)
+  );
+  if (json.refresh_token) {
+    cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.refresh_token, REFRESH_TOKEN_TTL_SECONDS));
+  }
+  return {
+    status: 200,
+    body: { success: true, data: { authenticated: true } },
+    cookies
+  };
+}
+async function handleRefresh(config, input) {
+  const cfg = resolve(config);
+  const refreshToken = input.refreshToken;
+  if (!refreshToken) {
+    return {
+      status: 401,
+      body: { success: false, error: { code: "TOKEN_INVALID", message: "Missing refresh token" } },
+      cookies: clearCookies(cfg)
+    };
+  }
+  const res = await cfg.fetchImpl(`${cfg.issuer}${cfg.refreshPath}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ refreshToken })
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || !json.success || !json.data?.accessToken) {
+    return {
+      status: res.status || 401,
+      body: {
+        success: false,
+        error: {
+          code: json.error?.code || "TOKEN_INVALID",
+          message: json.error?.message || "Refresh failed"
+        }
+      },
+      cookies: clearCookies(cfg)
+    };
+  }
+  const cookies = [
+    makeCookie(cfg, cfg.accessCookieName, json.data.accessToken, ACCESS_TOKEN_TTL_SECONDS)
+  ];
+  if (json.data.refreshToken) {
+    cookies.push(makeCookie(cfg, cfg.refreshCookieName, json.data.refreshToken, REFRESH_TOKEN_TTL_SECONDS));
+  }
+  return {
+    status: 200,
+    body: { success: true, data: { accessToken: json.data.accessToken } },
+    cookies
+  };
+}
+async function handleSignout(config, input) {
+  const cfg = resolve(config);
+  if (input.accessToken) {
+    try {
+      await cfg.fetchImpl(`${cfg.issuer}${cfg.logoutPath}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${input.accessToken}`
+        }
+      });
+    } catch {
+    }
+  }
+  return {
+    status: 200,
+    body: { success: true, data: { signedOut: true } },
+    cookies: clearCookies(cfg)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleCallback,
+  handleRefresh,
+  handleSignout,
+  serializeCookie
+});

package/dist/server/handlers.mjs

@@ -0,0 +1,14 @@
+import {
+  handleCallback,
+  handleRefresh,
+  handleSignout,
+  serializeCookie
+} from "../chunk-5HF3OBNO.mjs";
+import "../chunk-5WFR6Y33.mjs";
+import "../chunk-Y6FXYEAI.mjs";
+export {
+  handleCallback,
+  handleRefresh,
+  handleSignout,
+  serializeCookie
+};

package/dist/server.d.mts

@@ -0,0 +1,14 @@
+import { b as IQAuthTokenClientConfig, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-Cxl3bQHt.mjs';
+import { I as IQAuthClient } from './client-C1DXfB8Z.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-CpfyYTmw.mjs';
+export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie } from './server/handlers.mjs';
+import 'jsonwebtoken';
+
+declare class ServerIQAuthClient extends IQAuthClient {
+    constructor(config: IQAuthTokenClientConfig);
+    middleware(options?: ExpressMiddlewareOptions): (req: IQAuthRequestLike, res: IQAuthResponseLike, next: IQAuthNextFunction) => Promise<void>;
+}
+declare function createServerClient(config: IQAuthTokenClientConfig): ServerIQAuthClient;
+
+export { ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, ServerIQAuthClient, createServerClient };

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { b as IQAuthTokenClientConfig, N as ExpressMiddlewareOptions, Q as IQAuthRequestLike, R as IQAuthResponseLike, V as IQAuthNextFunction } from './types-Cxl3bQHt.js';
+import { I as IQAuthClient } from './client-CggvJmmm.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
+export { C as CookieAwareMiddlewareOptions, D as DEFAULT_ACCESS_COOKIE, a as DEFAULT_REFRESH_COOKIE, i as iqAuthMiddleware } from './express-BKAXB5Nl.js';
+export { HandlerResponse, IQAuthHelperConfig, SetCookieDirective, handleCallback, handleRefresh, handleSignout, serializeCookie } from './server/handlers.js';
+import 'jsonwebtoken';
+
+declare class ServerIQAuthClient extends IQAuthClient {
+    constructor(config: IQAuthTokenClientConfig);
+    middleware(options?: ExpressMiddlewareOptions): (req: IQAuthRequestLike, res: IQAuthResponseLike, next: IQAuthNextFunction) => Promise<void>;
+}
+declare function createServerClient(config: IQAuthTokenClientConfig): ServerIQAuthClient;
+
+export { ExpressMiddlewareOptions, IQAuthClient, IQAuthTokenClientConfig, ServerIQAuthClient, createServerClient };