Change Who Can Reach Your KDCube App Without Rebuilding

10OPSeparate Existence From Policy

Keep five questions independent. One private switch cannot express all of them.

enabled is availability. visibility is audience policy. auth is authority policy. csrf is request proof, not another role or grant.

20OPDeclare Portable API Defaults

Put the operation and its safe defaults on @api(...).

from typing import Any
from kdcube_ai_app.infra.plugin.bundle_loader import api

@api(
    method="POST",
    alias="report_publish",
    route="operations",
    user_types=("registered",),
    roles=("kdcube:role:editor",),
    csrf=True,
)
async def report_publish(self, **payload: Any) -> dict[str, Any]:
    return await self.reports.publish(payload)

Both visibility dimensions apply when both are present. user_types use anonymous < registered < paid < privileged. roles compare raw role ids.

csrf=True is valid only for POST on operations. Public webhooks use provider proof or another configured guard.

30OPOverride The Exact API Method

Write only the deployment difference under the concrete route, alias, and method.

bundles:
  items:
    - id: reporting@1-0
      config:
        surfaces:
          as_provider:
            api:
              operations:
                report_publish:
                  POST:
                    visibility:
                      user_types: [registered]
                      roles: [kdcube:role:publisher]
                    auth:
                      authority_id: platform
                      grants: [reports:publish]
                    csrf: true

Resolution: method policy wins over alias fallback; alias fallback wins over the decorator default.

A missing value keeps the code default. An explicit empty visibility list removes that restriction for this deployment. Keep descriptors sparse so they do not pin every old code default.

40OPSwitch One Resource Off

enabled:
  bundle: true
  api:
    "operations.report_publish.POST": false
  mcp:
    reports: true
  widget:
    reporting: true

Missing values mean enabled. This is an override layer, not a second inventory of app resources.

50OPUse The Apps View

Open Apps, select the app, then select the concrete API, MCP endpoint, or widget. The editor writes the same descriptor-backed paths.

For an API POST on operations, Cookie request CSRF shows the effective value, decorator default, exact descriptor path, and explicit-override state. Save writes the method override. Reset writes a null marker there and restores the decorator default for that method.

The MCP editor has no CSRF switch. MCP uses explicit protocol credentials and its own auth contract, not ambient browser cookies.

60OPTeach The Browser The CSRF Exchange

When the effective API policy has csrf: true, a cookie-authenticated browser obtains one token before the mutation.

GET  .../operations/report_publish/csrf
  -> {csrf_required: true, csrf_token: "...", expires_in: 600}

POST .../operations/report_publish
X-KDCube-CSRF-Token: <returned token>

The token binds subject, tenant, project, app, operation, and method, then is consumed once. Missing, expired, reused, or mismatched proof gets 403. Shared proof-state unavailability gets 503.

Explicit bearer and ID-token requests do not perform this cookie exchange. Their credential is non-ambient request proof; visibility, authority, grants, and product authorization still run.

70OPUse Each Surface's Vocabulary

@mcp(...) intentionally has no proc-side user types, roles, or CSRF. Govern a protected MCP endpoint through its auth owner.

surfaces:
  as_provider:
    mcp:
      reports:
        auth:
          mode: managed
          authority_id: delegated_client
          tools:
            report_read:
              grants: [reports:read]
            report_publish:
              grants: [reports:publish]
          selected_tool_grants: true

Managed mode checks the delegated bearer, concrete resource, selected tool, and grants before app MCP code runs. Bundle mode leaves credential verification to the app.

80OPVerify The Effective Deployment

• Reload the app or wait for the live property update.
• Reopen Apps and inspect effective values and override markers.
• Test a permitted and denied user/role independently.
• Test authority/grant denial independently from visibility.
• Test CSRF missing, accepted, and reused states when enabled.
• Run MCP discovery and one real tool call.
• Disable one surface and verify siblings remain live.
• Reset one override and verify the code default returns.

For local source changes, refresh or reload the staged runtime copy before judging the result.