@hasna/recordings 0.2.10 → 0.2.11

package/README.md

@@ -11,6 +11,41 @@ Speech-to-text recording tool with MCP and CLI — records, transcribes, and opt
 npm install -g @hasna/recordings
 ```
 
+## macOS app, code signing & permissions
+
+On macOS the package builds a native `Recordings.app` (into
+`~/.hasna/recordings/Recordings.app`) during `postinstall` and requires
+Microphone and Accessibility grants. Those grants are bound by macOS (TCC) to
+the app's **code-signing designated requirement**, so signing has to stay stable
+across updates or macOS re-prompts on every install.
+
+- **Stable signing by default — no configuration needed.** If
+  `RECORDINGS_CODESIGN_IDENTITY` is set (e.g. a Developer ID or a station signing
+  certificate), it is used. Otherwise the build creates, once, a per-machine
+  self-signed code-signing certificate named **"Hasna Recordings Signing"** and
+  reuses it for every subsequent build. Because the same certificate is reused,
+  the designated requirement is certificate-based and constant across rebuilds,
+  so your Microphone/Accessibility grants survive updates. The build never falls
+  back to ad-hoc signing (which would change the requirement on every rebuild and
+  force re-authorization).
+- **Works headless (over SSH).** The signing identity lives in a **dedicated**
+  keychain (`~/.hasna/recordings/signing/recordings-signing.keychain-db`) whose
+  password is generated once and stored in the secrets vault
+  (`hasna/machine/<host>/recordings/signing/keychain_password`). The build
+  unlocks that keychain with the known password and runs
+  `security set-key-partition-list -S apple-tool:,apple:` so `codesign` gets
+  non-interactive key access with no prompt — it never depends on the login
+  keychain being unlocked. Requires the `secrets` vault CLI on the machine.
+- **Fails closed without entitlements.** If `RecordingsLib/Recordings.entitlements`
+  is missing the build aborts rather than shipping an unsigned/unentitled app.
+- **Rebuild only on real changes.** Reinstalling the same version does not
+  rebuild the app: the installer compares a hash of the native sources plus the
+  package version (recorded at `~/.hasna/recordings/.recordings-source-hash`) and
+  skips the rebuild when nothing changed, leaving the already-granted app
+  untouched. A genuine update rebuilds and re-signs with the same certificate, so
+  grants still survive. The installer never resets TCC permissions.
+- **Force a rebuild** with `RECORDINGS_FORCE_APP_REINSTALL=1 recordings app install`.
+
 ## CLI Usage
 
 ```bash

package/dist/cli/index.js

@@ -1518,7 +1518,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.11";
 
 // src/db/feedback.ts
 function saveFeedback(input) {

package/dist/index.js

@@ -777,7 +777,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.11";
 
 // src/db/feedback.ts
 function saveFeedback(input) {

package/dist/mcp/index.js

@@ -4651,7 +4651,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.11";
 
 // src/db/feedback.ts
 function saveFeedback(input) {

package/dist/server/index.js

@@ -18,7 +18,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.11";
 
 // src/db/remote-storage.ts
 import pg from "pg";

package/dist/storage.js

@@ -616,7 +616,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.11";
 
 // src/db/feedback.ts
 function saveFeedback(input) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.10";
+export declare const VERSION = "0.2.11";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/recordings",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "type": "module",
   "description": "Speech-to-text recording tool with MCP and CLI — records, transcribes, and optionally enhances text using AI",
   "repository": {

package/scripts/install_macos_app.sh

@@ -52,6 +52,67 @@ warn_or_fail() {
   exit 1
 }
 
+# Deterministic, source-freshness-based rebuild skip.
+#
+# We rebuild only when the app SOURCES or the package VERSION actually changed.
+# The decision is a hash of the native app source tree plus the package version
+# — NOT the app's signature. This is deliberate:
+#   * Identical reinstall (same source/version): keep the already-installed,
+#     already-granted app untouched, so macOS permission grants survive.
+#   * Genuine app update (source or version changed): rebuild and re-sign with
+#     the same stable per-machine certificate. Its certificate-based designated
+#     requirement is unchanged, so the grants survive the update too — no
+#     update-starvation and no force flag needed.
+STAMP_FILE="${DATA_DIR}/.recordings-source-hash"
+
+# Keep the ~/Applications launch point pointed at the current build and restart
+# a running instance. A second, stale copy in ~/Applications splits TCC
+# permissions and leaves users on an old build, so we refresh it from the
+# canonical app on EVERY path — including the skip-rebuild path, where the
+# canonical app is the already-installed APP_DEST.
+refresh_alt_copy_and_restart() {
+  local source_app="$1"
+  [ -d "$source_app" ] || return 0
+
+  local alt_copy="${HOME}/Applications/Recordings.app"
+  if [ -d "$alt_copy" ]; then
+    rm -rf "$alt_copy"
+    cp -R "$source_app" "$alt_copy" || true
+    echo "Updated stale copy at ${alt_copy} to the current app."
+  fi
+
+  # If an old instance is running, restart it on the current build.
+  if pgrep -x Recordings >/dev/null 2>&1; then
+    pkill -x Recordings || true
+    sleep 1
+    open "$APP_DEST" || true
+    echo "Restarted Recordings.app on the current build."
+  fi
+}
+
+compute_source_hash() {
+  command -v shasum >/dev/null 2>&1 || return 1
+  [ -d "$NATIVE_DIR" ] || return 1
+  {
+    # Version-aware: the package version line participates in the hash.
+    grep '"version"' "${PACKAGE_ROOT}/package.json" 2>/dev/null
+    # Source-aware: hash every native source file (relative paths, so the hash
+    # is independent of the install location), excluding build artifacts.
+    ( cd "$NATIVE_DIR" && find . -type f ! -path './.build/*' -exec shasum {} + 2>/dev/null | sort )
+  } | shasum | awk '{print $1}'
+}
+
+SOURCE_HASH="$(compute_source_hash)"
+
+if [ -d "$APP_DEST" ] && [ "${RECORDINGS_FORCE_APP_REINSTALL:-0}" != "1" ] && \
+   [ -n "$SOURCE_HASH" ] && [ -f "$STAMP_FILE" ] && \
+   [ "$(cat "$STAMP_FILE" 2>/dev/null)" = "$SOURCE_HASH" ]; then
+  echo "Recordings.app at ${APP_DEST} is already built from the current sources; skipping rebuild to preserve macOS permission grants."
+  echo "Set RECORDINGS_FORCE_APP_REINSTALL=1 to force a rebuild."
+  refresh_alt_copy_and_restart "$APP_DEST"
+  exit 0
+fi
+
 if ! command -v swift >/dev/null 2>&1; then
   warn_or_fail "Swift toolchain not found"
 fi
@@ -73,53 +134,16 @@ rm -rf "$APP_DEST"
 mkdir -p "$DATA_DIR"
 cp -R "$APP_SOURCE" "$APP_DEST" || warn_or_fail "failed to copy app bundle"
 
-current_cdhash() {
-  codesign -d --verbose=4 "$1" 2>&1 | awk -F= '/^CDHash=/ { print toupper($2); exit }'
-}
-
-tcc_csreq_hex() {
-  local db_path="$1"
-  local service="$2"
-  if [ ! -r "$db_path" ] || ! command -v sqlite3 >/dev/null 2>&1; then
-    return 0
-  fi
-  sqlite3 "$db_path" \
-    "SELECT hex(csreq) FROM access WHERE service = '${service}' AND client = 'com.hasna.recordings' ORDER BY last_modified DESC LIMIT 1;" \
-    2>/dev/null || true
-}
-
-reset_stale_permission() {
-  local service="$1"
-  local tcc_service="$2"
-  local db_path="$3"
-  local cdhash="$4"
-  local csreq_hex
-  csreq_hex="$(tcc_csreq_hex "$db_path" "$tcc_service" | tr '[:lower:]' '[:upper:]')"
-  if [ -n "$cdhash" ] && [ -n "$csreq_hex" ] && [[ "$csreq_hex" != *"$cdhash"* ]]; then
-    tccutil reset "$service" com.hasna.recordings >/dev/null 2>&1 || true
-    echo "Reset stale ${service} permission for the newly installed Recordings.app."
-  fi
-}
-
-APP_CDHASH="$(current_cdhash "$APP_DEST" || true)"
-reset_stale_permission "Microphone" "kTCCServiceMicrophone" "${HOME}/Library/Application Support/com.apple.TCC/TCC.db" "$APP_CDHASH"
-reset_stale_permission "Accessibility" "kTCCServiceAccessibility" "/Library/Application Support/com.apple.TCC/TCC.db" "$APP_CDHASH"
-
-# A second copy in ~/Applications splits TCC permissions and leaves users running
-# stale builds. Keep that launch point but always point it at the fresh build.
-ALT_COPY="${HOME}/Applications/Recordings.app"
-if [ -d "$ALT_COPY" ]; then
-  rm -rf "$ALT_COPY"
-  cp -R "$APP_SOURCE" "$ALT_COPY" || true
-  echo "Updated stale copy at ${ALT_COPY} to the freshly built app."
+# Record the source/version hash this build was produced from so an identical
+# future reinstall is skipped (see the rebuild-skip guard above).
+if [ -n "$SOURCE_HASH" ]; then
+  printf '%s\n' "$SOURCE_HASH" > "$STAMP_FILE"
 fi
 
-# If an old instance is running, restart it on the new build.
-if pgrep -x Recordings >/dev/null 2>&1; then
-  pkill -x Recordings || true
-  sleep 1
-  open "$APP_DEST" || true
-  echo "Restarted Recordings.app on the new build."
-fi
+# NOTE: this installer must never modify TCC permission state. Automatically
+# resetting "stale" grants deleted the user's Microphone/Accessibility
+# approvals on every update; users must always keep their existing decisions.
+
+refresh_alt_copy_and_restart "$APP_DEST"
 
 echo "Installed Recordings.app from package: ${APP_DEST}"

package/src/native/Recordings/build.sh

@@ -8,6 +8,200 @@ MODE="${1:-release}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 cd "$SCRIPT_DIR"
 
+# A STABLE certificate identity keeps the app's TCC designated requirement
+# constant across rebuilds so macOS permission grants (Microphone /
+# Accessibility) persist. Ad-hoc ("-") pins the identity to this exact binary's
+# CDHash and forces re-authorization after every build, so we NEVER default to
+# it. When no explicit identity is provided we create (once) and reuse a
+# per-machine self-signed code-signing certificate held in a DEDICATED signing
+# keychain, so the default postinstall path is self-contained AND works over a
+# headless SSH session — no out-of-band env and no unlocked login keychain
+# required.
+SIGNING_CN="Hasna Recordings Signing"
+SIGNING_DIR="${HOME}/.hasna/recordings/signing"
+# Dedicated code-signing keychain. We NEVER touch the login keychain: over SSH
+# the login keychain is locked and codesign would block on an interactive
+# unlock/allow prompt. A dedicated keychain with a KNOWN password (stored in the
+# vault) can be created, unlocked, and key-partition-listed non-interactively.
+SIGNING_KEYCHAIN="${SIGNING_DIR}/recordings-signing.keychain-db"
+
+# Resolve the macOS keychain/codesign tools by ABSOLUTE path when present, so a
+# same-named shim earlier on PATH (e.g. the Hasna `security` CLI installed in
+# ~/.bun/bin) cannot shadow the real /usr/bin/security. On hosts without those
+# absolute paths (e.g. the Linux unit-test sandbox) we fall back to PATH so the
+# tests can stub them.
+SECURITY="/usr/bin/security"; [ -x "$SECURITY" ] || SECURITY="security"
+CODESIGN="/usr/bin/codesign"; [ -x "$CODESIGN" ] || CODESIGN="codesign"
+# SHA-1 hash of the signing identity, resolved by ensure_local_signing_identity.
+SIGNING_IDENTITY=""
+
+# Vault keys are host-scoped so each machine owns its own signing material.
+signing_host() {
+    hostname -s 2>/dev/null || hostname 2>/dev/null || echo unknown
+}
+vault_prefix() {
+    printf 'hasna/machine/%s/recordings/signing' "$(signing_host)"
+}
+
+# Append the dedicated keychain to the USER search list (never replacing it) so
+# codesign / find-identity can see the identity while leaving login and other
+# keychains intact.
+add_signing_keychain_to_search_list() {
+    local target="$SIGNING_KEYCHAIN"
+    local -a current=()
+    local line trimmed
+    while IFS= read -r line; do
+        # `security list-keychains` prints each path indented and quoted.
+        trimmed="${line#"${line%%[![:space:]]*}"}"   # strip leading whitespace
+        trimmed="${trimmed%\"}"; trimmed="${trimmed#\"}"
+        [ -n "$trimmed" ] || continue
+        [ "$trimmed" = "$target" ] && return 0        # already in the list
+        current+=("$trimmed")
+    done < <("$SECURITY" list-keychains -d user 2>/dev/null)
+    "$SECURITY" list-keychains -d user -s "$target" ${current[@]+"${current[@]}"} >/dev/null 2>&1 \
+        || echo "WARN: could not add $target to the keychain search list" >&2
+}
+
+# Create/reuse the "Hasna Recordings Signing" identity inside the DEDICATED
+# signing keychain, unlocking it non-interactively with the known vault-stored
+# password so codesign can sign over SSH without any prompt. Reusing the same
+# certificate is what makes the designated requirement (certificate-based)
+# stable across rebuilds so TCC grants survive. Returns 0 when usable.
+ensure_local_signing_identity() {
+    command -v "$SECURITY" >/dev/null 2>&1 || { echo "ERROR: 'security' not found" >&2; return 1; }
+    command -v openssl  >/dev/null 2>&1 || { echo "ERROR: 'openssl' not found" >&2; return 1; }
+    # The dedicated keychain's password lives in the vault; without the vault CLI
+    # we cannot manage it non-interactively, so fail closed rather than fall back
+    # to the (headless-hostile) login keychain.
+    command -v secrets  >/dev/null 2>&1 || { echo "ERROR: 'secrets' vault CLI not found; cannot manage the dedicated signing keychain password" >&2; return 1; }
+
+    local prefix pw_key cert_key key_key
+    prefix="$(vault_prefix)"
+    pw_key="${prefix}/keychain_password"
+    cert_key="${prefix}/certificate_pem_b64"
+    key_key="${prefix}/private_key_pem_b64"
+
+    mkdir -p "$SIGNING_DIR" && chmod 700 "$SIGNING_DIR" 2>/dev/null || true
+
+    # 1. Known keychain password: generate once, persist in the vault, reuse.
+    local kc_pw
+    kc_pw="$(secrets get "$pw_key" 2>/dev/null || true)"
+    if [ -z "$kc_pw" ]; then
+        kc_pw="$(openssl rand -base64 24 | tr -d '\n')"
+        if ! secrets set "$pw_key" "$kc_pw" --type password \
+                --label "Recordings signing keychain password ($(signing_host))" >/dev/null 2>&1; then
+            echo "ERROR: failed to store signing keychain password in the vault ($pw_key)" >&2
+            return 1
+        fi
+        echo "Generated dedicated signing keychain password (stored in vault: $pw_key)."
+    fi
+
+    # 2. Create the dedicated keychain if missing; ALWAYS unlock it with the
+    #    known password. Disable auto-lock so the key stays reachable headless.
+    if [ ! -f "$SIGNING_KEYCHAIN" ]; then
+        echo "Creating dedicated code-signing keychain: $SIGNING_KEYCHAIN"
+        if ! "$SECURITY" create-keychain -p "$kc_pw" "$SIGNING_KEYCHAIN" >/dev/null 2>&1; then
+            echo "ERROR: failed to create dedicated signing keychain" >&2; return 1
+        fi
+    fi
+    if ! "$SECURITY" unlock-keychain -p "$kc_pw" "$SIGNING_KEYCHAIN" >/dev/null 2>&1; then
+        echo "ERROR: failed to unlock dedicated signing keychain (stale vault password?)" >&2; return 1
+    fi
+    # No timeout / no lock-on-sleep: keep it usable across a headless build.
+    "$SECURITY" set-keychain-settings "$SIGNING_KEYCHAIN" >/dev/null 2>&1 || true
+
+    # 3. Make the dedicated keychain discoverable to codesign/find-identity.
+    add_signing_keychain_to_search_list
+
+    # 4. Reuse the identity if it is already present in the dedicated keychain.
+    #    NOTE: no -v (valid-only) filter. A self-signed identity is untrusted
+    #    (CSSMERR_TP_NOT_TRUSTED) — and marking it trusted needs GUI auth that is
+    #    unavailable over SSH — so it is invisible to `find-identity -v`. codesign
+    #    can nonetheless sign with it, so we locate it by its SHA-1 HASH (which is
+    #    also what we pass to `codesign --sign`, decoupling signing from the
+    #    certificate's common name).
+    SIGNING_IDENTITY="$("$SECURITY" find-identity -p codesigning "$SIGNING_KEYCHAIN" 2>/dev/null | grep -oE '[0-9A-F]{40}' | head -1)"
+    if [ -n "$SIGNING_IDENTITY" ]; then
+        # Re-assert non-interactive key access with the KNOWN password.
+        "$SECURITY" set-key-partition-list -S apple-tool:,apple: -k "$kc_pw" "$SIGNING_KEYCHAIN" >/dev/null 2>&1 || true
+        return 0
+    fi
+
+    # 5. Materialize cert+key: reuse the vault copy if present (keeps the DR — and
+    #    the TCC grants bound to it — stable even if the keychain is recreated),
+    #    otherwise mint a new self-signed identity and persist it to the vault.
+    local work key crt p12 vault_cert_b64 vault_key_b64
+    work="$(mktemp -d)" || return 1
+    key="$work/key.pem"; crt="$work/cert.pem"; p12="$work/identity.p12"
+
+    vault_cert_b64="$(secrets get "$cert_key" 2>/dev/null || true)"
+    vault_key_b64="$(secrets get "$key_key" 2>/dev/null || true)"
+    if [ -n "$vault_cert_b64" ] && [ -n "$vault_key_b64" ]; then
+        printf '%s' "$vault_cert_b64" | openssl base64 -d -A > "$crt" 2>/dev/null || true
+        printf '%s' "$vault_key_b64"  | openssl base64 -d -A > "$key" 2>/dev/null || true
+        [ -s "$crt" ] && [ -s "$key" ] && echo "Reusing signing certificate from vault ($cert_key)."
+    fi
+    if [ ! -s "$crt" ] || [ ! -s "$key" ]; then
+        echo "Minting new self-signed code-signing certificate \"$SIGNING_CN\" (one-time)..."
+        cat > "$work/req.cnf" <<EOF
+[ req ]
+distinguished_name = dn
+x509_extensions    = ext
+prompt             = no
+[ dn ]
+CN = $SIGNING_CN
+[ ext ]
+basicConstraints   = critical,CA:false
+keyUsage           = critical,digitalSignature
+extendedKeyUsage   = critical,codeSigning
+EOF
+        if ! openssl req -x509 -newkey rsa:2048 -nodes -keyout "$key" -out "$crt" \
+                -days 3650 -config "$work/req.cnf" >/dev/null 2>&1; then
+            rm -rf "$work"; echo "ERROR: failed to generate self-signed signing certificate" >&2; return 1
+        fi
+        # Persist so future rebuilds — even after keychain re-creation or machine
+        # re-provisioning — reuse the SAME identity and keep the DR stable.
+        secrets set "$cert_key" "$(openssl base64 -A -in "$crt")" --type certificate \
+            --label "Recordings signing cert ($(signing_host))" >/dev/null 2>&1 \
+            || echo "WARN: could not persist signing certificate to vault ($cert_key)" >&2
+        secrets set "$key_key" "$(openssl base64 -A -in "$key")" --type private_key \
+            --label "Recordings signing key ($(signing_host))" >/dev/null 2>&1 \
+            || echo "WARN: could not persist signing key to vault ($key_key)" >&2
+    fi
+
+    # Package as PKCS#12 for `security import`. macOS's Security framework cannot
+    # read the PBKDF2/AES encoding OpenSSL 3 emits by default, so prefer -legacy
+    # (RC2/3DES + SHA1 MAC) and fall back for OpenSSL builds without it. Use a
+    # non-empty transport passphrase (the keychain password): an empty p12
+    # password trips "MAC verification failed" on macOS import.
+    if ! openssl pkcs12 -export -legacy -inkey "$key" -in "$crt" -name "$SIGNING_CN" \
+            -out "$p12" -passout pass:"$kc_pw" >/dev/null 2>&1; then
+        if ! openssl pkcs12 -export -inkey "$key" -in "$crt" -name "$SIGNING_CN" \
+                -out "$p12" -passout pass:"$kc_pw" >/dev/null 2>&1; then
+            rm -rf "$work"; echo "ERROR: failed to package signing identity as PKCS#12" >&2; return 1
+        fi
+    fi
+    # Import into the DEDICATED keychain (never the login keychain), allowlisting
+    # codesign so it may use the private key.
+    if ! "$SECURITY" import "$p12" -k "$SIGNING_KEYCHAIN" -P "$kc_pw" -T /usr/bin/codesign >/dev/null 2>&1; then
+        rm -rf "$work"; echo "ERROR: failed to import signing identity into $SIGNING_KEYCHAIN" >&2; return 1
+    fi
+    # Trust the self-signed root for code signing so `codesign --verify` passes.
+    "$SECURITY" add-trusted-cert -r trustRoot -p codeSign -k "$SIGNING_KEYCHAIN" "$crt" >/dev/null 2>&1 || true
+    # THE headless fix: grant codesign non-interactive access to the imported key
+    # using the KNOWN keychain password (never an empty password, never the login
+    # keychain), so signing works over SSH with no interactive allow prompt.
+    if ! "$SECURITY" set-key-partition-list -S apple-tool:,apple: -k "$kc_pw" "$SIGNING_KEYCHAIN" >/dev/null 2>&1; then
+        echo "WARN: set-key-partition-list did not complete; codesign may prompt for key access" >&2
+    fi
+    rm -rf "$work"
+
+    # Locate the freshly imported identity by hash (again, no -v: it is an
+    # untrusted self-signed cert). codesign signs by this hash.
+    SIGNING_IDENTITY="$("$SECURITY" find-identity -p codesigning "$SIGNING_KEYCHAIN" 2>/dev/null | grep -oE '[0-9A-F]{40}' | head -1)"
+    [ -n "$SIGNING_IDENTITY" ]
+}
+
 echo "Building Recordings.app ($MODE)..."
 swift build -c "$MODE" --product App
 
@@ -34,9 +228,39 @@ for bundle in "$BUILD_DIR"/*.resources "$BUILD_DIR"/*.bundle .build/*/"$MODE"/*.
     ditto "$bundle" "$RESOURCES/$(basename "$bundle")"
 done
 
-# Copy entitlements (for codesigning)
-if [ -f RecordingsLib/Recordings.entitlements ]; then
-    codesign --force --sign - --entitlements RecordingsLib/Recordings.entitlements "$APP_DIR" 2>/dev/null || true
+# FAIL CLOSED on missing entitlements. Without the entitlements file the app
+# would be signed with no Microphone/Accessibility entitlements (or skipped and
+# left effectively unsigned) — a silent, safety-critical regression. Refuse to
+# build instead.
+if [ ! -f RecordingsLib/Recordings.entitlements ]; then
+    echo "ERROR: RecordingsLib/Recordings.entitlements is missing." >&2
+    echo "Refusing to build: the app must be signed with its entitlements;" >&2
+    echo "skipping signing would ship an unsigned/unentitled Recordings.app." >&2
+    exit 1
+fi
+
+# Sign with entitlements using a STABLE identity. A signing failure must fail
+# the build: silently falling back to ad-hoc would reintroduce identity churn
+# and invalidate existing TCC grants.
+#
+# Precedence:
+#   1. RECORDINGS_CODESIGN_IDENTITY — explicit identity (Developer ID, station
+#      signing cert, or "-" for an intentional ad-hoc build). An explicit
+#      identity that fails to sign fails the build.
+#   2. The per-machine "Hasna Recordings Signing" self-signed certificate in the
+#      DEDICATED signing keychain, created once and reused, so the default build
+#      is stably signed non-interactively (works over SSH) with no out-of-band
+#      configuration. We never fall back to ad-hoc by default.
+if [ -n "${RECORDINGS_CODESIGN_IDENTITY:-}" ]; then
+    "$CODESIGN" --force --sign "$RECORDINGS_CODESIGN_IDENTITY" --entitlements RecordingsLib/Recordings.entitlements "$APP_DIR"
+elif ensure_local_signing_identity; then
+    "$CODESIGN" --force --keychain "$SIGNING_KEYCHAIN" --sign "$SIGNING_IDENTITY" --entitlements RecordingsLib/Recordings.entitlements "$APP_DIR"
+else
+    echo "ERROR: no stable code-signing identity is available and refusing to" >&2
+    echo "ad-hoc sign: ad-hoc signatures change the app's designated requirement" >&2
+    echo "on every build and break macOS Microphone/Accessibility grants." >&2
+    echo "Set RECORDINGS_CODESIGN_IDENTITY to a valid signing identity and retry." >&2
+    exit 1
 fi
 
 echo "✓ Built $APP_DIR"