@takosjp/yurucommu-core 3.0.0

package/src/backend/routes/search.ts

@@ -0,0 +1,730 @@
+import { Hono } from "hono";
+import { and, desc, eq, gt, inArray, isNull, like, or, sql } from "drizzle-orm";
+import type { Env, Variables } from "../types.ts";
+import {
+  fetchWithTimeout,
+  formatUsername,
+  isSafeRemoteUrl,
+  normalizeRemoteDomain,
+  parseLimit,
+  parseOffset,
+  signRequest,
+} from "../federation-helpers.ts";
+import { getInstanceFetchSigner } from "./activitypub/query-helpers.ts";
+import type { Database } from "../../db/index.ts";
+import {
+  actorCache,
+  actors,
+  likes,
+  notDeleted,
+  objects,
+} from "../../db/index.ts";
+import {
+  parseWebFinger,
+  tryParseRemoteActor,
+} from "../lib/activitypub-validators.ts";
+import { logger } from "../lib/logger.ts";
+import { chunkForInClause } from "../lib/chunk.ts";
+import { type ActorInfo, loadActorInfoMap } from "./actors-helpers.ts";
+import { excludeBlockedMutedAuthors } from "../lib/feed-exclude.ts";
+import { withCache } from "../middleware/cache.ts";
+
+const log = logger.child({ component: "search" });
+
+// Trending hashtags are derived purely from public posts and carry no
+// per-viewer data, so the response is identical for every caller. Cache it
+// for 10 minutes to avoid re-scanning recent posts on every request.
+const TRENDING_HASHTAGS_TTL = 600;
+// Ceiling on the trending post scan. Hashtags are extracted from post CONTENT
+// in JS (D1/SQLite has no REGEXP, and tags_json is only populated by local
+// posts — federated inbound posts would be missed by a tags_json aggregation),
+// so this bounds memory on a cache miss. It is a memory bound, NOT a silent
+// window truncation: if a scan returns exactly this many rows we log that older
+// in-window posts went uncounted. The scalable fix (an FTS / normalized-tags
+// index aggregated in SQL) is tracked as deferred search work.
+const TRENDING_SCAN_LIMIT = 2000;
+
+const search = new Hono<{ Bindings: Env; Variables: Variables }>();
+const REMOTE_FETCH_TIMEOUT_MS = 10000;
+
+// ---------------------------------------------------------------------------
+// Sort validation
+// ---------------------------------------------------------------------------
+
+const ALLOWED_ACTOR_SORTS = ["relevance", "followers", "recent"] as const;
+type ActorSort = (typeof ALLOWED_ACTOR_SORTS)[number];
+
+const ALLOWED_POST_SORTS = ["recent", "popular"] as const;
+type PostSort = (typeof ALLOWED_POST_SORTS)[number];
+
+function validateSort<T extends string>(
+  value: string | undefined,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  if (value && (allowed as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  return fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+// ActorInfo + the local-wins author lookup come from the canonical, D1-chunked
+// loadActorInfoMap (actors-helpers). The previous file-local buildAuthorMap copy
+// passed the (up to 100) author ids straight into inArray with no chunking — at
+// D1's 100-bound-parameter ceiling with zero headroom — so it is removed in
+// favour of the shared loader.
+
+// ---------------------------------------------------------------------------
+// Shared helpers (file-local, not exported)
+// ---------------------------------------------------------------------------
+
+/**
+ * Public-searchability guard shared by every anonymous-reachable post search
+ * (/posts, /hashtag, /hashtags/trending).
+ *
+ * Community-scoped Notes are persisted as visibility="public" but carry a
+ * non-"[]" audienceJson (the community read-gate). Filtering on visibility
+ * alone would leak private-community post content (and, via trending, tag
+ * names/counts) to anonymous or non-member callers. Both guards MUST be
+ * applied together; centralizing them here prevents the two conditions from
+ * drifting apart across the three search routes.
+ *
+ * Pass content/recency predicates as extra args; they are AND-ed with the
+ * public-scope guard.
+ */
+function publicSearchableWhere(...extra: Parameters<typeof and>) {
+  return and(
+    // Search/trending surface POSTS only. Stories are stored as type='Story'
+    // with visibility='public' (their text lives in attachmentsJson, so content
+    // is empty today and they don't currently match), but gating on type keeps
+    // search consistent with the timeline + outbox and stops any non-Note object
+    // that ever carries content from leaking in.
+    eq(objects.type, "Note"),
+    eq(objects.visibility, "public"),
+    eq(objects.audienceJson, "[]"),
+    // Exclude soft-deleted/tombstoned objects, matching the takos-tools search
+    // path (which already filters isNull(deletedAt)). Objects are hard-deleted
+    // today so this is currently a no-op, but it keeps the two search surfaces
+    // consistent and future-proofs against any object soft-delete.
+    isNull(objects.deletedAt),
+    ...extra,
+  );
+}
+
+/** Build orderBy for post queries. A unique tiebreaker (`apId`) makes the sort
+ * TOTAL: `published` is a non-unique ISO-timestamp text (imported AP posts often
+ * share a whole second) and `likeCount` ties trivially, so without it SQLite
+ * gives no stable order for equal-key rows — across two independent OFFSET
+ * queries a tied row could shift into the already-consumed window and never be
+ * returned (the notifications keyset cursor uses a composite for the same
+ * reason). `apId` is the objects PK, so the ordering is unambiguous. */
+function postOrderByDrizzle(sort: PostSort) {
+  if (sort === "popular") {
+    return [
+      desc(objects.likeCount),
+      desc(objects.published),
+      desc(objects.apId),
+    ];
+  }
+  return [desc(objects.published), desc(objects.apId)];
+}
+
+// Canonical hashtag tokenizer. Shared by trending and hashtag search so the two
+// agree on what is a WHOLE hashtag token — a content `LIKE '%#tag%'` alone treats
+// "#go" as matching "#golang" (a substring), which is wrong for both surfaces.
+// The character class MUST match the one used by storage/federation
+// (transformers.ts extractHashtags) and the web linkifier (post-tokens.ts), which
+// both use full Unicode word chars (\p{L}\p{N}_). A narrower class here would let
+// a non-CJK tag (Korean / Cyrillic / accented Latin / Greek / …) render as a link
+// and federate but be un-findable by search/trending (and #café would mis-segment
+// to #caf), silently diverging the three layers.
+const HASHTAG_TOKEN_REGEX = /#([\p{L}\p{N}_]+)/gu;
+
+/** Extract the lowercased hashtag tokens (without the leading '#') from content. */
+function extractHashtags(content: string): string[] {
+  const tags: string[] = [];
+  HASHTAG_TOKEN_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = HASHTAG_TOKEN_REGEX.exec(content)) !== null) {
+    tags.push(match[1].toLowerCase());
+  }
+  return tags;
+}
+
+// Ceiling on the hashtag-search candidate scan. The `LIKE '%#tag%'` prefilter
+// returns a superset (substring matches); the exact whole-token filter then runs
+// in JS (SQLite has no REGEXP). This bounds memory; if a scan hits the ceiling we
+// log so deep results on a busy instance aren't silently dropped.
+const HASHTAG_SEARCH_SCAN_CAP = 1000;
+// Per-source (local + cached) row cap for actor search before the union/sort/
+// slice. Generous for a single-user instance; bounds the in-memory merge.
+const ACTOR_SEARCH_SCAN_CAP = 200;
+
+// Trigram FTS5 indexes 3-grams, so it cannot match a query shorter than 3 chars.
+const FTS_MIN_QUERY_LEN = 3;
+
+/**
+ * Post-content search predicate (used by GET /search/posts).
+ *
+ * For queries >= 3 chars, match via the `objects_fts` trigram index (migration
+ * 0012) — an indexed substring search that works for Japanese, which the default
+ * tokenizer cannot segment. The user input is wrapped as an FTS5 phrase (double
+ * quoted, internal quotes doubled) so it is treated as a LITERAL substring rather
+ * than FTS query syntax (a stray `"` or `*` would otherwise change the match or
+ * error). Shorter queries fall back to LIKE since trigram cannot index them.
+ *
+ * The caller AND-s this with `publicSearchableWhere`, so visibility/audience
+ * gating still applies on top of the match (no private-post leak).
+ */
+function likeContains(column: Parameters<typeof like>[0], value: string) {
+  // Match with instr() (a LITERAL substring search), lowercased for the same
+  // ASCII case-insensitivity LIKE gives — NOT `LIKE '%...%'`: a long search term
+  // (>~48 chars) trips D1's LIKE pattern-complexity limit (SQLITE_ERROR 7500).
+  // instr() has no wildcards (so a user's literal `%`/`_` matches literally,
+  // which is what search wants) and no length limit.
+  return sql`instr(lower(${column}), lower(${value})) > 0`;
+}
+
+export function postContentSearchPredicate(query: string) {
+  // Count CODEPOINTS, not UTF-16 units: the trigram tokenizer needs >=3
+  // codepoints to form a single trigram, but `query.length` counts UTF-16 units,
+  // so a 2-emoji query ("🦀🦀") has .length 4 yet only 2 codepoints — it would
+  // route to FTS MATCH, form ZERO trigrams, and silently match nothing. Use the
+  // codepoint count so 1-2 codepoint queries fall back to instr() which matches.
+  if ([...query].length < FTS_MIN_QUERY_LEN) {
+    return likeContains(objects.content, query);
+  }
+  const phrase = '"' + query.replace(/"/g, '""') + '"';
+  return sql`objects.rowid IN (SELECT rowid FROM objects_fts WHERE objects_fts MATCH ${phrase})`;
+}
+
+/** Load the set of post AP IDs that a given actor has liked. */
+async function loadLikedPostIds(
+  db: Database,
+  actorApId: string | undefined,
+  postApIds: string[],
+): Promise<Set<string>> {
+  if (!actorApId || postApIds.length === 0) return new Set();
+
+  // Chunk the IN(...) lookup: a full hashtag-search page is up to 100 post ids
+  // and D1 caps a query at 100 bound parameters (the extra eq() param pushes a
+  // 100-id IN over the edge). Chunks are disjoint id slices, so unioning the
+  // liked-id sets is collision-free.
+  const liked = new Set<string>();
+  for (const ids of chunkForInClause(postApIds)) {
+    const likeRows = await db
+      .select({ objectApId: likes.objectApId })
+      .from(likes)
+      .where(
+        and(eq(likes.actorApId, actorApId), inArray(likes.objectApId, ids)),
+      );
+    for (const l of likeRows) liked.add(l.objectApId);
+  }
+  return liked;
+}
+
+type PostRow = {
+  apId: string;
+  attributedTo: string;
+  content: string;
+  published: string | null;
+  likeCount: number;
+};
+
+/** Map a raw post + author map + liked set into the API response shape. */
+function formatPost(
+  post: PostRow,
+  authorMap: Map<string, ActorInfo>,
+  likedPostIds: Set<string>,
+): {
+  ap_id: string;
+  author: {
+    ap_id: string;
+    username: string;
+    preferred_username: string | null;
+    name: string | null;
+    icon_url: string | null;
+  };
+  content: string;
+  published: string | null;
+  like_count: number;
+  liked: boolean;
+} {
+  const author = authorMap.get(post.attributedTo);
+  return {
+    ap_id: post.apId,
+    author: {
+      ap_id: post.attributedTo,
+      username: formatUsername(post.attributedTo),
+      preferred_username: author?.preferredUsername ?? null,
+      name: author?.name ?? null,
+      icon_url: author?.iconUrl ?? null,
+    },
+    content: post.content,
+    published: post.published,
+    like_count: post.likeCount,
+    liked: likedPostIds.has(post.apId),
+  };
+}
+
+/** Enrich posts with author info and like status, returning formatted API results. */
+async function enrichPosts(
+  db: Database,
+  posts: PostRow[],
+  actorApId: string | undefined,
+): Promise<ReturnType<typeof formatPost>[]> {
+  if (posts.length === 0) return [];
+
+  const authorApIds = [...new Set(posts.map((p) => p.attributedTo))];
+  const [authorMap, likedPostIds] = await Promise.all([
+    loadActorInfoMap(db, authorApIds, "author"),
+    loadLikedPostIds(
+      db,
+      actorApId,
+      posts.map((p) => p.apId),
+    ),
+  ]);
+
+  return posts.map((p) => formatPost(p, authorMap, likedPostIds));
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+/**
+ * Search local actors by username or name
+ * GET /api/search/actors?q=query&sort=relevance|followers|recent
+ */
+search.get("/actors", async (c) => {
+  const rawQuery = c.req.query("q")?.trim();
+  if (!rawQuery) return c.json({ actors: [] });
+  // Users commonly type the leading "@" of a handle, but preferredUsername is
+  // stored without it — strip it so "@tako" finds "tako". (A full "@user@domain"
+  // handle is the remote-search path's job, not this local/cached lookup.)
+  const query = rawQuery.replace(/^@+/, "");
+  if (!query) return c.json({ actors: [] });
+
+  const db = c.get("db");
+  const sort = validateSort(
+    c.req.query("sort"),
+    ALLOWED_ACTOR_SORTS,
+    "relevance",
+  );
+  const limit = parseLimit(c.req.query("limit"), 20, 50);
+  const offset = parseOffset(c.req.query("offset"), 0, 10000);
+  const lowerQuery = query.toLowerCase();
+
+  const orderByClause =
+    sort === "recent" ? [desc(actors.createdAt)] : [desc(actors.followerCount)];
+
+  const [localRows, cachedRows] = await Promise.all([
+    db
+      .select({
+        apId: actors.apId,
+        preferredUsername: actors.preferredUsername,
+        name: actors.name,
+        iconUrl: actors.iconUrl,
+        summary: actors.summary,
+        followerCount: actors.followerCount,
+        createdAt: actors.createdAt,
+      })
+      .from(actors)
+      .where(
+        and(
+          notDeleted(actors),
+          // A private/locked account is discoverable:false + manuallyApproves
+          // followers; it must not surface in anonymous-reachable actor search
+          // (its existence/name/bio/follower-count would leak). Matches the
+          // takos-tools searchUsers + getUserProfile gates.
+          eq(actors.isPrivate, 0),
+          or(
+            likeContains(actors.preferredUsername, query),
+            likeContains(actors.name, query),
+          ),
+        ),
+      )
+      .orderBy(...orderByClause)
+      .limit(ACTOR_SEARCH_SCAN_CAP),
+    // Previously-discovered remote actors live in actorCache (populated by the
+    // /remote webfinger lookup). Consult it here so an account someone already
+    // found stays re-findable by name/username without re-typing the full
+    // handle. Cached actors have no local follower/created metadata.
+    db
+      .select({
+        apId: actorCache.apId,
+        preferredUsername: actorCache.preferredUsername,
+        name: actorCache.name,
+        iconUrl: actorCache.iconUrl,
+        summary: actorCache.summary,
+      })
+      .from(actorCache)
+      .where(
+        or(
+          likeContains(actorCache.preferredUsername, query),
+          likeContains(actorCache.name, query),
+        ),
+      )
+      .limit(ACTOR_SEARCH_SCAN_CAP),
+  ]);
+
+  // UNION local + cached, with local taking priority on apId collision.
+  const seen = new Set(localRows.map((a) => a.apId));
+  const actorRows: {
+    apId: string;
+    preferredUsername: string | null;
+    name: string | null;
+    iconUrl: string | null;
+    summary: string | null;
+    followerCount: number;
+    createdAt: string | null;
+  }[] = [
+    ...localRows,
+    ...cachedRows
+      .filter((a) => !seen.has(a.apId))
+      .map((a) => ({
+        apId: a.apId,
+        preferredUsername: a.preferredUsername,
+        name: a.name,
+        iconUrl: a.iconUrl,
+        summary: a.summary,
+        followerCount: 0,
+        createdAt: null,
+      })),
+  ];
+
+  if (sort === "relevance") {
+    actorRows.sort((a, b) => {
+      const aUsername = (a.preferredUsername ?? "").toLowerCase();
+      const bUsername = (b.preferredUsername ?? "").toLowerCase();
+
+      const aExact = aUsername === lowerQuery ? 0 : 1;
+      const bExact = bUsername === lowerQuery ? 0 : 1;
+      if (aExact !== bExact) return aExact - bExact;
+
+      const aPrefix = aUsername.startsWith(lowerQuery) ? 0 : 1;
+      const bPrefix = bUsername.startsWith(lowerQuery) ? 0 : 1;
+      if (aPrefix !== bPrefix) return aPrefix - bPrefix;
+
+      return b.followerCount - a.followerCount;
+    });
+  }
+
+  // Page the merged+sorted set in app code (the two underlying queries are each
+  // scan-capped, then unioned/sorted, so SQL LIMIT/OFFSET cannot paginate the
+  // combined result — same shape as the hashtag handler). has_more is exact up
+  // to the scan cap.
+  const total = actorRows.length;
+  const pageRows = actorRows.slice(offset, offset + limit);
+  const has_more = offset + pageRows.length < total;
+
+  const result = pageRows.map((a) => ({
+    ap_id: a.apId,
+    preferred_username: a.preferredUsername,
+    name: a.name,
+    icon_url: a.iconUrl,
+    summary: a.summary,
+    follower_count: a.followerCount,
+    created_at: a.createdAt,
+    username: formatUsername(a.apId),
+  }));
+
+  return c.json({ actors: result, limit, offset, has_more });
+});
+
+/**
+ * Search posts by content
+ * GET /api/search/posts?q=query&sort=recent|popular
+ */
+search.get("/posts", async (c) => {
+  const query = c.req.query("q")?.trim();
+  if (!query) return c.json({ posts: [] });
+
+  const actor = c.get("actor");
+  const db = c.get("db");
+  const sort = validateSort(c.req.query("sort"), ALLOWED_POST_SORTS, "recent");
+  const limit = parseLimit(c.req.query("limit"), 20, 50);
+  const offset = parseOffset(c.req.query("offset"), 0, 10000);
+
+  // Fetch one extra past the page to report has_more without a COUNT.
+  const rows = await db
+    .select({
+      apId: objects.apId,
+      attributedTo: objects.attributedTo,
+      content: objects.content,
+      published: objects.published,
+      likeCount: objects.likeCount,
+    })
+    .from(objects)
+    .where(
+      publicSearchableWhere(
+        postContentSearchPredicate(query),
+        // Suppress blocked/muted authors so keyword search honors the same
+        // moderation filter the home/timeline/notifications feeds apply
+        // (undefined for an anonymous viewer → and() drops it).
+        excludeBlockedMutedAuthors(db, actor?.ap_id ?? ""),
+      ),
+    )
+    .orderBy(...postOrderByDrizzle(sort))
+    .limit(limit + 1)
+    .offset(offset);
+
+  const has_more = rows.length > limit;
+  const posts = has_more ? rows.slice(0, limit) : rows;
+
+  return c.json({
+    posts: await enrichPosts(db, posts, actor?.ap_id),
+    limit,
+    offset,
+    has_more,
+  });
+});
+
+/**
+ * Search remote actors via WebFinger
+ * GET /api/search/remote?q=@user@domain
+ */
+search.get("/remote", async (c) => {
+  const query = c.req.query("q")?.trim();
+  if (!query) return c.json({ actors: [] });
+
+  const match = query.match(/^@?([^@]+)@([^@]+)$/);
+  if (!match) return c.json({ actors: [] });
+
+  const [, username, domain] = match;
+  const safeDomain = normalizeRemoteDomain(domain);
+  if (!safeDomain) return c.json({ actors: [] });
+
+  try {
+    // WebFinger lookup
+    const webfingerUrl = `https://${safeDomain}/.well-known/webfinger?resource=acct:${username}@${safeDomain}`;
+    const wfRes = await fetchWithTimeout(webfingerUrl, {
+      headers: { Accept: "application/jrd+json" },
+      timeout: REMOTE_FETCH_TIMEOUT_MS,
+    });
+    if (!wfRes.ok) return c.json({ actors: [] });
+
+    const wfRaw: unknown = await wfRes.json();
+    let wfData;
+    try {
+      wfData = parseWebFinger(wfRaw);
+    } catch {
+      return c.json({ actors: [] });
+    }
+    const actorLink = wfData.links?.find(
+      (l) => l.rel === "self" && l.type === "application/activity+json",
+    );
+    if (!actorLink?.href || !isSafeRemoteUrl(actorLink.href)) {
+      return c.json({ actors: [] });
+    }
+
+    // Fetch actor profile. Sign the GET as the instance actor so a remote in
+    // authorized-fetch / secure mode (which 401s the unsigned actor GET while
+    // leaving webfinger public) still resolves — otherwise searching for an
+    // account on such an instance silently returns zero results.
+    const signer = await getInstanceFetchSigner(c);
+    const actorRes = await fetchWithTimeout(actorLink.href, {
+      headers: {
+        Accept: "application/activity+json, application/ld+json",
+        ...(await signRequest(
+          signer.privateKeyPem,
+          signer.keyId,
+          "GET",
+          actorLink.href,
+        )),
+      },
+      timeout: REMOTE_FETCH_TIMEOUT_MS,
+    });
+    if (!actorRes.ok) return c.json({ actors: [] });
+
+    const actorRaw: unknown = await actorRes.json();
+    const actorData = tryParseRemoteActor(actorRaw);
+    if (!actorData) return c.json({ actors: [] });
+
+    if (actorData.id !== actorLink.href || !isSafeRemoteUrl(actorData.id)) {
+      return c.json({ actors: [] });
+    }
+
+    // Cache the actor (upsert: check if exists, then insert or update)
+    const db = c.get("db");
+    const cacheFields = {
+      type: actorData.type || "Person",
+      preferredUsername: actorData.preferredUsername || null,
+      name: actorData.name || null,
+      summary: actorData.summary || null,
+      iconUrl: actorData.icon?.url || null,
+      inbox: actorData.inbox || "",
+      outbox: actorData.outbox || null,
+      publicKeyId: actorData.publicKey?.id || null,
+      publicKeyPem: actorData.publicKey?.publicKeyPem || null,
+      rawJson: JSON.stringify(actorRaw),
+    };
+
+    const existing = await db
+      .select({ apId: actorCache.apId })
+      .from(actorCache)
+      .where(eq(actorCache.apId, actorData.id))
+      .get();
+
+    if (existing) {
+      await db
+        .update(actorCache)
+        .set(cacheFields)
+        .where(eq(actorCache.apId, actorData.id));
+    } else {
+      await db.insert(actorCache).values({
+        apId: actorData.id,
+        ...cacheFields,
+      });
+    }
+
+    return c.json({
+      actors: [
+        {
+          ap_id: actorData.id,
+          username: `${actorData.preferredUsername}@${safeDomain}`,
+          preferred_username: actorData.preferredUsername,
+          name: actorData.name,
+          summary: actorData.summary,
+          icon_url: actorData.icon?.url,
+        },
+      ],
+    });
+  } catch (e) {
+    log.error("Remote search failed", {
+      event: "search.remote.failed",
+      error: e,
+    });
+    return c.json({ actors: [] });
+  }
+});
+
+/**
+ * Search posts by hashtag
+ * GET /api/search/hashtag/:tag?sort=recent|popular
+ */
+search.get("/hashtag/:tag", async (c) => {
+  const tag = c.req.param("tag")?.trim().replace(/^#/, "");
+  if (!tag) return c.json({ posts: [], total: 0 });
+
+  const actor = c.get("actor");
+  const db = c.get("db");
+  const sort = validateSort(c.req.query("sort"), ALLOWED_POST_SORTS, "recent");
+  const limit = parseLimit(c.req.query("limit"), 50, 100);
+  const offset = parseOffset(c.req.query("offset"), 0, 10000);
+  const hashtagPattern = `#${tag}`;
+  const tagLower = tag.toLowerCase();
+
+  // instr() (literal, lowercased for case-insensitivity), NOT `LIKE '%...%'`: a
+  // long #tag would trip D1's LIKE pattern-complexity limit (SQLITE_ERROR 7500).
+  // This is a SUPERSET prefilter; the exact #tag check below narrows it.
+  const postWhere = publicSearchableWhere(
+    sql`instr(lower(${objects.content}), lower(${hashtagPattern})) > 0`,
+    // Same block/mute moderation filter as the feeds (see /search/posts).
+    excludeBlockedMutedAuthors(db, actor?.ap_id ?? ""),
+  );
+
+  // `LIKE '%#tag%'` is a SUPERSET prefilter: it also matches longer tags that
+  // share the prefix (searching "#deploy" would otherwise return "#deployed").
+  // SQLite has no REGEXP, so fetch the ordered candidates and keep only those
+  // whose content carries the tag as a WHOLE token (matching trending + the
+  // client linkifier). Filtering after the DB sort preserves recent/popular
+  // order; pagination + total are computed on the exact-matched set so they stay
+  // consistent. Content-based, so federated posts (no tags_json) are covered.
+  const candidates = await db
+    .select({
+      apId: objects.apId,
+      attributedTo: objects.attributedTo,
+      content: objects.content,
+      published: objects.published,
+      likeCount: objects.likeCount,
+    })
+    .from(objects)
+    .where(postWhere)
+    .orderBy(...postOrderByDrizzle(sort))
+    .limit(HASHTAG_SEARCH_SCAN_CAP);
+
+  if (candidates.length === HASHTAG_SEARCH_SCAN_CAP) {
+    log.warn("hashtag search hit candidate ceiling; deep results may be cut", {
+      event: "search.hashtag.truncated",
+      tag: tagLower,
+    });
+  }
+
+  const matched = candidates.filter((p) =>
+    extractHashtags(p.content || "").includes(tagLower),
+  );
+
+  const total = matched.length;
+  const pagePosts = matched.slice(offset, offset + limit);
+  const resultPosts = await enrichPosts(db, pagePosts, actor?.ap_id);
+
+  return c.json({
+    posts: resultPosts,
+    total,
+    limit,
+    offset,
+    has_more: offset + resultPosts.length < total,
+  });
+});
+
+/**
+ * Get trending hashtags
+ * GET /api/search/hashtags/trending?limit=10&days=7
+ */
+search.get(
+  "/hashtags/trending",
+  withCache({
+    ttl: TRENDING_HASHTAGS_TTL,
+    queryParamsToInclude: ["limit", "days"],
+  }),
+  async (c) => {
+    const limit = parseLimit(c.req.query("limit"), 10, 50);
+    const days = parseLimit(c.req.query("days"), 7, 30);
+    const sinceDate = new Date(
+      Date.now() - days * 24 * 60 * 60 * 1000,
+    ).toISOString();
+
+    const db = c.get("db");
+
+    const posts = await db
+      .select({ content: objects.content })
+      .from(objects)
+      .where(publicSearchableWhere(gt(objects.published, sinceDate)))
+      .orderBy(desc(objects.published))
+      .limit(TRENDING_SCAN_LIMIT);
+
+    if (posts.length === TRENDING_SCAN_LIMIT) {
+      // No silent truncation: the requested `days` window held more public posts
+      // than the scan ceiling, so older in-window posts were not counted toward
+      // the trend. Surface it for operators on busy instances.
+      log.warn("trending scan hit ceiling; older in-window posts uncounted", {
+        event: "search.trending.truncated",
+        scanned: posts.length,
+        days,
+      });
+    }
+
+    // Extract and count hashtags (shared whole-token tokenizer keeps trending
+    // and hashtag search consistent on what counts as a tag).
+    const hashtagCounts: Record<string, number> = {};
+    for (const post of posts) {
+      for (const tagName of extractHashtags(post.content || "")) {
+        hashtagCounts[tagName] = (hashtagCounts[tagName] || 0) + 1;
+      }
+    }
+
+    const trending = Object.entries(hashtagCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([tagName, count]) => ({ tag: tagName, count }));
+
+    return c.json({ trending });
+  },
+);
+
+export default search;