browser.chrome only api

browser.chrome-only-api

Rule ID: browser.chrome-only-api Severity: WARN Category: browser Target Standards: W3C Device Memory Specification (Chromium-only draft), W3C Network Information API (Excluded from Safari and Firefox), W3C Web Platform Status (Mozilla & WebKit Positions on Chromium APIs)

---

1. Overview & Core Invariant

Flags reliance on Chromium-exclusive APIs without cross-browser fallbacks for Firefox and Safari

Core Invariant:

"Reliance on Chromium-exclusive APIs ('navigator.deviceMemory', 'navigator.connection', Web Serial/USB, etc.) must include runtime guards and cross-browser fallbacks."

---

2. Technical Grounding & Engine Realities

Chromium exposes several proprietary or non-consensus APIs that Mozilla Firefox and Apple WebKit have formally opposed due to privacy or architecture concerns.

Direct, unguarded access to 'navigator.deviceMemory' or 'navigator.connection' will fail or return 'undefined', throwing TypeErrors when accessing nested properties.

---

3. Vulnerability & Risk Taxonomy

Risk Vector	Severity	Impact
Runtime Crash on Safari and Firefox	MEDIUM	Accessing 'navigator.connection.effectiveType' throws 'TypeError: Cannot read properties of undefined' on Safari and desktop Firefox.
Feature Lockout for Non-Chromium Users	MEDIUM	Users on Safari (iOS/macOS) and Firefox cannot complete critical workflows if File System Access or Web Serial is required without a standard fallback.

---

4. Non-Compliant Code Patterns (Bad Examples)

JAVASCRIPT (Direct unguarded access to navigator.connection):

const effectiveSpeed = navigator.connection.effectiveType;

JAVASCRIPT (Direct access to navigator.deviceMemory):

const memoryGiB = navigator.deviceMemory;

---

5. Compliant Implementation Patterns (Good Examples)

JAVASCRIPT (Guarded access with default fallback for non-Chromium browsers):

const effectiveSpeed = (typeof navigator !== "undefined" && navigator.connection?.effectiveType) || "4g";

JAVASCRIPT (Capability guard using in operator):

const memoryGiB = (typeof navigator !== "undefined" && "deviceMemory" in navigator) ? navigator.deviceMemory : 4;

---

6. Detection & Verification Pipeline (How The Rule Evaluates Code)

This rule evaluates source code through the standard AST inspection pipeline:

flowchart TD
    Node["AST Node (Astro / TSX element)"] --> Inspect["1. Inspect Element & Attributes"]
    Inspect --> Invariant{"2. Evaluate Rule Invariant"}
    Invariant -- "Compliant" --> Safe["Pass"]
    Invariant -- "Non-Compliant" --> IgnoreCheck{"3. Check charites:ignore directive"}
    IgnoreCheck -- "Ignored" --> Safe
    IgnoreCheck -- "Not Ignored" --> Diag["4. Emit Diagnostic: browser.chrome-only-api"]

Loading

Step-by-Step Evaluation:

1. AST Traversal: Visits normalized ir.Node structures during AST streaming.
2. Invariant Check: Compares node attributes against rule invariants.
3. Directive Suppression Check: Honors inline charites:ignore browser.chrome-only-api directives.
4. Diagnostic Emission: Emits compiler-grade diagnostic on invariant violation.

---

7. Verification & Test Harness (How The Test Works: 1-SSOT Tri-Corpus)

This rule is rigorously tested and validated across the canonical 1-SSOT Tri-Corpus in tests/correctness/browser.chrome-only-api/:

flowchart TD
    subgraph GoldenCorpus ["1-SSOT Tri-Corpus Test Matrix for browser.chrome-only-api"]
        subgraph P ["Positive Corpus (tests/correctness/browser.chrome-only-api/positive/)"]
            P1["P1: Obvious Direct Violation"]
            P2["P2: Indirect / Variant Concatenation"]
            P3["P3: Helper / clsx / cn Wrapper"]
            P4["P4: Deeply Nested Elements"]
            P5["P5: Aliased Imports / Re-exports"]
        end
        subgraph N ["Negative Corpus (tests/correctness/browser.chrome-only-api/negative/)"]
            N1["N1: Valid Design Tokens"]
            N2["N2: Explicit charites:ignore Directive"]
            N3["N3: Third-Party / Vendor Components"]
            N4["N4: Clean Semantic HTML"]
            N5["N5: Untokenized Custom Values (Banana Test)"]
        end
        subgraph A ["Adversarial Corpus (tests/correctness/browser.chrome-only-api/adversarial/)"]
            A1["A1: Template Literal Interpolations"]
            A2["A2: Ternary Conditional Expressions"]
            A3["A3: Spread Properties & Dynamic Overrides"]
            A4["A4: Dynamic Object Class Syntax"]
            A5["A5: Shadowed Variable Identifiers"]
            A6["A6: Nested Closures & HOC Wrappers"]
            A7["A7: Obfuscated Classes & Cyclic Tokens"]
        end
    end

    P --> TestRunner["Automated Runner (rule_test.go)"]
    N --> TestRunner
    A --> TestRunner
    TestRunner --> Gates["Quality Gates: Zero Panic, Zero False-Positive, Zero Bypass"]

Loading

• Positive Fixtures (P1-P5): Verified to trigger diagnostics at exact lines and column spans.
• Negative Fixtures (N1-N5): Verified to produce zero diagnostics on valid tokens and legitimate exemptions.
• Adversarial Fixtures (A1-A7): Verified to prevent evasion across dynamic expressions, string interpolations, and cyclic references.

---

8. How to Suppress (Ignore Directives)

If this pattern is required for an intentional exception, suppress the diagnostic using the canonical Charites Rule ID:

<!-- charites:ignore browser.chrome-only-api intentional exception -->

// charites:ignore browser.chrome-only-api intentional exception

---

9. Configuration Reference (charites.yaml)

rules:
  browser.chrome-only-api:
    severity: warn # error | warn | info | off