Developer SDK

Electron examples

Install the SDK · View source on GitHub ↗

provider/state.mjs

javascript
// Installation state of the Electron provider, kept in one private `provider`
// directory inside the app's user data directory (PROVIDER_CONTRACT.md,
// "Installation state"). The companion uses it as its state directory:
//
//   - client.jwt: the scoped client credential from the developer's backend,
//     imported by the user; the companion rewrites it when the sdk refreshes
//     the token.
//   - instance-id: this installation's UUID, created here on first start and
//     kept for the life of the installation.
//   - identity.json: the provider identity, created and read by the companion.
//   - logs/: the sdk's bounded log files, written by the companion.
//
// Every file is replaced atomically with owner-only permissions. On POSIX the
// directory and its files must not be accessible to group or others; Windows
// relies on the access control of the user's profile directory. Mirrors
// go/provider/state.go. Every error here is a configuration error: restarting
// does not fix it.

import {randomBytes, randomUUID} from "node:crypto";
import fs from "node:fs";
import path from "node:path";

export const clientJwtFileName = "client.jwt";
export const instanceIdFileName = "instance-id";
export const identityFileName = "identity.json";
export const logDirName = "logs";

// the state directory's name inside the app's user data directory
export const stateDirName = "provider";

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

// A configuration or credential problem that a restart does not fix: the
// console examples exit with 78 for it, this app shows it and does not start.
export class ProviderConfigError extends Error {
  // A configuration error with the message to show.
  constructor(message) {
    super(message);
    this.name = "ProviderConfigError";
  }
}

// The private state directory inside the app's user data directory.
export function providerStateDir(userDataDir) {
  return path.join(userDataDir, stateDirName);
}

// Whether a mode lets group or others in. Windows modes do not carry the
// profile's access control, so they are not checked there.
function accessibleToOthers(mode, platform) {
  return platform !== "win32" && (mode & 0o077) !== 0;
}

// The state directory must be an existing absolute directory, private to its
// owner on POSIX.
export function checkStateDir(stateDir, platform = process.platform) {
  if (!stateDir) {
    throw new ProviderConfigError("the provider state directory is not set");
  }
  if (!path.isAbsolute(stateDir)) {
    throw new ProviderConfigError("the provider state directory must be an absolute path");
  }
  let info;
  try {
    info = fs.statSync(stateDir);
  } catch (error) {
    throw new ProviderConfigError(`state directory: ${error.message}`);
  }
  if (!info.isDirectory()) {
    throw new ProviderConfigError(`${stateDir} is not a directory`);
  }
  if (accessibleToOthers(info.mode, platform)) {
    throw new ProviderConfigError(`the state directory must be private to its owner (chmod 700 "${stateDir}")`);
  }
}

// Creates the state directory with owner-only permissions on first start, then
// checks it. An existing directory that others can access is refused, not
// repaired.
export function ensureStateDir(stateDir, platform = process.platform) {
  if (!path.isAbsolute(stateDir)) {
    throw new ProviderConfigError("the provider state directory must be an absolute path");
  }
  fs.mkdirSync(stateDir, {recursive: true, mode: 0o700});
  checkStateDir(stateDir, platform);
}

// Reads a regular, private state file of bounded size. A symlink is refused
// so that the credential cannot be redirected to another file; where the OS
// has O_NOFOLLOW the file is checked through the descriptor it reads.
export function readPrivateFile(filePath, platform = process.platform) {
  const noFollow = fs.constants.O_NOFOLLOW ?? 0;
  let fd;
  try {
    const linkInfo = fs.lstatSync(filePath);
    if (!linkInfo.isFile()) {
      throw new Error("not a regular file");
    }
    fd = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow);
  } catch (error) {
    if (error.code === "ELOOP") {
      throw new Error("not a regular file");
    }
    throw error;
  }
  try {
    const info = fs.fstatSync(fd);
    if (!info.isFile()) {
      throw new Error("not a regular file");
    }
    if (stateFileByteLimit < info.size) {
      throw new Error("file is too large");
    }
    if (accessibleToOthers(info.mode, platform)) {
      throw new Error("file must be private to its owner (chmod 600)");
    }
    return fs.readFileSync(fd);
  } finally {
    fs.closeSync(fd);
  }
}

// Replaces a state file atomically: a private temporary file in the same
// directory is written, synced and renamed over the old file.
export function writePrivateFile(filePath, data) {
  const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomBytes(8).toString("hex")}`);
  let fd = fs.openSync(tempPath, "wx", 0o600);
  try {
    fs.fchmodSync(fd, 0o600);
    fs.writeFileSync(fd, data);
    fs.fsyncSync(fd);
    fs.closeSync(fd);
    fd = undefined;
    fs.renameSync(tempPath, filePath);
  } catch (error) {
    if (fd !== undefined) {
      fs.closeSync(fd);
    }
    fs.rmSync(tempPath, {force: true});
    throw error;
  }
}

// The canonical form of a UUID, as the sdk's ParseId reads it: 36 characters
// with the separators at 8, 13, 18 and 23, or 32 hex digits. Throws for
// anything else.
export function parseId(text) {
  let hex = text;
  if (typeof text === "string" && text.length === 36) {
    hex = text.slice(0, 8) + text.slice(9, 13) + text.slice(14, 18) + text.slice(19, 23) + text.slice(24);
  }
  if (typeof hex !== "string" || !/^[0-9a-fA-F]{32}$/.test(hex)) {
    throw new Error(`cannot parse UUID ${text}`);
  }
  hex = hex.toLowerCase();
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

// 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 = new ProviderConfigError("client.jwt does not hold a JWT; import the scoped client JWT from your backend");
  const parts = String(clientJwt).split(".");
  if (parts.length !== 3 || parts.some(part => part === "")) {
    throw notJwt;
  }
  // unpadded base64url, as Go's base64.RawURLEncoding reads it
  const payload = parts[1].replace(/=+$/, "");
  if (!/^[A-Za-z0-9_-]+$/.test(payload) || payload.length % 4 === 1) {
    throw notJwt;
  }
  let claims;
  try {
    claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
  } catch {
    throw notJwt;
  }
  const clientId = claims !== null && typeof claims === "object" && !Array.isArray(claims) ? claims.client_id : undefined;
  if (typeof clientId !== "string" || clientId === "") {
    throw new ProviderConfigError("client.jwt has no client_id claim; import a scoped client JWT, not a network JWT");
  }
  try {
    return parseId(clientId);
  } catch {
    throw new ProviderConfigError("client.jwt has an invalid client_id claim");
  }
}

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

// Reads and checks client.jwt.
export function loadClientJwt(stateDir, platform = process.platform) {
  let data;
  try {
    data = readPrivateFile(path.join(stateDir, clientJwtFileName), platform);
  } catch (error) {
    if (error.code === "ENOENT") {
      throw new ProviderConfigError(`${clientJwtFileName} is missing; import the scoped client JWT from your backend`);
    }
    throw new ProviderConfigError(`read ${clientJwtFileName} from the state directory: ${error.message}`);
  }
  const clientJwt = data.toString("utf8").trim();
  return {clientJwt, clientId: parseClientJwtClientId(clientJwt)};
}

// Loads the installation state before the companion starts, creating
// instance-id on first start: {stateDir, clientJwt, clientId, instanceId}.
export function loadProviderConfig(stateDir, platform = process.platform) {
  checkStateDir(stateDir, platform);
  const {clientJwt, clientId} = loadClientJwt(stateDir, platform);
  const instanceId = loadOrCreateInstanceId(stateDir, platform);
  return {stateDir, clientJwt, clientId, instanceId};
}

// Saves a scoped client JWT as client.jwt after checking its client_id claim,
// and returns the client id. The token itself is never shown or logged.
export function importClientJwt(stateDir, text, platform = process.platform) {
  checkStateDir(stateDir, platform);
  const clientJwt = String(text).trim();
  const clientId = parseClientJwtClientId(clientJwt);
  writePrivateFile(path.join(stateDir, clientJwtFileName), `${clientJwt}\n`);
  return clientId;
}