@hasna/recordings 0.2.14 → 0.3.2

package/scripts/macos_artifact.ts

@@ -31,6 +31,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { crc32, inflateRawSync } from "node:zlib";
 import {
   nativeFsGuard,
@@ -57,8 +58,100 @@ export const BUNDLE_ID = "com.hasna.recordings";
 export const PROVENANCE_FILENAME = "recordings-build-provenance.json";
 export const RELEASE_APPROVED_TARGET = "fleet";
 export const LEGACY_LOCAL_TARGET_IDENTITY_KIND = "hardware_uuid_sha256";
+export const LOCAL_ONLY_APPROVED_TARGETS_POLICY_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "policy",
+  "local-only-approved-targets.txt",
+);
+
+// The approved local-only targets are policy data, not code: one file is read by
+// this validator and, through scripts/read_local_only_targets.sh, by both shell entry
+// points, so a target is declared once. The shell reader is a separate implementation
+// of these rules; equivalence is enforced by an executing contract test, not by shared
+// code. Parsing stays deliberately strict — a malformed policy fails closed rather than
+// silently widening the allowlist.
+//
+// This is an operator-integrity control, NOT an authorization boundary. The file sits in
+// the same package root as the guards that read it, so anyone able to edit it can edit
+// those guards. Widening it still grants nothing on its own: the install additionally
+// requires a matching `hostname -s`, a matching authenticated Tailscale node digest, and
+// a matching authenticated manifest SHA-256.
+export function localOnlyApprovedTargets(
+  policyPath: string = LOCAL_ONLY_APPROVED_TARGETS_POLICY_PATH,
+): string[] {
+  // lstat, not readFileSync alone: readFileSync FOLLOWS a symlink, and the shell reader
+  // refuses one outright (`[ -L ]`). That divergence was real and it favoured the
+  // attacker — a policy symlinked at a widened allowlist was rejected by the shell gate
+  // and silently honoured here. Refusing every non-regular file matches the shell reader
+  // and keeps the wording it prints, so both sides fail closed identically.
+  let policyStats;
+  try {
+    policyStats = lstatSync(policyPath);
+  } catch {
+    throw new Error("local-only approved target policy is missing");
+  }
+  if (!policyStats.isFile()) {
+    throw new Error("local-only approved target policy is missing");
+  }
+  // An unreadable (mode 000) policy passes the lstat above and then threw a raw EACCES from
+  // here, while the shell reader emitted bash's own "Permission denied" and no reader
+  // message. Same fail-closed outcome, two unrecognizable errors; both now say this.
+  let rawContents: string;
+  try {
+    rawContents = readFileSync(policyPath, "utf8");
+  } catch {
+    throw new Error("local-only approved target policy is not readable");
+  }
+  // Reject a NUL anywhere, in the same order and with the same wording as the shell
+  // reader's pre-scan. This reader had no NUL check at all and only ever refused one that
+  // happened to land inside a would-be hostname: "# comment\0" was dropped as a comment,
+  // so "# comment\0\nstation03\n" was refused by the shell gate and ACCEPTED here.
+  if (rawContents.includes("\u0000")) {
+    throw new Error("local-only approved target policy contains a NUL byte");
+  }
+  // Strip a BOM at offset 0 only. A U+FEFF anywhere else is a zero-width no-break space,
+  // not a byte-order mark; the shell reader used to strip one per line and therefore
+  // accepted a BOM on line 2 that this reader rejected.
+  const contents = rawContents.replace(/^/, "");
+  const targets = contents
+    .split("\n")
+    // Deliberately NOT String.trim(): trim() also strips U+FEFF and U+00A0, and the
+    // shell reader trims neither, so a trailing NBSP or BOM would be accepted here and
+    // rejected there. ASCII space and tab only, matching read_local_only_targets.sh
+    // under its pinned LC_ALL=C; everything else is left for the hostname shape below.
+    .map((line) => line.replace(/\r$/, "").replace(/^[\t ]+|[\t ]+$/g, ""))
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+  if (targets.length === 0) {
+    throw new Error("local-only approved target policy lists no targets");
+  }
+  for (const target of targets) {
+    if (!/^[a-z][a-z0-9-]{1,30}[a-z0-9]$/.test(target)) {
+      throw new Error(`local-only approved target policy has an invalid target name: ${target}`);
+    }
+  }
+  if (new Set(targets).size !== targets.length) {
+    throw new Error("local-only approved target policy has duplicate targets");
+  }
+  if (targets.includes(RELEASE_APPROVED_TARGET)) {
+    throw new Error("local-only approved target policy must not list the release fleet target");
+  }
+  return targets;
+}
+
+export function isLocalOnlyApprovedTarget(
+  target: string | undefined,
+  policyPath?: string,
+): boolean {
+  if (target === undefined) return false;
+  return localOnlyApprovedTargets(policyPath).includes(target);
+}
+
+function localOnlyApprovedTargetsMessage(policyPath?: string): string {
+  return localOnlyApprovedTargets(policyPath).join(", ");
+}
 
 export type ArtifactPolicy = "release" | "local_only";
+export type ArtifactVariant = "full" | "bar";
 export type TargetIdentityKind =
   | typeof LEGACY_LOCAL_TARGET_IDENTITY_KIND
   | "tailscale_node_id_sha256";
@@ -67,6 +160,7 @@ type OperatorTargetIdentityKind = TargetIdentityKind | "none";
 export type BuildProvenance = {
   schema_version: 3 | 4;
   artifact_policy?: "local_only";
+  variant?: ArtifactVariant;
   approved_target?: string;
   approved_target_identity_kind?: TargetIdentityKind;
   approved_target_identity_sha256?: string;
@@ -89,13 +183,16 @@ export type BuildProvenance = {
 
 export type MacOSArtifactManifest = BuildProvenance & {
   artifact_type: "recordings-macos-app";
+  /// The top-level bundle directory name inside the artifact (Recordings.app for the
+  /// full app, HasnaRecordings.app for the bar variant per the fleet naming rule).
+  bundle_name: string;
   app_sha256: string;
   binding: {
     bundle_tree_sha256: string;
   };
   provenance_sha256: string;
   signing: {
-    mode?: "ad_hoc";
+    mode?: "ad_hoc" | "developer_id";
     authority: string;
     team_id: string;
     trusted_timestamp: string;
@@ -118,7 +215,7 @@ export type MacOSArtifactManifest = BuildProvenance & {
   };
   container: {
     type: "zip";
-    install_locations: ["/Applications/Recordings.app"] | ["~/Applications/Recordings.app"];
+    install_locations: [string];
   };
   nested_code_policy: {
     allowlist_sha256: string;
@@ -460,14 +557,43 @@ export function parseDesignatedRequirement(output: string): string {
   return requirement;
 }
 
+/**
+ * A local-station artifact is signed one of two ways, and the expected team identifier is
+ * what says which: the sentinel `ADHOC`, or a real 10-character Apple team.
+ *
+ * Developer ID signing exists on this path because ad-hoc signing cannot hold a macOS TCC
+ * grant. TCC keys Accessibility (and Microphone) to bundle id plus signing identity, and an
+ * ad-hoc signature offers only a CDHash that changes on every rebuild, so the hold-to-talk
+ * CGEventTap in FnKeyMonitor.swift lost its permission on each reinstall. Ad-hoc remains
+ * supported for builders that hold no signing key.
+ */
+export function isLocalOnlySigningTeam(expectedTeamId: string): boolean {
+  return expectedTeamId === "ADHOC" || /^[A-Z0-9]{10}$/.test(expectedTeamId);
+}
+
+export function localOnlySigningMode(expectedTeamId: string): "ad_hoc" | "developer_id" {
+  if (expectedTeamId === "ADHOC") return "ad_hoc";
+  if (!/^[A-Z0-9]{10}$/.test(expectedTeamId)) {
+    throw new Error(
+      "local-only Developer ID signing requires ADHOC or a 10-character Apple team identifier",
+    );
+  }
+  return "developer_id";
+}
+
 export function designatedRequirementForPolicy(
   output: string,
   artifactPolicy: ArtifactPolicy,
   adHocSignatureVerified = false,
+  developerIdSignatureVerified = false,
 ): string {
   if (artifactPolicy === "release") return parseDesignatedRequirement(output);
+  // A Developer ID local-station artifact always carries a real designated requirement, and
+  // that requirement is the whole point of signing it: it is the stable identity a TCC grant
+  // attaches to. Never let it degrade to the ad-hoc sentinel.
+  if (developerIdSignatureVerified) return parseDesignatedRequirement(output);
   if (!adHocSignatureVerified) {
-    throw new Error("local-only designated requirement evidence requires verified ad-hoc signing");
+    throw new Error("local-only designated requirement evidence requires verified signing");
   }
   try {
     return parseDesignatedRequirement(output);
@@ -558,11 +684,24 @@ function signingEvidence(
     if (!timestamp || timestamp.toLowerCase() === "none") {
       throw new Error(`${codePath} is missing a trusted signing timestamp`);
     }
+  } else if (localOnlySigningMode(expectedTeamId) === "developer_id") {
+    // Developer ID signed but deliberately NOT notarized: the notarization, single-target
+    // binding and builder attestation are what still separate this from a release. Only the
+    // signing identity is shared, and only because TCC cannot key a durable Accessibility
+    // grant to anything weaker (see localOnlySigningMode).
+    if (!authority.startsWith("Developer ID Application:")) {
+      throw new Error(`${codePath} is not signed by a Developer ID Application authority`);
+    }
+    if (teamId !== expectedTeamId) {
+      throw new Error(`${codePath} TeamIdentifier ${teamId || "missing"} does not match ${expectedTeamId}`);
+    }
+    if (rawSignature.toLowerCase() === "adhoc") {
+      throw new Error(`${codePath} is ad-hoc signed but a Developer ID team was pinned`);
+    }
+    // A trusted timestamp is a release-only claim; local-station builds never pass --timestamp.
+    timestamp = rawTimestamp && rawTimestamp.toLowerCase() !== "none" ? rawTimestamp : "none";
   } else {
     mode = "ad_hoc";
-    if (expectedTeamId !== "ADHOC") {
-      throw new Error("local-only code verification requires the ADHOC signing identity");
-    }
     if (rawSignature.toLowerCase() !== "adhoc" || authority) {
       throw new Error(`${codePath} is not consistently ad-hoc signed for local-only use`);
     }
@@ -587,6 +726,7 @@ function signingEvidence(
     requirementOutput,
     artifactPolicy,
     mode === "ad_hoc",
+    artifactPolicy !== "release" && mode === "developer_id",
   );
   const entitlements = canonicalEntitlements(codePath);
   if (entitlements !== canonicalJson(expectedEntitlements)) {
@@ -690,6 +830,22 @@ function manifestPolicy(manifest: MacOSArtifactManifest): ArtifactPolicy {
   return manifest.schema_version === LOCAL_ARTIFACT_SCHEMA_VERSION ? "local_only" : "release";
 }
 
+/**
+ * The variant an artifact was built as. Older manifests predate the field; they are
+ * full artifacts by definition ("full" was the only variant that existed).
+ */
+function manifestVariant(manifest: MacOSArtifactManifest): ArtifactVariant {
+  const value = manifest.variant ?? "full";
+  if (value !== "full" && value !== "bar") {
+    throw new Error(`manifest variant is unsupported: ${value}`);
+  }
+  return value;
+}
+
+function manifestBundleName(manifest: MacOSArtifactManifest): string {
+  return manifest.bundle_name ?? "Recordings.app";
+}
+
 function manifestTargetIdentityKind(manifest: MacOSArtifactManifest): OperatorTargetIdentityKind {
   if (manifestPolicy(manifest) === "release") return "none";
   return manifest.approved_target_identity_kind ?? LEGACY_LOCAL_TARGET_IDENTITY_KIND;
@@ -1270,6 +1426,7 @@ export function withPrivatelyExtractedArchiveApp<T>(
   operation: (appPath: string) => T,
   platformArchiveTool = "/usr/bin/ditto",
   expectedArchiveSha256?: string,
+  expectedBundleName = "Recordings.app",
 ): T {
   const privateRoot = mkdtempSync(join(tmpdir(), "recordings-artifact-extract-"));
   chmodSync(privateRoot, 0o700);
@@ -1314,13 +1471,17 @@ export function withPrivatelyExtractedArchiveApp<T>(
     inspectZipArchive(pinnedArchivePath);
     run(platformArchiveTool, ["-x", "-k", pinnedArchivePath, extractionRoot]);
     const rootEntries = readdirSync(extractionRoot);
-    if (rootEntries.length !== 1 || rootEntries[0] !== "Recordings.app") {
-      throw new Error("release archive must contain exactly one top-level Recordings.app");
+    if (rootEntries.length !== 1 || rootEntries[0] !== expectedBundleName) {
+      throw new Error(
+        `release archive must contain exactly one top-level ${expectedBundleName}`,
+      );
     }
-    const extractedAppPath = join(extractionRoot, "Recordings.app");
+    const extractedAppPath = join(extractionRoot, expectedBundleName);
     const appDetails = lstatSync(extractedAppPath);
     if (appDetails.isSymbolicLink() || !appDetails.isDirectory()) {
-      throw new Error("release archive top-level Recordings.app must be a regular directory");
+      throw new Error(
+        `release archive top-level ${expectedBundleName} must be a regular directory`,
+      );
     }
     assertRegularArchiveTree(extractedAppPath);
     return operation(extractedAppPath);
@@ -1343,6 +1504,7 @@ export function extractVerifiedArchiveToStaging(
   expectedApprovedTarget: string,
   expectedApprovedTargetIdentitySha256: string,
   expectedApprovedTargetIdentityKind: OperatorTargetIdentityKind,
+  expectedVariant: ArtifactVariant = "full",
   platformArchiveTool = "/usr/bin/ditto",
 ): void {
   if (resolve(stagingTarget) !== stagingTarget) {
@@ -1375,16 +1537,19 @@ export function extractVerifiedArchiveToStaging(
   withPrivatelyExtractedArchiveApp(
     archivePath,
     (appPath) => {
-      const targetAppPath = join(stagingTarget, "Recordings.app");
+      const targetAppPath = join(stagingTarget, manifestBundleName(manifest));
       renameSync(appPath, targetAppPath);
       assertRegularArchiveTree(targetAppPath);
       const entries = readdirSync(stagingTarget);
-      if (entries.length !== 1 || entries[0] !== "Recordings.app") {
-        throw new Error("archive extraction did not produce exactly Recordings.app in staging");
+      if (entries.length !== 1 || entries[0] !== manifestBundleName(manifest)) {
+        throw new Error(
+          `archive extraction did not produce exactly ${manifestBundleName(manifest)} in staging`,
+        );
       }
     },
     platformArchiveTool,
     manifest.archive.sha256,
+    manifestBundleName(manifest),
   );
 }
 
@@ -1412,6 +1577,20 @@ export function assertManifestShape(manifest: MacOSArtifactManifest): void {
   }
   if (manifest.artifact_type !== "recordings-macos-app") throw new Error("unexpected artifact type");
   if (manifest.bundle_id !== BUNDLE_ID) throw new Error("unexpected bundle identifier");
+  if (
+    manifest.bundle_name !== undefined &&
+    (typeof manifest.bundle_name !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9 .-]*\.app$/.test(manifest.bundle_name))
+  ) {
+    throw new Error("manifest bundle name must be a *.app bundle directory name");
+  }
+  if (
+    manifest.variant !== undefined &&
+    manifest.variant !== "full" &&
+    manifest.variant !== "bar"
+  ) {
+    throw new Error(`manifest variant is unsupported: ${manifest.variant}`);
+  }
   const artifactPolicy = manifestPolicy(manifest);
   for (const [label, value] of [
     ["bundle version", manifest.bundle_version],
@@ -1510,7 +1689,7 @@ export function assertManifestShape(manifest: MacOSArtifactManifest): void {
   } else {
     if (
       manifest.artifact_policy !== "local_only" ||
-      manifest.approved_target !== "station06" ||
+      !isLocalOnlyApprovedTarget(manifest.approved_target) ||
       (manifest.approved_target_identity_kind !== undefined &&
         manifest.approved_target_identity_kind !== "tailscale_node_id_sha256") ||
       (manifest.approved_target_identity_kind === undefined) !==
@@ -1523,20 +1702,38 @@ export function assertManifestShape(manifest: MacOSArtifactManifest): void {
       !isHex(manifest.builder_identity_sha256, 64) ||
       manifest.builder_identity_sha256 === manifest.approved_target_identity_sha256
     ) {
-      throw new Error("local-only schema v3 requires exact station06 name and machine identity");
+      throw new Error(
+        "local-only schema v3 requires an approved target name " +
+          `(${localOnlyApprovedTargetsMessage()}) and machine identity`,
+      );
     }
-    if (
-      manifest.non_notarized !== true ||
-      manifest.team_id !== "ADHOC" ||
-      manifest.signing.mode !== "ad_hoc" ||
-      manifest.signing.authority !== "adhoc" ||
-      manifest.signing.helper_authority !== "adhoc" ||
-      manifest.signing.team_id !== "ADHOC" ||
-      manifest.signing.helper_team_id !== "ADHOC" ||
-      manifest.signing.trusted_timestamp !== "none" ||
-      manifest.signing.helper_trusted_timestamp !== "none"
+    // A local-station manifest is internally consistent in exactly one of two shapes: fully
+    // ad-hoc, or fully Developer ID under one pinned team. Mixing them (e.g. a Developer ID
+    // app with an ad-hoc helper) would leave the bundle without one stable identity for TCC
+    // to key on, which is the failure this whole path exists to prevent.
+    if (manifest.non_notarized !== true || !isLocalOnlySigningTeam(manifest.team_id)) {
+      throw new Error("local-only manifest requires a non-notarized ADHOC or Developer ID team");
+    }
+    if (manifest.team_id === "ADHOC") {
+      if (
+        manifest.signing.mode !== "ad_hoc" ||
+        manifest.signing.authority !== "adhoc" ||
+        manifest.signing.helper_authority !== "adhoc" ||
+        manifest.signing.team_id !== "ADHOC" ||
+        manifest.signing.helper_team_id !== "ADHOC" ||
+        manifest.signing.trusted_timestamp !== "none" ||
+        manifest.signing.helper_trusted_timestamp !== "none"
+      ) {
+        throw new Error("local-only manifest requires consistent ad-hoc signing evidence");
+      }
+    } else if (
+      manifest.signing.mode !== "developer_id" ||
+      !manifest.signing.authority.startsWith("Developer ID Application:") ||
+      !manifest.signing.helper_authority.startsWith("Developer ID Application:") ||
+      manifest.signing.team_id !== manifest.team_id ||
+      manifest.signing.helper_team_id !== manifest.team_id
     ) {
-      throw new Error("local-only manifest requires consistent ad-hoc signing evidence");
+      throw new Error("local-only manifest requires consistent Developer ID signing evidence");
     }
     if (
       manifest.notarization.status !== "Not Submitted" ||
@@ -1602,6 +1799,7 @@ export function verifyArchiveManifest(
   expectedApprovedTarget: string = RELEASE_APPROVED_TARGET,
   expectedApprovedTargetIdentitySha256: string = "none",
   expectedApprovedTargetIdentityKind: OperatorTargetIdentityKind = LEGACY_LOCAL_TARGET_IDENTITY_KIND,
+  expectedVariant: ArtifactVariant = "full",
 ): MacOSArtifactManifest {
   if (!expectedTeamId) throw new Error("expected Team ID is required");
   const manifest = readAuthenticatedManifest<MacOSArtifactManifest>(
@@ -1612,6 +1810,11 @@ export function verifyArchiveManifest(
   if (manifestPolicy(manifest) !== expectedPolicy) {
     throw new Error("manifest artifact policy does not match the explicit operator selection");
   }
+  if (manifestVariant(manifest) !== expectedVariant) {
+    throw new Error(
+      `manifest variant ${manifestVariant(manifest)} does not match the explicit operator selection ${expectedVariant}`,
+    );
+  }
   const actualApprovedTarget = manifest.approved_target ?? RELEASE_APPROVED_TARGET;
   if (actualApprovedTarget !== expectedApprovedTarget) {
     throw new Error("manifest approved target does not match the exact operator-approved target");
@@ -1664,6 +1867,7 @@ function assertProvenanceMatchesManifest(
     "builder_identity_kind",
     "builder_identity_sha256",
     "non_notarized",
+    "variant",
     "bundle_id",
     "bundle_version",
     "git_sha",
@@ -1836,11 +2040,17 @@ export function verifyExtractedApp(
   expectedApprovedTarget: string = RELEASE_APPROVED_TARGET,
   expectedApprovedTargetIdentitySha256: string = "none",
   expectedApprovedTargetIdentityKind: OperatorTargetIdentityKind = LEGACY_LOCAL_TARGET_IDENTITY_KIND,
+  expectedVariant: ArtifactVariant = "full",
 ): MacOSArtifactManifest {
   const manifest = readAuthenticatedManifest<MacOSArtifactManifest>(
     manifestPath,
     expectedManifestSha256,
   );
+  if (manifestVariant(manifest) !== expectedVariant) {
+    throw new Error(
+      `manifest variant ${manifestVariant(manifest)} does not match the explicit operator selection ${expectedVariant}`,
+    );
+  }
   verifyAppAgainstManifest(
     appPath,
     manifest,
@@ -1910,6 +2120,7 @@ function verifySuppliedAndArchivedApps(
     },
     "/usr/bin/ditto",
     manifest.archive.sha256,
+    manifestBundleName(manifest),
   );
   if (sha256ArchiveFile(archivePath) !== manifest.archive.sha256) {
     throw new Error("release archive changed during exact-byte verification");
@@ -1927,6 +2138,7 @@ function writeProvenance(
   approvedTargetIdentitySha256: string,
   builderIdentityKind: OperatorTargetIdentityKind,
   builderIdentitySha256: string,
+  variant: ArtifactVariant,
 ): void {
   const executablePath = join(appPath, "Contents", "MacOS", "Recordings");
   const helperPath = join(appPath, "Contents", "Helpers", "recordings");
@@ -1936,6 +2148,7 @@ function writeProvenance(
       artifactPolicy === "release"
         ? RELEASE_ARTIFACT_SCHEMA_VERSION
         : LOCAL_ARTIFACT_SCHEMA_VERSION,
+    variant,
     bundle_id: plistValue(appPath, "CFBundleIdentifier"),
     bundle_version: plistValue(appPath, "CFBundleShortVersionString"),
     bundle_build_version: plistValue(appPath, "CFBundleVersion"),
@@ -1962,15 +2175,19 @@ function writeProvenance(
       throw new Error("release provenance has an invalid target or Team ID");
     }
   } else if (
-    expectedTeamId !== "ADHOC" ||
-    approvedTarget !== "station06" ||
+    // ADHOC or a pinned Developer ID team; localOnlySigningMode rejects anything else.
+    !isLocalOnlySigningTeam(expectedTeamId) ||
+    !isLocalOnlyApprovedTarget(approvedTarget) ||
     approvedTargetIdentityKind !== "tailscale_node_id_sha256" ||
     builderIdentityKind !== "tailscale_node_id_sha256" ||
     !isHex(approvedTargetIdentitySha256, 64) ||
     !isHex(builderIdentitySha256, 64) ||
     approvedTargetIdentitySha256 === builderIdentitySha256
   ) {
-    throw new Error("new local-only provenance requires ADHOC and a Tailscale node-bound station06 identity");
+    throw new Error(
+      "new local-only provenance requires ADHOC or a pinned Developer ID team and a Tailscale " +
+        `node-bound approved-target identity (${localOnlyApprovedTargetsMessage()})`,
+    );
   } else {
     provenance.artifact_policy = "local_only";
     provenance.approved_target = approvedTarget;
@@ -1994,6 +2211,7 @@ function finalizeArtifact(
   notaryLogPath: string,
   notarySubmissionId: string,
   submittedArchiveSha256: string,
+  expectedVariant: ArtifactVariant = "full",
 ): void {
   assertCurrentSourceRevision(packageRoot, expectedSourceSha);
   const executablePath = join(appPath, "Contents", "MacOS", "Recordings");
@@ -2003,6 +2221,14 @@ function finalizeArtifact(
   if (provenance.git_sha !== expectedSourceSha) {
     throw new Error("embedded provenance does not match the pinned source SHA");
   }
+  if (expectedVariant !== "full" && expectedVariant !== "bar") {
+    throw new Error(`finalize variant is unsupported: ${expectedVariant}`);
+  }
+  if ((provenance.variant ?? "full") !== expectedVariant) {
+    throw new Error(
+      `finalize variant ${expectedVariant} does not match the embedded provenance variant`,
+    );
+  }
   assertExpectedCodeLayout(appPath);
   const outerSigning = signingEvidence(appPath, expectedTeamId, APP_ENTITLEMENTS, executablePath);
   const helperSigning = signingEvidence(helperPath, expectedTeamId, HELPER_ENTITLEMENTS);
@@ -2015,9 +2241,14 @@ function finalizeArtifact(
   const notaryLog = JSON.parse(notaryLogSnapshot.toString("utf8")) as unknown;
   assertAcceptedNotaryLog(notaryLog, notarySubmissionId, submittedArchiveSha256);
   const items = nestedItems(appPath, expectedTeamId, "release", outerSigning, helperSigning);
+  const bundleName = basename(appPath);
+  if (!bundleName.endsWith(".app")) {
+    throw new Error(`release app bundle must be named *.app: ${appPath}`);
+  }
   const manifest: MacOSArtifactManifest = {
     ...provenance,
     artifact_type: "recordings-macos-app",
+    bundle_name: bundleName,
     app_sha256: sha256File(executablePath),
     binding: { bundle_tree_sha256: treeDigest(appPath) },
     provenance_sha256: sha256File(embeddedPath),
@@ -2044,7 +2275,7 @@ function finalizeArtifact(
     },
     container: {
       type: "zip",
-      install_locations: ["/Applications/Recordings.app"],
+      install_locations: [`/Applications/${bundleName}`],
     },
     nested_code_policy: {
       allowlist_sha256: nestedPolicyDigest(items),
@@ -2120,11 +2351,17 @@ function finalizeLocalArtifact(
   approvedTarget: string,
   approvedTargetIdentityKind: TargetIdentityKind,
   approvedTargetIdentitySha256: string,
+  expectedTeamId: string = "ADHOC",
+  expectedVariant: ArtifactVariant = "full",
 ): void {
   assertCurrentSourceRevision(packageRoot, expectedSourceSha);
   if (approvedTargetIdentityKind !== "tailscale_node_id_sha256") {
     throw new Error("new local-only artifacts require a Tailscale node ID identity hash");
   }
+  if (expectedVariant !== "full" && expectedVariant !== "bar") {
+    throw new Error(`finalize variant is unsupported: ${expectedVariant}`);
+  }
+  const localSigningMode = localOnlySigningMode(expectedTeamId);
   const executablePath = join(appPath, "Contents", "MacOS", "Recordings");
   const helperPath = join(appPath, "Contents", "Helpers", "recordings");
   const embeddedPath = provenancePath(appPath);
@@ -2137,34 +2374,44 @@ function finalizeLocalArtifact(
     provenance.approved_target_identity_sha256 !== approvedTargetIdentitySha256 ||
     provenance.builder_identity_kind !== "tailscale_node_id_sha256" ||
     provenance.non_notarized !== true ||
-    provenance.team_id !== "ADHOC"
+    provenance.team_id !== expectedTeamId
   ) {
     throw new Error("embedded provenance is not approved for this local-only target");
   }
+  if ((provenance.variant ?? "full") !== expectedVariant) {
+    throw new Error(
+      `finalize variant ${expectedVariant} does not match the embedded provenance variant`,
+    );
+  }
   assertExpectedCodeLayout(appPath);
   const outerSigning = signingEvidence(
     appPath,
-    "ADHOC",
+    expectedTeamId,
     APP_ENTITLEMENTS,
     executablePath,
     "local_only",
   );
   const helperSigning = signingEvidence(
     helperPath,
-    "ADHOC",
+    expectedTeamId,
     HELPER_ENTITLEMENTS,
     helperPath,
     "local_only",
   );
-  const items = nestedItems(appPath, "ADHOC", "local_only", outerSigning, helperSigning);
+  const items = nestedItems(appPath, expectedTeamId, "local_only", outerSigning, helperSigning);
+  const bundleName = basename(appPath);
+  if (!bundleName.endsWith(".app")) {
+    throw new Error(`local app bundle must be named *.app: ${appPath}`);
+  }
   const manifest: MacOSArtifactManifest = {
     ...provenance,
     artifact_type: "recordings-macos-app",
+    bundle_name: bundleName,
     app_sha256: sha256File(executablePath),
     binding: { bundle_tree_sha256: treeDigest(appPath) },
     provenance_sha256: sha256File(embeddedPath),
     signing: {
-      mode: "ad_hoc",
+      mode: localSigningMode,
       authority: outerSigning.authority,
       team_id: outerSigning.teamId,
       trusted_timestamp: outerSigning.timestamp,
@@ -2187,7 +2434,7 @@ function finalizeLocalArtifact(
     },
     container: {
       type: "zip",
-      install_locations: ["~/Applications/Recordings.app"],
+      install_locations: [`~/Applications/${bundleName}`],
     },
     nested_code_policy: {
       allowlist_sha256: nestedPolicyDigest(items),
@@ -2208,7 +2455,7 @@ function finalizeLocalArtifact(
     appPath,
     archivePath,
     manifest,
-    "ADHOC",
+    expectedTeamId,
     "local_only",
     approvedTarget,
     approvedTargetIdentitySha256,
@@ -2301,11 +2548,19 @@ function assertInstallTransition(
   assertVersionTransition(installedVersion, installedSource, manifest);
 }
 
-function requirementDigest(appPath: string, artifactPolicy: ArtifactPolicy): void {
+function requirementDigest(
+  appPath: string,
+  artifactPolicy: ArtifactPolicy,
+  expectedTeamId: string = "ADHOC",
+): void {
   if (artifactPolicy === "local_only") {
+    // The pinned team decides which local signing shape is verified. Hard-coding "ADHOC" here
+    // rejected every correctly Developer-ID-signed local-station bundle, and because
+    // install_macos_app.sh calls this for EVERY local install under `set -euo pipefail`, that
+    // rejection aborted the install outright — making a properly signed build uninstallable.
     const evidence = signingEvidence(
       appPath,
-      "ADHOC",
+      expectedTeamId,
       APP_ENTITLEMENTS,
       join(appPath, "Contents", "MacOS", "Recordings"),
       "local_only",
@@ -2349,6 +2604,7 @@ function verifyActiveApp(
   expectedApprovedTarget: string,
   expectedApprovedTargetIdentitySha256: string,
   expectedApprovedTargetIdentityKind: OperatorTargetIdentityKind,
+  expectedVariant: ArtifactVariant = "full",
 ): void {
   const manifest = verifyExtractedApp(
     appPath,
@@ -2359,6 +2615,7 @@ function verifyActiveApp(
     expectedApprovedTarget,
     expectedApprovedTargetIdentitySha256,
     expectedApprovedTargetIdentityKind,
+    expectedVariant,
   );
   const helperPath = join(appPath, "Contents", "Helpers", "recordings");
   if (companionVersion(helperPath) !== manifest.companion.version) {
@@ -2369,8 +2626,8 @@ function verifyActiveApp(
     const environment: NodeJS.ProcessEnv = {
       HOME: contractHome,
       PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
-      HASNA_RECORDINGS_STORAGE_MODE: "local",
-      RECORDINGS_STORAGE_MODE: "local",
+      HASNA_RECORDINGS_CLIENT_STORE: "sqlite",
+      RECORDINGS_CLIENT_STORE: "sqlite",
       HASNA_RECORDINGS_DB_PATH: join(contractHome, "recordings.db"),
       RECORDINGS_AUDIO_DIR: join(contractHome, "audio"),
     };
@@ -2702,7 +2959,7 @@ function readJournal(path: string): InstallJournal {
         journal.approved_target_identity_sha256 !== "none" ||
         journal.builder_identity_kind !== "none")) ||
     (journal.artifact_policy === "local_only" &&
-      (journal.approved_target !== "station06" ||
+      (!isLocalOnlyApprovedTarget(journal.approved_target) ||
         !isTargetIdentityKind(journal.approved_target_identity_kind) ||
         !isTargetIdentityKind(journal.builder_identity_kind) ||
         journal.approved_target_identity_kind !== journal.builder_identity_kind ||
@@ -5021,6 +5278,9 @@ function manifestGet(path: string, expectedManifestSha256: string, field: string
   }
   else if (field === "approved_target_identity_sha256") console.log(manifest.approved_target_identity_sha256);
   else if (field === "builder_identity_kind") console.log(manifestBuilderIdentityKind(manifest));
+  else if (field === "variant") console.log(manifestVariant(manifest));
+  // Pre-variant manifests carry no bundle_name; they are full builds by definition.
+  else if (field === "bundle_name") console.log(manifestBundleName(manifest));
   else throw new Error(`unsupported manifest field: ${field}`);
 }
 
@@ -5047,6 +5307,14 @@ function repeatedArguments(name: string): string[] {
   return values;
 }
 
+function variantArgument(defaultVariant: ArtifactVariant): ArtifactVariant {
+  const value = optionalArgument("--variant") ?? defaultVariant;
+  if (value !== "full" && value !== "bar") {
+    throw new Error(`artifact variant must be full or bar; got: ${value}`);
+  }
+  return value;
+}
+
 function artifactPolicyArgument(): ArtifactPolicy {
   const value = argument("--artifact-policy");
   if (value !== "release" && value !== "local_only") {
@@ -5109,6 +5377,7 @@ function main(): void {
       argument("--approved-target-identity-sha256"),
       builderIdentityKindArgument(policy),
       argument("--builder-identity-sha256"),
+      variantArgument("full"),
     );
   } else if (command === "finalize") {
     const sourceSha = argument("--source-sha");
@@ -5123,6 +5392,7 @@ function main(): void {
       argument("--notary-log"),
       argument("--notary-submission-id"),
       argument("--submitted-archive-sha256"),
+      variantArgument("full"),
     );
   } else if (command === "finalize-local") {
     const sourceSha = argument("--source-sha");
@@ -5135,6 +5405,8 @@ function main(): void {
       argument("--approved-target"),
       targetIdentityKindArgument(undefined, true),
       argument("--approved-target-identity-sha256"),
+      optionalArgument("--expected-team-id") ?? "ADHOC",
+      variantArgument("full"),
     );
   } else if (command === "verify-archive") {
     const teamId = argument("--team-id");
@@ -5150,6 +5422,7 @@ function main(): void {
       argument("--approved-target"),
       argument("--approved-target-identity-sha256"),
       targetIdentityKindArgument(policy),
+      variantArgument("full"),
     );
   } else if (command === "extract-verified-archive") {
     const teamId = argument("--team-id");
@@ -5166,6 +5439,7 @@ function main(): void {
       argument("--approved-target"),
       argument("--approved-target-identity-sha256"),
       targetIdentityKindArgument(policy),
+      variantArgument("full"),
     );
   } else if (command === "verify-app") {
     const teamId = argument("--team-id");
@@ -5179,6 +5453,7 @@ function main(): void {
       argument("--approved-target"),
       argument("--approved-target-identity-sha256"),
       targetIdentityKindArgument(policy),
+      variantArgument("full"),
     );
   } else if (command === "verify-active") {
     const teamId = argument("--team-id");
@@ -5192,6 +5467,7 @@ function main(): void {
       argument("--approved-target"),
       argument("--approved-target-identity-sha256"),
       targetIdentityKindArgument(policy),
+      variantArgument("full"),
     );
   } else if (command === "assert-release") {
     assertExpectedRelease(
@@ -5207,7 +5483,11 @@ function main(): void {
       argument("--manifest-sha256"),
     );
   } else if (command === "requirement-digest") {
-    requirementDigest(argument("--app"), artifactPolicyArgument());
+    requirementDigest(
+      argument("--app"),
+      artifactPolicyArgument(),
+      optionalArgument("--expected-team-id") ?? "ADHOC",
+    );
   } else if (command === "tailscale-node-id-sha256") {
     console.log(tailscaleNodeIdSha256(readFileSync(0, "utf8"), argument("--expected-hostname")));
   } else if (command === "verify-filesystem-tree") {