Snowbridge 6.0.1

docs/api-reference/snowbridge/configuration/targets/http/index.md

@@ -18,6 +18,10 @@ Version 4.0.0 makes breaking changes to the HTTP target. Details on migrating ca
 Version 5.0.0 makes breaking changes to the HTTP target. Details on migrating can be found [in the migration guide](/docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-5-X-X/index.md)
 :::
 
+:::note[Breaking changes in version 6.0.0]
+Version 6.0.0 makes breaking changes to the HTTP target's OAuth2 configuration. Details on migrating can be found [in the migration guide](/docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-6-X-X/index.md)
+:::
+
 ## Basic authentication
 
 Where basicauth is used, it may be configured using the `basic_auth_username` and `basic_auth_password` options. Where an authorization header is used, it may be set via the `headers` option.
@@ -28,10 +32,38 @@ TLS may be configured by providing the `key_file`, `cert_file` and `ca_file` opt
 
 ## OAuth2
 
-Snowbridge supports sending authorized requests to OAuth2-compliant HTTP targets. This can be enabled by setting `oauth2_client_id`, `oauth2_client_secret`, `oauth2_refresh_token` (these three are long-lived credentials used to generate short-lived bearer access tokens), and `oauth2_token_url` (which is the URL of the authorization server providing access tokens).
+Snowbridge supports sending authorized requests to OAuth2-compliant HTTP targets, via one of two flows. The `oauth_client {}` and `oauth_jwt {}` blocks are mutually exclusive — configuring both fails at startup.
 
 Like in the case of basic authentication, we recommend using environment variables for sensitive values.
 
+:::note[Configuration changed in version 6.0.0]
+Before version 6.0.0, the client credentials flow was configured through top-level `oauth2_*` settings. See the [6.x upgrade guide](/docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-6-X-X/index.md) for how to migrate.
+:::
+
+### Client credentials flow
+
+Configure the `oauth_client {}` block with `client_id`, `client_secret`, and `refresh_token` (these three are long-lived credentials used to generate short-lived bearer access tokens), and `token_url` (which is the URL of the authorization server providing access tokens).
+
+### JWT bearer flow
+
+:::note[Added in version 6.0.0]
+Snowbridge supports the JWT bearer flow from version 6.0.0 onwards.
+:::
+
+Where the target expects a [JWT bearer assertion](https://datatracker.ietf.org/doc/html/rfc7523) instead of client credentials — as service accounts on Google APIs do, for example — configure the `oauth_jwt {}` block. Snowbridge signs a JWT with your private key and exchanges it for an access token at `token_url`.
+
+The private key must be PEM-encoded; RSA (PKCS#1 and PKCS#8) and EC keys are supported. Supply it either inline via `key`, or as a path to a key file via `key_file`. These two are mutually exclusive.
+
+| Setting | Required | Description |
+|---|---|---|
+| `key` | One of `key` or `key_file` | PEM-encoded private key, supplied as a string. |
+| `key_file` | One of `key` or `key_file` | Path to a file containing the PEM-encoded private key. |
+| `issuer` | Yes | Issuer claim (`iss`) — typically a service account email or client identifier. |
+| `token_url` | Yes | URL of the authorization server providing access tokens. |
+| `subject` | No | Subject claim (`sub`), for impersonation flows. |
+| `audience` | No | Audience claim (`aud`). Defaults to `token_url`. |
+| `scopes` | No | Scopes to request in the token exchange. |
+
 ## Dynamic headers
 
 :::note

docs/api-reference/snowbridge/configuration/transformations/builtin/reusable/_jqHelpers.md

@@ -12,7 +12,7 @@ In addition to the native functions available in the jq language, the following
 { foo: .collector_tstamp | epochMillis }
 ```
 
-* `hash(algorithm, salt)` hashes the input value. To use unsalted hash, pass an empty string for salt. Salt may be provided as an environment variable using hcl syntax.
+* `hash(algorithm, salt)` hashes the input value, returning the hex-encoded digest. Where a salt is provided, the result is an HMAC of the input keyed with the salt. To use unsalted hash, pass an empty string for salt. Salt may be provided as an environment variable using hcl syntax.
 
 The following hash algorithms are supported:
 - `sha1` - SHA-1 hash (160 bits)
@@ -21,4 +21,8 @@ The following hash algorithms are supported:
 
 ```
 { foo: .user_id |  hash("sha1"; "${env.SHA1_SALT}") }
-```
+```
+
+:::warning[hash output changes in version 6.0.0]
+Version 6.0.0 changes the values this function returns. Before 6.0.0 it returned a PBKDF2-derived key rather than the digest, so hashes produced by 6.x do not match those produced by earlier versions for the same input. See the [6.x upgrade guide](/docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-6-X-X/index.md) for details.
+:::

docs/api-reference/snowbridge/configuration/transformations/custom-scripts/index.md

@@ -138,7 +138,7 @@ The headers will only be included if the target has the [`dynamic_headers = true
 
 ## Helper functions
 
-* `hash(input, algorithm)` hashes the input value. Salt is configured using the `hash_salt_secret` parameter in the hcl configuration. If no value is provided, this function will perform an unsalted hash
+* `hash(input, algorithm)` hashes the input value, returning the hex-encoded digest. Salt is configured using the `hash_salt_secret` parameter in the hcl configuration. Where a salt is provided, the result is an HMAC of the input keyed with the salt; where no value is provided, this function performs an unsalted hash of the input.
 
 The following hash algorithms are supported:
 - `sha1` - SHA-1 hash (160 bits)
@@ -149,6 +149,10 @@ The following hash algorithms are supported:
 hash(input.Data["app_id"], "sha1")
 ```
 
+:::warning[hash output changes in version 6.0.0]
+Version 6.0.0 changes the values this function returns. Before 6.0.0 it returned a PBKDF2-derived key rather than the digest, so hashes produced by 6.x do not match those produced by earlier versions for the same input. See the [6.x upgrade guide](/docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-6-X-X/index.md) for details.
+:::
+
 * `allContexts(data, contextName)` returns an array of all entity instances for a given entity name across all schema versions present in the data object. Instances are ordered by schema version descending (highest version first). `contextName` is the snake_case vendor and name portion of the key, without the `contexts_` prefix and version suffix. Returns an empty array if no matching keys are found.
 
 :::note

docs/api-reference/snowbridge/upgrade-guides/upgrade-guide-6-X-X/index.md

@@ -0,0 +1,83 @@
+---
+id: "Snowbridge 6.x upgrade"
+title: "Snowbridge 6.x upgrade guide"
+sidebar_label: "Snowbridge 6.x upgrade"
+date: "2026-07-15"
+sidebar_position: 600
+description: "Upgrade Snowbridge to version 6.X.X with breaking changes to HTTP target OAuth2 configuration, the hash transformation helper, and the Docker base image."
+keywords: ["snowbridge 6.x upgrade", "upgrade guide", "snowbridge migration", "version 6"]
+---
+
+## Version 6.0.0 breaking changes
+
+Version 6.0.0 restructures the HTTP target's OAuth2 settings, changes the values returned by the `hash` transformation helper, and rebuilds the Docker images on a distroless base. Only the OAuth2 change requires a configuration edit, but review each section below before upgrading.
+
+### HTTP target OAuth2 configuration
+
+The four top-level `oauth2_*` settings have been replaced by an `oauth_client {}` block. This makes room for the new [JWT bearer flow](/docs/api-reference/snowbridge/configuration/targets/http/index.md#jwt-bearer-flow), which is configured through a separate `oauth_jwt {}` block.
+
+| v5 setting (top-level) | v6 setting (inside `oauth_client {}`) |
+|---|---|
+| `oauth2_client_id` | `client_id` |
+| `oauth2_client_secret` | `client_secret` |
+| `oauth2_refresh_token` | `refresh_token` |
+| `oauth2_token_url` | `token_url` |
+
+**Migration required**: move your OAuth2 credentials into an `oauth_client {}` block.
+
+**Before:**
+```hcl
+target {
+  use "http" {
+    url                  = "https://acme.com/x"
+    oauth2_client_id     = env.CLIENT_ID
+    oauth2_client_secret = env.CLIENT_SECRET
+    oauth2_refresh_token = env.REFRESH_TOKEN
+    oauth2_token_url     = "https://my.auth.server/token"
+  }
+}
+```
+
+**After (6.0.0):**
+```hcl
+target {
+  use "http" {
+    url = "https://acme.com/x"
+
+    oauth_client {
+      client_id     = env.CLIENT_ID
+      client_secret = env.CLIENT_SECRET
+      refresh_token = env.REFRESH_TOKEN
+      token_url     = "https://my.auth.server/token"
+    }
+  }
+}
+```
+
+`oauth_client {}` and `oauth_jwt {}` are mutually exclusive — configuring both fails at startup.
+
+### `hash` transformation helper
+
+The `hash` helper available in [custom scripts](/docs/api-reference/snowbridge/configuration/transformations/custom-scripts/index.md) and [jq transformations](/docs/api-reference/snowbridge/configuration/transformations/builtin/jq.md) returns the digest of the chosen hash function, rather than a PBKDF2-derived key.
+
+**Output values change**, but no configuration change is required:
+
+* Unsalted hashing returns the plain digest of the selected function.
+* Salted hashing returns an HMAC of the input, keyed with the salt.
+* Output length follows the selected function — 40 hex characters for `sha1`, 64 for `sha256`, 32 for `md5` — instead of the fixed 48 hex characters produced by PBKDF2.
+
+**Migration required** if you depend on hash values matching data produced by earlier versions. Values hashed by Snowbridge 6.x will not match values hashed by 5.x or earlier for the same input, so any downstream joins, deduplication, or identity stitching on a hashed field will break across the upgrade boundary. Where a destination stores previously hashed values, plan for the change of value — for example by re-hashing historical data, or by switching to a new field.
+
+### Distroless Docker images
+
+Both the main and AWS-only images are built on `gcr.io/distroless/static-debian12:nonroot` instead of Alpine. The image contains only the Snowbridge binary — there is no shell, package manager, or other userland.
+
+This has no effect on how Snowbridge is configured or run, but it does change a few operational details:
+
+* `docker exec` into a running container no longer works — there is no `sh` or `busybox` to exec into. Use logs and metrics for debugging instead.
+* The container runs as UID/GID `65532:65532` (the distroless `nonroot` user) rather than the Alpine-created `snowplow` user. If you mount a config file or TLS certificates into the container, make sure they are readable by that UID.
+* Anything in your deployment that installs packages into the image or runs shell commands in it (for example a shell-based health check, or an entrypoint wrapper script) needs to be reworked.
+
+### Go module path
+
+The Go module path is `github.com/snowplow/snowbridge/v6`. This only affects you if you import Snowbridge packages in your own Go code — for example the [HTTP target's request templater](https://github.com/snowplow/snowbridge/tree/master/pkg/target/http). Update your imports from `github.com/snowplow/snowbridge/v5/...` to `github.com/snowplow/snowbridge/v6/...`.

src/componentVersions.js

@@ -25,7 +25,7 @@ export const versions = {
   enrich: '6.12.0',
   sqs2kinesis: '1.0.4',
   dataflowRunner: '0.7.8',
-  snowbridge: '5.2.0',
+  snowbridge: '6.0.1',
 
   // Loaders
   bqLoader: '2.2.1',