@agent-ix/spec-objects-security 0.5.0 → 0.9.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,7 @@ object_types:
     protects: [externally-exposed]
     references: [auth_flow]
   data_schema:
-    type: object
+    schema: schemas/AuthFlow.json
   body_extraction:
     yield_pattern:
       match:
@@ -45,13 +78,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -68,11 +106,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -83,12 +127,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -99,12 +149,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -115,12 +171,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -137,11 +199,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -152,12 +220,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -168,12 +241,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -185,12 +264,23 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -202,12 +292,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -219,11 +315,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -234,11 +336,16 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -249,11 +356,16 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -270,12 +382,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -287,12 +405,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -321,13 +445,19 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -338,12 +468,23 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -360,12 +501,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -382,11 +529,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -397,12 +550,18 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -413,11 +572,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -428,12 +593,17 @@ 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
   body_extraction:
     yield_pattern:
       match:
@@ -444,11 +614,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 +681,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.9.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/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/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/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/DefaultedField.json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "properties": {
+        "operations": {
+          "items": {
+            "properties": {
+              "params": {
+                "items": {
+                  "not": {
+                    "$ref": "https://schemas.agent-ix.org/agent-ix/spec-objects-security/DefaultedField.json"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}