@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/core/stac-static.js

@@ -0,0 +1,386 @@
+/**
+ * Static STAC catalog reader.
+ *
+ * A large share of public STAC catalogs are not API servers — they are
+ * static `catalog.json` / `collection.json` / item trees served from object
+ * storage, with no `/search` endpoint. This reader walks such a tree the
+ * spec-driven way: it follows `rel="child"` links to descend catalogs /
+ * collections and `rel="item"` links to reach STAC Items, resolving every
+ * href against the document it was found in (STAC best-practice relative
+ * links). Filtering (`collections` / `bbox` / `datetime` / `limit`) is
+ * applied client-side and the result is projected onto the same
+ * {@link HonuaStacItemCollectionResponse} envelope the STAC API search path
+ * returns, so the canonical `Source` surface is identical across both
+ * layouts.
+ *
+ * @module
+ */
+import { boundedJsonStructureViolation } from "./bounded-json.js";
+import { HonuaAbortError, HonuaCapabilityNotSupportedError } from "./errors.js";
+/** Guardrails match `connect()` static-STAC admission defaults and hard caps. */
+const DEFAULT_MAX_DOCUMENTS = 32;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_MAX_LINKS_PER_DOCUMENT = 64;
+const DEFAULT_MAX_DOCUMENT_BYTES = 1024 * 1024;
+const HARD_MAX_DOCUMENTS = 64;
+const HARD_MAX_DEPTH = 8;
+const HARD_MAX_LINKS_PER_DOCUMENT = 128;
+const HARD_MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
+const MAX_STATIC_JSON_DEPTH = 64;
+const MAX_STATIC_JSON_NODES = 100_000;
+const JSON_MEDIA_TYPES = new Set(["application/json", "application/geo+json"]);
+/**
+ * Reader bound to the URL of a static STAC catalog / collection root. The
+ * URL is the client baseUrl (the transport resolves same-origin absolute
+ * child/item hrefs directly), so `rootUrl` is normally `""` (the baseUrl
+ * itself) but may be an absolute `catalog.json` URL.
+ */
+export class HonuaStacStaticCatalog {
+    client;
+    rootUrl;
+    policy;
+    constructor(client, rootUrl = "", policy) {
+        this.client = client;
+        this.rootUrl = canonicalRuntimeUrl(rootUrl || client.serverBaseUrl, client.serverBaseUrl);
+        this.policy = normalizeRuntimePolicy(policy);
+    }
+    /**
+     * Traverse the catalog tree, collect matching items, and return them in
+     * the STAC search envelope shape.
+     */
+    async search(params = {}) {
+        const items = await this.collectItems(params);
+        const filtered = items.filter((item) => matchesFilters(item, params));
+        const cap = typeof params.limit === "number" && params.limit >= 0 ? params.limit : filtered.length;
+        const sliced = filtered.slice(0, cap);
+        return {
+            type: "FeatureCollection",
+            features: sliced,
+            numberReturned: sliced.length,
+            numberMatched: filtered.length,
+            links: [],
+        };
+    }
+    async fetchDoc(url, signal) {
+        const response = await this.client.pipelineFetch("GET", url, { headers: { Accept: "application/json, application/geo+json;q=0.9" } }, signal, { redirect: "error" });
+        const contentType = mediaEssence(response.headers.get("content-type") ?? "");
+        if (contentType && !JSON_MEDIA_TYPES.has(contentType)) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error("static STAC document did not return JSON");
+        }
+        const finalUrl = canonicalRuntimeUrl(response.url || url, url);
+        if (new URL(finalUrl).origin !== new URL(this.rootUrl).origin) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error("static STAC redirect left the admitted origin");
+        }
+        const value = await readBoundedJson(response, this.policy.maxDocumentBytes);
+        if (!isPlainObject(value))
+            throw new Error("static STAC document must be a JSON object");
+        if (value.links !== undefined && !Array.isArray(value.links)) {
+            throw new Error("static STAC links must be an array");
+        }
+        return { value: value, url: finalUrl };
+    }
+    /**
+     * Breadth-first walk collecting item documents. Descends `rel="child"`
+     * links; a `collections` filter prunes Collection subtrees whose `id`
+     * is not requested. Every attempted document, traversal depth, per-document
+     * link list, response body, redirect, and origin is bounded by the locator's
+     * admitted policy.
+     */
+    async collectItems(params) {
+        const wantedCollections = params.collections ? new Set(params.collections) : undefined;
+        const visitedRequests = new Set();
+        const completedUrls = new Set();
+        const queue = [{ url: this.rootUrl, depth: 0 }];
+        const items = [];
+        let attempts = 0;
+        while (queue.length > 0 && attempts < this.policy.maxDocuments) {
+            throwIfRuntimeAborted(params.signal);
+            const next = queue.shift();
+            if (!next || visitedRequests.has(next.url))
+                continue;
+            visitedRequests.add(next.url);
+            attempts += 1;
+            let fetched;
+            try {
+                fetched = await this.fetchDoc(next.url, params.signal);
+            }
+            catch (err) {
+                if (params.signal?.aborted || err instanceof HonuaAbortError)
+                    throw new HonuaAbortError();
+                if (next.depth === 0) {
+                    throw new HonuaCapabilityNotSupportedError("query", "stac", `static catalog root ${this.rootUrl} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                continue;
+            }
+            if (completedUrls.has(fetched.url))
+                continue;
+            completedUrls.add(fetched.url);
+            visitedRequests.add(fetched.url);
+            const doc = fetched.value;
+            if (doc.type === "Feature") {
+                if (isMinimallyValidStacItem(doc)) {
+                    items.push(doc);
+                }
+                else if (next.depth === 0) {
+                    throw new HonuaCapabilityNotSupportedError("query", "stac", "static catalog root Feature is not a minimally valid STAC Item");
+                }
+                continue;
+            }
+            // A Collection subtree not in the requested set is pruned entirely.
+            if (wantedCollections &&
+                doc.type === "Collection" &&
+                typeof doc.id === "string" &&
+                !wantedCollections.has(doc.id)) {
+                continue;
+            }
+            if (next.depth >= this.policy.maxDepth)
+                continue;
+            for (const link of (doc.links ?? []).slice(0, this.policy.maxLinksPerDocument)) {
+                if (!isPlainObject(link))
+                    continue;
+                if (typeof link.href !== "string")
+                    continue;
+                const rel = typeof link.rel === "string" ? link.rel.toLowerCase() : "";
+                if (rel !== "child" && rel !== "item")
+                    continue;
+                if (typeof link.type === "string" && !JSON_MEDIA_TYPES.has(mediaEssence(link.type)))
+                    continue;
+                const resolved = safeTraversalUrl(link.href, fetched.url, this.rootUrl);
+                if (resolved && !visitedRequests.has(resolved))
+                    queue.push({ url: resolved, depth: next.depth + 1 });
+            }
+        }
+        return items;
+    }
+}
+function safeTraversalUrl(href, base, root) {
+    let url;
+    try {
+        url = new URL(href, base);
+    }
+    catch {
+        return undefined;
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.origin !== new URL(root).origin) {
+        return undefined;
+    }
+    return url.toString();
+}
+function canonicalRuntimeUrl(value, base) {
+    const url = new URL(value, base);
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new HonuaCapabilityNotSupportedError("query", "stac", "static STAC URLs must be credential-free HTTP(S) URLs without query parameters or fragments");
+    }
+    return url.toString();
+}
+function normalizeRuntimePolicy(value) {
+    if (value === undefined) {
+        return Object.freeze({
+            maxDocuments: DEFAULT_MAX_DOCUMENTS,
+            maxDepth: DEFAULT_MAX_DEPTH,
+            maxLinksPerDocument: DEFAULT_MAX_LINKS_PER_DOCUMENT,
+            maxDocumentBytes: DEFAULT_MAX_DOCUMENT_BYTES,
+        });
+    }
+    const maxDocuments = runtimeBound(value.maxDocuments, 1, HARD_MAX_DOCUMENTS, "maxDocuments");
+    const maxDepth = runtimeBound(value.maxDepth, 1, HARD_MAX_DEPTH, "maxDepth");
+    const maxLinksPerDocument = runtimeBound(value.maxLinksPerDocument, 1, HARD_MAX_LINKS_PER_DOCUMENT, "maxLinksPerDocument");
+    const maxDocumentBytes = runtimeBound(value.maxDocumentBytes, 1, HARD_MAX_DOCUMENT_BYTES, "maxDocumentBytes");
+    // Validate the complete admitted locator even though asset inspection and
+    // HEAD-probe budgets are used only by connect-time discovery.
+    runtimeBound(value.maxAssets, 1, 1024, "maxAssets");
+    runtimeBound(value.maxAssetProbes, 0, 16, "maxAssetProbes");
+    return Object.freeze({ maxDocuments, maxDepth, maxLinksPerDocument, maxDocumentBytes });
+}
+function runtimeBound(value, minimum, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new HonuaCapabilityNotSupportedError("query", "stac", `static STAC ${name} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+async function readBoundedJson(response, maximum) {
+    const advertised = response.headers.get("content-length");
+    if (advertised !== null && Number(advertised) > maximum) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error(`static STAC response exceeds the ${maximum}-byte limit`);
+    }
+    if (!response.body)
+        throw new Error("static STAC response body is empty");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > maximum) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error(`static STAC response exceeds the ${maximum}-byte limit`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new Error("static STAC response contained invalid JSON");
+    }
+    const violation = boundedJsonStructureViolation(value, MAX_STATIC_JSON_DEPTH, MAX_STATIC_JSON_NODES);
+    if (violation === "max-depth") {
+        throw new Error(`static STAC response exceeds the ${MAX_STATIC_JSON_DEPTH}-level nesting limit`);
+    }
+    if (violation === "max-nodes") {
+        throw new Error(`static STAC response exceeds the ${MAX_STATIC_JSON_NODES}-node structural limit`);
+    }
+    if (violation === "non-json")
+        throw new Error("static STAC response contains non-finite JSON data");
+    return value;
+}
+function mediaEssence(value) {
+    return value.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function throwIfRuntimeAborted(signal) {
+    if (signal?.aborted)
+        throw new HonuaAbortError();
+}
+function isMinimallyValidStacItem(value) {
+    if (value.type !== "Feature" ||
+        typeof value.stac_version !== "string" ||
+        !value.stac_version.trim() ||
+        value.stac_version.length > 64 ||
+        typeof value.id !== "string" ||
+        !value.id.trim() ||
+        value.id.length > 512 ||
+        !isPlainObject(value.properties) ||
+        !Array.isArray(value.links) ||
+        !isPlainObject(value.assets)) {
+        return false;
+    }
+    if (value.stac_extensions !== undefined &&
+        (!Array.isArray(value.stac_extensions) || value.stac_extensions.some((entry) => typeof entry !== "string"))) {
+        return false;
+    }
+    if (value.collection !== undefined && (typeof value.collection !== "string" || !value.collection.trim())) {
+        return false;
+    }
+    if (!Object.hasOwn(value, "geometry") || !isRuntimeGeometry(value.geometry))
+        return false;
+    if (value.bbox !== undefined && !isRuntimeBbox(value.bbox))
+        return false;
+    if (value.links.some((link) => !isPlainObject(link) ||
+        typeof link.rel !== "string" ||
+        !link.rel.trim() ||
+        typeof link.href !== "string" ||
+        !link.href.trim())) {
+        return false;
+    }
+    if (Object.values(value.assets).some((asset) => !isPlainObject(asset) || typeof asset.href !== "string" || !asset.href.trim())) {
+        return false;
+    }
+    const datetime = value.properties.datetime;
+    if (datetime === null) {
+        return validRuntimeDatetime(value.properties.start_datetime) && validRuntimeDatetime(value.properties.end_datetime);
+    }
+    return validRuntimeDatetime(datetime);
+}
+function isRuntimeGeometry(value) {
+    if (value === null)
+        return true;
+    if (!isPlainObject(value) || typeof value.type !== "string")
+        return false;
+    if (value.type === "GeometryCollection")
+        return Array.isArray(value.geometries);
+    return ((value.type === "Point" ||
+        value.type === "MultiPoint" ||
+        value.type === "LineString" ||
+        value.type === "MultiLineString" ||
+        value.type === "Polygon" ||
+        value.type === "MultiPolygon") &&
+        Array.isArray(value.coordinates));
+}
+function isRuntimeBbox(value) {
+    return (Array.isArray(value) &&
+        (value.length === 4 || value.length === 6) &&
+        value.every((entry) => typeof entry === "number" && Number.isFinite(entry)) &&
+        value[0] <= value[value.length / 2] &&
+        value[1] <= value[value.length / 2 + 1] &&
+        (value.length === 4 || value[2] <= value[5]));
+}
+function validRuntimeDatetime(value) {
+    return typeof value === "string" && value.length <= 128 && !Number.isNaN(Date.parse(value));
+}
+function matchesFilters(item, params) {
+    const doc = item;
+    if (params.collections && params.collections.length > 0) {
+        if (typeof doc.collection !== "string" || !params.collections.includes(doc.collection))
+            return false;
+    }
+    if (params.bbox && Array.isArray(doc.bbox) && doc.bbox.length >= 4) {
+        if (!bboxIntersects(params.bbox, doc.bbox))
+            return false;
+    }
+    if (params.datetime) {
+        if (!datetimeMatches(params.datetime, doc))
+            return false;
+    }
+    return true;
+}
+function bboxIntersects(a, b) {
+    // 2D envelope intersection; ignores any z components.
+    const [axmin, aymin, axmax, aymax] = a;
+    const bxmin = b[0];
+    const bymin = b[1];
+    // A 4- or 6-tuple bbox: max x/y are the second half.
+    const bxmax = b.length >= 6 ? b[3] : b[2];
+    const bymax = b.length >= 6 ? b[4] : b[3];
+    return axmin <= bxmax && axmax >= bxmin && aymin <= bymax && aymax >= bymin;
+}
+function datetimeMatches(query, doc) {
+    const dt = typeof doc.properties?.datetime === "string" ? doc.properties.datetime : undefined;
+    // Closed / open interval query per STAC (`start/end`, `../end`, `start/..`).
+    if (query.includes("/")) {
+        const [rawStart, rawEnd] = query.split("/");
+        const start = rawStart && rawStart !== ".." ? Date.parse(rawStart) : Number.NEGATIVE_INFINITY;
+        const end = rawEnd && rawEnd !== ".." ? Date.parse(rawEnd) : Number.POSITIVE_INFINITY;
+        const startProp = typeof doc.properties?.start_datetime === "string" ? doc.properties.start_datetime : dt;
+        const endProp = typeof doc.properties?.end_datetime === "string" ? doc.properties.end_datetime : dt;
+        if (!startProp && !endProp)
+            return false;
+        const itemStart = startProp ? Date.parse(startProp) : Number.NEGATIVE_INFINITY;
+        const itemEnd = endProp ? Date.parse(endProp) : Number.POSITIVE_INFINITY;
+        return itemStart <= end && itemEnd >= start;
+    }
+    if (!dt)
+        return false;
+    return Date.parse(dt) === Date.parse(query);
+}

package/core/stac.d.ts

@@ -11,6 +11,13 @@ import type { HonuaProtocolTransport } from "./protocol-transport.js";
 import type { HonuaOgcCollectionMetadata, HonuaOgcCollectionsResponse, HonuaStacItemCollectionResponse, HonuaStacItemResponse, HonuaStacLandingResponse, OgcCollectionRequest, OgcMetadataRequest, StacSearchRequest } from "./types.js";
 export interface HonuaStacSearchOptions {
     client: HonuaClient;
+    /**
+     * Path prefix the STAC endpoints are mounted under. Defaults to `/stac`
+     * (Honua facade). Pass `""` for a raw STAC API root (e.g. Earth Search
+     * served at `.../v1`), so the search / collection paths resolve directly
+     * under the client baseUrl.
+     */
+    basePath?: string;
 }
 export interface HonuaStacSearchAllRequest extends StacSearchRequest {
     /** Maximum number of items to materialize across pages. */
@@ -25,7 +32,10 @@ export interface HonuaStacSearchAllRequest extends StacSearchRequest {
  */
 export declare class HonuaStacSearch {
     readonly client: HonuaClient;
+    private readonly basePath;
     constructor(options: HonuaStacSearchOptions);
+    /** Inject the configured STAC base path unless the caller already set one. */
+    private withBase;
     landing(request?: OgcMetadataRequest): Promise<HonuaStacLandingResponse>;
     collections(request?: OgcMetadataRequest): Promise<HonuaOgcCollectionsResponse>;
     collection(request: OgcCollectionRequest): Promise<HonuaOgcCollectionMetadata>;
@@ -35,6 +45,7 @@ export declare class HonuaStacSearch {
         signal?: AbortSignal;
         responseFormat?: string;
         extraParams?: Record<string, string | number | boolean>;
+        stacBasePath?: string;
     }): Promise<HonuaStacItemResponse>;
     search(request?: StacSearchRequest): Promise<HonuaStacItemCollectionResponse>;
     searchAll(request?: HonuaStacSearchAllRequest): Promise<HonuaStacItemResponse[]>;
@@ -50,6 +61,7 @@ export declare function getStacItem(transport: HonuaProtocolTransport, request:
     signal?: AbortSignal;
     responseFormat?: string;
     extraParams?: Record<string, string | number | boolean>;
+    stacBasePath?: string;
 }): Promise<HonuaStacItemResponse>;
 export declare function searchStac(transport: HonuaProtocolTransport, request?: StacSearchRequest): Promise<HonuaStacItemCollectionResponse>;
 //# sourceMappingURL=stac.d.ts.map

package/core/stac.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stac.d.ts","sourceRoot":"","sources":["../../../src/core/stac.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAEjB,OAAO,EAAE,sBAAsB;IAIrC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAI5E,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAInF,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAI9E,IAAI,CAAC,OAAO,EAAE;QACzB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;QAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACzD,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIrB,MAAM,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,+BAA+B,CAAC;IAIjF,SAAS,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAyBnF,YAAY,CACxB,OAAO,GAAE,yBAA8B,GACtC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC;CAoB5D;AAkCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAE1E;AAID,wBAAsB,cAAc,CAClC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAOnC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,2BAA2B,CAAC,CAOtC;AAED,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAOrC;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE;IACP,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACzD,GACA,OAAO,CAAC,qBAAqB,CAAC,CAMhC;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,+BAA+B,CAAC,CAmB1C"}
+{"version":3,"file":"stac.d.ts","sourceRoot":"","sources":["../../../src/core/stac.ts"],"names":[],"mappings":"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"}

package/core/stac.js

@@ -16,23 +16,31 @@ const DEFAULT_STAC_MAX_PAGES = 100;
  */
 export class HonuaStacSearch {
     client;
+    basePath;
     constructor(options) {
         this.client = options.client;
+        this.basePath = options.basePath;
+    }
+    /** Inject the configured STAC base path unless the caller already set one. */
+    withBase(request) {
+        if (this.basePath === undefined || request.stacBasePath !== undefined)
+            return request;
+        return { ...request, stacBasePath: this.basePath };
     }
     async landing(request = {}) {
-        return this.client.getStacLanding(request);
+        return this.client.getStacLanding(this.withBase(request));
     }
     async collections(request = {}) {
-        return this.client.listStacCollections(request);
+        return this.client.listStacCollections(this.withBase(request));
     }
     async collection(request) {
-        return this.client.getStacCollection(request);
+        return this.client.getStacCollection(this.withBase(request));
     }
     async item(request) {
-        return this.client.getStacItem(request);
+        return this.client.getStacItem(this.withBase(request));
     }
     async search(request = {}) {
-        return this.client.searchStac(request);
+        return this.client.searchStac(this.withBase(request));
     }
     async searchAll(request = {}) {
         const pageSize = request.pageSize ?? request.limit ?? DEFAULT_STAC_PAGE_SIZE;
@@ -40,12 +48,12 @@ export class HonuaStacSearch {
         const items = [];
         let cursor = { offset: request.offset, next: request.next };
         for (let page = 0; page < maxPages; page += 1) {
-            const response = await this.client.searchStac({
+            const response = await this.client.searchStac(this.withBase({
                 ...request,
                 limit: pageSize,
                 offset: cursor.offset,
                 next: cursor.next,
-            });
+            }));
             const pageItems = response.features ?? [];
             if (pageItems.length === 0)
                 break;
@@ -65,12 +73,12 @@ export class HonuaStacSearch {
         const maxPages = request.maxPages ?? DEFAULT_STAC_MAX_PAGES;
         let cursor = { offset: request.offset, next: request.next };
         for (let page = 0; page < maxPages; page += 1) {
-            const response = await this.client.searchStac({
+            const response = await this.client.searchStac(this.withBase({
                 ...request,
                 limit: pageSize,
                 offset: cursor.offset,
                 next: cursor.next,
-            });
+            }));
             const pageItems = response.features ?? [];
             if (pageItems.length === 0)
                 break;
@@ -118,33 +126,55 @@ export function createHonuaStacSearch(client) {
     return new HonuaStacSearch({ client });
 }
 // ── STAC API wire methods ───────────────────────────────────────
+/**
+ * Path prefix the STAC endpoints are mounted under. Defaults to `/stac`
+ * (the Honua Server facade). Backend-agnostic callers pointing at a raw
+ * STAC API root pass `""` so the paths resolve directly under the client
+ * baseUrl (e.g. Earth Search served at `.../v1`).
+ */
+function stacBase(request) {
+    const base = request.stacBasePath;
+    if (base === undefined)
+        return "/stac";
+    // Trim trailing slashes; an explicit "" means "the client baseUrl is the
+    // STAC API root".
+    let end = base.length;
+    while (end > 0 && base.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return base.slice(0, end);
+}
 export async function getStacLanding(transport, request = {}) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`stac:landing:${params.toString()}`, `/stac?${params.toString()}`, request);
+    const base = stacBase(request);
+    return transport.requestCachedMetadataJson(`stac:landing:${base}:${params.toString()}`, `${base}?${params.toString()}`, request);
 }
 export async function listStacCollections(transport, request = {}) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`stac:collections:${params.toString()}`, `/stac/collections?${params.toString()}`, request);
+    const base = stacBase(request);
+    return transport.requestCachedMetadataJson(`stac:collections:${base}:${params.toString()}`, `${base}/collections?${params.toString()}`, request);
 }
 export async function getStacCollection(transport, request) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`stac:collection:${request.collectionId}:${params.toString()}`, `/stac/collections/${encodeURIComponent(String(request.collectionId))}?${params.toString()}`, request);
+    const base = stacBase(request);
+    return transport.requestCachedMetadataJson(`stac:collection:${base}:${request.collectionId}:${params.toString()}`, `${base}/collections/${encodeURIComponent(String(request.collectionId))}?${params.toString()}`, request);
 }
 export async function getStacItem(transport, request) {
     const params = createOgcMetadataParams(request);
-    const path = `/stac/collections/${encodeURIComponent(String(request.collectionId))}` +
+    const base = stacBase(request);
+    const path = `${base}/collections/${encodeURIComponent(String(request.collectionId))}` +
         `/items/${encodeURIComponent(String(request.itemId))}`;
     return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
 }
 export async function searchStac(transport, request = {}) {
+    const base = stacBase(request);
     if (request.usePost) {
-        return transport.requestJson("POST", "/stac/search", {
+        return transport.requestJson("POST", `${base}/search`, {
             headers: mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }),
             body: JSON.stringify(stacSearchBody(request)),
         }, request.signal);
     }
     const params = serializeStacSearchParams(request);
-    return transport.requestJson("GET", `/stac/search?${params.toString()}`, undefined, request.signal);
+    return transport.requestJson("GET", `${base}/search?${params.toString()}`, undefined, request.signal);
 }
 function serializeStacSearchParams(request) {
     const params = new URLSearchParams();

package/core/surfaces.d.ts

@@ -3,6 +3,7 @@ import type { SpatialAggregationRequest, SpatialAggregationResult } from "../con
 import type { SourceId } from "../contract/types.js";
 import type { HonuaMetadataRequestOptions } from "./cache-state.js";
 import type { HonuaClient } from "./client.js";
+import type { OgcApiLayoutMode } from "./ogc-endpoint-layout.js";
 import type { ApplyEditsRequest, ExportMapRequest, HonuaAddAttachmentResponse, HonuaApplyEditsResponse, HonuaAttachmentListResponse, HonuaDeleteAttachmentsResponse, HonuaExportMapResponse, HonuaExtent, HonuaFeature, HonuaFindResponse, HonuaIdentifyResponse, HonuaLayerMetadata, HonuaLegendResponse, HonuaOgcCollectionMetadata, HonuaOgcCollectionsResponse, HonuaOgcConformanceResponse, HonuaOgcFeatureCollectionResponse, HonuaOgcFeatureResponse, HonuaOgcLandingResponse, HonuaOgcQueryablesResponse, HonuaQueryAttachmentsResponse, HonuaQueryResponse, HonuaRawRequest, HonuaRelatedRecordsResponse, HonuaServiceMetadata, HonuaTypedFeature, HonuaTypedQueryResponse, HonuaUpdateAttachmentResponse, MapFindRequest, MapIdentifyRequest, MapLayerQueryRequest, MapLegendRequest, MapRelatedRecordsRequest, OgcCollectionRequest, OgcCreateItemRequest, OgcDeleteItemRequest, OgcItemRequest, OgcItemsRequest, OgcMetadataRequest, OgcPatchItemRequest, OgcReplaceItemRequest, QueryFeaturesRequest, QueryMethod, QueryRelatedRecordsRequest } from "./types.js";
 export interface HonuaServiceOptions {
     client: HonuaClient;
@@ -231,14 +232,24 @@ export declare class HonuaMapLayer {
 }
 export interface HonuaOgcFeaturesOptions {
     client: HonuaClient;
+    /**
+     * Endpoint-layout discovery mode. `honua-facade` (default) uses the fixed
+     * `/ogc/features/...` fast path; `ogc-api` / `auto` discover the layout
+     * from the server landing page so the surface works against raw pygeoapi
+     * / ldproxy / GeoServer OGC API endpoints.
+     */
+    layout?: OgcApiLayoutMode;
 }
 export interface HonuaOgcFeatureCollectionOptions {
     client: HonuaClient;
     collectionId: string | number;
+    layout?: OgcApiLayoutMode;
 }
 export declare class HonuaOgcFeatures {
     readonly client: HonuaClient;
+    private readonly layoutMode;
     constructor(options: HonuaOgcFeaturesOptions);
+    private layout;
     collection(collectionId: string | number): HonuaOgcFeatureCollection;
     landing(request?: HonuaOgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
     conformance(request?: HonuaOgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
@@ -256,7 +267,9 @@ export declare class HonuaOgcFeatures {
 export declare class HonuaOgcFeatureCollection {
     readonly client: HonuaClient;
     readonly collectionId: string | number;
+    private readonly layoutMode;
     constructor(options: HonuaOgcFeatureCollectionOptions);
+    private layout;
     metadata(request?: HonuaOgcMetadataRequest): Promise<HonuaOgcCollectionMetadata>;
     queryables(request?: HonuaOgcMetadataRequest): Promise<HonuaOgcQueryablesResponse>;
     items(request?: HonuaOgcCollectionItemsRequest): Promise<HonuaOgcFeatureCollectionResponse>;