feat(auth): add row/size caps + streaming to export-user-data

- Add per-collection row cap (default 10k, env EXPORT_ROW_CAP) via Prisma take on all findMany calls - Add total size cap (default 100MB, env EXPORT_SIZE_CAP_MB); throws PayloadTooLargeException (413) when exceeded - Convert response to Node.js Readable stream piped via NestJS StreamableFile to avoid large in-memory buffers - Export ExportUserDataResult interface (stream + truncated flag) from handler - Update controller to set Content-Type/Content-Disposition headers and return StreamableFile - Document EXPORT_ROW_CAP and EXPORT_SIZE_CAP_MB env vars in Swagger - Extend tests: row-cap assertion (take arg), size-cap 413 path, stream assertions Fixes GOO-223 (M-1 from GOO-200 audit). Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-24 12:10:54 +07:00
parent b4bb05479e
commit fa3ba88f40
34 changed files with 1494 additions and 45 deletions
--- a/libs/contracts/events/README.md
+++ b/libs/contracts/events/README.md
@@ -0,0 +1,53 @@
+# @goodgo/contracts-events
+
+Cross-runtime (Node + Python) event contracts for RFC-004's async messaging
+backbone. See [GOO-95](/GOO/issues/GOO-95) for the RFC and
+[GOO-172](/GOO/issues/GOO-172) for Phase 0.
+
+## What lives here
+
+- `src/envelope.ts` — `EventEnvelope<T>` TypeScript type + `EVENT_ENVELOPE_SCHEMA_VERSION`.
+- `src/uuid-v7.ts` — pure-Node UUIDv7 generator (no runtime deps).
+- `src/event-types.ts` — string-literal union of all known event types.
+- `schemas/envelope.schema.json` — JSON Schema for the envelope itself.
+- `schemas/<event-type>.schema.json` — JSON Schema for each event payload.
+
+The `schemas/` directory is consumed by the Python AI services
+(`libs/ai-services`) via `redis-py` consumers — JSON Schema is the single
+source of truth across runtimes.
+
+## Envelope shape
+
+```ts
+interface EventEnvelope<TPayload = unknown> {
+  schemaVersion: number;     // bump when envelope itself changes
+  eventId: string;           // UUIDv7 — time-ordered, idempotency key
+  eventType: string;         // dotted: "payment.completed"
+  occurredAt: string;        // ISO-8601 UTC
+  producer: string;          // service name, e.g. "api"
+  traceId: string;           // OpenTelemetry-compatible (32 hex chars or "00…")
+  payload: TPayload;         // event-specific, validated by per-type schema
+}
+```
+
+`schemaVersion` starts at `1`. Bump only when the **envelope** changes;
+payload changes are versioned per event-type schema independently.
+
+## First 3 schemas (Phase 0 deliverable)
+
+| Event type           | Trigger                                          |
+|----------------------|--------------------------------------------------|
+| `payment.completed`  | Payment moves to `succeeded` after gateway IPN   |
+| `listing.approved`   | Moderation approves a listing                    |
+| `kyc.verified`       | KYC review marks a user verified                 |
+
+Phase 1 (notifications cutover, [GOO-173](/GOO/issues/GOO-173)) will add
+the rest of the production event surface.
+
+## Adding a new event type
+
+1. Pick a stable dotted name (`<aggregate>.<past-tense-verb>`).
+2. Add a `schemas/<name>.schema.json` JSON Schema describing the payload.
+3. Add the literal to `src/event-types.ts`.
+4. (Optional) Re-export a typed payload alias from `src/index.ts`.
+5. Land + dual-publish for at least one sprint before any consumer hard-fails on it.
--- a/libs/contracts/events/package.json
+++ b/libs/contracts/events/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@goodgo/contracts-events",
+  "version": "0.1.0",
+  "private": true,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schemas/*": "./schemas/*"
+  },
+  "scripts": {
+    "lint": "echo \"(no lint configured)\"",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"(no tests yet)\""
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}
--- a/libs/contracts/events/schemas/envelope.schema.json
+++ b/libs/contracts/events/schemas/envelope.schema.json
@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://goodgo.vn/schemas/events/envelope.schema.json",
+  "title": "EventEnvelope",
+  "description": "Cross-runtime event envelope for RFC-004 (GOO-95). Source of truth — Node and Python consumers validate against this file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "eventId",
+    "eventType",
+    "occurredAt",
+    "producer",
+    "traceId",
+    "payload"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Envelope wire-format version. Currently 1."
+    },
+    "eventId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+      "description": "UUIDv7 — time-ordered. Used as idempotency key (30-day TTL in idempotency table)."
+    },
+    "eventType": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$",
+      "description": "Dotted event type, e.g. payment.completed."
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp of the domain event (not publish time)."
+    },
+    "producer": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Producing service identifier, e.g. api, ai-services."
+    },
+    "traceId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "description": "OpenTelemetry-compatible 32-hex trace id. Use 32 zeros when no active span."
+    },
+    "payload": {
+      "description": "Event-specific payload; validated separately against schemas/<eventType>.schema.json."
+    }
+  }
+}
--- a/libs/contracts/events/schemas/kyc.verified.schema.json
+++ b/libs/contracts/events/schemas/kyc.verified.schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://goodgo.vn/schemas/events/kyc.verified.schema.json",
+  "title": "kyc.verified",
+  "description": "Emitted when a user's KYC review transitions to VERIFIED.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["userId", "verifiedByUserId", "level", "verifiedAt", "documentRefs"],
+  "properties": {
+    "userId": { "type": "string", "minLength": 1 },
+    "verifiedByUserId": { "type": "string", "minLength": 1 },
+    "level": { "type": "string", "enum": ["basic", "enhanced"] },
+    "verifiedAt": { "type": "string", "format": "date-time" },
+    "documentRefs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Opaque references (e.g. S3 keys) to the documents used for verification."
+    }
+  }
+}
--- a/libs/contracts/events/schemas/listing.approved.schema.json
+++ b/libs/contracts/events/schemas/listing.approved.schema.json
@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://goodgo.vn/schemas/events/listing.approved.schema.json",
+  "title": "listing.approved",
+  "description": "Emitted when a Listing is approved by moderation and goes live.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "listingId",
+    "propertyId",
+    "agentId",
+    "approvedByUserId",
+    "approvedAt",
+    "expiresAt"
+  ],
+  "properties": {
+    "listingId": { "type": "string", "minLength": 1 },
+    "propertyId": { "type": "string", "minLength": 1 },
+    "agentId": { "type": "string", "minLength": 1 },
+    "approvedByUserId": { "type": "string", "minLength": 1 },
+    "approvedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Null when the listing has no scheduled expiry."
+    }
+  }
+}
--- a/libs/contracts/events/schemas/payment.completed.schema.json
+++ b/libs/contracts/events/schemas/payment.completed.schema.json
@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://goodgo.vn/schemas/events/payment.completed.schema.json",
+  "title": "payment.completed",
+  "description": "Emitted when a Payment aggregate transitions to SUCCEEDED after a verified gateway IPN (VNPay / MoMo / ZaloPay).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "paymentId",
+    "orderId",
+    "userId",
+    "amount",
+    "currency",
+    "gateway",
+    "gatewayTransactionId",
+    "paidAt"
+  ],
+  "properties": {
+    "paymentId": { "type": "string", "minLength": 1 },
+    "orderId": { "type": "string", "minLength": 1 },
+    "userId": { "type": "string", "minLength": 1 },
+    "amount": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Decimal as string to preserve VND precision (no float rounding)."
+    },
+    "currency": { "type": "string", "enum": ["VND", "USD"] },
+    "gateway": { "type": "string", "enum": ["vnpay", "momo", "zalopay"] },
+    "gatewayTransactionId": { "type": "string", "minLength": 1 },
+    "paidAt": { "type": "string", "format": "date-time" }
+  }
+}
--- a/libs/contracts/events/src/envelope.ts
+++ b/libs/contracts/events/src/envelope.ts
@@ -0,0 +1,69 @@
+import { isUuidV7 } from './uuid-v7';
+
+export const EVENT_ENVELOPE_SCHEMA_VERSION = 1;
+
+export interface EventEnvelope<TPayload = unknown> {
+  schemaVersion: number;
+  eventId: string;
+  eventType: string;
+  occurredAt: string;
+  producer: string;
+  traceId: string;
+  payload: TPayload;
+}
+
+const TRACE_ID_RE = /^[0-9a-f]{32}$/i;
+const ISO_8601_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+export interface EnvelopeValidationIssue {
+  path: string;
+  message: string;
+}
+
+export function validateEnvelope(envelope: unknown): EnvelopeValidationIssue[] {
+  const issues: EnvelopeValidationIssue[] = [];
+  if (envelope === null || typeof envelope !== 'object') {
+    return [{ path: '$', message: 'envelope must be an object' }];
+  }
+  const e = envelope as Record<string, unknown>;
+  if (e['schemaVersion'] !== EVENT_ENVELOPE_SCHEMA_VERSION) {
+    issues.push({
+      path: 'schemaVersion',
+      message: `expected ${EVENT_ENVELOPE_SCHEMA_VERSION}, got ${String(e['schemaVersion'])}`,
+    });
+  }
+  if (typeof e['eventId'] !== 'string' || !isUuidV7(e['eventId'])) {
+    issues.push({ path: 'eventId', message: 'must be a UUIDv7 string' });
+  }
+  if (
+    typeof e['eventType'] !== 'string' ||
+    !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(e['eventType'])
+  ) {
+    issues.push({
+      path: 'eventType',
+      message: 'must match /^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$/',
+    });
+  }
+  if (typeof e['occurredAt'] !== 'string' || !ISO_8601_RE.test(e['occurredAt'])) {
+    issues.push({ path: 'occurredAt', message: 'must be an ISO-8601 timestamp' });
+  }
+  if (typeof e['producer'] !== 'string' || e['producer'].length === 0) {
+    issues.push({ path: 'producer', message: 'must be a non-empty string' });
+  }
+  if (typeof e['traceId'] !== 'string' || !TRACE_ID_RE.test(e['traceId'])) {
+    issues.push({ path: 'traceId', message: 'must be 32 hex characters' });
+  }
+  if (!('payload' in e)) {
+    issues.push({ path: 'payload', message: 'is required (use {} for empty)' });
+  }
+  return issues;
+}
+
+export function assertValidEnvelope(envelope: unknown): asserts envelope is EventEnvelope {
+  const issues = validateEnvelope(envelope);
+  if (issues.length > 0) {
+    const flat = issues.map((i) => `${i.path}: ${i.message}`).join('; ');
+    throw new Error(`Invalid EventEnvelope — ${flat}`);
+  }
+}
--- a/libs/contracts/events/src/event-types.ts
+++ b/libs/contracts/events/src/event-types.ts
@@ -0,0 +1,11 @@
+export const KNOWN_EVENT_TYPES = [
+  'kyc.verified',
+  'listing.approved',
+  'payment.completed',
+] as const;
+
+export type KnownEventType = (typeof KNOWN_EVENT_TYPES)[number];
+
+export function isKnownEventType(value: string): value is KnownEventType {
+  return (KNOWN_EVENT_TYPES as readonly string[]).includes(value);
+}
--- a/libs/contracts/events/src/index.ts
+++ b/libs/contracts/events/src/index.ts
@@ -0,0 +1,37 @@
+export {
+  EVENT_ENVELOPE_SCHEMA_VERSION,
+  type EventEnvelope,
+  type EnvelopeValidationIssue,
+  validateEnvelope,
+  assertValidEnvelope,
+} from './envelope';
+export { uuidv7, isUuidV7 } from './uuid-v7';
+export { KNOWN_EVENT_TYPES, type KnownEventType, isKnownEventType } from './event-types';
+
+export interface PaymentCompletedPayload {
+  paymentId: string;
+  orderId: string;
+  userId: string;
+  amount: string;
+  currency: 'VND' | 'USD';
+  gateway: 'vnpay' | 'momo' | 'zalopay';
+  gatewayTransactionId: string;
+  paidAt: string;
+}
+
+export interface ListingApprovedPayload {
+  listingId: string;
+  propertyId: string;
+  agentId: string;
+  approvedByUserId: string;
+  approvedAt: string;
+  expiresAt: string | null;
+}
+
+export interface KycVerifiedPayload {
+  userId: string;
+  verifiedByUserId: string;
+  level: 'basic' | 'enhanced';
+  verifiedAt: string;
+  documentRefs: string[];
+}
--- a/libs/contracts/events/src/uuid-v7.ts
+++ b/libs/contracts/events/src/uuid-v7.ts
@@ -0,0 +1,44 @@
+import { randomBytes } from 'node:crypto';
+
+/**
+ * UUIDv7 — 48-bit Unix-ms timestamp in the high bits, 74 random bits below.
+ *
+ * Time-ordered, monotonic enough for our needs (idempotency keys + Stream IDs).
+ * No dependency on the `uuid` package — Phase 0 keeps the foundation
+ * tree-shakeable for the Python side (which uses its own implementation).
+ *
+ * Reference: RFC 9562 §5.7.
+ */
+export function uuidv7(now: number = Date.now()): string {
+  const ts = BigInt(now); // milliseconds since epoch
+  const bytes = randomBytes(16);
+
+  // 48-bit timestamp (big-endian) in bytes 0..5
+  bytes[0] = Number((ts >> 40n) & 0xffn);
+  bytes[1] = Number((ts >> 32n) & 0xffn);
+  bytes[2] = Number((ts >> 24n) & 0xffn);
+  bytes[3] = Number((ts >> 16n) & 0xffn);
+  bytes[4] = Number((ts >> 8n) & 0xffn);
+  bytes[5] = Number(ts & 0xffn);
+
+  // Version 7 in the high nibble of byte 6
+  bytes[6] = (bytes[6]! & 0x0f) | 0x70;
+  // RFC 4122 variant (10xx) in the high bits of byte 8
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+  const hex = Buffer.from(bytes).toString('hex');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+}
+
+const UUID_V7_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isUuidV7(value: string): boolean {
+  return UUID_V7_RE.test(value);
+}
--- a/libs/contracts/events/tsconfig.json
+++ b/libs/contracts/events/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "schemas/**/*.json"]
+}