OpenFreyt Protocol — Threat Model

Generated from security/threat-model.md. Edit the canonical source file, not this page.

Status: Normative
Version: 1.0.0-draft
Locked by: M001-S01-T03
Last reviewed: 2026-08-31

1. Scope

This threat model covers the attack surface of the OpenFreyt Protocol (PCX) specification and any conformant broker implementation. It does not cover infrastructure-level concerns (OS hardening, network topology, key management HSMs) except where the protocol makes normative statements about them.

In-scope components:

PCX REST/JSON API surface (all 9 authorization scopes)
Token validation and audience binding
Resource lifecycle state machines
Webhook delivery infrastructure
Audit log subsystem
Organization / isolation boundaries

Out-of-scope:

Physical datacenter security
TLS certificate lifecycle (assumed: TLS 1.3 minimum, valid certs)
Internal broker-to-broker transport (not yet specified)

2. Assets

Asset ID	Asset	Confidentiality	Integrity	Availability
A-01	PartnerRelationship records	HIGH	CRITICAL	HIGH
A-02	CapacityOffer payload (price, volume, route)	HIGH	HIGH	HIGH
A-03	LoadRequest payload (cargo details, shipper identity)	HIGH	HIGH	HIGH
A-04	MatchProposal (counterparty identity revealed post-match)	CRITICAL	CRITICAL	HIGH
A-05	MatchDecision and commitment records	CRITICAL	CRITICAL	HIGH
A-06	OutcomeReport and compliance data	HIGH	CRITICAL	MEDIUM
A-07	Organization identity and legalIdentifier fields	HIGH	HIGH	HIGH
A-08	JWT access tokens and scopes	CRITICAL	CRITICAL	HIGH
A-09	Audit trail / event log	MEDIUM	CRITICAL	HIGH
A-10	Webhook endpoint URLs	MEDIUM	HIGH	MEDIUM

3. Trust Boundaries

[External Client] --- TLS/JWT ---> [API Gateway]
                                        |
                              [Scope + Org Validation]
                                        |
                            [Protocol Domain Services]
                            /          |           \
                   [Capacity]     [Matching]    [Outcomes]
                                        |
                                  [Audit Log]
                                        |
                                  [Webhook Fan-out]
                                        |
                              [External Org Webhooks] (untrusted)

Trust is never inherited across organization boundaries. A token issued for OrganizationService:A grants no authority over resources owned by OrganizationService:B, regardless of PartnerRelationship status.

4. OWASP API Security Top 10 (2023) Mapping

API1 — Broken Object Level Authorization

Affected components: All resource endpoints (CapacityOffer, LoadRequest, MatchProposal, MatchDecision, OutcomeReport, PartnerRelationship, Organization).

Attack description: Attacker increments or guesses resource IDs (UUIDs) to access objects belonging to another organization.

Protocol controls:

All resource IDs are UUIDv7 (128-bit, random node component) — guessing probability is negligible for individual requests, but sequential scanning must be mitigated at the API layer.
Every resource lookup enforces ownerOrganizationId match against the token’s org_id claim before returning any data.
Non-owning requesters MUST receive 404 Not Found (never 403) per R-001 and the authorization-matrix 404-vs-403 rule.

Residual risk: LOW — UUIDv7 provides ~122 bits of effective entropy; 404-not-403 prevents existence confirmation.

Acceptance status: ACCEPTED — mitigated by design.

API2 — Broken Authentication

Affected components: API Gateway, token validation, webhook delivery.

Attack description: Attacker presents expired, tampered, or wrong-audience tokens. Webhook replay of valid delivery payloads without signature.

Protocol controls:

Tokens MUST carry a specific aud claim matching the broker’s service identifier; generic bearer tokens are rejected.
Token expiry (exp) and issuance time (iat) MUST be validated with a max clock skew of 30 s.
Webhook payloads MUST be signed (HMAC-SHA256 or asymmetric) with a shared secret negotiated during PartnerRelationship establishment; replayed payloads rejected via nonce or timestamp window (≤ 300 s).

Residual risk: LOW — audience binding and webhook signing are normative requirements.

Acceptance status: ACCEPTED.

API3 — Broken Object Property Level Authorization

Affected components: MatchProposal, CapacityOffer, LoadRequest field disclosure.

Attack description: Attacker reads pre-match fields (counterparty ownerOrganizationId, contact details, rate breakdowns) that should be hidden until a MatchDecision is committed.

Protocol controls:

Field-level disclosure rules documented in authorization-matrix.md §5 (R-005).
Pre-match: ownerOrganizationId of the counterparty is suppressed; unlocked only by matches:read scope combined with an active MatchDecision in ACCEPTED state.
Serialization layer MUST strip suppressed fields before sending; reliance on client-side filtering is prohibited.

Residual risk: LOW — server-side field stripping is required by spec; tested in conformance suite.

Acceptance status: ACCEPTED.

API4 — Unrestricted Resource Consumption

Affected components: All write endpoints, webhook fan-out, relationship management.

Attack description: Attacker floods the broker with CapacityOffers, LoadRequests, or PartnerRelationship invites to exhaust storage or processing capacity.

Protocol controls:

Broker implementations MUST enforce per-organization rate limits on all write scopes.
Pagination is mandatory on all list endpoints (max page size 100).
Webhook fan-out MUST be asynchronous with bounded retry budgets (max 5 attempts, exponential back-off with jitter, circuit breaker at 50% failure rate over a 5-minute window).
Oversized payloads MUST be rejected at the API boundary: max body size 256 KiB for standard resources, 64 KiB for PartnerRelationship payloads.

Residual risk: MEDIUM — rate-limit parameters are implementation-specific; the protocol specifies minimum requirements only. Implementors must tune thresholds.

Acceptance status: ACCEPTED with implementation guidance.

API5 — Broken Function Level Authorization

Affected components: Decision policy enforcement (BILATERAL_REQUIRED, INITIATOR_ONLY, ACCEPTOR_ONLY), scope checks on state-transition endpoints.

Attack description: Attacker invokes ACCEPT or COMMIT on a MatchDecision they are not authorized to finalize, or bypasses BILATERAL_REQUIRED by making two calls from the same organization in sequence.

Protocol controls:

Each MatchDecision records initiatorOrganizationId and acceptorOrganizationId from the PartnerRelationship at creation time; these are immutable.
Decision policy is evaluated against these stored IDs, not token identity at decision time.
BILATERAL_REQUIRED: both organizations must submit separate ACCEPT actions; a second ACCEPT from the initiator is a no-op (idempotent) and does not advance state.
State-transition endpoints check both the matches:decide scope and the decision-policy role before executing any state change.

Residual risk: LOW.

Acceptance status: ACCEPTED.

API6 — Unrestricted Access to Sensitive Business Flows

Affected components: MatchDecision COMMIT flow, OutcomeReport submission.

Attack description: Attacker exploits automated account creation or bulk match commitment to manipulate freight market prices or commit counterparties to spurious loads.

Protocol controls:

PartnerRelationship activation requires explicit bilateral relationships:manage scope actions — no auto-accept.
MatchDecision COMMIT is gated on BILATERAL_REQUIRED by default; INITIATOR_ONLY and ACCEPTOR_ONLY require explicit configuration in the PartnerRelationship.
OutcomeReport requires outcomes:write scope, which MUST NOT be granted to automated ingestion accounts without a compliance review (outcomes:review scope audit path).

Residual risk: LOW.

Acceptance status: ACCEPTED.

API7 — Server Side Request Forgery

Affected components: Webhook endpoint registration and delivery.

Attack description: Attacker registers a webhook URL pointing to an internal service (169.254.x.x, 10.x.x.x, 127.x.x.x, metadata endpoints) to exfiltrate internal tokens or trigger internal actions.

Protocol controls:

Webhook URL validation MUST reject RFC 1918 addresses, loopback addresses, link-local addresses, and cloud metadata endpoints (169.254.169.254, fd00:ec2::254) at registration time.
URL scheme MUST be https:// (no http://, file://, ftp://, etc.).
DNS resolution at delivery time MUST be re-validated; a URL that resolves to a forbidden range at delivery time causes immediate disablement of the webhook endpoint.
Redirect following is PROHIBITED during webhook delivery; HTTP 3xx responses cause delivery failure.

Residual risk: MEDIUM — DNS rebinding attacks remain possible in environments with short TTLs. Mitigated by time-bounded re-validation on each delivery attempt.

Acceptance status: ACCEPTED with time-bounded DNS re-validation requirement.

API8 — Security Misconfiguration

Affected components: API Gateway, CORS headers, error response bodies.

Attack description: Verbose error messages reveal internal stack traces, SQL errors, or resource existence. Overly permissive CORS allows cross-origin token exfiltration.

Protocol controls:

Error responses MUST use the standard PCX error envelope {code, message, requestId} and MUST NOT include stack traces, internal identifiers, or query plans.
CORS policy: Access-Control-Allow-Origin MUST NOT be * for authenticated endpoints.
Security headers MUST include: Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY.

Residual risk: LOW.

Acceptance status: ACCEPTED.

API9 — Improper Inventory Management

Affected components: Deprecated API versions, shadow endpoints.

Attack description: Attacker discovers and uses deprecated v0 or staging endpoints that lack current authorization controls.

Protocol controls:

The PCX specification versioning scheme (X-PCX-Version header) requires brokers to declare supported versions; deprecated versions MUST return 410 Gone after a published sunset date.
Specification changelog MUST record all removed fields and endpoints with their sunset dates.

Residual risk: LOW.

Acceptance status: ACCEPTED.

API10 — Unsafe Consumption of APIs

Affected components: Broker-to-broker federation (future), third-party identity providers.

Attack description: A PCX broker blindly trusts data received from a partner broker or identity provider, leading to injection or privilege escalation.

Protocol controls:

All inbound data (including counterparty-supplied fields) MUST be validated against PCX schemas before processing.
externalReferences array items MUST be treated as opaque strings; brokers MUST NOT follow external URLs embedded in these fields.
Identity provider claims MUST be validated against a pinned JWKS endpoint; dynamic JWKS discovery is PROHIBITED without explicit configuration.

Residual risk: LOW.

Acceptance status: ACCEPTED.

5. Additional Threat Categories (security/README.md §12)

T-01 — Organization and Object-Level Isolation

ID: T-01
Category: Object-level authorization
Affected component: All resource endpoints
Attack description: Cross-organization data leakage via missing ownerOrganizationId filter on list queries.
Protocol control: Every list endpoint MUST filter by the token’s org_id; missing filter is a CRITICAL conformance failure.
Residual risk: LOW
Acceptance status: ACCEPTED

T-02 — Field-Level Disclosure

ID: T-02
Category: Property-level authorization
Affected component: MatchProposal, CapacityOffer, LoadRequest
Attack description: Pre-match counterparty fields leaked via overly broad serialization.
Protocol control: Server-side field stripping enforced per authorization-matrix.md §5.
Residual risk: LOW
Acceptance status: ACCEPTED

T-03 — Token Audience and Scope Validation

ID: T-03
Category: Broken authentication
Affected component: API Gateway, token middleware
Attack description: Token issued for service A accepted by service B; token with broad scope accepted for narrow-scope endpoint.
Protocol control: Strict aud claim matching; per-endpoint minimum scope check before handler dispatch.
Residual risk: LOW
Acceptance status: ACCEPTED

T-04 — Replay Resistance

ID: T-04
Category: Replay attack
Affected component: MatchDecision state transitions, webhook delivery
Attack description: Replayed ACCEPT or COMMIT request re-triggers a state transition already executed; replayed webhook payload duplicates business event processing.
Protocol control: MatchDecision state machine is idempotent on transitions from a given state; idempotency keys REQUIRED on all mutating requests; webhook nonce / timestamp window.
Residual risk: LOW
Acceptance status: ACCEPTED

T-05 — Webhook Authentication

ID: T-05
Category: SSRF / integrity
Affected component: Webhook fan-out
Attack description: Broker delivers to an unauthenticated URL; attacker intercepts delivery or forges events.
Protocol control: HMAC-SHA256 signing of webhook body (see API7 controls); HTTPS-only URLs.
Residual risk: LOW
Acceptance status: ACCEPTED

T-06 — Resource Enumeration Resistance

ID: T-06
Category: Information disclosure
Affected component: All resource GET endpoints
Attack description: 403 response reveals resource existence to unauthorized caller.
Protocol control: 404-not-403 rule per R-001; UUIDv7 IDs.
Residual risk: LOW
Acceptance status: ACCEPTED

T-07 — Injection and Hostile References

ID: T-07
Category: Injection
Affected component: All write endpoints, externalReferences array
Attack description: Attacker submits SQL injection, XSS payloads, or hostile URLs in free-text or reference fields.
Protocol control: Schema validation on all inputs; externalReferences treated as opaque strings, never followed; output encoding in error messages.
Residual risk: LOW
Acceptance status: ACCEPTED

T-08 — Oversized Payload Handling

ID: T-08
Category: DoS
Affected component: All write endpoints
Attack description: Attacker sends a multi-megabyte JSON body to exhaust parser memory.
Protocol control: Max body size 256 KiB enforced at API boundary (64 KiB for PartnerRelationship). Requests exceeding limit receive 413 Payload Too Large.
Residual risk: LOW
Acceptance status: ACCEPTED

T-09 — Sensitive Log Redaction

ID: T-09
Category: Data leakage via logs
Affected component: Audit log, application logs
Attack description: Bearer tokens, legalIdentifier values, contact details written to plaintext logs and accessible to log aggregation operators.
Protocol control: Audit log schema specifies which fields are loggable; token values MUST be replaced with [REDACTED]; legalIdentifier.value MUST be hashed (SHA-256 truncated to 12 chars) in application logs.
Residual risk: LOW
Acceptance status: ACCEPTED

T-10 — Retention and Deletion

ID: T-10
Category: Data lifecycle
Affected component: All resources, audit log
Attack description: Organization requests deletion of its data but records persist indefinitely due to missing cascade logic.
Protocol control: PCX specifies a DELETED lifecycle state; once a resource reaches DELETED, it MUST be excluded from all list results and individual GETs return 404. Physical deletion is implementation-specific but MUST be achievable within the agreed retention window.
Residual risk: MEDIUM — physical deletion scheduling is implementation-specific. Normative requirement is logical deletion + listing exclusion.
Acceptance status: ACCEPTED with implementation guidance.

T-11 — Software Supply Chain

ID: T-11
Category: Supply chain
Affected component: Reference implementation build pipeline
Attack description: Compromised npm/pip/cargo dependency introduces malicious code.
Protocol control: Lock files committed for all package managers; SBOM generated at build time; dependency scan in CI (npm audit / dependabot); no latest version ranges.
Residual risk: MEDIUM — supply chain attacks are difficult to fully mitigate at the protocol specification level; mitigated by CI scanning.
Acceptance status: ACCEPTED with CI gate requirement.

T-12 — Double-Commitment Race

ID: T-12
Category: Race condition / data integrity
Affected component: MatchDecision COMMIT endpoint
Attack description: Two concurrent COMMIT requests from different org members arrive simultaneously; both succeed due to missing serialization, creating two committed records.
Protocol control: COMMIT MUST be implemented using a compare-and-swap or serializable transaction on resourceVersion; optimistic lock failure returns 409 Conflict with the current resourceVersion.
Residual risk: LOW
Acceptance status: ACCEPTED

6. Risk Summary

Level	Count	All mitigated?
CRITICAL	0	—
HIGH	0	—
MEDIUM	4	Yes — all have time-bounded acceptance rationale
LOW	18	Yes

No unresolved CRITICAL or HIGH findings. All MEDIUM findings are accepted with concrete implementation requirements documented above. The four MEDIUM residual risks are:

T-04 / API4 — Rate-limit parameter tuning is implementation-specific; minimum requirements specified. Reviewed at: M002 broker reference implementation milestone.
T-07 / API7 — DNS rebinding residual; time-bounded re-validation required on each webhook delivery attempt. Reviewed at: M002 webhook delivery implementation.
T-10 — Physical deletion scheduling is implementation-specific. Reviewed at: M003 data lifecycle milestone.
T-11 — Supply chain scan is a CI gate; cannot be fully eliminated at spec level. Reviewed at: each milestone that changes dependencies.