ADR-0023: Decision Against Implementing Lock/Unlock Mechanism in SPIKE Nexus

Status: accepted
Date: 2025-07-22
Tags: Security, Operations, HA, Simplicity, SPIRE

Context and Problem Statement

A proposal was made to add a lock/unlock mechanism to SPIKE Nexus, allowing operators to globally lock the system (e.g., via a CLI or API) to prevent all secret and policy operations except unlock/status. The lock state would be persisted in the backing store and enforced across all Nexus instances, with the root key zeroed out in memory. This was intended to provide a system-wide freeze for security or operational reasons.

However, this approach introduces significant complexity, especially in high-availability (HA) and distributed deployments. It also creates new operational and security risks and may not align with SPIFFE-native best practices.

Decision Drivers

Simplicity and maintainability of the SPIKE architecture
Security model alignment with SPIFFE/SPIRE
Operational clarity and reliability in HA/distributed setups
Avoiding unnecessary complexity and performance overhead
Leveraging existing SPIRE mechanisms for system-level access control

Considered Options

Implement a lock/unlock mechanism in SPIKE Nexus (persisted in the backing store, enforced at API level)
Use SPIRE registration entry management (delete/disable Nexus entries to “lock” the system)
Rely on infrastructure-level controls (e.g., scaling down Nexus, process management)
Do nothing (status quo)

Decision

SPIKE Nexus will NOT implement a lock/unlock API or CLI feature.

Instead, operators are recommended to achieve system-level locking by either:

Managing SPIRE registration entries: Removing or disabling the relevant SPIRE registration entries for SPIKE Nexus will immediately block all authenticated API access, effectively freezing the system in a secure, auditable, and SPIFFE-native way.
Using infrastructure-level controls: Scaling down the Nexus deployment, stopping Nexus processes, or otherwise restricting access at the infrastructure level are also valid and supported approaches.

These methods are the supported and recommended ways to “lock” the system. No additional lock/unlock API or CLI subcommand will be provided by SPIKE Nexus at this time.

A sample script for SPIRE registration entry management:

SPIFFE_ID="spiffe://spike.ist/spike/nexus/..."
ENTRY_ID=$(spire-server entry show --spiffeID "$SPIFFE_ID" \
  | awk '/Entry ID/ {print $NF}')
if [ -z "$ENTRY_ID" ]; then
  echo "No entry found for SPIFFE ID: $SPIFFE_ID"
  exit 1
fi
if spire-server entry delete --entryID "$ENTRY_ID"; then
  echo "Successfully deleted entry with SPIFFE ID: $SPIFFE_ID"
else
  echo "Failed to delete entry with SPIFFE ID: $SPIFFE_ID"
  exit 1
fi

Rationale

Simplicity: Avoids introducing distributed consensus, state management, and API enforcement logic for a rarely used feature.
Security: SPIRE registration entries are the root of trust; removing them is the most secure and auditable way to block access. Infrastructure controls are also robust and well-understood.
Operational Clarity: The lock/unlock state is unambiguous and enforced at the trust boundary or infrastructure, not in application logic.
HA/Scaling: No need for all Nexus instances to coordinate or poll a shared lock state, avoiding performance and reliability issues.
SPIFFE-Native: Embraces the SPIFFE/SPIRE model for access control, rather than reinventing similar mechanisms in SPIKE.

Consequences

Positive

Simpler, more maintainable codebase
No performance or reliability impact on Nexus API
Locking is enforced at the trust boundary (SPIRE), not in application logic
Immediate effect across all Nexus instances
No risk of partial lock or split-brain scenarios
Aligns with SPIFFE-native best practices

Negative

Locking/unlocking requires SPIRE server access (not just SPIKE operator privileges)—This can be seen as a “positive” consequence, too, as it provides an additional level of isolation and security.
No fine-grained or temporary lock state within SPIKE Nexus itself
Some operational scenarios (e.g., “pause but keep registration”) are not directly supported

Alternatives Considered

Implementing Lock/Unlock in SPIKE Nexus

Rejected due to complexity, risk of split-brain, performance overhead, and operational ambiguity in HA setups.
Would require distributed consensus or polling and add significant code and operational burden.

Infrastructure-Level Controls

Scaling down Nexus or killing processes is effective but “nuclear” and may disrupt monitoring, logging, or other integrations.

Direct DB Manipulation

Not recommended or supported, but possible for those with privileged access. Not considered a safe or auditable approach.

Decision Outcome

This ADR documents the decision to rely on SPIRE registration entry management or infrastructure-level controls for system-level “locking” of SPIKE Nexus, and to avoid implementing a separate lock/unlock API or CLI feature in SPIKE Nexus itself.

This decision may be revisited if/when a true SPIKE Nexus HA topology is implemented and operational experience suggests a different approach is warranted.