Security Considerations

Clockworks focuses on deterministic time and causality tooling. As with any identifiers and timestamps that cross trust boundaries, be deliberate about what you expose.

UUIDv7 time exposure

UUIDv7 values embed a millisecond-resolution timestamp by design (RFC 9562). As a result, UUIDv7 generated by UuidV7Factory can often be decoded to reveal an approximate creation time, and ordering/rate information can sometimes be inferred from sequences of IDs.

If you are issuing identifiers across untrusted/public boundaries (URLs, externally-visible resource IDs, third-party logs), do not treat UUIDv7 as opaque.

Common mitigations:

• Use a random UUID (UUIDv4) for externally-visible identifiers.
• Keep UUIDv7 as an internal primary key, and expose a separate opaque token externally.
• Wrap/encrypt identifiers for external presentation if you need internal ordering but external opacity.