feat(sdk): comprehensive DPoP nonce handling and verification

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

@@ -2,7 +2,7 @@
 
 set -x
 
-: "${KC_VERSION:=24.0.3}"
+: "${KC_VERSION:=26.2.0}"
 
 if ! which kcadm.sh; then
   KCADM_URL=https://github.com/keycloak/keycloak/releases/download/${KC_VERSION}/keycloak-${KC_VERSION}.zip
@@ -48,7 +48,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'
@@ -34,19 +28,6 @@ services:
       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

cli/src/cli.ts

@@ -21,6 +21,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;
@@ -52,14 +53,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');
@@ -78,18 +75,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}]`);
@@ -393,8 +404,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')
@@ -510,6 +527,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',
@@ -558,9 +590,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: {
@@ -571,7 +605,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,
           });
@@ -597,14 +632,14 @@ 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) {
+                  if (dpopEnabled) {
                     console.assert(accessToken.cnf?.jkt, 'Access token must have a cnf.jkt');
                   }
                   break;
               }
             }
             console.assert(accessToken, 'No access_token found');
-            console.assert(!argv.dpop || dpopToken, 'DPoP requested but absent');
+            console.assert(!dpopEnabled || dpopToken, 'DPoP requested but absent');
           } finally {
             client.close();
           }
@@ -621,7 +656,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);
 
@@ -630,7 +666,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,
           });