Entity Literal Substitution

[andrewmwells-amazon]

Description of changes

API for Entity literal substitution.

Issue #, if available

#1120

Checklist for requesting a review

The change in this PR is (choose one, and delete the other options):

• A backwards-compatible change requiring a minor version bump to cedar-policy (e.g., addition of a new API).

I confirm that this PR (choose one, and delete the other options):

• Updates the "Unreleased" section of the CHANGELOG with a description of my change (required for major/minor version bumps).

I confirm that cedar-spec (choose one, and delete the other options):

• Does not require updates because my change does not impact the Cedar formal model or DRT infrastructure.

I confirm that docs.cedarpolicy.com (choose one, and delete the other options):

• Does not require updates because my change does not impact the Cedar language specification.

[shaobo-he-aws]

There seem to be conflicts with main.

[cdisselkoen]

Looks good overall; tiny nits and one question about an .expect()

[cdisselkoen]

help me understand why this expect is safe -- the panic-safety comment notes that the est must be valid; but what if the mapping isn't valid or something?

[andrewmwells-amazon]

I think this particular part will be panic-free because we're substituting EntityUIDs for EntityUIDs. I'm less confident about the construction of the AST.

My original thought was that this method can't ensure a policy that previously passed validation still passes after substitution, so the caller will be responsible for checking that policies are valid. I'm not sure that's the best idea. There are some errors that we could catch e.g., mapping Action::"view" -> User::"Alice". Maybe we should try to catch as many as possible and then the caller still needs to re-validate against their schema?

Another option would be to require that the mapping not change entity types.

[andrewmwells-amazon]

Added test based on this that would have caused the AST check below to panic. Now returning an error type again, but I'm not sure reusing the error type is ideal because I suspect there are only a few ways this substitution could fail (the only one I've found so far is the Action -> User one).

[cdisselkoen]

If we wanted the mapping to not change entity types, it could be an Eid->Eid mapping instead of EntityUID->EntityUID. If this fits the need, this might be a better solution.

[andrewmwells-amazon]

Maybe that's the right call for now? It would work well for the internal use case, but I'm hesitant because I think using the same type for human-readable and UUIDs is an anti-pattern. It requires adding constraints like disallowing some prefix from the human-readable Eid and requiring it for the UUIDs.