@imagina-build/ias-cli 0.0.0 → 0.1.1

package/schema/ias.schema.json

@@ -0,0 +1,535 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://ias.imagina.build/schema/ias.schema.json",
+    "title": "ias.json",
+    "description": "The configuration of an app in Imagina Application Services (IAS): at the root of the app, next to app.json, and in git. It holds no secrets, only where they are: op:// references to 1Password, or the IAS_TOKEN variable. It replaces ota.config.json, dist.config.json and eas.json (PLAN-APPLICATION-SERVICES.md §2.7).",
+    "type": "object",
+    "required": [
+        "app"
+    ],
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "description": "Where editors find this schema.",
+            "type": "string"
+        },
+        "app": {
+            "description": "The code of the application in IAS (php artisan apps:create), such as jscheduler. It is also the code of its distribution project unless distribution.project says another.",
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,31}$"
+        },
+        "server": {
+            "description": "The origin of IAS. OTA updates go to the server of updates.url in app.json, which is the one the builds ask (without it, the config plugin of @imagina-build/ias gives the builds this one's); the rest goes here. IAS_SERVER wins over it, except for that URL.",
+            "type": "string",
+            "pattern": "^https?://[^/?#\\s]+/?$",
+            "default": "https://ias.imagina.build"
+        },
+        "build": {
+            "description": "The build profiles, by name, as in eas.json. Phase 2 (ias build) completes them.",
+            "type": "object",
+            "propertyNames": {
+                "$ref": "#/$defs/profileName"
+            },
+            "additionalProperties": {
+                "$ref": "#/$defs/buildProfile"
+            }
+        },
+        "updates": {
+            "$ref": "#/$defs/updates"
+        },
+        "distribution": {
+            "$ref": "#/$defs/distribution"
+        },
+        "push": {
+            "$ref": "#/$defs/push"
+        },
+        "vault": {
+            "description": "The sealed vault of the team (ias vault, ias credentials, ias env; docs/technical/vault.md): where its keys are in 1Password.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "item": {
+                    "description": "The 1Password item that ias vault init made, as op://<vault>/<item> (op://Private/IAS vault <host> by default). It holds the private keys of the team; only the reference goes here.",
+                    "type": "string",
+                    "pattern": "^op://[^/\\s]+/[^/]+$"
+                }
+            }
+        },
+        "submit": {
+            "description": "How each profile is sent to the stores, as in eas.json, without credentials: they go to the vault (ias credentials, track 1D).",
+            "type": "object",
+            "propertyNames": {
+                "$ref": "#/$defs/profileName"
+            },
+            "additionalProperties": {
+                "$ref": "#/$defs/submitProfile"
+            }
+        },
+        "workflows": {
+            "description": "What GitHub starts (docs/technical/manage-api.md §16.3), by name: a tag, a branch or a pull request starts a series of steps, each one after the one before it, and the first that fails stops the workflow. A step builds (the build profile and platforms) or submits to the stores what the build before it made; there is no step that publishes an OTA update, because its signing key lives on a Mac. Store builds, and every submission, still wait for an owner's approval with a passkey. A pull request from a fork never builds.",
+            "type": "object",
+            "propertyNames": {
+                "$ref": "#/$defs/profileName"
+            },
+            "additionalProperties": {
+                "$ref": "#/$defs/workflow"
+            }
+        }
+    },
+    "$defs": {
+        "profileName": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,49}$"
+        },
+        "projectCode": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,31}$"
+        },
+        "environment": {
+            "description": "The three environments of every application: each brings its OTA channel, build profile and variables.",
+            "enum": [
+                "development",
+                "preview",
+                "production"
+            ]
+        },
+        "projectPath": {
+            "description": "A path inside the project: relative, without ...",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "pattern": "^(?!/)(?!.*\\.\\.)[^\\\\\\n]+$"
+        },
+        "secretReference": {
+            "description": "Where a secret is: a 1Password reference (op://vault/item/field), read with the op CLI when needed. Never the secret itself.",
+            "type": "string",
+            "pattern": "^op://[^/\\s]+/[^/]+/.+$"
+        },
+        "buildProfile": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "extends": {
+                    "description": "The profile this one takes its fields from.",
+                    "$ref": "#/$defs/profileName"
+                },
+                "type": {
+                    "description": "expo (the default): an Expo app, built with npm ci, prebuild and the fingerprint. native: a project without Expo, built as the commit has it (no npm, prebuild or fingerprint): on iOS ios.workspace or ios.project and ios.scheme are needed; on Android, android.gradleTask and android.outputPath default to the release of the app module.",
+                    "enum": [
+                        "expo",
+                        "native"
+                    ]
+                },
+                "distribution": {
+                    "description": "store: for the App Store and Google Play. internal: for the install pages (ias dist), ad hoc on iOS.",
+                    "enum": [
+                        "store",
+                        "internal"
+                    ]
+                },
+                "environment": {
+                    "$ref": "#/$defs/environment"
+                },
+                "channel": {
+                    "description": "The OTA channel the build asks for (expo-channel-name). Without it, the project's default channel.",
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,49}$"
+                },
+                "developmentClient": {
+                    "description": "A development build (expo-dev-client).",
+                    "type": "boolean"
+                },
+                "autoIncrement": {
+                    "description": "Raise the build number (true, buildNumber or versionCode) or the version before each build.",
+                    "anyOf": [
+                        {
+                            "type": "boolean"
+                        },
+                        {
+                            "enum": [
+                                "version",
+                                "buildNumber",
+                                "versionCode"
+                            ]
+                        }
+                    ]
+                },
+                "ios": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "simulator": {
+                            "description": "A build for the iOS Simulator.",
+                            "type": "boolean"
+                        },
+                        "workspace": {
+                            "description": "Native projects (type native): the .xcworkspace to build, relative to the root of the repository. Use this or project.",
+                            "$ref": "#/$defs/projectPath"
+                        },
+                        "project": {
+                            "description": "Native projects (type native): the .xcodeproj to build, relative to the root of the repository. Use this or workspace.",
+                            "$ref": "#/$defs/projectPath"
+                        },
+                        "scheme": {
+                            "description": "Native projects (type native): the Xcode scheme to archive.",
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]{0,99}$"
+                        },
+                        "configuration": {
+                            "description": "Native projects (type native): the Xcode build configuration. Release by default.",
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]{0,99}$"
+                        },
+                        "exportMethod": {
+                            "description": "Native projects (type native): the method of xcodebuild -exportArchive. It must agree with the distribution: app-store-connect or app-store for the stores, release-testing or ad-hoc for the internal builds. By default, the one of the distribution.",
+                            "enum": [
+                                "app-store-connect",
+                                "app-store",
+                                "release-testing",
+                                "ad-hoc"
+                            ]
+                        }
+                    }
+                },
+                "android": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "format": {
+                            "description": "apk installs directly (internal); aab is what Google Play takes (store).",
+                            "enum": [
+                                "apk",
+                                "aab"
+                            ]
+                        },
+                        "directory": {
+                            "description": "Native projects (type native): the folder of the Gradle project (the one with gradlew), relative to the root of the repository. android by default.",
+                            "$ref": "#/$defs/projectPath"
+                        },
+                        "gradleTask": {
+                            "description": "Native projects (type native): the Gradle task that makes the release, such as :app:bundleRelease. By default :app:bundleRelease for an aab and :app:assembleRelease for an apk. The runner signs it with the upload key (android.injected.signing.*) and passes the build number as -Pias.buildNumber and IAS_BUILD_NUMBER.",
+                            "type": "string",
+                            "pattern": "^:?[A-Za-z0-9_][A-Za-z0-9_.:-]{0,99}$"
+                        },
+                        "outputPath": {
+                            "description": "Native projects (type native): where the task leaves the apk or aab, relative to android.directory. app/build/outputs/bundle/release/app-release.aab (or apk/release/app-release.apk) by default.",
+                            "$ref": "#/$defs/projectPath"
+                        }
+                    }
+                }
+            }
+        },
+        "updates": {
+            "description": "OTA updates (ias update). The server and project come from updates.url in app.json, which is what the builds ask, or without it from server and app, as the config plugin of @imagina-build/ias writes it; the certificate and keyid, from its updates.codeSigning* or from signing.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "signing": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "keyId": {
+                            "description": "The keyid of the certificate: the one of updates.codeSigningMetadata.keyid in app.json. Without it there, the config plugin of @imagina-build/ias writes this one into the builds.",
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9._-]{1,64}$"
+                        },
+                        "certificate": {
+                            "description": "The certificate (public) of the default channel, a file of the repository: the one of updates.codeSigningCertificate in app.json. Without it there, the config plugin of @imagina-build/ias writes this one into the builds; if both are written, they must be the same file.",
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        "privateKey": {
+                            "description": "The private key of the certificate, in 1Password. It never leaves the Mac that publishes; IAS_UPDATES_PRIVATE_KEY (a reference or a file outside the project) wins over it.",
+                            "$ref": "#/$defs/secretReference"
+                        }
+                    }
+                },
+                "channels": {
+                    "description": "The other channels of the OTA project, by name (API.md §36.8), each with a key of its own: what ias update signs with for --channel <name> and promote --to <name>, and the certificate its builds carry. The default channel (app.json's certificate, or signing) needs no entry.",
+                    "type": "object",
+                    "propertyNames": {
+                        "$ref": "#/$defs/profileName"
+                    },
+                    "additionalProperties": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "required": [
+                            "keyId",
+                            "privateKey",
+                            "certificate"
+                        ],
+                        "properties": {
+                            "keyId": {
+                                "description": "The keyid of the channel's certificate, the one its builds carry in updates.codeSigningMetadata.keyid.",
+                                "type": "string",
+                                "pattern": "^[A-Za-z0-9._-]{1,64}$"
+                            },
+                            "privateKey": {
+                                "description": "The private key of the channel's certificate, in 1Password. It never leaves the Mac that publishes.",
+                                "$ref": "#/$defs/secretReference"
+                            },
+                            "certificate": {
+                                "description": "The channel's certificate (public), a file of the repository: the one its builds carry.",
+                                "type": "string",
+                                "minLength": 1
+                            }
+                        }
+                    }
+                },
+                "token": {
+                    "description": "The publishing token of the OTA project (ota_…, php artisan ota:token). IAS_TOKEN wins over it.",
+                    "$ref": "#/$defs/secretReference"
+                },
+                "envFile": {
+                    "description": "The environment file of production, ignored by git, that is copied to the export: what is not in the commit does not reach the bundle.",
+                    "type": "string",
+                    "minLength": 1
+                },
+                "bundleEnv": {
+                    "description": "Variables of envFile whose value the bundle must carry. If one is missing, nothing is published.",
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                    },
+                    "uniqueItems": true
+                }
+            }
+        },
+        "distribution": {
+            "description": "Internal distribution (ias dist): ad hoc IPAs and APKs on the install pages.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "project": {
+                    "description": "The code of the distribution project (php artisan dist:project), when it is not the one of app.",
+                    "$ref": "#/$defs/projectCode"
+                },
+                "token": {
+                    "description": "The publishing token of the distribution project (dist_…, php artisan dist:token). IAS_TOKEN wins over it.",
+                    "$ref": "#/$defs/secretReference"
+                }
+            }
+        },
+        "push": {
+            "description": "Push notifications in the app (API.md §38): what ias.push of @imagina-build/ias and its config plugin (@imagina-build/ias/plugin) need. Nothing here is a secret.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "installKey": {
+                    "description": "The install key of the application (iasi_…), from the panel: the application › Notificaciones › Dispositivos. With it the app registers its device without a session of Sync. It is not a secret: anyone with the app can read it (API.md §38.1). The plugin puts it in extra.ias of the app config; after changing it in the panel, the builds that carry the old one no longer register devices.",
+                    "type": "string",
+                    "pattern": "^iasi_[A-Za-z0-9_-]{43}$"
+                },
+                "background": {
+                    "description": "Whether the sync notices (API.md §39) wake the app in the background: the remote-notification background mode of iOS. true by default.",
+                    "type": "boolean",
+                    "default": true
+                },
+                "ios": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "apsEnvironment": {
+                            "description": "The aps-environment entitlement: development by default, as expo-notifications; exporting a store or ad hoc build signs it with the profile's production.",
+                            "enum": [
+                                "development",
+                                "production"
+                            ]
+                        }
+                    }
+                },
+                "android": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "googleServicesFile": {
+                            "description": "The google-services.json of the app's Firebase project, a file of the repository: android.googleServicesFile of the app config, which FCM needs.",
+                            "type": "string",
+                            "minLength": 1
+                        }
+                    }
+                }
+            }
+        },
+        "workflow": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "on",
+                "steps"
+            ],
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "maxLength": 200
+                },
+                "on": {
+                    "description": "What starts it: a tag or a branch pushed that matches the pattern (* matches any characters), or any pull request opened or updated from this repository. A workflow can also be started by hand (ias workflows run).",
+                    "type": "object",
+                    "additionalProperties": false,
+                    "minProperties": 1,
+                    "properties": {
+                        "tag": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9._/*?-]{1,100}$"
+                        },
+                        "branch": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9._/*?-]{1,100}$"
+                        },
+                        "pull_request": {
+                            "type": "boolean"
+                        }
+                    }
+                },
+                "steps": {
+                    "description": "In order. A submit step sends the store builds of the build step before it.",
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 10,
+                    "items": {
+                        "oneOf": [
+                            {
+                                "$ref": "#/$defs/workflowBuildStep"
+                            },
+                            {
+                                "$ref": "#/$defs/workflowSubmitStep"
+                            }
+                        ]
+                    }
+                }
+            }
+        },
+        "workflowBuildStep": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "build"
+            ],
+            "properties": {
+                "build": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "profile"
+                    ],
+                    "properties": {
+                        "profile": {
+                            "description": "A build profile of build.",
+                            "$ref": "#/$defs/profileName"
+                        },
+                        "platform": {
+                            "description": "ios, android or all (both, the default).",
+                            "enum": [
+                                "ios",
+                                "android",
+                                "all"
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "workflowSubmitStep": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "submit"
+            ],
+            "properties": {
+                "submit": {
+                    "description": "Where each platform goes. A platform without a build in the step before is left out. Releases are always drafts: they are sent for review in the store.",
+                    "type": "object",
+                    "additionalProperties": false,
+                    "minProperties": 1,
+                    "properties": {
+                        "ios": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": [
+                                "target"
+                            ],
+                            "properties": {
+                                "target": {
+                                    "enum": [
+                                        "app_store_connect"
+                                    ]
+                                }
+                            }
+                        },
+                        "android": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": [
+                                "target",
+                                "track"
+                            ],
+                            "properties": {
+                                "target": {
+                                    "enum": [
+                                        "google_play"
+                                    ]
+                                },
+                                "track": {
+                                    "description": "The Google Play track: production, beta, alpha, internal or a custom one.",
+                                    "type": "string",
+                                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "submitProfile": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "ios": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "ascAppId": {
+                            "description": "The Apple ID of the app in App Store Connect.",
+                            "type": "string",
+                            "pattern": "^[0-9]+$"
+                        },
+                        "appleTeamId": {
+                            "type": "string",
+                            "pattern": "^[A-Z0-9]{10}$"
+                        }
+                    }
+                },
+                "android": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "track": {
+                            "description": "The Google Play track: production, beta, alpha, internal or a custom one.",
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        "releaseStatus": {
+                            "enum": [
+                                "completed",
+                                "draft",
+                                "halted",
+                                "inProgress"
+                            ]
+                        },
+                        "rollout": {
+                            "description": "The fraction of users for a release in progress.",
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 1
+                        },
+                        "changesNotSentForReview": {
+                            "type": "boolean"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

package/shared/credentials/cms.mjs

@@ -0,0 +1,105 @@
+// The signed content of a CMS SignedData message (RFC 5652), in DER or in BER with indefinite lengths: a provisioning
+// profile is one, with its property list inside. The signature is not verified: the profile is only read for what it
+// says, and codesign checks it when a build uses it.
+import { Buffer } from 'node:buffer';
+
+const SIGNED_DATA = '1.2.840.113549.1.7.2';
+const OCTET_STRING = 4;
+const MAX_DEPTH = 32;
+
+const fail = () => {
+  throw new Error('not a CMS signed message');
+};
+
+/** One BER node at `offset`: its tag, whether it is constructed, and where its content and the node end. */
+function readNode(bytes, offset, depth) {
+  if (depth > MAX_DEPTH || offset + 2 > bytes.length) fail();
+  const first = bytes[offset];
+  let position = offset + 1;
+  let tag = first & 0x1f;
+  if (tag === 0x1f) {
+    tag = 0;
+    let byte;
+    do {
+      if (position >= bytes.length || tag > 0xffffff) fail();
+      byte = bytes[position++];
+      tag = tag * 128 + (byte & 0x7f);
+    } while (byte & 0x80);
+  }
+  const result = { tagClass: first >> 6, constructed: (first & 0x20) !== 0, tag, start: 0, end: 0, next: 0 };
+  if (position >= bytes.length) fail();
+  const lengthByte = bytes[position++];
+  if (lengthByte === 0x80) {
+    if (!result.constructed) fail();
+    result.start = position;
+    let cursor = position;
+    for (;;) {
+      if (cursor + 2 > bytes.length) fail();
+      if (bytes[cursor] === 0 && bytes[cursor + 1] === 0) break;
+      cursor = readNode(bytes, cursor, depth + 1).next;
+    }
+    result.end = cursor;
+    result.next = cursor + 2;
+    return result;
+  }
+  let length = lengthByte;
+  if (lengthByte & 0x80) {
+    const count = lengthByte & 0x7f;
+    if (count > 4 || position + count > bytes.length) fail();
+    length = 0;
+    for (let index = 0; index < count; index++) length = length * 256 + bytes[position++];
+  }
+  if (position + length > bytes.length) fail();
+  Object.assign(result, { start: position, end: position + length, next: position + length });
+  return result;
+}
+
+function children(bytes, parent, depth) {
+  const list = [];
+  for (let cursor = parent.start; cursor < parent.end; ) {
+    const child = readNode(bytes, cursor, depth + 1);
+    list.push(child);
+    cursor = child.next;
+  }
+  return list;
+}
+
+function oid(bytes, { start, end }) {
+  const parts = [];
+  let value = 0;
+  for (let index = start; index < end; index++) {
+    value = value * 128 + (bytes[index] & 0x7f);
+    if (!(bytes[index] & 0x80)) {
+      parts.push(value);
+      value = 0;
+    }
+  }
+  if (parts.length === 0) return '';
+  const head = parts[0] < 80 ? [Math.floor(parts[0] / 40), parts[0] % 40] : [2, parts[0] - 80];
+  return [...head, ...parts.slice(1)].join('.');
+}
+
+/** The bytes of an OCTET STRING, joining the pieces of a constructed one. */
+function octets(bytes, string, depth) {
+  if (string.tagClass !== 0 || string.tag !== OCTET_STRING) fail();
+  if (!string.constructed) return bytes.subarray(string.start, string.end);
+  return Buffer.concat(children(bytes, string, depth).map((piece) => octets(bytes, piece, depth + 1)));
+}
+
+/** The encapsulated content of a CMS SignedData message (a provisioning profile gives its XML property list). */
+export function signedContent(der) {
+  const bytes = Buffer.from(der);
+  const root = readNode(bytes, 0, 0);
+  if (root.tag !== 16 || !root.constructed) fail();
+  const [type, explicit] = children(bytes, root, 0);
+  if (!type || type.tag !== 6 || oid(bytes, type) !== SIGNED_DATA || !explicit || explicit.tagClass !== 2 || explicit.tag !== 0) fail();
+  const [signedData] = children(bytes, explicit, 1);
+  if (!signedData || signedData.tag !== 16) fail();
+  const encapsulated = children(bytes, signedData, 2)[2];
+  if (!encapsulated || encapsulated.tag !== 16) fail();
+  const [, content] = children(bytes, encapsulated, 3);
+  if (!content || content.tagClass !== 2 || content.tag !== 0) fail();
+  const [string] = children(bytes, content, 4);
+  if (!string) fail();
+  return Buffer.from(octets(bytes, string, 5));
+}