@hogsend/engine 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.25.0",
-    "@hogsend/db": "^0.25.0",
-    "@hogsend/email": "^0.25.0",
-    "@hogsend/plugin-posthog": "^0.25.0",
-    "@hogsend/plugin-resend": "^0.25.0"
+    "@hogsend/core": "^0.27.0",
+    "@hogsend/db": "^0.27.0",
+    "@hogsend/email": "^0.27.0",
+    "@hogsend/plugin-posthog": "^0.27.0",
+    "@hogsend/plugin-resend": "^0.27.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.25.0"
+    "@hogsend/plugin-postmark": "^0.27.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/connectors/runtime.ts

@@ -72,6 +72,9 @@ export interface ConnectorRuntimesHandle {
 const LEASE_TTL_MS = 30_000;
 const RENEW_MS = 10_000;
 const ELECT_MS = 5_000;
+// ~30s of failed elections (6 * ELECT_MS) before warning loudly that a
+// configured runtime still can't acquire its lease (Redis down or contended).
+const LEASE_MISS_WARN_AT = 6;
 
 /** Build the in-process dispatch→transform→ingest sink for one connector. */
 function makeIngest(client: HogsendClient, connector: DefinedConnector) {
@@ -150,6 +153,7 @@ function startController(
   let leading = false;
   let token = "";
   let stopped = false;
+  let leaseMisses = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
 
   /** Drop leadership: heartbeat key deleted FIRST (immediate Offline), then socket. */
@@ -178,6 +182,7 @@ function startController(
           ttlMs: LEASE_TTL_MS,
         });
         if (won) {
+          leaseMisses = 0;
           leading = true;
           heartbeat = startConnectorHeartbeat(connectorId, logger);
           heartbeat.state.setMetadata(rt.getMetadata());
@@ -198,6 +203,22 @@ function startController(
             leading = false;
             await releaseLeaderLease({ key: leaseKey, token });
           }
+        } else {
+          // Lease not acquired: another replica holds it (benign, normal during
+          // rollout) OR Redis is unreachable (the gateway can NEVER connect) —
+          // indistinguishable from the boolean. Warn LOUDLY once after ~30s of
+          // misses so a genuinely stuck runtime surfaces instead of silently
+          // never connecting (which Studio otherwise mis-reads as "intents off").
+          leaseMisses++;
+          if (leaseMisses === LEASE_MISS_WARN_AT) {
+            logger.error(
+              "Connector runtime has not acquired its leader lease after ~30s — " +
+                "Redis unreachable (check REDIS_URL points at the SAME instance " +
+                "as the API) or another replica holds it; if none does, the " +
+                "gateway will not connect.",
+              { connectorId },
+            );
+          }
         }
       } else {
         const renewed = await renewLeaderLease({

package/src/index.ts

@@ -327,6 +327,13 @@ export {
   releaseLeaderLease,
   renewLeaderLease,
 } from "./lib/leader-lease.js";
+// --- Managed tracked links (channel-agnostic mint — Studio/Discord/share) ---
+export {
+  type LinkType,
+  type MintedLink,
+  type MintLinkOptions,
+  mintLink,
+} from "./lib/links.js";
 // --- Logging ---
 export { createLogger, type Logger } from "./lib/logger.js";
 export { createTrackedMailer } from "./lib/mailer.js";

package/src/lib/identity-token.ts

@@ -64,6 +64,12 @@ export class InvalidIdentityTokenError extends Error {
 }
 
 const DEFAULT_EXPIRY_SECONDS = 60 * 60; // 1 hour — a click-to-landing hop
+/**
+ * The single-use burn sentinel (`POST /v1/t/identify`) lives in Redis for the
+ * token's full validity window, so a reshared token can't replay a merge while
+ * it would still validate. Kept equal to the token lifetime.
+ */
+export const IDENTITY_TOKEN_TTL_SECONDS = DEFAULT_EXPIRY_SECONDS;
 const IV_LENGTH = 12;
 const TAG_LENGTH = 16;
 

package/src/lib/links.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { type Database, links, trackedLinks } from "@hogsend/db";
+
+/**
+ * The channel-agnostic MANAGED tracked-link mint — the counterpart to the email
+ * HTML-rewrite path (`prepareTrackedHtml`). Any non-email channel (the Studio
+ * Links UI, a Discord DM/channel post, SMS, a share link) mints through here.
+ *
+ * It inserts a durable `links` row (the operator/campaign identity that the
+ * Studio lists + manages) plus a `tracked_links` click-counter row pointing back
+ * at it, and returns the `/v1/t/c/:id` redirect URL. Email does NOT use this — it
+ * rewrites HTML at send time and keeps `tracked_links.link_id` NULL, so the two
+ * remain independent consumers of the same click spine.
+ *
+ * SHARE-SAFE INVARIANT: a link is identity-bearing (carries a `distinctId` the
+ * click can stitch + may mint a single-use `hs_t`) ONLY when `type: "personal"`
+ * AND an explicit `distinctId` is passed. A `"public"` link NEVER carries a
+ * person token — a shared/reshared public link attributes by campaign only.
+ */
+export type LinkType = "personal" | "public";
+
+export interface MintLinkOptions {
+  db: Database;
+  /** The destination URL the redirect 302s to. Must be http(s). */
+  url: string;
+  /** Public base URL of this instance (the tracking host) — the redirect prefix. */
+  baseUrl: string;
+  /** Originating channel: "studio" | "discord" | "sms" | "referral" | … (open). */
+  source: string;
+  /** "personal" (1:1, identity-bearing) | "public" (shareable). Default "public". */
+  type?: LinkType;
+  /** Operator-facing name (Studio list). */
+  label?: string;
+  /** UTM-style campaign grouping (public links). */
+  campaign?: string;
+  /**
+   * The canonical contact key a click should stitch — honoured ONLY for
+   * `type: "personal"`; dropped for public links (the share-safe invariant).
+   */
+  distinctId?: string;
+  /** The admin actor who minted it (Studio). */
+  createdBy?: string;
+}
+
+export interface MintedLink {
+  /** The `links` row id (the managed identity). */
+  linkId: string;
+  /** The `tracked_links` row id — the `:id` in the redirect URL. */
+  trackedLinkId: string;
+  /** The short redirect URL: `${baseUrl}/v1/t/c/:id`. */
+  url: string;
+}
+
+/**
+ * Reject a non-http(s) destination at mint time. The click route 302s to the
+ * stored URL verbatim, so giving operators a UI to mint these would otherwise
+ * widen the latent open-redirect into `javascript:`/`data:` territory.
+ */
+function assertHttpUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`mintLink: invalid destination URL: ${url}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `mintLink: destination must be http(s), got "${parsed.protocol}"`,
+    );
+  }
+}
+
+export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
+  assertHttpUrl(opts.url);
+  const type: LinkType = opts.type ?? "public";
+  // A public link must NEVER carry a person token — drop any distinctId.
+  const distinctId = type === "personal" ? (opts.distinctId ?? null) : null;
+
+  const linkId = randomUUID();
+  const trackedLinkId = randomUUID();
+
+  await opts.db.insert(links).values({
+    id: linkId,
+    originalUrl: opts.url,
+    type,
+    label: opts.label ?? null,
+    campaign: opts.campaign ?? null,
+    source: opts.source,
+    distinctId,
+    createdBy: opts.createdBy ?? null,
+  });
+  await opts.db.insert(trackedLinks).values({
+    id: trackedLinkId,
+    linkId,
+    emailSendId: null,
+    distinctId,
+    source: opts.source,
+    originalUrl: opts.url,
+  });
+
+  return {
+    linkId,
+    trackedLinkId,
+    url: `${opts.baseUrl}/v1/t/c/${trackedLinkId}`,
+  };
+}

package/src/routes/admin/connectors.ts

@@ -97,7 +97,10 @@ const connectInfoSchema = z.object({
   apiPublicUrl: z.string(),
   redirectUri: z.string(),
   interactionsUrl: z.string(),
-  ingressSecretConfigured: z.boolean(),
+  // @deprecated legacy standalone-gateway signal (Boolean(CONNECTOR_INGRESS_SECRET)).
+  // The default inline runtime never uses the ingress secret; readiness is
+  // `workerOnline` (the owned Redis heartbeat). Kept one minor; NOT a precondition.
+  legacyIngressSecretConfigured: z.boolean(),
   credentialStored: z.boolean(),
   guildId: z.string().nullable(),
   // Tri-state — null = unknown (no guild from worker or derived credential).
@@ -420,7 +423,7 @@ export const adminConnectorsRouter = new OpenAPIHono<AppEnv>()
         apiPublicUrl,
         redirectUri,
         interactionsUrl: `${apiPublicUrl}/v1/connectors/discord/interactions`,
-        ingressSecretConfigured: Boolean(env.CONNECTOR_INGRESS_SECRET),
+        legacyIngressSecretConfigured: Boolean(env.CONNECTOR_INGRESS_SECRET),
         credentialStored: derived !== null,
         guildId,
         // Tri-state — a guild id (live or derived) confirms install; else null.

package/src/routes/admin/index.ts

@@ -17,6 +17,7 @@ import { emailsRouter } from "./emails.js";
 import { eventsRouter } from "./events.js";
 import { journeyLogsRouter } from "./journey-logs.js";
 import { journeysRouter } from "./journeys.js";
+import { linksRouter } from "./links.js";
 import { metricsRouter } from "./metrics.js";
 import { preferencesRouter } from "./preferences.js";
 import { providerCredentialsRouter } from "./provider-credentials.js";
@@ -38,6 +39,7 @@ adminRouter.route("/journeys", journeysRouter);
 adminRouter.route("/buckets", bucketsRouter);
 adminRouter.route("/events", eventsRouter);
 adminRouter.route("/emails", emailsRouter);
+adminRouter.route("/links", linksRouter);
 adminRouter.route("/journey-logs", journeyLogsRouter);
 adminRouter.route("/metrics", metricsRouter);
 adminRouter.route("/reporting", reportingRouter);

package/src/routes/admin/links.ts

@@ -0,0 +1,453 @@
+import { linkClicks, links, trackedLinks } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, count, desc, eq, inArray, isNull, sql, sum } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { mintLink } from "../../lib/links.js";
+import { errorSchema } from "../../lib/schemas.js";
+
+// ---------------------------------------------------------------------------
+// Admin CRUD for managed (operator-owned) tracked links — the surface behind
+// the Studio "Links" view. A `links` row is the durable, named identity of a
+// tracked link; the click counter + per-hit `link_clicks` live in
+// `tracked_links` (which back-references via `link_id`). Email's per-send
+// rewritten links are a SEPARATE consumer of the same click spine (they keep
+// `tracked_links.link_id` NULL) and are NOT listed here — this view is the
+// managed/standalone surface only.
+//
+// The click count is computed ON READ by summing `tracked_links.click_count`
+// for the link's `tracked_links` rows — there is deliberately NO denormalized
+// counter on `links`, so a click never has to write back to this table.
+//
+// One FLAT `Link` shape is returned everywhere: `url` is the short redirect URL
+// and `clickCount` is the computed count, both baked onto the row. `GET /:id`
+// adds a `clicks` array. Archive returns the (now-archived) flat link.
+// ---------------------------------------------------------------------------
+
+// Resolves the minting actor across the two admin auth paths (mirrors the audit
+// middleware): an API key carries a `name`; a Better-Auth session carries a
+// `user` whose email we record. Stored verbatim on `links.created_by`.
+function resolveActor(c: {
+  get: (k: "apiKey" | "user") => unknown;
+}): string | null {
+  const apiKey = c.get("apiKey") as { name?: string } | undefined;
+  if (apiKey?.name) return apiKey.name;
+  const user = c.get("user") as { email?: string } | null | undefined;
+  return user?.email ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Shared response shapes
+// ---------------------------------------------------------------------------
+
+const linkSchema = z.object({
+  id: z.string(),
+  // The link's redirect tracked-row id (one per managed link). Absent only if a
+  // link somehow has no tracked row — kept nullable to stay total.
+  trackedLinkId: z.string().nullable(),
+  originalUrl: z.string(),
+  type: z.enum(["personal", "public"]),
+  label: z.string().nullable(),
+  campaign: z.string().nullable(),
+  source: z.string(),
+  distinctId: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  // Computed on read (summed across the link's tracked_links rows).
+  clickCount: z.number(),
+  // The short redirect URL: `${API_PUBLIC_URL}/v1/t/c/:trackedLinkId`.
+  url: z.string(),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const clickSchema = z.object({
+  id: z.string(),
+  trackedLinkId: z.string(),
+  ipAddress: z.string().nullable(),
+  userAgent: z.string().nullable(),
+  clickedAt: z.string(),
+});
+
+const linkDetailSchema = linkSchema.extend({
+  clicks: z.array(clickSchema),
+});
+
+type LinkRow = typeof links.$inferSelect;
+type ClickAgg = { clicks: number; trackedLinkId: string | null };
+
+// The short redirect URL for a link's tracked row, or a bare prefix if the link
+// has no tracked row (should not happen for a minted link, but keep it total).
+function shortUrlFor(baseUrl: string, trackedLinkId: string | null): string {
+  return `${baseUrl}/v1/t/c/${trackedLinkId ?? ""}`;
+}
+
+function serializeLink(
+  row: LinkRow,
+  agg: ClickAgg | undefined,
+  baseUrl: string,
+): z.infer<typeof linkSchema> {
+  const trackedLinkId = agg?.trackedLinkId ?? null;
+  return {
+    id: row.id,
+    trackedLinkId,
+    originalUrl: row.originalUrl,
+    // The column is a free text; mintLink only ever writes these two values.
+    type: row.type === "personal" ? "personal" : "public",
+    label: row.label,
+    campaign: row.campaign,
+    source: row.source,
+    distinctId: row.distinctId,
+    createdBy: row.createdBy,
+    clickCount: agg?.clicks ?? 0,
+    url: shortUrlFor(baseUrl, trackedLinkId),
+    archivedAt: row.archivedAt ? row.archivedAt.toISOString() : null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+const createLinkRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Admin — Links"],
+  summary: "Mint a managed tracked link",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            url: z.string().url(),
+            type: z.enum(["personal", "public"]).default("public"),
+            label: z.string().optional(),
+            campaign: z.string().optional(),
+            // Honoured ONLY for personal links (the share-safe invariant in
+            // mintLink drops it for public). A canonical contact key the click
+            // should stitch the visitor's anon session into.
+            distinctId: z.string().optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: linkSchema } },
+      description: "Minted link",
+    },
+    400: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Invalid destination URL",
+    },
+  },
+});
+
+const listLinksRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Links"],
+  summary: "List managed links (newest first)",
+  request: {
+    query: z.object({
+      limit: z.coerce.number().min(1).max(200).default(50),
+      offset: z.coerce.number().min(0).default(0),
+      type: z.enum(["personal", "public"]).optional(),
+      includeArchived: z.coerce.boolean().default(false),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            links: z.array(linkSchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Managed link list",
+    },
+  },
+});
+
+const getLinkRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Admin — Links"],
+  summary: "Get a managed link with recent clicks",
+  request: { params: z.object({ id: z.string().uuid() }) },
+  responses: {
+    200: {
+      content: { "application/json": { schema: linkDetailSchema } },
+      description: "Link detail",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Link not found",
+    },
+  },
+});
+
+const updateLinkRoute = createRoute({
+  method: "patch",
+  path: "/{id}",
+  tags: ["Admin — Links"],
+  summary: "Update a managed link (label + campaign)",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            label: z.string().nullable().optional(),
+            campaign: z.string().nullable().optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: linkSchema } },
+      description: "Updated link",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Link not found",
+    },
+  },
+});
+
+const archiveLinkRoute = createRoute({
+  method: "delete",
+  path: "/{id}",
+  tags: ["Admin — Links"],
+  summary: "Archive a managed link (soft-delete)",
+  request: { params: z.object({ id: z.string().uuid() }) },
+  responses: {
+    200: {
+      content: { "application/json": { schema: linkSchema } },
+      description: "Archived link",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Link not found",
+    },
+  },
+});
+
+type Db = AppEnv["Variables"]["container"]["db"];
+
+// Aggregates each link's tracked_links rows in ONE grouped query: the summed
+// click_count (computed on read — no denormalized counter on `links`) and the
+// link's redirect id (a managed link has exactly one tracked row, minted
+// alongside it). Returns a map keyed by link id; links with no tracked rows are
+// simply absent (callers default to 0 / a bare prefix).
+async function aggregateFor(
+  db: Db,
+  linkIds: string[],
+): Promise<Map<string, ClickAgg>> {
+  const map = new Map<string, ClickAgg>();
+  if (linkIds.length === 0) return map;
+  const rows = await db
+    .select({
+      linkId: trackedLinks.linkId,
+      clicks: sql<number>`coalesce(${sum(trackedLinks.clickCount)}, 0)`.mapWith(
+        Number,
+      ),
+      trackedLinkId: sql<string>`min(${trackedLinks.id}::text)`,
+    })
+    .from(trackedLinks)
+    .where(inArray(trackedLinks.linkId, linkIds))
+    .groupBy(trackedLinks.linkId);
+  for (const r of rows) {
+    if (r.linkId) {
+      map.set(r.linkId, {
+        clicks: r.clicks,
+        trackedLinkId: r.trackedLinkId ?? null,
+      });
+    }
+  }
+  return map;
+}
+
+export const linksRouter = new OpenAPIHono<AppEnv>()
+  .openapi(createLinkRoute, async (c) => {
+    const { db, env } = c.get("container");
+    const body = c.req.valid("json");
+
+    try {
+      const minted = await mintLink({
+        db,
+        url: body.url,
+        baseUrl: env.API_PUBLIC_URL,
+        source: "studio",
+        type: body.type,
+        label: body.label,
+        campaign: body.campaign,
+        distinctId: body.distinctId,
+        createdBy: resolveActor(c) ?? undefined,
+      });
+
+      const [row] = await db
+        .select()
+        .from(links)
+        .where(eq(links.id, minted.linkId))
+        .limit(1);
+
+      if (!row) {
+        return c.json({ error: "Mint succeeded but link not found" }, 400);
+      }
+
+      return c.json(
+        serializeLink(
+          row,
+          { clicks: 0, trackedLinkId: minted.trackedLinkId },
+          env.API_PUBLIC_URL,
+        ),
+        200,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Mint failed";
+      return c.json({ error: message }, 400);
+    }
+  })
+  .openapi(listLinksRoute, async (c) => {
+    const { db, env } = c.get("container");
+    const { limit, offset, type, includeArchived } = c.req.valid("query");
+
+    const where = and(
+      includeArchived ? undefined : isNull(links.archivedAt),
+      type ? eq(links.type, type) : undefined,
+    );
+
+    const [rows, totalRows] = await Promise.all([
+      db
+        .select()
+        .from(links)
+        .where(where)
+        .orderBy(desc(links.createdAt))
+        .limit(limit)
+        .offset(offset),
+      db.select({ value: count() }).from(links).where(where),
+    ]);
+
+    const agg = await aggregateFor(
+      db,
+      rows.map((r) => r.id),
+    );
+
+    return c.json(
+      {
+        links: rows.map((row) =>
+          serializeLink(row, agg.get(row.id), env.API_PUBLIC_URL),
+        ),
+        total: totalRows[0]?.value ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  })
+  .openapi(getLinkRoute, async (c) => {
+    const { db, env } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const [row] = await db
+      .select()
+      .from(links)
+      .where(eq(links.id, id))
+      .limit(1);
+
+    if (!row) {
+      return c.json({ error: "Link not found" }, 404);
+    }
+
+    // Recent clicks joined via the link's tracked_links rows, newest first,
+    // capped. The aggregate gives the summed count + the redirect id.
+    const [agg, clickRows] = await Promise.all([
+      aggregateFor(db, [id]),
+      db
+        .select({
+          id: linkClicks.id,
+          trackedLinkId: linkClicks.trackedLinkId,
+          ipAddress: linkClicks.ipAddress,
+          userAgent: linkClicks.userAgent,
+          clickedAt: linkClicks.clickedAt,
+        })
+        .from(linkClicks)
+        .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
+        .where(eq(trackedLinks.linkId, id))
+        .orderBy(desc(linkClicks.clickedAt))
+        .limit(50),
+    ]);
+
+    return c.json(
+      {
+        ...serializeLink(row, agg.get(id), env.API_PUBLIC_URL),
+        clicks: clickRows.map((cl) => ({
+          id: cl.id,
+          trackedLinkId: cl.trackedLinkId,
+          ipAddress: cl.ipAddress,
+          userAgent: cl.userAgent,
+          clickedAt: cl.clickedAt.toISOString(),
+        })),
+      },
+      200,
+    );
+  })
+  .openapi(updateLinkRoute, async (c) => {
+    const { db, env } = c.get("container");
+    const { id } = c.req.valid("param");
+    const body = c.req.valid("json");
+
+    const patch: Partial<Pick<LinkRow, "label" | "campaign">> & {
+      updatedAt: Date;
+    } = { updatedAt: new Date() };
+    if (body.label !== undefined) patch.label = body.label;
+    if (body.campaign !== undefined) patch.campaign = body.campaign;
+
+    const [updated] = await db
+      .update(links)
+      .set(patch)
+      .where(eq(links.id, id))
+      .returning();
+
+    if (!updated) {
+      return c.json({ error: "Link not found" }, 404);
+    }
+
+    const agg = await aggregateFor(db, [updated.id]);
+    return c.json(
+      serializeLink(updated, agg.get(updated.id), env.API_PUBLIC_URL),
+      200,
+    );
+  })
+  .openapi(archiveLinkRoute, async (c) => {
+    const { db, env } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const archivedAt = new Date();
+    // Archive only if not already archived — a second DELETE is a 404, not a
+    // silent re-archive. History (link_clicks via tracked_links) survives.
+    const [archived] = await db
+      .update(links)
+      .set({ archivedAt, updatedAt: archivedAt })
+      .where(and(eq(links.id, id), isNull(links.archivedAt)))
+      .returning();
+
+    if (!archived) {
+      return c.json({ error: "Link not found" }, 404);
+    }
+
+    const agg = await aggregateFor(db, [archived.id]);
+    return c.json(
+      serializeLink(archived, agg.get(archived.id), env.API_PUBLIC_URL),
+      200,
+    );
+  });

package/src/routes/tracking/identify.ts

@@ -1,9 +1,12 @@
+import { createHash } from "node:crypto";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
 import {
+  IDENTITY_TOKEN_TTL_SECONDS,
   InvalidIdentityTokenError,
   validateIdentityToken,
 } from "../../lib/identity-token.js";
+import { getRedis } from "../../lib/redis.js";
 
 /**
  * Exchange a redirect identity token (`hs_t`) for the distinct id, AND — when
@@ -82,6 +85,50 @@ export const identifyRouter = new OpenAPIHono<AppEnv>().openapi(
       throw err;
     }
 
+    // SINGLE-USE BURN (anti-reshare): a tracked link can be forwarded, so the
+    // `hs_t` token rides into other inboxes. The control is single-use — the
+    // FIRST exchange of a token wins; a second exchange of the SAME token must
+    // NOT fire another identify/merge (a reshared link can't keep folding the
+    // subject around). Key on a sha256 of the RAW token (never the plaintext id)
+    // and claim it atomically with SET … NX; if the claim loses (`null`), the
+    // token is already spent → return a 200 no-op (never error the landing
+    // page). TTL matches the token lifetime so the sentinel covers the whole
+    // window in which the token would still validate.
+    // The resolve-only response (no server merge) — returned when the token is
+    // already spent.
+    const resolveOnly = {
+      distinctId: payload.distinctId,
+      src: payload.src,
+      emailSendId: payload.emailSendId,
+    };
+    const burnKey = `hs_t:burn:${createHash("sha256").update(token).digest("hex")}`;
+    try {
+      const claimed = await getRedis().set(
+        burnKey,
+        "1",
+        "EX",
+        IDENTITY_TOKEN_TTL_SECONDS,
+        "NX",
+      );
+      if (claimed === null) {
+        // Token already spent — no-op (no identify/merge), still 200 the page.
+        logger.info("identify: token already spent (single-use burn)", {
+          src: payload.src,
+        });
+        return c.json(resolveOnly, 200);
+      }
+    } catch (err) {
+      // Redis unavailable — degrade to the normal identify. The burn works when
+      // Redis is up (≈ always); a Redis-down window restores the pre-burn merge
+      // behaviour rather than coupling the exchange to Redis liveness or dropping
+      // legitimate first-time merges. Never fail the exchange. (A stricter deploy
+      // could fail CLOSED here — skip the merge — to also close the narrow
+      // reshare-during-outage replay window; we accept it as best-effort.)
+      logger.warn("identify: single-use burn unavailable (degrading)", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
     // MF-5 — fire the alias FIRE-AND-FORGET (never await on the response path)
     // and respond synchronously. The token-proven canonical key is the survivor;
     // the caller's own session is the absorbed (anonymous) side. A provider