:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
docs(security): describe per-surface access rule enforcement (#121097)
Yasen4a0e35a78509
diff --git a/products/security/README.md b/products/security/README.mdindex 67abd933c094..351d2ee5fff2 100644--- a/products/security/README.md+++ b/products/security/README.md@@ -11,7 +11,25 @@ This product pulls them, decides them in-process, and answers the hub's questionWhen the hub is down, the last snapshot stays in force. When nothing is loaded, nobody is blocked and the login email code stays required.- `facade.api.decide(subject, surface)` returns allow, block or exempt with the deciding rule.A posthog.com account is never blocked.-- Phase 1 enforces only `email_code` exemptions. Signup, login, sessions and the AI gateway call `shadow_check`, which logs `security_access_would_block` and counts `posthog_security_access_would_block_total`, and blocks nobody.+ A rule's scope picks the surfaces it decides. `all_access` covers `signup`, `app` and `ai_gateway`.+- The `security-access-enforcement` flag in PostHog's own project turns refusals on per surface.+ Its JSON payload maps each surface to a value, for example `{"signup": true, "app": false, "ai_gateway": false}`.+ A surface refuses requests only when its value is a literal `true`.+ Any other value, a missing payload or an unreadable flag leaves that surface logging only.+ Turning the flag off stops every refusal at once.+- Signup, login, sessions and the AI gateway call `facade.api.access_refused`.+ On an enforced surface, a block refuses the request, logs `security_access_refused` and counts `posthog_security_access_refusals_total`.+ Signup and app callers answer with the error code `access_blocked`.+ AI gateway callers answer in their own shape: OAuth authorization returns `access_denied`, the desktop token endpoint returns `reason: "blocked"`, and the wizard endpoints return a 403 with the AI gateway block message.+ On any other surface, a block logs `security_access_would_block`, counts `posthog_security_access_would_block_total` and refuses nobody.+ On the app surface, staff who impersonate a blocked account get through, and the match counts as a would-block.+ `posthog_security_access_decisions_total` counts every decision, so an empty would-block series still shows that the checks ran.+- Exemptions do not depend on the flag.+ `is_email_code_exempt` lets an account skip the emailed login code.+ `is_signup_risk_exempt` lets a signup skip the WorkOS Radar verdict.+- Every check fails open.+ A decision that raises refuses nobody, keeps the email code and the Radar verdict, and counts `posthog_security_access_decision_errors_total`.+- The AI gateway credential sweep (`posthog/tasks/wizard_blocklist.py`) revokes credentials for a block rule only while `ai_gateway` is enforced.- To drop the emailed login code for every account during an email outage, add an `everyone` rule with scope `email_code` at the hub.Give it an expiry. The Redis switch it replaces capped itself at 7 days; a rule without `expiresAt` stays in force until somebody revokes it.It applies on the next pull plus the memo window, so allow about 6 minutes.