disclose what the session.cookieCache door costs, measured against better-auth 1.7.1 (#12735)

* disclose what the cookieCache door costs, measured against better-auth 1.7.1

Extends the #4785 opt-in-with-disclosed-cost posture to `session.cookieCache`,
the sibling key of `secondaryStorage`. No boot refusal, no config rejection,
no narrowing of what `AuthManagerOptions` accepts — the ruled posture is
disclosure, and the disclosure is now written where a future author would
plumb the key.

Adds an end-of-chain observation pin: a host-supplied `session.cookieCache`
is dropped rather than honoured today, so revocation still de-authenticates
on the next request.

Co-authored-by: Claude <noreply@anthropic.com>

* add the changeset: the CHANGELOG is where the sibling door's posture lives

An operator weighing `cookieCache` reads the changelog, not our TSDoc. One
door's cost being on the public record while its sibling's is not is the
asymmetry this closes.

Co-authored-by: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/plugin-auth-cookiecache-cost-disclosure.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+docs(plugin-auth): state what the `session.cookieCache` door costs, measured against better-auth 1.7.1 (#12547)
+
+No behaviour change, no API change, and ⛔ **no boot refusal** — the #4785
+posture stands on both doors: deliberate opt-in with the cost disclosed
+(maintainer ruling 2026-08-27). `cacheSecondaryStorage()` stays exported and
+`AuthManagerOptions` accepts exactly what it accepted before.
+
+This is shipped as a changeset rather than left in source comments because the
+CHANGELOG is where the sibling door's posture already lives — *"remains
+exported for anyone who wants better-auth's cached session store deliberately.
+It now says plainly what it costs."* An operator weighing `cookieCache` reads
+the changelog, not our TSDoc, and one door's cost being on the public record
+while its sibling's is not is the asymmetry this closes.
+
+**What was measured**, against the installed better-auth `1.7.1` (read out of
+`node_modules`, never off the `^1.7.1` range):
+
+- **The failure direction is the sibling's.** With `cookieCache` enabled,
+  `/get-session` answers from a signed payload in the client's own
+  `session_data` cookie and returns before any adapter read. ObjectStack
+  revokes by writing the `sys_session` row (ADR-0069 D4) and hides tombstoned
+  rows from better-auth's reads — all read-path enforcement, so while the
+  cookie answers, a revoked session keeps authenticating and nobody gets an
+  error.
+- ⭐ **The reach is materially smaller, and the disclosure says so rather than
+  inheriting the sibling's wording.** The session of record does not move —
+  `createSession` still writes the row, so admin session lists, the
+  concurrent-cap count and D4's audit trail stay correct. The staleness window
+  is bounded and per-client (`cookieCache.maxAge`, default 300s) and cannot be
+  extended without a database read, because better-auth force-disables its
+  stateless `refreshCache` whenever a `database` is configured — which
+  ObjectStack always does. Sensitive operations already bypass it via
+  better-auth's own authoritative re-read. `secondaryStorage` has none of these
+  three bounds.
+- **It is not reachable from ObjectStack config today, by construction rather
+  than by refusal.** The spec's `AuthConfigSchema.session` declares
+  `expiresIn` / `updateAge` only and `createAuthInstance` reads only those two,
+  so a `cookieCache` key is dropped rather than honoured. The one way in is the
+  `authInstance` escape hatch, where the host has replaced the whole config.
+
+The disclosure lands at `auth-manager.ts`'s `session:` block — the place a
+future author would plumb the key — with a pointer from `secondary-storage.ts`
+so the two doors are described together. An **observation** pin in
+`session-of-record.test.ts` records the drop end-of-chain: a revoked session
+still de-authenticates on the very next request. ⛔ It pins no refusal; it is
+the tripwire a paragraph alone could not give, so the day someone plumbs
+`cookieCache` through, a red test points at the cost note instead of D4
+quietly acquiring a revocation window nobody chose.

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -1379,6 +1379,62 @@ export class AuthManager {
       } : {}),
 
       // Session configuration
+      //
+      // ⚠️ `session.cookieCache` is the OTHER door into the architecture #4785
+      // rejected, and it is deliberately not opened here. What that costs, and
+      // what is actually known about it, measured 2026-08-27 against the
+      // installed better-auth `1.7.1` (read out of `node_modules`, never off
+      // the `^1.7.1` range) — each claim names the file it came from so a
+      // version bump is re-checkable one grep at a time:
+      //
+      //  - **The failure DIRECTION is the sibling's.** With `cookieCache`
+      //    enabled, `/get-session` answers from a signed payload in the
+      //    client's own `session_data` cookie and returns before any adapter
+      //    read (`dist/api/routes/session.mjs:48-130`). ObjectStack revokes by
+      //    writing the `sys_session` row — `enforceSessionControls` /
+      //    `enforceConcurrentCap` stamp `revoked_at` + a past `expires_at`
+      //    (ADR-0069 D4), and `hideRevokedSessionRow` hides a tombstoned row
+      //    from better-auth's reads (`session-tombstone.ts`). All of it is
+      //    read-path enforcement, so for as long as the cookie answers, a
+      //    revoked session keeps authenticating and nobody gets an error. Same
+      //    silent direction as `secondaryStorage` (see `secondary-storage.ts`).
+      //
+      //  - ⭐ **The REACH is materially smaller, and saying so is the point.**
+      //    Three differences, all measured, not inferred:
+      //    1. The session of RECORD does not move. `cookieCache` is read-side
+      //       only — `createSession` still writes the `sys_session` row, so
+      //       admin session lists, the concurrent-cap count and D4's audit
+      //       trail all stay correct. `secondaryStorage` skips the row.
+      //    2. The staleness window is BOUNDED and per-client:
+      //       `cookieCache.maxAge`, default 300s (`dist/cookies/index.mjs:50`,
+      //       `:99`). It cannot be extended without a database read either —
+      //       better-auth force-disables the stateless `refreshCache` whenever
+      //       a `database` is configured, which ObjectStack always does
+      //       (`dist/context/create-context.mjs:149-165`). Under
+      //       `secondaryStorage` the cache IS the record and the window has no
+      //       bound at all.
+      //    3. Sensitive operations already bypass it: better-auth's own
+      //       `getAuthoritativeSessionFromCtx` / `sensitiveSessionMiddleware`
+      //       re-read with `disableCookieCache: true` when a `database` is
+      //       configured (`dist/api/routes/session.mjs:270-280`). There is no
+      //       equivalent escape from `secondaryStorage`.
+      //
+      //  - **It is not reachable from ObjectStack config today, by
+      //    construction rather than by refusal.** The spec's
+      //    `AuthConfigSchema.session` declares `expiresIn` / `updateAge` only,
+      //    and this block reads only those two, so a `cookieCache` key on
+      //    `AuthManagerOptions.session` is DROPPED, not honoured — pinned
+      //    end-of-chain in `session-of-record.test.ts`. The one way in is
+      //    `authInstance`, where the host has replaced this whole config.
+      //
+      // ⛔ So this is a disclosed cost on a door a host must build to reach —
+      // NOT a guard, and deliberately not one. The #4785 posture is opt-in with
+      // the cost stated (maintainer ruling 2026-08-27), the same posture
+      // `cacheSecondaryStorage()` is exported under. Plumbing `cookieCache`
+      // through is therefore a decision that re-opens #4785, not a feature: it
+      // would trade D4's revocation latency for request latency, and the trade
+      // has to be made deliberately, by a maintainer, with the window written
+      // down. If you are here to add it, that ruling is what you need first.
       session: {
         ...AUTH_SESSION_CONFIG,
         expiresIn: this.config.session?.expiresIn || 60 * 60 * 24 * 7, // 7 days default

packages/plugins/plugin-auth/src/secondary-storage.ts

@@ -36,6 +36,18 @@ type SecondaryStorage = NonNullable<BetterAuthOptions['secondaryStorage']>;
  * cache at all (and rewrite D4's revocation to match) is #4785 — a decision,
  * not a bug fix.
  *
+ * ⚠️ **`session.cookieCache` is the sibling key, and its cost is NOT the same
+ * size.** It reaches the same read-path failure direction — a revoked session
+ * keeps authenticating, silently — but the session of record stays in
+ * `sys_session`, the window is bounded by `cookieCache.maxAge` (default 300s)
+ * rather than unbounded, and better-auth's own sensitive-operation path
+ * re-reads with the cookie cache disabled. It is also not reachable through
+ * `AuthManagerOptions`. The measurement, with the better-auth files each claim
+ * was read out of, is at `auth-manager.ts`'s `session:` block — the place a
+ * future author would plumb it. ⛔ Neither door is boot-refused by
+ * ObjectStack, and that is the ruled posture, not a gap: opt-in with the cost
+ * stated. Adding a refusal to either needs a new maintainer ruling.
+ *
  * better-auth's `secondaryStorage` contract is string-valued: `get` returns the
  * stored string (or null), `set` takes a string value + optional TTL (seconds),
  * `delete` removes it. We map straight onto `ICacheService`, translating

packages/plugins/plugin-auth/src/session-of-record.test.ts

@@ -476,6 +476,55 @@ describe('#4785 — why cache is NOT the session store (the rejected architectur
     expect(sessionRows(engine)).toHaveLength(0);
   });
 
+  it('session.cookieCache is not reachable through config either — asking for it changes nothing', async () => {
+    // The OTHER door into the same read-path failure, pinned the same way as
+    // option C above and for the same reason: `AuthManager` builds better-auth's
+    // `session` block from `AUTH_SESSION_CONFIG` plus `expiresIn`/`updateAge`
+    // only, so a host that asks for `cookieCache` is silently NOT getting it.
+    //
+    // ⛔ This is an OBSERVATION pin, not a refusal — nothing here rejects the
+    // key, and nothing should: the ruled posture (maintainer, 2026-08-27) is
+    // opt-in with the cost disclosed on BOTH doors, exactly as
+    // `cacheSecondaryStorage()` stays exported. What this pin buys is the
+    // tripwire the disclosure alone could not give: the day someone plumbs
+    // `cookieCache` through, this test goes red and points them at the cost
+    // note in `auth-manager.ts` instead of letting D4 quietly acquire a
+    // revocation window nobody chose.
+    //
+    // End-of-chain, per this file's header — asserting "the emitted options
+    // carry no cookieCache" would be the middle of the chain and would pass
+    // against a build that reached the cache some other way. If the key were
+    // honoured, sign-up would mint a `session_data` cookie (which `cookieFrom`
+    // collects, so it really would be replayed below), `/get-session` would
+    // answer from that payload without an adapter read for up to
+    // `maxAge` (default 300s), and the revoked cookie would still
+    // authenticate. It must not.
+    const engine = createMemoryEngine();
+    const manager = makeManager(engine, {
+      sessionIdleTimeoutMinutes: 30,
+      session: { cookieCache: { enabled: true, maxAge: 300 } },
+    });
+
+    const cookie = cookieFrom(await signUp(manager, 'cookiecache@example.com'));
+    const id = sessionRows(engine)[0]!.id;
+
+    // The row is still the session of record: unlike `secondaryStorage`,
+    // `cookieCache` never relocates it even when it IS honoured.
+    expect(sessionRows(engine)).toHaveLength(1);
+    expect(await isAuthenticated(manager, cookie)).toBe(true);
+
+    ageSession(engine, id, { last_activity_at: new Date(Date.now() - 90 * MINUTE) });
+
+    // Same one-request lag as every other D4 control: the request that detects
+    // the timeout is still authenticated, the next one is not.
+    expect(await isAuthenticated(manager, cookie)).toBe(true);
+    expect(sessionRows(engine).find((r) => r.id === id)!.revoke_reason).toBe('idle_timeout');
+
+    // The assertion that matters, and the one a honoured `cookieCache` breaks:
+    // the cookie is dead on the very next request, not 300 seconds later.
+    expect(await isAuthenticated(manager, cookie)).toBe(false);
+  });
+
   it('the DEFAULT composition refuses to boot with a secondaryStorage rather than degrading quietly', async () => {
     // The safety net under all of the above, and the reason this hole could
     // never have opened silently in a standard `serve`: the OIDC provider