@incorta/auth 1.5.0 → 1.7.0

package/dist/express.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/express.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport type { AuthSession, IncortaAuth } from \"./index.js\";\nimport { toNodeHandler, toWebRequest } from \"./node.js\";\n\nexport type { AuthSession, IncortaAuth } from \"./index.js\";\n\n/**\n * Minimal structural types so this adapter works with Express 4/5 (and\n * anything Connect-compatible) without depending on Express itself.\n */\nexport interface AuthedRequest extends IncomingMessage {\n  originalUrl?: string;\n  /** Populated by `incortaAuth()`: the current session, or null when signed out. */\n  incortaAuth?: AuthSession | null;\n}\ntype NextFunction = (err?: unknown) => void;\ntype Middleware = (\n  req: AuthedRequest,\n  res: ServerResponse,\n  next: NextFunction,\n) => void | Promise<void>;\n\n/**\n * Express/Connect middleware that serves the auth routes (under\n * `auth.config.basePath`) and attaches the current session to every other\n * request as `req.incortaAuth`.\n *\n * ```ts\n * const auth = createIncortaAuth();\n * app.use(incortaAuth(auth));\n * app.get(\"/api/me\", requireAuth(auth), (req, res) => res.json(req.incortaAuth.user));\n * ```\n */\nexport function incortaAuth(auth: IncortaAuth): Middleware {\n  const nodeHandler = toNodeHandler(auth);\n  const { basePath } = auth.config;\n\n  return async (req, res, next) => {\n    try {\n      const path = (req.originalUrl ?? req.url ?? \"/\").split(\"?\")[0];\n      if (path === basePath || path.startsWith(`${basePath}/`)) {\n        await nodeHandler(req, res);\n        return;\n      }\n      req.incortaAuth = await auth.getSession(await toWebRequest(req));\n      next();\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\nexport interface RequireAuthOptions {\n  /**\n   * How to reject unauthenticated requests:\n   * - `\"redirect\"`: 302 to the login route (which bounces through Incorta login\n   *   and back to the original URL) — right for page routes.\n   * - `\"json\"`: 401 `{ error: \"unauthenticated\" }` — right for API routes.\n   * - `\"auto\"` (default): redirect when the request accepts text/html, 401 otherwise.\n   */\n  unauthenticated?: \"redirect\" | \"json\" | \"auto\";\n}\n\n/** Guards a route: only signed-in Incorta users get through. */\nexport function requireAuth(auth: IncortaAuth, options: RequireAuthOptions = {}): Middleware {\n  const mode = options.unauthenticated ?? \"auto\";\n  const { basePath } = auth.config;\n\n  return async (req, res, next) => {\n    try {\n      if (req.incortaAuth === undefined) {\n        req.incortaAuth = await auth.getSession(await toWebRequest(req));\n      }\n      if (req.incortaAuth) {\n        next();\n        return;\n      }\n\n      const wantsHtml = (req.headers.accept ?? \"\").includes(\"text/html\");\n      if (mode === \"redirect\" || (mode === \"auto\" && wantsHtml)) {\n        const returnTo = req.originalUrl ?? req.url ?? \"/\";\n        res.statusCode = 302;\n        res.setHeader(\n          \"location\",\n          `${basePath}/login?redirect_to=${encodeURIComponent(returnTo)}`,\n        );\n        res.end();\n        return;\n      }\n\n      res.statusCode = 401;\n      res.setHeader(\"content-type\", \"application/json; charset=utf-8\");\n      res.end(JSON.stringify({ error: \"unauthenticated\" }));\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n"],"mappings":";;;;;;AAiCO,SAAS,YAAY,MAA+B;AACzD,QAAM,cAAc,cAAc,IAAI;AACtC,QAAM,EAAE,SAAS,IAAI,KAAK;AAE1B,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,YAAM,QAAQ,IAAI,eAAe,IAAI,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AAC7D,UAAI,SAAS,YAAY,KAAK,WAAW,GAAG,QAAQ,GAAG,GAAG;AACxD,cAAM,YAAY,KAAK,GAAG;AAC1B;AAAA,MACF;AACA,UAAI,cAAc,MAAM,KAAK,WAAW,MAAM,aAAa,GAAG,CAAC;AAC/D,WAAK;AAAA,IACP,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;AAcO,SAAS,YAAY,MAAmB,UAA8B,CAAC,GAAe;AAC3F,QAAM,OAAO,QAAQ,mBAAmB;AACxC,QAAM,EAAE,SAAS,IAAI,KAAK;AAE1B,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,UAAI,IAAI,gBAAgB,QAAW;AACjC,YAAI,cAAc,MAAM,KAAK,WAAW,MAAM,aAAa,GAAG,CAAC;AAAA,MACjE;AACA,UAAI,IAAI,aAAa;AACnB,aAAK;AACL;AAAA,MACF;AAEA,YAAM,aAAa,IAAI,QAAQ,UAAU,IAAI,SAAS,WAAW;AACjE,UAAI,SAAS,cAAe,SAAS,UAAU,WAAY;AACzD,cAAM,WAAW,IAAI,eAAe,IAAI,OAAO;AAC/C,YAAI,aAAa;AACjB,YAAI;AAAA,UACF;AAAA,UACA,GAAG,QAAQ,sBAAsB,mBAAmB,QAAQ,CAAC;AAAA,QAC/D;AACA,YAAI,IAAI;AACR;AAAA,MACF;AAEA,UAAI,aAAa;AACjB,UAAI,UAAU,gBAAgB,iCAAiC;AAC/D,UAAI,IAAI,KAAK,UAAU,EAAE,OAAO,kBAAkB,CAAC,CAAC;AAAA,IACtD,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/express.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { AppAccessTokenRejectedError } from \"./core/app-access.js\";\nimport type { AuthSession, IncortaAuth } from \"./index.js\";\nimport { sendWebResponse, toNodeHandler, toWebRequest } from \"./node.js\";\n\nexport type { AppAccess, AppAccessPolicy, AuthSession, IncortaAuth } from \"./index.js\";\n\n/**\n * Minimal structural types so this adapter works with Express 4/5 (and\n * anything Connect-compatible) without depending on Express itself.\n */\nexport interface AuthedRequest extends IncomingMessage {\n  originalUrl?: string;\n  /** Populated by `incortaAuth()`: the current session, or null when signed out. */\n  incortaAuth?: AuthSession | null;\n}\ntype NextFunction = (err?: unknown) => void;\ntype Middleware = (\n  req: AuthedRequest,\n  res: ServerResponse,\n  next: NextFunction,\n) => void | Promise<void>;\n\n/**\n * Express/Connect middleware that serves the auth routes (under\n * `auth.config.basePath`) and attaches the current session to every other\n * request as `req.incortaAuth`.\n *\n * ```ts\n * const auth = createIncortaAuth();\n * app.use(incortaAuth(auth));\n * app.get(\"/api/me\", requireAuth(auth), (req, res) => res.json(req.incortaAuth.user));\n * ```\n */\nexport function incortaAuth(auth: IncortaAuth): Middleware {\n  const nodeHandler = toNodeHandler(auth);\n  const { basePath } = auth.config;\n\n  return async (req, res, next) => {\n    try {\n      const path = (req.originalUrl ?? req.url ?? \"/\").split(\"?\")[0];\n      if (path === basePath || path.startsWith(`${basePath}/`)) {\n        await nodeHandler(req, res);\n        return;\n      }\n      req.incortaAuth = await auth.getSession(await toWebRequest(req));\n      next();\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\nexport interface RequireAuthOptions {\n  /**\n   * How to reject unauthenticated requests:\n   * - `\"redirect\"`: 302 to the login route (which bounces through Incorta login\n   *   and back to the original URL) — right for page routes.\n   * - `\"json\"`: 401 `{ error: \"unauthenticated\" }` — right for API routes.\n   * - `\"auto\"` (default): redirect when the request accepts text/html, 401 otherwise.\n   */\n  unauthenticated?: \"redirect\" | \"json\" | \"auto\";\n}\n\n/**\n * Guards a route: only signed-in Incorta users get through — regardless of\n * the app's `appAccess` policy (an explicit `requireAuth` is the author's\n * promise that this route needs a user, so `\"public\"` mode does not neuter\n * it). Under the `\"catalog\"` policy the signed-in user must additionally\n * hold at least VIEW access to this app; the resolved verdict is attached as\n * `req.incortaAuth.appAccess`.\n */\nexport function requireAuth(auth: IncortaAuth, options: RequireAuthOptions = {}): Middleware {\n  const mode = options.unauthenticated ?? \"auto\";\n  const { basePath } = auth.config;\n\n  return async (req, res, next) => {\n    try {\n      if (req.incortaAuth === undefined) {\n        req.incortaAuth = await auth.getSession(await toWebRequest(req));\n      }\n      if (req.incortaAuth) {\n        if (auth.config.appAccess !== \"catalog\") {\n          next();\n          return;\n        }\n        const session = req.incortaAuth;\n        try {\n          const verdict = await auth.getAppAccess(session);\n          if (verdict.allowed) {\n            session.appAccess = verdict;\n            next();\n            return;\n          }\n          res.statusCode = 403;\n          res.setHeader(\"content-type\", \"application/json; charset=utf-8\");\n          res.end(JSON.stringify({ error: \"app_access_denied\" }));\n          return;\n        } catch (error) {\n          if (!(error instanceof AppAccessTokenRejectedError)) {\n            // Verdicts unavailable — NEVER fail open.\n            res.statusCode = 503;\n            res.setHeader(\"content-type\", \"application/json; charset=utf-8\");\n            res.setHeader(\"retry-after\", \"30\");\n            res.end(JSON.stringify({ error: \"app_access_unavailable\" }));\n            return;\n          }\n          // Incorta rejected the session's token — treat as signed out.\n          req.incortaAuth = null;\n        }\n      }\n\n      const wantsHtml = (req.headers.accept ?? \"\").includes(\"text/html\");\n      if (mode === \"redirect\" || (mode === \"auto\" && wantsHtml)) {\n        const returnTo = req.originalUrl ?? req.url ?? \"/\";\n        res.statusCode = 302;\n        res.setHeader(\n          \"location\",\n          `${basePath}/login?redirect_to=${encodeURIComponent(returnTo)}`,\n        );\n        res.end();\n        return;\n      }\n\n      res.statusCode = 401;\n      res.setHeader(\"content-type\", \"application/json; charset=utf-8\");\n      res.end(JSON.stringify({ error: \"unauthenticated\" }));\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Whole-app gate middleware: `auth.gate` as Express/Connect middleware.\n * Mount it FIRST (before your routes, instead of `incortaAuth()` — it also\n * serves the auth routes) to give the entire app the platform-stamped\n * `appAccess` policy: `\"public\"` apps let everyone through, `\"authenticated\"`\n * apps require login, `\"catalog\"` apps require catalog VIEW access (with the\n * SDK's deny/unavailable pages). Requests that pass get `req.incortaAuth`\n * populated like `incortaAuth()` does.\n */\nexport function appGate(auth: IncortaAuth): Middleware {\n  return async (req, res, next) => {\n    try {\n      const request = await toWebRequest(req);\n      const response = await auth.gate(request);\n      if (response) {\n        await sendWebResponse(res, response);\n        return;\n      }\n      req.incortaAuth = await auth.getSession(request);\n      next();\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;AAkCO,SAAS,YAAY,MAA+B;AACzD,QAAM,cAAc,cAAc,IAAI;AACtC,QAAM,EAAE,SAAS,IAAI,KAAK;AAE1B,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,YAAM,QAAQ,IAAI,eAAe,IAAI,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC;AAC7D,UAAI,SAAS,YAAY,KAAK,WAAW,GAAG,QAAQ,GAAG,GAAG;AACxD,cAAM,YAAY,KAAK,GAAG;AAC1B;AAAA,MACF;AACA,UAAI,cAAc,MAAM,KAAK,WAAW,MAAM,aAAa,GAAG,CAAC;AAC/D,WAAK;AAAA,IACP,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;AAqBO,SAAS,YAAY,MAAmB,UAA8B,CAAC,GAAe;AAC3F,QAAM,OAAO,QAAQ,mBAAmB;AACxC,QAAM,EAAE,SAAS,IAAI,KAAK;AAE1B,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,UAAI,IAAI,gBAAgB,QAAW;AACjC,YAAI,cAAc,MAAM,KAAK,WAAW,MAAM,aAAa,GAAG,CAAC;AAAA,MACjE;AACA,UAAI,IAAI,aAAa;AACnB,YAAI,KAAK,OAAO,cAAc,WAAW;AACvC,eAAK;AACL;AAAA,QACF;AACA,cAAM,UAAU,IAAI;AACpB,YAAI;AACF,gBAAM,UAAU,MAAM,KAAK,aAAa,OAAO;AAC/C,cAAI,QAAQ,SAAS;AACnB,oBAAQ,YAAY;AACpB,iBAAK;AACL;AAAA,UACF;AACA,cAAI,aAAa;AACjB,cAAI,UAAU,gBAAgB,iCAAiC;AAC/D,cAAI,IAAI,KAAK,UAAU,EAAE,OAAO,oBAAoB,CAAC,CAAC;AACtD;AAAA,QACF,SAAS,OAAO;AACd,cAAI,EAAE,iBAAiB,8BAA8B;AAEnD,gBAAI,aAAa;AACjB,gBAAI,UAAU,gBAAgB,iCAAiC;AAC/D,gBAAI,UAAU,eAAe,IAAI;AACjC,gBAAI,IAAI,KAAK,UAAU,EAAE,OAAO,yBAAyB,CAAC,CAAC;AAC3D;AAAA,UACF;AAEA,cAAI,cAAc;AAAA,QACpB;AAAA,MACF;AAEA,YAAM,aAAa,IAAI,QAAQ,UAAU,IAAI,SAAS,WAAW;AACjE,UAAI,SAAS,cAAe,SAAS,UAAU,WAAY;AACzD,cAAM,WAAW,IAAI,eAAe,IAAI,OAAO;AAC/C,YAAI,aAAa;AACjB,YAAI;AAAA,UACF;AAAA,UACA,GAAG,QAAQ,sBAAsB,mBAAmB,QAAQ,CAAC;AAAA,QAC/D;AACA,YAAI,IAAI;AACR;AAAA,MACF;AAEA,UAAI,aAAa;AACjB,UAAI,UAAU,gBAAgB,iCAAiC;AAC/D,UAAI,IAAI,KAAK,UAAU,EAAE,OAAO,kBAAkB,CAAC,CAAC;AAAA,IACtD,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;AAWO,SAAS,QAAQ,MAA+B;AACrD,SAAO,OAAO,KAAK,KAAK,SAAS;AAC/B,QAAI;AACF,YAAM,UAAU,MAAM,aAAa,GAAG;AACtC,YAAM,WAAW,MAAM,KAAK,KAAK,OAAO;AACxC,UAAI,UAAU;AACZ,cAAM,gBAAgB,KAAK,QAAQ;AACnC;AAAA,MACF;AACA,UAAI,cAAc,MAAM,KAAK,WAAW,OAAO;AAC/C,WAAK;AAAA,IACP,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;","names":[]}

package/dist/index.cjs

@@ -20,7 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AppAccessTokenRejectedError: () => AppAccessTokenRejectedError,
+  AppAccessUnavailableError: () => AppAccessUnavailableError,
+  EDIT_BIT: () => EDIT_BIT,
   IncortaAuthError: () => IncortaAuthError,
+  SHARE_BIT: () => SHARE_BIT,
+  VIEW_BIT: () => VIEW_BIT,
   createIncortaAuth: () => createIncortaAuth,
   deleteClient: () => deleteClient,
   getClient: () => getClient,
@@ -30,6 +35,16 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/core/config.ts
+function resolveAppAccess(input, envValue) {
+  if (input) return input;
+  const raw = envValue?.trim().toLowerCase();
+  if (!raw) return "authenticated";
+  if (raw === "public" || raw === "authenticated" || raw === "catalog") return raw;
+  console.warn(
+    `[incorta-auth] Unrecognized INCORTA_APP_ACCESS value "${envValue}" \u2014 using "authenticated".`
+  );
+  return "authenticated";
+}
 function required(value, name, envVar) {
   if (!value) {
     throw new Error(
@@ -103,6 +118,8 @@ function resolveConfig(input = {}) {
     cookieSameSite,
     cookiePartitioned,
     exposeAccessToken: input.exposeAccessToken ?? false,
+    appAccess: resolveAppAccess(input.appAccess, env.INCORTA_APP_ACCESS),
+    embeddedSignIn: input.embeddedSignIn ?? (env.INCORTA_EMBEDDED_SIGN_IN?.toLowerCase() === "new-tab" ? "new-tab" : "redirect"),
     issuer,
     discoveryUrl: input.advanced?.discoveryUrl ?? `${issuer}/.well-known/openid-configuration`,
     jwksOverride: input.advanced?.jwks,
@@ -113,6 +130,99 @@ function resolveConfig(input = {}) {
 // src/core/handler.ts
 var import_node_crypto2 = require("crypto");
 
+// src/core/app-access.ts
+var VIEW_BIT = 1;
+var SHARE_BIT = 2;
+var EDIT_BIT = 4;
+var AppAccessUnavailableError = class extends Error {
+  constructor(cause) {
+    super(`[incorta-auth] App access check unavailable: ${cause}`);
+    this.name = "AppAccessUnavailableError";
+  }
+};
+var AppAccessTokenRejectedError = class extends Error {
+  constructor() {
+    super("[incorta-auth] Incorta rejected the session token during the app access check");
+    this.name = "AppAccessTokenRejectedError";
+  }
+};
+var APP_ACCESS_CACHE_TTL_MS = 3e4;
+var CHECK_TIMEOUT_MS = 5e3;
+var CACHE_MAX_ENTRIES = 5e3;
+function toVerdict(registered, access) {
+  const canView = (access & VIEW_BIT) === VIEW_BIT;
+  return {
+    registered,
+    access,
+    canView,
+    canEdit: (access & EDIT_BIT) === EDIT_BIT,
+    allowed: !registered || canView
+  };
+}
+function createAppAccessChecker(config) {
+  const base = config.internalIncortaUrl ?? config.incortaUrl;
+  const checkUrl = `${base}/apps-catalog/check`;
+  const cache = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  function prune(now) {
+    if (cache.size < CACHE_MAX_ENTRIES) return;
+    for (const [key, entry] of cache) {
+      if (entry.expiresAt <= now) cache.delete(key);
+    }
+  }
+  async function fetchVerdict(accessToken) {
+    let response;
+    try {
+      response = await config.fetch(checkUrl, {
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${accessToken}`
+        },
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS)
+      });
+    } catch (error) {
+      throw new AppAccessUnavailableError(error.message);
+    }
+    if (response.status === 401) throw new AppAccessTokenRejectedError();
+    if (!response.ok) {
+      throw new AppAccessUnavailableError(`HTTP ${response.status}`);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new AppAccessUnavailableError("invalid JSON response");
+    }
+    if (typeof body.registered !== "boolean" || typeof body.access !== "number") {
+      throw new AppAccessUnavailableError("malformed check response");
+    }
+    return toVerdict(body.registered, body.access);
+  }
+  async function check(accessToken, userKey) {
+    const now = Date.now();
+    const cached = cache.get(userKey);
+    if (cached && cached.expiresAt > now) return cached.verdict;
+    const pending = inFlight.get(userKey);
+    if (pending) return pending;
+    const promise = fetchVerdict(accessToken).then((verdict) => {
+      prune(now);
+      cache.set(userKey, { verdict, expiresAt: Date.now() + APP_ACCESS_CACHE_TTL_MS });
+      return verdict;
+    }).finally(() => {
+      inFlight.delete(userKey);
+    });
+    inFlight.set(userKey, promise);
+    return promise;
+  }
+  return {
+    check,
+    clearCache() {
+      cache.clear();
+      inFlight.clear();
+    }
+  };
+}
+
 // src/core/cookies.ts
 function parseCookies(header) {
   const out = {};
@@ -411,7 +521,17 @@ function withErrorParam(target, code) {
 function randomToken() {
   return (0, import_node_crypto2.randomBytes)(16).toString("base64url");
 }
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function wantsHtml(request) {
+  return request.method.toUpperCase() === "GET" && (request.headers.get("accept") ?? "").includes("text/html");
+}
+function requestPath(url) {
+  return `${url.pathname}${url.search}`;
+}
 function createHandler(config) {
+  const appAccessChecker = createAppAccessChecker(config);
   const sessionCookieOptions = (secure) => ({
     httpOnly: true,
     // SameSite=None requires Secure — force the pair even on plain http
@@ -444,6 +564,9 @@ function createHandler(config) {
     authorizeUrl.searchParams.set("scope", config.scope);
     authorizeUrl.searchParams.set("state", state);
     authorizeUrl.searchParams.set("nonce", nonce);
+    if (config.embeddedSignIn === "new-tab") {
+      return newTabSignInPage(authorizeUrl.toString(), `${origin}/`, [stateCookie]);
+    }
     return redirect(authorizeUrl.toString(), [stateCookie]);
   }
   async function callback(request, url) {
@@ -558,6 +681,18 @@ function createHandler(config) {
       setCookies
     );
   }
+  async function refreshRoute(request, url) {
+    const origin = requestOrigin(config, request);
+    const returnTo = validateReturnTo(url.searchParams.get("redirect_to"), origin);
+    const { session, setCookies } = await loadSession(request);
+    if (!session) {
+      return redirect(
+        `${config.basePath}/login?redirect_to=${encodeURIComponent(returnTo)}`,
+        setCookies
+      );
+    }
+    return redirect(returnTo, setCookies);
+  }
   async function logout(request, url) {
     const secure = isSecureRequest(config, request);
     const clearSession = deleteCookie(config.cookieName, sessionCookieOptions(secure));
@@ -610,6 +745,143 @@ function createHandler(config) {
       }
     );
   }
+  function newTabSignInPage(authorizeUrl, appRoot, cookies) {
+    const body = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sign in with Incorta</title>
+    <style>
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             background: #fafafa; color: #18181b;
+             font-family: ui-sans-serif, system-ui, sans-serif; }
+      main { max-width: 26rem; padding: 2rem; text-align: center; }
+      h1 { font-size: 1.2rem; margin: 0 0 .5rem; }
+      p { color: #52525b; font-size: .9rem; line-height: 1.5; margin: 0 0 1.25rem; }
+      a.btn { display: inline-block; padding: .55rem 1.1rem; border-radius: .5rem;
+              background: #18181b; color: #fafafa; text-decoration: none;
+              font-weight: 600; }
+    </style>
+  </head>
+  <body>
+    <main id="frame" hidden>
+      <h1>Sign in with Incorta</h1>
+      <p>
+        This app signs you in with your Incorta account. The embedded preview
+        can&rsquo;t complete sign-in here &mdash; continue in a new tab.
+      </p>
+      <a class="btn" href="${appRoot}" target="_blank" rel="noopener noreferrer">Sign in with Incorta &#8599;</a>
+    </main>
+    <script>
+      (function () {
+        var authorize = ${JSON.stringify(authorizeUrl)};
+        if (window.top === window.self) {
+          window.location.replace(authorize);
+        } else {
+          document.getElementById("frame").hidden = false;
+        }
+      })();
+    </script>
+    <noscript><a href="${appRoot}">Continue to sign in</a></noscript>
+  </body>
+</html>`;
+    const headers = new Headers({
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store"
+    });
+    for (const cookie of cookies) headers.append("set-cookie", cookie);
+    return new Response(body, { status: 200, headers });
+  }
+  function accessDeniedResponse(request, session) {
+    if (!wantsHtml(request)) {
+      return json(403, { error: "app_access_denied" });
+    }
+    const identity = escapeHtml(session.user.name?.trim() || session.user.sub);
+    const detail = session.user.name?.trim() && session.user.name.trim() !== session.user.sub ? `${identity} (${escapeHtml(session.user.sub)})` : identity;
+    const switchHref = `${config.basePath}/logout`;
+    return new Response(
+      `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>No access</title>
+    <style>
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             background: #fafafa; color: #18181b;
+             font-family: ui-sans-serif, system-ui, sans-serif; }
+      main { max-width: 26rem; padding: 2rem; text-align: center; }
+      h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+      p { color: #52525b; font-size: .9rem; line-height: 1.5; margin: 0 0 1.25rem; }
+      strong { color: #18181b; font-weight: 600; }
+      a { display: inline-block; padding: .55rem 1.1rem; border-radius: .5rem;
+          background: #18181b; color: #fafafa; font-size: .9rem;
+          text-decoration: none; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>You don&rsquo;t have access to this application</h1>
+      <p>
+        Ask the app&rsquo;s owner to share it with you in Incorta.
+        You are signed in as <strong>${detail}</strong>.
+      </p>
+      <a href="${switchHref}">Sign in with a different account</a>
+    </main>
+  </body>
+</html>`,
+      {
+        status: 403,
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          "cache-control": "no-store"
+        }
+      }
+    );
+  }
+  function accessUnavailableResponse(request) {
+    if (!wantsHtml(request)) {
+      return json(503, { error: "app_access_unavailable" });
+    }
+    return new Response(
+      `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta http-equiv="refresh" content="15" />
+    <title>Temporarily unavailable</title>
+    <style>
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             background: #fafafa; color: #18181b;
+             font-family: ui-sans-serif, system-ui, sans-serif; }
+      main { max-width: 26rem; padding: 2rem; text-align: center; }
+      h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+      p { color: #52525b; font-size: .9rem; line-height: 1.5; margin: 0; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>This app is temporarily unavailable</h1>
+      <p>
+        Your access could not be verified because Incorta did not respond.
+        This page retries automatically &mdash; you can also refresh in a
+        moment.
+      </p>
+    </main>
+  </body>
+</html>`,
+      {
+        status: 503,
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          "cache-control": "no-store",
+          "retry-after": "30"
+        }
+      }
+    );
+  }
   async function handler(request) {
     const url = new URL(request.url);
     if (url.pathname !== config.basePath && !url.pathname.startsWith(`${config.basePath}/`)) {
@@ -622,6 +894,7 @@ function createHandler(config) {
       if (route === "/callback" && method === "GET") return await callback(request, url);
       if (route === "/session" && method === "GET") return await sessionRoute(request);
       if (route === "/token" && method === "GET") return await tokenRoute(request);
+      if (route === "/refresh" && method === "GET") return await refreshRoute(request, url);
       if (route === "/logout" && (method === "POST" || method === "GET")) {
         return await logout(request, url);
       }
@@ -647,7 +920,57 @@ function createHandler(config) {
       expiresAt
     };
   }
-  return { handler, getSession };
+  function getAppAccess(session) {
+    return appAccessChecker.check(session.accessToken, session.user.sub);
+  }
+  async function gate(request) {
+    const url = new URL(request.url);
+    if (url.pathname === config.basePath || url.pathname.startsWith(`${config.basePath}/`)) {
+      return handler(request);
+    }
+    if (config.appAccess === "public") return null;
+    const session = await getSession(request);
+    if (!session) {
+      if (wantsHtml(request)) {
+        return redirect(
+          `${config.basePath}/login?redirect_to=${encodeURIComponent(requestPath(url))}`
+        );
+      }
+      return json(401, { error: "unauthenticated" });
+    }
+    if (config.appAccess !== "catalog") return null;
+    if (session.accessTokenExpiresAt <= Date.now()) {
+      if (wantsHtml(request)) {
+        return redirect(
+          `${config.basePath}/refresh?redirect_to=${encodeURIComponent(requestPath(url))}`
+        );
+      }
+      return json(401, { error: "token_expired" });
+    }
+    try {
+      const verdict = await getAppAccess(session);
+      if (verdict.allowed) return null;
+      return accessDeniedResponse(request, session);
+    } catch (error) {
+      if (error instanceof AppAccessTokenRejectedError) {
+        const secure = isSecureRequest(config, request);
+        const clearSession = deleteCookie(config.cookieName, sessionCookieOptions(secure));
+        if (wantsHtml(request)) {
+          return redirect(
+            `${config.basePath}/login?redirect_to=${encodeURIComponent(requestPath(url))}`,
+            [clearSession]
+          );
+        }
+        return json(401, { error: "unauthenticated" }, [clearSession]);
+      }
+      if (!(error instanceof AppAccessUnavailableError)) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error("[incorta-auth] app access check failed unexpectedly:", message);
+      }
+      return accessUnavailableResponse(request);
+    }
+  }
+  return { handler, getSession, gate, getAppAccess };
 }
 
 // src/core/register.ts
@@ -782,12 +1105,17 @@ async function deleteClient(options) {
 // src/index.ts
 function createIncortaAuth(config = {}) {
   const resolved = resolveConfig(config);
-  const { handler, getSession } = createHandler(resolved);
-  return { handler, getSession, config: resolved };
+  const { handler, getSession, gate, getAppAccess } = createHandler(resolved);
+  return { handler, getSession, gate, getAppAccess, config: resolved };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AppAccessTokenRejectedError,
+  AppAccessUnavailableError,
+  EDIT_BIT,
   IncortaAuthError,
+  SHARE_BIT,
+  VIEW_BIT,
   createIncortaAuth,
   deleteClient,
   getClient,