@mmerterden/multi-agent-toolkit-mcp 3.9.0 → 3.11.0

package/tools/pass-kit/sign.js

@@ -0,0 +1,255 @@
+/**
+ * sign.js  -  manifest, signature, archive. And where the passphrase comes from.
+ *
+ * NO SHELL. Every child is `execFileSync(bin, [argv])`. The passphrase reaches
+ * openssl through `-passin env:VAR` and never as an argument, because an
+ * argument is world-readable in `ps` for as long as the process runs. It is
+ * never written to disk, never logged, and scrubbed out of any error text
+ * before that text is returned.
+ *
+ * WHERE IT COMES FROM, in order: an explicit `passphrase_env` naming an
+ * environment variable, then a keychain entry, then nothing. A literal
+ * passphrase is not an accepted input at all - a tool that takes one invites a
+ * caller to put it in a config file, and that is how the project this replaces
+ * ended up publishing its own in a README three times.
+ *
+ * @module tools/pass-kit/sign
+ */
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdtempSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { tmpdir } from "node:os";
+
+const ERROR_PREFIX = "ERROR: ";
+
+/** Files the manifest never covers, because they are produced from it. */
+const NOT_HASHED = new Set(["manifest.json", "signature"]);
+
+/**
+ * Every file in a `.pass` directory, as manifest-relative names.
+ * Localization folders are included with their `xx.lproj/` prefix.
+ */
+export function listPassFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith(".")) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else out.push(relative(dir, p).split(sep).join("/"));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/**
+ * SHA-1 of every file, which is what Apple specifies - not a choice.
+ */
+export function buildManifest(dir, files) {
+  const manifest = {};
+  for (const f of files) {
+    if (NOT_HASHED.has(f)) continue;
+    manifest[f] = createHash("sha1").update(readFileSync(join(dir, f))).digest("hex");
+  }
+  return manifest;
+}
+
+/**
+ * Read a passphrase without it ever becoming an argument or a file.
+ * @returns {{value: string}|{error: string}}
+ */
+export function resolvePassphrase({ passphrase_env, keychain_account, keychain_service }) {
+  if (passphrase_env) {
+    const v = process.env[passphrase_env];
+    if (!v) {
+      return {
+        error: `${ERROR_PREFIX}the environment variable ${passphrase_env} is unset or empty`,
+      };
+    }
+    return { value: v, source: `env:${passphrase_env}` };
+  }
+  if (keychain_account) {
+    try {
+      const v = execFileSync(
+        "/usr/bin/security",
+        [
+          "find-generic-password",
+          "-a",
+          keychain_account,
+          "-s",
+          keychain_service || "pkpass",
+          "-w",
+        ],
+        { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 },
+      ).trim();
+      if (v) return { value: v, source: `keychain:${keychain_account}` };
+    } catch {
+      /* fall through to the error below */
+    }
+    return {
+      error: `${ERROR_PREFIX}no keychain entry for account "${keychain_account}" in service "${keychain_service || "pkpass"}". Store one with: security add-generic-password -a ${keychain_account} -s ${keychain_service || "pkpass"} -w '<passphrase>'`,
+    };
+  }
+  return {
+    error: `${ERROR_PREFIX}no passphrase source. Give passphrase_env (the NAME of an environment variable) or keychain_account. A literal passphrase is deliberately not accepted.`,
+  };
+}
+
+/** Certificate metadata, without ever touching the private key. */
+export function inspectCertificate(certPath) {
+  try {
+    const subject = openssl(["x509", "-in", certPath, "-noout", "-subject"]).trim();
+    const dates = openssl(["x509", "-in", certPath, "-noout", "-dates"]).trim();
+    const notAfter = /notAfter=(.+)/.exec(dates)?.[1]?.trim() || null;
+    const notBefore = /notBefore=(.+)/.exec(dates)?.[1]?.trim() || null;
+    const expiresAt = notAfter ? new Date(notAfter) : null;
+    const expired = expiresAt ? expiresAt.getTime() < Date.now() : null;
+    const uid = /UID\s*=\s*([^,/]+)/.exec(subject)?.[1]?.trim() || null;
+    const ou = /OU\s*=\s*([^,/]+)/.exec(subject)?.[1]?.trim() || null;
+    return {
+      path: certPath,
+      passTypeIdentifier: uid,
+      teamIdentifier: ou,
+      notBefore,
+      notAfter,
+      expired,
+      daysLeft: expiresAt ? Math.floor((expiresAt.getTime() - Date.now()) / 86400000) : null,
+    };
+  } catch (e) {
+    return { path: certPath, error: `cannot read: ${short(e)}` };
+  }
+}
+
+function openssl(args, opts = {}) {
+  return execFileSync("openssl", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 30000,
+    ...opts,
+  });
+}
+
+function short(e) {
+  return String(e?.stderr || e?.message || e)
+    .trim()
+    .slice(0, 300);
+}
+
+/**
+ * Detached PKCS#7 signature over the manifest.
+ *
+ * @returns {{ok: true}|{error: string}}
+ */
+export function signManifest({ manifestPath, signaturePath, certificate, privateKey, wwdr, passphrase }) {
+  const env = { ...process.env, PKPASS_KEY_PASSPHRASE: passphrase };
+  try {
+    execFileSync(
+      "openssl",
+      [
+        "smime",
+        "-binary",
+        "-sign",
+        "-certfile",
+        wwdr,
+        "-signer",
+        certificate,
+        "-inkey",
+        privateKey,
+        "-in",
+        manifestPath,
+        "-out",
+        signaturePath,
+        "-passin",
+        "env:PKPASS_KEY_PASSPHRASE",
+        "-outform",
+        "DER",
+      ],
+      { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60000 },
+    );
+    return { ok: true };
+  } catch (e) {
+    return { error: `${ERROR_PREFIX}signing failed: ${scrub(short(e), passphrase)}` };
+  }
+}
+
+/**
+ * Verify a signature against its manifest and report the chain.
+ *
+ * Deliberately does NOT assert trust: the WWDR chain is not in the system store
+ * on every machine, and a verification that fails for that reason would read as
+ * a broken pass. `-noverify` checks the signature itself; the chain is reported
+ * so a human can see what signed it.
+ */
+export function verifySignature({ signaturePath, manifestPath }) {
+  try {
+    openssl([
+      "smime",
+      "-verify",
+      "-binary",
+      "-inform",
+      "DER",
+      "-in",
+      signaturePath,
+      "-content",
+      manifestPath,
+      "-noverify",
+      "-out",
+      "/dev/null",
+    ]);
+    const certs = openssl(["pkcs7", "-inform", "DER", "-in", signaturePath, "-print_certs", "-noout"]);
+    const chain = certs
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.startsWith("subject="))
+      .map((l) => l.replace(/^subject=\s*/, ""));
+    return { valid: true, chain };
+  } catch (e) {
+    return { valid: false, reason: short(e) };
+  }
+}
+
+/** Zip a directory into a .pkpass, with the entries at the archive root. */
+export function archive(passDir, outPath) {
+  try {
+    execFileSync("/usr/bin/zip", ["-q", "-r", "-X", outPath, "."], {
+      cwd: passDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 60000,
+    });
+    return { ok: true, bytes: statSync(outPath).size };
+  } catch (e) {
+    return { error: `${ERROR_PREFIX}archiving failed: ${short(e)}` };
+  }
+}
+
+/** Unpack a .pkpass into a temporary directory for inspection. */
+export function unpack(pkpassPath) {
+  const dir = mkdtempSync(join(tmpdir(), "pkpass-"));
+  try {
+    execFileSync("/usr/bin/unzip", ["-q", "-o", pkpassPath, "-d", dir], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 60000,
+    });
+    return { dir };
+  } catch (e) {
+    return { error: `${ERROR_PREFIX}cannot unpack ${pkpassPath}: ${short(e)}` };
+  }
+}
+
+export function writeManifest(dir, manifest) {
+  const p = join(dir, "manifest.json");
+  writeFileSync(p, JSON.stringify(manifest, null, 2));
+  return p;
+}
+
+function scrub(text, secret) {
+  if (!secret) return text;
+  return text.split(secret).join("***");
+}
+
+export { ERROR_PREFIX };

package/tools/pass-kit/spec.js

@@ -0,0 +1,317 @@
+/**
+ * spec.js  -  what Apple requires of a pass, as data.
+ *
+ * Everything here is a table rather than a code path, because all of it is
+ * somebody else's specification and the only useful property is that it is easy
+ * to correct. Nothing in this file is tied to an airline, a brand or a project;
+ * the five styles are the five Apple defines.
+ *
+ * The enum lists matter more than they look. A single invalid
+ * `PKPassengerCapability*` value does not produce an error - Wallet silently
+ * declines to render the enhanced layout and the pass falls back to the old
+ * one, with nothing anywhere saying why. That failure mode is the reason this
+ * file exists at all.
+ *
+ * @module tools/pass-kit/spec
+ */
+
+export const STYLES = ["boardingPass", "coupon", "eventTicket", "generic", "storeCard"];
+
+/**
+ * Top-level keys every pass must carry, whatever its style.
+ * Apple rejects a pass missing any of these outright.
+ */
+export const REQUIRED_TOP_LEVEL = [
+  "description",
+  "formatVersion",
+  "organizationName",
+  "passTypeIdentifier",
+  "serialNumber",
+  "teamIdentifier",
+];
+
+/**
+ * Images, per style.
+ *
+ * `required` is what Wallet will not render without. `optional` is what the
+ * style can use. Anything outside both lists is dead weight in the manifest -
+ * worth reporting, because it is usually a naming mistake rather than a spare.
+ *
+ * Retina variants are implied: `logo` means logo.png, logo@2x.png, logo@3x.png,
+ * and the 1x file carries no suffix. That last detail is a real trap - a file
+ * named `footer@1x.png` is not the 1x footer, it is a file Wallet ignores.
+ */
+export const ASSETS = {
+  boardingPass: { required: ["icon", "logo"], optional: ["footer", "background", "thumbnail"] },
+  coupon: { required: ["icon", "logo"], optional: ["strip"] },
+  eventTicket: { required: ["icon", "logo"], optional: ["strip", "background", "thumbnail"] },
+  generic: { required: ["icon", "logo"], optional: ["thumbnail"] },
+  storeCard: { required: ["icon", "logo"], optional: ["strip"] },
+};
+
+/** Every image name a pass may legitimately contain, at any scale. */
+export const ALL_IMAGE_BASENAMES = [
+  "icon",
+  "logo",
+  "strip",
+  "background",
+  "thumbnail",
+  "footer",
+  "personalizationLogo",
+];
+
+export const SCALES = ["", "@2x", "@3x"];
+
+/** boardingPass carries one extra required key inside its style dictionary. */
+export const STYLE_REQUIRED_KEYS = {
+  boardingPass: ["transitType"],
+};
+
+export const TRANSIT_TYPES = [
+  "PKTransitTypeAir",
+  "PKTransitTypeBoat",
+  "PKTransitTypeBus",
+  "PKTransitTypeGeneric",
+  "PKTransitTypeTrain",
+];
+
+export const BARCODE_FORMATS = [
+  "PKBarcodeFormatQR",
+  "PKBarcodeFormatPDF417",
+  "PKBarcodeFormatAztec",
+  "PKBarcodeFormatCode128",
+];
+
+export const FIELD_BUCKETS = [
+  "headerFields",
+  "primaryFields",
+  "secondaryFields",
+  "auxiliaryFields",
+  "backFields",
+  // Newer than the other five and only meaningful on a boardingPass. Listed
+  // because a real, working, signed enhanced boarding pass uses it: reporting
+  // it as "a bucket Apple does not define" was this validator being wrong
+  // about somebody else's correct pass, which is worse than saying nothing.
+  "footerFields",
+];
+
+/**
+ * Enumerated semantic values.
+ *
+ * An unknown value in one of these is the quiet failure described in the file
+ * header: no error, no warning, and an enhanced pass that silently renders as a
+ * legacy one.
+ */
+export const SEMANTIC_ENUMS = {
+  passengerCapabilities: [
+    "PKPassengerCapabilityPreBoarding",
+    "PKPassengerCapabilityPriorityBoarding",
+    "PKPassengerCapabilityCarryon",
+    "PKPassengerCapabilityPersonalItem",
+  ],
+  departureLocationSecurityPrograms: [
+    "PKTransitSecurityProgramTSAPreCheck",
+    "PKTransitSecurityProgramGlobalEntry",
+    "PKTransitSecurityProgramClear",
+    "PKTransitSecurityProgramNexus",
+    "PKTransitSecurityProgramSentri",
+    "PKTransitSecurityProgramTSAPreCheckTouchlessID",
+    "PKTransitSecurityProgramFastTrack",
+  ],
+  eventType: [
+    "PKEventTypeGeneric",
+    "PKEventTypeLivePerformance",
+    "PKEventTypeMovie",
+    "PKEventTypeSports",
+    "PKEventTypeConference",
+    "PKEventTypeConvention",
+    "PKEventTypeWorkshop",
+    "PKEventTypeSocialGathering",
+  ],
+};
+
+SEMANTIC_ENUMS.destinationLocationSecurityPrograms =
+  SEMANTIC_ENUMS.departureLocationSecurityPrograms;
+SEMANTIC_ENUMS.passengerEligibleSecurityPrograms =
+  SEMANTIC_ENUMS.departureLocationSecurityPrograms;
+
+/**
+ * Semantic tags, by the type a validator can actually check.
+ *
+ * Not exhaustive of Apple's catalogue and not trying to be - it covers the
+ * shapes that are wrong often enough to be worth catching: a date that is not
+ * ISO 8601, a number sent as a string, a location missing a coordinate.
+ */
+export const SEMANTIC_TYPES = {
+  // Flight and transit
+  airlineCode: "string",
+  flightCode: "string",
+  flightNumber: "number",
+  departureAirportCode: "string",
+  departureAirportName: "string",
+  departureCityName: "string",
+  departureStationName: "string",
+  departurePlatform: "string",
+  departureLocationDescription: "string",
+  departureGate: "string",
+  departureTerminal: "string",
+  departureLocation: "location",
+  departureLocationTimeZone: "string",
+  destinationAirportCode: "string",
+  destinationAirportName: "string",
+  destinationCityName: "string",
+  destinationStationName: "string",
+  destinationPlatform: "string",
+  destinationLocationDescription: "string",
+  destinationGate: "string",
+  destinationTerminal: "string",
+  destinationLocation: "location",
+  destinationLocationTimeZone: "string",
+  boardingGroup: "string",
+  boardingSequenceNumber: "string",
+  boardingZone: "string",
+  originalBoardingDate: "date",
+  currentBoardingDate: "date",
+  originalDepartureDate: "date",
+  currentDepartureDate: "date",
+  originalArrivalDate: "date",
+  currentArrivalDate: "date",
+  transitProvider: "string",
+  transitStatus: "string",
+  transitStatusReason: "string",
+  vehicleName: "string",
+  vehicleNumber: "string",
+  vehicleType: "string",
+  carNumber: "string",
+  confirmationNumber: "string",
+  passengerName: "personName",
+  membershipProgramName: "string",
+  membershipProgramNumber: "string",
+  priorityStatus: "string",
+  ticketFareClass: "string",
+  securityScreening: "string",
+  membershipProgramStatus: "string",
+  internationalDocumentsAreVerified: "boolean",
+  internationalDocumentsVerifiedDeclarationName: "string",
+  passengerAirlineSSRs: "array",
+  passengerInformationSSRs: "array",
+  passengerServiceSSRs: "array",
+  loungePlaceIDs: "array",
+  wifiAccess: "array",
+  seats: "array",
+  // Event
+  eventName: "string",
+  eventType: "string",
+  eventStartDate: "date",
+  eventEndDate: "date",
+  venueName: "string",
+  venueLocation: "location",
+  venueRoom: "string",
+  venueEntrance: "string",
+  venueRegionName: "string",
+  venuePhoneNumber: "string",
+  venueOpenDate: "date",
+  venueDoorsOpenDate: "date",
+  venueGatesOpenDate: "date",
+  venueCloseDate: "date",
+  entranceDescription: "string",
+  admissionLevelAbbreviation: "string",
+  additionalTicketAttributes: "string",
+  tailgatingAllowed: "boolean",
+  admissionLevel: "string",
+  attendeeName: "string",
+  performerNames: "array",
+  genre: "string",
+  sportName: "string",
+  leagueName: "string",
+  leagueAbbreviation: "string",
+  homeTeamName: "string",
+  homeTeamAbbreviation: "string",
+  homeTeamLocation: "string",
+  awayTeamName: "string",
+  awayTeamAbbreviation: "string",
+  awayTeamLocation: "string",
+  artistIDs: "array",
+  albumIDs: "array",
+  playlistIDs: "array",
+  // General
+  totalPrice: "currency",
+  balance: "currency",
+  duration: "number",
+  silenceRequested: "boolean",
+};
+
+/**
+ * Keys renamed between iOS 18 and iOS 26.
+ *
+ * A pass carrying the old spelling is not rejected; the tag is ignored, which
+ * means the feature it drives silently does not appear.
+ */
+export const RENAMED_SEMANTICS = {
+  departureAirportTimeZone: "departureLocationTimeZone",
+  destinationAirportTimeZone: "destinationLocationTimeZone",
+  airlinePassengerCapabilities: "passengerCapabilities",
+};
+
+/**
+ * Semantic tags an enhanced boarding pass needs before Wallet will use the
+ * richer layout. Missing any of them is not an error - the pass simply renders
+ * the way it did before, which is exactly why it is worth reporting.
+ */
+export const ENHANCED_BOARDING_PASS_TAGS = [
+  "airlineCode",
+  "flightNumber",
+  "departureAirportCode",
+  "destinationAirportCode",
+  "originalDepartureDate",
+  "originalArrivalDate",
+  "originalBoardingDate",
+  "departureLocationTimeZone",
+  "destinationLocationTimeZone",
+];
+
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * @returns {string|null} why the value is wrong for its declared type
+ */
+export function checkSemanticValue(key, type, value) {
+  switch (type) {
+    case "string":
+      return typeof value === "string" ? null : `must be a string, got ${typeOf(value)}`;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value)
+        ? null
+        : `must be a number, got ${typeOf(value)}`;
+    case "boolean":
+      return typeof value === "boolean" ? null : `must be a boolean, got ${typeOf(value)}`;
+    case "array":
+      return Array.isArray(value) ? null : `must be an array, got ${typeOf(value)}`;
+    case "date":
+      if (typeof value !== "string") return `must be an ISO 8601 string, got ${typeOf(value)}`;
+      return ISO_8601.test(value) ? null : `"${value}" is not ISO 8601`;
+    case "location":
+      if (!value || typeof value !== "object") return `must be an object with latitude and longitude`;
+      if (typeof value.latitude !== "number" || typeof value.longitude !== "number") {
+        return "latitude and longitude are both required and must be numbers";
+      }
+      return null;
+    case "currency":
+      if (!value || typeof value !== "object") return "must be an object";
+      if (typeof value.currencyCode !== "string") return "currencyCode is required";
+      if (typeof value.amount !== "string") return "amount must be a STRING, not a number";
+      return null;
+    case "personName":
+      if (!value || typeof value !== "object") return "must be an object of name components";
+      return null;
+    default:
+      return null;
+  }
+}
+
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}