Security & Encryption

Understand the encryption boundary

Hosted BLUE/staging and GREEN/production share production PostgreSQL, Valkey, signing/encryption material and account records. Preview actions can change shared data; hosted QA is restricted to authorized Nexova records and sandbox payment connections. Browser sign-in storage is host-specific; the one-active-session policy applies across slots. Both slots remain on the same host, so this is not high availability or full disaster recovery. Isolated restore drills use their own separate fixtures.

Hosted PostgreSQL, Valkey, core application proxy links and API metrics use verified internal TLS, including server certificate names. Other monitoring transport remains a separate review scope. Self-hosted installations must configure their own transport and environment boundaries; visitor HTTPS alone does not establish all-link encryption.

PermitCore protects license storage, account access, and tenant boundaries in different ways. “Zero-knowledge” describes the default browser-created license workflow; it does not describe every operation the service performs.

Platform SuperAdmins have privileged operational access across tenants. This does not supply an unknown browser passphrase, but server-managed delivery material and opt-in escrow are recoverable by the service. Escrow recovery is audited and attempts to notify active CompanyAdmins; notification delivery is not guaranteed. The browser, delivered JavaScript and deployment secrets remain part of the trust boundary.

WorkflowWhat happensWho can recover the key?
Admin-created licenseYour browser generates and encrypts the key with your passphrase before submitting ciphertext and a lookup hash.Someone with the passphrase or your configured recovery material.
Validation / activationThe app sends the plaintext license key over HTTPS in the POST body. The server hashes it for lookup without decrypting stored ciphertext.This operation does not recover your passphrase or decrypt the stored key.
Store-issued licenseThe server generates the key for checkout delivery and stores protected delivery material using server-managed encryption.The service can decrypt that material for authorized delivery or customer key reveal.
Optional passphrase escrowYou explicitly send your passphrase for encryption with a server-managed key.The service can recover it. Enabling escrow changes the zero-knowledge boundary.

Keep license keys, API keys, passphrases, and webhook secrets out of application logs and analytics. Using POST avoids URL/access-log exposure; it does not stop your own code or middleware from logging request bodies.

The supplied API gateway, Public, Admin and configured outer NPM access formats retain generated request IDs and operational metadata, but omit request paths, query strings, Referer, credentials and bodies. Client IP addresses remain operational data. Reset-mail, tenant SSO exchange and global API failure records use bounded type/status/code metadata without raw exception messages or private reset URLs; global failures use route templates rather than bound paths. Verification, welcome, Store/Portal recovery, OTP and license-delivery mail failures also omit raw mail payloads. License-delivery retries receive a safe exception so the job error record cannot echo the key/body; intended emails and existing retry settings are retained. Reviewed billing/price administration, Stripe webhook and dunning/expiry/trial-reminder error records use the same bounded diagnostics without changing charges, refunds, grace or retry decisions. Reviewed contact/admin-test, GDPR, escrow, self-host and digest failure records also omit raw exception payloads, preserving existing operation results/audits and best-effort notification behavior. Failed mail is not guaranteed delivery. Reviewed license/webhook, metering, analytics, expiry, retention and self-host job failure records also omit raw exception payloads. Existing responses, retry/fallback and business decisions remain. Operational identifiers/emails/IPs, lower-level library logs, job arguments, stored fields, external proxies and older records remain separate review scopes. Treat emailed reset, verification and download links as private; referrer protection does not remove the original URL from browser history or every logging layer.

Database and SMTP connection tests return safe operation messages instead of raw provider exceptions. Check the saved server, port, credentials and TLS settings; SMTP also needs a valid sender address. A missing mail provider remains a specific configuration error. Successful test sending is unchanged and confirms SMTP acceptance, not inbox arrival. Reviewed startup and installation catch records retain bounded code/type diagnostics without raw exception text. A skipped startup task is not successful migration or deployment; lower-level library logs and older records remain separate review scopes.

The supplied Console/File log outputs omit raw selected HTTP, database and authentication library diagnostics, plus attached exception payloads, while retaining bounded code/status metadata. Other custom sinks, job history and proxy error logs remain separate. Existing file-count/size rotation is not a calendar erasure or backup-deletion guarantee; this change does not purge old data.

Configured nginx error outputs for Public, Admin, gateway and outer NPM retain only time, hop, severity and a fixed failure category; raw URL/message payloads are discarded before storage. The isolated collector must be healthy before ingress upgrades. Error delivery is best effort: a logging outage must not stop customer requests. Direct subprocess/library output, custom overrides, external proxies and old records remain separate; no history is purged.

Normal Certbot diagnostic files omit messages, arguments, private-key data and exception text. New records contain only time, fixed logger family, level, an exception flag and a diagnostic category. Console output and command results keep their behavior; original rotation and historical records remain. This is not certificate issuance or renewal acceptance; custom entrypoints and direct process streams are outside this file-only policy.

NPM application logger channels omit raw certificate objects, commands, credentials and error payloads. Existing severity, scope and fixed operation categories remain. Command results and errors, certificate operations and initial-admin login are unchanged. Direct subprocess/library output and stored audit/history remain separate; this change does not purge records.

Protected API 401 exception responses preserve fixed sign-in explanations and otherwise use a generic authentication message instead of raw exception text. Upgraded Store mail deployments can queue only an outbox reference; the worker uses the original purchase download snapshot. Existing queued jobs remain compatible and may retain older arguments. Outbox data, legacy history and queue recovery remain separate review scopes.

Self-host check-in failure audits use bounded diagnostics in Details and an independent tenant-scoped save, without retrying failed check-in writes. If audit storage is unavailable, the existing response is retained and a safe warning records the failed audit attempt. This is best-effort failure auditing; historical records and other error fields are not rewritten.

In account exports, a Store-issued license's EncryptedKey can be a store-order: reference rather than passphrase-decryptable ciphertext. The ordinary ZIP excludes order delivery material and server encryption secrets; it cannot recover those Store key values by itself. Preserve delivered keys and arrange authorized recovery while the service is available. A standalone bulk Store-key recovery package is not currently provided by this ZIP.

Protect your account

For a configured SuperAdmin MFA rollout, the notice shows a fixed deadline with 14 days from activation to enroll. Open Set up MFA, scan the locally generated QR code (or enter the manual time-based key), save the one-time recovery codes separately, then verify the six-digit code. After the deadline, unenrolled SuperAdmins must finish setup before business access, including existing sessions. Company accounts retain their existing tenant policy.

If an unfinished setup key or recovery codes were exposed, use Restart setup. This generates a new authenticator key and recovery codes and invalidates the previous unfinished set. Reloading the page does not redisplay old setup material; starting setup again generates a fresh set. Existing enabled authenticators cannot be replaced this way.

If your authenticator is lost, enter a saved recovery code with your password at sign-in. Each code works once. To replace an enabled authenticator, first disable it in Settings → Security using both your password and an existing authenticator or recovery code. Password reset alone does not remove MFA. Never send recovery codes to support in chat.

Sign-in and authenticated API responses instruct browsers and proxies not to store them. API writes and authorization failures use the same no-store policy. Public catalog reads can retain a short cache lifetime; unchanged frontend scripts use separate content-derived cache addresses. These response rules do not clear sign-in storage or change the 30-minute Admin inactivity policy.

  1. Enable MFA in Settings → Security and save the backup codes separately from your authenticator.
  2. Give teammates custom roles containing only the menus and actions they need. See Account & team.
  3. Keep admin API keys on trusted servers, in a secret store. Never ship them inside a desktop app, browser bundle, mobile app, or public repository.
  4. Store your encryption passphrase in a password manager and configure recovery before distributing keys.
  5. Subscribe to license.abuse_suspected webhooks and review unusual activation or login activity.

Feature availability depends on your plan. A hidden menu can also mean your custom role does not have access; ask a Company Admin to check both before troubleshooting an integration.

Browser-created licenses and passphrase recovery

General-purpose random-key snippets are educational examples, not issued PermitCore licenses or offline tokens. Use Admin license creation or Store fulfillment for issuance. See the C#, Python and Node.js key-generation guide for the distinction between a random identifier, a server record and signed proof.

  1. The browser creates a random key in the format PERMIT-XXXX-XXXX-XXXX-XXXX.
  2. PBKDF2-SHA256 derives a 256-bit encryption key from your passphrase and tenant salt, using 600,000 iterations.
  3. AES-256-GCM encrypts the license key with a random IV. The browser sends ciphertext, IV, and the SHA-256 lookup input.
  4. The server applies HMAC-SHA256 with a server-held secret before storing the lookup value.
  5. For validation, the server receives the customer-supplied plaintext key transiently, recomputes that lookup value, and checks the license restrictions.

A stolen database alone does not contain the passphrase needed to decrypt browser-created keys, or the server secret needed to check guesses against the HMAC lookup values. Protecting the browser, passphrase, and server secrets remains necessary.

Keep the original passphrase

The passphrase is needed to reveal or copy encrypted keys. Changing your account password does not change it. Losing it does not stop online validation of keys your customers already hold, but you may lose the ability to retrieve their plaintext from the admin panel.

Recovery key

Under Settings → Security → Passphrase Recovery, configure the browser-based recovery option and save the generated recovery key securely. Recovery requires the matching recovery material; simply resetting your login password cannot decrypt old license ciphertext.

Optional escrow

Escrow sends the passphrase to the service for server-managed encryption. Use it only if this recovery model fits your organization's requirements. It allows service-side recovery and therefore removes the zero-knowledge property for that passphrase.

Technical security reference

AreaImplementationIntegration consequence
License ciphertextAES-256-GCM; browser PBKDF2-SHA256 derivationRetain the passphrase and recovery material.
License lookupSHA-256 followed by server-keyed HMAC-SHA256Send the original key in an HTTPS POST body.
PasswordsArgon2idUse unique passwords and MFA.
Access tokensRS256 JWT signatures and rotating refresh tokensUse the supported login/refresh flow; never embed a signing secret in clients.
Offline tokensECDSA P-256 / SHA-256 signaturesVerify with the trusted public key and enforce token expiry/binding.
Tenant isolationApplication authorization plus PostgreSQL row-level policies on protected tenant tablesAdmin operations remain scoped to your tenant. Self-hosted installations must use the restricted app database role.
Webhook authenticityHMAC-SHA256 over the raw bodyVerify the signature and deduplicate event IDs. A signature alone does not prevent replay.

Rate limits

Public endpoints have per-IP controls in addition to the tenant's plan allowance and per-license abuse checks. A higher plan allowance does not remove a per-IP restriction. Handle HTTP 429, honor Retry-After when present, and avoid synchronizing every customer's checks at the same moment. See error handling.

Operational security

Audit retention commits each cleanup batch together with a count-only audit receipt. A failed batch rolls back and the job reports incomplete work; earlier committed receipts remain. Tenant cleanup follows plan windows. System audit cleanup requires a separate operator switch, disabled by default; deploying an update does not enable it. Ordinary application access still cannot delete audit rows. This is not an immutable archive or complete erasure guarantee.

Activation history minimization clears IP, country, city and end-user email on records older than the configured window (365 days by default), including records whose IP is already empty. The daily job preserves activation rows, device binding, license relationships and usage counters. Retained device/software metadata, old backups and job-failure handling remain separate; this is not complete anonymization or an exact calendar-erasure guarantee.

Production uses HTTPS and security headers. New backup generations stream database dumps into GPG encryption and verify off-site copies before expiry. New deployment bundles include the encrypted database and selected configuration bytes with a verified manifest. Complete new copies become eligible after 30 days and after verification; holds, failed verification and the newest deployment recovery point can extend retention. Legacy generations remain retained separately under operator-managed review; old gzip compression is not encryption. An isolated data restore does not prove full application recovery. The public status page reports a database-connectivity probe, not independent checkout, email or full license-flow monitoring. For current infrastructure and data-residency information, see the security page. For data-processing terms and subprocessors, see the DPA and privacy policy.

Report a suspected vulnerability to info@permitcore.dev. Include affected URLs, reproduction steps, and impact; do not include real customer keys or unrelated personal data.

Backups and business continuity

Backups recover account data. Offline tokens and signing-key export address whether your software can keep verifying licenses without a live service. Plan for these separately.

Your own recovery package

  • Keep account-data exports and license-key exports separately, along with the passphrase/recovery material needed to use encrypted keys. The account-data ZIP includes encrypted license values, IVs and salt, not plaintext keys or private signing keys. It also includes customer/Store/payment records, usage, configuration and historical public verification keys; asset URLs are references.
  • Keep your product identifiers, integration configuration, and trusted signing public keys with your release records.
  • Test the offline flow before a customer needs it; a machine without network access cannot fetch its first public key.
  • For self-hosting, back up both the database and required deployment secrets, then test a restore in an isolated environment.

Available continuity options

OptionWhat it providesLimit
Offline activation (Professional+)A signed token verified on the customer's machine.Only works until that token expires and cannot learn about revocation while fully offline.
Signing-key export (all plans, including Free)Your own copy of signing material for independent issuance.Protect the private key; anyone holding it can issue tokens trusted by your software.
Self-hosting (Enterprise)Your own deployment, database, and operational control.You operate and recover the infrastructure. See the deployment guide.

Rotation versus compromise

Read the signing-key rotation guide before changing a signer. Rotate activates the new signer immediately; deliver its approved public key through your trusted app/configuration update process. Regeneration does not update disconnected applications or mark every historical deprecated key compromised.

The exit plan and recovery checklist separates offline proof, encrypted data exports, signing-key recovery and the services your app still needs. The account-data ZIP is a selected export, not a restorable database backup.

Take your keys anytime: signing-key export and the associated rotation, regeneration and history tools are available on every plan, including Free, to your CompanyAdmin. In Settings → Security → Business Continuity, read the warning and acknowledge responsibility before exporting. The private PKCS8 key is a vendor secret; customer apps receive only trusted public verification keys. Hosted offline-token generation remains subject to its separate plan entitlement, and self-hosting remains Enterprise.

For an end-of-life release, inventory sign-in, activation, refresh, downloads and hosted-feature dependencies. Test reinstalls on a clean device after the signed token deadline with your endpoints unavailable. A final offline build is your own release strategy; an exported key or backup does not distribute that build. See the software ownership and shutdown planning guide.

Rotate creates a new active signing key and keeps the previous key available as deprecated for verifying older tokens. Regenerate marks the prior key compromised and revokes tracked tokens. Online verification can apply that change immediately; a disconnected app with an old public key cannot discover it until it reconnects or its token expires. Preserve the relationship between a token's kid and its verification key.

These mechanisms do not make every existing online license permanently offline-capable. Issue and distribute the required tokens or deploy your continuity solution before relying on it.

Company single sign-on

Company SSO supports tenant-configured Google, Microsoft or GitHub sign-in for your team. It is separate from customer license validation and Store customer accounts.

  1. Open Settings → SSO and choose an available provider.
  2. Create the corresponding application in that provider's console.
  3. Copy the redirect URI shown in PermitCore exactly into the provider settings.
  4. Enter the client ID and secret, enter the required email domain, and save.
  5. Create the teammate's PermitCore record first, or explicitly enable Auto-provision and select its required default role.
  6. Test with a non-owner account before rolling it out to the team.

With Auto-provision off, only existing active tenant users can sign in. When you explicitly enable it, a matching-domain user can be created with the configured default role; missing or deleted roles reject provisioning. Require organization SSO blocks password and general social sign-in for tenant users, including renewal of sessions without a verified required-provider binding. Only enabled required SSO providers are accepted. Existing sessions without a binding need one fresh SSO sign-in. Test the provider before enabling and keep an administrator recovery process. API keys and authorized support impersonation retain their separate rules.

Google profile lookup sends its provider access token in the Authorization header over HTTPS. PermitCore returns a short-lived one-time sign-in code to the Admin callback and redeems it through a POST request; raw local access and refresh tokens are not put in the callback URL. Existing client IDs, redirect URIs and configured sign-in flows remain unchanged.

Country and IP restrictions

Set Allowed Countries in a license's metadata using comma-separated ISO country codes such as US, DE, GB. An empty list means no country restriction. Both validate and activate check the configured restrictions.

The country is inferred from the request IP. A VPN or proxy can change the apparent country; this is not proof of residence or a complete compliance control. If a legitimate customer is blocked, check their exit IP and the license's allowed countries before changing the policy. IP allowlists provide a separate network restriction.

External checks and API discovery

Frontend deployment images support an HTTP Content Security Policy in report-only or enforced mode. The target allows the Blazor WebAssembly runtime without general script eval or inline event handlers; report-only observes the target while retaining existing protections. Self-hosted operators must verify their API origin and browser/payment flows before enforcement. Dynamic branding still uses inline styles and HTTPS images.

Browser policy diagnostics go to the first-party API. Only grouped surface, directive, source-family, disposition, counts and timestamps are retained in memory for up to 24 hours. Raw URLs, query parameters, tokens and script samples are discarded. A SuperAdmin session can inspect the no-store summary; API keys cannot. These untrusted diagnostics are not an audit or proof that every browser sent a report.

The hosted service requires TLS 1.2 or newer, with TLS 1.3 enabled. Self-hosted operators manage their own TLS edge. The Security page records dated, host-specific SSL Labs and Mozilla Observatory results; these are not an application audit or certification.

The gateway root GET / returns public JSON discovery links with no authentication or caching. This static response does not check API availability, the database or payments. Use /healthz for application readiness and /api/status for the separately documented database probe. Unknown application routes retain their existing behavior.