Skip to main content

Identity Graph

The identity graph turns anonymous visitor sessions into resolved, enriched people — the backbone of leads, cross-session context, and CRM sync. It lives primarily in backend, with ms-ai consuming it (via a gRPC client) for AI context.

The model​

EntityMeaning
UserSessionModelone raw visitor session (device, fingerprint, IPs, URLs)
PersonModela resolved distinct visitor (may span many sessions/devices)
PersonProfileModelenriched identity for a Person (name, email, company, B2B data)
PersonIpSignalModelIP→person signals used for IP-assisted resolution

Person is the identity; PersonProfile is what we know about them. A session resolves to a Person; multiple sessions/devices can collapse into one Person as evidence accumulates.

The resolution chain​

Wired in backend/app/hooks.js boot() as an ordered subsystem:

IdentityGraphRenderer → IdentityGraphConfig → SubscriptionGate
→ IdentityGraph → Verifier → PersonResolver → PersonWatch
  • IdentityGraphConfig — per-company verification policy (permissive/moderate/strict/regulated) controlling how aggressively sessions are merged.
  • SubscriptionGate — gates identity features by plan.
  • Verifier — applies the policy to candidate matches.
  • PersonResolver — the core resolution: match a session to an existing Person or create a new one, using fingerprint, IP signals, and form captures.
  • PersonWatch — drives the Nox "visitor watch" / auto-engage-on-return behavior.

Trust model (post-overhaul, 2026-07)​

user_sessions.identity_trust is anonymous | claimed | verified. Provenance is enforced by source-set helpers in PersonResolverService.js, not a constants file:

  • _isHighTrustSource() — form, crm, inbound_call, booking, chat_form. Only these may overwrite canonical name/email/phone (_mayOverwriteCanon); everything else fills empty fields only.
  • GENUINE_USER_SOURCES (in _decideTrust) — high-trust ∪ chat, call. Only genuine sources can verify; a first profile minted by a non-genuine source stays unverified (first_profile_untrusted_source). Enrichment can never mint verified or overwrite a self-provided name.
  • Direct-trigger reasons: first_party_form, first_party_booking (bookings auto-verify), crm_tracked_landing, caller_id_match, and chat/call self-identification → verify_chat / reason chat_identification.
  • kk link clicks verify (3cdbfd124, management decision 2026-10) — kk_token is a genuine source: a bot-filtered ?kk= click verifies (verify_kk_link / reason kk_link_click) and seeds device/IP signals. It is treated as passive: the session gets kk_shadow_person_id, so a forwarded link stays overridable — the visitor's own form/chat/booking wins (_overridesPassive) and self-healing withdraws the shared signals.
  • Name moderation — app/lib/NameModeration.js screen(name) (obscenity + denylists) rejects junk/profane names before persisting; the frontend falls back to "Unknown Visitor" (getSessionName, frontend/src/common/helpers/session.js).
  • AI prompts get verified names only: IdentityGraphRendererService emits a name only when name_addressable (verified). The Apollo colleague list (company_contacts) is excluded from the default section set — opt-in via identity_graph_config.enabled_sections.

Resolution order on session create​

UserSessionController.create resolves internally before spending enrichment quota: _applyWidgetUserSessionId() → _backfillPersonFromPriorVisit() (widget-id/cookie link at claimed). The enrichment gate is internally_resolved = knowsVisitor(body) || personResolver.hasGraphCandidate() — hasGraphCandidate counts the device and the IP candidate (a known visitor on a new browser still matches by IP), and knowsVisitor (app/helpers/VisitorIdentityHelper.js) is the single definition of "we know who this is": a graph link or shadow marker, or a stated name/email/phone (first_name/last_name excluded — pre-July-2026 sessions hold the Apollo guess there). grantTracking applies the graph half (person ids + hasGraphCandidate). Session create evaluates the IP candidate on the server-observed IP, and since d7e76b75d so does the stored user_ip: a public request.ip (trust proxy) overwrites the client-reported value, which was forgeable and fed the reverse IP index once the visitor verified. hasGraphCandidate applies the same GDPR gate as the IP claim (c2d955069), so an EEA visitor whose IP can't be claimed keeps company-level enrichment. Snitcher/Apollo only fire when !internally_resolved && user_ip && suspected_bot !== true. When the server sees only a private IP, it falls back to the client value, then x-forwarded-for / x-real-ip.

After the session row exists, in order:

  1. Widget-id return — promoteWidgetLink() stamps widget_shadow_person_id and runs passive promotion (below).
  2. Device claim — claimDeviceCandidate() (fp_hash).
  3. IP claim — claimIpCandidate() on the server-observed IP (request.ip via trust proxy, never the client-reported user_ip — a forged body must not read someone's identity), only when no device claim linked.

_claimCandidate() links a still-anonymous session (person_id: null filter) at claimed, projects the Person's name/email/phone onto the session, sets the origin's shadow marker (device_shadow_person_id / ip_shadow_person_id), releases any enrichment CRM link, and then calls _promotePassiveClaim().

Device claims (cross-tenant since d8a283a1b, 2026-09-09): evaluateDeviceCandidate({ fpHash, softSig }) — a hash matching a single verified PersonProfile on any tenant, seen within IP_CANDIDATE_FRESHNESS_DAYS (90). A claim requires an fp_hash match (c5484a81e); a soft signature alone never claims. Ambiguity is decided by the fingerprint alone (c2d955069): the soft signature is only looked up when there is no fp (to label the refusal) — counting its matches had refused 32% of new sessions as "ambiguous", because everyone on the same phone model shares it. More than one person on a hash is ambiguous and rejected; a fingerprint in contested_devices (below) refuses as device_contested. A corroborated device claim (soft sig, IP or subnet also on the profile) bumps the existing fp sighting (_refreshDeviceSighting) so a regular visitor who never re-verifies doesn't age out after 90 days. PersonWatchService._recognizeByDeviceSignals delegates to the resolver.

IP claims (cross-tenant since b3ad3d4ef, 2026-09-23; were per-tenant shadow-only before): evaluateIpCandidate({ ip }) reads person_ip_signals by ip_hash across every company (sightings of one person summed; verified if any company verified it). Claims only when the IP is public, not a bot, not shared, maps to exactly one person, trust_tier: verified, fresh within IP_CANDIDATE_FRESHNESS_DAYS (90, aligned with the signal TTL) and IP_CANDIDATE_MIN_HITS (1), and not contested (person_ip_signals.contested_until). _isSharedIp() refuses datacenter/VPN/proxy/Tor (session_ips.info), an ipdetective ip_type matching SHARED_IP_TYPES (hosting/mobile/carrier/cgnat…), or SHARED_IP_DEVICES (15) distinct fingerprints on the IP in SHARED_IP_DEVICE_WINDOW_DAYS (30) — counted in the capped session_ips.devices[] (_noteDeviceOnIp, last 50; each entry now stores the soft signature sig next to fp). Device churn is waived (b185b2d7f) only for one verified person with ≥ SINGLE_PERSON_IP_EXEMPT_HITS (10) hits on ≤ SINGLE_PERSON_IP_MAX_SIGS (5) distinct soft signatures — incognito re-mints the fingerprint, not the machine; entries without a sig are ignored and provider-classified IPs never qualify. The claim also passes _personLevelBlocked() — the same GDPR gate as Apollo, because server-side IP identification is person-level. Both candidate reads page 25 rows; a full page is re-checked for a second person past the limit (_otherPersonBeyondLimit, errors count as "yes"). shadowIpCandidate() (the old IP-PR2 shadow mode) is no longer called from session create. A failed candidate lookup stamps lookup_error (refusal reason lookup_error) instead of device_unknown / ip_unknown.

Late recognition (b185b2d7f) — retryRecognition({userSessionId, ip}) re-runs the device then IP claim for a still-anonymous, non-gdpr_anonymous session: on every widget socket connect (SocketService, throttled to once per RECOGNITION_RETRY_HOURS = 3 by an atomic recognition.retry_at stamp) and forced on a late consent grant (grant-tracking; the widget now uploads fp_hash + soft signature with it). Results go to recognition.retry_path / retry_device_refused / retry_ip_refused; recognition.path stays the create-time measure. new_user_identified fires for post-create recognition too (shared lib/notifyIdentifiedPerson.js). PersonWatch device recognition goes through claimDeviceCandidate (shadow marker + company gate).

Passive promotion — _promotePassiveClaim() scores the session against the person's profile on this tenant with IdentityVerifierService.scoreClaim at the strict threshold whatever the tenant policy (permissive is not honoured — it would verify every passive claim; regulated disables it). A lone fp (60) or IP (20) never verifies; fp + IP or fp + soft signature can. Pass → verified_person_id + identity_trust: verified, event verify_passive_score, IP recorded at verified and the profile's verified_signals grow (new IP, soft signature, widget id). Fail → stays claimed; non-IP origins record the IP at claimed tier (an IP-origin claim never re-records the IP that gated it, or it would keep itself alive). The widget id is the +100 returning-device signal (verified_signals.widget_ids), so the second visit after a verification verifies on its own.

Contamination protection — the shadow marker stays after a passive verification (_isPassivelyVerified: marker equals verified_person_id). A genuine first-party source or a kk click (_overridesPassive) overrides a passive verification instead of hitting the conflict guard (it also mints its own Person rather than being rejected as a scrape); resolve() then clears the wrong person's projected name/email/phone off the session and runs _healContradiction().

Self-healing (d7e76b75d, c2d955069) — contradiction-triggered and only ever undoes guesses (never merges, deletes or touches a verified identity):

  • IP-origin guess → _contestIp sets contested_until (+90 days, IP_CONTEST_DAYS) on every person_ip_signals row for that hash; no IP claims from it until it passes.
  • Dashboard users (_isAccountHolder: Person email matches a users row — agency owners onboarding clients, staff testing with fake data) stop here; the IP contest still applies, nothing else does.
  • Device-origin guess → _contestDevice upserts contested_devices ({fp_hash, until}, TTL index) for 90 days, so a shared laptop stops flip-flopping to whoever identified last.
  • _retractPassiveClaim() pulls the session's fp/soft-sig/IP/subnet (IPv4 /24, IPv6 /64 — shared ipSignals.subnetOf)/session id/widget id from every profile of the wrong person (cross-tenant), logs claim_contradicted, and downgrades their person_ip_signals rows to claimed.
  • _unclaimSiblings() returns up to 200 other sessions the same IP/device/ widget id/kk link guessed as that person (shadow marker still naming them) to anonymous, clearing name/email/phone only where they still hold the wrong person's values.

Admin detach/split/unlink call retractSessionSignals() so repaired sessions stop vouching for the person they left. The anchor guard (_isDeviceSuspectedClaim) covers device, IP and widget links and passive verifications: a first-party identifier on such a session mints its own Person rather than attaching to the suspect. An anchor also never attaches an email/phone that differs from the anchor Person's own (a scraped admin-dashboard form is someone else's identifier).

Email and phone owned by different Persons — _findByMatchKeys takes the email's owner (phones are shared within households) and returns the other Person's keys as foreignHashes, which are never copied (previously an E11000 on match_keys_hash_unique aborted the resolve). A race-adopted Person still receives this call's keys/fields.

Shared phone lines (b185b2d7f, narrowed in 72b54d8dd) — _isSharedPhoneMatch: a new email on a phone owned by a Person with a different email mints its own Person only when both names are present and the first names differ; same first name or no name keeps merging (one person's personal + work email on one mobile stays one Person). The verified-session conflict guard now runs before any Person write, so a rejected claim no longer adds keys or overwrites canonical fields on the other Person.

Mid-session IP changes — every widget socket handshake calls personResolver.trackSessionIp() (SocketService). A no-op unless the IP hash differs; the IP is the right-most x-forwarded-for hop (the one our ingress appended — the left-most is client-supplied); records ip_hash + capped ip_changes[] (raw IP blank on Snitcher-enriched sessions) and, for a linked session, feeds the graph at the session's own tier (ip_change event when verified).

Suspected identity — cross-device guesses are shadow markers, not a trust tier: ip_shadow_person_id / device_shadow_person_id / widget_shadow_person_id on UserSessionModel (all three stripped from the public session payload with fp_hash, ip_hash, ip_changes). IdentityGraphService._buildSuspectedIdentity renders an owner-facing "⚠ Suspected Identity (UNCONFIRMED)" block; the frontend SuspectedIdentityBadge shows while the session is linked by a marker and not verified (basis IP / device / returning browser). Session display naming (getSessionName) tiers: person → self-provided → suspected → Apollo person → Snitcher company (business type) → email → phone → Snitcher domain (non-business, ⚠); every enrichment tier is skipped once hasKnownVisitor.

Enrichment guesses vs known visitors​

An Apollo-matched employee must never speak for a visitor we can identify (40ad30396, c3bb4713b):

  • CrmSyncHelper.hasGraphIdentity drops an apollo-sourced sync outright for a session the graph placed (audited skipped_known_person) and stops enrichment LinkedIn reaching a known visitor's contact. A stated sync never inherits a guessed link — it re-resolves.
  • An enrichment link is marked user_sessions.ghl_contact_from_enrichment so it keeps carrying visit activity while nobody knows the visitor. lib/enrichmentLink.releaseGuessedContact() clears the link, crm_links row, cached ghl_context and the flag (filtered on the flag, so a contact the visitor produced is never touched; the CRM record is left alone). Called from ChatController the moment any first-party field lands and from PersonResolver when a person is stamped (_detachEnrichmentCrmLink).
  • userActiveSessions attaches the resolved person so the live screen stops falling back to Apollo. Legacy echo is ignored: image / first_name equal to the Apollo values are skipped by resolveName, the mobile avatar endpoint and the daily brief.
  • Frontend: hasIdentityGraphMatch (person, bare person id — the public single-session endpoint strips person/apollo/snitcher data — or suspected match) and hasKnownVisitor (mirrors knowsVisitor) in src/common/helpers/session.js gate every person-level provider fallback on live + recorded sessions (name, avatar, Apollo city, decision makers, other contacts, Apollo header). The Snitcher company card stays.
  • Backlog: /migrations/unlink-apollo-contacts (see Admin surface).

Phone region and account holders​

  • IdentityNormalize.resolvePhoneRegion (25f258299) used to read only the flat countryCode/country/geo.timezone, which web sessions never carry, so every web phone was stored as typed. It now also reads ip_info.countryCode and the browser timezone under knox.geo / user_meta.timezone; the resolver's session projection carries those fields. A NZ national number now stores as +64… and later matches the international form.
  • Account-holder seeding — AuthController login calls personResolver.recordAccountHolder() (fire-and-forget): recordContact + outbound_only: false + the request IP at verified tier against the user's company. It is the only cross-site signal for EEA/UK/CH owners, whose device signature is suppressed at capture. Impersonation (UserController@loginAs) must never seed — it would stamp our office IP onto the customer; locked by test/identity-graph/account-holder-seeding.test.js.

Duplicate Persons and the unique match-key index​

Persons split across phone-region hash variants and find-then-create races collide on match_keys.hash, which also blocked the unique index that stops the race. lib/personMerge.js (967ae4782 and follow-ups):

  • Clusters are connected components over shared hashes; the oldest Person wins, losers' keys/profiles/references move onto it (profile arrays deduped by their hashes; REPOINT collections and REPOINT_UNIQUE funnel contacts / IP signals, sessions' five person-id fields), then losers are deleted.
  • Agreement gate — a cluster merges only when members agree on every non-empty email (case-insensitive) and phone (last 9 digits); otherwise it is reported under conflicting_clusters. The prod dry run showed components chaining through office phones, test numbers and wrongly-merged Persons. Clusters above maxClusterSize (5) are reported only.
  • detachSharedKeys (opt-in) runs first: a key shared by people who are not the same human stays on its owner (whose own email/phone backs it, else the oldest) and is pulled from the rest, so the freed duplicates merge in the same pass. Dry run reports detached_keys.
  • Index preflight — every repointed field must lead an index or each updateMany is a full scan (prod Apply hit the 45 s socket timeout). Indexes were added on person_id in ten collections and on the session claimed/verified/device_shadow person ids; the dry run reports indexes_missing and Apply refuses while any are still building after a deploy.
  • rebuildIndex creates match_keys_hash_unique (unique, partial on match_keys.hash existing) before dropping the legacy match_keys.hash_1, and is refused while any skipped or conflicting cluster remains.
  • scripts/person-merge-integration.js is the local-dev real-Mongo check.

Signals feeding resolution​

  • Fingerprint (FingerprintJS) + device/browser attributes.
  • IP signals (PersonIpSignalModel, IpShadowOutcomeModel, app/lib/ipSignals.js) — IP-assisted resolution, shadow scoring, and backfill. Keyed by ip_hash = ipSignals.hashIp(), an HMAC-SHA256 of the normalized IP with IP_HASH_SECRET (falls back to the app salt). HMAC, not a bare hash: IPv4 is small enough to reverse an unkeyed digest. The Snitcher contract forbids storing the raw IP next to their enrichment, so user_sessions.user_ip is blanked when Snitcher returns a company but ip_hash survives and keeps the visitor recognisable. person_ip_signals unique key is (company_id, person_id, ip_hash) (partial on ip_hash > '') plus an ip_hash index for the cross-tenant lookup; ip is blank on hash-only rows. Legacy raw-ip rows are matched in place until the ip-hash-index migration (below) rewrites them. session_ips now persists the ipdetective ip_type + raw info and the devices[] churn list.
  • Form captures — emails/names auto-captured from forms (HubSpot/GHL/Calendly/ Typeform interception) attach identity to a session; the widget pre-chat form posts POST /api/intake with source: 'form' (direct verification trigger).
  • HubSpot tracking cookie (5b55a0b55, 2026-10-14) — the widget loader sends the tenant's own hubspotutk cookie (re-checked on SPA navigation and HubSpot form submit) to public POST /user-session/hubspot-utk; the backend looks it up in HubSpot (legacy v1 contact-by-utk) and, when HubSpot already knows the contact, links the session (crmLinks) and resolves it as a crm identity — outranks device/IP claims, not the visitor's own form. Gated on consent + GDPR (loader and backend), bot sessions, and a connected HubSpot; one lookup per session+utk (Redis, 10 min). It replaces the old _maybeTriggerCrmLanding call (hit an api-key route, always 401); the GHL ?contact_id= landing half was dropped as spoofable from a URL.
  • B2B enrichment — Snitcher (reverse IP → company) then Apollo (domain → person) fill PersonProfile. Clearbit's live API call is disabled (cache-read only); RB2B is the alternative per-company provider (below) and still has its legacy webhook path. HappierLeads is gone (d8a283a1b): service, config, HappierLeadSessionModel, inbound webhook, provisioning route, and the ms-communication mirror fields were deleted (the pixel left the widget 2026-07-01); only readers of the historic happier_leads_data session blob remain (StatsV2, KnoxCrm, Notification, Chat, ServiceRoom controllers, VisitorIdentityHelper). The enrichment-guess CRM push job (LeadContactSyncJob) is disabled globally (commented out in SchedulerService). Enrichment is consent-gated when the tenant enables consent gating (identification category).
  • Per-page-view arrival source (7a5930202) — the classifier moved to app/lib/trafficSource.js (+ formatSourceLabel) and is stamped on the live socket path in SocketService.saveSessionStart (source_category). URL markers (?kk=, UTMs, gclid) win, else referrer; same-host referrer is internal navigation; widget.js sends document.referrer on the first page-load emit only. app/lib/visitGroups.js splits page-views into visits on a 30-minute gap; a visit's source is the page-view that opened it. The frontend Repeat badge (2+ visits) and Session Timeline grouping use the same rule; StatsV2Controller exposes return_visitors + return_visitor_ids (capped 50).

Who gets identified: the one rule, and the GDPR gate​

Identification is snitcher_enabled && (snitcher_allowed ?? 20) > 0 (KnoxStatsController ~3245, mirrored by the leads-screen notice). Everything else is gone: companies.lead_intelligence / lead_intelligence_allowed, the admin toggle and cap, /happier-leads/quota, and the package-sync writes to them were deleted in d8a283a1b — they only ever gated the HappierLeads pixel. Two consequences:

  • snitcher_allowed: 0 now blocks (67534d306); before, a zero cap skipped the cap block and meant unlimited. The ?? 20 is deliberate — callers use .lean(), which applies no schema defaults.
  • Identification is package-driven for everyone (d2e1dce98): SubscriptionHelper sets snitcher_enabled = !!features.lead_intelligence_allowed and snitcher_allowed = features.lead_intelligence ?? 20 at all five sync sites (trial, Stripe subscribe, subscription update, package change, platform create). A super-admin override is reset by the next sync. Partner-invite redemption clears snitcher_enabled (AuthController ~895); archiving a company or agency switches identification off.

Provider switch (05246d130, 2026-10-28) — identification moved out of UserSessionController into VisitorIdentificationService.identify(), called by session create and grantTracking (which lost its duplicate Snitcher/Apollo copy). It reads companies.identification_provider:

  • 'snitcher' or null (no schema default — a lean read of an unset field must behave as today): Snitcher → Apollo, unchanged.
  • 'rb2b': RB2B IP + User-Agent → person/company chain (Rb2bService.collect() returns without persisting). Used only when rb2b_enabled is on, an RB2B API key is configured (rb2b.api_key) and the visitor is not GDPR-restricted — otherwise it falls back to Snitcher. Same consent, country-filter, daily-quota, paid add-on and AI spend guard checks as Snitcher; rb2b_sessions rows now carry company_id, tier and identified, and a cache hit (by IP) is free. Lead Intelligence pricing (lib/leadIntelPricing.js) gains an rb2b step (charged only for rb2b companies; a miss is free).
  • Only writer: PUT /company/:_id/identification-provider (super admin; refuses rb2b while rb2b_enabled is off). Admin → Companies → detail has the Visitor identification toggle with a warning when RB2B is selected but disabled. lib/sessionIdentifiedFlag, lead rows and the frontend session helpers read rb2b_data.

GDPR person-level block (655140ec5, plan GDPR_IDENTIFICATION_PLAN.md):

  • app/lib/GdprGeo.js — RESTRICTED_COUNTRIES is 32 codes: EU27 + IS/LI/NO + GB (UK GDPR/PECR) + CH (revFADP). personLevelBlocked() returns true for empty/unknown — a failed geo lookup fails closed. blockedForCompany(company, codes) accepts one code or an array and takes the restrictive answer; only company.gdpr_protection_enabled === false opens it — never test truthiness, because .lean() docs have no default.
  • companies.gdpr_protection_enabled defaults true — the inverse of every other gate in that schema. Toggle: PUT /company/:_id/gdpr-protection (admin-only, logs the actor); admin company detail shows an amber note while off.
  • Gate points: Apollo people-match in UserSessionController.getApolloData (new 4th arg countryCode, the single choke for session-create and grantTracking); widget fingerprint — GET /company/:id returns identification_restricted, and public/widget.js ConsentGate.fingerprintAllowed() skips computeSoftSignature() / fetchFpHash() so the FingerprintJS bundle is never fetched (ePrivacy Art. 5(3): the hash must not be computed, not merely discarded). It is deliberately separate from identificationAllowed(), which drives Snitcher. Since 3cdbfd124 a restricted-country visitor is fingerprinted after an explicit identification grant (kkConsentExplicit: banner answer, stored choice, kkSetConsent, or a window.knockKnockConsent preset by the site's own consent tool) with identification === true; the non-blocking banner's default-accept and no-consent visitors stay un-fingerprinted.
  • The hubspotutk lookup gates on the request IP (falls back to user_ip), since Snitcher-enriched sessions have user_ip wiped and an unknown country fails closed.
  • Not gated: Snitcher — company-level reverse IP on legitimate interest (comment at the call site). A visit from Acme still shows as Acme.
  • Geo: app/lib/IpGeo.js + app/lib/DbipCountry.js with the vendored data/dbip-country-lite.csv.gz (DB-IP Lite, CC-BY 4.0, no network call) and IpGeoModel (30-day TTL). ip-api is display-only fallback; IP_API_KEY is read only in IpGeo.js and is not set in any configmap yet — the plan's "both configmaps" line is an instruction, not current state.

Recognition coverage​

d7e76b75d stamps user_sessions.recognition on every new session (UserSessionController._stampRecognition, sparse index on recognition.at): path (carried | device | ip | none) plus device_refused / ip_refused — the first gate each passive route failed (PersonResolverService.deviceRefusal / ipRefusal: no_fingerprint, device_unknown, device_ambiguous, soft_signature_only, device_stale, device_contested, no_ip, gdpr_blocked, ip_not_public, ip_bot, ip_shared_network, ip_unknown, ip_ambiguous, ip_unverified, ip_stale, ip_contested, ip_few_hits, graph_unavailable, already_linked, error). When an anonymous-at-create session later resolves to a Person that already existed, _recordLateRecognition adds late_source, late_at and late_known_device (the graph held fp/IP evidence, so a passive route could have matched).

IpSignalSeedService.recognitionCoverage({days, companyId}) aggregates it (POST /admin/identity/maintenance/recognition-coverage, read-only, default 7 days): coverage = (recognized at start + recognized by link) / known-visitor sessions, where link sources are kk_token, crm, email_click; everything else late is a miss, broken down by refusal reason, device/browser and late_known_device. graph_unavailable_companies lists tenants whose graph is off (no active owner subscription). New sessions only — a same-browser return reuses its session.

Other guards​

  • IdentityVerifierService.resolvePolicy fails closed (strict) when the config read errors — it used to fall to permissive and auto-verify.
  • PersonWatchService._nameTokensMatch is one-directional: every token of the watched name must appear in the session name ("watch Anna" matches "Anna Hyatt"; a visitor typing only "Anna" never fires "watch Anna Hyatt").
  • FormSubmissionService de-duplication only swallows a form on a session the visitor verified themselves; on a device/IP/link match the same details are the confirmation that verifies it (c2d955069).
  • IdentityCleanupService normalize only adds match keys (dropping old ones made each former email/phone mint a duplicate Person), and a bulk batch skips E11000 rows instead of aborting the sweep.

Enrichment quota​

UserSessionController.getSnitcherData: daily cap company.snitcher_allowed, counted in company-local timezone; 00:00–06:00 local spends only yesterday's leftover; bots never spend quota. Apollo has no separate quota — it only runs after Snitcher resolves a domain. Apollo error responses are never cached (error-cache poisoning fix); POST /migrations/cleanup-apollo-records (and the admin wrapper POST /admin/identity/maintenance/cleanup-apollo-records) purges poisoned ApolloRecordModel rows so domains retry.

Writing identity back to the CRM​

  • app/lib/ghlContactFill.js (014f45457) — STATED_SOURCES = {chat_form, new_lead, transcript_ai, session_create} may write onto a matched GHL contact, not just a created one: name only over a placeholder (unknown/guest/user/not provided, or name == email local part), email replaced only when the match was by phone (else only when the contact has none), phone only when empty. Enrichment sources (apollo, lead_sync) never write. Applied at three CrmSyncHelper._fillGhlContact sites (already-linked, email match, phone match).
  • _syncGhlLinkedin (2d5310b08) writes visitor + employer LinkedIn (Apollo → RB2B → HappierLeads blob) on matched contacts, never over an existing value. It also fixed the custom-field write shape to {id, field_value} — the old {key, value} never landed. _ensureField lives in app/lib/ghlCustomFields.js.
  • Partial-write wipe (798d6337b): ChatController.updateContactInformation merges into chat.contact_information (new value still wins) instead of $setting the whole subdoc, and ChatTranscriptEmailJob is fill-only — an email-only extraction was nulling a pre-chat-form name.
  • Agent K → graph (ec5b2e36f): PersonResolver.recordContact() is a session-less find-or-create called from AgentKPushService._finalize on every delivery path; fill-only on an existing Person; no match key → no Person. New profiles are outbound_only: true so _decideTrust treats them as no history; any real resolve clears it. person_id now rides into enterFunnel.
  • GHL visit activity — GhlVisitActivityJob (every 15 min, opt-in go_high_level.log_visit_activity) posts one internal conversation comment per ended visit (GHL has no Activity write API): sessions with a GHL contact, non-bot/non-owner, updated in the last 7 days but quiet for VISIT_GAP_MS; 200 sessions per company, max 10 comments per run. Dedupe is the watermark user_sessions.ghl_visit_activity_synced_at, written per comment — internal comments cannot be deleted, so a missed watermark means a duplicate forever.
  • kk_token coverage (33a9bbea6): company.kk_tokens.app_contacts (stamp every contact the app creates, fire-and-forget in saveContact) and kk_tokens.auto_sync; KkTokenSyncJob ticks hourly with RESYNC_MS = 22h, reusing AgentKPushService.startTokenBackfill(id, {createField: true}) and ai_agent_k.kk_backfill.status/finished_at as the day-claim; tokens mint with source ghl_backfill so clicks never attribute to Agent K. Picker: GET /company/:id/kk-tokens/untokenized, POST …/stamp (25 per request). The kk-click stitch (65908d2da, d1dc0f893) now checks three homes for the click's contact — session CRM stamp, PersonProfile by (person_id, company_id), and the LeadConnector email-click recipient — because the resolver writes the contact onto the profile and never stamps the session back; a background backfill repairs click rows written without one.

Blocked visitors​

BlockedModel (collection blocked, {type: 'ip'|'url'|'company', value, company_id}, index {type, value, company_id}): company_id set = tenant block; null = platform-wide "don't track at all" (super admin). PUT /user-session/:_id/block (setBlocked) scopes to every session for that company sharing user_ip in the last 30 days (BLOCK_LOOKBACK_MS — bounded so a NAT'd office isn't a six-figure updateMany), sets user_sessions.is_blocked, upserts/deletes the IP row, and broadcasts block-user to each session room and the company room. Tracking and recording continue; is_active is untouched. is_blocked is off-limits to the public PUT, and the spoofable client-emitted relay in SocketService was deleted.

ms-communication enforces it in the existing socket.use middleware via BlockedVisitorsHelper.createBlockedVisitorCache — first lookup awaited (a scripted socket got one message through otherwise), 30 s TTL, 5,000-entry cap, DB failure keeps the last known set — so one check covers chat, calls, and AI; auto-trigger delivery receipts stay exempt. The widget's applyBlocked() ends any call in flight and asks the host page to drop the iframe, listening for block-user on all three sockets.

Admin surface​

Super-admins manage identity via frontend/src/repositories/admin/identity.js against backend's adminIdentityRoutes.js: list persons/profiles/form- submissions, session detail (fingerprint/verified-signal display), the identity graph config (moved admin-side: GET/PUT /admin/identity/config/defaults, PUT /admin/identity/config/company/:id), maintenance panels (trim session events — NDJSON progress, retry poisoned Apollo domains, unlink enrichment identities, backfill chat human-message flag, IP-signal backfills, the crm_links backfill and the CRM smoke test), and the GHL reconcile-conflicts queue.

Person repair (5675bd36f, f4a1c2dca, 33ea5733d, all in AdminIdentityController, dry-run unless apply):

  • POST …/persons/:id/detach-match-key — removes the key, unlinks sessions, drops matching form submissions, forgets those sessions as device proof, recomputes canonical email/phone.
  • POST …/persons/:id/split-match-keys — moves selected keys to a new Person; genuinely-identified sessions re-link at claimed, device-suspected sessions detach to anonymous (a device stamp is a guess); form submissions follow to the new per-company profile.
  • PUT …/persons/:id/identity — edit canonical name/email/phone. Keys are rebuilt by the resolver's own _buildMatchKeys; phone must be E.164; a fully-unchanged save is a no-op (protects the 50-cap on identity_events); blanking a field that still has a match key is refused — Detach is the removal path.
  • POST …/persons/:id/reset-trust-signals, POST …/sessions/:id/unlink.
  • DELETE …/persons/:id and DELETE …/persons/:id/profiles/:company_id (b3ad3d4ef) — the full cascade, shared with the cleanup sweeps via IdentityCleanupService.prunePersons() / deleteProfile(): profiles and person_ip_signals deleted, sessions' person_id / claimed_person_id / verified_person_id nulled to anonymous, funnel_contacts.person_id nulled, active knox_visitor_directives expired. Profile delete is scoped to that company; the Person and other tenants' profiles stay.
  • getPerson returns each session's ip_info so the edit dialog seeds the phone country picker from the visitor's own geo (vue-tel-input's auto-detect fell back to Afghanistan and re-saved numbers with the wrong code).

Every write emits an admin_repair identity event plus session identity_audit entries; getPerson returns identity_audit and the shadow markers for the frontend Copy JSON diagnostic export.

Graph maintenance jobs — each is api-key /migrations/* + a super-admin /admin/identity/maintenance/* wrapper, runs as a background job (poll …/jobs/:job_id), dry-run unless apply:

JobEndpointNotes
Key IP Signals by Haship-hash-indexlib/ipHashIndexMigration.js: fills ip_hash on legacy rows, deletes unhashable ones, folds a legacy row into its hash-keyed twin (delete first — the ordered bulk would trip the legacy index), createIndexes() then drops company_id_1_person_id_1_ip_1. Also runs at boot (hooks.js, 20 s after start) under Redis lock lock:ip_hash_index_migration when anything is left.
Backfill Device Claimsbackfill-device-claims (companyId?, sinceDays 30)lib/deviceClaimBackfill.js re-runs claimDeviceCandidate for sessions created before cross-tenant device claims. Starts from fresh verified fp_hashes on profiles, evaluates each once, then walks the window in one-hour slices (person_id: null, fp_hash $in, hinted person_id/created_at index, maxTimeMS 20 s). No fp_hash index on user_sessions by choice (storage); cursors over the whole window died in socket timeouts. Returns 50 samples.
Merge Duplicate Personsmerge-duplicate-persons (maxClusterSize, rebuildIndex, detachSharedKeys)See Duplicate Persons.
Unlink Apollo CRM Contactsunlink-apollo-contacts (companyId?, includeAnonymous?)lib/apolloContactUnlink.js clears sessions still linked to a guessed GHL contact (link, crm_links row, cached ghl_context; the contact is never touched). Pass 1 reads ghl_appolo_sync (only exists since 2026-08-13); pass 2 scans sessions with apollo_data.enriched_person still linked, tenant by tenant (companies without a GHL location skipped, paged by _id 300 / maxTimeMS 20 s, per-company try/catch → companies_failed; a scan failure returns scan_error alongside pass-1 stats). A link counts as the guess when the cached snapshot names the Apollo person, or neither session nor Person ever held an email/phone; skipped when either name is the Apollo person. Samples carry found_by and person_name.

Device-claim diagnostic — GET /admin/identity/sessions/:id/markdown-preview on an unlinked session runs evaluateDeviceCandidate and adds the reason to reasons[]: no signature (fingerprinting blocked), no verified profile carries it, ambiguous (N persons), soft-signature-only match, or stale (last verification older than 90 days). It also runs evaluateIpCandidate and returns ip_candidate: no raw IP (Snitcher-wiped), GDPR-blocked, private/CGNAT, bot, shared network, no person on the IP, N persons (dashboard logins count), claimed-not-verified, or stale.

Consumers​

  • AI agents — cross-session context is injected into chat/voice prompts so the AI knows a returning visitor.
  • Nox — visitor lookups, presence, and watch directives.
  • CRM sync — resolved identities + outcomes flow to GHL/HubSpot. See CRM Integration.

Reliability​

Identity resolution has had a dedicated reliability effort (IP-assisted resolution, form-intercept fixes, calls/read-gate/reconcile work). Treat resolution changes as high-blast-radius: they affect lead counts, dedup, and CRM records. Validate against real session samples before shipping.