@takosjp/yurucommu-core 3.2.0 → 3.2.1

package/src/backend/lib/notification-eligibility.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared social-notification eligibility predicates.
+ *
+ * SINGLE owner of the WHERE fragments that decide whether an inbox row is a
+ * user-facing notification. Consumed by ALL of:
+ *   - GET /api/notifications (list),
+ *   - GET /api/notifications/unread/count (badge),
+ *   - the push outbox processor (delivery-time re-check + push unread badge)
+ * so a change to eligibility (a new activity type, a new suppression rule)
+ * cannot silently drift between the list, the badge, and push delivery — the
+ * dispersion that past audits repeatedly flagged for visibility logic.
+ */
+
+import {
+  and,
+  eq,
+  exists,
+  inArray,
+  isNull,
+  ne,
+  notExists,
+  or,
+  type SQL,
+} from "drizzle-orm";
+
+import {
+  activities,
+  dmArchivedConversations,
+  inbox,
+  notificationArchived,
+  objects,
+  type Database,
+} from "../../db/index.ts";
+import { excludeBlockedMutedAuthors } from "./feed-exclude.ts";
+
+/**
+ * The activity types that surface as notifications. Any addition must hold for
+ * the list, the unread badge, AND push delivery — they all read this constant.
+ */
+export const NOTIFICATION_ACTIVITY_TYPES = [
+  "Follow",
+  "Like",
+  "Announce",
+  "Create",
+] as const;
+
+export interface NotificationEligibilityOptions {
+  /**
+   * How direct-visibility (DM) Creates are treated:
+   * - "exclude" (list/badge): a DM surfaces in the DM view, never as a
+   *   notification row, so drop it entirely.
+   * - "unless-dm-archived" (push): a direct Create IS push-eligible (routed to
+   *   Yurume), unless the recipient archived the conversation — archiving is a
+   *   delivery preference, not merely a presentation filter.
+   */
+  readonly direct: "exclude" | "unless-dm-archived";
+  /**
+   * Archive partition. "exclude" (default: badge/push and the default list
+   * view) hides archived rows; "only" (the list's archived view) shows ONLY
+   * archived rows.
+   */
+  readonly archived?: "exclude" | "only";
+  /**
+   * Restrict to a subset of NOTIFICATION_ACTIVITY_TYPES (the list's type
+   * filter). Defaults to the full set; callers must not widen it.
+   */
+  readonly activityTypes?: readonly string[];
+}
+
+/**
+ * Eligibility conditions for a query shaped as
+ * `inbox JOIN activities LEFT JOIN objects` scoped to `actorApId`'s inbox.
+ * Returns the shared conditions only; callers add their own paging/read/type
+ * filters on top.
+ */
+export function notificationEligibilityWhere(
+  db: Database,
+  actorApId: string,
+  options: NotificationEligibilityOptions,
+): SQL[] {
+  // Never notify an actor about their own activity.
+  const notSelf = ne(activities.actorApId, actorApId);
+
+  // Only user-facing activity types.
+  const userFacingType = inArray(activities.type, [
+    ...(options.activityTypes ?? NOTIFICATION_ACTIVITY_TYPES),
+  ]);
+
+  // Archive partition. Archived notifications are hidden from the default
+  // list, excluded from the badge, and must not push; the list's archived view
+  // inverts the predicate.
+  const archivedSubquery = db
+    .select({ activityApId: notificationArchived.activityApId })
+    .from(notificationArchived)
+    .where(
+      and(
+        eq(notificationArchived.actorApId, inbox.actorApId),
+        eq(notificationArchived.activityApId, inbox.activityApId),
+      ),
+    );
+  const notArchived =
+    options.archived === "only"
+      ? exists(archivedSubquery)
+      : notExists(archivedSubquery);
+
+  // Direct (DM) handling. The object join is LEFT (Follow's object is an
+  // actor, not an objects row), so NULL visibility must be kept.
+  let directCondition: SQL;
+  if (options.direct === "exclude") {
+    directCondition = or(
+      isNull(objects.visibility),
+      ne(objects.visibility, "direct"),
+    )!;
+  } else {
+    const archivedDmSubquery = db
+      .select({ conversationId: dmArchivedConversations.conversationId })
+      .from(dmArchivedConversations)
+      .where(
+        and(
+          eq(dmArchivedConversations.actorApId, actorApId),
+          eq(dmArchivedConversations.conversationId, objects.conversation),
+        ),
+      );
+    directCondition = or(
+      isNull(objects.visibility),
+      ne(objects.visibility, "direct"),
+      notExists(archivedDmSubquery),
+    )!;
+  }
+
+  const conditions: SQL[] = [
+    notSelf,
+    userFacingType,
+    notArchived,
+    directCondition,
+  ];
+
+  // Suppress notifications whose actor the recipient has blocked or muted.
+  // This is the read-time choke point: mutes are read-only everywhere, and not
+  // every notify WRITE path block-checks, so gating here covers like/repost/
+  // follow/reply/mention (local AND federated) for both blocks and mutes.
+  const blockMute = excludeBlockedMutedAuthors(
+    db,
+    actorApId,
+    activities.actorApId,
+  );
+  if (blockMute) conditions.push(blockMute);
+
+  return conditions;
+}

package/src/backend/lib/notification-push.ts

@@ -1,25 +1,11 @@
 import type { Message } from "@cloudflare/workers-types";
-import {
-  and,
-  asc,
-  eq,
-  exists,
-  inArray,
-  isNull,
-  lte,
-  ne,
-  notExists,
-  or,
-  sql,
-} from "drizzle-orm";
+import { and, asc, eq, exists, inArray, lte, ne, sql } from "drizzle-orm";
 
 import {
   activities,
   affectedRowCount,
   communityMembers,
-  dmArchivedConversations,
   inbox,
-  notificationArchived,
   notificationPushers,
   notificationPushJobs,
   objectRecipients,
@@ -41,6 +27,11 @@ import {
   type DeliveryQueueMessageV1,
 } from "./delivery/types.ts";
 import { excludeBlockedMutedAuthors } from "./feed-exclude.ts";
+import {
+  NOTIFICATION_ACTIVITY_TYPES,
+  notificationEligibilityWhere,
+} from "./notification-eligibility.ts";
+import { yurumeUnreadCounts } from "./unread-counts.ts";
 import { logger } from "./logger.ts";
 import { generateId } from "./oauth-utils.ts";
 
@@ -53,17 +44,21 @@ export const MAX_NOTIFICATION_PUSH_ATTEMPTS = 5;
 export const NOTIFICATION_PUSHER_RETENTION_DAYS = 90;
 export const NOTIFICATION_PUSH_JOB_RETENTION_DAYS = 90;
 export const MAX_NOTIFICATION_PUSH_JOB_PURGE = 50;
+export const MAX_NOTIFICATION_PUSHER_PURGE = 50;
 
 const DEFAULT_GATEWAY_TIMEOUT_MS = 10_000;
 const MAX_GATEWAY_RESPONSE_BYTES = 64 * 1024;
 const MAX_QUEUE_SCAN = 50;
 const STALE_PROCESSING_MS = 2 * 60 * 1000;
-const SOCIAL_NOTIFICATION_ACTIVITY_TYPES = [
-  "Follow",
-  "Like",
-  "Announce",
-  "Create",
-] as const;
+// A 'queued'/'processing' row whose queue message is GONE (auto-dead-lettered
+// after max retries with the raw body, dropped after queue retention, consumer
+// down long enough) is otherwise unreachable: the sweep sends only
+// pending/retry_wait and message-based recovery needs a message. Reclaim such
+// rows to 'pending' once they are far staler than any live in-flight state —
+// a live processing owner refreshes its lease before every gateway call
+// (≤ ~40s between touches) and a queued message is consumed or dead-lettered
+// within minutes.
+const STALE_INFLIGHT_RECLAIM_MS = 15 * 60 * 1000;
 
 export interface NotificationPusherRegistrationResponse {
   readonly id: string;
@@ -330,22 +325,58 @@ export function buildNotificationPushMessage(
 export async function enqueuePendingNotificationPushJobs(
   env: Env,
 ): Promise<number> {
-  // Terminal rows are retained long enough to preserve the deterministic job
+  const db = env.DB_INSTANCE;
+  // Expired rows are retained long enough to preserve the deterministic job
   // idempotency window, then removed opportunistically in a bounded batch.
   // This runs even without a Queue binding so disabled push delivery cannot
-  // turn the outbox ledger into unbounded storage.
-  await purgeExpiredNotificationPushJobs(env.DB_INSTANCE);
+  // turn the outbox ledger into unbounded storage. Stale pushers are purged
+  // here too (bounded), NOT inside per-job processing.
+  await purgeExpiredNotificationPushJobs(db);
+  await purgeExpiredNotificationPushers(db);
   if (!env.DELIVERY_QUEUE) return 0;
   const now = new Date().toISOString();
-  const rows = await env.DB_INSTANCE.select({ id: notificationPushJobs.id })
+
+  // Reclaim in-flight rows whose queue message is gone (see
+  // STALE_INFLIGHT_RECLAIM_MS). The reclaim consumes one attempt so a
+  // crash-looping job terminates at the same MAX_NOTIFICATION_PUSH_ATTEMPTS
+  // budget instead of ping-ponging forever.
+  const staleCutoff = new Date(
+    Date.now() - STALE_INFLIGHT_RECLAIM_MS,
+  ).toISOString();
+  await db
+    .update(notificationPushJobs)
+    .set({
+      status: sql`CASE WHEN ${notificationPushJobs.attempts} + 1 >= ${MAX_NOTIFICATION_PUSH_ATTEMPTS} THEN 'failed' ELSE 'pending' END`,
+      attempts: sql`${notificationPushJobs.attempts} + 1`,
+      processingToken: null,
+      lastError: sql`COALESCE(${notificationPushJobs.lastError}, 'reclaimed stale in-flight push job')`,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        inArray(notificationPushJobs.status, ["queued", "processing"]),
+        lte(notificationPushJobs.updatedAt, staleCutoff),
+      ),
+    );
+
+  // The trigger creates a job for EVERY unread inbox insert, including
+  // recipients with zero pushers. Only enqueue jobs that can actually deliver;
+  // pusher-less rows stay pending (no queue traffic, no processing cycle) and
+  // age out through the retention purge above.
+  const actorHasPusher = exists(
+    db
+      .select({ id: notificationPushers.id })
+      .from(notificationPushers)
+      .where(eq(notificationPushers.actorApId, notificationPushJobs.actorApId)),
+  );
+  const rows = await db
+    .select({ id: notificationPushJobs.id })
     .from(notificationPushJobs)
     .where(
       and(
-        or(
-          eq(notificationPushJobs.status, "pending"),
-          eq(notificationPushJobs.status, "retry_wait"),
-        ),
+        inArray(notificationPushJobs.status, ["pending", "retry_wait"]),
         lte(notificationPushJobs.nextAttemptAt, now),
+        actorHasPusher,
       ),
     )
     .orderBy(asc(notificationPushJobs.createdAt))
@@ -355,7 +386,8 @@ export async function enqueuePendingNotificationPushJobs(
   await env.DELIVERY_QUEUE.sendBatch(
     rows.map((row) => ({ body: buildNotificationPushMessage(row.id) })),
   );
-  await env.DB_INSTANCE.update(notificationPushJobs)
+  await db
+    .update(notificationPushJobs)
     .set({ status: "queued", processingToken: null, updatedAt: now })
     .where(
       and(
@@ -363,16 +395,82 @@ export async function enqueuePendingNotificationPushJobs(
           notificationPushJobs.id,
           rows.map((row) => row.id),
         ),
-        or(
-          eq(notificationPushJobs.status, "pending"),
-          eq(notificationPushJobs.status, "retry_wait"),
-        ),
+        inArray(notificationPushJobs.status, ["pending", "retry_wait"]),
       ),
     );
   return rows.length;
 }
 
-/** Remove at most one bounded batch of expired terminal delivery jobs. */
+/**
+ * Reset a dead-lettered push job so the durable outbox can retry it. Called by
+ * the DLQ consumer when a `notification_push` message exhausted its Cloudflare
+ * Queue retries with the RAW body (automatic dead-lettering) — without this,
+ * the job row would be stranded in 'queued'/'processing' forever. Consumes one
+ * attempt so a permanently failing job still terminates at the attempts budget.
+ */
+export async function recoverDeadLetteredNotificationPushJob(
+  db: Database,
+  jobId: string,
+): Promise<boolean> {
+  const now = new Date().toISOString();
+  const recovered = await db
+    .update(notificationPushJobs)
+    .set({
+      status: sql`CASE WHEN ${notificationPushJobs.attempts} + 1 >= ${MAX_NOTIFICATION_PUSH_ATTEMPTS} THEN 'failed' ELSE 'retry_wait' END`,
+      attempts: sql`${notificationPushJobs.attempts} + 1`,
+      processingToken: null,
+      nextAttemptAt: now,
+      lastError: sql`COALESCE(${notificationPushJobs.lastError}, 'queue message dead-lettered')`,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(notificationPushJobs.id, jobId),
+        inArray(notificationPushJobs.status, [
+          "pending",
+          "queued",
+          "processing",
+          "retry_wait",
+        ]),
+      ),
+    );
+  return affectedRowCount(recovered) > 0;
+}
+
+/** Remove at most one bounded batch of pushers idle past the retention window. */
+export async function purgeExpiredNotificationPushers(
+  db: Database,
+  now = new Date(),
+): Promise<number> {
+  const cutoff = new Date(
+    now.getTime() - NOTIFICATION_PUSHER_RETENTION_DAYS * 86_400_000,
+  ).toISOString();
+  const stale = await db
+    .select({ id: notificationPushers.id })
+    .from(notificationPushers)
+    .where(lte(notificationPushers.lastSeenAt, cutoff))
+    .orderBy(asc(notificationPushers.lastSeenAt), asc(notificationPushers.id))
+    .limit(MAX_NOTIFICATION_PUSHER_PURGE);
+  if (stale.length === 0) return 0;
+  const deleted = await db.delete(notificationPushers).where(
+    and(
+      inArray(
+        notificationPushers.id,
+        stale.map((row) => row.id),
+      ),
+      lte(notificationPushers.lastSeenAt, cutoff),
+    ),
+  );
+  return affectedRowCount(deleted);
+}
+
+/**
+ * Remove at most one bounded batch of jobs past the retention window. ANY
+ * status qualifies: terminal rows have served their idempotency window, a
+ * pending row that old belongs to a pusher-less recipient (never enqueued —
+ * see the sweep's actorHasPusher filter), and no live in-flight state survives
+ * 90 days (stale queued/processing rows are reclaimed within minutes).
+ */
 export async function purgeExpiredNotificationPushJobs(
   db: Database,
   now = new Date(),
@@ -380,16 +478,10 @@ export async function purgeExpiredNotificationPushJobs(
   const cutoff = new Date(
     now.getTime() - NOTIFICATION_PUSH_JOB_RETENTION_DAYS * 86_400_000,
   ).toISOString();
-  const terminalStatuses = ["delivered", "failed"] as const;
   const expired = await db
     .select({ id: notificationPushJobs.id })
     .from(notificationPushJobs)
-    .where(
-      and(
-        inArray(notificationPushJobs.status, terminalStatuses),
-        lte(notificationPushJobs.updatedAt, cutoff),
-      ),
-    )
+    .where(lte(notificationPushJobs.updatedAt, cutoff))
     .orderBy(asc(notificationPushJobs.updatedAt), asc(notificationPushJobs.id))
     .limit(MAX_NOTIFICATION_PUSH_JOB_PURGE);
   if (expired.length === 0) return 0;
@@ -400,7 +492,6 @@ export async function purgeExpiredNotificationPushJobs(
         notificationPushJobs.id,
         expired.map((row) => row.id),
       ),
-      inArray(notificationPushJobs.status, terminalStatuses),
       lte(notificationPushJobs.updatedAt, cutoff),
     ),
   );
@@ -470,12 +561,17 @@ export async function processNotificationPushJob(
         eq(notificationPushJobs.id, job.id),
         eq(notificationPushJobs.status, job.status),
         eq(notificationPushJobs.updatedAt, job.updatedAt),
+        // Honor the backoff schedule: a duplicate message that survived a
+        // double-enqueue race must not claim a retry_wait row before its
+        // nextAttemptAt, which would bypass exponential backoff / Retry-After
+        // and hammer a gateway that is actively rate-limiting us.
+        lte(notificationPushJobs.nextAttemptAt, now),
       ),
     );
   if (affectedRowCount(claimed) === 0) {
-    // Another Queue delivery owns this job now. Do not ack the competing
-    // message permanently: a retry lets it observe the terminal row or recover
-    // if that owner crashes after claiming.
+    // Another Queue delivery owns this job now, or it is not yet due. Do not
+    // ack the competing message permanently: a retry lets it observe the
+    // terminal row, become due, or recover if that owner crashes after claiming.
     message.retry({ delaySeconds: 30 });
     return;
   }
@@ -503,12 +599,10 @@ export async function processNotificationPushJob(
       (event.visibility === "direct" ? "yurume" : "yurucommu");
     let pendingIds = parsePendingIds(job.pendingPusherIdsJson);
     if (pendingIds === null) {
-      const cutoff = new Date(
-        Date.now() - NOTIFICATION_PUSHER_RETENTION_DAYS * 86_400_000,
-      ).toISOString();
-      await db
-        .delete(notificationPushers)
-        .where(lte(notificationPushers.lastSeenAt, cutoff));
+      // Retention purge of idle pushers is a bounded sweep in
+      // enqueuePendingNotificationPushJobs, NOT an unbounded all-actor DELETE
+      // on this hot per-job path. Stale rows simply resolve to zero deliveries
+      // here and get reaped by the sweep.
       pendingIds = (
         await db
           .select({ id: notificationPushers.id })
@@ -900,7 +994,7 @@ async function loadPushEvent(
         and(
           eq(activities.apId, activityApId),
           ne(activities.actorApId, actorApId),
-          inArray(activities.type, SOCIAL_NOTIFICATION_ACTIVITY_TYPES),
+          inArray(activities.type, [...NOTIFICATION_ACTIVITY_TYPES]),
           exists(currentCommunityMembership),
           excludeBlockedMutedAuthors(db, actorApId, activities.actorApId),
         ),
@@ -910,27 +1004,9 @@ async function loadPushEvent(
 
   // The inbox trigger intentionally captures every unread insert so it cannot
   // lose a notification in a route-specific crash window. Eligibility is
-  // therefore re-checked here immediately before external delivery. This
-  // mirrors the notification list/count choke point: only user-facing activity
-  // types, never self events, never archived rows, and never blocked/muted
-  // senders. Direct Creates remain eligible and are routed to Yurume below.
-  const archivedCorrelation = and(
-    eq(notificationArchived.actorApId, inbox.actorApId),
-    eq(notificationArchived.activityApId, inbox.activityApId),
-  );
-  const archivedSubquery = db
-    .select({ activityApId: notificationArchived.activityApId })
-    .from(notificationArchived)
-    .where(archivedCorrelation);
-  const archivedDmSubquery = db
-    .select({ conversationId: dmArchivedConversations.conversationId })
-    .from(dmArchivedConversations)
-    .where(
-      and(
-        eq(dmArchivedConversations.actorApId, actorApId),
-        eq(dmArchivedConversations.conversationId, objects.conversation),
-      ),
-    );
+  // therefore re-checked here immediately before external delivery, using the
+  // SAME shared predicate builder as the notification list/count. Direct
+  // Creates remain eligible (archived DMs excepted) and route to Yurume below.
   return selectEvent()
     .from(inbox)
     .innerJoin(activities, eq(inbox.activityApId, activities.apId))
@@ -939,18 +1015,9 @@ async function loadPushEvent(
       and(
         eq(inbox.actorApId, actorApId),
         eq(inbox.activityApId, activityApId),
-        ne(activities.actorApId, actorApId),
-        inArray(activities.type, SOCIAL_NOTIFICATION_ACTIVITY_TYPES),
-        notExists(archivedSubquery),
-        // Archiving a Yurume conversation is a current delivery preference,
-        // not merely a presentation filter. A queued direct event must stop at
-        // this choke point if the recipient archived it after enqueue.
-        or(
-          isNull(objects.visibility),
-          ne(objects.visibility, "direct"),
-          notExists(archivedDmSubquery),
-        )!,
-        excludeBlockedMutedAuthors(db, actorApId, activities.actorApId),
+        ...notificationEligibilityWhere(db, actorApId, {
+          direct: "unless-dm-archived",
+        }),
       ),
     )
     .get();
@@ -963,63 +1030,13 @@ async function unreadCountForProduct(
   product: SocialNotificationProduct,
 ): Promise<number> {
   if (product === "yurume") {
-    // Keep parity with GET /api/dm/unread/count: direct messages use their
-    // per-conversation read baseline, while community talk uses the later of
-    // the membership join time and the per-community read baseline.
-    const dmRow = await db.get<{ c: number }>(sql`
-      SELECT COUNT(*) AS c
-      FROM objects o
-      JOIN object_recipients orp
-        ON orp.object_ap_id = o.ap_id
-        AND orp.recipient_ap_id = ${actorApId}
-        AND orp.type = 'to'
-      LEFT JOIN dm_read_status r
-        ON r.conversation_id = o.conversation
-        AND r.actor_ap_id = ${actorApId}
-      WHERE o.visibility = 'direct'
-        AND o.type = 'Note'
-        AND o.conversation IS NOT NULL
-        AND o.attributed_to != ${actorApId}
-        AND o.published > COALESCE(r.last_read_at, '1970-01-01T00:00:00Z')
-        AND o.conversation NOT IN (
-          SELECT conversation_id FROM dm_archived_conversations
-          WHERE actor_ap_id = ${actorApId}
-        )
-    `);
-    const communityRow = await db.get<{ c: number }>(sql`
-      SELECT COUNT(*) AS c
-      FROM community_members cm
-      JOIN object_recipients orp
-        ON orp.recipient_ap_id = cm.community_ap_id
-        AND orp.type = 'audience'
-      JOIN objects o
-        ON o.ap_id = orp.object_ap_id
-        AND o.type = 'Note'
-        AND o.community_ap_id IS NULL
-        AND o.attributed_to != ${actorApId}
-      LEFT JOIN dm_community_read_status r
-        ON r.community_ap_id = cm.community_ap_id
-        AND r.actor_ap_id = ${actorApId}
-      WHERE cm.actor_ap_id = ${actorApId}
-        AND o.published > COALESCE(
-          r.last_read_at,
-          cm.joined_at,
-          '1970-01-01T00:00:00Z'
-        )
-    `);
-    return Number(dmRow?.c ?? 0) + Number(communityRow?.c ?? 0);
+    // Reuse the SAME helper as GET /api/dm/unread/count so the badge a push
+    // sets can never drift from the badge the client computes on open.
+    return (await yurumeUnreadCounts(db, actorApId)).total;
   }
 
-  // Keep parity with the default social notification list/unread count. A
-  // Yurume DM row must never inflate the Yurucommu app badge.
-  const archivedCorrelation = and(
-    eq(notificationArchived.actorApId, inbox.actorApId),
-    eq(notificationArchived.activityApId, inbox.activityApId),
-  );
-  const archivedSubquery = db
-    .select({ activityApId: notificationArchived.activityApId })
-    .from(notificationArchived)
-    .where(archivedCorrelation);
+  // Reuse the SAME eligibility predicate as the notification list/badge. A
+  // Yurume DM row must never inflate the Yurucommu app badge (direct: exclude).
   const row = await db
     .select({ count: sql<number>`COUNT(*)` })
     .from(inbox)
@@ -1029,11 +1046,7 @@ async function unreadCountForProduct(
       and(
         eq(inbox.actorApId, actorApId),
         eq(inbox.read, 0),
-        ne(activities.actorApId, actorApId),
-        inArray(activities.type, SOCIAL_NOTIFICATION_ACTIVITY_TYPES),
-        or(isNull(objects.visibility), ne(objects.visibility, "direct"))!,
-        notExists(archivedSubquery),
-        excludeBlockedMutedAuthors(db, actorApId, activities.actorApId),
+        ...notificationEligibilityWhere(db, actorApId, { direct: "exclude" }),
       ),
     )
     .get();

package/src/backend/lib/session-actor.ts

@@ -17,7 +17,7 @@ function isExpired(expiresAt: string): boolean {
 export async function extractActorFromSession(
   c: Context<{ Bindings: Env; Variables: Variables }>,
 ): Promise<void> {
-  const sessionId = getCookie(c, "session");
+  const sessionId = rawSessionCredential(c);
   if (!sessionId) return;
 
   const db = c.get("db");
@@ -59,3 +59,18 @@ export async function extractActorFromSession(
   };
   c.set("actor", actor);
 }
+
+/**
+ * Resolve the host-owned session credential used by browser and native clients.
+ * Cookie auth wins when both are present so adding an Authorization header to a
+ * browser request never changes its CSRF/session identity semantics.
+ */
+export function rawSessionCredential(
+  c: Context<{ Bindings: Env; Variables: Variables }>,
+): string | undefined {
+  const cookie = getCookie(c, "session")?.trim();
+  if (cookie) return cookie;
+  const authorization = c.req.header("Authorization")?.trim();
+  const match = authorization?.match(/^Bearer\s+([^\s]+)$/i);
+  return match?.[1];
+}