@gjsify/cli 0.45.0 → 0.47.0

package/lib/utils/ship/signing.js

@@ -30,38 +30,53 @@
 //     exist before the validation, because they are computed from its output,
 //     and the arriving stage is never written to at all.
 //
-// WHAT THIS DELIBERATELY DOES NOT DO, each with its reason:
+// THREE THINGS THIS FILE USED TO REFUSE TO DO, and the measurement that changed
+// each of them (ADR 0040). Every one is marked UNVERIFIED where it is: this
+// repository has no macOS host of its own, so what follows is argv and file
+// structure decided from Apple's documentation and held by unit tests, with the
+// darwin CI leg as the only thing that has ever run `codesign` here.
 //
-//  * It does not seal the `<App>.app` BUNDLE. `codesign` on a bundle writes
-//    `Contents/_CodeSignature/CodeResources` and — for a main executable that is
-//    a shell script, which every layout's launcher is — stores that script's own
-//    signature in an extended attribute (Apple's documented behaviour, not
-//    measured here). What IS measured here is our side of it: the payload round
-//    trip is `readStage` → bytes + mode → `writePayload`, and it carries no
-//    extended attributes at all, so a bundle seal made now would not survive into
-//    the `.zip` beside the `.app`. The images the dynamic loader validates are
-//    the ones signed, which is what § A4's argument is about.
-//  * It passes no `--options runtime`, no `--entitlements` and no `--timestamp`.
-//    § A16 leaves library validation vs. hardened runtime explicitly unmeasured,
-//    and a secure timestamp needs a real Developer ID plus network. Adding any of
-//    them would be code no run in this repository has ever executed.
-//  * It does not staple, and the reason is NOT that stapling is unevidenced.
-//    Measured here on `refs/node` at the pinned `0618e9f0`, against the ADR's own
-//    control of 16 files for `codesign`: `stapler` returns 4 files, of which
-//    `tools/osx-notarize.sh:58` is real code — `xcrun stapler staple
-//    "node-$pkgid.pkg"`, three lines past where § A15 stopped quoting; the other
-//    three are changelog entries. What is NOT measured is whether it accepts
-//    OUR container: the reference staples a `.pkg`, and the only file-shaped
-//    darwin artifact this command produces is a `.zip`. Adding a call that may
-//    refuse the one artifact it would run on is code no run in this repository
-//    has exercised, deciding something it cannot justify. Recorded in
-//    `status/open-todos.md` instead.
-import { readFileSync } from 'node:fs';
-import { join, sep } from 'node:path';
+//  * IT NOW SEALS THE `<App>.app` BUNDLE, and the reason it did not was WRONG.
+//    The header used to say a bundle seal "would not survive into the `.zip`"
+//    because a script main executable's signature lives in an extended attribute
+//    and the payload round trip carries none. That is Apple's rule for a LOOSE
+//    file, not for a bundle. Apple's TN3126 gives four cases and ours is the
+//    second: *"If the item is a bundle without a Mach-O image, the code signature
+//    is stored in the bundle's _CodeSignature directory"* — regular files, mode
+//    0644, which a plain zip carries like any other. TN2206 states the same from
+//    the other side: *"a properly-signed app that has all of its files in the
+//    correct places will not contain any signatures stored as extended
+//    attributes."* So the seal is reachable, and what was actually blocking it was
+//    this file's own refusal of a changed file set. {@link signPayload} now allows
+//    exactly the additions the seal makes and still refuses every other one.
+//  * IT NOW PASSES `--options runtime`, `--entitlements` and (for a real identity)
+//    `--timestamp`. The hardened runtime is a bit in the CODE DIRECTORY, which an
+//    ad-hoc signature has, so the flag is accepted with `--sign -` as it is with a
+//    Developer ID. `--timestamp` is not: a timestamp lives in the CMS structure
+//    and an ad-hoc signature has no CMS and no certificate to pin, so it is passed
+//    only for a named identity — and Apple documents nothing about what
+//    `codesign --sign - --timestamp` does, which is a second reason not to send it.
+//  * IT NOW STAPLES what `stapler` accepts. `stapler(1)` is explicit —
+//    *"stapler works only with UDIF disk images, signed \"flat\" installer
+//    packages, and certain code-signed executable bundles such as \".app\""* — and
+//    Apple's notarisation guide adds the exception that decides our zip:
+//    *"While you can notarize a ZIP archive, you can't staple to it directly.
+//    Instead, run stapler against each item that you added to the archive."*
+//    `canCarryTicket` in `utils/ship/formats.ts` is that fact per format, so the
+//    `.dmg` is stapled and the `.zip` is told what a user has to do instead.
+//
+// WHAT IS STILL NOT DONE, deliberately: `signtool` is never given a timestamp URL
+// (see the win32 row), and the entitlement § A16 is about —
+// `com.apple.security.cs.disable-library-validation` — is NOT granted, because
+// § A4's re-sign of every image in the closure is the design of record and
+// granting the entitlement would quietly make it look unnecessary.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
 import { isOnPath } from '../check-system-deps.js';
 import { describeExit, spawnToCompletion } from '../spawn.js';
 import { listFilesRecursive } from './discover.js';
 import { classifyBinary } from './payload.js';
+import { renderEntitlements } from './plist.js';
 import { writePayload } from './stage-writer.js';
 /**
  * The signers, keyed by the LAYOUT they sign — never by the host they run on.
@@ -87,10 +102,63 @@ export const SIGNERS = {
         // ad-hoc (§ A4: 106 of 106) — `install_name_tool` invalidates the original
         // during relocation and the relocator re-signs. Without it `codesign`
         // refuses a file that already carries a signature.
-        args: (identity, file) => ['--force', '--sign', identity, file],
+        //
+        // `--options runtime` on BOTH identities and `--timestamp` on only one:
+        // the hardened runtime is a code-directory bit, which an ad-hoc signature
+        // has, while a timestamp is a CMS countersignature over a CERTIFICATE, and
+        // an ad-hoc signature has neither ("Ad-hoc signing does not use an identity
+        // at all", `codesign(1)`). Apple documents nothing about what
+        // `--sign - --timestamp` does, so it is not sent rather than guessed at —
+        // and the one thing `codesign(1)` does promise about the flag is that "if
+        // the timestamp authority service cannot be contacted … the signing
+        // operation will fail", which is not a failure worth inventing for a
+        // signature that cannot carry the result.
+        args: ({ identity, file, entitlements, adhoc }) => [
+            '--force',
+            '--sign',
+            identity,
+            '--options',
+            'runtime',
+            ...(entitlements === undefined ? [] : ['--entitlements', entitlements]),
+            ...(adhoc ? [] : ['--timestamp']),
+            file,
+        ],
+        // FOUR OF THE REFERENCE'S SIX, and both omissions are decisions:
+        //
+        //  * `com.apple.security.cs.get-task-allow` is granted by
+        //    `refs/node/tools/osx-entitlements.plist:15` and is a DEBUGGING
+        //    entitlement — it lets another process attach to this one. Apple's
+        //    notarisation rules refuse a Developer-ID artifact carrying it, so
+        //    shipping it would trade a working debug build for an artifact that
+        //    cannot be distributed. The reference signs its own build; we sign what
+        //    a stranger downloads.
+        //  * `com.apple.security.cs.disable-library-validation` is § A16's open
+        //    question and stays open. § A4's design of record is that every Mach-O
+        //    in the closure is re-signed with the SAME identity as the launcher, so
+        //    library validation has nothing to object to — and granting the
+        //    entitlement anyway would make that re-sign look optional the first
+        //    time somebody reads this list.
+        //
+        // The four that remain are what a shipped V8 needs under a hardened
+        // runtime, plus the one our own loader story needs:
+        // `@gjsify/node-gi`'s `maybeReexecForGtkRuntime` sets `DYLD_*` for its
+        // child on darwin, and a hardened process may not do that without
+        // `allow-dyld-environment-variables`.
+        entitlements: [
+            'com.apple.security.cs.allow-jit',
+            'com.apple.security.cs.allow-unsigned-executable-memory',
+            'com.apple.security.cs.disable-executable-page-protection',
+            'com.apple.security.cs.allow-dyld-environment-variables',
+        ],
+        // The `.app` is a bundle, and a bundle's signature is the seal over its
+        // whole tree — the images alone leave `codesign --verify` with nothing to
+        // read at the bundle level.
+        sealsBundle: true,
+        sealAddPrefix: (bundleRoot) => `${bundleRoot}/Contents/_CodeSignature/`,
         configKey: 'gjsify.ship.sign.darwin.identity',
-        gap: 'the images are signed; the `.app` bundle itself is not sealed and no entitlements are ' +
-            'granted (ADR 0024 § A16 leaves library validation unmeasured)',
+        gap: 'the images are signed and the bundle is sealed; UNVERIFIED end to end — no macOS host in this ' +
+            'repository has run a `--sign` over a real `.app`, and ADR 0024 § A16 still leaves library ' +
+            'validation unmeasured',
     },
     win32: {
         layoutOs: 'win32',
@@ -108,7 +176,17 @@ export const SIGNERS = {
         // records that SmartScreen only WARNS until per-file-hash reputation
         // accrues — signed or not. The argv is unit-tested, the skip and the
         // refusals are e2e-tested, and the invocation itself has no proof.
-        args: (identity, file) => ['sign', '/n', identity, '/fd', 'sha256', file],
+        args: ({ identity, file }) => ['sign', '/n', identity, '/fd', 'sha256', file],
+        // Windows has no equivalent concept. An Authenticode signature carries no
+        // capability claims — what a hardened runtime and an entitlement do on
+        // macOS is done on Windows by the manifest and by AppContainer, neither of
+        // which this signer touches.
+        entitlements: [],
+        // A Windows program directory is a DIRECTORY and nothing more: there is no
+        // manifest to seal and no per-directory signature format. `signtool` signs
+        // images, one at a time, which is what the loop above already does.
+        sealsBundle: false,
+        sealAddPrefix: () => '',
         configKey: 'gjsify.ship.sign.win32.identity',
         gap: 'no timestamp countersignature is requested, so the signature expires with the certificate ' +
             '(UNVERIFIED: no run in this repository has ever invoked signtool)',
@@ -174,6 +252,31 @@ export function assertHostCanSign(signer) {
             'a legitimate output (ADR 0024 § A13); silently producing one while --sign was asked for is not.');
     }
 }
+/**
+ * What a signing run did to the payload's FILE SET, split three ways.
+ *
+ * PURE, and extracted from {@link signPayload} for one reason: it is the whole of
+ * the seal decision and the only half of it that can be checked without a macOS
+ * host. Everything else about a bundle seal needs `codesign`, which this
+ * repository has on exactly one CI leg; this function needs nothing.
+ *
+ * `sealPrefix` absent means "this signer seals nothing", and then EVERY addition
+ * is unexpected — which is what the file did before ADR 0040 and is still the
+ * right answer for `signtool`.
+ */
+export function partitionSignedFileSet(input) {
+    const planned = new Set(input.planned);
+    const arrived = new Set(input.arrived);
+    const added = [...arrived].filter((path) => !planned.has(path)).sort();
+    const prefix = input.sealPrefix;
+    return {
+        sealed: prefix === undefined ? [] : added.filter((path) => path.startsWith(prefix)),
+        unexpected: prefix === undefined ? added : added.filter((path) => !path.startsWith(prefix)),
+        removed: [...planned].filter((path) => !arrived.has(path)).sort(),
+    };
+}
+/** `codesign --sign -`: the one identity value that names no identity at all. */
+export const ADHOC_IDENTITY = '-';
 /**
  * Re-sign every signable image in the payload, and hand back the new bytes.
  *
@@ -184,28 +287,29 @@ export function assertHostCanSign(signer) {
  * same tree fail `readStage`'s size comparison (measured — see the header), and
  * `writeStage`'s wipe would delete the payload it was about to pack.
  *
- * THE FILE SET MAY NOT CHANGE, and that is asserted rather than assumed. Both
- * tools rewrite an image in place, so a payload that gained or lost a path here
- * means something else ran — a bundle seal writing `_CodeSignature/`, say, whose
- * files would then be dropped on the way back into the payload without anyone
- * noticing.
+ * TWO STEPS ON DARWIN, ONE EVERYWHERE ELSE: every Mach-O in the closure, then the
+ * bundle itself. The second is what `codesign --verify <App>.app` reads, and it
+ * writes five regular files into `Contents/_CodeSignature/` that the returned
+ * payload carries — so the seal reaches the `.zip` and the `.dmg` alike, which is
+ * the correction ADR 0040 makes to this file's previous claim that it could not.
+ *
+ * THE FILE SET MAY ONLY GROW WHERE THE SEAL WRITES, and that is asserted rather
+ * than assumed. Both tools rewrite an image in place, so a payload that gained a
+ * path outside `sealAddPrefix` — or lost one anywhere — means something else ran,
+ * and its files would be packed with no mode from the plan.
  */
 export async function signPayload(input) {
     const { payload, signer, workDir } = input;
     writePayload(workDir, payload, '');
-    const signable = payload.filter((entry) => classifyBinary(entry.data) === signer.signs);
-    if (signable.length === 0) {
-        // NOT silent, and not an error either. A `--app gjs` payload really is
-        // JavaScript and a launcher, so there is nothing for the loader to
-        // validate — but a run that asked for a signature and made none has to
-        // say so, or "signed" and "signed nothing" look identical in the log.
-        input.log(`nothing in this payload is a ${signer.signs === 'macho' ? 'Mach-O' : 'PE'} image, so ` +
-            `${signer.tool} signed 0 file(s). The artifact carries no signature.`);
-        return [...payload];
+    const adhoc = input.identity === ADHOC_IDENTITY;
+    let entitlements;
+    if (signer.entitlements.length > 0) {
+        mkdirSync(dirname(input.entitlementsPath), { recursive: true });
+        writeFileSync(input.entitlementsPath, renderEntitlements(signer.entitlements));
+        entitlements = input.entitlementsPath;
     }
-    for (const entry of signable) {
-        const file = join(workDir, entry.path.split('/').join(sep));
-        const args = signer.args(input.identity, file);
+    const run = async (file, what) => {
+        const args = signer.args({ identity: input.identity, file, adhoc, ...(entitlements ? { entitlements } : {}) });
         if (input.verbose)
             input.log(`${signer.tool} ${args.join(' ')}`);
         const result = await spawnToCompletion(signer.tool, args, {
@@ -215,33 +319,75 @@ export async function signPayload(input) {
             notFound: () => new Error(`gjsify ship: \`${signer.tool}\` is not on PATH — ${signer.installHint}.`),
         });
         if (result.code !== 0) {
-            throw new Error(`gjsify ship: ${signer.tool} failed on ${entry.path} with ${describeExit(result)}. ` +
+            throw new Error(`gjsify ship: ${signer.tool} failed on ${what} with ${describeExit(result)}. ` +
                 'Nothing is packed from a payload whose signature failed: an artifact that is half ' +
                 'signed installs and is refused at first launch, which is worse than not shipping.');
         }
+    };
+    const signable = payload.filter((entry) => classifyBinary(entry.data) === signer.signs);
+    if (signable.length === 0 && !signer.sealsBundle) {
+        // NOT silent, and not an error either. A `--app gjs` payload really is
+        // JavaScript and a launcher, so there is nothing for the loader to
+        // validate — but a run that asked for a signature and made none has to
+        // say so, or "signed" and "signed nothing" look identical in the log.
+        //
+        // `&& !sealsBundle` is what keeps the message TRUE rather than what
+        // narrows it: a darwin run with no image still seals the bundle, which is
+        // a signature, so printing "the artifact carries no signature" there would
+        // be the log contradicting the artifact.
+        input.log(`nothing in this payload is a ${signer.signs === 'macho' ? 'Mach-O' : 'PE'} image, so ` +
+            `${signer.tool} signed 0 file(s). The artifact carries no signature.`);
+        return [...payload];
     }
-    const arrived = new Set(listFilesRecursive(workDir));
-    const planned = new Set(payload.map((entry) => entry.path));
-    const added = [...arrived].filter((path) => !planned.has(path));
-    const removed = [...planned].filter((path) => !arrived.has(path));
-    if (added.length > 0 || removed.length > 0) {
+    for (const entry of signable) {
+        await run(join(workDir, entry.path.split('/').join(sep)), entry.path);
+    }
+    // THE IMAGES FIRST, THE SEAL LAST, and the order is not stylistic: a bundle
+    // seal hashes the files it seals, so sealing before the closure is signed
+    // would record the digests of the images this run is about to replace and
+    // produce a bundle that verifies against a tree it no longer contains.
+    let sealPrefix;
+    if (signer.sealsBundle) {
+        if (input.bundleRoot === '') {
+            throw new Error(`gjsify ship: the ${signer.layoutOs} signer seals a bundle and this layout has no root to ` +
+                'seal. `Layout.root` is what names the artifact directory; a signer that sealed the whole ' +
+                'stage would sign the payload of every other format beside it.');
+        }
+        sealPrefix = signer.sealAddPrefix(input.bundleRoot);
+        await run(join(workDir, input.bundleRoot.split('/').join(sep)), `${input.bundleRoot} (bundle seal)`);
+    }
+    // THE FILE SET MAY ONLY GROW WHERE THE SEAL WRITES. Both tools rewrite an
+    // image in place, so any other new path means something else ran — and a file
+    // that appeared unnoticed would be packed with no mode from the plan, while
+    // one that vanished would be packed as absent.
+    const changes = partitionSignedFileSet({
+        arrived: listFilesRecursive(workDir),
+        planned: payload.map((entry) => entry.path),
+        ...(sealPrefix === undefined ? {} : { sealPrefix }),
+    });
+    if (changes.unexpected.length > 0 || changes.removed.length > 0) {
         throw new Error(`gjsify ship: ${signer.tool} changed the payload's file set — ` +
-            `${added.length} added (${added.slice(0, 3).join(', ') || '—'}), ` +
-            `${removed.length} removed (${removed.slice(0, 3).join(', ') || '—'}). ` +
-            'Signing is a mutation of the files that are already in the payload (ADR 0024 § A4); a ' +
-            'file that appeared here would be packed with no mode from the plan, and one that ' +
-            'vanished would be packed as absent.');
+            `${changes.unexpected.length} added (${changes.unexpected.slice(0, 3).join(', ') || '—'}), ` +
+            `${changes.removed.length} removed (${changes.removed.slice(0, 3).join(', ') || '—'}). ` +
+            'Signing is a mutation of the files that are already in the payload (ADR 0024 § A4), plus ' +
+            `exactly the seal's own directory${sealPrefix === undefined ? '' : ` (\`${sealPrefix}\`)`}.`);
     }
+    const sealed = changes.sealed;
     input.log(`${signer.tool} signed ${signable.length} of ${payload.length} payload file(s) as ` +
-        `${input.identity === '-' ? 'ad-hoc (`-`)' : `\`${input.identity}\``} — ${signer.gap}.`);
+        `${adhoc ? 'ad-hoc (`-`)' : `\`${input.identity}\``}` +
+        `${sealPrefix === undefined ? '' : ` and sealed ${input.bundleRoot} (${sealed.length} seal file(s))`}` +
+        ` — ${signer.gap}.`);
     // Modes come from the PLAN, exactly as `readStage` insists: the signer
     // rewrites bytes and this re-read must not turn a 0755 launcher into
-    // whatever the scratch directory's umask produced.
-    return payload.map((entry) => ({
-        path: entry.path,
-        mode: entry.mode,
-        data: new Uint8Array(readFileSync(join(workDir, entry.path.split('/').join(sep)))),
-    }));
+    // whatever the scratch directory's umask produced. The seal's own files have
+    // no plan entry — they did not exist when the plan was made — so they take
+    // 0644, which is what `codesign` writes them as
+    // (`bundlediskrep.cpp`: `O_WRONLY | O_CREAT | O_TRUNC, 0644`).
+    const read = (path) => new Uint8Array(readFileSync(join(workDir, path.split('/').join(sep))));
+    return [
+        ...payload.map((entry) => ({ path: entry.path, mode: entry.mode, data: read(entry.path) })),
+        ...sealed.map((path) => ({ path, mode: 0o644, data: read(path) })),
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
 }
 export const NOTARIES = {
     darwin: {
@@ -313,5 +459,48 @@ export async function notarizeArtifact(input) {
     if (result.code !== 0) {
         throw new Error(`gjsify ship: ${notary.tool} notarytool failed with ${describeExit(result)}.`);
     }
-    input.log(`${notary.tool} notarytool accepted ${input.artifact}. The artifact is NOT stapled.`);
+    input.log(`${notary.tool} notarytool accepted ${input.artifact}.`);
+}
+/**
+ * Attach the notarisation ticket to an artifact that can hold one.
+ *
+ * WHY IT IS A SEPARATE CALL AND NOT THE TAIL OF {@link notarizeArtifact}: not
+ * every artifact the notary service ACCEPTS can carry a ticket, and the pair that
+ * comes apart is exactly the one this command produces. Apple:
+ * *"While you can notarize a ZIP archive, you can't staple to it directly.
+ * Instead, run stapler against each item that you added to the archive. Then
+ * create a new ZIP file containing the stapled items for distribution."*
+ * `stapler(1)` gives the accepting side of the same list: *"stapler works only
+ * with UDIF disk images, signed \"flat\" installer packages, and certain
+ * code-signed executable bundles such as \".app\"."* So the `.dmg` is stapled
+ * here and the `.zip` is told, in the artifact log, what a person has to do
+ * instead — which is a fact about the CONTAINER and therefore lives on the format
+ * (`canCarryTicket`), not in a branch here.
+ *
+ * ⚠️ UNVERIFIED END TO END, for the same reason `notarizeArtifact` is: stapling
+ * needs a real notarisation, which needs an Apple account (ADR 0024 § A15, § A17).
+ * The argv is unit-tested and the invocation has never run in this repository.
+ *
+ * `stapler(1)` also states the constraint that decides the ORDER: *"Stapling does
+ * not invalidate the code signature and must be run after an executable or archive
+ * has been code-signed and notarized … Code-signing a supported file format
+ * invalidates any stapled tickets"* — so nothing may re-sign after this, and
+ * nothing in `packOne` does.
+ */
+export async function stapleArtifact(input) {
+    const args = ['stapler', 'staple', input.artifact];
+    if (input.verbose)
+        input.log(`${input.notary.tool} ${args.join(' ')}`);
+    const result = await spawnToCompletion(input.notary.tool, args, {
+        completion: 'return',
+        stdio: 'inherit',
+        notFound: () => new Error(`gjsify ship: \`${input.notary.tool}\` is not on PATH — ${input.notary.installHint}.`),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: ${input.notary.tool} stapler failed with ${describeExit(result)}. The artifact is ` +
+            'notarised and NOT stapled, which means every launch asks Gatekeeper to check online — and ' +
+            'fails closed on a machine with no network. Re-run the finish phase; `stapler` requires ' +
+            'internet access and the ticket may not have propagated yet.');
+    }
+    input.log(`${input.notary.tool} stapler attached the ticket to ${input.artifact}.`);
 }

package/lib/utils/ship/stage-writer.js

@@ -45,7 +45,26 @@ export function writeStage(root, files) {
     for (const file of files) {
         const target = join(root, file.path.split('/').join(sep));
         mkdirSync(dirname(target), { recursive: true });
-        const data = file.source.kind === 'text' ? new TextEncoder().encode(file.source.text) : readFileSync(file.source.path);
+        // A `switch` with a `never` guard rather than a ternary chain: the third
+        // source kind arrived because a LAYOUT started owning a binary, and a
+        // fourth would otherwise be written as whatever the last branch happens
+        // to be — the same closed-vocabulary hazard `packOne` uses one for.
+        let data;
+        switch (file.source.kind) {
+            case 'text':
+                data = new TextEncoder().encode(file.source.text);
+                break;
+            case 'file':
+                data = new Uint8Array(readFileSync(file.source.path));
+                break;
+            case 'bytes':
+                data = file.source.data;
+                break;
+            default: {
+                const unhandled = file.source;
+                throw new Error(`gjsify ship: no writer for the "${JSON.stringify(unhandled)}" source kind.`);
+            }
+        }
         writeFileSync(target, data);
         chmodSync(target, file.mode);
     }

package/lib/utils/ship/types.d.ts

@@ -7,13 +7,23 @@ export interface StagedMode {
 }
 /** One file in the payload, addressed relative to the install prefix. */
 export interface StagedFile extends StagedMode {
-    /** Where the bytes come from. */
+    /**
+     * Where the bytes come from.
+     *
+     * `bytes` is the third kind because a layout can now OWN a binary: the
+     * windows row emits a GUI-subsystem launcher (`utils/ship/pe-launcher.ts`)
+     * that exists nowhere on disk and is not text. Spelling it as `text` would
+     * round-trip it through UTF-8 and rewrite every byte above 0x7f.
+     */
     source: {
         kind: 'text';
         text: string;
     } | {
         kind: 'file';
         path: string;
+    } | {
+        kind: 'bytes';
+        data: Uint8Array;
     };
 }
 /**
@@ -286,6 +296,12 @@ export interface ShipMimeType {
  *    `share/locale/<rel>`, and no packer reads the field. So translations
  *    cross in the payload, where they belong, and the `abs` path does not
  *    cross at all. This list being explicit is what caught that.
+ *  - `fontFiles` — the same shape one milestone later (ADR 0038). `planStage`
+ *    copies each face into `share/fonts/<appId>/`, no packer reads the field, and
+ *    the only pack-time question — "does this payload carry fonts" — is answered
+ *    by the payload's own paths. There is no scriptlet to key off it either:
+ *    fontconfig scans the directory and caches lazily per user, measured rather
+ *    than assumed.
  *  - `kind`, `execArgs` — read by the planner and the metadata renderers, all of
  *    which have run by the time a stage exists. `appId` was on this line and
  *    MOVED: the Flatpak packer needs it at pack time twice over — it is the
@@ -342,7 +358,13 @@ export interface PackSettings {
     typelibPackages: Record<string, Record<DistroFormatId, string>>;
     /**
      * The interpreter the launcher execs, and therefore the one the package
-     * depends on. From `gjsify.app`; default `'gjs'`.
+     * depends on. THIS TARGET's runtime, resolved once by `resolveShipApp` out of
+     * `gjsify.ship.app.<os>` falling back to `gjsify.app`; default `'gjs'`.
+     *
+     * PER TARGET and never the project field, which is #1486's fix and whose
+     * measurement `resolveShipApp` carries. That the stage manifest records the
+     * RESOLVED value is what keeps `--from-stage` honest: the packing host has no
+     * project and needs none.
      *
      * ON `PackSettings`, not on `ShipSettings` alone, because BOTH halves need it
      * and they must not answer it differently: `renderLauncher` writes
@@ -432,6 +454,16 @@ export interface ShipSettings extends PackSettings {
         rel: string;
         abs: string;
     }[];
+    /**
+     * Absolute paths of the font faces the application ships (`gjsify.ship.fonts`).
+     *
+     * Read by `planStage` alone, which copies each into `share/fonts/<appId>/` — the
+     * one directory fontconfig reaches through the launcher's existing
+     * `XDG_DATA_DIRS` (ADR 0038). Nothing in the pack path reads it, which is why it
+     * is not on {@link PackSettings}; the fonts cross in the payload, like the
+     * catalogues.
+     */
+    fontFiles: string[];
     /** `<dest relative to prefix>` → absolute source path. */
     extraFiles: Record<string, string>;
     /** Arguments appended to the launcher's `exec` line. */

package/lib/utils/system-gi.d.ts

@@ -28,11 +28,25 @@ export declare const PROBED_GI_LIBDIRS: Record<string, readonly string[]>;
 /**
  * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
  *
- * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
- * one string this whole layout rule turns on. Both mirrors export it, so the
- * agreement suite still compares two files that differ only in language.
+ * Exported so `gi-typelib.ts` shares it rather than keeping a fourth copy of the
+ * one string this whole layout rule turns on, and compared across all three copies
+ * by the agreement suite rather than trusting three literals to stay equal.
  */
 export declare const TYPELIB_SUBDIR = "girepository-1.0";
+/**
+ * The library directories a typelib directory implies, most specific first.
+ *
+ * TWO LAYOUTS, and a path alone cannot always say which: GI's INSTALL layout keeps
+ * the libraries in the PARENT (`<libdir>/girepository-1.0/…`), while a STAGED pair —
+ * an ADR 0017 prebuild directory, `gjsify.ship.bundledTypelibs` — keeps them in the
+ * DIRECTORY ITSELF. {@link TYPELIB_SUBDIR} as the basename is a positive signal for
+ * the first; absent it, both readings are offered and the caller's `existsDir` keeps
+ * whichever is real.
+ *
+ * The measurement, and why the ORDER of the two is the load-bearing half, are in the
+ * ORIGINAL, `packages/node-gi/node-gi/system-gi.js`.
+ */
+export declare function giLibraryDirsForTypelibDir(typelibDir: string): string[];
 /** Split an OS search-path variable, dropping empty segments. */
 export declare function splitSearchPath(value: string | undefined, separator?: string): string[];
 /**
@@ -52,8 +66,9 @@ export declare function pkgConfigSearchDirs(env: Record<string, string | undefin
  *
  * Three sources, in precedence order:
  *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
- *      libraries are the sibling `dirname()`. Accepted on directory existence
- *      alone: an explicit statement is not second-guessed.
+ *      libraries are wherever {@link giLibraryDirsForTypelibDir} says the layout
+ *      puts them. Accepted on directory existence alone: an explicit statement is
+ *      not second-guessed.
  *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
  *      general mechanism (any prefix, including a custom one).
  *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common

package/lib/utils/system-gi.js

@@ -3,10 +3,12 @@
 // dynamic loader can find the ones a typelib names by BARE LEAF
 // (`libgtk-4.1.dylib`, `libgdk_pixbuf-2.0.0.dylib`, …).
 //
-// A PINNED MIRROR of `packages/node-gi/node-gi/system-gi.js` — the two must agree
-// and `system-gi.spec.ts` asserts it over a table of injected host shapes. Why a
-// mirror and not an import, and what is owed to retire it:
-// `status/open-todos.md` § "systemGiLibraryDirs() lives in two places".
+// A PINNED MIRROR of `packages/node-gi/node-gi/system-gi.js`, and of
+// `@gjsify/utils/core`'s `system-gi-dirs.ts` — all three must agree and
+// `system-gi.spec.ts` asserts it over a table of injected host shapes. Why a mirror
+// and not an import, and what is owed to retire THIS copy (a delegation to
+// `@gjsify/utils`, which the CLI already depends on):
+// `status/open-todos.md` § "systemGiLibraryDirs() lives in three places".
 //
 // WHY THIS EXISTS. A failed `dlopen('libgtk-4.1.dylib')` surfaces one layer up as
 // something that reads like a type-system bug — `TypeError: Gtk.DrawingArea is not
@@ -32,6 +34,8 @@
 // `<libdir>/libgtk-4.1.dylib`. A directory holding `girepository-1.0/` therefore IS
 // a GI library directory, which is what makes this package-manager-agnostic — it
 // lands on Homebrew, MacPorts or a custom prefix without knowing any of them exist.
+// THAT IS ONE LAYOUT, NOT THE LAYOUT — {@link giLibraryDirsForTypelibDir}; a staged
+// pair keeps typelib and backer in ONE directory, and the incident is in the ORIGINAL.
 //
 // PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
 // `resolvePrebuildDirName()` and `buildNativeEnv()` beside it, so the darwin branch
@@ -74,11 +78,28 @@ export const PROBED_GI_LIBDIRS = {
 /**
  * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
  *
- * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
- * one string this whole layout rule turns on. Both mirrors export it, so the
- * agreement suite still compares two files that differ only in language.
+ * Exported so `gi-typelib.ts` shares it rather than keeping a fourth copy of the
+ * one string this whole layout rule turns on, and compared across all three copies
+ * by the agreement suite rather than trusting three literals to stay equal.
  */
 export const TYPELIB_SUBDIR = 'girepository-1.0';
+/**
+ * The library directories a typelib directory implies, most specific first.
+ *
+ * TWO LAYOUTS, and a path alone cannot always say which: GI's INSTALL layout keeps
+ * the libraries in the PARENT (`<libdir>/girepository-1.0/…`), while a STAGED pair —
+ * an ADR 0017 prebuild directory, `gjsify.ship.bundledTypelibs` — keeps them in the
+ * DIRECTORY ITSELF. {@link TYPELIB_SUBDIR} as the basename is a positive signal for
+ * the first; absent it, both readings are offered and the caller's `existsDir` keeps
+ * whichever is real.
+ *
+ * The measurement, and why the ORDER of the two is the load-bearing half, are in the
+ * ORIGINAL, `packages/node-gi/node-gi/system-gi.js`.
+ */
+export function giLibraryDirsForTypelibDir(typelibDir) {
+    const parent = dirname(typelibDir);
+    return basename(typelibDir) === TYPELIB_SUBDIR ? [parent] : [typelibDir, parent];
+}
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;
 /** Split an OS search-path variable, dropping empty segments. */
@@ -124,8 +145,9 @@ export function pkgConfigSearchDirs(env) {
  *
  * Three sources, in precedence order:
  *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
- *      libraries are the sibling `dirname()`. Accepted on directory existence
- *      alone: an explicit statement is not second-guessed.
+ *      libraries are wherever {@link giLibraryDirsForTypelibDir} says the layout
+ *      puts them. Accepted on directory existence alone: an explicit statement is
+ *      not second-guessed.
  *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
  *      general mechanism (any prefix, including a custom one).
  *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common
@@ -155,11 +177,12 @@ export function systemGiLibraryDirs({ platform = process.platform, env = process
         if (dir && dir !== '/' && !out.includes(dir))
             out.push(dir);
     };
-    // 1. Explicit: the typelib dir's sibling libdir.
+    // 1. Explicit: the libdirs each typelib dir implies, both layouts.
     for (const typelibDir of splitSearchPath(env['GI_TYPELIB_PATH'])) {
-        const libDir = dirname(typelibDir);
-        if (existsDir(libDir))
-            add(libDir);
+        for (const libDir of giLibraryDirsForTypelibDir(typelibDir)) {
+            if (existsDir(libDir))
+                add(libDir);
+        }
     }
     // 2 + 3. Candidate prefixes, believed only on the girepository-1.0 marker.
     const candidates = [];