@honua/react 0.1.7-beta.0 → 0.1.10-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/error-envelope.d.ts

@@ -17,6 +17,7 @@ export interface HonuaErrorMetadata {
     readonly operationId?: string;
     readonly requestId?: string;
     readonly context?: Readonly<Record<string, unknown>>;
+    readonly terminalReceipt?: HonuaTerminalFailureReceipt;
 }
 export interface HonuaErrorOptions extends ErrorOptions, HonuaErrorMetadata {
 }
@@ -29,9 +30,38 @@ export interface SerializedHonuaError {
     readonly retryable: boolean;
     readonly operationId?: string;
     readonly requestId?: string;
+    readonly receipt?: HonuaTerminalFailureReceipt;
     readonly context: HonuaErrorEnvelopeContext;
     readonly cause?: SerializedHonuaErrorCause;
 }
+/** Stable failure classes shared by HTTP, GeoServices, and gRPC terminal receipts. */
+export type HonuaFailureKind = "authentication" | "authorization" | "not-found" | "validation" | "conflict" | "throttled" | "unavailable" | "unknown";
+/** One field- or item-addressable server rejection. */
+export interface HonuaFieldFailure {
+    readonly code?: string;
+    readonly severity?: string;
+    readonly path?: string;
+    readonly fieldId?: string;
+    readonly itemIndex?: number;
+    readonly message?: string;
+}
+/** Protocol-native metadata retained at a terminal transport boundary. */
+export interface HonuaProtocolMetadata {
+    readonly initial: Readonly<Record<string, readonly string[]>>;
+    readonly trailing: Readonly<Record<string, readonly string[]>>;
+}
+/** Machine-actionable receipt exposed by every remote terminal SDK error. */
+export interface HonuaTerminalFailureReceipt {
+    readonly transportStatus?: number;
+    readonly protocolCode?: number | string;
+    readonly kind: HonuaFailureKind;
+    readonly code?: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly correlationId?: string;
+    readonly fieldErrors: readonly HonuaFieldFailure[];
+    readonly protocolMetadata: HonuaProtocolMetadata;
+}
 export interface SerializedHonuaErrorCause {
     readonly name: string;
     readonly domain?: HonuaErrorDomain;
@@ -49,6 +79,7 @@ export declare abstract class HonuaSdkError extends Error {
     readonly retryable: boolean;
     readonly operationId: string | undefined;
     readonly requestId: string | undefined;
+    readonly terminalReceipt: HonuaTerminalFailureReceipt | undefined;
     readonly context: HonuaErrorEnvelopeContext;
     protected constructor(code: HonuaErrorCode, message: string, options?: HonuaErrorOptions);
     /** Safe JSON projection. Raw messages, stacks, details, bodies, and causes are intentionally omitted. */

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

@@ -1 +1 @@
-{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../../../src/core/error-envelope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../../../src/core/error-envelope.ts"],"names":[],"mappings":"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"}

package/core/error-envelope.js

@@ -18,6 +18,7 @@ export class HonuaSdkError extends Error {
     retryable;
     operationId;
     requestId;
+    terminalReceipt;
     context;
     constructor(code, message, options = {}) {
         const [domain, category, retryable] = errorCodeClassification(code);
@@ -29,6 +30,7 @@ export class HonuaSdkError extends Error {
         this.retryable = retryable;
         this.operationId = sanitizeIdentifier(options.operationId);
         this.requestId = sanitizeIdentifier(options.requestId);
+        this.terminalReceipt = options.terminalReceipt;
         this.context = sanitizeHonuaErrorContext(options.context);
     }
     /** Safe JSON projection. Raw messages, stacks, details, bodies, and causes are intentionally omitted. */
@@ -69,6 +71,7 @@ export function serializeHonuaError(error) {
     const cause = serializeCause(ownDataProperty(error, "cause"));
     const operationId = sanitizeIdentifier(asOptionalString(ownDataProperty(error, "operationId")));
     const requestId = sanitizeIdentifier(asOptionalString(ownDataProperty(error, "requestId")));
+    const receipt = ownDataProperty(error, "terminalReceipt");
     const context = ownDataProperty(error, "context");
     return {
         kind: HONUA_ERROR_KIND,
@@ -79,10 +82,18 @@ export function serializeHonuaError(error) {
         retryable,
         ...(operationId ? { operationId } : {}),
         ...(requestId ? { requestId } : {}),
+        ...(isTerminalFailureReceipt(receipt) ? { receipt } : {}),
         context: isRecord(context) && !Array.isArray(context) ? sanitizeHonuaErrorContext(context) : emptyContext(),
         ...(cause ? { cause } : {}),
     };
 }
+function isTerminalFailureReceipt(value) {
+    return (isRecord(value) &&
+        typeof ownDataProperty(value, "kind") === "string" &&
+        typeof ownDataProperty(value, "retryable") === "boolean" &&
+        Array.isArray(ownDataProperty(value, "fieldErrors")) &&
+        isRecord(ownDataProperty(value, "protocolMetadata")));
+}
 /** Redact structured context before it is stored on an SDK error. */
 export function sanitizeHonuaErrorContext(context) {
     if (!context)