Privacy & Security APIs — Developer Integration Guide

Overview

The Ngwenya platform provides a comprehensive privacy and security layer spanning two subgraphs:

• nodes subgraph (NestJS/GraphQL): Cookie consent, GDPR data export, age verification
• auth subgraph (Rust/async-graphql): Session activity, security event log, account change hooks

These APIs fulfill GDPR Articles 15, 17, and 20, CCPA requirements, and general security best practices for protecting Visitor and Buyer data across the platform.

┌──────────────────────────────────────────────────────────┐
│                   Frontend (SvelteKit)                     │
│  Cookie Banner · Settings · Security Dashboard             │
└──────────────┬───────────────────────┬───────────────────┘
               │ GraphQL Federation     │ REST + GraphQL
        ┌──────▼──────┐         ┌──────▼──────┐
        │   nodes     │         │    auth      │
        │  (NestJS)   │         │   (Rust)     │
        │             │         │              │
        │ • Cookie    │  hooks  │ • Sessions   │
        │ • GDPR      │◄───────►│ • Audit Log  │
        │ • Age Gate  │         │ • Devices    │
        └─────────────┘         └──────────────┘

Cookie Consent API

Subgraph: nodes · Service: CookieConsentService · Resolver: CookieConsentResolver

GDPR and CCPA require explicit, granular consent for non-essential cookies. The platform stores consent preferences per-user with four categories:

Query — Get Current Consent

query {
	cookieConsent {
		necessary
		analytics
		marketing
		functional
		consentedAt
	}
}

Returns defaults (all optional cookies false) if no consent has been recorded.

Mutation — Granular Update

mutation {
	updateCookieConsent(input: { analytics: true, marketing: false, functional: true }) {
		necessary
		analytics
		marketing
		functional
		consentedAt
	}
}

Only provided fields are updated — omitted categories retain their current value.

Mutation — Accept All / Reject All

# Cookie banner "Accept All" button
mutation {
	acceptAllCookies {
		analytics
		marketing
		functional
		consentedAt
	}
}

# Cookie banner "Reject All" button
mutation {
	rejectAllCookies {
		analytics
		marketing
		functional
		consentedAt
	}
}

Data Model

Cookie consent is stored as a subdocument on UserPreferences in MongoDB:

class CookieConsentPreferences {
	necessary: boolean; // always true
	analytics: boolean; // default: false
	marketing: boolean; // default: false
	functional: boolean; // default: false
	consentedAt?: Date; // audit timestamp, set on every update
}

GDPR Data Export

Subgraph: nodes · Service: DataExportService · Resolver: DataExportResolver

Implements GDPR Article 20 — Right to Data Portability. Aggregates all user-owned data from the nodes service into structured JSON.

Mutation — Full Export

mutation {
	requestDataExport {
		userId
		exportedAt
		legalBasis
		sections {
			section
			source
			data
		}
	}
}

Response example:

{
	"requestDataExport": {
		"userId": "abc-123",
		"exportedAt": "2026-04-05T22:00:00.000Z",
		"legalBasis": "GDPR Article 20 — Right to Data Portability",
		"sections": [
			{
				"section": "Profile",
				"source": "nodes",
				"data": {
					"displayName": "Jane",
					"email": "jane@example.com",
					"location": "Cape Town"
				}
			},
			{
				"section": "Preferences",
				"source": "nodes",
				"data": {
					"theme": "dark",
					"cookieConsent": { "analytics": true, "marketing": false },
					"ageVerification": { "dateOfBirth": "2000-01-15" }
				}
			}
		]
	}
}

Query — Preview Available Sections

query {
	dataExportSections
}
# Returns: ["Profile", "Preferences", "Attributes", "Support Aliases"]

Exported Sections

Architecture Note

The DataExportSection pattern is designed to be extensible. Future cross-service data (Murchase history, uCart contents, community activity) can be added via TCP MessagePattern calls to other subgraphs without modifying the core resolver:

interface DataExportSection {
	section: string; // Human-readable label
	source: string; // Subgraph that owns the data
	data: Record<string, any> | Record<string, any>[];
}

Session Activity API

Subgraph: auth · Service: SessionService · Queries/Mutations: query.rs, mutation.rs

Exposes active sessions, devices, and IPs so Visitors can monitor and control where they are signed in.

Query — List Active Sessions

query {
	mySessions {
		id
		deviceName
		deviceType
		ipAddress
		userAgent
		isCurrent
		createdAt
		lastActivityAt
		expiresAt
	}
}

Mutation — Revoke Single Session

mutation {
	revokeSession(sessionId: "uuid-of-session-to-revoke")
}

Returns true on success. Cleans up both Redis (session + refresh tokens) and PostgreSQL. Logs a session_revoked audit event.

Mutation — Sign Out Everywhere

mutation {
	revokeAllSessions(keepCurrent: true) {
		revokedCount
		keptCurrent
	}
}

Logs an all_sessions_revoked audit event (severity: critical).

Security Event Log

Subgraph: auth · Service: AuditService · Model: AuditEvent

A chronological audit trail of all security-relevant actions. Events are enriched with:

• Human-readable descriptions (e.g. "Failed sign-in attempt")
• Severity levels (info, warning, critical)
• IP masking for privacy

Query — All Events

query {
	mySecurityEvents(limit: 20) {
		id
		eventType
		description
		severity
		authMethod
		success
		ipAddress
		userAgent
		errorMessage
		createdAt
	}
}

Query — Filter by Event Type

query {
	mySecurityEvents(limit: 10, eventType: "login_failed") {
		description
		severity
		ipAddress
		createdAt
	}
}

Query — Critical Events Only

query {
	myCriticalSecurityEvents(limit: 20) {
		eventType
		description
		createdAt
	}
}

Returns only events classified as critical:

Event Severity Classification

Full Event Type Reference

The system tracks 24 distinct event types:

login_success · login_failed · logout
session_refresh · session_refresh_failed · session_revoked · all_sessions_revoked
device_trusted · device_untrusted · device_revoked · device_renamed
account_deactivated · account_reactivated · account_deleted
email_changed · phone_changed · password_changed
passkey_registered · passkey_prompt_dismissed
mfa_enrolled · mfa_disabled · mfa_verify_success · mfa_verify_failed
backup_code_used

Account Change Hooks

Sender: auth (Rust) · Receiver: nodes (NestJS)

When a Visitor changes their email or phone in the auth subgraph, a fire-and-forget webhook notifies the nodes subgraph to sync the profile data.

Architecture

                  ┌────────────────┐
                  │  auth (Rust)    │
                  │  contact.rs     │
                  └───────┬────────┘
                          │ POST /hooks/account-change
                          │ Authorization: Bearer <INTERNAL_WEBHOOK_SECRET>
                  ┌───────▼────────┐
                  │  nodes (NestJS) │
                  │  HookController │
                  └────────────────┘

Webhook Payload

{
	"userId": "uuid",
	"field": "email",
	"value": "new@example.com"
}

Valid field values: "email" or "phone".

Security

The webhook is authenticated with a shared secret (INTERNAL_WEBHOOK_SECRET). The nodes service validates this header before processing updates.

Environment Variables

Age Verification

Subgraph: nodes · Model: AgeVerification on UserPreferences

Basic self-declared date-of-birth age gating for age-restricted Malet verticals (e.g. alcohol, tobacco).

Mutation — Submit DOB

mutation {
	submitDateOfBirth(dateOfBirth: "2000-01-15") {
		verificationStatus
		verificationMethod
		verifiedAt
	}
}

Query — Check Eligibility

query {
	checkAgeEligibility(minimumAge: 18)
}
# Returns: true or false

Content Visibility Matrix

Subgraph: nodes · Resolver: ContentVisibilityResolver · DTO: PrivacyPreferences

Controls how a Visitor's identity appears on community content — reviews, blog comments, and "Helpful" votes. Users choose between three levels:

Mutation — Update Content Visibility

mutation {
	updatePrivacySettings(input: { contentVisibility: ANONYMOUS }) {
		id
		contentVisibilityStatus
		contentDisplayName
		contentAvatarUrl
	}
}

The mutation accepts any PrivacyPreferencesInput field, but for content visibility, only contentVisibility is relevant. The response includes the resolved display name and avatar, which the frontend uses for the live preview.

Query — Get Current Setting

query {
	me {
		id
		displayName
		avatarUrl
		contentVisibilityStatus
		contentDisplayName
		contentAvatarUrl
	}
}

Resolved Fields

The ContentVisibilityResolver computes three read-only fields on the User type:

These fields are the canonical source of author identity across the federation. Other subgraphs (community, blogs) automatically receive these values when resolving a User reference.

Architecture

┌──────────────────────────────────────────────────────┐
│              Frontend (SvelteKit)                     │
│  Settings → Privacy → ContentVisibilitySection       │
│  ┌──────────────────────────────────────────────┐    │
│  │  [Full Name] [First Name] [Anonymous]         │    │
│  │  ────────── Live Preview ──────────           │    │
│  │  👤 Jane D. · left a review · 2 days ago      │    │
│  └──────────────────────────────────────────────┘    │
└──────────────┬───────────────────────────────────────┘
               │ updatePrivacySettings mutation
        ┌──────▼──────┐
        │   nodes     │
        │  (NestJS)   │
        │             │
        │ ContentVisibilityResolver  ←── computes display fields
        │ UserMutationResolver       ←── updatePrivacySettings
        │ PrivacyPreferences.contentVisibility (MongoDB)
        └─────────────┘

Frontend Integration

The feature is implemented in the Settings → Privacy & Security section:

Data Model

Content visibility is stored as a field on PrivacyPreferences in MongoDB:

class PrivacyPreferences {
	profileVisibility: VisibilityPrivacy;  // PUBLIC | PRIVATE
	whoCanMessage: MessagePrivacy;         // EVERYONE | FRIENDS | NOONE
	whoCanConnect: ConnectionPrivacy;      // EVERYONE | MUTUALS_ONLY
	showFollowing: VisibilityPrivacy;
	showFavorites: VisibilityPrivacy;
	contentVisibility: ContentVisibility;  // FULL_NAME | FIRST_NAME_ONLY | ANONYMOUS ← NEW
}

File Reference

nodes subgraph

auth subgraph

Related

• MFA & Passkeys — TOTP, SMS 2FA, and WebAuthn passkey registration/authentication

• Settings Architecture — Frontend settings UI for privacy, security, and session management

• User Listing API (Admin) — Admin-only user management with privacy bypass

• E2E Testing Infrastructure — Auth mocking and cookie consent bypass patterns

• IndexedDB Storage Layer — Client-side data persistence and GDPR data export considerations

• Wishlists & Collections — Private client-side wishlist data architecture

• uChat Client SDK — E2EE messaging and content visibility integration

• User Identity Resolution — Shared profileResolver.ts that replaces raw UUIDs with handles or display names across all UI surfaces

• Support Ticket Anonymity — Pseudo-anonymous alias system protecting Visitor identity in Malet support interactions

• uChat Online Presence — Architecture and privacy considerations for real-time presence indicators.