Blackcap requires a Microwave Pie signed license credential. The credential is self-describing and is verified locally with Ed25519, so a correctly licensed installation can start and continue operating without access to tracking.microwavepie.com.

Credential and trust model

The user-facing credential is MPL1.<header>.<claims>.<signature>. Blackcap accepts only alg=EdDSA, typ=MPL, the blackcap application claim, a recognized scope, a supported signed claim schema, and a signature from a trusted Microwave Pie signing key. Production trust roots are shipped with Blackcap in inky_admin/licensing/trusted_public_keys.json, which maps signing key IDs to Base64 DER/X.509 Ed25519 public keys. BLACKCAP_LICENSE_PUBLIC_KEYS_JSON remains available only as an optional deployment/test addition or override. Blackcap never has the Microwave Pie private signing key and has no unsigned fallback or production bypass.

Legacy/perpetual credentials remain signed claim schema v1. Trial credentials use signed claim schema v2. This is deliberate: pre-Trial Blackcap builds already reject a schema other than v1, so a Trial key cannot be silently accepted by an older build as perpetual merely because that build ignores unfamiliar fields. The outer credential remains MPL1; v2 is the signed claim schema, not a second credential system.

Common signed claims include the product key, stable license reference/number, Limited/Full scope, entitlement revision, credential generation, issue time (iat), offline capability, nonce, and the numeric Limited Use entitlements. A v2 Trial additionally signs term=trial and an absolute UTC expiration (exp). Owner email, Trial eligibility/override history, and description are Tracker metadata and are deliberately not in the signed credential.

The complete credential is encrypted locally through Blackcap's existing secret facility. UI/API surfaces expose only masked credential metadata and a fingerprint. Routine tracking heartbeats never include the credential.

License scope and term

Scope and term are independent dimensions. Scope remains Limited Use or Full Use. Term is Perpetual or Trial. Existing v1 credentials with no term/expiration continue to mean Perpetual and do not need to be rotated. The initial commercial Trial issuance flow supports Limited Use + Trial, while the domain model and regenerated entitlements keep scope separate from the Trial clock.

A Trial always uses an absolute signed expiration. A duration-based Trial initially carries an issuance-time offline fallback. If first-use license registration completes online, Tracker may replace that fallback exactly once with another signed expiration equal to Tracker UTC registration time plus the signed Trial duration. If registration does not complete during first use and Blackcap proceeds offline, Blackcap records a host-local fallback lock and the originally signed fallback expiration becomes final; later connectivity may complete registration/binding but does not restart the Trial. After the online anchor or offline fallback lock exists—or immediately for an explicitly fixed-end Trial—its validity rule is effective_time < expires_at; at the exact expiration instant (effective_time >= expires_at) the state is Trial Expired. Reinstalling Blackcap, restarting it, restoring a database backup, resending the key, transferring ownership, releasing/rebinding an installation, rotating a credential, or changing scope does not create another Trial start. A malformed v2 Trial, a missing expiration, or an expiration not after issuance fails closed.

Trial expiration is non-destructive. Recipes, organizations, users, meal plans, shopping lists, inventory, displays, settings, integrations, AI history, and backups remain intact. Normal licensed operations and Extension APIs are server-side restricted, while authenticated System Admin license status/remediation, About, System, Login/Logout, and the existing safe health/status surfaces remain available. Replacing an expired Trial first validates the new signed credential and then uses the existing replacement/reconciliation path; a failed replacement leaves the expired Trial and customer data untouched. When any valid replacement License Key is successfully activated on the same Blackcap instance, Tracker makes the replacement license the instance's current association and releases the previous license binding; the old Tracker license record/history remains available but is no longer associated with that instance. A failed replacement does not release the previous binding.

Scopes

Limited Use permits at most 5 active normal organizations, 5 users per active normal organization (accepted memberships plus active pending invitations), and 10 combined active Regression + Diagnostic Clone organizations. The Default organization does not count. Platform System Admin capability by itself does not consume an organization seat.

Full Use has no numeric organization/user/test-organization caps, but still requires a valid signed Blackcap credential and remains subject to authoritative online revocation/conflict state when tracking is reachable.

Organization purpose is explicit (default, normal, regression, diagnostic_clone) and is not inferred from display names. Capacity enforcement is centralized and serialized before entitlement-consuming writes for both SQLite and PostgreSQL.

Setup and existing installations

A new installation enters Setup, requires a License Key, verifies it locally, and then attempts tracking registration/binding. A connectivity failure does not fail activation after local signature validation. An authoritative tracking rejection does.

An upgraded existing installation preserves its data and enters License Required until a System Admin installs a valid signed key. No reinstall is required. Restricted states retain Login/Logout, health/status, and license remediation routes while normal application and Extension APIs are blocked server-side.

Offline behavior

A valid perpetual signed credential can be used indefinitely offline according to its signed scope. Internet loss is not revocation and there is no mandatory online grace timer. A Trial always has a signed absolute expiration that Blackcap can enforce without Tracker. A duration-based Trial is initially issued with an offline fallback expiration. If first-use registration reaches Tracker successfully, Tracker returns a newly signed entitlement whose expiration is the Tracker UTC registration time plus the Trial duration. That replacement happens once. If first-use registration cannot complete and Blackcap proceeds offline, Blackcap locks the fallback locally; when connectivity later returns it reports that lock so Tracker preserves the original expiration instead of granting a fresh period. If the registration service is unexpectedly unavailable at first use, the customer can contact Microwave Pie for administrative assistance.

A permanently disconnected installation cannot learn about a later remote revocation, duplicate-use decision, credential rotation, ownership transfer, or scope change. If the same valid key is copied to two machines and both remain offline, both can verify it. This is the unavoidable tradeoff for perpetual offline operation.

When connectivity returns, the authenticated tracking heartbeat reports only safe license identity, revision/generation, signed Trial activation metadata when present, host-local license installation identity, and aggregate entitlement usage. Tracking can then return active, activation-needed, conflict, revoked, replacement-required, or an updated signed entitlement. For a duration-based Trial that has never activated online, activation-needed triggers the one-time Tracker anchor and Blackcap verifies and installs the returned signed replacement entitlement. Scope revisions are applied as a new signed entitlement. In particular, after a connected Full Use license is changed to Limited Use, the next successful heartbeat installs the Limited entitlement; existing organizations remain intact, but new organization/user creation is blocked as soon as the configured Limited limits are reached. A fully offline Blackcap cannot learn a remote scope change until it reconnects. Security credential rotations require intentional replacement-key entry. Ownership transfer changes the responsible owner/contact metadata only and does not rotate the installed credential.

Instance binding and restore safety

License binding uses the existing tracker instance plus a random bli_... license installation identity stored beside Blackcap's local encryption key, outside the ordinary application database. Trial rollback protection is stored at the same host-local security boundary in blackcap_license_trusted_time.json, not in browser/session/organization state or the restorable application database. Effective Trial time is the maximum of current local UTC, the highest persisted trusted time, and authenticated Tracker time when available. Updates are monotonic and atomically replaced, so setting the local clock backward or restoring an older database does not gain Trial time while host-local state survives.

A small backward NTP correction is not treated as tampering; evaluation simply remains at the previously trusted instant. A large erroneous forward system-clock jump can therefore expire a fully offline Trial early. That fail-safe limitation is preferable to making trusted time reversible, which would create a trivial rollback bypass. A complete machine wipe can remove local rollback state, but the signed absolute expiration still never changes; perfect offline time enforcement on customer-controlled hardware is not claimed.

Restoring/copying the DB does not silently make a second host indistinguishable from the original when it reconnects. Tracking detects a different license installation identity as a conflict even if a copied DB contains the same tracker state.

For planned hardware replacement, use the tracking site's Release / Transfer Instance Binding action. It releases the old binding and rotates the credential before reassignment.

About, System, License Details, and Extension

About shows only a high-level license summary: scope, effective status, License Number, License Period, and Ends when applicable. The System page shows a compact application/scope/status/number/period/end/compliance summary with a button to License Details.

GET /admin/license is intentionally available even before sign-in, but an unauthenticated request receives a separate read-only public-safe view containing only application, License Number, scope, effective status, period/end, and compliance. It does not expose License Reference, credential/masked credential, fingerprint, generation/revision, binding diagnostics, or administrative actions. An authenticated System Admin receives the full License Details diagnostic view with safe term/issued/end/time-remaining, reference, masked/fingerprint metadata, generation/revision, usage, binding, and compliance detail. Enter New License Key remains authenticated and validates a replacement before changing the installed credential.

Authenticated License Details also provides Refresh License Details. That action calls the existing POST /api/system/instance-reporting/trigger production reporting path, waits for the registration/heartbeat attempt to finish, then reads authenticated GET /api/license/status and updates the displayed fields in place without a full page reload. The trigger/status APIs remain System Admin-only even though the public-safe License Details GET is available before login. Tracking-contact timestamps are intentionally not exposed in user-facing UI or the License Status API. Full credentials are never rendered there.

The Chrome Extension relies on server-side licensing and cannot bypass it. Structured LICENSE_* responses are displayed as useful license remediation errors rather than generic network/token errors.

Production trust configuration

The production Microwave Pie verification key is committed to Blackcap in:

inky_admin/licensing/trusted_public_keys.json

The file contains only public verification material and is intentionally distributed with every Pi and GCP Blackcap deployment, for example:

{
  "mp-prod-2026": "<Base64 DER Ed25519 public key>"
}

No per-instance configuration is required for the normal production signing authority. Public verification keys are not secrets. Never commit or deploy the production private signing key, credential-encryption key, INSTANCE_SECRET_PEPPER, SMTP credentials, or customer License Keys to Blackcap.

BLACKCAP_LICENSE_PUBLIC_KEYS_JSON is optional. When present, its entries are merged over the repository keyring and may add or replace key IDs. This is intended for automated tests, development, emergency trust transitions, or deployments that deliberately need an additional authority; it is not required for normal Pi or GCP production installs.

Deployment order

Trial credentials introduce a signed claim schema that must fail closed on older clients, so deploy in this order:

Deploy the Blackcap release containing v2 Trial parsing/enforcement and verify existing v1 Full Use/Limited Use, bound, offline, transferred, and rotated perpetual credentials still validate.
Deploy Tracker migrations V18__trial_license_terms.sql, V19__trial_online_activation_anchor.sql, and V20__trial_offline_fallback_lock.sql plus the Tracker service/UI changes. Validate locale-key parity, Guide/documentation contract tests, and licensing SMTP.
Keep existing signing-key/public-key trust configuration; Trial does not require a new production signing authority.
Only after Trial-capable Blackcap is available to intended customers, issue the first v2 Trial credential.
Validate one active Trial online, Active Offline, exact expiration, Trial Expired restriction, and replacement with a valid perpetual key on representative Pi/GCP deployments.

Once a v2 Trial has been issued to an installation, the Trial-capable Blackcap build is the minimum safe rollback floor for that installation. Rolling back to an older build that cannot interpret v2 will reject the Trial rather than grant perpetual access, but it will also make that Trial unusable until a compatible build is restored. Do not enable Tracker Trial issuance before this deployment order is satisfied.

Signing-key operations

The production Ed25519 private key must be generated once using a secure key-management process, stored in secret management, backed up securely, and never committed. The matching public key and key ID should be committed to inky_admin/licensing/trusted_public_keys.json. Signing-key rotation is distinct from rotating one customer's credential. During a planned signing-key transition, commit both old and new public keys to Blackcap's trusted keyring before Tracker begins signing with the new authority, and keep the old public key until credentials signed by it no longer need to validate.

Regression, API Tester, and Database Admin

Regression testing is license-aware but does not exercise the live license lifecycle. A normal regression run preflights 2 temporary organization slots and a Diagnostic Clone preflights 1. If capacity is unavailable, the run is not created; scheduled runs are skipped/rescheduled with an audit event. The installed License Key is never changed by this preflight.

System Admins can use API Tester → Licensing → License Status for the same safe read-only license status exposed by /api/license/status, including Trial term/period, signed issue/end/activation metadata, fallback-lock state, time remaining, entitlement revision/generation, online status, and aggregate usage/compliance. Installation/replacement is deliberately unavailable there. API Tester → System → Trigger Instance Report is a separate confirmed, non-Postman diagnostic action that accepts no caller-supplied instance identity and uses the normal production reporting path.

Database Admin shows only derived License / Entitlement Diagnostics and exposes organization_purpose on Organizations; it never exposes the full or encrypted credential. The diagnostics panel includes online status, Trial activation/fallback-lock state when applicable, entitlement revision/generation, trusted time, public license identity/fingerprint, organization usage, and compliance so support can distinguish local entitlement state from Tracker reconciliation state.

Migration 224_license_entitlement_integrity.py hardens organization-purpose metadata and seeds the non-secret blackcap_license internal state row used to serialize entitlement-sensitive writes. Database parity checks these requirements on both SQLite and PostgreSQL.

Signing-authority disaster recovery

The production public verification key is intentionally distributed with Blackcap. The private signing authority and the credential-encryption key belong only to Microwave Pie Tracker and must be protected and backed up with the Tracker operational data. They must never be copied into Blackcap or source control.

If the Tracker credential-encryption key is lost, already-installed Blackcap credentials can still validate locally, but Tracker may be unable to decrypt/resend the stored credential; recovery should issue/rotate a replacement using a functioning signing authority. If the private signing key is lost, Tracker cannot issue new credentials under that authority and must transition to a new authority.

If a private signing key is suspected compromised, create a new signing authority, distribute the new public key to Blackcap before making it the active issuer where possible, rotate affected credentials, and only remove the old public key after the transition is complete. Permanently offline Blackcap installations necessarily keep trusting every public key bundled in the Blackcap version they are running until that software/trust keyring is updated. That is an explicit tradeoff of perpetual offline validation.

Revocation memory

Tracker removes old revoked licenses from its normal license inventory according to the configurable revoked-license retention period, but it retains a minimal non-secret revocation tombstone. Tombstones should be retained indefinitely, or at minimum under a deliberately much longer security-retention policy than ordinary audit/history rows, because they prevent a deliberately revoked credential/reference from later becoming indistinguishable from something that was never issued.

Blackcap does not store or receive Tracker's tombstone records. It only receives the resulting online decision (for example revoked) during activation/reconciliation.

Packaged license bootstrap

A Microwave Pie deployment package may carry a customer-specific signed MPL1 credential in a protected bootstrap file. Blackcap validates and imports it through the same License service used by manual installation; it does not create a parallel entitlement. A different existing valid license is never silently replaced. Package metadata is reported without the credential so Tracker can reconcile Package → License → Instance. Packaged Trials are first signed at package delivery and subsequent downloads/reinstalls do not restart them. See Packaged Blackcap deployment.

On this page