[Feat]: Include actor and request metadata in Webhook Events

[cainydev]

Is your feature request related to a problem? Please describe.

I am building a SaaS platform / multi-tenant system on top of Zot and heavily rely on the events extension (specifically the http sink) to react to pushes, calculate billing, and write audit logs.

While the usage of the CloudEvents standard is fantastic, the event payload itself is missing critical context. Currently, events like zotregistry.image.updated only include name, reference, digest, mediaType, and manifest.

Crucially, it is impossible to know WHO triggered the event.
To maintain a proper audit trail or correlate actions to specific users/teams, downstream systems need to know the identity of the authenticated user (actor) and ideally metadata about the HTTP request (IP address, user-agent), similar to how distribution/distribution handles its webhook payloads.

Describe the solution you'd like

Looking at the codebase, this omission seems to be a side effect of where events are fired. The eventRecorder is tightly coupled to the storage layer (passed via storage.New(...)).
When a push happens, the api layer knows the actor via reqCtx.UserAcFromContext(request.Context()) in UpdateManifest (pkg/api/routes.go). However, this context is not passed down to imgStore.PutImageManifest(...). Thus, when the storage layer finally triggers ImageUpdated, the HTTP and Authentication context has been completely lost.

Interestingly, Zot already recognizes the importance of tracking the actor! Right after the storage operation completes in UpdateManifest, Zot calls meta.OnUpdateManifest(request.Context(), ...). By passing the HTTP context to the meta extension, the database layers (e.g., boltdb.go) are able to extract the user and successfully populate the PushedBy field in DescriptorStatistics. This data is just currently siloed in the MetaDB and never reaches the event system.

I would like the CloudEvents data payload to include information about the actor and the request. For example:

{
  "name": "space/my-image",
  "reference": "latest",
  "actor": {
    "name": "username_or_token_subject"
  },
  "request": {
    "addr": "192.168.0.1",
    "method": "PUT",
    "useragent": "docker/24.0.5"
  }
}

Describe alternatives you've considered

Querying the GraphQL API / MetaDB: Knowing that Zot already tracks the actor internally via the meta extension (populating the PushedBy field in DescriptorStatistics within the database), the natural alternative was to simply let the webhook trigger a synchronous GraphQL query back to Zot to ask for the actor. However, this is currently impossible, because the PushedBy field is not exposed in the ImageSummary GraphQL schema (pkg/extensions/search/schema.graphql). Therefore, I have no way to retrieve this internal data without parsing raw DB files.

Auth Token Correlation: Since my SaaS acts as the identity provider (issuing JWTs for Zot), I could temporarily cache whenever a user requests a push token for a specific repository. When the Zot webhook arrives a few seconds later, I correlate the webhook's name (repo) with the cached token intent. While this works as a band-aid, it adds stateful caching complexity, is susceptible to race conditions, and completely leaves out users relying on standard htpasswd or LDAP authentication.

Additional context

No response

[rchincha]

@cainydev do you want to give a PR for this?

[cainydev]

Yes, I'd love to!

I think it makes sense to split this into two PRs:

• Exposing PushedBy in the GraphQL ImageSummary schema (quick fix).
• Adding actor and request data to the CloudEvents.

For the CloudEvents PR, I'd love to know your preference before I start. The issue is that the event is currently fired deep inside the storage layer, where the HTTP context (and the user) is already lost.

Option A: Update the storage interfaces to accept context.Context. This passes the context down to where the event is currently fired. It keeps the current behavior perfectly intact (so internal background jobs like sync still fire events), but it requires updating all storage drivers.

Option B: Fire the event from a higher layer (like the api or meta hooks) where the context is already available. This requires fewer changes to the core code, but it might mean that we have to duplicate code so that background jobs like sync still fire the events as well.

Which route do you prefer for the project? I think Option A is much more idiomatic and would also allow storage drivers like S3 react to context cancels.