create-ailk 0.2.0 → 0.3.0

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

@@ -1,342 +0,0 @@
-/**
- * @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 } };
-  }
-}