create-ailk 0.2.0 → 0.3.0

package/templates/database/migrations/20260914120000_listing_founder_identity/migration.sql

@@ -0,0 +1,123 @@
+-- The founder's structured identity and PROVEN email address on
+-- `project_listings` (#5407).
+--
+-- Step one of the application collected ONE `founder_name` line and an email.
+-- samhenry spec 316 D1 asks for first name, last name, email and phone, with
+-- the two name parts stored separately, and 316 D6b asks that an application
+-- whose emailed resume link was opened be marked verified so the operator can
+-- filter on it at review.
+--
+-- FIVE NULLABLE COLUMNS, NO BACKFILL, NO CHANGE TO ANY EXISTING ONE.
+--
+-- `founder_first_name` / `founder_last_name` sit BESIDE `founder_name`, not
+-- instead of it — the #5279 precedent that put six address parts beside the
+-- single-line `address`. `founder_name` stays NOT NULL and stays the DISPLAY
+-- string every existing reader already reads (the submit-time slug fallback,
+-- the approve/reject email's greeting, the Slack review card's Founder row,
+-- the build issue, the `routeLead` identity); where the parts are written the
+-- server COMPOSES it from them, and where they are not it is the line the
+-- founder typed, verbatim.
+--
+-- Composition runs ONE WAY ONLY, and that is why nothing here backfills.
+-- "First" + "Last" composes into a display line deterministically; a display
+-- line does not decompose into parts. Splitting on the last space mangles
+-- "van der Berg", "Maria del Carmen" and every mononym, and a wrong split is
+-- silent — it would put an invented surname on the row the approve email
+-- greets and the operator reviews, with nothing to mark it as invented. A
+-- null part is honest; a guessed one is not. Every existing row therefore
+-- keeps `founder_name` byte-for-byte and keeps both parts NULL for the life
+-- of the row.
+--
+-- `founder_phone` is the contact detail spec 316 D1 adds. Nullable at rest
+-- for the #5036 D1 reason — every field the submit payload requires must be
+-- storable half-filled — and nullable permanently besides: a row written
+-- before #5407 has none, and a site may declare the question optional through
+-- its own listing config. It NEVER rides the public read; the public row
+-- shape omits it beside `founder_email`.
+--
+-- `email_verify_nonce_hash` and `email_verified_at` are the verification pair,
+-- and the first is what makes the second mean what it says.
+--
+-- The obvious design is to stamp verification when the emailed resume link is
+-- opened, keyed on the resume token that link carries. That design does not
+-- work, and the reason is worth stating here because the column name does not
+-- carry it: `start` returns the resume token to WHOEVER POSTED THE FORM, in
+-- its own 201 body. The emailed link is a second copy of a credential the
+-- applicant already holds — so two HTTP calls (open a draft under a
+-- stranger's address, take the token out of the response, present it back)
+-- would forge the stamp with no mailbox involved. Caught by this PR's
+-- security review before it shipped.
+--
+-- So verification requires a SECOND credential the applicant never receives
+-- any other way. `email_verify_nonce_hash` holds the sha-256 digest of a
+-- 256-bit nonce minted at `start`, handed to nothing except the resume-email
+-- builder (apps/api/src/services/project-listing-resume-email.ts), and
+-- present in no response body and no log line. It reaches exactly one place:
+-- the `?verify=` parameter of the link inside the email. Holding it means
+-- having read mail sent to `founder_email`, which is what the stamp claims.
+--
+-- `email_verified_at` is therefore genuine evidence of address control, and
+-- is still WRITE-ONCE: the verify call sets it only where it is still NULL,
+-- by compare-and-swap, so a founder who opens the link five times is stamped
+-- with the first opening and two concurrent openings produce one stamp
+-- between them.
+--
+-- WHAT IT STILL DOES NOT SAY is who the founder is. `owner_user_id`
+-- (20260912120000_listing_owner_link) is the identity claim and needs a
+-- signed-in user whose own address the auth system verified. A row can carry
+-- either, both, or neither.
+--
+-- Neither is a backfill target. Stamping an existing row would assert exactly
+-- the event nobody recorded. NULL means "not verified", never "verification
+-- failed" — and it is also what a site that has not switched the resume email
+-- on will read forever, because the nonce is minted there and simply never
+-- delivered. That is the correct outcome, not a gap.
+--
+-- `email_verify_nonce_hash` is UNIQUE, mirroring `resume_token_hash`: two
+-- rows can never share a nonce, and the digest lookup is indexed. It is
+-- cleared at `submit` beside the resume-token digest, so a credential that
+-- leaks after the draft stops being a draft is inert twice over. It has NO
+-- EXPIRY otherwise, by design and for the reason the service records: the
+-- same message carries the resume token, so a TTL on the nonce alone would
+-- bound nothing.
+--
+-- OPERATIONAL NOTE on the index. `CREATE UNIQUE INDEX` below is not
+-- `CONCURRENTLY`, so it takes a SHARE lock and blocks writes to
+-- `project_listings` while it builds. Every existing row is NULL there and
+-- Postgres treats NULLs as distinct in a unique index (no NULLS NOT
+-- DISTINCT), so it cannot fail on existing data and builds fast — and the
+-- same property is why `submit` setting many rows back to NULL never
+-- collides. Stated so whoever runs this against a large table knows it is
+-- write-blocking DDL; it matches the `resume_token_hash` precedent.
+--
+-- Distinct from `owner_user_id` (20260912120000_listing_owner_link), which
+-- needs a SIGNED-IN user whose own address the auth system verified. This
+-- column needs no account at all: it records that a capability sent to
+-- `founder_email` came back. A row can carry either, both, or neither.
+--
+-- NO INDEX on the other four. The verify write is keyed by the row's primary
+-- key plus two digests, both already UNIQUE, and the operator filters
+-- verified applications inside a site's already-indexed page of listings
+-- (`project_listings_site_id_status_idx`) rather than by scanning on
+-- `email_verified_at`.
+--
+-- Forward-additive only: all five columns are nullable with no default, so
+-- every existing read and write is unaffected.
+--
+-- Rollback:
+--   DROP INDEX "project_listings_email_verify_nonce_hash_key";
+--   ALTER TABLE "project_listings" DROP COLUMN "email_verified_at";
+--   ALTER TABLE "project_listings" DROP COLUMN "email_verify_nonce_hash";
+--   ALTER TABLE "project_listings" DROP COLUMN "founder_phone";
+--   ALTER TABLE "project_listings" DROP COLUMN "founder_last_name";
+--   ALTER TABLE "project_listings" DROP COLUMN "founder_first_name";
+
+-- AlterTable
+ALTER TABLE "project_listings" ADD COLUMN     "founder_first_name" TEXT,
+ADD COLUMN     "founder_last_name" TEXT,
+ADD COLUMN     "founder_phone" TEXT,
+ADD COLUMN     "email_verify_nonce_hash" TEXT,
+ADD COLUMN     "email_verified_at" TIMESTAMP(3);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "project_listings_email_verify_nonce_hash_key" ON "project_listings"("email_verify_nonce_hash");

package/templates/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@working-theory/database",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/templates/package.json

@@ -60,7 +60,7 @@
     "yaml": "^2.9.0",
     "zod": "^4.2.1",
     "zod-to-ts": "^2.1.0",
-    "@working-theory/cli": "^0.20.0"
+    "@working-theory/cli": "^0.22.0"
   },
   "lint-staged": {
     "*.{ts,tsx}": [