Node Control Grants and Bounded Automation

1. Authentication is not authorization

A coordinator or operator can authenticate successfully and still lack permission for a particular local action. Authentication answers who sent the request; it does not prove that this actor may execute every action on every node with arbitrary parameters. LOC-013 therefore produces Node Control Grant & Action Authorization Ledger v1, which binds actor identity, identity generation, target node, allowed action, scope, lifetime, grant generation, revocation, and the concrete request.

2. LOC-013 owns only the action-authorization boundary

This lesson owns authorization for bounded local actions. CPU, memory, and I/O limits belong to LOC-014; sleep, shutdown mechanics, and Wake-on-LAN belong to LOC-015. A grant can authorize worker.restart, but it does not prove a resource budget or hardware wake capability. Keeping these boundaries separate prevents hidden authority from leaking across local-control concerns.

3. A grant must be content-bound

A defensible grant is not an opaque token whose meaning is simply “admin.” Record at least grant_id, grant_generation, actor_identity, actor_generation, target_node_id, action_allowlist, resource_scope, parameter_scope, condition_set, not_before, and expires_at. If a request is broader than those bindings, reject the request instead of silently widening the grant.

4. RFC 9396 is a useful fine-grained authorization pattern

OAuth Rich Authorization Requests defines structured authorization_details for fine-grained requirements and requires rejection of unknown or invalid authorization-detail structures. We use that as a design discipline: authorization requirements should be structured and validated. RFC 9396 does not define MAKNOW node-control transport or policy.

5. Keep the allowlist separate from the requested action

The ledger must distinguish what the grant permits from what the request asks to do. If the allowlist contains only worker.restart and the request asks for node.shutdown, the decision is DENY even when the actor has operating-system administrator privileges. Ambient authority must not expand a bounded grant.

6. Target node is an independent boundary

A grant for node-A must not be treated as valid for node-B. The actor may be correct and the action may be in the allowlist, yet a target mismatch alone is sufficient for denial. This matters in fleet automation where a routing error can deliver a valid grant to the wrong machine.

7. Resource and parameter scope must be explicit

The action name can match while its parameters exceed the authorized scope. A grant may allow restarting worker-alpha, while the request targets every service on the node. Evaluate resource_scope and parameter_scope independently. A matching command name is not sufficient authorization evidence.

8. Evaluate lifetime and generation separately

issued_at, not_before, and expires_at form the time boundary. grant_generation and actor_generation protect against stale authority after rotation. A grant may still be inside its wall-clock lifetime while being invalid because a newer generation or revocation superseded it. Time and generation are separate evidence dimensions.

9. Revocation must fail closed

If generation seven is revoked, a cached request carrying generation seven must be rejected even when its original expires_at has not passed. Check revocation_state before ALLOW and record the denial in the audit trail. Reauthorization is the recovery path; bypassing revocation is not.

10. Design one-shot and replay semantics up front

Sensitive actions can use a one-shot grant with a grant_nonce. Once consumed, replay of the same nonce must be denied. For recurring automation, do not ambiguously reuse a one-shot grant; issue a renewable grant or a new grant generation under an explicit policy. Application idempotency and authorization replay are different problems.

11. Conditions are part of the authorization decision

A grant may require an open maintenance window, membership in a node group, or a valid change record. If a decisive condition is UNKNOWN, do not promote the action to ALLOW. Preserve DEFER or UNKNOWN and state the recheck trigger. Missing evidence is not the same as false, but it is also not success.

12. Denial reasons must be auditable

DENY is not just a boolean. Record an exact reason such as EXPIRED_GRANT, WRONG_NODE, WRONG_ACTION, SCOPE_MISMATCH, REVOKED_GRANT, or ACTOR_GENERATION_MISMATCH. The audit_event should retain grant id/generation, request identity, and evaluation time so retries and incident review can reconstruct the decision.

13. Worked example: a bounded restart

Assume actor ops-bot/v12 holds grant generation 8 for node-17. The allowlist contains only worker.restart, the resource scope is worker-alpha, the parameter scope is mode=safe, the grant is valid from 20:00 to 20:20, and revocation=ACTIVE. A 20:07 request matching those fields is ALLOW. Route the same request to node-18 and the actor remains valid, but the result becomes DENY / WRONG_NODE.

14. Decisive failure probes

Reject four tempting shortcuts: (1) correct actor and node but an expired grant → DENY/EXPIRED_GRANT; (2) current grant but wrong target node → DENY/WRONG_NODE; (3) restart-only grant but shutdown request → DENY/WRONG_ACTION; (4) revoked grant generation replayed from cache → DENY/REVOKED_GRANT. Learner materials do not expose the hidden expected labels.

15. Transfer to scheduled maintenance

Move the same contract from an interactive one-shot restart to scheduled maintenance automation. The trigger changes and the grant may become renewable, but actor/node/action/scope/lifetime/revocation invariants remain. Do not copy the baseline decision; re-evaluate current time, actor generation, condition set, grant generation, and revocation at each execution. Bounded automation never inherits authority broader than current evidence.