# Kpanel visitor tracking through your gateway

Source: https://frosvo.com/docs/kpanel-visitor-tracking
Updated: 2026-11-09

Connect Kpanel orders, invoices, services and tickets with verified customer identity and a restricted read-only gateway.

The supplied `integrations/customer-gateway/kpanel-adapter.cjs` runs on your Kpanel host through the [customer-owned gateway](/docs/customer-owned-integration-gateway). It supports verified Kpanel Prisma 5 and 7 clients with `User`, `Order`, `Invoice`, `Service` and `Ticket`. It does not modify the panel, provision servers, send email or copy customer records into Frosvo.

## Prepare a restricted reader

Create a dedicated loopback database account. Replace the database, account and password placeholders through your private administration tool; never use Kpanel's application/root database credential. Grant only these columns:

```sql
CREATE USER 'frosvo_tracking'@'127.0.0.1' IDENTIFIED BY '<private-generated-password>';
GRANT SELECT (id,email,status,emailVerified) ON kpanel.users TO 'frosvo_tracking'@'127.0.0.1';
GRANT SELECT (id,userId,orderNumber,status,updatedAt) ON kpanel.orders TO 'frosvo_tracking'@'127.0.0.1';
GRANT SELECT (id,userId,invoiceNumber,status,updatedAt) ON kpanel.invoices TO 'frosvo_tracking'@'127.0.0.1';
GRANT SELECT (id,userId,serviceNumber,status,updatedAt) ON kpanel.services TO 'frosvo_tracking'@'127.0.0.1';
GRANT SELECT (id,userId,ticketNumber,status,updatedAt) ON kpanel.tickets TO 'frosvo_tracking'@'127.0.0.1';
```

No table-wide SELECT or write grant is required. Verify that both updates and reads of `passwordHash` are denied. Keep gateway environment files private, outside the website directory. URL-encode special characters in the password when composing a connection URL.

Hostinger web hosting documents one user per database, so a second reader may not be available on that plan. Do not reduce the existing Kpanel user's permissions: the panel needs writes. If using the existing credential within the same customer-operated hosting account, recognize that read-only behavior is enforced by the adapter's fixed parameterized queries, not by the credential's SQL grants. Keep it on that host and never send the database URL to Frosvo. A separate restricted reader remains preferable where the hosting platform supports one. See [Hostinger's database limits](https://www.hostinger.com/support/1583542-how-to-create-a-new-mysql-database-in-hostinger/).

## Configure the gateway

1. Copy the supplied gateway directory to the Kpanel host. Use its installed Node runtime and Kpanel's existing generated Prisma client. Prisma 7 uses its MariaDB driver adapter; Prisma 5 uses its native client with a one-connection pool and bounded timeouts. Prisma 5 defaults to one Tokio worker in this gateway process to respect shared-hosting thread budgets. Do not install or regenerate Kpanel's client inside Frosvo's application dependencies.
2. Set `FROSVO_GATEWAY_ADAPTER=kpanel`, `FROSVO_KPANEL_ROOT` to the absolute Kpanel project directory, and `FROSVO_KPANEL_DATABASE_URL` to `mysql://frosvo_tracking:<encoded-password>@127.0.0.1:3306/kpanel`. This built-in adapter accepts loopback database addresses only; do not expose the database publicly.
3. Set `FROSVO_GATEWAY_SCOPES=order.lookup,invoice.lookup,service.status,ticket.status`. Configure a gateway signing secret, durable replay storage and an HTTPS reverse proxy as described in the gateway guide. Run `node integrations/customer-gateway/server.cjs` under your process supervisor. No gateway daemon is installed automatically.
4. Configure that HTTPS URL and matching secret in Frosvo's gateway settings; run **Test connection**. Enable [visitor tracking](/docs/visitor-order-and-service-tracking) for the website.
5. Use Kpanel's server-signed identity integration. The external account ID must be the exact Kpanel CUID, optionally prefixed `kpanel:`. A verified email-only session is also supported. When both are supplied they must name the same active, email-verified Kpanel account. Never sign an ID or email supplied by an untrusted browser.

Use exact public `orderNumber`, `invoiceNumber`, `serviceNumber` or `ticketNumber` references; an exact internal record ID is also accepted. References are scoped to the chosen type and account. No partial or account-wide search is exposed. Draft invoices and suspended/closed or email-unverified accounts are refused.

## What customers see

Results contain only a generic record title, reference, status and actual source update time. Passwords, IPs, ticket subjects/messages, payment details and internal notes are absent. Known Kpanel statuses are passed through; new statuses appear as **Unknown**. A paid invoice does not imply an active service. Source failures show unavailable status rather than inventing a successful lookup.

## Verify before customer use

Test one owned account and one different account against all four record types. Verify cross-account denial, email/ID mismatch denial, draft hiding, suspended-account denial and unknown statuses. Confirm UTC database timestamp handling on your installation, HTTPS, signing-key rotation, replay persistence across restarts, access revocation during a lookup and private logging. Do not use a customer's real ticket or invoice for these checks.

Developer acceptance: `node --test tests/kpanel-tracking.test.cjs`. The opt-in `tests/kpanel-tracking-database.cjs` needs an explicit local `TEST_DATABASE_URL` naming `frosvo_test` and an absolute `KPANEL_TEST_ROOT`. It creates and removes its own complete-schema database and column-restricted reader. Both the Prisma 7 checkout and an isolated generated Prisma 5.22 client from the live schema were verified. Local schema/HTTP acceptance does not prove your live deployment's credentials, DNS, proxy or identity configuration.

## Passenger-managed hosting

For a separate Passenger-managed Node app, use the supplied gateway directory as the app root and `app.js` as its startup file. Keep Kpanel's existing generated `server.js`, application root and runtime unchanged. `passenger.cjs` requires an absolute `FROSVO_GATEWAY_CONFIG` path to a private regular environment file (mode 600 on Linux), `FROSVO_GATEWAY_ADAPTER=kpanel` and an already initialized absolute `FROSVO_GATEWAY_REPLAY_DB`. It refuses custom replay modules and missing retained storage. Passenger manages the first HTTP listener; this entry does not launch a detached daemon.

The private configuration includes the gateway secret/scopes, Kpanel root, database URL and replay namespace/path. Store it outside any public document root; do not commit it or place it in a deploy ZIP. Configure a dedicated HTTPS application mapping through the hosting provider, verify its certificate and signed ping, and then configure that URL in Frosvo. A copied private package is staging, not a live endpoint. Managed-entry process/restart acceptance is `node --test tests/gateway-managed-startup.test.cjs`; real Passenger routing still needs deployment verification.

## Common questions

### Does this gateway receive Kpanel admin or customer passwords?

No customer or admin login passwords are selected or returned. Database credentials remain on your hosting account; the adapter selects only the tracking columns and omits ticket messages and private notes.

### Can a visitor enter another customer's email or invoice number?

An entered email does not establish identity. The signed verified account and the record's userId must match. Another customer's reference is refused.
