docs: Add examples for crypto.sha256 and base64.encode built-in functions

[ToluGIT]

Summary

This PR adds examples for two commonly used built-in functions:

• crypto.md5: Demonstrates payload digest verification with interactive guidance
• base64.encode: Shows HTTP Basic Authentication header creation in Envoy external authorization

Why these changes are needed

Issue #3786 requests examples for built-in functions that currently lack documentation. The crypto.md5 and base64.encode functions are commonly used in authentication and security workflows but have no
practical examples showing integration patterns.

What's included

crypto.md5 example (/docs/docs/policy-reference/_examples/crypto/digest_verification/):

• Verifies payload integrity using MD5 digest verification (commonly used for content verification)
• Includes interactive guidance encouraging users to modify payload values to see verification fail
• Explains real-world motivation for API/webhook integrity checking

base64.encode example (/docs/docs/policy-reference/_examples/encoding/base64_encode_http_auth/):

• Creates HTTP Basic Auth headers in Envoy external authorization responses
• Uses proper envoy.authz package convention and response_headers_to_add object format
• Demonstrates client-server communication bridging when they "don't speak the same language"
• Extracts credentials from request headers following OPA-Envoy integration patterns

Both examples follow documentation patterns with policy.rego, config.json, intro.md, and title.txt files, are integrated into their respective builtin documentation pages with proper headings, and include educational context explaining why these patterns are useful.

Notes to assist PR review:

• Examples tested and validated with opa eval and opa fmt
• Follows the exact same structure as existing examples in the _examples/ directory
• Focused on DevOps/Security use cases as these are the target audience for these functions
• No tests needed as these are documentation examples that demonstrate function usage

Further comments:

This addresses the long-standing issue #3786 incrementally - additional built-in functions can be documented in future PRs using the same approach. The examples chosen are foundational functions that many other security and
DevOps tools depend on.

[netlify]

✅ Deploy Preview for openpolicyagent ready!

Name	Link
🔨 Latest commit	885e3ae
🔍 Latest deploy log	https://app.netlify.com/projects/openpolicyagent/deploys/6880f0ca75eeb90008491ac8
😎 Deploy Preview	https://deploy-preview-7762--openpolicyagent.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[charlieegan3]

Hi there, thanks for working on some more examples here. You'll need to add them to the /docs/policy-reference/builtins/crypto page for them to be visible.

I have left a few other comments. The most important thing with these examples is to show a real or approximately real example, as simply as possible rather than cover all use cases for a function. If we want to show many examples, we can created independent examples with more detail in their explanations. Hope that makes sense! lmk if you have any questions.

Also, can you unmark the PR desc as fixing #3786 since that issue needs more work to close (examples for other functions that we can add in alter PRs).

[charlieegan3]

I would prefer to see an example here that shows a more realistic example of encode. We have the option to use data.json and input.json in these examples to better simulate real policies.

One example might be adding a new header to a downstream request in opa-envoy. e.g.

encoded_username := base64.encode(input.username)
encoded_password := base64.encode(input.password)

basic_auth_header := sprintf("Basic %s", [base64.encode(sprintf("%s:%s", [input.username, input.password]))])

If you have a look here:

https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkresponse

and here:

https://github.com/open-policy-agent/opa-envoy-plugin/blob/main/examples/envoy-uds/quick_start.yaml#L204

you can see how the policy is used to add extra headers as part of the ext auth response. Perhaps something like that would be a good idea to show a more real-world use case here?

[ToluGIT]

Hmmm, true, okay.
Instead of hardcoded fake credentials, now the modified example now takes real input data (username/password) and shows how OPA would process it.

[charlieegan3]

Hey, I don't see the update yet. Have you pushed your changes?

[charlieegan3]

Hey, I've reviewed the changes to this example, but they're incomplete. response_headers_to_add is expected in such an integration. You'll need to base the example around that expected format in order for this to make sense.

Docs are here: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkresponse

You can also see some examples from this test: https://github.com/open-policy-agent/opa-envoy-plugin/blob/7ebf657a09b931ef2417d0502bad6bdf600267d5/envoyauth/response_test.go#L461

[ToluGIT]

Fixed. I have added the complete response_headers_to_add structure as requested.

Thanks for flagging it.

[charlieegan3]

This isn't really the case in OPA since generally OPA is not running against file system content. It'd be nice to update this description to be more about the real world example you choose to implement here instead of a general description of the function.

[ToluGIT]

Instead of generic descriptions about what the functions do, refined the descriptions now to explain exactly what THIS specific example demonstrates.

[charlieegan3]

? 😕 not sure what you mean here sorry.

[ToluGIT]

Hi! I was referring to the description

The current version now says, "This example shows how to use crypto.sha256 to verify data integrity by comparing a provided hash with the computed hash of the actual content."

Instead of the generic description about "file integrity verification in DevOps workflows," it now describes exactly what THIS specific example demonstrates. Comparing a provided hash with the computed hash of input data.

[charlieegan3]

Typically, envoy policies are invoked from envoy/authz/allow.

[ToluGIT]

Fixed. I changed the package to "envoy.authz" following the standard OPA-Envoy convention for external authorisation policies.

[charlieegan3]

Usually a default rule would be used there instead.

[ToluGIT]

Updated to use proper default deny pattern with default allow := false and conditional allow rule based on credential presence

[charlieegan3]

response_headers_to_add is not a list, but an object of str:str

[ToluGIT]

Corrected response_headers_to_add format from array to object (str:str) as per Envoy CheckResponse specification

[charlieegan3]

input.username is not set by OPA envoy, you'd need to have extracted this from either the request body or another header in the envoy case. There are in the input, but in different locations depending on body/header. Header is likely the easiest to use for this example.

[ToluGIT]

Fixed input structure to use proper Envoy CheckRequest format. Now extracts credentials from request headers (x-username/x-password) as suggested, following actual OPA-Envoy integration patterns.

[charlieegan3]

Thanks for updating this example. Can we rename the folder to something more descriptive than sha256?

[ToluGIT]

hmmm
verify_signed_payload or signature_verification which would be preferable?

[charlieegan3]

Perhaps something like digest verification? crypto.md5sum might be better as it's often used for such things. https://www.openpolicyagent.org/docs/policy-reference/builtins/crypto#builtin-crypto-cryptomd5

[ToluGIT]

Switched to crypto.md5 as you suggested

it's indeed more commonly used for digest verification. Renamed folder to "digest_verification" for clarity.

[charlieegan3]

Something nice we can do in these intros is explain to users how they can play with the example. In this example, we should prompt users to change the contents of the payload to show that the signature verification would fail. Or something like that.

It'd also be nice to motivate why something like this might be getting done in a policy. Answering the question: why is this useful would be helpful here too.

[ToluGIT]

Great suggestion! modified the intro with both interactive guidance and motivation:

Added "Try it yourself" section that allows users to change any value in the payload object (like user name or resource path) and re-run the example to see digest_valid become false.

Added a "Why this is useful" section explaining that content verification is essential in APIs and webhooks where you need to ensure data hasn't been tampered with during transmission. The digest acts as a fingerprint for the payload.

[charlieegan3]

Here I think we need to explain that the context is using a base64 encoded example to set a value expected by some downstream service. It is a nice usecase that shows how OPA and envoy can glue things together when the client and server don't speak the same language. Does that make sense? we're using the base64 function here as a utility function.

[ToluGIT]

Yeah, it does make sense.
Now it clearly demonstrates how OPA and Envoy work together when client and server "don't speak the same language."

[charlieegan3]

Suggested change

	This example shows how `base64.encode` acts as a utility function to bridge communication between client and server when they don't speak the same language.
	This example shows how `base64.encode` acts as a utility function to bridge communication between client and server when they expect differing request formats.

[ToluGIT]

Thanks for the review @charlieegan3

[charlieegan3]

I think we should rename

docs/docs/policy-reference/_examples/encoding/base64_encode_http_auth/*

to match the title here.

[ToluGIT]

Yeah, true.

Done! Renamed the folder from "base64_encode_http_auth" to "envoy_header_manipulation" to match the "OPA Envoy Header Manipulation" title. Also updated the built-in page reference and verified everything still works correctly.

[charlieegan3]

Thanks for the back and forth here @ToluGIT, just a few minor edits needed now to get it looking nice in the website editors and we can get this merged.

[ToluGIT]

Thanks so much for all the detailed feedback and guidance throughout this process, @charlieegan3. Your insights have really helped shape these examples into something much more practical and educational. I appreciate you taking the time to walk through the proper OPA-Envoy integration patterns.

Thanks again for the thorough review; it's been a great learning experience working with you on this! 🙏

[ToluGIT]

Sorry about that! I accidentally closed the PR instead of waiting for you to merge it. It's reopened now and ready for merge. Thanks again for all the feedback and approval!