@gjsify/cli 0.44.0 → 0.46.0

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

@@ -0,0 +1,311 @@
+import { type PayloadEntry } from './payload.js';
+import type { HostOs } from './types.js';
+/**
+ * Everything that is per-OS about making a signature, as data.
+ *
+ * The same shape argument `FormatDescriptor` makes one directory over: a second
+ * OS is a row, not a branch. It is a separate table from `FORMATS` on purpose —
+ * § A14 measured that a format declares where it can be PACKED and never what it
+ * can be signed with, and darwin has two format rows that must not be able to
+ * disagree about their signature.
+ */
+export interface SignerDescriptor {
+    /** The layout whose payload this signer signs. */
+    layoutOs: HostOs;
+    /** The command that makes the signature. */
+    tool: string;
+    /** OSes whose tooling can run {@link tool}. */
+    signOn: readonly HostOs[];
+    /** Where {@link tool} comes from, in this signer's own words. */
+    installHint: string;
+    /**
+     * Which payload files carry a signature on this OS.
+     *
+     * `classifyBinary`'s vocabulary, so the predicate is the magic number and
+     * not a filename pattern: a darwin closure names its images `.dylib`,
+     * `.so`, `.node` and nothing at all (the interpreter), and a suffix list
+     * would sign three of those four.
+     */
+    signs: 'macho' | 'pe';
+    /** argv after {@link tool}, for ONE file. */
+    args: (input: SignArgs) => readonly string[];
+    /**
+     * The entitlements this signer asks for, or `[]` where the OS has none.
+     *
+     * `[]` is an ANSWER and not an omission — the same rule `Layout.metadata`
+     * states. Windows has no equivalent concept at all, and a signer that granted
+     * nothing on macOS would be a different decision from one that has nothing to
+     * grant.
+     */
+    entitlements: readonly string[];
+    /**
+     * Does this signer seal the ARTIFACT ROOT after signing the images inside it?
+     *
+     * Only true where the OS has a bundle format, which is darwin alone. The root
+     * itself is not on the descriptor because it belongs to the LAYOUT
+     * (`Layout.root`), and a second copy here is where the two would come apart.
+     */
+    sealsBundle: boolean;
+    /**
+     * Payload paths a seal is allowed to ADD, given the artifact root.
+     *
+     * A PREFIX rather than a free hand: `codesign` on a bundle writes
+     * `Contents/_CodeSignature/{CodeResources,CodeDirectory,CodeRequirements,
+     * CodeRequirements-1,CodeSignature}` and nothing else, so anything appearing
+     * outside that directory is something else having run — which is exactly the
+     * class {@link signPayload}'s file-set check exists to catch.
+     */
+    sealAddPrefix: (bundleRoot: string) => string;
+    /** The config key a project spells its default identity under. */
+    configKey: string;
+    /** What a signature from this signer does NOT yet cover — printed once per run. */
+    gap: string;
+}
+/**
+ * The signers, keyed by the LAYOUT they sign — never by the host they run on.
+ *
+ * Linux is deliberately absent rather than present-and-empty. A `.deb` and an
+ * `.rpm` carry no per-file signature: the artifact is signed as a whole, by the
+ * repository that serves it (`debsigs`, `rpmsign`), with a key that belongs to
+ * that repository and not to this build. A row here would make `--sign` on Linux
+ * look like it did something.
+ */
+export declare const SIGNERS: Partial<Record<HostOs, SignerDescriptor>>;
+/** `gjsify.ship.sign` as declared — one entry per {@link HostOs}. */
+export type SignConfig = Partial<Record<HostOs, {
+    identity?: string;
+}>>;
+/**
+ * What this run will do about signatures.
+ *
+ * A union rather than an optional string, because the three states need three
+ * different words and collapsing them is exactly what § A13 warns about: "no
+ * signer for this layout" is silence, "a slot exists and is empty" is a printed
+ * skip, and "here is an identity" is work.
+ */
+export type SignPlan = {
+    kind: 'unsupported';
+} | {
+    kind: 'skip';
+    message: string;
+} | {
+    kind: 'sign';
+    identity: string;
+    signer: SignerDescriptor;
+    source: 'flag' | 'config';
+};
+/**
+ * Resolve the identity for this run, or say why there is none.
+ *
+ * `flag` beats `config` and neither is a yargs `default:` — the uniform
+ * precedence `resolveShipSettings` documents. `config` is `undefined` on the
+ * `--from-stage` path and that is not an omission: § A14 amends § A1 to *a
+ * format declares where it can be packed; the RUN declares what it can sign
+ * with*, and the finishing host has no project to read a default out of.
+ */
+export declare function resolveSignPlan(input: {
+    /** `--sign` as typed. `''` is a value: it is `[ -z "$SIGN" ]` (§ A13). */
+    flag?: string;
+    /** `gjsify.ship.sign`, when a project is in reach. */
+    config?: SignConfig;
+    layoutOs: HostOs;
+}): SignPlan;
+/**
+ * Refuse a signing run this host cannot make, and say which half is missing.
+ *
+ * Two checks and not one, for the same reason `assertCanPack` splits them: the
+ * wrong OS needs another machine, an absent tool needs a package. Both are
+ * knowable before anything is packed.
+ */
+export declare function assertHostCanSign(signer: SignerDescriptor): void;
+/**
+ * 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 declare function partitionSignedFileSet(input: {
+    /** Paths found under the scratch directory after the tool ran. */
+    arrived: readonly string[];
+    /** Paths the payload had before it. */
+    planned: readonly string[];
+    /** Directory prefix the seal is allowed to write into, when there is one. */
+    sealPrefix?: string;
+}): {
+    sealed: string[];
+    unexpected: string[];
+    removed: string[];
+};
+/** What one invocation of a signing tool is given. */
+export interface SignArgs {
+    identity: string;
+    /** Absolute path of the file — or, for a bundle seal, of the bundle DIRECTORY. */
+    file: string;
+    /** Absolute path of the entitlements plist this run wrote, or absent when the signer grants none. */
+    entitlements?: string;
+    /** Is {@link identity} the reserved ad-hoc `-`? */
+    adhoc: boolean;
+}
+/** `codesign --sign -`: the one identity value that names no identity at all. */
+export declare const ADHOC_IDENTITY = "-";
+export interface SignPayloadInput {
+    /** What `readStage` returned — the PRE-sign tree, already held against the manifest. */
+    payload: readonly PayloadEntry[];
+    identity: string;
+    signer: SignerDescriptor;
+    /** A scratch directory this function owns and WIPES. Never the arriving stage. */
+    workDir: string;
+    /**
+     * `Layout.root` — the payload-relative directory that IS the artifact, or `''`.
+     *
+     * Read only by a signer that seals: it is what `codesign` is pointed at, and
+     * it comes from the layout rather than from this table because the layout is
+     * what decided the `<App>.app` name in the first place.
+     */
+    bundleRoot: string;
+    /**
+     * Where to write the entitlements plist, OUTSIDE {@link workDir}.
+     *
+     * Outside is not a preference: the file-set check below lists `workDir` and
+     * compares it with the payload, so an entitlements file written inside would
+     * read as a file the signer added.
+     */
+    entitlementsPath: string;
+    /** Print every invocation. */
+    verbose: boolean;
+    log: (line: string) => void;
+}
+/**
+ * Re-sign every signable image in the payload, and hand back the new bytes.
+ *
+ * The signature is made on FILES because that is the only interface `codesign`
+ * and `signtool` have, so the payload is materialised into `workDir`, signed
+ * there, and read back. `workDir` is a scratch directory rather than the stage:
+ * writing into an arriving stage would make the next `--from-stage` run of the
+ * same tree fail `readStage`'s size comparison (measured — see the header), and
+ * `writeStage`'s wipe would delete the payload it was about to pack.
+ *
+ * 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 declare function signPayload(input: SignPayloadInput): Promise<PayloadEntry[]>;
+/**
+ * What this run will do about notarisation.
+ *
+ * A SECOND credential and an unrelated one (§ A15): `--sign` names an identity
+ * the signing machine holds, `--notarize` names an account credential. They are
+ * two flags because they are two inputs, and the reference keeps them in two
+ * scripts.
+ */
+export interface NotaryDescriptor {
+    layoutOs: HostOs;
+    tool: string;
+    notarizeOn: readonly HostOs[];
+    installHint: string;
+    /**
+     * argv after {@link tool}.
+     *
+     * `credential` is threaded straight into the flag the command consumes, and
+     * that is the whole design of {@link resolveNotaryPlan}'s guard. § A15
+     * measured the trap: `refs/node/tools/osx-notarize.sh` guards on three
+     * environment variables it never uses and then submits with a
+     * `--keychain-profile` nothing checked, so the skip is reachable from an
+     * input the next line does not read. Here the guarded value IS the argument.
+     *
+     * ⚠️ `--keychain-profile` is the ONLY shape § A15 found evidenced, and the
+     * App Store Connect API-key form (`--key`/`--key-id`/`--issuer`) is NOT
+     * implemented because nothing measured it. UNVERIFIED, and marked as such:
+     * no run in this repository has ever invoked `notarytool` — notarisation
+     * needs an Apple account, which ad-hoc signing deliberately does not.
+     */
+    args: (credential: string, artifact: string) => readonly string[];
+}
+export declare const NOTARIES: Partial<Record<HostOs, NotaryDescriptor>>;
+export type NotaryPlan = {
+    kind: 'unsupported';
+} | {
+    kind: 'skip';
+    message: string;
+} | {
+    kind: 'notarize';
+    credential: string;
+    notary: NotaryDescriptor;
+};
+/**
+ * Resolve the notarisation credential, or say why there is none.
+ *
+ * Deliberately NOT defaultable from the project. An identity is a name a machine
+ * may hold for years and is worth writing into a repository; a notarisation
+ * credential is a per-run account credential, and a config key for it is an
+ * invitation to commit one.
+ */
+export declare function resolveNotaryPlan(input: {
+    flag?: string;
+    layoutOs: HostOs;
+    sign: SignPlan;
+}): NotaryPlan;
+/**
+ * Submit one written artifact for notarisation.
+ *
+ * ⚠️ UNVERIFIED END TO END. Everything up to the `spawnToCompletion` is covered
+ * — the argv by `signing.spec.ts`, the guard and both refusals by
+ * `tests/e2e/ship-signing` — and the invocation itself has never run: it needs
+ * an Apple Developer account, and § A17's whole point is that M6's proof does
+ * not. Whoever first runs this on a real credential should record what it did
+ * beside § A15, which is where the question was left open.
+ */
+export declare function notarizeArtifact(input: {
+    plan: Extract<NotaryPlan, {
+        kind: 'notarize';
+    }>;
+    /** The artifact to submit. Must be a FILE — notarytool takes an archive or an installer. */
+    artifact: string;
+    verbose: boolean;
+    log: (line: string) => void;
+}): Promise<void>;
+/**
+ * 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 declare function stapleArtifact(input: {
+    notary: NotaryDescriptor;
+    artifact: string;
+    verbose: boolean;
+    log: (line: string) => void;
+}): Promise<void>;