@imagina-build/ias-cli 0.0.0 → 0.1.0

package/src/schema.mjs

@@ -0,0 +1,131 @@
+// ias.json and its JSON Schema (schema/ias.schema.json), which the runner and the SDK read too. The validator covers
+// the part of JSON Schema 2020-12 that the schema uses; a keyword it does not know is an error, so the schema cannot
+// grow past what is checked.
+import { readFileSync } from 'node:fs';
+
+export const SCHEMA_URL = new URL('../schema/ias.schema.json', import.meta.url);
+
+let schema;
+
+/** The JSON Schema of ias.json. */
+export function iasSchema() {
+  schema ??= JSON.parse(readFileSync(SCHEMA_URL, 'utf8'));
+  return schema;
+}
+
+/** Keywords that only describe: they never fail. */
+const ANNOTATIONS = new Set(['$schema', '$id', '$comment', 'title', 'description', 'default', 'examples', 'markdownDescription', 'deprecated', 'format']);
+
+const typeOf = (value) => (value === null ? 'null' : Array.isArray(value) ? 'array' : Number.isInteger(value) ? 'integer' : typeof value);
+const matchesType = (value, type) => typeOf(value) === type || (type === 'number' && typeOf(value) === 'integer');
+const show = (value) => JSON.stringify(value);
+const at = (path) => (path.length > 0 ? path.join('.') : 'the file');
+
+/**
+ * The errors of `value` against `schema` (the schema of ias.json by default), as sentences that start with the path:
+ * «build.preview.android.format must be one of "apk", "aab"». An empty list means it is valid.
+ */
+export function validate(value, rootSchema = iasSchema()) {
+  const errors = [];
+  check(value, rootSchema, [], rootSchema, errors);
+  return errors;
+}
+
+function resolveRef(ref, root) {
+  if (!ref.startsWith('#/')) throw new Error(`the schema refers to ${ref}: only #/… references are supported`);
+  const node = ref.slice(2).split('/').reduce((parent, key) => parent?.[key.replaceAll('~1', '/').replaceAll('~0', '~')], root);
+  if (node === undefined) throw new Error(`the schema has no ${ref}`);
+  return node;
+}
+
+function check(value, node, path, root, errors) {
+  if (node === true) return;
+  if (node === false) {
+    errors.push(`${at(path)} is not allowed`);
+    return;
+  }
+  for (const [keyword, rule] of Object.entries(node)) {
+    if (ANNOTATIONS.has(keyword) || keyword === '$defs') continue;
+    switch (keyword) {
+      case '$ref':
+        check(value, resolveRef(rule, root), path, root, errors);
+        break;
+      case 'type': {
+        const types = [rule].flat();
+        if (!types.some((type) => matchesType(value, type))) {
+          errors.push(`${at(path)} must be ${types.map((type) => (/^[aeiou]/.test(type) ? `an ${type}` : `a ${type}`)).join(' or ')}`);
+          return;
+        }
+        break;
+      }
+      case 'enum':
+        if (!rule.some((option) => JSON.stringify(option) === JSON.stringify(value))) errors.push(`${at(path)} must be one of ${rule.map(show).join(', ')}`);
+        break;
+      case 'const':
+        if (JSON.stringify(rule) !== JSON.stringify(value)) errors.push(`${at(path)} must be ${show(rule)}`);
+        break;
+      case 'pattern':
+        if (typeof value === 'string' && !new RegExp(rule, 'u').test(value)) errors.push(`${at(path)} (${show(value)}) must match ${rule}`);
+        break;
+      case 'minLength':
+        if (typeof value === 'string' && [...value].length < rule) errors.push(`${at(path)} must have at least ${rule} characters`);
+        break;
+      case 'maxLength':
+        if (typeof value === 'string' && [...value].length > rule) errors.push(`${at(path)} must have at most ${rule} characters`);
+        break;
+      case 'minimum':
+        if (typeof value === 'number' && value < rule) errors.push(`${at(path)} must be at least ${rule}`);
+        break;
+      case 'maximum':
+        if (typeof value === 'number' && value > rule) errors.push(`${at(path)} must be at most ${rule}`);
+        break;
+      case 'required':
+        if (typeOf(value) === 'object') for (const key of rule) if (!(key in value)) errors.push(`${at([...path, key])} is missing`);
+        break;
+      case 'properties':
+        if (typeOf(value) === 'object') for (const [key, child] of Object.entries(rule)) if (key in value) check(value[key], child, [...path, key], root, errors);
+        break;
+      case 'propertyNames':
+        if (typeOf(value) === 'object') {
+          for (const key of Object.keys(value)) {
+            const nameErrors = [];
+            check(key, rule, [...path, key], root, nameErrors);
+            if (nameErrors.length > 0) errors.push(`${at(path)} has a key that is not valid (${show(key)})`);
+          }
+        }
+        break;
+      case 'additionalProperties':
+        if (typeOf(value) === 'object') {
+          const known = Object.keys(node.properties ?? {});
+          for (const key of Object.keys(value).filter((candidate) => !known.includes(candidate))) {
+            if (rule === false) errors.push(`${at(path)} has an unknown key ${show(key)}`);
+            else check(value[key], rule, [...path, key], root, errors);
+          }
+        }
+        break;
+      case 'items':
+        if (Array.isArray(value)) value.forEach((item, index) => check(item, rule, [...path, String(index)], root, errors));
+        break;
+      case 'minItems':
+        if (Array.isArray(value) && value.length < rule) errors.push(`${at(path)} must have at least ${rule} items`);
+        break;
+      case 'maxItems':
+        if (Array.isArray(value) && value.length > rule) errors.push(`${at(path)} must have at most ${rule} items`);
+        break;
+      case 'minProperties':
+        if (typeOf(value) === 'object' && Object.keys(value).length < rule) errors.push(`${at(path)} must have at least ${rule} fields`);
+        break;
+      case 'uniqueItems':
+        if (rule && Array.isArray(value) && new Set(value.map((item) => JSON.stringify(item))).size !== value.length) errors.push(`${at(path)} must not repeat items`);
+        break;
+      case 'anyOf':
+      case 'oneOf': {
+        const matching = rule.filter((option) => validate(value, { ...option, $defs: root.$defs }).length === 0).length;
+        if (matching === 0 || (keyword === 'oneOf' && matching > 1)) errors.push(`${at(path)} (${show(value)}) does not match any of the allowed forms`);
+        break;
+      }
+      default:
+        throw new Error(`the schema uses ${keyword}, which this validator does not check`);
+    }
+  }
+}

package/src/sdk.mjs

@@ -0,0 +1,120 @@
+// The SDK @imagina/ias (packages/sdk) in an app: which package manager installs it, where it comes from, whether it is
+// installed and compatible with this ias, and its config plugin in the plugins of app.json. ias sdk install and ias
+// doctor share it.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from './cli.mjs';
+import { DYNAMIC_CONFIGS, IAS_PLUGINS, readExpo, readJson } from './config.mjs';
+import { IasError } from './errors.mjs';
+import { INSTALLS } from './ota.mjs';
+
+export const SDK_PACKAGE = '@imagina/ias';
+
+/**
+ * The registry the packages are published to (scripts/publish.mjs) and their scope there: the public npm registry,
+ * where the organization is imagina-build, so @imagina/ias goes out as @imagina-build/ias and the apps install it under
+ * its own name with an alias (@imagina/ias@npm:@imagina-build/ias@…). Installing needs no token.
+ */
+export const REGISTRY = 'https://registry.npmjs.org';
+export const REGISTRY_SCOPE = 'imagina-build';
+export const REGISTRY_SDK = `@${REGISTRY_SCOPE}/ias`;
+
+/** How each package manager adds a dependency. */
+const ADD = { npm: ['install'], yarn: ['add'], pnpm: ['add'], bun: ['add'] };
+
+/** The SDK next to this CLI when it runs from a clone of the repository (packages/sdk), or undefined. */
+export function repositorySdk() {
+  const dir = fileURLToPath(new URL('../../sdk/', import.meta.url));
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name === SDK_PACKAGE ? resolve(dir) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The range ias sdk install asks for: ^VERSION, the same minor while the major is 0. */
+export const compatibleRange = (version = VERSION) => `^${version}`;
+
+/** Whether `version` of the SDK speaks the same ias.json as `cliVersion`: the same major, and the same minor while it is 0. */
+export function isCompatible(version, cliVersion = VERSION) {
+  const [major, minor] = String(version).split('.').map(Number);
+  const [cliMajor, cliMinor] = String(cliVersion).split('.').map(Number);
+  return major === cliMajor && (major !== 0 || minor === cliMinor);
+}
+
+/**
+ * Where the SDK is installed from: --from, IAS_SDK_SOURCE, the packages/sdk of the repository when ias runs from a
+ * clone, or npm (REGISTRY_SDK@^VERSION under the name @imagina/ias). { spec, origin }; a folder of the
+ * repository becomes a path relative to the app, as package.json keeps it.
+ */
+export function sdkSource(dir, { from, env = {}, repository = repositorySdk() } = {}) {
+  const asSpec = (value) => (!/^[a-z+]+:/i.test(value) && existsSync(resolve(dir, value)) ? `file:${relative(dir, resolve(dir, value)) || '.'}` : value);
+  if (from) return { spec: asSpec(from), origin: '--from' };
+  if (env.IAS_SDK_SOURCE) return { spec: asSpec(env.IAS_SDK_SOURCE), origin: 'IAS_SDK_SOURCE' };
+  if (repository) return { spec: `file:${relative(dir, repository)}`, origin: 'the packages/sdk of the repository ias runs from', folder: repository };
+  return { spec: `${SDK_PACKAGE}@npm:${REGISTRY_SDK}@${compatibleRange()}`, origin: `npm (${REGISTRY_SDK})` };
+}
+
+/** The package manager of the app: packageManager of package.json, or the first lockfile from `dir` up; npm without one. */
+export function packageManager(dir) {
+  const declared = readPackageJson(dir)?.packageManager;
+  const named = typeof declared === 'string' ? declared.split('@')[0] : undefined;
+  if (ADD[named]) return { name: named, from: 'packageManager of package.json' };
+  for (let current = resolve(dir); ; current = dirname(current)) {
+    const install = INSTALLS.find(([lockfile]) => existsSync(join(current, lockfile)));
+    if (install) return { name: install[1], from: relative(dir, join(current, install[0])) || install[0] };
+    if (dirname(current) === current) return { name: 'npm', from: 'no lockfile' };
+  }
+}
+
+/** The command that adds `spec` with `manager`: [program, args]. */
+export const addCommand = (manager, spec) => [manager, [...ADD[manager], spec]];
+
+function readPackageJson(dir) {
+  const file = join(dir, 'package.json');
+  return existsSync(file) ? readJson(file, 'package.json', 'fix package.json: ias reads the dependencies of the app from it') : undefined;
+}
+
+/**
+ * The SDK in the app in `dir`: { packageJson (whether there is one), declared (its range in the dependencies),
+ * installed (the version in node_modules), plugin (yes, no, or dynamic when an app.config.* may add it), dynamic }.
+ */
+export function sdkState(dir) {
+  const pkg = readPackageJson(dir);
+  const declared = pkg?.dependencies?.[SDK_PACKAGE] ?? pkg?.devDependencies?.[SDK_PACKAGE];
+  let installed;
+  for (let current = resolve(dir); ; current = dirname(current)) {
+    const file = join(current, 'node_modules', SDK_PACKAGE, 'package.json');
+    if (existsSync(file)) {
+      installed = readJson(file, `node_modules/${SDK_PACKAGE}/package.json`, 'install the SDK again (ias sdk install)').version;
+      break;
+    }
+    if (dirname(current) === current) break;
+  }
+  const dynamic = DYNAMIC_CONFIGS.find((name) => existsSync(join(dir, name)));
+  const listed = hasIasPlugin(readExpo(dir)?.plugins);
+  return { packageJson: Boolean(pkg), declared, installed, plugin: listed ? 'yes' : dynamic ? 'dynamic' : 'no', dynamic, dependencies: { ...pkg?.devDependencies, ...pkg?.dependencies } };
+}
+
+const hasIasPlugin = (plugins) => (Array.isArray(plugins) ? plugins : []).some((entry) => IAS_PLUGINS.includes(Array.isArray(entry) ? entry[0] : entry));
+
+/**
+ * Adds "@imagina/ias" to the plugins of app.json, keeping the rest of the file and its indentation: { changed, reason }.
+ * With an app.config.*, which ias cannot rewrite, it changes nothing and says so (reason dynamic).
+ */
+export function addPlugin(dir, { dryRun = false } = {}) {
+  const dynamic = DYNAMIC_CONFIGS.find((name) => existsSync(join(dir, name)));
+  if (dynamic) return { changed: false, reason: 'dynamic', file: dynamic };
+  const file = join(dir, 'app.json');
+  if (!existsSync(file)) throw new IasError(`no app.json in ${dir}`, { fix: 'run it in the folder of the Expo app, or pass --project <app folder>' });
+  const text = readFileSync(file, 'utf8');
+  const appJson = readJson(file, 'app.json', 'fix app.json, then run ias sdk install again');
+  if (!appJson?.expo || typeof appJson.expo !== 'object') throw new IasError('app.json has no expo object', { fix: 'the config plugin goes in app.json › expo › plugins' });
+  if (appJson.expo.plugins !== undefined && !Array.isArray(appJson.expo.plugins)) throw new IasError('plugins of app.json is not a list', { fix: 'make it a list, such as "plugins": ["@imagina/ias"]' });
+  if (hasIasPlugin(appJson.expo.plugins)) return { changed: false, reason: 'present', file: 'app.json' };
+  appJson.expo.plugins = [...(appJson.expo.plugins ?? []), SDK_PACKAGE];
+  const indent = text.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
+  if (!dryRun) writeFileSync(file, `${JSON.stringify(appJson, null, indent)}\n`);
+  return { changed: true, reason: 'added', file: 'app.json' };
+}

package/src/secret-input.mjs

@@ -0,0 +1,27 @@
+// Where a command reads a secret it was given: an op:// reference, an environment variable (env:NAME) or stdin (-).
+// Never the secret itself on the command line, where ps and the history of the shell would keep it.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { IasError } from './errors.mjs';
+import { isReference, readSecret, readSecretFile } from './secrets.mjs';
+
+/** The value of a secret given as op://…, env:NAME or - (stdin, without its last newline). */
+export function secretValue(spec, { env, option, stdin = () => readFileSync(0, 'utf8') }) {
+  if (typeof spec !== 'string' || spec === '') throw new IasError(`${option} is missing`, { fix: `give it as an op:// reference, env:NAME (a variable of the environment) or - (stdin)` });
+  if (isReference(spec)) return readSecret(spec, { env });
+  if (spec.startsWith('env:')) {
+    const name = spec.slice(4);
+    if (env[name] === undefined) throw new IasError(`${option} is env:${name}, but ${name} is not set`, { fix: `export ${name} first, or give an op:// reference` });
+    return env[name];
+  }
+  if (spec === '-') return stdin().replace(/\r?\n$/, '');
+  throw new IasError(`${option} takes a reference, not the secret itself`, { fix: 'a secret on the command line is seen by ps and kept in the shell history: give op://…, env:NAME or - (stdin)', code: 'secret_on_command_line' });
+}
+
+/** A file given as a path or an op:// reference (read with op into this run's temporary folder): its path. */
+export function filePath(spec, { env, cwd, name }) {
+  if (isReference(spec)) return readSecretFile(spec, name, { env });
+  const path = resolve(cwd, spec);
+  if (!existsSync(path) || !statSync(path).isFile()) throw new IasError(`there is no file at ${spec}`, { fix: 'give a path or an op:// reference to the file in 1Password' });
+  return path;
+}

package/src/secrets.mjs

@@ -0,0 +1,37 @@
+// Secrets: never in a file of the repository. They are read from 1Password (op:// references) or from the environment.
+import { join } from 'node:path';
+import { temporary, run } from './process.mjs';
+
+export const isReference = (value) => typeof value === 'string' && value.startsWith('op://');
+
+/** The value of an op:// reference, with the 1Password CLI (Touch ID with the desktop app), or `value` as it is. */
+export const readSecret = (value, { stdio = ['inherit', 'pipe', 'inherit'], env } = {}) => (isReference(value) ? run('op', ['read', '--no-newline', value], { label: `op read ${value}`, stdio, ...(env ? { env } : {}) }) : value);
+
+/** An op:// reference written to a file of this run's temporary folder, readable only by this user; returns its path. */
+export function readSecretFile(reference, name, { env } = {}) {
+  const path = join(temporary(), name);
+  run('op', ['read', '--file-mode', '0600', '--out-file', path, reference], { label: `op read ${reference}`, stdio: ['inherit', 'ignore', 'inherit'], ...(env ? { env } : {}) });
+  return path;
+}
+
+/** What a secret written in a file looks like: a token of IAS (ota_, dist_, iasp_, iasr_) or a PEM block. */
+const SECRET = /^(?:(?:ota|dist|iasp|iasr)_[A-Za-z0-9_-]{16,}|-----BEGIN [A-Z ]+-----)/;
+
+/**
+ * The paths («updates.token») of the secrets written in a configuration: any `token` or `privateKey` that is not an
+ * op:// reference, and any value that looks like a token or a key.
+ */
+export function writtenSecrets(value, path = []) {
+  if (typeof value === 'string') {
+    const key = path.at(-1);
+    return (['token', 'privateKey'].includes(key) && !isReference(value)) || SECRET.test(value.trim()) ? [path.join('.')] : [];
+  }
+  if (Array.isArray(value)) return value.flatMap((item, index) => writtenSecrets(item, [...path, String(index)]));
+  if (value && typeof value === 'object') return Object.entries(value).flatMap(([key, item]) => writtenSecrets(item, [...path, key]));
+  return [];
+}
+
+/** The kind of a token by its prefix: ota_ and dist_ are today's robot tokens; iasp_ and iasr_ come with track 1A. */
+export function tokenKind(token) {
+  return token.match(/^(ota|dist|iasp|iasr)_/)?.[1];
+}

package/src/shared.mjs

@@ -0,0 +1,5 @@
+// What the CLI takes from @imagina/ias-shared (packages/shared): the vault (docs/technical/vault.md) and the reading of the
+// signing credentials. The packages have no dependencies (decision D5), so it is a path inside the repository; npm pack
+// does not take ../shared with it, so scripts/pack.mjs packs a copy with shared/ inside and points these imports there.
+export * from '../shared/vault/index.mjs';
+export * as credentials from '../shared/credentials/index.mjs';

package/src/team-vault.mjs

@@ -0,0 +1,152 @@
+// The team's keys of the vault (docs/technical/vault.md §2): the recovery key (X25519) and the signing key (Ed25519), in one
+// 1Password item that ias vault init creates. The CLI trusts that item, never the server: before sealing it compares
+// the public keys of the item with the ones of GET /vault, and it seals only for the runners of the list the team
+// signed. Private keys are read with op read into memory, never printed, never written to a file nor a command line.
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { FORMAT, keyId, publicRecipient, signingKeyFromPrivateKey, verifyRunnerList } from './shared.mjs';
+import { IasError } from './errors.mjs';
+
+/** The fields of the 1Password item, as docs/technical/vault.md §2.2 lists them. */
+export const ITEM_FIELDS = Object.freeze({
+  recoveryPrivateKey: 'recovery-private-key',
+  recoveryPublicKey: 'recovery-public-key',
+  recoveryKid: 'recovery-kid',
+  signingPrivateKey: 'signing-private-key',
+  signingPublicKey: 'signing-public-key',
+  signingKid: 'signing-kid',
+  format: 'format',
+  server: 'server',
+});
+
+const ITEM = /^op:\/\/([^/\s]+)\/([^/]+)$/;
+
+/**
+ * The 1Password item of the vault of `server`: --item, IAS_VAULT_ITEM, vault.item of ias.json, or op://Private/IAS
+ * vault <host>. Returns { reference, vault, title }.
+ */
+export function vaultItem(context, project, server) {
+  const reference = context.values?.item ?? context.env.IAS_VAULT_ITEM ?? project?.config?.vault?.item ?? `op://Private/IAS vault ${new URL(server).hostname}`;
+  const match = ITEM.exec(reference);
+  if (!match) throw new IasError(`«${reference}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://Private/IAS vault ias.imagina.build' });
+  return { reference, vault: match[1], title: match[2] };
+}
+
+const op = (args, { env, input } = {}) => spawnSync('op', args, { encoding: 'utf8', env, input, maxBuffer: 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+
+/** The first line of what op said, which names the reference and never a value. */
+const opReason = (result) => (result.error ? result.error.message : (result.stderr || '').trim().split('\n').at(-1) || `exit ${result.status}`);
+
+/** A field of the item, or undefined if the item has no such field or does not exist. Throws if op cannot answer. */
+export function readField(item, name, env = process.env) {
+  const result = op(['read', '--no-newline', `${item.reference}/${name}`], { env });
+  if (result.status === 0) return result.stdout;
+  const reason = opReason(result);
+  if (/isn't an item|isn.t a field|not found|no item|could not find|does not have a field/i.test(reason)) return undefined;
+  throw new IasError(`op could not read ${item.reference}/${name}: ${reason}`, { fix: result.error ? 'install the 1Password CLI (brew install 1password-cli) and turn on its integration with the desktop app' : 'unlock 1Password (op signin) and check that the item and its vault exist' });
+}
+
+/** The public keys of the item, each with its kid checked: { recovery, signing } ({ kid, publicKey }), or undefined. */
+export function publicKeysOf(item, env = process.env) {
+  const recovery = readField(item, ITEM_FIELDS.recoveryPublicKey, env);
+  if (recovery === undefined) return undefined;
+  const signing = readField(item, ITEM_FIELDS.signingPublicKey, env);
+  if (signing === undefined) throw new IasError(`${item.reference} has a recovery key but no signing key`, { fix: 'it was made by an older ias: the vault needs both (docs/technical/vault.md §2.2)' });
+  try {
+    return { recovery: publicRecipient({ kind: 'recovery', kid: keyId(recovery), publicKey: recovery }), signing: { kid: keyId(signing), publicKey: signing } };
+  } catch {
+    throw new IasError(`the public keys in ${item.reference} are not valid`, { fix: 'restore the item from 1Password\'s history' });
+  }
+}
+
+/** The team's private signing key, from the item, checked against the public one beside it. */
+export function signingKeyOf(item, keys, env = process.env) {
+  const seed = readField(item, ITEM_FIELDS.signingPrivateKey, env);
+  if (seed === undefined) throw new IasError(`${item.reference} has no ${ITEM_FIELDS.signingPrivateKey}`, { fix: 'signing needs the item ias vault init made, with its private keys: ask an owner to share it with you in 1Password' });
+  let pair;
+  try {
+    pair = signingKeyFromPrivateKey(seed);
+  } catch {
+    throw new IasError(`${ITEM_FIELDS.signingPrivateKey} of ${item.reference} is not a signing key`, { fix: 'restore the item from 1Password\'s history' });
+  }
+  if (pair.kid !== keys.signing.kid) throw new IasError(`the signing key in ${item.reference} does not match its public key`, { fix: 'restore the item from 1Password\'s history' });
+  return pair;
+}
+
+/**
+ * Creates the item with the keys of `recovery` and `signing` (pairs with their private key). The template goes to op
+ * through stdin, so no private key is ever an argument of a process.
+ */
+export function createItem(item, { recovery, signing, server }, env = process.env) {
+  const field = (label, value, type = 'STRING') => ({ id: label, label, type, value });
+  const template = {
+    title: item.title,
+    category: 'SECURE_NOTE',
+    fields: [
+      { id: 'notesPlain', type: 'STRING', purpose: 'NOTES', label: 'notesPlain', value: `The keys of the IAS vault of ${server} (${FORMAT}): the recovery key opens every sealed credential and the signing key signs them. Made by ias vault init. Never share them outside the team; see docs/technical/vault.md.` },
+      field(ITEM_FIELDS.recoveryPrivateKey, recovery.privateKey, 'CONCEALED'),
+      field(ITEM_FIELDS.recoveryPublicKey, recovery.publicKey),
+      field(ITEM_FIELDS.recoveryKid, recovery.kid),
+      field(ITEM_FIELDS.signingPrivateKey, signing.privateKey, 'CONCEALED'),
+      field(ITEM_FIELDS.signingPublicKey, signing.publicKey),
+      field(ITEM_FIELDS.signingKid, signing.kid),
+      field(ITEM_FIELDS.format, FORMAT),
+      field(ITEM_FIELDS.server, server),
+    ],
+  };
+  const result = op(['item', 'create', '--vault', item.vault, '--format', 'json', '-'], { env, input: JSON.stringify(template) });
+  if (result.status !== 0) throw new IasError(`op could not create ${item.reference}: ${opReason(result)}`, { fix: 'unlock 1Password (op signin) and check that the vault exists and you can write to it' });
+}
+
+/**
+ * The runners to seal for: those of the list the team signed (docs/technical/vault.md §2.3), checked with the team's signing
+ * public key of 1Password. Runners the server lists outside a valid signed list are left out, with a warning.
+ */
+export function signedRunners(vault, signing, output) {
+  const listed = Array.isArray(vault.runners) ? vault.runners : [];
+  if (!vault.runner_list) {
+    if (listed.length > 0) output?.warn(`the server lists ${listed.length} runner${listed.length === 1 ? '' : 's'} but no list signed by the team: sealing for the recovery key only (ias vault grant signs the list)`);
+    return { serial: null, runners: [] };
+  }
+  let verified;
+  try {
+    verified = verifyRunnerList(vault.runner_list, signing.publicKey);
+  } catch (error) {
+    throw new IasError(`the list of runners the server gives is not signed by the team (${error.code})`, { fix: 'nothing was sealed: someone may have changed it on the server; ias vault status says more', code: 'runner_list_invalid' });
+  }
+  const signed = new Set(verified.runners.map((runner) => runner.kid));
+  const outside = listed.filter((runner) => runner?.kid && !signed.has(runner.kid));
+  if (outside.length > 0) output?.warn(`${outside.length} runner${outside.length === 1 ? '' : 's'} of the server ${outside.length === 1 ? 'is' : 'are'} not in the list the team signed: left out`);
+  return verified;
+}
+
+/** The kids of the server's keys against the item's: [{ name, server, local, ok }]. */
+export function compareKeys(vault, keys) {
+  return ['recovery', 'signing'].map((name) => {
+    const remote = vault[`${name}_key`];
+    const local = keys?.[name];
+    return { name, server: remote ? { kid: remote.kid, publicKey: remote.public_key } : null, local: local ?? null, ok: Boolean(remote && local && remote.public_key === local.publicKey && remote.kid === local.kid) };
+  });
+}
+
+/**
+ * What sealing needs, all checked against 1Password: the recipients (the recovery key and the signed runners) and the
+ * team's signing key. Stops if the vault has no keys, if the server's keys are not the item's, or if the runner list
+ * does not verify.
+ */
+export async function sealingKeys(client, item, env, output) {
+  const { data: vault } = await client.request('GET', '/vault');
+  if (!vault.recovery_key || !vault.signing_key) throw new IasError('the vault has no keys yet', { fix: 'an owner of the team runs ias vault init', code: 'vault_not_ready' });
+  const keys = publicKeysOf(item, env);
+  if (!keys) throw new IasError(`there is no ${item.reference} in 1Password`, { fix: 'sealing needs the item of the vault: ask an owner to share it with you, or point --item (IAS_VAULT_ITEM, vault.item of ias.json) at it' });
+  const mismatched = compareKeys(vault, keys).filter((entry) => !entry.ok);
+  if (mismatched.length > 0) {
+    throw new IasError(`the ${mismatched.map((entry) => entry.name).join(' and ')} key${mismatched.length > 1 ? 's' : ''} of the server ${mismatched.length > 1 ? 'are' : 'is'} not the one${mismatched.length > 1 ? 's' : ''} in ${item.reference}`, {
+      fix: 'nothing was sealed: ias vault status shows both; if the server changed them, someone may be trying to read or replace the credentials',
+      code: 'vault_keys_mismatch',
+    });
+  }
+  const signingKey = signingKeyOf(item, keys, env);
+  const { runners } = signedRunners(vault, keys.signing, output);
+  return { recipients: [keys.recovery, ...runners], signingKey, keys, vault };
+}

package/src/token-store.mjs

@@ -0,0 +1,93 @@
+// Where ias login keeps the personal token (iasp_…) of each server: the macOS keychain (service ias, account the
+// origin of the server), a file with mode 600 elsewhere, or nowhere on CI, where IAS_TOKEN is the token. The token
+// never goes on a command line, where ps would show it: the keychain gets it through the stdin of security -i.
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { IasError } from './errors.mjs';
+
+export const KEYCHAIN_SERVICE = 'ias';
+export const STORES = Object.freeze(['keychain', 'file', 'none']);
+
+/**
+ * Which store this machine uses: IAS_TOKEN_STORE if it is set; none on CI (CI is set), where tokens come from
+ * IAS_TOKEN; the keychain on macOS; a file elsewhere.
+ */
+export function storeKind(env = process.env, platform = process.platform) {
+  if (env.IAS_TOKEN_STORE) {
+    if (!STORES.includes(env.IAS_TOKEN_STORE)) throw new IasError(`IAS_TOKEN_STORE is ${env.IAS_TOKEN_STORE}`, { fix: `it is one of ${STORES.join(', ')}` });
+    return env.IAS_TOKEN_STORE;
+  }
+  if (env.CI && env.CI !== 'false' && env.CI !== '0') return 'none';
+  return platform === 'darwin' ? 'keychain' : 'file';
+}
+
+/** The file of the tokens when there is no keychain: $XDG_CONFIG_HOME/ias/tokens.json (~/.config by default). */
+export function tokenFile(env = process.env) {
+  return join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config'), 'ias', 'tokens.json');
+}
+
+/** What people read about where the token is. */
+export const storeLabel = (kind, env = process.env) => ({ keychain: 'the macOS keychain', file: tokenFile(env), none: 'nowhere (CI)' })[kind];
+
+function readTokens(file) {
+  if (!existsSync(file)) return {};
+  const mode = statSync(file).mode & 0o777;
+  if (mode & 0o077) throw new IasError(`${file} can be read by other users (mode ${mode.toString(8)})`, { fix: `chmod 600 ${file}, and run ias login again if someone else may have read it` });
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    throw new IasError(`${file} is not valid JSON`, { fix: 'remove it and run ias login again' });
+  }
+}
+
+function writeTokens(file, tokens) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}`;
+  writeFileSync(temporary, `${JSON.stringify(tokens, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(temporary, 0o600);
+  renameSync(temporary, file);
+}
+
+const security = (args, { env, input } = {}) => spawnSync('security', args, { encoding: 'utf8', env, input, stdio: ['pipe', 'pipe', 'pipe'] });
+
+/** The stored token for `server` (an origin), or undefined. */
+export function storedToken(server, { env = process.env, kind = storeKind(env) } = {}) {
+  if (kind === 'none') return undefined;
+  if (kind === 'file') return readTokens(tokenFile(env))[server]?.token;
+  const result = security(['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', server, '-w'], { env });
+  if (result.error) throw new IasError('the macOS keychain cannot be read (security is missing)', { fix: 'set IAS_TOKEN_STORE=file to keep the token in a file, or IAS_TOKEN' });
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : undefined;
+}
+
+/** Keeps `token` for `server`; returns where it went. */
+export function saveToken(server, token, { env = process.env, kind = storeKind(env) } = {}) {
+  if (kind === 'none') throw new IasError('this machine keeps no tokens (CI)', { fix: 'set IAS_TOKEN to a robot token (iasr_…, created in the panel: the application › Settings › Access)' });
+  if (!/^iasp_[A-Za-z0-9_-]{43}$/.test(token)) throw new IasError('the server gave a token that is not a personal token (iasp_…)', { fix: 'run ias login again; if it goes on, check the server' });
+  if (kind === 'file') {
+    const file = tokenFile(env);
+    writeTokens(file, { ...readTokens(file), [server]: { token, saved_at: new Date().toISOString() } });
+    return file;
+  }
+  // security -i reads its commands from stdin: the token never is an argument of a process.
+  const quote = (value) => `"${value.replace(/["\\]/g, '\\$&')}"`;
+  const result = security(['-i'], { env, input: `add-generic-password -U -s ${quote(KEYCHAIN_SERVICE)} -a ${quote(server)} -w ${quote(token)}\n` });
+  if (result.error || result.status !== 0 || /error/i.test(result.stderr ?? '')) throw new IasError('the macOS keychain did not take the token', { fix: 'unlock the login keychain and run ias login again, or set IAS_TOKEN_STORE=file' });
+  return 'the macOS keychain';
+}
+
+/** Forgets the token of `server`; true if there was one. */
+export function forgetToken(server, { env = process.env, kind = storeKind(env) } = {}) {
+  if (kind === 'none') return false;
+  if (kind === 'file') {
+    const file = tokenFile(env);
+    const tokens = readTokens(file);
+    if (!tokens[server]) return false;
+    delete tokens[server];
+    writeTokens(file, tokens);
+    return true;
+  }
+  return security(['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', server], { env }).status === 0;
+}