@browsercore/profiles 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Domain types for @browsercore/profiles.
+ *
+ * Pure data: this package defines WHAT a browser fingerprint looks like, never
+ * HOW to emit it on the wire. Protocol implementations (tls, http1, http2) read
+ * these definitions and translate them into bytes / header order / settings frames.
+ */
+/** Branded browser-profile identifier (e.g. "chrome-140"). */
+export type ProfileId = string & {
+    __brand: "ProfileId";
+};
+/** Known browser families. Discriminated-union literal set. */
+export type ProfileName = "chrome" | "firefox" | "safari" | "edge";
+/** TLS-layer fingerprint: everything a TLS client hello reveals about the client. */
+export interface TlsProfile {
+    /** Ordered list of offered cipher suites (IANA names). Order matters for fingerprinting. */
+    readonly cipherSuites: readonly string[];
+    /** Order of TLS extensions in the ClientHello. */
+    readonly extensionOrder: readonly number[];
+    /** Supported TLS versions, highest first. */
+    readonly supportedVersions: readonly string[];
+    /** Key-share groups offered (TLS 1.3). */
+    readonly keyShareGroups: readonly string[];
+    /** Signature algorithms offered. */
+    readonly signatureAlgorithms: readonly string[];
+    /** record_size_limit extension value, if advertised. Absent when not sent. */
+    readonly recordSizeLimit?: number;
+    /** Whether this browser randomizes with GREASE values (RFC 8701). */
+    readonly grease: boolean;
+}
+/** HTTP/2 SETTINGS + tuning parameters. */
+export interface Http2Profile {
+    /** HTTP/2 settings the client sends in its first SETTINGS frame. */
+    readonly settings: Partial<Http2Settings>;
+    /** Initial TCP-level / stream window size in bytes. */
+    readonly initialWindowSize: number;
+    /** SETTINGS_MAX_FRAME_SIZE advertised by the client. */
+    readonly maxFrameSize: number;
+    /** SETTINGS_HEADER_TABLE_SIZE advertised by the client. */
+    readonly headerTableSize: number;
+    /** Default stream weight (1-256). */
+    readonly weight: number;
+    /** Default priority dependency / exclusive flag, if any. */
+    readonly priority?: Http2Priority;
+}
+/** HTTP/2 numeric settings (RFC 9113 §6.5.1). */
+export interface Http2Settings {
+    readonly headerTableSize: number;
+    readonly enablePush: boolean;
+    readonly maxConcurrentStreams: number;
+    readonly initialWindowSize: number;
+    readonly maxFrameSize: number;
+    readonly maxHeaderListSize: number;
+}
+/** HTTP/2 stream priority descriptor. */
+export interface Http2Priority {
+    readonly streamDependency: number;
+    readonly exclusive: boolean;
+    readonly weight: number;
+}
+/** HTTP/1.1-layer fingerprint: header defaults and ordering. */
+export interface Http1Profile {
+    /** Default headers sent on every request, in order. */
+    readonly defaultHeaders: Readonly<Record<string, string>>;
+    /** Order in which headers are serialized (client-enforced). */
+    readonly headerOrder: readonly string[];
+    /** Connection header value. */
+    readonly connection: "keep-alive" | "close";
+    /** Accept-Encoding value sent by default. */
+    readonly acceptEncoding: string;
+}
+/** A complete browser fingerprint across all layers. */
+export interface BrowserProfile {
+    readonly id: ProfileId;
+    /** Human-readable browser name. */
+    readonly name: string;
+    /** Browser version string (e.g. "140.0.7339.18"). */
+    readonly version: string;
+    readonly tls: TlsProfile;
+    readonly http2: Http2Profile;
+    readonly http1: Http1Profile;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GACjB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,MAAM,CAAC;AAEb,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,6CAA6C;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,0CAA0C;IAC1C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,oCAAoC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC5B;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;CACrC;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACtC;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IACzB,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACnC;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAChC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Domain types for @browsercore/profiles.
+ *
+ * Pure data: this package defines WHAT a browser fingerprint looks like, never
+ * HOW to emit it on the wire. Protocol implementations (tls, http1, http2) read
+ * these definitions and translate them into bytes / header order / settings frames.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Small shared helpers for @browsercore/profiles.
+ *
+ * Kept dependency-free so every package can copy the pattern without pulling in
+ * cross-package imports.
+ */
+/**
+ * Exhaustiveness check for `switch`/`if-else` over discriminated unions.
+ * Call in the `default` branch: `default: assertNever(x)`.
+ * Adding a new union member forces every handler to compile-error until handled.
+ */
+export declare function assertNever(x: never): never;
+/**
+ * Build a branded {@link ProfileId} from a browser name + version.
+ * Format: `${name}-${version}`, e.g. "chrome-140".
+ */
+export declare function createId(name: string, version: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AAEH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAE3C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/utils.js

@@ -0,0 +1,23 @@
+/**
+ * Small shared helpers for @browsercore/profiles.
+ *
+ * Kept dependency-free so every package can copy the pattern without pulling in
+ * cross-package imports.
+ */
+/**
+ * Exhaustiveness check for `switch`/`if-else` over discriminated unions.
+ * Call in the `default` branch: `default: assertNever(x)`.
+ * Adding a new union member forces every handler to compile-error until handled.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function assertNever(x) {
+    throw new Error(`Unexpected value: ${JSON.stringify(x)}`);
+}
+/**
+ * Build a branded {@link ProfileId} from a browser name + version.
+ * Format: `${name}-${version}`, e.g. "chrome-140".
+ */
+export function createId(name, version) {
+    return `${name}-${version}`;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAAC,CAAQ;IAChC,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAe;IAClD,OAAO,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC;AAChC,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Profile validation against real captures.
+ *
+ * Real Wireshark / JA4 captures are produced later by the testing package; this
+ * module is the reusable utility that consumes them. It projects a profile's TLS
+ * fields onto the wire values a ClientHello would carry, then compares those
+ * expectations to a captured ClientHello, reporting diffs.
+ *
+ * A key honesty: GREASE (RFC 8701) values are randomized per-connection, so a
+ * profile cannot predict the exact GREASE bytes. We handle this where the data
+ * lets us — cipher suites mark GREASE slots with a named placeholder, so a
+ * GREASE slot in the profile matches any GREASE-pattern byte pair in the capture.
+ * Extension GREASE is not handled here because the profile stores literal wire
+ * codes for extensions (not placeholders), so it cannot robustly flag a GREASE
+ * extension slot. See the per-field comments below.
+ */
+import type { BrowserProfile } from "./types.js";
+import type { ProfileDiff } from "./diff.js";
+import { ProfileError } from "./errors.js";
+/** A captured ClientHello, as parsed out of a packet capture by the testing package. */
+export interface TlsCapture {
+    /** Offered cipher suites as IANA 2-byte codes, in wire order. */
+    readonly cipherSuites: readonly number[];
+    /** Extension type codes present, in wire order. */
+    readonly extensionTypes: readonly number[];
+    /** Supported versions advertised, as 2-byte codes, highest first. */
+    readonly supportedVersions: readonly number[];
+    /** Key-share named-group ids offered. */
+    readonly keyShareGroups: readonly number[];
+    /** Signature algorithm codes offered. */
+    readonly signatureAlgorithms: readonly number[];
+    /** Whether the ClientHello used GREASE randomization. */
+    readonly grease: boolean;
+    /** Optional JA3 / JA4 strings, when the capture tool computed them. */
+    readonly ja3?: string;
+    readonly ja4?: string;
+}
+/** The wire values a profile's ClientHello is expected to carry. */
+export interface ClientHelloExpected {
+    /** Cipher suites as IANA 2-byte codes, in wire order. */
+    readonly cipherSuites: readonly number[];
+    /** Extension type codes, in wire order. */
+    readonly extensionTypes: readonly number[];
+    /** Supported versions as 2-byte codes, highest first. */
+    readonly supportedVersions: readonly number[];
+    /** Key-share named-group ids. */
+    readonly keyShareGroups: readonly number[];
+    /** Signature algorithm codes. */
+    readonly signatureAlgorithms: readonly number[];
+    /** Whether GREASE randomization is expected. */
+    readonly grease: boolean;
+    /** SNI hostname the client would send, derived from the connection target. */
+    readonly sni: string;
+}
+/** Validation / projection failure (unknown profile value, bad capture, etc.). */
+export declare class ValidationError extends ProfileError {
+    readonly kind: "ValidationError";
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Project a profile's TLS fields onto the wire values its ClientHello should
+ * carry for a connection to `serverName`. Extension order is taken verbatim from
+ * the profile (already stored as wire codes), since extension order is a
+ * fingerprint signal.
+ */
+export declare function buildExpectedClientHello(profile: BrowserProfile, serverName: string): ClientHelloExpected;
+/**
+ * Validate a profile against a captured ClientHello.
+ *
+ * Returns `ok: true` when every field matches (respecting GREASE randomization
+ * for cipher suites), and the list of diffs otherwise. SNI is not compared
+ * because captures do not record the destination hostname.
+ */
+export declare function validateProfileAgainstCapture(profile: BrowserProfile, capture: TlsCapture): {
+    ok: boolean;
+    diffs: ProfileDiff[];
+};
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACvB,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,yCAAyC;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yCAAyC;IACzC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAChC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yDAAyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,iCAAiC;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACxB;AAmED,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,YAAY;IAC7C,SAAyB,IAAI,EAAG,iBAAiB,CAAU;gBAE/C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAI3D;AAkCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,GACnB,mBAAmB,CAUrB;AAsDD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CACzC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,UAAU,GACpB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,CAoBvC"}

package/dist/validate.js

@@ -0,0 +1,185 @@
+/**
+ * Profile validation against real captures.
+ *
+ * Real Wireshark / JA4 captures are produced later by the testing package; this
+ * module is the reusable utility that consumes them. It projects a profile's TLS
+ * fields onto the wire values a ClientHello would carry, then compares those
+ * expectations to a captured ClientHello, reporting diffs.
+ *
+ * A key honesty: GREASE (RFC 8701) values are randomized per-connection, so a
+ * profile cannot predict the exact GREASE bytes. We handle this where the data
+ * lets us — cipher suites mark GREASE slots with a named placeholder, so a
+ * GREASE slot in the profile matches any GREASE-pattern byte pair in the capture.
+ * Extension GREASE is not handled here because the profile stores literal wire
+ * codes for extensions (not placeholders), so it cannot robustly flag a GREASE
+ * extension slot. See the per-field comments below.
+ */
+import { ProfileError } from "./errors.js";
+/** The name Chrome uses in its cipher list to mark a GREASE slot (RFC 8701). */
+const CIPHER_GREASE_PLACEHOLDER = "TLS_GREASE_RESERVED_0";
+/**
+ * IANA TLS Cipher Suite Registry — selected codes.
+ *
+ * Values are the canonical 2-byte wire codes from
+ * <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4>.
+ * Only the suites used by the shipped profiles are mapped; an unknown name is a
+ * bug in a profile definition and throws.
+ */
+const CIPHER_SUITE_CODES = {
+    // GREASE: real value is randomized per-connection (0x0a0a..0xfafa). We use the
+    // first canonical GREASE code for the expected representation; validation
+    // accepts any GREASE-pattern value at a GREASE slot.
+    [CIPHER_GREASE_PLACEHOLDER]: 0x0a0a,
+    TLS_AES_128_GCM_SHA256: 0x1301,
+    TLS_AES_256_GCM_SHA384: 0x1302,
+    TLS_CHACHA20_POLY1305_SHA256: 0x1303,
+    TLS_AES_128_CCM_SHA256: 0x1304,
+    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: 0xc02b,
+    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: 0xc02f,
+    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: 0xc02c,
+    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: 0xc030,
+    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: 0xcca9,
+    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: 0xcca8,
+    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA: 0xc013,
+    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA: 0xc014,
+    TLS_RSA_WITH_AES_128_GCM_SHA256: 0x009c,
+    TLS_RSA_WITH_AES_256_GCM_SHA384: 0x009d,
+    TLS_RSA_WITH_AES_128_CBC_SHA: 0x002f,
+    TLS_RSA_WITH_AES_256_CBC_SHA: 0x0035,
+};
+/**
+ * IANA TLS Supported Groups Registry (named groups) — selected codes.
+ * <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8>
+ */
+const NAMED_GROUP_CODES = {
+    x25519: 0x001d,
+    secp256r1: 0x0017,
+    secp384r1: 0x0018,
+};
+/**
+ * IANA TLS SignatureScheme Registry — selected codes.
+ * <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16>
+ */
+const SIGNATURE_SCHEME_CODES = {
+    ecdsa_secp256r1_sha256: 0x0403,
+    rsa_pss_rsae_sha256: 0x0804,
+    rsa_pkcs1_sha256: 0x0401,
+    ecdsa_secp384r1_sha384: 0x0503,
+    rsa_pss_rsae_sha384: 0x0805,
+    rsa_pkcs1_sha384: 0x0501,
+};
+/** IANA TLS ProtocolVersion codes for the supported_versions extension. */
+const VERSION_CODES = {
+    "TLS 1.3": 0x0304,
+    "TLS 1.2": 0x0303,
+    "TLS 1.1": 0x0302,
+    "TLS 1.0": 0x0301,
+};
+/** Validation / projection failure (unknown profile value, bad capture, etc.). */
+export class ValidationError extends ProfileError {
+    kind = "ValidationError";
+    constructor(message, options) {
+        super("ValidationError", message, options);
+        this.name = "ValidationError";
+    }
+}
+function lookupCode(map, name, field) {
+    const code = map[name];
+    if (code === undefined) {
+        throw new ValidationError(`Unknown ${field}: ${name}`);
+    }
+    return code;
+}
+/** Map a cipher-suite name to its 2-byte IANA code. */
+function mapCipherSuite(name) {
+    return lookupCode(CIPHER_SUITE_CODES, name, "cipher suite");
+}
+/** Map a named-group name to its IANA id. */
+function mapNamedGroup(name) {
+    return lookupCode(NAMED_GROUP_CODES, name, "named group");
+}
+/** Map a signature-scheme name to its IANA code. */
+function mapSignatureScheme(name) {
+    return lookupCode(SIGNATURE_SCHEME_CODES, name, "signature scheme");
+}
+/** Map a TLS version string to its 2-byte wire code. */
+function mapVersion(name) {
+    return lookupCode(VERSION_CODES, name, "TLS version");
+}
+/**
+ * Project a profile's TLS fields onto the wire values its ClientHello should
+ * carry for a connection to `serverName`. Extension order is taken verbatim from
+ * the profile (already stored as wire codes), since extension order is a
+ * fingerprint signal.
+ */
+export function buildExpectedClientHello(profile, serverName) {
+    return {
+        cipherSuites: profile.tls.cipherSuites.map(mapCipherSuite),
+        extensionTypes: Array.from(profile.tls.extensionOrder),
+        supportedVersions: profile.tls.supportedVersions.map(mapVersion),
+        keyShareGroups: profile.tls.keyShareGroups.map(mapNamedGroup),
+        signatureAlgorithms: profile.tls.signatureAlgorithms.map(mapSignatureScheme),
+        grease: profile.tls.grease,
+        sni: serverName,
+    };
+}
+/** A 2-byte value matches the GREASE pattern 0x?a?a (high byte === low byte). */
+function isGreaseValue(v) {
+    return (v >> 8) === (v & 0xff);
+}
+/**
+ * Element-wise diff of two numeric arrays, reporting one {@link ProfileDiff} per
+ * mismatched index (including length differences).
+ */
+function diffNumberArray(path, expected, actual, out) {
+    const n = Math.max(expected.length, actual.length);
+    for (let i = 0; i < n; i++) {
+        const e = expected[i];
+        const c = actual[i];
+        if (e !== c) {
+            out.push({ path: `${path}[${i}]`, a: e, b: c });
+        }
+    }
+}
+/** Diff cipher suites with GREASE awareness: a GREASE slot matches any GREASE-pattern value. */
+function diffCipherSuites(profile, expected, capture, out) {
+    const n = Math.max(expected.length, capture.length);
+    for (let i = 0; i < n; i++) {
+        const path = `tls.cipherSuites[${i}]`;
+        const e = expected[i];
+        const c = capture[i];
+        const greaseSlot = profile.tls.cipherSuites[i] === CIPHER_GREASE_PLACEHOLDER;
+        if (greaseSlot) {
+            // Profile reserves a GREASE slot; accept any GREASE-pattern value, but a
+            // missing or non-GREASE value is still a mismatch.
+            if (c === undefined || !isGreaseValue(c)) {
+                out.push({ path, a: e, b: c });
+            }
+            continue;
+        }
+        if (e !== c) {
+            out.push({ path, a: e, b: c });
+        }
+    }
+}
+/**
+ * Validate a profile against a captured ClientHello.
+ *
+ * Returns `ok: true` when every field matches (respecting GREASE randomization
+ * for cipher suites), and the list of diffs otherwise. SNI is not compared
+ * because captures do not record the destination hostname.
+ */
+export function validateProfileAgainstCapture(profile, capture) {
+    const expected = buildExpectedClientHello(profile, "");
+    const diffs = [];
+    diffCipherSuites(profile, expected.cipherSuites, capture.cipherSuites, diffs);
+    diffNumberArray("tls.extensionTypes", expected.extensionTypes, capture.extensionTypes, diffs);
+    diffNumberArray("tls.supportedVersions", expected.supportedVersions, capture.supportedVersions, diffs);
+    diffNumberArray("tls.keyShareGroups", expected.keyShareGroups, capture.keyShareGroups, diffs);
+    diffNumberArray("tls.signatureAlgorithms", expected.signatureAlgorithms, capture.signatureAlgorithms, diffs);
+    if (expected.grease !== capture.grease) {
+        diffs.push({ path: "tls.grease", a: expected.grease, b: capture.grease });
+    }
+    return { ok: diffs.length === 0, diffs };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@browsercore/profiles",
+  "version": "0.1.0",
+  "description": "Browser fingerprint definitions (TLS / HTTP/2 / HTTP/1.1). Pure data — no protocol implementation.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jverneuer/browsercore-profiles.git"
+  },
+  "homepage": "https://github.com/jverneuer/browsercore-profiles#readme",
+  "bugs": {
+    "url": "https://github.com/jverneuer/browsercore-profiles/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}