@honua/react 0.1.7-beta.0 → 0.1.9-beta.0

package/core/credential-redaction.js

@@ -0,0 +1,389 @@
+/**
+ * Credential-recognition and redaction primitives shared by every Honua export
+ * pipeline.
+ *
+ * These were extracted verbatim from `src/web-components/export-redaction.ts`
+ * (issue #683) when the runtime's portable MapPackage export (#1426) needed the
+ * same scanner. There must be exactly one credential recognizer in this SDK: a
+ * second copy would drift, and the copy that drifts is the one that leaks. The
+ * web-components module re-exports every symbol below so its published surface
+ * is unchanged, and keeps the app-platform-specific state projection that
+ * layers on top of these primitives.
+ *
+ * This module lives in `src/core` rather than `src/web-components` because
+ * `src/runtime` ships in the stable-tier `@honua/sdk` split package while
+ * `src/web-components` ships in `@honua/app-platform`; the runtime cannot
+ * reach across that boundary (`scripts/prepare-split-packages.mjs`).
+ *
+ * Deliberately dependency-free apart from the SDK's shared error base: no
+ * `node:crypto`, no DOM, no renderer. Safe in a browser, a worker, or an SSR
+ * render pass.
+ *
+ * @module
+ */
+import { HonuaSdkError } from "./error-envelope.js";
+/** Placeholder substituted for any value the export pipeline refuses to emit. */
+export const HONUA_EXPORT_REDACTED = "[REDACTED]";
+/** Thrown when the export pipeline cannot produce a provably credential-free artifact. */
+export class HonuaExportSafetyError extends HonuaSdkError {
+    reason;
+    constructor(message, reason = "assertion") {
+        super("app.export-unsafe", message);
+        this.name = "HonuaExportSafetyError";
+        this.reason = reason;
+    }
+}
+// ── credential recognition ───────────────────────────────────────────────
+/**
+ * Property names that are never exported, whatever their value. Matched
+ * case-insensitively against the whole key (substring match), so `apiKey`,
+ * `X-API-KEY`, `refresh_token`, and `sessionCookie` are all caught.
+ *
+ * The `<qualifier>Key` family is enumerated rather than reduced to a bare
+ * `key`: `key` alone would refuse `primaryKey`, `layerKey`, `sortKey`, and the
+ * MapLibre style spec's own `*-key` properties, and an exporter that withholds
+ * a table's primary key is not safer, only broken. The qualifiers listed here
+ * have no innocent reading — `adminKey` in particular is the property name this
+ * repository's own CLI configuration uses for the root administrator
+ * credential (`profiles.<name>.adminKey`), so it must never ride out of an
+ * export or a diagnostic bundle.
+ */
+const SENSITIVE_KEY = /(?:api[-_]?key|(?:access|admin|encryption|master|root|signing)[-_]?key|auth|bearer|cookie|credential|cred(?:s)?\b|jwt|nonce|pass(?:word|wd)?|private[-_]?key|pwd|secret|session|sig(?:nature)?|subscription[-_]?key|token)/i;
+/** Property names that leak *authorization scope* rather than the secret itself. */
+const AUTHORIZATION_SCOPE_KEY = /(?:^|[-_.])(?:scope|scopes|audience|aud|tenant|tenant[-_]?id|client[-_]?id|grant|grant[-_]?type|roles|permissions|principal|subject|assume[-_]?role)(?:$|[-_.])/i;
+/** Query-parameter names that make a URL a *signed* URL (presigned S3/GCS/SAS/Esri/CDN). */
+const SIGNED_QUERY_NAME = /(?:^|[-_])(?:sig|signature|token|access[-_]?token|id[-_]?token|refresh[-_]?token|api[-_]?key|apikey|key|subscription[-_]?key|code|password|pwd|auth|jwt|hmac|policy|credential|se|sp|sv|st|srt|ss|skoid|sktid|sig)(?:$|[-_])/i;
+/**
+ * Free-text credential shapes. Every pattern is a linear scan over bounded
+ * character classes — no nested quantifiers, no backtracking traps (the repo's
+ * CodeQL ReDoS rule).
+ */
+const CREDENTIAL_PATTERNS = [
+    [/\b(?:Bearer|Basic|Digest|Negotiate)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "[REDACTED_AUTH]"],
+    // `scheme://user:password@host` — basic-auth credentials embedded in a URL.
+    // `projectExportEndpoint` refuses these structurally, but a URL can also reach
+    // an export through an adapter's free-text error message, so the text scan has
+    // to recognize the same shape.
+    [/\b[a-z][a-z0-9+.-]{1,31}:\/\/[^\s/@:]{1,128}:[^\s/@]{1,128}@/gi, "[REDACTED_URL_CREDENTIALS]@"],
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, "[REDACTED_JWT]"],
+    [/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_KEY]"],
+    [/\bASIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_KEY]"],
+    [/\bAIza[0-9A-Za-z_-]{20,}/g, "[REDACTED_PROVIDER_TOKEN]"],
+    [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, "[REDACTED_PROVIDER_TOKEN]"],
+    [/\bglpat-[A-Za-z0-9_-]{10,}/g, "[REDACTED_PROVIDER_TOKEN]"],
+    [/\bxox[baprs]-[A-Za-z0-9-]{8,}/gi, "[REDACTED_PROVIDER_TOKEN]"],
+    [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{8,}/gi, "[REDACTED_PROVIDER_TOKEN]"],
+    [/\bsk-[A-Za-z0-9]{16,}/g, "[REDACTED_PROVIDER_TOKEN]"],
+    // Labelled `name=value` / `name: value` pairs. The name alternation covers
+    // the short, provider-specific parameter names real signed URLs use — Azure
+    // SAS `sig`/`sv`/`se`/`st`, AWS/GCS `x-amz-signature`/`x-goog-signature`, and
+    // the bare `key` that tile providers favour — because those values are
+    // frequently *short* (a 24-character SAS signature is common) and so slip
+    // under any entropy heuristic. `\b` before each name keeps `turnkey=` and
+    // `monkey=` from matching.
+    [
+        /\b(access[-_]?key|admin[-_]?key|api[-_]?key|apikey|authorization|client[-_]?secret|cookie|credential|encryption[-_]?key|jwt|key|master[-_]?key|pass(?:password)?|password|pwd|root[-_]?key|se|secret|session|sig|signature|signing[-_]?key|st|subscription[-_]?key|sv|token|x-amz-[a-z-]{1,32}|x-goog-[a-z-]{1,32})\s*[:=]\s*(?:"[^"]{0,512}"|'[^']{0,512}'|[^\s&,;}"']{1,512})/gi,
+        `$1=${HONUA_EXPORT_REDACTED}`,
+    ],
+];
+/**
+ * High-entropy blob heuristic, applied last so labelled matches win first.
+ *
+ * Deliberately excludes `/` and `-` from the character class. Including them
+ * made ordinary URL paths match — `arcgis/rest/services/Roads/FeatureServer/0`
+ * is 41 characters of `[A-Za-z0-9/]` and was being reported as a secret, which
+ * would have thrown away the endpoint an attribution block legitimately needs.
+ * Base64 blobs containing `/` still get caught: in practice they appear as a
+ * labelled parameter value or an `Authorization` header, both of which the
+ * patterns above match first.
+ */
+const OPAQUE_SECRET = /\b[A-Za-z0-9_+=]{40,}\b/g;
+function decodePercentEncoding(value) {
+    let decoded = value;
+    for (let pass = 0; pass < 2; pass += 1) {
+        if (!decoded.includes("%"))
+            break;
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            break;
+        }
+        if (next === decoded)
+            break;
+        decoded = next;
+    }
+    return decoded;
+}
+/**
+ * Redacts credential material from arbitrary human-readable text: adapter
+ * error messages, titles, status strings, log lines, event detail messages.
+ *
+ * Percent-encoded payloads are decoded (twice, bounded) before matching so a
+ * `%42earer%20abc` style evasion cannot slip a token past the scan; the
+ * returned string is the redacted *decoded* form when decoding changed
+ * anything, because emitting the still-encoded original would defeat the
+ * point.
+ */
+export function redactHonuaExportText(value) {
+    if (value.length === 0)
+        return value;
+    let redacted = decodePercentEncoding(value);
+    for (const [pattern, replacement] of CREDENTIAL_PATTERNS) {
+        redacted = redacted.replace(pattern, replacement);
+    }
+    return redacted.replace(OPAQUE_SECRET, "[REDACTED_TOKEN]");
+}
+/** Whether `value` still looks like it carries credential material. */
+export function containsCredentialMaterial(value) {
+    return redactHonuaExportText(value) !== decodePercentEncoding(value);
+}
+/**
+ * Fail-closed assertion for finished export payloads (REQ-002). Throws
+ * {@link HonuaExportSafetyError} rather than scrubbing, because reaching this
+ * point with credential material means an earlier layer is broken.
+ */
+export function assertCredentialFreeExportText(value, label) {
+    if (containsCredentialMaterial(value)) {
+        throw new HonuaExportSafetyError(`${label} still contains credential material after redaction; refusing to emit the export.`, "assertion");
+    }
+}
+// ── binary artifact scanning ─────────────────────────────────────────────
+/** Shortest printable run worth scanning. Below this it is structural noise, not text. */
+const MIN_PRINTABLE_RUN = 4;
+/** Printable text accumulated before a chunk is scanned and flushed. */
+const PRINTABLE_CHUNK_BYTES = 1 << 20;
+/**
+ * Characters carried between chunks so a token straddling a flush boundary is
+ * still matched. Comfortably longer than the longest pattern this module has.
+ */
+const PRINTABLE_CHUNK_OVERLAP = 512;
+/**
+ * Extracts runs of printable ASCII from a binary buffer, joined by newlines.
+ *
+ * This is the `strings(1)` idea, and it exists because "binary" is not a
+ * security boundary. A PNG `tEXt`/`iTXt` chunk, a JPEG `COM` marker, PDF
+ * metadata or an embedded XMP packet, an EXIF `UserComment`, a ZIP comment —
+ * all carry plainly readable text inside a buffer that will never decode as
+ * UTF-8 as a whole. Scanning only whole-buffer-decodable artifacts would let a
+ * token ride out inside any of them.
+ *
+ * Runs shorter than {@link MIN_PRINTABLE_RUN} are dropped: they are the
+ * incidental byte values that fall in the ASCII range inside compressed data,
+ * and keeping them would produce noise without ever forming a credential.
+ */
+export function extractPrintableRuns(bytes, start = 0, end = bytes.byteLength) {
+    const runs = [];
+    let current = "";
+    for (let index = start; index < end; index += 1) {
+        const byte = bytes[index];
+        // Printable ASCII plus tab. Deliberately not the full latin-1 upper range:
+        // every credential shape this module recognizes is ASCII, and admitting
+        // 0x80-0xFF would turn arbitrary compressed data into "text".
+        if ((byte >= 0x20 && byte <= 0x7e) || byte === 0x09) {
+            current += String.fromCharCode(byte);
+            continue;
+        }
+        if (current.length >= MIN_PRINTABLE_RUN)
+            runs.push(current);
+        current = "";
+    }
+    if (current.length >= MIN_PRINTABLE_RUN)
+        runs.push(current);
+    return runs.join("\n");
+}
+/**
+ * Fail-closed credential scan over a binary artifact (REQ-002).
+ *
+ * Scans in bounded chunks with an overlap, so an arbitrarily large artifact
+ * costs bounded memory while a token that straddles a chunk boundary is still
+ * caught. Throws {@link HonuaExportSafetyError} on a hit, like the text scan —
+ * a credential surviving to this point means an earlier layer is broken, and
+ * emitting the bytes anyway is the one outcome that cannot be walked back.
+ */
+export function assertCredentialFreeExportBytes(bytes, label) {
+    let carry = "";
+    for (let offset = 0; offset < bytes.byteLength; offset += PRINTABLE_CHUNK_BYTES) {
+        const end = Math.min(bytes.byteLength, offset + PRINTABLE_CHUNK_BYTES);
+        const printable = extractPrintableRuns(bytes, offset, end);
+        if (printable.length === 0 && carry.length === 0)
+            continue;
+        assertCredentialFreeExportText(`${carry}${printable}`, label);
+        carry = printable.slice(-PRINTABLE_CHUNK_OVERLAP);
+    }
+}
+/**
+ * Reduces a source URL to `origin + pathname`, always dropping the query
+ * string and fragment.
+ *
+ * Query strings are where every practical map-service credential lives (Esri
+ * `?token=`, Azure SAS `?sv=...&sig=`, S3/GCS presigned `?X-Amz-Signature=`,
+ * tile-provider `?api_key=`), and a partial per-parameter allowlist has to be
+ * right about every provider forever. Dropping the whole query is the only
+ * rule that is right by construction; the origin+path that remains is what an
+ * attribution/provenance block legitimately needs.
+ *
+ * Non-HTTP(S) schemes (`data:`, `blob:`, `file:`), URLs with embedded
+ * `user:password@` userinfo, and unparseable strings yield no endpoint at all.
+ */
+export function projectExportEndpoint(url) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0 || trimmed.length > 4096) {
+        return { endpoint: undefined, reason: "unsupported-value" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        // Relative locators carry no host and therefore no credential context, but
+        // they can still carry a query string; keep only the path portion.
+        const [path] = trimmed.split(/[?#]/, 1);
+        if (path.length === 0 || containsCredentialMaterial(path)) {
+            return { endpoint: undefined, reason: "credential-pattern" };
+        }
+        return path === trimmed ? { endpoint: path } : { endpoint: path, reason: "signed-url" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { endpoint: undefined, reason: "unsupported-value" };
+    }
+    if (parsed.username.length > 0 || parsed.password.length > 0) {
+        return { endpoint: undefined, reason: "signed-url" };
+    }
+    const hadSecretQuery = [...parsed.searchParams.keys()].some((name) => SIGNED_QUERY_NAME.test(name) || SENSITIVE_KEY.test(name));
+    const endpoint = `${parsed.origin}${parsed.pathname}`;
+    if (containsCredentialMaterial(endpoint)) {
+        return { endpoint: undefined, reason: "credential-pattern" };
+    }
+    const droppedSomething = parsed.search.length > 0 || parsed.hash.length > 0;
+    if (hadSecretQuery)
+        return { endpoint, reason: "signed-url" };
+    return droppedSomething ? { endpoint, reason: "unsupported-value" } : { endpoint };
+}
+/**
+ * Removes credential material from a URL while leaving the URL *functional*.
+ *
+ * This is the counterpart to {@link projectExportEndpoint}, not a replacement
+ * for it. `projectExportEndpoint` reduces a URL to origin+path for a
+ * provenance/attribution block, where the query is never needed and dropping
+ * all of it is right by construction. That rule cannot be used on a URL the
+ * artifact still has to *fetch*: an OGC WMS `GetMap` request, an Esri
+ * `?f=json` endpoint, and a tile template with `?format=pbf` all carry their
+ * operation in the query string, and a portable map that lost it would import
+ * as a map that no longer renders.
+ *
+ * So this function removes exactly what is credential-bearing — `user:pass@`
+ * userinfo, and query parameters whose *name* reads as a secret or a
+ * signature — and then re-scans the remainder, refusing to emit anything that
+ * still looks like it carries a token. Non-HTTP(S) schemes are refused
+ * outright; `data:` payloads are handled by the caller, which can bound and
+ * scan the decoded bytes with {@link assertCredentialFreeExportBytes}.
+ */
+export function stripCredentialsFromUrl(url) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0 || trimmed.length > 8192) {
+        return { url: undefined, reason: "unsupported-value" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed === undefined) {
+        // Relative or template locator: no host, so no userinfo, but it can still
+        // carry a query string. Filter the query the same way and keep the rest.
+        const hashIndex = trimmed.indexOf("#");
+        const withoutHash = hashIndex === -1 ? trimmed : trimmed.slice(0, hashIndex);
+        const queryIndex = withoutHash.indexOf("?");
+        const pathPart = queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
+        const queryPart = queryIndex === -1 ? "" : withoutHash.slice(queryIndex + 1);
+        const { query, dropped } = filterCredentialQuery(queryPart);
+        const rebuilt = query.length > 0 ? `${pathPart}?${query}` : pathPart;
+        if (rebuilt.length === 0 || containsCredentialMaterial(rebuilt)) {
+            return { url: undefined, reason: "credential-pattern" };
+        }
+        // Nothing was dropped: return the caller's exact string rather than a
+        // reassembled one, so a safe URL round-trips byte-for-byte.
+        return dropped ? { url: rebuilt, reason: "signed-url" } : { url: trimmed };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { url: undefined, reason: "unsupported-value" };
+    }
+    let dropped = false;
+    if (parsed.username.length > 0 || parsed.password.length > 0) {
+        parsed.username = "";
+        parsed.password = "";
+        dropped = true;
+    }
+    for (const name of [...parsed.searchParams.keys()]) {
+        if (SIGNED_QUERY_NAME.test(name) || SENSITIVE_KEY.test(name)) {
+            parsed.searchParams.delete(name);
+            dropped = true;
+        }
+    }
+    // `URL` percent-encodes `{`/`}`, which would break a MapLibre tile template
+    // (`{z}/{x}/{y}`, `{bbox-epsg-3857}`). Restore them; they are structural, not
+    // credential material.
+    const rebuilt = parsed.toString().replace(/%7B/g, "{").replace(/%7D/g, "}");
+    if (containsCredentialMaterial(rebuilt)) {
+        return { url: undefined, reason: "credential-pattern" };
+    }
+    // Nothing was dropped: return the caller's exact string. `URL.toString()`
+    // normalizes (a bare origin gains a trailing `/`, reserved characters are
+    // re-encoded), and a portable artifact should not have its endpoints
+    // rewritten when there was nothing to remove.
+    return dropped ? { url: rebuilt, reason: "signed-url" } : { url: trimmed };
+}
+function filterCredentialQuery(query) {
+    if (query.length === 0)
+        return { query: "", dropped: false };
+    const kept = [];
+    let dropped = false;
+    for (const pair of query.split("&")) {
+        if (pair.length === 0)
+            continue;
+        const eq = pair.indexOf("=");
+        const name = eq === -1 ? pair : pair.slice(0, eq);
+        if (SIGNED_QUERY_NAME.test(name) || SENSITIVE_KEY.test(name)) {
+            dropped = true;
+            continue;
+        }
+        kept.push(pair);
+    }
+    return { query: kept.join("&"), dropped };
+}
+// ── header + key allowlists ──────────────────────────────────────────────
+const EXPORTABLE_HEADERS = new Set(["accept", "accept-language", "content-type", "user-agent"]);
+/**
+ * Filters a header map down to the export allowlist, recording every drop.
+ * Exposed so adapters can prove — in their own tests — that no `Authorization`,
+ * `Cookie`, or provider-specific key header rides along with export metadata.
+ */
+export function sanitizeHonuaExportHeaders(headers) {
+    const redactions = [];
+    const output = {};
+    for (const [rawName, rawValue] of Object.entries(headers ?? {})) {
+        const name = rawName.toLowerCase();
+        if (!EXPORTABLE_HEADERS.has(name)) {
+            redactions.push({
+                path: `headers[${name}]`,
+                reason: SENSITIVE_KEY.test(name) || AUTHORIZATION_SCOPE_KEY.test(name) ? "sensitive-key" : "private-header",
+            });
+            continue;
+        }
+        const value = redactHonuaExportText(rawValue);
+        if (value !== rawValue) {
+            redactions.push({ path: `headers[${name}]`, reason: "credential-pattern" });
+            continue;
+        }
+        output[name] = value.slice(0, 512);
+    }
+    return { headers: output, redactions };
+}
+/** Whether a property name is refused outright by the export pipeline. */
+export function isSensitiveExportKey(name) {
+    return SENSITIVE_KEY.test(name) || AUTHORIZATION_SCOPE_KEY.test(name);
+}

package/core/error-classifications.d.ts

@@ -47,6 +47,19 @@ export declare const HONUA_ERROR_RUNTIME_CLASSIFICATIONS: Readonly<{
     readonly "core.coverage.unsupported-format": HonuaErrorRuntimeClassification;
     readonly "core.coverage.service-error": HonuaErrorRuntimeClassification;
     readonly "core.coverage.wcs-exception": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.invalid-request": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.invalid-response": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.response-too-large": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.metadata-pending": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.missing-spatial-extent": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.no-tileable-variable": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.missing-spatial-reference": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.spatial-reference-mismatch": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.unsupported-version": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.unsupported-codec": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.unsupported-dtype": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.ambiguous-dimensions": HonuaErrorRuntimeClassification;
+    readonly "core.zarr.service-error": HonuaErrorRuntimeClassification;
     readonly "discovery.ambiguous-protocol": HonuaErrorRuntimeClassification;
     readonly "discovery.ambiguous-source": HonuaErrorRuntimeClassification;
     readonly "discovery.invalid-cloud-native-input": HonuaErrorRuntimeClassification;
@@ -106,6 +119,8 @@ export declare const HONUA_ERROR_RUNTIME_CLASSIFICATIONS: Readonly<{
     readonly "runtime.map-package.fetch": HonuaErrorRuntimeClassification;
     readonly "runtime.map-package.load": HonuaErrorRuntimeClassification;
     readonly "runtime.map-package.validate": HonuaErrorRuntimeClassification;
+    readonly "runtime.map-package.export": HonuaErrorRuntimeClassification;
+    readonly "runtime.map-package.import": HonuaErrorRuntimeClassification;
     readonly "runtime.map-package.update": HonuaErrorRuntimeClassification;
     readonly "runtime.map-package.style-compose": HonuaErrorRuntimeClassification;
     readonly "runtime.map-package.source-bind": HonuaErrorRuntimeClassification;

package/core/error-classifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-classifications.d.ts","sourceRoot":"","sources":["../../../src/core/error-classifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAkB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAErG;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG,SAAS;IACrD,MAAM,EAAE,gBAAgB;IACxB,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE,OAAO;CACnB,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8J6B,CAAC"}
+{"version":3,"file":"error-classifications.d.ts","sourceRoot":"","sources":["../../../src/core/error-classifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAkB,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAErG;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG,SAAS;IACrD,MAAM,EAAE,gBAAgB;IACxB,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE,OAAO;CACnB,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6K6B,CAAC"}

package/core/error-classifications.js

@@ -32,6 +32,19 @@ export const HONUA_ERROR_RUNTIME_CLASSIFICATIONS = Object.freeze({
     "core.coverage.unsupported-format": runtimeClassification("core", "capability", false),
     "core.coverage.service-error": runtimeClassification("core", "protocol", false),
     "core.coverage.wcs-exception": runtimeClassification("core", "protocol", false),
+    "core.zarr.invalid-request": runtimeClassification("core", "validation", false),
+    "core.zarr.invalid-response": runtimeClassification("core", "protocol", false),
+    "core.zarr.response-too-large": runtimeClassification("core", "validation", false),
+    "core.zarr.metadata-pending": runtimeClassification("core", "capability", false),
+    "core.zarr.missing-spatial-extent": runtimeClassification("core", "capability", false),
+    "core.zarr.no-tileable-variable": runtimeClassification("core", "capability", false),
+    "core.zarr.missing-spatial-reference": runtimeClassification("core", "capability", false),
+    "core.zarr.spatial-reference-mismatch": runtimeClassification("core", "capability", false),
+    "core.zarr.unsupported-version": runtimeClassification("core", "capability", false),
+    "core.zarr.unsupported-codec": runtimeClassification("core", "capability", false),
+    "core.zarr.unsupported-dtype": runtimeClassification("core", "capability", false),
+    "core.zarr.ambiguous-dimensions": runtimeClassification("core", "validation", false),
+    "core.zarr.service-error": runtimeClassification("core", "protocol", false),
     "discovery.ambiguous-protocol": runtimeClassification("discovery", "validation", false),
     "discovery.ambiguous-source": runtimeClassification("discovery", "validation", false),
     "discovery.invalid-cloud-native-input": runtimeClassification("discovery", "validation", false),
@@ -91,6 +104,8 @@ export const HONUA_ERROR_RUNTIME_CLASSIFICATIONS = Object.freeze({
     "runtime.map-package.fetch": runtimeClassification("runtime", "network", true),
     "runtime.map-package.load": runtimeClassification("runtime", "internal", false),
     "runtime.map-package.validate": runtimeClassification("runtime", "validation", false),
+    "runtime.map-package.export": runtimeClassification("runtime", "validation", false),
+    "runtime.map-package.import": runtimeClassification("runtime", "validation", false),
     "runtime.map-package.update": runtimeClassification("runtime", "internal", false),
     "runtime.map-package.style-compose": runtimeClassification("runtime", "validation", false),
     "runtime.map-package.source-bind": runtimeClassification("runtime", "internal", false),

package/core/error-code-registry.d.ts

@@ -51,6 +51,19 @@ export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
     readonly "core.coverage.unsupported-format": HonuaErrorCodeDescriptor;
     readonly "core.coverage.service-error": HonuaErrorCodeDescriptor;
     readonly "core.coverage.wcs-exception": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.invalid-request": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.invalid-response": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.response-too-large": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.metadata-pending": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.missing-spatial-extent": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.no-tileable-variable": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.missing-spatial-reference": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.spatial-reference-mismatch": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.unsupported-version": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.unsupported-codec": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.unsupported-dtype": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.ambiguous-dimensions": HonuaErrorCodeDescriptor;
+    readonly "core.zarr.service-error": HonuaErrorCodeDescriptor;
     readonly "discovery.ambiguous-protocol": HonuaErrorCodeDescriptor;
     readonly "discovery.ambiguous-source": HonuaErrorCodeDescriptor;
     readonly "discovery.invalid-cloud-native-input": HonuaErrorCodeDescriptor;
@@ -110,6 +123,8 @@ export declare const HONUA_ERROR_CODE_REGISTRY: Readonly<{
     readonly "runtime.map-package.fetch": HonuaErrorCodeDescriptor;
     readonly "runtime.map-package.load": HonuaErrorCodeDescriptor;
     readonly "runtime.map-package.validate": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.export": HonuaErrorCodeDescriptor;
+    readonly "runtime.map-package.import": HonuaErrorCodeDescriptor;
     readonly "runtime.map-package.update": HonuaErrorCodeDescriptor;
     readonly "runtime.map-package.style-compose": HonuaErrorCodeDescriptor;
     readonly "runtime.map-package.source-bind": HonuaErrorCodeDescriptor;

package/core/error-code-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-code-registry.d.ts","sourceRoot":"","sources":["../../../src/core/error-code-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,OAAO,GACP,KAAK,GACL,SAAS,GACT,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkpBwB,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAC"}
+{"version":3,"file":"error-code-registry.d.ts","sourceRoot":"","sources":["../../../src/core/error-code-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,OAAO,GACP,KAAK,GACL,SAAS,GACT,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,CAAC;AAEV,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqrBwB,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,yBAAyB,CAAC"}

package/core/error-code-registry.js

@@ -35,6 +35,19 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "core.coverage.unsupported-format": classification("core", "capability", false, "Coverage format is unsupported"),
     "core.coverage.service-error": classification("core", "protocol", false, "Coverage service rejected the request"),
     "core.coverage.wcs-exception": classification("core", "protocol", false, "WCS exception report"),
+    "core.zarr.invalid-request": classification("core", "validation", false, "Zarr request is invalid"),
+    "core.zarr.invalid-response": classification("core", "protocol", false, "Zarr response is invalid"),
+    "core.zarr.response-too-large": classification("core", "validation", false, "Zarr response exceeds its byte limit"),
+    "core.zarr.metadata-pending": classification("core", "capability", false, "Zarr metadata scan is pending"),
+    "core.zarr.missing-spatial-extent": classification("core", "capability", false, "Zarr storage spatial extent is missing or unusable"),
+    "core.zarr.no-tileable-variable": classification("core", "capability", false, "Zarr metadata contains no tileable variable"),
+    "core.zarr.missing-spatial-reference": classification("core", "capability", false, "Zarr registration is missing a positive storage SRID for tile handoff"),
+    "core.zarr.spatial-reference-mismatch": classification("core", "capability", false, "Zarr storage and tile matrix spatial references do not match"),
+    "core.zarr.unsupported-version": classification("core", "capability", false, "Zarr version is unsupported"),
+    "core.zarr.unsupported-codec": classification("core", "capability", false, "Zarr codec is unsupported"),
+    "core.zarr.unsupported-dtype": classification("core", "capability", false, "Zarr dtype is unsupported"),
+    "core.zarr.ambiguous-dimensions": classification("core", "validation", false, "Zarr dimensions are ambiguous"),
+    "core.zarr.service-error": classification("core", "protocol", false, "Zarr service rejected the request"),
     "discovery.ambiguous-protocol": classification("discovery", "validation", false, "Multiple protocols match the endpoint"),
     "discovery.ambiguous-source": classification("discovery", "validation", false, "Multiple sources match the selection"),
     "discovery.invalid-cloud-native-input": classification("discovery", "validation", false, "Cloud-native discovery input is invalid or ambiguous"),
@@ -94,6 +107,8 @@ export const HONUA_ERROR_CODE_REGISTRY = Object.freeze({
     "runtime.map-package.fetch": classification("runtime", "network", true, "Map package fetch failed"),
     "runtime.map-package.load": classification("runtime", "internal", false, "Map package load failed"),
     "runtime.map-package.validate": classification("runtime", "validation", false, "Map package validation failed"),
+    "runtime.map-package.export": classification("runtime", "validation", false, "Map package export refused"),
+    "runtime.map-package.import": classification("runtime", "validation", false, "Map package import refused"),
     "runtime.map-package.update": classification("runtime", "internal", false, "Map package update failed"),
     "runtime.map-package.style-compose": classification("runtime", "validation", false, "Map package style composition failed"),
     "runtime.map-package.source-bind": classification("runtime", "internal", false, "Map package source binding failed"),

package/core/grpc-adapter.d.ts

@@ -1,9 +1,9 @@
-import { type FeaturePage, type QueryFeaturesResponse } from "../gen/honua/v1/feature_service_pb.js";
+import { type FeaturePage, type QueryFeaturesResponse } from "../gen/geospatial/v1/index.js";
 import type { HonuaCountResponse, HonuaExtentResponse, HonuaFeature, HonuaObjectIdsResponse, HonuaQueryResponse, QueryFeaturesRequest } from "./types.js";
 /**
  * Converts a SDK QueryFeaturesRequest into a proto QueryFeaturesRequest message.
  */
-export declare function toProtoQueryRequest(request: QueryFeaturesRequest): import("../gen/honua/v1/feature_service_pb.js").QueryFeaturesRequest;
+export declare function toProtoQueryRequest(request: QueryFeaturesRequest): import("../gen/geospatial/v1/feature_service_pb.js").QueryFeaturesRequest;
 /**
  * Converts a proto QueryFeaturesResponse into the JSON-compatible shape
  * matching the `f=json` response format.

package/core/grpc-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grpc-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/grpc-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAWhB,KAAK,qBAAqB,EAM3B,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EAEZ,sBAAsB,EACtB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAwFpB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,wEAoIhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,qBAAqB,GAC9B,kBAAkB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAkDxF;AA0UD;;;;GAIG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAiBjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYtD"}
+{"version":3,"file":"grpc-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/grpc-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAWhB,KAAK,qBAAqB,EAM3B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EAEZ,sBAAsB,EACtB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AA6GpB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,6EAyIhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,qBAAqB,GAC9B,kBAAkB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAkDxF;AA0UD;;;;GAIG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAiBjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYtD"}

package/core/grpc-adapter.js

@@ -1,5 +1,5 @@
 import { create } from "@bufbuild/protobuf";
-import { CoordinateSchema, CoordinateSequenceSchema, DistanceUnit, FieldType, GeometrySchema, GeometryType, MultiPointGeometrySchema, PointGeometrySchema, PolygonGeometrySchema, PolylineGeometrySchema, QueryFeaturesRequestSchema, SpatialFilterSchema, SpatialReferenceSchema, SpatialRelationship, StatisticDefinitionSchema, StatisticType, } from "../gen/honua/v1/feature_service_pb.js";
+import { CoordinateSchema, CoordinateSequenceSchema, DistanceUnit, FieldType, GeometrySchema, GeometryType, MultiPointGeometrySchema, PointGeometrySchema, PolygonGeometrySchema, PolylineGeometrySchema, QueryFeaturesRequestSchema, SpatialFilterSchema, SpatialReferenceSchema, SpatialRelationship, StatisticDefinitionSchema, StatisticType, } from "../gen/geospatial/v1/index.js";
 import { HonuaGrpcError } from "./errors.js";
 /**
  * Maps proto FieldType enum values to Esri-style field type strings
@@ -81,6 +81,25 @@ const STATISTIC_TYPE_MAP = {
 };
 const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE_INTEGER_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+const MIN_PROTO_INT64 = -(1n << 63n);
+const MAX_PROTO_INT64 = (1n << 63n) - 1n;
+function toProtoObjectId(value) {
+    const token = value.trim();
+    if (!/^(?:0|-?[1-9][0-9]*)$/.test(token)) {
+        throw new RangeError("string objectIds must contain canonical decimal int64 values");
+    }
+    const parsed = BigInt(token);
+    if (parsed < MIN_PROTO_INT64 || parsed > MAX_PROTO_INT64) {
+        throw new RangeError("string objectIds must remain within the signed int64 range");
+    }
+    return parsed;
+}
+function toProtoPageInt64(field, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${field} must be a non-negative safe integer for the gRPC int64 contract`);
+    }
+    return BigInt(value);
+}
 /**
  * Converts a SDK QueryFeaturesRequest into a proto QueryFeaturesRequest message.
  */
@@ -107,15 +126,20 @@ export function toProtoQueryRequest(request) {
     }
     if (request.objectIds !== undefined) {
         const ids = typeof request.objectIds === "string"
-            ? request.objectIds.split(",").map((id) => BigInt(id.trim()))
-            : request.objectIds.map((id) => BigInt(id));
+            ? request.objectIds.split(",").map(toProtoObjectId)
+            : request.objectIds.map((id) => {
+                if (!Number.isSafeInteger(id)) {
+                    throw new RangeError("objectIds must contain only safe integers for the gRPC int64 contract");
+                }
+                return BigInt(id);
+            });
         msg.objectIds = ids;
     }
     if (request.resultOffset !== undefined) {
-        msg.resultOffset = request.resultOffset;
+        msg.resultOffsetLong = toProtoPageInt64("resultOffset", request.resultOffset);
     }
     if (request.resultRecordCount !== undefined) {
-        msg.resultRecordCount = request.resultRecordCount;
+        msg.resultRecordCountLong = toProtoPageInt64("resultRecordCount", request.resultRecordCount);
     }
     if (request.orderByFields !== undefined) {
         msg.orderBy = request.orderByFields;
@@ -577,7 +601,7 @@ function convertField(field) {
     return {
         name: field.name,
         type: FIELD_TYPE_MAP[field.fieldType] ?? "esriFieldTypeString",
-        alias: field.name,
+        alias: field.alias || field.name,
         length: field.length || undefined,
         nullable: field.nullable,
     };

package/core/job-run-errors.d.ts

@@ -0,0 +1,10 @@
+import type { JobStatus } from "../contract/jobs.js";
+import { HonuaSdkError } from "./error-envelope.js";
+/** Error thrown when `IJobRun.results()` observes a non-success terminal. */
+export declare class HonuaJobFailedError extends HonuaSdkError {
+    readonly status: JobStatus;
+    readonly errorCode: string | undefined;
+    readonly details: unknown;
+    constructor(message: string, status: JobStatus, errorCode?: string, details?: unknown);
+}
+//# sourceMappingURL=job-run-errors.d.ts.map

package/core/job-run-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-run-errors.d.ts","sourceRoot":"","sources":["../../../src/core/job-run-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,SAAgB,MAAM,EAAE,SAAS,CAAC;IAClC,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAO7F"}

package/core/job-run-errors.js

@@ -0,0 +1,14 @@
+import { HonuaSdkError } from "./error-envelope.js";
+/** Error thrown when `IJobRun.results()` observes a non-success terminal. */
+export class HonuaJobFailedError extends HonuaSdkError {
+    status;
+    errorCode;
+    details;
+    constructor(message, status, errorCode, details) {
+        super("core.job-failed", message, { context: { status, errorCode } });
+        this.name = "HonuaJobFailedError";
+        this.status = status;
+        this.errorCode = errorCode;
+        this.details = details;
+    }
+}