feat(controlplane): administrative lifecycle operations for stale enrollment requests and bootstrap-token revocation

[toasterbook88]

Problem Description

During operational maintenance and recovery of a sam-control-plane deployment, two administrative lifecycle gaps were identified that necessitate direct database mutation (e.g. manual SQLite queries) rather than canonical API interactions:

1. Enrollment Request Caching vs. Client Reset

When an operator resets a client node via sam-node reset, its local identity store is wiped. When that client attempts to re-enroll with the same Peer ID (using a new bootstrap token or challenge), the control plane handler (HandleEnroll in internal/controlplane/server.go) executes:

existingReq, err := s.store.GetEnrollmentRequest(ctx, req.PeerId)
if err == nil {
    // Request already exists, return status
    if existingReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED {
        resp, err = s.buildApprovedBootstrapEnrollResponse(ctx, existingReq.BiscuitToken, existingReq.ResolvedAt)
        ...
        s.writeEnrollResponse(w, resp)
        return
    }
}

Because s.store.GetEnrollmentRequest(ctx, req.PeerId) finds the existing approved record in the enrollment_requests table, HandleEnroll serves the previously generated Biscuit token stored in the database.

• If that Biscuit was issued under a signing key that has since retired past its grace period, the reset node receives an unrefreshable token and fails to start.
• There is currently no administrative API endpoint to invalidate, supersede, or delete stale enrollment requests for a peer. Recovery currently requires direct database surgery:
  DELETE FROM enrollment_requests WHERE peer_id = '...';

2. Absence of Bootstrap Token Revocation Endpoint

The control plane provides endpoints to create and list bootstrap tokens:

• POST /admin/bootstrap-tokens
• GET /admin/bootstrap-tokens

However, there is no corresponding endpoint to revoke or delete an issued bootstrap token (neither under /admin/bootstrap-tokens/{id} nor /admin/revoke). If a multi-use bootstrap token needs to be decommissioned early or a token was compromised, an operator has no canonical API mechanism to revoke it. Revocation currently requires manual database deletion:
DELETE FROM bootstrap_tokens WHERE id = '...';

Proposed Enhancements

We propose introducing canonical administrative lifecycle operations so control plane deployments do not require direct database access:

1. Enrollment Request Lifecycle Operation (Reset / Supersede / Invalidate):

   • Provide an administrative operation (e.g. DELETE /admin/enrollments/{peer_id} or POST /admin/enrollments/{peer_id}/invalidate) to transition or purge approved enrollment state, allowing nodes to cleanly re-enroll.
   • Alternatively or additionally, allow HandleEnroll to supersede an existing approved enrollment if the enrollee proves possession of the private key corresponding to the registered peer_id and presents a valid bootstrap token.

2. Bootstrap Token Revocation:

   • Provide an administrative endpoint (e.g. DELETE /admin/bootstrap-tokens/{id} or POST /admin/bootstrap-tokens/{id}/revoke) to explicitly invalidate an active bootstrap token.