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

package/tools/pass-kit/index.js

@@ -0,0 +1,432 @@
+/**
+ * pass-kit  -  build, sign, validate and inspect Apple Wallet passes.
+ *
+ * GENERIC BY CONSTRUCTION. No airline, no brand, no project appears anywhere in
+ * this directory. All five of Apple's styles are first-class, the asset
+ * contract is a table per style, and every identifier - pass type, team,
+ * organization, colours, copy - is caller input. The only thing that is not
+ * input is the specification itself.
+ *
+ * NO SECRETS. A literal passphrase is not an accepted parameter. The caller
+ * names an environment variable or a keychain entry, and the value reaches
+ * openssl through `-passin env:` so it never appears in `ps`, never lands in a
+ * log, and is scrubbed out of any error text on the way back.
+ *
+ * OFFLINE. Nothing here contacts Apple or anything else.
+ *
+ * @module tools/pass-kit
+ */
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { tmpdir } from "node:os";
+import { validatePass } from "./validate.js";
+import { STYLES, ASSETS, SCALES } from "./spec.js";
+import {
+  ERROR_PREFIX,
+  listPassFiles,
+  buildManifest,
+  writeManifest,
+  resolvePassphrase,
+  inspectCertificate,
+  signManifest,
+  verifySignature,
+  archive,
+  unpack,
+} from "./sign.js";
+
+const CERT_ARGS = {
+  certificate: { type: "string", description: "Pass Type ID certificate, PEM" },
+  private_key: { type: "string", description: "Private key for that certificate, PEM" },
+  wwdr_certificate: { type: "string", description: "Apple WWDR intermediate certificate, PEM" },
+  passphrase_env: {
+    type: "string",
+    description:
+      "NAME of an environment variable holding the private-key passphrase. Not the passphrase itself - a literal is deliberately not accepted",
+  },
+  keychain_account: {
+    type: "string",
+    description: "Keychain account to read the passphrase from, instead of passphrase_env",
+  },
+  keychain_service: { type: "string", description: 'Keychain service (default "pkpass")' },
+};
+
+export const PASS_TOOLS = [
+  {
+    name: "pass_validate",
+    description:
+      "Check a pass against Apple's rules without building or signing anything: required keys, the one style dictionary, field shapes, colours, barcodes, the per-style image contract, localization consistency, and semantic tags. Grades findings by consequence - an error is a pass Wallet refuses, a warning is a pass Wallet accepts while quietly doing less than intended. One unknown PKPassengerCapability value is the canonical example: no error anywhere, and the enhanced layout silently falls back.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pass_json: { type: "string", description: "Path to a pass.json" },
+        pass_dir: { type: "string", description: "Path to a .pass directory - checks its images and localizations too" },
+        pkpass: { type: "string", description: "Path to a built .pkpass - unpacked and checked, signature included" },
+      },
+    },
+  },
+  {
+    name: "pass_build",
+    description:
+      "Assemble, sign and archive a .pkpass. Takes a pass.json and an asset directory, writes the manifest (SHA-1 per file, as Apple specifies), signs it with openssl into a detached PKCS#7 signature, and zips the result. Validates first and refuses on an error-grade finding unless told otherwise. Offline, deterministic, and never accepts a literal passphrase.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pass_json: { type: "string", description: "Path to the pass.json to build from" },
+        assets_dir: { type: "string", description: "Directory holding the images and any xx.lproj folders" },
+        output: { type: "string", description: "Path to write the .pkpass to" },
+        ...CERT_ARGS,
+        overrides: {
+          type: "object",
+          description:
+            "Top-level keys to merge into pass.json before building - serialNumber, relevantDate, barcodes and so on. The file on disk is not modified",
+        },
+        allow_errors: {
+          type: "boolean",
+          description: "Build even when validation reports errors (default false)",
+        },
+      },
+      required: ["pass_json", "assets_dir", "output"],
+    },
+  },
+  {
+    name: "pass_inspect",
+    description:
+      "Open an existing .pkpass and report what is actually in it: style, top-level keys, semantic tags, images and their scales, localizations, whether the manifest matches the files, and the certificate chain that signed it. Read-only, and it never needs the private key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pkpass: { type: "string", description: "Path to the .pkpass to open" },
+        show_pass_json: { type: "boolean", description: "Include the full pass.json in the result" },
+      },
+      required: ["pkpass"],
+    },
+  },
+  {
+    name: "pass_certificates",
+    description:
+      "Report the signing material: which certificate this is, its pass type and team identifier, when it expires and whether it already has. An expired Pass Type ID certificate still builds, still signs and still verifies - Wallet is the first thing that refuses it, and it does not say why. Never reads or reports key material.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        certificate: { type: "string", description: "Pass Type ID certificate, PEM" },
+        wwdr_certificate: { type: "string", description: "Apple WWDR intermediate certificate, PEM" },
+        passphrase_env: { type: "string", description: "Name of an env var to check is set (its value is never read out)" },
+        keychain_account: { type: "string", description: "Keychain account to check exists" },
+        keychain_service: { type: "string", description: 'Keychain service (default "pkpass")' },
+      },
+      required: ["certificate"],
+    },
+  },
+];
+
+export const PASS_READ_ONLY = ["pass_validate", "pass_inspect", "pass_certificates"];
+
+export const PASS_OUTPUT_SCHEMAS = {
+  pass_validate: {
+    type: "object",
+    properties: {
+      style: { type: "string" },
+      ok: { type: "boolean" },
+      errors: { type: "array", items: { type: "object" } },
+      warnings: { type: "array", items: { type: "object" } },
+      notes: { type: "array", items: { type: "object" } },
+      checked: { type: "object" },
+    },
+    required: ["ok", "errors", "warnings", "notes"],
+  },
+  pass_certificates: {
+    type: "object",
+    properties: {
+      certificate: { type: "object" },
+      wwdr: { type: "object" },
+      passphrase: { type: "object" },
+      usable: { type: "boolean" },
+    },
+    required: ["certificate", "usable"],
+  },
+};
+
+function requireAbs(p, label) {
+  if (!p) return `${label} is required`;
+  if (!isAbsolute(p)) return `${label} must be an absolute path, got "${p}"`;
+  if (!existsSync(p)) return `no such ${label}: ${p}`;
+  return null;
+}
+
+function readJson(p) {
+  try {
+    return { value: JSON.parse(readFileSync(p, "utf8")) };
+  } catch (e) {
+    return { error: `${ERROR_PREFIX}${p} is not readable JSON: ${e.message}` };
+  }
+}
+
+function validateTool(args) {
+  if (args.pkpass) {
+    const bad = requireAbs(args.pkpass, "pkpass");
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+    const un = unpack(args.pkpass);
+    if (un.error) return un.error;
+    try {
+      const passPath = join(un.dir, "pass.json");
+      if (!existsSync(passPath)) return `${ERROR_PREFIX}${args.pkpass} contains no pass.json`;
+      const doc = readJson(passPath);
+      if (doc.error) return doc.error;
+      const files = listPassFiles(un.dir);
+      const report = validatePass(doc.value, files);
+      const sig = existsSync(join(un.dir, "signature"))
+        ? verifySignature({
+            signaturePath: join(un.dir, "signature"),
+            manifestPath: join(un.dir, "manifest.json"),
+          })
+        : { valid: false, reason: "no signature file" };
+      const manifestCheck = checkManifest(un.dir, files);
+      return {
+        ...report,
+        checked: { source: args.pkpass, files: files.length, signature: sig, manifest: manifestCheck },
+      };
+    } finally {
+      rmSync(un.dir, { recursive: true, force: true });
+    }
+  }
+
+  const dir = args.pass_dir;
+  if (dir) {
+    const bad = requireAbs(dir, "pass_dir");
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+    const passPath = join(dir, "pass.json");
+    if (!existsSync(passPath)) return `${ERROR_PREFIX}${dir} contains no pass.json`;
+    const doc = readJson(passPath);
+    if (doc.error) return doc.error;
+    const files = listPassFiles(dir);
+    return { ...validatePass(doc.value, files), checked: { source: dir, files: files.length } };
+  }
+
+  const p = args.pass_json;
+  const bad = requireAbs(p, "pass_json");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const doc = readJson(p);
+  if (doc.error) return doc.error;
+  const report = validatePass(doc.value, []);
+  // Asset findings against an empty file list would be noise, not findings.
+  return {
+    ...report,
+    errors: report.errors.filter((e) => e.kind !== "asset"),
+    checked: { source: p, files: 0, note: "pass.json only - give pass_dir or pkpass to check images too" },
+  };
+}
+
+function checkManifest(dir, files) {
+  const manifestPath = join(dir, "manifest.json");
+  if (!existsSync(manifestPath)) return { present: false };
+  const doc = readJson(manifestPath);
+  if (doc.error) return { present: true, valid: false, reason: "unreadable" };
+  const expected = buildManifest(dir, files);
+  const missing = Object.keys(expected).filter((f) => !(f in doc.value));
+  const extra = Object.keys(doc.value).filter((f) => !(f in expected));
+  const mismatched = Object.keys(expected).filter((f) => f in doc.value && doc.value[f] !== expected[f]);
+  return {
+    present: true,
+    valid: missing.length === 0 && extra.length === 0 && mismatched.length === 0,
+    entries: Object.keys(doc.value).length,
+    ...(missing.length ? { missing } : {}),
+    ...(extra.length ? { extra } : {}),
+    ...(mismatched.length ? { mismatched } : {}),
+  };
+}
+
+function buildTool(args) {
+  for (const [p, label] of [
+    [args.pass_json, "pass_json"],
+    [args.assets_dir, "assets_dir"],
+    [args.certificate, "certificate"],
+    [args.private_key, "private_key"],
+    [args.wwdr_certificate, "wwdr_certificate"],
+  ]) {
+    const bad = requireAbs(p, label);
+    if (bad) return `${ERROR_PREFIX}${bad}`;
+  }
+  if (!args.output || !isAbsolute(args.output)) {
+    return `${ERROR_PREFIX}output must be an absolute path`;
+  }
+
+  const pass = readJson(args.pass_json);
+  if (pass.error) return pass.error;
+  const doc = { ...pass.value, ...(args.overrides || {}) };
+
+  const cert = inspectCertificate(args.certificate);
+  if (cert.expired) {
+    return `${ERROR_PREFIX}the Pass Type ID certificate expired on ${cert.notAfter}. A pass signed with it builds, signs and verifies, and Wallet then refuses it without saying why. Renew it before building.`;
+  }
+
+  const secret = resolvePassphrase(args);
+  if (secret.error) return secret.error;
+
+  const staging = mkdtempSync(join(tmpdir(), "pass-build-"));
+  try {
+    cpSync(args.assets_dir, staging, { recursive: true });
+    rmSync(join(staging, "pass.json"), { force: true });
+    rmSync(join(staging, "manifest.json"), { force: true });
+    rmSync(join(staging, "signature"), { force: true });
+    writeFileSync(join(staging, "pass.json"), JSON.stringify(doc, null, 2));
+
+    const files = listPassFiles(staging);
+    const report = validatePass(doc, files);
+    if (!report.ok && !args.allow_errors) {
+      return {
+        built: false,
+        reason: "validation failed - pass allow_errors: true to build anyway",
+        ...report,
+      };
+    }
+
+    const manifest = buildManifest(staging, files);
+    const manifestPath = writeManifest(staging, manifest);
+    const signed = signManifest({
+      manifestPath,
+      signaturePath: join(staging, "signature"),
+      certificate: args.certificate,
+      privateKey: args.private_key,
+      wwdr: args.wwdr_certificate,
+      passphrase: secret.value,
+    });
+    if (signed.error) return signed.error;
+
+    mkdirSync(dirname(args.output), { recursive: true });
+    rmSync(args.output, { force: true });
+    const zipped = archive(staging, args.output);
+    if (zipped.error) return zipped.error;
+
+    return {
+      built: true,
+      output: args.output,
+      bytes: zipped.bytes,
+      style: report.style,
+      files: files.length + 2,
+      manifestEntries: Object.keys(manifest).length,
+      passphraseSource: secret.source,
+      certificate: { passTypeIdentifier: cert.passTypeIdentifier, teamIdentifier: cert.teamIdentifier, notAfter: cert.notAfter, daysLeft: cert.daysLeft },
+      warnings: report.warnings,
+      notes: report.notes,
+      ...(report.ok ? {} : { errors: report.errors, builtWithErrors: true }),
+    };
+  } catch (e) {
+    return `${ERROR_PREFIX}build failed: ${e.message}`;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function inspectTool(args) {
+  const bad = requireAbs(args.pkpass, "pkpass");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const un = unpack(args.pkpass);
+  if (un.error) return un.error;
+  try {
+    const passPath = join(un.dir, "pass.json");
+    if (!existsSync(passPath)) return `${ERROR_PREFIX}${args.pkpass} contains no pass.json`;
+    const doc = readJson(passPath);
+    if (doc.error) return doc.error;
+    const pass = doc.value;
+    const files = listPassFiles(un.dir);
+    const style = STYLES.find((s) => pass[s] !== undefined) || null;
+
+    const images = {};
+    for (const f of files) {
+      const m = /^([a-zA-Z]+)(@2x|@3x)?\.png$/.exec(f.split("/").pop() || "");
+      if (!m) continue;
+      images[m[1]] = images[m[1]] || [];
+      images[m[1]].push(m[2] || "1x");
+    }
+    const localizations = [
+      ...new Set(files.filter((f) => f.includes(".lproj/")).map((f) => f.split(".lproj/")[0].split("/").pop())),
+    ];
+
+    const sig = existsSync(join(un.dir, "signature"))
+      ? verifySignature({ signaturePath: join(un.dir, "signature"), manifestPath: join(un.dir, "manifest.json") })
+      : { valid: false, reason: "no signature file" };
+
+    return {
+      pkpass: args.pkpass,
+      bytes: statSync(args.pkpass).size,
+      style,
+      passTypeIdentifier: pass.passTypeIdentifier,
+      teamIdentifier: pass.teamIdentifier,
+      organizationName: pass.organizationName,
+      serialNumber: pass.serialNumber,
+      formatVersion: pass.formatVersion,
+      topLevelKeys: Object.keys(pass).sort(),
+      semanticTags: Object.keys(pass.semantics || {}).sort(),
+      barcodes: (pass.barcodes || []).map((b) => b.format),
+      updates: pass.webServiceURL ? { webServiceURL: pass.webServiceURL, hasAuthenticationToken: Boolean(pass.authenticationToken) } : null,
+      images,
+      localizations,
+      files: files.length,
+      manifest: checkManifest(un.dir, files),
+      signature: sig,
+      ...(args.show_pass_json ? { passJson: pass } : {}),
+    };
+  } finally {
+    rmSync(un.dir, { recursive: true, force: true });
+  }
+}
+
+function certificatesTool(args) {
+  const bad = requireAbs(args.certificate, "certificate");
+  if (bad) return `${ERROR_PREFIX}${bad}`;
+  const cert = inspectCertificate(args.certificate);
+  const wwdr = args.wwdr_certificate ? inspectCertificate(args.wwdr_certificate) : null;
+
+  let passphrase = { configured: false, note: "give passphrase_env or keychain_account to check one" };
+  if (args.passphrase_env || args.keychain_account) {
+    const r = resolvePassphrase(args);
+    // The VALUE is never reported, only whether one was found.
+    passphrase = r.error
+      ? { configured: false, reason: r.error.replace(ERROR_PREFIX, "") }
+      : { configured: true, source: r.source };
+  }
+
+  const usable = Boolean(cert && !cert.error && cert.expired === false);
+  const advice = [];
+  if (cert.expired) {
+    advice.push(
+      `The certificate expired on ${cert.notAfter}. A pass signed with it builds, signs and verifies; Wallet refuses it and says nothing. Renew it at developer.apple.com.`,
+    );
+  } else if (cert.daysLeft !== null && cert.daysLeft < 30) {
+    advice.push(`The certificate expires in ${cert.daysLeft} day(s).`);
+  }
+  if (!wwdr) advice.push("Give wwdr_certificate to check the intermediate too; signing needs it.");
+  if (!passphrase.configured) {
+    advice.push(
+      "No passphrase source configured. Name an environment variable (passphrase_env) or store one in the keychain; a literal passphrase is deliberately not an accepted input.",
+    );
+  }
+
+  return { certificate: cert, wwdr, passphrase, usable, advice };
+}
+
+/**
+ * @param {string} name
+ * @param {object} args
+ */
+export async function handlePass(name, args = {}) {
+  try {
+    switch (name) {
+      case "pass_validate":
+        return validateTool(args);
+      case "pass_build":
+        return buildTool(args);
+      case "pass_inspect":
+        return inspectTool(args);
+      case "pass_certificates":
+        return certificatesTool(args);
+      default:
+        return null;
+    }
+  } catch (e) {
+    return `${ERROR_PREFIX}${name}: ${e?.message || String(e)}`;
+  }
+}
+
+export { STYLES, ASSETS, SCALES };

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 };