@nest-yalc-2/field-middleware 2.2.13 → 2.2.15

package/README.md

@@ -6,13 +6,6 @@
   [![License](https://img.shields.io/npm/l/%40nest-yalc-2%2Ffield-middleware.svg)](https://github.com/AI-Autistic-Intelligence)
 </div>
 
-## 📖 Overview
-
-**@nest-yalc-2/field-middleware** is a core enterprise module of the [Ferrox Ecosystem](https://ferrox-rust.dev). 
-Core enterprise module for the @nest-yalc-2/field-middleware integration within the Ferrox/YALC ecosystem.
-
-> ⚠️ **Note:** This package is a foundational component of the enterprise Ferrox/YALC microservice architecture. For comprehensive documentation, architecture patterns (including the 7-Layer Architecture), and ecosystem comparisons across Node, Rust, Python, and PHP, please visit the [Official Documentation Portal](https://ferrox-rust.dev/docs/nestjs-yalc/abstractions/field-middleware).
-
 ## 🚀 Installation
 
 ```bash
@@ -23,18 +16,165 @@ yarn add @nest-yalc-2/field-middleware
 pnpm add @nest-yalc-2/field-middleware
 ```
 
-## 📚 Precise Documentation
+---
+
+# GraphQL Field Middleware & Dynamic Property Transformers
+
+The `@nestjs-yalc/field-middleware` package provides fine-grained property-level access control, dynamic field encryption, value maskers, and runtime formatting transformers for GraphQL schemas and REST DTO entities.
+
+---
+
+## 1. What It Is & Architectural Purpose
+
+In GraphQL APIs and REST services, security and privacy requirements frequently demand hiding or transforming specific entity fields based on user permissions or compliance mandates (e.g., masking credit card numbers, masking email addresses for non-admins, decrypting PII data on read, or applying localized currency formatting).
+
+`@nestjs-yalc/field-middleware` injects field middleware hooks into the NestJS execution context. It allows developers to attach declarative decorators (`@FieldMiddleware(...)`, `@MaskField()`, `@EncryptField()`) directly to GraphQL ObjectType fields or class DTO properties without polluting business domain services with inline security checks.
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                        GraphQL Query / DTO                             │
+├────────────────────────────────────────────────────────────────────────┤
+│  1. Incoming Request Context (User Role: 'GUEST')                      │
+│  2. Resolving Field: 'user.email'                                      │
+└──────────────────────────────────┬─────────────────────────────────────┘
+                                   │
+                                   ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│                      YalcFieldMiddleware Engine                        │
+├────────────────────────────────────────────────────────────────────────┤
+│  Evaluate Field Decorators (@MaskField({ type: 'EMAIL' }))             │
+│  User is GUEST -> Transform 'john.doe@example.com'                     │
+│               -> Result: 'j***e@example.com'                           │
+└──────────────────────────────────┬─────────────────────────────────────┘
+                                   │
+                                   ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│                   Masked GraphQL / JSON Output                         │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. What It Does & Key Capabilities
+
+- **Declarative Field Protection**: Attach middleware rules to fields using NestJS decorators.
+- **Role-Based Property Masking**: Dynamically mask Sensitive Data (PII, SSN, Credit Cards) depending on the requestor's JWT roles/permissions.
+- **Property-Level Encryption**: Transparently decrypt AES-256 encrypted database columns during GraphQL object resolution.
+- **Computed Value Formatting**: Apply localized date, currency, or string case transformations dynamically on read operations.
+
+---
+
+## 3. How It Works Under the Hood
+
+### Execution Flow Sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as GraphQL Client
+    participant Resolver as Field Resolver
+    participant Middleware as FieldMiddleware Pipeline
+    participant Security as Auth Context Guard
+    participant Output as Transformed Value
+
+    Client->>Resolver: Query User { id, email, ssn }
+    Resolver->>Middleware: Resolve 'ssn' Field Value
+    Middleware->>Security: Inspect Request Context (User Roles)
+    alt User Has 'ADMIN' Role
+        Security-->>Middleware: Authorized
+        Middleware-->>Output: Return Unmasked SSN ("123-45-6789")
+    else User Has 'USER' / 'GUEST' Role
+        Security-->>Middleware: Unauthorized for Raw Value
+        Middleware->>Middleware: Apply SSN Mask ("***-**-6789")
+        Middleware-->>Output: Return Masked Value
+    end
+    Output-->>Client: Deliver GraphQL JSON Payload
+```
+
+---
+
+## 4. Why It Was Designed This Way
+
+| Feature | Standard Manual Field Checks | @nestjs-yalc/field-middleware |
+| :--- | :--- | :--- |
+| **Separation of Concerns** | Controllers/Services littered with `if (role === 'GUEST') mask()` logic. | Zero business service clutter; declarative `@Field()` decorators. |
+| **GraphQL Parity** | Requires writing custom GraphQL field directives by hand. | Native NestJS field middleware integration with standard context. |
+| **Consistency** | Risk of forgetting field masks in newly created API routes. | Centralized middleware pipeline guarantees compliance rules. |
+
+---
+
+## 5. Practical Usage Guide & Extended Code Examples
+
+### 5.1 Masking Sensitive PII Fields in GraphQL
+
+```typescript
+import { Field, ObjectType } from '@nestjs/graphql';
+import { MaskField, FieldMiddleware } from '@nestjs-yalc/field-middleware';
+
+@ObjectType()
+export class UserProfileType {
+  @Field()
+  id: string;
+
+  @Field()
+  @MaskField({ type: 'EMAIL', allowedRoles: ['ADMIN', 'SUPERUSER'] })
+  email: string;
+
+  @Field()
+  @MaskField({ type: 'SSN', allowedRoles: ['COMPLIANCE_OFFICER'] })
+  ssn: string;
+}
+```
+
+### 5.2 Creating Custom Field Middleware Transformers
+
+```typescript
+import { FieldMiddleware, MiddlewareContext, NextFn } from '@nestjs-yalc/field-middleware';
+
+export const CurrencyFormatterMiddleware: FieldMiddleware = async (
+  ctx: MiddlewareContext,
+  next: NextFn,
+) => {
+  const value = await next();
+  if (typeof value !== 'number') return value;
+
+  const userLocale = ctx.context.req?.headers['accept-language'] || 'en-US';
+  return new Intl.NumberFormat(userLocale, { style: 'currency', currency: 'USD' }).format(value);
+};
+```
+
+---
+
+## 6. Anti-Patterns: How NOT to Use It
+
+> [!CAUTION]
+> **Anti-Pattern 1: Performing Heavy Async I/O in Field Middleware**
+> Field middleware runs for *every resolved property instance* in a GraphQL query array. Executing database queries inside field middleware causes N+1 performance bottlenecks. Use DataLoaders for async field enrichment.
+
+---
+
+## 7. Pro-Tips & Best Practices
+
+> [!TIP]
+> **Pro-Tip 1: Combining with NestJS Guards**
+> Use Field Middleware for property-level transformation while keeping NestJS Guards responsible for overall endpoint routing access.
+
+
+---
 
-Instead of fragmented and duplicated READMEs across our 60+ NPM packages, we maintain a **centralized, highly structured documentation platform based on our 7-Layer Architecture**. 
+## 🔗 Cross-References
 
-For deep dives, API references, and full usage examples for this specific module, refer to its exact official documentation page:
+To see how this module integrates with the rest of the Ferrox architecture, refer to the following documentation:
 
-👉 **[Read the Documentation for @nest-yalc-2/field-middleware](https://ferrox-rust.dev/docs/nestjs-yalc/abstractions/field-middleware)**
+- [Authentication & Auth](https://ferrox-rust.dev/docs/nestjs-yalc/node-yalc/docs/security/auth)
+- [Database & TypeORM](https://ferrox-rust.dev/docs/nestjs-yalc/databases/database)
+- [GraphQL Transport Module](https://ferrox-rust.dev/docs/nestjs-yalc/transports/graphql)
+- [Sentinel Security Guards](https://ferrox-rust.dev/docs/nestjs-yalc/security/sentinel)
 
-## 🛡️ Security & Enterprise Support
 
-This module adheres to the Ferrox Zero-Trust security architecture. If you find any security vulnerabilities, please do NOT open a public issue. Reach out directly to the security team.
+---
+## 📚 Ecosystem Documentation
 
-## 📄 License
+This module is a core component of the Ferrox enterprise microservice architecture. 
 
-Maintained by the Ferrox Enterprise Architecture team.
+👉 **[Read the Full Documentation on Ferrox-Rust.dev](https://ferrox-rust.dev/docs/nestjs-yalc/abstractions/field-middleware)**

package/package.json

@@ -1,23 +1,23 @@
 {
-    "name": "@nest-yalc-2/field-middleware",
-    "version": "2.2.13",
-    "description": "",
-    "main": "src/index.ts",
-    "exports": {
-        ".": "./dist/src/index.js",
-        "./*": "./dist/src/*"
-    },
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "author": "Autistic_Intelligence",
-    "license": "AGPL-3.0-or-later",
-    "keywords": [
-        "nestjs",
-        "nestjs-yalc",
-        "yalc",
-        "field-middleware",
-        "framework",
-        "utility"
-    ]
-}
+  "name": "@nest-yalc-2/field-middleware",
+  "version": "2.2.15",
+  "description": "",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./*": "./dist/src/*"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Autistic_Intelligence",
+  "license": "AGPL-3.0-or-later",
+  "keywords": [
+    "nestjs",
+    "nestjs-yalc",
+    "yalc",
+    "field-middleware",
+    "framework",
+    "utility"
+  ]
+}