@atlasent/safeguard-manifest 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @atlasent/safeguard-manifest
+
+Versioned, deterministic projection of the **authoritative safeguard package**
+(`contract/safeguard-pack/`) into the **design / EXPECTED facts** a consumer needs
+to render the console **SafeguardMap** — per protected action: owner, authority,
+expected evidence sources, and expected gates.
+
+## What this is (and is NOT)
+
+- **IS:** expected/design truth. What each safeguard is *designed to require*.
+- **IS NOT:** runtime observed state. It carries **no** enforcement mode in
+  effect, verification status, coverage, or observed gaps. Those stay live in the
+  runtime and are joined by the consumer.
+
+The manifest exists so the console never hand-maintains a semantic copy that can
+drift from the Canon / package. This is the single authoritative feed.
+
+## The three states it enables
+
+The consumer joins this manifest with live runtime facts to produce a
+reconciliation view over three distinct states:
+
+| State | Source |
+|---|---|
+| **Expected** | this manifest (versioned safeguard package) |
+| **Configured** | runtime — current configuration (enforcement mode, bound bundle) |
+| **Proven** | runtime — execution + verification evidence (verification_events, coverage) |
+
+A safeguard is **not "covered"** merely because it is in the package (Expected) or
+configured in runtime (Configured) — coverage requires observed runtime + acceptance
+evidence (Proven). Where Expected and Configured/Proven disagree, the consumer
+displays the discrepancy as a **gap**; it must not reconcile or reinterpret it.
+
+## Regeneration & determinism
+
+The JSON is generated by `scripts/generate-safeguard-manifest.py` (in the repo
+root) from the authoritative YAML. It is **deterministic** — same inputs produce
+byte-identical output, so CI fails on any unexpected regeneration diff:
+
+```bash
+python3 scripts/generate-safeguard-manifest.py           # regenerate
+python3 scripts/generate-safeguard-manifest.py --check    # CI: fail if stale
+```
+
+**Do not hand-edit `safeguard-manifest.json`.** Change the authoritative
+`contract/safeguard-pack/*` YAML and regenerate.
+
+## Provenance
+
+- `provenance.source_files[]` records the SHA-256 of each authoritative input —
+  identifying the exact inputs deterministically (no volatile git SHA / timestamp
+  in the artifact, so `--check` stays stable).
+- Release/commit provenance is bound **at publish time** via npm `--provenance`
+  (Sigstore keyless, same trust model as the other AtlaSent published packages).
+
+## Distribution & pinning
+
+Published through the existing packages release path (`v1_1-release.yml` packs +
+cosign-signs every non-private `packages/*` on a version tag). **Consumers pin an
+explicit `manifest_version` / package version** — never silently consume "latest"
+— and validate the manifest against `safeguard-manifest.schema.json`
+(`schema_version` + provenance) before use.
+
+## Usage
+
+```ts
+import {
+  safeguardManifest,
+  getSafeguardAction,
+  SAFEGUARD_MANIFEST_VERSION,
+} from "@atlasent/safeguard-manifest";
+
+const deploy = getSafeguardAction("production.deploy");
+deploy?.owner_role;                 // expected owner (design)
+deploy?.expected_evidence_sources;  // expected evidence sources (design)
+```

package/index.d.ts

@@ -0,0 +1,61 @@
+// Type declarations for @atlasent/safeguard-manifest (zero-build package).
+// The manifest carries DESIGN / EXPECTED facts only — no runtime observed state.
+
+export interface SafeguardEvidenceSource {
+  capability_id: string;
+  tools: string[];
+  /** Human safeguard label (only present for actions with a product safeguard-map). */
+  safeguard?: string;
+  source?: string;
+}
+
+export interface SafeguardGateSatisfier {
+  capability_id: string;
+  via_tools: string[];
+}
+
+export interface SafeguardExpectedGate {
+  gate: string;
+  required_assertion_class?: string;
+  satisfied_by: SafeguardGateSatisfier[];
+}
+
+export interface SafeguardAction {
+  id: string;
+  business_action: string | null;
+  slug: string;
+  canon_id: string | null;
+  act_id: string | null;
+  risk_posture: string | null;
+  /** DESIGN facts — the owner/authority the safeguard is designed to require. */
+  owner_role: string | null;
+  owner_display_name: string | null;
+  owner_maps_to_org_role: string | null;
+  approver_role: string | null;
+  /** Recommended STARTING enforcement mode — a design recommendation, NOT the runtime's observed mode. */
+  recommended_lifecycle: string | null;
+  expected_gates: SafeguardExpectedGate[];
+  expected_evidence_sources: SafeguardEvidenceSource[];
+}
+
+export interface SafeguardManifestProvenance {
+  source_repo: string;
+  source_files: Array<{ path: string; sha256: string }>;
+}
+
+export interface SafeguardManifest {
+  schema_version: string;
+  manifest_version: string;
+  kind: "safeguard-manifest";
+  generated_by?: string;
+  notice?: string;
+  provenance: SafeguardManifestProvenance;
+  actions: SafeguardAction[];
+}
+
+export declare const safeguardManifest: SafeguardManifest;
+export declare const SAFEGUARD_MANIFEST_SCHEMA_VERSION: string;
+export declare const SAFEGUARD_MANIFEST_VERSION: string;
+export declare function getSafeguardAction(idOrSlug: string): SafeguardAction | undefined;
+declare const _default: SafeguardManifest;
+export default _default;

package/index.js

@@ -0,0 +1,28 @@
+// @atlasent/safeguard-manifest — zero-build entry.
+//
+// The manifest JSON is GENERATED by scripts/generate-safeguard-manifest.py from
+// contract/safeguard-pack/*. This module is a thin, dependency-free re-export so
+// consumers get typed access (see index.d.ts) without a build step.
+// Do not hand-edit safeguard-manifest.json — regenerate it.
+
+"use strict";
+
+const manifest = require("./safeguard-manifest.json");
+
+/** The generated manifest. All values are design/EXPECTED facts. */
+const safeguardManifest = manifest;
+
+/** Look up a protected action's expected/design facts by SG-ACT id or slug. */
+function getSafeguardAction(idOrSlug) {
+  return manifest.actions.find(function (a) {
+    return a.id === idOrSlug || a.slug === idOrSlug;
+  });
+}
+
+module.exports = {
+  safeguardManifest: safeguardManifest,
+  getSafeguardAction: getSafeguardAction,
+  SAFEGUARD_MANIFEST_SCHEMA_VERSION: manifest.schema_version,
+  SAFEGUARD_MANIFEST_VERSION: manifest.manifest_version,
+  default: safeguardManifest,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@atlasent/safeguard-manifest",
+  "version": "1.0.0",
+  "description": "Versioned, deterministic projection of the authoritative AtlaSent safeguard package into the design/EXPECTED facts (owner, authority, expected evidence sources, expected gates) for the console SafeguardMap. Carries no runtime observed state. Zero-build, zero-dependency. Regenerate via scripts/generate-safeguard-manifest.py; do not hand-edit.",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./safeguard-manifest.json": "./safeguard-manifest.json",
+    "./schema": "./safeguard-manifest.schema.json"
+  },
+  "scripts": {
+    "generate": "python3 ../../scripts/generate-safeguard-manifest.py",
+    "check": "python3 ../../scripts/generate-safeguard-manifest.py --check"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "safeguard-manifest.json",
+    "safeguard-manifest.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "license": "MIT"
+}

package/safeguard-manifest.json

@@ -0,0 +1,527 @@
+{
+  "actions": [
+    {
+      "act_id": "ACT-0001",
+      "approver_role": "approver",
+      "business_action": "Production deployment",
+      "canon_id": "CANON-000001",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "change_review.approved",
+          "safeguard": "Review",
+          "source": "GitHub",
+          "tools": [
+            "github"
+          ]
+        },
+        {
+          "capability_id": "change_request.approved",
+          "tools": [
+            "jira",
+            "servicenow"
+          ]
+        },
+        {
+          "capability_id": "state.snapshot_captured",
+          "safeguard": "Artifact identity",
+          "source": "build or registry",
+          "tools": [
+            "github-actions",
+            "terraform"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_human_approval",
+          "satisfied_by": [
+            {
+              "capability_id": "change_review.approved",
+              "via_tools": [
+                "github"
+              ]
+            },
+            {
+              "capability_id": "change_request.approved",
+              "via_tools": [
+                "jira",
+                "servicenow"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_state_snapshot",
+          "satisfied_by": [
+            {
+              "capability_id": "state.snapshot_captured",
+              "via_tools": [
+                "github-actions",
+                "terraform"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-001",
+      "owner_display_name": "Release Owner",
+      "owner_maps_to_org_role": "admin",
+      "owner_role": "release_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "high",
+      "slug": "production.deploy"
+    },
+    {
+      "act_id": "ACT-0036",
+      "approver_role": "approver",
+      "business_action": "Infrastructure change",
+      "canon_id": "CANON-000033",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "change_request.approved",
+          "tools": [
+            "jira",
+            "servicenow"
+          ]
+        },
+        {
+          "capability_id": "change_review.approved",
+          "tools": [
+            "github"
+          ]
+        },
+        {
+          "capability_id": "state.snapshot_captured",
+          "tools": [
+            "github-actions",
+            "terraform"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_human_approval",
+          "satisfied_by": [
+            {
+              "capability_id": "change_request.approved",
+              "via_tools": [
+                "jira",
+                "servicenow"
+              ]
+            },
+            {
+              "capability_id": "change_review.approved",
+              "via_tools": [
+                "github"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_state_snapshot",
+          "satisfied_by": [
+            {
+              "capability_id": "state.snapshot_captured",
+              "via_tools": [
+                "github-actions",
+                "terraform"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-002",
+      "owner_display_name": "Infrastructure Owner",
+      "owner_maps_to_org_role": "admin",
+      "owner_role": "infra_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "high",
+      "slug": "infrastructure.change"
+    },
+    {
+      "act_id": "ACT-0035",
+      "approver_role": "approver",
+      "business_action": "Database migration",
+      "canon_id": "CANON-000032",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "change_review.approved",
+          "tools": [
+            "github"
+          ]
+        },
+        {
+          "capability_id": "change_request.approved",
+          "tools": [
+            "jira",
+            "servicenow"
+          ]
+        },
+        {
+          "capability_id": "state.snapshot_captured",
+          "tools": [
+            "github-actions",
+            "terraform"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_human_approval",
+          "satisfied_by": [
+            {
+              "capability_id": "change_review.approved",
+              "via_tools": [
+                "github"
+              ]
+            },
+            {
+              "capability_id": "change_request.approved",
+              "via_tools": [
+                "jira",
+                "servicenow"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_state_snapshot",
+          "satisfied_by": [
+            {
+              "capability_id": "state.snapshot_captured",
+              "via_tools": [
+                "github-actions",
+                "terraform"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-003",
+      "owner_display_name": "Database Owner",
+      "owner_maps_to_org_role": "admin",
+      "owner_role": "dba_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "high",
+      "slug": "database.migrate"
+    },
+    {
+      "act_id": "ACT-0032",
+      "approver_role": "approver",
+      "business_action": "Security-control exception",
+      "canon_id": "CANON-000029",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "change_request.approved",
+          "tools": [
+            "jira",
+            "servicenow"
+          ]
+        },
+        {
+          "capability_id": "caller.mfa_satisfied",
+          "tools": [
+            "entra-id",
+            "okta"
+          ]
+        },
+        {
+          "capability_id": "caller.identity_verified",
+          "tools": [
+            "entra-id",
+            "okta"
+          ]
+        },
+        {
+          "capability_id": "state.snapshot_captured",
+          "tools": [
+            "generic-webhook",
+            "terraform"
+          ]
+        },
+        {
+          "capability_id": "caller.role_membership_asserted",
+          "tools": [
+            "entra-id",
+            "okta"
+          ]
+        },
+        {
+          "capability_id": "risk.assessment_recorded",
+          "tools": [
+            "generic-webhook",
+            "servicenow"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_human_approval",
+          "satisfied_by": [
+            {
+              "capability_id": "change_request.approved",
+              "via_tools": [
+                "jira",
+                "servicenow"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_mfa",
+          "satisfied_by": [
+            {
+              "capability_id": "caller.mfa_satisfied",
+              "via_tools": [
+                "entra-id",
+                "okta"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_verified_actor",
+          "satisfied_by": [
+            {
+              "capability_id": "caller.identity_verified",
+              "via_tools": [
+                "entra-id",
+                "okta"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "requires_state_snapshot",
+          "satisfied_by": [
+            {
+              "capability_id": "state.snapshot_captured",
+              "via_tools": [
+                "generic-webhook",
+                "terraform"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "identity",
+          "satisfied_by": [
+            {
+              "capability_id": "caller.identity_verified",
+              "via_tools": [
+                "entra-id",
+                "okta"
+              ]
+            },
+            {
+              "capability_id": "caller.role_membership_asserted",
+              "via_tools": [
+                "entra-id",
+                "okta"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "risk",
+          "satisfied_by": [
+            {
+              "capability_id": "risk.assessment_recorded",
+              "via_tools": [
+                "generic-webhook",
+                "servicenow"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-004",
+      "owner_display_name": "Security Owner",
+      "owner_maps_to_org_role": "owner",
+      "owner_role": "security_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "critical",
+      "slug": "security.breakglass"
+    },
+    {
+      "act_id": "ACT-0031",
+      "approver_role": "approver",
+      "business_action": "Customer-production-data access",
+      "canon_id": "CANON-000028",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "change_request.approved",
+          "tools": [
+            "jira",
+            "servicenow"
+          ]
+        },
+        {
+          "capability_id": "change_review.approved",
+          "tools": [
+            "github"
+          ]
+        },
+        {
+          "capability_id": "consent.obtained",
+          "tools": [
+            "generic-webhook"
+          ]
+        },
+        {
+          "capability_id": "data.residency_asserted",
+          "tools": [
+            "aws",
+            "generic-webhook"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_human_approval",
+          "satisfied_by": [
+            {
+              "capability_id": "change_request.approved",
+              "via_tools": [
+                "jira",
+                "servicenow"
+              ]
+            },
+            {
+              "capability_id": "change_review.approved",
+              "via_tools": [
+                "github"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "consent",
+          "satisfied_by": [
+            {
+              "capability_id": "consent.obtained",
+              "via_tools": [
+                "generic-webhook"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "residency",
+          "satisfied_by": [
+            {
+              "capability_id": "data.residency_asserted",
+              "via_tools": [
+                "aws",
+                "generic-webhook"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-005",
+      "owner_display_name": "Data Owner",
+      "owner_maps_to_org_role": "admin",
+      "owner_role": "data_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "high",
+      "slug": "data.export"
+    },
+    {
+      "act_id": "ACT-0029",
+      "approver_role": "approver",
+      "business_action": "AI-agent production action",
+      "canon_id": "CANON-000026",
+      "expected_evidence_sources": [
+        {
+          "capability_id": "caller.identity_verified",
+          "tools": [
+            "generic-webhook",
+            "github-actions",
+            "okta"
+          ]
+        },
+        {
+          "capability_id": "risk.assessment_recorded",
+          "tools": [
+            "generic-webhook"
+          ]
+        }
+      ],
+      "expected_gates": [
+        {
+          "gate": "requires_verified_actor",
+          "satisfied_by": [
+            {
+              "capability_id": "caller.identity_verified",
+              "via_tools": [
+                "generic-webhook",
+                "github-actions",
+                "okta"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "identity",
+          "satisfied_by": [
+            {
+              "capability_id": "caller.identity_verified",
+              "via_tools": [
+                "generic-webhook",
+                "github-actions",
+                "okta"
+              ]
+            }
+          ]
+        },
+        {
+          "gate": "required_assertion_classes",
+          "required_assertion_class": "risk",
+          "satisfied_by": [
+            {
+              "capability_id": "risk.assessment_recorded",
+              "via_tools": [
+                "generic-webhook"
+              ]
+            }
+          ]
+        }
+      ],
+      "id": "SG-ACT-006",
+      "owner_display_name": "Agent Owner",
+      "owner_maps_to_org_role": "admin",
+      "owner_role": "agent_owner",
+      "recommended_lifecycle": "shadow",
+      "risk_posture": "high",
+      "slug": "agent.tool.invoke"
+    }
+  ],
+  "generated_by": "scripts/generate-safeguard-manifest.py",
+  "kind": "safeguard-manifest",
+  "manifest_version": "1.0.0",
+  "notice": "DESIGN/EXPECTED facts only \u2014 no runtime observed state. Deterministic; do not hand-edit.",
+  "provenance": {
+    "source_files": [
+      {
+        "path": "contract/safeguard-pack/authority/authority-model.yaml",
+        "sha256": "6a303d2ce35ddd4ff7c2539b8ab2ee69411af2d65ab52ebcf0e5f12020fe9c47"
+      },
+      {
+        "path": "contract/safeguard-pack/products/saas-production-safeguard/safeguard-map.yaml",
+        "sha256": "e14a8ee6ce3b6a7a2171c0ac3de70a2f713d46f1c808131b5aee9ee241fb68b4"
+      },
+      {
+        "path": "contract/safeguard-pack/protected-actions/safeguard-actions.yaml",
+        "sha256": "6932a4c9c7aac3e9e7a17480ca9921ecf1f1942115778963f82488bb2738de68"
+      }
+    ],
+    "source_repo": "AtlaSent-Systems-Inc/atlasent"
+  },
+  "schema_version": "1.0"
+}

package/safeguard-manifest.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://atlasent.io/schemas/safeguard-manifest.schema.json",
+  "title": "Safeguard Manifest",
+  "description": "Versioned, deterministic projection of the authoritative safeguard package (safeguard-actions + authority-model + safeguard-map) into the design/EXPECTED facts a consumer needs: per protected action, its owner, authority, expected evidence sources, and expected gates. Carries NO runtime observed state (enforcement mode in effect, verification status, coverage, gaps) — those stay live in the runtime. Consumers pin an explicit manifest_version and must validate provenance.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "manifest_version", "kind", "provenance", "actions"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0" },
+    "manifest_version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "kind": { "type": "string", "const": "safeguard-manifest" },
+    "generated_by": { "type": "string" },
+    "notice": { "type": "string" },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_repo", "source_files"],
+      "description": "Deterministic input provenance. Release/commit provenance is bound at publish time (npm --provenance / Sigstore), not baked here.",
+      "properties": {
+        "source_repo": { "type": "string" },
+        "source_files": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "sha256"],
+            "properties": {
+              "path": { "type": "string" },
+              "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+            }
+          }
+        }
+      }
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "slug", "owner_role", "expected_gates", "expected_evidence_sources"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^SG-ACT-[0-9]{3}$" },
+          "business_action": { "type": ["string", "null"] },
+          "slug": { "type": "string" },
+          "canon_id": { "type": ["string", "null"] },
+          "act_id": { "type": ["string", "null"] },
+          "risk_posture": { "type": ["string", "null"] },
+          "owner_role": { "type": ["string", "null"] },
+          "owner_display_name": { "type": ["string", "null"] },
+          "owner_maps_to_org_role": { "type": ["string", "null"] },
+          "approver_role": { "type": ["string", "null"] },
+          "recommended_lifecycle": { "type": ["string", "null"] },
+          "expected_gates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["gate", "satisfied_by"],
+              "properties": {
+                "gate": { "type": "string" },
+                "required_assertion_class": { "type": "string" },
+                "satisfied_by": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["capability_id", "via_tools"],
+                    "properties": {
+                      "capability_id": { "type": "string" },
+                      "via_tools": { "type": "array", "items": { "type": "string" } }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "expected_evidence_sources": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["capability_id", "tools"],
+              "properties": {
+                "capability_id": { "type": "string" },
+                "tools": { "type": "array", "items": { "type": "string" } },
+                "safeguard": { "type": "string" },
+                "source": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}