Developer SDK

JavaScript examples

Install the SDK · View source on GitHub ↗

embed/state.mjs

javascript
// Installation state of one embed installation, kept in one private directory
// named by URNETWORK_EMBED_STATE_DIR (EMBED_CONTRACT.md, "Installation
// state"), with the provider contract's rules:
//
// - client.jwt: the scoped client credential. The token fetch writes it, or
//   the backend tool's provision or the developer; the native companion
//   rewrites it whenever the SDK refreshes the token.
// - instance-id: this installation's UUID, created on first run and kept for
//   the life of the installation. It is also the installation ID the app sends
//   to the token server.
// - logs/: the SDK's bounded log files, written by the companion.
//
// Files are replaced atomically with owner-only permissions. On POSIX the
// directory and its files must not be accessible to group or others, and a
// symlinked file is refused; Windows relies on the access control of the
// user's profile directory, under %LOCALAPPDATA%.

import {randomBytes, randomUUID} from "node:crypto";
import {lstat, open, readFile, rename, stat, unlink} from "node:fs/promises";
import {basename, dirname, isAbsolute, join} from "node:path";
import {normalizeId} from "./status.mjs";

export const clientJwtFileName = "client.jwt";
export const instanceIdFileName = "instance-id";

// the largest state file the app reads
const stateFileByteLimit = 64 * 1024;

// Checks of POSIX permission bits do not apply on Windows.
const posix = process.platform !== "win32";

// A configuration problem that restarting does not fix (exit code 78).
export class ConfigurationError extends Error {}

// The state directory must be an existing absolute directory, private to its
// owner on POSIX.
export async function checkStateDir(stateDir) {
  if (!stateDir) {
    throw new ConfigurationError("set URNETWORK_EMBED_STATE_DIR to this installation's private state directory");
  }
  if (!isAbsolute(stateDir)) {
    throw new ConfigurationError("URNETWORK_EMBED_STATE_DIR must be an absolute path");
  }
  let info;
  try {
    info = await stat(stateDir);
  } catch (error) {
    throw new ConfigurationError(`state directory: ${error.message}`);
  }
  if (!info.isDirectory()) {
    throw new ConfigurationError("URNETWORK_EMBED_STATE_DIR is not a directory");
  }
  if (posix && (info.mode & 0o077) !== 0) {
    throw new ConfigurationError("the state directory must be private to its owner (chmod 700)");
  }
}

// Reads a regular, private state file of bounded size. A symlink is refused
// so that the credential cannot be redirected to another file. A missing file
// rejects with the ENOENT error.
export async function readPrivateFile(path) {
  const info = await lstat(path);
  if (!info.isFile()) {
    throw new Error("not a regular file");
  }
  if (stateFileByteLimit < info.size) {
    throw new Error("file is too large");
  }
  if (posix && (info.mode & 0o077) !== 0) {
    throw new Error("file must be private to its owner (chmod 600)");
  }
  return readFile(path);
}

// Replaces a state file atomically: a private temporary file in the same
// directory is written, synced and renamed over the old file.
export async function writePrivateFile(path, data) {
  const tempPath = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}`);
  const file = await open(tempPath, "wx", 0o600);
  try {
    try {
      await file.writeFile(data);
      await file.sync();
    } finally {
      await file.close();
    }
    await rename(tempPath, path);
  } catch (error) {
    await unlink(tempPath).catch(() => {});
    throw error;
  }
}

// The client_id claim of a scoped client JWT. This checks the token's shape
// and claim only; the SDK and the server verify the token itself.
export function parseClientJwtClientId(clientJwt) {
  const notJwt = "client.jwt does not hold a JWT; write the scoped client JWT from your backend";
  const parts = typeof clientJwt === "string" ? clientJwt.split(".") : [];
  if (parts.length !== 3 || parts.some(part => part === "")) {
    throw new ConfigurationError(notJwt);
  }
  const payload = parts[1].replace(/=+$/, "");
  if (!/^[A-Za-z0-9_-]+$/.test(payload)) {
    throw new ConfigurationError(notJwt);
  }
  let claims;
  try {
    claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
  } catch {
    claims = null;
  }
  if (claims === null || typeof claims !== "object" || typeof claims.client_id !== "string" || claims.client_id === "") {
    throw new ConfigurationError("client.jwt has no client_id claim; write a scoped client JWT, not a network JWT");
  }
  const clientId = normalizeId(claims.client_id);
  if (clientId === "") {
    throw new ConfigurationError("client.jwt has an invalid client_id claim");
  }
  return clientId;
}

// Reads the scoped client JWT, trimmed, and its client_id claim.
export async function loadClientJwt(stateDir) {
  let data;
  try {
    data = await readPrivateFile(join(stateDir, clientJwtFileName));
  } catch (error) {
    if (error?.code === "ENOENT") {
      throw new ConfigurationError(`there is no ${clientJwtFileName} in the state directory: configure a token server (URNETWORK_TOKEN_SERVER_URL and URNETWORK_DEMO_SESSION) or write the client JWT from your backend tool's provision`);
    }
    throw new ConfigurationError(`read ${clientJwtFileName} from the state directory: ${error.message}`);
  }
  const clientJwt = data.toString("utf8").trim();
  return {clientJwt, clientId: parseClientJwtClientId(clientJwt)};
}

// Saves a scoped client JWT as client.jwt, atomically and privately.
export async function saveClientJwt(stateDir, clientJwt) {
  await writePrivateFile(join(stateDir, clientJwtFileName), `${clientJwt}\n`);
}

// Reads instance-id, creating it on first run. An installation keeps one
// instance id for its lifetime.
export async function loadOrCreateInstanceId(stateDir) {
  const path = join(stateDir, instanceIdFileName);
  let data;
  try {
    data = await readPrivateFile(path);
  } catch (error) {
    if (error?.code !== "ENOENT") {
      throw new ConfigurationError(`read ${instanceIdFileName} from the state directory: ${error.message}`);
    }
    const instanceId = randomUUID();
    try {
      await writePrivateFile(path, `${instanceId}\n`);
    } catch (writeError) {
      throw new ConfigurationError(`write ${instanceIdFileName}: ${writeError.message}`);
    }
    return instanceId;
  }
  const instanceId = normalizeId(data.toString("utf8").trim());
  if (instanceId === "") {
    throw new ConfigurationError(`${instanceIdFileName} does not hold a UUID`);
  }
  return instanceId;
}