@imagina-build/ias-cli 0.2.1 → 0.3.0

package/src/provisioning.mjs

@@ -0,0 +1,281 @@
+// Provisioning of the projects of an application from the Mac: the OTA project, its signing key and its publishing
+// token, and the distribution project and its token. The server only gets public material and returns a token once;
+// the private key and the token go to 1Password, and ias.json keeps their op:// references. `ias update init`,
+// `ias dist init`, `ias tokens create`, `ias runners code` and `ias setup` use this.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadProject, readExpo, saveProjectConfig } from './config.mjs';
+import { IasError } from './errors.mjs';
+import { connect, serverOrigin } from './manage.mjs';
+import { createItem, itemOf, readField, setField } from './op.mjs';
+import { generateKeyPair, readCertificate } from './ota-key.mjs';
+
+const KEY_ID = /^[A-Za-z0-9._-]{1,64}$/;
+const SECRET = /^op:\/\/[^/]+\/[^/]+$/;
+
+/** The app folder, its configuration and the Expo metadata the provisioning needs; errors name what is missing. */
+function projectOf(dir) {
+  const project = loadProject(dir);
+  if (!project.config) throw new IasError(`no ias.json in ${dir}`, { fix: 'run ias init there first (or ias setup next)', code: 'config_missing' });
+  const code = project.config.app;
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(code ?? '')) throw new IasError(`ias.json has no valid app (${code ?? 'none'})`, { fix: 'write the code of the application in app, or run ias init --app <code>' });
+  return { project, config: project.config, app: code, expo: readExpo(dir) ?? {} };
+}
+
+const clientOf = (client, project, env, sleep) => client ?? connect({ env, ...(sleep ? { sleep } : {}) }, project);
+const refOf = (reference) => itemOf(reference).reference;
+
+/** An item reference from --item (op://vault/item), or the default one in Private. */
+function itemOption(value, fallback) {
+  if (value === undefined) return fallback;
+  if (!SECRET.test(value)) throw new IasError(`«${value}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://Private/My app OTA' });
+  return value;
+}
+
+/** The certificate of the app's signing configuration, or undefined if it has none yet. */
+function signingOf(dir, config) {
+  const signing = config.updates?.signing;
+  if (!signing?.keyId || !signing?.privateKey || !signing?.certificate) return undefined;
+  if (!KEY_ID.test(signing.keyId)) throw new IasError(`updates.signing.keyId (${signing.keyId}) is not valid`, { fix: 'letters, digits, dots, hyphens and underscores, up to 64' });
+  if (!existsSync(join(dir, signing.certificate))) throw new IasError(`no certificate at ${signing.certificate}`, { fix: 'restore it from git, or remove updates.signing and run ias update init again' });
+  return signing;
+}
+
+/**
+ * Makes sure the app has its OTA project on the server and its signing key and token in 1Password, and writes their
+ * references in ias.json. It never prints the private key nor the token. Returns what it did for --json.
+ */
+export async function provisionOta({ dir, env = process.env, output, values = {}, client, sleep, dryRun = values['dry-run'] === true }) {
+  const { project, config, app, expo } = projectOf(dir);
+  const server = serverOrigin(project, env);
+  const name = values.name ?? expo.name ?? app;
+  const existing = signingOf(dir, config);
+  const item = itemOption(values.item, `op://IAS/${app} OTA`);
+  const keyId = values.keyid ?? existing?.keyId ?? expo.updates?.codeSigningMetadata?.keyid ?? `${app}-ota-1`;
+
+  if (!KEY_ID.test(keyId)) throw new IasError(`«${keyId}» is not a valid keyid`, { fix: 'letters, digits, dots, hyphens and underscores, up to 64' });
+  if (expo.updates?.codeSigningMetadata?.keyid && expo.updates.codeSigningMetadata.keyid !== keyId) {
+    throw new IasError(`app.json carries the keyid ${expo.updates.codeSigningMetadata.keyid}, not ${keyId}`, { fix: `pass --keyid ${expo.updates.codeSigningMetadata.keyid}, or change app.json and make a new build` });
+  }
+  if (expo.updates?.codeSigningCertificate && !existing) {
+    throw new IasError(`app.json already carries updates.codeSigningCertificate (${expo.updates.codeSigningCertificate})`, { fix: 'ias update init is for a new key: keep the certificate the app already has, or remove it and make a new build' });
+  }
+
+  let privateKey = null;
+  let certificate = null;
+  let certificatePath = existing?.certificate ?? 'certs/ota-certificate.pem';
+
+  if (!dryRun) {
+    const itemKey = readField(item, 'private-key', env) ?? readField(item, 'private-key.pem', env);
+    const itemCertificate = readField(item, 'certificate', env) ?? readField(item, 'certificate.pem', env);
+    if ((itemKey === undefined) !== (itemCertificate === undefined)) {
+      throw new IasError(`${item} has only one of the private key and the certificate`, { fix: 'restore the item from 1Password history, or remove it and run ias update init again' });
+    }
+
+    if (existing) {
+      certificate = readFileSync(join(dir, existing.certificate), 'utf8');
+      privateKey = readField(item, 'private-key', env) ?? readField(item, 'private-key.pem', env) ?? readField(existing.privateKey, 'private-key', env) ?? readField(existing.privateKey, 'private-key.pem', env);
+      if (!privateKey) throw new IasError(`no private key for ${existing.privateKey}`, { fix: 'the key of the certificate is not in 1Password: restore the item, or make a new key and a new build' });
+      certificatePath = existing.certificate;
+    } else if (itemKey && itemCertificate) {
+      privateKey = itemKey;
+      certificate = itemCertificate;
+      writeFileSync(join(dir, certificatePath), certificate, { mode: 0o644 });
+      output?.log(`${output.prefix}: ${item} already has the signing key; wrote ${certificatePath}`);
+    } else {
+      const made = generateKeyPair({ dir, app, certificatePath, dryRun, output });
+      privateKey = made.privateKey;
+      certificate = made.certificate;
+    }
+  } else if (!existing) {
+    output?.progress(`${output.prefix}: would make an RSA key and a certificate at ${certificatePath}`);
+  }
+
+  if (dryRun) {
+    output?.log(`${output.prefix}: would make the OTA project ${app} on ${server} (keyid ${keyId}) and keep its key and token in ${item}`);
+    return { server, app, project: app, keyid: keyId, item, certificate: certificatePath, dry_run: true };
+  }
+
+  const parsed = readCertificate(join(dir, certificatePath));
+  const api = clientOf(client, project, env, sleep);
+
+  let response;
+  try {
+    response = await api.request('POST', `/apps/${app}/updates`, { json: { certificate, key_id: keyId, name } });
+  } catch (error) {
+    if (error.code === 'project_exists') throw new IasError(error.message, { fix: 'the application already has an OTA project with another certificate: rotate it with php artisan ota:project --force and a new build, or use the key the builds carry' });
+    throw error;
+  }
+
+  const created = response.status === 201;
+  const projectSlug = response.data?.project?.project ?? app;
+  let token = response.data?.token ?? null;
+  const itemToken = readField(item, 'token', env) ?? readField(item, 'credential', env);
+  const configToken = config.updates?.token;
+
+  if (!token && !itemToken && !configToken) {
+    const rotated = await api.request('POST', `/apps/${app}/updates/token`, {});
+    token = rotated.data?.token ?? null;
+  }
+
+  if (token) {
+    if (readField(item, 'private-key', env) === undefined && readField(item, 'private-key.pem', env) === undefined) {
+      createItem(item, {
+        notes: `The signing key of the OTA updates of ${name} (${server}). The private key signs every manifest; it never leaves this item. Made by ias update init.`,
+        fields: [
+          { label: 'private-key', value: privateKey, type: 'CONCEALED' },
+          { label: 'certificate', value: certificate },
+          { label: 'key-id', value: keyId },
+          { label: 'token', value: token, type: 'CONCEALED' },
+          { label: 'project', value: projectSlug },
+          { label: 'server', value: server },
+        ],
+      }, env);
+      output?.log(`${output.prefix}: created ${item} with the signing key and the publishing token`);
+    } else {
+      setField(item, 'token', token, env);
+      output?.log(`${output.prefix}: wrote the publishing token to ${item}`);
+    }
+  } else if (readField(item, 'private-key', env) === undefined && readField(item, 'private-key.pem', env) === undefined) {
+    createItem(item, {
+      notes: `The signing key of the OTA updates of ${name} (${server}). The private key signs every manifest; it never leaves this item. Made by ias update init.`,
+      fields: [
+        { label: 'private-key', value: privateKey, type: 'CONCEALED' },
+        { label: 'certificate', value: certificate },
+        { label: 'key-id', value: keyId },
+        { label: 'project', value: projectSlug },
+        { label: 'server', value: server },
+      ],
+    }, env);
+    output?.log(`${output.prefix}: created ${item} with the signing key`);
+  }
+
+  const privateKeyRef = existing?.privateKey ?? `${refOf(item)}/private-key`;
+  const tokenRef = token || itemToken ? `${refOf(item)}/token` : configToken;
+  config.updates = {
+    ...(config.updates ?? {}),
+    signing: { keyId, privateKey: privateKeyRef, certificate: certificatePath },
+    ...(tokenRef ? { token: tokenRef } : {}),
+  };
+  saveProjectConfig(dir, config, { dryRun });
+  output?.log(`${output.prefix}: OTA project ${projectSlug} on ${server} (keyid ${keyId}, certificate ${certificatePath})`);
+  output?.log(`${output.prefix}: key and token in ${item}; ias.json has their op:// references`);
+  output?.log(`${output.prefix}: publish with ias update publish --message "…" (a build with this certificate is needed first)`);
+  return {
+    server,
+    app,
+    project: projectSlug,
+    keyid: keyId,
+    item,
+    certificate: certificatePath,
+    certificate_sha256: parsed.fingerprint256,
+    created,
+    token_created: Boolean(token),
+    manifest_url: response.data?.project?.manifest_url ?? `${server}/api/v1/ota/${projectSlug}/manifest`,
+  };
+}
+
+/** Makes sure the app has its distribution project and its token in 1Password, and writes the reference in ias.json. */
+export async function provisionDistribution({ dir, env = process.env, output, values = {}, client, sleep, dryRun = values['dry-run'] === true }) {
+  const { project, config, app, expo } = projectOf(dir);
+  const server = serverOrigin(project, env);
+  const name = values.name ?? expo.name ?? app;
+  const item = itemOption(values.item, `op://IAS/${app} distribution`);
+
+  if (dryRun) {
+    output?.log(`${output.prefix}: would make the distribution project ${app} on ${server} and keep its token in ${item}`);
+    return { server, app, project: app, item, dry_run: true };
+  }
+
+  const api = clientOf(client, project, env, sleep);
+  const response = await api.request('POST', `/apps/${app}/distribution`, { json: { name } });
+  const projectSlug = response.data?.project?.project ?? app;
+  let token = response.data?.token ?? null;
+  const itemToken = readField(item, 'token', env) ?? readField(item, 'credential', env);
+  const configToken = config.distribution?.token;
+
+  if (!token && !itemToken && !configToken) {
+    const rotated = await api.request('POST', `/apps/${app}/distribution/token`, {});
+    token = rotated.data?.token ?? null;
+  }
+
+  if (token) {
+    if (itemToken === undefined) {
+      createItem(item, {
+        notes: `The publishing token of the internal distribution of ${name} (${server}). It uploads and retires builds; it does nothing else. Made by ias dist init.`,
+        fields: [
+          { label: 'token', value: token, type: 'CONCEALED' },
+          { label: 'project', value: projectSlug },
+          { label: 'server', value: server },
+        ],
+      }, env);
+      output?.log(`${output.prefix}: created ${item} with the publishing token`);
+    } else {
+      setField(item, 'token', token, env);
+      output?.log(`${output.prefix}: wrote the publishing token to ${item}`);
+    }
+  }
+
+  config.distribution = { ...(config.distribution ?? {}), token: `${refOf(item)}/token` };
+  saveProjectConfig(dir, config, { dryRun });
+  const install = response.data?.project?.install_url ?? `${server}/install/<token>`;
+  output?.log(`${output.prefix}: distribution project ${projectSlug} on ${server}: ${install}`);
+  output?.log(`${output.prefix}: the token is in ${item}; ias.json has its op:// reference`);
+  return { server, app, project: projectSlug, item, install_url: install, created: response.status === 201, token_created: Boolean(token) };
+}
+
+/** Makes a robot token of the application for CI, keeps it in 1Password and says where. It never prints the token. */
+export async function createRobotToken({ dir, env = process.env, output, values = {}, client, sleep, dryRun = values['dry-run'] === true }) {
+  const { project, app: configuredApp, expo } = projectOf(dir);
+  const app = values.app ?? configuredApp;
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(app)) throw new IasError(`«${app}» is not the code of an application`, { fix: 'ias apps lists them' });
+  const server = serverOrigin(project, env);
+  const name = values.name ?? 'CI';
+  const item = itemOption(values.item, `op://IAS/${app} CI`);
+  const scopes = values.scopes ? String(values.scopes).split(',').map((scope) => scope.trim()).filter(Boolean) : ['apps:read', 'builds:create'];
+  const days = Number(values.days ?? 90);
+
+  if (dryRun) {
+    output?.log(`${output.prefix}: would make a robot token «${name}» of ${app} (${scopes.join(', ')}, ${days} days) and keep it in ${item}`);
+    return { server, app, name, scopes, days, item, dry_run: true };
+  }
+
+  const api = clientOf(client, project, env, sleep);
+  const response = await api.request('POST', `/apps/${app}/tokens`, { json: { name, scopes, days } });
+  const token = response.data?.token;
+  if (!token) throw new IasError('the server did not return the robot token', { fix: 'this is a bug of ias or the server: report it with what you ran' });
+
+  if (readField(item, 'token', env) === undefined && readField(item, 'credential', env) === undefined) {
+    createItem(item, {
+      notes: `Robot token «${name}» of ${app} (${server}), scopes ${scopes.join(', ')}, until ${response.data?.expires_at ?? `${days} days`}. It works without a person: keep it only in CI. Made by ias tokens create.`,
+      fields: [
+        { label: 'token', value: token, type: 'CONCEALED' },
+        { label: 'scopes', value: scopes.join(',') },
+        { label: 'expires-at', value: String(response.data?.expires_at ?? '') },
+        { label: 'application', value: app },
+      ],
+    }, env);
+  } else {
+    setField(item, 'token', token, env);
+  }
+
+  output?.log(`${output.prefix}: robot token «${name}» of ${app} in ${item} (scopes ${scopes.join(', ')}, until ${response.data?.expires_at ?? `${days} days`})`);
+  output?.log(`${output.prefix}: in CI, set IAS_TOKEN from that item, or keep the reference ${refOf(item)}/token`);
+  return { server, app, id: response.data?.id, name, scopes, expires_at: response.data?.expires_at, item };
+}
+
+/** A one-time code to register a runner (valid 30 minutes, once). The code is printed once and not stored. */
+export async function createRunnerCode({ dir, env = process.env, output, client, sleep, dryRun = false }) {
+  const { project } = projectOf(dir);
+  const server = serverOrigin(project, env);
+  if (dryRun) {
+    output?.log(`${output.prefix}: would make a one-time runner code on ${server}`);
+    return { server, dry_run: true };
+  }
+  const api = clientOf(client, project, env, sleep);
+  const response = await api.request('POST', '/runners/codes', {});
+  output?.log(`${output.prefix}: runner code ${response.data.code} (valid until ${response.data.expires_at})`);
+  output?.log(`${output.prefix}: on the runner Mac: ${response.data.register}`);
+  output?.log(`${output.prefix}: then authorize it here with ias vault grant "<its name>"`);
+  return { server, ...response.data };
+}

package/src/schema.mjs

@@ -112,6 +112,9 @@ function check(value, node, path, root, errors) {
       case 'maxItems':
         if (Array.isArray(value) && value.length > rule) errors.push(`${at(path)} must have at most ${rule} items`);
         break;
+      case 'maxProperties':
+        if (typeOf(value) === 'object' && Object.keys(value).length > rule) errors.push(`${at(path)} must have at most ${rule} fields`);
+        break;
       case 'minProperties':
         if (typeOf(value) === 'object' && Object.keys(value).length < rule) errors.push(`${at(path)} must have at least ${rule} fields`);
         break;

package/src/setup-state.mjs

@@ -0,0 +1,76 @@
+// The state of ias setup: which services the app uses and what a person acknowledged. It lives outside the repository,
+// because ias build refuses a dirty tree and onboarding is per computer (a teammate runs ias setup on theirs).
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+
+export const SETUP_STATE_VERSION = 1;
+
+/** The services of an application, as the panel and the management API name them. */
+export const SERVICES = Object.freeze(['updates', 'distribution', 'push']);
+
+/** The folder of the state of this computer: IAS_STATE_DIR, or the one of the platform. */
+export function stateHome(env = process.env) {
+  if (env.IAS_STATE_DIR) return resolve(env.IAS_STATE_DIR);
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Application Support', 'ias');
+  return join(env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'ias');
+}
+
+/** The file of the setup of `dir`: one per app, named after its real path. */
+export function setupStateFile(dir, env = process.env) {
+  const key = createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 24);
+  return join(stateHome(env), 'setup', `${key}.json`);
+}
+
+/** The state of `dir`: { version, dir, services, acknowledged, updated_at }, or a new one. */
+export function readSetupState(dir, env = process.env) {
+  const file = setupStateFile(dir, env);
+  if (!existsSync(file)) return { version: SETUP_STATE_VERSION, dir: resolve(dir), services: undefined, acknowledged: {}, updated_at: null };
+  try {
+    const state = JSON.parse(readFileSync(file, 'utf8'));
+    if (state.version !== SETUP_STATE_VERSION) return { version: SETUP_STATE_VERSION, dir: resolve(dir), services: state.services, acknowledged: {}, updated_at: null };
+    return { version: SETUP_STATE_VERSION, dir: resolve(dir), services: state.services, acknowledged: state.acknowledged ?? {}, updated_at: state.updated_at ?? null };
+  } catch {
+    return { version: SETUP_STATE_VERSION, dir: resolve(dir), services: undefined, acknowledged: {}, updated_at: null };
+  }
+}
+
+/** Writes the state of `dir` with mode 600, in a folder with mode 700. It holds no secret. */
+export function writeSetupState(dir, { services, acknowledged }, env = process.env) {
+  const file = setupStateFile(dir, env);
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const state = { version: SETUP_STATE_VERSION, dir: resolve(dir), services, acknowledged, updated_at: new Date().toISOString() };
+  writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  return state;
+}
+
+/** Forgets the state of `dir` (ias setup reset): the checklist starts from what the files and the server say. */
+export function resetSetupState(dir, env = process.env) {
+  rmSync(setupStateFile(dir, env), { force: true });
+}
+
+/** The services of `--services`: a comma-separated list of updates, distribution and push, or one of them. */
+export function parseServices(text) {
+  const names = String(text).split(',').map((name) => name.trim()).filter(Boolean);
+  const unknown = names.filter((name) => !SERVICES.includes(name));
+  if (unknown.length > 0) return { error: `unknown service ${unknown.join(', ')}` };
+  return { services: [...new Set(names)] };
+}
+
+/**
+ * The services of an app when nobody said: those its configuration and its app.json show, or updates and distribution
+ * for a new one, which is what ias is for.
+ */
+export function inferServices({ config, expo, dependencies = {} }) {
+  const services = new Set();
+  if (config?.updates || expo?.updates?.url) services.add('updates');
+  if (config?.distribution) services.add('distribution');
+  if (config?.push || dependencies['expo-notifications']) services.add('push');
+  if (services.size === 0) {
+    services.add('updates');
+    services.add('distribution');
+  }
+  return [...services];
+}