nexarch 0.12.6 → 0.12.7

package/dist/lib/terraform-projection.js

@@ -0,0 +1,231 @@
+/**
+ * Terraform state projector (ADR: infrastructure-as-code ingestion, v1).
+ *
+ * Turns `terraform show -json` into the small, safe projection that ingestion
+ * is allowed to send. This is the security-critical component of the feature:
+ * state files carry generated passwords, storage keys, connection strings and
+ * certificate material in clear text, verified against a real estate.
+ *
+ * Two independent gates, both deny-by-default:
+ *
+ *   1. The catalogue names, per resource type, the attributes that may be read.
+ *      Anything not named is dropped. The catalogue is reference data served by
+ *      the platform, not a list baked into this CLI, so support for a new Azure
+ *      service is a data change rather than a release.
+ *
+ *   2. Terraform's own `sensitive_values` map is consulted for every attribute
+ *      that survives gate 1, and anything flagged there is dropped even when the
+ *      catalogue names it. A mistake in the curated list is therefore not on its
+ *      own sufficient to leak a secret.
+ *
+ * Values are additionally restricted to scalars and shallow string arrays.
+ * Nested blocks are never emitted wholesale: a container app's `secret` block or
+ * an env var's `value` can hold credentials, so structure is only ever read by a
+ * named extractor that has been reviewed for that purpose.
+ */
+/**
+ * Parses a state document from raw bytes.
+ *
+ * PowerShell's `>` redirection writes UTF-16 with a BOM, which is what a Windows
+ * user gets from `terraform show -json > state.json` and what a naive reader
+ * chokes on. Both endiannesses and plain UTF-8 are accepted.
+ */
+export function parseTerraformStateBuffer(buffer) {
+    let text;
+    if (buffer[0] === 0xff && buffer[1] === 0xfe)
+        text = buffer.toString("utf16le");
+    else if (buffer[0] === 0xfe && buffer[1] === 0xff)
+        text = Buffer.from(buffer).swap16().toString("utf16le");
+    else
+        text = buffer.toString("utf8");
+    return JSON.parse(text.replace(/^/, ""));
+}
+/**
+ * Infers the environment from resource tags.
+ *
+ * Estates that tag at all tag consistently — the first real one carried
+ * `environment` on every resource — so the dominant value of a conventional tag
+ * key beats asking a human to pass a flag correctly in a pipeline. Returns null
+ * when there is no clear winner, leaving the caller to fall back to the
+ * Terraform workspace or an explicit flag.
+ */
+export function inferEnvironmentFromTags(resources) {
+    const TAG_KEYS = ["environment", "env", "Environment", "Env"];
+    const counts = new Map();
+    for (const resource of resources) {
+        for (const key of TAG_KEYS) {
+            const value = resource.tags[key];
+            if (typeof value !== "string" || !value.trim())
+                continue;
+            const normalised = value.trim().toLowerCase();
+            counts.set(normalised, (counts.get(normalised) ?? 0) + 1);
+            break;
+        }
+    }
+    if (counts.size === 0)
+        return null;
+    const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    const [environment, hits] = ranked[0];
+    const total = ranked.reduce((sum, [, n]) => sum + n, 0);
+    return { environment, confidence: hits / total };
+}
+/** Maps a free-text environment name onto an ontology environment subtype. */
+export function environmentSubtypeFor(environment) {
+    const name = environment.trim().toLowerCase();
+    if (/^(prod|production|live)$/.test(name))
+        return "env_production";
+    if (/^(stag|staging|preprod|pre-prod|uat)$/.test(name))
+        return "env_staging";
+    if (/^(test|qa|sit)$/.test(name))
+        return "env_test";
+    if (/^(dr|failover)$/.test(name))
+        return "env_dr";
+    return "env_development";
+}
+/** Longest value we will carry for any single attribute. */
+const MAX_VALUE_LENGTH = 400;
+const MAX_ARRAY_ITEMS = 12;
+function flattenResources(module, out = []) {
+    if (!module)
+        return out;
+    for (const resource of module.resources ?? [])
+        out.push(resource);
+    for (const child of module.child_modules ?? [])
+        flattenResources(child, out);
+    return out;
+}
+/**
+ * True when Terraform flagged this attribute as sensitive. The map mirrors the
+ * shape of `values`, so a `true` anywhere beneath the attribute — an env var's
+ * value inside a container template, for instance — disqualifies the whole
+ * attribute rather than just the leaf.
+ */
+function isSensitive(sensitiveValues, attribute) {
+    if (!sensitiveValues || typeof sensitiveValues !== "object" || Array.isArray(sensitiveValues))
+        return false;
+    const flag = sensitiveValues[attribute];
+    if (flag === undefined)
+        return false;
+    if (flag === true)
+        return true;
+    return JSON.stringify(flag).includes("true");
+}
+/** Scalars and shallow string arrays only; anything structural is refused. */
+function safeValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return value.length > MAX_VALUE_LENGTH ? value.slice(0, MAX_VALUE_LENGTH) : value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+        return value.slice(0, MAX_ARRAY_ITEMS).map((item) => item.slice(0, MAX_VALUE_LENGTH));
+    }
+    return null;
+}
+/**
+ * Tags carry the binding convention, so they are read — but a tag whose value
+ * Terraform flagged, or which does not look like a label, is left behind.
+ */
+function projectTags(values, sensitiveValues) {
+    if (isSensitive(sensitiveValues, "tags"))
+        return {};
+    const raw = values.tags;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const tags = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== "string")
+            continue;
+        if (value.length > 200)
+            continue;
+        tags[key] = value;
+    }
+    return tags;
+}
+/**
+ * User-assigned identity references. Reviewed extractor: identity ids are
+ * resource paths, never credentials, and they are how a workload is tied to the
+ * role assignments that define what it may reach.
+ */
+function projectIdentityIds(values) {
+    const identity = values.identity;
+    if (!Array.isArray(identity))
+        return [];
+    const ids = [];
+    for (const block of identity) {
+        if (!block || typeof block !== "object")
+            continue;
+        const identityIds = block.identity_ids;
+        if (!Array.isArray(identityIds))
+            continue;
+        for (const id of identityIds)
+            if (typeof id === "string")
+                ids.push(id);
+    }
+    return ids.slice(0, MAX_ARRAY_ITEMS);
+}
+export function projectTerraformState(params) {
+    const { document, catalogue, environment } = params;
+    const byType = new Map(catalogue.map((entry) => [entry.resourceType, entry]));
+    const resources = flattenResources(document.values?.root_module);
+    const projected = [];
+    const unknown = new Map();
+    let attributesDroppedNotAllowlisted = 0;
+    let attributesDroppedSensitive = 0;
+    for (const resource of resources) {
+        const resourceType = typeof resource.type === "string" ? resource.type : "";
+        if (!resourceType)
+            continue;
+        const entry = byType.get(resourceType);
+        if (!entry) {
+            unknown.set(resourceType, (unknown.get(resourceType) ?? 0) + 1);
+            continue;
+        }
+        const values = (resource.values && typeof resource.values === "object" ? resource.values : {});
+        const sensitiveValues = resource.sensitive_values;
+        const attributes = {};
+        for (const [key, value] of Object.entries(values)) {
+            if (!entry.attributes.includes(key)) {
+                attributesDroppedNotAllowlisted += 1;
+                continue;
+            }
+            if (isSensitive(sensitiveValues, key)) {
+                attributesDroppedSensitive += 1;
+                continue;
+            }
+            const safe = safeValue(value);
+            if (safe === null) {
+                attributesDroppedNotAllowlisted += 1;
+                continue;
+            }
+            attributes[key] = safe;
+        }
+        projected.push({
+            address: typeof resource.address === "string" ? resource.address : `${resourceType}.${resource.name ?? "unknown"}`,
+            resourceType,
+            entityTypeCode: entry.entityTypeCode,
+            entitySubtypeCode: entry.entitySubtypeCode ?? null,
+            role: entry.role,
+            mode: typeof resource.mode === "string" ? resource.mode : "managed",
+            name: typeof values.name === "string" ? values.name : null,
+            attributes,
+            tags: projectTags(values, sensitiveValues),
+            identityIds: projectIdentityIds(values),
+        });
+    }
+    return {
+        environment,
+        terraformVersion: typeof document.terraform_version === "string" ? document.terraform_version : null,
+        resources: projected,
+        unknownTypes: [...unknown.entries()]
+            .map(([resourceType, count]) => ({ resourceType, count }))
+            .sort((a, b) => b.count - a.count),
+        stats: {
+            resourcesSeen: resources.length,
+            resourcesProjected: projected.length,
+            attributesDroppedNotAllowlisted,
+            attributesDroppedSensitive,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",