@imagina-build/ias-cli 0.2.2 → 0.3.1

package/shared/vault/vectors.mjs

@@ -37,6 +37,7 @@ import {
   PLAINTEXT_TYPES,
 } from './index.mjs';
 import { approverVectors } from './approvers-vectors.mjs';
+import { policyVectors } from './policy-vectors.mjs';
 
 export const VECTORS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'test-vectors');
 
@@ -695,6 +696,7 @@ function vectors2(all) {
       ...runners,
     },
     'ias-vault-2/approvers.json': approverVectors(signing),
+    'ias-policy-1/policy.json': policyVectors(signing),
     'ias-vault-2/plaintexts.json': {
       ...header('What an envelope holds for each credential type (docs/technical/vault.md §3.5): good has one plaintext per type, with fake files; bad must be refused with code by validatePlaintext(type, bytes). text is the UTF-8 of the plaintext; plaintext, its bytes in base64url.'),
       ...plain,

package/src/apple/capabilities.mjs

@@ -0,0 +1,96 @@
+// The capabilities of an App ID and the entitlements of the app that ask for them (docs/plans/gaps/02-perfil-app-store.md
+// §3.4 and Anexo B), read from app.json › expo › ios › entitlements. The App Store Connect API only enables some
+// CapabilityTypes: push notifications, associated domains, App Groups, iCloud containers, merchant ids and the rest that
+// need settings of their own (a group, a container, a merchant) are left to Apple Developer › Identifiers, because the
+// public API does not create them; ias says which ones and where, and never touches the App ID for them. Nothing here
+// disables a capability: turning one off can break another app or extension of the same App ID, and signing does not need
+// it. Only one direction: what the entitlements ask for and the App ID lacks is enabled, one by one, with the API.
+
+/** Where the capabilities of an App ID are enabled by hand. `bundleIdId` is Apple's id of the /v1/bundleIds resource. */
+export const portalUrl = (bundleIdId) =>
+  bundleIdId ? `https://developer.apple.com/account/resources/identifiers/edit/${encodeURIComponent(bundleIdId)}` : 'https://developer.apple.com/account/resources/identifiers/list';
+
+/** The entitlements that map to a CapabilityType the public API can enable. */
+export const CAPABILITIES = Object.freeze({
+  'com.apple.developer.applesignin': 'APPLE_ID_AUTH',
+  'com.apple.developer.in-app-payments': 'APPLE_PAY',
+  'com.apple.developer.healthkit': 'HEALTHKIT',
+  'com.apple.developer.homekit': 'HOMEKIT',
+  'com.apple.developer.networking.wifi-info': 'ACCESS_WIFI_INFORMATION',
+  'com.apple.developer.networking.vpn.api': 'PERSONAL_VPN',
+  'com.apple.developer.networking.networkextension': 'NETWORK_EXTENSIONS',
+  'com.apple.developer.nfc.readersession.formats': 'NFC_TAG_READING',
+  'com.apple.developer.siri': 'SIRIKIT',
+  'com.apple.developer.pass-type-identifiers': 'WALLET',
+});
+
+/**
+ * The entitlements Apple writes into the App ID and the profile itself: there is no capability to enable for them, and
+ * a profile carries them whatever the App ID says.
+ */
+export const AUTOMATIC = Object.freeze([
+  'application-identifier',
+  'com.apple.developer.team-identifier',
+  'keychain-access-groups',
+  'get-task-allow',
+  'beta-reports-active',
+]);
+
+/**
+ * The entitlements whose capability the public API cannot enable, with why: the endpoint takes only a CapabilityType,
+ * and these need a value (a service, a domain, a group, a container, a merchant). They are never skipped silently.
+ */
+export const UNSUPPORTED = Object.freeze({
+  'aps-environment': 'PUSH_NOTIFICATIONS needs the push settings of the App ID, which the API does not write',
+  'com.apple.developer.associated-domains': 'ASSOCIATED_DOMAINS needs the list of domains of the App ID',
+  'com.apple.security.application-groups': 'APP_GROUPS needs the group identifiers, and creating them is not in the public API',
+  'com.apple.developer.icloud-container-identifiers': 'ICLOUD needs the containers, and creating them is not in the public API',
+  'com.apple.developer.icloud-services': 'ICLOUD needs the containers, and creating them is not in the public API',
+  'com.apple.developer.ubiquity-kvstore-identifier': 'ICLOUD needs the containers, and creating them is not in the public API',
+  'com.apple.developer.merchant-id': 'APPLE_PAY merchant ids are created in Apple Developer, not with the API',
+  'com.apple.developer.usernotifications.communication': 'the communication notifications need PUSH_NOTIFICATIONS, which the API does not enable for this',
+  'com.apple.developer.push-to-talk': 'PUSH_TO_TALK needs the push settings of the App ID, which the API does not write',
+});
+
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * What the entitlements of the app ask of its App ID: { requested, automatic, unsupported }. `requested` is one entry per
+ * CapabilityType ({ capabilityType, entitlements }), in the order of the table; `automatic` are the keys Apple writes
+ * itself; `unsupported` names what has to be enabled in the portal ({ entitlement, why }). A false or empty value means
+ * the app does not ask for it.
+ */
+export function capabilityPlan(entitlements) {
+  const requested = new Map();
+  const automatic = [];
+  const unsupported = [];
+  for (const [entitlement, value] of Object.entries(isRecord(entitlements) ? entitlements : {})) {
+    if (value === false || value === null || value === undefined) continue;
+    if (CAPABILITIES[entitlement]) {
+      const capabilityType = CAPABILITIES[entitlement];
+      const entry = requested.get(capabilityType) ?? { capabilityType, entitlements: [] };
+      entry.entitlements.push(entitlement);
+      requested.set(capabilityType, entry);
+      continue;
+    }
+    if (AUTOMATIC.includes(entitlement)) {
+      automatic.push(entitlement);
+      continue;
+    }
+    unsupported.push({
+      entitlement,
+      why: UNSUPPORTED[entitlement] ?? 'the App Store Connect API has no capability for it',
+    });
+  }
+  return { requested: [...requested.values()], automatic, unsupported };
+}
+
+/** The CapabilityTypes of an App ID as Apple lists them, as a Set of names. */
+export function currentCapabilities(resources) {
+  return new Set((Array.isArray(resources) ? resources : []).map((resource) => resource?.attributes?.capabilityType).filter(Boolean));
+}
+
+/** The entries of `requested` whose CapabilityType the App ID does not have yet. */
+export function missingCapabilities(requested, current) {
+  return (Array.isArray(requested) ? requested : []).filter((entry) => !current.has(entry.capabilityType));
+}

package/src/apple/inventory.mjs

@@ -0,0 +1,75 @@
+// What Apple has and the vault can sign with, for ias credentials generate (docs/plans/gaps/00-estados-cuenta.md §1):
+// the distribution certificates with their SHA-1 and expiry, and the profiles of a bundle id with their state, the
+// certificate they hold and how many devices they list. Reading only: nothing here writes in Apple or the vault. The
+// SHA-1 of a certificate is what codesign and checkIos compare, and what ties a .p12 of the vault to Apple.
+import { createHash } from 'node:crypto';
+import { credentials as inspect } from '../shared.mjs';
+
+const DAY = 24 * 60 * 60 * 1000;
+
+/** The SHA-1 of a certificate as Apple gives it: certificateContent is the DER in base64. */
+export const sha1OfDer = (base64) => createHash('sha1').update(Buffer.from(String(base64 ?? ''), 'base64')).digest('hex').toUpperCase();
+
+/** Whether a date is past; an absent date is not. */
+export const expiredAt = (date, now = Date.now()) => Boolean(date) && !(Date.parse(date) > now);
+
+/** The whole days until a date, negative when it is past. */
+export const daysUntil = (date, now = Date.now()) => Math.floor((Date.parse(date) - now) / DAY);
+
+/** The profile type of IAS (app-store, ad-hoc…) from Apple's ProfileType. */
+export function localProfileType(profileType) {
+  const types = { IOS_APP_STORE: 'app-store', IOS_APP_ADHOC: 'ad-hoc', IOS_APP_DEVELOPMENT: 'development', IOS_APP_INHOUSE: 'enterprise' };
+  return types[profileType] ?? null;
+}
+
+/**
+ * A certificate of Apple as the inventory shows it: id, name, serial, SHA-1, expiry, type, and whether it is valid,
+ * expired or inactive (Apple's `activated`). The SHA-1 is null when Apple gave no content (nothing to compare with).
+ */
+export function certificateSummary(certificate, { now = Date.now() } = {}) {
+  const attributes = certificate.attributes ?? {};
+  const sha1 = attributes.certificateContent ? sha1OfDer(attributes.certificateContent) : null;
+  const status = attributes.activated === false ? 'inactive' : expiredAt(attributes.expirationDate, now) ? 'expired' : 'valid';
+  return {
+    id: certificate.id,
+    name: attributes.displayName ?? attributes.name ?? null,
+    serial: attributes.serialNumber ?? null,
+    sha1,
+    expires: attributes.expirationDate ?? null,
+    type: attributes.certificateType ?? null,
+    status,
+  };
+}
+
+/**
+ * A profile of Apple as the inventory shows it: uuid, name, type, state, expiry, the SHA-1 of the certificates it holds,
+ * its bundle id and how many devices it lists. Both come from its CMS when Apple sends the content, which is what the
+ * vault seals; the attributes are the fallback.
+ */
+export function profileSummary(profile, { now = Date.now() } = {}) {
+  const attributes = profile.attributes ?? {};
+  let parsed = null;
+  if (attributes.profileContent) {
+    try {
+      parsed = inspect.inspectProfile(Buffer.from(attributes.profileContent, 'base64'));
+    } catch {
+      parsed = null;
+    }
+  }
+  const expires = attributes.expirationDate ?? parsed?.expires ?? null;
+  const state = attributes.profileState ?? null;
+  const status = state !== null && state !== 'ACTIVE' ? 'invalid' : expiredAt(expires, now) ? 'expired' : 'valid';
+  return {
+    id: profile.id,
+    uuid: attributes.uuid ?? parsed?.uuid ?? null,
+    name: attributes.name ?? parsed?.name ?? null,
+    type: localProfileType(attributes.profileType) ?? parsed?.type ?? null,
+    state,
+    team: parsed?.team ?? null,
+    expires,
+    certificates: parsed?.certificates ?? [],
+    bundleId: parsed?.bundleId ?? null,
+    devices: parsed?.devices ?? null,
+    status,
+  };
+}

package/src/apple/signing.mjs

@@ -0,0 +1,134 @@
+// The local half of an Apple distribution certificate (docs/plans/gaps/01-certificado-ios.md §3.4): an RSA-2048 key and a
+// SHA-256 CSR made here, with the LibreSSL of macOS (the .p12 format macOS and the runner expect), and the .p12 that
+// holds the certificate Apple issues and that key — one identity, no WWDR intermediate, as inspectP12 and the runner
+// need. Everything lives in a temporary folder (0700, files 0600) that is removed at the end; the password of the .p12
+// is random and is never printed, written outside that folder, nor an argument of a process (openssl gets it through the
+// environment). The private key never leaves this computer: only the CSR travels to Apple.
+import { spawnSync } from 'node:child_process';
+import { createHash, createPublicKey, randomBytes } from 'node:crypto';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { IasError } from '../errors.mjs';
+import { credentials as inspect } from '../shared.mjs';
+
+/** The openssl of macOS (LibreSSL): the one that makes the .p12 the runner imports. */
+export const OPENSSL = '/usr/bin/openssl';
+
+/** The subject Apple expects in the CSR: the CN, the team in OU, and no locale surprises. */
+export const certificateSubject = ({ name, team }) => `/CN=Apple Distribution: ${name} (${team})/OU=${team}/O=${name}/C=ES`;
+
+/** The CN of the certificate: the name Apple gives it, and the name of the .p12. */
+export const certificateCommonName = ({ name, team }) => `Apple Distribution: ${name} (${team})`;
+
+/** Whether `openssl` answers (ias doctor style): { ok, output }. Never throws. */
+export function opensslState(openssl = OPENSSL) {
+  const result = spawnSync(openssl, ['version'], { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+  return { ok: !result.error && result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}
+
+/** The error of a missing or broken openssl, with the doctor-style fix. */
+function missingOpenSSL(openssl, error) {
+  return new IasError(`openssl does not answer (${error.message})`, {
+    fix: 'the key, the CSR and the .p12 are made with the openssl of macOS (/usr/bin/openssl, which comes with the command line tools): run xcode-select --install, or set IAS_OPENSSL to another openssl',
+    code: 'openssl_missing',
+  });
+}
+
+/**
+ * The local material of a certificate, in a new temporary folder: the RSA-2048 key, the CSR (as text and its SHA-256),
+ * the subject, and `complete(certificateContent)` to turn the DER Apple answers (base64) into the .p12 of one identity,
+ * validated with inspectP12. `cleanup()` removes the folder; `preserve()` keeps it, with the password in a 0600 file,
+ * only for the case in which Apple issued the certificate and it could not be stored anywhere else.
+ */
+export function appleSigningMaterial({ name, team, openssl = OPENSSL } = {}) {
+  if (!name || !team) throw new IasError('the name and the team of the certificate are missing', { fix: 'pass --name and --team-id, or give the app its Apple team in the panel' });
+  const state = opensslState(openssl);
+  if (!state.ok) throw missingOpenSSL(openssl, new Error(state.output || 'no version'));
+
+  const subject = certificateSubject({ name, team });
+  const commonName = certificateCommonName({ name, team });
+  const directory = mkdtempSync(join(tmpdir(), 'ias-certificate-'));
+  chmodSync(directory, 0o700);
+  const key = join(directory, 'key.pem');
+  const csr = join(directory, 'request.certSigningRequest');
+  const der = join(directory, 'certificate.der');
+  const pem = join(directory, 'certificate.pem');
+  const p12 = join(directory, 'certificate.p12');
+  const secrets = {};
+  let kept = false;
+
+  const run = (args, why, env = {}) => {
+    const result = spawnSync(openssl, args, { encoding: 'utf8', env: { ...process.env, ...env }, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 });
+    if (result.error) throw missingOpenSSL(openssl, result.error);
+    if (result.status !== 0) {
+      const reason = `${result.stderr}\n${result.stdout}`.split('\n').map((line) => line.trim()).find(Boolean) ?? `exit ${result.status}`;
+      throw new IasError(`${why}: ${reason}`, { fix: 'nothing was sent to Apple: run it again, and if it goes on check openssl with ias doctor', code: 'openssl_failed' });
+    }
+    return result;
+  };
+
+  // An RSA-2048 key, 0600 from the start, and the CSR with SHA-256 (Apple signs it and keeps only the public half).
+  run(['genrsa', '-out', key, '2048'], 'openssl could not make the RSA-2048 key');
+  chmodSync(key, 0o600);
+  run(['req', '-new', '-sha256', '-key', key, '-subj', subject, '-out', csr], 'openssl could not make the CSR');
+  chmodSync(csr, 0o600);
+  const csrBytes = readFileSync(csr);
+  const csrPem = csrBytes.toString('utf8');
+  const csrSha256 = createHash('sha256').update(csrBytes).digest('hex');
+
+  return {
+    directory,
+    subject,
+    commonName,
+    key,
+    csr,
+    csrPem,
+    csrSha256,
+    get password() {
+      return secrets.IAS_P12_PASSWORD ?? null;
+    },
+    /** The .p12 of one identity from the certificate Apple issued (its DER in base64), validated here. */
+    complete(certificateContent) {
+      writeFileSync(der, Buffer.from(String(certificateContent ?? ''), 'base64'), { mode: 0o600 });
+      run(['x509', '-inform', 'DER', '-in', der, '-out', pem], 'the certificate Apple gave does not read');
+      chmodSync(pem, 0o600);
+      // The certificate has to be the one of this key: otherwise the .p12 would never sign with it.
+      if (!createPublicKey(readFileSync(pem)).equals(createPublicKey(readFileSync(key)))) {
+        throw new IasError('the certificate Apple gave is not the one of the key made here', { fix: 'nothing was stored: run it again (the certificate may stay in Apple Developer until someone revokes it)', code: 'certificate_key_mismatch' });
+      }
+      // One identity (leaf + key) and no WWDR intermediate: what inspectP12 accepts and the runner imports.
+      const password = randomBytes(24).toString('base64url');
+      secrets.IAS_P12_PASSWORD = password;
+      run(['pkcs12', '-export', '-inkey', key, '-in', pem, '-name', commonName, '-passout', 'env:IAS_P12_PASSWORD', '-out', p12], 'openssl could not export the .p12', secrets);
+      chmodSync(p12, 0o600);
+      let metadata;
+      try {
+        metadata = inspect.inspectP12(p12, password, { openssl });
+      } catch (error) {
+        throw new IasError(`the .p12 made here does not read (${error.message})`, { fix: 'nothing was stored: run it again, and if it goes on report it', code: 'p12_invalid' });
+      }
+      return { p12, password, metadata, pem, der };
+    },
+    /** Keeps the folder (0700) with the password in a 0600 file, only when nothing else could store the key. */
+    preserve() {
+      kept = true;
+      if (secrets.IAS_P12_PASSWORD) writeFileSync(join(directory, 'password'), `${secrets.IAS_P12_PASSWORD}\n`, { mode: 0o600 });
+      return directory;
+    },
+    cleanup() {
+      if (!kept) rmSync(directory, { recursive: true, force: true });
+    },
+  };
+}
+
+/** Runs `work` with the material and removes its folder however it ends, unless work kept it. */
+export async function withAppleSigningMaterial(options, work) {
+  const material = appleSigningMaterial(options);
+  try {
+    return await work(material);
+  } finally {
+    material.cleanup();
+  }
+}

package/src/applications.mjs

@@ -0,0 +1,114 @@
+// Applications from the management API: create one with its identity and services, change its services, and make sure
+// push has its install key (which goes to push.installKey of ias.json). `ias apps` and `ias setup` share it.
+import { loadProject, saveProjectConfig } from './config.mjs';
+import { IasError } from './errors.mjs';
+
+export const APPLICATION_SERVICES = ['credentials', 'builds', 'distribution', 'updates', 'sync', 'push'];
+
+/** The list of services of --services, in the order the API keeps them. */
+export function parseApplicationServices(text) {
+  const names = String(text).split(',').map((name) => name.trim()).filter(Boolean);
+  const unknown = names.filter((name) => !APPLICATION_SERVICES.includes(name));
+  if (unknown.length > 0) throw new IasError(`unknown service ${unknown.join(', ')}`, { fix: `ias.json takes ${APPLICATION_SERVICES.join(', ')}` });
+  return [...new Set(names)];
+}
+
+/** POST /apps: the application, with its code, identity and services. */
+export async function createApplication(client, { code, name, iosBundleId, androidPackage, appleTeamId, services = [] }) {
+  const { data } = await client.request('POST', '/apps', {
+    json: {
+      code,
+      ...(name ? { name } : {}),
+      ...(iosBundleId ? { ios_bundle_id: iosBundleId } : {}),
+      ...(androidPackage ? { android_package: androidPackage } : {}),
+      ...(appleTeamId ? { apple_team_id: appleTeamId } : {}),
+      services,
+    },
+  });
+  return data;
+}
+
+/**
+ * What `ias apps --create` would send, for --dry-run: the same plan `ias setup --create-app --dry-run` prints and
+ * returns, so the two commands cannot drift.
+ */
+export function applicationPlan({ code, name, iosBundleId, androidPackage, appleTeamId, services = [] }) {
+  return {
+    dry_run: true,
+    code,
+    name: name ?? null,
+    ios_bundle_id: iosBundleId ?? null,
+    android_package: androidPackage ?? null,
+    apple_team_id: appleTeamId ?? null,
+    services,
+  };
+}
+
+/** The lines of a plan: what would be created, with what, and that nothing was. */
+export function printApplicationPlan(plan, output) {
+  output.progress(`${output.prefix}: would create the application ${plan.code} in IAS (${plan.services.join(', ') || 'no service'})`);
+  if (plan.name) output.progress(`  name          ${plan.name}`);
+  if (plan.ios_bundle_id) output.progress(`  ios           ${plan.ios_bundle_id}${plan.apple_team_id ? ` (team ${plan.apple_team_id})` : ''}`);
+  if (plan.android_package) output.progress(`  android       ${plan.android_package}`);
+  output.progress(`  services      ${plan.services.join(', ') || 'none'}`);
+  output.progress('nothing was created: an owner with a personal token runs it again without --dry-run');
+}
+
+/** PUT /apps/{code}/services: the whole list; a service with pieces cannot be dropped. */
+export async function setApplicationServices(client, app, services) {
+  const { data } = await client.request('PUT', `/apps/${app}/services`, { json: { services } });
+  return data;
+}
+
+/**
+ * Push on and an install key: reads the application, turns push on if it is
+ * not, reads the key or makes one if there is none, and writes it to
+ * push.installKey of ias.json. The key is not a secret: every copy of the
+ * app carries it. It never replaces an existing key unless `replace` says so.
+ */
+export async function ensurePush({ client, dir, app, output, dryRun = false, replace = false }) {
+  const { data: current } = await client.request('GET', `/apps/${app}`);
+  let services = current.services ?? [];
+
+  if (!services.includes('push')) {
+    if (dryRun) {
+      output?.progress(`${output.prefix}: would turn push on for ${app}`);
+      return { app, services: [...services, 'push'], install_key: null, dry_run: true };
+    }
+    const updated = await setApplicationServices(client, app, [...services, 'push']);
+    services = updated.services;
+    output?.log(`${output.prefix}: push is on for ${app}`);
+  }
+
+  let key;
+  if (dryRun) {
+    try {
+      key = (await client.request('GET', `/apps/${app}/push/install-key`)).data.install_key;
+    } catch (error) {
+      if (error.code !== 'install_key_missing' && error.status !== 404) throw error;
+      key = null;
+    }
+    return { app, services, install_key: key, dry_run: true };
+  }
+
+  if (replace) {
+    key = (await client.request('POST', `/apps/${app}/push/install-key`, {})).data.install_key;
+    output?.log(`${output.prefix}: made a new install key for ${app} (the old one stops working)`);
+  } else {
+    try {
+      key = (await client.request('GET', `/apps/${app}/push/install-key`)).data.install_key;
+    } catch (error) {
+      if (error.code !== 'install_key_missing' && error.status !== 404) throw error;
+      key = (await client.request('POST', `/apps/${app}/push/install-key`, {})).data.install_key;
+      output?.log(`${output.prefix}: made the install key of ${app}`);
+    }
+  }
+
+  const project = loadProject(dir);
+  if (!project.config) throw new IasError(`no ias.json in ${dir}`, { fix: 'run ias init there first' });
+  const config = project.config;
+  config.push = { ...(config.push ?? {}), installKey: key };
+  saveProjectConfig(dir, config);
+  output?.log(`${output.prefix}: push.installKey of ias.json is the key of ${app}`);
+  return { app, services, install_key: key };
+}

package/src/cli.mjs

@@ -17,7 +17,7 @@ export { EXIT_CODE };
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 /** The order of the commands in the help; the rest follow by name. */
-const ORDER = ['login', 'logout', 'whoami', 'apps', 'init', 'doctor', 'sdk', 'update', 'dist', 'credentials', 'env', 'vault'];
+const ORDER = ['login', 'logout', 'whoami', 'apps', 'setup', 'init', 'doctor', 'skill', 'sdk', 'update', 'dist', 'credentials', 'env', 'vault', 'policy', 'tokens', 'runners'];
 
 /** The options of every command. */
 export const GLOBAL_OPTIONS = {
@@ -90,13 +90,22 @@ export function generalHelp(commands) {
   ].join('\n');
 }
 
+/** The help of a command with subcommands; one that also runs itself (ias testflight <build>) shows its own form too. */
 export function commandHelp(command) {
   if (!command.subcommands) return leafHelp([command.name], command);
+  const own = command.run ? command : null;
+  const positionals = own?.positionals ?? [];
+  const options = { ...(own?.options ?? {}), ...GLOBAL_OPTIONS };
+  const argumentRows = positionals.map((positional) => [`<${positional.name}>`, positional.description ?? '']);
   return [
     `ias ${command.name}: ${command.summary}`,
     ...(command.description ? ['', command.description] : []),
     '',
-    `usage: ias ${command.name} <subcommand> [options]`,
+    ...(own
+      ? [`usage: ${usageLine([command.name], own)}`, `   or: ias ${command.name} <subcommand> [options]`]
+      : [`usage: ias ${command.name} <subcommand> [options]`]),
+    ...(argumentRows.length > 0 ? ['', 'arguments:', table(argumentRows)] : []),
+    ...(own ? ['', 'options:', table(Object.entries(options).map(([name, option]) => [optionLabel(name, option), option.description ?? '']))] : []),
     '',
     'subcommands:',
     table(command.subcommands.map((subcommand) => [[subcommand.name, ...(subcommand.aliases ?? [])].join(', '), subcommand.summary])),
@@ -199,20 +208,29 @@ export async function main(argv = process.argv.slice(2), { env = process.env, cw
     const path = [command.name];
     if (command.subcommands) {
       const word = args[0];
-      if (word === undefined || word.startsWith('-')) {
-        if (args.includes('--help') || args.includes('-h')) {
+      const subcommand = word === undefined ? undefined : named(command.subcommands, word);
+      // A command can also have a positional form, such as `ias apps <code>`: without a subcommand, it runs itself.
+      if (subcommand) {
+        leaf = subcommand;
+        path.push(leaf.name);
+        args = args.slice(1);
+      } else if (command.run) {
+        // It runs itself: its options, or its positional form (ias apps <code>).
+        if ((word === undefined || word.startsWith('-')) && (args.includes('--help') || args.includes('-h'))) {
           print(commandHelp(command));
           return 0;
         }
-        throw new UsageError(`ias ${command.name} needs a subcommand`, { fix: `one of ${command.subcommands.map((subcommand) => subcommand.name).join(', ')}; ias ${command.name} --help says what each does` });
-      }
-      leaf = named(command.subcommands, word);
-      if (!leaf) {
+      } else {
+        if (word === undefined || word.startsWith('-')) {
+          if (args.includes('--help') || args.includes('-h')) {
+            print(commandHelp(command));
+            return 0;
+          }
+          throw new UsageError(`ias ${command.name} needs a subcommand`, { fix: `one of ${command.subcommands.map((subcommand) => subcommand.name).join(', ')}; ias ${command.name} --help says what each does` });
+        }
         const guess = closest(word, command.subcommands.map((subcommand) => subcommand.name));
         throw new UsageError(`ias ${command.name} has no subcommand «${word}»`, { fix: guess ? `did you mean ias ${command.name} ${guess}? ias ${command.name} --help lists them` : `ias ${command.name} --help lists them` });
       }
-      path.push(leaf.name);
-      args = args.slice(1);
     }
     const { values, positionals } = parseCommandLine(path, leaf, args);
     if (values.help) {

package/src/commands/apps/index.mjs

@@ -1,12 +1,18 @@
-// ias apps: the applications the token can see (docs/technical/manage-api.md §4), or one of them. A robot token sees only its own.
+// ias apps: the applications the token can see (docs/technical/manage-api.md §4), one of them, a new one, or its
+// services. A robot token sees only its own and cannot create or change them.
 import { resolve } from 'node:path';
+import { applicationPlan, createApplication, parseApplicationServices, printApplicationPlan, setApplicationServices } from '../../applications.mjs';
 import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
 import { connect } from '../../manage.mjs';
+import storeCommand, { appRecordLine } from './store.mjs';
 
 /** The lines that describe an application for people. */
 export function describeApplication(app) {
-  const lines = [`${app.code}  ${app.name}`, `  services      ${app.services.length > 0 ? app.services.join(', ') : 'none'}`];
+  const lines = [`${app.code}  ${app.name}`, `  services      ${(app.services ?? []).length > 0 ? app.services.join(', ') : 'none'}`];
   if (app.ios) lines.push(`  ios           ${app.ios.bundle_id ?? '—'} (team ${app.ios.team_id ?? '—'})`);
+  const record = appRecordLine(app);
+  if (record) lines.push(record);
   if (app.android) lines.push(`  android       ${app.android.package ?? '—'}`);
   if (app.updates) lines.push(`  updates       project ${app.updates.project}, channel ${app.updates.default_channel}, ${app.updates.manifest_url}`);
   if (app.distribution) lines.push(`  distribution  project ${app.distribution.project}, ${app.distribution.install_url}`);
@@ -14,23 +20,67 @@ export function describeApplication(app) {
 }
 
 async function apps(context) {
-  const client = connect(context, loadProject(resolve(context.cwd, context.values.project ?? '.')));
-  const [code] = context.positionals;
+  const { values, output, positionals } = context;
+  const project = loadProject(resolve(context.cwd, values.project ?? '.'));
+  const clientOf = () => connect(context, project);
+  let code = positionals[0] ?? values.code;
+
+  if (values.create) {
+    if (!code) throw new IasError('which code for the application?', { fix: 'ias apps --create --code <code> --name "…" --services updates,distribution' });
+    const services = values.services === undefined ? [] : parseApplicationServices(values.services);
+    const details = {
+      code,
+      name: values.name,
+      iosBundleId: values['ios-bundle-id'],
+      androidPackage: values['android-package'],
+      appleTeamId: values['apple-team-id'],
+      services,
+    };
+    if (values['dry-run']) {
+      const plan = applicationPlan(details);
+      printApplicationPlan(plan, output);
+      return plan;
+    }
+    const app = await createApplication(clientOf(), details);
+    for (const line of describeApplication(app)) output.log(line);
+    return app;
+  }
+
+  if (values.services !== undefined) {
+    if (!code) throw new IasError('which application?', { fix: 'pass its code: ias apps <code> --services updates,distribution,push' });
+    const app = await setApplicationServices(clientOf(), code, parseApplicationServices(values.services));
+    output.log(`${output.prefix}: ${app.code}: services ${app.services.length > 0 ? app.services.join(', ') : 'none'}`);
+    return app;
+  }
+
   if (code) {
-    const { data } = await client.request('GET', `/apps/${encodeURIComponent(code)}`);
-    for (const line of describeApplication(data)) context.output.log(line);
+    const { data } = await clientOf().request('GET', `/apps/${encodeURIComponent(code)}`);
+    for (const line of describeApplication(data)) output.log(line);
     return data;
   }
-  const { data } = await client.request('GET', '/apps');
-  if (data.data.length === 0) context.output.log('No applications: create one in the panel (Aplicaciones › Crear aplicación).');
+
+  const { data } = await clientOf().request('GET', '/apps');
+  if (data.data.length === 0) output.log('No applications: ias apps --create --code <code> --name "…" --services updates,distribution');
   const width = Math.max(0, ...data.data.map((app) => app.code.length));
-  for (const app of data.data) context.output.log(`${app.code.padEnd(width)}  ${app.name}  (${app.services.join(', ') || 'no services'})`);
+  for (const app of data.data) output.log(`${app.code.padEnd(width)}  ${app.name}  (${app.services.join(', ') || 'no services'})`);
   return data;
 }
 
 export default {
   name: 'apps',
-  summary: 'The applications the token can see, or one of them in detail',
-  positionals: [{ name: 'code', optional: true, description: 'The code of one application, to see it in detail.', pattern: /^[a-z0-9][a-z0-9-]{0,31}$/ }],
+  summary: 'The applications the token can see: the list, one of them, a new one (--create), its services or its store identity',
+  description: 'Without arguments, the list. With a code, one in detail. --create makes one (an owner with a personal token) with its identity and services; --services replaces the services of one (a service with pieces cannot be turned off). ias apps store <code> shows and settles its identity in App Store Connect (see ias apps store --help).',
+  positionals: [{ name: 'code', optional: true, description: 'The code of one application, to see it in detail or to change its services.', pattern: /^[a-z0-9][a-z0-9-]{0,31}$/ }],
+  subcommands: [storeCommand],
+  options: {
+    create: { type: 'boolean', description: 'Make a new application with --code, --name and the identity flags; an owner with a personal token.' },
+    code: { type: 'string', value: '<code>', description: 'The code of the new application, or of the one whose services change.' },
+    name: { type: 'string', value: '"…"', description: 'The name in the panel (the code by default).' },
+    'ios-bundle-id': { type: 'string', value: '<id>', description: 'The bundle id of iOS, such as com.imagina.jscheduler.' },
+    'android-package': { type: 'string', value: '<id>', description: 'The package of Android, such as com.imagina.jscheduler.' },
+    'apple-team-id': { type: 'string', value: '<id>', description: 'The Apple team id (10 letters and digits).' },
+    services: { type: 'string', value: '<list>', description: `The services, comma-separated: ${['credentials', 'builds', 'distribution', 'updates', 'sync', 'push'].join(', ')}.` },
+    'dry-run': { type: 'boolean', description: '--create: say what it would create and create nothing (the same plan as ias setup --create-app --dry-run).' },
+  },
   run: apps,
 };