@agent-ix/spec-objects-security 0.4.0

package/README.md

@@ -0,0 +1,109 @@
+# spec-objects-security
+
+> 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.
+
+## Installing quire-cli
+
+`@agent-ix` packages are published to public npm. Install the CLI globally:
+
+```bash
+npm install -g @agent-ix/quire-cli
+```
+
+See https://github.com/agent-ix/quire-cli#install for details.
+
+## Install this module via npm
+
+This module is also published as a config-only npm package: `@agent-ix/spec-objects-security`.
+The package root **is** the Filament module (`manifest.yaml` + schemas/skeletons),
+so it works directly as a `--module` target or via quoin's `package:` source.
+
+```bash
+npm install @agent-ix/spec-objects-security
+```
+
+```bash
+# quoin — resolve the module from npm by name
+quoin plugin install package:@agent-ix/spec-objects-security
+
+# or point any tool at the installed package root
+quire validate spec/**/*.md --module node_modules/@agent-ix/spec-objects-security
+```
+
+## Object types provided
+
+This module adds the following object kinds (frontmatter `type:` value in parentheses). All kinds are tier-2 embedded ObjectTypes — they require `id`, `title` and `type` in frontmatter plus the kind-specific contract below.
+
+| Object | `type:` | Description |
+|--------|---------|-------------|
+| Auth flow | `auth_flow` | An authentication/login flow, with a `Flow` section carrying a mermaid diagram of the sequence (e.g. OIDC authorization code flow). |
+| Permission | `permission` | A single grantable permission, naming the protected `resource` kind and the `verb` (action) it grants on it. |
+| Scope | `scope` | An OAuth/authorization scope, with a `Grants` section listing the permissions the scope confers. |
+| Role | `role` | A named role, with a `Permissions` section listing the permissions bound to it. |
+| Secret | `secret` | A managed secret (e.g. client secret), with a `Rotation` section describing how and how often it rotates. |
+| Encryption key | `encryption_key` | An encryption key, with frontmatter `algorithm` (cipher) and optional `rotation` cadence. |
+| Session config | `session_config` | A session configuration, with a `Settings` section enumerating the effective session parameters (cookies, timeouts, limits). |
+| Data classification | `data_classification` | A data sensitivity class, with a `Handling` section stating the handling requirements for that class. |
+| Trust boundary | `trust_boundary` | A trust boundary between security zones, with a `Boundary` section carrying a mermaid diagram of the zones. |
+| Audit event | `audit_event` | An emitted audit/log event, with an `Event Schema` section carrying a JSON code block of its payload schema. |
+| CSRF token | `csrf_token` | A CSRF-protection token, with frontmatter `rotation_window` (how often a fresh token is issued). |
+| CORS policy | `cors_policy` | A browser cross-origin policy, with an `Origins` section enumerating the allowed origins and their rules. |
+| Password policy | `password_policy` | A password policy, with a `Rules` section enumerating the enforced password rules. |
+| MFA method | `mfa_method` | A multi-factor authentication method, with frontmatter `kind` (method kind) and optional `factor` (auth factor class). |
+| JWT claim | `jwt_claim` | A JWT/token claim, with a `Schema` section carrying a JSON code block of the claim's JSON Schema. |
+| Threat | `threat` | A threat, with frontmatter `stride_category` (STRIDE class) and `vector` (the attack vector). |
+| Control | `control` | A security control, with a `Mappings` section mapping it to the threats, risks and standards it addresses. |
+| Risk | `risk` | A risk-register entry, with frontmatter `likelihood` and `impact` qualitative ratings driving its score. |
+| Vulnerability | `vulnerability` | A vulnerability, with frontmatter `severity` and optional `cve_id` linking the public advisory. |
+| Asset | `asset` | A protected asset, with a `Description` section describing the asset and why it matters. |
+| Attack surface | `attack_surface` | An attack surface, with an `Entry Points` section enumerating the externally reachable entry points. |
+| Policy | `policy` | A normative security policy, with a `Policy` section stating the policy text. |
+| Audit finding | `audit_finding` | A security-audit finding, with a `Recommendation` section stating the remediation recommendation. |
+
+## How this module is used
+
+### With quoin (recommended)
+
+[`quoin`](https://github.com/agent-ix/quoin) is the spec-domain authoring CLI. Install the module as a plugin, then author and validate:
+
+```bash
+quoin plugin install path:../spec-objects-security
+quoin catalog list                      # list the kinds this module adds
+quoin write . --types threat,control    # scaffold artifacts of these kinds
+quoin review                            # validate authored files
+```
+
+### With quire-cli directly
+
+Point `quire` at this module (the package directory holds `manifest.yaml` and `skeletons/`):
+
+```bash
+quire schema threat --module ./spec_objects_security                 # a kind's extraction contract
+quire validate spec/**/*.md --module ./spec_objects_security         # structural validation
+quire extract <DOC> --module ./spec_objects_security                 # extract structured data
+```
+
+See the [quire-cli usage docs](https://github.com/agent-ix/quire-cli#usage-instructions) for all commands.
+
+## Development
+
+This module is a flat-layout Python package (`spec_objects_security`, Python 3.13+) managed with [Poetry](https://python-poetry.org/) and built/published via GitHub Actions to Google Artifact Registry (PyPI-compatible).
+
+```bash
+make install          # install dependencies in the Poetry venv
+make test             # run pytest
+make lint             # ruff + black --check
+make format           # auto-format (ruff --fix + black)
+make build            # build wheel + sdist under dist/
+make local-publish    # publish to the local pypi.ix registry
+make update-lock      # update poetry.lock
+make use-local p=<name> / make use-upstream p=<name>   # swap a dep source
+```
+
+**CI:** GitHub Actions runs on `push`, `pull_request`, and `v*.*.*` tags — it tests, lints, builds with `poetry build`, and on tags publishes via `twine upload -r internal-pypi`. Versioning is dynamic from the Git tag. Required CI config: `GCP_SERVICE_ACCOUNT_KEY` (secret) plus `GCP_REGION`, `GCP_PROJECT_NAME`, `GCP_PYPI` (variables).
+
+## License
+
+AGPL-3.0-or-later — see [LICENSE](./LICENSE).

package/manifest.yaml

@@ -0,0 +1,464 @@
+manifest_version: 1.0.0
+name: spec-objects-security
+version: 0.1.0
+description: 'Filament Module: tier-2 security and identity ObjectTypes (threats, controls, auth flows, secrets, policies)'
+nav:
+  category:
+    slug: security
+    label: Security
+    icon: ShieldCheck
+    order: 54
+archetypes: []
+grammars: []
+artifact_types: []
+lint_rules: []
+object_types:
+- name: auth_flow
+  roles: [externally-exposed]
+  allowed_links:
+    requires: [mfa_method]
+    grants: [role]
+    protects: [externally-exposed]
+    references: [auth_flow]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: &id001
+          from: frontmatter_field
+          path:
+          - id
+          required: true
+        title: &id002
+          from: frontmatter_field
+          path:
+          - title
+          required: true
+        type: &id003
+          from: frontmatter_field
+          path:
+          - type
+          required: true
+        flow:
+          from: code_block
+          after_heading: Flow
+          required: true
+          language: mermaid
+- name: permission
+  allowed_links:
+    grants: [scope]
+    guards: [externally-exposed]
+    references: [role]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        resource:
+          from: frontmatter_field
+          path:
+          - resource
+          required: true
+        verb:
+          from: frontmatter_field
+          path:
+          - verb
+          required: true
+- name: scope
+  allowed_links:
+    references: [permission]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        grants:
+          from: section_body
+          after_heading: Grants
+          required: true
+- name: role
+  allowed_links:
+    grants: [permission]
+    references: [role]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        permissions:
+          from: section_body
+          after_heading: Permissions
+          required: true
+- name: secret
+  roles: [sensitive]
+  allowed_links:
+    references: [secret]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        rotation:
+          from: section_body
+          after_heading: Rotation
+          required: true
+- name: encryption_key
+  roles: [sensitive]
+  allowed_links:
+    encrypts: [sensitive, data_classification]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        algorithm:
+          from: frontmatter_field
+          path:
+          - algorithm
+          required: true
+        rotation:
+          from: frontmatter_field
+          path:
+          - rotation
+          required: false
+- name: session_config
+  allowed_links:
+    references: [auth_flow, jwt_claim]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        settings:
+          from: section_body
+          after_heading: Settings
+          required: true
+- name: data_classification
+  allowed_links:
+    classifies: [persistable, externally-exposed, sensitive]
+    references: [data_classification]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        handling:
+          from: section_body
+          after_heading: Handling
+          required: true
+- name: trust_boundary
+  allowed_links:
+    contains: [asset, api_endpoint]
+    references: [trust_boundary]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        boundary:
+          from: code_block
+          after_heading: Boundary
+          required: true
+          language: mermaid
+- name: audit_event
+  roles: [event-like]
+  allowed_links:
+    references: [audit_event]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        event_schema:
+          from: code_block
+          after_heading: Event Schema
+          required: true
+          language: json
+- name: csrf_token
+  roles: [sensitive]
+  allowed_links:
+    references: [csrf_token]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        rotation_window:
+          from: frontmatter_field
+          path:
+          - rotation_window
+          required: true
+- name: cors_policy
+  allowed_links:
+    references: [cors_policy]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        origins:
+          from: section_body
+          after_heading: Origins
+          required: true
+- name: password_policy
+  allowed_links:
+    references: [password_policy]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        rules:
+          from: section_body
+          after_heading: Rules
+          required: true
+- name: mfa_method
+  allowed_links:
+    references: [mfa_method]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        kind:
+          from: frontmatter_field
+          path:
+          - kind
+          required: true
+        factor:
+          from: frontmatter_field
+          path:
+          - factor
+          required: false
+- name: jwt_claim
+  roles: [sensitive]
+  allowed_links:
+    references: [jwt_claim]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id001
+        title: *id002
+        type: *id003
+        schema_json:
+          from: code_block
+          after_heading: Schema
+          required: true
+          language: json
+- name: threat
+  allowed_links:
+    threatens: [asset, attack_surface]
+    exploits: [vulnerability]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: &id004
+          from: frontmatter_field
+          path:
+          - id
+          required: true
+        title: &id005
+          from: frontmatter_field
+          path:
+          - title
+          required: true
+        type: &id006
+          from: frontmatter_field
+          path:
+          - type
+          required: true
+        stride_category:
+          from: frontmatter_field
+          path:
+          - stride_category
+          required: true
+        vector:
+          from: frontmatter_field
+          path:
+          - vector
+          required: true
+- name: control
+  allowed_links:
+    mitigates: [threat, risk, vulnerability]
+    implements: [policy]
+    protects: [externally-exposed, asset]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        mappings:
+          from: section_body
+          after_heading: Mappings
+          required: true
+- name: risk
+  allowed_links:
+    arises_from: [threat, vulnerability]
+    references: [asset]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        likelihood:
+          from: frontmatter_field
+          path:
+          - likelihood
+          required: true
+        impact:
+          from: frontmatter_field
+          path:
+          - impact
+          required: true
+- name: vulnerability
+  allowed_links:
+    affects: [asset, attack_surface]
+    references: [vulnerability]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        cve_id:
+          from: frontmatter_field
+          path:
+          - cve_id
+          required: false
+        severity:
+          from: frontmatter_field
+          path:
+          - severity
+          required: true
+- name: asset
+  allowed_links:
+    references: [data_classification, trust_boundary]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        description_body:
+          from: section_body
+          after_heading: Description
+          required: true
+- name: attack_surface
+  roles: [externally-exposed]
+  allowed_links:
+    exposes: [asset, api_endpoint]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        entry_points:
+          from: section_body
+          after_heading: Entry Points
+          required: true
+- name: policy
+  allowed_links:
+    governs: [control, role, permission, data_classification]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        policy_body:
+          from: section_body
+          after_heading: Policy
+          required: true
+- name: audit_finding
+  allowed_links:
+    traces_to: [risk]
+    references: [control, vulnerability, asset]
+  data_schema:
+    type: object
+  body_extraction:
+    yield_pattern:
+      match:
+        id: *id004
+        title: *id005
+        type: *id006
+        recommendation:
+          from: section_body
+          after_heading: Recommendation
+          required: true
+
+# FR-043: concrete-term lexicon — security / identity / auth objects.
+lexicon:
+  token: {definition: a bearer credential representing identity or grant}
+  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}
+  credential: {definition: data proving an identity}
+  certificate: {definition: a signed binding of identity to a public key}
+  signature: {definition: a cryptographic proof of integrity/origin}
+  principal: {definition: an authenticated identity (user/service)}
+  keypair: {definition: a public/private cryptographic key pair}
+  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}
+  policy: {definition: a declarative rule governing access or behavior}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@agent-ix/spec-objects-security",
+  "version": "0.4.0",
+  "description": "Filament Module: tier-2 security and identity ObjectTypes (threat, control, risk, asset, policy, auth_flow, role, scope, jwt_claim, secret)",
+  "license": "MIT",
+  "author": "Agent IX <agents@agent-ix.dev>",
+  "keywords": [
+    "agent-ix",
+    "filament",
+    "filament-module",
+    "quoin",
+    "quire",
+    "spec"
+  ],
+  "files": [
+    "manifest.yaml",
+    "schemas/",
+    "skeletons/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "node scripts/stage-npm.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-ix/spec-objects-security.git"
+  }
+}

package/skeletons/asset.md

@@ -0,0 +1,22 @@
+---
+id: ASSET-001
+title: "Session store"
+type: asset
+---
+<!-- asset authoring skeleton (spec-objects-security). Fill every part with
+     substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type: asset).
+     - A "Description" section MUST describe the asset and why it matters. -->
+# [ASSET-001] Session store
+
+Redis cluster holding all active Atlas web sessions and CSRF token state.
+
+## Description
+
+The session store is the authority for who is currently authenticated:
+compromise yields the ability to mint or hijack any active session across all
+tenants, bypassing AUTHFLOW-001 entirely. It runs in the trusted private
+subnet behind BOUND-001, accepts only mTLS connections from the auth service,
+and persists nothing to disk (RDB/AOF disabled) so session identifiers never
+reach backup media. Data it holds is classified Confidential (CLASS-001
+handling applies to the embedded user identifiers).

package/skeletons/attack_surface.md

@@ -0,0 +1,25 @@
+---
+id: SURF-001
+title: "Atlas authentication attack surface"
+type: attack_surface
+---
+<!-- attack_surface authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       attack_surface).
+     - An "Entry Points" section MUST enumerate the externally reachable
+       entry points. -->
+# [SURF-001] Atlas authentication attack surface
+
+Internet-reachable surface of the Atlas authentication subsystem, reviewed
+whenever a new route crosses BOUND-001 outward.
+
+## Entry Points
+
+- `GET /login`, `GET /callback` — browser OIDC endpoints (AUTHFLOW-001)
+- `POST /api/token` — public API token exchange for integrations (SCOPE-001)
+- `POST /auth/local` — break-glass local login, gated by PASSPOL-001 and
+  MFA-001
+- `POST /webhooks/idp` — IdP back-channel logout receiver, HMAC-verified
+- Session cookie and `X-Atlas-CSRF` header parsing in the gateway middleware
+  (CSRF-001), reachable from any authenticated page

package/skeletons/audit_event.md

@@ -0,0 +1,34 @@
+---
+id: AUDIT-001
+title: "user.login.succeeded audit event"
+type: audit_event
+---
+<!-- audit_event authoring skeleton (spec-objects-security). Fill every part
+     with substantive content. Contract (manifest body_extraction asserts):
+     - Frontmatter MUST carry id, title, type (type:
+       audit_event).
+     - An "Event Schema" section MUST carry a ```json code block with the
+       event's payload schema. -->
+# [AUDIT-001] user.login.succeeded audit event
+
+Emitted by the auth service when AUTHFLOW-001 completes and a session is
+established. Appended to the tenant's immutable audit stream and queryable by
+ROLE-001 (Tenant Auditor) holders.
+
+## Event Schema
+
+```json
+{
+  "type": "object",
+  "required": ["event", "occurred_at", "tenant_id", "user_id", "source_ip"],
+  "properties": {
+    "event": { "const": "user.login.succeeded" },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "tenant_id": { "type": "string", "format": "uuid" },
+    "user_id": { "type": "string", "format": "uuid" },
+    "source_ip": { "type": "string" },
+    "idp_issuer": { "type": "string", "format": "uri" },
+    "mfa_method": { "type": "string", "enum": ["totp", "webauthn", "none"] }
+  }
+}
+```