create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/listing-promotion.ts

@@ -0,0 +1,342 @@
+/**
+ * @file listing-promotion.ts
+ * @description ProjectListing → owner-user linking across the inbox/auth
+ * namespace boundary (#5295; ADR 0009 D3 service-layer pattern).
+ *
+ * The sibling of `lead-promotion.ts`, for the same shape of problem. A
+ * `ProjectListing` is written on an ANONYMOUS route: `founderEmail` is a string
+ * a stranger typed into a form, and nothing about typing an address proves you
+ * own it. So `founderEmail` can never by itself say whose row it is — two
+ * people who type the same address are two people — and this service
+ * materializes the ownership claim that a read may actually join on.
+ *
+ * The link is stamped only when ALL THREE hold:
+ *
+ *   1. the reconciling user's OWN email is VERIFIED (`User.emailVerified`) —
+ *      the consent basis, inherited from `lead-promotion.ts` D2, and a
+ *      service-level invariant rather than a caller obligation, so a wrong
+ *      call-site cannot bypass it;
+ *   2. that verified address matches the listing's `founderEmail`;
+ *   3. the listing's `siteId` is one of that user's OWN tenant workspaces —
+ *      the tenant-safety invariant (`lead-promotion.ts` D3), which is what
+ *      makes a row captured under another organization's workspace unmatchable
+ *      by construction rather than by a later filter.
+ *
+ * Any one failing is a NO-OP returning `count: 0`, never a throw — the lead
+ * service's posture, for the same reason: this runs on a reconciliation path
+ * (an email-verification callback, a sign-in), where a throw would fail an
+ * unrelated request that had nothing to do with listings.
+ *
+ * And one condition the lead service does NOT have: the match must be
+ * UNAMBIGUOUS. Two strangers can type the same address into the anonymous form,
+ * and when they do nothing says which of the two rows is whose — so a row is
+ * claimed only when it is the only un-linked row carrying that address at its
+ * site. See the refusal block in the body; this is the difference between
+ * mirroring the lead service's mechanism and inheriting a disclosure from it.
+ *
+ * Workspace resolution is delegated to `tenant-context.ts`'s `listTenancy` —
+ * the sole cross-namespace tenancy assembler — so this file never issues a raw
+ * membership or workspace model query of its own (`architecture.yaml`'s
+ * tenant-scope forbidden pattern reserves those to
+ * `tenant-context.ts` / `tenant-db.ts`). That delegation is module-conditional;
+ * see the note above TENANT_CONTEXT_SPECIFIER.
+ *
+ * PII boundary: this module never logs or returns `founderEmail`,
+ * `founderName`, or any application answer. The result carries ids only — a
+ * listing id and the workspace id it sits in.
+ *
+ * NOTE for whoever wires this to a verification hook: `internal_error` carries
+ * the raw `Error.message`, which can be a database error string. It is for the
+ * caller's log, not for a response body. Same shape as `lead-promotion.ts`.
+ */
+
+import type { Id } from "@working-theory/ids";
+import { logger } from "@working-theory/observability";
+import { PROJECT_LISTING_STORED_STATUSES } from "@working-theory/validation";
+
+import { isModuleEnabled } from "../config/modules.js";
+import { prisma } from "../lib/prisma.js";
+
+/**
+ * `tenant-context.ts` is a multi-tenant SLICE file the OSS strip removes
+ * (#5182), and `listTenancy` is a VALUE — a runtime call, not an erasable type
+ * — so neither a static import nor a literal `await import("./tenant-context.js")`
+ * survives the strip: `tsc` resolves a string-literal specifier whether or not
+ * the branch containing it can ever run, and either form is TS2307 on the
+ * public tree.
+ *
+ * The remedy is the one `lead-promotion.ts`, `server.ts` and
+ * `routes/content/index.ts` already use: gate the call on
+ * `isModuleEnabled('multi-tenant')` and read the specifier from this constant
+ * so it is not a literal written at the call site. What defeats resolution is
+ * the INDIRECTION, not the type of the value.
+ *
+ * Restated here rather than shared with `lead-promotion.ts`: the mechanism is
+ * three lines and a constant, and extracting it would mean editing the Lead
+ * promotion path this file deliberately only mirrors.
+ *
+ * Semantics on a build without the module: there is no workspace concept at
+ * all, so a user has no workspaces, so no listing can match
+ * `siteId ∈ workspaceIds` — which is exactly the zero-workspace early return
+ * below. The no-op is correct rather than degraded.
+ */
+const TENANT_CONTEXT_SPECIFIER = "./tenant-context.js";
+
+/**
+ * The statuses a row must be in to be claimable: every stored status EXCEPT
+ * `draft`.
+ *
+ * Two reasons, and the second is a security one.
+ *
+ * A `draft` is addressed by its RESUME TOKEN, which is that draft's whole
+ * credential, and `resumeTokenHash` is cleared at submit — so the token and the
+ * owner link hand off to each other cleanly. Before submit the token is the
+ * access path; after it, the link is. A draft needs no link and gains nothing
+ * from one.
+ *
+ * And `POST /v1/project-listings` is ANONYMOUS with the concurrent-listing
+ * quota enforced at SUBMIT rather than at start, so anyone holding a site's
+ * public key — it ships in browser JavaScript by design — can create unbounded
+ * `draft` rows carrying any address they choose. If drafts were claimable, one
+ * such row would be enough either to hand a stranger's text to whoever verifies
+ * that address, or (under the ambiguity refusal below) to block that person
+ * from ever claiming their own listing. Excluding drafts raises the cost of
+ * that from one anonymous request to a COMPLETE application that passes submit
+ * validation, counts against the two-row quota for that address at that site,
+ * and sends an operator notification to the address itself.
+ *
+ * Derived from the exported vocabulary rather than restated, so a new stored
+ * status is a deliberate decision here rather than a silent inclusion.
+ */
+const CLAIMABLE_STATUSES: readonly string[] = PROJECT_LISTING_STORED_STATUSES.filter(
+  (status) => status !== "draft",
+);
+
+/** The one export this file needs from the multi-tenant slice. */
+interface TenantContextSlice {
+  listTenancy: (params: {
+    userId: Id<"user">;
+    sessionTenant: undefined;
+  }) => Promise<
+    | {
+        ok: true;
+        value: { organizations: Array<{ workspaces: Array<{ id: string }> }> };
+      }
+    | { ok: false; error: { message: string } }
+  >;
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type PromotedListing = {
+  listingId: string;
+  siteId: string;
+};
+
+export type PromoteListingsResult =
+  | { ok: true; count: number; promoted: PromotedListing[] }
+  | {
+      ok: false;
+      error: { kind: "user_not_found" | "internal_error"; message: string };
+    };
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Link every un-linked `ProjectListing` whose `founderEmail` is the verifying
+ * user's own verified address, within that user's own tenant workspaces.
+ *
+ * No-ops (`count: 0`) — never throws — when: the user's email is unverified,
+ * the user belongs to no workspace, no matching un-linked listing exists, or
+ * the match is ambiguous (more than one un-linked listing carries the address
+ * at one site).
+ *
+ * Idempotent, and proved so on both sides of the write: a listing already
+ * carrying `ownerUserId` is excluded from the candidate read AND from the
+ * update's own `where`, so a re-invocation links nothing and a concurrent run
+ * cannot transfer a row away from the user who already claimed it.
+ */
+export async function promoteListingsForVerifiedUser(params: {
+  userId: string;
+}): Promise<PromoteListingsResult> {
+  const { userId } = params;
+
+  try {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { id: true, email: true, emailVerified: true },
+    });
+
+    if (!user) {
+      return {
+        ok: false,
+        error: { kind: "user_not_found", message: "User not found" },
+      };
+    }
+
+    // Condition 1 — the verified-email gate. A service-level invariant, not a
+    // caller obligation: it cannot be bypassed by a wrong call-site.
+    if (!user.emailVerified) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    // Condition 3 — resolve the verifying user's OWN workspaces via the sole
+    // tenant-context assembler (never a raw membership or workspace model query
+    // in this file). Module-conditional per the note on
+    // TENANT_CONTEXT_SPECIFIER above: no multi-tenant module, no workspaces.
+    let workspaceIds: string[] = [];
+    if (isModuleEnabled("multi-tenant")) {
+      const specifier: string = TENANT_CONTEXT_SPECIFIER;
+      const { listTenancy } = (await import(specifier)) as TenantContextSlice;
+      const tenancy = await listTenancy({
+        userId: user.id as Id<"user">,
+        sessionTenant: undefined,
+      });
+      if (!tenancy.ok) {
+        return {
+          ok: false,
+          error: { kind: "internal_error", message: tenancy.error.message },
+        };
+      }
+
+      workspaceIds = tenancy.value.organizations.flatMap((org) =>
+        org.workspaces.map((workspace) => workspace.id as string),
+      );
+    }
+
+    if (workspaceIds.length === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    /**
+     * Conditions 2 + 3, both in the WHERE clause so neither is a post-filter.
+     *
+     * The email comparison is EXACT equality against the same normalization
+     * `startProjectListingDraft` applies when it writes the column
+     * (`normalizeFounderEmail` — trim + lower-case), so the two sides of the
+     * match are normalized the same way by construction.
+     *
+     * Deliberately NOT `{ equals, mode: "insensitive" }`, the form
+     * `waitlist-signups.ts` uses on `Lead.email`: Prisma compiles an
+     * insensitive `equals` to `founder_email ILIKE $1`, which makes `_` and
+     * `%` in the CALLER'S own verified address LIKE wildcards. A user whose
+     * real address is `a_c@example.com` then matches a different founder's
+     * `abc@example.com` in the same workspace — verified in this repo against
+     * a live Postgres, two rows in, two rows out. That is precisely the
+     * cross-founder capture this link exists to remove, so the stricter
+     * comparison wins. The cost is a listing whose stored `founderEmail`
+     * predates `normalizeFounderEmail` and carries upper case: it stays
+     * un-linked, which is the safe direction (a missing link is a no-op; a
+     * wrong one hands over a stranger's submission) and the same resting
+     * state every un-promoted row already sits in.
+     *
+     * `ownerUserId: null` is what makes this idempotent.
+     */
+    const candidates = await prisma.projectListing.findMany({
+      where: {
+        founderEmail: user.email.trim().toLowerCase(),
+        siteId: { in: workspaceIds },
+        ownerUserId: null,
+        // See CLAIMABLE_STATUSES: a draft is token-addressed, and an anonymous
+        // caller can create them without passing the quota.
+        status: { in: [...CLAIMABLE_STATUSES] },
+      },
+      select: { id: true, siteId: true },
+    });
+
+    if (candidates.length === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    /**
+     * AMBIGUITY REFUSAL — the case a verified email cannot resolve.
+     *
+     * Two strangers can both type the same address into the anonymous form, and
+     * when they do there are two un-linked rows carrying it and NOTHING that
+     * says which is whose. Linking both to whoever verifies the address hands
+     * one person the other's whole application — the exact disclosure this
+     * column exists to remove, arriving by the back door. `lead-promotion.ts`
+     * links every match and therefore has this shape; it is out of scope to
+     * change there, and it is not inherited here.
+     *
+     * So the rule is: within ONE site, a verified address claims a row only
+     * when it is the ONLY un-linked row carrying that address. Otherwise every
+     * row in that ambiguous group stays null. The grain is the site because
+     * that is where the collision happens and where the concurrent-listing
+     * limit is already counted (`countOtherNonTerminalListings`); a second site
+     * of the same user is judged on its own.
+     *
+     * The cost is a founder who legitimately submitted TWO applications at one
+     * site (`PROJECT_LISTING_CONCURRENT_LIMIT` is 2): neither is linked, and
+     * they reach those rows the way they do today. That is the deliberate
+     * trade. Nothing in the data distinguishes their second application from a
+     * stranger's first, so the honest answer is to claim neither — and an
+     * unclaimed row is the resting state this column already treats as
+     * legitimate, not a failure.
+     *
+     * `users.email` is UNIQUE, so there is never a SECOND verifier competing
+     * for the refused rows: refusing costs no other claimant anything.
+     */
+    const perSite = new Map<string, number>();
+    for (const listing of candidates) {
+      perSite.set(listing.siteId, (perSite.get(listing.siteId) ?? 0) + 1);
+    }
+    const attributable = candidates.filter(
+      (listing) => perSite.get(listing.siteId) === 1,
+    );
+
+    const ambiguousRows = candidates.length - attributable.length;
+    if (ambiguousRows > 0) {
+      // PII-safe: counts and the user id only — never the address, the
+      // founder's name, or a listing id that would identify whose row it is.
+      logger.warn(
+        {
+          kind: "ambiguous_listing_owner",
+          userId: user.id,
+          ambiguousRows,
+          attributableRows: attributable.length,
+        },
+        "[listing-promotion] more than one un-linked listing shares this address at one site; leaving those rows unlinked",
+      );
+    }
+
+    if (attributable.length === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    /**
+     * `ownerUserId: null` is repeated on the WRITE, not only on the read above.
+     * Without it the update is a blind write over whatever the row holds now,
+     * and two reconciliation runs that both saw the row un-linked would let the
+     * second one TRANSFER ownership away from the first — which contradicts the
+     * idempotency this service documents. With it the write is a
+     * compare-and-swap: the loser of the race matches 0 rows.
+     *
+     * `count` therefore reports rows this call actually claimed, not rows it
+     * intended to.
+     */
+    const written = await prisma.projectListing.updateMany({
+      where: {
+        id: { in: attributable.map((listing) => listing.id) },
+        ownerUserId: null,
+      },
+      data: { ownerUserId: user.id, ownerLinkedAt: new Date() },
+    });
+
+    if (written.count === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    return {
+      ok: true,
+      count: written.count,
+      promoted: attributable.map((listing) => ({
+        listingId: listing.id,
+        siteId: listing.siteId,
+      })),
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { kind: "internal_error", message } };
+  }
+}