@cyvest/cyvest-js 7.0.0 → 7.2.0

package/dist/index.cjs

@@ -1027,6 +1027,28 @@ var cyvest_schema_default = {
 			"title": "Tag",
 			"type": "object"
 		},
+		"Taxonomy": {
+			"additionalProperties": false,
+			"description": "A named value with a display verdict. No weight, confidence or scoring effect.",
+			"properties": {
+				"name": {
+					"title": "Name",
+					"type": "string"
+				},
+				"value": {
+					"title": "Value",
+					"type": "string"
+				},
+				"verdict": {
+					"$ref": "#/$defs/Verdict",
+					"default": "INFO",
+					"description": "Descriptive only; never affects scoring"
+				}
+			},
+			"required": ["name", "value"],
+			"title": "Taxonomy",
+			"type": "object"
+		},
 		"ThreatIntel": {
 			"additionalProperties": false,
 			"description": "A verdict from a threat-intelligence source.\n\nIdentity is ``(source, subject_key)``, so a source re-asserting the same observable updates\nin place instead of piling up duplicates. Pass ``external_id`` to keep history on purpose.",
@@ -1126,7 +1148,7 @@ var cyvest_schema_default = {
 				},
 				"taxonomies": {
 					"default": [],
-					"items": { "type": "string" },
+					"items": { "$ref": "#/$defs/Taxonomy" },
 					"title": "Taxonomies",
 					"type": "array"
 				},
@@ -1165,7 +1187,7 @@ var cyvest_schema_default = {
 	description: "A complete serialized investigation.",
 	properties: {
 		"schema_version": {
-			"default": "7.0.0",
+			"default": "7.1.0",
 			"pattern": "^7\\.\\d+\\.\\d+$",
 			"title": "Schema Version",
 			"type": "string"
@@ -1211,7 +1233,7 @@ var cyvest_schema_default = {
 * window is the SDK's job alone; reading and judging the version first also keeps the error
 * message explicit instead of an opaque ajv shape error.
 */
-const SCHEMA_VERSION = "7.0.0";
+const SCHEMA_VERSION = "7.1.0";
 const SEMVER = /^\d+\.\d+\.\d+$/;
 const ajv = new ajv_dist_2020_js.default({ allErrors: true });
 (0, ajv_formats.default)(ajv);
@@ -1243,16 +1265,40 @@ function assertReadableVersion(version) {
 	if (docMajor > libMajor || docMajor === libMajor && docMinor > libMinor) throw new Error(`Document schema ${version} is newer than this SDK (${SCHEMA_VERSION}); upgrade @cyvest/cyvest-js.`);
 	if (docMajor < libMajor) throw new Error(`Document schema ${version} predates this SDK (${SCHEMA_VERSION}); run 'cyvest migrate'.`);
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Normalize 7.0 free-text taxonomies once at the input boundary, without mutating the caller. */
+function normalizeTaxonomies(json) {
+	if (!isRecord(json) || !isRecord(json.facts) || !isRecord(json.facts.signals)) return json;
+	const signals = Object.fromEntries(Object.entries(json.facts.signals).map(([key, signal]) => [key, isRecord(signal) && Array.isArray(signal.taxonomies) ? {
+		...signal,
+		taxonomies: signal.taxonomies.map((entry) => typeof entry === "string" ? {
+			name: entry,
+			value: "",
+			verdict: "INFO"
+		} : entry)
+	} : signal]));
+	return {
+		...json,
+		facts: {
+			...json.facts,
+			signals
+		}
+	};
+}
 function parseCyvest(json) {
 	assertReadableVersion(detectSchemaVersion(json));
+	const normalized = normalizeTaxonomies(json);
 	const validate = getValidator();
-	if (!validate(json)) throw new Error(`Invalid Cyvest payload: ${ajv.errorsText(validate.errors || [])}`);
-	return json;
+	if (!validate(normalized)) throw new Error(`Invalid Cyvest payload: ${ajv.errorsText(validate.errors || [])}`);
+	return normalized;
 }
+/** A type guard cannot normalize its argument: legacy strings need parseCyvest first. */
 function isCyvest(json) {
 	try {
-		parseCyvest(json);
-		return true;
+		assertReadableVersion(detectSchemaVersion(json));
+		return !!getValidator()(json);
 	} catch {
 		return false;
 	}

package/dist/index.d.cts

@@ -45,7 +45,7 @@ export type ExternalId2 = string | null;
 export type EvidenceKeys2 = string[];
 export type ObservedAt1 = string | null;
 export type Labels = Label[];
-export type Taxonomies = string[];
+export type Taxonomies = Taxonomy[];
 export type OccurredAt3 = string | null;
 export type ExternalId3 = string | null;
 export type EvidenceKeys3 = string[];
@@ -293,6 +293,14 @@ export interface Label {
 export interface Payload {
   [k: string]: unknown;
 }
+/**
+ * A named value with a display verdict. No weight, confidence or scoring effect.
+ */
+export interface Taxonomy {
+  name: string;
+  value: string;
+  verdict?: Verdict;
+}
 export interface Evidences {
   [k: string]: Evidence;
 }
@@ -526,7 +534,7 @@ type FindingResult$1 = FindingResult;
 type InvestigationResult$1 = InvestigationResult;
 //#endregion
 //#region src/helpers.d.ts
-export declare const SCHEMA_VERSION = "7.0.0";
+export declare const SCHEMA_VERSION = "7.1.0";
 /**
  * Read the declared schema version, falling back to `"5"` for anything unversioned.
  *
@@ -538,6 +546,7 @@ export declare function detectSchemaVersion(json: unknown): string;
 /** Upward compatibility only: read older documents, never newer ones. */
 export declare function assertReadableVersion(version: string): void;
 export declare function parseCyvest(json: unknown): Investigation;
+/** A type guard cannot normalize its argument: legacy strings need parseCyvest first. */
 export declare function isCyvest(json: unknown): json is Investigation;
 //#endregion
 //#region src/keys.d.ts

package/dist/index.d.ts

@@ -45,7 +45,7 @@ export type ExternalId2 = string | null;
 export type EvidenceKeys2 = string[];
 export type ObservedAt1 = string | null;
 export type Labels = Label[];
-export type Taxonomies = string[];
+export type Taxonomies = Taxonomy[];
 export type OccurredAt3 = string | null;
 export type ExternalId3 = string | null;
 export type EvidenceKeys3 = string[];
@@ -293,6 +293,14 @@ export interface Label {
 export interface Payload {
   [k: string]: unknown;
 }
+/**
+ * A named value with a display verdict. No weight, confidence or scoring effect.
+ */
+export interface Taxonomy {
+  name: string;
+  value: string;
+  verdict?: Verdict;
+}
 export interface Evidences {
   [k: string]: Evidence;
 }
@@ -526,7 +534,7 @@ type FindingResult$1 = FindingResult;
 type InvestigationResult$1 = InvestigationResult;
 //#endregion
 //#region src/helpers.d.ts
-export declare const SCHEMA_VERSION = "7.0.0";
+export declare const SCHEMA_VERSION = "7.1.0";
 /**
  * Read the declared schema version, falling back to `"5"` for anything unversioned.
  *
@@ -538,6 +546,7 @@ export declare function detectSchemaVersion(json: unknown): string;
 /** Upward compatibility only: read older documents, never newer ones. */
 export declare function assertReadableVersion(version: string): void;
 export declare function parseCyvest(json: unknown): Investigation;
+/** A type guard cannot normalize its argument: legacy strings need parseCyvest first. */
 export declare function isCyvest(json: unknown): json is Investigation;
 //#endregion
 //#region src/keys.d.ts

package/dist/index.js

@@ -1002,6 +1002,28 @@ var cyvest_schema_default = {
 			"title": "Tag",
 			"type": "object"
 		},
+		"Taxonomy": {
+			"additionalProperties": false,
+			"description": "A named value with a display verdict. No weight, confidence or scoring effect.",
+			"properties": {
+				"name": {
+					"title": "Name",
+					"type": "string"
+				},
+				"value": {
+					"title": "Value",
+					"type": "string"
+				},
+				"verdict": {
+					"$ref": "#/$defs/Verdict",
+					"default": "INFO",
+					"description": "Descriptive only; never affects scoring"
+				}
+			},
+			"required": ["name", "value"],
+			"title": "Taxonomy",
+			"type": "object"
+		},
 		"ThreatIntel": {
 			"additionalProperties": false,
 			"description": "A verdict from a threat-intelligence source.\n\nIdentity is ``(source, subject_key)``, so a source re-asserting the same observable updates\nin place instead of piling up duplicates. Pass ``external_id`` to keep history on purpose.",
@@ -1101,7 +1123,7 @@ var cyvest_schema_default = {
 				},
 				"taxonomies": {
 					"default": [],
-					"items": { "type": "string" },
+					"items": { "$ref": "#/$defs/Taxonomy" },
 					"title": "Taxonomies",
 					"type": "array"
 				},
@@ -1140,7 +1162,7 @@ var cyvest_schema_default = {
 	description: "A complete serialized investigation.",
 	properties: {
 		"schema_version": {
-			"default": "7.0.0",
+			"default": "7.1.0",
 			"pattern": "^7\\.\\d+\\.\\d+$",
 			"title": "Schema Version",
 			"type": "string"
@@ -1186,7 +1208,7 @@ var cyvest_schema_default = {
 * window is the SDK's job alone; reading and judging the version first also keeps the error
 * message explicit instead of an opaque ajv shape error.
 */
-const SCHEMA_VERSION = "7.0.0";
+const SCHEMA_VERSION = "7.1.0";
 const SEMVER = /^\d+\.\d+\.\d+$/;
 const ajv = new Ajv2020({ allErrors: true });
 addFormats(ajv);
@@ -1218,16 +1240,40 @@ function assertReadableVersion(version) {
 	if (docMajor > libMajor || docMajor === libMajor && docMinor > libMinor) throw new Error(`Document schema ${version} is newer than this SDK (${SCHEMA_VERSION}); upgrade @cyvest/cyvest-js.`);
 	if (docMajor < libMajor) throw new Error(`Document schema ${version} predates this SDK (${SCHEMA_VERSION}); run 'cyvest migrate'.`);
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Normalize 7.0 free-text taxonomies once at the input boundary, without mutating the caller. */
+function normalizeTaxonomies(json) {
+	if (!isRecord(json) || !isRecord(json.facts) || !isRecord(json.facts.signals)) return json;
+	const signals = Object.fromEntries(Object.entries(json.facts.signals).map(([key, signal]) => [key, isRecord(signal) && Array.isArray(signal.taxonomies) ? {
+		...signal,
+		taxonomies: signal.taxonomies.map((entry) => typeof entry === "string" ? {
+			name: entry,
+			value: "",
+			verdict: "INFO"
+		} : entry)
+	} : signal]));
+	return {
+		...json,
+		facts: {
+			...json.facts,
+			signals
+		}
+	};
+}
 function parseCyvest(json) {
 	assertReadableVersion(detectSchemaVersion(json));
+	const normalized = normalizeTaxonomies(json);
 	const validate = getValidator();
-	if (!validate(json)) throw new Error(`Invalid Cyvest payload: ${ajv.errorsText(validate.errors || [])}`);
-	return json;
+	if (!validate(normalized)) throw new Error(`Invalid Cyvest payload: ${ajv.errorsText(validate.errors || [])}`);
+	return normalized;
 }
+/** A type guard cannot normalize its argument: legacy strings need parseCyvest first. */
 function isCyvest(json) {
 	try {
-		parseCyvest(json);
-		return true;
+		assertReadableVersion(detectSchemaVersion(json));
+		return !!getValidator()(json);
 	} catch {
 		return false;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyvest/cyvest-js",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Typed reader for Cyvest investigation documents: schema validation, fact accessors, and graph helpers.",
   "keywords": [
     "cybersecurity",