HealthLog/src/app/api/share-links/route.ts

/**
 * /api/share-links — owner clinician-share-link lifecycle (Epic C, C4).
 *
 *   POST  → create a link. Mints an `hls_<48 hex>` token (192-bit), stores
 *           ONLY its HMAC hash, returns the raw token EXACTLY ONCE. Every
 *           scope column is frozen write-once at creation.
 *   GET   → list the caller's own links (never the raw token — it is
 *           unrecoverable after the create response).
 *
 * Auth: cookie session OR Bearer (`requireAuth`). `userId` is always narrowed
 * from the auth context; there is no `userId` body field. Rate-limited.
 * This is the OWNER lifecycle only — the public resolver / view (C3/C5) is a
 * separate surface.
 */
import { randomBytes } from "node:crypto";
import { NextRequest } from "next/server";

import { apiHandler, requireAuth } from "@/lib/api-handler";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { hashToken } from "@/lib/auth/hmac";
import {
  apiError,
  apiSuccess,
  getClientIp,
  returnAllZodIssues,
  safeJson,
} from "@/lib/api-response";
import { checkRateLimit } from "@/lib/rate-limit";
import { prisma } from "@/lib/db";
import { createShareLinkSchema } from "@/lib/validations/clinician-share-link";
import { EMPTY_DOCTOR_REPORT_PREFS } from "@/lib/validations/doctor-report-prefs";
import {
  generatePassphrase,
  hashPassphrase,
  normalisePassphrase,
  PASSPHRASE_FRAGMENT_KEY,
} from "@/lib/clinician-share/passphrase";
import type { Prisma } from "@/generated/prisma/client";

/**
 * The absolute origin to build the public share URL from. Prefers the
 * forwarded host/proto a reverse proxy sets (the documented self-hosting path
 * fronts the app with Caddy/Traefik/Nginx), falling back to the request URL's
 * own origin. The QR payload carries the passphrase in the FRAGMENT only.
 */
function resolveOrigin(request: NextRequest): string {
  const proto =
    request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim() ||
    new URL(request.url).protocol.replace(":", "");
  const host =
    request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() ||
    request.headers.get("host") ||
    new URL(request.url).host;
  return `${proto}://${host}`;
}

/**
 * The row selection every owner-facing projection reads. `_count.documents`
 * surfaces the size of the frozen document set without ever loading the ids
 * (let alone the blobs) — the metadata-only discipline (P3-D5).
 */
const shareLinkSummarySelect = {
  id: true,
  label: true,
  rangeStart: true,
  rangeEnd: true,
  resourceTypes: true,
  allowFhirApi: true,
  documentOnly: true,
  passphraseHash: true,
  expiresAt: true,
  createdAt: true,
  revokedAt: true,
  lastAccessAt: true,
  accessCount: true,
  _count: { select: { documents: true } },
} as const;

/** Project a stored row to the safe owner-facing shape (never the token). */
function toSummary(row: {
  id: string;
  label: string;
  rangeStart: Date;
  rangeEnd: Date | null;
  resourceTypes: string[];
  allowFhirApi: boolean;
  documentOnly: boolean;
  passphraseHash: string | null;
  expiresAt: Date;
  createdAt: Date;
  revokedAt: Date | null;
  lastAccessAt: Date | null;
  accessCount: number;
  _count: { documents: number };
}) {
  return {
    id: row.id,
    label: row.label,
    rangeStart: row.rangeStart.toISOString(),
    rangeEnd: row.rangeEnd ? row.rangeEnd.toISOString() : null,
    resourceTypes: row.resourceTypes,
    allowFhirApi: row.allowFhirApi,
    // v1.28.16 — the frozen documents-only flag (owner-facing; the serve path
    // gates on the column, not on "are all sections off?").
    documentOnly: row.documentOnly,
    // v1.18.7 — surface only WHETHER a passphrase guards the link, never the
    // hash itself. Legacy (null-hash) links read `false` and stay ungated.
    protected: row.passphraseHash !== null,
    // v1.28 — how many documents this share carries (never the ids, never the
    // bytes; the serve route is the only decrypt path).
    documentCount: row._count.documents,
    expiresAt: row.expiresAt.toISOString(),
    createdAt: row.createdAt.toISOString(),
    revokedAt: row.revokedAt ? row.revokedAt.toISOString() : null,
    lastAccessAt: row.lastAccessAt ? row.lastAccessAt.toISOString() : null,
    accessCount: row.accessCount,
    // Status the UI can render without re-deriving expiry/revocation.
    active: row.revokedAt === null && row.expiresAt.getTime() > Date.now(),
  };
}

export const POST = apiHandler(async (request: NextRequest) => {
  const { user } = await requireAuth();
  annotate({ action: { name: "share-link.create" } });

  const rl = await checkRateLimit(`share-link:${user.id}`, 20, 60 * 60 * 1000);
  if (!rl.allowed) {
    return apiError("Maximum 20 share-link operations per hour", 429);
  }

  const { data: body, error: jsonError } = await safeJson(request, {
    maxBytes: 16 * 1024,
  });
  if (jsonError) return jsonError;

  const parsed = createShareLinkSchema.safeParse(body);
  if (!parsed.success) {
    return returnAllZodIssues(parsed.error);
  }
  const input = parsed.data;

  // v1.28.13 — a documents-only share carries NO report scope. Force the scope
  // columns to empty here (not just at the client) so a document link can never
  // serve a single health metric, whatever the body tried to smuggle: no
  // sections (an explicit all-OFF prefs blob, distinct from the `{}` that means
  // "full record defaults"), no FHIR resource types, FHIR API off. "Share this
  // document" means the document, not the whole record.
  const documentOnly = input.documentOnly === true;
  const sectionsJson = documentOnly
    ? EMPTY_DOCTOR_REPORT_PREFS
    : (input.sections ?? {});
  const resourceTypes = documentOnly ? [] : (input.resourceTypes ?? []);
  const allowFhirApi = documentOnly ? false : (input.allowFhirApi ?? false);
  annotate({ meta: { documentOnly } });

  // Mint the 192-bit raw token, store only its HMAC hash.
  const rawToken = `hls_${randomBytes(24).toString("hex")}`;
  const tokenHash = hashToken(rawToken);

  // v1.18.7 — always mint a passphrase second factor; store only its HMAC
  // hash. The raw passphrase is returned exactly once below. `normalisePassphrase`
  // is the canonical store form so the grouped (`XXXX-XXXX-…`) display and the
  // bare fragment value collide to one hash.
  const rawPassphrase = generatePassphrase();
  const passphraseHash = hashPassphrase(normalisePassphrase(rawPassphrase)!);

  // v1.28 — resolve the frozen document set. The ids are deduped (a client
  // could repeat one, which the unique membership index would otherwise
  // reject) and then validated as the caller's OWN live documents. A single
  // foreign / deleted / unknown id seals the whole create as 422 — no share is
  // ever minted with a document the caller does not own (B5). The rows are
  // created in the SAME transaction as the link (nested create), so the
  // membership is frozen write-once atomically with the scope columns.
  const documentIds = Array.from(new Set(input.documentIds ?? []));
  if (documentIds.length > 0) {
    const owned = await prisma.inboundDocument.findMany({
      where: { id: { in: documentIds }, userId: user.id, deletedAt: null },
      select: { id: true },
    });
    if (owned.length !== documentIds.length) {
      return apiError("One or more documents are not available to share", 422, {
        errorCode: "share-link.documents.invalid",
      });
    }
  }

  // Field-by-field build — no mass assignment. Scope columns are written
  // exactly once here and never updated.
  const created = await prisma.clinicianShareLink.create({
    data: {
      userId: user.id,
      tokenHash,
      passphraseHash,
      label: input.label,
      rangeStart: new Date(input.rangeStart),
      rangeEnd: input.rangeEnd ? new Date(input.rangeEnd) : null,
      sectionsJson: sectionsJson as Prisma.InputJsonValue,
      resourceTypes,
      allowFhirApi,
      documentOnly,
      expiresAt: new Date(input.expiresAt),
      documents:
        documentIds.length > 0
          ? { create: documentIds.map((documentId) => ({ documentId })) }
          : undefined,
    },
    select: shareLinkSummarySelect,
  });

  await auditLog("share-link.create", {
    userId: user.id,
    ipAddress: getClientIp(request),
    details: {
      shareLinkId: created.id,
      resourceTypes: created.resourceTypes,
      allowFhirApi: created.allowFhirApi,
      documentCount: created._count.documents,
      expiresAt: created.expiresAt.toISOString(),
    },
  });

  // The raw token AND raw passphrase are returned exactly once; both are
  // unrecoverable thereafter. The QR/deep-link payload carries the passphrase
  // in the URL FRAGMENT (`#k=`) — never the path or query — so it is never
  // sent to the server, kept out of logs, referrers, and the access record.
  const origin = resolveOrigin(request);
  const shareUrl = `${origin}/c/${rawToken}`;
  const qrUrl = `${shareUrl}#${PASSPHRASE_FRAGMENT_KEY}=${rawPassphrase}`;
  return apiSuccess(
    {
      ...toSummary(created),
      token: rawToken,
      passphrase: rawPassphrase,
      shareUrl,
      qrUrl,
    },
    201,
  );
});

export const GET = apiHandler(async () => {
  const { user } = await requireAuth();
  annotate({ action: { name: "share-link.list" } });

  const rows = await prisma.clinicianShareLink.findMany({
    where: { userId: user.id },
    orderBy: { createdAt: "desc" },
    select: shareLinkSummarySelect,
  });

  return apiSuccess({ shareLinks: rows.map(toSummary) });
});