A link that expires, and who may hold it

if (channel?.type === "private" && !(await this.isMember(channelId, userId))) {
  return [];
}

async channelVisibleTo(channelId: string, userId?: string): Promise<boolean> {
  // …
  if (!channel) return false;
  if (channel.type !== "private" || userId === undefined) return true;
  return this.isMember(channelId, userId);
}

@@ -1,10 +1,12 @@
-import { Body, Controller, Post, Req, UseGuards } from "@nestjs/common";
+import { Body, Controller, Get, Param, Post, Req, UseGuards } from "@nestjs/common";
+import { z } from "zod";
 
 import { Accepts, CredentialGuard } from "../auth/credential.guard";
 import type { RequestWithPrincipal } from "../auth/principal";
+import { protocolError } from "../protocol-error";
 import { MediaService, type SlotRequest } from "./media.service";
 
 // THE UPLOAD SLOT (FR-MED-01). One route, and the bytes do not come through it.
 //
 // `Accepts("application", "user")` — BOTH, which is FR-MED-01's own wording: "on
 // request (user token or API key)". A photo sent by a person and an attachment
@@ -28,7 +30,45 @@
     // both ways — and an unreachable arm in a file the ratchet pins at 100% is a
     // coverage failure with no fix but a comment.
     const actingUser =
       req.principal?.kind === "user" ? req.principal.userExternalId : undefined;
     return this.media.createSlot(body, actingUser);
   }
+
+  /** A signed GET for an object the caller may read (FR-MED-08). 200 with a URL and an
+   * expiry, or 404 — the same 404 for an object of another tenant, an object referenced
+   * only where the caller cannot read, and an id no object has.
+   *
+   * THE PATH PARAMETER IS VALIDATED, AND NO OTHER ROUTE IN THIS API DOES THAT. Measured
+   * against the composed api before this route existed:
+   *
+   *     GET /v1/channels/not-a-uuid/messages
+   *     500 {"code":"internal_error","message":"unexpected internal error"}
+   *
+   * A malformed uuid reaches the driver, Postgres answers `invalid input syntax for type
+   * uuid`, and the filter has no rung for it — a caller-triggered 500 on sixteen shipped
+   * routes, thirteen taking `channelId` and three taking `messageId`. It is chapter
+   * 4.11's research R3 exactly, which found the same defect in a request BODY, measured
+   * it, and fixed it with `z.uuid()` — while nobody looked at the path. The other sixteen
+   * are recorded in `gaps.md` with their measurement rather than repaired here, because a
+   * chapter about signed delivery that rewrites three controllers is teaching two things
+   * badly.
+   *
+   * NOT THROUGH `ZodValidationPipe`, AND THE REASON IS ITS `field`. That pipe names the
+   * field from the zod issue's `path`, which is empty for a scalar and then omitted — so
+   * the reuse would answer 400 without saying which parameter was wrong. The check is
+   * three lines here and names `mediaId`. */
+  @Get(":mediaId")
+  deliver(@Param("mediaId") mediaId: string, @Req() req: RequestWithPrincipal) {
+    if (!z.uuid().safeParse(mediaId).success) {
+      throw protocolError(
+        "invalid_request",
+        "mediaId must be a uuid",
+        400,
+        "mediaId",
+      );
+    }
+    const actingUser =
+      req.principal?.kind === "user" ? req.principal.userExternalId : undefined;
+    return this.media.deliver(mediaId, actingUser);
+  }
 }

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
 
-import { HttpStatus, Injectable } from "@nestjs/common";
+import { BadRequestException, HttpStatus, Injectable } from "@nestjs/common";
 
 import { Repository } from "../db/repository";
 import { protocolError } from "../protocol-error";
 import { KIND_CAPS, kindOf } from "./kinds";
 import { presign } from "./presign";
 import { storeConfig, storeReady, type StoreConfig } from "./store";
@@ -20,12 +20,28 @@
   media_id: string;
   state: "pending";
   upload_url: string;
   expires_at: string;
 }
 
+export interface Delivery {
+  url: string;
+  expires_at: string;
+}
+
+/** FR-MED-08's one hour, against the upload slot's fifteen minutes.
+ *
+ * THE URL OUTLIVES THE AUTHORISATION THAT PRODUCED IT AND NOTHING HERE CAN FIX THAT. A
+ * caller issued a URL at minute 0 and removed from the channel at minute 1 holds a
+ * working link until minute 60: the store checks a signature and has never heard of a
+ * channel. Shortening the window trades one exposure for another — a URL that expires
+ * while a page is still rendering is a broken image — and revocation would mean the api
+ * standing in front of the bytes, which is what ADR-13 was decided against. The clause
+ * names the hour, so the hour is what ships and the window is published as a cost. */
+const DELIVERY_SECONDS = 3600;
+
 /** FR-MED-01's fifteen minutes. The STORE enforces it — a URL past its expiry comes
  * back `AccessDenied · Request has expired` from the store's own clock — and
  * `expires_at` below is published so a client can decide whether to reuse the URL
  * rather than so anything here can check it. */
 const SLOT_SECONDS = 900;
 
@@ -128,7 +144,59 @@
       state: "pending",
       upload_url,
       expires_at: new Date(Date.now() + SLOT_SECONDS * 1000).toISOString(),
     };
   }
 
+  /** A signed GET for an object this caller may read, or a refusal (FR-MED-08).
+   *
+   * THE SIGNER NEEDED NO CHANGE AND THAT IS ASSERTED RATHER THAN ARRANGED. `presign` has
+   * taken `"GET"` since chapter 4.10, and `presign.itest.ts:53` — titled "FR-MED-08's
+   * precondition" — already proves the other half of this clause from outside the
+   * container: a signed GET answers 200, an unsigned one 403, a tampered one 403. Half of
+   * what this chapter was asked for was built two chapters ago, and re-proving it would
+   * claim work somebody else did.
+   *
+   * THE EXTERNAL ID IS RESOLVED BEFORE THE PREDICATE SEES IT. `req.principal.userExternalId`
+   * is `tuan` or `delivery-bot`; `channelVisibleTo` reaches `isMember`, which compares
+   * against `members.user_id`, a `uuid` column. Handing one straight through is a
+   * caller-triggered 500 where a tenant's ids are not UUID-shaped — and something worse
+   * where they are, because no parse fails, `isMember` simply returns false, and every
+   * private channel silently refuses every member while every public one still works.
+   *
+   * `endpoint` AND NOT `internalEndpoint` (4.11's FR-026). This URL is handed to a client
+   * outside the network and the host is inside the SigV4 signature, so signing with the
+   * api's own address produces a URL the store refuses rather than one that is slow. */
+  async deliver(mediaId: string, userExternalId?: string): Promise<Delivery> {
+    let userId: string | undefined;
+    if (userExternalId !== undefined) {
+      const user = await this.repo.getUserByExternalId(userExternalId);
+      if (!user) throw new BadRequestException("unknown user");
+      userId = user.id;
+    }
+
+    const objectKey = await this.repo.readableMediaObjectKey(mediaId, userId);
+    // ONE ANSWER FOR THREE CONDITIONS — another environment's object, an object
+    // referenced only where this caller cannot read, and an id no object has. The
+    // precedent is `channelVisibleTo`'s own: the leak it was written to close was a
+    // private channel answering `200, empty page` where an absent one answered 404, and
+    // the fix was to make both answer identically. A refusal that names its cause reports
+    // whether somebody else's object exists.
+    if (objectKey === undefined) {
+      throw protocolError(
+        "not_found",
+        "no such media object",
+        HttpStatus.NOT_FOUND,
+      );
+    }
+
+    return {
+      url: presign({
+        method: "GET",
+        ...this.store,
+        key: objectKey,
+        expiresIn: DELIVERY_SECONDS,
+      }),
+      expires_at: new Date(Date.now() + DELIVERY_SECONDS * 1000).toISOString(),
+    };
+  }
 }

{ "url": "http://localhost:9100/relay-media/<env>/<id>?X-Amz-Algorithm=…&X-Amz-Expires=3600&…",
  "expires_at": "2026-09-20T04:04:11.000Z" }

@@ -5526,12 +5526,109 @@
       );
     if (!channel) return false;
     if (channel.type !== "private" || userId === undefined) return true;
     return this.isMember(channelId, userId);
   }
 
+  /** The `object_key` of a media object this caller may read, or `undefined` (FR-MED-08).
+   *
+   * Three questions, and each refusal is the same refusal: does this environment own an
+   * object with that id, which of this environment's channels carry a message referencing
+   * it, and may this caller see any of them.
+   *
+   * TWO QUERIES AND NOT ONE, WHICH IS THE OPPOSITE OF WHAT THE PLAN SAID. The design this
+   * chapter was planned with was a single three-way join — `media_objects` to `messages`
+   * on containment to `channels` — and it is the shape that makes the new GIN index
+   * unusable. The containment operand is built from `o.id`, a value from the other side of
+   * the join, so the planner cannot look it up; it narrows to the tenant's channels and
+   * applies containment as a join filter over every message they hold. Measured on the
+   * lane's busiest tenant, 1,018 messages:
+   *
+   *     one joined query, a hit     Nested Loop, `Rows Removed by Join Filter: 1017`
+   *                                 86 buffers · 1.109 ms · the index unused
+   *     two queries, a hit           3 + 17 buffers · 0.034 + 0.077 ms
+   *                                 `Bitmap Index Scan on messages_attachments_gin`
+   *
+   * Splitting it makes the containment operand a bound value, which is the only form the
+   * index can serve. The scope survives the split — step two still names this environment
+   * — and so does the reason for reading the object row at all: `object_key` is what
+   * `presign` signs, and reading it is what makes the object's own `environment_id` a
+   * check this route performs rather than one it inherits from the send path.
+   *
+   * AND THE SMALL TENANT HID IT. The same one-query plan costs 14 buffers on a
+   * nine-message environment, which is what the analysis passes measured. Its cost is the
+   * tenant's message count; the two-query cost is not.
+   *
+   * `channelVisibleTo` IS REUSED RATHER THAN REWRITTEN, and that is FR-MED-08's note
+   * being satisfied by construction. The clause says media access "inherits channel
+   * membership rather than inventing a parallel ACL system" — a second predicate written
+   * here would be a parallel ACL however faithfully it copied the first. It also answers
+   * the clause's own "or API key" arm, because `userId === undefined` means the tenant is
+   * reading and sees everything it owns.
+   *
+   * AND READING THE CLAUSE LITERALLY WOULD HAVE BEEN STRICTER THAN THE MESSAGE. FR-MED-08
+   * says "channel membership"; this platform checks membership for `private` channels
+   * only, so a membership test would refuse a user the photo in a message whose text they
+   * can read. 11,557 public channels against 1,016 private on this lane. */
+  async readableMediaObjectKey(
+    mediaId: string,
+    userId?: string,
+  ): Promise<string | undefined> {
+    const [object] = await this.db
+      .select({ objectKey: mediaObjects.objectKey })
+      .from(mediaObjects)
+      .where(
+        and(
+          eq(mediaObjects.id, mediaId),
+          eq(mediaObjects.environmentId, this.environmentId),
+        ),
+      );
+    if (!object) return undefined;
+
+    for (const channelId of await this.channelsReferencingMedia(mediaId)) {
+      if (await this.channelVisibleTo(channelId, userId)) return object.objectKey;
+    }
+    return undefined;
+  }
+
+  /** Every channel of this environment holding a message that references this object.
+   *
+   * EVERY REFERENCING CHANNEL, NOT THE FIRST AND NOT EVERY REFERENCE. FR-MED-08's
+   * singular — "the referencing message" — does not describe this platform: FR-MSG-11 has
+   * allowed the same id twice since 3.24, and forwarding a photo is the ordinary way one
+   * object acquires a second reference. Authorisation is a disjunction over them, so a
+   * query that stopped at the first row would refuse a caller whose channel happened to be
+   * second — a correctness bug that presents as flakiness.
+   *
+   * `DISTINCT` BOUNDS IT BY CHANNEL. A photo forwarded into one channel a hundred times is
+   * one authorisation question, not a hundred, and a private channel costs two queries per
+   * question rather than one.
+   *
+   * SCOPED HERE AND NOT ONLY IN THE CALLER. `channelVisibleTo` refuses another tenant's
+   * channel afterwards, so the predicate below is redundant for correctness — and without
+   * it this is the only read in this file that would scan every tenant's rows. A query
+   * whose safety depends on a later call is a query somebody will reuse without it. */
+  private async channelsReferencingMedia(mediaId: string): Promise<string[]> {
+    const rows = await this.db
+      .selectDistinct({ id: channels.id })
+      .from(messages)
+      .innerJoin(channels, eq(channels.id, messages.channelId))
+      .where(
+        and(
+          // THE OPERAND IS A BOUND VALUE, WHICH IS WHAT THE INDEX NEEDS. Built here
+          // rather than in SQL from a joined column: `jsonb_build_array(...)` over
+          // `o.id` is an expression the planner cannot look up.
+          sql`${messages.attachments} @> ${JSON.stringify([
+            { type: "media", media_id: mediaId },
+          ])}::jsonb`,
+          eq(channels.environmentId, this.environmentId),
+        ),
+      );
+    return rows.map((row) => row.id);
+  }
+
   async channelExists(channelId: string): Promise<boolean> {
     const rows = await this.db
       .select({ id: channels.id })
       .from(channels)
       .where(
         and(

-- Chapter 4.12 — the reference lookup, and the index that is not the point.
--
-- FR-MED-08 issues a signed URL "only to callers authorised to read the referencing
-- message", so the route has to find which messages reference a `media_id`. That question
-- lives in `messages.attachments`, a jsonb column nothing has ever queried: every index on
-- this table today is `(channel_id, sequence)`, `(channel_id, idempotency_key)` or the
-- primary key.
--
-- `jsonb_path_ops` AND NOT THE DEFAULT `jsonb_ops`. The only operator this route uses is
-- containment -- `attachments @> '[{"type":"media","media_id":"…"}]'` -- which is the one
-- class `jsonb_path_ops` supports, and the reason it is the smaller of the two.
--
-- ON THE WHOLE COLUMN, NOT A PARTIAL INDEX ON THE MEDIA ARM. A partial index
-- (`WHERE attachments @> '[{"type":"media"}]'`) would be smaller still and would make the
-- planner's choice depend on the query's predicate matching the index's own -- which works
-- until somebody writes the query slightly differently and gets a sequential scan with no
-- error.
--
-- `CREATE INDEX` AND NOT `CREATE INDEX CONCURRENTLY`, AND THE CHOICE IS NOT OPEN.
-- `migrate.ts:46` issues `BEGIN` around every file in this directory, and the server
-- refuses: `CREATE INDEX CONCURRENTLY cannot run inside a transaction block`. Asked of
-- Postgres rather than reasoned about. The cost is a lock that blocks writes to `messages`
-- for the duration of the build -- milliseconds on a lane, a deploy-shaped number on a
-- table with a million rows, and a table this platform expects to be large.
CREATE INDEX messages_attachments_gin
  ON messages USING gin (attachments jsonb_path_ops);

@@ -410,12 +412,24 @@
       .on(t.channelId, t.idempotencyKey)
       .where(sql`${t.idempotencyKey} IS NOT NULL`),
     // No dedicated (channel_id, sequence DESC) index: DR-01's unique
     // constraint above already supplies that ordering, and Postgres walks
     // it backward for newest-first pages. Chapter 2.4 measured it and
     // migration 0001 dropped the redundant twin (SAD §6.3, amended).
+    //
+    // THE FIRST NON-BTREE INDEX IN THIS SCHEMA (chapter 4.12, migration 0017).
+    // `grep -c 'using('` here was 0 before this line: every other entry is a
+    // plain btree or a unique constraint, so there was no local shape to copy.
+    // `jsonb_path_ops` supports containment and nothing else, which is the only
+    // operator the media delivery route uses and the reason it is the smaller
+    // of the two operator classes.
+    //
+    // THE MIGRATION IS THE SOURCE OF TRUTH (ADR-16: forward-only, hand-reviewed
+    // SQL). This declaration exists so the next generator run does not propose
+    // to drop an index the migration created.
+    index("messages_attachments_gin").using("gin", t.attachments.op("jsonb_path_ops")),
   ],
 );
 
 // WHAT A MESSAGE USED TO SAY (FR-MSG-07). Published in SAD §6.1
 // since the SAD was written and built here — the absence note above named this
 // chapter as its arrival.

// ── THE DELIVERY URL (chapter 4.12, FR-MED-08), AND THE DERIVATION FOUND IT NINTH ──
//
// `read` AND NOT `credential`, WHICH IS THE OPPOSITE CALL FROM ITS SIBLING ONE ENTRY
// UP AND FOR THE SAME REASON. `POST /v1/media` is `credential` because its body carries
// no identifier a foreign tenant could forge. This route's whole input IS an
// identifier: a `media_id` in the path, minted by the platform for one environment.
{ method: "GET", path: "/v1/media/:mediaId", accepts: "either", shape: "read" },