feat(server): add access control

.env.example

@@ -22,9 +22,16 @@ POWERCONTEXT_SERVER_HTTP_PORT=8000
 POWERCONTEXT_SERVER_MCP_ENABLED=true
 POWERCONTEXT_SERVER_MCP_PATH=/mcp
 
-# Authentication is optional on loopback. Load the real token from a secret manager.
-POWERCONTEXT_SERVER_AUTH_ENABLED=false
+# Access Control --------------------------------------------------------------
+# ACCESS_MODE is the only supported Access Control switch.
+POWERCONTEXT_SERVER_ACCESS_MODE=disabled
+# Legacy static Bearer compatibility. An injected Authentication Provider takes precedence.
+# POWERCONTEXT_SERVER_AUTH_ENABLED=true
 # POWERCONTEXT_SERVER_AUTH_TOKEN=replace-me
+POWERCONTEXT_SERVER_ACCESS_DEPLOYMENT_ID=powercontext
+# Multi-user deployments with scheduled jobs must bind an explicit service Principal.
+# POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_ID=service:scheduled-processing
+# POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_DESCRIPTION=Scheduled processing
 
 # Dashboard -------------------------------------------------------------------
 # The Dashboard discovers Scopes from the Server. The Server creates a default Scope on first startup.

.gitignore

@@ -175,6 +175,7 @@ venv.bak/
 .ropeproject
 
 # Generated outputs
+site/
 e2e/bub/results/
 
 # mypy

docker/README.md

@@ -41,8 +41,8 @@ PowerContext refuses to start an unauthenticated Server on a non-loopback addres
 port is reachable, and its network namespace is the controlled boundary that opt-in is meant for, so the image sets
 it by default and the `docker run` above starts without extra configuration. Access is still governed by which ports
 you publish (`--publish`) and the surrounding network. For an exposed deployment, put the Server behind a
-TLS-terminating proxy and enable bearer authentication with
-`POWERCONTEXT_SERVER_AUTH_ENABLED=true` and `POWERCONTEXT_SERVER_AUTH_TOKEN=...`; when authentication is enabled the
+TLS-terminating proxy and enable enforced Access Control with
+`POWERCONTEXT_SERVER_ACCESS_MODE=enforced` and `POWERCONTEXT_SERVER_AUTH_TOKEN=...`; in enforced mode the
 opt-in is no longer required.
 
 The `Build Docker image` GitHub workflow builds downloadable Linux amd64 and arm64 image archives for pull requests,

docs/en/development/remote-access-implementation.md

@@ -25,7 +25,7 @@ is otherwise controlled.
 
 ```bash
 # Recommended: authenticate the Server, then bind a routable address (put TLS in front in production).
-POWERCONTEXT_SERVER_AUTH_ENABLED=true \
+POWERCONTEXT_SERVER_ACCESS_MODE=enforced \
 POWERCONTEXT_SERVER_AUTH_TOKEN="replace-with-a-strong-token" \
   uv run powercontext server run --host 0.0.0.0 --port 8080
 ```

docs/en/docs/how-to/configure-claude-code.md

@@ -136,7 +136,7 @@ client remains managed by Claude Code.
 Start the Server with its token loaded from your secret manager:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/configure-codex.md

@@ -88,7 +88,7 @@ This adds inference latency to each prompt and is not the normal interactive set
 Load one token from your local secret manager, then start the Server with authentication enabled:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/configure-dsh.md

@@ -56,7 +56,7 @@ This adds inference latency to each prompt and is not the normal interactive set
 ## Connect to an authenticated local Server
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/configure-openclaw.md

@@ -77,7 +77,7 @@ selection contract.
 Start an authenticated Server from a protected environment:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/configure-pi.md

@@ -81,7 +81,7 @@ write rather than persisting it silently. `/pc doctor`, `/pc search <query>`, `/
 Start an authenticated Server from a protected environment:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/configure-workbuddy.md

@@ -244,7 +244,7 @@ Load one token from your local secret manager, then start the Server with
 authentication enabled:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
 powercontext server run
 ```

docs/en/docs/how-to/deploy-server.md

@@ -117,7 +117,7 @@ named volume persists the SQLite database and scheduler state after the containe
 Load a strong token from your secret manager into the Server process environment:
 
 ```bash
-export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
 export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_DEPLOYMENT_TOKEN"
 powercontext server run
 ```
@@ -129,7 +129,7 @@ docker run --rm \
   --name powercontext-server \
   --publish 127.0.0.1:8000:8000 \
   --volume powercontext-data:/data \
-  --env POWERCONTEXT_SERVER_AUTH_ENABLED=true \
+  --env POWERCONTEXT_SERVER_ACCESS_MODE=enforced \
   --env POWERCONTEXT_SERVER_AUTH_TOKEN \
   powercontext-server:local
 ```

docs/en/docs/reference/configuration.md

@@ -46,8 +46,12 @@ Server settings use the `POWERCONTEXT_SERVER_` prefix.
 | `POWERCONTEXT_SERVER_WORKSPACE` | Server startup directory | Resolution root for local project Agent Skill folders |
 | `POWERCONTEXT_SERVER_MCP_ENABLED` | `true` | Enable Streamable HTTP MCP |
 | `POWERCONTEXT_SERVER_MCP_PATH` | `/mcp` | MCP path |
-| `POWERCONTEXT_SERVER_AUTH_ENABLED` | `false` | Require one static bearer token for HTTP and MCP |
-| `POWERCONTEXT_SERVER_AUTH_TOKEN` | unset | Static bearer token; required when authentication is enabled |
+| `POWERCONTEXT_SERVER_AUTH_ENABLED` | `false` | Legacy static bearer switch; `true` maps to `ACCESS_MODE=enforced` and requires `AUTH_TOKEN` |
+| `POWERCONTEXT_SERVER_AUTH_TOKEN` | unset | Legacy static bearer token; used as compatibility authentication and mapped to the built-in administrator when no Authentication Provider is injected |
+| `POWERCONTEXT_SERVER_ACCESS_MODE` | `disabled` | The only supported Access switch: `disabled` or `enforced` |
+| `POWERCONTEXT_SERVER_ACCESS_DEPLOYMENT_ID` | `powercontext` | Stable deployment identity used by the `server` Access Resource |
+| `POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_ID` | unset | Explicit service Principal for scheduled jobs in a multi-user enforced deployment |
+| `POWERCONTEXT_SERVER_ACCESS_BACKGROUND_PRINCIPAL_DESCRIPTION` | unset | Optional display-only description for the scheduled service Principal |
 | `POWERCONTEXT_SERVER_PUBLIC_URL` | unset | Remotely reachable base URL used by remote Skill enrollment guidance; HTTPS is required by default |
 | `POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP` | `false` | Explicitly allow cleartext HTTP for remote Skill Receiver endpoints and guidance |
 | `POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK` | `false` | Opt in to a non-loopback bind while authentication is disabled |
@@ -98,14 +102,56 @@ key. Configure the same `POWERCONTEXT_SERVER_CURSOR_SIGNING_SECRET` on every rep
 restart or when the next request reaches another replica. Never expose or rotate this value while issued cursors
 must remain valid.
 
-Static bearer authentication is disabled by default. When enabled, API and MCP requests must include
-`Authorization: Bearer <token>`; the liveness and readiness endpoints remain public. Plain HTTP is trusted only on a
+Access Control is disabled by default. In `enforced` mode, API and MCP requests must establish a Principal through the
+selected Authentication Provider; the liveness and readiness endpoints remain public. The built-in `static-bearer`
+Provider accepts `Authorization: Bearer <token>`. Plain HTTP is trusted only on a
 loopback address (`localhost`, `::1`, or any address in `127.0.0.0/8`). The Server refuses to start when it binds to a
 non-loopback address while authentication is disabled; either enable authentication, keep the bind on loopback, or,
 when TLS is terminated upstream or the network is otherwise controlled, set
 `POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true` to opt in explicitly. Use TLS before exposing an
 authenticated Server over a network.
 
+`POWERCONTEXT_SERVER_ACCESS_MODE` is the only supported switch. `disabled` bypasses authorization decisions inside the
+trusted local boundary. `enforced` enables one policy enforcement point plus Binding and audit behavior. Authorization
+defaults to the built-in implementation and can be replaced through `create_server_app(access_control=...)`;
+Authentication is supplied through `create_server_app(authentication_provider=...)`. Without an injected Authentication
+Provider, the Server accepts only the legacy `AUTH_TOKEN` fallback and bootstraps its fixed `server-token` Principal as a
+built-in administrator. Startup fails when neither is available. The old `AUTH_ENABLED=true` plus `AUTH_TOKEN`
+configuration maps automatically to `ACCESS_MODE=enforced`.
+
+Authentication establishes a Principal; Access Control decides what that Principal may do. Principal IDs are
+deployment-wide unique, non-reused identifiers; `description` is display metadata and is not part of identity. The
+built-in static token always represents one service Principal, so it cannot distinguish user A from user B. The
+compatibility token materializes explicit Server and per-scope roles for that Principal. Inject the deployment
+Authentication Provider and corresponding AccessControlService when different users or groups need different access.
+
+Scheduled Source processing and Experience incubation run as the fixed static Principal, or as the service Principal
+selected by `ACCESS_BACKGROUND_PRINCIPAL_ID`. That Principal must have `scope.contribute` for each processed scope;
+new Memory entries and Candidates retain it as their direct proposed owner. An enforced multi-user deployment that
+configures a schedule without this explicit Principal fails at startup.
+
+Remote, multi-user, and shared-Dashboard deployments must use `enforced`. In that mode, HTTP, MCP, Dashboard data
+routes, and metrics share one Server PEP. Configured Dashboard scopes are filtered by the current Principal's
+`scope.read` decision before they are returned. `/v1/access/me` reports the `server`/`scope`/`artifact` Resource Kinds,
+Provider batch/list/relationship capabilities and Artifact Family profiles. Managed Skill export and installation do
+not introduce separate Access actions: the recipient first needs `artifact.read` on the logical Skill identity, then
+chooses whether and how to install an exact Revision.
+
+The built-in Access schema uses the configured SQLite, seekDB, or OceanBase backend, but remains Server-owned rather
+than becoming a Runtime domain. A custom deployment can inject an `AccessControlService` into `create_server_app`.
+`CasbinAuthorizationProvider` is the included writable external adapter: it evaluates the fixed action vocabulary in
+embedded Casbin while using the canonical Binding Store as its persistent adapter, so it supports point/batch checks,
+safe resource filters, create/revoke, expiry, and CAS without a second policy shadow. Pass that provider as both the
+decision provider and `relationships`, and retain the relational repository as the audit store.
+
+`AuthZenAuthorizationProvider` is an included decision-only adapter for the OpenID AuthZEN Authorization API 1.0
+`evaluation` and `evaluations` endpoints. Configure its capabilities with `multi_requirement_check=true`,
+`relationship_management=false`, and `safe_resource_filtering=false`; self-service Binding mutation and authorized
+resource listing then return 503 instead of claiming an unsafe capability. The adapter accepts HTTPS endpoints or
+loopback HTTP, rejects credentials embedded in URLs, and does not expose PDP response bodies or errors. An
+authentication middleware must still bind an opaque `PrincipalRef`; `scope_id` is only a resource partition and never
+establishes identity.
+
 The Python Client and CLI apply the matching rule for general outbound requests: a configured unencrypted `http://`
 Server URL is accepted only for loopback hosts. The explicit remote Skill Receiver PoC exception is documented below.
 Code whose `http://` base URL is only a routing label for a transport that is secure in practice, such as an in-process
@@ -155,7 +201,7 @@ The non-loopback opt-in in this example is independent of the Receiver transport
 Server routes on this listener are reachable without the Server-wide bearer token. Prefer enabling authentication or
 terminating TLS in front of a loopback-bound Server whenever the deployment permits it.
 
-When bearer authentication is enabled, the HTML shells at `/`, `/skills`, `/reviews`, and `/handoff-reports`, plus
+When compatibility static Bearer authentication is enforced, the HTML shells at `/`, `/skills`, `/reviews`, and `/handoff-reports`, plus
 their static assets, remain public so the browser can render the sign-in form. Data requests stay protected. Enter the
 Server token in that form; the browser keeps it only in the current tab's session storage. Disable both Dashboard and
 Handoff Report if even these sign-in pages must not be exposed.

docs/en/docs/reference/http-api.md

@@ -92,16 +92,79 @@ curl --fail \
   "$POWERCONTEXT_URL/v1/memory/search"
 ```
 
+## Grant one logical Handoff to a receiver
+
+`scope_id` never grants access by itself. The Handoff owner or an authorized delegator assigns one logical committed Handoff by creating a
+Binding for the receiver's authenticated Principal:
+
+```bash
+curl --fail \
+  --request POST \
+  --header 'Content-Type: application/json' \
+  --header "$POWERCONTEXT_AUTH_HEADER" \
+  --data '{
+    "subject": {"type": "user", "id": "idp:user-b", "description": "User B"},
+    "resource": {
+      "type": "artifact",
+      "scope_id": "project:example",
+      "identity": {"family": "handoff", "artifact_id": "handoff-42"},
+      "selector": null
+    },
+    "role": "handoff.receiver",
+    "idempotency_key": "handoff-42-to-user-b"
+  }' \
+  "$POWERCONTEXT_URL/v1/access/bindings/create"
+```
+
+The receiver can read and acknowledge the Handoff's history, current Revision, and future Revisions. Continue exposes
+the citations in the selected Revision's immutable manifest and checks those cited resources without requiring a
+second Binding for each citation. This manifest-scoped inspection does not authorize generic Source, Memory, or
+Artifact endpoints: the receiver still cannot discover another Handoff or read the parent scope unless a separate
+scope or Artifact role allows it. It may request `latest` only for the bound logical Handoff. Use `/v1/access/me` to
+verify which Principal the deployment established, `/v1/access/check` for one compound `all` or `any` requirement, and
+`/v1/access/resources/list` for a non-discovering list of already visible resources. Creation is idempotent per
+grantor and key; revocation uses `binding_id` plus `expected_version`. An atomic `/v1/access/bindings/replace`
+revokes one immutable Binding and creates its successor with the same Resource and role. Role descriptors expose
+whether they allow `many_per_resource` or `one_per_resource` active Bindings. Relationship and decision events are
+available to Server administrators through `/v1/access/audit/list`. When authentication establishes delegated execution,
+each audit event keeps the effective `principal` and the trusted `actor` as separate opaque identities.
+
+The Access wire contract has only three Resource Kinds: `server`, `scope`, and `artifact`. An Artifact Resource uses
+the logical identity `{family, artifact_id}` and deliberately contains no Revision. Memory can narrow a grant with a
+`memory_entry` selector containing only `entry_id`. Unknown Families, `prompt` when no Prompt lifecycle is implemented,
+and mismatched selectors or roles never create a Binding. `/v1/access/me` reports the current mode, Provider
+capabilities, and each Artifact Family's enabled state.
+
+Cross-Scope Artifact publication uses `POST /v1/artifact-publications`. The request selects an exact source Revision,
+but authorization checks `artifact.share` on its logical `{family, artifact_id}` identity and `scope.admin` on the
+target Scope. Consequently, one logical sharing grant covers earlier and later source Revisions while every
+publication still records the exact copied Revision and its provenance. Host-local Dashboard projection remains an
+operational surface protected by the corresponding Scope and Artifact checks.
+
+The standard Skill lifecycle uses the same Access boundary. Library listing requires `scope.read`; lifecycle changes
+require `artifact.write`; package manifest/download requires `artifact.read`; package proposals require
+`scope.contribute` and, when replacing an existing Skill, `artifact.write`; usage capture requires both
+`scope.contribute` and `artifact.read`. Remote target administration requires `scope.admin`, while publishing an exact
+Revision also requires `artifact.read` for that Skill. The enrollment endpoint is protected by its one-time code, and
+Receiver reconcile/download/receipt endpoints use the separately issued `TargetBearerAuth` credential instead of a
+user Principal. Dashboard data routes apply the corresponding Access checks before scope lookup, package inspection,
+target lookup, or filesystem work.
+
+The built-in static token represents one local administrator and cannot model different A/B users. A real multi-user
+deployment must authenticate each caller to a different Principal and inject an Authorization Provider. HTTP and MCP
+use the same policy enforcement point; MCP tool visibility is not permission.
+
 ## Find an operation
 
 | Area | Main paths | Purpose |
 | --- | --- | --- |
 | Health and capabilities | `/health/*`, `/v1/capabilities` | Probe the deployment and discover enabled runtime behavior |
+| Access Control | `/v1/access/*` | Inspect identity, check decisions, and administer roles, Bindings, and audit events |
 | Source and context | `/v1/sources/content`, `/v1/context/prepare` | Capture evidence and prepare bounded context |
 | Work continuity | `/v1/work/*` | Create work contracts, prepare or acknowledge Handoffs, and record outcomes |
 | Low-level Handoff | `/v1/handoff/*` | Activate, prepare, finalize, commit, or continue a Handoff |
 | Memory | `/v1/memory/*` | Flush, remember, search, list, get, revise, retire, and inspect changes |
-| Experience and Skill | `/v1/experience/*`, `/v1/skill/*` | Propose, generate, and read Artifact revisions |
+| Experience and Skill | `/v1/experience/*`, `/v1/skill/*`, `/v1/skills/*` | Propose, review, package, govern, distribute, and read managed Skill revisions |
 | Review | `/v1/artifact-candidates/*` | List, inspect, revise, approve, or reject pending Candidates |
 | External Skills | `/v1/external-skills/*` | Scan configured targets and resolve or import packages |
 | Handoff Reports | `/v1/handoff-reports/*` | Generate a read-only report for a Scope selection |
@@ -129,6 +192,7 @@ Common statuses are:
 | Status | Meaning |
 | --- | --- |
 | `401` | The Server requires a valid bearer token |
+| `403` | The authenticated Principal is not authorized for the requested action and resource |
 | `404` | The requested immutable value does not exist |
 | `409` | The request conflicts with current immutable state or an expected version |
 | `413` | A selected Handoff Report exceeds its output limit |