@open-mercato/onboarding 0.6.6-develop.5412.1.e2a52b14f0 → 0.6.6-develop.5431.1.384a97c7a2

package/dist/modules/onboarding/lib/verify-base-url.js

@@ -0,0 +1,86 @@
+import {
+  AppOriginConfigurationError,
+  AppOriginRejectedError,
+  getSecurityEmailBaseUrl,
+  resolveRequestOrigin
+} from "@open-mercato/shared/lib/url";
+function normalizeOrigin(raw) {
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return null;
+  }
+}
+function originPort(url) {
+  if (url.port) return url.port;
+  if (url.protocol === "https:") return "443";
+  if (url.protocol === "http:") return "80";
+  return "";
+}
+function isLoopbackHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+function originsMatchForRedirect(configuredOrigin, requestOrigin) {
+  if (configuredOrigin === requestOrigin) return true;
+  try {
+    const configured = new URL(configuredOrigin);
+    const request = new URL(requestOrigin);
+    return configured.protocol === request.protocol && isLoopbackHostname(configured.hostname) && isLoopbackHostname(request.hostname) && originPort(configured) === originPort(request);
+  } catch {
+    return false;
+  }
+}
+function resolveVerifyRedirectBaseUrl(req, env = process.env) {
+  try {
+    const baseUrl = getSecurityEmailBaseUrl(req, env);
+    const configuredOrigin = normalizeOrigin(baseUrl);
+    const requestOrigin = normalizeOrigin(resolveRequestOrigin(req)) ?? normalizeOrigin(req.url);
+    if (configuredOrigin && requestOrigin && !originsMatchForRedirect(configuredOrigin, requestOrigin)) {
+      console.error("[onboarding.verify] APP_URL does not match verification request origin", {
+        requestUrl: req.url,
+        configuredOrigin,
+        requestOrigin
+      });
+      return {
+        ok: false,
+        status: "redirect_misconfigured",
+        message: "Onboarding verification redirect is misconfigured.",
+        redirectOrigin: requestOrigin,
+        httpStatus: 400
+      };
+    }
+    return { ok: true, baseUrl };
+  } catch (error) {
+    if (error instanceof AppOriginRejectedError) {
+      console.error("[onboarding.verify] rejected request origin for redirect base", {
+        requestUrl: req.url,
+        reason: error.message
+      });
+      return {
+        ok: false,
+        status: "origin_not_allowed",
+        message: "Onboarding verification request origin is not allowed.",
+        redirectOrigin: null,
+        httpStatus: 400
+      };
+    }
+    if (error instanceof AppOriginConfigurationError) {
+      console.error("[onboarding.verify] APP_URL is required for onboarding verification redirects", {
+        requestUrl: req.url,
+        reason: error.message
+      });
+      return {
+        ok: false,
+        status: "url_not_configured",
+        message: "Onboarding verification redirect is not configured.",
+        redirectOrigin: null,
+        httpStatus: 500
+      };
+    }
+    throw error;
+  }
+}
+export {
+  resolveVerifyRedirectBaseUrl
+};
+//# sourceMappingURL=verify-base-url.js.map

package/dist/modules/onboarding/lib/verify-base-url.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/onboarding/lib/verify-base-url.ts"],
+  "sourcesContent": ["import {\n  AppOriginConfigurationError,\n  AppOriginRejectedError,\n  getSecurityEmailBaseUrl,\n  resolveRequestOrigin,\n} from '@open-mercato/shared/lib/url'\n\ntype EnvLike = Record<string, string | undefined>\n\nexport type VerifyRedirectBaseUrlResult =\n  | { ok: true; baseUrl: string }\n  | {\n    ok: false\n    status: 'origin_not_allowed' | 'redirect_misconfigured' | 'url_not_configured'\n    message: string\n    redirectOrigin: string | null\n    httpStatus: number\n  }\n\nfunction normalizeOrigin(raw: string): string | null {\n  try {\n    return new URL(raw).origin\n  } catch {\n    return null\n  }\n}\n\nfunction originPort(url: URL): string {\n  if (url.port) return url.port\n  if (url.protocol === 'https:') return '443'\n  if (url.protocol === 'http:') return '80'\n  return ''\n}\n\nfunction isLoopbackHostname(hostname: string): boolean {\n  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'\n}\n\nfunction originsMatchForRedirect(configuredOrigin: string, requestOrigin: string): boolean {\n  if (configuredOrigin === requestOrigin) return true\n  try {\n    const configured = new URL(configuredOrigin)\n    const request = new URL(requestOrigin)\n    return (\n      configured.protocol === request.protocol &&\n      isLoopbackHostname(configured.hostname) &&\n      isLoopbackHostname(request.hostname) &&\n      originPort(configured) === originPort(request)\n    )\n  } catch {\n    return false\n  }\n}\n\nexport function resolveVerifyRedirectBaseUrl(\n  req: Request,\n  env: EnvLike = process.env,\n): VerifyRedirectBaseUrlResult {\n  try {\n    const baseUrl = getSecurityEmailBaseUrl(req, env)\n    const configuredOrigin = normalizeOrigin(baseUrl)\n    const requestOrigin = normalizeOrigin(resolveRequestOrigin(req)) ?? normalizeOrigin(req.url)\n    if (configuredOrigin && requestOrigin && !originsMatchForRedirect(configuredOrigin, requestOrigin)) {\n      console.error('[onboarding.verify] APP_URL does not match verification request origin', {\n        requestUrl: req.url,\n        configuredOrigin,\n        requestOrigin,\n      })\n      return {\n        ok: false,\n        status: 'redirect_misconfigured',\n        message: 'Onboarding verification redirect is misconfigured.',\n        redirectOrigin: requestOrigin,\n        httpStatus: 400,\n      }\n    }\n    return { ok: true, baseUrl }\n  } catch (error) {\n    if (error instanceof AppOriginRejectedError) {\n      console.error('[onboarding.verify] rejected request origin for redirect base', {\n        requestUrl: req.url,\n        reason: error.message,\n      })\n      return {\n        ok: false,\n        status: 'origin_not_allowed',\n        message: 'Onboarding verification request origin is not allowed.',\n        redirectOrigin: null,\n        httpStatus: 400,\n      }\n    }\n    if (error instanceof AppOriginConfigurationError) {\n      console.error('[onboarding.verify] APP_URL is required for onboarding verification redirects', {\n        requestUrl: req.url,\n        reason: error.message,\n      })\n      return {\n        ok: false,\n        status: 'url_not_configured',\n        message: 'Onboarding verification redirect is not configured.',\n        redirectOrigin: null,\n        httpStatus: 500,\n      }\n    }\n    throw error\n  }\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAcP,SAAS,gBAAgB,KAA4B;AACnD,MAAI;AACF,WAAO,IAAI,IAAI,GAAG,EAAE;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,WAAW,KAAkB;AACpC,MAAI,IAAI,KAAM,QAAO,IAAI;AACzB,MAAI,IAAI,aAAa,SAAU,QAAO;AACtC,MAAI,IAAI,aAAa,QAAS,QAAO;AACrC,SAAO;AACT;AAEA,SAAS,mBAAmB,UAA2B;AACrD,SAAO,aAAa,eAAe,aAAa,eAAe,aAAa;AAC9E;AAEA,SAAS,wBAAwB,kBAA0B,eAAgC;AACzF,MAAI,qBAAqB,cAAe,QAAO;AAC/C,MAAI;AACF,UAAM,aAAa,IAAI,IAAI,gBAAgB;AAC3C,UAAM,UAAU,IAAI,IAAI,aAAa;AACrC,WACE,WAAW,aAAa,QAAQ,YAChC,mBAAmB,WAAW,QAAQ,KACtC,mBAAmB,QAAQ,QAAQ,KACnC,WAAW,UAAU,MAAM,WAAW,OAAO;AAAA,EAEjD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,6BACd,KACA,MAAe,QAAQ,KACM;AAC7B,MAAI;AACF,UAAM,UAAU,wBAAwB,KAAK,GAAG;AAChD,UAAM,mBAAmB,gBAAgB,OAAO;AAChD,UAAM,gBAAgB,gBAAgB,qBAAqB,GAAG,CAAC,KAAK,gBAAgB,IAAI,GAAG;AAC3F,QAAI,oBAAoB,iBAAiB,CAAC,wBAAwB,kBAAkB,aAAa,GAAG;AAClG,cAAQ,MAAM,0EAA0E;AAAA,QACtF,YAAY,IAAI;AAAA,QAChB;AAAA,QACA;AAAA,MACF,CAAC;AACD,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,gBAAgB;AAAA,QAChB,YAAY;AAAA,MACd;AAAA,IACF;AACA,WAAO,EAAE,IAAI,MAAM,QAAQ;AAAA,EAC7B,SAAS,OAAO;AACd,QAAI,iBAAiB,wBAAwB;AAC3C,cAAQ,MAAM,iEAAiE;AAAA,QAC7E,YAAY,IAAI;AAAA,QAChB,QAAQ,MAAM;AAAA,MAChB,CAAC;AACD,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,gBAAgB;AAAA,QAChB,YAAY;AAAA,MACd;AAAA,IACF;AACA,QAAI,iBAAiB,6BAA6B;AAChD,cAAQ,MAAM,iFAAiF;AAAA,QAC7F,YAAY,IAAI;AAAA,QAChB,QAAQ,MAAM;AAAA,MAChB,CAAC;AACD,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ;AAAA,QACR,SAAS;AAAA,QACT,gBAAgB;AAAA,QAChB,YAAY;AAAA,MACd;AAAA,IACF;AACA,UAAM;AAAA,EACR;AACF;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/onboarding",
-  "version": "0.6.6-develop.5412.1.e2a52b14f0",
+  "version": "0.6.6-develop.5431.1.384a97c7a2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -69,10 +69,10 @@
     }
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5412.1.e2a52b14f0"
+    "@open-mercato/shared": "0.6.6-develop.5431.1.384a97c7a2"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5412.1.e2a52b14f0",
+    "@open-mercato/shared": "0.6.6-develop.5431.1.384a97c7a2",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/__tests__/onboarding-submit-rate-limit.test.ts

@@ -0,0 +1,22 @@
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: jest.fn(),
+}))
+
+import { metadata, openApi } from '../modules/onboarding/api/post/onboarding'
+
+describe('onboarding submission rate limiting', () => {
+  it('declares an IP rate limit so the API dispatcher throttles unauthenticated submissions', () => {
+    expect(metadata.POST.requireAuth).toBe(false)
+    expect(metadata.POST.rateLimit).toEqual({
+      points: 10,
+      duration: 60,
+      blockDuration: 60,
+      keyPrefix: 'onboarding',
+    })
+  })
+
+  it('documents the 429 response in the OpenAPI doc', () => {
+    const errors = openApi.methods?.POST?.errors ?? []
+    expect(errors.some((entry) => entry.status === 429)).toBe(true)
+  })
+})

package/src/__tests__/provisioning.test.ts

@@ -0,0 +1,89 @@
+import { runBestEffortProvisioningStep } from '@open-mercato/onboarding/modules/onboarding/lib/provisioning'
+
+function makeLogger() {
+  return { error: jest.fn(), info: jest.fn() }
+}
+
+function uniqueViolation(message: string): Error {
+  return Object.assign(new Error(message), {
+    code: '23505',
+    constraint: 'catalog_products_handle_scope_unique',
+  })
+}
+
+describe('runBestEffortProvisioningStep', () => {
+  it('returns ok and does not log when the step succeeds', async () => {
+    const logger = makeLogger()
+    const run = jest.fn().mockResolvedValue(undefined)
+
+    const result = await runBestEffortProvisioningStep('marketing-consent', run, logger)
+
+    expect(result).toEqual({ ok: true })
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+
+  it('swallows a thrown error, logs it, and reports failure instead of re-throwing', async () => {
+    const logger = makeLogger()
+    const failure = new Error('boom')
+
+    const result = await runBestEffortProvisioningStep(
+      'seedDefaults:catalog',
+      () => Promise.reject(failure),
+      logger,
+    )
+
+    expect(result).toEqual({ ok: false, error: failure })
+    expect(logger.error).toHaveBeenCalledWith(
+      '[onboarding.verify] non-fatal provisioning step failed',
+      { step: 'seedDefaults:catalog', error: failure },
+    )
+  })
+
+  it('logs an expected unique-constraint collision at info, not error', async () => {
+    // A concurrent verify / re-verify re-applies a seed against rows that
+    // already exist. seed hooks are not fully idempotent, so the duplicate-key
+    // collision is expected and harmless — it must not surface as an error and
+    // bury genuine failures (maintainer feedback on PR #2954).
+    const logger = makeLogger()
+    const failure = uniqueViolation('duplicate key value violates unique constraint')
+
+    const result = await runBestEffortProvisioningStep(
+      'seedExamples:catalog',
+      () => Promise.reject(failure),
+      logger,
+    )
+
+    expect(result).toEqual({ ok: false, error: failure })
+    expect(logger.error).not.toHaveBeenCalled()
+    expect(logger.info).toHaveBeenCalledWith(
+      '[onboarding.verify] non-fatal provisioning step skipped (already applied)',
+      { step: 'seedExamples:catalog' },
+    )
+  })
+
+  it('keeps provisioning alive when one module hook throws or times out (issue #2951)', async () => {
+    // Regression for #2951: a single seedDefaults hook that throws (or exceeds
+    // its timeout) must not abort the loop or strand the freshly provisioned
+    // workspace. Every module still runs and the sequence resolves so the
+    // verify handler can reach markCompleted.
+    const logger = makeLogger()
+    const ran: string[] = []
+    const hooks: Record<string, () => Promise<void>> = {
+      auth: async () => { ran.push('auth') },
+      catalog: async () => { ran.push('catalog'); throw new Error('seed failed') },
+      sales: async () => { ran.push('sales') },
+    }
+
+    const results = []
+    for (const moduleId of Object.keys(hooks)) {
+      results.push(
+        await runBestEffortProvisioningStep(`seedDefaults:${moduleId}`, hooks[moduleId], logger),
+      )
+    }
+
+    expect(ran).toEqual(['auth', 'catalog', 'sales'])
+    expect(results.map((r) => r.ok)).toEqual([true, false, true])
+    expect(logger.error).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/status-endpoint-auth.test.ts

@@ -2,6 +2,19 @@ import { OnboardingRequest } from '../modules/onboarding/data/entities'
 
 const findLatestByTenantId = jest.fn()
 const sendWorkspaceReadyEmail = jest.fn()
+const assertAllowedAppOrigin = jest.fn()
+const markCompleted = jest.fn()
+const runDeferredProvisioning = jest.fn()
+
+jest.mock('next/server', () => {
+  const actual = jest.requireActual('next/server')
+  return {
+    ...actual,
+    after: (callback: () => unknown) => {
+      void callback()
+    },
+  }
+})
 
 jest.mock('@open-mercato/shared/lib/di/container', () => ({
   createRequestContainer: jest.fn(async () => ({
@@ -13,13 +26,19 @@ jest.mock('@open-mercato/shared/lib/di/container', () => ({
 }))
 
 jest.mock('@open-mercato/shared/lib/url', () => ({
-  getSecurityEmailBaseUrl: () => 'https://app.example.com',
-  mapSecurityEmailUrlError: () => null,
+  assertAllowedAppOrigin: (...args: unknown[]) => assertAllowedAppOrigin(...args),
+  mapSecurityEmailUrlError: (error: unknown) => {
+    if (error instanceof Error && error.message === 'origin rejected') {
+      return { status: 400, body: { error: 'Invalid request origin' } }
+    }
+    return null
+  },
 }))
 
 jest.mock('@open-mercato/onboarding/modules/onboarding/lib/service', () => ({
   OnboardingService: jest.fn().mockImplementation(() => ({
     findLatestByTenantId,
+    markCompleted,
   })),
 }))
 
@@ -27,6 +46,18 @@ jest.mock('@open-mercato/onboarding/modules/onboarding/lib/ready-email', () => (
   sendWorkspaceReadyEmail,
 }))
 
+jest.mock('@open-mercato/onboarding/modules/onboarding/lib/deferred-provisioning', () => ({
+  resolveProvisioningIds: (request: OnboardingRequest) => {
+    if (!request.tenantId || !request.organizationId || !request.userId) return null
+    return {
+      tenantId: request.tenantId,
+      organizationId: request.organizationId,
+      userId: request.userId,
+    }
+  },
+  runDeferredProvisioning: (...args: unknown[]) => runDeferredProvisioning(...args),
+}))
+
 import { GET } from '../modules/onboarding/api/get/onboarding/status'
 
 const TENANT_ID = '11111111-1111-4111-8111-111111111111'
@@ -56,6 +87,21 @@ describe('onboarding status endpoint authorization', () => {
   beforeEach(() => {
     findLatestByTenantId.mockReset()
     sendWorkspaceReadyEmail.mockReset()
+    assertAllowedAppOrigin.mockReset()
+    markCompleted.mockReset()
+    runDeferredProvisioning.mockReset()
+    markCompleted.mockImplementation(async (request: OnboardingRequest, data: {
+      tenantId: string
+      organizationId: string
+      userId: string
+    }) => {
+      request.status = 'completed'
+      request.tenantId = data.tenantId
+      request.organizationId = data.organizationId
+      request.userId = data.userId
+      request.completedAt = new Date()
+      request.processingStartedAt = null
+    })
     findLatestByTenantId.mockResolvedValue(makeRequest())
   })
 
@@ -97,8 +143,23 @@ describe('onboarding status endpoint authorization', () => {
     expect(body.ok).toBe(true)
     expect(body.tenantId).toBe(TENANT_ID)
     expect(body.ready).toBe(true)
-    expect(body.loginUrl).toBe(`https://app.example.com/login?tenant=${TENANT_ID}`)
+    expect(body.loginUrl).toBe(`/login?tenant=${TENANT_ID}`)
     expect(findLatestByTenantId).toHaveBeenCalledWith(TENANT_ID)
+    expect(assertAllowedAppOrigin).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects a matched cookie when the request origin is not allowed', async () => {
+    assertAllowedAppOrigin.mockImplementation(() => {
+      throw new Error('origin rejected')
+    })
+
+    const res = await GET(
+      buildRequest({ tenantId: TENANT_ID, cookie: `om_login_tenant=${TENANT_ID}` }),
+    )
+
+    expect(res.status).toBe(400)
+    expect(await res.json()).toEqual({ ok: false, error: 'Invalid request origin' })
+    expect(findLatestByTenantId).not.toHaveBeenCalled()
   })
 
   it('returns 404 for an authorized caller when no onboarding record exists', async () => {
@@ -108,4 +169,32 @@ describe('onboarding status endpoint authorization', () => {
     )
     expect(res.status).toBe(404)
   })
+
+  it('recovers an interrupted processing request that already has provisioned ids', async () => {
+    const request = makeRequest({
+      status: 'processing',
+      tenantId: TENANT_ID,
+      organizationId: '44444444-4444-4444-8444-444444444444',
+      userId: '55555555-5555-4555-8555-555555555555',
+      completedAt: null,
+      preparationCompletedAt: null,
+      processingStartedAt: new Date(),
+    })
+    findLatestByTenantId.mockResolvedValue(request)
+
+    const res = await GET(
+      buildRequest({ tenantId: TENANT_ID, cookie: `om_login_tenant=${TENANT_ID}` }),
+    )
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.ok).toBe(true)
+    expect(body.status).toBe('completed')
+    expect(body.ready).toBe(false)
+    expect(markCompleted).toHaveBeenCalledWith(request, {
+      tenantId: TENANT_ID,
+      organizationId: '44444444-4444-4444-8444-444444444444',
+      userId: '55555555-5555-4555-8555-555555555555',
+    })
+  })
 })

package/src/__tests__/verify-base-url.test.ts

@@ -0,0 +1,65 @@
+import { resolveVerifyRedirectBaseUrl } from '../modules/onboarding/lib/verify-base-url'
+
+function buildRequest(url: string, headers: Record<string, string> = {}) {
+  return new Request(url, { headers })
+}
+
+describe('onboarding verify redirect base URL', () => {
+  it('uses APP_URL when it matches the verification request origin', () => {
+    const result = resolveVerifyRedirectBaseUrl(
+      buildRequest('https://demo.openmercato.com/api/onboarding/onboarding/verify?token=t'),
+      {
+        APP_URL: 'https://demo.openmercato.com',
+        NODE_ENV: 'production',
+      },
+    )
+
+    expect(result).toEqual({ ok: true, baseUrl: 'https://demo.openmercato.com' })
+  })
+
+  it('rejects a verify request when APP_URL points to a different local port', () => {
+    const result = resolveVerifyRedirectBaseUrl(
+      buildRequest('http://localhost:3001/api/onboarding/onboarding/verify?token=t'),
+      {
+        APP_URL: 'http://localhost:3000',
+        APP_ALLOWED_ORIGINS: 'http://localhost:3001',
+        NODE_ENV: 'development',
+      },
+    )
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.status).toBe('redirect_misconfigured')
+      expect(result.redirectOrigin).toBe('http://localhost:3001')
+    }
+  })
+
+  it('accepts equivalent loopback hostnames on the same port', () => {
+    const result = resolveVerifyRedirectBaseUrl(
+      buildRequest('http://127.0.0.1:3001/api/onboarding/onboarding/verify?token=t'),
+      {
+        APP_URL: 'http://localhost:3001',
+        NODE_ENV: 'development',
+      },
+    )
+
+    expect(result).toEqual({ ok: true, baseUrl: 'http://localhost:3001' })
+  })
+
+  it('returns an explicit error for non-allowlisted origins', () => {
+    const result = resolveVerifyRedirectBaseUrl(
+      buildRequest('https://evil.example/api/onboarding/onboarding/verify?token=t'),
+      {
+        APP_URL: 'https://demo.openmercato.com',
+        NODE_ENV: 'production',
+      },
+    )
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.status).toBe('origin_not_allowed')
+      expect(result.redirectOrigin).toBeNull()
+      expect(result.httpStatus).toBe(400)
+    }
+  })
+})

package/src/modules/onboarding/__integration__/TC-ONB-001-self-service-consent.spec.ts

@@ -0,0 +1,176 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { expect, test } from '@playwright/test';
+import { withClient } from '@open-mercato/core/helpers/integration/dbFixtures';
+
+export const integrationMeta = {
+  dependsOnModules: ['onboarding'],
+  requiredEnvVars: ['SELF_SERVICE_ONBOARDING_ENABLED'],
+  requiredAnyEnvVars: ['CONSENT_INTEGRITY_SECRET', 'AUTH_SECRET', 'NEXTAUTH_SECRET', 'JWT_SECRET'],
+};
+
+type OnboardingRequestRow = {
+  id: string;
+  status: string;
+  tenant_id: string | null;
+  organization_id: string | null;
+  user_id: string | null;
+  marketing_consent: boolean | null;
+  completed_at: Date | null;
+};
+
+type UserConsentRow = {
+  consent_type: string;
+  is_granted: boolean;
+  source: string | null;
+  integrity_hash: string | null;
+  granted_at: Date | null;
+};
+
+const ONBOARDING_PASSWORD = 'IntegrationPass123!';
+const BASE_URL = process.env.BASE_URL?.trim() || 'http://localhost:3000';
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+async function replaceVerificationToken(email: string, token: string): Promise<string> {
+  return withClient(async (client) => {
+    const result = await client.query<{ id: string }>(
+      `update onboarding_requests
+         set token_hash = $2,
+             expires_at = now() + interval '24 hours',
+             updated_at = now()
+       where email = $1
+       returning id`,
+      [email, hashToken(token)],
+    );
+    expect(result.rowCount, 'onboarding request should exist after submitting the form').toBe(1);
+    return result.rows[0].id;
+  });
+}
+
+async function readCompletedRequest(requestId: string): Promise<OnboardingRequestRow> {
+  return withClient(async (client) => {
+    const result = await client.query<OnboardingRequestRow>(
+      `select id, status, tenant_id, organization_id, user_id, marketing_consent, completed_at
+         from onboarding_requests
+        where id = $1`,
+      [requestId],
+    );
+    expect(result.rowCount, 'completed onboarding request should remain queryable').toBe(1);
+    return result.rows[0];
+  });
+}
+
+async function readMarketingConsent(userId: string): Promise<UserConsentRow> {
+  return withClient(async (client) => {
+    const result = await client.query<UserConsentRow>(
+      `select consent_type, is_granted, source, integrity_hash, granted_at
+         from user_consents
+        where user_id = $1 and consent_type = 'marketing_email'
+        order by created_at desc
+        limit 1`,
+      [userId],
+    );
+    expect(result.rowCount, 'marketing consent should be persisted for the onboarded user').toBe(1);
+    return result.rows[0];
+  });
+}
+
+test.describe('TC-ONB-001: self-service onboarding with marketing consent', () => {
+  test('does not offer tenant login while workspace preparation is still running', async ({ page }) => {
+    const tenantId = '33333333-3333-4333-8333-333333333333';
+    await page.route('**/api/onboarding/onboarding/status?**', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          ok: true,
+          status: 'processing',
+          ready: false,
+          emailSent: false,
+          tenantId,
+          loginUrl: null,
+        }),
+      });
+    });
+
+    await page.goto(`/onboarding/preparing?tenant=${tenantId}`);
+
+    await expect(page.getByText('We are preparing your workspace')).toBeVisible();
+    await expect(page.getByRole('link', { name: 'Open tenant login' })).toHaveCount(0);
+    await expect(page.getByRole('link', { name: 'Go to home page' })).toBeVisible();
+  });
+
+  test('shows a retryable error when workspace status polling fails', async ({ page }) => {
+    const tenantId = '33333333-3333-4333-8333-333333333333';
+    await page.route('**/api/onboarding/onboarding/status?**', async (route) => {
+      await route.fulfill({
+        status: 400,
+        contentType: 'application/json',
+        body: JSON.stringify({ ok: false, error: 'Invalid request origin' }),
+      });
+    });
+
+    await page.goto(`/onboarding/preparing?tenant=${tenantId}`);
+
+    await expect(page.getByText('We are preparing your workspace')).toBeVisible();
+    const statusAlert = page.getByText('Workspace status check failed').locator('..');
+    await expect(statusAlert).toContainText('Invalid request origin');
+    await expect(page.getByRole('link', { name: 'Open tenant login' })).toHaveCount(0);
+  });
+
+  test('creates the workspace, verifies from the email link, and logs in to the new tenant', async ({ page }) => {
+    const unique = randomUUID().slice(0, 8);
+    const email = `qa-onboarding-${unique}@example.test`;
+    const organizationName = `QA Onboarding ${unique}`;
+    const token = `integration-onboarding-${randomUUID().replace(/-/g, '')}`;
+
+    await page.goto('/onboarding');
+    await expect(page.getByText('Create your Open Mercato workspace')).toBeVisible();
+
+    await page.getByLabel('Work email').fill(email);
+    await page.getByLabel('First name').fill('QA');
+    await page.getByLabel('Last name').fill('Onboarding');
+    await page.getByLabel('Organization name').fill(organizationName);
+    await page.locator('input[name="password"]').fill(ONBOARDING_PASSWORD);
+    await page.locator('input[name="confirmPassword"]').fill(ONBOARDING_PASSWORD);
+    await page.locator('#terms').click();
+    await page.locator('#marketingConsent').click();
+    await page.getByRole('button', { name: 'Send verification email' }).click();
+
+    await expect(page.getByRole('status')).toContainText('Check your inbox');
+    await expect(page.getByRole('status')).toContainText(email);
+
+    const requestId = await replaceVerificationToken(email, token);
+    const verifyUrl = `${BASE_URL}/api/onboarding/onboarding/verify?token=${encodeURIComponent(token)}`;
+
+    await page.setContent(`<a href="${verifyUrl}">Verify workspace</a>`);
+    await page.getByRole('link', { name: 'Verify workspace' }).click();
+    await expect(page).toHaveURL(/\/onboarding\/preparing\?tenant=[0-9a-f-]+/);
+    await expect(page.getByText('We are preparing your workspace')).toBeVisible();
+
+    const completed = await readCompletedRequest(requestId);
+    expect(completed.status).toBe('completed');
+    expect(completed.marketing_consent).toBe(true);
+    expect(completed.completed_at).toBeTruthy();
+    expect(completed.tenant_id, 'tenant id should be recorded').toBeTruthy();
+    expect(completed.organization_id, 'organization id should be recorded').toBeTruthy();
+    expect(completed.user_id, 'user id should be recorded').toBeTruthy();
+
+    const consent = await readMarketingConsent(completed.user_id!);
+    expect(consent.consent_type).toBe('marketing_email');
+    expect(consent.is_granted).toBe(true);
+    expect(consent.source).toBeTruthy();
+    expect(consent.granted_at).toBeTruthy();
+    expect(consent.integrity_hash, 'consent integrity hash should be computed instead of redirecting to status=error').toBeTruthy();
+
+    await page.goto(`/login?tenant=${encodeURIComponent(completed.tenant_id!)}`);
+    await expect(page.locator('form[data-auth-ready="1"]')).toBeVisible();
+    await expect(page.getByText(/You're logging in to/i)).toBeVisible();
+    await page.getByLabel('Email').fill(email);
+    await page.getByLabel('Password', { exact: true }).fill(ONBOARDING_PASSWORD);
+    await page.getByRole('button', { name: 'Sign in' }).click();
+    await expect(page).toHaveURL(/\/backend(?:\/.*)?$/);
+  });
+});