You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by kr...@apache.org on 2026/08/14 03:17:20 UTC

(opennlp) 02/16: util: Usage example and hardening tests for the resource installer and tar reader, corrected javadoc

This is an automated email from the ASF dual-hosted git repository.

krickert pushed a commit to branch OPENNLP-1909-resource-installer
in repository https://gitbox.apache.org/repos/asf/opennlp.git

commit 0826827fceb1a87aa79618cf0248e92dff10885e
Author: Kristian Rickert <kr...@gmail.com>
AuthorDate: Thu Jul 16 01:19:45 2026 -0400

    util: Usage example and hardening tests for the resource installer and tar reader, corrected javadoc
---
 .../java/opennlp/tools/util/ResourceInstaller.java |  22 +-
 .../java/opennlp/tools/util/archive/TarStream.java |  37 +++-
 .../opennlp/tools/util/ResourceInstallerTest.java  | 178 ++++++++++++++-
 .../opennlp/tools/util/archive/TarStreamTest.java  | 244 +++++++++++++++++++++
 4 files changed, 465 insertions(+), 16 deletions(-)

diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
index 739833634..881db4da0 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
@@ -33,8 +33,8 @@ import java.util.zip.ZipInputStream;
 import opennlp.tools.util.archive.TarStream;
 
 /**
- * Fetches a user-chosen third-party resource, a training corpus, a dictionary archive,
- * a lexicon, into a local directory. The user supplies the location and thereby
+ * Fetches a user-chosen third-party resource, such as a training corpus, a dictionary
+ * archive, or a lexicon, into a local directory. The user supplies the location and thereby
  * accepts that resource's license; nothing is bundled and no location is built in,
  * which keeps externally licensed data entirely outside this library's distribution.
  *
@@ -51,7 +51,7 @@ import opennlp.tools.util.archive.TarStream;
 public final class ResourceInstaller {
 
   private ResourceInstaller() {
-    // static installer only
+    // This class exposes static methods only and is never instantiated.
   }
 
   /**
@@ -61,7 +61,7 @@ public final class ResourceInstaller {
    * @param targetDirectory The directory to install into; created when absent. Must
    *                        not be {@code null}.
    * @return The target directory. Never {@code null}.
-   * @throws IOException Thrown if fetching, verification, or unpacking fails.
+   * @throws IOException Thrown if fetching or unpacking fails.
    * @throws IllegalArgumentException Thrown if a parameter is {@code null}.
    */
   public static Path install(URI source, Path targetDirectory) throws IOException {
@@ -74,8 +74,9 @@ public final class ResourceInstaller {
    * @param source The resource location. Must not be {@code null}.
    * @param targetDirectory The directory to install into; created when absent. Must
    *                        not be {@code null}.
-   * @param sha256 The expected SHA-256 of the downloaded bytes as a hex string,
-   *               compared case-insensitively, or {@code null} to skip verification.
+   * @param sha256 The expected SHA-256 of the downloaded bytes as a hex string, compared
+   *               case-insensitively and ignoring leading and trailing whitespace, or
+   *               {@code null} to skip verification.
    * @return The target directory. Never {@code null}.
    * @throws IOException Thrown if fetching fails, the checksum does not match, or
    *         unpacking fails.
@@ -106,7 +107,10 @@ public final class ResourceInstaller {
     }
   }
 
-  /** Compares the file's SHA-256 with the expected hex digest. */
+  /**
+   * Computes the file's SHA-256 and compares it with the expected hex digest, ignoring
+   * hex letter case and any leading or trailing whitespace around the expected value.
+   */
   private static void verify(Path file, String expected) throws IOException {
     final MessageDigest digest;
     try {
@@ -176,6 +180,7 @@ public final class ResourceInstaller {
     }
   }
 
+  /** Unpacks every regular zip entry to its relative location beneath the target. */
   private static void unpackZip(InputStream raw, Path target) throws IOException {
     final ZipInputStream zip = new ZipInputStream(raw);
     ZipEntry entry;
@@ -204,7 +209,8 @@ public final class ResourceInstaller {
         && block[260] == 'a' && block[261] == 'r') {
       return true;
     }
-    // classic tar: a name and a valid octal size field
+    // Without the ustar magic, treat the block as a classic tar header when it starts
+    // with a name and its size field holds only octal digits, blanks, or NUL padding.
     if (block[0] == 0) {
       return false;
     }
diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
index db7b4f4f4..653ab99ca 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
@@ -28,9 +28,10 @@ import opennlp.tools.commons.Internal;
  * entry, skipping whatever remains of the current one, and {@link #entryStream()}
  * exposes exactly the current entry's bytes. No external archive library is involved.
  *
- * <p>Reads classic and ustar headers: entry name, octal size, and type flag. Long-name
- * extensions are not interpreted; such entries appear under their extension header
- * names and are skippable like any other.</p>
+ * <p>Reads classic and ustar headers: entry name, octal size, and type flag. The ustar
+ * name prefix field is not consulted, so an entry's name is always the content of the
+ * 100-byte name field alone. Long-name extension entries are not interpreted either;
+ * they appear under their extension header names and are skippable like any other.</p>
  */
 @Internal
 public final class TarStream {
@@ -146,6 +147,13 @@ public final class TarStream {
     };
   }
 
+  /**
+   * Fills the header buffer with the next 512-byte block.
+   *
+   * @return {@code true} when a full block was read, {@code false} at a clean end of
+   *         the stream before any byte of the block.
+   * @throws IOException Thrown if the stream ends inside the block.
+   */
   private boolean readBlock() throws IOException {
     int filled = 0;
     while (filled < header.length) {
@@ -161,6 +169,10 @@ public final class TarStream {
     return true;
   }
 
+  /**
+   * @return {@code true} if the current header buffer is one of the all-zero blocks
+   *         that terminate a tar archive.
+   */
   private boolean isEndBlock() {
     for (final byte b : header) {
       if (b != 0) {
@@ -170,6 +182,14 @@ public final class TarStream {
     return true;
   }
 
+  /**
+   * Parses the octal size field of the current header, tolerating NUL and blank
+   * padding around the digits.
+   *
+   * @return The entry size in bytes.
+   * @throws IOException Thrown if the field contains a character that is not an octal
+   *         digit, a blank, or NUL padding.
+   */
   private long parseOctal() throws IOException {
     long value = 0;
     for (int i = SIZE_OFFSET; i < SIZE_OFFSET + SIZE_LENGTH; i++) {
@@ -185,11 +205,22 @@ public final class TarStream {
     return value;
   }
 
+  /**
+   * @param entrySize The size of an entry's content in bytes.
+   * @return The number of padding bytes that align the entry to the next 512-byte
+   *         block boundary.
+   */
   private long padding(long entrySize) {
     final long remainder = entrySize % BLOCK;
     return remainder == 0 ? 0 : BLOCK - remainder;
   }
 
+  /**
+   * Consumes and discards the given number of bytes from the underlying stream.
+   *
+   * @param bytes The number of bytes to discard.
+   * @throws IOException Thrown if the stream ends before all bytes were consumed.
+   */
   private void skip(long bytes) throws IOException {
     long toSkip = bytes;
     final byte[] buffer = new byte[8192];
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
index 5c937e7da..9c95a9762 100644
--- a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
@@ -23,6 +23,8 @@ import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.security.MessageDigest;
+import java.util.List;
+import java.util.stream.Stream;
 import java.util.zip.GZIPOutputStream;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;
@@ -33,11 +35,24 @@ import org.junit.jupiter.api.io.TempDir;
 
 public class ResourceInstallerTest {
 
-  /** Writes one ustar entry: a 512-byte header block and padded content. */
+  /**
+   * Writes one tar entry into the given buffer: a 512-byte header block carrying the
+   * name, the octal content size, and the regular-file type flag, followed by the
+   * content padded to the next 512-byte block boundary.
+   *
+   * @param tar The buffer receiving the entry bytes. Must not be {@code null}.
+   * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+   * @param content The entry content. Must not be {@code null}.
+   * @throws IOException Thrown if writing to the buffer fails.
+   * @throws IllegalArgumentException Thrown if the name exceeds the tar name field.
+   */
   private static void tarEntry(ByteArrayOutputStream tar, String name, byte[] content)
       throws IOException {
     final byte[] header = new byte[512];
     final byte[] nameBytes = name.getBytes(StandardCharsets.UTF_8);
+    if (nameBytes.length > 100) {
+      throw new IllegalArgumentException("entry name exceeds 100 bytes: " + name);
+    }
     System.arraycopy(nameBytes, 0, header, 0, nameBytes.length);
     final String size = String.format("%011o", content.length);
     System.arraycopy(size.getBytes(StandardCharsets.US_ASCII), 0, header, 124, 11);
@@ -48,6 +63,14 @@ public class ResourceInstallerTest {
     tar.write(new byte[padding]);
   }
 
+  /**
+   * Builds a gzip-compressed tar archive from name and content pairs, terminated by
+   * the two all-zero blocks that end a tar archive.
+   *
+   * @param entries Pairs of entry name and UTF-8 text content. Must not be {@code null}.
+   * @return The archive bytes. Never {@code null}.
+   * @throws IOException Thrown if assembling the archive fails.
+   */
   private static byte[] tarGz(String[][] entries) throws IOException {
     final ByteArrayOutputStream tar = new ByteArrayOutputStream();
     for (final String[] entry : entries) {
@@ -61,6 +84,13 @@ public class ResourceInstallerTest {
     return compressed.toByteArray();
   }
 
+  /**
+   * Computes the SHA-256 of the given bytes as a lowercase hex string.
+   *
+   * @param content The bytes to digest. Must not be {@code null}.
+   * @return The 64-character lowercase hex digest. Never {@code null}.
+   * @throws Exception Thrown if the digest algorithm is unavailable.
+   */
   private static String sha256(byte[] content) throws Exception {
     final StringBuilder hex = new StringBuilder();
     for (final byte b : MessageDigest.getInstance("SHA-256").digest(content)) {
@@ -70,6 +100,72 @@ public class ResourceInstallerTest {
     return hex.toString();
   }
 
+  /**
+   * Computes the SHA-256 of the given bytes as an uppercase hex string, built from an
+   * uppercase digit table, so tests can prove that checksum comparison does not depend
+   * on the hex letter case.
+   *
+   * @param content The bytes to digest. Must not be {@code null}.
+   * @return The 64-character uppercase hex digest. Never {@code null}.
+   * @throws Exception Thrown if the digest algorithm is unavailable.
+   */
+  private static String sha256UpperCase(byte[] content) throws Exception {
+    final String digits = "0123456789ABCDEF";
+    final StringBuilder hex = new StringBuilder();
+    for (final byte b : MessageDigest.getInstance("SHA-256").digest(content)) {
+      hex.append(digits.charAt((b >> 4) & 0xF)).append(digits.charAt(b & 0xF));
+    }
+    return hex.toString();
+  }
+
+  /**
+   * Lists every regular file below the given directory as relative paths with forward
+   * slashes, sorted lexicographically, so tests can assert the exact installed file
+   * set.
+   *
+   * @param root The directory to walk. Must not be {@code null}.
+   * @return The sorted relative paths. Never {@code null}.
+   * @throws IOException Thrown if walking the directory fails.
+   */
+  private static List<String> installedFiles(Path root) throws IOException {
+    try (Stream<Path> walk = Files.walk(root)) {
+      return walk.filter(Files::isRegularFile)
+          .map(file -> root.relativize(file).toString().replace('\\', '/'))
+          .sorted()
+          .toList();
+    }
+  }
+
+  /**
+   * Demonstrates the intended end-to-end flow: package a small corpus as tar.gz,
+   * compute its real SHA-256, install it through the public API, and verify that
+   * exactly the archived files, and nothing else, appear on disk with their exact
+   * content.
+   */
+  @Test
+  void testInstallEndToEndUsageExample(@TempDir Path source, @TempDir Path target)
+      throws Exception {
+    final byte[] archive = tarGz(new String[][] {
+        {"corpus/README", "A tiny example corpus.\n"},
+        {"corpus/tokens.txt", "the\ncat\n"},
+        {"corpus/pos/tags.tsv", "the\tDET\ncat\tNOUN\n"}});
+    final Path file = source.resolve("corpus.tar.gz");
+    Files.write(file, archive);
+
+    final Path result = ResourceInstaller.install(file.toUri(), target, sha256(archive));
+
+    Assertions.assertEquals(target, result);
+    Assertions.assertEquals(
+        List.of("corpus/README", "corpus/pos/tags.tsv", "corpus/tokens.txt"),
+        installedFiles(target));
+    Assertions.assertEquals("A tiny example corpus.\n",
+        Files.readString(target.resolve("corpus/README")));
+    Assertions.assertEquals("the\ncat\n",
+        Files.readString(target.resolve("corpus/tokens.txt")));
+    Assertions.assertEquals("the\tDET\ncat\tNOUN\n",
+        Files.readString(target.resolve("corpus/pos/tags.tsv")));
+  }
+
   @Test
   void testTarGzUnpacksWithStructure(@TempDir Path source, @TempDir Path target)
       throws Exception {
@@ -94,12 +190,35 @@ public class ResourceInstallerTest {
     final Path file = source.resolve("archive.tar.gz");
     Files.write(file, archive);
 
-    Assertions.assertThrows(IOException.class, () -> ResourceInstaller.install(
-        file.toUri(), target, "00000000000000000000000000000000"
-            + "00000000000000000000000000000000"));
+    final String wrong = "0".repeat(64);
+    final IOException thrown = Assertions.assertThrows(IOException.class,
+        () -> ResourceInstaller.install(file.toUri(), target, wrong));
+    Assertions.assertEquals(IOException.class, thrown.getClass());
+    Assertions.assertEquals("checksum mismatch: expected " + wrong
+        + " but downloaded " + sha256(archive), thrown.getMessage());
     Assertions.assertEquals(0, Files.list(target).count());
   }
 
+  /**
+   * Proves that the hex digest comparison is case-insensitive: an uppercase rendering
+   * of the correct digest passes verification and the archive is unpacked.
+   */
+  @Test
+  void testChecksumComparisonIgnoresHexLetterCase(@TempDir Path source,
+      @TempDir Path target) throws Exception {
+    final byte[] archive = tarGz(new String[][] {{"data/entry.txt", "payload"}});
+    final Path file = source.resolve("cased.tar.gz");
+    Files.write(file, archive);
+    // The uppercase digest must differ textually from the lowercase one, otherwise
+    // this test would not exercise the case handling at all.
+    Assertions.assertNotEquals(sha256(archive), sha256UpperCase(archive));
+
+    ResourceInstaller.install(file.toUri(), target, sha256UpperCase(archive));
+
+    Assertions.assertEquals("payload",
+        Files.readString(target.resolve("data/entry.txt")));
+  }
+
   @Test
   void testEscapingEntriesAreRejected(@TempDir Path source, @TempDir Path target)
       throws Exception {
@@ -107,11 +226,60 @@ public class ResourceInstallerTest {
     final Path file = source.resolve("evil.tar.gz");
     Files.write(file, archive);
 
-    Assertions.assertThrows(IOException.class,
+    final IOException thrown = Assertions.assertThrows(IOException.class,
         () -> ResourceInstaller.install(file.toUri(), target));
+    Assertions.assertEquals(
+        "archive entry escapes the target directory: ../escape.txt",
+        thrown.getMessage());
     Assertions.assertTrue(Files.notExists(target.getParent().resolve("escape.txt")));
   }
 
+  /**
+   * Proves that a tar entry with an absolute name is rejected before anything is
+   * written, so a hostile archive cannot place files at arbitrary locations.
+   */
+  @Test
+  void testAbsoluteTarEntryIsRejected(@TempDir Path source, @TempDir Path target)
+      throws Exception {
+    final byte[] archive = tarGz(new String[][] {
+        {"/absolute-escape-attempt/evil.txt", "bad"}});
+    final Path file = source.resolve("absolute.tar.gz");
+    Files.write(file, archive);
+
+    final IOException thrown = Assertions.assertThrows(IOException.class,
+        () -> ResourceInstaller.install(file.toUri(), target));
+    Assertions.assertEquals(
+        "archive entry escapes the target directory: /absolute-escape-attempt/evil.txt",
+        thrown.getMessage());
+    Assertions.assertEquals(0, Files.list(target).count());
+    Assertions.assertTrue(Files.notExists(Path.of("/absolute-escape-attempt")));
+  }
+
+  /**
+   * Proves that the escape guard also covers zip content: an entry whose name climbs
+   * out of the target directory is rejected and nothing is written.
+   */
+  @Test
+  void testZipEntryWithTraversalIsRejected(@TempDir Path source, @TempDir Path target)
+      throws Exception {
+    final ByteArrayOutputStream out = new ByteArrayOutputStream();
+    try (ZipOutputStream zip = new ZipOutputStream(out)) {
+      zip.putNextEntry(new ZipEntry("../zip-escape.txt"));
+      zip.write("bad".getBytes(StandardCharsets.UTF_8));
+      zip.closeEntry();
+    }
+    final Path file = source.resolve("evil.zip");
+    Files.write(file, out.toByteArray());
+
+    final IOException thrown = Assertions.assertThrows(IOException.class,
+        () -> ResourceInstaller.install(file.toUri(), target));
+    Assertions.assertEquals(
+        "archive entry escapes the target directory: ../zip-escape.txt",
+        thrown.getMessage());
+    Assertions.assertTrue(Files.notExists(target.getParent().resolve("zip-escape.txt")));
+    Assertions.assertEquals(0, Files.list(target).count());
+  }
+
   @Test
   void testZipUnpacks(@TempDir Path source, @TempDir Path target) throws Exception {
     final ByteArrayOutputStream out = new ByteArrayOutputStream();
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java
new file mode 100644
index 000000000..dc79ee4e9
--- /dev/null
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java
@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.util.archive;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Exercises {@link TarStream} against archives built byte by byte in the test, covering
+ * regular traversal as well as boundary and corruption cases.
+ */
+public class TarStreamTest {
+
+  /**
+   * Builds one 512-byte tar header block with the given name, declared content size,
+   * and type flag. The mode field is populated with a non-zero octal value so that a
+   * name filling the whole 100-byte name field is followed by non-zero bytes, which
+   * makes name-boundary tests meaningful.
+   *
+   * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+   * @param size The content size to declare in the octal size field; must not be
+   *             negative.
+   * @param typeFlag The tar type flag, for example {@code '0'} for a regular file,
+   *                 {@code '5'} for a directory, or {@code '\0'} for an old-style
+   *                 regular file.
+   * @return The header block. Never {@code null}.
+   * @throws IllegalArgumentException Thrown if the name does not fit the name field or
+   *         the size is negative.
+   */
+  private static byte[] header(String name, long size, char typeFlag) {
+    final byte[] nameBytes = name.getBytes(StandardCharsets.UTF_8);
+    if (nameBytes.length > 100) {
+      throw new IllegalArgumentException("entry name exceeds 100 bytes: " + name);
+    }
+    if (size < 0) {
+      throw new IllegalArgumentException("size must not be negative: " + size);
+    }
+    final byte[] block = new byte[512];
+    System.arraycopy(nameBytes, 0, block, 0, nameBytes.length);
+    final byte[] mode = "0000644 ".getBytes(StandardCharsets.US_ASCII);
+    System.arraycopy(mode, 0, block, 100, mode.length);
+    final String sizeOctal = String.format("%011o", size);
+    System.arraycopy(sizeOctal.getBytes(StandardCharsets.US_ASCII), 0, block, 124, 11);
+    block[156] = (byte) typeFlag;
+    return block;
+  }
+
+  /**
+   * Writes one complete tar entry into the given buffer: the header block declaring
+   * the content's actual length, the content itself, and zero padding up to the next
+   * 512-byte block boundary.
+   *
+   * @param tar The buffer receiving the entry bytes. Must not be {@code null}.
+   * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+   * @param content The entry content. Must not be {@code null}.
+   * @param typeFlag The tar type flag for the header.
+   * @throws IOException Thrown if writing to the buffer fails.
+   */
+  private static void entry(ByteArrayOutputStream tar, String name, byte[] content,
+      char typeFlag) throws IOException {
+    tar.write(header(name, content.length, typeFlag));
+    tar.write(content);
+    tar.write(new byte[(512 - content.length % 512) % 512]);
+  }
+
+  /**
+   * Proves that a stream without a single byte is treated as an archive with no
+   * entries rather than as an error.
+   */
+  @Test
+  void testEmptyStreamHasNoEntries() throws IOException {
+    final TarStream stream = new TarStream(new ByteArrayInputStream(new byte[0]));
+    Assertions.assertFalse(stream.next());
+  }
+
+  /**
+   * Proves that an archive consisting only of the two all-zero terminator blocks
+   * reports no entries.
+   */
+  @Test
+  void testTerminatorOnlyArchiveHasNoEntries() throws IOException {
+    final TarStream stream = new TarStream(new ByteArrayInputStream(new byte[1024]));
+    Assertions.assertFalse(stream.next());
+  }
+
+  /**
+   * Walks an archive holding a directory, a file whose content is deliberately left
+   * unread, a file with an old-style NUL type flag, and a file whose size is an exact
+   * block multiple, asserting name, size, type classification, and content for each
+   * entry, and the end of the archive after the last one.
+   */
+  @Test
+  void testReadsEntriesSizesTypesAndContent() throws IOException {
+    final byte[] blockSized = new byte[512];
+    for (int i = 0; i < blockSized.length; i++) {
+      blockSized[i] = (byte) (i % 251);
+    }
+    final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+    entry(tar, "data/", new byte[0], '5');
+    entry(tar, "data/skip.bin", "0123456789".getBytes(StandardCharsets.US_ASCII), '0');
+    entry(tar, "data/alpha.txt", "alpha\n".getBytes(StandardCharsets.UTF_8), '\0');
+    entry(tar, "block.bin", blockSized, '0');
+    tar.write(new byte[1024]);
+    final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+    Assertions.assertTrue(stream.next());
+    Assertions.assertEquals("data/", stream.name());
+    Assertions.assertEquals(0, stream.size());
+    Assertions.assertFalse(stream.isFile());
+
+    // The next call must skip the unread content and padding of this entry.
+    Assertions.assertTrue(stream.next());
+    Assertions.assertEquals("data/skip.bin", stream.name());
+    Assertions.assertEquals(10, stream.size());
+    Assertions.assertTrue(stream.isFile());
+
+    Assertions.assertTrue(stream.next());
+    Assertions.assertEquals("data/alpha.txt", stream.name());
+    Assertions.assertEquals(6, stream.size());
+    Assertions.assertTrue(stream.isFile());
+    Assertions.assertArrayEquals("alpha\n".getBytes(StandardCharsets.UTF_8),
+        stream.entryStream().readAllBytes());
+
+    Assertions.assertTrue(stream.next());
+    Assertions.assertEquals("block.bin", stream.name());
+    Assertions.assertEquals(512, stream.size());
+    Assertions.assertTrue(stream.isFile());
+    Assertions.assertArrayEquals(blockSized, stream.entryStream().readAllBytes());
+
+    Assertions.assertFalse(stream.next());
+  }
+
+  /**
+   * Proves that a name occupying all 100 bytes of the name field is read in full and
+   * does not bleed into the adjacent, non-zero mode field.
+   */
+  @Test
+  void testNameFillsFullHundredByteField() throws IOException {
+    final StringBuilder longName = new StringBuilder("d/");
+    while (longName.length() < 100) {
+      longName.append('x');
+    }
+    final String name = longName.toString();
+    final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+    entry(tar, name, "n".getBytes(StandardCharsets.US_ASCII), '0');
+    tar.write(new byte[1024]);
+    final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+    Assertions.assertTrue(stream.next());
+    Assertions.assertEquals(100, stream.name().length());
+    Assertions.assertEquals(name, stream.name());
+    Assertions.assertArrayEquals("n".getBytes(StandardCharsets.US_ASCII),
+        stream.entryStream().readAllBytes());
+    Assertions.assertFalse(stream.next());
+  }
+
+  /**
+   * Proves that a stream ending in the middle of a header block fails loud instead of
+   * silently reporting the end of the archive.
+   */
+  @Test
+  void testTruncatedHeaderFailsLoud() {
+    final byte[] partial = Arrays.copyOf(header("cut.bin", 0, '0'), 200);
+    final TarStream stream = new TarStream(new ByteArrayInputStream(partial));
+
+    final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+    Assertions.assertEquals("truncated tar header", thrown.getMessage());
+  }
+
+  /**
+   * Proves that an entry stream fails loud when the underlying stream ends before the
+   * declared entry size has been delivered.
+   */
+  @Test
+  void testTruncatedEntryContentFailsLoud() throws IOException {
+    final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+    tar.write(header("data.bin", 10, '0'));
+    tar.write("1234".getBytes(StandardCharsets.US_ASCII));
+    final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+    Assertions.assertTrue(stream.next());
+    final IOException thrown = Assertions.assertThrows(IOException.class,
+        () -> stream.entryStream().readAllBytes());
+    Assertions.assertEquals("truncated tar entry: data.bin", thrown.getMessage());
+  }
+
+  /**
+   * Proves that advancing past an entry whose content is missing from the stream fails
+   * loud during the skip instead of reporting a clean end of the archive.
+   */
+  @Test
+  void testTruncatedArchiveWhenSkippingFailsLoud() throws IOException {
+    final TarStream stream = new TarStream(
+        new ByteArrayInputStream(header("gone.bin", 600, '0')));
+
+    Assertions.assertTrue(stream.next());
+    final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+    Assertions.assertEquals("truncated tar archive", thrown.getMessage());
+  }
+
+  /**
+   * Proves that a header whose size field carries a non-octal digit is rejected with a
+   * descriptive exception instead of producing a bogus size.
+   */
+  @Test
+  void testMalformedSizeFieldFailsLoud() {
+    final byte[] block = header("bad.bin", 0, '0');
+    block[124] = '9';
+    final TarStream stream = new TarStream(new ByteArrayInputStream(block));
+
+    final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+    Assertions.assertEquals("malformed tar size field in entry header",
+        thrown.getMessage());
+  }
+
+  /**
+   * Proves that the constructor rejects a missing input stream.
+   */
+  @Test
+  void testNullStreamIsRejected() {
+    Assertions.assertThrows(IllegalArgumentException.class, () -> new TarStream(null));
+  }
+}