feat(external-sources): auto-pin SHA-256 on external install (TOFU) (#95)

Records the observed SHA-256 of every externally-installed artifact in the
app's source binding on first successful install, and enforces it on any
later download of the same app+version from the same source. A rewritten
GitHub/Codeberg release (including a co-published, rewritten .sha256
sibling) now fails the install closed instead of being silently absorbed.

- SourceBinding gains a capped (200-entry, oldest-evicted) sha256 map with
  typed accessors, round-tripping through toArray()/fromArray()
- ExternalReleaseInstallerService enforces the recorded digest before
  extraction/backup (no filesystem change on mismatch), records on success
  only, and supports a single-request acceptNewSha override that is
  warning-logged and folded into the existing install audit entry
- SourceBindingStore preserves recorded digests on a same-source rebind and
  discards them on a different-source rebind (single write path for both
  the bind endpoint and the implicit install-time bind)
- API: binding read + version list expose recorded digests; install
  responses carry a sha_mismatch machine-readable code (422) with expected/
  actual digests, and a recordedShaMatched flag on success
- Frontend: version picker badges versions with a recorded digest; a new
  ShaMismatchDialog offers the explicit "Accept new checksum and install"
  escape hatch through the normal password-confirmed install flow

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>

Author: rubenvdlinde

appinfo/info.xml

@@ -7,7 +7,7 @@
 	<description>> ⚠️ **Active development — not for production use yet.** This app is under active development. Although it may carry a stable release status, **please do not use it in production environments before 12 June 2026.** See [conduction.nl/apps](https://conduction.nl/apps) for release planning and what this app does.
 
 App Versions gives Nextcloud administrators the ability to roll back apps to previous versions or install specific newer versions. Essential for debugging, testing compatibility, and recovering from broken updates.</description>
-	<version>1.2.0</version>
+	<version>1.3.0</version>
 	<licence>EUPL-1.2</licence>
 	<author mail="info@conduction.nl" homepage="https://conduction.nl">Conduction B.V.</author>
 	<namespace>AppVersions</namespace>

l10n/nl.json

@@ -18,7 +18,15 @@
         "{appId} is pinned to {pinnedVersion} but is now running {observedVersion} — something other than App Versions changed it.": "{appId} is vastgezet op {pinnedVersion}, maar draait nu {observedVersion} — iets anders dan App Versions heeft dit gewijzigd.",
         "Re-pin {version}": "Opnieuw vastzetten op {version}",
         "Accept: move pin to {version}": "Accepteren: vastzetting verplaatsen naar {version}",
-        "Accept: remove pin": "Accepteren: vastzetting verwijderen"
+        "Accept: remove pin": "Accepteren: vastzetting verwijderen",
+        "Checksum does not match first install": "Checksum komt niet overeen met de eerste installatie",
+        "Accept new checksum and install": "Nieuwe checksum accepteren en installeren",
+        "{appId} {version} was previously installed with a different SHA-256 checksum. The upstream release may have been rewritten since — App Versions blocks the install to protect you from a silently altered artifact.": "{appId} {version} is eerder geïnstalleerd met een andere SHA-256-checksum. De release bij de bron is mogelijk sindsdien herschreven — App Versions blokkeert de installatie om je te beschermen tegen een stilzwijgend gewijzigd bestand.",
+        "Recorded at first install": "Vastgelegd bij eerste installatie",
+        "Just downloaded": "Zojuist gedownload",
+        "Only accept if you are certain this change is legitimate — for example the maintainer re-tagged the release to fix a packaging error.": "Accepteer dit alleen als je zeker weet dat deze wijziging legitiem is — bijvoorbeeld wanneer de maintainer de release opnieuw heeft getagd om een verpakkingsfout te herstellen.",
+        "Matches first-install checksum": "Komt overeen met checksum van eerste installatie",
+        "Checksum recorded": "Checksum vastgelegd"
     },
     "pluralForm": "nplurals=2; plural=(n != 1);"
 }

lib/Controller/ApiController.php

@@ -141,7 +141,9 @@ public function sources(): DataResponse {
 	}
 
 	/**
-	 * Returns the active source binding for an app; see "Source binding".
+	 * Returns the active source binding for an app, including any recorded
+	 * SHA-256 digests (not secrets); see "Source binding" and "Recorded
+	 * digests are binding-scoped and surfaced".
 	 *
 	 * @spec openspec/specs/external-sources/spec.md
 	 */
@@ -200,10 +202,16 @@ public function bindSource(string $appId): DataResponse {
 			return new DataResponse(['message' => $error->getMessage()], Http::STATUS_FORBIDDEN);
 		}
 
+		// Re-read the persisted binding: rebinding to the same source id
+		// preserves any previously recorded SHA-256 digests, so the response
+		// should reflect what was actually written, not the pre-write value —
+		// see "Recorded digests are binding-scoped and surfaced".
+		$persisted = $this->installerService->getBinding($appId);
+
 		return new DataResponse([
 			'appId' => $appId,
 			'sourceId' => $binding->getId(),
-			'binding' => $binding->toArray(),
+			'binding' => ($persisted ?? $binding)->toArray(),
 		]);
 	}
 
@@ -293,10 +301,14 @@ public function appVersions(string $appId): DataResponse {
 	/**
 	 * Installs a specific version (password-confirmed); see "Install Specific
 	 * Version" and, when the app is pinned, "Pins are enforced on App
-	 * Versions' own install path" (`overridePin=repin|unpin`, `pin=1`).
+	 * Versions' own install path" (`overridePin=repin|unpin`, `pin=1`). For an
+	 * external source with a recorded SHA-256 mismatch, `acceptNewSha=1`
+	 * bypasses the check once and replaces the recorded digest on success; see
+	 * "Recorded SHA-256 enforced on reinstall".
 	 *
 	 * @spec openspec/specs/version-management/spec.md
 	 * @spec openspec/specs/version-pinning/spec.md
+	 * @spec openspec/specs/external-sources/spec.md
 	 */
 	#[PasswordConfirmationRequired(strict: false)]
 	#[ApiRoute(verb: 'POST', url: '/api/app/{appId}/versions/{version}/install')]
@@ -322,6 +334,7 @@ public function installVersion(string $appId, string $version): DataResponse {
 		$overridePinRaw = $this->stringParam('overridePin', '');
 		$overridePin = $overridePinRaw === '' ? null : $overridePinRaw;
 		$pinRequested = $this->readBinaryBool($this->request->getParam('pin', '0'), false);
+		$acceptNewSha = $this->readBinaryBool($this->request->getParam('acceptNewSha', '0'), false);
 
 		$result = $this->installerService->installAppVersion(
 			$appId,
@@ -330,6 +343,7 @@ public function installVersion(string $appId, string $version): DataResponse {
 			$sourceOverride,
 			$overridePin,
 			$pinRequested,
+			$acceptNewSha,
 		);
 		$result['payload']['requestedVersion'] = $requestedVersion;
 		$result['payload']['routeVersion'] = $version;

lib/Service/ExternalReleaseInstallerService.php

@@ -20,6 +20,7 @@
 use OCA\AppVersions\Service\Installer\FailureClassifier;
 use OCA\AppVersions\Service\Installer\InstallFailure;
 use OCA\AppVersions\Service\Installer\InstallFinalizer;
+use OCA\AppVersions\Service\Installer\ShaMismatchException;
 use OCA\AppVersions\Service\Pat\PatManager;
 use OCA\AppVersions\Service\Pat\PatResolver;
 use OCA\AppVersions\Service\Source\SourceBinding;
@@ -42,9 +43,14 @@
  * Nextcloud-issued code-signing certificate to verify and no per-release
  * signature to check. To compensate we apply:
  *   1. Trusted-source allowlist gate (no download until passed)
- *   2. Optional SHA-256 verification when the release publishes a sibling .sha256 asset
- *   3. Mandatory appId match against the extracted `appinfo/info.xml`
- *   4. Mandatory version match against the extracted `appinfo/info.xml`
+ *   2. Trust-on-first-use: the downloaded archive's SHA-256 MUST match the
+ *      digest recorded on the binding from a previous successful install of
+ *      the same (appId, version, source), if one is recorded — before
+ *      extraction/backup, `acceptNewSha` bypasses once and replaces on
+ *      success; see "Recorded SHA-256 enforced on reinstall"
+ *   3. Optional SHA-256 verification when the release publishes a sibling .sha256 asset
+ *   4. Mandatory appId match against the extracted `appinfo/info.xml`
+ *   5. Mandatory version match against the extracted `appinfo/info.xml`
  *
  * The post-extract finalization (migrations, repair steps, config writes) is
  * delegated to `InstallFinalizer` so signed and external installs cannot drift
@@ -80,20 +86,27 @@ public function getDebugLog(): array {
 	}
 
 	/**
-	 * Downloads, integrity-checks (allowlist, SHA-256, appId/version), and installs an external release;
-	 * see "External install integrity checks".
+	 * Downloads, integrity-checks (allowlist, recorded SHA-256, sibling SHA-256,
+	 * appId/version), and installs an external release; see "External install
+	 * integrity checks", "SHA-256 recorded on first successful external
+	 * install", and "Recorded SHA-256 enforced on reinstall".
 	 *
 	 * @spec openspec/specs/external-sources/spec.md
 	 * @param array<string, mixed> $release
-	 * @return array{status: string, installedVersionBefore: ?string, installedApp?: string, integrityWarning?: ?string, dryRun: bool, debug: list<array{stage: string, data: mixed}>}
+	 * @param bool $acceptNewSha Single-request bypass of the recorded-SHA-256
+	 *                           check; on success the recorded digest is replaced (password-confirmed
+	 *                           at the API layer, warning-logged and audited here).
+	 * @return array{status: string, installedVersionBefore: ?string, installedApp?: string, integrityWarning?: ?string, dryRun: bool, debug: list<array{stage: string, data: mixed}>, binding: SourceBinding, recordedShaMatched: bool}
 	 * @throws Exception
+	 * @throws ShaMismatchException
 	 */
 	public function installFromExternalRelease(
 		string $appId,
 		string $version,
 		array $release,
 		SourceBinding $binding,
 		bool $dryRun = false,
+		bool $acceptNewSha = false,
 	): array {
 		$this->resetDebug();
 		$this->addDebug('requested-install', [
@@ -142,7 +155,34 @@ public function installFromExternalRelease(
 			}
 			$this->addDebug('downloaded', ['tempFile' => $tempFile, 'sourceUrl' => $downloadUrl]);
 
-			$integrityWarning = $this->verifyChecksum($tempFile, $shaUrl, $authResolution);
+			// Hash the downloaded archive exactly once; both the recorded-digest
+			// (TOFU) check below and the sibling `.sha256` verification reuse
+			// this value — see design.md "Enforcement point".
+			$actualSha = hash_file('sha256', $tempFile);
+			if ($actualSha === false) {
+				throw new Exception('Could not compute SHA-256 of downloaded archive.');
+			}
+			$actualSha = strtolower($actualSha);
+
+			// Trust-on-first-use enforcement: a digest recorded from a previous
+			// successful install of this (appId, version, source) outranks
+			// whatever the source serves now, including a co-published,
+			// possibly-rewritten `.sha256` sibling — see "Recorded SHA-256
+			// enforced on reinstall". Checked before extraction/backup: no
+			// filesystem change happens on mismatch.
+			$recordedSha = $binding->getRecordedSha($version);
+			$recordedShaMatched = $recordedSha !== null && hash_equals($recordedSha, $actualSha);
+			if ($recordedSha !== null && !$acceptNewSha && !$recordedShaMatched) {
+				throw new ShaMismatchException($appId, $version, $recordedSha, $actualSha);
+			}
+			$this->addDebug('recorded-sha-check', [
+				'recordedSha' => $recordedSha,
+				'actualSha' => $actualSha,
+				'matched' => $recordedShaMatched,
+				'acceptNewSha' => $acceptNewSha,
+			]);
+
+			$integrityWarning = $this->verifyChecksum($actualSha, $shaUrl, $authResolution);
 			$this->addDebug('checksum', ['shaUrl' => $shaUrl, 'integrityWarning' => $integrityWarning]);
 
 			$archivePath = $this->extractArchive($tempFile, $tempFolder);
@@ -175,6 +215,8 @@ public function installFromExternalRelease(
 					'integrityWarning' => $integrityWarning,
 					'dryRun' => true,
 					'debug' => $this->debug,
+					'binding' => $binding,
+					'recordedShaMatched' => $recordedShaMatched,
 				];
 			}
 
@@ -234,7 +276,32 @@ public function installFromExternalRelease(
 			}
 			$this->addDebug('finalized', ['appId' => $installedApp, 'enabled' => $enabled]);
 
-			$this->recordInstallAudit($appId, $binding, $installedVersion, $version, AuditLogger::STATUS_SUCCESS, $integrityWarning);
+			// Record the observed digest only now that the install fully
+			// succeeded (never on a failure path) — see "SHA-256 recorded on
+			// first successful external install". Sibling-verified or locally
+			// computed, the value is the same: verifyChecksum() above already
+			// threw if a sibling digest existed and disagreed with $actualSha.
+			$updatedBinding = $binding->withRecordedSha($version, $actualSha);
+			$shaAccepted = $recordedSha !== null && !$recordedShaMatched;
+			$auditMessage = $integrityWarning;
+			if ($shaAccepted) {
+				$this->logger->warning('ExternalReleaseInstallerService: accepted a new SHA-256 for a previously recorded version (acceptNewSha override)', [
+					'appId' => $appId,
+					'version' => $version,
+					'previousSha' => $recordedSha,
+					'newSha' => $actualSha,
+				]);
+				$shaAcceptNote = sprintf(
+					'SHA-256 override accepted for %s@%s: previous %s, new %s.',
+					$appId,
+					$version,
+					$recordedSha,
+					$actualSha,
+				);
+				$auditMessage = $auditMessage !== null ? $auditMessage . ' ' . $shaAcceptNote : $shaAcceptNote;
+			}
+
+			$this->recordInstallAudit($appId, $binding, $installedVersion, $version, AuditLogger::STATUS_SUCCESS, $auditMessage);
 
 			return [
 				'status' => 'installed',
@@ -243,6 +310,8 @@ public function installFromExternalRelease(
 				'integrityWarning' => $integrityWarning,
 				'dryRun' => false,
 				'debug' => $this->debug,
+				'binding' => $updatedBinding,
+				'recordedShaMatched' => $recordedShaMatched,
 			];
 		} catch (\Throwable $error) {
 			// Best-effort audit write on the failure path, before the exception
@@ -322,7 +391,13 @@ private function authenticatedDownload(string $url, string $sinkPath, ?\OCA\AppV
 		});
 	}
 
-	private function verifyChecksum(string $tempFile, ?string $shaUrl, ?\OCA\AppVersions\Db\Pat $pat): ?string {
+	/**
+	 * Verifies the already-computed `$actualSha` (downloaded archive) against
+	 * the release's sibling `.sha256` asset when one exists. This is a
+	 * transport check only — see design.md "Trust model: TOFU" for why the
+	 * recorded-digest check (above, in the caller) takes precedence.
+	 */
+	private function verifyChecksum(string $actualSha, ?string $shaUrl, ?\OCA\AppVersions\Db\Pat $pat): ?string {
 		if ($shaUrl === null) {
 			return 'No SHA-256 checksum available for this artifact.';
 		}
@@ -364,16 +439,11 @@ private function verifyChecksum(string $tempFile, ?string $shaUrl, ?\OCA\AppVers
 			return 'SHA-256 file format unrecognized; install proceeded without verification.';
 		}
 
-		$actual = hash_file('sha256', $tempFile);
-		if ($actual === false) {
-			return 'Could not compute SHA-256 of downloaded archive.';
-		}
-
-		if (!hash_equals(strtolower($expected), strtolower($actual))) {
+		if (!hash_equals(strtolower($expected), $actualSha)) {
 			throw new Exception(sprintf(
 				'SHA-256 mismatch — expected %s, got %s.',
 				strtolower($expected),
-				strtolower($actual)
+				$actualSha
 			));
 		}
 

lib/Service/Installer/FailureClassifier.php

@@ -34,6 +34,13 @@ class FailureClassifier {
 	public const CATEGORY_PREFLIGHT_PERMISSION = 'preflight_permission';
 	public const CATEGORY_DOWNLOAD = 'download';
 	public const CATEGORY_CHECKSUM_MISMATCH = 'checksum_mismatch';
+	/**
+	 * A recorded (trust-on-first-use) SHA-256 mismatch — distinct from
+	 * {@see CATEGORY_CHECKSUM_MISMATCH} (the source-published sibling
+	 * checksum): this is a history check the source cannot rewrite. See
+	 * "Recorded SHA-256 enforced on reinstall".
+	 */
+	public const CATEGORY_SHA_MISMATCH = 'sha_mismatch';
 	public const CATEGORY_EXTRACT = 'extract';
 	public const CATEGORY_APPID_MISMATCH = 'appid_mismatch';
 	public const CATEGORY_VERSION_MISMATCH = 'version_mismatch';
@@ -88,7 +95,8 @@ public function httpStatusFor(string $category): int {
 			self::CATEGORY_INCOMPATIBLE,
 			self::CATEGORY_VERSION_MISMATCH,
 			self::CATEGORY_APPID_MISMATCH,
-			self::CATEGORY_CHECKSUM_MISMATCH => Http::STATUS_UNPROCESSABLE_ENTITY,
+			self::CATEGORY_CHECKSUM_MISMATCH,
+			self::CATEGORY_SHA_MISMATCH => Http::STATUS_UNPROCESSABLE_ENTITY,
 			self::CATEGORY_DOWNLOAD => Http::STATUS_BAD_GATEWAY,
 			default => Http::STATUS_INTERNAL_SERVER_ERROR,
 		};
@@ -152,6 +160,7 @@ public function hintFor(string $category): string {
 			self::CATEGORY_PREFLIGHT_PERMISSION => $l->t('The app folder is not writable by the web-server user. If this is a bind-mounted dev checkout, fix the folder ownership/permissions (or install the app into a writable apps directory).'),
 			self::CATEGORY_DOWNLOAD => $l->t('The release could not be downloaded from its source. Check connectivity to the source and that the release asset still exists.'),
 			self::CATEGORY_CHECKSUM_MISMATCH => $l->t('The downloaded archive failed its integrity check. The release may be corrupted or tampered with; do not install it.'),
+			self::CATEGORY_SHA_MISMATCH => $l->t('The downloaded artifact does not match the SHA-256 recorded the first time this version was installed. The upstream release may have been rewritten. Only proceed if you are certain the new artifact is legitimate, then explicitly accept the new checksum to install it.'),
 			self::CATEGORY_EXTRACT => $l->t('The release archive could not be extracted. The downloaded file may be incomplete or not a valid app archive.'),
 			self::CATEGORY_APPID_MISMATCH => $l->t('The downloaded archive is for a different app than requested. Verify the source binding points at the correct repository.'),
 			self::CATEGORY_VERSION_MISMATCH => $l->t('The downloaded archive declares a different version than requested. The source metadata and asset may be out of sync.'),

lib/Service/Installer/ShaMismatchException.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @license EUPL-1.2
+ * @copyright Copyright (c) 2025, Conduction B.V. <info@conduction.nl>
+ *
+ * SPDX-FileCopyrightText: 2025 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+
+namespace OCA\AppVersions\Service\Installer;
+
+use Exception;
+
+/**
+ * Thrown by {@see \OCA\AppVersions\Service\ExternalReleaseInstallerService}
+ * when the SHA-256 of a freshly downloaded artifact does not match the digest
+ * recorded on the binding at a previous successful install of the same
+ * (appId, version, source) triple. Thrown before extraction/backup — no
+ * filesystem change has happened when this is raised. The HTTP layer maps
+ * this to the machine-readable `sha_mismatch` error code; see "Recorded
+ * SHA-256 enforced on reinstall".
+ *
+ * @spec openspec/specs/external-sources/spec.md
+ * @psalm-api
+ */
+final class ShaMismatchException extends Exception {
+	public function __construct(
+		public readonly string $appId,
+		public readonly string $version,
+		public readonly string $expectedSha,
+		public readonly string $actualSha,
+	) {
+		parent::__construct(sprintf(
+			'Artifact for %s@%s does not match the checksum recorded at first install (expected %s, got %s). The release may have been rewritten upstream.',
+			$appId,
+			$version,
+			$expectedSha,
+			$actualSha,
+		));
+	}
+}