From fc80ee1659d1e1a2bd9661f85a1d3219342adc2b Mon Sep 17 00:00:00 2001
From: Andy Dixon <andy@andydixon.com>
Date: Thu, 26 Feb 2026 13:38:45 +0000
Subject: [PATCH] docs: add provider security model for sdk integrators

Introduces security-model guidance covering provider invariants, expected auth failure modes, and integration-safe handling.
---
 README.md              |  7 ++++---
 docs/SECURITY_MODEL.md | 27 +++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 3 deletions(-)
 create mode 100644 docs/SECURITY_MODEL.md

diff --git a/README.md b/README.md
index 03c1a9b..2e4a1c8 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,7 @@ exit;
 ```
 
 For callback handling, see `docs/INTEGRATION_GUIDE.md`.
+For provider-side threat/invariant assumptions, see `docs/SECURITY_MODEL.md`.
 
 Minimal callback example:
 
@@ -135,12 +136,12 @@ This wrapper now delegates to `BlackWall\Auth\AuthClient`.
 - Expect revoked JWT access tokens to be rejected by provider `userinfo` even before token expiry.
 - Register only HTTPS redirect URIs in provider client settings (HTTP should be used only for localhost loopback during development).
 - Use OAuth/portal authentication endpoints for end users; provider admin login endpoints enforce separate admin scope checks.
-- For provider admin enrollment URL export operations, use `POST` with CSRF protection; do not automate them via unauthenticated `GET` links.
+- For provider admin enrolment URL export operations, use `POST` with CSRF protection; do not automate them via unauthenticated `GET` links.
 - Handle provider CSV exports with formula-injection safety in mind if opening them in spreadsheet applications.
-- Treat generated enrollment URLs as secrets and keep them out of URL query strings and request logs.
+- Treat generated enrolment URLs as secrets and keep them out of URL query strings and request logs.
 - For reverse-proxy deployments, harden trusted proxy/IP forwarding configuration to prevent spoofed client IP headers.
 - Prefer narrowly scoped trusted-proxy entries (explicit IPs/CIDR ranges) instead of broad network trust.
-- Keep client-side admin mutation retries idempotent; approval workflows can be lock-serialized and should not be assumed to execute twice.
+- Keep client-side admin mutation retries idempotent; approval workflows can be lock-serialised and should not be assumed to execute twice.
 - Do not submit parallel approve/reject/cancel decisions for the same approval request ID.
 - Apply bounded CSV import sizes and row counts for admin bulk-user operations.
 - Never place client secrets, refresh tokens, or access tokens in URL query strings.
diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md
new file mode 100644
index 0000000..4b2a961
--- /dev/null
+++ b/docs/SECURITY_MODEL.md
@@ -0,0 +1,27 @@
+# BlackWall Provider Security Model (SDK View)
+
+Last reviewed: 2026-02-26
+
+This document summarises provider-side security guarantees that SDK integrators should design around.
+
+## Threat Assumptions
+
+- Provider is internet-exposed.
+- Attackers can register and attempt tenant-boundary abuse.
+- OAuth/WebAuthn endpoints are abuse targets and may rate limit.
+
+## Invariants Integrators Should Assume
+
+1. Tenant/project/user/client scope is enforced server-side and can change between request steps.
+2. OAuth authorize can fail with `invalid_scope` if requested scopes are not currently allowed for the client.
+3. Token/refresh exchange can fail with `invalid_grant` when subject/client state or scope policy changes.
+4. UserInfo can fail for revoked/invalid/inactive subjects even before nominal token expiry.
+5. Admin and portal workflows are distinct scope domains; do not mix them in client UX flows.
+
+## Integration Guidance
+
+- Keep requested scopes minimal and aligned to the provider client configuration.
+- Treat `access_denied`, `invalid_scope`, and `invalid_grant` as expected security outcomes, not transport errors.
+- Build retries only for transient failures; do not blindly retry authz/authn denials.
+- Keep enrollment URLs/tokens and OAuth tokens out of URLs, logs, and analytics tags.
+- Use strict HTTPS and secure session-cookie handling in the relying party app.