@walkthru-earth/objex 1.2.0 → 1.3.0

package/dist/query/stac-geoparquet.js

@@ -0,0 +1,136 @@
+/**
+ * Read a stac-geoparquet file through the existing DuckDB-WASM engine and
+ * materialize a standard STAC FeatureCollection in memory.
+ *
+ * Reuses:
+ *   - `getQueryEngine()` + `queryCancellable`/`query` for the single worker
+ *   - `resolveTableSourceAsync(tab)` for presigned `signed-s3` URL handling
+ *   - `stacRowToItem` from `utils/stac-geoparquet.js` for the pure transform
+ *   - `parseWKB` from `utils/wkb.js` for geometry decoding
+ *
+ * The returned `FeatureCollection` is the same shape `classifyStac()` returns
+ * as `{ kind: 'item-collection', fc }`, so downstream viewers
+ * (`StacMosaicViewer`, `MultiCogViewer`) consume it unchanged.
+ */
+import { stacRowToItem } from '../utils/stac-geoparquet.js';
+import { parseWKB } from '../utils/wkb.js';
+import { QueryCancelledError } from './engine.js';
+import { getQueryEngine } from './index.js';
+import { resolveTableSourceAsync } from './source.js';
+const DEFAULT_LIMIT = 2000;
+/**
+ * Build the SELECT list. All columns are optional in the stac-geoparquet
+ * spec, so we only project what we know we'll use and the spec requires.
+ * The optional `proj:*` / `raster:*` / `bands` columns are sniffed from the
+ * schema so missing columns don't trigger a DuckDB binder error.
+ */
+function buildSelectList(availableColumns) {
+    const required = [
+        'id',
+        'collection',
+        'type',
+        'stac_version',
+        'stac_extensions',
+        'assets',
+        'bbox',
+        'links'
+    ];
+    const optional = [
+        'datetime',
+        'proj:code',
+        'proj:bbox',
+        'proj:transform',
+        'proj:shape',
+        'raster:spatial_resolution',
+        'bands'
+    ];
+    const cols = [];
+    for (const name of required) {
+        if (availableColumns.has(name))
+            cols.push(quoteIdent(name));
+    }
+    for (const name of optional) {
+        if (availableColumns.has(name))
+            cols.push(quoteIdent(name));
+    }
+    // Always project geometry as WKB so parseWKB can decode it regardless of
+    // whether DuckDB presents it as the v1.5 GEOMETRY type or a plain BLOB.
+    if (availableColumns.has('geometry')) {
+        cols.push('ST_AsWKB(geometry) AS geom_wkb');
+    }
+    return cols.join(', ');
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Query a stac-geoparquet tab and return a STAC FeatureCollection whose
+ * features are proper STAC Items (assets absolutized, WKB decoded, bbox
+ * flattened).
+ *
+ * @param tab - the tab pointing at the `.parquet` file
+ * @param connId - connection id used for DuckDB's httpfs S3 config; pass
+ *   an empty string for URL-source tabs (DuckDB will use anonymous httpfs)
+ */
+export async function queryStacGeoparquetFeatureCollection(tab, connId, opts = {}) {
+    const { signal, limit = DEFAULT_LIMIT } = opts;
+    if (signal?.aborted)
+        throw new QueryCancelledError();
+    const engine = await getQueryEngine();
+    const resolved = await resolveTableSourceAsync(tab);
+    if (signal?.aborted)
+        throw new QueryCancelledError();
+    // Discover which optional columns are present so the SELECT list doesn't
+    // reference missing columns.
+    const schema = await engine.getSchema(connId, resolved);
+    if (signal?.aborted)
+        throw new QueryCancelledError();
+    const available = new Set(schema.map((f) => f.name));
+    const selectList = buildSelectList(available);
+    if (!available.has('geometry') || !available.has('assets')) {
+        throw new Error('Not a stac-geoparquet file (missing geometry or assets column)');
+    }
+    const sql = `SELECT ${selectList} FROM ${resolved.ref} LIMIT ${limit}`;
+    // Prefer cancellable path when the engine exposes it.
+    let resultPromise;
+    let cancel = null;
+    if (engine.queryCancellable) {
+        const handle = engine.queryCancellable(connId, sql);
+        cancel = handle.cancel;
+        resultPromise = handle.result;
+    }
+    else {
+        resultPromise = engine.query(connId, sql);
+    }
+    const onAbort = () => {
+        cancel?.().catch(() => { });
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    let rows;
+    try {
+        const result = await resultPromise;
+        rows = result.rows ?? [];
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
+    if (signal?.aborted)
+        throw new QueryCancelledError();
+    // Asset hrefs in stac-geoparquet are typically written relative to each
+    // item's original `self` URL, not the parquet URL. The stactools default
+    // layout places each item JSON at `{catalog_dir}/{item.id}/{item.id}.json`,
+    // so a per-row base of `{parquet_dir}/{item.id}/` resolves `./foo.tif` to
+    // `{parquet_dir}/{item.id}/foo.tif`. Absolute hrefs pass through unchanged
+    // via `resolveStacAssetHref`.
+    const parquetUrl = resolved.fileUrl ?? tab.path;
+    const parquetDir = parquetUrl.replace(/[^/]*(?:\?.*)?$/, '');
+    const features = rows.map((row) => {
+        const id = typeof row.id === 'string' ? row.id : String(row.id ?? '');
+        const itemBase = id ? `${parquetDir}${id}/` : parquetUrl;
+        return stacRowToItem(row, itemBase, { wkbParser: parseWKB });
+    });
+    return {
+        type: 'FeatureCollection',
+        features
+    };
+}

package/dist/query/wasm.js

@@ -1,8 +1,9 @@
 import { DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, WGS84_CODES } from '../constants.js';
-import { getAccessMode } from '../storage/providers.js';
+import { getAccessMode, resolveProviderEndpoint } from '../storage/providers.js';
 import { credentialStore } from '../stores/credentials.svelte.js';
 import { buildTransformExpr, wrapWkbWithCrs } from '../utils/geometry-type.js';
 import { QueryCancelledError } from './engine';
+import { isHttpsSourceRef } from './source.js';
 const DUCKDB_VERSION = __DUCKDB_WASM_VERSION__;
 const CDN_BASE = `https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@${DUCKDB_VERSION}/dist`;
 const duckdb_wasm = `${CDN_BASE}/duckdb-mvp.wasm`;
@@ -234,13 +235,18 @@ async function extractCrsFromLogicalType(logicalType, conn, path) {
 // DuckDB Arrow type strings that represent binary/blob data — not useful
 // for map tooltips and expensive to extract row-by-row.
 const BINARY_TYPES = new Set(['BLOB', 'BYTEA', 'BINARY', 'LARGEBINARY', 'WKB_BLOB']);
-/** True if the Arrow type string represents a numeric primitive (zero-copy .toArray()). */
+/**
+ * True if the Arrow type string represents a numeric primitive whose `.toArray()`
+ * returns a plain typed array (zero-copy fast path). DECIMAL is excluded: Arrow
+ * emits decimals as multi-word BigInt buffers that need scale-aware formatting.
+ */
 function isNumericArrowType(typeStr) {
     const t = typeStr.toUpperCase();
+    if (t.startsWith('DECIMAL'))
+        return false;
     return (t.includes('INT') ||
         t.includes('FLOAT') ||
         t.includes('DOUBLE') ||
-        t.includes('DECIMAL') ||
         t === 'TINYINT' ||
         t === 'SMALLINT' ||
         t === 'BIGINT' ||
@@ -250,6 +256,53 @@ function isNumericArrowType(typeStr) {
         t === 'USMALLINT' ||
         t === 'UTINYINT');
 }
+/**
+ * Parse DuckDB/Arrow DECIMAL type string → scale. Returns -1 if not a decimal.
+ *
+ * DuckDB DESCRIBE emits `DECIMAL(10,2)`. Arrow's `Decimal.toString()` emits
+ * `Decimal[10e+2]` (precision `e` signed-scale). Accept both.
+ */
+function decimalScale(typeStr) {
+    const m = /^(?:DECIMAL\(\s*\d+\s*,\s*(-?\d+)\s*\)|Decimal\[\s*\d+e([+-]?\d+)\s*\])/i.exec(typeStr);
+    if (!m)
+        return -1;
+    return Number(m[1] ?? m[2]);
+}
+/**
+ * Format an Arrow Decimal value (BigInt or Uint32Array of little-endian words)
+ * into a human-readable decimal string, applying the column scale.
+ */
+function formatDecimal(raw, scale) {
+    if (raw == null)
+        return null;
+    let bn;
+    if (typeof raw === 'bigint') {
+        bn = raw;
+    }
+    else if (raw instanceof Uint32Array || raw instanceof Int32Array) {
+        const hi = BigInt(raw[raw.length - 1] >>> 0);
+        const signed = hi >= 0x80000000n;
+        let acc = 0n;
+        for (let w = raw.length - 1; w >= 0; w--) {
+            acc = (acc << 32n) | BigInt(raw[w] >>> 0);
+        }
+        bn = signed ? acc - (1n << BigInt(raw.length * 32)) : acc;
+    }
+    else if (typeof raw === 'number') {
+        bn = BigInt(raw);
+    }
+    else {
+        return String(raw);
+    }
+    const neg = bn < 0n;
+    const abs = neg ? -bn : bn;
+    if (scale <= 0)
+        return (neg ? '-' : '') + abs.toString();
+    const divisor = 10n ** BigInt(scale);
+    const intPart = abs / divisor;
+    const fracPart = (abs % divisor).toString().padStart(scale, '0');
+    return `${neg ? '-' : ''}${intPart}.${fracPart}`;
+}
 /**
  * Extract column values using the fastest available method:
  * - Numeric primitives → .toArray() returns a typed array view (zero-copy),
@@ -257,6 +310,14 @@ function isNumericArrowType(typeStr) {
  * - Other types → per-element .get(i) for correctness (strings, structs, etc.)
  */
 function extractColumnBulk(col, numRows, typeStr) {
+    const scale = decimalScale(typeStr);
+    if (scale >= 0) {
+        const values = new Array(numRows);
+        for (let i = 0; i < numRows; i++) {
+            values[i] = formatDecimal(col.get(i), scale);
+        }
+        return values;
+    }
     if (isNumericArrowType(typeStr)) {
         // .toArray() returns a TypedArray (Float64Array, Int32Array, etc.)
         // which is a zero-copy view over the Arrow buffer.
@@ -273,6 +334,13 @@ function extractColumnBulk(col, numRows, typeStr) {
  * Same optimisation as extractColumnBulk but appends instead of creating new.
  */
 function appendColumnBulk(target, col, numRows, typeStr) {
+    const scale = decimalScale(typeStr);
+    if (scale >= 0) {
+        for (let i = 0; i < numRows; i++) {
+            target.push(formatDecimal(col.get(i), scale));
+        }
+        return;
+    }
     if (isNumericArrowType(typeStr)) {
         const arr = col.toArray();
         for (let i = 0; i < arr.length; i++) {
@@ -299,7 +367,7 @@ export class WasmQueryEngine {
         log(`query → connected in ${elapsed(t0)}`);
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, sql);
                 log(`query → storage configured in ${elapsed(tConn)}`);
             }
             const tQuery = performance.now();
@@ -320,14 +388,25 @@ export class WasmQueryEngine {
                     rows: []
                 };
             }
+            // Arrow emits DECIMAL columns as multi-word BigInt / Uint32Array buffers.
+            // `String(rawDecimal)` yields the unscaled integer (or "0,0,0,0"),
+            // so rewrite each decimal cell through formatDecimal with the column scale.
+            const decimalCols = [];
+            for (let i = 0; i < cols.length; i++) {
+                const s = decimalScale(types[i]);
+                if (s >= 0)
+                    decimalCols.push({ name: cols[i], scale: s });
+            }
             // Extract rows directly — avoids Arrow version mismatch
             const rows = result.toArray().map((row) => {
-                if (typeof row.toJSON === 'function')
-                    return row.toJSON();
-                // Fallback: manually build row object
-                const obj = {};
-                for (const col of cols)
-                    obj[col] = row[col];
+                const obj = typeof row.toJSON === 'function' ? row.toJSON() : {};
+                if (typeof row.toJSON !== 'function') {
+                    for (const col of cols)
+                        obj[col] = row[col];
+                }
+                for (const { name, scale } of decimalCols) {
+                    obj[name] = formatDecimal(obj[name], scale);
+                }
                 return obj;
             });
             log(`query → done in ${elapsed(t0)}, ${numRows} rows, ${cols.length} cols`);
@@ -348,7 +427,7 @@ export class WasmQueryEngine {
         const conn = await db.connect();
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, sql);
             }
             // Build geometry expression based on column type:
             // - Native spatial types (GEOMETRY, GEOMETRY('EPSG:...'), WKB_BLOB, etc.) → use directly
@@ -442,7 +521,7 @@ export class WasmQueryEngine {
         const conn = await db.connect();
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, source.ref);
             }
             const result = await conn.query(`DESCRIBE SELECT * FROM ${source.ref}`);
             const rows = result.toArray();
@@ -469,7 +548,7 @@ export class WasmQueryEngine {
         const conn = await db.connect();
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, source.ref);
             }
             // For Parquet files, try reading row count from file footer metadata first.
             // This avoids parsing column types (which can fail on exotic geometry types)
@@ -510,7 +589,7 @@ export class WasmQueryEngine {
         const conn = await db.connect();
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, source.ref);
             }
             // Schema detection
             const tSchema = performance.now();
@@ -543,9 +622,18 @@ export class WasmQueryEngine {
             await conn.close();
         }
     }
-    async configureStorage(conn, connId) {
+    async configureStorage(conn, connId, sourceRef) {
         try {
-            // Read connection metadata from localStorage
+            // Defensive: callers may pass a destroyed Svelte $derived (returns a
+            // Symbol sentinel) across async boundaries. Template literals below
+            // would throw "can't convert symbol to string" and pollute logs.
+            if (typeof connId !== 'string' || !connId)
+                return;
+            // Presigned HTTPS refs are self-authenticating; no S3 SETs needed.
+            if (sourceRef && isHttpsSourceRef(sourceRef)) {
+                log('configureStorage → presigned HTTPS source, skipping S3 config');
+                return;
+            }
             const stored = localStorage.getItem('obstore-explore-connections');
             if (!stored) {
                 log('configureStorage → no connections in localStorage');
@@ -577,10 +665,16 @@ export class WasmQueryEngine {
             if (connection.region) {
                 sets.push(`SET s3_region = '${connection.region}'`);
             }
-            if (connection.endpoint) {
-                const endpoint = connection.endpoint.replace(/^https?:\/\//, '');
-                sets.push(`SET s3_endpoint = '${endpoint}'`);
-                if (connection.endpoint.startsWith('http://')) {
+            // Non-AWS providers with an empty `endpoint` field fall back to the
+            // provider registry's template, otherwise DuckDB routes them to AWS.
+            let endpoint = connection.endpoint;
+            if (!endpoint && connection.provider && connection.provider !== 's3') {
+                endpoint = resolveProviderEndpoint(connection.provider, connection.region);
+            }
+            if (endpoint) {
+                const endpointHost = endpoint.replace(/^https?:\/\//, '');
+                sets.push(`SET s3_endpoint = '${endpointHost}'`);
+                if (endpoint.startsWith('http://')) {
                     sets.push(`SET s3_use_ssl = false`);
                 }
             }
@@ -603,7 +697,7 @@ export class WasmQueryEngine {
         const conn = await db.connect();
         try {
             if (connId) {
-                await this.configureStorage(conn, connId);
+                await this.configureStorage(conn, connId, source.ref);
             }
             const crs = await this.detectCrsWithConn(conn, source, geomCol);
             log(`detectCrs → ${crs ?? 'WGS84/null'} in ${elapsed(t0)}`);
@@ -706,7 +800,7 @@ export class WasmQueryEngine {
             log(`queryCancellable → connected in ${elapsed(t0)}`);
             try {
                 if (connId) {
-                    await this.configureStorage(conn, connId);
+                    await this.configureStorage(conn, connId, sql);
                 }
                 const tQuery = performance.now();
                 const reader = await conn.send(sql);
@@ -714,6 +808,7 @@ export class WasmQueryEngine {
                 const rows = [];
                 let cols = [];
                 let types = [];
+                let decimalCols = [];
                 const batches = reader[Symbol.asyncIterator]();
                 let first = true;
                 while (true) {
@@ -725,6 +820,12 @@ export class WasmQueryEngine {
                     if (first && batch.schema) {
                         cols = batch.schema.fields.map((f) => f.name);
                         types = batch.schema.fields.map((f) => String(f.type));
+                        decimalCols = [];
+                        for (let i = 0; i < cols.length; i++) {
+                            const s = decimalScale(types[i]);
+                            if (s >= 0)
+                                decimalCols.push({ name: cols[i], scale: s });
+                        }
                         first = false;
                     }
                     for (const row of batch.toArray()) {
@@ -738,6 +839,12 @@ export class WasmQueryEngine {
                                 json[key] = json[key].slice();
                             }
                         }
+                        // DECIMAL raw values are BigInt / Uint32Array (unscaled). Convert
+                        // to a human-readable string via formatDecimal — also drops the
+                        // Uint32Array view, so stale-buffer reuse across batches is moot.
+                        for (const { name, scale } of decimalCols) {
+                            json[name] = formatDecimal(json[name], scale);
+                        }
                         rows.push(json);
                     }
                 }
@@ -780,7 +887,7 @@ export class WasmQueryEngine {
             conn = await db.connect();
             try {
                 if (connId) {
-                    await this.configureStorage(conn, connId);
+                    await this.configureStorage(conn, connId, sql);
                 }
                 // Build geometry expression (same logic as queryForMap)
                 const quoted = `"${geomCol}"`;

package/dist/storage/adapter.d.ts

@@ -5,6 +5,15 @@ export interface ListPage {
     continuationToken?: string;
     hasMore: boolean;
 }
+/**
+ * Thrown by adapters when the server returns 401 or 403 on an anonymous
+ * request. The browser store catches this to trigger a credential prompt
+ * for auto-detected `?url=` connections that turned out to be private.
+ */
+export declare class AuthRequiredError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
 export interface StorageAdapter {
     list(path: string, signal?: AbortSignal): Promise<FileEntry[]>;
     read(path: string, offset?: number, length?: number, signal?: AbortSignal): Promise<Uint8Array>;

package/dist/storage/adapter.js

@@ -1 +1,13 @@
-export {};
+/**
+ * Thrown by adapters when the server returns 401 or 403 on an anonymous
+ * request. The browser store catches this to trigger a credential prompt
+ * for auto-detected `?url=` connections that turned out to be private.
+ */
+export class AuthRequiredError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'AuthRequiredError';
+        this.status = status;
+    }
+}

package/dist/storage/browser-azure.d.ts

@@ -1,5 +1,5 @@
 import type { FileEntry, WriteResult } from '../types.js';
-import type { ListPage, StorageAdapter } from './adapter.js';
+import { type ListPage, type StorageAdapter } from './adapter.js';
 /**
  * Browser-based Azure Blob Storage adapter.
  *

package/dist/storage/browser-azure.js

@@ -1,5 +1,6 @@
 import { connectionStore } from '../stores/connections.svelte.js';
 import { credentialStore } from '../stores/credentials.svelte.js';
+import { AuthRequiredError } from './adapter.js';
 // --- Helpers ---
 function nameFromKey(key) {
     const trimmed = key.replace(/\/$/, '');
@@ -92,6 +93,9 @@ export class BrowserAzureAdapter {
         const res = await fetch(url, { signal });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
+            if (res.status === 401 || res.status === 403) {
+                throw new AuthRequiredError(res.status, `Azure list failed (${res.status}): ${body || res.statusText}`);
+            }
             throw new Error(`Azure list failed (${res.status}): ${body || res.statusText}`);
         }
         const xml = await res.text();

package/dist/storage/browser-cloud.d.ts

@@ -1,5 +1,5 @@
 import type { FileEntry, WriteResult } from '../types.js';
-import type { ListPage, StorageAdapter } from './adapter.js';
+import { type ListPage, type StorageAdapter } from './adapter.js';
 /**
  * Browser-based cloud storage adapter (S3-compatible).
  *

package/dist/storage/browser-cloud.js

@@ -1,6 +1,7 @@
 import { AwsClient } from 'aws4fetch';
 import { connectionStore } from '../stores/connections.svelte.js';
 import { credentialStore } from '../stores/credentials.svelte.js';
+import { AuthRequiredError } from './adapter.js';
 import { buildProviderBaseUrl, isGcsProvider } from './providers.js';
 // --- Helpers ---
 /** Extract the last path segment from an object key. */
@@ -128,6 +129,9 @@ export class BrowserCloudAdapter {
         const res = await fetch(`${url}?${params}`, { signal });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
+            if (res.status === 401 || res.status === 403) {
+                throw new AuthRequiredError(res.status, `GCS list failed (${res.status}): ${body || res.statusText}`);
+            }
             throw new Error(`GCS list failed (${res.status}): ${body || res.statusText}`);
         }
         const json = await res.json();
@@ -185,6 +189,9 @@ export class BrowserCloudAdapter {
         const res = await cloudFetch(`${baseUrl}?${params}`, { signal });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
+            if (res.status === 401 || res.status === 403) {
+                throw new AuthRequiredError(res.status, `List failed (${res.status}): ${body || res.statusText}`);
+            }
             throw new Error(`List failed (${res.status}): ${body || res.statusText}`);
         }
         const xml = await res.text();

package/dist/storage/presign.d.ts

@@ -0,0 +1,13 @@
+import type { Connection } from '../types.js';
+/**
+ * Presign an HTTPS URL using SigV4 query-string authentication (`X-Amz-*` params).
+ *
+ * Consumers like DuckDB's httpfs can fetch the returned URL directly with just a
+ * `Range` header, which avoids the `Authorization` header preflight that breaks
+ * on GCS's S3-compatible endpoint (cached preflight mismatches, `responseHeader`
+ * list not matching the browser's requested headers, etc.).
+ *
+ * Returns null when the connection is anonymous, Azure, or has no SigV4 creds.
+ * Callers should fall back to the `s3://` + SigV4 header path in that case.
+ */
+export declare function presignHttpsUrl(conn: Connection, key: string, expiresIn?: number): Promise<string | null>;

package/dist/storage/presign.js

@@ -0,0 +1,55 @@
+import { credentialStore } from '../stores/credentials.svelte.js';
+import { safeDecodeURIComponent } from '../utils/cloud-url.js';
+import { buildProviderBaseUrl, getAccessMode } from './providers.js';
+// 7 days is the SigV4 protocol maximum and is the hard cap on every
+// S3-compatible provider we support (AWS, GCS, R2, B2, DO, Wasabi, Storj,
+// Hetzner, Contabo, Linode, OVHcloud, MinIO). SDK defaults are lower
+// (GCS ships 3600s) but that's a default, not a limit.
+const MAX_EXPIRES_IN_SECONDS = 7 * 24 * 3600;
+const DEFAULT_EXPIRES_IN_SECONDS = MAX_EXPIRES_IN_SECONDS;
+/**
+ * Presign an HTTPS URL using SigV4 query-string authentication (`X-Amz-*` params).
+ *
+ * Consumers like DuckDB's httpfs can fetch the returned URL directly with just a
+ * `Range` header, which avoids the `Authorization` header preflight that breaks
+ * on GCS's S3-compatible endpoint (cached preflight mismatches, `responseHeader`
+ * list not matching the browser's requested headers, etc.).
+ *
+ * Returns null when the connection is anonymous, Azure, or has no SigV4 creds.
+ * Callers should fall back to the `s3://` + SigV4 header path in that case.
+ */
+export async function presignHttpsUrl(conn, key, expiresIn = DEFAULT_EXPIRES_IN_SECONDS) {
+    if (getAccessMode(conn) !== 'signed-s3')
+        return null;
+    const creds = credentialStore.get(conn.id);
+    if (!creds || creds.type !== 'sigv4')
+        return null;
+    const cleanKey = safeDecodeURIComponent(key.replace(/^\//, ''));
+    const baseUrl = buildProviderBaseUrl(conn.provider, conn.endpoint, conn.bucket, conn.region);
+    const url = new URL(`${baseUrl}/${encodeKey(cleanKey)}`);
+    // Clamp to the protocol max so callers asking for longer don't silently
+    // produce URLs every provider rejects.
+    const effectiveExpiry = Math.min(Math.max(1, expiresIn), MAX_EXPIRES_IN_SECONDS);
+    url.searchParams.set('X-Amz-Expires', String(effectiveExpiry));
+    // Lazy-load aws4fetch so public-only sessions don't pull it into the
+    // shared viewer chunk (utils/url.ts is imported widely).
+    const { AwsClient } = await import('aws4fetch');
+    const client = new AwsClient({
+        accessKeyId: creds.accessKey,
+        secretAccessKey: creds.secretKey,
+        service: 's3',
+        region: conn.region || 'us-east-1'
+    });
+    const signed = await client.sign(url.toString(), {
+        method: 'GET',
+        aws: { signQuery: true, allHeaders: false }
+    });
+    return signed.url;
+}
+/** Encode an object key for URL path, preserving `/` separators. */
+function encodeKey(key) {
+    return key
+        .split('/')
+        .map((s) => encodeURIComponent(s))
+        .join('/');
+}

package/dist/storage/providers.d.ts

@@ -64,6 +64,12 @@ export declare const PROVIDER_IDS: ProviderId[];
 export declare function getProvider(id: string): ProviderDef;
 /** Build endpoint URL from template + region. */
 export declare function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+/**
+ * Resolve an endpoint URL for a provider using its registered template,
+ * falling back to the provider's default region when none is supplied.
+ * Returns '' when the provider has no template (e.g. plain S3 or MinIO).
+ */
+export declare function resolveProviderEndpoint(provider: string, region?: string): string;
 /**
  * Build the base URL for API requests (endpoint + bucket).
  * Used by browser-cloud adapter and url-state.

package/dist/storage/providers.js

@@ -275,9 +275,9 @@ export const CORS_HELP = {
     gcs: {
         defaultEnabled: false,
         docsUrl: 'https://cloud.google.com/storage/docs/using-cors',
-        note: 'CORS cannot be configured via the Cloud Console. Use the gcloud CLI.',
+        note: 'Use the gcloud CLI. GCS `responseHeader` is dual-purpose (Access-Control-Expose-Headers AND Access-Control-Allow-Headers), so every request header the browser sends must be listed or the preflight fails silently. For private buckets signed with HMAC, include the AWS SigV4 headers (Authorization, x-amz-date, x-amz-content-sha256). For DuckDB httpfs partial reads, also include Range and the conditional If-* headers.',
         cliSteps: [
-            'Create a cors.json file:\n[\n  {\n    "origin": ["*"],\n    "method": ["GET", "HEAD"],\n    "responseHeader": [\n      "Content-Type",\n      "Content-Length",\n      "Content-Range",\n      "Accept-Ranges",\n      "ETag"\n    ],\n    "maxAgeSeconds": 3600\n  }\n]',
+            'Create a cors.json file:\n[\n  {\n    "origin": ["*"],\n    "method": ["GET", "HEAD"],\n    "responseHeader": [\n      "Content-Type",\n      "Content-Length",\n      "Content-Range",\n      "Accept-Ranges",\n      "Range",\n      "If-Match",\n      "If-Modified-Since",\n      "If-None-Match",\n      "If-Unmodified-Since",\n      "ETag",\n      "Authorization",\n      "x-amz-content-sha256",\n      "x-amz-date",\n      "x-amz-*",\n      "x-goog-*"\n    ],\n    "maxAgeSeconds": 3600\n  }\n]',
             'gcloud storage buckets update gs://BUCKET --cors-file=cors.json'
         ]
     },
@@ -438,6 +438,17 @@ export function buildEndpointFromTemplate(id, region) {
         return '';
     return def.endpointTemplate.replace('{region}', region);
 }
+/**
+ * Resolve an endpoint URL for a provider using its registered template,
+ * falling back to the provider's default region when none is supplied.
+ * Returns '' when the provider has no template (e.g. plain S3 or MinIO).
+ */
+export function resolveProviderEndpoint(provider, region) {
+    const def = PROVIDERS[provider];
+    if (!def?.endpointTemplate)
+        return '';
+    return buildEndpointFromTemplate(provider, region || def.defaultRegion);
+}
 /**
  * Build the base URL for API requests (endpoint + bucket).
  * Used by browser-cloud adapter and url-state.

package/dist/stores/browser.svelte.d.ts

@@ -11,6 +11,8 @@ export declare const browser: {
         total: number;
     };
     readonly canWrite: boolean;
+    readonly authRequired: Connection | null;
+    clearAuthRequired: () => void;
     browse: (connection: Connection, prefix?: string) => Promise<void>;
     navigateTo: (prefix: string) => Promise<void>;
     navigateUp: () => Promise<void>;