Scoped Permission Error in One Code Branch (Capability Evidence First)

A permission failure occurring in a single code path should be treated as a capability discovery issue. Record the intended operation performed by the path and compare it with the declared grants of the credentials. Stop the process before making any outbound call to prevent potential issues. To manage this, assign each workload a narrow credential along with a spending boundary.

When only the usage-alert path encounters failure, log a stable operation name, the required capability, and a one-way credential fingerprint. Avoid logging the actual secret. A local preflight check can separate issues related to missing grants from those affecting routing, tenant, and upstream operations. The credential is not a binary switch for the entire application.

Multiple handlers can read the same environment variable but request different operations. A ticket-reply worker may handle support conversations, whereas a usage-alert worker needs to access metering data before stopping or deferring any work. Even if both operations are granted, the distinction in shared secrets does not matter.

The aim is not to grant maximum access but to create a small failure domain that can be easily reasoned about between releases. Instead of maximizing access, focus on a small failure domain that can be managed easily between weekly releases. If the alert workload cannot inspect its own usage, expanding the credential until the error disappears merely shifts a visible authorization failure to an invisible spending risk.

The first useful artifact to generate is a capability matrix, not a new key. Workload and intended operation, along with the required capability and failure policy, should be defined. When a ticket reply handler fails, draft a response and use the name `support.reply.write`. For usage alerts, read the current usage, set the name to `usage.read`, and halt any paid work for that tenant using the `workload.pause` capability.

By mapping these names to the appropriate grants provided by the upstream system, vendor syntax is kept out of business logic, making the review process concrete and focused on which workload can spend, inspect spending, or halt spending. The smallest possible capability check should be implemented at the adapter boundary, ensuring that authorization intent is visible before any network code is executed.

The adapter receives a credential descriptor alongside the secret, checks the intended operation, and emits a structured decision that can be safely retained in logs or error objects. The secret itself should never appear in logs or error objects. Define a type for Capability, which can be `support.reply.write`, `usage.read`, or `workload.pause`.

A Credential type includes a secret and a set of capabilities. An AuthDecision type records the operation, the required capability, a one-way credential fingerprint, and an allowed flag. The fingerprint function creates a twelve-character SHA-256 hash of the secret. The authorize function takes a credential, operation, required capability, and returns an AuthDecision.

If the decision indicates that the credential lacks the required capability for the operation, throw an error indicating the missing capability and the operation. Finally, the requireCapability function checks if the decision allows the operation and throws an error if it does not. To determine if a spend cap should be checked, create a UsageSnapshot type with consumedUnits and capUnits.

Define a UsageClient type with a readUsage method that returns a UsageSnapshot given a tenant ID and secret. The mayDraftReply function authorizes the operation using the authorize function, logs the authorization decision, requires the necessary capability, reads the usage snapshot using the usageClient, and checks if the consumed units are within the cap units.