@honua/app-platform 0.1.1-beta.0 → 0.1.4-beta.0

package/web-components/export-redaction.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Credential-safe redaction primitives for the Honua component kit's export
+ * pipeline (issue #683, parent epic #678 "app-platform component production
+ * readiness"; REQ-002).
+ *
+ * The export pipeline is **redact-by-default in two independent layers**, and
+ * both layers run on every export regardless of who supplied the state:
+ *
+ * 1. **Allowlist projection.** {@link sanitizeHonuaExportState} never walks a
+ *    caller's state object generically. It projects a fixed, enumerated set of
+ *    presentation fields (viewport, layer identity/visibility/opacity, legend
+ *    labels, filter text, selection identity, source identity + attribution)
+ *    into a new object. Anything the projection does not name — arbitrary
+ *    `metadata` bags, request headers, credential stores, feature attributes,
+ *    locator query strings — simply has no path into the output. New fields
+ *    added to `HonuaWebComponentState` upstream are therefore *excluded* until
+ *    somebody deliberately allowlists them, which is the safe default
+ *    direction for a security boundary.
+ * 2. **Outbound scrub + assertion.** Every string that survives projection is
+ *    passed through {@link redactHonuaExportText}, URLs are reduced to
+ *    origin+path, and the finished payload is re-scanned by
+ *    {@link assertCredentialFreeExportText}. A scan hit is a *hard failure*
+ *    (`HonuaExportSafetyError`), not a silent scrub — a leak that reaches the
+ *    assertion means the projection has a bug, and failing closed is the only
+ *    honest response.
+ *
+ * The same primitives are applied to filenames ({@link
+ * sanitizeHonuaExportFilename}) and to every human-readable message the export
+ * pipeline puts on an event or a log line ({@link redactHonuaExportText}),
+ * because REQ-002 covers "exported bytes, serialized state, logs, events, or
+ * filenames" — a token leaked through a download filename or an error string
+ * is exactly as disclosed as one leaked through the payload.
+ *
+ * This module is deliberately dependency-free apart from the SDK's shared
+ * error base: no `node:crypto` (unlike `src/diagnostics/sanitize.ts`, which is
+ * a Node-side bundle helper), no DOM, no renderer, no localization framework.
+ * It is safe to import in a browser, a worker, or an SSR render pass, and
+ * carries no weight that NFR-001 forbids in the component bundles.
+ *
+ * @module
+ */
+import { HonuaSdkError } from "../core/error-envelope.js";
+import type { HonuaViewportState, HonuaWebComponentState } from "./types.js";
+/** Schema id stamped on every sanitized state document. */
+export declare const HONUA_EXPORT_STATE_SCHEMA = "honua.app-platform.export-state.v1";
+/** Placeholder substituted for any value the export pipeline refuses to emit. */
+export declare const HONUA_EXPORT_REDACTED = "[REDACTED]";
+/** Why a value was withheld from an export. */
+export type HonuaExportRedactionReason = 
+/** The property name itself named a credential (`token`, `apiKey`, `cookie`, ...). */
+"sensitive-key"
+/** A URL carried a signature, SAS, or token query parameter, or embedded userinfo. */
+ | "signed-url"
+/** A free-text value matched a credential shape (bearer token, JWT, provider key, ...). */
+ | "credential-pattern"
+/** A request-header map was dropped because it is not on the export allowlist. */
+ | "private-header"
+/** OAuth/authorization scope, audience, tenant, or grant detail. */
+ | "authorization-scope"
+/** A source explicitly marked as not exportable by the plan or the source itself. */
+ | "non-exportable-source"
+/** A value could not be represented safely (unserializable, cyclic, over budget). */
+ | "unsupported-value";
+/** One withheld value, addressed by its path in the sanitized document. */
+export interface HonuaExportRedaction {
+    /** Dotted/bracketed path in the *sanitized* document, e.g. `sources[0].endpoint`. */
+    readonly path: string;
+    readonly reason: HonuaExportRedactionReason;
+}
+/** Thrown when the export pipeline cannot produce a provably credential-free artifact. */
+export declare class HonuaExportSafetyError extends HonuaSdkError {
+    readonly reason: HonuaExportRedactionReason | "assertion";
+    constructor(message: string, reason?: HonuaExportRedactionReason | "assertion");
+}
+/**
+ * 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 declare function redactHonuaExportText(value: string): string;
+/** Whether `value` still looks like it carries credential material. */
+export declare function containsCredentialMaterial(value: string): boolean;
+/**
+ * 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 declare function assertCredentialFreeExportText(value: string, label: string): void;
+/**
+ * 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 declare function extractPrintableRuns(bytes: Uint8Array, start?: number, end?: number): string;
+/**
+ * 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 declare function assertCredentialFreeExportBytes(bytes: Uint8Array, label: string): void;
+/** Result of reducing an endpoint URL to its exportable form. */
+export interface HonuaExportEndpointProjection {
+    /** `scheme://host[:port]/path` with query, fragment, and userinfo removed, or `undefined` when nothing is safe to emit. */
+    readonly endpoint: string | undefined;
+    readonly reason?: HonuaExportRedactionReason;
+}
+/**
+ * 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 declare function projectExportEndpoint(url: string): HonuaExportEndpointProjection;
+export interface SanitizeHonuaExportFilenameOptions {
+    /** Caller-supplied title (map title, package id, adapter hint). May be untrusted. */
+    readonly title?: string;
+    /** Media type used to pick the extension. */
+    readonly mediaType?: string;
+    /** Stable prefix, defaults to `honua`. */
+    readonly prefix?: string;
+}
+/**
+ * Produces a download filename that cannot disclose a credential (REQ-002
+ * "…or filenames").
+ *
+ * A title that matches any credential shape is **discarded wholesale** rather
+ * than partially redacted: emitting `map-REDACTED_TOKEN-tiles.png` still tells
+ * an observer that a token was present and can preserve unmatched prefixes of
+ * it. The result is always confined to `[A-Za-z0-9._-]`, never begins with a
+ * dot, contains no path separators, and is length-bounded.
+ */
+export declare function sanitizeHonuaExportFilename(options?: SanitizeHonuaExportFilenameOptions): string;
+/** Exportable projection of one layer. */
+export interface HonuaSanitizedExportLayer {
+    readonly id: string;
+    readonly title: string;
+    readonly visible: boolean;
+    readonly opacity?: number;
+    readonly sourceId?: string;
+    readonly type?: string;
+}
+/** Exportable projection of one legend entry. */
+export interface HonuaSanitizedExportLegendItem {
+    readonly id: string;
+    readonly label: string;
+    readonly color?: string;
+    readonly layerId?: string;
+}
+/** Exportable projection of one bound source: identity and attribution only. */
+export interface HonuaSanitizedExportSource {
+    readonly sourceId: string;
+    readonly protocol?: string;
+    /** `scheme://host[:port]/path` — never a query string. Omitted when nothing was safe. */
+    readonly endpoint?: string;
+    readonly attribution?: string;
+    /** `true` when the source was withheld entirely (see `redactions`). */
+    readonly omitted?: boolean;
+}
+/** Exportable projection of the active filter for one source. */
+export interface HonuaSanitizedExportFilter {
+    readonly sourceId?: string;
+    readonly text?: string;
+    readonly expression?: string;
+}
+/** Exportable projection of the current selection: identity, never attributes. */
+export interface HonuaSanitizedExportSelection {
+    readonly sourceId?: string;
+    readonly sourceLayer?: string;
+    readonly featureId?: string | number;
+}
+/**
+ * The credential-free state document an export emits. Deliberately a *new*
+ * shape rather than a `Partial<HonuaWebComponentState>`: an export document is
+ * a published artifact with its own compatibility story, and reusing the
+ * live-state type would silently widen the export whenever the live state
+ * grows a field.
+ */
+export interface HonuaSanitizedExportState {
+    readonly schema: typeof HONUA_EXPORT_STATE_SCHEMA;
+    readonly packageId?: string;
+    readonly viewport?: HonuaViewportState;
+    readonly layers: readonly HonuaSanitizedExportLayer[];
+    readonly legend: readonly HonuaSanitizedExportLegendItem[];
+    readonly sources: readonly HonuaSanitizedExportSource[];
+    readonly filters: readonly HonuaSanitizedExportFilter[];
+    readonly selection?: HonuaSanitizedExportSelection;
+    /** Data-freshness timestamp carried through from controller state (REQ-003). */
+    readonly refreshedAt?: string;
+    readonly stale?: boolean;
+    /** Every value withheld from this document, with the reason. */
+    readonly redactions: readonly HonuaExportRedaction[];
+}
+export interface SanitizeHonuaExportStateOptions {
+    /**
+     * Sources the accepted plan or the source itself marks non-exportable. Their
+     * identity is preserved as `{ sourceId, omitted: true }` — an export that
+     * silently dropped a layer would misrepresent the map — but no endpoint,
+     * attribution, or filter detail is emitted, and every layer bound to them is
+     * withheld too.
+     */
+    readonly nonExportableSourceIds?: readonly string[];
+}
+export interface HonuaExportStateSanitizationResult {
+    readonly state: HonuaSanitizedExportState;
+    readonly redactions: readonly HonuaExportRedaction[];
+}
+/**
+ * Projects live component state into the credential-free export document
+ * (REQ-002). Never throws for hostile input — hostile values are withheld and
+ * recorded — but the finished document is asserted credential-free by
+ * {@link assertCredentialFreeExportText} in the export runner before any byte
+ * reaches a caller.
+ */
+export declare function sanitizeHonuaExportState(state: HonuaWebComponentState<unknown> | undefined, options?: SanitizeHonuaExportStateOptions): HonuaExportStateSanitizationResult;
+/**
+ * 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 declare function sanitizeHonuaExportHeaders(headers: Readonly<Record<string, string>> | undefined): {
+    headers: Readonly<Record<string, string>>;
+    redactions: readonly HonuaExportRedaction[];
+};
+/** Whether a property name is refused outright by the export pipeline. */
+export declare function isSensitiveExportKey(name: string): boolean;
+//# sourceMappingURL=export-redaction.d.ts.map

package/web-components/export-redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-redaction.d.ts","sourceRoot":"","sources":["../../../src/web-components/export-redaction.ts"],"names":[],"mappings":"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"}