Skip to contentSkip to content
Developers

Kpanel visitor tracking through your gateway

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

Last updated

The supplied integrations/customer-gateway/kpanel-adapter.cjs runs on your Kpanel host through the customer-owned 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.

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 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.

Frequently asked 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.