@imagina-build/ias-cli 0.0.0 → 0.1.0

package/shared/vault/plaintext.mjs

@@ -0,0 +1,115 @@
+// What an ias-vault-2 envelope holds for each type of credential (docs/technical/vault.md §3.5): one UTF-8 JSON object with the
+// type, the files (base64url of their exact bytes) and the fields the runner needs to sign with them. The CLI writes
+// it with encodePlaintext before sealing and the runner reads it with decodePlaintext after opening; the server never
+// sees it. The type inside must be the credential.type of the envelope, so a plaintext of one type is never read as
+// another.
+import { Buffer } from 'node:buffer';
+
+const APPLE_ID = /^[A-Z0-9]{10}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const APPLICATION = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const VARIABLE = /^[A-Z][A-Z0-9_]{0,63}$/;
+const ENVIRONMENTS = ['development', 'preview', 'production'];
+
+/** The kinds of field: what each one holds and how it is checked. `file` is base64url, the rest JSON strings. */
+const KINDS = {
+  file: { rule: 'the base64url (no padding) of a file of at least one byte', check: (value) => decodeFile(value) !== null },
+  password: { rule: 'a string of at most 1024 characters, which may be empty', check: (value) => typeof value === 'string' && value.length <= 1024 },
+  secret: { rule: 'a string of 1 to 1024 characters', check: (value) => typeof value === 'string' && value.length >= 1 && value.length <= 1024 },
+  alias: { rule: 'a string of 1 to 255 characters', check: (value) => typeof value === 'string' && value.length >= 1 && value.length <= 255 },
+  appleId: { rule: '10 characters of A-Z and 0-9', check: (value) => typeof value === 'string' && APPLE_ID.test(value) },
+  uuid: { rule: 'a UUID', check: (value) => typeof value === 'string' && UUID.test(value) },
+  application: { rule: 'the code of an application: 1 to 32 characters of a-z 0-9 -, not starting with -', check: (value) => typeof value === 'string' && APPLICATION.test(value) },
+  environment: { rule: `one of ${ENVIRONMENTS.join(', ')}`, check: (value) => ENVIRONMENTS.includes(value) },
+  variable: { rule: 'a name of A-Z 0-9 _ that starts with a letter, up to 64, and not EXPO_PUBLIC_ (those are always plain)', check: (value) => typeof value === 'string' && VARIABLE.test(value) && !value.startsWith('EXPO_PUBLIC_') },
+  value: { rule: 'a string', check: (value) => typeof value === 'string' },
+};
+
+/**
+ * The plaintext of each type, field by field and in this order after `type`. `scope` says whether the credential is
+ * the team's (shared by several applications) or one application's, which then goes inside as `application`.
+ */
+export const PLAINTEXT_TYPES = Object.freeze({
+  apple_distribution_certificate: { scope: 'team', fields: { p12: 'file', password: 'password' } },
+  apple_provisioning_profile: { scope: 'application', fields: { application: 'application', mobileprovision: 'file' } },
+  android_upload_keystore: { scope: 'application', fields: { application: 'application', keystore: 'file', store_password: 'secret', key_alias: 'alias', key_password: 'secret' } },
+  apns_key: { scope: 'team', fields: { p8: 'file', key_id: 'appleId', team_id: 'appleId' } },
+  asc_api_key: { scope: 'team', fields: { p8: 'file', key_id: 'appleId', issuer_id: 'uuid' } },
+  google_service_account: { scope: 'application', fields: { application: 'application', json: 'file' } },
+  environment_variable: { scope: 'application', fields: { application: 'application', environment: 'environment', name: 'variable', value: 'value' } },
+});
+
+/** A plaintext that is not what its type says. `code` is stable (docs/technical/vault.md §3.5); the message holds no value. */
+export class PlaintextError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'PlaintextError';
+    this.code = code;
+  }
+}
+
+function decodeFile(text) {
+  if (typeof text !== 'string' || !/^[A-Za-z0-9_-]+$/.test(text) || text.length % 4 === 1) return null;
+  const bytes = Buffer.from(text, 'base64url');
+  return bytes.length > 0 && bytes.toString('base64url') === text ? bytes : null;
+}
+
+function schemaOf(type) {
+  const schema = PLAINTEXT_TYPES[type];
+  if (!schema) throw new PlaintextError('plaintext.type', `there is no plaintext for the type ${type}: it is one of ${Object.keys(PLAINTEXT_TYPES).join(', ')}`);
+  return schema;
+}
+
+function problemOf(type, value) {
+  const schema = PLAINTEXT_TYPES[type];
+  if (!schema) return ['plaintext.type', `there is no plaintext for the type ${type}`];
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return ['plaintext.json', 'the plaintext must be a JSON object'];
+  const names = ['type', ...Object.keys(schema.fields)];
+  const own = Object.keys(value);
+  if (own.length !== names.length || !names.every((name) => own.includes(name))) return ['plaintext.fields', `the plaintext of ${type} has exactly ${names.join(', ')}`];
+  if (value.type !== type) return ['plaintext.type', `the plaintext is of type ${typeof value.type === 'string' ? value.type : 'nothing'}, not ${type}`];
+  for (const [name, kind] of Object.entries(schema.fields)) {
+    if (!KINDS[kind].check(value[name])) return [`plaintext.${name}`, `${name} must be ${KINDS[kind].rule}`];
+  }
+  return null;
+}
+
+/** Checks the plaintext bytes of `type`: { valid: true } or { valid: false, code, message }. */
+export function validatePlaintext(type, bytes) {
+  let value;
+  try {
+    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } catch {
+    return { valid: false, code: 'plaintext.json', message: 'the plaintext is not UTF-8 JSON' };
+  }
+  const problem = problemOf(type, value);
+  return problem ? { valid: false, code: problem[0], message: problem[1] } : { valid: true };
+}
+
+/**
+ * The plaintext of `type` from its fields: files as bytes (or their base64url), the rest as strings. Returns the bytes
+ * to seal: compact JSON with `type` first and the fields in the order of PLAINTEXT_TYPES.
+ */
+export function encodePlaintext(type, fields) {
+  const schema = schemaOf(type);
+  const value = { type };
+  for (const [name, kind] of Object.entries(schema.fields)) {
+    const given = fields?.[name];
+    value[name] = kind === 'file' && given instanceof Uint8Array ? Buffer.from(given).toString('base64url') : given;
+  }
+  const extra = Object.keys(fields ?? {}).filter((name) => !(name in schema.fields));
+  if (extra.length > 0) throw new PlaintextError('plaintext.fields', `the plaintext of ${type} has no ${extra.join(', ')}`);
+  const problem = problemOf(type, value);
+  if (problem) throw new PlaintextError(...problem);
+  return Buffer.from(JSON.stringify(value), 'utf8');
+}
+
+/** The fields of a plaintext of `type`, checked, with each file as bytes. */
+export function decodePlaintext(type, bytes) {
+  schemaOf(type);
+  const result = validatePlaintext(type, bytes);
+  if (!result.valid) throw new PlaintextError(result.code, result.message);
+  const value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+  for (const [name, kind] of Object.entries(PLAINTEXT_TYPES[type].fields)) if (kind === 'file') value[name] = decodeFile(value[name]);
+  return value;
+}