@mirrormedia/lilith-google-auth 0.1.0

package/lib/log.js

@@ -0,0 +1,68 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.emitLogEntry = emitLogEntry;
+exports.formatErrorEntry = formatErrorEntry;
+exports.formatLogEntry = formatLogEntry;
+
+/**
+ * Single-line JSON envelope for Cloud Logging. `severity` lets Cloud Logging
+ * parse the entry as `jsonPayload` instead of a multi-line `textPayload`, and
+ * an `ERROR` entry whose `message` is a stack trace is picked up by Error
+ * Reporting. Shape is shared with the upcoming lilith-core password-login
+ * change (separate PR); this file intentionally has no dependency on
+ * `@twreporter/errors`.
+ */
+
+/**
+ * Maps a login event to a log entry. Fields stay top-level (no nesting) so a
+ * Logs Explorer query can filter on e.g. `jsonPayload.userId` directly.
+ */
+function formatLogEntry(event) {
+  if (event.outcome === 'success') {
+    return {
+      severity: 'INFO',
+      message: 'google-login success',
+      ...event
+    };
+  }
+
+  return {
+    severity: 'WARNING',
+    message: `google-login failure: ${event.reason}`,
+    ...event
+  };
+}
+/**
+ * Maps an unexpected throw (callback catch-all, or a caller-supplied logger
+ * throwing) to an ERROR entry. `message` is the stack trace when available so
+ * Error Reporting can group and display it; a non-Error thrown value falls
+ * back to its string form.
+ */
+
+
+function formatErrorEntry(err, context) {
+  const message = err instanceof Error && err.stack ? err.stack : String(err);
+  return {
+    severity: 'ERROR',
+    message,
+    type: context.type,
+    stage: context.stage,
+    email: context.email,
+    timestamp: new Date().toISOString()
+  };
+}
+/** Prints `entry` as a single JSON line: `console.error` for ERROR, `console.log` otherwise. */
+
+
+function emitLogEntry(entry) {
+  const line = JSON.stringify(entry);
+
+  if (entry.severity === 'ERROR') {
+    console.error(line);
+  } else {
+    console.log(line);
+  }
+}

package/lib/mini-app.js

@@ -0,0 +1,267 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createGoogleAuthMiniApp = createGoogleAuthMiniApp;
+
+var _express = require("express");
+
+var _cookie = require("cookie");
+
+var _google = require("./google");
+
+var _log = require("./log");
+
+var _passwordGuard = require("./password-guard");
+
+var _redirect = require("./redirect");
+
+var _session = require("./session");
+
+var _signinPage = require("./signin-page");
+
+var _stateCookie = require("./state-cookie");
+
+/** Express path syntax that would silently turn callbackPath into a pattern. */
+const PATH_PATTERN_CHARS = /[:()*?+]/;
+/**
+ * The mini-app is mounted before the host's own middleware (see
+ * withGoogleAuth), so it cannot inherit a host X-Robots-Tag middleware and
+ * stamps its own pages instead. Pass-through and guard responses are left
+ * alone: those belong to the host.
+ */
+
+const ROBOTS_TAG = 'noindex, nofollow, noimageindex';
+
+function fail(reason) {
+  throw new Error(`[google-auth] ${reason}`);
+}
+/**
+ * Fails fast on an option set that cannot produce a working flow. A CMS that
+ * boots with a broken sign-in is worse than one that refuses to boot.
+ */
+
+
+function validateOptions(options) {
+  var _options$clientId, _options$clientSecret, _options$stateSecret;
+
+  if (!((_options$clientId = options.clientId) !== null && _options$clientId !== void 0 && _options$clientId.trim())) fail('clientId is required');
+  if (!((_options$clientSecret = options.clientSecret) !== null && _options$clientSecret !== void 0 && _options$clientSecret.trim())) fail('clientSecret is required');
+  if (!((_options$stateSecret = options.stateSecret) !== null && _options$stateSecret !== void 0 && _options$stateSecret.trim())) fail('stateSecret is required');
+
+  if (options.stateSecret.length < 32) {
+    fail('stateSecret must be at least 32 characters');
+  }
+
+  const allowedDomains = (options.allowedDomains ?? []).map(domain => domain.trim().toLowerCase()).filter(Boolean);
+
+  if (allowedDomains.length === 0) {
+    fail('allowedDomains must list at least one Workspace domain');
+  }
+
+  let callbackUrl;
+
+  try {
+    callbackUrl = new URL(options.callbackUrl);
+  } catch {
+    fail(`callbackUrl must be an absolute URL, got ${options.callbackUrl}`);
+  }
+
+  if (callbackUrl.protocol !== 'http:' && callbackUrl.protocol !== 'https:') {
+    fail(`callbackUrl must be http(s), got ${callbackUrl.protocol}`);
+  }
+
+  const callbackPath = callbackUrl.pathname;
+
+  if (callbackPath === '/' || PATH_PATTERN_CHARS.test(callbackPath)) {
+    fail(`callbackUrl path is not usable as a route: ${callbackPath}`);
+  }
+
+  return {
+    allowedDomains,
+    callbackPath
+  };
+}
+
+function createGoogleAuthMiniApp(options, deps = {}) {
+  const {
+    allowedDomains,
+    callbackPath
+  } = validateOptions(options);
+  const passwordLoginEnabled = options.passwordLoginEnabled !== false;
+  const graphqlPath = options.graphqlPath ?? '/api/graphql';
+  const redirectDefault = options.signinRedirectDefault ?? '/';
+  const log = options.logger ?? defaultLogger;
+  const google = deps.google ?? (0, _google.createGoogleClient)({
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    callbackUrl: options.callbackUrl
+  });
+  const secureCookie = options.callbackUrl.startsWith('https://');
+  const router = (0, _express.Router)();
+
+  if (!passwordLoginEnabled) {
+    // First of two layers. This one never sees a multipart request, so the
+    // host must also register createPasswordLoginBlockPlugin() (see README).
+    router.use(graphqlPath, ...(0, _passwordGuard.createPasswordLoginGuard)());
+  }
+
+  router.get('/signin', (req, res, next) => {
+    if (passwordLoginEnabled && req.query.password === '1') return next();
+    const from = typeof req.query.from === 'string' ? req.query.from : undefined;
+    const error = typeof req.query.error === 'string' ? req.query.error : undefined;
+    res.status(200).type('html').set('Cache-Control', 'no-store').set('X-Robots-Tag', ROBOTS_TAG).send((0, _signinPage.renderSigninPage)({
+      passwordLoginEnabled,
+      from,
+      error
+    }));
+  });
+  router.get('/auth/google', (req, res) => {
+    const from = (0, _redirect.sanitizeRedirectPath)(req.query.from, redirectDefault);
+    const state = (0, _stateCookie.createAuthState)(from);
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Robots-Tag', ROBOTS_TAG);
+    res.setHeader('Set-Cookie', (0, _cookie.serialize)(_stateCookie.STATE_COOKIE_NAME, (0, _stateCookie.sealAuthState)(state, options.stateSecret), {
+      httpOnly: true,
+      secure: secureCookie,
+      sameSite: 'lax',
+      path: callbackPath,
+      maxAge: _stateCookie.STATE_TTL_SECONDS
+    }));
+    res.redirect(302, google.buildAuthUrl({
+      state: state.state,
+      nonce: state.nonce,
+      hdHint: allowedDomains.length === 1 ? allowedDomains[0] : undefined
+    }));
+  });
+  router.get(callbackPath, async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Robots-Tag', ROBOTS_TAG);
+    const clearState = (0, _cookie.serialize)(_stateCookie.STATE_COOKIE_NAME, '', {
+      httpOnly: true,
+      secure: secureCookie,
+      sameSite: 'lax',
+      path: callbackPath,
+      maxAge: 0
+    }); // A caller-supplied logger must never be able to block the redirect or
+    // the state-cookie clear that follow it.
+
+    const safeLog = event => {
+      try {
+        log(event);
+      } catch (err) {
+        (0, _log.emitLogEntry)((0, _log.formatErrorEntry)(err, {
+          type: 'google-login',
+          stage: 'logger'
+        }));
+      }
+    };
+
+    const failWith = (reason, email) => {
+      safeLog(buildEvent(req, {
+        outcome: 'failure',
+        reason,
+        email
+      }));
+      res.setHeader('Set-Cookie', clearState);
+      res.redirect(302, `/signin?error=${reason}`);
+    };
+
+    const cookies = (0, _cookie.parse)(req.headers.cookie ?? '');
+    const state = (0, _stateCookie.unsealAuthState)(cookies[_stateCookie.STATE_COOKIE_NAME], options.stateSecret);
+    if (!state) return failWith('state', null); // Everything below can call out to Google, Keystone/Prisma, or a
+    // caller-supplied logger. Express 4 does not route a rejected async
+    // handler's promise to the error middleware, so any unexpected throw
+    // here must be caught and fail closed rather than hang the request or
+    // crash the process.
+
+    let email = null;
+
+    try {
+      if (typeof req.query.error === 'string') return failWith('token', null);
+
+      if (typeof req.query.state !== 'string' || req.query.state !== state.state) {
+        return failWith('state', null);
+      }
+
+      if (typeof req.query.code !== 'string' || req.query.code.length === 0) {
+        return failWith('token', null);
+      }
+
+      let identity;
+
+      try {
+        identity = await google.exchangeCode(req.query.code);
+      } catch {
+        return failWith('token', null);
+      }
+
+      email = identity.email;
+      if (!identity.email || identity.nonce !== state.nonce) return failWith('token', identity.email);
+      if (!identity.emailVerified) return failWith('unverified_email', identity.email);
+
+      if (!identity.hd || !allowedDomains.includes(identity.hd.toLowerCase())) {
+        return failWith('domain', identity.email);
+      }
+
+      const result = await (0, _session.signInByEmail)(options.keystoneContext, req, res, identity.email);
+      if (!result.ok) return failWith(result.reason, identity.email);
+      safeLog(buildEvent(req, {
+        outcome: 'success',
+        email: result.user.email ?? identity.email,
+        userId: result.user.id,
+        name: result.user.name,
+        role: result.user.role
+      })); // sessionStrategy.start() already set the session cookie; append the clear.
+
+      appendSetCookie(res, clearState);
+      res.redirect(302, (0, _redirect.sanitizeRedirectPath)(state.from, redirectDefault));
+    } catch (err) {
+      (0, _log.emitLogEntry)((0, _log.formatErrorEntry)(err, {
+        type: 'google-login',
+        stage: 'callback',
+        email
+      }));
+      return failWith('session', email);
+    }
+  });
+  return router;
+}
+
+function appendSetCookie(res, value) {
+  const existing = res.getHeader('Set-Cookie');
+  const list = Array.isArray(existing) ? existing.map(String) : existing ? [String(existing)] : [];
+  res.setHeader('Set-Cookie', [...list, value]);
+}
+/** Same precedence and IPv6-localhost normalisation as lilith-core. */
+
+
+function clientIp(req) {
+  var _req$socket;
+
+  const forwarded = req.headers['x-forwarded-for'];
+  const realIp = req.headers['x-real-ip'];
+  const ip = (typeof forwarded === 'string' ? forwarded.split(',')[0].trim() : undefined) || (typeof realIp === 'string' ? realIp.trim() : undefined) || ((_req$socket = req.socket) === null || _req$socket === void 0 ? void 0 : _req$socket.remoteAddress) || null;
+  if (ip === '::1' || ip === '::ffff:127.0.0.1') return '127.0.0.1';
+  return ip;
+}
+
+function buildEvent(req, fields) {
+  const userAgent = req.headers['user-agent'] ?? null;
+  return {
+    type: 'google-login',
+    timestamp: new Date().toISOString(),
+    userId: null,
+    name: null,
+    role: null,
+    ipAddress: clientIp(req),
+    userAgent,
+    ...fields
+  };
+}
+
+function defaultLogger(event) {
+  // Same field names as lilith-core's login-logging plugin so log queries match.
+  (0, _log.emitLogEntry)((0, _log.formatLogEntry)(event));
+}

package/lib/password-guard.js

@@ -0,0 +1,66 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PASSWORD_MUTATION_PATTERN = void 0;
+exports.createPasswordLoginGuard = createPasswordLoginGuard;
+exports.requestUsesPasswordLogin = requestUsesPasswordLogin;
+
+var _express = _interopRequireDefault(require("express"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/** Field name of Keystone's password mutation for listKey 'User'. */
+const PASSWORD_MUTATION_PATTERN = /\bauthenticateUserWithPassword\b/;
+/**
+ * True when a GraphQL request body (single or batched) selects the password
+ * mutation. Aliases cannot hide it because the field name must still appear.
+ */
+
+exports.PASSWORD_MUTATION_PATTERN = PASSWORD_MUTATION_PATTERN;
+
+function requestUsesPasswordLogin(body) {
+  const operations = Array.isArray(body) ? body : [body];
+  return operations.some(operation => {
+    if (!operation || typeof operation !== 'object') return false;
+    const query = operation.query;
+    return typeof query === 'string' && PASSWORD_MUTATION_PATTERN.test(query);
+  });
+}
+/**
+ * Express handlers that reject the password mutation with 403. Mount on the
+ * GraphQL path only when password login is disabled. The 500mb limit mirrors
+ * the host packages' own body parser so large DraftJS payloads are not
+ * rejected here with 413.
+ */
+
+
+function createPasswordLoginGuard() {
+  const parseJson = _express.default.json({
+    limit: '500mb'
+  });
+
+  const parseIfNeeded = (req, res, next) => {
+    if (req.method !== 'POST' || req.body !== undefined) return next();
+    return parseJson(req, res, next);
+  };
+
+  const guard = (req, res, next) => {
+    if (req.method === 'POST' && requestUsesPasswordLogin(req.body)) {
+      res.status(403).json({
+        errors: [{
+          message: 'Password login is disabled. Sign in with Google.',
+          extensions: {
+            code: 'PASSWORD_LOGIN_DISABLED'
+          }
+        }]
+      });
+      return;
+    }
+
+    next();
+  };
+
+  return [parseIfNeeded, guard];
+}

package/lib/password-plugin.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PASSWORD_MUTATION_FIELD = void 0;
+exports.createPasswordLoginBlockPlugin = createPasswordLoginBlockPlugin;
+exports.documentSelectsPasswordLogin = documentSelectsPasswordLogin;
+
+var _graphql = require("graphql");
+
+/** Field name of Keystone's password mutation for listKey 'User'. */
+const PASSWORD_MUTATION_FIELD = 'authenticateUserWithPassword';
+exports.PASSWORD_MUTATION_FIELD = PASSWORD_MUTATION_FIELD;
+const BLOCKED_MESSAGE = 'Password login is disabled. Sign in with Google.';
+/**
+ * True when any mutation operation in the document selects the password
+ * mutation at top level, directly or through a fragment spread. Working on the
+ * parsed document instead of the raw query string is what makes this immune to
+ * the multipart bypass: Keystone mounts `graphqlUploadExpress` after
+ * `extendExpressApp`, so an HTTP-layer guard never sees the operation carried
+ * in a multipart `operations` field.
+ */
+
+function documentSelectsPasswordLogin(document) {
+  const fragments = new Map();
+
+  for (const definition of document.definitions) {
+    if (definition.kind === _graphql.Kind.FRAGMENT_DEFINITION) {
+      fragments.set(definition.name.value, definition);
+    }
+  }
+
+  const selectsPasswordLogin = (selections, visited) => selections.some(selection => {
+    if (selection.kind === _graphql.Kind.FIELD) {
+      return selection.name.value === PASSWORD_MUTATION_FIELD;
+    }
+
+    if (selection.kind === _graphql.Kind.INLINE_FRAGMENT) {
+      return selectsPasswordLogin(selection.selectionSet.selections, visited);
+    }
+
+    const name = selection.name.value; // A self-referential fragment would otherwise recurse forever.
+
+    if (visited.has(name)) return false;
+    visited.add(name);
+    const fragment = fragments.get(name);
+    return fragment ? selectsPasswordLogin(fragment.selectionSet.selections, visited) : false;
+  });
+
+  return document.definitions.some(definition => definition.kind === _graphql.Kind.OPERATION_DEFINITION && definition.operation === 'mutation' && selectsPasswordLogin(definition.selectionSet.selections, new Set()));
+}
+/**
+ * Structural view of the slice of Apollo Server 4's plugin API this package
+ * uses. Typed by hand so the package does not depend on @apollo/server; the
+ * shape is assignable to `ApolloServerPlugin` where the host needs it.
+ */
+
+
+/**
+ * Apollo Server plugin that rejects the password mutation with 403. Add it to
+ * `config.graphql.apolloConfig.plugins` whenever the password kill switch is
+ * on; the mini-app's HTTP guard alone cannot see multipart requests.
+ */
+function createPasswordLoginBlockPlugin() {
+  return {
+    async requestDidStart() {
+      return {
+        async didResolveOperation(requestContext) {
+          if (documentSelectsPasswordLogin(requestContext.document)) {
+            throw new _graphql.GraphQLError(BLOCKED_MESSAGE, {
+              extensions: {
+                code: 'PASSWORD_LOGIN_DISABLED',
+                http: {
+                  status: 403
+                }
+              }
+            });
+          }
+        }
+
+      };
+    }
+
+  };
+}

package/lib/redirect.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.sanitizeRedirectPath = sanitizeRedirectPath;
+
+/**
+ * Only same-origin relative paths are honoured as a post-login redirect.
+ * Anything else falls back so the callback can never become an open redirect.
+ */
+function sanitizeRedirectPath(from, fallback = '/') {
+  if (typeof from !== 'string' || from.length === 0) return fallback;
+  if (!from.startsWith('/')) return fallback;
+  if (from.startsWith('//') || from.startsWith('/\\')) return fallback; // Any C0 control character or DEL: header-splitting vectors beyond CR/LF,
+  // plus bytes a proxy or logger may re-interpret.
+  // eslint-disable-next-line no-control-regex
+
+  if (/[\u0000-\u001f\u007f]/.test(from)) return fallback;
+  return from;
+}

package/lib/session.js

@@ -0,0 +1,59 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.signInByEmail = signInByEmail;
+const SESSION_LIST_KEY = 'User';
+/**
+ * Looks up the User by email and issues the same session cookie Keystone's
+ * password login would. No row is ever created here.
+ */
+
+async function signInByEmail(keystoneContext, req, res, email) {
+  const row = await keystoneContext.sudo().query[SESSION_LIST_KEY].findOne({
+    where: {
+      email
+    },
+    query: 'id email name role'
+  });
+
+  if (!row || row.id === undefined || row.id === null) {
+    return {
+      ok: false,
+      reason: 'no_user'
+    };
+  }
+
+  const user = {
+    id: String(row.id),
+    email: typeof row.email === 'string' ? row.email : null,
+    name: typeof row.name === 'string' ? row.name : null,
+    role: typeof row.role === 'string' ? row.role : null
+  }; // start() silently returns undefined without a response-bound context.
+
+  const context = await keystoneContext.withRequest(req, res);
+  if (!context.sessionStrategy) return {
+    ok: false,
+    reason: 'session'
+  };
+  const token = await context.sessionStrategy.start({
+    data: {
+      listKey: SESSION_LIST_KEY,
+      itemId: user.id
+    },
+    context
+  });
+
+  if (typeof token !== 'string' || token.length === 0) {
+    return {
+      ok: false,
+      reason: 'session'
+    };
+  }
+
+  return {
+    ok: true,
+    user
+  };
+}

package/lib/signin-page.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ERROR_MESSAGES = void 0;
+exports.renderSigninPage = renderSigninPage;
+const ERROR_MESSAGES = {
+  state: '登入逾時或狀態不符，請重新登入。',
+  token: '無法驗證 Google 回傳的資料，請重新登入。',
+  domain: '此 Google 帳號不屬於允許的網域。',
+  unverified_email: 'Google 帳號的 email 尚未驗證。',
+  no_user: '此 email 尚未建立 CMS 帳號，請聯絡管理員。',
+  session: '建立登入工作階段失敗，請重試。'
+};
+exports.ERROR_MESSAGES = ERROR_MESSAGES;
+const GENERIC_ERROR = '登入失敗，請重新登入。';
+
+function renderSigninPage(options) {
+  const fromQuery = options.from ? `from=${encodeURIComponent(options.from)}` : '';
+  const googleHref = fromQuery ? `/auth/google?${fromQuery}` : '/auth/google';
+  const passwordHref = fromQuery ? `/signin?password=1&${fromQuery}` : '/signin?password=1';
+  const message = options.error ? ERROR_MESSAGES[options.error] ?? GENERIC_ERROR : '';
+  return `<!doctype html>
+<html lang="zh-Hant">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>登入</title>
+<style>
+  body { margin: 0; font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans TC", sans-serif; background: #f4f5f7; color: #172b4d; }
+  main { max-width: 360px; margin: 12vh auto; padding: 32px; background: #fff; border-radius: 8px; box-shadow: 0 2px 8px rgba(9, 30, 66, 0.15); text-align: center; }
+  h1 { font-size: 20px; margin: 0 0 24px; }
+  .btn { display: block; padding: 12px 16px; border-radius: 6px; background: #1a73e8; color: #fff; text-decoration: none; font-weight: 600; }
+  .btn:hover { background: #1765cc; }
+  .alt { display: inline-block; margin-top: 20px; color: #5e6c84; font-size: 14px; }
+  .error { margin: 0 0 20px; padding: 10px 12px; border-radius: 6px; background: #ffebe6; color: #bf2600; font-size: 14px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>登入 CMS</h1>
+  ${message ? `<p class="error">${escapeHtml(message)}</p>` : ''}
+  <a class="btn" href="${escapeHtml(googleHref)}">使用 Google 帳號登入</a>
+  ${options.passwordLoginEnabled ? `<a class="alt" href="${escapeHtml(passwordHref)}">使用密碼登入</a>` : ''}
+</main>
+</body>
+</html>
+`;
+}
+
+function escapeHtml(value) {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}

package/lib/state-cookie.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.STATE_TTL_SECONDS = exports.STATE_COOKIE_NAME = void 0;
+exports.createAuthState = createAuthState;
+exports.sealAuthState = sealAuthState;
+exports.unsealAuthState = unsealAuthState;
+
+var _nodeCrypto = require("node:crypto");
+
+const STATE_COOKIE_NAME = 'lilith-google-auth-state';
+exports.STATE_COOKIE_NAME = STATE_COOKIE_NAME;
+const STATE_TTL_SECONDS = 300;
+exports.STATE_TTL_SECONDS = STATE_TTL_SECONDS;
+
+function createAuthState(from, now = Date.now()) {
+  return {
+    state: (0, _nodeCrypto.randomBytes)(32).toString('base64url'),
+    nonce: (0, _nodeCrypto.randomBytes)(32).toString('base64url'),
+    from,
+    exp: now + STATE_TTL_SECONDS * 1000
+  };
+}
+
+function sealAuthState(state, secret) {
+  const payload = Buffer.from(JSON.stringify(state), 'utf8').toString('base64url');
+  return `${payload}.${sign(payload, secret)}`;
+}
+
+function unsealAuthState(sealed, secret, now = Date.now()) {
+  if (!sealed) return undefined;
+  const dot = sealed.lastIndexOf('.');
+  if (dot <= 0) return undefined;
+  const payload = sealed.slice(0, dot);
+  const signature = sealed.slice(dot + 1);
+  const expected = sign(payload, secret);
+  const a = Buffer.from(signature, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length || !(0, _nodeCrypto.timingSafeEqual)(a, b)) return undefined;
+
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+
+    if (typeof parsed.state !== 'string' || typeof parsed.nonce !== 'string' || typeof parsed.from !== 'string' || typeof parsed.exp !== 'number') {
+      return undefined;
+    }
+
+    if (parsed.exp <= now) return undefined;
+    return {
+      state: parsed.state,
+      nonce: parsed.nonce,
+      from: parsed.from,
+      exp: parsed.exp
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function sign(payload, secret) {
+  return (0, _nodeCrypto.createHmac)('sha256', secret).update(payload).digest('base64url');
+}

package/lib/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});