Protection Levels (L0–L4)

How to actually integrate CopyLocker, and how much work each protection level forces an attacker to redo.

How to actually integrate CopyLocker, and how much work each choice forces an attacker to redo. This guide is the consumer-facing version of .agents/03-modules/60-instrumentation-guard.md, with code aligned to the shipped SDKs (packages/web, crates/copylocker-client).

The mental model

Wrong: "I call the SDK to check whether a license exists, and exit if not."

Right: "Part of my application physically cannot be decrypted until a valid credential derives its key."

TypeScript
1// ❌ one `if` between the attacker and your product2if (!license.valid) return3doExpensiveWork()45// ✅ no key, no content6const key = await cl.unseal('pro', sealedConfig)7doExpensiveWork(JSON.parse(decode(key)))

The levels

Level	Technique	Integration cost	Cracking cost	Use for
L0	Single `if (!valid) exit()`	5 minutes	Minutes	❌ Not recommended; demos only
L1	Multi-point async instrumentation + delayed, randomized failure	Half a day	Hours	Cheap tools, trial limits
L2	Critical config/data sealed under a feature key	1 day	Requires one legitimate credential	✅ Default recommendation
L3	Critical code chunks / WASM segments sealed	2–3 days	A legitimate credential + repeated per-version work	High-value software
L4	Critical computation server-side	Business-dependent	Cannot be cracked offline	SaaS-shaped, AI-shaped products

Pick L2 to start. Every level below has complete, copyable examples.

L1: instrumentation discipline (when L2+ does not apply)

Principles:

Principle	Meaning
Multi-point	At least 5–10 instrumentation points across different modules
Async	Points are hints; validation happens asynchronously, never blocking the user
Delayed	On failure, degrade after a random delay (minutes to hours), never crash instantly
Diverse	Different points fail differently (missing feature, wrong result, silent degradation)
Deep	Inside core business flows, not at startup
No strings	No greppable strings like `"license"` or `"trial expired"`

Anti-patterns: a single checkLicense() choke point, a one-time startup check, user-visible license strings, and blocking synchronous validation.

Recommended shape — the hint is a side effect; the seal is the gate:

TypeScript
1async function exportProject(project: Project) {2  cl.hintOnline()                                        // opportunistic revalidation hint3  const key = await cl.unseal('export', SEALED_EXPORT_PROFILE)  // ← the actual gate4  return runExport(project, decodeProfile(key))5}

L2: sealed data (default)

What to seal

Good candidates: configuration/parameter tables, pro templates and assets, model weights, API endpoints and credentials for your own backend (this also stops free users from abusing it), and business rules (pricing, tax tables, format mappings).

Poor candidates: anything recoverable from the UI, huge rarely-changing assets (decrypt cost on every run — use KEK caching), and open-source code.

Web

Seal at build time with @copylocker/unplugin (which drives @copylocker/seal):

TypeScript
1// vite.config.ts2copylocker({3  // …4  seal: { assets: [{ globs: ['assets/pro-*.json'], feature: 'pro' }] },5})

Open at runtime with the real @copylocker/web API — loadSealed(url, featureId):

TypeScript
1const preset = JSON.parse(new TextDecoder().decode(2  await cl.loadSealed('/assets/pro-presets.json.sealed', 'pro')3))

Desktop (Rust client core)

crates/copylocker-client exposes unseal(&self, feature: &str, sealed: &[u8]):

Rust
1let bytes = client.unseal("pro", include_bytes!("../assets/pro/presets.sealed"))?;

Failure UX matters

When a seal does not open, the user must see a meaningful prompt, not a crash. Distinguish "not entitled" from "corrupt file / network problem" — otherwise a paying user with a CDN hiccup concludes you treated them as a pirate. On the web SDK, errors are typed classes (packages/web/src/errors.ts):

TypeScript
1import { NotEntitledError, UnsealError, TransportError } from '@copylocker/web'23try {4  data = await cl.loadSealed(url, 'pro')5} catch (e) {6  if (e instanceof NotEntitledError) showUpgradePrompt()        // no entitlement7  else if (e instanceof TransportError) showConnectPrompt()     // network / offline8  else if (e instanceof UnsealError) showReinstallPrompt()      // corrupt or tampered bytes9  else showGenericError()10}

Why the internal design sketch differs

The internal module doc shows string codes (e.code === 'NOT_ENTITLED'). The shipped web SDK instead throws typed errors carrying a numeric code (NFR-SEC-011: no greppable feature strings). The classes above are the real contract.

L3: sealed code

Web chunks (opt-in)

TypeScript
1copylocker({2  seal: { chunks: [{ match: /features\/pro\//, feature: 'pro' }] },3})

The matched chunk is replaced by a loader stub at build time:

JavaScript
1export default async function load() {2  const code = await __cl.loadSealed('/chunks/pro-x7f2.js.sealed', 'pro')3  return import(URL.createObjectURL(new Blob([code], { type: 'text/javascript' })))4}

CSP trade-off: the Blob-URL dynamic import needs script-src blob:. If that is unacceptable, use the WASM variant.

WASM segments (no eval, recommended)

Compile the pro functionality to a standalone .wasm and seal it whole:

TypeScript
1const wasmBytes = await cl.loadSealed('/pro.wasm.sealed', 'pro')2const { instance } = await WebAssembly.instantiate(wasmBytes, imports)

WebAssembly.instantiate from an ArrayBuffer only needs wasm-unsafe-eval — no unsafe-eval — and suits compute-heavy core logic.

Desktop

Rust
1// Ship critical logic as a sealed .wasm or data-driven bytecode module.2let module = client.unseal("pro", PRO_MODULE_SEALED)?;3let engine = wasmtime::Module::from_binary(&engine, &module)?;

Or simpler: seal the critical data tables and keep code in plaintext that cannot run without them.

Using feature keys correctly

feature_key exists for cases where you decrypt with your own AEAD instead of unseal. The Rust client signature is feature_key(&self, feature: &str) -> Result<Secret<[u8; 32]>, CoreError>:

Rust
1// ✅ correct: the key does real work2let key = client.feature_key("pro")?;3let plaintext = aead_open(&key, &sealed_data)?;45// ❌ wrong: collapsing the key to a boolean is L0 again6let has_pro = client.feature_key("pro").is_ok();7if has_pro { /* … */ }

SDK guardrails:

feature_key() returns Secret<[u8; 32]> with no Debug/Display/PartialEq, so it cannot be casually printed or compared.
Every feature_key example should be followed by a real decryption use.
After a transition to Locked/Revoked, feature_key() fails and cached plaintext is yours to clear:

TypeScript
1cl.onStateChange((s) => {2  if (s === 'Locked' || s === 'Revoked') assetCache.clear()3})

Trials

No special mechanism — entitlements plus not_after:

Text
1Policy: validity = Trial(14d, once_per = fingerprint), seats = 1, features = ['trial']

Trial assets are sealed under the trial feature; paid assets under pro. Expiry → Locked → no key. Re-trial abuse is bounded server-side by fingerprint dedup (one trial per fingerprint, with tolerance matching so a new NIC does not reset it). Trials are pinned to one seat and cannot transfer machines.