Hardening a KahunaCart store

What a production store needs beyond the defaults: web-server rules for the directories no visitor may fetch, delivery methods that hand a file transfer to the web server, correct visitor counting behind a CDN, order link expiry, and where to report a vulnerability. The defaults are safe on Apache and on a store with nothing in front of it.

Before you begin

• Have access to the web server configuration, or to whoever does.
• Be able to run curl against the store from outside the server.

Deny the data directories

KahunaCart keeps four things under user/ that no visitor may fetch directly.

On first use, KahunaCart writes a deny-all .htaccess and an empty index.html into the database directory, the files root and the bundles folder, and chmods the SQLite file to 0640. That covers Apache only. nginx and Caddy ignore .htaccess and serve the files until you add rules.

Test it from outside the server, before you take orders:

curl -sI https://your-site.com/user/data/kahunacart/db/kahunacart.sqlite | head -1
curl -sI https://your-site.com/user/data/kahunacart/files/ | head -1

Anything other than 403 or 404 is a problem.

Move the data directories out of the document root

This is the fix to prefer.

database:
  sqlite:
    path: '/var/lib/kahunacart/kahunacart.sqlite'
downloads:
  path: '/var/lib/kahunacart/files'

PHP still needs read and write access to both. The xaccel and xsendfile delivery methods still work.

Deny them on nginx

Add this to the server block, above the PHP location:

# The whole KahunaCart data tree: database, WAL files, downloadable files.
location ^~ /user/data/kahunacart/ {
    deny all;
    return 404;
}

# Belt and braces for the database itself, wherever it ends up.
location ~* \.(sqlite|sqlite3|db|db-wal|db-shm)$ {
    deny all;
    return 404;
}

^~ stops a later location ~ \.php$ claiming a URL under that prefix. return 404 rather than 403 so the path does not confirm it exists.

Deny them on Caddy

In the site block:

example.com {
    root * /var/www/example.com

    @kahunacart_data path /user/data/kahunacart/*
    respond @kahunacart_data 404

    @databases path *.sqlite *.sqlite3 *.db *.db-wal *.db-shm
    respond @databases 404

    php_fastcgi unix//run/php/php8.3-fpm.sock
    file_server
}

Matchers are evaluated in order, so both respond directives must come before file_server.

Deny them on Apache

There is nothing to do, as long as AllowOverride lets Apache read the shipped .htaccess files. If your vhost sets AllowOverride None, put the equivalent in the vhost:

<DirectoryMatch "^/var/www/example\.com/user/data/kahunacart/">
    Require all denied
</DirectoryMatch>

Serve downloads through the web server

downloads.method decides who pushes the bytes.

The php method streams in fixed chunks and honours a Range request, so memory is not the cost. The cost is that one 400 MB download holds one PHP process for as long as the customer's connection lasts, and a handful of slow downloads on a small worker pool can starve the site.

xaccel and xsendfile hand the file to the web server and exit immediately, with no memory or worker cost and the server's own range handling.

Configure X-Accel-Redirect on nginx

1. Add an internal location whose prefix matches downloads.xaccel_prefix, default /kahunacart-files/, and whose alias points at the files root:

location /kahunacart-files/ {
    internal;
    alias /var/lib/kahunacart/files/;
}

2. Set downloads.method to xaccel.

Keep the trailing slashes on both the location and the alias.

Configure X-Sendfile on Apache

1. Install mod_xsendfile.
2. Add both directives to the server or vhost configuration:

XSendFile On
XSendFilePath /var/lib/kahunacart/files

3. Set downloads.method to xsendfile.

XSendFilePath is mandatory. Point it at the files root and nothing wider. It is a server- or vhost-level directive and cannot go in .htaccess. LiteSpeed implements the same header natively and usually needs no configuration.

Full snippets, including what a misconfigured method looks like from the customer's side, are in Digital products → Delivery methods.

Restrict where downloadable files may live

downloads.allowed_roots is the list of directories a purchased file may be served from. It defaults to [downloads.path].

A file is refused at upload if the bytes did not land inside an allowed root, and again at delivery if the path no longer resolves inside one. Both comparisons go through realpath(), so a symlink, a .. or a bind mount is followed before anything is compared.

Add a second root when files live in two places, usually during a migration:

downloads:
  path: '/var/lib/kahunacart/files'
  allowed_roots:
    - '/var/lib/kahunacart/files'
    - '/srv/legacy-downloads'

Absolute paths and Grav stream URIs both work. A configured root that does not exist is dropped, not created.

Audit what a store holds:

bin/plugin kahunacart downloads:check

It lists every product file that cannot be delivered, says whether the bytes are missing or only outside the roots, and exits non-zero when it found something. See CLI → downloads:check.

Order links expire

The receipt, the invoice, the invoice PDF and the pay page are each reached by a signed link that stops working.

Signatures come from a per-site secret that KahunaCart creates once, from 32 random bytes, and keeps in its own database. To rotate it, delete the security.secret row from kahunacart_settings; that invalidates every link the store has already emailed.

Three things open an order page: a valid unexpired link, a logged-in customer whose id is on the order, or an admin holding kahunacart.orders.view. Anything else gets an expired-link page with a button that emails a fresh one to the address on the order. That page shows nothing about the order, whether or not the hash is real.

A pay link also carries a deadline on the order itself, written when the link is issued. When a customer says their pay link no longer works, open the order in the admin and press Reissue, or Reissue & email to send it straight to them. See Orders and the admin → Pay links.

Rate limits

Every route a visitor can hammer is counted per client address in a named bucket.

Override any of them under security.rate_limits:

security:
  rate_limits:
    checkout: { limit: 5, window: 60 }
    download: { limit: 0, window: 60 }   # 0 turns the bucket off

A limited request answers 429 with a Retry-After header, and is logged at info level.

The three buckets that answer an order hash (order_lookup, invoice and link_request) are counted twice: once per address and once per order, with the same limit on each. That stops one host working through hashes, and a botnet working on a single hash from many addresses.

Counts live in kahunacart_rate_limits in the store's own database, so every PHP worker and every node counts against the same rows. Old rows are swept automatically and need no cron.

Trusted proxies

Behind Cloudflare, a load balancer, or an ingress controller, REMOTE_ADDR is the proxy and every visitor shares one rate-limit bucket. Name the proxies:

security:
  trusted_proxies:
    - '173.245.48.0/20'
    - '103.21.244.0/22'
    - '2400:cb00::/32'

X-Forwarded-For is read only when the connection itself came from an address on that list. With the list empty, the default, the header is ignored.

IPs and CIDR ranges in either family are accepted. The chain is walked from the right past every trusted hop, and the first untrusted one is the client. A chain that is trusted the whole way down falls back to its leftmost entry.

To check it, hammer one endpoint through the proxy from two different addresses. They should get two budgets.

Site address for emailed links

Every link in an email (a sign-in link, a set-password link, a cart link, a receipt) has to start with the store's address. A request's address comes from its Host header, and on a server that answers any host, the visitor gets to pick it. So KahunaCart never builds an emailed link from a request's host unless the store has said that host is its own. It looks, in this order, for:

1. system.custom_base_url. When it is set, every link uses it.
2. The entry of security.site_urls whose host the customer was on, so a store served on several of its own addresses links each customer to the one they used.
3. The first entry of security.site_urls. Anything sent from the command line uses this one too.
4. With neither setting filled in, the address of a signed-in administrator's own request, so an invitation sent from the admin still works on a new store.

security:
  site_urls:
    - 'https://shop.example.com'
    - 'https://www.shop.example.com'

The admin field is Site Addresses under Settings → Security. An entry with no scheme is read as https://.

Most stores never type it. While both settings are empty, the address a signed-in administrator is using is recorded into security.site_urls the first time they open the Admin Next dashboard or KahunaCart's admin page, or save KahunaCart's settings. The account has to be signed in to the admin with admin.super or api.access. An API key with scopes never counts, and neither does anything run from the command line. The address goes into the same file the admin's settings save would write, one notice line in the Grav log says what was recorded and by whom, and it is recorded only once, never over a value that is already there.

Only an HTTPS address is recorded. A development address (localhost, an IP, or a name ending in .test, .local and the like) never is, because settings saved on a laptop often get committed and deployed. A public store answering on plain HTTP is usually one whose HTTPS is not set up yet. In either case, add the address customers use by hand.

With no trusted address, sign-in, set-password and cart links are not sent. The visitor sees the same "check your email" page as always, so the form gives nothing away, and the reason goes to the Grav log and the job's failure record. Other emails still go out, with links that carry no address. A job held back like this is retried after a minute and then two, and after that only once the store has an address: the worker releases every one of them at the start of its next run after it sees an address, so they go out then instead of never. A worker started with --daemon sees the new address when it next restarts. Until the store names its address, the dashboard shows an alert and bin/plugin kahunacart check fails its site address check.

bin/plugin kahunacart check runs the database, download-roots, trusted-proxies and site-address checks from this page with every other pre-launch check. See Going live.

Agent endpoints

Agentic commerce adds public URLs that machines call rather than people: /.well-known/ucp at the site root, and {base}/feeds/*, {base}/mcp and {base}/ucp/* under the storefront. Each one answers 404 until its switch is on.

Let them through your CDN

KahunaCart blocks no user agent, so Google's agents, Visa Intelligent Commerce, Mastercard Agent Pay and Cloudflare's signed agents (RFC 9421 Signature-Agent) reach the store as ordinary clients. Your CDN may not be so relaxed.

• Keep these four paths out of "block AI bots" rules, bot-fight modes and JavaScript challenges. An agent cannot solve a challenge page, and a feed fetch that gets one fails in Merchant Center's diagnostics with no hint why.
• Allow verified bots and signed agents at the CDN if it offers the setting.
• Set security.trusted_proxies. Agent traffic arrives from a few shared addresses, and behind a proxy with the list empty every platform shares one bucket with every shopper. A UCP request that has authenticated (a valid API key or a verified signature) is counted per platform and session instead of per address.
• *Do not cache {base}/mcp or `{base}/ucp/.** The feeds and/.well-known/ucpsend their own publicCache-Control` and may be cached as sent.

What protects each endpoint

Semantic search sends text to a provider

With semantic search on, every product's title, summary, description, category names, tags, brand and attribute and option values go to the embedding provider, and so does every search term a shopper types. Customer data never does. Nothing from an order, a cart or an account is embedded.

• To keep it all on your server, point base_url at Ollama on the same host.
• The API key is stored encrypted, like a payment provider's secret. env:NAME keeps it out of the config files altogether.
• A shopper never waits on a batch. Embedding runs only on the job worker, and a search waits at most query_timeout seconds for the provider before answering from keywords.
• The vectors live in the product index under user/data/kahunacart/search/, which the deny rules above already cover.

Session-built pages are never shared-cacheable

The cart, the checkout, every receipt, the invoice, the pay page, the expired-link page and the whole account area answer with Cache-Control: private, no-store, max-age=0. Catalog pages stay cacheable until the visitor has a cart or an account, at which point they become private, no-cache. While the store is coming soon or paused, every page that would otherwise be cached is private, no-cache, and the pages above keep private, no-store; purge your CDN after you change the status. See Configuration → Store status.

Grav's default is system.pages.expires: 604800, which would otherwise put a week-long max-age on a page built from somebody's session, and a CDN would hand it to the next visitor.

Reporting a vulnerability

Do not open a public issue for a security problem; a report on the public tracker is a disclosure before there is a fix. Report privately to [email protected] with:

• The KahunaCart version, from bin/plugin kahunacart status or blueprints.yaml.
• The Grav version and the web server.
• What an attacker gets, and the smallest set of steps that shows it.
• Whether the store needs to be configured unusually for it to work.

You get an acknowledgement, then an assessment once the report has been reproduced. Give a fix a reasonable window before disclosing publicly. The advisory credits you unless you ask it not to.

Related

• Going live
• Agentic commerce
• Configuration
• Digital products and downloads
• CLI
• Troubleshooting
• Demo store