feat: add masking

Signed-off-by: Hung-Han (Henry) Chen <[email protected]>

src/resources/(groups)/[groupId]/index.ts

@@ -3,6 +3,7 @@ import { headers } from "xmcp/headers";
 import { z } from "zod";
 import { getScimBaseUrl } from "../../../utils/getSCIMBaseUrl";
 import { getScimToken } from "../../../utils/getSCIMToken";
+import { maskPII, PII_FIELDS } from "../../../utils/piiMasking";
 
 export const schema = {
   groupId: z.string().describe("The ID of the group"),
@@ -18,6 +19,13 @@ export const schema = {
     .describe(
       "Comma-separated list of attribute names to exclude from the response. Per RFC 7644 Section 3.9"
     ),
+  piiMasking: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Enable PII masking for sensitive fields including member information (display names, references). When true, values are partially masked while maintaining readability. Default: true"
+    ),
 };
 
 export const metadata: ResourceMetadata = {
@@ -30,6 +38,7 @@ export default async function handler({
   groupId,
   attributes,
   excludedAttributes,
+  piiMasking = true,
 }: InferSchema<typeof schema>) {
   const requestHeaders = headers();
   const apiToken = getScimToken(requestHeaders);
@@ -65,7 +74,12 @@ export default async function handler({
     throw new Error(await response.text());
   }
 
-  const data = await response.json();
+  let data = await response.json();
+
+  // Apply PII masking if enabled
+  if (piiMasking) {
+    data = maskPII(data, PII_FIELDS);
+  }
 
   return {
     contents: [

src/resources/(groups)/index.ts

@@ -3,6 +3,7 @@ import { headers } from "xmcp/headers";
 import { z } from "zod";
 import { getScimBaseUrl } from "../../utils/getSCIMBaseUrl";
 import { getScimToken } from "../../utils/getSCIMToken";
+import { maskPII, PII_FIELDS } from "../../utils/piiMasking";
 
 export const schema = {
   filter: z
@@ -23,6 +24,13 @@ export const schema = {
     .describe(
       "Non-negative integer. Specifies the desired maximum number of query results per page."
     ),
+  piiMasking: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Enable PII masking for sensitive fields including member information (username, emails, phone numbers, display names). When true, values are partially masked while maintaining readability. Default: true"
+    ),
 };
 
 export const metadata: ResourceMetadata = {
@@ -35,6 +43,7 @@ export default async function handler({
   filter,
   startIndex,
   count,
+  piiMasking = true,
 }: InferSchema<typeof schema>) {
   const requestHeaders = headers();
   const apiToken = getScimToken(requestHeaders);
@@ -71,7 +80,12 @@ export default async function handler({
     throw new Error(await response.text());
   }
 
-  const data = await response.json();
+  let data = await response.json();
+
+  // Apply PII masking if enabled
+  if (piiMasking) {
+    data = maskPII(data, PII_FIELDS);
+  }
 
   return {
     contents: [

src/resources/(users)/[userId]/index.ts

@@ -3,6 +3,7 @@ import { headers } from "xmcp/headers";
 import { z } from "zod";
 import { getScimBaseUrl } from "../../../utils/getSCIMBaseUrl";
 import { getScimToken } from "../../../utils/getSCIMToken";
+import { maskPII, PII_FIELDS } from "../../../utils/piiMasking";
 
 export const schema = {
   userId: z.string().describe("The ID of the user"),
@@ -18,6 +19,13 @@ export const schema = {
     .describe(
       "Comma-separated list of attribute names to exclude from the response. Per RFC 7644 Section 3.9"
     ),
+  piiMasking: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Enable PII masking for sensitive fields (username, emails, phone numbers, addresses). When true, values are partially masked while maintaining readability. Default: true"
+    ),
 };
 
 export const metadata: ResourceMetadata = {
@@ -30,6 +38,7 @@ export default async function handler({
   userId,
   attributes,
   excludedAttributes,
+  piiMasking = true,
 }: InferSchema<typeof schema>) {
   const requestHeaders = headers();
   const apiToken = getScimToken(requestHeaders);
@@ -65,7 +74,12 @@ export default async function handler({
     throw new Error(await response.text());
   }
 
-  const data = await response.json();
+  let data = await response.json();
+
+  // Apply PII masking if enabled
+  if (piiMasking) {
+    data = maskPII(data, PII_FIELDS);
+  }
 
   return {
     contents: [

src/resources/(users)/index.ts

@@ -3,6 +3,7 @@ import { headers } from "xmcp/headers";
 import { z } from "zod";
 import { getScimBaseUrl } from "../../utils/getSCIMBaseUrl";
 import { getScimToken } from "../../utils/getSCIMToken";
+import { maskPII, PII_FIELDS } from "../../utils/piiMasking";
 
 export const schema = {
   filter: z
@@ -23,6 +24,13 @@ export const schema = {
     .describe(
       "Non-negative integer. Specifies the desired maximum number of query results per page."
     ),
+  piiMasking: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Enable PII masking for sensitive fields (username, emails, phone numbers, addresses). When true, values are partially masked while maintaining readability. Also know as privacy mode. Default: true"
+    ),
 };
 
 export const metadata: ResourceMetadata = {
@@ -35,6 +43,7 @@ export default async function handler({
   filter,
   startIndex,
   count,
+  piiMasking = true,
 }: InferSchema<typeof schema>) {
   const requestHeaders = headers();
   const apiToken = getScimToken(requestHeaders);
@@ -71,7 +80,12 @@ export default async function handler({
     throw new Error(await response.text());
   }
 
-  const data = await response.json();
+  let data = await response.json();
+
+  // Apply PII masking if enabled
+  if (piiMasking) {
+    data = maskPII(data, PII_FIELDS);
+  }
 
   return {
     contents: [

src/utils/piiMasking.ts

@@ -0,0 +1,91 @@
+export function maskEmail(email: string): string {
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return email;
+  
+  const visibleChars = Math.min(2, Math.floor(local.length * 0.3));
+  const masked = local.substring(0, visibleChars) + "******";
+  return `${masked}@${domain}`;
+}
+
+export function maskPhoneNumber(phone: string): string {
+  // Keep country code and last 2 digits visible
+  const digits = phone.replace(/\D/g, "");
+  if (digits.length < 4) return "***";
+  
+  const lastTwo = digits.slice(-2);
+  const prefix = digits.length > 10 ? digits.substring(0, 2) : "";
+  return prefix ? `+${prefix}******${lastTwo}` : `******${lastTwo}`;
+}
+
+export function maskString(value: string): string {
+  if (value.length <= 2) return "***";
+  
+  const visibleChars = Math.min(2, Math.floor(value.length * 0.3));
+  const masked = value.substring(0, visibleChars) + "******";
+  return masked;
+}
+
+export function maskPII(obj: any, piiFields: Set<string>): any {
+  if (obj === null || obj === undefined) return obj;
+  
+  if (Array.isArray(obj)) {
+    return obj.map(item => maskPII(item, piiFields));
+  }
+  
+  if (typeof obj === "object") {
+    const masked: any = {};
+    
+    for (const [key, value] of Object.entries(obj)) {
+      const lowerKey = key.toLowerCase();
+      
+      // Check if this field contains PII
+      if (piiFields.has(lowerKey)) {
+        if (typeof value === "string") {
+          if (lowerKey.includes("email") || key === "value" && obj.type === "email") {
+            masked[key] = maskEmail(value);
+          } else if (lowerKey.includes("phone") || lowerKey.includes("mobile") || 
+                     key === "value" && (obj.type === "phone" || obj.type === "mobile")) {
+            masked[key] = maskPhoneNumber(value);
+          } else {
+            masked[key] = maskString(value);
+          }
+        } else if (value !== null && typeof value === "object") {
+          // Recursively mask nested objects
+          masked[key] = maskPII(value, piiFields);
+        } else {
+          masked[key] = value;
+        }
+      } else if (value !== null && typeof value === "object") {
+        // Recursively process nested objects even for non-PII fields
+        masked[key] = maskPII(value, piiFields);
+      } else {
+        masked[key] = value;
+      }
+    }
+    
+    return masked;
+  }
+  
+  return obj;
+}
+
+export const PII_FIELDS = new Set([
+  "username",
+  "email",
+  "emails",
+  "displayname",
+  "phonenumber",
+  "phonenumbers",
+  "phone",
+  "mobile",
+  "streetaddress",
+  "locality",
+  "region",
+  "postalcode",
+  "address",
+  "addresses",
+  "givenname",
+  "familyname",
+  "middlename",
+  "formatted", // formatted name/address
+]);