fix(search): admit the search POST at read level through a declared, frozen readOverPost

src/lib/__tests__/acting-account-resolver.test.ts

@@ -505,6 +505,29 @@ describe("requireRecordAuth — every way a grant can fail", () => {
     );
   });
 
+  it("reads a POST at read level only where the route declares readOverPost", async () => {
+    signedInCookie(OWNER);
+    liveGrant();
+    const declared = route(() =>
+      requireRecordAuth("read", "record", { readOverPost: true }),
+    );
+    expect((await declared("POST")).status).toBe(200);
+    // The declaration covers POST alone: every other write method still
+    // needs a write grant.
+    for (const method of ["PUT", "PATCH", "DELETE"]) {
+      expect((await declared(method)).status, method).toBe(403);
+    }
+  });
+
+  it("does not lower a declared write for a readOverPost route", async () => {
+    signedInCookie(OWNER);
+    liveGrant();
+    const response = await route(() =>
+      requireRecordAuth("write", "record", { readOverPost: true }),
+    )("POST");
+    expect(response.status).toBe(403);
+  });
+
   it("refuses a declared write under a read grant", async () => {
     signedInCookie(OWNER);
     liveGrant();

src/lib/api-handler.ts

@@ -889,6 +889,19 @@ export interface RecordAuthOptions {
    * else.
    */
   readonly scope?: string;
+  /**
+   * v1.42.2 — this route answers a POST without changing anything: the body
+   * carries a query that must not stand in a URL (the record search, whose
+   * text is health data a proxy's access log would otherwise keep). Under a
+   * route declaring `"read"`, a POST is then read at the grant's read level
+   * instead of being escalated to a write.
+   *
+   * Like `scope`, naming it is a WIDENING and is frozen by
+   * `read-over-post-guard.test.ts`, so it lands in a reviewed diff. It does
+   * nothing for any other method, and nothing for a route declaring a need
+   * above `"read"`.
+   */
+  readonly readOverPost?: true;
 }
 
 /**
@@ -980,8 +993,11 @@ export async function requireRecordAuth(
   }
 
   const method = (getEvent()?.getHttpMethod() ?? "").toUpperCase();
+  const readsOnly =
+    READ_HTTP_METHODS.has(method) ||
+    (options?.readOverPost === true && method === "POST");
   const effectiveNeed: GrantNeed =
-    need !== "read" || !READ_HTTP_METHODS.has(method) ? escalate(need) : "read";
+    need !== "read" || !readsOnly ? escalate(need) : "read";
 
   return resolveSwitchedRecord(auth, carrier, (grant) => {
     if (!grantAllows(grant, effectiveNeed)) return "insufficient_access";