@walkthru-earth/objex 1.1.0 → 1.2.1

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

@@ -38,12 +38,38 @@ export interface ProviderDef {
     schemes: string[];
 }
 export declare const PROVIDERS: Record<ProviderId, ProviderDef>;
+export interface CorsHelp {
+    /** True if the provider returns CORS headers by default. */
+    defaultEnabled: boolean;
+    /** Official CORS configuration docs URL. */
+    docsUrl?: string;
+    /** Brief note shown in the UI. */
+    note?: string;
+    /** CLI steps when no console UI or docs are insufficient. */
+    cliSteps?: string[];
+}
+export declare const CORS_HELP: Record<ProviderId, CorsHelp>;
+export interface ReadOnlyHelp {
+    /** Brief note shown in the UI. */
+    note: string;
+    /** Official docs URL. */
+    docsUrl?: string;
+    /** CLI steps to apply a read-only bucket policy. */
+    cliSteps?: string[];
+}
+export declare const READ_ONLY_HELP: Partial<Record<ProviderId, ReadOnlyHelp>>;
 /** All provider IDs, ordered for the UI. */
 export declare const PROVIDER_IDS: ProviderId[];
 /** Get provider def, falling back to S3 for unknown. */
 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.
@@ -51,3 +77,30 @@ export declare function buildEndpointFromTemplate(id: ProviderId, region: string
 export declare function buildProviderBaseUrl(provider: ProviderId, endpoint: string, bucket: string, region: string): string;
 /** Check if a provider uses the GCS JSON API (not S3 XML). */
 export declare function isGcsProvider(provider: string, endpoint: string): boolean;
+/**
+ * Minimal connection shape needed to decide access mode.
+ * Kept loose so callers don't need to import the full Connection type.
+ */
+export interface AccessModeInput {
+    provider: string;
+    anonymous?: boolean;
+    endpoint?: string;
+}
+/**
+ * How a connection's files can be read by the browser:
+ *
+ * - `public-https`: plain HTTPS via any HTTP client. No auth, no signing.
+ *   Covers anonymous AWS/GCS/R2/Storj/Wasabi/etc.
+ * - `sas-https`: HTTPS with SAS token embedded in the URL. Still works with
+ *   any HTTP client. Azure only.
+ * - `signed-s3`: requires SigV4 signing. DuckDB uses the `s3://` URI and
+ *   signs it via its S3 config; other viewers must go through the storage
+ *   adapter (which returns a blob) instead of streaming the HTTPS URL.
+ */
+export type AccessMode = 'public-https' | 'sas-https' | 'signed-s3';
+export declare function getAccessMode(conn: AccessModeInput): AccessMode;
+/**
+ * True when the connection's files can be fetched by any HTTP client
+ * (fetch/img/video/DuckDB httpfs/COG/Zarr/etc.) without the storage adapter.
+ */
+export declare function isPubliclyStreamable(conn: AccessModeInput): boolean;

package/dist/storage/providers.js

@@ -266,6 +266,148 @@ export const PROVIDERS = {
         schemes: []
     }
 };
+export const CORS_HELP = {
+    s3: {
+        defaultEnabled: false,
+        docsUrl: 'https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html',
+        note: 'Enable via S3 Console: Bucket > Permissions > CORS, or use the AWS CLI.'
+    },
+    gcs: {
+        defaultEnabled: false,
+        docsUrl: 'https://cloud.google.com/storage/docs/using-cors',
+        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      "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'
+        ]
+    },
+    r2: {
+        defaultEnabled: false,
+        docsUrl: 'https://developers.cloudflare.com/r2/buckets/cors/',
+        note: 'Enable via R2 Dashboard: Bucket > Settings > CORS Policy.'
+    },
+    azure: {
+        defaultEnabled: false,
+        docsUrl: 'https://learn.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services',
+        note: 'Enable via Azure Portal: Storage Account > Blob Service > CORS, or use the Azure CLI.',
+        cliSteps: [
+            'az storage cors add --services b --methods GET HEAD \\\n  --origins "*" --allowed-headers "*" \\\n  --exposed-headers "*" --max-age 3600 \\\n  --account-name ACCOUNT'
+        ]
+    },
+    minio: {
+        defaultEnabled: true,
+        docsUrl: 'https://docs.min.io/enterprise/aistor-object-store/reference/cli/mc-cors/',
+        note: 'MinIO allows all origins by default. For custom rules, use mc cors set.'
+    },
+    storj: {
+        defaultEnabled: true,
+        note: 'Storj S3 gateway returns CORS headers by default.'
+    },
+    b2: {
+        defaultEnabled: false,
+        docsUrl: 'https://www.backblaze.com/docs/cloud-storage-cross-origin-resource-sharing-rules',
+        note: 'Enable via B2 Console: Bucket Settings > CORS Rules, or use the B2 CLI.',
+        cliSteps: [
+            'b2 bucket update --cors-rules \'[{\n  "corsRuleName": "allow-all",\n  "allowedOrigins": ["*"],\n  "allowedOperations": ["s3_head", "s3_get"],\n  "allowedHeaders": ["*"],\n  "maxAgeSeconds": 3600\n}]\' BUCKET allPublic'
+        ]
+    },
+    digitalocean: {
+        defaultEnabled: false,
+        docsUrl: 'https://docs.digitalocean.com/products/spaces/how-to/configure-cors/',
+        note: 'Enable via Control Panel: Space > Settings > CORS Configurations.'
+    },
+    wasabi: {
+        defaultEnabled: true,
+        docsUrl: 'https://docs.wasabi.com/docs/bucket-policy',
+        note: 'Wasabi returns CORS headers by default for all buckets.'
+    },
+    contabo: {
+        defaultEnabled: false,
+        note: 'S3-compatible CORS via the AWS CLI.',
+        cliSteps: [
+            'Create a cors.json file:\n{\n  "CORSRules": [{\n    "AllowedOrigins": ["*"],\n    "AllowedMethods": ["GET", "HEAD"],\n    "AllowedHeaders": ["*"],\n    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Content-Range", "Accept-Ranges"],\n    "MaxAgeSeconds": 3600\n  }]\n}',
+            'aws s3api put-bucket-cors --bucket BUCKET \\\n  --cors-configuration file://cors.json \\\n  --endpoint-url https://REGION.contaboobj.com'
+        ]
+    },
+    hetzner: {
+        defaultEnabled: false,
+        docsUrl: 'https://docs.hetzner.com/storage/object-storage/howto-protect-objects/cors/',
+        note: 'S3-compatible CORS via the AWS CLI.',
+        cliSteps: [
+            'Create a cors.json file:\n{\n  "CORSRules": [{\n    "AllowedOrigins": ["*"],\n    "AllowedMethods": ["GET", "HEAD"],\n    "AllowedHeaders": ["*"],\n    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Content-Range", "Accept-Ranges"],\n    "MaxAgeSeconds": 3600\n  }]\n}',
+            'aws s3api put-bucket-cors --bucket BUCKET \\\n  --cors-configuration file://cors.json \\\n  --endpoint-url https://REGION.your-objectstorage.com \\\n  --region REGION'
+        ]
+    },
+    linode: {
+        defaultEnabled: false,
+        docsUrl: 'https://www.linode.com/docs/guides/working-with-cors-linode-object-storage/',
+        note: 'S3-compatible CORS via the AWS CLI.',
+        cliSteps: [
+            'Create a cors.json file:\n{\n  "CORSRules": [{\n    "AllowedOrigins": ["*"],\n    "AllowedMethods": ["GET", "HEAD"],\n    "AllowedHeaders": ["*"],\n    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Content-Range", "Accept-Ranges"],\n    "MaxAgeSeconds": 3600\n  }]\n}',
+            'aws s3api put-bucket-cors --bucket BUCKET \\\n  --cors-configuration file://cors.json \\\n  --endpoint-url https://REGION.linodeobjects.com'
+        ]
+    },
+    ovhcloud: {
+        defaultEnabled: false,
+        docsUrl: 'https://help.ovhcloud.com/csm/en-public-cloud-storage-s3-cors?id=kb_article_view&sysparm_article=KB0058291',
+        note: 'S3-compatible CORS via the AWS CLI.',
+        cliSteps: [
+            'Create a cors.json file:\n{\n  "CORSRules": [{\n    "AllowedOrigins": ["*"],\n    "AllowedMethods": ["GET", "HEAD"],\n    "AllowedHeaders": ["*"],\n    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Content-Range", "Accept-Ranges"],\n    "MaxAgeSeconds": 3600\n  }]\n}',
+            'aws s3api put-bucket-cors --bucket BUCKET \\\n  --cors-configuration file://cors.json \\\n  --endpoint-url https://s3.REGION.io.cloud.ovh.net'
+        ]
+    }
+};
+export const READ_ONLY_HELP = {
+    s3: {
+        note: 'Use IAM policies to create a read-only user, or apply a bucket policy that allows only s3:GetObject and s3:ListBucket.',
+        docsUrl: 'https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-policies-s3.html'
+    },
+    gcs: {
+        note: 'Assign the Storage Object Viewer role (roles/storage.objectViewer) to the service account.',
+        docsUrl: 'https://cloud.google.com/storage/docs/access-control/iam-roles'
+    },
+    r2: {
+        note: 'Create an API token with Object Read permissions in the R2 dashboard.',
+        docsUrl: 'https://developers.cloudflare.com/r2/api/tokens/'
+    },
+    azure: {
+        note: 'Generate a SAS token with Read and List permissions only. Avoid granting Write or Delete.',
+        docsUrl: 'https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview'
+    },
+    b2: {
+        note: 'Create an application key with readFiles and listBuckets capabilities only.',
+        docsUrl: 'https://www.backblaze.com/docs/cloud-storage-application-keys'
+    },
+    hetzner: {
+        note: 'Keys have full read/write by default. Use a bucket policy with the correct ARN format to deny write and policy actions. To undo, generate a new admin key from the Hetzner Console.',
+        docsUrl: 'https://docs.hetzner.com/storage/object-storage/faq/s3-credentials/#how-do-i-restrict-access-per-key',
+        cliSteps: [
+            'Find your project ID from the Hetzner Console URL:\nhttps://console.hetzner.com/projects/<PROJECT_ID>/servers',
+            'Create a policy.json file:\n{\n  "Version": "2012-10-17",\n  "Statement": [\n    {\n      "Sid": "DenyWrites",\n      "Effect": "Deny",\n      "Principal": {\n        "AWS": "arn:aws:iam:::user/p<PROJECT_ID>:<ACCESS_KEY>"\n      },\n      "Action": [\n        "s3:PutObject",\n        "s3:DeleteObject",\n        "s3:AbortMultipartUpload",\n        "s3:PutBucketPolicy",\n        "s3:DeleteBucketPolicy"\n      ],\n      "Resource": [\n        "arn:aws:s3:::BUCKET",\n        "arn:aws:s3:::BUCKET/*"\n      ]\n    }\n  ]\n}',
+            'aws s3api put-bucket-policy --bucket BUCKET \\\n  --policy file://policy.json \\\n  --endpoint-url https://REGION.your-objectstorage.com \\\n  --region REGION',
+            'Note: This key can no longer modify the policy.\nTo restore write access, generate a new key in the\nHetzner Console and use it to delete the policy.'
+        ]
+    },
+    minio: {
+        note: 'Create a read-only policy with mc admin policy, or use the built-in readonly canned policy.',
+        docsUrl: 'https://docs.min.io/enterprise/aistor-object-store/administration/iam/access/'
+    },
+    digitalocean: {
+        note: 'Spaces keys are project-wide. Use a bucket policy to restrict write actions for a specific key.',
+        docsUrl: 'https://docs.digitalocean.com/products/spaces/how-to/manage-access/'
+    },
+    wasabi: {
+        note: 'Create a sub-user with a read-only policy in the Wasabi Console.',
+        docsUrl: 'https://docs.wasabi.com/docs/creating-a-user-account-and-access-key'
+    },
+    contabo: {
+        note: 'S3-compatible bucket policies. Use a Deny policy for write actions with the key ARN.',
+        cliSteps: [
+            'Create a policy.json with a Deny statement for s3:PutObject and s3:DeleteObject.',
+            'aws s3api put-bucket-policy --bucket BUCKET \\\n  --policy file://policy.json \\\n  --endpoint-url https://REGION.contaboobj.com'
+        ]
+    }
+};
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -296,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.
@@ -316,3 +469,21 @@ export function buildProviderBaseUrl(provider, endpoint, bucket, region) {
 export function isGcsProvider(provider, endpoint) {
     return provider === 'gcs' || (!!endpoint && /storage\.googleapis\.com/i.test(endpoint));
 }
+export function getAccessMode(conn) {
+    if (conn.provider === 'azure')
+        return 'sas-https';
+    // Anonymous buckets: every provider serves files over plain HTTPS without
+    // signing (AWS path/vhost, GCS, R2 public, Storj, Wasabi, DO, etc.).
+    if (conn.anonymous)
+        return 'public-https';
+    // Authenticated: needs SigV4 signing.
+    return 'signed-s3';
+}
+/**
+ * True when the connection's files can be fetched by any HTTP client
+ * (fetch/img/video/DuckDB httpfs/COG/Zarr/etc.) without the storage adapter.
+ */
+export function isPubliclyStreamable(conn) {
+    const mode = getAccessMode(conn);
+    return mode === 'public-https' || mode === 'sas-https';
+}

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>;

package/dist/stores/browser.svelte.js

@@ -1,3 +1,4 @@
+import { AuthRequiredError } from '../storage/adapter.js';
 import { getAdapter } from '../storage/index.js';
 import { credentialStore } from './credentials.svelte.js';
 import { safeLock } from './safelock.svelte.js';
@@ -7,6 +8,7 @@ function createBrowserStore() {
     let entries = $state([]);
     let loading = $state(false);
     let error = $state(null);
+    let authRequired = $state(null);
     let uploading = $state(false);
     let uploadProgress = $state({ current: 0, total: 0 });
     async function browse(connection, prefix) {
@@ -22,12 +24,22 @@ function createBrowserStore() {
             entries = result;
         }
         catch (e) {
-            error = e instanceof Error ? e.message : String(e);
+            if (e instanceof AuthRequiredError && connection.anonymous) {
+                // Auto-detected a private bucket. Surface it for the Sidebar to
+                // flip the connection to non-anonymous and prompt for credentials.
+                authRequired = connection;
+            }
+            else {
+                error = e instanceof Error ? e.message : String(e);
+            }
         }
         finally {
             loading = false;
         }
     }
+    function clearAuthRequired() {
+        authRequired = null;
+    }
     async function navigateTo(prefix) {
         if (!activeConnection)
             return;
@@ -145,6 +157,10 @@ function createBrowserStore() {
                 return false;
             return credentialStore.has(activeConnection.id);
         },
+        get authRequired() {
+            return authRequired;
+        },
+        clearAuthRequired,
         browse,
         navigateTo,
         navigateUp,

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

@@ -1,6 +1,6 @@
 import type { FileEntry } from '../types.js';
 import { type SortConfig, type SortField } from '../utils/file-sort.js';
-export declare const fileStore: {
+export declare const files: {
     readonly entries: FileEntry[];
     readonly currentPath: string;
     readonly loading: boolean;
@@ -12,4 +12,3 @@ export declare const fileStore: {
     setError(message: string | null): void;
     sort(field: SortField): void;
 };
-export { fileStore as files };

package/dist/stores/files.svelte.js

@@ -40,5 +40,4 @@ function createFilesStore() {
         }
     };
 }
-export const fileStore = createFilesStore();
-export { fileStore as files };
+export const files = createFilesStore();

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

@@ -1,5 +1,13 @@
 import type { Tab } from '../types.js';
-export declare const tabStore: {
+/**
+ * Tab-id for eagerly-opened direct-URL tabs (`source: 'url'`).
+ * The Sidebar's host-detection auto-migration closes an eager tab by its id
+ * and re-opens as a remote tab once a connection is available; the eager id
+ * is built in `+page.svelte::openUrlTab` and matched in `Sidebar.svelte::
+ * handleAutoDetection`, so both sides must agree on the format.
+ */
+export declare function eagerUrlTabId(url: string): string;
+export declare const tabs: {
     readonly items: Tab[];
     readonly activeTabId: string | null;
     readonly active: Tab | undefined;
@@ -14,4 +22,3 @@ export declare const tabStore: {
     setActive(id: string): void;
     update(id: string, partial: Partial<Omit<Tab, "id">>): void;
 };
-export { tabStore as tabs };

package/dist/stores/tabs.svelte.js

@@ -1,6 +1,16 @@
 import { tabResources } from './tab-resources.svelte.js';
 /** Maximum number of viewer instances kept alive (mounted but hidden). */
 const MAX_ALIVE = 5;
+/**
+ * Tab-id for eagerly-opened direct-URL tabs (`source: 'url'`).
+ * The Sidebar's host-detection auto-migration closes an eager tab by its id
+ * and re-opens as a remote tab once a connection is available; the eager id
+ * is built in `+page.svelte::openUrlTab` and matched in `Sidebar.svelte::
+ * handleAutoDetection`, so both sides must agree on the format.
+ */
+export function eagerUrlTabId(url) {
+    return `url:${url}`;
+}
 function releaseDuckDbMemory() {
     import('../query/index.js')
         .then(({ getQueryEngine }) => getQueryEngine().then((engine) => engine.releaseMemory()))
@@ -106,5 +116,4 @@ function createTabsStore() {
         }
     };
 }
-export const tabStore = createTabsStore();
-export { tabStore as tabs };
+export const tabs = createTabsStore();

package/dist/types.d.ts

@@ -38,6 +38,17 @@ export interface Tab {
     connectionId?: string;
     extension: string;
     size?: number;
+    /**
+     * When set, the tab reads data from a SQL FROM-clause target (e.g. an
+     * attached DuckLake/DuckDB/SQLite table) rather than a file URL. The ref
+     * is inserted directly into generated SQL, so it must be fully-qualified
+     * and pre-quoted, e.g. `__objex_db__."main"."air_quality"`.
+     *
+     * When `sourceRef` is set, file-specific loading paths (hyparquet
+     * metadata, `parquet_kv_metadata`, etc.) are skipped, and schema / CRS /
+     * row count are derived from the SQL source directly via DuckDB.
+     */
+    sourceRef?: string;
 }
 export interface WriteResult {
     key: string;