Audit, Scopes, And Rate Limits

MyronCMS uses the same safety gates for direct API and MCP action calls. MCP tools/call delegates to MyronActionDispatcher, so authorization, scope checks, audit binding, and rate limiting stay centralized.

This page is for AI operators and documentation authors who need to describe those gates without weakening them.

Human Path

An operator controls AI access by provisioning integrations and scopes outside the MCP client's own control path. A developer documents actions by naming the required scope and the expected failure surface.

For extension v1, there are two separate gates:

Extension grant gate: the extension must be registered, enabled, and granted manifest scopes.
Caller scope gate: the API or MCP caller must hold the action's requiredScope.

Passing one gate does not bypass the other.

AI Path

An installed AI client discovers available tools through tools/list. If a tool is absent or a call returns an authorization error, the safe behavior is to stop or ask the operator for access. The client must not attempt to mint, rotate, revoke, or rescope its own credentials.

An API client can call the audit-log action only when it holds administration.read, but that action is intentionally hidden from MCP by exposeToMcp:false.

Scopes

MyronApiScopes::covers() allows direct scope matches and base-scope coverage for matching sub-scopes.

Base scopes:

Scope	Use
`design.read`	Read design surfaces.
`design.write`	Mutate design surfaces.
`content.read`	Read content surfaces.
`content.write`	Mutate content surfaces.
`administration.read`	Read administration surfaces.
`administration.write`	Mutate administration surfaces.

The codebase also defines platform scopes such as administration.destructive, deployment.push, and deployment.receive. Extension manifest grants remain bounded to the extension-supported base scopes documented in Scopes And Grants.

Audit

The dispatcher allocates an auditEventId when audit logging is configured and writes audit rows for reached actions. Current outcomes include:

ok,
error,
authz_denied,
rate_limited.

Audit records include caller integration, action id, action verb, action domain, request URI, request method, sanitized input/output, outcome, error code, HTTP status, latency, client IP, user agent, and timestamp.

MyronAuditSanitiser recursively redacts known secret keys and base64 content payloads before persistence. The goal is to preserve payload shape without storing secrets.

Audit Log Access

The audit-log read action is registered at:

GET /api/v1/system/audit-log

It declares:

requiredScope: administration.read
exposeToMcp: false

That means it is API-callable for an appropriately scoped caller, but not listed as an MCP tool. The source rationale is to avoid an audit-of-audit feedback loop and keep audit review operator-oriented.

Rate Limits

MyronRateLimiter applies to AI bearer callers through the dispatcher. Current defaults:

Field	Default
Requests per minute	`60`
Burst capacity	`20`
Window	`60` seconds

Per-integration configuration can override:

{
  "requestsPerMinute": 60,
  "burstCapacity": 20,
  "exemptScopes": []
}

The audit log is the counter. A rate-limited request still writes an audit row with outcome=rate_limited.

Artifacts

Source contracts:

app/system/api/Scopes.php
app/system/api/ActionDispatcher.php
app/system/api/RateLimiter.php
app/modules/audit/AuditEvent.php
app/api/actions/system/GetAuditLogAction.php
.amphion/control-plane/architecture-log/full-parity-mcp-2026-05-10.md

Runtime surfaces:

direct /api/v1/... action calls,
MCP tools/list,
MCP tools/call,
/api/v1/system/audit-log.

Safety Boundary

Do not document scope failures as something an AI client can self-remediate. Access changes are operator/admin workflows.

Do not document audit log as MCP-callable. It may be present in the full action catalog but is intentionally hidden from MCP tools.

Do not recommend aggressive parallel retries after a rate limit. Back off and retry after the reported window.

Verification

For a scoped action:

Call with a caller that holds the required scope and confirm success.
Call with an under-scoped caller and confirm scope_insufficient.
Check MCP tools/list with both callers and confirm visibility changes with scope.
Trigger a validation failure and confirm a stable error envelope.
Confirm audit rows are written for reached actions when audit logging is configured.

For audit-log policy:

/api/v1/system/audit-log is registered with administration.read
MCP tools/list does not include the audit-log action

Failure Modes

Failure	Likely cause	Safe response
`auth_required`	Private action was called without an authenticated session or bearer token.	Use an authenticated operator-approved caller.
`auth_invalid`	Bearer token is invalid, revoked, malformed, or not accepted.	Use a valid operator-provisioned token.
`scope_insufficient`	Caller lacks the action's required scope.	Ask the operator to review grants; do not self-rescope.
`rate_limited`	AI bearer caller exceeded its request budget.	Back off and retry after the reported window.
Audit-log tool missing from MCP	Expected hidden policy: `exposeToMcp:false`.	Use operator-facing/API audit review rather than MCP tool access.
Extension action loads but caller still fails	Extension grant gate passed, caller scope gate failed.	Check both extension grants and caller scopes.