refactor(signing-2fa): simplify server-side and UI code for external 2FA

- Extract throwVerificationError helper in verify-signing-two-factor-token.ts
- Extract throwIssuanceDenied helper in issue-signing-two-factor-token.ts
- Eliminate duplicated attemptsRemaining state in UI component
- Use imported SIGNING_2FA_VERIFY_REASON_CODES constants
- Add statusQuery.refetch() after failed verify for single source of truth
- Fix TypeScript control flow with explicit returns after throws

packages/prisma/migrations/20260210095133_add_signing_two_factor_tokens/migration.sql

@@ -0,0 +1,60 @@
+-- CreateEnum
+CREATE TYPE "SigningTwoFactorTokenStatus" AS ENUM ('ACTIVE', 'CONSUMED', 'REVOKED', 'EXPIRED');
+
+-- CreateTable
+CREATE TABLE "SigningTwoFactorToken" (
+    "id" TEXT NOT NULL,
+    "recipientId" INTEGER NOT NULL,
+    "envelopeId" TEXT NOT NULL,
+    "tokenHash" TEXT NOT NULL,
+    "tokenSalt" TEXT NOT NULL,
+    "status" "SigningTwoFactorTokenStatus" NOT NULL DEFAULT 'ACTIVE',
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "consumedAt" TIMESTAMP(3),
+    "revokedAt" TIMESTAMP(3),
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "attemptLimit" INTEGER NOT NULL DEFAULT 5,
+    "issuedByApiTokenId" INTEGER,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "SigningTwoFactorToken_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "SigningSessionTwoFactorProof" (
+    "id" TEXT NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "recipientId" INTEGER NOT NULL,
+    "envelopeId" TEXT NOT NULL,
+    "verifiedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "SigningSessionTwoFactorProof_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "SigningTwoFactorToken_recipientId_envelopeId_status_idx" ON "SigningTwoFactorToken"("recipientId", "envelopeId", "status");
+
+-- CreateIndex
+CREATE INDEX "SigningTwoFactorToken_envelopeId_idx" ON "SigningTwoFactorToken"("envelopeId");
+
+-- CreateIndex
+CREATE INDEX "SigningSessionTwoFactorProof_recipientId_envelopeId_idx" ON "SigningSessionTwoFactorProof"("recipientId", "envelopeId");
+
+-- CreateIndex
+CREATE INDEX "SigningSessionTwoFactorProof_expiresAt_idx" ON "SigningSessionTwoFactorProof"("expiresAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SigningSessionTwoFactorProof_sessionId_recipientId_envelope_key" ON "SigningSessionTwoFactorProof"("sessionId", "recipientId", "envelopeId");
+
+-- AddForeignKey
+ALTER TABLE "SigningTwoFactorToken" ADD CONSTRAINT "SigningTwoFactorToken_recipientId_fkey" FOREIGN KEY ("recipientId") REFERENCES "Recipient"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SigningTwoFactorToken" ADD CONSTRAINT "SigningTwoFactorToken_envelopeId_fkey" FOREIGN KEY ("envelopeId") REFERENCES "Envelope"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SigningSessionTwoFactorProof" ADD CONSTRAINT "SigningSessionTwoFactorProof_recipientId_fkey" FOREIGN KEY ("recipientId") REFERENCES "Recipient"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SigningSessionTwoFactorProof" ADD CONSTRAINT "SigningSessionTwoFactorProof_envelopeId_fkey" FOREIGN KEY ("envelopeId") REFERENCES "Envelope"("id") ON DELETE CASCADE ON UPDATE CASCADE;

packages/prisma/schema.prisma

@@ -430,6 +430,9 @@ model Envelope {
 
   envelopeAttachments EnvelopeAttachment[]
 
+  signingTwoFactorTokens       SigningTwoFactorToken[]
+  signingSessionTwoFactorProofs SigningSessionTwoFactorProof[]
+
   @@index([type])
   @@index([status])
   @@index([userId])
@@ -588,6 +591,9 @@ model Recipient {
   fields            Field[]
   signatures        Signature[]
 
+  signingTwoFactorTokens       SigningTwoFactorToken[]
+  signingSessionTwoFactorProofs SigningSessionTwoFactorProof[]
+
   @@index([token])
   @@index([email])
   @@index([envelopeId])
@@ -1076,3 +1082,55 @@ model Counter {
   id    String @id
   value Int
 }
+
+enum SigningTwoFactorTokenStatus {
+  ACTIVE
+  CONSUMED
+  REVOKED
+  EXPIRED
+}
+
+model SigningTwoFactorToken {
+  id String @id @default(cuid())
+
+  recipientId Int
+  envelopeId  String
+
+  tokenHash String
+  tokenSalt String
+
+  status       SigningTwoFactorTokenStatus @default(ACTIVE)
+  expiresAt    DateTime
+  consumedAt   DateTime?
+  revokedAt    DateTime?
+  attempts     Int                         @default(0)
+  attemptLimit Int                         @default(5)
+
+  issuedByApiTokenId Int?
+
+  createdAt DateTime @default(now())
+
+  recipient Recipient @relation(fields: [recipientId], references: [id], onDelete: Cascade)
+  envelope  Envelope  @relation(fields: [envelopeId], references: [id], onDelete: Cascade)
+
+  @@index([recipientId, envelopeId, status])
+  @@index([envelopeId])
+}
+
+model SigningSessionTwoFactorProof {
+  id String @id @default(cuid())
+
+  sessionId   String
+  recipientId Int
+  envelopeId  String
+
+  verifiedAt DateTime @default(now())
+  expiresAt  DateTime
+
+  recipient Recipient @relation(fields: [recipientId], references: [id], onDelete: Cascade)
+  envelope  Envelope  @relation(fields: [envelopeId], references: [id], onDelete: Cascade)
+
+  @@unique([sessionId, recipientId, envelopeId])
+  @@index([recipientId, envelopeId])
+  @@index([expiresAt])
+}