@harshankur/viewcounter 3.0.0

package/.env.example

@@ -0,0 +1,115 @@
+# ViewCounter configuration
+#
+# Copy to `.env` and fill in. Every value here can also come from dbInfo.json /
+# allowed.json, which take precedence — see config/index.js for the resolution
+# order (config file > environment variable > built-in default).
+#
+# Anything marked Required is checked at startup in production: the server
+# refuses to boot rather than run on a guessable default.
+
+# ---------------------------------------------------------------------------
+# Required in production
+# ---------------------------------------------------------------------------
+
+# Database credentials. The server will not start in production while these are
+# still root with an empty password.
+DB_USER=viewcounter
+DB_PASSWORD=
+
+# Database to write into. Created automatically when DB_MODE=create.
+DB_NAME=viewcounterdb
+
+# Apps allowed to record views, comma-separated. This is an authorization
+# boundary, not a convenience list: an appId absent from it is rejected, and it
+# also determines which tables get created in `create` mode. The placeholder
+# `example_app` is refused in production.
+ALLOWED_APP_IDS=blog,portfolio
+
+# Browser origins permitted to call the write endpoints, comma-separated.
+# Required in production: without it, CORS blocks every browser caller. Use the
+# exact scheme+host+port, no trailing slash.
+CORS_ORIGINS=https://example.com,https://www.example.com
+
+# ---------------------------------------------------------------------------
+# Recommended
+# ---------------------------------------------------------------------------
+
+# Credentials for the analytics READ endpoints (/stats, /views, /trends, ...),
+# comma-separated, sent by clients as the `x-api-key` header. Keys shorter than
+# 32 characters are ignored. List several so one consumer's key can be revoked
+# without rotating everyone else's. With none set, the read API returns 503 —
+# it fails closed rather than serving your analytics to anyone who asks.
+#   Generate one with:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+READ_API_KEYS=
+
+# Credential for the ADMIN API (POST /apps, which provisions a new app and
+# creates its table). A separate tier from READ_API_KEYS on purpose: leaking a
+# tenant's read key must never confer the ability to create apps, and revoking
+# one tier must not force rotating the other. Leave unset to disable
+# provisioning over HTTP entirely.
+ADMIN_API_KEYS=
+
+# Number of reverse proxies in front of this service, or a comma-separated list
+# of trusted proxy CIDRs. Leave unset if nothing proxies it.
+#
+# Do NOT set this to `true`. Trusting every hop means any caller can send their
+# own X-Forwarded-For and be believed, which forges geolocation, inflates
+# unique-visitor counts, and lets an attacker rotate the rate-limiter key to
+# bypass it entirely. `true` and `*` are downgraded to a single hop with a
+# warning. Your proxy must set X-Forwarded-For; X-Real-IP alone is not read.
+#TRUST_PROXY=1
+
+# Where the visitor-hash secret is persisted. Generated with a CSPRNG on first
+# run at mode 0600. This secret is the only reason a stored visitor hash cannot
+# be brute-forced back to the IP that produced it, so back it up with the same
+# care as the database password — and note that replacing it makes existing
+# hashes unlinkable from new ones (which is deliberate, not a bug).
+#VISITOR_SECRET_PATH=/var/lib/viewcounter/.visitor-secret
+
+# Supply the secret directly instead of persisting a file. Useful for
+# containers with a read-only filesystem or an external secrets manager.
+#VISITOR_SECRET=
+
+# ---------------------------------------------------------------------------
+# Optional
+# ---------------------------------------------------------------------------
+
+# `connect` uses an existing database; `create` creates the database and one
+# table per allowed appId on startup. Default: connect.
+DB_MODE=connect
+
+DB_HOST=127.0.0.1
+DB_PORT=3306
+
+# Port the HTTP server listens on. Default: 3030.
+PORT=3030
+
+# Defaults to `production`. Set to `development` for local work. This does not
+# change what is returned to callers — errors never include internal detail in
+# any environment — but it does relax the startup checks above.
+#NODE_ENV=production
+
+# Operational log verbosity: debug | info | warn | error | silent.
+# The audit trail for state-mutating actions is emitted regardless.
+LOG_LEVEL=info
+
+# Rate limiting, applied per client IP across all endpoints. This is the
+# single-abuser backstop.
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
+# Per-app ceiling on the write endpoints, within the same window. Stops one
+# tenant consuming the budget every other tenant on the instance depends on.
+# Keyed on appId only, so it cannot be bypassed by rotating IP addresses.
+# Set 0 to disable (sensible for a single-tenant deployment).
+APP_RATE_LIMIT_MAX=1000
+
+# How long a visitor counts as "the same visitor" for deduplication, in hours.
+# Also the rotation period for the visitor hash: after this window the same
+# person hashes differently, so their visits cannot be linked across windows.
+# Set 0 to disable deduplication (the hash still rotates hourly).
+UNIQUE_VISITOR_WINDOW_HOURS=24
+
+# Device size buckets accepted on /registerView, comma-separated.
+#ALLOWED_DEVICE_SIZES=small,medium,large

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harsh Ankur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.