Sps-Execution-Context Character Constraints

[djbqrex]

Summary of Issue

The existing 100-character limit allowed by the Sps-Execution-Context header is already generous and gives us essentially unlimited, human-readable tags using only the characters A-Z. Since this is a user defined value being sent with the request we need to handle it safely across the stack:

• sanitize user input
• avoid CodeQL/CWE-117 log injection findings
• keeping inter-service propagation predictable.

Allowing “any dynamic string” feels at odds with common engineering practices for identifiers that are:

• logged (risk of control chars/newlines > log forgery),
• propagated through proxies/middleware (odd chars can get mangled or blocked),
• used in metrics/labels (some backends dislike spaces or punctuation).

If we keep the spec broad, we’ll have to sanitize/escape on every log site, which adds boilerplate and still won’t be perfectly consistent across services.

Concrete Proposal

I've created a PR looking to limit the character set allowed by the Sps-Execution-Context header, found here: #106, and corresponding sps-api-design change here.

Specifically, narrow character set allowed to: [A-Za-z0-9_-]

This still allows human readable values to be passed, with the benefit that it will be easy to sanitize consistently across the org.

My ask to you:

Please respond with:

• How would this change impact you?
• Are you using any characters outside of the suggested set in production today?

We want to identify how backwards compatible this change is as we are making this more restrictive. I am open to other characters being allowed if needed, especially if already used in production code today. However I would be hesitant to allow anything that would be harder to sanitize.

[djbqrex]

This would help validate the "Human Readable" requirement that already exists as well. As for why that's important, cover up the right two columns and tell me what the difference is here:

Human Read(able? maybe not)	ASCII+Unicode	Reason
Acme Corp	Acme Corp	✅ Normal ASCII
Aсme Corp	AU+0441me Corp	❌ Cyrillic "с" (U+0441) instead of Latin "c"
Acme Сorp	Acme U+0421orp	❌ Cyrillic "С" (U+0421) instead of Latin "C"
Acme Coгp	Acme CoU+0433p	❌ Cyrillic "г" (U+0433) instead of Latin "r"
Acme Corp	Acme CorpU+202F	❌ Includes a narrow no-break space (U+202F) at the end
Acme Corp	AcmeU+00A0Corp	❌ Includes a non-breaking space (U+00A0) between words
Acme Corp	AcmeU+2009Corp	❌ Includes a thin space (U+2009) between words

Technically all human readable, but not human distinguishable.

[nicholas-s-perkins]

I would guess this won't affect most users.
For example, parcel-service only allows these fixed values and it's probably not going to change any time soon.

integration
preprod
prod

One could imagine that if we're trying to restrict this for one reason or another, that even [A-Za-z0-9_-] is too permissive. Like why not just limit it to [a-z]?

So while this is a fine change, just to devils advocate a bit, this reminds me a bit of the Zero one infinity rule.
If we're not going to really clamp down on it, like say maybe there should only be a few valid values, why clamp down on it at all? What problem is that practically solving? Because there are other headers teams use as well.

logged (risk of control chars/newlines > log forgery)
propagated through proxies/middleware (odd chars can get mangled or blocked)

We log other headers, and this is a problem with a variety of things, e.g. User-Agent, other MDC things, and maybe should be solved more at the logging framework level if it's an issue? You can suggest this as validation, but practically we don't enforce it that hard.

used in metrics/labels (some backends dislike spaces or punctuation).

Your restriction isn't nearly restrictive enough to protect it for metric labels. It's far more of a cardinality problem than a character problem. Like any app doing this has to limit it to like 3 choices for safe label usage anyway.

[acchristensen]

I could get behind limiting to [a-z0-9_-]. The primary reason, tactically speaking, is to prevent questions of "is it Prod or prod? Is it PreProd, preProd, or preprod?" I see value in practically restricting this.
I would also want to caveat that loosening the restrictions later should be expected, and so we should not assume EC values are "safe" and will forever meet this criteria. As we see expanded use cases, we may want to loosen restrictions to support them.

[djbqrex]

We already have this requirement so the questions around casing should not be an issue, it shouldn't matter when handled per the standard:
The header value MUST be case-insensitive.
Limiting to lower case would make that handling easier to maintain from a dev perspective though. I'm all for it!

[omnipitous]

The RegEx has to be a-zA-Z because we have a requirement for the Headers to be case-insensitive SO it has to be able to successfully "receive" all of "PreProd" "preProd" "preprod" "pRePrOd" even if it's going to treat them all as the same thing (which is "preprod" technically)

[omnipitous]

"[a-zA-Z0-9/:.-_()[]]+" is the updated RegEx I'm proposing to accommodate some well reasoned suggested naming needs (Largely JIRA, Git, Version and URN) . The current tiny subset of available EC values can Not drive the restrictiveness of this Header value.

[acchristensen]

Right, from an HTTP Header perspective. Then, if we moved forward with, it would be prudent to add a MUST clause (or some kind of an aside) that applications must interpret it as lower case since it will be used/set that way in non-header scenarios. In the cases where it's stored from the Header, it's gotta be stored that way.

[acchristensen]

As new use cases come up, I think that's when we consider loosening restrictions.

[djbqrex]

I'm good with the set Nate Dogg provided, it seems reasonable to me, and achieves the goal I have of preventing control characters and other difficult characters to sanitize from being a valid header. This obviously doesn't mean no sanitization is needed on the application side but it will be a lot easier to handle than how the header is defined today.

I don't think we should plan on loosening restrictions. It would be better to have a stable standard declared now that doesn't change with different people/projects. If we loosen restrictions that could mean dev time across a number of services is needed.

Are there any hard objections to [a-zA-Z0-9/:.-_()[]]+?

I'll make sure to update the shared model with the decided upon regex as Travis called out on the PR.

[acchristensen]

I'm more inclined to say we should keep this a-z0-9-_ initially, and loosen the restriction as we move forward and the requirements for to expand become concrete. Right now it's to support "prod" and "preprod" (and maybe "integration"). Opening it up as much as above seems like there is some standard or expectation that a broader audience is not aware of or necessarily aligned on. We can start down that track... but I'm not sure we're ready or will have the time at this moment if there's not a driving priority.
I wouldn't be opposed to making it very clear that we're likely to expand, and anyone accepting an EC to sanitize, validate, store, etc should be ready to treat it as more interesting characters than just what we agree on, here.

[travisgosselin]

I appreciate not having to revisit this later to make it less restrictive. However, without more concrete information—or broader alignment on where execution context is heading—we need to model it based on the current state. That means keeping it practical and not overly pedantic, since going too deep right now would likely delay resolution by weeks or months.

With that in mind, I suggest we move forward with Aaron’s proposed regex. We can note the potential implications for future adjustments, but at least this allows us to make a qualified, time-sensitive decision today.

@djbqrex — would you like to proceed with that updated regex and add a short note in the API Standards about possible future changes (perhaps linking back to this GHD for context)?

Without a doubt, more architectural discussion on the implementation of EC will be needed in the future (which will inform potential future changes to the API contract here).

[djbqrex]

Thank you for guiding this discussion from the architecture side @travisgosselin! It's hard to agree on standards, but I believe it's good to start somewhere. With that, I agree on your approach you've outlined and will make the changes to align with @acchristensen's proposed regex.

It will be nice to have some guidance right NOW for teams, with the announced expectation for expansion in the future. This allows teams to plan for a reasonable expansion, but have a more defined structure to work with for now. I'll make the changes in all the needed places within the next few days, referencing this conversation. We can close this discussion out. Thank you to all who participated!