feat(astrolabe): add background token refresh job

Prevents users from having to re-authorize Astrolabe after periods of inactivity by proactively refreshing OAuth tokens before they expire. Changes: - Add RefreshUserTokens background job that runs every 15 minutes - Add on-demand token refresh in SemanticSearchProvider (Unified Search) - Store issued_at timestamp for accurate token lifetime calculation - Add getAllUsersWithTokens() to query users needing refresh The job dynamically calculates refresh threshold based on actual token lifetime (50% remaining), working with any IdP (Nextcloud OIDC, Keycloak, etc.) rather than relying on IdP-specific configuration. Closes #510 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 10:34:39 +01:00
parent daaf460b0c
commit 28219e00e7
4 changed files with 217 additions and 3 deletions
@@ -0,0 +1,155 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\Astrolabe\BackgroundJob;
+
+use OCA\Astrolabe\Service\IdpTokenRefresher;
+use OCA\Astrolabe\Service\McpTokenStorage;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\IJob;
+use OCP\BackgroundJob\TimedJob;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Background job to proactively refresh OAuth tokens before expiration.
+ *
+ * Runs every 15 minutes and refreshes tokens based on their actual expiration
+ * time. Works with any IdP (Nextcloud OIDC, Keycloak, etc.) since it uses
+ * the real token expiration rather than IdP configuration.
+ *
+ * Refresh strategy: Refresh when less than 50% of token lifetime remains,
+ * ensuring tokens are refreshed well before expiration regardless of the
+ * IdP's configured token lifetime.
+ *
+ * @psalm-suppress UnusedClass - Background jobs are loaded dynamically by Nextcloud
+ */
+class RefreshUserTokens extends TimedJob {
+	/** Job runs every 15 minutes */
+	private const JOB_INTERVAL_SECONDS = 900;
+
+	/** Refresh when this percentage of token lifetime remains */
+	private const REFRESH_AT_REMAINING_PERCENT = 0.5;
+
+	/** Minimum threshold to avoid constant refresh (5 minutes) */
+	private const MIN_THRESHOLD_SECONDS = 300;
+
+	/** Default assumed token lifetime if we can't determine it (1 hour) */
+	private const DEFAULT_TOKEN_LIFETIME_SECONDS = 3600;
+
+	public function __construct(
+		ITimeFactory $time,
+		private McpTokenStorage $tokenStorage,
+		private IdpTokenRefresher $tokenRefresher,
+		private LoggerInterface $logger,
+	) {
+		parent::__construct($time);
+		$this->setInterval(self::JOB_INTERVAL_SECONDS);
+		$this->setTimeSensitivity(IJob::TIME_INSENSITIVE);
+	}
+
+	protected function run(mixed $argument): void {
+		$this->logger->info('RefreshUserTokens: Starting background token refresh');
+
+		$userIds = $this->tokenStorage->getAllUsersWithTokens();
+		$this->logger->debug('RefreshUserTokens: Found ' . count($userIds) . ' users with tokens');
+
+		$refreshed = 0;
+		$failed = 0;
+		$skipped = 0;
+
+		foreach ($userIds as $userId) {
+			$result = $this->refreshUserTokenIfNeeded($userId);
+			match ($result) {
+				'refreshed' => $refreshed++,
+				'failed' => $failed++,
+				'skipped' => $skipped++,
+			};
+		}
+
+		$this->logger->info("RefreshUserTokens: Complete - refreshed=$refreshed, failed=$failed, skipped=$skipped");
+	}
+
+	/**
+	 * Refresh a user's token if it's nearing expiration.
+	 *
+	 * Calculates the refresh threshold based on the token's actual lifetime,
+	 * refreshing when less than 50% of the lifetime remains.
+	 *
+	 * @return string 'refreshed', 'failed', or 'skipped'
+	 */
+	private function refreshUserTokenIfNeeded(string $userId): string {
+		$token = $this->tokenStorage->getUserToken($userId);
+
+		if ($token === null) {
+			return 'skipped';
+		}
+
+		$expiresAt = (int)($token['expires_at'] ?? 0);
+		$issuedAt = isset($token['issued_at']) ? (int)$token['issued_at'] : null;
+		$timeRemaining = $expiresAt - time();
+
+		// Calculate token lifetime from stored data or use default
+		if ($issuedAt !== null) {
+			$tokenLifetime = $expiresAt - $issuedAt;
+		} else {
+			// Fallback: use default lifetime assumption
+			$tokenLifetime = self::DEFAULT_TOKEN_LIFETIME_SECONDS;
+		}
+
+		// Calculate threshold: refresh when 50% of lifetime remains
+		$threshold = max(
+			(int)($tokenLifetime * self::REFRESH_AT_REMAINING_PERCENT),
+			self::MIN_THRESHOLD_SECONDS
+		);
+
+		if ($timeRemaining > $threshold) {
+			// Token still has plenty of time, skip
+			return 'skipped';
+		}
+
+		// Token is expiring soon, attempt refresh
+		if (!isset($token['refresh_token'])) {
+			$this->logger->warning("RefreshUserTokens: User $userId has no refresh token");
+			return 'failed';
+		}
+
+		$this->logger->debug("RefreshUserTokens: Refreshing token for user $userId (remaining={$timeRemaining}s, threshold={$threshold}s)");
+
+		try {
+			/** @var string $refreshToken */
+			$refreshToken = $token['refresh_token'];
+			$newTokenData = $this->tokenRefresher->refreshAccessToken($refreshToken);
+
+			if ($newTokenData === null) {
+				$this->logger->warning("RefreshUserTokens: Refresh returned null for user $userId");
+				// Don't delete token here - let on-demand refresh handle cleanup
+				return 'failed';
+			}
+
+			// Calculate new expiration and store issued_at for future calculations
+			$expiresIn = (int)($newTokenData['expires_in'] ?? self::DEFAULT_TOKEN_LIFETIME_SECONDS);
+			$now = time();
+
+			/** @var string $accessToken */
+			$accessToken = $newTokenData['access_token'];
+			/** @var string $newRefreshToken */
+			$newRefreshToken = $newTokenData['refresh_token'] ?? $refreshToken;
+
+			$this->tokenStorage->storeUserToken(
+				$userId,
+				$accessToken,
+				$newRefreshToken,
+				$now + $expiresIn,
+				$now  // issued_at
+			);
+
+			$this->logger->debug("RefreshUserTokens: Successfully refreshed token for user $userId");
+			return 'refreshed';
+
+		} catch (\Exception $e) {
+			$this->logger->error("RefreshUserTokens: Failed to refresh for user $userId: " . $e->getMessage());
+			return 'failed';
+		}
+	}
+}