feat(sdk): comprehensive DPoP nonce handling and verification

.github/workflows/roundtrip/config-demo-idp.sh

@@ -2,31 +2,22 @@
 
 set -x
 
-: "${KC_VERSION:=24.0.3}"
+APP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null && pwd)"
 
-if ! which kcadm.sh; then
-  KCADM_URL=https://github.com/keycloak/keycloak/releases/download/${KC_VERSION}/keycloak-${KC_VERSION}.zip
-  echo "DOWNLOADING ${KCADM_URL}"
-  if ! curl --output kc.zip --fail --location "${KCADM_URL}"; then
-    echo "[ERROR] Failed to download ${KCADM_URL}"
-    exit 3
-  fi
-  ls -l
-  if ! unzip ./kc.zip; then
-    echo "[ERROR] Failed to unzip file from ${KCADM_URL}"
-    exit 3
-  fi
-  ls -l
-  ls -l "$(pwd)/keycloak-${KC_VERSION}/bin"
-  PATH=$PATH:"$(pwd)/keycloak-${KC_VERSION}/bin"
-  export PATH
-  if ! which kcadm.sh; then
-    echo "[ERROR] Failed to find kcadm.sh"
-    exit 3
-  fi
-fi
+# Run kcadm inside the keycloak container instead of downloading the release
+# zip. The container ships a JRE matching its own Keycloak version; the host
+# does not necessarily -- Keycloak 26's kcadm needs Java 17, while the
+# ubuntu-22.04 runner defaults to Java 11 (UnsupportedClassVersionError).
+# Using -f makes the compose project resolve from this script's directory, so
+# the caller's working directory doesn't matter.
+kcadm.sh() {
+  docker compose -f "${APP_DIR}/docker-compose.yaml" \
+    exec -T keycloak /opt/keycloak/bin/kcadm.sh "$@"
+}
 
-kcadm.sh config credentials --server http://localhost:65432/auth \
+# Inside the container Keycloak is reached on its own KC_HTTP_PORT, not through
+# the vite dev-server proxy on 65432 that host-side callers use.
+kcadm.sh config credentials --server http://localhost:8888/auth \
   --realm master --user admin --password changeme
 
 kcadm.sh create clients -r opentdf \
@@ -48,7 +39,8 @@ kcadm.sh create clients -r opentdf \
   -s enabled=true \
   -s standardFlowEnabled=true \
   -s serviceAccountsEnabled=true \
-  -s 'protocolMappers=[{"name":"aud","protocol":"openid-connect","protocolMapper":"oidc-audience-mapper","consentRequired":false,"config":{"access.token.claim":"true","included.custom.audience":"http://localhost:65432"}}]'
+  -s 'protocolMappers=[{"name":"aud","protocol":"openid-connect","protocolMapper":"oidc-audience-mapper","consentRequired":false,"config":{"access.token.claim":"true","included.custom.audience":"http://localhost:65432"}}]' \
+  -s 'attributes={"dpop.bound.access.tokens":"true"}'
 
 kcadm.sh create users -r opentdf -s username=user1 -s enabled=true -s firstName=Alice -s lastName=User
 kcadm.sh set-password -r opentdf --username user1 --new-password testuser123

.github/workflows/roundtrip/docker-compose.yaml

@@ -1,18 +1,12 @@
 services:
   keycloak:
-    image: keycloak/keycloak:24.0.5
+    image: keycloak/keycloak:26.2
     restart: always
     command:
     - "start-dev"
     - "--verbose"
     environment:
-      KC_DB_VENDOR: postgres
-      KC_DB_URL_HOST: keycloakdb
-      KC_DB_URL_PORT: 5432
-      KC_DB_URL_DATABASE: keycloak
-      KC_DB_USERNAME: keycloak
-      KC_DB_PASSWORD: changeme
-      KC_FEATURES: 'preview,token-exchange'
+      KC_FEATURES: "preview,token-exchange,admin-fine-grained-authz:v1"
       KC_HEALTH_ENABLED: 'true'
       KC_HOSTNAME_ADMIN_URL: 'http://localhost:65432/auth'
       KC_HOSTNAME_PORT: '65432'
@@ -29,24 +23,11 @@ services:
     ports:
       - '8888:8888'
     healthcheck:
-      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:8888/auth/health/live']
+      test: ['CMD-SHELL', '[ -f /tmp/HealthCheck.java ] || echo "public class HealthCheck { public static void main(String[] args) throws java.lang.Throwable { System.exit(java.net.HttpURLConnection.HTTP_OK == ((java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection()).getResponseCode() ? 0 : 1); } }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java http://localhost:9000/auth/health/live']
       interval: 5s
       timeout: 10s
       retries: 3
       start_period: 2m
-  keycloakdb:
-    image: postgres:15-alpine
-    restart: always
-    user: postgres
-    environment:
-      POSTGRES_PASSWORD: changeme
-      POSTGRES_USER: postgres
-      POSTGRES_DB: keycloak
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
   opentdfdb:
     image: postgres:15-alpine
     restart: always

.github/workflows/roundtrip/encrypt-decrypt.sh

@@ -16,6 +16,7 @@ _tdf3_test() {
     --ignoreAllowList \
     --oidcEndpoint http://localhost:65432/auth/realms/opentdf \
     --auth testclient:secret \
+    --dpop \
     --output sample.txt.tdf \
     encrypt "${plain}" \
     --containerType tdf3 \
@@ -28,6 +29,7 @@ _tdf3_test() {
     --ignoreAllowList \
     --oidcEndpoint http://localhost:65432/auth/realms/opentdf \
     --auth testclient:secret \
+    --dpop \
     --output sample_out.txt \
     --containerType tdf3 \
     decrypt sample.txt.tdf
@@ -50,6 +52,7 @@ _tdf3_inspect_test() {
     --ignoreAllowList \
     --oidcEndpoint http://localhost:65432/auth/realms/opentdf \
     --auth testclient:secret \
+    --dpop \
     --output sample-with-attrs.txt.tdf \
     --attributes 'https://attr.io/attr/a/value/1,https://attr.io/attr/x/value/2' \
     encrypt "${plain}" \

.github/workflows/roundtrip/keycloak_data.yaml

@@ -42,9 +42,11 @@ realms:
           serviceAccountsEnabled: true
           clientAuthenticatorType: client-secret
           secret: secret
+          attributes:
+            dpop.bound.access.tokens: "true"
           protocolMappers:
             - *customAudMapper
-        sa_realm_roles: 
+        sa_realm_roles:
           - opentdf-standard
       - client:
           clientID: tdf-entity-resolution

.github/workflows/roundtrip/opentdf.yaml

@@ -54,6 +54,16 @@ server:
     public_client_id: 'opentdf-public'
     audience: 'http://localhost:65432'
     issuer: http://localhost:65432/auth/realms/opentdf
+    dpop:
+      # Make KAS answer the first DPoP-proofed request with 401 + DPoP-Nonce so
+      # the roundtrip actually walks the server-issued nonce retry, not just
+      # plain proof-of-possession. xtest can't cover this: its nonce cases only
+      # run when the shared `dpop-challenge` input is on, which also swaps in a
+      # platform config other SDKs aren't ready for. Left off, this PR's headline
+      # feature would ship with no CI coverage at all.
+      # Only `enforce` would reject bearer tokens outright; that stays off, so
+      # the non-DPoP paths in this job are unaffected.
+      require_nonce: true
     policy:
       ## Dot notation is used to access nested claims (i.e. realm_access.roles)
       # Claim that represents the user (i.e. email)

.github/workflows/roundtrip/wait-and-test.sh

@@ -115,7 +115,7 @@ _init_platform() {
     return 1
   fi
   if ! ./config-demo-idp.sh; then
-    echo "[ERROR] unable to provision keycloak"
+    echo "[ERROR] unable to configure demo idp clients"
     return 1
   fi
   if ! ./init-temp-keys.sh; then

cli/src/cli.ts

@@ -22,6 +22,7 @@ import { CLIError, Level, log } from './logger.js';
 import * as assertions from '@opentdf/sdk/assertions';
 import { base64 } from '@opentdf/sdk/encodings';
 import { type KeyPair } from '@opentdf/sdk/singlecontainer';
+import { resolveDPoPFromArgs } from './dpop-helpers.js';
 
 type AuthToProcess = {
   auth?: string;
@@ -53,14 +54,10 @@ const parseJwtComplete = (jwt: string) => {
   return { header: parseJwt(jwt, 0), payload: parseJwt(jwt) };
 };
 
-async function processAuth({
-  auth,
-  clientId,
-  clientSecret,
-  concurrencyLimit,
-  oidcEndpoint,
-  userId,
-}: AuthToProcess): Promise<LoggedAuthProvider> {
+async function processAuth(
+  { auth, clientId, clientSecret, concurrencyLimit, oidcEndpoint, userId }: AuthToProcess,
+  dpopKeyPair?: KeyPair
+): Promise<LoggedAuthProvider> {
   log('DEBUG', 'Processing auth params');
   if (!oidcEndpoint) {
     throw new CLIError('CRITICAL', 'oidcEndpoint must be specified');
@@ -79,18 +76,32 @@ async function processAuth({
       'Auth expects clientId and clientSecret, or combined auth param'
     );
   }
+  // Pass DPoP key into the provider config so the AccessToken is born with
+  // DPoP enabled (config.dpopEnabled + signingKey). Without this, the very
+  // first POST /token would go out without a DPoP proof — Keycloak clients
+  // with dpop_bound_access_tokens=true reject that with 400 invalid_request.
+  // Without a key, DPoP stays off so non-DPoP clients still get plain Bearer
+  // tokens that the platform will accept.
   const actual = await AuthProviders.clientSecretAuthProvider({
     clientId,
     oidcOrigin: oidcEndpoint,
     exchange: 'client',
     clientSecret,
+    dpopEnabled: !!dpopKeyPair,
+    signingKey: dpopKeyPair,
   });
   if (concurrencyLimit !== 1) {
     await actual.oidcAuth.get();
   }
   const requestLog: AuthProviders.HttpRequest[] = [];
   return {
     requestLog,
+    // Forward the wrapped provider's per-client DPoP-Nonce cache. Without this,
+    // the auth interceptor/transport fall back to the shared default cache while
+    // `withCreds` (delegated below) mints proofs from the wrapped provider's own
+    // cache — the two diverge and the DPoP-Nonce challenge retry never carries
+    // the server nonce (RFC 9449 §9).
+    nonceCache: actual.nonceCache,
     updateClientPublicKey: async (signingKey: KeyPair) => {
       actual.updateClientPublicKey(signingKey);
       log('DEBUG', `updateClientPublicKey: [${signingKey?.publicKey}]`);
@@ -394,8 +405,14 @@ export const handleArgs = (args: string[]) => {
       })
       .option('dpop', {
         group: 'Security:',
-        desc: 'Use DPoP for token binding',
-        type: 'boolean',
+        desc: 'Enable DPoP token binding. Optional value selects algorithm: ES256 (default), ES384, ES512, RS256. Use --dpop=ES512 to specify.',
+        type: 'string',
+      })
+      .option('dpopKey', {
+        alias: 'dpop-key',
+        group: 'Security:',
+        desc: 'Path to PEM-encoded PKCS8 private key for DPoP signing. Enables DPoP alone if --dpop is omitted.',
+        type: 'string',
       })
       .implies('auth', '--no-clientId')
       .implies('auth', '--no-clientSecret')
@@ -513,6 +530,21 @@ export const handleArgs = (args: string[]) => {
         description: 'output file',
       })
 
+      .command(
+        'supports <feature>',
+        'Check if a feature is supported',
+        (yargs) => {
+          yargs.strict().positional('feature', {
+            describe: 'feature name to check',
+            type: 'string',
+            choices: ['dpop'],
+          });
+        },
+        async () => {
+          // yargs choices validation ensures feature is supported; return naturally exits 0
+        }
+      )
+
       .command(
         'inspect [file]',
         'Inspect TDF and extract header information, without decrypting',
@@ -561,9 +593,11 @@ export const handleArgs = (args: string[]) => {
           if (!argv.oidcEndpoint) {
             throw new CLIError('CRITICAL', 'oidcEndpoint must be specified');
           }
-          const authProvider = await processAuth(argv);
+          const { dpopEnabled, dpopKeyPair } = await resolveDPoPFromArgs(argv);
+          const authProvider = await processAuth(argv, dpopKeyPair);
           log('DEBUG', `Initialized auth provider ${JSON.stringify(authProvider)}`);
           const guessedPolicyEndpoint = guessPolicyUrl(argv);
+
           const client = new OpenTDF({
             authProvider,
             defaultCreateOptions: {
@@ -574,7 +608,8 @@ export const handleArgs = (args: string[]) => {
               ignoreAllowlist: ignoreAllowList,
               noVerify: !!argv.noVerifyAssertions,
             },
-            disableDPoP: !argv.dpop,
+            disableDPoP: !dpopEnabled,
+            dpopKeys: dpopKeyPair ? Promise.resolve(dpopKeyPair) : undefined,
             policyEndpoint: guessedPolicyEndpoint,
             platformUrl: argv.platformUrl || guessedPolicyEndpoint,
           });
@@ -600,14 +635,23 @@ export const handleArgs = (args: string[]) => {
                   console.assert(!accessToken, 'Multiple authorization headers found');
                   accessToken = parseJwt(lastRequest.headers[h].split(' ')[1]);
                   log('INFO', `Access Token: ${JSON.stringify(accessToken)}`);
-                  if (argv.dpop) {
-                    console.assert(accessToken.cnf?.jkt, 'Access token must have a cnf.jkt');
+                  if (dpopEnabled && !accessToken.cnf?.jkt) {
+                    // A missing cnf.jkt means token binding silently didn't take
+                    // effect; fail loudly rather than exit 0 with only a warning.
+                    throw new CLIError(
+                      'CRITICAL',
+                      'DPoP requested but the access token is not bound (missing cnf.jkt)'
+                    );
                   }
                   break;
               }
             }
-            console.assert(accessToken, 'No access_token found');
-            console.assert(!argv.dpop || dpopToken, 'DPoP requested but absent');
+            if (!accessToken) {
+              throw new CLIError('CRITICAL', 'No access_token found');
+            }
+            if (dpopEnabled && !dpopToken) {
+              throw new CLIError('CRITICAL', 'DPoP requested but no DPoP proof was sent');
+            }
           } finally {
             client.close();
           }
@@ -624,7 +668,8 @@ export const handleArgs = (args: string[]) => {
         },
         async (argv) => {
           log('DEBUG', 'Running encrypt command');
-          const authProvider = await processAuth(argv);
+          const { dpopEnabled, dpopKeyPair } = await resolveDPoPFromArgs(argv);
+          const authProvider = await processAuth(argv, dpopKeyPair);
           log('DEBUG', `Initialized auth provider ${JSON.stringify(authProvider)}`);
           const guessedPolicyEndpoint = guessPolicyUrl(argv);
 
@@ -633,7 +678,8 @@ export const handleArgs = (args: string[]) => {
             defaultCreateOptions: {
               defaultKASEndpoint: argv.kasEndpoint,
             },
-            disableDPoP: !argv.dpop,
+            disableDPoP: !dpopEnabled,
+            dpopKeys: dpopKeyPair ? Promise.resolve(dpopKeyPair) : undefined,
             policyEndpoint: guessedPolicyEndpoint,
             platformUrl: argv.platformUrl || guessedPolicyEndpoint,
           });