@wildo-ai/saas-backend-lib 1.0.1

package/src/security/scim/models/scim-protocol.backend.schemas.ts

@@ -0,0 +1,258 @@
+/**
+ * SCIM Protocol Schemas — Step 20
+ * 
+ * SCIM 2.0 types, attribute mapping, and protocol constants for directory provisioning.
+ * 
+ * Decision 13: Lean SCIM — Users only in v1, no Groups, no generic adapter.
+ * SCIM_USER_ATTRIBUTE_MAP maps SCIM attributes → NormalizedUserProfile fields
+ * (the same type used by SSO JIT provisioning in Step 4/15).
+ *
+ * Token schema has moved to @wildo-ai/saas-models (scimTokensPolymorphicDeclaration).
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM User Attribute Mapping
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Maps SCIM User resource attribute paths to NormalizedUserProfile fields.
+ * Hardcoded for v1 — only the SCIM User resource is supported.
+ * 
+ * FUTURE: If SCIM Groups or custom resources are needed, extract this into a
+ * generic SCIMResourceMappingRegistry. See Decision 13 for the architecture.
+ */
+export const SCIM_USER_ATTRIBUTE_MAP = {
+  'userName':        'email',
+  'name.givenName':  'firstName',
+  'name.familyName': 'lastName',
+  'displayName':     'displayName',
+  'active':          '_active',        // computed: maps to user status (active/inactive)
+  'externalId':      'providerUserId',
+} as const;
+
+/**
+ * Reverse map: NormalizedUserProfile field → SCIM attribute path.
+ * Used by the response formatter to build SCIM User resources from internal data.
+ */
+export const PROFILE_TO_SCIM_ATTRIBUTE_MAP: Record<string, string> = Object.fromEntries(
+  Object.entries(SCIM_USER_ATTRIBUTE_MAP).map(([scim, profile]) => [profile, scim])
+);
+
+/**
+ * FUTURE: SCIM Groups → Organization Roles
+ * SCIM Groups map to role assignments, not departments.
+ * Example: Okta group "Wildo Admins" → ADMIN role.
+ * Implementation: add /scim/v2/Groups endpoints with:
+ *   - POST/PUT/PATCH /Groups → create/update org roles
+ *   - Group membership changes → OrganizationMember role updates
+ *   - Group displayName → role identifier mapping (configurable per org)
+ *
+ * FUTURE: SCIM User department → OrganizationUnit
+ * The SCIM Enterprise User extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User)
+ * carries department, division, manager fields.
+ * Implementation: map these to OrganizationUnit assignments.
+ * Requires OrganizationUnit infrastructure to be in place first.
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM Protocol Constants
+// ═══════════════════════════════════════════════════════════════
+
+export const SCIM_SCHEMAS = {
+  USER: 'urn:ietf:params:scim:schemas:core:2.0:User',
+  ENTERPRISE_USER: 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User',
+  LIST_RESPONSE: 'urn:ietf:params:scim:api:messages:2.0:ListResponse',
+  ERROR: 'urn:ietf:params:scim:api:messages:2.0:Error',
+  PATCH_OP: 'urn:ietf:params:scim:api:messages:2.0:PatchOp',
+  BULK_REQUEST: 'urn:ietf:params:scim:api:messages:2.0:BulkRequest',
+  BULK_RESPONSE: 'urn:ietf:params:scim:api:messages:2.0:BulkResponse',
+  SERVICE_PROVIDER_CONFIG: 'urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig',
+  RESOURCE_TYPE: 'urn:ietf:params:scim:schemas:core:2.0:ResourceType',
+  SCHEMA: 'urn:ietf:params:scim:schemas:core:2.0:Schema',
+} as const;
+
+export const SCIM_CONTENT_TYPE = 'application/scim+json';
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM Error Types (RFC 7644 §3.12)
+// ═══════════════════════════════════════════════════════════════
+
+export type SCIMErrorType =
+  | 'invalidFilter'
+  | 'tooMany'
+  | 'uniqueness'
+  | 'mutability'
+  | 'invalidSyntax'
+  | 'invalidPath'
+  | 'noTarget'
+  | 'invalidValue'
+  | 'invalidVers'
+  | 'sensitive';
+
+export interface SCIMErrorResponse {
+  schemas: [typeof SCIM_SCHEMAS.ERROR];
+  status: string;
+  detail: string;
+  scimType?: SCIMErrorType;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM PATCH Operation Types (RFC 7644 §3.5.2)
+// ═══════════════════════════════════════════════════════════════
+
+export interface SCIMPatchOperation {
+  op: 'add' | 'remove' | 'replace';
+  path?: string;
+  value?: unknown;
+}
+
+export interface SCIMPatchRequest {
+  schemas: string[];
+  Operations: SCIMPatchOperation[];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM Bulk Operation Types (RFC 7644 §3.7)
+// ═══════════════════════════════════════════════════════════════
+
+export interface SCIMBulkOperation {
+  method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  bulkId?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface SCIMBulkRequest {
+  schemas: [typeof SCIM_SCHEMAS.BULK_REQUEST];
+  Operations: SCIMBulkOperation[];
+  failOnErrors?: number;
+}
+
+export interface SCIMBulkOperationResponse {
+  method: string;
+  bulkId?: string;
+  location?: string;
+  status: string;
+  response?: SCIMErrorResponse;
+}
+
+export interface SCIMBulkResponse {
+  schemas: [typeof SCIM_SCHEMAS.BULK_RESPONSE];
+  Operations: SCIMBulkOperationResponse[];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM User Resource Type (RFC 7643 §4.1)
+// ═══════════════════════════════════════════════════════════════
+
+export interface SCIMUserResource {
+  schemas: string[];
+  id: string;
+  externalId?: string;
+  userName: string;
+  name?: {
+    formatted?: string;
+    familyName?: string;
+    givenName?: string;
+  };
+  displayName?: string;
+  active: boolean;
+  emails?: Array<{
+    value: string;
+    type?: string;
+    primary?: boolean;
+  }>;
+  meta: {
+    resourceType: 'User';
+    created: string;
+    lastModified: string;
+    location: string;
+  };
+}
+
+export interface SCIMListResponse<T = SCIMUserResource> {
+  schemas: [typeof SCIM_SCHEMAS.LIST_RESPONSE];
+  totalResults: number;
+  startIndex: number;
+  itemsPerPage: number;
+  Resources: T[];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM ServiceProviderConfig (RFC 7643 §5)
+// ═══════════════════════════════════════════════════════════════
+
+export const SCIM_SERVICE_PROVIDER_CONFIG = {
+  schemas: [SCIM_SCHEMAS.SERVICE_PROVIDER_CONFIG],
+  documentationUri: 'https://docs.wildo.ai/scim',
+  patch: { supported: true },
+  bulk: { supported: true, maxOperations: 100, maxPayloadSize: 1048576 },
+  filter: { supported: true, maxResults: 200 },
+  changePassword: { supported: false },
+  sort: { supported: false },
+  etag: { supported: false },
+  authenticationSchemes: [{
+    type: 'oauthbearertoken',
+    name: 'OAuth Bearer Token',
+    description: 'Authentication scheme using the OAuth Bearer Token Standard',
+    specUri: 'https://www.rfc-editor.org/info/rfc6750',
+    documentationUri: 'https://docs.wildo.ai/scim/auth',
+    primary: true,
+  }],
+  meta: {
+    resourceType: 'ServiceProviderConfig',
+    location: '/scim/v2/ServiceProviderConfig',
+  },
+} as const;
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM User Schema Definition (RFC 7643 §7)
+// ═══════════════════════════════════════════════════════════════
+
+export const SCIM_USER_SCHEMA_DEFINITION = {
+  schemas: [SCIM_SCHEMAS.SCHEMA],
+  id: SCIM_SCHEMAS.USER,
+  name: 'User',
+  description: 'User Account',
+  attributes: [
+    { name: 'userName', type: 'string', multiValued: false, required: true, caseExact: false, mutability: 'readWrite', returned: 'default', uniqueness: 'server' },
+    { name: 'name', type: 'complex', multiValued: false, required: false, mutability: 'readWrite', returned: 'default', subAttributes: [
+      { name: 'givenName', type: 'string', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+      { name: 'familyName', type: 'string', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+      { name: 'formatted', type: 'string', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+    ]},
+    { name: 'displayName', type: 'string', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+    { name: 'active', type: 'boolean', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+    { name: 'emails', type: 'complex', multiValued: true, required: false, mutability: 'readWrite', returned: 'default', subAttributes: [
+      { name: 'value', type: 'string', multiValued: false, required: true },
+      { name: 'type', type: 'string', multiValued: false, required: false },
+      { name: 'primary', type: 'boolean', multiValued: false, required: false },
+    ]},
+    { name: 'externalId', type: 'string', multiValued: false, required: false, mutability: 'readWrite', returned: 'default' },
+  ],
+  meta: {
+    resourceType: 'Schema',
+    location: `/scim/v2/Schemas/${SCIM_SCHEMAS.USER}`,
+  },
+} as const;
+
+// ═══════════════════════════════════════════════════════════════
+// SCIM Resource Types Definition (RFC 7644 §4)
+// ═══════════════════════════════════════════════════════════════
+
+export const SCIM_RESOURCE_TYPES = [{
+  schemas: [SCIM_SCHEMAS.RESOURCE_TYPE],
+  id: 'User',
+  name: 'User',
+  endpoint: '/Users',
+  description: 'User Account',
+  schema: SCIM_SCHEMAS.USER,
+  schemaExtensions: [{
+    schema: SCIM_SCHEMAS.ENTERPRISE_USER,
+    required: false,
+  }],
+  meta: {
+    resourceType: 'ResourceType',
+    location: '/scim/v2/ResourceTypes/User',
+  },
+}] as const;

package/src/security/scim/utils/scim-filter-parser.ts

@@ -0,0 +1,289 @@
+/**
+ * SCIM Filter Parser — Step 20
+ * 
+ * Parses SCIM 2.0 filter expressions (RFC 7644 §3.4.2.2) and translates them
+ * into MongoDB-compatible query filters using the SCIM attribute map.
+ * 
+ * Supports: eq, ne, co (contains), sw (starts with), ew (ends with), pr (present),
+ *           gt, ge, lt, le, and, or, not
+ * Does NOT support: complex multi-valued attribute sub-filters (these require SCIM 2.0 conformance suite — Step 21)
+ */
+
+import { SCIM_USER_ATTRIBUTE_MAP } from '~wildo-backend-lib/security/scim/models/scim-protocol.backend.schemas';
+
+export interface SCIMFilterNode {
+  type: 'comparison' | 'logical';
+  operator?: string;
+  attribute?: string;
+  value?: string;
+  logicalOp?: 'and' | 'or' | 'not';
+  children?: SCIMFilterNode[];
+}
+
+export interface MongoQueryFilter {
+  [key: string]: unknown;
+}
+
+/**
+ * Parse a SCIM filter expression and translate it to a MongoDB-compatible query filter.
+ * 
+ * Examples:
+ *   parseSCIMFilter('userName eq "john@acme.com"') → { email: "john@acme.com" }
+ *   parseSCIMFilter('active eq true') → special handling for user status
+ *   parseSCIMFilter('name.familyName co "Smith"') → { lastName: { $regex: "Smith", $options: "i" } }
+ *   parseSCIMFilter('userName sw "john" and active eq true') → { $and: [...] }
+ * 
+ * @param filter - SCIM filter expression string
+ * @param attributeMap - Optional custom attribute map (defaults to SCIM_USER_ATTRIBUTE_MAP)
+ */
+export function parseSCIMFilter(
+  filter: string | undefined,
+  attributeMap: Record<string, string> = SCIM_USER_ATTRIBUTE_MAP as unknown as Record<string, string>,
+): MongoQueryFilter {
+  if (!filter || filter.trim().length === 0) {
+    return {};
+  }
+
+  const trimmed = filter.trim();
+  const ast = _parseExpression(trimmed);
+  return _astToMongoFilter(ast, attributeMap);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Tokenizer
+// ═══════════════════════════════════════════════════════════════
+
+interface Token {
+  type: 'attribute' | 'operator' | 'value' | 'logical' | 'lparen' | 'rparen';
+  value: string;
+}
+
+const SCIM_OPERATORS = new Set(['eq', 'ne', 'co', 'sw', 'ew', 'gt', 'ge', 'lt', 'le', 'pr']);
+const LOGICAL_OPERATORS = new Set(['and', 'or', 'not']);
+
+function _tokenize(input: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+
+  while (i < input.length) {
+    // Skip whitespace
+    if (input[i] === ' ' || input[i] === '\t') {
+      i++;
+      continue;
+    }
+
+    // Parentheses
+    if (input[i] === '(') {
+      tokens.push({ type: 'lparen', value: '(' });
+      i++;
+      continue;
+    }
+    if (input[i] === ')') {
+      tokens.push({ type: 'rparen', value: ')' });
+      i++;
+      continue;
+    }
+
+    // Quoted string value
+    if (input[i] === '"') {
+      i++;
+      let value = '';
+      while (i < input.length && input[i] !== '"') {
+        if (input[i] === '\\' && i + 1 < input.length) {
+          value += input[i + 1];
+          i += 2;
+        } else {
+          value += input[i];
+          i++;
+        }
+      }
+      i++; // skip closing quote
+      tokens.push({ type: 'value', value });
+      continue;
+    }
+
+    // Words: attribute names, operators, logical operators, unquoted values
+    let word = '';
+    while (i < input.length && input[i] !== ' ' && input[i] !== '\t' && input[i] !== '(' && input[i] !== ')' && input[i] !== '"') {
+      word += input[i];
+      i++;
+    }
+
+    if (word.length === 0) continue;
+
+    const lowerWord = word.toLowerCase();
+    if (SCIM_OPERATORS.has(lowerWord)) {
+      tokens.push({ type: 'operator', value: lowerWord });
+    } else if (LOGICAL_OPERATORS.has(lowerWord)) {
+      tokens.push({ type: 'logical', value: lowerWord });
+    } else if (lowerWord === 'true' || lowerWord === 'false' || lowerWord === 'null') {
+      tokens.push({ type: 'value', value: lowerWord });
+    } else {
+      // Check if it looks like an attribute path (contains dots or is a known attribute)
+      tokens.push({ type: 'attribute', value: word });
+    }
+  }
+
+  return tokens;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Parser (recursive descent)
+// ═══════════════════════════════════════════════════════════════
+
+function _parseExpression(input: string): SCIMFilterNode {
+  const tokens = _tokenize(input);
+  let pos = 0;
+
+  function parseOr(): SCIMFilterNode {
+    let left = parseAnd();
+    while (pos < tokens.length && tokens[pos]?.type === 'logical' && tokens[pos]?.value === 'or') {
+      pos++; // skip 'or'
+      const right = parseAnd();
+      left = { type: 'logical', logicalOp: 'or', children: [left, right] };
+    }
+    return left;
+  }
+
+  function parseAnd(): SCIMFilterNode {
+    let left = parsePrimary();
+    while (pos < tokens.length && tokens[pos]?.type === 'logical' && tokens[pos]?.value === 'and') {
+      pos++; // skip 'and'
+      const right = parsePrimary();
+      left = { type: 'logical', logicalOp: 'and', children: [left, right] };
+    }
+    return left;
+  }
+
+  function parsePrimary(): SCIMFilterNode {
+    // `not` prefix: RFC 7644 §3.4.2.2 — `not (expression)`
+    if (pos < tokens.length && tokens[pos]?.type === 'logical' && tokens[pos]?.value === 'not') {
+      pos++; // skip 'not'
+      const inner = parsePrimary();
+      return { type: 'logical', logicalOp: 'not', children: [inner] };
+    }
+
+    if (pos < tokens.length && tokens[pos]?.type === 'lparen') {
+      pos++; // skip '('
+      const node = parseOr();
+      if (pos < tokens.length && tokens[pos]?.type === 'rparen') {
+        pos++; // skip ')'
+      }
+      return node;
+    }
+
+    // Comparison: attribute operator [value]
+    const attributeToken = tokens[pos];
+    if (!attributeToken || attributeToken.type !== 'attribute') {
+      return { type: 'comparison', attribute: '', operator: 'eq', value: '' };
+    }
+    pos++;
+
+    const operatorToken = tokens[pos];
+    if (!operatorToken || operatorToken.type !== 'operator') {
+      return { type: 'comparison', attribute: attributeToken.value, operator: 'eq', value: '' };
+    }
+    pos++;
+
+    // 'pr' (present) operator has no value
+    if (operatorToken.value === 'pr') {
+      return { type: 'comparison', attribute: attributeToken.value, operator: 'pr' };
+    }
+
+    const valueToken = tokens[pos];
+    const value = valueToken ? valueToken.value : '';
+    if (valueToken) pos++;
+
+    return { type: 'comparison', attribute: attributeToken.value, operator: operatorToken.value, value };
+  }
+
+  return parseOr();
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AST to MongoDB Filter
+// ═══════════════════════════════════════════════════════════════
+
+function _astToMongoFilter(node: SCIMFilterNode, attributeMap: Record<string, string>): MongoQueryFilter {
+  if (node.type === 'logical' && node.children) {
+    if (node.logicalOp === 'not') {
+      return { $nor: [_astToMongoFilter(node.children[0]!, attributeMap)] };
+    }
+    const childFilters = node.children.map(c => _astToMongoFilter(c, attributeMap));
+    if (node.logicalOp === 'or') {
+      return { $or: childFilters };
+    }
+    return { $and: childFilters };
+  }
+
+  // Comparison node
+  const scimAttr = node.attribute || '';
+  const dbField = attributeMap[scimAttr] || scimAttr;
+  const op = node.operator || 'eq';
+  const rawValue = node.value;
+
+  // Special handling for 'active' attribute → maps to user status field
+  if (dbField === '_active') {
+    const isActive = rawValue === 'true';
+    if (op === 'eq') {
+      return { status: isActive ? 'active' : 'inactive' };
+    }
+    if (op === 'ne') {
+      return { status: isActive ? 'inactive' : 'active' };
+    }
+    return {};
+  }
+
+  // Parse value type
+  const parsedValue = _parseValue(rawValue);
+
+  switch (op) {
+    case 'eq':
+      if (typeof parsedValue === 'string') {
+        // Case-insensitive exact match for strings (SCIM spec: userName is case-insensitive)
+        return { [dbField]: { $regex: `^${_escapeRegex(parsedValue)}$`, $options: 'i' } };
+      }
+      return { [dbField]: parsedValue };
+
+    case 'ne':
+      return { [dbField]: { $ne: parsedValue } };
+
+    case 'co':
+      return { [dbField]: { $regex: _escapeRegex(String(parsedValue)), $options: 'i' } };
+
+    case 'sw':
+      return { [dbField]: { $regex: `^${_escapeRegex(String(parsedValue))}`, $options: 'i' } };
+
+    case 'ew':
+      return { [dbField]: { $regex: `${_escapeRegex(String(parsedValue))}$`, $options: 'i' } };
+
+    case 'pr':
+      return { [dbField]: { $exists: true, $ne: null } };
+
+    case 'gt':
+      return { [dbField]: { $gt: parsedValue } };
+
+    case 'ge':
+      return { [dbField]: { $gte: parsedValue } };
+
+    case 'lt':
+      return { [dbField]: { $lt: parsedValue } };
+
+    case 'le':
+      return { [dbField]: { $lte: parsedValue } };
+
+    default:
+      return {};
+  }
+}
+
+function _parseValue(raw: string | undefined): string | boolean | null {
+  if (raw === undefined || raw === 'null') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}
+
+function _escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/security/scim/utils/scim-response-formatter.ts

@@ -0,0 +1,122 @@
+/**
+ * SCIM Response Formatter — Step 20
+ * 
+ * Formats internal user data as SCIM 2.0 compliant responses.
+ * Wraps users in the SCIM User schema envelope with proper metadata.
+ */
+
+import { type User, UserStatus } from '@wildo-ai/saas-models';
+import {
+  SCIM_SCHEMAS,
+  type SCIMUserResource,
+  type SCIMListResponse,
+  type SCIMErrorResponse,
+  type SCIMErrorType,
+} from '~wildo-backend-lib/security/scim/models/scim-protocol.backend.schemas';
+
+interface UserProfile {
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  avatarUrl?: string;
+}
+
+/**
+ * Format a single user as a SCIM 2.0 User resource.
+ * 
+ * @param user - The internal User object
+ * @param profile - The user's profile (firstName, lastName, etc.)
+ * @param baseUrl - Base URL for SCIM resource locations (e.g., "https://api.wildo.ai/scim/v2")
+ * @param externalId - Optional external ID from the IdP
+ */
+export function formatUserAsSCIM(
+  user: User,
+  profile: UserProfile | null,
+  baseUrl: string,
+  externalId?: string,
+): SCIMUserResource {
+  const isActive = user.status === UserStatus.ACTIVE;
+  const createdAt = (user as Record<string, unknown>).createdAt;
+  const updatedAt = (user as Record<string, unknown>).updatedAt;
+
+  return {
+    schemas: [SCIM_SCHEMAS.USER],
+    id: user._id,
+    externalId: externalId || undefined,
+    userName: user.email,
+    name: {
+      givenName: profile?.firstName || undefined,
+      familyName: profile?.lastName || undefined,
+      formatted: _formatFullName(profile?.firstName, profile?.lastName),
+    },
+    displayName: profile?.displayName || _formatFullName(profile?.firstName, profile?.lastName) || user.email,
+    active: isActive,
+    emails: [{
+      value: user.email,
+      type: 'work',
+      primary: true,
+    }],
+    meta: {
+      resourceType: 'User',
+      created: _toISO(createdAt),
+      lastModified: _toISO(updatedAt),
+      location: `${baseUrl}/Users/${user._id}`,
+    },
+  };
+}
+
+/**
+ * Format a list of users as a SCIM 2.0 ListResponse.
+ * 
+ * @param users - Array of { user, profile, externalId } objects
+ * @param totalCount - Total number of matching users (for pagination)
+ * @param startIndex - 1-based start index for pagination
+ * @param baseUrl - Base URL for SCIM resource locations
+ */
+export function formatListAsSCIM(
+  users: Array<{ user: User; profile: UserProfile | null; externalId?: string }>,
+  totalCount: number,
+  startIndex: number,
+  baseUrl: string,
+): SCIMListResponse {
+  return {
+    schemas: [SCIM_SCHEMAS.LIST_RESPONSE],
+    totalResults: totalCount,
+    startIndex: startIndex,
+    itemsPerPage: users.length,
+    Resources: users.map(({ user, profile, externalId }) =>
+      formatUserAsSCIM(user, profile, baseUrl, externalId)
+    ),
+  };
+}
+
+/**
+ * Format a SCIM 2.0 error response.
+ */
+export function formatSCIMError(
+  status: number,
+  detail: string,
+  scimType?: SCIMErrorType,
+): SCIMErrorResponse {
+  return {
+    schemas: [SCIM_SCHEMAS.ERROR],
+    status: String(status),
+    detail,
+    scimType,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════
+
+function _formatFullName(firstName?: string, lastName?: string): string | undefined {
+  if (firstName && lastName) return `${firstName} ${lastName}`;
+  return firstName || lastName || undefined;
+}
+
+function _toISO(value: unknown): string {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  return new Date().toISOString();
+}