diff --git a/spec/functional/FR-003-semantic-manifest-contract.md b/spec/functional/FR-003-semantic-manifest-contract.md index 16a5406..e9d41fa 100644 --- a/spec/functional/FR-003-semantic-manifest-contract.md +++ b/spec/functional/FR-003-semantic-manifest-contract.md @@ -44,7 +44,7 @@ traceability rule keeps its meaning. ## Behavior - The manifest `semantic` block SHALL carry exactly these keys and values: `contract_version: 1.0.0`, `package: agent-ix/spec-objects-security`, `exports` listing every object type that ships a schema, `imports: {}`, `targets: [json-schema, markdown]`, `mappings: [typed-table, sysml-fence, ocl-clause, record-sections]`, `compatibility_posture: additive`, `legacy_forms: warning`. -- `semantic.exports` SHALL name all twenty-six object types: `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`, `soup_record`, `scope_exclusion`, `threat_model`. +- `semantic.exports` SHALL name all twenty-seven object types: `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`, `soup_record`, `scope_exclusion`, `threat_model`, `processing_activity`. - Every exported object type's `data_schema` SHALL be `{ schema: schemas/.json }`. - No exported object type SHALL carry an inline `data_schema`. - The manifest SHALL carry the `traceability` block (`required_relations`, `acyclic_edges`) and every object type's `allowed_links` and `roles`. `control.allowed_links.mitigates` is `[threat, risk, vulnerability, hazard, failure_mode]` ([FR-007](./FR-007-control-mitigates-safety-objects.md)); the other target lists are as authored in the manifest. @@ -65,8 +65,8 @@ traceability rule keeps its meaning. | ID | Criteria | Verification | |----|----------|--------------| -| FR-003-AC-1 | The loaded `semantic` block equals the eight admitted keys with the values above, and `exports` equals the twenty-six object-type names. | Test | -| FR-003-AC-4 | `quire.Registry.load_from([module dir])` lists all twenty-six archetypes and `validate_document` on each skeleton reports no `semantic.*` load failure. | Test | +| FR-003-AC-1 | The loaded `semantic` block equals the eight admitted keys with the values above, and `exports` equals the twenty-seven object-type names. | Test | +| FR-003-AC-4 | `quire.Registry.load_from([module dir])` lists all twenty-seven archetypes and `validate_document` on each skeleton reports no `semantic.*` load failure. | Test | | FR-003-AC-5 | `quoin module install path:` exits zero and `quoin module` lists `spec-objects-security`; the previously installed entry is restored afterwards. | Test | | FR-003-AC-6 | A manifest copy whose `semantic` block gains a key `foo` is refused by Quire's loader. The refusal is verified; the half that requires the diagnostic to *name* `foo` or the path is an explicit expected failure while `agent-ix/quire-rs#221` and `agent-ix/quire-rs#394` are open. | Test | | FR-003-AC-7 | `quire validate --module ` and `quoin module install path:` (with `HOME` pointed at a temporary directory, so the real install and registry are untouched) both accept the shipped manifest; a copy with an unknown top-level key is refused by `quire validate` naming `bogus_key`, and a copy with an unknown `semantic` key is refused by `quoin module install` naming `semantic.foo`. No copy of the schema is held here. | Test | diff --git a/spec/functional/FR-004-role-schemas.md b/spec/functional/FR-004-role-schemas.md index 8ce6433..59dec6d 100644 --- a/spec/functional/FR-004-role-schemas.md +++ b/spec/functional/FR-004-role-schemas.md @@ -31,7 +31,7 @@ rules. ## Outputs -- Twenty-six object-type models, each emitted as `schemas/.json`, +- Twenty-seven object-type models, each emitted as `schemas/.json`, sealed (`unevaluatedProperties: {not: {}}`). - Support models emitted as sibling files: the open marker models `IdentityField`, `DefaultedField`, `OccurrenceField`, `OccurrenceTypeRef`, @@ -40,7 +40,8 @@ rules. records `ControlMapping` and `FlowStep`; and the closed graded vocabularies `Severity`, `Likelihood`, `Impact`, `StrideCategory`, `ControlEffectiveness`, `FindingStatus`, `ConfidentialityLevel`, `TrustLevel`, `SecretLifecycle`, - `MfaFactorKind`. + `MfaFactorKind`; and the processing-activity support schemas `ProcessingRole`, + `ProcessingActivityFrontmatter`, `NonBlankText` and `RegionCode`. ## Behavior @@ -80,6 +81,7 @@ semantic-core release that renders `identity: false` is a breaking change to the | session_config | `SessionConfig` | `clauses` | `fields`, `binds_flow: SemanticId` | `clauses` has ≥ 1 item; `operations` and `relations` forbidden | | auth_flow | `AuthFlow` | `operations` | `fields`, `clauses`, `steps: FlowStep[]` | `operations` has ≥ 1 item — a flow is its exchanges; `fields` has 0 defaulted fields; `relations` forbidden | | audit_event | `AuditEvent` | `fields` | `clauses`, `source: SemanticId` | `fields` has ≥ 1 item, 0 identity fields, ≥ 1 occurrence field, and 0 defaulted fields; `operations` and `relations` forbidden | +| processing_activity | `ProcessingActivity` | `role`, `controller`, `home_regions` | `joint_controllers`, `representative`, `dpo_contact`, `purposes`, `data_subject_categories`, `retention` | `role` is `controller` or `processor`; role-specific constraints are defined by FR-028; `home_regions` has ≥ 1 item | - The keys `mappings` and `effectiveness` of `control` are populated by the `record-sections` mapping (`agent-ix/quire-rs` FR-081) from the `## Mappings` and `## Effectiveness` sections, as [FR-014](./FR-014-control-mappings-are-clause-references.md) defines; the extractor still does not populate the other keys listed below. - `ControlMapping` SHALL be `{ set: string, clause: string }` as [FR-014](./FR-014-control-mappings-are-clause-references.md) defines it. @@ -108,13 +110,13 @@ semantic-core release that renders `identity: false` is a breaking change to the | ID | Constraint | Type | Validation | |----|------------|------|------------| | FR-004-CON-1 | No model SHALL redeclare a semantic-core model or scalar; the module namespace contributes archetype shapes only (semantic-core NFR-014 kernel discipline). | Architecture | Test | -| FR-004-CON-2 | The empty record `{}` SHALL fail every one of the twenty-six types, because every type has a non-empty required set. | Integrity | Test | +| FR-004-CON-2 | The empty record `{}` SHALL fail every one of the twenty-seven types, because every type has a non-empty required set. | Integrity | Test | ## Acceptance Criteria | ID | Criteria | Verification | |----|----------|--------------| -| FR-004-AC-1 | Each of the twenty-six shipped object-type schemas differs from every other in at least one required key, admitted key, or item rule listed in the table; a schema with only `type: object` is absent. | Test | +| FR-004-AC-1 | Each of the twenty-seven shipped object-type schemas differs from every other in at least one required key, admitted key, or item rule listed in the table; a schema with only `type: object` is absent. | Test | | FR-004-AC-2 | An asset record with one identity field validates against `Asset.json`; the same record with the identity flag removed fails; a record with no `fields` fails. | Test | | FR-004-AC-3 | A role record validates; a record carrying `operations` fails. A permission and a scope record each fail when they carry `relations`. | Test | | FR-004-AC-4 | A threat record with a `stride_category` field validates; the same record without that field fails; a `stride_category` outside `StrideCategory` fails. | Test | @@ -124,7 +126,7 @@ semantic-core release that renders `identity: false` is a breaking change to the | FR-004-AC-8 | An auth-flow record with one operation validates; an empty `operations` array fails; a record carrying `relations` fails. | Test | | FR-004-AC-9 | An audit-event record with a `Timestamp` field and no identity field validates against `AuditEvent.json`; a record whose only fields are non-`Timestamp` fails; a record with an identity field fails; a record with `operations` fails. | Test | | FR-004-AC-10 | A trust-boundary record with one clause and a `trust_level` field validates; the same record without `clauses` fails; a `trust_level` outside `TrustLevel` fails. | Test | -| FR-004-AC-11 | The empty record `{}` fails against all twenty-six schemas. | Test | +| FR-004-AC-11 | The empty record `{}` fails against all twenty-seven schemas. | Test | | FR-004-AC-12 | A `type.target` of `ix://agent-ix/spec-objects-security/unresolved/Mystery` is accepted by the schema (it is a `SemanticId`) and reported by the extractor as `semantic.unresolved-type`; a `SemanticId`-tagged `Mystery` (no `ix://` prefix) is rejected by the schema. | Test | | FR-004-AC-13 | No module schema redeclares a semantic-core model; every grammar item is a `$ref` to semantic-core. | Test | | FR-004-AC-14 | A data-classification record with a `level` field validates; one without it fails; a record carrying `relations` fails. | Test | diff --git a/spec/functional/FR-005-executable-skeletons.md b/spec/functional/FR-005-executable-skeletons.md index bc81675..efd19a8 100644 --- a/spec/functional/FR-005-executable-skeletons.md +++ b/spec/functional/FR-005-executable-skeletons.md @@ -78,13 +78,13 @@ engine refuse. | ID | Criteria | Verification | |----|----------|--------------| -| FR-005-AC-1 | Every skeleton file (twenty-six types plus three alternates) passes `validate_document` against this module with `is_valid` true and no `semantic.record-invalid` error. | Test | +| FR-005-AC-1 | Every skeleton file (twenty-seven types plus three alternates) passes `validate_document` against this module with `is_valid` true and no `semantic.record-invalid` error. | Test | | FR-005-AC-2 | For `asset`, `secret`, and `threat`, the table and `sysml` skeletons extract to identical normalized `fields` with `fieldsForm` `table` and `fence` respectively. | Test | | FR-005-AC-3 | Under a bundle index built from the skeleton frontmatter, every skeleton extracts with zero `error` diagnostics and zero `semantic.unresolved-type` findings, and every non-kernel `type.target.value` (kind `SemanticId`) starts with `ix://agent-ix/spec-objects-security/type/`. | Test | | FR-005-AC-4 | Each skeleton's `availability` states match its type: `fields` `available` for the nineteen field-bearing types, `clauses` `available` for the six clause-bearing types, `operations` `available` for `auth_flow`; `not_applicable` for every other kind. | Test | | FR-005-AC-5 | Every negative fixture produces a diagnostic carrying its `expect:` code, and at least the ten cases listed in Behavior are present. | Test | | FR-005-AC-6 | Every skeleton's H2 set equals a subset of the headings the manifest asserts for its type and includes every `required: true` heading. | Test | -| FR-005-AC-7 | The skeleton for each of the twenty-six types has no placeholder token and every asserted section body is non-empty. | Test | +| FR-005-AC-7 | The skeleton for each of the twenty-seven types has no placeholder token and every asserted section body is non-empty. | Test | | FR-005-AC-8 | Every skeleton `title` matches the `Identifier` pattern, is unique across the skeletons, and is not a `KernelScalar` name; every skeleton frontmatter carries `object` equal to `type`. | Test | | FR-005-AC-9 | No skeleton or negative fixture matches a credential-shaped literal (a private-key PEM header, a JWT triple, an `AKIA` or `ghp_`/`sk-` prefixed token, or a `password`/`secret`/`token` assignment to a literal). | Test | diff --git a/spec/functional/FR-006-security-safe-declarations.md b/spec/functional/FR-006-security-safe-declarations.md index 75909c5..66f9676 100644 --- a/spec/functional/FR-006-security-safe-declarations.md +++ b/spec/functional/FR-006-security-safe-declarations.md @@ -56,7 +56,7 @@ that an omitted grade reads as a refusal rather than as an implicit grant. - No key of any type SHALL carry secret material. - The module SHALL gate the free-text carriers the grammar admits — `FieldDecl.doc`, `FlowStep.doc`, and the clause bodies — with the credential-shape scan of [FR-005](./FR-005-executable-skeletons.md) rather than with a schema, because no JSON Schema can forbid a string from containing a credential. - No emitted schema of this module SHALL carry a JSON Schema `default` keyword anywhere, so no consumer can read a permission, a trust level, or a control effectiveness that the author did not write. -- Every one of the twenty-six object types SHALL admit 0 defaulted fields: a `FieldDecl` carrying `default` is refused, so a declaration cannot carry the material or the grade it is about. +- Every one of the twenty-seven object types SHALL admit 0 defaulted fields: a `FieldDecl` carrying `default` is refused, so a declaration cannot carry the material or the grade it is about. - The rule SHALL cover the types that grant, not only the types that hold material. Restricting it to `secret`, `encryption_key`, `jwt_claim` and `csrf_token` leaves it off exactly the rows the merge gate names: a `control` whose `effectiveness` defaults to `effective`, a `trust_boundary` whose `trust_level` defaults to `trusted`, and a `role`, `permission` or `scope` whose grant row carries a default. - Each type that admits `operations` SHALL apply the same refusal to `operations[].params[]`, whose items are `FieldDecl`s too. Without it the guard reaches the declaration's own fields and misses the parameter list, which is exactly where an authentication exchange names its code, verifier and token. - The TypeSpec source SHALL encode every negative item rule as `items: { not: … }`. @@ -82,7 +82,7 @@ that an omitted grade reads as a refusal rather than as an implicit grant. | FR-006-AC-1 | Each of the ten emitted vocabularies has exactly the members listed, as a closed `enum`, and admits no other value. | Test | | FR-006-AC-2 | For each vocabulary, a record carrying its unassessed member validates and a record carrying an invented member fails. | Test | | FR-006-AC-3 | No shipped schema of this module carries a `default` in **schema position** at any depth. The discriminator is the criterion: semantic-core's `FieldDecl` and this module's `DefaultedField.json` both declare a *property* named `default`, which is a key of a `properties` object and not a keyword, so a scan that reports those means nothing. | Test | -| FR-006-AC-4 | For each of the twenty-six types, a record carrying a field with a `default` — or, where the type admits `operations`, an operation parameter with a `default` — fails its schema, while the same record without it validates. The defaulted `FieldDecl` used to test this is itself a valid semantic-core `FieldDecl`, so the module's own rule is what refuses it rather than the grammar. | Test | +| FR-006-AC-4 | For each of the twenty-seven types, a record carrying a field with a `default` — or, where the type admits `operations`, an operation parameter with a `default` — fails its schema, while the same record without it validates. The defaulted `FieldDecl` used to test this is itself a valid semantic-core `FieldDecl`, so the module's own rule is what refuses it rather than the grammar. | Test | | FR-006-AC-7 | No shipped schema uses `minContains` or `maxContains`, so no negative item rule can invert under a validator that does not implement them. | Test | | FR-006-AC-5 | A skeleton whose `Constraints` cell carries `default: ` is refused by the extractor with `semantic.unknown-constraint-keyword`, so the Markdown path cannot express embedded material. | Test | | FR-006-AC-6 | `ControlEffectiveness` and `TrustLevel` — the two vocabularies ordered by how much they grant — begin at their unassessed member (`not_assessed`, `untrusted`). The other eight are unordered: their `unknown` member states that nobody assessed it, and no schema turns that into a grant. | Test | diff --git a/spec/functional/FR-026-threat-model-object.md b/spec/functional/FR-026-threat-model-object.md index d3cb805..5cb63ed 100644 --- a/spec/functional/FR-026-threat-model-object.md +++ b/spec/functional/FR-026-threat-model-object.md @@ -90,8 +90,8 @@ module. This requirement names no requirement id for the architecture objects un ### Exports -- `threat_model` is the twenty-sixth object type. `semantic.exports` SHALL name it ([FR-003](./FR-003-semantic-manifest-contract.md)), - and it is one of the twenty-six types covered by the schema, skeleton and no-default contracts of +- `threat_model` is one of the twenty-seven object types. `semantic.exports` SHALL name it ([FR-003](./FR-003-semantic-manifest-contract.md)), + and it is one of the twenty-seven types covered by the schema, skeleton and no-default contracts of [FR-004](./FR-004-role-schemas.md), [FR-005](./FR-005-executable-skeletons.md) and [FR-006](./FR-006-security-safe-declarations.md). @@ -122,7 +122,7 @@ not a testable obligation of this requirement. | FR-026-AC-7 | `ThreatModel.json` carries no `default` for `method` or `reviewed_by`, and an extracted record has no `method` or `reviewed_by` key the author did not write. | Test | | FR-026-AC-8 | No manifest entry, rule text, skeleton or README added by this requirement names or quotes a paywalled standard; the only sources named are STRIDE, OWASP's free threat-modelling guidance and NIST SP 800-154. | Inspection | | FR-026-AC-9 | The module manifest declares `considers` and `covers` in `edge_types`; the module loads, and removing either declaration makes it fail to load naming the verb. | Test | -| FR-026-AC-10 | `semantic.exports` names `threat_model` and has twenty-six entries; `ThreatModel.json` is emitted without `default` keys; the `threat_model` skeleton validates; the empty record `{}` fails `ThreatModel.json`. | Test | +| FR-026-AC-10 | `semantic.exports` names `threat_model` and has twenty-seven entries; `ThreatModel.json` is emitted without `default` keys; the `threat_model` skeleton validates; the empty record `{}` fails `ThreatModel.json`. | Test | ## Dependencies diff --git a/spec/functional/FR-028-processing-activity.md b/spec/functional/FR-028-processing-activity.md new file mode 100644 index 0000000..6e4a8eb --- /dev/null +++ b/spec/functional/FR-028-processing-activity.md @@ -0,0 +1,69 @@ +--- +id: FR-028 +title: "A processing_activity states the person-authored context for records of processing" +type: FR +relationships: + - target: "ix://agent-ix/spec-objects-security/FR-023" + type: depends_on + - target: "ix://agent-ix/spec-objects-architecture/FR-015" + type: depends_on +--- +# FR-028: A processing_activity states the person-authored context for records of processing + +## Description + +The security module SHALL let a person describe one processing activity and identify the connections, sinks and parts it covers. The authored fields state contextual facts that the data-flow model cannot supply. The module SHALL NOT derive them from names, code, runtime observations, a purpose field on a sink, or any source outside this requirement. + +## Inputs + +- A Markdown object with `type: processing_activity` and `object: processing_activity`. +- The `ProcessingActivity` TypeSpec model and its generated frontmatter schema. +- `covers` relationships to `connection`, `data_sink` or `part` objects. + +## Outputs + +- A `processing_activity` object type exported in `semantic.exports`. +- `ProcessingActivity.json`, `ProcessingActivityFrontmatter.json`, `ProcessingRole.json`, a manifest entry and an authoring skeleton. +- A required-relation declaration that reports an activity with no `covers` edge. + +## Behavior + +### Frontmatter + +- `ProcessingActivity` SHALL require `role`, `controller` and a non-empty `home_regions` list. +- `role` SHALL be exactly `controller` or `processor`. +- When `role` is `controller`, `controller` SHALL be one non-empty name-and-contact string; `purposes`, `data_subject_categories` and `retention` SHALL each be present and non-empty. +- When `role` is `processor`, `processor` SHALL be a non-empty name-and-contact string for the processor itself, and `controller` SHALL be a non-empty list of non-empty name-and-contact strings, one for each controller it acts for. `purposes`, `data_subject_categories` and `retention` MAY be absent; the dossier takes categories of processing from covered sinks. +- `joint_controllers` SHALL be an optional list of non-empty name-and-contact strings for a controller activity. `representative` and `dpo_contact` SHALL be optional non-empty text. +- Each `home_regions` member SHALL be an ISO 3166-1 alpha-2 country code or `eu` or `eea`, using the same vocabulary as `data_sink.region`. +- The schema SHALL NOT provide a default for any authored field or derive a value from another field. + +### Coverage edges + +- The module manifest SHALL declare the `processing_activity` object type and allow `covers` targets of `connection`, `data_sink` and `part`. +- Each `processing_activity` SHALL have at least one outgoing `covers` edge to one of those types. +- A `covers` edge to any other object type or to a missing target SHALL fail validation with a located edge diagnostic. +- A `covers` edge to a `queue` SHALL fail as a wrong-kind edge. + +### Skeleton + +- The `processing_activity` skeleton SHALL show both role forms, the required fields for each form and a valid `covers` edge. +- The skeleton SHALL validate with `quire validate`. + +## Acceptance Criteria + +| ID | Criteria | Verification | +|----|----------|--------------| +| FR-028-AC-1 | A controller activity with controller details, purposes, data-subject categories, retention, home regions and a valid `covers` edge validates. | Test | +| FR-028-AC-2 | A processor activity with a processor name and contact, a non-empty controller list and home regions validates without `purposes`, `data_subject_categories` or `retention`. | Test | +| FR-028-AC-3 | A controller activity without `retention`, `purposes` or `data_subject_categories`, and a processor activity without its own `processor` identity/contact or with an empty controller list, each fail with a diagnostic naming the missing or invalid field. | Test | +| FR-028-AC-4 | An unknown role, an empty home-region list, or a home-region value outside the stated vocabulary fails validation. | Test | +| FR-028-AC-5 | A `processing_activity` with no `covers` edge fails validation; an edge to a `connection`, `data_sink` or `part` validates. | Test | +| FR-028-AC-6 | A `covers` edge to a `queue` fails with a wrong-kind diagnostic, and an edge to an absent target fails with a dangling-target diagnostic. | Test | +| FR-028-AC-7 | The module exports `processing_activity`; its generated schema and skeleton pass the module schema-drift and `quire validate` checks. | Test | +| FR-028-AC-8 | Omitting any optional authored field leaves it absent in the extracted record; no omitted value is populated from another field, artifact, code or runtime source. | Test | + +## Dependencies + +- **Upstream**: spec-objects-architecture `data_sink` and `connection` (PLAT-1532, PLAT-1535); spec-objects-security FR-023. +- **Downstream**: quoin FR-207, which reads this object to generate records of processing. diff --git a/spec/functional/index.md b/spec/functional/index.md index 1df31f7..17fcf6f 100644 --- a/spec/functional/index.md +++ b/spec/functional/index.md @@ -32,3 +32,4 @@ description: "Index of artifacts in this directory." * [FR-025: A control states safeguards and protects a connection or data_sink, and the module ships the remediation vocabulary and starter flow rules](./FR-025-control-safeguards-and-starter-flow-rules.md) * [FR-026: A threat_model states its method, who led it, what it covers and which threats it considers](./FR-026-threat-model-object.md) * [FR-027: A threat targets model elements, a risk records a named person's decision, and the module ships the threat-model completeness flow rules](./FR-027-threat-treatment-and-completeness-rules.md) +* [FR-028: A processing_activity states the person-authored context for records of processing](./FR-028-processing-activity.md)