What’s New in tinystruct 1.7.39
This document highlights the changes introduced in tinystruct version 1.7.39, a security, stability, and portability release featuring the new TokenGuard pre-authentication input validation engine, HTTP and MCP status code mapping, template engine cross-platform portability and locale fixes, ClassLoader fallback resolution, and core DOM and connection manager bug fixes.
See also: What’s New in 1.7.38 for the previous release featuring ASM CVE patches, JSON round-trip fixes, and faster lock-file I/O.
Highlights of 1.7.39
- TokenGuard Pre-Authentication Token Defense: Introduced
org.tinystruct.http.security.TokenGuardfor proactive, pre-authentication validation of authorization tokens across the framework. Enforces configurable maximum length limits (4096), rejects empty or whitespace-only inputs, filters illegal ASCII control characters and newlines, strictly validates Base64 padding semantics, and validates compact JWT structure (RFC 7515/7519) prior to expensive cryptographic operations. - ReDoS Protection with Bounded Regex Evaluation: Token deny patterns support regular expressions evaluated through a step-budgeted
CharSequence(budgeted at 50,000 character reads), preventing Regular Expression Denial of Service (ReDoS) and failing closed safely if evaluation exceeds budget. - HTTP Server & MCP Security Status Mapping:
HttpServerandAuthorizationHandlerintegrateTokenGuard.HttpServermaps validation and parsing outcomes to precise HTTP response statuses:400 Bad Requestfor malformed or oversized tokens,401 Unauthorizedfor failed authentication or expired tokens, and403 Forbiddenfor policy-blocked tokens.AuthorizationHandlercleanly supports optionalBearerscheme prefixes without rejecting standard headers. - Template Engine Cross-Platform Portability:
AbstractApplication.toString()standardizes on'/'as the template path separator instead of the OS-dependentFile.separatorChar, ensuring seamless cross-platform template resolution on Windows and within executable JARs. - Locale Resolution & ClassLoader Hierarchy: Removed the hardcoded
Locale.CHINAcomparison inAbstractApplicationso localized templates work consistently across all configured locales. Added a 3-tier ClassLoader fallback (Thread context class loader -> Class-level class loader -> System class loader) ingetResourceAsStream. - Stream Leak Prevention: Converted template
InputStreamloading inAbstractApplicationto try-with-resources, preventing resource leaks on I/O or parsing failures. - DOM & Core Stability Fixes: Fixed an infinite loop in
Element.removeElement(String)by properly advancing the child index; wrapped originalIOExceptioninDocument.load(...)instead of its potentially null cause; safely handled URI credentials inConnectionManagerwhen username is provided without a password; and allowed 1-, 2-, or 3-part locales inAbstractApplication.setLocale(...).
Details
1. TokenGuard Pre-Authentication Token Defense
Prior to version 1.7.39, invalid or malicious authorization tokens were passed directly to cryptographic parsing libraries (such as JJWT), which could incur high CPU costs when parsing oversized payloads, deeply nested structures, or malformed inputs.
TokenGuard provides a dedicated, lightweight pre-authentication validation layer in org.tinystruct.http.security.TokenGuard:
- Oversized Token Mitigation: Enforces a configurable maximum length limit (default
4096characters, configurable viasecurity.token.guard.max-length). Oversized tokens are rejected in sub-millisecond time before entering cryptographic parsers, preventing memory exhaustion and denial-of-service vectors. - Whitespace & Control Character Filtering: Strips leading and trailing whitespace and rejects tokens containing newlines (
\r,\n), tabs, null bytes, or non-printable ASCII control characters (< 0x20or0x7F). - Base64 Padding Semantics: Validates that Base64 padding (
=) only appears at the end of payloads, contains at most two padding characters, and enforces modulo-4 total length constraints whenever padding is present. - RFC 7515/7519 Compact JWT Validation: For JWT tokens, verifies exactly 2 period separators dividing into 3 non-empty unpadded Base64URL parts (
header.payload.signature), rejecting misplaced or invalid characters before cryptographic verification. - Safe Token Masking in Logs: Provides
TokenGuard.mask(token)to prevent accidental leakage of sensitive credentials in log files (e.g.eyJ...abc [len=142]).
// Create a TokenGuard with custom configuration
TokenGuard guard = new TokenGuard();
guard.setMaxLength(2048);
guard.setPatternDetection(true);
guard.setBlockPatterns("^revoked-.*,.*malicious.*");
// Validate tokens prior to cryptographic operations
TokenGuard.ValidationResult result = guard.validate(rawToken, TokenGuard.TokenType.JWT);
if (!result.isValid()) {
// Status can be: INVALID_FORMAT, OVERSIZED, MALFORMED, or BLOCKED
logger.warning("Token rejected: " + result.getStatus() + " - " + result.getMessage());
}
// Attach TokenGuard to JWTManager
JWTManager jwtManager = new JWTManager().withTokenGuard(guard);
2. ReDoS Protection with Bounded Regex Evaluation
When token pattern detection is enabled (security.token.guard.pattern-detection=true), tokens are checked against configured regex deny patterns (security.token.guard.block-patterns).
To defend against Regular Expression Denial of Service (ReDoS) from catastrophic backtracking patterns, TokenGuard wraps evaluated inputs in a BudgetedCharSequence limited to 50,000 character read operations:
- If pattern evaluation exceeds the allocated step budget, a
PatternBudgetExceededExceptionis thrown. - The guard fails closed, returning
TokenGuard.Status.BLOCKED, ensuring predictable execution times (< 1 ms) regardless of input size or pattern complexity.
// Bounded evaluation prevents catastrophic backtracking from locking worker threads
tokenGuard.setPatternDetection(true);
tokenGuard.setBlockPatterns("a*a*a*a*a*b");
// Catastrophic pattern terminates within bounded steps and fails closed safely
TokenGuard.ValidationResult result = tokenGuard.validate("aaaaaaaaaaaaaaaaaaaaaaaaa", TokenGuard.TokenType.GENERIC);
assert TokenGuard.Status.BLOCKED == result.getStatus();
3. HTTP Server & MCP Security Status Mapping
HttpServer and MCP AuthorizationHandler now integrate TokenGuard to return accurate HTTP response statuses:
| Status Code | Meaning | Trigger |
|---|---|---|
400 Bad Request |
Malformed input | Oversized tokens, control characters, invalid Base64 padding, or broken JWT structure |
401 Unauthorized |
Authentication failure | Expired tokens, invalid cryptographic signatures, or missing JWT secret/keys |
403 Forbidden |
Policy blocked | Tokens matching configured security.token.guard.block-patterns |
In MCP AuthorizationHandler:
- Authorization headers with optional
Bearerschemes are properly parsed before validation, preventing normal scheme separation spaces from being flagged as invalid control whitespace. - Malformed or oversized credentials fail closed immediately before attempting database or token comparisons.
4. Template Engine Portability & ClassLoader Improvements
- Cross-Platform Template Paths: In
AbstractApplication.toString(), template file path concatenation now standardizes on/instead ofFile.separatorChar. On Windows,File.separatorCharproduced\paths that failed to resolve resources packaged inside JAR files or across UNIX-standard container deployments. - Locale Resolution Fix: Removed a hardcoded
Locale.CHINAidentity check inAbstractApplicationthat prevented templates for other configured locales from resolving correctly. Localized templates now match the application’s actual locale setting. - ClassLoader Hierarchy Fallback:
AbstractApplication.getResourceAsStream(...)now implements a robust three-tier ClassLoader search strategy:- Thread context ClassLoader:
Thread.currentThread().getContextClassLoader() - Class-level ClassLoader:
AbstractApplication.class.getClassLoader() - System ClassLoader:
ClassLoader.getSystemClassLoader()
- Thread context ClassLoader:
- Try-With-Resources Leak Prevention: Template stream reads in
AbstractApplicationare now wrapped intry-with-resourcesblocks to guaranteeInputStreamclosure even if parsing or reading encounters an exception.
5. DOM, Data & Core Stability Fixes
Element.removeElement(String)Infinite Loop: Advancing loop counter index fixed an issue where removing elements by tag name from an XML or DOM tree could stall in an infinite loop.Document.load(...)Exception Cause: When XML parsing fails with anIOException, the exception is now wrapped directly rather than referencinge.getCause(), which was frequentlynulland obscured the underlying error message.- Safe ConnectionManager User Info Parsing: Safely parses URI authority when only a username is provided without a colon or password (e.g.
user@host), eliminatingArrayIndexOutOfBoundsException. - Flexible Locale Parsing:
AbstractApplication.setLocale(String)now safely parses 1-, 2-, or 3-part locale strings (e.g.en,zh_CN,zh_CN_POSIX).
6. Configuration Reference
New configuration properties in application.properties:
| Property | Description | Default |
|---|---|---|
security.token.guard.enabled |
Enable pre-authentication token validation (TokenGuard) |
true |
security.token.guard.max-length |
Maximum allowed token character length | 4096 |
security.token.guard.reject-malformed |
Reject invalid Base64 padding, control chars, and malformed JWT structures | true |
security.token.guard.pattern-detection |
Enable regex deny-pattern evaluation | false |
security.token.guard.block-patterns |
Comma-separated list of regex patterns to block | (empty) |
Example application.properties snippet:
# Security Token Guard settings
security.token.guard.enabled=true
security.token.guard.max-length=4096
security.token.guard.reject-malformed=true
security.token.guard.pattern-detection=false
security.token.guard.block-patterns=
Migration Guide
Updating to 1.7.39
Update your pom.xml dependency:
<dependency>
<groupId>org.tinystruct</groupId>
<artifactId>tinystruct</artifactId>
<version>1.7.39</version>
</dependency>
Things to Check When Upgrading from 1.7.38
- Token Pre-Validation Behavior: Requests with invalid JWT structures or trailing padding errors that previously resulted in
401 Unauthorizedwill now receive400 Bad Request. If client integrations expect 401 specifically for malformed tokens, verify client-side handling. - Token Length Limit: If your application issues exceptionally large JWTs (e.g., carrying large permission claims or serialized state > 4 KB), increase
security.token.guard.max-lengthinapplication.propertiesaccordingly. - Template Resource Separators: Custom template loaders relying on Windows backslashes (
\) should be updated to use/, ensuring seamless deployment across both Linux and Windows environments.
Community and Resources
- GitHub Repository: https://github.com/tinystruct/tinystruct
- Official Documentation: https://tinystruct.org
- Examples: https://github.com/tinystruct/tinystruct-examples
- Project Archetype: https://github.com/tinystruct/tinystruct-archetype