promote: IAM registration and replay hardening

docs/operations/coderabbit-pr-37-disposition.md

@@ -1,6 +1,6 @@
 # CodeRabbit PR #37 disposition
 
-Review run: `d034f311-c043-4139-8372-ed69b774a83f`  
+Review run: `d034f311-c043-4139-8372-ed69b774a83f`
 Review policy: one automatic review run for this promotion PR; no rerun.
 
 After the fixes were pushed, the CodeRabbit app automatically queued a

docs/operations/iam-010-invitation-token-2026-08-03.md

@@ -14,6 +14,9 @@ complete.
 - `PrismaIamInvitationRepositoryAdapter` maps persisted rows through domain validation, enforces
   tenant scope visibility, rejects sibling-token reads, prevents multiple active invitations per
   membership, and uses compare-and-set revisions for redemption and membership activation.
+- The versioned invitation controller and IAM module composition now expose the acceptance flow
+  through the same replaceable repository and delivery ports; the HTTP boundary never returns the
+  raw token.
 - The Prisma foundation test proves the schema diff and migration inventory include the new table.
 
 ## Verification
@@ -25,7 +28,6 @@ complete.
 
 ## Explicitly not complete
 
-The invitation HTTP/controller and production composition wiring, transactional AUD append,
-registration for unknown recipients, resend/revocation administration, email-provider adapter,
-and production PostgreSQL/backup/security evidence remain future work. IAM-010 therefore remains
-`partial` and `not-verified` in the requirement manifest.
+Transactional AUD append, registration for unknown recipients, resend/revocation administration,
+an SMTP/SES delivery adapter, and production PostgreSQL/backup/security evidence remain future
+work. IAM-010 therefore remains `partial` and `not-verified` in the requirement manifest.

docs/operations/iam-registration-2026-08-03.md

@@ -9,7 +9,8 @@ It does not claim that IAM-001 or the IAM plan is complete.
 - Hash the password through the existing Argon2id password port; raw passwords never enter persistence.
 - Create the user, credential, personal organization, workspace, internal project, and owner membership in one transaction.
 - Keep duplicate-email responses generic and map persistence races to a safe rejection.
-- Return only hierarchy identifiers and locale from `POST /v1/auth/register`; the endpoint never returns bearer material or automatically creates a session.
+- Return a generic `202 Accepted` body (`{"accepted":true}`) from `POST /v1/auth/register`; the endpoint never returns hierarchy identifiers, bearer material, or an account-existence signal and never automatically creates a session.
+- Apply bounded, domain-separated admission before Argon2id hashing: the control plane hashes the normalized client IP and normalized email into separate rate-limit namespaces, and the durable Redis adapter fails closed on counter errors.
 - Select the Prisma registration adapter only when durable registration storage and the password boundary are configured; otherwise the endpoint fails closed.
 
 ## Evidence
@@ -23,4 +24,4 @@ It does not claim that IAM-001 or the IAM plan is complete.
 
 ## Verification
 
-The scoped API TypeScript build, registration tests, i18n tests, OpenAPI generation/check, and Redocly validation passed on 2026-08-03. The requirement remains `partial` and `not-verified` until the complete IAM release gates, audit integration, recovery, MFA, and restoration evidence are delivered.
+The scoped API TypeScript build, registration tests, i18n tests, OpenAPI generation/check, and Redocly validation passed on 2026-08-04. The rollback test stages the row in the transaction before injecting a persistence failure, proving no partial hierarchy remains. Admission tests prove IP/email throttling occurs before password hashing and persistence. The requirement remains `partial` and `not-verified` until the complete IAM release gates, audit integration, recovery, MFA, and restoration evidence are delivered.

docs/operations/secret-rotation.md

@@ -5,6 +5,13 @@ job envelopes, or client storage. Rotation is performed by an authorized
 operator through the provider adapter and is audited without recording the
 plaintext value.
 
+Service-account create-replay envelopes require a stable, managed 32-byte
+envelope key in every durable environment. The process-local random fallback
+is limited to tests and private alpha instances with no durable service-account
+repository; it must not be used by replicas or after a restart. Rotate the
+managed key through an overlap plan and invalidate old replay envelopes before
+retiring the previous key.
+
 ## General procedure
 
 1. Identify the secret reference, owning organization/workspace, provider,

packages/domain/src/entitlements/v1.ts

@@ -317,7 +317,12 @@ export function createEntitlementLeaseV1(
     expiresAt,
   };
   const payload = canonicalLease(unsigned);
-  const signature = text(signer.sign(payload), 2048);
+  let signature: string | undefined;
+  try {
+    signature = text(signer.sign(payload), 2048);
+  } catch {
+    return rejected('LEASE_INVALID');
+  }
   if (!signature) return rejected('LEASE_INVALID');
   return Object.freeze({
     accepted: true,

packages/domain/src/invitation/v1.ts

@@ -136,7 +136,8 @@ export function consumeInvitationTokenV1(
 ): InvitationTokenResultV1<InvitationTokenV1> {
   const timestampValue = timestamp(at);
   if (!timestampValue) return rejected('INVALID_TIMESTAMP');
-  if (token.status !== 'ACTIVE') return rejected('ALREADY_CONSUMED');
+  if (token.status === 'REDEEMED') return rejected('ALREADY_CONSUMED');
+  if (token.status !== 'ACTIVE') return rejected('INVALID_STATE');
   const nowMs = Date.parse(timestampValue);
   const issuedMs = Date.parse(token.issuedAt);
   const expiresMs = Date.parse(token.expiresAt);
@@ -151,3 +152,21 @@ export function consumeInvitationTokenV1(
     }),
   );
 }
+
+/** Revoke a token after a delivery acknowledgement failure; no bearer is reusable. */
+export function revokeInvitationTokenV1(
+  token: InvitationTokenV1,
+  at: unknown,
+): InvitationTokenResultV1<InvitationTokenV1> {
+  const timestampValue = timestamp(at);
+  if (!timestampValue) return rejected('INVALID_TIMESTAMP');
+  if (token.status !== 'ACTIVE') return rejected('INVALID_STATE');
+  if (Date.parse(timestampValue) < Date.parse(token.issuedAt)) return rejected('INVALID_TIMESTAMP');
+  return accepted(
+    Object.freeze({
+      ...token,
+      status: 'REVOKED' as const,
+      revision: token.revision + 1,
+    }),
+  );
+}

packages/domain/test/entitlement-lease-issuance-v1.test.mjs

@@ -104,6 +104,25 @@ void test('[BUA-017, BUA-018] suspended snapshots and overlong leases fail close
   );
 });
 
+void test('[BUA-018] a signing-provider exception fails closed as an invalid lease', () => {
+  assert.deepEqual(
+    createEntitlementLeaseV1(
+      snapshot(),
+      {
+        leaseId: '00000000-0000-4000-8000-000000000759',
+        issuedAt: '2026-01-01T00:00:00.000Z',
+        expiresAt: '2026-01-01T01:00:00.000Z',
+      },
+      {
+        sign: () => {
+          throw new Error('provider unavailable');
+        },
+      },
+    ),
+    { accepted: false, code: 'LEASE_INVALID' },
+  );
+});
+
 void test('[BUA-018] acceptance rejects payloads that do not canonically bind lease fields', () => {
   const lease = createEntitlementLeaseV1(
     snapshot(),

packages/domain/test/invitation-v1.test.mjs

@@ -90,3 +90,14 @@ void test('[IAM-010] consuming after expiry or before issue fails closed', () =>
     { accepted: false, code: 'INVALID_TIMESTAMP' },
   );
 });
+
+void test('[IAM-010] consuming a revoked token returns an invalid-state result', () => {
+  const created = createInvitationTokenV1(input());
+  assert.equal(created.accepted, true);
+  if (!created.accepted) return;
+  const revoked = { ...created.value, status: 'REVOKED' };
+  assert.deepEqual(consumeInvitationTokenV1(revoked, issuedAt), {
+    accepted: false,
+    code: 'INVALID_STATE',
+  });
+});

services/api/openapi/v1.json

@@ -3083,7 +3083,7 @@
           }
         },
         "responses": {
-          "201": {
+          "202": {
             "description": "",
             "content": {
               "application/json": {
@@ -9799,20 +9799,13 @@
             "name": "snapshotRevision",
             "required": true,
             "in": "query",
-            "schema": { "minimum": 1, "type": "number" }
+            "schema": { "minimum": 1, "maximum": 9007199254740991, "type": "integer" }
           },
           {
             "name": "securityEpoch",
             "required": true,
             "in": "query",
-            "schema": { "minimum": 1, "type": "number" }
-          },
-          {
-            "name": "now",
-            "required": false,
-            "in": "query",
-            "description": "Verification time; server clock is used when omitted",
-            "schema": { "format": "date-time", "type": "string" }
+            "schema": { "minimum": 1, "maximum": 9007199254740991, "type": "integer" }
           },
           {
             "name": "X-Correlation-Id",
@@ -10164,7 +10157,13 @@
           "mfaRequired": { "type": "boolean" },
           "mfaReenrollmentRequired": { "type": "boolean" }
         },
-        "required": ["userId", "organizationId", "authorizationEpoch", "mfaRequired"]
+        "required": [
+          "userId",
+          "organizationId",
+          "authorizationEpoch",
+          "mfaRequired",
+          "mfaReenrollmentRequired"
+        ]
       },
       "SignInDto": {
         "type": "object",
@@ -10197,7 +10196,8 @@
           "accessToken",
           "accessExpiresAt",
           "securityEpoch",
-          "mfaRequired"
+          "mfaRequired",
+          "mfaReenrollmentRequired"
         ]
       },
       "SessionRefreshDto": {
@@ -10411,7 +10411,12 @@
       "RegistrationDto": {
         "type": "object",
         "properties": {
-          "email": { "type": "string", "example": "ngu***@example.com", "maxLength": 254 },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "example": "nguyen@example.com",
+            "maxLength": 254
+          },
           "displayName": { "type": "string", "minLength": 1, "maxLength": 200 },
           "password": { "type": "string", "minLength": 12, "maxLength": 128, "writeOnly": true },
           "locale": { "type": "string", "enum": ["vi-VN", "en"], "default": "vi-VN" }
@@ -10420,22 +10425,8 @@
       },
       "RegistrationResponseDto": {
         "type": "object",
-        "properties": {
-          "userId": { "type": "string", "format": "uuid" },
-          "organizationId": { "type": "string", "format": "uuid" },
-          "workspaceId": { "type": "string", "format": "uuid" },
-          "projectId": { "type": "string", "format": "uuid" },
-          "membershipId": { "type": "string", "format": "uuid" },
-          "locale": { "type": "string", "enum": ["vi-VN", "en"] }
-        },
-        "required": [
-          "userId",
-          "organizationId",
-          "workspaceId",
-          "projectId",
-          "membershipId",
-          "locale"
-        ]
+        "properties": { "accepted": { "type": "boolean", "enum": [true], "example": true } },
+        "required": ["accepted"]
       },
       "RecoveryRequestDto": {
         "type": "object",
@@ -10614,7 +10605,7 @@
               { "type": "null" }
             ]
           },
-          "expectedRevision": { "type": "number", "minimum": 1 }
+          "expectedRevision": { "type": "integer", "minimum": 1 }
         }
       },
       "CreateEvidenceGrantDto": {
@@ -11563,8 +11554,8 @@
             "description": "Server-generated when omitted"
           },
           "signerKeyId": { "type": "string", "minLength": 1, "maxLength": 200 },
-          "firstSequence": { "type": "number", "minimum": 1 },
-          "lastSequence": { "type": "number", "minimum": 1 },
+          "firstSequence": { "type": "integer", "minimum": 1 },
+          "lastSequence": { "type": "integer", "minimum": 1 },
           "rootDigest": { "type": "string", "minLength": 1, "maxLength": 512 }
         },
         "required": ["signerKeyId", "firstSequence", "lastSequence", "rootDigest"]

services/api/prisma/migrations/20260804000000_iam_invitation_active_membership_unique/migration.sql

@@ -0,0 +1,4 @@
+-- IAM-010: enforce one active invitation per membership at the database boundary.
+CREATE UNIQUE INDEX "invitation_tokens_active_membership_key"
+ON "iam"."invitation_tokens"("membership_id")
+WHERE "status" = 'ACTIVE';

services/api/prisma/migrations/20260804010000_iam_service_account_create_idempotency/migration.sql

@@ -0,0 +1,34 @@
+-- IAM-013/INT-004: bind service-account create retries to one actor, target scope, and request hash.
+-- The replayable one-time secret is stored only as an application-encrypted envelope.
+ALTER TABLE "iam"."service_accounts"
+    ADD COLUMN "created_by_actor_id" UUID,
+    ADD COLUMN "create_idempotency_key" VARCHAR(200),
+    ADD COLUMN "create_request_hash" CHAR(64),
+    ADD COLUMN "create_secret_envelope" TEXT;
+
+CREATE UNIQUE INDEX "service_accounts_create_idempotency_key"
+ON "iam"."service_accounts"(
+    "organization_id",
+    "workspace_id",
+    "created_by_actor_id",
+    "create_idempotency_key"
+);
+
+-- PostgreSQL treats NULL values as distinct in a composite unique index. These partial
+-- constraints close the organization-scope and workspace-scope retry races explicitly.
+CREATE UNIQUE INDEX "service_accounts_create_idempotency_org_key"
+ON "iam"."service_accounts"("organization_id", "created_by_actor_id", "create_idempotency_key")
+WHERE "workspace_id" IS NULL
+  AND "created_by_actor_id" IS NOT NULL
+  AND "create_idempotency_key" IS NOT NULL;
+
+CREATE UNIQUE INDEX "service_accounts_create_idempotency_workspace_key"
+ON "iam"."service_accounts"(
+    "organization_id",
+    "workspace_id",
+    "created_by_actor_id",
+    "create_idempotency_key"
+)
+WHERE "workspace_id" IS NOT NULL
+  AND "created_by_actor_id" IS NOT NULL
+  AND "create_idempotency_key" IS NOT NULL;

services/api/prisma/migrations/20260804020000_iam_service_account_replay_bounds/migration.sql

@@ -0,0 +1,8 @@
+-- IAM-013/INT-004: bound replayable create envelopes and preserve create-time state.
+ALTER TABLE "iam"."service_accounts"
+    ADD COLUMN "create_idempotency_expires_at" TIMESTAMPTZ(6),
+    ADD COLUMN "create_account_snapshot" TEXT;
+
+-- The composite unique index already covers non-null workspace identities. Keep the
+-- organization partial index for NULL workspace rows, but remove the redundant copy.
+DROP INDEX IF EXISTS "service_accounts_create_idempotency_workspace_key";

services/api/prisma/migrations/20260804030000_iam_recovery_compensation_failures/migration.sql

@@ -0,0 +1,7 @@
+-- IAM-015: a delivery failure whose compensating revoke cannot be persisted is
+-- durably blocked from token completion until an operator resolves the marker.
+CREATE TABLE "iam"."recovery_compensation_failures" (
+    "token_digest" CHAR(64) NOT NULL,
+    "recorded_at" TIMESTAMPTZ(6) NOT NULL,
+    CONSTRAINT "recovery_compensation_failures_pkey" PRIMARY KEY ("token_digest")
+);

services/api/prisma/migrations/20260804040000_iam_invitation_delivery_failures/migration.sql

@@ -0,0 +1,6 @@
+-- IAM-010: retain a durable block when an invitation delivery acknowledgement fails.
+CREATE TABLE "iam"."invitation_delivery_failures" (
+    "token_digest" CHAR(64) NOT NULL,
+    "recorded_at" TIMESTAMPTZ(6) NOT NULL,
+    CONSTRAINT "invitation_delivery_failures_pkey" PRIMARY KEY ("token_digest")
+);

services/api/prisma/schema/iam.prisma

@@ -118,6 +118,15 @@ model InvitationTokenRecord {
   @@schema("iam")
 }
 
+/// IAM-010: delivery failures block bearer acceptance across restarts.
+model InvitationDeliveryFailureRecord {
+  tokenDigest String   @id @map("token_digest") @db.Char(64)
+  recordedAt  DateTime @map("recorded_at") @db.Timestamptz(6)
+
+  @@map("invitation_delivery_failures")
+  @@schema("iam")
+}
+
 /// IAM-015: recovery bearers are short-lived, email-bound, and hashed at rest.
 model RecoveryChallengeRecord {
   id           String    @id @db.Uuid
@@ -139,6 +148,15 @@ model RecoveryChallengeRecord {
   @@schema("iam")
 }
 
+/// IAM-015: delivery-compensation failures remain blocked across restarts until reviewed.
+model RecoveryCompensationFailureRecord {
+  tokenDigest String   @id @map("token_digest") @db.Char(64)
+  recordedAt  DateTime @map("recorded_at") @db.Timestamptz(6)
+
+  @@map("recovery_compensation_failures")
+  @@schema("iam")
+}
+
 model SessionRecord {
   id                 String   @id @db.Uuid
   userId             String   @map("user_id") @db.Uuid
@@ -300,9 +318,16 @@ model ServiceAccountRecord {
   createdAt      DateTime  @default(now()) @map("created_at") @db.Timestamptz(6)
   revokedAt      DateTime? @map("revoked_at") @db.Timestamptz(6)
   revision       Int       @default(1)
+  createdByActorId String?  @map("created_by_actor_id") @db.Uuid
+  createIdempotencyKey String? @map("create_idempotency_key") @db.VarChar(200)
+  createRequestHash String? @map("create_request_hash") @db.Char(64)
+  createSecretEnvelope String? @map("create_secret_envelope") @db.Text
+  createIdempotencyExpiresAt DateTime? @map("create_idempotency_expires_at") @db.Timestamptz(6)
+  createAccountSnapshot String? @map("create_account_snapshot") @db.Text
 
   @@index([organizationId, workspaceId, status], map: "service_accounts_scope_status_idx")
   @@index([secretExpiresAt, status], map: "service_accounts_expiry_status_idx")
+  @@unique([organizationId, workspaceId, createdByActorId, createIdempotencyKey], map: "service_accounts_create_idempotency_key")
   @@map("service_accounts")
   @@schema("iam")
 }