TypeScript REST client

samples/
  sdks/
    typescript/
      client.ts
      package.json
      package-lock.json
  security/
    javascript/
      canonical.mjs
      verify.mjs

{
  "name": "kdpika-typescript-rest-example",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "engines": {"node": ">=22"},
  "devDependencies": {"@types/node": "22.19.7", "typescript": "7.0.2"}
}

npm ci --ignore-scripts --no-audit --no-fund
npx --no-install tsc --strict --allowJs --checkJs false --target es2022 --module nodenext --moduleResolution nodenext --types node --outDir ./build client.ts

// Complete Sandbox REST session client, not an additional official SDK.
// Node22+, TypeScript7.0.2, @types/node22.19.7; no runtime npm dependencies.
// Keep the adjacent published security/javascript modules in their layout.
import * as fs from "node:fs";
import * as path from "node:path";
import {createHash, randomBytes, randomUUID} from "node:crypto";
import {verifyEnvelope} from "../../security/javascript/verify.mjs";
import {parseRaw, canonical} from "../../security/javascript/canonical.mjs";

type ObjectValue = Record<string, unknown>;
type State = {token: string; envelope: string | null; checkpoint: string};
type Decision = {valid: boolean; source: string; signature_valid: boolean; error_code: string | null;
  request_id: string | null; pdf_export_allowed: boolean; seat_count: number | null; message: string};
class Refusal extends Error {
  constructor(readonly code: string, readonly requestId: string | null = null) {super(code);}
}
class Unreachable extends Error {}
const decode = (bytes: Uint8Array): unknown => parseRaw(bytes);
const object = (value: unknown): ObjectValue => {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Refusal("INVALID_RESPONSE");
  return value as ObjectValue;
};
const time = (value: unknown): number => {
  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(value)) throw new Refusal("INVALID_TIME");
  const result = Date.parse(value);
  if (!Number.isFinite(result)) throw new Refusal("INVALID_TIME");
  return result;
};
const friendly = (code: string): string => {
  if (code === "INVALID_LICENSE") return "Check your license key and the email used for this license.";
  if (code === "NOT_ACTIVATED") return "Activate this installation to continue.";
  if (["NETWORK_ERROR", "OFFLINE_GRACE_EXPIRED"].includes(code)) return "Connect to the internet and try again.";
  if (code === "CLOCK_ROLLBACK_DETECTED") return "Check your device date and time, then try again.";
  return "Your license could not be confirmed. Please contact your software provider.";
};
const denied = (code: string, source: string, requestId: string | null = null): Decision => ({valid: false, source,
  signature_valid: false, error_code: code, request_id: requestId, pdf_export_allowed: false, seat_count: null, message: friendly(code)});

class Session {
  readonly directory: string;
  readonly installation: string;
  private readonly trusted: Buffer;
  private readonly api: string;
  private readonly app: string;
  private readonly lock: string;
  private readonly lockHandle: number;

  constructor() {
    this.app = process.env.KDP_APP_ID ?? "";
    if (!/^[A-Za-z0-9_-]{3,160}$/.test(this.app)) throw new Error("Set KDP_APP_ID.");
    const rawBase = process.env.KDP_BASE_URL ?? "https://licensing.kdpika.com/api/v1";
    const base = new URL(rawBase);
    const local = base.protocol === "http:" && ["127.0.0.1", "localhost"].includes(base.hostname) && process.env.KDP_ALLOW_LOOPBACK === "1";
    if ((base.protocol !== "https:" && !local) || base.username || base.password || base.search || base.hash || base.pathname.replace(/\/$/, "") !== "/api/v1") throw new Error("Use the HTTPS API URL; only explicit loopback HTTP is allowed.");
    this.api = base.origin + "/api/v1";
    const root = process.env.KDP_STATE_DIR ?? "";
    const trustedFile = process.env.KDP_TRUSTED_KEY_FILE ?? "";
    if (!path.isAbsolute(root) || !path.isAbsolute(trustedFile)) throw new Error("Set absolute private state and independently trusted key paths.");
    this.trusted = this.readFile(trustedFile);
    const key = object(decode(this.trusted));
    if (key.algorithm !== "Ed25519" || key.encoding !== "base64url") throw new Error("Use the actual trusted public-key document.");
    const namespace = createHash("sha256").update(this.api + "|" + this.app + "|SANDBOX|typescript-rest-v1").digest("hex").slice(0, 20);
    fs.mkdirSync(root, {recursive: true, mode: 0o700});
    if (fs.lstatSync(root).isSymbolicLink()) throw new Error("State must not be a symlink.");
    this.directory = path.join(root, namespace);
    fs.mkdirSync(this.directory, {mode: 0o700, recursive: true});
    if (fs.lstatSync(this.directory).isSymbolicLink()) throw new Error("Namespace must not be a symlink.");
    fs.chmodSync(this.directory, 0o700);
    this.lock = path.join(this.directory, ".lock");
    this.lockHandle = fs.openSync(this.lock, "wx", 0o600);
    try {
      const identity = path.join(this.directory, "installation.json");
      if (!fs.existsSync(identity)) this.write("installation.json", {installation_id: "lmp-install-" + randomUUID()});
      const value = object(JSON.parse(this.readFile(identity).toString("utf8"))).installation_id;
      if (typeof value !== "string" || !/^lmp-install-[0-9a-f-]{36}$/.test(value)) throw new Error("Installation identity is invalid; do not reset automatically.");
      this.installation = value;
    } catch (error) {this.close(); throw error;}
  }

  close(): void {fs.closeSync(this.lockHandle); fs.unlinkSync(this.lock);}
  private readFile(file: string): Buffer {
    const stat = fs.lstatSync(file);
    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1048576) throw new Error("Unsafe state/key file.");
    return fs.readFileSync(file);
  }
  private write(name: string, value: unknown): void {
    const target = path.join(this.directory, name), temporary = target + "." + randomBytes(12).toString("hex");
    fs.writeFileSync(temporary, JSON.stringify(value), {flag: "wx", mode: 0o600});
    fs.renameSync(temporary, target);
  }
  private state(): State | null {
    const file = path.join(this.directory, "session.json");
    if (!fs.existsSync(file)) return null;
    const value = object(JSON.parse(this.readFile(file).toString("utf8")));
    if (typeof value.token !== "string" || !/^act_[A-Za-z0-9_-]+$/.test(value.token) ||
      !(value.envelope === null || typeof value.envelope === "string") || typeof value.checkpoint !== "string") throw new Error("Stored session is invalid.");
    return value as State;
  }
  private clear(): void {
    const file = path.join(this.directory, "session.json");
    if (fs.existsSync(file)) {this.readFile(file); fs.unlinkSync(file);}
  }
  private async request(endpoint: string, body: ObjectValue, token?: string): Promise<{body: ObjectValue; requestId: string | null}> {
    const headers: Record<string, string> = {Accept: "application/json", "Content-Type": "application/json", "User-Agent": "KDPika-REST-TypeScript-example/1.0"};
    if (token) {headers.Authorization = "Bearer " + token; headers["X-Installation-ID"] = this.installation;}
    else {headers["X-App-ID"] = this.app; headers["X-Environment"] = "SANDBOX";}
    let response: Response, raw: Buffer;
    try {
      response = await fetch(this.api + endpoint, {method: "POST", headers, body: JSON.stringify(body), redirect: "error", signal: AbortSignal.timeout(15000)});
      const reader = response.body?.getReader(); if (!reader) throw new Refusal("INVALID_RESPONSE");
      const chunks: Uint8Array[] = []; let size = 0;
      for (;;) {
        const next = await reader.read(); if (next.done) break;
        size += next.value.length;
        if (size > 1048576) {await reader.cancel(); throw new Refusal("INVALID_RESPONSE");}
        chunks.push(next.value);
      }
      raw = Buffer.concat(chunks);
    } catch (error) {if (error instanceof Refusal) throw error; throw new Unreachable();}
    let value: ObjectValue;
    try {value = object(decode(raw));} catch {throw new Refusal("INVALID_RESPONSE");}
    const requestId = typeof value.request_id === "string" && /^req_[A-Za-z0-9_-]{1,120}$/.test(value.request_id) ? value.request_id : null;
    if (!response.ok || value.success !== true) {
      const error = value.error && typeof value.error === "object" ? object(value.error) : {};
      const code = typeof error.code === "string" && /^[A-Z0-9_]{1,64}$/.test(error.code) ? error.code : "HTTP_ERROR";
      throw new Refusal(code, requestId);
    }
    return {body: value, requestId};
  }
  private verify(envelope: string, source: string, checkpoint: string | null, requestId: string | null): Decision {
    if (!verifyEnvelope(this.trusted, Buffer.from(envelope))) throw new Refusal("SIGNATURE_INVALID", requestId);
    // Only after byte-level verification, decode a semantic view for policy.
    const payload = object(object(JSON.parse(envelope)).payload), now = Date.now();
    if (payload.product_id !== this.app || payload.environment !== "sandbox" ||
      object(payload.device).installation_hash !== createHash("sha256").update(this.installation).digest("hex")) throw new Refusal("BINDING_MISMATCH", requestId);
    const server = time(payload.server_time), next = time(payload.next_validation_at), grace = time(payload.offline_grace_until);
    if (next < server || grace < server) throw new Refusal("INVALID_TIME", requestId);
    const previous = checkpoint === null ? server : Math.max(server, time(checkpoint));
    if (now + 300000 < previous) throw new Refusal("CLOCK_ROLLBACK_DETECTED", requestId);
    if (payload.status !== "active") throw new Refusal("LICENSE_NOT_ACTIVE", requestId);
    if (payload.starts_at !== null && payload.starts_at !== undefined && now < time(payload.starts_at)) throw new Refusal("LICENSE_NOT_STARTED", requestId);
    if (payload.expires_at !== null && now >= time(payload.expires_at)) throw new Refusal("LICENSE_EXPIRED", requestId);
    if (source !== "online" && now > grace) throw new Refusal("OFFLINE_GRACE_EXPIRED", requestId);
    const features = object(payload.features), seat = features.seat_count;
    return {valid: true, source, signature_valid: true, error_code: null, request_id: requestId,
      pdf_export_allowed: features.pdf_export === true, seat_count: typeof seat === "number" && Number.isSafeInteger(seat) && seat >= 0 ? seat : null,
      message: "Your license is ready."};
  }
  private accepted(state: State, source: string, requestId: string | null): Decision {
    if (!state.envelope) throw new Refusal("OFFLINE_CACHE_MISSING");
    const result = this.verify(state.envelope, source, state.checkpoint, requestId);
    this.write("session.json", {...state, checkpoint: new Date().toISOString()});
    return result;
  }
  async run(action: string): Promise<Decision | ObjectValue> {
    let state = this.state();
    if (action === "status") return {activated: state !== null, installation_hash: createHash("sha256").update(this.installation).digest("hex"), storage_security: "permission-protected-file"};
    if (action === "activate") {
      const license = process.env.KDP_LICENSE_KEY ?? "", email = process.env.KDP_CUSTOMER_EMAIL ?? "";
      if (!license.startsWith("TEST") || /[\r\n]/.test(license + email)) throw new Error("Use a Sandbox test key and valid input.");
      // Never replace an existing installation token implicitly or retry a
      // mutation automatically. Reconcile an uncertain activation first.
      if (state) throw new Refusal("ALREADY_ACTIVATED");
      const response = await this.request("/licenses/activate", {license_key: license, device_id: this.installation,
        device_name: "TypeScript REST example", platform: process.platform, app_version: "1.0.0", ...(email ? {email} : {})});
      const token = response.body.activation_token;
      if (typeof token !== "string" || !/^act_[A-Za-z0-9_-]+$/.test(token)) throw new Refusal("INVALID_RESPONSE", response.requestId);
      try {
        const envelope = canonical(object(response.body.license));
        const result = this.verify(envelope, "online", null, response.requestId);
        this.write("session.json", {token, envelope, checkpoint: new Date().toISOString()});
        return result;
      } catch (error) {
        try {await this.request("/licenses/deactivate", {}, token);} catch { /* Reconcile uncertain release with the developer. */ }
        throw error;
      }
    }
    if (!state) throw new Refusal("NOT_ACTIVATED");
    if (action === "deactivate") {
      const response = await this.request("/licenses/deactivate", {}, state.token);
      if (response.body.deactivated !== true) throw new Refusal("INVALID_RESPONSE", response.requestId);
      this.clear();
      return {valid: true, source: "online", signature_valid: false, error_code: null, request_id: response.requestId,
        pdf_export_allowed: false, seat_count: null, message: "This installation has been deactivated."};
    }
    if (action === "check" && state.envelope) {
      try {
        const checked = this.verify(state.envelope, "cache", state.checkpoint, null);
        const payload = object(object(JSON.parse(state.envelope)).payload);
        if (Date.now() < time(payload.next_validation_at)) {this.write("session.json", {...state, checkpoint: new Date().toISOString()}); return checked;}
      } catch {state = {...state, envelope: null}; this.write("session.json", state);}
    }
    try {
      const response = await this.request("/licenses/validate", {}, state.token);
      const envelope = canonical(object(response.body.license));
      const result = this.verify(envelope, "online", state.checkpoint, response.requestId);
      this.write("session.json", {...state, envelope, checkpoint: new Date().toISOString()}); return result;
    } catch (error) {
      if (error instanceof Unreachable) return this.accepted(state, "offline", null);
      if (error instanceof Refusal) {
        if (["INVALID_TOKEN", "DEVICE_MISMATCH", "LICENSE_REVOKED", "LICENSE_EXPIRED", "LICENSE_CANCELLED"].includes(error.code)) this.clear();
        else this.write("session.json", {...state, envelope: null});
      }
      throw error;
    }
  }
}

async function main(): Promise<void> {
  const action = process.argv[2] ?? "";
  if (process.argv.length !== 3 || !["status", "activate", "check", "validate", "deactivate"].includes(action)) throw new Error("Choose status, activate, check, validate or deactivate.");
  const session = new Session();
  try {
    try {
      const result = await session.run(action); console.log(JSON.stringify(result));
      process.exitCode = "valid" in result && result.valid !== true ? 1 : 0;
    } catch (error) {
      if (error instanceof Refusal || error instanceof Unreachable) {
        console.log(JSON.stringify(denied(error instanceof Refusal ? error.code : "NETWORK_ERROR", "local", error instanceof Refusal ? error.requestId : null)));
        process.exitCode = 1;
      } else throw error;
    }
  } finally {session.close();}
}
main().catch(() => {console.error("Check your application settings and private storage. Please contact your software provider if the problem continues."); process.exitCode = 2;});