Activation with the permissions you have
Activation ties a license key to one device. You call it once, when the customer enters the key, and keep the returned instance.id, which validate and deactivate need, and the signed token. Checking the license on later starts is validation. The code below saves into the same license.json, and reuses call, load, save, dir and FILE from that page.
// activate.ts: call, load, save, dir and FILE come from license.ts on the validation page.
import { call, dir, FILE, load, save } from "./license.ts";
const MACHINE_ID = "/etc/machine-id"; // Linux; grant it with --allow-read=/etc/machine-id
/** Uses only what the user already granted. Query never prompts, so activation is not interrupted. */
async function granted(descriptor: Deno.PermissionDescriptor): Promise<boolean> {
return (await Deno.permissions.query(descriptor)).state === "granted";
}
async function installId(): Promise<string> {
const file = `${dir}/install-id`;
try {
return (await Deno.readTextFile(file)).trim();
} catch (error) {
if (!(error instanceof Deno.errors.NotFound)) throw error;
await Deno.mkdir(dir, { recursive: true });
const id = crypto.randomUUID();
await Deno.writeTextFile(file, id);
return id;
}
}
/** Stable per machine when permitted, otherwise per installation. Hashed, and different per app. */
export async function fingerprint(): Promise<string> {
let seed: string | undefined;
if (await granted({ name: "read", path: MACHINE_ID })) {
seed = await Deno.readTextFile(MACHINE_ID).then((t) => t.trim(), () => undefined);
}
seed ??= await installId(); // deleting the config folder means a new seat
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode("inkwell:" + seed));
return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
}
async function deviceName(): Promise<string> {
if (await granted({ name: "sys", kind: "hostname" })) return `${Deno.hostname()} (${Deno.build.os})`.slice(0, 120);
return `${Deno.build.os} ${Deno.build.arch}`; // what the buyer sees on the device page
}
export type ActivateResult =
| { ok: true; used: number; limit: number | null }
| { ok: false; reason: "limit"; used: number; limit: number | null }
| { ok: false; reason: "expired" | "disabled" | "unknown-key" | "offline" | "error"; message?: string };
export async function activate(key: string): Promise<ActivateResult> {
const { status, json } = await call("activate", {
license_key: key.trim(),
instance_name: await deviceName(),
fingerprint: await fingerprint(),
});
if (json.activated) {
await save({ key: key.trim(), instanceId: json.instance.id, token: json.token, checkedAt: Math.floor(Date.now() / 1000) });
return { ok: true, used: json.license_key.activation_usage, limit: json.license_key.activation_limit };
}
if (status === 0) return { ok: false, reason: "offline" };
const lk = json.license_key;
if (status === 400 && lk) {
// Branch on data, not on error text. Expired and disabled are refused before the limit is checked.
if (lk.status === "expired" || lk.status === "disabled") return { ok: false, reason: lk.status, message: json.error };
return { ok: false, reason: "limit", used: lk.activation_usage, limit: lk.activation_limit };
}
return { ok: false, reason: status === 404 ? "unknown-key" : "error", message: json.error };
}
/** Frees this device's seat. Keeps the local copy when the server could not be reached, so you can retry. */
export async function deactivate(): Promise<{ ok: boolean; status?: number }> {
const saved = await load();
if (!saved) return { ok: true };
const { status } = await call("deactivate", { license_key: saved.key, instance_id: saved.instanceId });
if (status !== 200 && status !== 404) return { ok: false, status }; // 404: the seat was already gone
await Deno.remove(FILE);
return { ok: true };
}
ActivateResult is a union, so TypeScript forces the caller to handle the limit case before it can read used and limit. The limit can be null: a product with unlimited devices reports activation_limit: null.
What each fingerprint costs
instance_name is for people. The buyer sees it on the device page. fingerprint is for machines, and Deno charges for every source of one:
| Source | Permission | What to know |
|---|---|---|
| Generated install id in the config folder | The read and write access the license file needs anyway | One id per installation. Delete the folder and the next activation takes another seat. |
/etc/machine-id |
--allow-read=/etc/machine-id |
Linux only. Per OS install, and a VM cloned from one image carries the same id. |
Deno.hostname() |
--allow-sys=hostname |
Good for the device name, poor as a fingerprint: it changes when the machine is renamed, and many machines share a default. |
ioreg or reg query output |
--allow-run=ioreg or --allow-run=reg |
Stable per machine on macOS and Windows, but it lets the tool start a process. |
The code uses the machine id when it is granted and the install id when it is not, and takes the hostname for the name only when --allow-sys=hostname was given. It checks with Deno.permissions.query and never asks. A tool you hand to others should work with the flags in your documentation and become more precise only when the user opts in.
The hash uses the prefix inkwell:, so the id is not the machine’s raw id and cannot be matched against another app’s. The API takes up to 200 characters for a fingerprint. A SHA-256 hex digest is 64.
Asking for the key
// main.ts (excerpt)
import { activate } from "./activate.ts";
const key = prompt("License key:")?.trim(); // null without a terminal
if (!key) {
console.error("Run this in a terminal, or pass the key as an argument.");
Deno.exit(2);
}
const result = await activate(key);
if (!result.ok && result.reason === "limit") {
console.error(`This key is already active on ${result.used} of ${result.limit} devices.`);
console.error("Remove one at https://clavem.io/licenses/manage, or run the deactivate command on that machine.");
}
What was run
The code ran under Deno 2.9.7 against a local server that returns the documented responses, with a limit of two devices. We ran it twice: with -A and a machine-id file containing a test value, and with only --allow-net for the server, the config folder and the XDG_CONFIG_HOME variable.
| Step | Full permissions | Narrow permissions |
|---|---|---|
| Fingerprint source | The machine-id file | A generated install-id file |
| Fingerprint called twice | Same value | Same value |
| Activate | used: 1, limit: 2 |
used: 1, limit: 2 |
| Activate again | Same instance.id |
Same instance.id |
| Unknown key | unknown-key |
unknown-key |
| Expired key | expired |
expired |
| Deactivate | ok, local file removed |
ok, local file removed |
The machine-id hash equalled the SHA-256 of inkwell: plus the test value, computed separately. The activation limit and the second device were exercised in the Node.js version of the same flow, against the same local server. We did not call activate or deactivate on the live demo license.
Deactivating, and the customer who lost a machine
deactivate removes the local file only after the server confirms, or answers 404 because the seat was already gone. When the server cannot be reached it keeps the file and returns ok: false, so the command can say so and the customer can retry. A customer whose machine is gone can free the seat without you at /licenses/manage.
Doing this with Clavem
Activating again with a fingerprint that is already active on the license returns that seat with its name updated, instead of using another. The install-id fallback relies on that: a reinstall that keeps the config folder does not take a second seat. The fields are in the API reference.
Questions
Does Deno.permissions.query prompt the user?
No. query only reports the state, which is granted, denied or prompt. We ran it on a path with no read flag and it returned prompt without asking anything. Only Deno.permissions.request shows a prompt, which you do not want in the middle of activation.
What does prompt() return when the tool runs in a script or a service?
null. We ran prompt with stdin redirected from /dev/null and with a piped line, and both returned null, because stdin was not a terminal. Accept the key as an argument or read it from stdin yourself in those cases.