Skip to content

About

Browser tool for Unicode and whitespace inspection with exact file hashes and checked signed 64-bit positions.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Magic Comb

Magic Comb inspects explicitly supplied text and local files for whitespace, invisible Unicode, path controls, encoding faults, and exact SHA-256 hashes. It runs in the browser without uploading the supplied content. The static site has no audit server, crawler, account, or telemetry endpoint.

Paste text to start an audit automatically after 250 ms, or choose files/a folder to start immediately. A newer input generation cancels the old pool; stale results cannot replace the current input. Recheck repeats the selected File objects. Browsers may retain a file snapshot; reselect a changed file when necessary.

Run or publish

Serve this folder over HTTPS, or run ./Preview.ps1 in PowerShell and open http://127.0.0.1:19630/. SHA-256 uses the browser secure-context Web Crypto API. No npm packages or network build step are required. Rebuild the embedded JavaScript from the readable source files with ./Build.ps1. Copy this folder as static content, retaining assets, licenses and relative links. It also works without an internet connection once served locally. Direct file: behavior is browser-dependent; the supported preview is local HTTP/HTTPS.

Exact scope

  • Every accepted file retains its original bytes and is hashed in full. No source trimming, Unicode normalization, line-ending conversion or rewrite occurs. Downloading a report writes a new JSON file only.
  • Names and folder-relative paths are shown in full, alongside escaped displays. Browsers generally do not expose absolute operating-system paths; the tool never invents one from a fake input path.
  • Pasted input has no original file bytes. Its primary hash covers exactly the textarea's UTF-16LE code units, with no synthetic BOM. The browser may already normalize line endings on paste. Select the original file for byte and CRLF/LF/CR fidelity. Unpaired surrogates remain in the UTF-16 hash and are reported without replacement; their UTF-8 hash is unavailable.
  • Strict UTF-8 and BOM-marked UTF-16LE/BE are inspected. A starting BOM stays at logical offset zero and is structural metadata. Embedded FEFF is a finding. Invalid UTF-8, odd UTF-16, and UTF-32 BOMs are explicit failures.
  • Known opaque extensions/signatures are hash-only. A hash-only file is not declared text-clean. Explicit text extensions take priority over signature heuristics. “Try text decoding” explicitly requests strict decoding for otherwise opaque files. Extensions describe a profile, not content proof.
  • Positions are zero-based UTF-16 offset/codepoint-element index and one-based logical line/UTF-16 column. CRLF is one line ending; LS and PS remain source characters. Unpaired units are not Unicode scalar values.
  • Findings include exact character strings, U+ codepoints, escaped context, severity and location domain. The UI paginates 100 findings at a time; accepted reports retain every finding in downloadable JSON.
  • No Unicode bidirectional algorithm, grapheme/word segmentation, compiler, vulnerability scan, manufacturing trust, reviewer identity, regulatory approval or safety certification is inferred from lexical findings.

Resource profile and Turbo

The web tool accepts up to 256 files, 4 MiB per file, 32 MiB per batch, 2,097,152 decoded UTF-16 units per text, and 16,384 UTF-16 units per name/path. An unsupported selection is rejected before reading/auditing it; nothing is silently dropped. A count preflight rejects a whole text audit if more than 100,000 detailed records would be required. Its row is explicitly incomplete, with no truncated completed report. Use the separate PowerShell Magic Comb for larger projects and unbounded finding details.

Turbo creates at most four concurrent dedicated Blob workers. Each worker processes independent supplied jobs; final results use ordinal path/hash/order sorting and are identical to the one-worker canonical report. Worker counts are diagnostic metadata outside that deterministic report. Four workers are a concurrency option, not a promise of greater speed. Each three-array cache uses 24 bytes per UTF-16 slot, plus source/findings and browser overhead.

There are no optional network audit operations in this version. The proposed transient retry schedule 2, 4, 8, 16 and 32 seconds is inactive; no fake retry delays are applied. Static scripts, styles and fonts are self-hosted.

Rules

Rule Severity Observation
MC001 ERROR Cc, LS/PS or explicit bidi controls in supplied name/path
MC002 ERROR Strict decoding failure or unsupported encoding
MC003 ERROR NUL in decoded text
MC004 ERROR Unpaired UTF-16 code unit in decoded text
MC005 ERROR Explicit expected SHA-256 mismatch
MC101 WARNING Trailing Unicode whitespace
MC102 WARNING Mixed CRLF/LF/CR endings
MC103 WARNING Other Cc controls except TAB/CR/LF/NUL
MC104 WARNING Bidi formatting/control characters in logical text
MC105 WARNING Zero-width/joining characters; also supplied names
MC106 WARNING Nonordinary spaces/separators; also supplied names

Ordinary ASCII spaces and TABs are counted. They are not errors by themselves. Joiners and direction controls can be intentional language content. Preserve them and inspect semantic ownership before deciding whether to edit source. Context radius is 32 UTF-16 units, adjusted to preserve surrogate pairs.

Signed 64-bit representation

Protocol MAGIC-COMB-WEB-3 uses checked BigInt arithmetic and three BigInt64Array caches for stored lines, columns and codepoint-element indices. Overflow is checked before assignment. Canonical integer report fields are decimal strings because JSON cannot encode BigInt directly. Number input is rejected by the generic Int64 parser; explicit checked conversion helpers guard actual string, array, worker and DOM boundaries.

Exceptions: raw octets/digests remain Uint8Array; Unicode scalar/code-unit values are Number values from JavaScript string APIs; array lengths/indices, File.size, DOM table sizes, sort-comparator -1/0/1 and timer milliseconds use their standard browser Number APIs under explicit resource/range checks. No arbitrary unbounded integer is silently converted to Number. There is no clock field in the deterministic audit body. See Int64 transition notes for time/API distinctions; elapsed milliseconds, if recorded in diagnostics, are floating-point monotonic values, not invented integer nanoseconds.

Typography and license

One house policy uses local, unmodified Noto fonts with automatic script and symbol companions. There is no font picker or Google Fonts CSS request. Full SIL OFL 1.1 texts, official source commits and hashes are included under assets/fonts/; see font licenses. No single font or finite pack guarantees every writing system/culture or future input glyph. Automatic installed-system fallback may occur outside the bundled repertoire; font rendering never changes the exact source/hash evidence.

The application code is MIT licensed. Fonts retain their separate OFL licenses and copyrights and must not be sold on their own. .gitattributes disables Git text conversion so published hashes and line endings remain intact.

Verification and revision history

The current WEB3 artifact has 14 core/helper preflight checks, 26 independent signed64/core checks, and 21 actual Chrome integration checks. The browser receipt records the real browser/JavaScript version, source hashes, viewport, local worker behavior, font probes and network scope. These are software test results for the stated fixtures, not a claim that arbitrary source is safe.

For a fresh local core run, use node tests/verify-core.cjs with a recent Node runtime that supports Web Crypto and BigInt64Array. For a fresh browser run, start ./Preview.ps1, then use node tests/verify-browser.cjs. Set CHROME_PATH to the Chrome executable if it is not in the Windows default location. These opt-in tests write fresh receipts and screenshots; archive existing evidence first if retaining a comparison. No test starts on page load.

WEB1 was a draft before the signed64 migration. WEB2 introduced checked Int64 positions. WEB3 retains that arithmetic and adds the already-defined GSP1 binary bundle extension to the opaque classifier. The earlier source and preflight failure remain in the local controlled artifact history, excluded from the public deployment allowlist. No original inspected project files were edited by the auditor or its tests.

About

Browser tool for Unicode and whitespace inspection with exact file hashes and checked signed 64-bit positions.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages