@openauditmodel/cli 0.2.1 → 0.4.0

package/profiles/secrets-and-key-management/0.1/profile.json

@@ -0,0 +1,219 @@
+{
+  "profileVersion": "0.1",
+  "name": "secrets-and-key-management",
+  "version": "0.1",
+  "status": "experimental",
+  "coreVersions": ["0.1"],
+  "title": "Secrets and Key Management Profile",
+  "description": "Additional conformance requirements for the custody of secrets, cryptographic keys and certificates: creation, rotation, revocation, destruction, policy change, and the privileged reveal and export operations that turn protected material into copied material. Every requirement adds to the OpenAuditModel Core Specification; none relaxes it. Routine automated retrieval of a secret and ordinary cryptographic operations against a key are deliberately not governed. An audit event records that a secret operation occurred; it never records the secret.",
+  "rules": [
+    {
+      "id": "SECRET-CORE-001",
+      "description": "Every governed secret, key or certificate operation records the authorization decision that permitted it and the classification of the material it acted on.",
+      "rationale": "Custody operations are the ones an attacker performs after gaining a foothold and before doing anything visible, so an operation with no recorded decision cannot be separated from one that bypassed policy. Classification is what makes the record triageable: a key protecting settlement records and a key in a sandbox produce identical events otherwise, and a reviewer who cannot tell them apart must treat every rotation as an incident or none of them.",
+      "severity": "error",
+      "events": [
+        "secret.create",
+        "secret.update",
+        "secret.rotate",
+        "secret.revoke",
+        "secret.delete",
+        "secret.reveal",
+        "secret.export",
+        "key.generate",
+        "key.import",
+        "key.rotate",
+        "key.enable",
+        "key.disable",
+        "key.destroy",
+        "key.export",
+        "certificate.issue",
+        "certificate.renew",
+        "certificate.revoke",
+        "certificate.delete"
+      ],
+      "eventPrefixes": ["secret.policy.", "key.policy."],
+      "requiredPaths": ["/authorization", "/resource/classification"]
+    },
+    {
+      "id": "SECRET-CORE-002",
+      "description": "Every governed operation records the kind of protected material it acted on.",
+      "rationale": "The kind of material is the blast radius. Replacing a read-only reporting credential and replacing the key that signs every payment instruction are the same event shape and entirely different incidents, and no external reader can recover the difference from an opaque identifier once the material is gone. The type is recorded rather than inferred because only the custodian knows it, and it is known at exactly the moment the event is emitted.",
+      "severity": "error",
+      "events": [
+        "secret.create",
+        "secret.update",
+        "secret.rotate",
+        "secret.revoke",
+        "secret.delete",
+        "secret.reveal",
+        "secret.export",
+        "key.generate",
+        "key.import",
+        "key.rotate",
+        "key.enable",
+        "key.disable",
+        "key.destroy",
+        "key.export",
+        "certificate.issue",
+        "certificate.renew",
+        "certificate.revoke",
+        "certificate.delete"
+      ],
+      "eventPrefixes": ["secret.policy.", "key.policy."],
+      "requiredMetadata": [{ "path": "/secret/type", "type": "string" }]
+    },
+    {
+      "id": "SECRET-CORE-003",
+      "description": "A governed operation should record why it happened, which custody system holds the material, and how it correlates with the wider operation.",
+      "rationale": "These are the fields a reviewer reaches for first and a producer omits most often. They are recommended rather than required because a scheduled rotation has no justification beyond the policy that scheduled it, because a deployment may have exactly one custody system and nothing to distinguish, and because correlation identifiers presuppose a tracing or workflow discipline that a conforming producer may not have. A missing answer here should prompt a question, not fail a build.",
+      "severity": "warning",
+      "events": [
+        "secret.create",
+        "secret.update",
+        "secret.rotate",
+        "secret.revoke",
+        "secret.delete",
+        "secret.reveal",
+        "secret.export",
+        "key.generate",
+        "key.import",
+        "key.rotate",
+        "key.enable",
+        "key.disable",
+        "key.destroy",
+        "key.export",
+        "certificate.issue",
+        "certificate.renew",
+        "certificate.revoke",
+        "certificate.delete"
+      ],
+      "eventPrefixes": ["secret.policy.", "key.policy."],
+      "recommendedPaths": ["/reason", "/request/correlationId", "/metadata/secret/provider"]
+    },
+    {
+      "id": "SECRET-LIFECYCLE-001",
+      "description": "Material brought into custody records who owns it.",
+      "rationale": "An unowned secret cannot be rotated and cannot be retired, because nobody knows which systems break when it changes. Ownership is knowable at exactly one moment — when the material is created, generated, imported or issued — and every later attempt to reconstruct it is archaeology across deployment manifests. Recording an owning team or service is not personal data and does not require naming an individual.",
+      "severity": "error",
+      "events": ["secret.create", "key.generate", "key.import", "certificate.issue"],
+      "requiredPaths": ["/resource/ownerId"]
+    },
+    {
+      "id": "SECRET-ROTATE-001",
+      "description": "Rotation records the transition it performed, naming what changed rather than what the material now is.",
+      "rationale": "Rotation is the healthy operation in this domain and the one most often recorded as a bare fact. Without `/change` the trail says something was replaced and nothing about which version succeeded which, so a consumer failing on a stale value cannot be tied to the rotation that caused it and a rotation that silently did nothing is indistinguishable from one that worked. `/change` is the core structure designed to carry that transition without carrying a value: `changedFields` names members, and `before` and `after` carry version identifiers, never key or secret material.",
+      "severity": "error",
+      "events": ["secret.rotate", "key.rotate", "certificate.renew"],
+      "requiredPaths": ["/change"],
+      "recommendedPaths": ["/change/changedFields"]
+    },
+    {
+      "id": "SECRET-ACCESS-001",
+      "description": "Revealing a stored value or exporting material records how the principal authenticated and why the access was needed.",
+      "rationale": "Reveal and export are the two operations that convert protected material into copied material: after them the custodian is no longer the only holder and no later control can undo that. The authentication context is what distinguishes a reviewed operator session from a replayed one, and the justification is the only thing a reviewer has months later, when the actor has changed teams and the copy is still valid. Recording the fact of the access never requires recording any part of the value.",
+      "severity": "error",
+      "events": ["secret.reveal", "secret.export", "key.export"],
+      "requiredPaths": ["/authentication", "/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "SECRET-ACCESS-002",
+      "description": "Access the producer has declared to be emergency or break-glass access is approved and performed from a multi-factor authenticated session.",
+      "rationale": "Break-glass access exists precisely to bypass the controls that normally apply, so it is the one path where the audit record is the only remaining control. `/approval` is required as a present object rather than as an approved decision, because emergencies are frequently approved retrospectively and the model can say so — `status: pending` on a successful access is an accurate record of a control bypass and exactly what a post-incident review looks for. Suppressing it would be the failure this rule exists to prevent. The rule fires only on the producer's own declaration, so the profile never has to guess what counts as an emergency in a given deployment.",
+      "severity": "error",
+      "events": ["secret.reveal", "secret.export", "key.export"],
+      "when": { "path": "/metadata/secret/emergencyAccess", "equals": true },
+      "requiredPaths": ["/approval"],
+      "requiredValues": [{ "path": "/authentication/mfa", "equals": true }]
+    },
+    {
+      "id": "SECRET-EXPORT-001",
+      "description": "An export records the kind of destination the material was moved to.",
+      "rationale": "Where exported material went is the single fact that determines the risk of the operation, and it is the fact least likely to survive in anyone's memory. Material copied into a second hardware custodian, written to offline backup media, displayed on an operator console and handed to an external party are four different exposures that produce identical events without this field. The profile requires the kind of destination rather than an address, because an address is often itself sensitive and is never comparable across deployments.",
+      "severity": "error",
+      "events": ["secret.export", "key.export"],
+      "requiredMetadata": [{ "path": "/secret/destinationType", "type": "string" }]
+    },
+    {
+      "id": "SECRET-DESTROY-001",
+      "description": "Revoking, disabling, destroying or deleting protected material is justified.",
+      "rationale": "These are the operations an audit trail is least able to reconstruct afterwards, because the evidence is what was removed. Destroying an encryption key destroys the readability of everything it protected, and revoking a certificate can take a service offline as effectively as an outage — so the difference between a planned decommissioning, an incident response and a mistake has to be stated at the time, by the only party who knows it. Approval is recommended rather than required because many deployments legitimately let a team retire its own test material, and a rule that forbade that would be switched off rather than met.",
+      "severity": "error",
+      "events": [
+        "secret.revoke",
+        "secret.delete",
+        "key.disable",
+        "key.destroy",
+        "certificate.revoke",
+        "certificate.delete"
+      ],
+      "requiredPaths": ["/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "SECRET-APPROVAL-001",
+      "description": "An operation the producer has declared to require approval records the approval.",
+      "rationale": "Approval requirements in this domain are set locally: one organization requires two signatures to destroy a key and another rotates certificates unattended thousands of times a day, and a profile that imposed either model on the other would describe one deployment and be ignored by the rest. So the producer declares the requirement and the profile enforces the consequence — an operation that its own policy says needs approval, and that carries none, is the control gap this rule makes visible. The rule requires the approval object, not an approved status, so that a rejected or still-pending approval on a completed operation is recordable rather than unrepresentable.",
+      "severity": "error",
+      "events": [
+        "secret.create",
+        "secret.update",
+        "secret.rotate",
+        "secret.revoke",
+        "secret.delete",
+        "secret.reveal",
+        "secret.export",
+        "key.generate",
+        "key.import",
+        "key.rotate",
+        "key.enable",
+        "key.disable",
+        "key.destroy",
+        "key.export",
+        "certificate.issue",
+        "certificate.renew",
+        "certificate.revoke",
+        "certificate.delete"
+      ],
+      "eventPrefixes": ["secret.policy.", "key.policy."],
+      "when": { "path": "/metadata/secret/approvalRequired", "equals": true },
+      "requiredPaths": ["/approval"]
+    },
+    {
+      "id": "SECRET-POLICY-001",
+      "description": "A change to a secret or key policy records the transition and why it was made.",
+      "rationale": "A policy change is where the controls over every piece of material in scope are switched off at once, and it usually leaves no trace anywhere else: lengthening a rotation interval, removing an approval requirement or widening who may reveal a value weakens thousands of secrets in a single event that looks like routine configuration. Recording the before and after state is what turns that event into evidence, and recording the reason is what separates a deliberate policy decision from an accident nobody noticed for a year.",
+      "severity": "error",
+      "eventPrefixes": ["secret.policy.", "key.policy."],
+      "requiredPaths": ["/change", "/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "SECRET-CERT-001",
+      "description": "Issuing or renewing a certificate records when it stops being valid.",
+      "rationale": "A certificate always has an end of validity, it is fixed at the moment of issue, and it is the fact that causes the outage when nobody wrote it down. This profile recommends an expiry everywhere else and requires it here for that reason: expiry is optional for material that may legitimately be indefinite, and mandatory for material that cannot be. The rule constrains presence and JSON type only; the v0.1 rule language cannot compare an expiry against the event time or against a maximum lifetime.",
+      "severity": "error",
+      "events": ["certificate.issue", "certificate.renew"],
+      "requiredMetadata": [{ "path": "/secret/expiresAt", "type": "string" }],
+      "recommendedPaths": ["/metadata/secret/algorithm"]
+    },
+    {
+      "id": "SECRET-KEY-001",
+      "description": "Importing key material generated outside the custody system is justified.",
+      "rationale": "Imported material existed somewhere else before the import, under procedures the custodian did not run and cannot attest to, and it may still exist there afterwards. That is the one property of a key that a custody system cannot establish for itself, so the reason for accepting external material has to be recorded by the party that decided to accept it. Generation inside the custodian carries no such requirement, which is deliberate: the profile should make the safer path the cheaper one.",
+      "severity": "error",
+      "events": ["key.import"],
+      "requiredPaths": ["/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "SECRET-KEY-002",
+      "description": "Key lifecycle events should record the algorithm the key uses and when it stops being valid.",
+      "rationale": "Algorithm and expiry are what make a key inventory answerable — which keys use a deprecated algorithm, which expire this quarter — and neither can be reconstructed after the key is destroyed. They are recommended rather than required because a custodian may legitimately treat the algorithm as an internal detail of a managed key service it does not control, and because a key held for as long as the data it protects has no expiry to record.",
+      "severity": "warning",
+      "events": ["key.generate", "key.import", "key.rotate"],
+      "recommendedPaths": ["/metadata/secret/algorithm", "/metadata/secret/expiresAt"]
+    }
+  ]
+}

package/semantic-conventions/README.md

@@ -21,16 +21,21 @@ The vocabularies here are **open**. The core schema constrains their form, not t
 
 ## Documents
 
-| Document                                                   | Covers                                            |
-| ---------------------------------------------------------- | ------------------------------------------------- |
-| [event-naming.md](event-naming.md)                         | The naming rule, categories, activity types       |
-| [authentication.md](authentication.md)                     | Sign-in, sign-out, sessions, credentials, factors |
-| [identity-and-access.md](identity-and-access.md)           | Users, roles, permissions, service accounts       |
-| [data-access.md](data-access.md)                           | Reading, exporting, sharing and modifying data    |
-| [configuration-and-change.md](configuration-and-change.md) | Settings, secrets, deployments, releases          |
-| [workflow-and-approval.md](workflow-and-approval.md)       | Requests, approvals, workflow state, incidents    |
-| [privileged-operations.md](privileged-operations.md)       | Administrative and break-glass operations         |
-| [correlation-and-tracing.md](correlation-and-tracing.md)   | Request, trace, span and correlation identifiers  |
+| Document                                                   | Covers                                              |
+| ---------------------------------------------------------- | --------------------------------------------------- |
+| [event-naming.md](event-naming.md)                         | The naming rule, categories, activity types         |
+| [authentication.md](authentication.md)                     | Sign-in, sign-out, sessions, credentials, factors   |
+| [identity-and-access.md](identity-and-access.md)           | Users, roles, permissions, service accounts         |
+| [data-access.md](data-access.md)                           | Reading, exporting, sharing and modifying data      |
+| [configuration-and-change.md](configuration-and-change.md) | Settings, secrets, deployments, releases            |
+| [workflow-and-approval.md](workflow-and-approval.md)       | Requests, approvals, workflow state, incidents      |
+| [privileged-operations.md](privileged-operations.md)       | Administrative and break-glass operations           |
+| [message-brokers.md](message-brokers.md)                   | Broker control plane: destinations, access, offsets |
+| [secrets-and-keys.md](secrets-and-keys.md)                 | Secret, key and certificate lifecycle and access    |
+| [financial-transactions.md](financial-transactions.md)     | Movements of money, limits and reconciliation       |
+| [backup-and-recovery.md](backup-and-recovery.md)           | Backup, restore, recovery and retention policy      |
+| [customer-and-account.md](customer-and-account.md)         | Business parties and business accounts              |
+| [correlation-and-tracing.md](correlation-and-tracing.md)   | Request, trace, span and correlation identifiers    |
 
 ## Relationship to profiles
 

package/semantic-conventions/backup-and-recovery.md

@@ -0,0 +1,124 @@
+# Backup and Recovery Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+## 1. Recommended event names
+
+Three categories, because taking a backup, deleting one and changing a retention policy are different
+kinds of operation:
+
+| Family                                  | `event.category`       |
+| --------------------------------------- | ---------------------- |
+| Backup, snapshot and restore operations | `data-infrastructure`  |
+| Deletion, expiry and failover           | `privileged-operation` |
+| Retention and schedule policy           | `configuration`        |
+
+### Backups and snapshots
+
+| Name              | Operation                                          |
+| ----------------- | -------------------------------------------------- |
+| `backup.create`   | A backup was started                               |
+| `backup.complete` | A backup finished, successfully or otherwise       |
+| `backup.verify`   | A backup was tested for restorability              |
+| `backup.expire`   | A backup passed its retention date and was removed |
+| `backup.delete`   | A backup was deleted before its retention date     |
+| `snapshot.create` | A point-in-time snapshot was taken                 |
+| `snapshot.delete` | A snapshot was removed                             |
+
+### Restore and recovery
+
+| Name                | Operation                                     |
+| ------------------- | --------------------------------------------- |
+| `restore.start`     | A restore was started                         |
+| `restore.complete`  | A restore finished, successfully or otherwise |
+| `recovery.start`    | A recovery procedure was started              |
+| `recovery.complete` | A recovery procedure finished                 |
+| `recovery.failover` | Service was moved to a standby site or system |
+| `recovery.failback` | Service was returned to the primary           |
+
+### Policy
+
+`backup.policy.update` records a change to a retention period, a schedule or a verification
+requirement. It is the operation that decides whether the rest of this vocabulary will have anything
+to describe.
+
+## 2. These operations come in pairs
+
+`backup.create` and `backup.complete`, `restore.start` and `restore.complete`, `recovery.start` and
+`recovery.complete` are two events about one operation, because the operation takes long enough that
+its beginning and its end are separately interesting.
+
+**The pair MUST share a `request.correlationId`.** A start with no completion is precisely what an
+auditor is looking for — a backup that never finished, a restore abandoned halfway — and it is only
+findable when the two events can be joined. See
+[correlation-and-tracing.md](correlation-and-tracing.md).
+
+The outcome belongs on the completion event, in `event.outcome`, not in the name:
+`backup.complete` with `outcome: failure` rather than a `backup.failed` name. See
+[event-naming.md](event-naming.md) §5.
+
+## 3. Progress events are deliberately ungoverned
+
+A running backup emits progress continuously. `restore.progress` and `backup.chunk.write` appear in
+the published fixtures as events the profile does **not** govern, and the reason is the one
+[profiles/backup-and-recovery/README.md](../profiles/backup-and-recovery/README.md) gives: requiring
+an authorization decision and a reason on every chunk written would put the heaviest requirements on
+the highest-volume event, and the requirement would be switched off rather than met.
+
+Producers MAY emit progress events. They are operational telemetry, and an audit trail that filled
+with them would be reviewed by nobody.
+
+## 4. What must never be recorded
+
+**The backed-up content.** A backup event names a backup; it does not sample it, summarise it or
+quote a record from it. A backup exists precisely because it holds everything, and an audit trail is
+not the place to leak a row of it.
+
+**Nothing that identifies the data subjects inside a backup.** A backup of a customer database is
+described by its scope, its size and its source system, never by whose records it contains. A restore
+event is the same: it records that data was restored, from which backup, to where, and by whom.
+
+Credentials for the backup target, storage account keys and connection strings are out of bounds for
+the ordinary reason — see [privacy.md](../specification/privacy.md) §6.
+
+## 5. Which principal goes where
+
+| Operation                                         | `actor`                 | `resource`      | `subject` |
+| ------------------------------------------------- | ----------------------- | --------------- | --------- |
+| A scheduled job takes a backup                    | the job's identity      | the **backup**  | absent    |
+| An operator deletes a backup before its retention | the operator            | the **backup**  | absent    |
+| An operator restores a database                   | the operator            | the **restore** | absent    |
+| A platform fails service over to a standby        | the platform's identity | the **service** | absent    |
+
+The system that was backed up is a **related resource**, not the primary one: what the event is about
+is the backup or the restore, and that is what changed. `subject` does not appear in this domain — no
+backup operation is performed on another principal's behalf in the sense
+[actor-model.md](../specification/actor-model.md) §5 defines.
+
+## 6. Early deletion is the event that matters
+
+`backup.expire` is routine: a retention period elapsed and the platform did what it was configured to
+do. `backup.delete` is not: a principal removed a backup before its retention date, and the recovery
+position of whatever it protected is now different.
+
+Where the producer distinguishes the two, the distinction SHOULD be in the name rather than in a
+field, which is why both names exist. An early deletion SHOULD carry its justification in `reason`,
+and where the producer's policy requires a second principal to agree, in `approval`.
+
+## 7. Context to populate
+
+| Field                   | Guidance                                                             |
+| ----------------------- | -------------------------------------------------------------------- |
+| `authorization`         | The decision that permitted the operation                            |
+| `request.correlationId` | Shared by the start and completion of one operation                  |
+| `relatedResources`      | The system, database or volume the backup protects                   |
+| `reason`                | Why an early deletion, a failover or an unscheduled restore was done |
+| `approval`              | Where deletion or failover requires a second principal's decision    |
+| `metadata.backup`       | Scope, size, retention class, target and verification state          |
+
+## 8. Example
+
+See
+[examples/profiles/backup-and-recovery/valid/restore-start.json](../examples/profiles/backup-and-recovery/valid/restore-start.json)
+for the start of a restore with the authorization decision, the correlation identifier that joins it
+to its completion, and the backup it restores from.

package/semantic-conventions/customer-and-account.md

@@ -0,0 +1,133 @@
+# Customer and Account Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+## 1. Recommended event names
+
+Several categories, because opening an account, restricting one and reading a customer record are
+different kinds of operation:
+
+| Family                                   | `event.category`     |
+| ---------------------------------------- | -------------------- |
+| Customer and account record changes      | `data-modification`  |
+| Opening, closing and reopening           | `resource-lifecycle` |
+| Restriction, freezing and status changes | `security`           |
+| Reading a customer or account record     | `data-access`        |
+| Limits and thresholds                    | `configuration`      |
+
+### Customers
+
+| Name                | Operation                                          |
+| ------------------- | -------------------------------------------------- |
+| `customer.create`   | A customer record was created                      |
+| `customer.update`   | Customer attributes changed                        |
+| `customer.merge`    | Two customer records were combined                 |
+| `customer.restrict` | A restriction was placed on a customer             |
+| `customer.close`    | A customer relationship was ended                  |
+| `customer.delete`   | A customer record was removed                      |
+| `customer.restore`  | A closed or deleted customer record was reinstated |
+
+### Accounts
+
+| Name               | Operation                              |
+| ------------------ | -------------------------------------- |
+| `account.open`     | An account was opened                  |
+| `account.update`   | Account attributes changed             |
+| `account.freeze`   | An account was frozen                  |
+| `account.unfreeze` | A freeze was lifted                    |
+| `account.restrict` | A restriction was placed on an account |
+| `account.close`    | An account was closed                  |
+| `account.reopen`   | A closed account was reopened          |
+
+### Limits and status
+
+Two families are selected by prefix, so any action under them is governed:
+
+| Prefix            | Covers                                              |
+| ----------------- | --------------------------------------------------- |
+| `account.limit.`  | Changes to a limit or threshold on an account       |
+| `account.status.` | Changes to an account's standing or lifecycle state |
+
+## 2. This is not the identity vocabulary
+
+**A customer is not a user, and an account is not a login.** This document governs business parties
+and business accounts. A user, a role, a permission, a credential or a session belongs to
+[identity-and-access.md](identity-and-access.md), and the two vocabularies never select the same
+event — [profiles/customer-and-account-management/README.md](../profiles/customer-and-account-management/README.md)
+states the boundary and the profile enforces it: `identity.` is not a prefix here, and neither
+`customer.` nor `account.` is a prefix there.
+
+This is the most likely misuse of this vocabulary. A person who signs in is an identity; the same
+person as a party the business holds a relationship with is a customer. One human, two objects, two
+vocabularies, and events about them answer different questions.
+
+Where one operation genuinely touches both — closing a customer relationship and disabling the login
+that belonged to it — that is two events, one from each vocabulary, joined by
+`request.correlationId`.
+
+## 3. What must never be recorded
+
+**The customer record's contents.** Names, addresses, dates of birth, national identifiers, tax
+numbers, contact details and anything else the record holds belong in the system of record. An audit
+event says that a customer record changed, by whom, under what authorization, and **which fields
+moved** — not what they moved to.
+
+`change.changedFields` is the recommended shape for exactly this reason: it names the fields without
+carrying the values. Where before and after values genuinely must be recorded — a status transition,
+a limit amount — they SHOULD be recorded only for fields that are not personal data. See
+[change-model.md](../specification/change-model.md) and
+[privacy.md](../specification/privacy.md).
+
+An audit trail is retained for years, is read by people with no business need for a customer's
+address, and is frequently exported. It concentrates who-did-what-to-whom, which is what makes it
+valuable and what makes it dangerous.
+
+## 4. Which principal goes where
+
+| Operation                                          | `actor`      | `resource`       | `subject`    |
+| -------------------------------------------------- | ------------ | ---------------- | ------------ |
+| An agent creates a customer record                 | the agent    | the **customer** | absent       |
+| A customer updates their own details               | the customer | the **customer** | absent       |
+| An agent updates a customer's details for them     | the agent    | the **customer** | the customer |
+| An operator freezes an account                     | the operator | the **account**  | absent       |
+| An onboarding service opens an account from a form | the service  | the **account**  | absent       |
+
+The customer is the `resource` when the customer record is what changed, and the `subject` only when
+the actor acted **on the customer's behalf** — the third row. A customer is not a `subject` merely
+because the operation concerns them:
+[actor-model.md](../specification/actor-model.md) §5.2 calls that the single most common modelling
+mistake the section exists to prevent.
+
+The account a customer owns is a **related resource** on a customer event, and the customer is a
+related resource on an account event.
+
+## 5. Restriction and manual override
+
+Freezing an account, restricting a customer and overriding a limit are the operations a reviewer
+looks for, because each changes what someone may do without changing the record they would look at
+first.
+
+Where the producer distinguishes a manual override from a rule-driven one, the distinction SHOULD
+appear in `metadata` and the justification in `reason`. A restriction with no recorded reason is a
+finding. Where the producer's policy requires a second principal to agree — closing an account,
+lifting a freeze — the decision belongs in `approval`, including when approval was evaluated and
+found not to be required.
+
+## 6. Context to populate
+
+| Field                   | Guidance                                                                |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `authorization`         | The decision that permitted the change                                  |
+| `change.changedFields`  | Which fields moved, in preference to before and after values            |
+| `approval`              | Where the operation requires a second principal, including not-required |
+| `reason`                | Why a restriction, freeze, override or early closure was applied        |
+| `relatedResources`      | The accounts a customer holds, or the customer an account belongs to    |
+| `metadata.customer`     | The producer's own identifiers, the record's status and its segment     |
+| `request.correlationId` | Shared with the identity events that accompany a closure or an opening  |
+
+## 7. Example
+
+See
+[examples/profiles/customer-and-account-management/valid/customer-update.json](../examples/profiles/customer-and-account-management/valid/customer-update.json)
+for a customer record change with the authorization decision, the fields that moved, and none of the
+values that moved into them.

package/semantic-conventions/financial-transactions.md

@@ -0,0 +1,128 @@
+# Financial Transaction Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+## 1. Recommended event names
+
+This domain spans several categories, because moving money, reading a statement and changing a limit
+are different kinds of operation:
+
+| Family                               | `event.category`    |
+| ------------------------------------ | ------------------- |
+| Movements of money                   | `data-modification` |
+| Reading a transaction or a statement | `data-access`       |
+| Limits and thresholds                | `configuration`     |
+| An operation awaiting a decision     | `workflow`          |
+
+### Families
+
+Most of this vocabulary is **open by family**. The profile selects by prefix, so any action under a
+family name is governed, and the actions below are the ones the published fixtures carry rather than
+a closed list.
+
+| Prefix                      | Covers                                                 |
+| --------------------------- | ------------------------------------------------------ |
+| `financial.transfer.`       | Movement between two accounts                          |
+| `financial.payment.`        | Payment to a payee                                     |
+| `financial.payout.`         | Disbursement to a beneficiary                          |
+| `financial.deposit.`        | Money received into an account                         |
+| `financial.withdrawal.`     | Money taken out of an account                          |
+| `financial.refund.`         | Return of a previously captured amount                 |
+| `financial.chargeback.`     | A disputed payment reversed by the scheme              |
+| `financial.reversal.`       | An operation undone by the producer                    |
+| `financial.settlement.`     | Net position settled between parties                   |
+| `financial.reconciliation.` | Recorded position corrected against an external record |
+
+### Actions the fixtures carry
+
+| Name                              | Operation                                 |
+| --------------------------------- | ----------------------------------------- |
+| `financial.transfer.execute`      | A transfer was carried out                |
+| `financial.transfer.cancel`       | A transfer was cancelled before execution |
+| `financial.payment.capture`       | An authorized payment was captured        |
+| `financial.payment.reject`        | A payment was refused                     |
+| `financial.payment.cancel`        | A payment was cancelled                   |
+| `financial.payout.execute`        | A payout was carried out                  |
+| `financial.payout.cancel`         | A payout was cancelled                    |
+| `financial.withdrawal.execute`    | A withdrawal was carried out              |
+| `financial.withdrawal.reject`     | A withdrawal was refused                  |
+| `financial.refund.create`         | A refund was raised                       |
+| `financial.chargeback.open`       | A chargeback was opened                   |
+| `financial.reversal.execute`      | An operation was reversed                 |
+| `financial.settlement.execute`    | A settlement run completed                |
+| `financial.settlement.cancel`     | A settlement run was cancelled            |
+| `financial.reconciliation.adjust` | A recorded position was corrected         |
+
+### Limits
+
+| Name                     | Operation           |
+| ------------------------ | ------------------- |
+| `financial.limit.create` | A limit was defined |
+| `financial.limit.update` | A limit was changed |
+| `financial.limit.delete` | A limit was removed |
+
+## 2. The audit event is not the payment record
+
+This is the distinction the domain most often loses. An audit event records that an operation was
+performed and that it was permitted. The payment itself — the instruction, the parties, the
+reference data — lives in the system that made it.
+
+[README.md](../README.md) makes the point with the profile's own requirements: the financial profile
+asks for an amount, a currency, a direction and a status, and asks for **no account number, no
+counterparty name and no payment instruction**. That is not an oversight. A profile requires the
+fields that make an operation reviewable, not the business record itself.
+
+A reviewer needs to answer: who moved money, how much, in which direction, under what authorization,
+and did anyone approve it. None of those questions needs the payee's address.
+
+## 3. What must never be recorded
+
+- **Primary account numbers**, in full or truncated to a length that narrows the search.
+- **IBANs, sort codes and account numbers** wherever an internal identifier would serve. Where a
+  counterparty account genuinely must be identifiable, a producer SHOULD record a reference the
+  system of record can resolve, not the number itself.
+- **Counterparty personal data** — names, addresses, dates of birth.
+- **Anything that would let a reader reconstruct the payment instruction**, including a free-text
+  remittance field copied verbatim.
+- **Authentication and authorization material**: card verification values, one-time codes, tokens.
+
+An audit trail is retained for years and read by people who were not party to the transaction. It is
+the wrong place for the data a payment scheme already protects.
+
+## 4. Which principal goes where
+
+| Operation                                        | `actor`      | `resource`       | `subject`    |
+| ------------------------------------------------ | ------------ | ---------------- | ------------ |
+| A customer initiates a transfer                  | the customer | the **transfer** | absent       |
+| A payments service executes a scheduled transfer | the service  | the **transfer** | absent       |
+| An operator reverses a payment                   | the operator | the **reversal** | absent       |
+| An agent acts on a customer's instruction        | the agent    | the **payment**  | the customer |
+
+The account is a **related resource**, not the primary one: what changed is the movement of money,
+and the movement is what the event is about. The last row is the only place `subject` belongs —
+someone's authority was borrowed. See [actor-model.md](../specification/actor-model.md) §5.
+
+## 5. Manual intervention
+
+An operation performed by hand rather than by the normal path is what an auditor looks for first: a
+manual correction, an override of a limit, a reconciliation adjustment. Where the producer
+distinguishes such operations, the distinction SHOULD appear in `metadata` and the justification in
+`reason`. Where a second principal approved it, the decision belongs in `approval`.
+
+## 6. Context to populate
+
+| Field                   | Guidance                                                             |
+| ----------------------- | -------------------------------------------------------------------- |
+| `authorization`         | The decision that permitted the movement                             |
+| `approval`              | Where a second principal decided, including when not required        |
+| `request.correlationId` | The transaction reference, shared by every event about one movement  |
+| `relatedResources`      | The accounts involved, by internal identifier                        |
+| `reason`                | Why a manual correction, reversal or adjustment was made             |
+| `metadata.financial`    | Amount, currency, direction, status and the producer's own reference |
+
+## 7. Example
+
+See
+[examples/profiles/financial-transaction-management/valid/transfer-execute.json](../examples/profiles/financial-transaction-management/valid/transfer-execute.json)
+for a completed transfer with the authorization decision, the correlation reference, the amount and
+currency, and no account or counterparty detail.