Clavem

Validate a license key in a Deno app or compiled executable

Call POST /v1/licenses/validate with fetch, store the key and the last signed token in a file only your app can read, and run with --allow-net=clavem.io instead of blanket network access. The part that trips people up is permissions, because a missing flag looks like a network failure.

Permissions first

Deno denies network, file and environment access until you grant it. That is useful for a licensed tool: you can ship a command line that says exactly what it touches. It also changes how the license check fails. In Node, a check that cannot reach the server is offline. In Deno, it can be offline, or it can be a missing flag, and the two must not look alike.

The code below is the check. It asks the server at most once a day, never sleeps on a retry, and falls back to the stored token. The token check is verifyToken and isLicensed from offline verification in Deno. Activation, which creates the file, is on the device activation page.

// license.ts
// Run with the narrowest permissions that work:
//   deno run --allow-net=clavem.io --allow-env=HOME,XDG_CONFIG_HOME \
//     --allow-read="$HOME/.config/inkwell" --allow-write="$HOME/.config/inkwell" main.ts
import { isLicensed, verifyToken } from "./token.ts"; // from the offline verification page

const BASE = "https://clavem.io";
const PUBLIC_KEY = "YOUR_PUBLIC_KEY"; // from your product page
const PRODUCT_ID = 75; // from your product page
const ONLINE_EVERY = 24 * 60 * 60; // seconds between online checks; the token covers the days in between

export interface Saved {
  key: string;
  instanceId?: string;
  token?: string;
  checkedAt?: number;
  pauseUntil?: number;
}
export type LicenseState =
  | { state: "licensed" | "needs-network" | "unlicensed" }
  | { state: "invalid"; message: string };

const home = Deno.env.get("HOME") ?? "."; // HOME needs --allow-env; on Windows read APPDATA instead
export const dir = `${Deno.env.get("XDG_CONFIG_HOME") ?? `${home}/.config`}/inkwell`;
export const FILE = `${dir}/license.json`;

export async function load(): Promise<Saved | null> {
  try {
    return JSON.parse(await Deno.readTextFile(FILE));
  } catch (error) {
    if (error instanceof Deno.errors.NotFound || error instanceof SyntaxError) return null;
    throw error; // NotCapable (a missing permission flag) must not look like "no license"
  }
}

export async function save(license: Saved): Promise<void> {
  await Deno.mkdir(dir, { recursive: true });
  await Deno.writeTextFile(FILE + ".tmp", JSON.stringify(license), { mode: 0o600 });
  await Deno.rename(FILE + ".tmp", FILE); // atomic: a crash never leaves half a file
}

/** One POST. Resolves with status 0 when there is no answer. Throws only for a missing permission. */
export async function call(action: string, body: Record<string, string | undefined>) {
  try {
    const res = await fetch(`${BASE}/v1/licenses/${action}`, {
      method: "POST",
      headers: { "content-type": "application/json", "user-agent": "inkwell/1.4.0" },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(5000),
    });
    const retryAfter = Number(res.headers.get("retry-after")) || null;
    return { status: res.status, retryAfter, json: await res.json().catch(() => ({})) };
  } catch (error) {
    if (error instanceof Deno.errors.NotCapable) throw error; // you ran it without --allow-net=clavem.io
    return { status: 0, retryAfter: null, json: {} }; // offline, DNS failure or timeout
  }
}

export async function check(): Promise<LicenseState> {
  const saved = await load();
  if (!saved) return { state: "unlicensed" };
  const now = Math.floor(Date.now() / 1000);

  if (now - (saved.checkedAt ?? 0) >= ONLINE_EVERY && now >= (saved.pauseUntil ?? 0)) {
    const { status, retryAfter, json } = await call("validate", { license_key: saved.key, instance_id: saved.instanceId });
    if (status === 200 && typeof json.valid === "boolean") {
      // Keep the new token even when the license is not valid: offline, it then says so.
      await save({ ...saved, token: json.token, checkedAt: now, pauseUntil: 0 });
      return json.valid ? { state: "licensed" } : { state: "invalid", message: json.error };
    }
    if (status === 404 && json.valid === false) {
      await Deno.remove(FILE); // unknown key, or this device was removed: ask for the key again
      return { state: "invalid", message: json.error };
    }
    // 429 and 503 say when to come back. Do not wait here: skip the online check until then.
    if (status === 429 || status === 503) await save({ ...saved, pauseUntil: now + (retryAfter ?? 60) });
  }

  // Not asked today, offline, rate limited or the service is down: use the stored token.
  const claims = await verifyToken(saved.token, PUBLIC_KEY);
  if (claims?.valid === false) return { state: "invalid", message: `This license is ${claims.status}.` };
  return isLicensed(claims, PRODUCT_ID) ? { state: "licensed" } : { state: "needs-network" };
}

A missing flag is not “offline”

Two lines in the code exist for this. call rethrows Deno.errors.NotCapable instead of turning it into status 0, and load does the same. Without them, a tool started without --allow-net=clavem.io would report “no answer” on every launch and quietly run on its stored token until the 14 days ran out. We ran the same file four ways with --no-prompt:

Flags Result
Net clavem.io, env, read and write on the config folder { state: "licensed" } against the demo key
Net example.com only NotCapable: Requires net access to "clavem.io:443"
No write access to the folder NotCapable: Requires write access to that folder
No env access NotCapable: Requires env access to "HOME", thrown before any request

Without --no-prompt, Deno asks interactively on a terminal. Do not rely on that for a licensed tool: a prompt in the middle of startup confuses buyers, and in a script or a service there is no terminal to answer it.

What each answer does

Answer What the code does
200 with valid: true Stores the new token, which restarts the 14-day window.
200 with valid: false Expired or disabled. Stores the token so offline says the same, and returns invalid with error.
404 Unknown key, or instance_id not found after the device was removed. Deletes the file and asks for a key.
429 or 503 Writes pauseUntil from Retry-After (60 and 5 seconds) and uses the token.
No answer A five-second timeout, no DNS or a refused connection. The token decides.
200 or 404 without the JSON body A captive portal or a proxy error page. Ignored: the token decides and the license file survives.

Branch on the status and on valid, not on the text of error. The local server returned each of these rows, and so did the live demo license for the 200 case.

Compiled executables

deno compile bakes the permission flags in. The documentation says the flags used to run the script must be given at compile time. A path flag is expanded by your shell first:

deno compile --allow-net=clavem.io --allow-env=HOME,XDG_CONFIG_HOME \
  --allow-read="$HOME/.config/inkwell" --allow-write="$HOME/.config/inkwell" -o inkwell main.ts

We compiled it with a temporary folder in place of $HOME/.config. The executable worked when XDG_CONFIG_HOME pointed at that folder and failed with NotCapable ... specify the required permissions during compilation using deno compile --allow-write when it pointed anywhere else. A customer’s home folder is never yours. Either grant --allow-read and --allow-write without a path for a tool that runs on other people’s machines, or keep the license file in a place whose path you know when you build, and say so in your documentation.

Where the key lives

One JSON file in the config folder, written to a temporary file and renamed, with mode 0o600. Deno’s standard APIs have no keychain access. On Windows do not count on the mode: put the file under %APPDATA% and treat it as readable by that user, which it must be anyway for the tool to run.

Doing this with Clavem

The License API needs no secret, so nothing sensitive ships in the executable. The key is the credential, and the public key used for the token check is meant to be shipped. The endpoints are in the API reference.

Questions

Which Deno permissions does a license check need?

Net access to clavem.io, read and write access to the one folder that holds the license file, and env access to the variables that name that folder. Verifying the signed token needs no permission at all.

Why does my compiled executable fail with NotCapable on a customer's machine?

deno compile bakes the permission flags into the executable. A flag such as --allow-read=$HOME/.config/inkwell is expanded by your shell at build time, so the executable is allowed to read your home folder, not the customer's.

Sources

  1. Deno documentation, security and permissions (checked November 2026)
  2. Deno documentation, deno compile (checked November 2026)