v2.1.2: dedicated decode-failure preview, no more sentinel leakage into UI

The decode-failure sentinels INVALID_COMPRESSED_DATA_MESSAGE and
MAX_DECOMPRESSED_SIZE_MESSAGE were never honoured by the consumers --
they leaked through getContent() / getDataUri() into Angular code
viewers, JSON viewers, and base64 data URIs inside <img>/<audio>/<video>
tags. The size-limit sentinel has been there for a long time; the
invalid-data one is new in v2.1.1 -- both have the same downstream
problem.

This commit short-circuits both the parser preview functions to detect
the sentinel and return a clean, dedicated "decode failure" iframe HTML
with two distinct headlines:
- 'Inscription too large to decode' (size-limit)
- 'Inscription content cannot be decoded' (invalid-data)

InscriptionPreviewService.getPreview() does the check at the top, so
backend `/preview/:id` rendering automatically benefits without any
backend code change. getContentTypeInstructions() gains a new
'decode-failure' return shape for the frontend's inline routing
(text/code/json/yaml/css/js paths). The existing else branch in
inscription-viewer.component.html already routes 'decode-failure' to
<app-preview-viewer>, which calls getPreview() -> the new failure HTML.
No frontend component changes needed.

Other changes in this commit:
- Added an exported helper `isDecodeFailureSentinel(content)` for
  consumers that want to detect the failure case directly.
- Migrated all `// test here: http://localhost:...` URL comments in
  inscription-preview.service.ts to https://ordpool.space/... so they
  remain useful for anyone who doesn't have a local dev environment.

Tests: 5 new (sentinel helper coverage + getContentTypeInstructions /
getPreview behavior on the corrupt-brotli fixture, plus a regression
guard that the sentinel string and its base64 don't leak into the
preview HTML).

Author: hans-crypto

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ordpool-parser",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Zero-dependency TypeScript parser for Bitcoin digital artifacts: Inscriptions, Runes, BRC-20, SRC-20, CAT-21, Atomicals, and Labitbu. Works in Node.js and browsers.",
   "repository": {
     "type": "git",

src/digital-artifact-analyser.service.corrupt-brotli.spec.ts

@@ -4,7 +4,8 @@ import { DigitalArtifactsParserService } from './digital-artifacts-parser.servic
 import { DigitalArtifactType } from './types/digital-artifact';
 import { ParsedInscription } from './types/parsed-inscription';
 import { OrdpoolTransactionFlags } from './types/ordpool-transaction-flags';
-import { INVALID_COMPRESSED_DATA_MESSAGE } from './lib/brotli-decode';
+import { INVALID_COMPRESSED_DATA_MESSAGE, MAX_DECOMPRESSED_SIZE_MESSAGE } from './lib/brotli-decode';
+import { InscriptionPreviewService, isDecodeFailureSentinel } from './inscription/inscription-preview.service';
 import { IEsploraApi } from './types/mempool';
 
 /**
@@ -87,3 +88,68 @@ describe('analyseTransaction with malformed inscription compression', () => {
     expect(stats.amounts.inscriptionJson ?? 0).toBe(0);
   });
 });
+
+describe('decode-failure sentinel detection helper', () => {
+
+  it('detects INVALID_COMPRESSED_DATA_MESSAGE as invalid-data', () => {
+    expect(isDecodeFailureSentinel(INVALID_COMPRESSED_DATA_MESSAGE)).toBe('invalid-data');
+  });
+
+  it('detects MAX_DECOMPRESSED_SIZE_MESSAGE as size-limit', () => {
+    expect(isDecodeFailureSentinel(MAX_DECOMPRESSED_SIZE_MESSAGE)).toBe('size-limit');
+  });
+
+  it('returns null for any other string', () => {
+    expect(isDecodeFailureSentinel('Hello World!')).toBeNull();
+    expect(isDecodeFailureSentinel('')).toBeNull();
+    expect(isDecodeFailureSentinel('{"p":"brc-20"}')).toBeNull();
+    // Substring of the sentinel must not match -- exact string only.
+    expect(isDecodeFailureSentinel('Error: invalid')).toBeNull();
+  });
+});
+
+describe('InscriptionPreviewService on the corrupt-brotli inscription', () => {
+
+  function getCorruptInscription(): ParsedInscription {
+    const tx = readCorruptBrotliFixture();
+    const artifacts = DigitalArtifactsParserService.parse(tx);
+    const inscription = artifacts.find(a => a.type === DigitalArtifactType.Inscription) as ParsedInscription | undefined;
+    if (!inscription) throw new Error('fixture has no inscription');
+    return inscription;
+  }
+
+  it('getContentTypeInstructions returns whatToShow=decode-failure with reason=invalid-data', async () => {
+    const inscription = getCorruptInscription();
+
+    const instructions = await InscriptionPreviewService.getContentTypeInstructions(inscription);
+
+    expect(instructions.whatToShow).toBe('decode-failure');
+    expect(instructions.reason).toBe('invalid-data');
+    expect(instructions.content).toBeUndefined();
+  });
+
+  it('getPreview returns the decode-failure HTML and never the sentinel string', async () => {
+    const inscription = getCorruptInscription();
+
+    const preview = await InscriptionPreviewService.getPreview(inscription);
+
+    // renderDirectly must be false -- we never let the iframe load /preview/ for
+    // a malformed inscription, otherwise the browser would just render garbage
+    // bytes (which is what we're trying to avoid).
+    expect(preview.renderDirectly).toBe(false);
+
+    // Failure HTML contains the human-readable headline for invalid-data.
+    expect(preview.previewContent).toContain('Inscription content cannot be decoded');
+
+    // The sentinel string itself MUST NOT leak into the iframe HTML -- if it
+    // did, that would mean a downstream preview function embedded the sentinel
+    // bytes into a data URI. The whole point of the short-circuit is to avoid
+    // exactly that.
+    expect(preview.previewContent).not.toContain(INVALID_COMPRESSED_DATA_MESSAGE);
+
+    // Same for the base64 of the sentinel bytes -- catches the case where
+    // getDataUri()-based preview functions accidentally bypass the short-circuit.
+    const sentinelBase64 = Buffer.from(INVALID_COMPRESSED_DATA_MESSAGE, 'utf8').toString('base64');
+    expect(preview.previewContent).not.toContain(sentinelBase64);
+  });
+});

src/inscription/inscription-preview.service.ts

@@ -1,3 +1,4 @@
+import { INVALID_COMPRESSED_DATA_MESSAGE, MAX_DECOMPRESSED_SIZE, MAX_DECOMPRESSED_SIZE_MESSAGE } from '../lib/brotli-decode';
 import { binaryStringToBase64, bytesToBinaryString, unicodeStringToBytes } from '../lib/conversions';
 import { ParsedInscription } from '../types/parsed-inscription';
 
@@ -7,6 +8,22 @@ export interface PreviewInstructions {
   renderDirectly: boolean;
 }
 
+export type DecodeFailureReason = 'invalid-data' | 'size-limit';
+
+/**
+ * If `content` is one of the decoder's failure sentinels (returned by
+ * brotliDecodeUint8Array / gzipDecode when the inscription's compressed
+ * body cannot be decoded or would exceed the size limit), report which
+ * one. Otherwise null. Used by the preview pipeline to short-circuit
+ * downstream rendering -- e.g. avoid embedding 30 bytes of "Error:
+ * invalid compressed data" as a base64 data URI inside an `<img>` tag.
+ */
+export function isDecodeFailureSentinel(content: string): DecodeFailureReason | null {
+  if (content === INVALID_COMPRESSED_DATA_MESSAGE) return 'invalid-data';
+  if (content === MAX_DECOMPRESSED_SIZE_MESSAGE) return 'size-limit';
+  return null;
+}
+
 /**
  * Takes a parsed inscription and returns a preview HTML
  * It tries to embed the dataUri of the inscription to save one network-request
@@ -30,6 +47,24 @@ export class InscriptionPreviewService {
       }
     }
 
+    // Decode-failure check first. If the body can't be decoded (corrupt
+    // brotli/gzip stream) or would exceed the decompression size limit,
+    // we must NOT continue into the per-content-type preview functions:
+    // they call getDataUri() which would embed the sentinel string as a
+    // base64 image/audio/etc, producing broken-icon previews. Show a
+    // dedicated failure page instead, regardless of declared contentType.
+    // Same outcome for renderDirectly types (image/svg+xml, text/html) --
+    // we replace the would-be iframe-src with the failure page.
+    const decodedContent = await inscription.getContent();
+    const failureReason = isDecodeFailureSentinel(decodedContent);
+    if (failureReason) {
+      return {
+        instructionsFor: inscription.inscriptionId,
+        previewContent: getPreviewDecodeFailure(failureReason),
+        renderDirectly: false
+      };
+    }
+
     let previewFunction: (inscription: ParsedInscription) => Promise<string> = getPreviewUnknown;
     if (inscription.contentType && table[inscription.contentType]) {
       previewFunction = table[inscription.contentType];
@@ -78,7 +113,8 @@ export class InscriptionPreviewService {
    */
   static async getContentTypeInstructions(inscription: ParsedInscription): Promise<{
     content: string | undefined,
-    whatToShow: 'json' | 'code' | 'preview'
+    whatToShow: 'json' | 'code' | 'preview' | 'decode-failure',
+    reason?: DecodeFailureReason
   }> {
 
     let content: string | undefined = undefined;
@@ -87,6 +123,21 @@ export class InscriptionPreviewService {
       inscription.contentType?.startsWith('application/json')) {
 
         content = await inscription.getContent();
+
+        // Short-circuit on decode failure -- the sentinel string is not
+        // valid JSON anyway, but if we let it fall through to the 'preview'
+        // branch below (or to the 'code' branch for yaml/css/js) the
+        // frontend would render the literal "Error: ..." text as the
+        // inscription's content. Route to a dedicated failure UI instead.
+        const failureReason = isDecodeFailureSentinel(content);
+        if (failureReason) {
+          return {
+            content: undefined,
+            whatToShow: 'decode-failure',
+            reason: failureReason
+          };
+        }
+
         const isValidJson = validateJson(content);
 
         if (isValidJson) {
@@ -105,6 +156,15 @@ export class InscriptionPreviewService {
 
       content = content || await inscription.getContent();
 
+      const failureReason = isDecodeFailureSentinel(content);
+      if (failureReason) {
+        return {
+          content: undefined,
+          whatToShow: 'decode-failure',
+          reason: failureReason
+        };
+      }
+
       return {
         content,
         whatToShow: 'code'
@@ -161,13 +221,13 @@ const table: { [key: string]: (inscription: ParsedInscription) => Promise<string
 
 
 
-// test here: http://localhost:4200/tx/751007cf3090703f241894af5c057fc8850d650a577a800447d4f21f5d2cecde
+// test here: https://ordpool.space/tx/751007cf3090703f241894af5c057fc8850d650a577a800447d4f21f5d2cecde
 async function getPreviewIframe(_inscription: ParsedInscription): Promise<string> {
   // return decodeDataURI(dataUri);
   return ''
 }
 
-// test here: http://localhost:4200/tx/ad99172fce60028406f62725b91b5c508edd95bf21310de5afeb0966ddd89be3
+// test here: https://ordpool.space/tx/ad99172fce60028406f62725b91b5c508edd95bf21310de5afeb0966ddd89be3
 async function getPreviewAudio(inscription: ParsedInscription): Promise<string> {
 
   const dataUri = await inscription.getDataUri();
@@ -185,7 +245,7 @@ async function getPreviewAudio(inscription: ParsedInscription): Promise<string>
 </html>`;
 }
 
-// test here http://localhost:4200/tx/6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799
+// test here https://ordpool.space/tx/6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799
 async function getPreviewImage(inscription: ParsedInscription): Promise<string> {
 
   const dataUri = await inscription.getDataUri();
@@ -223,7 +283,7 @@ async function getPreviewImage(inscription: ParsedInscription): Promise<string>
 </html>`;
 }
 
-// test here: http://localhost:4200/tx/c133c03e2ed44bb8ada79b1640b6649129de75a8f31d8e6ad573ede442f91cdb
+// test here: https://ordpool.space/tx/c133c03e2ed44bb8ada79b1640b6649129de75a8f31d8e6ad573ede442f91cdb
 async function getPreviewMarkdown(inscription: ParsedInscription): Promise<string> {
 
   const dataUri = await inscription.getDataUri();
@@ -240,7 +300,7 @@ async function getPreviewMarkdown(inscription: ParsedInscription): Promise<strin
 </html>`;
 }
 
-// test here: http://localhost:4200/tx/25013a3ab212e0ca5b3ccbd858ff988f506b77080c51963c948c055028af2051
+// test here: https://ordpool.space/tx/25013a3ab212e0ca5b3ccbd858ff988f506b77080c51963c948c055028af2051
 async function getPreviewModel(inscription: ParsedInscription): Promise<string> {
 
   const dataUri = await inscription.getDataUri();
@@ -263,7 +323,7 @@ async function getPreviewModel(inscription: ParsedInscription): Promise<string>
 </html>`;
 }
 
-// test here: http://localhost:4200/tx/85b10531435304cbe47d268106b58b57a4416c76573d4b50fa544432597ad670i0
+// test here: https://ordpool.space/tx/85b10531435304cbe47d268106b58b57a4416c76573d4b50fa544432597ad670i0
 // (shows only the first page)
 async function getPreviewPdf(inscription: ParsedInscription): Promise<string> {
 
@@ -282,7 +342,7 @@ async function getPreviewPdf(inscription: ParsedInscription): Promise<string> {
 </html>`;
 }
 
-// test here: http://localhost:4200/tx/430901147831e41111aced3895ee4b9742cf72ac3cffa132624bd38c551ef379
+// test here: https://ordpool.space/tx/430901147831e41111aced3895ee4b9742cf72ac3cffa132624bd38c551ef379
 async function getPreviewText(inscription: ParsedInscription): Promise<string> {
 
   const instructions = await InscriptionPreviewService.getContentTypeInstructions(inscription);
@@ -354,7 +414,7 @@ async function getPreviewText(inscription: ParsedInscription): Promise<string> {
 </html>`;
 }
 
-// test here: http://localhost:4200/tx/06158001c0be9d375c10a56266d8028b80ebe1ef5e2a9c9a4904dbe31b72e01c
+// test here: https://ordpool.space/tx/06158001c0be9d375c10a56266d8028b80ebe1ef5e2a9c9a4904dbe31b72e01c
 async function getPreviewUnknown(_inscription?: ParsedInscription): Promise<string> {
 
   return `<!doctype html>
@@ -369,7 +429,56 @@ async function getPreviewUnknown(_inscription?: ParsedInscription): Promise<stri
 `;
 }
 
-// test here: http://localhost:4200/tx/700f348e1acef6021cdee8bf09e4183d6a3f4d573b4dc5585defd54009a0148c
+/**
+ * Iframe HTML shown when an inscription's compressed body cannot be
+ * decoded (or would exceed the decompression size limit). Used by both
+ * the parser's getPreview() and the frontend's `<app-preview-viewer>`
+ * (via getContentTypeInstructions returning 'decode-failure', which
+ * routes to the same component that renders this HTML).
+ *
+ * Self-contained -- no external CSS or fonts -- because it has to render
+ * inside the sandboxed iframe used by `<app-preview-viewer>` AND inside
+ * the backend's `/preview/:id` response. Two distinct messages so the
+ * user knows whether it's a malformed inscription or a too-large one.
+ *
+ * test here (invalid-data: Content-Encoding: br body that is actually gzip):
+ *   https://ordpool.space/tx/5125c1269bd9c4605764fe76d253078d4c35897646004b8fa9837ad41e94a634
+ * test here (size-limit): no real-data fixture yet -- a >1 MB-decompressing
+ *   brotli body is needed to exercise this branch via the live UI.
+ */
+function getPreviewDecodeFailure(reason: DecodeFailureReason): string {
+  const headline = reason === 'size-limit'
+    ? 'Inscription too large to decode'
+    : 'Inscription content cannot be decoded';
+
+  const detail = reason === 'size-limit'
+    ? `The decompressed content exceeds the ${MAX_DECOMPRESSED_SIZE / 1024 / 1024}&#160;MB safety limit. The data is preserved on chain and remains accessible via the raw content link.`
+    : `The inscription declares a brotli or gzip Content-Encoding that doesn't match its actual body. The data is preserved on chain and remains accessible via the raw content link.`;
+
+  return `<!doctype html>
+<html lang='en'>
+  <head>
+    <meta charset='utf-8'>
+    <style>
+      html, body { margin: 0; padding: 0; height: 100%; background: #131516; color: #d3d4d5; font-family: system-ui, -apple-system, sans-serif; }
+      .wrap { display: flex; align-items: center; justify-content: center; height: 100%; padding: 1.5rem; box-sizing: border-box; }
+      .panel { max-width: 32rem; text-align: center; }
+      .panel h1 { margin: 0 0 0.6rem; font-size: 1.05rem; font-weight: 600; color: #ff9f43; }
+      .panel p { margin: 0; line-height: 1.5; font-size: 0.9rem; color: #b1b3b5; }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <div class="panel">
+        <h1>${headline}</h1>
+        <p>${detail}</p>
+      </div>
+    </div>
+  </body>
+</html>`;
+}
+
+// test here: https://ordpool.space/tx/700f348e1acef6021cdee8bf09e4183d6a3f4d573b4dc5585defd54009a0148c
 async function getPreviewVideo(inscription: ParsedInscription): Promise<string> {
 
   const dataUri = await inscription.getDataUri();