@oxy.so/services 13.2.0 → 13.4.0

package/plugins/withOxyReleaseSigning.js

@@ -0,0 +1,277 @@
+/**
+ * Config plugin: withOxyReleaseSigning (EVERY Oxy Android app, through
+ * `withOxySharedPermissions`; listed on its own only by an app that declares no
+ * Oxy permission).
+ *
+ * An app that declares the Oxy signature permissions (`so.oxy.permission.IDENTITY`,
+ * `DEVICE_SESSION`) is only safe to install when it carries the ONE Oxy ecosystem
+ * certificate. Signed with anything else it takes ownership of both permissions,
+ * after which Android refuses to install every correctly signed Oxy app next to it
+ * (`INSTALL_FAILED_DUPLICATE_PERMISSION`), and Commons refuses it as a caller
+ * anyway. That is why the plugin that declares the permissions applies this one:
+ * an app cannot get the permissions without the signing rule.
+ *
+ * It edits `android/app/build.gradle` in three places:
+ *
+ * 1. Before `android {`: resolve the keystore from Gradle properties (set in
+ *    `~/.gradle/gradle.properties`, with `-P`, or as `ORG_GRADLE_PROJECT_<name>`
+ *    environment variables; never in the repo):
+ *      - `OXY_UPLOAD_STORE_FILE`: the keystore (`~/` is expanded).
+ *      - `OXY_UPLOAD_STORE_PASSWORD`, or `OXY_UPLOAD_STORE_PASSWORD_FILE`: a file
+ *        holding it (trimmed).
+ *      - `OXY_UPLOAD_KEY_ALIAS`: `oxy` for the ecosystem key.
+ *      - `OXY_UPLOAD_KEY_PASSWORD` / `OXY_UPLOAD_KEY_PASSWORD_FILE`: optional,
+ *        defaults to the store password (a PKCS12 keystore has one password).
+ * 2. `signingConfigs.release` from those, and the `release` buildType signed by
+ *    it ALWAYS (the `debug` buildType only with `OXY_UPLOAD_SIGN_DEBUG`, below).
+ *    Expo's template signs release with the debug key; nothing here falls back
+ *    to it.
+ * 3. `oxyVerifyReleaseSigning`, a task every release variant's `pre…ReleaseBuild`
+ *    and `validateSigning…Release` depend on. It opens the release buildType's
+ *    EFFECTIVE signing config and fails the build unless the key's certificate
+ *    SHA-256 is the ecosystem one, so it holds however the keystore arrived
+ *    (these properties, EAS's injected `credentials.json`, anything else) and it
+ *    refuses a debug key, a per-app key and a wrong alias alike. Debug builds
+ *    never run it.
+ *
+ * Opt-in for debug: `OXY_UPLOAD_SIGN_DEBUG=true` signs the debug buildType with
+ * the same key and runs the same guard before every debug variant, so a dev
+ * client can sit next to real Oxy apps and be granted the permissions (Willo's
+ * `withOxyDebugSigning` did this with `OXY_DEBUG_*`). Without it debug keeps
+ * Expo's debug key and is never checked.
+ *
+ * There is deliberately no opt-out for release: no CI job builds an Android
+ * release without the key, and a release signed with anything else must not
+ * exist. An app that declares no Oxy permission (Authenticator) lists this
+ * plugin directly to get the same release signing.
+ *
+ * `android/` is generated by `expo prebuild`, so these edits live here or they
+ * are lost on the next prebuild.
+ */
+// The app's own Expo SDK copy, never one this package ships (Expo's guidance for library plugins).
+const { withAppBuildGradle } = require('expo/config-plugins');
+
+/** SHA-256 of the Oxy ecosystem release certificate (alias `oxy`), lowercase hex. */
+const ECOSYSTEM_CERT_SHA256 = 'b8ab3746466ce4569d7a6a0ffa1eed91bc375174d503613987ca09cb33d6a58d';
+
+const MARKER = '@generated oxy-release-signing';
+const PLUGIN = '[@oxy.so/services withOxyReleaseSigning]';
+
+/** Gradle property names holding the release signing material. */
+const PROPERTIES = {
+  storeFile: 'OXY_UPLOAD_STORE_FILE',
+  storePassword: 'OXY_UPLOAD_STORE_PASSWORD',
+  keyAlias: 'OXY_UPLOAD_KEY_ALIAS',
+  keyPassword: 'OXY_UPLOAD_KEY_PASSWORD',
+  signDebug: 'OXY_UPLOAD_SIGN_DEBUG',
+};
+
+/** Resolves the OXY_UPLOAD_* properties; inserted before `android {`. */
+const RESOLVE_PROPERTIES = `// ${MARKER}: the Oxy ecosystem release key (@oxy.so/services
+// withOxyReleaseSigning). Edit the plugin, never this file.
+def oxyHomePath = { String path -> path.startsWith('~/') ? System.getProperty('user.home') + path.substring(1) : path }
+def oxySigningProblems = []
+def oxySigningSecret = { String name ->
+    def value = findProperty(name)
+    if (value != null) return value.toString()
+    def path = findProperty(name + '_FILE')
+    if (path == null) return null
+    def secretFile = file(oxyHomePath(path.toString()))
+    if (!secretFile.isFile()) {
+        oxySigningProblems << (name + '_FILE names ' + secretFile + ', which is not a file')
+        return null
+    }
+    return secretFile.getText('UTF-8').trim()
+}
+def oxyStoreFilePath = findProperty('${PROPERTIES.storeFile}')
+def oxyStoreFile = oxyStoreFilePath == null ? null : file(oxyHomePath(oxyStoreFilePath.toString()))
+def oxyStorePassword = oxySigningSecret('${PROPERTIES.storePassword}')
+def oxyKeyAlias = findProperty('${PROPERTIES.keyAlias}')?.toString()
+def oxyKeyPassword = oxySigningSecret('${PROPERTIES.keyPassword}') ?: oxyStorePassword
+if (oxyStoreFile == null) oxySigningProblems << '${PROPERTIES.storeFile} is not set'
+if (oxyStorePassword == null && findProperty('${PROPERTIES.storePassword}_FILE') == null) oxySigningProblems << '${PROPERTIES.storePassword} (or ${PROPERTIES.storePassword}_FILE) is not set'
+if (oxyKeyAlias == null) oxySigningProblems << '${PROPERTIES.keyAlias} is not set'
+def oxyUploadSigning = oxyStoreFile != null && oxyStorePassword != null && oxyKeyAlias != null
+// Opt-in: sign debug with the ecosystem key too (a dev client next to real Oxy apps),
+// and then refuse a debug build without it exactly like a release.
+def oxySignDebug = (findProperty('${PROPERTIES.signDebug}') ?: 'false').toString().toBoolean()
+def oxySignedBuildTypes = oxySignDebug ? ['release', 'debug'] : ['release']
+
+`;
+
+const RELEASE_SIGNING_CONFIG = `        release {
+            // ${MARKER}: the Oxy ecosystem key from the OXY_UPLOAD_* properties.
+            // Without them it stays empty and oxyVerifyReleaseSigning fails the build.
+            if (oxyUploadSigning) {
+                storeFile oxyStoreFile
+                storePassword oxyStorePassword
+                keyAlias oxyKeyAlias
+                keyPassword oxyKeyPassword
+            }
+        }
+`;
+
+const RELEASE_SIGNING_LINE = 'signingConfig signingConfigs.release';
+const DEBUG_SIGNING_LINE = 'signingConfig signingConfigs.debug';
+const OPT_IN_DEBUG_SIGNING_LINE =
+  'signingConfig oxySignDebug ? signingConfigs.release : signingConfigs.debug';
+
+/** The fail-closed guard; appended to the file. */
+const VERIFY_TASK = String.raw`
+// ${MARKER}: every release build must carry the Oxy ecosystem certificate.
+// Signed with anything else, the app declares so.oxy.permission.IDENTITY and
+// DEVICE_SESSION under the wrong certificate: Android then refuses to install the
+// correctly signed Oxy apps next to it (INSTALL_FAILED_DUPLICATE_PERMISSION), and
+// Commons refuses it. This checks the release buildType's EFFECTIVE signing config.
+def oxyVerifyReleaseSigning = tasks.register('oxyVerifyReleaseSigning') {
+    group = 'verification'
+    description = 'Fails unless release (and, with OXY_UPLOAD_SIGN_DEBUG, debug) is signed with the Oxy ecosystem certificate.'
+    notCompatibleWithConfigurationCache('reads the android extension when it runs')
+    doLast {
+        def expected = '${ECOSYSTEM_CERT_SHA256}'
+        def fail = { String reason ->
+            throw new GradleException([
+                'Oxy release signing: ' + reason,
+                '',
+                'Every Oxy Android release is signed with the ONE ecosystem key (certificate SHA-256 ' + expected + ').',
+                'Provide it as Gradle properties, in ~/.gradle/gradle.properties, as -P<name>=<value>,',
+                'or as ORG_GRADLE_PROJECT_<name> environment variables:',
+                '  ${PROPERTIES.storeFile}=~/.config/oxy/oxy-ecosystem-release.keystore',
+                '  ${PROPERTIES.storePassword}_FILE=~/.config/oxy/oxy-ecosystem-release-keystore.pass (or ${PROPERTIES.storePassword})',
+                '  ${PROPERTIES.keyAlias}=oxy',
+                '  ${PROPERTIES.keyPassword}[_FILE] only when the key password differs from the store password',
+                'Debug builds need none of this unless ${PROPERTIES.signDebug}=true.',
+            ].join('\n'))
+        }
+        oxySignedBuildTypes.each { buildType ->
+            def config = android.buildTypes.getByName(buildType).signingConfig
+            if (config == null || config.storeFile == null) {
+                fail('the ' + buildType + ' build has no keystore' + (oxySigningProblems ? ': ' + oxySigningProblems.join('; ') : '') + '.')
+            }
+            def keyStore = null
+            try {
+                keyStore = java.security.KeyStore.getInstance(config.storeFile, config.storePassword?.toCharArray())
+            } catch (Exception e) {
+                fail('could not open ' + config.storeFile + ' (' + e.getClass().getSimpleName() + ': ' + e.getMessage() + ').')
+            }
+            def certificate = keyStore.getCertificate(config.keyAlias)
+            if (certificate == null) {
+                fail(config.storeFile.toString() + ' has no certificate under the alias "' + config.keyAlias + '".')
+            }
+            def actual = java.security.MessageDigest.getInstance('SHA-256').digest(certificate.getEncoded()).encodeHex().toString()
+            if (actual != expected) {
+                fail('the ' + buildType + ' build is signed by "' + config.name + '" (' + config.storeFile + ', alias ' + config.keyAlias + '), certificate SHA-256 ' + actual + ', not the Oxy ecosystem one.')
+            }
+        }
+    }
+}
+tasks.configureEach { task ->
+    if (task.name ==~ (oxySignDebug ? /pre\w*(Release|Debug)Build|validateSigning\w*(Release|Debug)/ : /pre\w*ReleaseBuild|validateSigning\w*Release/)) {
+        task.dependsOn(oxyVerifyReleaseSigning)
+    }
+}
+`;
+
+function fail(message) {
+  throw new Error(`${PLUGIN} ${message}`);
+}
+
+/**
+ * Apply the edits to the text of a Groovy `android/app/build.gradle`.
+ * Idempotent; refuses a file another plugin already gave a release signing config.
+ *
+ * @param {string} contents
+ * @returns {string}
+ */
+function applyReleaseSigning(contents) {
+  if (contents.includes(MARKER)) return contents;
+
+  if (contents.includes('OXY_UPLOAD_')) {
+    fail(
+      'app/build.gradle already has an OXY_UPLOAD_* signing config written by another plugin: ' +
+        "`@oxy.so/app-preset/plugin/withOxyAndroidRelease` (app-preset 4 or earlier) or an app's " +
+        "own copy (such as Mention's plugins/withAndroidReleaseBuild.js). Remove it from the app " +
+        'config: withOxySharedPermissions signs every Oxy release.',
+    );
+  }
+
+  if (contents.includes('OXY_DEBUG_')) {
+    fail(
+      "app/build.gradle already has an OXY_DEBUG_* debug signing config (such as Willo's " +
+        'plugins/withOxyDebugSigning.js). Remove that plugin and set the Gradle property ' +
+        `${PROPERTIES.signDebug}=true to sign debug builds with the ecosystem key.`,
+    );
+  }
+
+  const androidBlock = /^android \{$/m;
+  if (!androidBlock.test(contents)) {
+    fail(
+      'Could not find the top-level `android {` block in app/build.gradle. The Expo template changed: update this plugin.',
+    );
+  }
+  let next = contents.replace(androidBlock, `${RESOLVE_PROPERTIES}android {`);
+
+  // Declare signingConfigs.release immediately after the generated debug entry.
+  const debugSigningBlock =
+    /(signingConfigs\s*\{\s*\n\s*debug\s*\{[\s\S]*?\n\s{8}\}\n)(\s*release\s*\{)?/;
+  const debugMatch = next.match(debugSigningBlock);
+  if (!debugMatch) {
+    fail(
+      'Could not find the generated signingConfigs.debug block in app/build.gradle. The Expo template changed: update this plugin.',
+    );
+  }
+  if (debugMatch[2]) {
+    fail(
+      'app/build.gradle already declares signingConfigs.release. Remove the plugin that writes it: withOxySharedPermissions signs every Oxy release.',
+    );
+  }
+  next = next.replace(debugSigningBlock, `$1${RELEASE_SIGNING_CONFIG}`);
+
+  // Point the release buildType at it. The debug buildType has its own
+  // `signingConfig signingConfigs.debug`, so only the line inside `release {` is replaced.
+  const buildTypes = next.indexOf('buildTypes {');
+  const releaseBuildType = buildTypes === -1 ? -1 : next.indexOf('release {', buildTypes);
+  if (releaseBuildType === -1) {
+    fail('Could not find the release buildType in app/build.gradle.');
+  }
+  const releaseBody = next.slice(releaseBuildType);
+  const signingLine = releaseBody.match(/signingConfig [^\n]+/);
+  const closing = releaseBody.indexOf('\n        }');
+  if (
+    !signingLine ||
+    signingLine.index === undefined ||
+    (closing !== -1 && signingLine.index > closing)
+  ) {
+    fail('Could not find the signingConfig line of the release buildType in app/build.gradle.');
+  }
+  const at = releaseBuildType + signingLine.index;
+  next = next.slice(0, at) + RELEASE_SIGNING_LINE + next.slice(at + signingLine[0].length);
+
+  // The debug buildType keeps Expo's debug key unless OXY_UPLOAD_SIGN_DEBUG asks.
+  const debugBuildType = next.indexOf('debug {', next.indexOf('buildTypes {'));
+  const debugLine = debugBuildType === -1 ? -1 : next.indexOf(DEBUG_SIGNING_LINE, debugBuildType);
+  if (debugLine === -1 || debugLine > next.indexOf('release {', next.indexOf('buildTypes {'))) {
+    fail('Could not find the signingConfig line of the debug buildType in app/build.gradle.');
+  }
+  next =
+    next.slice(0, debugLine) +
+    OPT_IN_DEBUG_SIGNING_LINE +
+    next.slice(debugLine + DEBUG_SIGNING_LINE.length);
+
+  return `${next.replace(/\n*$/, '\n')}${VERIFY_TASK}`;
+}
+
+function withOxyReleaseSigning(config) {
+  return withAppBuildGradle(config, (modConfig) => {
+    if (modConfig.modResults.language !== 'groovy') {
+      fail(`Expected a Groovy app/build.gradle, got ${modConfig.modResults.language}.`);
+    }
+    modConfig.modResults.contents = applyReleaseSigning(modConfig.modResults.contents);
+    return modConfig;
+  });
+}
+
+module.exports = withOxyReleaseSigning;
+module.exports.applyReleaseSigning = applyReleaseSigning;
+module.exports.ECOSYSTEM_CERT_SHA256 = ECOSYSTEM_CERT_SHA256;
+module.exports.PROPERTIES = PROPERTIES;

package/plugins/withOxySharedPermissions.js

@@ -29,9 +29,16 @@
  *
  * `signature` is the whole trust boundary at the manifest level; each provider
  * also checks the calling package and its certificate itself.
+ *
+ * Declaring these permissions is only safe under the ONE Oxy ecosystem
+ * certificate, so this plugin also applies `withOxyReleaseSigning`: every
+ * release build is signed with the ecosystem key from the `OXY_UPLOAD_*` Gradle
+ * properties and FAILS unless its certificate is the ecosystem one. Apps list
+ * neither that plugin nor any signing plugin of their own.
  */
 // The app's own Expo SDK copy, never one this package ships (Expo's guidance for library plugins).
 const { withAndroidManifest } = require('expo/config-plugins');
+const withOxyReleaseSigning = require('./withOxyReleaseSigning');
 
 const IDENTITY_PERMISSION = 'so.oxy.permission.IDENTITY';
 const DEVICE_SESSION_PERMISSION = 'so.oxy.permission.DEVICE_SESSION';
@@ -52,7 +59,7 @@ const HOST_AUTHORITIES = [
 ];
 
 function withOxySharedPermissions(config) {
-  return withAndroidManifest(config, (modConfig) => {
+  return withAndroidManifest(withOxyReleaseSigning(config), (modConfig) => {
     const manifest = modConfig.modResults.manifest;
 
     manifest.permission = manifest.permission ?? [];

package/src/ui/client.ts

@@ -53,6 +53,8 @@ export {
   resolveAccountColor,
   entitledAccountColors,
 } from './hooks/useAccountColor';
+export { useAccountTheme, useAccountThemeControls } from './hooks/useAccountTheme';
+export type { AccountThemeControls, ThemeSource } from './hooks/useAccountTheme';
 // This app's Oxy-signed assertion of which app it is (ADR 0045), for an SDK
 // that attaches it to its own requests without pulling in the account screens.
 export {

package/src/ui/hooks/useAccountTheme.ts

@@ -0,0 +1,177 @@
+/**
+ * useAccountTheme / useAccountThemeControls
+ *
+ * The Oxy account carries a portable theme (`user.themePreference`: a mode and
+ * a colour preset) that every Oxy app can wear. The COLOUR is the account
+ * colour and always applies (`useAccountColor`). Whether an app also follows
+ * the account's MODE is the viewer's choice per device: the theme SOURCE.
+ *
+ * - `account` (the default): the account's mode is applied to Bloom, and a mode
+ *   chosen here is written back to the account for the other Oxy apps.
+ * - `app`: the mode stays on this device; nothing is written to the account.
+ *
+ * The source is a local preference, never sent anywhere. On web it is read
+ * synchronously, so the first paint already knows it; on native it resolves
+ * from AsyncStorage right after mount. Bloom's own persistence still paints the
+ * last theme instantly on cold boot, so the account theme lands without a flash
+ * once the session resolves.
+ */
+
+import { useCallback, useEffect } from 'react';
+import { create } from 'zustand';
+import { logger, type User } from '@oxy.so/core';
+import { useBloomTheme, type AppColorName, type ThemeMode } from '@oxy.so/bloom/theme';
+import { createPlatformStorage, isReactNative } from '../utils/storageHelpers';
+import { resolveAccountColor, useAccountColor } from './useAccountColor';
+import { useAuth } from './useAuth';
+import { useUpdateProfile } from './mutations/useAccountMutations';
+
+/** Where the app's theme MODE comes from on this device. */
+export type ThemeSource = 'app' | 'account';
+
+type PortableThemeMode = NonNullable<User['themePreference']>['mode'];
+
+const THEME_SOURCE_KEY = 'oxy.theme.source';
+
+function normalizeSource(stored: string | null | undefined): ThemeSource {
+  return stored === 'app' ? 'app' : 'account';
+}
+
+/**
+ * Bloom's richer mode set onto the portable subset the account stores
+ * (`adaptive` has no cross-app meaning, so it is `system`).
+ */
+function toPortableMode(mode: ThemeMode): PortableThemeMode {
+  return mode === 'light' || mode === 'dark' ? mode : 'system';
+}
+
+/** Web reads `localStorage` synchronously; native resolves in `hydrate`. */
+function readInitialSource(): { source: ThemeSource; hydrated: boolean } {
+  if (isReactNative() || typeof window === 'undefined') {
+    return { source: 'account', hydrated: false };
+  }
+  try {
+    return {
+      source: normalizeSource(window.localStorage?.getItem(THEME_SOURCE_KEY)),
+      hydrated: true,
+    };
+  } catch {
+    // A sandboxed document's storage getter throws: no stored choice.
+    return { source: 'account', hydrated: true };
+  }
+}
+
+interface ThemeSourceState {
+  source: ThemeSource;
+  /** True once the stored source is known (at once on web). */
+  hydrated: boolean;
+  setSource: (source: ThemeSource) => void;
+  hydrate: () => Promise<void>;
+}
+
+const useThemeSourceStore = create<ThemeSourceState>((set, get) => ({
+  ...readInitialSource(),
+  setSource(source) {
+    set({ source, hydrated: true });
+    void createPlatformStorage()
+      .then((storage) => storage.setItem(THEME_SOURCE_KEY, source))
+      .catch(() => undefined);
+  },
+  async hydrate() {
+    if (get().hydrated) return;
+    const stored = await createPlatformStorage()
+      .then((storage) => storage.getItem(THEME_SOURCE_KEY))
+      .catch(() => null);
+    // A choice made while storage was being read wins over the stored one.
+    if (!get().hydrated) set({ source: normalizeSource(stored), hydrated: true });
+  },
+}));
+
+/**
+ * Apply the account theme to Bloom: the colour always (through
+ * `useAccountColor`, which `canUse` can narrow), the mode while this device's
+ * source is `account`. Mount ONCE, inside `OxyProvider` and Bloom's theme
+ * provider.
+ */
+export function useAccountTheme({
+  canUse,
+}: {
+  canUse?: (name: AppColorName) => boolean;
+} = {}): void {
+  const { isAuthenticated, user } = useAuth();
+  const source = useThemeSourceStore((state) => state.source);
+  const hydrated = useThemeSourceStore((state) => state.hydrated);
+  const hydrate = useThemeSourceStore((state) => state.hydrate);
+  const { setMode } = useBloomTheme();
+  useAccountColor({ canUse });
+
+  useEffect(() => {
+    void hydrate();
+  }, [hydrate]);
+
+  const accountMode = user?.themePreference?.mode;
+  useEffect(() => {
+    if (!hydrated || !isAuthenticated || source !== 'account' || !accountMode) return;
+    setMode(accountMode);
+  }, [hydrated, isAuthenticated, source, accountMode, setMode]);
+}
+
+export interface AccountThemeControls {
+  /** The effective source: `app` whenever no session can reach the account. */
+  source: ThemeSource;
+  /** Switch this device's source; enabling `account` seeds an account with no theme yet. */
+  changeThemeSource: (source: ThemeSource) => void;
+  /** Change the mode now; on the `account` source, also write it to the account. */
+  changeThemeMode: (mode: ThemeMode) => Promise<void>;
+}
+
+/**
+ * Source-aware theme mode changes for a settings screen. Bloom changes at once;
+ * on the `account` source the account's portable theme follows. Without a
+ * usable session the effective source is `app`, so changes stay local, and the
+ * stored choice applies again once signed in. The colour is chosen with
+ * `useAccountColorSave`.
+ */
+export function useAccountThemeControls(): AccountThemeControls {
+  const { user, canUsePrivateApi } = useAuth();
+  const { mode, colorPreset, setMode } = useBloomTheme();
+  const { mutateAsync } = useUpdateProfile();
+  const storedSource = useThemeSourceStore((state) => state.source);
+  const setSource = useThemeSourceStore((state) => state.setSource);
+  const source: ThemeSource = canUsePrivateApi ? storedSource : 'app';
+
+  const persist = useCallback(
+    async (next: { mode: ThemeMode; colorPreset: AppColorName }) => {
+      await mutateAsync({
+        themePreference: { mode: toPortableMode(next.mode), colorPreset: next.colorPreset },
+      });
+    },
+    [mutateAsync],
+  );
+
+  const changeThemeMode = useCallback(
+    async (nextMode: ThemeMode) => {
+      setMode(nextMode);
+      if (source === 'account') await persist({ mode: nextMode, colorPreset });
+    },
+    [setMode, source, persist, colorPreset],
+  );
+
+  const accountTheme = user?.themePreference;
+  const hasAccountTheme =
+    !!accountTheme && resolveAccountColor({ themePreference: accountTheme }) !== null;
+  const changeThemeSource = useCallback(
+    (nextSource: ThemeSource) => {
+      setSource(nextSource);
+      // An existing account theme is applied by `useAccountTheme`; only an
+      // account without one is seeded, from what the viewer sees now.
+      if (nextSource !== 'account' || !canUsePrivateApi || hasAccountTheme) return;
+      persist({ mode, colorPreset }).catch((error: unknown) => {
+        logger.error('Failed to seed the account theme', error);
+      });
+    },
+    [setSource, canUsePrivateApi, hasAccountTheme, persist, mode, colorPreset],
+  );
+
+  return { source, changeThemeSource, changeThemeMode };
+}

package/src/ui/hooks/useFileDownloadUrl.ts

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import type { OxyServices } from '@oxy.so/core';
+import { useOptionalOxy } from '../context/oxyRuntimeContext';
 
 export interface UseFileDownloadUrlOptions {
   variant?: string;
@@ -12,72 +13,81 @@ export interface UseFileDownloadUrlResult {
   error: Error | null;
 }
 
+interface Settled {
+  request: string;
+  url: string | null;
+  error: Error | null;
+}
+
+function isAbsoluteUrl(ref: string): boolean {
+  return ref.startsWith('http://') || ref.startsWith('https://');
+}
+
 /**
- * Hook to resolve a file's download URL asynchronously.
+ * Resolve a file's download URL for the current caller.
  *
- * Uses `getFileDownloadUrlAsync`, which returns a scoped media-token stream URL
- * for private assets. There is no sync CDN fallback — the synchronous
- * `getFileDownloadUrl` is public-CDN-only and 404s for private uploads.
+ * A URL `assets.url` already resolved is answered in the FIRST render from
+ * core's identity-scoped cache (`assets.cachedUrl`): no request, no loading
+ * frame. Only a miss resolves asynchronously, through `assets.url`, which
+ * returns a scoped media-token stream URL for a private asset. There is no
+ * public-CDN fallback: `assets.publicUrl` 404s for private uploads. A
+ * reference that is already an absolute `http(s)` URL is returned unchanged.
+ *
+ * For a synchronous, render-only answer (an image resolver, a list row) use
+ * `oxyServices.assets.renderUrl`, which reads the same cache.
  */
 export const useFileDownloadUrl = (
   oxyServices: OxyServices | null | undefined,
   fileId: string | null | undefined,
   options?: UseFileDownloadUrlOptions,
 ): UseFileDownloadUrlResult => {
-  const [url, setUrl] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
   const variant = options?.variant;
   const expiresIn = options?.expiresIn;
+  // A resolved URL can carry the viewer's scoped media token, so the viewer is
+  // part of what was asked: an account switch never shows the previous one's.
+  const viewerId = useOptionalOxy()?.user?.id ?? '';
+  const request = fileId ? `${viewerId}|${fileId}|${variant ?? ''}|${expiresIn ?? ''}` : null;
+  const immediate = !fileId
+    ? null
+    : isAbsoluteUrl(fileId)
+      ? fileId
+      : (oxyServices?.assets.cachedUrl(fileId, variant, expiresIn) ?? null);
+  const needsResolve = !!fileId && !!oxyServices && immediate === null;
 
-  useEffect(() => {
-    if (!fileId) {
-      setUrl(null);
-      setLoading(false);
-      setError(null);
-      return;
-    }
-
-    if (!oxyServices) {
-      setUrl(null);
-      setLoading(false);
-      setError(new Error('OxyServices instance not configured for useFileDownloadUrl'));
-      return;
-    }
+  const [settled, setSettled] = useState<Settled | null>(null);
 
+  useEffect(() => {
+    if (!needsResolve || !fileId || !oxyServices || !request) return;
     let cancelled = false;
-    const instance = oxyServices;
-    const targetFileId = fileId;
-
-    const load = async () => {
-      setLoading(true);
-      setError(null);
-
-      try {
-        const resolvedUrl = await instance.assets.url(targetFileId, variant, expiresIn);
-
+    oxyServices.assets.url(fileId, variant, expiresIn).then(
+      (url) => {
+        if (!cancelled) setSettled({ request, url: url || null, error: null });
+      },
+      (err: unknown) => {
         if (!cancelled) {
-          setUrl(resolvedUrl || null);
+          setSettled({
+            request,
+            url: null,
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
-      } catch (err: unknown) {
-        if (!cancelled) {
-          setUrl(null);
-          setError(err instanceof Error ? err : new Error(String(err)));
-        }
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    };
-
-    load();
-
+      },
+    );
     return () => {
       cancelled = true;
     };
-  }, [fileId, oxyServices, variant, expiresIn]);
+  }, [needsResolve, fileId, oxyServices, variant, expiresIn, request]);
 
-  return { url, loading, error };
+  if (!fileId) return { url: null, loading: false, error: null };
+  if (immediate !== null) return { url: immediate, loading: false, error: null };
+  if (!oxyServices) {
+    return {
+      url: null,
+      loading: false,
+      error: new Error('OxyServices instance not configured for useFileDownloadUrl'),
+    };
+  }
+  // A result settled for another file, variant or expiry is never shown.
+  if (settled?.request !== request) return { url: null, loading: true, error: null };
+  return { url: settled.url, loading: false, error: settled.error };
 };