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
| Entity | Meaning |
|---|---|
UserSessionModel | one raw visitor session (device, fingerprint, IPs, URLs) |
PersonModel | a resolved distinct visitor (may span many sessions/devices) |
PersonProfileModel | enriched identity for a Person (name, email, company, B2B data) |
PersonIpSignalModel | IP→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 mintverifiedor 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/ reasonchat_identification. - kk link clicks verify (
3cdbfd124, management decision 2026-10) —kk_tokenis a genuine source: a bot-filtered?kk=click verifies (verify_kk_link/ reasonkk_link_click) and seeds device/IP signals. It is treated as passive: the session getskk_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.jsscreen(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:
IdentityGraphRendererServiceemits a name only whenname_addressable(verified). The Apollo colleague list (company_contacts) is excluded from the default section set — opt-in viaidentity_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:
- Widget-id return —
promoteWidgetLink()stampswidget_shadow_person_idand runs passive promotion (below). - Device claim —
claimDeviceCandidate()(fp_hash). - IP claim —
claimIpCandidate()on the server-observed IP (request.ipvia trust proxy, never the client-reporteduser_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 →
_contestIpsetscontested_until(+90 days,IP_CONTEST_DAYS) on everyperson_ip_signalsrow for that hash; no IP claims from it until it passes. - Dashboard users (
_isAccountHolder: Person email matches ausersrow — agency owners onboarding clients, staff testing with fake data) stop here; the IP contest still applies, nothing else does. - Device-origin guess →
_contestDeviceupsertscontested_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 — sharedipSignals.subnetOf)/session id/widget id from every profile of the wrong person (cross-tenant), logsclaim_contradicted, and downgrades theirperson_ip_signalsrows toclaimed._unclaimSiblings()returns up to 200 other sessions the same IP/device/ widget id/kk link guessed as that person (shadow marker still naming them) toanonymous, 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.hasGraphIdentitydrops anapollo-sourced sync outright for a session the graph placed (auditedskipped_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_enrichmentso it keeps carrying visit activity while nobody knows the visitor.lib/enrichmentLink.releaseGuessedContact()clears the link,crm_linksrow, cachedghl_contextand the flag (filtered on the flag, so a contact the visitor produced is never touched; the CRM record is left alone). Called fromChatControllerthe moment any first-party field lands and fromPersonResolverwhen a person is stamped (_detachEnrichmentCrmLink). userActiveSessionsattaches the resolved person so the live screen stops falling back to Apollo. Legacy echo is ignored:image/first_nameequal to the Apollo values are skipped byresolveName, 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) andhasKnownVisitor(mirrorsknowsVisitor) insrc/common/helpers/session.jsgate 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 flatcountryCode/country/geo.timezone, which web sessions never carry, so every web phone was stored as typed. It now also readsip_info.countryCodeand the browser timezone underknox.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 —
AuthControllerlogin callspersonResolver.recordAccountHolder()(fire-and-forget):recordContact+outbound_only: false+ the request IP atverifiedtier 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 bytest/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;
REPOINTcollections andREPOINT_UNIQUEfunnel 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 abovemaxClusterSize(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 reportsdetached_keys.- Index preflight — every repointed field must lead an index or each
updateManyis a full scan (prod Apply hit the 45 s socket timeout). Indexes were added onperson_idin ten collections and on the sessionclaimed/verified/device_shadowperson ids; the dry run reportsindexes_missingand Apply refuses while any are still building after a deploy. rebuildIndexcreatesmatch_keys_hash_unique(unique, partial onmatch_keys.hashexisting) before dropping the legacymatch_keys.hash_1, and is refused while any skipped or conflicting cluster remains.scripts/person-merge-integration.jsis 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 byip_hash=ipSignals.hashIp(), an HMAC-SHA256 of the normalized IP withIP_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, souser_sessions.user_ipis blanked when Snitcher returns a company butip_hashsurvives and keeps the visitor recognisable.person_ip_signalsunique key is(company_id, person_id, ip_hash)(partial onip_hash > '') plus anip_hashindex for the cross-tenant lookup;ipis blank on hash-only rows. Legacy raw-ip rows are matched in place until the ip-hash-index migration (below) rewrites them.session_ipsnow persists the ipdetectiveip_type+ rawinfoand thedevices[]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/intakewithsource: 'form'(direct verification trigger). - HubSpot tracking cookie (
5b55a0b55, 2026-10-14) — the widget loader sends the tenant's ownhubspotutkcookie (re-checked on SPA navigation and HubSpot form submit) to publicPOST /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 acrmidentity — 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_maybeTriggerCrmLandingcall (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 historichappier_leads_datasession blob remain (StatsV2, KnoxCrm, Notification, Chat, ServiceRoom controllers,VisitorIdentityHelper). The enrichment-guess CRM push job (LeadContactSyncJob) is disabled globally (commented out inSchedulerService). Enrichment is consent-gated when the tenant enables consent gating (identification category). - Per-page-view arrival source (
7a5930202) — the classifier moved toapp/lib/trafficSource.js(+formatSourceLabel) and is stamped on the live socket path inSocketService.saveSessionStart(source_category). URL markers (?kk=, UTMs,gclid) win, else referrer; same-host referrer is internal navigation;widget.jssendsdocument.referreron the first page-load emit only.app/lib/visitGroups.jssplits 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;StatsV2Controllerexposesreturn_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: 0now blocks (67534d306); before, a zero cap skipped the cap block and meant unlimited. The?? 20is deliberate — callers use.lean(), which applies no schema defaults.- Identification is package-driven for everyone (
d2e1dce98):SubscriptionHelpersetssnitcher_enabled = !!features.lead_intelligence_allowedandsnitcher_allowed = features.lead_intelligence ?? 20at 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 clearssnitcher_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'ornull(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 whenrb2b_enabledis 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_sessionsrows now carrycompany_id, tier andidentified, and a cache hit (by IP) is free. Lead Intelligence pricing (lib/leadIntelPricing.js) gains anrb2bstep (charged only forrb2bcompanies; a miss is free).- Only writer:
PUT /company/:_id/identification-provider(super admin; refusesrb2bwhilerb2b_enabledis 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 readrb2b_data.
GDPR person-level block (655140ec5, plan GDPR_IDENTIFICATION_PLAN.md):
app/lib/GdprGeo.js—RESTRICTED_COUNTRIESis 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; onlycompany.gdpr_protection_enabled === falseopens it — never test truthiness, because.lean()docs have no default.companies.gdpr_protection_enableddefaultstrue— 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 argcountryCode, the single choke for session-create andgrantTracking); widget fingerprint —GET /company/:idreturnsidentification_restricted, andpublic/widget.jsConsentGate.fingerprintAllowed()skipscomputeSoftSignature()/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 fromidentificationAllowed(), which drives Snitcher. Since3cdbfd124a restricted-country visitor is fingerprinted after an explicit identification grant (kkConsentExplicit: banner answer, stored choice,kkSetConsent, or awindow.knockKnockConsentpreset by the site's own consent tool) withidentification === true; the non-blocking banner's default-accept and no-consent visitors stay un-fingerprinted. - The
hubspotutklookup gates on the request IP (falls back touser_ip), since Snitcher-enriched sessions haveuser_ipwiped 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.jswith the vendoreddata/dbip-country-lite.csv.gz(DB-IP Lite, CC-BY 4.0, no network call) andIpGeoModel(30-day TTL). ip-api is display-only fallback;IP_API_KEYis read only inIpGeo.jsand 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.resolvePolicyfails closed (strict) when the config read errors — it used to fall topermissiveand auto-verify.PersonWatchService._nameTokensMatchis 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").FormSubmissionServicede-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).IdentityCleanupServicenormalize 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 threeCrmSyncHelper._fillGhlContactsites (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._ensureFieldlives inapp/lib/ghlCustomFields.js.- Partial-write wipe (
798d6337b):ChatController.updateContactInformationmerges intochat.contact_information(new value still wins) instead of$setting the whole subdoc, andChatTranscriptEmailJobis 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 fromAgentKPushService._finalizeon every delivery path; fill-only on an existing Person; no match key → no Person. New profiles areoutbound_only: trueso_decideTrusttreats them as no history; any real resolve clears it.person_idnow rides intoenterFunnel. - GHL visit activity —
GhlVisitActivityJob(every 15 min, opt-ingo_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 forVISIT_GAP_MS; 200 sessions per company, max 10 comments per run. Dedupe is the watermarkuser_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 insaveContact) andkk_tokens.auto_sync;KkTokenSyncJobticks hourly withRESYNC_MS = 22h, reusingAgentKPushService.startTokenBackfill(id, {createField: true})andai_agent_k.kk_backfill.status/finished_atas the day-claim; tokens mint with sourceghl_backfillso 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 atclaimed, 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 onidentity_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/:idandDELETE …/persons/:id/profiles/:company_id(b3ad3d4ef) — the full cascade, shared with the cleanup sweeps viaIdentityCleanupService.prunePersons()/deleteProfile(): profiles andperson_ip_signalsdeleted, sessions'person_id/claimed_person_id/verified_person_idnulled toanonymous,funnel_contacts.person_idnulled, activeknox_visitor_directivesexpired. Profile delete is scoped to that company; the Person and other tenants' profiles stay.getPersonreturns each session'sip_infoso 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:
| Job | Endpoint | Notes |
|---|---|---|
| Key IP Signals by Hash | ip-hash-index | lib/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 Claims | backfill-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 Persons | merge-duplicate-persons (maxClusterSize, rebuildIndex, detachSharedKeys) | See Duplicate Persons. |
| Unlink Apollo CRM Contacts | unlink-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.