@agent-ix/spec-objects-security 0.5.0 → 0.8.0

package/README.md

@@ -1,5 +1,7 @@
 # spec-objects-security
 
+[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/6qsdhSPE)
+
 > Filament Module: tier-2 security and identity ObjectTypes (threats, controls, auth flows, secrets, policies)
 
 `spec-objects-security` is an **Agent-IX Filament module**: a `manifest.yaml` plus per-kind authoring **skeletons** (and frontmatter schemas) that teach the spec tooling a vocabulary of object kinds. It is not a standalone app — it is loaded by [`quire-cli`](https://github.com/agent-ix/quire-cli) and [`quoin`](https://github.com/agent-ix/quoin) to author and validate Markdown spec artifacts.

package/manifest.yaml

@@ -1,7 +1,40 @@
 manifest_version: 1.0.0
 name: spec-objects-security
-version: 0.1.0
+version: 0.2.0
 description: 'Filament Module: tier-2 security and identity ObjectTypes (threats, controls, auth flows, secrets, policies)'
+semantic:
+  contract_version: 1.0.0
+  semantic_core: 0.3.0
+  package: agent-ix/spec-objects-security
+  exports:
+  - auth_flow
+  - permission
+  - scope
+  - role
+  - secret
+  - encryption_key
+  - session_config
+  - data_classification
+  - trust_boundary
+  - audit_event
+  - csrf_token
+  - cors_policy
+  - password_policy
+  - mfa_method
+  - jwt_claim
+  - threat
+  - control
+  - risk
+  - vulnerability
+  - asset
+  - attack_surface
+  - policy
+  - audit_finding
+  imports: {}
+  targets: [json-schema, markdown]
+  mappings: [typed-table, sysml-fence, ocl-clause]
+  compatibility_posture: additive
+  legacy_forms: warning
 nav:
   category:
     slug: security
@@ -21,7 +54,8 @@ object_types:
     protects: [externally-exposed]
     references: [auth_flow]
   data_schema:
-    type: object
+    schema: schemas/AuthFlow.json
+    digest: sha256:3e0bf1f277ead76fe354693c49563ffd73c990086822ac8b8ad91225589d9e49
   body_extraction:
     yield_pattern:
       match:
@@ -45,13 +79,19 @@ object_types:
           after_heading: Flow
           required: true
           language: mermaid
+        # Added at 0.2.0 (FR-005): the `## Operations` subsections.
+        operations:
+          from: section_body
+          after_heading: Operations
+          required: false
 - name: permission
   allowed_links:
     grants: [scope]
     guards: [externally-exposed]
     references: [role]
   data_schema:
-    type: object
+    schema: schemas/Permission.json
+    digest: sha256:fbe12967f34580936a83f496ca51f7f879c01affaa39c66988d724de169e1220
   body_extraction:
     yield_pattern:
       match:
@@ -68,11 +108,18 @@ object_types:
           path:
           - verb
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: scope
   allowed_links:
     references: [permission]
   data_schema:
-    type: object
+    schema: schemas/Scope.json
+    digest: sha256:8d68d19fc7950d9a17b3d0e757e276689a002d15316133e9d774f220c0af52d2
   body_extraction:
     yield_pattern:
       match:
@@ -83,12 +130,19 @@ object_types:
           from: section_body
           after_heading: Grants
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: role
   allowed_links:
     grants: [permission]
     references: [role]
   data_schema:
-    type: object
+    schema: schemas/Role.json
+    digest: sha256:407a81699de5fea5f1a7868b456216afa99201f82bbe11f1c6203784c1ee7e33
   body_extraction:
     yield_pattern:
       match:
@@ -99,12 +153,19 @@ object_types:
           from: section_body
           after_heading: Permissions
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: secret
   roles: [sensitive]
   allowed_links:
     references: [secret]
   data_schema:
-    type: object
+    schema: schemas/Secret.json
+    digest: sha256:2d06ce2ad6ea0a23014a301529a4caa1691a3757ed9f4b4b5dc3f9b559fd1586
   body_extraction:
     yield_pattern:
       match:
@@ -115,12 +176,19 @@ object_types:
           from: section_body
           after_heading: Rotation
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: encryption_key
   roles: [sensitive]
   allowed_links:
     encrypts: [sensitive, data_classification]
   data_schema:
-    type: object
+    schema: schemas/EncryptionKey.json
+    digest: sha256:171b8ffdececb9061db539f4a4bbc410df6f76494bb53819728cc610f41eb54c
   body_extraction:
     yield_pattern:
       match:
@@ -137,11 +205,18 @@ object_types:
           path:
           - rotation
           required: false
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: session_config
   allowed_links:
     references: [auth_flow, jwt_claim]
   data_schema:
-    type: object
+    schema: schemas/SessionConfig.json
+    digest: sha256:125c2d9668ecc9cc031950916069754a33a315b33c6c9069151da8c651def4fd
   body_extraction:
     yield_pattern:
       match:
@@ -152,12 +227,18 @@ object_types:
           from: section_body
           after_heading: Settings
           required: true
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: data_classification
   allowed_links:
     classifies: [persistable, externally-exposed, sensitive]
     references: [data_classification]
   data_schema:
-    type: object
+    schema: schemas/DataClassification.json
+    digest: sha256:32e1217369954ee17b09fa4aba8b02a062fa2a432f124dd99f87db468f87b9ec
   body_extraction:
     yield_pattern:
       match:
@@ -168,12 +249,19 @@ object_types:
           from: section_body
           after_heading: Handling
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: trust_boundary
   allowed_links:
     contains: [asset, api_endpoint]
     references: [trust_boundary]
   data_schema:
-    type: object
+    schema: schemas/TrustBoundary.json
+    digest: sha256:0069a8d8e1dae0353bbb5446983138a6ac6be2aba5cb0bc93e195d284372ef84
   body_extraction:
     yield_pattern:
       match:
@@ -185,12 +273,24 @@ object_types:
           after_heading: Boundary
           required: true
           language: mermaid
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: audit_event
   roles: [event-like]
   allowed_links:
     references: [audit_event]
   data_schema:
-    type: object
+    schema: schemas/AuditEvent.json
+    digest: sha256:bd4fed5dc4d80f9041b368d151789d9b2c2a39b4c72f1c1c71a30820b70f52ec
   body_extraction:
     yield_pattern:
       match:
@@ -202,12 +302,19 @@ object_types:
           after_heading: Event Schema
           required: true
           language: json
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: csrf_token
   roles: [sensitive]
   allowed_links:
     references: [csrf_token]
   data_schema:
-    type: object
+    schema: schemas/CsrfToken.json
+    digest: sha256:7abfff62af262c21376408e97faa1fc1546df2a9954c59aae5af25ee9469c254
   body_extraction:
     yield_pattern:
       match:
@@ -219,11 +326,18 @@ object_types:
           path:
           - rotation_window
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: cors_policy
   allowed_links:
     references: [cors_policy]
   data_schema:
-    type: object
+    schema: schemas/CorsPolicy.json
+    digest: sha256:55b8cb1c09cc43d8daa6aa7c461d3ede2f8c600d51f5c74cff0facfed0fe1af3
   body_extraction:
     yield_pattern:
       match:
@@ -234,11 +348,17 @@ object_types:
           from: section_body
           after_heading: Origins
           required: true
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: password_policy
   allowed_links:
     references: [password_policy]
   data_schema:
-    type: object
+    schema: schemas/PasswordPolicy.json
+    digest: sha256:3deb79e250c2ee75b380a5c50c0f2942b9fa4d7207c8b2b5b2bce1bd8aad408f
   body_extraction:
     yield_pattern:
       match:
@@ -249,11 +369,17 @@ object_types:
           from: section_body
           after_heading: Rules
           required: true
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: mfa_method
   allowed_links:
     references: [mfa_method]
   data_schema:
-    type: object
+    schema: schemas/MfaMethod.json
+    digest: sha256:89797c934801cba2523b6d79c2ec746cdb79d18b3e071a3693e37fb0fea04064
   body_extraction:
     yield_pattern:
       match:
@@ -270,12 +396,19 @@ object_types:
           path:
           - factor
           required: false
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: jwt_claim
   roles: [sensitive]
   allowed_links:
     references: [jwt_claim]
   data_schema:
-    type: object
+    schema: schemas/JwtClaim.json
+    digest: sha256:7c38c084af9264b74dfa135e11825a0f09211664b325093e632521155c006321
   body_extraction:
     yield_pattern:
       match:
@@ -287,12 +420,19 @@ object_types:
           after_heading: Schema
           required: true
           language: json
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: threat
   allowed_links:
     threatens: [asset, attack_surface]
     exploits: [vulnerability]
   data_schema:
-    type: object
+    schema: schemas/Threat.json
+    digest: sha256:7103325eae471a7d8f8cf345b91297e89a169eaf9ee6f69b9925badc07b74046
   body_extraction:
     yield_pattern:
       match:
@@ -321,13 +461,20 @@ object_types:
           path:
           - vector
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: control
   allowed_links:
     mitigates: [threat, risk, vulnerability]
     implements: [policy]
     protects: [externally-exposed, asset]
   data_schema:
-    type: object
+    schema: schemas/Control.json
+    digest: sha256:1ae3e01ec7d15725eb6bc179d75b583ebe5794a8724c08811cfaa8b0a013eacd
   body_extraction:
     yield_pattern:
       match:
@@ -338,12 +485,24 @@ object_types:
           from: section_body
           after_heading: Mappings
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: risk
   allowed_links:
     arises_from: [threat, vulnerability]
     references: [asset]
   data_schema:
-    type: object
+    schema: schemas/Risk.json
+    digest: sha256:08424445bfb977cd7f407dc2221b3728eb69d90e7ff94398781dc1105d4e6597
   body_extraction:
     yield_pattern:
       match:
@@ -360,12 +519,19 @@ object_types:
           path:
           - impact
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: vulnerability
   allowed_links:
     affects: [asset, attack_surface]
     references: [vulnerability]
   data_schema:
-    type: object
+    schema: schemas/Vulnerability.json
+    digest: sha256:9c1f1e726faf41be9d6547bb2c84588c6339d0eb468d22e79b8a631ef11266b3
   body_extraction:
     yield_pattern:
       match:
@@ -382,11 +548,18 @@ object_types:
           path:
           - severity
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: asset
   allowed_links:
     references: [data_classification, trust_boundary]
   data_schema:
-    type: object
+    schema: schemas/Asset.json
+    digest: sha256:d41e5f5acc58187e9237ee8ee0e3d173c403e24a557d053c1fbed8c9eebf7a37
   body_extraction:
     yield_pattern:
       match:
@@ -397,12 +570,19 @@ object_types:
           from: section_body
           after_heading: Description
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: attack_surface
   roles: [externally-exposed]
   allowed_links:
     exposes: [asset, api_endpoint]
   data_schema:
-    type: object
+    schema: schemas/AttackSurface.json
+    digest: sha256:fd36db8ffc5df3b4dda5175b1bb14f1cf67b9e0c76a3a3fdf626bcea9961ccf3
   body_extraction:
     yield_pattern:
       match:
@@ -413,11 +593,18 @@ object_types:
           from: section_body
           after_heading: Entry Points
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 - name: policy
   allowed_links:
     governs: [control, role, permission, data_classification]
   data_schema:
-    type: object
+    schema: schemas/Policy.json
+    digest: sha256:824bb21f2689ed75c5cd33e361b56baa5a28555bbd3fe387510195982ef0c299
   body_extraction:
     yield_pattern:
       match:
@@ -428,12 +615,18 @@ object_types:
           from: section_body
           after_heading: Policy
           required: true
+        # Added at 0.2.0 (FR-005): the `## Invariants` OCL clauses.
+        invariants:
+          from: section_body
+          after_heading: Invariants
+          required: false
 - name: audit_finding
   allowed_links:
     traces_to: [risk]
     references: [control, vulnerability, asset]
   data_schema:
-    type: object
+    schema: schemas/AuditFinding.json
+    digest: sha256:e5c166f8dea995a7babd81f9f2d93ea14570965a7fe0dc3042135ab0924688a7
   body_extraction:
     yield_pattern:
       match:
@@ -444,11 +637,62 @@ object_types:
           from: section_body
           after_heading: Recommendation
           required: true
+        # Added at 0.2.0 (FR-005): the typed `## Properties` table the
+        # semantic layer reads. Optional, so every 0.1.0 artifact stays valid.
+        properties:
+          from: section_body
+          after_heading: Properties
+          required: false
 
 # FR-043: concrete-term lexicon — security / identity / auth objects.
+# FR-058 (quire-rs v0.31.0): upward-trace completeness — the second half of
+# agent-ix/spec-objects-security#5. Declaration, not code: the engine holds no
+# archetype name, no verb and no direction.
+#
+# A threat nobody controls and a risk nobody treats are both perfectly
+# well-formed documents that pass every schema and grammar check, and both are
+# evidence of an unaddressed exposure. Nothing that reads a document on its own
+# can see it; only reading the edge set upward can.
+traceability:
+  required_relations:
+  # STRIDE without coverage is a list. A threat with no inbound `mitigates` is
+  # one somebody enumerated and then left.
+  - name: threat-has-control
+    from: threat
+    edges: [mitigates]
+    to: []
+    direction: incoming
+    check: uncontrolled-threat
+  # The same statement about the scored artefact rather than the mechanism: a
+  # risk with no treatment was assessed and then dropped.
+  - name: risk-has-treatment
+    from: risk
+    edges: [mitigates]
+    to: []
+    direction: incoming
+    check: untreated-risk
+  # `direction: incoming` throughout, because the mitigation is authored from
+  # the control's or requirement's end — a control says what it mitigates. A
+  # threat listing its own controls would duplicate the fact and let the two
+  # drift.
+  #
+  # DELIBERATELY NOT DECLARED: `vulnerability`. #5 names "threat/hazard/risk"
+  # and a vulnerability is a property of an implementation rather than a thing
+  # the specification owes a response to. Adding it would widen the ticket.
+  #
+  # ALSO NOT DECLARED: the reverse direction, "every security-classified
+  # requirement traces to an upstream threat". It needs a way to say a
+  # requirement is security-classified, and no such axis exists — neither this
+  # module nor iso declares one. Filed rather than invented.
+  #
+  # A risk that transitively arises from itself states nothing, and no
+  # per-document check can see it: the defect is a property of the graph.
+  acyclic_edges:
+  - arises_from
+
 lexicon:
   token: {definition: a bearer credential representing identity or grant}
-  secret: {definition: a confidential value (key, password) kept out of code}
+  secret: {definition: "a confidential value (key, password) kept out of code"}
   scope: {definition: a named permission boundary on a grant}
   claim: {definition: an assertion carried in a token}
   permission: {definition: an allowed action on a resource}
@@ -460,5 +704,5 @@ lexicon:
   nonce: {definition: a single-use value preventing replay}
   hash: {definition: a fixed-size digest of input}
   cipher: {definition: an encryption/decryption algorithm}
-  audit: {definition: a recorded, tamper-evident event trail}
+  audit: {definition: "a recorded, tamper-evident event trail"}
   policy: {definition: a declarative rule governing access or behavior}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-ix/spec-objects-security",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Filament Module: tier-2 security and identity ObjectTypes (threat, control, risk, asset, policy, auth_flow, role, scope, jwt_claim, secret)",
   "license": "AGPL-3.0-or-later",
   "author": "Agent IX <agents@agent-ix.dev>",
@@ -20,7 +20,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "prepack": "node scripts/stage-npm.mjs"
+    "prepack": "node scripts/stage-npm.mjs",
+    "postpack": "node scripts/stage-npm.mjs --clean"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -29,5 +30,10 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agent-ix/spec-objects-security.git"
+  },
+  "devDependencies": {
+    "@agent-ix/semantic-core": "0.3.0",
+    "@typespec/compiler": "1.15.0",
+    "@typespec/json-schema": "1.15.0"
   }
 }

package/schemas/Asset.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/0.2.0/Asset.json",
+  "type": "object",
+  "properties": {
+    "fields": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.0/FieldDecl.json"
+      },
+      "minItems": 1,
+      "contains": {
+        "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/0.2.0/IdentityField.json"
+      }
+    },
+    "relations": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.0/RelationDecl.json"
+      }
+    },
+    "clauses": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.0/ClauseRef.json"
+      }
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.0/OperationDecl.json"
+      }
+    },
+    "classification": {
+      "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/0.2.0/ConfidentialityLevel.json"
+    },
+    "owner": {
+      "$ref": "https://schemas.agent-ix.org/semantic-core/0.3.0/SemanticId.json"
+    }
+  },
+  "required": [
+    "fields"
+  ],
+  "unevaluatedProperties": {
+    "not": {}
+  },
+  "description": "A thing worth protecting.",
+  "allOf": [
+    {
+      "properties": {
+        "fields": {
+          "items": {
+            "not": {
+              "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/0.2.0/DefaultedField.json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "properties": {
+        "operations": {
+          "items": {
+            "properties": {
+              "params": {
+                "items": {
+                  "not": {
+                    "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/0.2.0/DefaultedField.json"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}