@bongos/core 1.19.1076 → 1.19.1078

package/src/bongos/routes/auth.js

@@ -210,9 +210,41 @@ function renderAccessPendingPage(login, startHref) {
 // SESSION_COOKIE_NAMES, because the request-level token extractor there has to
 // accept exactly the names this router sets and clears: two lists would drift,
 // and the only symptom of the drift is a builder being silently signed out.
-// Head = the one name we SET. Tail = the names we accept and clear on write.
+// Head = the name we SET over https: the host-only `__Host-bongos_session`
+// (task 1004357). The second name is what we SET over plain http (localhost dev),
+// where a browser refuses any `__Host-` cookie. Every other name is accepted on
+// read and cleared on write.
 const SESSION_COOKIE = auth.SESSION_COOKIE_NAMES[0];
-const SESSION_COOKIE_OLD = auth.SESSION_COOKIE_NAMES.slice(1);
+const SESSION_COOKIE_INSECURE = auth.SESSION_COOKIE_NAMES[1];
+
+function isSecureReq(req) {
+  return !!(req.secure || req.headers['x-forwarded-proto'] === 'https');
+}
+
+// The one session-cookie name this request should carry.
+function sessionCookieName(req) {
+  return isSecureReq(req) ? SESSION_COOKIE : SESSION_COOKIE_INSECURE;
+}
+
+// Set the session cookie. ALWAYS host-only — no Domain attribute, on any host
+// (task 1004357, ADR 0145 Finding 1). The hub used to scope it to ".<apex>" so
+// one sign-in spanned builders./status., but a Domain cookie reaches EVERY
+// subdomain, and a project's hall at <handle>.<apex> runs code from the
+// project's own repository: any visiting hub builder handed that code their hub
+// session. The subdomains now receive their own copy through the one-time
+// handoff below (mintHandoffCode / GET /auth/web/handoff) instead.
+function setSessionCookie(req, res, token, expires) {
+  res.cookie(sessionCookieName(req), token, {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: isSecureReq(req),
+    path: '/',
+    ...(expires ? { expires } : {}),
+  });
+  // A browser arriving with an older session cookie must not keep it — above
+  // all the apex-scoped one, which is still being sent to every project hall.
+  clearSupersededSessionCookies(req, res);
+}
 
 // The session token off a request's cookies, trying each accepted name newest
 // first. Replaces the hand-written `parseCookie(new) || parseCookie(legacy)`
@@ -225,16 +257,25 @@ function sessionCookieToken(req) {
   return null;
 }
 
-// Clear every SUPERSEDED session cookie, in both the host-only and apex-scoped
-// forms (a clearCookie only matches the cookie whose domain attribute it names).
-// Called wherever we set the current cookie, so a browser that arrived with a
-// `gds_session` leaves holding only `bongos_session` — otherwise the stale name
-// lingers until its own expiry and every later request carries two tokens.
-function clearSupersededSessionCookies(req, res) {
-  const domainOpts = sessionCookieDomainOpts(req);
-  for (const name of SESSION_COOKIE_OLD) {
+// Clear every SUPERSEDED session cookie, in both the host-only and the legacy
+// apex-scoped forms (a clearCookie only matches the cookie whose domain attribute
+// it names). Called wherever we set the current cookie, so a browser that arrived
+// with a `gds_session` or an apex-scoped `bongos_session` leaves holding only the
+// current host-only name — otherwise the stale one lingers until its own expiry,
+// every later request carries two tokens, and the apex-scoped one keeps reaching
+// project halls. `{ all: true }` clears the current name too (sign-out).
+function clearSupersededSessionCookies(req, res, { all = false } = {}) {
+  const keep = all ? null : sessionCookieName(req);
+  const legacy = legacyApexCookieOpts(req);
+  for (const name of auth.SESSION_COOKIE_NAMES) {
+    if (name === keep) continue;
+    if (name.startsWith('__Host-')) {
+      // A __Host- cookie only matches a clear that is itself Secure + Path=/.
+      res.clearCookie(name, { path: '/', secure: true });
+      continue;
+    }
     res.clearCookie(name);
-    if (domainOpts.domain) res.clearCookie(name, domainOpts);
+    if (legacy.domain) res.clearCookie(name, legacy);
   }
 }
 const STATE_COOKIE = 'gds_oauth_state';
@@ -293,29 +334,138 @@ function reqHost(req) {
   return String(raw).toLowerCase().split(',')[0].trim().split(':')[0];
 }
 
-// The production-facing hosts that share one sign-in. Deliberately enumerated
-// (not "any *.example.com") so staging.example.com — a SEPARATE
-// process + DB on :3001 — keeps a host-only cookie and never bleeds an
-// apex-scoped token into prod (or vice versa).
-// When COOKIE_APEX is "" (localhost / no configured cookieDomain) the set is
-// EMPTY → every host gets a host-only cookie (never a "." + "" = ".<empty>" leak).
-const APEX_COOKIE_HOSTS = new Set(
+// The hub's own hosts — the ones that share one sign-in. Deliberately enumerated
+// (not "any *.example.com"): every OTHER subdomain may be a project's hall
+// running that project's code (task 1004357), or staging.example.com — a
+// SEPARATE process + DB. When COOKIE_APEX is "" (localhost / no configured
+// cookieDomain) the set is EMPTY and there is nothing to share.
+//
+// Nothing is SET with a Domain attribute any more. The set decides two things
+// only: which hosts may be handed a session through the one-time handoff, and
+// where the LEGACY apex-scoped cookies (set before task 1004357) get cleared.
+const HUB_HOSTS = new Set(
   COOKIE_APEX
     ? [COOKIE_APEX, 'www.' + COOKIE_APEX, 'builders.' + COOKIE_APEX, 'status.' + COOKIE_APEX]
     : []
 );
 
-// Cookie attributes that vary by host. On the production-facing hosts the
-// session cookie is scoped to the apex so it crosses subdomains (the enabler
-// for builders.example.com, #726); everywhere else (localhost, staging)
-// it stays host-only. Returns a spread-able object.
-function sessionCookieDomainOpts(req) {
-  if (APEX_COOKIE_HOSTS.has(reqHost(req))) {
+// The Domain attribute the hub USED to scope its cookies to on its own hosts
+// (#726/#734) — kept ONLY so a clearCookie can match and expire those legacy
+// cookies. Never spread into a res.cookie(): that is the bug task 1004357 fixed.
+// Returns a spread-able object.
+function legacyApexCookieOpts(req) {
+  if (HUB_HOSTS.has(reqHost(req))) {
     return { domain: '.' + COOKIE_APEX };
   }
   return {};
 }
 
+// Host of the pinned sign-in origin (WEB_REDIRECT_ORIGIN): the one host the
+// GitHub callback lands on, so the one host whose cookies the handshake reads.
+function canonicalHost() {
+  try {
+    return WEB_REDIRECT_ORIGIN ? new URL(WEB_REDIRECT_ORIGIN).hostname.toLowerCase() : '';
+  } catch {
+    return '';
+  }
+}
+
+// A hub host OTHER than the canonical one (builders., status., www.). Its
+// sign-in has to begin on the canonical host and come back via the handoff.
+function isSatelliteHubHost(host) {
+  const canon = canonicalHost();
+  return !!canon && HUB_HOSTS.has(canon) && HUB_HOSTS.has(host) && host !== canon;
+}
+
+// ── the one-time session handoff (task 1004357) ──
+// A host-only cookie set on the apex never reaches builders.<apex>, so after a
+// sign-in (which always completes on the apex) the apex hands the subdomain a
+// ONE-TIME code in a redirect, and the subdomain trades it for its own host-only
+// copy of the same session. The code is bound to the one target host, single-use
+// and lives HANDOFF_TTL_MS. It is only ever minted for a HUB_HOSTS member, so a
+// project hall on another subdomain can never be handed one. Same token, not a
+// fresh session: one sign-out revokes it everywhere.
+//
+// In-memory: the hub is one process serving all its hosts, and a code outlives
+// a restart by at most HANDOFF_TTL_MS — a builder caught by one signs in again
+// from the handoff page's door.
+const HANDOFF_TTL_MS = 60 * 1000;
+const HANDOFF_MAX = 10000;
+const handoffCodes = new Map();
+function mintHandoffCode({ token, host, expires, now = Date.now() }) {
+  for (const [c, v] of handoffCodes) if (v.until <= now) handoffCodes.delete(c);
+  if (handoffCodes.size >= HANDOFF_MAX) handoffCodes.delete(handoffCodes.keys().next().value);
+  const code = crypto.randomBytes(32).toString('hex');
+  handoffCodes.set(code, { token, host, expires: expires || null, until: now + HANDOFF_TTL_MS });
+  return code;
+}
+function redeemHandoffCode(code, host, now = Date.now()) {
+  if (typeof code !== 'string' || !/^[0-9a-f]{64}$/.test(code)) return null;
+  const v = handoffCodes.get(code);
+  if (!v) return null;
+  handoffCodes.delete(code); // single-use, even when the host does not match
+  if (v.until <= now || v.host !== host) return null;
+  return v;
+}
+
+// The API prefix this router is mounted under (/api/gds or /api/bongos).
+function apiBase(req) {
+  return req.baseUrl || '/api/bongos';
+}
+
+// The URL that hands the session to `target` — a validated return URL on a
+// satellite hub host — or null when `target` is anything else. The redirect
+// carries only the code; the path the builder was headed for rides as ?return=
+// and is re-validated (relative paths only) on the far side.
+function handoffUrlFor(req, target, token, expires) {
+  let u;
+  try { u = new URL(target); } catch { return null; }
+  const host = u.hostname.toLowerCase();
+  if (u.protocol !== 'https:' || u.port || !isSatelliteHubHost(host)) return null;
+  const code = mintHandoffCode({ token, host, expires });
+  const back = (u.pathname || '/') + (u.search || '');
+  return `https://${host}${apiBase(req)}/auth/web/handoff?code=${code}&return=${encodeURIComponent(back)}`;
+}
+
+// The live session token (and its expiry) this request carries, or null.
+async function liveSessionToken(req) {
+  for (const token of auth.extractTokens(req)) {
+    const session = await db.lookupSession(token);
+    if (session) return { token, expires: session.expires_at || null };
+  }
+  return null;
+}
+
+// Move a browser still holding a pre-1004357 session cookie onto the host-only
+// one (task 1004357). Every builder signed in before this shipped carries an
+// apex-scoped `bongos_session` that their browser still sends to every project
+// hall; waiting for them to sign in again would leave it live for the session's
+// whole lifetime. So on the first https request that carries an old name and not
+// the current one, re-issue the same token host-only and expire the old cookie
+// in both forms — or, when no old token is live any more, just expire it. A
+// lookup that THROWS changes nothing: never sign a builder out on a DB blip.
+async function migrateLegacySessionCookie(req, res, next) {
+  try {
+    if (isSecureReq(req) && !parseCookie(req, SESSION_COOKIE)
+      && auth.SESSION_COOKIE_NAMES.slice(1).some((n) => parseCookie(req, n))) {
+      const live = await liveSessionToken(req);
+      if (live) setSessionCookie(req, res, live.token, live.expires);
+      else clearSupersededSessionCookies(req, res, { all: true });
+    }
+  } catch (err) {
+    log.error('[auth] legacy session-cookie migration failed (non-blocking)', err);
+  }
+  next();
+}
+
+// A Discord link begun on a satellite hub host restarts on the canonical host,
+// where its callback lands and its host-only state cookie can be read back.
+function discordStartOnCanonicalHost(req, res, next) {
+  if (!isSatelliteHubHost(reqHost(req))) return next();
+  const qs = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+  return res.redirect(`${WEB_REDIRECT_ORIGIN.replace(/\/+$/, '')}${apiBase(req)}/auth/discord/start${qs}`);
+}
+
 // Validate a caller-supplied post-sign-in return target. Accept ONLY:
 //   - a relative path beginning with a single '/' (not '//', no backslash), or
 //   - an absolute https URL whose host is the apex or a *.example.com sub.
@@ -433,6 +583,9 @@ module.exports = function buildAuthRouter() {
   registerSeams();
   const router = express.Router();
 
+  // Runs ahead of every API route on this router (task 1004357) — see the helper.
+  router.use(migrateLegacySessionCookie);
+
   // /auth/device — CLI flow
   // rank: public — auth flow itself; identity establishment, not authorization.
   router.post('/auth/device/start', async (_req, res) => {
@@ -524,12 +677,43 @@ module.exports = function buildAuthRouter() {
 
   // /auth/web — browser flow (used by the /builders page).
   // rank: public — entry into the GitHub OAuth handshake.
-  router.get('/auth/web/start', (req, res) => {
+  router.get('/auth/web/start', async (req, res) => {
     // Either direct-GitHub creds OR platform-IdP federation must be configured
     // (ADR 0141 §1) — a federated instance has no GitHub app of its own.
     if (!auth.authConfigured() && !auth.idpConfigured()) {
       return res.status(503).type('text/plain').send('auth not configured');
     }
+    const wantsRepos = req.query.repos === '1' || req.query.repos === 'true';
+    // A sign-in begun on a satellite hub host (builders./status.) restarts on
+    // the canonical host (task 1004357). The handshake cookies are host-only now,
+    // and the callback always lands on the canonical host, so a state cookie set
+    // here could never be read back there. The return target is made absolute
+    // first, so the builder still lands back on THIS host — via the handoff.
+    const host = reqHost(req);
+    if (isSatelliteHubHost(host)) {
+      const raw = safeReturnTo(req.query.return) || safeReturnTo(req.headers.referer) || '/';
+      const back = raw.startsWith('/') ? `https://${host}${raw}` : raw;
+      const params = new URLSearchParams({ return: back });
+      if (wantsRepos) params.set('repos', '1');
+      return res.redirect(`${WEB_REDIRECT_ORIGIN.replace(/\/+$/, '')}${apiBase(req)}/auth/web/start?${params}`);
+    }
+    // Already signed in on the canonical host and headed for a satellite hub
+    // host (a builder who signed in on the apex, then opened builders.): no
+    // GitHub round-trip, just hand that host its copy. A repo-scope sign-in
+    // still goes to GitHub — it exists to ask for the broader grant.
+    if (!wantsRepos) {
+      const target = safeReturnTo(req.query.return);
+      if (target && !target.startsWith('/')) {
+        try {
+          const live = await liveSessionToken(req);
+          const url = live && handoffUrlFor(req, target, live.token, live.expires);
+          if (url) return res.redirect(url);
+        } catch (err) {
+          // A lookup failure falls through to an ordinary sign-in.
+          log.error('[auth] web/start: session lookup failed', err);
+        }
+      }
+    }
     const state = crypto.randomBytes(16).toString('hex');
     // redirect_uri is PINNED to the canonical origin (#734) — never derived from
     // the request host. GitHub only knows the apex callback, so a sign-in begun
@@ -541,9 +725,9 @@ module.exports = function buildAuthRouter() {
       sameSite: 'lax',
       secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
       maxAge: HANDSHAKE_COOKIE_MS,
-      // Apex-scoped (#734) so the state survives the host switch: start may run
-      // on the subdomain but the callback always lands on the apex.
-      ...sessionCookieDomainOpts(req),
+      // Host-only (task 1004357). It used to be apex-scoped (#734) so a start on
+      // a subdomain could reach the apex callback; that start now restarts on
+      // the canonical host instead (above), so the state never crosses a host.
     });
     // Post-sign-in return target (#726/#734): an explicit ?return= wins (set by
     // the page gates); otherwise fall back to the Referer (the page that kicked
@@ -557,22 +741,19 @@ module.exports = function buildAuthRouter() {
         sameSite: 'lax',
         secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
         maxAge: HANDSHAKE_COOKIE_MS,
-        ...sessionCookieDomainOpts(req),
       });
     }
     // Opt-in repo access (task 1002099 / ADR 0143): the onboarding wizard passes
     // ?repos=1 so it can list/create the user's repos. Remember the intent in a
     // short-lived cookie (same recipe as the state cookie) and request the broader
     // scope on the direct-GitHub leg. Absent the flag this is a no-op — hall + CLI
-    // sign-ins stay identity-only.
-    const wantsRepos = req.query.repos === '1' || req.query.repos === 'true';
+    // sign-ins stay identity-only. (wantsRepos is read at the top of the handler.)
     if (wantsRepos) {
       res.cookie(REPOS_COOKIE, '1', {
         httpOnly: true,
         sameSite: 'lax',
         secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
         maxAge: HANDSHAKE_COOKIE_MS,
-        ...sessionCookieDomainOpts(req),
       });
     }
     // Federate through the hub when configured (ADR 0141 §1); otherwise the direct
@@ -583,6 +764,32 @@ module.exports = function buildAuthRouter() {
       : auth.buildAuthorizeUrl(state, redirectUri, { repos: wantsRepos }));
   });
 
+  // GET /auth/web/handoff?code=&return= — the far side of the one-time session
+  // handoff (task 1004357). The canonical host minted `code` for THIS host after
+  // a sign-in (or for a builder already signed in there); trading it sets this
+  // host's own host-only copy of the session, then lands on `return` — a
+  // relative path only, so the handoff can never become an open redirect.
+  //
+  // rank: public — auth establishment; the one-time code is the bearer, bound to
+  //   this exact host, single-use and alive for HANDOFF_TTL_MS.
+  router.get('/auth/web/handoff', (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    // The URL carries a bearer code: never let it ride out in a Referer.
+    res.set('Referrer-Policy', 'no-referrer');
+    const host = reqHost(req);
+    const grant = isSatelliteHubHost(host) ? redeemHandoffCode(req.query.code, host) : null;
+    if (!grant) {
+      return res.status(400).type('text/html').send(renderAuthErrorPage(
+        'Sign-in link expired',
+        `This one-time sign-in link was already used, has expired (they last ${HANDOFF_TTL_MS / 1000} seconds) or belongs to another address. Sign in again.`,
+        { startHref: `${apiBase(req)}/auth/web/start` },
+      ));
+    }
+    setSessionCookie(req, res, grant.token, grant.expires ? new Date(grant.expires) : undefined);
+    const back = safeReturnTo(req.query.return);
+    res.redirect(back && back.startsWith('/') ? back : '/');
+  });
+
   // GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage
   // polls (task 1002097). Answers ONE question: would this login be admitted
   // right now? It mirrors the real gate via auth.webAdmissionStatus so the page
@@ -667,20 +874,10 @@ module.exports = function buildAuthRouter() {
       const { token, expiresAt, builder, githubToken, githubScope } = auth.idpConfigured()
         ? await auth.completeIdpFlow({ code, redirectUri, userAgent: req.headers['user-agent'] })
         : await auth.completeWebFlow({ code, redirectUri, userAgent: req.headers['user-agent'], captureRepoToken: wantsRepos });
-      res.cookie(SESSION_COOKIE, token, {
-        httpOnly: true,
-        sameSite: 'lax',
-        secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
-        path: '/',
-        expires: expiresAt,
-        // Apex-scoped on the production hosts so one sign-in spans
-        // example.com + builders. + status. (#726); host-only elsewhere.
-        ...sessionCookieDomainOpts(req),
-      });
-      // A browser arriving with an older session name must not keep it: two
-      // session cookies means every later request carries two candidate tokens,
-      // and the stale one outlives this sign-in.
-      clearSupersededSessionCookies(req, res);
+      // Host-only on every host (task 1004357) — setSessionCookie also clears
+      // every older name and the legacy apex-scoped copy, so a browser arriving
+      // with either leaves holding only the host-only cookie.
+      setSessionCookie(req, res, token, expiresAt);
       // Persist the wizard's repo token (task 1002099 / ADR 0143): encrypted at rest,
       // short-TTL, keyed to the builder — the repo picker/creator reads it back over
       // the next few minutes. Gated on secret-box being configured (upsertGithubToken
@@ -692,10 +889,9 @@ module.exports = function buildAuthRouter() {
           log.error('[gds] web/callback: repo-token capture failed (non-blocking):', e.message);
         }
       }
-      // The state cookie is apex-scoped now (#734) — clear it with the same
-      // domain or the browser keeps it. Clear the host-only form too for any
-      // cookie set before this change. Clear the repos-intent cookie the same way.
-      const domainOpts = sessionCookieDomainOpts(req);
+      // The handshake cookies are host-only now (task 1004357). Clear the legacy
+      // apex-scoped form too, for a handshake begun before that change.
+      const domainOpts = legacyApexCookieOpts(req);
       res.clearCookie(STATE_COOKIE);
       res.clearCookie(STATE_COOKIE_LEGACY);
       res.clearCookie(REPOS_COOKIE);
@@ -709,8 +905,12 @@ module.exports = function buildAuthRouter() {
       // configured post-login landing (default '/builders'; cloudbongos.com →
       // '/', its landing page — task 1002240).
       const returnTo = safeReturnTo(parseCookie(req, RETURN_COOKIE));
-      res.clearCookie(RETURN_COOKIE, domainOpts);
-      res.redirect(returnTo || postLoginLanding());
+      res.clearCookie(RETURN_COOKIE);
+      if (domainOpts.domain) res.clearCookie(RETURN_COOKIE, domainOpts);
+      // Headed for builders./status.? Their cookie cannot be set from here, so
+      // hand them the session through the one-time code (task 1004357).
+      const handoff = returnTo && !returnTo.startsWith('/') && handoffUrlFor(req, returnTo, token, expiresAt);
+      res.redirect(handoff || returnTo || postLoginLanding());
     } catch (err) {
       // Approval gate (2026-05-30): a first-time GitHub account that hasn't been
       // approved by an Archon can't enter. Send them to the hall to request
@@ -804,7 +1004,7 @@ module.exports = function buildAuthRouter() {
   // (503) until the server has Discord client creds. Mirrors the GitHub web
   // flow's CSRF-state discipline above — a hard requirement (ADR 0033 §2).
   // rank: any-builder — links to your OWN identity; no rank gate.
-  router.get('/auth/discord/start', auth.requireBuilder, (req, res) => {
+  router.get('/auth/discord/start', discordStartOnCanonicalHost, auth.requireBuilder, (req, res) => {
     if (!auth.discordConfigured()) {
       return res.status(503).type('text/plain').send('Discord linking not configured on this server yet.');
     }
@@ -815,12 +1015,9 @@ module.exports = function buildAuthRouter() {
       sameSite: 'lax',
       secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
       maxAge: 10 * 60 * 1000,
-      // Apex-scoped (#734 parity) so the state survives the host switch: the
-      // link may start on builders.example.com but DISCORD_REDIRECT_URI
-      // always lands the callback on the apex. A host-only cookie would be
-      // dropped on the hop and the state check would fail ("Link handshake
-      // expired"). Mirrors the GitHub web-flow state cookie above.
-      ...sessionCookieDomainOpts(req),
+      // Host-only (task 1004357). DISCORD_REDIRECT_URI always lands the callback
+      // on the canonical host, so a link begun on builders. first restarts
+      // there (discordStartOnCanonicalHost) — the state never crosses a host.
     });
     res.redirect(auth.buildDiscordAuthorizeUrl(state, redirectUri));
   });
@@ -832,10 +1029,8 @@ module.exports = function buildAuthRouter() {
     }
     const expectedState = parseCookie(req, DISCORD_STATE_COOKIE);
     const { state, code, error } = req.query;
-    // The state cookie is apex-scoped now (#734 parity) — clear it with the
-    // same domain or the browser keeps it. Clear the host-only form too for any
-    // cookie set before this change.
-    const stateDomainOpts = sessionCookieDomainOpts(req);
+    // Host-only now (task 1004357); clear the legacy apex-scoped form too.
+    const stateDomainOpts = legacyApexCookieOpts(req);
     res.clearCookie(DISCORD_STATE_COOKIE);
     if (stateDomainOpts.domain) res.clearCookie(DISCORD_STATE_COOKIE, stateDomainOpts);
     // CSRF FIRST: validate the state cookie against the state Discord echoes
@@ -962,15 +1157,12 @@ module.exports = function buildAuthRouter() {
     const token = (req.headers['authorization'] || '').replace(/^Bearer\s+/, '')
       || sessionCookieToken(req);
     if (token) await db.revokeSession(token);
-    // Clear BOTH the host-only form (older sessions) and the apex-scoped form
-    // (#726) — a clearCookie only matches the cookie whose domain attribute it
-    // names, so sign-out on a production host must target the apex domain too.
-    res.clearCookie(SESSION_COOKIE);
-    const domainOpts = sessionCookieDomainOpts(req);
-    if (domainOpts.domain) res.clearCookie(SESSION_COOKIE, domainOpts);
-    // …and every superseded name, or a sign-out leaves the older cookie behind
-    // and the next request re-authenticates on it.
-    clearSupersededSessionCookies(req, res);
+    // Clear every session name, host-only AND the legacy apex-scoped form — a
+    // clearCookie only matches the cookie whose domain attribute it names, and a
+    // sign-out that left one behind would re-authenticate the next request.
+    // The token itself is revoked above, which also kills the copies the
+    // handoff gave the hub's other hosts (they share it).
+    clearSupersededSessionCookies(req, res, { all: true });
     // Federated single-logout (ADR 0144, task 1002238): announce the logout so the
     // hub (platform-identity, enabled only on cloudbongos.com) can fan a signed
     // back-channel logout out to every federated project this builder entered. A
@@ -1170,7 +1362,13 @@ module.exports.safeReturnTo = safeReturnTo;
 module.exports.postLoginLanding = postLoginLanding;
 module.exports.recoveryStartHref = recoveryStartHref;
 module.exports.HANDSHAKE_COOKIE_MS = HANDSHAKE_COOKIE_MS;
-module.exports.sessionCookieDomainOpts = sessionCookieDomainOpts;
+module.exports.legacyApexCookieOpts = legacyApexCookieOpts;
+module.exports.setSessionCookie = setSessionCookie;
+module.exports.sessionCookieName = sessionCookieName;
+module.exports.mintHandoffCode = mintHandoffCode;
+module.exports.redeemHandoffCode = redeemHandoffCode;
+module.exports.handoffUrlFor = handoffUrlFor;
+module.exports.HANDOFF_TTL_MS = HANDOFF_TTL_MS;
 module.exports.reqHost = reqHost;
 // The auth-error page renderer (task 1439): pure over the branding pack, so a
 // test can prove every visible string is brand-owned (no OTB lore baked in).

package/src/bongos/routes/modules.js

@@ -23,6 +23,9 @@
 //                               server end of `bongos module publish`. Not the
 //                               upstreaming door above: submit proposes a module
 //                               INTO core; publish puts a version in the store.
+//   GET  /store/entitlements   the modules the caller holds, and at which version
+//   GET  /store/modules/:key/entitlement
+//                               does the caller hold this module (task 1003813).
 //
 // Read is open to any signed-in builder (same gate as the atlas/primer pages);
 // every write (enable/disable, submit) is metic+archon, same rank as
@@ -65,6 +68,7 @@ const modulesLib = require('../../modules');
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
 const moduleArtifact = require('../../../scripts/gds/module-artifact');
+const { checkEntitlement, listEntitlements } = require('../module-entitlements');
 const { stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion } = require('../module-store');
 const { KEY_RE } = require('../../module-loader/manifest-schema');
 // Named imports, not a namespace object (task 1004052 strand walk): knip cannot follow
@@ -347,6 +351,31 @@ module.exports = function buildModulesRouter() {
       res.status(201).json({ ok: true, created_module: result.created, version: result.version });
     }));
 
+  // GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the
+  // read side of the entitlement record (task 1003813, ADR 0338 D1). Own-scoped
+  // like /me/sessions: the holder is ALWAYS the caller (holder_kind 'builder',
+  // holder_ref = req.builder.id), never named in the query or path, so requireBuilder
+  // alone is the gate and one builder cannot read another's holdings. Granting has no
+  // route yet: install (task 1003785) grants a free module, area 8's buy action
+  // grants a paid one — both through src/bongos/module-entitlements.js.
+  router.get('/store/entitlements', auth.requireBuilder,
+    asyncHandler('GET /store/entitlements', async (req, res) => {
+      const entitlements = await listEntitlements({ holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json({ entitlements });
+    }));
+
+  router.get('/store/modules/:key/entitlement', auth.requireBuilder,
+    asyncHandler('GET /store/modules/:key/entitlement', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) {
+        return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      }
+      const held = await checkEntitlement({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json(held);
+    }));
+
   return router;
 };
 

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.19.1076'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1078'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');