# @stackline/har-validator 1.0.0

Canonical documentation: https://alexandro.net/docs/vanilla/har-validator/
Repository: https://github.com/alexandroit/stackline-har-validator
Registry: https://www.npmjs.com/package/@stackline/har-validator
License: MIT
Runtime: Node.js >=6; the verified compatibility floor is Node.js 6.17.1
Browser support: normal root/deep bundler graph plus root-only CJS and ESM bundles
Compatibility baseline: har-validator@5.1.5
Direct production dependencies: ajv@6.15.0 and har-schema@2.0.0

## Purpose

@stackline/har-validator validates complete HAR 1.2 archives and each schema
component. It is a compatibility-first continuation for applications that
need the unsupported har-validator API without taking ownership of schema
loading and Ajv 6 error normalization.

## Install and alias

Scoped dependency: npm install @stackline/har-validator
Compatibility alias: "har-validator": "npm:@stackline/har-validator@1.0.0"

The alias preserves require('har-validator'), lib/promise, lib/async, and
lib/error imports. Commit the manifest and lockfile together and run focused
valid/invalid application tests.

## Root Promise API

The CommonJS namespace has exactly these enumerable keys in order:
afterRequest, beforeRequest, browser, cache, content, cookie, creator, entry,
har, header, log, page, pageTimings, postData, query, request, response,
timings.

Every validator accepts an optional value and returns a Promise. Valid data
resolves to the exact input reference. Invalid data rejects with HARError.
Falsy input is normalized to an empty object before validation, matching the
baseline.

## Historical deep API

lib/promise is the root CommonJS implementation. lib/async exposes the same 18
validators: without a callback each returns a synchronous boolean; with a
callback it synchronously calls (error, valid) and returns the callback's own
return value. lib/error exports HARError. Each name works with or without .js.

HARError has name "HARError", message "validation failed", the complete Ajv
errors array, and the upstream stack behavior. It is an Error. The intentional
prototype correction means unrelated Error instances no longer satisfy
instanceof HARError.

## Validation engine

The implementation loads every HAR 1.2 draft-06 schema from har-schema@2.0.0,
adds the draft-06 meta-schema, and compiles lazily with Ajv 6.15.0 and
allErrors:true. Ajv remains on the 6.x line to preserve dataPath-based error
records and schema behavior.

The validator names cover archive/log, entries, request, response, creator,
browser, pages and timings, cache records, content and post data, cookies,
headers, and query items.

## ESM, browser, and TypeScript

The default ESM export is the Promise namespace and all 18 validators are
named exports. TypeScript 3.9-compatible CommonJS declarations and modern ESM
declarations are supplied. The Node.js 6.17.1 floor applies to CommonJS; ESM
is available where the runtime or build tool supports it.

Browser bundlers should import the normal root and deep entries to keep a
single HARError constructor identity. @stackline/har-validator/browser is an
additive self-contained root-only bundle. Ajv compiles with Function at
runtime, which may conflict with a browser Content Security Policy that blocks
dynamic code generation.

## Preserved behavior

The maintained contract includes validator property order, schema meanings,
falsy normalization, input-reference resolution, complete Ajv 6 error arrays,
synchronous boolean and callback behavior, callback return values, nullable
cache records, URI and date-time patterns, extension properties, the three
historical deep entries, and CommonJS support from Node.js 6.17.1.

## Intentional correction

Upstream assigned HARError.prototype directly to Error.prototype. The
maintained constructor uses a distinct object derived from Error.prototype.
This retains HARError instanceof Error and upstream constructor/stack behavior
without causing every ordinary Error to pass instanceof HARError.

## Security boundary

Schema validation is not JSON parsing, content sanitization, URL allowlisting,
resource limiting, or proof that an HTTP exchange occurred. Parse untrusted
input with explicit byte/depth limits, treat URLs, headers, cookies, and body
text as untrusted after validation, and bound batch size and validation work.
Do not weaken a Content Security Policy solely to accommodate runtime schema
compilation without reviewing the risk.

Report suspected vulnerabilities privately at:
https://github.com/alexandroit/stackline-har-validator/security/advisories/new

## License inventory

The package is MIT and retains Ahmad Nassri's upstream attribution. The exact
seven-component production graph is ajv 6.15.0, fast-deep-equal 3.1.3,
fast-json-stable-stringify 2.1.0, har-schema 2.0.0,
json-schema-traverse 0.4.1, punycode 2.3.1, and uri-js 4.4.1. Complete MIT,
ISC, and BSD-2-Clause texts are published with these docs and the npm package.

## References

README: https://alexandro.net/docs/vanilla/har-validator/README.md
API: https://alexandro.net/docs/vanilla/har-validator/API.md
Compatibility: https://alexandro.net/docs/vanilla/har-validator/COMPATIBILITY_CONTRACT.md
Migration: https://alexandro.net/docs/vanilla/har-validator/MIGRATION.md
Security: https://alexandro.net/docs/vanilla/har-validator/SECURITY.md
Licenses: https://alexandro.net/docs/vanilla/har-validator/THIRD_PARTY_LICENSES.md
CommonJS example: https://alexandro.net/docs/vanilla/har-validator/examples/commonjs.cjs
ESM example: https://alexandro.net/docs/vanilla/har-validator/examples/esm.mjs
Browser example: https://alexandro.net/docs/vanilla/har-validator/examples/browser.mjs
Metadata: https://alexandro.net/docs/vanilla/har-validator/package-meta.json