feat(sdk): Add requiredObligations to the PermissionDeniedError (#781)

elizabethhealy · web-flow · commit 9cd7b44b406e · 2025-10-30T16:14:05.000-04:00
* add requiredObligations to the permission denied error

* bump version for xtest trial, point to xtest branch

* trigger again

* update actual workflow

* revert some of the changes made for testing

* copilot suggestion

* add unit test, expose error types
diff --git a/lib/src/access/access-rpc.ts b/lib/src/access/access-rpc.ts
@@ -85,13 +85,22 @@ export function handleRpcRewrapError(e: unknown, platformUrl: string): never {
   throw new NetworkError(`[${platformUrl}] [Rewrap] ${extractRpcErrorMessage(e)}`);
 }
 
-export function handleRpcRewrapErrorString(e: string, platformUrl: string): never {
+export function handleRpcRewrapErrorString(
+  e: string,
+  platformUrl: string,
+  requiredObligations?: string[]
+): never {
   if (e.includes(Code[Code.InvalidArgument])) {
     // 400 Bad Request
     throw new InvalidFileError(`400 for [${platformUrl}]: rewrap bad request [${e}]`);
   }
   if (e.includes(Code[Code.PermissionDenied])) {
-    // 403 Forbidden
+    if (requiredObligations && requiredObligations.length > 0) {
+      throw new PermissionDeniedError(
+        `403 for [${platformUrl}]; rewrap permission denied`,
+        requiredObligations
+      );
+    }
     throw new PermissionDeniedError(`403 for [${platformUrl}]; rewrap permission denied`);
   }
   if (e.includes(Code[Code.Unauthenticated])) {
diff --git a/lib/src/errors.ts b/lib/src/errors.ts
@@ -103,6 +103,14 @@ export class UnauthenticatedError extends TdfError {
 /** Authorization failure (403) */
 export class PermissionDeniedError extends TdfError {
   override name = 'PermissionDeniedError';
+  readonly requiredObligations?: string[];
+
+  constructor(message: string, obligations?: string[], cause?: Error) {
+    super(message, cause);
+    if (obligations && obligations.length > 0) {
+      this.requiredObligations = obligations;
+    }
+  }
 }
 
 /**
diff --git a/lib/src/index.ts b/lib/src/index.ts
@@ -4,5 +4,15 @@ export { attributeFQNsAsValues } from './policy/api.js';
 export { version, clientType, tdfSpecVersion } from './version.js';
 export { PlatformClient, type PlatformClientOptions, type PlatformServices } from './platform.js';
 export * from './opentdf.js';
+export {
+  TdfError,
+  PermissionDeniedError,
+  IntegrityError,
+  InvalidFileError,
+  DecryptError,
+  NetworkError,
+  AttributeValidationError,
+  ConfigurationError,
+} from './errors.js';
 export * from './seekable.js';
 export * from '../tdf3/src/models/index.js';
diff --git a/lib/src/nanotdf/Client.ts b/lib/src/nanotdf/Client.ts
@@ -319,6 +319,8 @@ export default class Client {
       throw new DecryptError('KAS rewrap response missing expected response or result');
     }
 
+    const requiredObligations = getRequiredObligationFQNs(rewrapResp);
+
     let entityWrappedKey: Uint8Array<ArrayBufferLike>;
     switch (result.result.case) {
       case 'kasWrappedKey': {
@@ -328,7 +330,8 @@ export default class Client {
       case 'error': {
         handleRpcRewrapErrorString(
           result.result.value,
-          getPlatformUrlFromKasEndpoint(kasRewrapUrl)
+          getPlatformUrlFromKasEndpoint(kasRewrapUrl),
+          requiredObligations
         );
       }
       default: {
@@ -415,7 +418,7 @@ export default class Client {
     }
 
     return {
-      requiredObligations: getRequiredObligationFQNs(rewrapResp),
+      requiredObligations,
       unwrappedKey: unwrappedKey,
     };
   }
diff --git a/lib/tdf3/src/tdf.ts b/lib/tdf3/src/tdf.ts
@@ -894,7 +894,11 @@ async function unwrapKey({
       }
 
       case 'error': {
-        handleRpcRewrapErrorString(result.result.value, getPlatformUrlFromKasEndpoint(url));
+        handleRpcRewrapErrorString(
+          result.result.value,
+          getPlatformUrlFromKasEndpoint(url),
+          requiredObligations
+        );
       }
 
       default: {
diff --git a/lib/tests/server.ts b/lib/tests/server.ts
@@ -69,6 +69,7 @@ const kas: RequestListener = async (req, res) => {
       'range',
       'x-test-response',
       'x-test-response-message',
+      'x-test-required-obligations',
       'roundtrip-test-response',
       'connect-protocol-version',
       'connect-streaming-protocol-version',
@@ -127,6 +128,52 @@ const kas: RequestListener = async (req, res) => {
             res.end(JSON.stringify({ error: 'Unauthorized' }));
             return;
           case 403:
+            if (req.headers['x-test-required-obligations']) {
+              console.log(
+                '[DEBUG] required obligations header found ',
+                req.headers['x-test-required-obligations'] as string
+              );
+              const obligations: string[] = JSON.parse(
+                req.headers['x-test-required-obligations'] as string
+              );
+              console.log('[DEBUG] required obligations: ', obligations);
+              const reply = create(RewrapResponseSchema, {
+                responses: [
+                  create(PolicyRewrapResultSchema, {
+                    results: [
+                      create(KeyAccessRewrapResultSchema, {
+                        metadata: {
+                          'X-Required-Obligations': {
+                            kind: {
+                              case: 'listValue',
+                              value: {
+                                values: obligations.map((obligation) =>
+                                  create(ValueSchema, {
+                                    kind: {
+                                      case: 'stringValue',
+                                      value: obligation,
+                                    },
+                                  })
+                                ),
+                              },
+                            },
+                          },
+                        },
+                        result: {
+                          case: 'error',
+                          value: 'Permission denied',
+                        },
+                      }),
+                    ],
+                  }),
+                ],
+              });
+
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'application/json');
+              res.end(toJsonString(RewrapResponseSchema, reply));
+              return;
+            }
             res.end(JSON.stringify({ error: 'Forbidden' }));
             return;
           case 500:
diff --git a/lib/tests/web/platform-rpc.test.ts b/lib/tests/web/platform-rpc.test.ts
@@ -2,6 +2,8 @@ import { expect } from '@esm-bundle/chai';
 import { type AuthProvider, HttpRequest, withHeaders } from '../../src/auth/auth.js';
 import { PlatformClient } from '../../src/platform.js';
 import { attributeFQNsAsValues } from '../../src/policy/api.js';
+import { fetchWrappedKey } from '../../src/access/access-rpc.js';
+import { PermissionDeniedError } from '../../src/errors.js';
 
 const authProvider = <AuthProvider>{
   updateClientPublicKey: async () => {
@@ -14,6 +16,20 @@ const authProvider = <AuthProvider>{
     }),
 };
 
+function authProviderWithHeaders(headers: Record<string, string>): AuthProvider {
+  return <AuthProvider>{
+    updateClientPublicKey: async () => {
+      /* mocked function */
+    },
+    withCreds: async (req: HttpRequest): Promise<HttpRequest> =>
+      withHeaders(req, {
+        Authorization:
+          'Bearer dummy-auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0ZGYiLCJzdWIiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMn0.XFu4sQxAd6n-b7urqTdQ-I9zKqKSQtC04unHsMSpJjc',
+        ...headers,
+      }),
+  };
+}
+
 const platformUrl = 'http://localhost:3000';
 
 describe('Local Platform Connect RPC Client Tests', () => {
@@ -107,4 +123,31 @@ describe('Local Platform Connect RPC Client Tests', () => {
       expect.fail('Test failed missing auth headers', e);
     }
   });
+
+  it(`rewrap key with requiredobligations in error`, async () => {
+    try {
+      const ap = authProviderWithHeaders({
+        'x-test-response': '403',
+        'x-test-required-obligations':
+          '["https://example.com/obl/obligation1","https://example.com/obl/obligation2"]',
+      });
+      try {
+        await fetchWrappedKey(
+          `${platformUrl}/`,
+          'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJyZXF1ZXN0Qm9keSI6Im1vY2stcmVxdWVzdC1ib2R5In0.0O9eyg-zC5Ztf78mPaa61n6INtpTdJv6iQQ_3tg2TRlzA73Md-JDTedGKwQ_J6QQycR5AMY5UqrsQvkcK50jfQ',
+          ap
+        );
+        expect.fail('Test should have thrown PermissionDeniedError');
+      } catch (e) {
+        expect(e).to.be.instanceOf(PermissionDeniedError);
+        const pde = e as PermissionDeniedError;
+        expect(pde.requiredObligations).to.deep.equal([
+          'https://example.com/obl/obligation1',
+          'https://example.com/obl/obligation2',
+        ]);
+      }
+    } catch (e) {
+      console.log(e);
+    }
+  });
 });

Original file line number	Diff line number	Diff line change
`@@ -319,6 +319,8 @@ export default class Client {`
`319`	`319`	`throw new DecryptError('KAS rewrap response missing expected response or result');`
`320`	`320`	`}`
`321`	`321`
	`322`	`+ const requiredObligations = getRequiredObligationFQNs(rewrapResp);`
	`323`	`+`
`322`	`324`	`let entityWrappedKey: Uint8Array<ArrayBufferLike>;`
`323`	`325`	`switch (result.result.case) {`
`324`	`326`	`case 'kasWrappedKey': {`
`@@ -328,7 +330,8 @@ export default class Client {`
`328`	`330`	`case 'error': {`
`329`	`331`	`handleRpcRewrapErrorString(`
`330`	`332`	`result.result.value,`
`331`		`- getPlatformUrlFromKasEndpoint(kasRewrapUrl)`
	`333`	`+ getPlatformUrlFromKasEndpoint(kasRewrapUrl),`
	`334`	`+ requiredObligations`
`332`	`335`	`);`
`333`	`336`	`}`
`334`	`337`	`default: {`
`@@ -415,7 +418,7 @@ export default class Client {`
`415`	`418`	`}`
`416`	`419`
`417`	`420`	`return {`
`418`		`- requiredObligations: getRequiredObligationFQNs(rewrapResp),`
	`421`	`+ requiredObligations,`
`419`	`422`	`unwrappedKey: unwrappedKey,`
`420`	`423`	`};`
`421`	`424`	`}`
Original file line number	Diff line number	Diff line change
`@@ -894,7 +894,11 @@ async function unwrapKey({`
`894`	`894`	`}`
`895`	`895`
`896`	`896`	`case 'error': {`
`897`		`- handleRpcRewrapErrorString(result.result.value, getPlatformUrlFromKasEndpoint(url));`
	`897`	`+ handleRpcRewrapErrorString(`
	`898`	`+ result.result.value,`
	`899`	`+ getPlatformUrlFromKasEndpoint(url),`
	`900`	`+ requiredObligations`
	`901`	`+ );`
`898`	`902`	`}`
`899`	`903`
`900`	`904`	`default: {`