@react-vault/create-app 0.1.0

package/claude-toolkit/skills/bfsi-compliance-check/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: bfsi-compliance-check
+description: Runs an OWASP Top 10 + RBI + PCI-DSS + IRDAI + SOC2 compliance checklist against the current branch's diff. Reports findings grouped by severity (critical, high, medium, low) with file:line references and remediation steps. Use when the user types /bfsi-compliance-check, asks to "run compliance check", "audit my changes for compliance", or "check this PR for security issues".
+disable-model-invocation: true
+allowed-tools: Read Grep Glob Bash(git diff:*) Bash(git log:*)
+---
+
+# BFSI Compliance Check
+
+Static compliance scan over the current branch's diff (`git diff origin/main...HEAD`).
+
+## Checks performed
+
+### Critical (must fix before merge)
+
+1. **Hardcoded secrets** — API keys, tokens, passwords, connection strings in code/configs
+   - Pattern: `api_key|secret|password|token|private_key` followed by `= ?['"][^'"]+['"]`
+   - Action: extract to env var
+2. **Card data in non-PCI iframe** — `<input>` capturing card number/CVV outside `<PCITokenizedCardInput>`
+   - Pattern: `name="card_number"|name="cvv"|name="cvc"` not inside `PCITokenized*`
+3. **PII in console.log / console.error** — `console.log(user.pan)`, etc.
+   - Pattern: `console\.(log|info|warn|error).*\.(pan|aadhaar|account|password|cvv|otp)`
+4. **localStorage with PII** — `localStorage.setItem(..., user.pan)`, etc.
+   - Pattern: `localStorage\.setItem.*\.(pan|aadhaar|account|password)`
+5. **Unencrypted IndexedDB** — direct `idb.put()` of objects containing PII fields
+   - Suggest using `secureStorage` from `@react-vault/core/storage`
+6. **Missing CSRF token on mutation** — `fetch('/api/...', { method: 'POST', ... })` without `X-CSRF-Token` (if not using cookie-less JWT)
+
+### High (fix before next sprint)
+
+7. **Weak crypto** — `md5`, `sha1`, `Math.random()` for security purposes, `crypto.createCipher` (deprecated)
+8. **`dangerouslySetInnerHTML`** without sanitisation
+9. **Missing `<ProtectedRoute>`** on a route that fetches user data
+10. **Missing `permission` prop** on `<ProtectedRoute>` (defaults to authenticated-only)
+11. **API mutation without audit hook** — `useMutation` instead of `useAuditedMutation`
+12. **Missing Zod parse on API response** — `query` without `transformResponse: z.parse(...)`
+13. **`autocomplete="on"` on PII input field**
+14. **Form submit without idempotency-key header**
+
+### Medium (track for hardening)
+
+15. **Inline event handlers in JSX** for sensitive actions (harder to audit)
+16. **Untranslated user-facing strings** (no `t()` wrap)
+17. **Missing `aria-label`** on PII reveal buttons
+18. **Magic numbers** for amounts (use named constants)
+19. **TODO/FIXME** comments mentioning security
+20. **No tests** for files in `src/features/*/api.ts` or containers
+
+### Low (best-practice nudges)
+
+21. **`React.FC`** usage (prefer named function components for stack traces)
+22. **Default exports** (prefer named exports for refactor safety)
+23. **`as any`** type assertions
+24. **Files over 400 lines**
+
+## Workflow
+
+### Step 1: Get the diff
+
+```bash
+git diff --name-only origin/main...HEAD
+```
+
+If no diff (or origin/main missing), fall back to `git diff HEAD~5...HEAD`.
+
+### Step 2: For each category, run targeted greps
+
+Use the patterns above. Be specific — minimise false positives. Each finding records: file, line, category, severity, the offending snippet, suggested fix.
+
+### Step 3: Group + report
+
+Output as markdown:
+
+```
+# Compliance Check Report
+
+Branch: <name>  →  origin/main (N files changed)
+
+## Critical (must fix): N findings
+1. **Hardcoded secret** in src/api/auth.ts:42
+```
+
+const API_KEY = 'sk-abc123...'
+
+```
+Fix: replace with `import.meta.env.VITE_API_KEY` and add to `.env.local.sample`.
+
+## High: N findings
+...
+```
+
+### Step 4: Exit code
+
+If any critical findings, end with: "❌ NOT MERGE-READY: N critical findings must be addressed."
+If high but no critical: "⚠️ Mergeable but address N high findings before next sprint."
+Otherwise: "✅ All checks passed."
+
+## Note on scope
+
+This is a **static** check based on patterns. It catches obvious issues but is not a substitute for:
+
+- `bfsi-security-reviewer` agent (which reasons about flows)
+- Backend security review
+- Penetration testing
+- Third-party SAST/DAST tools
+
+Always run before requesting human PR review.

package/claude-toolkit/skills/bfsi-encrypt-helper/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: bfsi-encrypt-helper
+description: Reference for encrypting and decrypting sensitive data using @react-vault/core/encryption. Covers AES-GCM (symmetric), RSA-OAEP (asymmetric), PBKDF2 (key derivation), and envelope encryption patterns. Auto-loads when the user asks about encrypting data, decrypting data, key derivation, key rotation, Web Crypto API usage, securing sensitive fields, or implementing envelope encryption.
+---
+
+# BFSI Encryption Helper
+
+Reference for `@react-vault/core/encryption`. Uses the browser's Web Crypto API — no external dependencies, no key material crosses package boundaries unprotected.
+
+## Algorithms
+
+| Algorithm       | Use                           | Module                               |
+| --------------- | ----------------------------- | ------------------------------------ |
+| AES-GCM 256     | Symmetric encryption of data  | `aesgcm.encrypt`, `aesgcm.decrypt`   |
+| RSA-OAEP-SHA256 | Asymmetric encryption of keys | `rsaoaep.encrypt`, `rsaoaep.decrypt` |
+| PBKDF2-SHA256   | Derive key from password      | `pbkdf2.deriveKey`                   |
+| HKDF-SHA256     | Derive key from existing key  | `hkdf.deriveKey`                     |
+| ECDSA-P256      | Sign / verify                 | `ecdsa.sign`, `ecdsa.verify`         |
+
+## Common patterns
+
+### Encrypt a string with a known symmetric key
+
+```ts
+import { aesgcm } from '@react-vault/core/encryption';
+
+const key = await aesgcm.generateKey();
+const ciphertext = await aesgcm.encrypt(key, 'sensitive value');
+const plaintext = await aesgcm.decrypt(key, ciphertext);
+```
+
+`encrypt` returns a base64 blob containing IV + ciphertext + auth tag. Don't try to compose this yourself — it's not interchangeable with raw Web Crypto output without the framing.
+
+### Derive a key from a password
+
+```ts
+import { pbkdf2 } from '@react-vault/core/encryption';
+
+const salt = crypto.getRandomValues(new Uint8Array(16));
+const key = await pbkdf2.deriveKey(password, salt, { iterations: 600_000 });
+// Use the key for AES-GCM. Store salt alongside ciphertext.
+```
+
+600k iterations is OWASP 2025 recommendation for PBKDF2-SHA256. Don't lower it.
+
+### Envelope encryption (BFSI standard)
+
+This is the right pattern for storing many fields with one key, with key rotation:
+
+```ts
+import { envelope } from '@react-vault/core/encryption';
+
+// Setup: backend provides a public KEK (key-encrypting-key).
+const masterPublicKey = await rsaoaep.importPublicKey(masterPublicKeyPem);
+
+// Encrypt: generate a per-record DEK, encrypt data with DEK,
+// then encrypt DEK with the master KEK.
+const { ciphertext, encryptedDek } = await envelope.encrypt(
+  masterPublicKey,
+  JSON.stringify({ pan: '...', aadhaar: '...' }),
+);
+
+// Store: { ciphertext, encryptedDek } alongside the record.
+// Decrypt: backend decrypts DEK with master private key, sends DEK to client,
+// client decrypts ciphertext with DEK.
+```
+
+Key rotation: rotate the KEK on the backend; re-encrypt only the small `encryptedDek` per record. The large `ciphertext` doesn't need to be touched.
+
+## Where NOT to use
+
+- **Passwords**: never encrypt — hash with bcrypt/argon2 on the BACKEND. Client-side hashing helps you nothing.
+- **Card numbers**: never encrypt yourself. Use `<PCITokenizedCardInput>`. Real card data should never reach your app.
+- **Auth tokens**: don't encrypt — protect via secure storage (memory-first, see `@react-vault/core/storage`).
+- **Session cookies**: server's job, not yours.
+
+## Anti-patterns
+
+```ts
+// ❌ Don't roll your own crypto
+const encrypted = btoa(JSON.stringify(data)); // NOT encryption
+
+// ❌ Don't use Math.random() for keys / IVs
+const iv = new Uint8Array(12).map(() => Math.random() * 256); // INSECURE
+
+// ❌ Don't reuse IV across messages
+const fixedIv = new Uint8Array(12); // CATASTROPHIC for GCM
+
+// ❌ Don't store keys in localStorage
+localStorage.setItem('encryption_key', exportedKey); // Defeats the point
+
+// ❌ Don't use SHA-1 for anything security-related
+const hash = crypto.subtle.digest('SHA-1', data); // Use SHA-256 minimum
+```
+
+## Verification
+
+After implementing encryption, verify with:
+
+```ts
+import { aesgcm } from '@react-vault/core/encryption';
+import { describe, expect, it } from 'vitest';
+
+describe('encryption round-trip', () => {
+  it('produces different ciphertext each time (IV randomness)', async () => {
+    const key = await aesgcm.generateKey();
+    const a = await aesgcm.encrypt(key, 'test');
+    const b = await aesgcm.encrypt(key, 'test');
+    expect(a).not.toBe(b);
+  });
+
+  it('decrypts to the original', async () => {
+    const key = await aesgcm.generateKey();
+    const ciphertext = await aesgcm.encrypt(key, 'test');
+    expect(await aesgcm.decrypt(key, ciphertext)).toBe('test');
+  });
+
+  it('throws on tampered ciphertext', async () => {
+    const key = await aesgcm.generateKey();
+    const ciphertext = await aesgcm.encrypt(key, 'test');
+    const tampered = ciphertext.slice(0, -2) + 'XX';
+    await expect(aesgcm.decrypt(key, tampered)).rejects.toThrow();
+  });
+});
+```
+
+These three tests catch 95% of misuses.

package/claude-toolkit/skills/bfsi-error-message/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: bfsi-error-message
+description: Reference for writing safe error messages — what users see, what gets logged, what gets sent to telemetry. Prevents stack traces, SQL, request IDs, or PII from leaking to UI or third-party services. Auto-loads when the user asks about error messages, error handling, exception messages, error boundaries, or Sentry/observability config.
+---
+
+# Safe Error Messages
+
+Reference for what's safe to show users, log to console, and send to telemetry.
+
+## The three-tier model
+
+Every error has three audiences:
+
+| Tier          | Audience         | What they should see                                       |
+| ------------- | ---------------- | ---------------------------------------------------------- |
+| **UI**        | End user         | Friendly, actionable, generic. NO technical detail.        |
+| **Logs**      | Developers       | Full technical detail, structured. PII scrubbed.           |
+| **Telemetry** | Sentry / Datadog | Anonymised stack + breadcrumbs. NO PII, NO request bodies. |
+
+A single error gives different content to each tier.
+
+## UI messages
+
+### What users SHOULD see
+
+- ✅ "Something went wrong. Please try again."
+- ✅ "We couldn't process your transaction. Please check your details and try again. (Ref: ERR-A7K2)"
+- ✅ "This PAN is already registered with another account."
+- ✅ "Your session has expired. Please log in again."
+
+### What users SHOULD NEVER see
+
+- ❌ `TypeError: Cannot read properties of undefined (reading 'data')`
+- ❌ `Failed to fetch: HTTP 500 from /api/v1/users/12345/kyc`
+- ❌ `Connection refused: postgres://prod-db.internal:5432`
+- ❌ `SQL syntax error near "DROP TABLE users"`
+- ❌ Any raw error from the backend
+- ❌ Stack traces
+- ❌ Internal IDs (user IDs, session IDs — except a short ref code)
+
+### Reference codes
+
+Generate a short alphanumeric code (e.g. `ERR-A7K2`) that maps to the full error in logs. The user reads this to support; support looks it up. The user sees ONLY the code, never the underlying ID or message.
+
+```ts
+import { generateErrorRef, recordError } from '@react-vault/core/audit';
+
+try {
+  // ...
+} catch (err) {
+  const ref = generateErrorRef();
+  recordError(ref, err, { feature: 'kyc', action: 'submit' });
+  showToast({ title: t('errors.generic'), description: t('errors.ref', { ref }) });
+}
+```
+
+## Log messages
+
+Logs go to console (dev) and structured log shipper (prod). Full detail is fine, but:
+
+- **PII scrubbed** — run through `auditClient.scrub()` before logging
+- **Structured** — log as JSON (`pino`-style), not strings
+- **Correlated** — include `request_id`, `user_id` (NOT email/name), `session_id`
+
+```ts
+log.error({
+  request_id: req.id,
+  user_id: user.id,
+  feature: 'kyc',
+  action: 'submit',
+  error: err.message,
+  stack: err.stack,
+  // NEVER: pan: user.pan, aadhaar: user.aadhaar
+});
+```
+
+## Telemetry (Sentry)
+
+Sentry is third-party and may be subject to different data residency rules. Treat its data as escaping your perimeter.
+
+### Configure scrubbing
+
+```ts
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  beforeSend(event) {
+    // Scrub PII from breadcrumbs, request bodies, URL params
+    return scrubSentryEvent(event);
+  },
+  ignoreErrors: [
+    // Browser extension noise
+    'top.GLOBALS',
+    'ResizeObserver loop limit exceeded',
+  ],
+});
+```
+
+`scrubSentryEvent` (from `@react-vault/core/observability`) walks the event and:
+
+- Removes `request.data` (request body)
+- Removes URL query params matching PII patterns
+- Replaces values in `extra` / `tags` / `user` that match PII patterns with `<scrubbed>`
+- Trims breadcrumbs older than 30 seconds (to limit blast radius)
+
+### Sentry user context
+
+Set the bare minimum:
+
+```ts
+Sentry.setUser({ id: user.id }); // ID only — NEVER email, name, mobile
+```
+
+## Error boundary
+
+Wrap every route in `<BFSIErrorBoundary>` (from `@react-vault/ui`). It:
+
+1. Catches the error
+2. Generates a ref code
+3. Records full detail to logs + telemetry (with scrubbing)
+4. Shows a generic friendly message with the ref code
+5. Provides a "go back" button
+
+Never expose the actual error message via `componentDidCatch`'s `error.message` to JSX.
+
+## When to throw vs when to swallow
+
+- **Throw** when something genuinely went wrong and the calling code can't continue safely.
+- **Swallow + log** when the operation can degrade gracefully (e.g. analytics failed — show UI anyway).
+
+Never swallow silently. Even degraded paths should leave a log entry.
+
+## Form validation errors (different rules)
+
+Validation errors are NOT exceptions — they're expected user input. These can be specific:
+
+- ✅ "PAN must be 10 characters: 5 letters, 4 digits, 1 letter"
+- ✅ "Amount must be at least ₹100"
+- ✅ "Mobile number must start with 6, 7, 8, or 9"
+
+These come from Zod's `.message()` and are user-facing on purpose. Just keep them generic — don't include the _value_ the user typed back into the error.
+
+## Edge cases
+
+### Network errors
+
+Don't show "Failed to fetch" or similar. Map to: "We couldn't reach our servers. Check your internet connection and try again."
+
+### 401 (auth)
+
+Don't show "Unauthorized" or "Token expired". Map to: "Your session has expired. Please log in again." Then redirect to login.
+
+### 403 (permission)
+
+Don't show "Forbidden" or "Insufficient permissions". Map to: "You don't have access to this. Contact your administrator if you think this is wrong."
+
+### 5xx (server)
+
+Don't show "Internal server error" or HTTP details. Map to: "We're having trouble right now. Please try again in a moment. (Ref: ERR-XXXX)"
+
+### 429 (rate limit)
+
+Map to: "Too many attempts. Please wait a moment and try again."

package/claude-toolkit/skills/bfsi-feature/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: bfsi-feature
+description: Scaffolds a new BFSI feature module with the full directory structure (api, containers, components, routes, tests, i18n keys). Variant-aware — generates RTK Query OR TanStack Query code based on the project's stack. Use when the user types /bfsi-feature, asks to "scaffold a feature", "create a new feature module", "add a CRUD page", or "start a new BFSI module".
+disable-model-invocation: true
+argument-hint: <feature-name> [--variant rtk|tanstack] [--no-i18n]
+allowed-tools: Read Write Edit Glob Grep Bash(mkdir:*) Bash(node:*)
+---
+
+# BFSI Feature Scaffold
+
+Generates a complete feature module under `src/features/<FeatureName>/` following the Your Real Company BFSI architecture: container-component split, RTK Query / TanStack Query API layer, Zod validation, audit-wrapped mutations, accessible UI, i18n keys.
+
+## Arguments
+
+- `$0` — feature name in PascalCase (e.g. `KycVerification`, `LoanApplication`, `Transactions`). **Required.**
+- `--variant rtk|tanstack` — overrides project default (auto-detected from `package.json`).
+- `--no-i18n` — skip i18n key generation.
+
+## What gets generated
+
+```
+src/features/<FeatureName>/
+├── api.ts                          # RTK Query slice OR TanStack hook factories
+├── schema.ts                       # Zod schemas (request, response, form)
+├── types.ts                        # Inferred TS types from Zod
+├── constants.ts                    # API URLs, cache tags, audit event names
+├── routes.tsx                      # Feature routes with <ProtectedRoute>
+├── containers/
+│   ├── <FeatureName>List.tsx       # Container: data + handlers
+│   └── <FeatureName>Form.tsx       # Container: form state
+├── components/
+│   ├── <FeatureName>Table.tsx      # Presentational: receives props
+│   ├── <FeatureName>FormFields.tsx # Presentational: form fields
+│   └── <FeatureName>Actions.tsx    # Audit-wrapped action buttons
+├── hooks/
+│   └── use<FeatureName>.ts         # Custom hooks
+├── utils/
+│   └── mappers.ts                  # snake_case ↔ camelCase, value mappers
+├── __tests__/
+│   ├── containers.test.tsx
+│   ├── schema.test.ts
+│   └── e2e.spec.ts                 # Playwright
+└── index.ts                        # Barrel export
+```
+
+Plus updates to:
+
+- `src/routes/index.tsx` — registers the new feature routes
+- `src/i18n/translations/en.json` — adds `<feature>.*` namespace
+- `src/i18n/translations/hi.json` — placeholder keys (translator fills in)
+
+## Workflow
+
+### Step 1: Validate inputs
+
+Confirm:
+
+- `$0` is PascalCase (regex `^[A-Z][A-Za-z0-9]+$`).
+- The feature directory does NOT already exist.
+- A `package.json` exists at the project root.
+- Detect variant: look for `@reduxjs/toolkit` vs `@tanstack/react-query` in dependencies.
+
+If validation fails, exit and tell the user what to fix.
+
+### Step 2: Run the scaffold script
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/skills/bfsi-feature/scripts/scaffold.mjs $0 --variant=<detected>
+```
+
+The script writes all files using the templates in `references/templates/`.
+
+### Step 3: Verify
+
+After generation:
+
+1. Run `pnpm typecheck` and report any errors.
+2. Run `pnpm lint` on the new files only.
+3. Read the generated `routes.tsx` and confirm it's registered.
+
+### Step 4: Summarise
+
+Output a short summary to the user:
+
+- N files created
+- Routes registered: `/<feature>` and `/<feature>/:id`
+- Next step suggestion: "Run `pnpm dev` and visit /<feature> to see the empty list. Then add fields to `schema.ts`."
+
+## Conventions enforced
+
+- **No `any` types.** All types flow from Zod schemas via `z.infer<>`.
+- **No hardcoded strings.** All user-facing strings go through `t()` (or `<Trans>`).
+- **Sensitive fields get `<PIIMaskedDisplay>` wrappers** by default if their names match `/^(pan|aadhaar|account|mobile|email|dob)$/i`.
+- **All mutations go through `useAuditedMutation`** which logs the action.
+- **All routes are `<ProtectedRoute>`** with an explicit `permission` prop.
+- **All forms use `useFormWithZod`** (from `@react-vault/ui`) for consistent validation display.
+
+## Examples
+
+### Create a KYC feature
+
+```
+/bfsi-feature KycVerification
+```
+
+Result: `src/features/KycVerification/` populated. PAN, Aadhaar, address fields auto-wrapped with PIIMaskedDisplay. Routes `/kyc-verification` and `/kyc-verification/:id` registered with `permission="kyc.view"`.
+
+### Override variant
+
+```
+/bfsi-feature LoanApplication --variant tanstack
+```
+
+Force TanStack Query API layer even if project default is RTK.
+
+## References
+
+- Full file templates: [`references/templates/`](references/templates/)
+- BFSI architecture rationale: [`references/architecture.md`](references/architecture.md)
+- Audit event naming convention: [`references/audit-events.md`](references/audit-events.md)

package/claude-toolkit/skills/bfsi-feature/references/architecture.md

@@ -0,0 +1,69 @@
+# BFSI Feature — Architecture rationale
+
+## Why container-component split?
+
+**Containers** own all side-effects: API calls, audit logging, mutations, navigation, form state. They have no JSX of their own — just compose a presentational component and pass it props.
+
+**Components** receive props, render UI, emit events. No `useFetch`, no `useDispatch`, no `useNavigate`. They are pure and easy to test with React Testing Library.
+
+For BFSI, this split matters because:
+
+- **Audit clarity** — security review only needs to look at containers to see what data flows in/out
+- **Easy mocking** — components test in isolation; you don't fight network in unit tests
+- **Reusability** — same component renders in two contexts with different containers (e.g. customer-view vs admin-view)
+
+## Why Zod everywhere?
+
+We use Zod for THREE distinct purposes:
+
+1. **API response validation** — every API response is parsed through a Zod schema before reaching components. Rejects malformed responses (XSS defence).
+2. **Form validation** — same schema or a derived schema validates form inputs.
+3. **Type generation** — `z.infer<typeof schema>` gives us TS types from a single source of truth.
+
+This means: edit one Zod schema, and types + runtime checks update together. No drift.
+
+## Why audit-wrapped mutations?
+
+Every state-changing API call must be audited for BFSI compliance (RBI Annexure I, SOC2 CC7.3). The `useAuditedMutation` hook from `@react-vault/core/audit` wraps RTK Query / TanStack Query mutations and:
+
+1. Generates an event ID (UUID v4)
+2. Records: actor, action, target, timestamp, request hash
+3. POSTs to `/api/audit` with PII scrubbed
+4. Records success/failure result
+5. Returns the same shape as the underlying mutation
+
+The container layer always uses `useAuditedMutation` instead of raw `useMutation`.
+
+## Why permission-gated routes?
+
+`<ProtectedRoute permission="kyc.view">` does TWO checks:
+
+1. **Authentication** — is there a valid session?
+2. **Authorization** — does the current user's permission set include `"kyc.view"`?
+
+Failing #1 → redirect to login. Failing #2 → render 403 with audit log entry.
+
+The permission string is checked against the current user's permission set fetched at login. We do NOT trust client-side permissions for security; the backend re-checks on every API call. The client check is a UX optimisation (don't show what they can't access) and an audit-log trigger.
+
+## Sensitive field auto-wrap
+
+The scaffolder auto-wraps fields whose names match `/^(pan|aadhaar|account|mobile|email|dob)$/i` with `<PIIMaskedDisplay>` in the table component. This means:
+
+- The value is masked by default (`****1234` for account numbers, `ABCDE****F` for PAN, etc.)
+- A reveal toggle fires an audit log event with reason
+- Reveals expire after 30 seconds and re-mask
+
+This is a default; you can opt out by editing the generated component. But by default, PII never appears unmasked in lists or tables.
+
+## i18n namespace per feature
+
+Each feature gets its own i18n namespace `<feature>.*`. This keeps translation files navigable (one team can own KYC translations, another Loans) and lets us lazy-load translation chunks per route.
+
+Naming:
+
+- `<feature>.title`
+- `<feature>.list.empty`
+- `<feature>.form.fields.<fieldName>.label`
+- `<feature>.form.fields.<fieldName>.placeholder`
+- `<feature>.errors.<errorCode>`
+- `<feature>.actions.<actionName>`

package/claude-toolkit/skills/bfsi-feature/references/audit-events.md

@@ -0,0 +1,70 @@
+# Audit Event Naming Convention
+
+Every state-changing action emits an audit event. Names follow:
+
+```
+<feature>.<entity>.<action>
+```
+
+Examples:
+
+- `kyc.verification.submitted`
+- `kyc.verification.approved`
+- `kyc.verification.rejected`
+- `loan.application.created`
+- `loan.application.documents_uploaded`
+- `transaction.transfer.initiated`
+- `transaction.transfer.confirmed`
+- `user.profile.password_changed`
+- `user.session.logged_in`
+- `user.session.logged_out_idle`
+- `data.account_number.revealed`
+- `data.pan.revealed`
+
+## Required event metadata
+
+Every event must include:
+
+| Field              | Source                              | Notes                                             |
+| ------------------ | ----------------------------------- | ------------------------------------------------- |
+| `event_id`         | UUID v4                             | Generated client-side                             |
+| `event_name`       | string                              | e.g. `kyc.verification.submitted`                 |
+| `actor_id`         | from session                        | User performing the action                        |
+| `actor_session_id` | from session                        | Session correlation                               |
+| `target_type`      | string                              | e.g. `kyc_verification`                           |
+| `target_id`        | string                              | Resource ID                                       |
+| `timestamp`        | ISO 8601                            | Client clock — backend re-stamps for legal record |
+| `outcome`          | `success` \| `failure` \| `pending` | Always populated                                  |
+| `request_hash`     | sha256                              | Of request body, for tamper detection             |
+| `client_metadata`  | object                              | User agent, viewport — no PII                     |
+
+## Reveal events
+
+When a user reveals a masked PII field, fire:
+
+```
+data.<field>.revealed
+```
+
+With metadata `{ field, reason?, duration_ms }`. If `reason` is required by policy (e.g. for Aadhaar in some flows), the UI must prompt and include it.
+
+## Failure events
+
+For failed sensitive operations:
+
+```
+<feature>.<entity>.<action>_failed
+```
+
+With metadata including the error code (but NEVER the raw error message — that may contain PII).
+
+## NEVER include in audit events
+
+- Card numbers (raw or last-4)
+- Passwords
+- OTP codes
+- Full PAN / Aadhaar (only masked, e.g. `****1234`)
+- Full account numbers
+- Free-text user input from forms (it might contain PII)
+
+The `auditClient` in `@react-vault/core/audit` runs every payload through a PII scrubber before POST.