HealthLog/src/__tests__/record-session-fence-guard.test.ts

/**
 * Structural guards on the record-session fence.
 *
 * The behavioural proofs live in `src/lib/sharing/__tests__/record-session-fence.test.ts`
 * (the verdict and the refusals), `tests/integration/record-session-fence.test.ts`
 * (a refusal before any database work, with a positive control) and
 * `tests/integration/record-session-fence-idempotency.test.ts` (a refusal above
 * the replay cache). Those prove what today's code does. This file freezes what
 * tomorrow's may not do, because the fence has one shape that makes it worth
 * anything:
 *
 *   * exactly two auth helpers consult it, and both consult it BEFORE they read
 *     a carrier or look up a grant;
 *   * the helpers that deliberately do not consult it still do not;
 *   * one file writes the epoch and a closed list reads it;
 *   * the header names live in four files and no fifth: declared in the contract
 *     module, read by the server fence, attached by the browser transport, and
 *     published by the OpenAPI route module.
 *
 * ## What these matchers cannot see
 *
 * Everything here is a text match over source, so the guard's own limit is
 * worth writing down the way `session-surface-guard.test.ts` writes down its
 * own: **a fence bypass under a different header name would slip every matcher
 * below.** A future module that read `x-healthlog-record-context` and made its
 * own admission decision would be invisible here, exactly as the share-link
 * tree was invisible to a sweep that grepped only for `getSession`. The header
 * leg pins the names that exist; it cannot pin the ones that do not yet.
 *
 * Nor can it prove ordering at runtime. The placement legs compare source
 * offsets inside a function body, which is a proxy for execution order and
 * holds only because neither call sits inside a branch. The runtime property —
 * "no grant was looked up" — is proved by the integration file's `lastUsedAt`
 * and `sharing.record.accessed` instruments and by the `findActiveGrant`
 * zero-call spy, not here.
 *
 * Every leg asserts a non-zero match count before it asserts a set, because a
 * guard whose matcher finds nothing reports success, and this repository has
 * shipped several of those.
 */
import { describe, it, expect } from "vitest";
import { join } from "node:path";

import { authGuardsText, guardSourceOf } from "./helpers/auth-guards";
import {
  readSource,
  readSourceText,
  walkSourceFiles,
} from "./helpers/source-files";

const SRC = join(process.cwd(), "src");

function sourceFiles(): string[] {
  return walkSourceFiles(SRC, { floor: 3000 })
    .filter((p) => !p.startsWith("generated/"))
    .filter((p) => !p.includes("__tests__"))
    .filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"))
    .sort();
}

function read(rel: string): string {
  return readSourceText(join(SRC, rel));
}

function filesMatching(re: RegExp): string[] {
  return sourceFiles().filter((rel) => re.test(read(rel)));
}

/**
 * The source text of a top-level exported function, braces included. Same
 * brace-matching walk `acting-account-boundary-guard.test.ts` uses.
 */
function functionBody(src: string, name: string): string {
  const start = src.indexOf(`export async function ${name}(`);
  if (start === -1) return "";
  const open = src.indexOf("{", src.indexOf(")", start));
  let depth = 0;
  for (let i = open; i < src.length; i++) {
    if (src[i] === "{") depth++;
    else if (src[i] === "}") {
      depth -= 1;
      if (depth === 0) return src.slice(open, i + 1);
    }
  }
  return "";
}

/**
 * The auth layer: the route wrapper and every guard module it re-exports,
 * joined, with the two record resolvers as anchors so a move that loses them
 * throws instead of leaving the negative legs below green.
 */
const AUTH_LAYER = (() => {
  guardSourceOf("requireRecordAuth", ["requireGuardianAuth"]);
  return [
    readSource("src/lib/api-handler.ts", "apiHandler"),
    authGuardsText(),
  ].join("\n");
})();

/** The two helpers that resolve a record and therefore must consult the fence. */
const FENCED_RESOLVERS = ["requireRecordAuth", "requireGuardianAuth"] as const;

/**
 * The helpers that deliberately do NOT consult the fence.
 *
 * This is a statement about the HELPERS. It must not be read as "no admin route
 * is ever fenced", and it must not be read as the reverse either.
 * `POST /api/admin/backups/[id]/restore` composes `withIdempotency` OUTSIDE
 * `apiHandler`, so the wrapper's fence check runs on it — but that check
 * refuses only the STALE half. An `unfenced-client` verdict falls through to
 * the handler, whose `requireAdmin` is on this list, so a headerless admin
 * request is served exactly as it was before the fence existed. The accurate
 * claim is therefore narrow: an idempotent admin write under a context the
 * client asserted WRONGLY is refused; one that asserts nothing is not.
 *
 * Each entry's reason, once:
 *
 *   * `requireActorAuth` is the way OUT of a switch. Fencing it would make an
 *     unprovable context unrecoverable, and it serves the caller's own rows by
 *     definition, so the selector cannot change what it returns.
 *   * `requireAuth` bare already refuses outright under an active switch, and
 *     its routes are classified actor-only elsewhere.
 *   * `requireAdmin`, `requireCookieAuth` and `requireFreshMfa` resolve through
 *     `getSession()` and are structurally unreachable by a switch.
 */
const UNFENCED_HELPERS = [
  "requireAuth",
  "requireActorAuth",
  "requireAdmin",
  "requireCookieAuth",
  "requireFreshMfa",
] as const;

describe("the fence runs in exactly two auth helpers", () => {
  it("is called by both record resolvers and by nothing else in the auth layer", () => {
    const calls = [
      ...authGuardsText().matchAll(/assertRecordSessionFence\s*\(/g),
    ];
    expect(readSource("src/lib/api-handler.ts", "apiHandler")).not.toMatch(
      /assertRecordSessionFence\s*\(/,
    );
    // Non-zero proof: an emptied file would agree with an emptied expectation.
    expect(calls.length).toBeGreaterThan(0);

    const callers = FENCED_RESOLVERS.filter((name) =>
      functionBody(AUTH_LAYER, name).includes("assertRecordSessionFence("),
    );
    expect(callers).toEqual([...FENCED_RESOLVERS]);
    // Two call sites, one import. Anything else means a third caller appeared.
    expect(calls.length).toBe(FENCED_RESOLVERS.length);
  });

  it.each(FENCED_RESOLVERS)(
    "%s fences after authentication and before the carrier and the grant",
    (name) => {
      const body = functionBody(AUTH_LAYER, name);
      expect(body.length).toBeGreaterThan(100);

      const fence = body.indexOf("assertRecordSessionFence(");
      const authenticate = body.indexOf("authenticateCaller(");
      const carrier = body.indexOf("readActingCarrier(");
      expect(fence).toBeGreaterThan(-1);
      expect(authenticate).toBeGreaterThan(-1);
      expect(carrier).toBeGreaterThan(-1);

      // `authenticateCaller` NECESSARILY precedes the fence: it supplies the
      // session row the fence reads, and the whole atomicity argument rests on
      // both facts coming off that one read. So the invariant is "after
      // authentication, before the carrier" — NOT "before the first database
      // await", which would be false and must not be asserted here.
      expect(fence).toBeGreaterThan(authenticate);
      expect(fence).toBeLessThan(carrier);
    },
  );

  it("fences before any grant lookup in the shared resolver path", () => {
    // `findActiveGrant` lives in `resolveSwitchedRecord`, which both resolvers
    // tail-call. Assert it appears nowhere ABOVE the fence in either body.
    const grantCalls = [...authGuardsText().matchAll(/findActiveGrant\s*\(/g)];
    expect(grantCalls.length).toBeGreaterThan(0);

    for (const name of FENCED_RESOLVERS) {
      const body = functionBody(AUTH_LAYER, name);
      const fence = body.indexOf("assertRecordSessionFence(");
      const grant = body.indexOf("findActiveGrant(");
      // Either the body never names it (it is in the shared tail) or it names
      // it after the fence. Both are the property; neither may invert.
      if (grant !== -1) expect(fence).toBeLessThan(grant);
    }
  });

  it.each(UNFENCED_HELPERS)("%s deliberately does not fence", (name) => {
    const body = functionBody(AUTH_LAYER, name);
    expect(body.length).toBeGreaterThan(50);
    expect(body).not.toContain("assertRecordSessionFence");
  });

  it("the two unfenced routes stay unfenced", () => {
    // `/api/auth/me` is the reconciliation bootstrap and must answer while the
    // client's context is unknown; the switch endpoint is the way out of a
    // context that cannot be proved. Fencing either would make an unprovable
    // context unrecoverable.
    const me = readSource("src/app/api/auth/me/route.ts", "requireActorAuth");
    const sw = readSource(
      "src/app/api/account/switch/route.ts",
      "requireActorAuth",
    );
    expect(me).toContain("requireActorAuth");
    expect(sw).toContain("requireActorAuth");
    expect(me).not.toContain("assertRecordSessionFence");
    expect(sw).not.toContain("assertRecordSessionFence");
  });
});

/**
 * Both lists below grow as the feature lands, and that is the point rather than
 * a defect: the idempotency arm and the browser's adopted-context module each
 * arrive as a visible diff here rather than as a quiet new reader. Same posture
 * as `CARRIER_ALLOWLIST` in `acting-account-boundary-guard.test.ts`.
 */
describe("the epoch has one writer and a closed reader set", () => {
  it("is written in exactly one file", () => {
    // The SQL spelling only. `acting-session.ts` owns the conditional write
    // because it needs `RETURNING`, which no model delegate expresses — and
    // keeping the statement there is what keeps this list at one.
    const writers = filesMatching(/record_epoch/);
    expect(writers.length).toBeGreaterThan(0);
    expect(writers).toEqual(["lib/sharing/acting-session.ts"]);
  });

  it("is read by a closed list and nothing else", () => {
    // The identifier, bounded so `recordEpochParameter` in the OpenAPI module
    // does not count — that file publishes a header name, it does not read a
    // column.
    const readers = filesMatching(/\brecordEpoch(?![\w$])/);
    expect(readers.length).toBeGreaterThan(0);
    expect(readers).toEqual(
      [
        // Projects it off the session row it already loaded.
        "lib/auth/session.ts",
        // Carries it on the auth context the fence is handed.
        "lib/auth/guards/context.ts",
        // Compares it. The one place that decides anything from it.
        "lib/sharing/record-session-fence.ts",
        // Reads it off the same session lookup the idempotency wrapper already
        // makes, so the fence can be evaluated above the replay cache without a
        // second round trip.
        "lib/auth/acting-carrier.ts",
      ].sort(),
    );
  });

  it("is consulted by the idempotency wrapper, above the cache", () => {
    const src = readSource(
      "src/lib/idempotency.ts",
      "refuseStaleRecordSessionClaim(claim)",
    );
    const fence = src.indexOf("refuseStaleRecordSessionClaim(claim)");
    const cache = src.indexOf("findCached(ctx)");
    const claimRow = src.indexOf("claimKey(ctx)");
    expect(fence).toBeGreaterThan(-1);
    expect(cache).toBeGreaterThan(-1);
    expect(claimRow).toBeGreaterThan(-1);
    // A stale request must not learn whether a cell exists, replay a body out
    // of one, or insert a claim row. The runtime proof is the zero-call
    // instrument in `src/lib/__tests__/idempotency.test.ts`; this is the
    // tripwire that says the line moved.
    expect(fence).toBeLessThan(cache);
    expect(fence).toBeLessThan(claimRow);
    // And it comes from the fence module, not from a second copy of the rule.
    expect(src).toContain('from "@/lib/sharing/record-session-fence"');
  });

  it("does not leak the raw counter into the browser's vocabulary", () => {
    // The client never names the epoch as a column. It receives
    // `recordSession: { epoch, scope }` and asserts it back as a header, which
    // is why no file under `hooks/` or `components/` appears in the list above.
    // A client that started naming `recordEpoch` would be reaching past the
    // published shape into the row.
    const clientReaders = filesMatching(/\brecordEpoch(?![\w$])/).filter(
      (rel) =>
        rel.startsWith("hooks/") ||
        rel.startsWith("components/") ||
        rel.startsWith("app/"),
    );
    expect(clientReaders).toEqual([]);
  });
});

describe("the header names live in a closed set of files", () => {
  it("is declared, read and published — and nowhere else", () => {
    // Mirrors the `x-healthlog-account` leg in
    // `acting-account-boundary-guard.test.ts`. A route that started reading
    // these headers itself would be making an admission decision the fence
    // exists to make once.
    const namers = filesMatching(
      /RECORD_EPOCH_HEADER|RECORD_SCOPE_HEADER|x-healthlog-record-(epoch|scope)/i,
    );
    expect(namers.length).toBeGreaterThan(0);
    expect(namers).toEqual([
      // Attaches them to every same-origin request, and validates the echo.
      "lib/api/record-fence.ts",
      // Publishes them to the clients that have to send them.
      "lib/openapi/routes/account-sharing.ts",
      // Declares them.
      "lib/sharing/record-session-fence-contract.ts",
      // Reads them off the request scope, and writes the response echo.
      // `apiHandler` attaches the echo through this module's helper rather than
      // naming the headers itself, which is what keeps this list at four.
      "lib/sharing/record-session-fence.ts",
    ]);
  });

  it("keeps the 409's code in the contract module and the client that branches on it", () => {
    const namers = filesMatching(/sharing\.session\.changed/);
    expect(namers.length).toBeGreaterThan(0);
    // The error class reads the constant rather than restating the string, so
    // `api-handler.ts` is deliberately NOT on this list.
    expect(namers).toContain("lib/sharing/record-session-fence-contract.ts");
  });
});