Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

docs/02-security/IDENTITY_AND_AUTHORIZATION.md

@@ -0,0 +1,55 @@
+# Identity and Authorization
+
+## Human management users
+
+Use Authentik OIDC authorization code flow with PKCE and a same-origin BFF session. Browser JavaScript receives only user/session metadata and CSRF protection, never reusable access or refresh tokens.
+
+## Machine clients
+
+Each MCP client has its own principal and credential. Preferred flow is client credentials or an Authentik service-account equivalent with audience restricted to the MCP Hub.
+
+Examples:
+
+```text
+svc-mcp-codex-workstation
+svc-mcp-claude-workstation
+svc-mcp-ludarium-prod
+svc-mcp-inspector
+```
+
+Never reuse one broad token across projects.
+
+After machine authentication and database-backed binding authorization, the
+dataplane replaces all caller-supplied identity headers and signs the exact
+project, environment, client, trace, and timestamp tuple. ContextForge forwards
+that assertion without receiving the signing key. Every connector verifies the
+HMAC and the 60-second age bound before repeating its own project, environment,
+and resource-registration checks. Missing, expired, or modified assertions deny.
+
+## Effective authorization inputs
+
+- trusted issuer and audience;
+- principal subject;
+- client identity;
+- workspace;
+- project;
+- environment;
+- endpoint/virtual server;
+- capability or tool;
+- risk class;
+- enabled status and revocation time;
+- matching policies and role bindings.
+
+## Decision semantics
+
+- explicit global deny wins;
+- disabled entities deny;
+- missing project/environment binding denies;
+- missing capability binding denies;
+- any matched deny wins over allows;
+- allow decisions include a trace explaining matched rules;
+- clients never select their own project through an untrusted body field when the endpoint already scopes it.
+
+## Revocation
+
+Client disable or binding removal must affect new requests immediately or within a documented cache ceiling of at most 60 seconds. Cache invalidation is event-driven where possible and always bounded.