@fnndsc/cumin 3.8.1 → 3.10.0

package/dist/chrisapi/contract.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @file Typed ChRIS API contract — domain-typed access to the hot wire surfaces.
+ *
+ * The adapter (`adapter.ts`) is the unsafe seam: the only module that imports
+ * `@fnndsc/chrisapi` and the only one allowed to cast against it. This module
+ * is the typed floor above that seam. It declares the wire shapes for the two
+ * surfaces that have produced live defects (the jobs surface: plugin
+ * instances, feeds; the PACS surface: download tokens, PACS files) and exposes
+ * domain-typed accessors built purely on the adapter's generics. Downstream
+ * packages call these instead of casting the opaque client per call site,
+ * which is what this module exists to end.
+ *
+ * Key components:
+ *   - ListPage<T>: normalized page shape (data + totalCount) for CUBE lists
+ *   - FeedData / PluginInstanceData / InstanceParameterData: wire row shapes
+ *   - feedsPage_get / publicFeedsPage_get / pluginInstancesPage_get: paged reads
+ *   - pluginInstance_get: detail handle (data, parameters, status, logs, delete)
+ *   - downloadToken_create: PACS/LONK download token
+ *
+ * Dependencies: only `adapter.ts`. This file must contain no unchecked double
+ * casts and no `@fnndsc/chrisapi` import; the cast ratchet and the seam lint
+ * enforce that shape.
+ *
+ * @module
+ */
+import { Client } from './adapter';
+import type { PipelineRecord } from '../pipelines/chrisPipeline';
+/**
+ * One normalized page of a paginated CUBE list.
+ *
+ * @property data - The rows of this page, in server order.
+ * @property totalCount - The collection's total row count when the server
+ *   reported one, otherwise null. A null total means "unknown", not zero.
+ */
+export interface ListPage<T> {
+    data: T[];
+    totalCount: number | null;
+}
+/**
+ * Wire shape of one CUBE feed row, as served by the feeds list endpoints.
+ *
+ * @property id - Feed id.
+ * @property name - Feed title.
+ * @property owner_username - Owning user, when serialized.
+ * @property public - Public visibility flag.
+ * @property creation_date - ISO creation timestamp.
+ * @property finished_jobs - Count of jobs finished successfully.
+ * @property errored_jobs - Count of jobs finished with error.
+ * @property started_jobs - Count of running jobs.
+ * @property scheduled_jobs - Count of scheduled jobs.
+ * @property cancelled_jobs - Count of cancelled jobs.
+ * @property created_jobs - Count of created (not yet scheduled) jobs.
+ */
+export interface FeedData {
+    id: number;
+    name: string;
+    owner_username?: string;
+    public?: boolean;
+    creation_date?: string;
+    finished_jobs?: number;
+    errored_jobs?: number;
+    started_jobs?: number;
+    scheduled_jobs?: number;
+    cancelled_jobs?: number;
+    created_jobs?: number;
+    [key: string]: unknown;
+}
+/**
+ * Wire shape of one CUBE plugin-instance row.
+ *
+ * @property id - Instance id.
+ * @property feed_id - Owning feed id.
+ * @property previous_id - Parent instance id, or null for a feed root.
+ * @property plugin_name - Name of the plugin this instance runs.
+ * @property plugin_type - Plugin type (`fs`, `ds`, `ts`), when serialized.
+ * @property status - Current job status string.
+ * @property output_path - CFS output directory, once CUBE records one.
+ * @property raw - Base64 zlib-compressed pfcon response, when present.
+ */
+export interface PluginInstanceData {
+    id: number;
+    feed_id: number;
+    previous_id?: number | null;
+    plugin_name: string;
+    plugin_type?: string;
+    status?: string;
+    output_path?: string;
+    raw?: string;
+    [key: string]: unknown;
+}
+/**
+ * One resolved parameter value recorded on a plugin instance.
+ *
+ * @property param_name - The parameter's flag name.
+ * @property value - The recorded invocation value.
+ */
+export interface InstanceParameterData {
+    param_name?: string;
+    value?: unknown;
+}
+/**
+ * A CUBE file-download token, used for authenticated downloads and the LONK
+ * WebSocket.
+ *
+ * @property token - The token string.
+ * @property url - REST URL of the token resource (its origin hosts the LONK
+ *   WebSocket endpoint).
+ */
+export interface DownloadToken {
+    token: string;
+    url: string;
+}
+/**
+ * Typed handle over one plugin-instance detail resource.
+ *
+ * Wraps the live chrisapi resource so callers can read its payload and drive
+ * its lifecycle without touching the unsafe object.
+ *
+ * @property data - The instance's wire payload, or null when the resource
+ *   carries none (the sub-resources and lifecycle methods still work).
+ */
+export interface PluginInstanceHandle {
+    data: PluginInstanceData | null;
+    /**
+     * Reads one page of the instance's effective parameter values.
+     *
+     * @param params - Page window (limit, offset).
+     * @returns The page of recorded parameter values.
+     */
+    parametersPage_get(params: {
+        limit: number;
+        offset: number;
+    }): Promise<ListPage<InstanceParameterData>>;
+    /**
+     * Writes a new status to the instance (e.g. `cancelled`).
+     *
+     * @param status - The status string to PUT.
+     */
+    status_set(status: string): Promise<void>;
+    /** Deletes the instance record from CUBE. */
+    delete(): Promise<void>;
+    /**
+     * Fetches the instance's log text via its logs sub-resource.
+     *
+     * @returns The joined log text, or null when this instance's resource does
+     *   not expose logs.
+     */
+    logs_get(): Promise<string | null>;
+}
+/**
+ * Reads one page of the session user's feeds (owned and shared).
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (limit, offset, id, ...).
+ * @returns The typed feed page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function feedsPage_get(client: Client, params: Record<string, unknown>): Promise<ListPage<FeedData>>;
+/**
+ * Reads one page of public feeds, when the connected CUBE offers them.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params.
+ * @returns The typed feed page, or null when the client has no public-feeds
+ *   endpoint (older CUBE versions).
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function publicFeedsPage_get(client: Client, params: Record<string, unknown>): Promise<ListPage<FeedData> | null>;
+/**
+ * Reads one page of plugin instances, optionally filtered.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (feed_id, id, plugin_name, ...).
+ * @returns The typed instance page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pluginInstancesPage_get(client: Client, params: Record<string, unknown>): Promise<ListPage<PluginInstanceData>>;
+/**
+ * Fetches one plugin instance's detail resource as a typed handle.
+ *
+ * @param client - Connected chrisapi client.
+ * @param instanceID - The plugin instance id.
+ * @returns The typed handle, or null when CUBE returns no such instance.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pluginInstance_get(client: Client, instanceID: number): Promise<PluginInstanceHandle | null>;
+/**
+ * Wire shape of one registered pipeline source file row.
+ *
+ * @property fname - CFS path of the uploaded pipeline source.
+ * @property pipeline_name - Name of the pipeline it registered.
+ * @property pipeline_id - Id of the pipeline it registered.
+ */
+export interface PipelineSourceFileData {
+    fname: string;
+    pipeline_name?: string;
+    pipeline_id?: number;
+    [key: string]: unknown;
+}
+/**
+ * Wire shape of one plugin piping row in a registered pipeline.
+ *
+ * @property id - Piping id.
+ * @property title - Piping title, when authored.
+ * @property plugin_name - Name of the plugin this piping runs.
+ * @property plugin_version - Version of that plugin.
+ * @property previous_id - Parent piping id, or null for the root.
+ */
+export interface PluginPipingData {
+    id: number;
+    title?: string;
+    plugin_name?: string;
+    plugin_version?: string;
+    previous_id?: number | null;
+    [key: string]: unknown;
+}
+/**
+ * Wire shape of one stored piping default-parameter row.
+ *
+ * @property plugin_piping_id - Piping the default belongs to.
+ * @property param_name - The parameter's flag name.
+ * @property value - The stored default value.
+ */
+export interface PipingDefaultParameterData {
+    plugin_piping_id?: number;
+    param_name?: string;
+    value?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Wire shape of one plugin parameter definition row.
+ *
+ * @property name - The parameter's flag name.
+ * @property type - Declared value type (e.g. "string").
+ * @property optional - Whether the parameter may be omitted.
+ * @property default - Declared default value.
+ * @property help - Author-provided help text.
+ */
+export interface PluginParameterData {
+    name: string;
+    type?: string;
+    optional?: boolean;
+    default?: unknown;
+    help?: string;
+    [key: string]: unknown;
+}
+/**
+ * Wire shape of one compute-resource row attached to a plugin.
+ *
+ * @property name - The compute environment's name.
+ */
+export interface ComputeResourceData {
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Typed handle over one plugin detail resource (metadata surfaces only).
+ */
+export interface PluginHandle {
+    /**
+     * Reads one page of the plugin's declared parameters.
+     *
+     * @param params - Page window (limit, offset).
+     * @returns The page of parameter definitions.
+     */
+    parametersPage_get(params: Record<string, unknown>): Promise<ListPage<PluginParameterData>>;
+    /**
+     * Reads one page of the plugin's registered compute resources.
+     *
+     * @param params - Page window (limit, offset).
+     * @returns The page of compute-resource rows.
+     */
+    computeResourcesPage_get(params: Record<string, unknown>): Promise<ListPage<ComputeResourceData>>;
+}
+/**
+ * One plugin piping of a registered pipeline, with its plugin reachable.
+ *
+ * @property data - The piping's wire payload.
+ */
+export interface PluginPipingItem {
+    data: PluginPipingData;
+    /**
+     * Fetches the plugin this piping runs, when the item links one.
+     *
+     * @returns The plugin handle, or null when the item exposes no plugin link.
+     */
+    plugin_get(): Promise<PluginHandle | null>;
+}
+/**
+ * Typed handle over one registered pipeline resource.
+ *
+ * @property data - The pipeline's wire payload, or null when absent.
+ */
+export interface PipelineHandle {
+    data: PipelineRecord | null;
+    /**
+     * Reads the pipeline's plugin pipings as items (plugin link preserved).
+     *
+     * @param params - Page window (limit, offset).
+     * @returns The piping items of that page.
+     */
+    pluginPipings_get(params: Record<string, unknown>): Promise<PluginPipingItem[]>;
+    /**
+     * Reads one page of the stored piping default parameters.
+     *
+     * @param params - Page window (limit, offset).
+     * @returns The page of stored defaults.
+     */
+    defaultParametersPage_get(params: Record<string, unknown>): Promise<ListPage<PipingDefaultParameterData>>;
+}
+/**
+ * Fetches one registered pipeline's detail resource as a typed handle.
+ *
+ * @param client - Connected chrisapi client.
+ * @param pipelineID - The pipeline id.
+ * @returns The typed handle, or null when CUBE returns no such pipeline.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pipeline_get(client: Client, pipelineID: number): Promise<PipelineHandle | null>;
+/**
+ * Reads one page of registered pipeline source files.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (pipeline_id, limit, ...).
+ * @returns The typed source-file page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pipelineSourceFilesPage_get(client: Client, params: Record<string, unknown>): Promise<ListPage<PipelineSourceFileData>>;
+/**
+ * Creates a CUBE download token for authenticated file access and LONK.
+ *
+ * @param client - Connected chrisapi client.
+ * @returns The token string and the token resource's REST URL.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function downloadToken_create(client: Client): Promise<DownloadToken>;

package/dist/chrisapi/contract.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * @file Typed ChRIS API contract — domain-typed access to the hot wire surfaces.
+ *
+ * The adapter (`adapter.ts`) is the unsafe seam: the only module that imports
+ * `@fnndsc/chrisapi` and the only one allowed to cast against it. This module
+ * is the typed floor above that seam. It declares the wire shapes for the two
+ * surfaces that have produced live defects (the jobs surface: plugin
+ * instances, feeds; the PACS surface: download tokens, PACS files) and exposes
+ * domain-typed accessors built purely on the adapter's generics. Downstream
+ * packages call these instead of casting the opaque client per call site,
+ * which is what this module exists to end.
+ *
+ * Key components:
+ *   - ListPage<T>: normalized page shape (data + totalCount) for CUBE lists
+ *   - FeedData / PluginInstanceData / InstanceParameterData: wire row shapes
+ *   - feedsPage_get / publicFeedsPage_get / pluginInstancesPage_get: paged reads
+ *   - pluginInstance_get: detail handle (data, parameters, status, logs, delete)
+ *   - downloadToken_create: PACS/LONK download token
+ *
+ * Dependencies: only `adapter.ts`. This file must contain no unchecked double
+ * casts and no `@fnndsc/chrisapi` import; the cast ratchet and the seam lint
+ * enforce that shape.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feedsPage_get = feedsPage_get;
+exports.publicFeedsPage_get = publicFeedsPage_get;
+exports.pluginInstancesPage_get = pluginInstancesPage_get;
+exports.pluginInstance_get = pluginInstance_get;
+exports.pipeline_get = pipeline_get;
+exports.pipelineSourceFilesPage_get = pipelineSourceFilesPage_get;
+exports.downloadToken_create = downloadToken_create;
+const adapter_1 = require("./adapter");
+/**
+ * Normalizes a raw chrisapi list response into a typed ListPage.
+ *
+ * @param page - The raw list resource (or null/undefined).
+ * @returns The typed page; totalCount is null when the server sent none.
+ */
+function listPage_wrap(page) {
+    const total = page?.totalCount;
+    return {
+        data: (0, adapter_1.listData_get)(page ?? undefined),
+        totalCount: typeof total === 'number' && total >= 0 ? total : null,
+    };
+}
+/**
+ * Reads one page of the session user's feeds (owned and shared).
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (limit, offset, id, ...).
+ * @returns The typed feed page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function feedsPage_get(client, params) {
+    return listPage_wrap(await (0, adapter_1.resource_call)(client, 'getFeeds', params));
+}
+/**
+ * Reads one page of public feeds, when the connected CUBE offers them.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params.
+ * @returns The typed feed page, or null when the client has no public-feeds
+ *   endpoint (older CUBE versions).
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function publicFeedsPage_get(client, params) {
+    if (!(0, adapter_1.method_exists)(client, 'getPublicFeeds'))
+        return null;
+    return listPage_wrap(await (0, adapter_1.resource_call)(client, 'getPublicFeeds', params));
+}
+/**
+ * Reads one page of plugin instances, optionally filtered.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (feed_id, id, plugin_name, ...).
+ * @returns The typed instance page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function pluginInstancesPage_get(client, params) {
+    return listPage_wrap(await (0, adapter_1.resource_call)(client, 'getPluginInstances', params));
+}
+/**
+ * Fetches one plugin instance's detail resource as a typed handle.
+ *
+ * @param client - Connected chrisapi client.
+ * @param instanceID - The plugin instance id.
+ * @returns The typed handle, or null when CUBE returns no such instance.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function pluginInstance_get(client, instanceID) {
+    const resource = await (0, adapter_1.resource_call)(client, 'getPluginInstance', instanceID);
+    if (!resource)
+        return null;
+    const data = (0, adapter_1.itemData_get)(resource);
+    return {
+        data,
+        async parametersPage_get(params) {
+            // Some chrisapi versions serve rows in `data`, others only via getItems().
+            return listPageFlexible_wrap(await (0, adapter_1.resource_call)(resource, 'getParameters', params));
+        },
+        async status_set(status) {
+            await (0, adapter_1.resource_call)(resource, 'put', { status });
+        },
+        async delete() {
+            await (0, adapter_1.resource_call)(resource, 'delete');
+        },
+        async logs_get() {
+            if (!(0, adapter_1.method_exists)(resource, 'getLogs'))
+                return null;
+            const logs = await (0, adapter_1.resource_call)(resource, 'getLogs');
+            const rows = (0, adapter_1.listData_get)(logs);
+            return rows.map((row) => (typeof row.log === 'string' ? row.log : '')).join('\n');
+        },
+    };
+}
+/**
+ * Normalizes a chrisapi list response that may serve rows in `data` or only
+ * via `getItems()` into a typed ListPage.
+ *
+ * @param page - The raw list resource.
+ * @returns The typed page; totalCount is null when the server sent none.
+ */
+function listPageFlexible_wrap(page) {
+    if (Array.isArray(page?.data) || typeof page?.getItems !== 'function') {
+        return listPage_wrap(page);
+    }
+    const rows = (0, adapter_1.items_get)(page)
+        .map((item) => (0, adapter_1.itemData_get)(item))
+        .filter((row) => row !== null);
+    const total = page?.totalCount;
+    return { data: rows, totalCount: typeof total === 'number' && total >= 0 ? total : null };
+}
+/**
+ * Wraps a plugin detail resource as a typed metadata handle.
+ *
+ * @param resource - The chrisapi plugin resource.
+ * @returns The typed handle.
+ */
+function pluginHandle_wrap(resource) {
+    return {
+        async parametersPage_get(params) {
+            return listPageFlexible_wrap(await (0, adapter_1.resource_call)(resource, 'getPluginParameters', params));
+        },
+        async computeResourcesPage_get(params) {
+            return listPageFlexible_wrap(await (0, adapter_1.resource_call)(resource, 'getPluginComputeResources', params));
+        },
+    };
+}
+/**
+ * Fetches one registered pipeline's detail resource as a typed handle.
+ *
+ * @param client - Connected chrisapi client.
+ * @param pipelineID - The pipeline id.
+ * @returns The typed handle, or null when CUBE returns no such pipeline.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function pipeline_get(client, pipelineID) {
+    const resource = await (0, adapter_1.resource_call)(client, 'getPipeline', pipelineID);
+    if (!resource)
+        return null;
+    return {
+        data: (0, adapter_1.itemData_get)(resource),
+        async pluginPipings_get(params) {
+            const page = await (0, adapter_1.resource_call)(resource, 'getPluginPipings', params);
+            const rawItems = typeof page?.getItems === 'function'
+                ? (0, adapter_1.items_get)(page)
+                : (0, adapter_1.listData_get)(page).map((row) => ({ data: row }));
+            return rawItems
+                .map((item) => {
+                const data = (0, adapter_1.itemData_get)(item);
+                if (!data)
+                    return null;
+                return {
+                    data,
+                    async plugin_get() {
+                        if (!(0, adapter_1.method_exists)(item, 'getPlugin'))
+                            return null;
+                        const plugin = await (0, adapter_1.resource_call)(item, 'getPlugin');
+                        return plugin ? pluginHandle_wrap(plugin) : null;
+                    },
+                };
+            })
+                .filter((item) => item !== null);
+        },
+        async defaultParametersPage_get(params) {
+            return listPageFlexible_wrap(await (0, adapter_1.resource_call)(resource, 'getDefaultParameters', params));
+        },
+    };
+}
+/**
+ * Reads one page of registered pipeline source files.
+ *
+ * @param client - Connected chrisapi client.
+ * @param params - CUBE search/pagination params (pipeline_id, limit, ...).
+ * @returns The typed source-file page.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function pipelineSourceFilesPage_get(client, params) {
+    return listPageFlexible_wrap(await (0, adapter_1.resource_call)(client, 'getPipelineSourceFiles', params));
+}
+/**
+ * Creates a CUBE download token for authenticated file access and LONK.
+ *
+ * @param client - Connected chrisapi client.
+ * @returns The token string and the token resource's REST URL.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+async function downloadToken_create(client) {
+    const resource = await (0, adapter_1.resource_call)(client, 'createDownloadToken');
+    const data = (0, adapter_1.itemData_get)(resource);
+    return {
+        token: String(data?.token ?? ''),
+        url: String(resource?.url ?? ''),
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/chrisapi/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/chrisapi/contract.ts"],"names":[],"mappings":"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"}

package/dist/connect/chrisConnection.d.ts

@@ -24,6 +24,11 @@ interface ConnectOptions {
     debug: boolean;
     url: string;
 }
+/** Credentials used to obtain a short-lived elevated CUBE token. */
+export interface ElevationCredentials {
+    username: string;
+    password: string;
+}
 /**
  * Manages the connection and authentication with a ChRIS CUBE.
  */
@@ -35,6 +40,7 @@ export declare class ChRISConnection {
     private client;
     private _config?;
     private storageProvider?;
+    private readonly elevatedClientContext;
     /**
      * Constructs a new ChRISConnection instance.
      * @param config - The connection configuration object.
@@ -89,6 +95,20 @@ export declare class ChRISConnection {
      * @returns A Promise resolving to the Client instance or null.
      */
     client_get(): Promise<Client | null>;
+    /**
+     * Executes one operation with a non-persistent CUBE client for supplied
+     * credentials. The client follows only the nested operation's asynchronous
+     * context, so concurrent normal and elevated commands retain their own
+     * identities.
+     *
+     * The normal session token, cached client, and token storage remain intact.
+     *
+     * @param credentials - Credentials for the requested CUBE identity.
+     * @param operation - Work to perform while the temporary client is active.
+     * @returns The operation's result.
+     * @throws {Error} When no CUBE URL is available or authentication fails.
+     */
+    elevation_withCredentials<T>(credentials: ElevationCredentials, operation: () => Promise<T>): Promise<T>;
     /**
      * Checks if the client is currently connected.
      * @returns True if connected, false otherwise.

package/dist/connect/chrisConnection.js

@@ -22,6 +22,7 @@ const chrisContext_js_1 = require("../context/chrisContext.js");
 const chrisIO_js_1 = require("../io/chrisIO.js");
 const errorStack_js_1 = require("../error/errorStack.js");
 const chalk_1 = __importDefault(require("chalk"));
+const node_async_hooks_1 = require("node:async_hooks");
 /**
  * Helper function to validate and format a context string.
  * @param context - The context string to check.
@@ -50,6 +51,7 @@ class ChRISConnection {
         this.user = null;
         this.chrisURL = null;
         this.client = null;
+        this.elevatedClientContext = new node_async_hooks_1.AsyncLocalStorage();
         if (config && storageProvider) {
             this.init(config, storageProvider);
         }
@@ -228,6 +230,9 @@ class ChRISConnection {
      * @returns A Promise resolving to the Client instance or null.
      */
     async client_get() {
+        const elevatedClient = this.elevatedClientContext.getStore();
+        if (elevatedClient)
+            return elevatedClient;
         if ((await this.authToken_get()) &&
             (await this.chrisURL_get()) &&
             this.chrisURL &&
@@ -238,6 +243,27 @@ class ChRISConnection {
         }
         return this.client;
     }
+    /**
+     * Executes one operation with a non-persistent CUBE client for supplied
+     * credentials. The client follows only the nested operation's asynchronous
+     * context, so concurrent normal and elevated commands retain their own
+     * identities.
+     *
+     * The normal session token, cached client, and token storage remain intact.
+     *
+     * @param credentials - Credentials for the requested CUBE identity.
+     * @param operation - Work to perform while the temporary client is active.
+     * @returns The operation's result.
+     * @throws {Error} When no CUBE URL is available or authentication fails.
+     */
+    async elevation_withCredentials(credentials, operation) {
+        const url = await this.chrisURL_get();
+        if (!url)
+            throw new Error('Not connected to ChRIS. Run connect first.');
+        const token = await (0, adapter_js_1.authToken_get)(`${url}auth-token/`, credentials.username, credentials.password);
+        const elevatedClient = (0, adapter_js_1.client_create)(url, token);
+        return await this.elevatedClientContext.run(elevatedClient, operation);
+    }
     /**
      * Checks if the client is currently connected.
      * @returns True if connected, false otherwise.
@@ -281,6 +307,13 @@ class ChRISConnection {
             this.authToken = await this.storageProvider.read(this.tokenFile);
         }
         catch (error) {
+            // A missing token file is the normal logged-out state; any other read
+            // failure (permissions, disk) must not silently present as logged-out.
+            const code = error?.code;
+            if (code !== "ENOENT") {
+                const msg = error instanceof Error ? error.message : String(error);
+                errorStack_js_1.errorStack.stack_push("warning", `Could not read auth token file ${this.tokenFile}: ${msg}`);
+            }
             this.authToken = null;
         }
     }