@opentdf/sdk 0.5.0-rc.44 → 0.6.0-beta.52

package/src/access/access-rpc.ts

@@ -8,7 +8,14 @@ import {
 } from '../access.js';
 
 import { type AuthProvider } from '../auth/auth.js';
-import { ConfigurationError, NetworkError } from '../errors.js';
+import {
+  ConfigurationError,
+  InvalidFileError,
+  NetworkError,
+  PermissionDeniedError,
+  ServiceError,
+  UnauthenticatedError,
+} from '../errors.js';
 import { PlatformClient } from '../platform.js';
 import { RewrapResponse } from '../platform/kas/kas_pb.js';
 import { ListKeyAccessServersResponse } from '../platform/policy/kasregistry/key_access_server_registry_pb.js';
@@ -19,6 +26,7 @@ import {
   validateSecureUrl,
 } from '../utils.js';
 import { X_REWRAP_ADDITIONAL_CONTEXT } from './constants.js';
+import { ConnectError, Code } from '@connectrpc/connect';
 
 /**
  * Get a rewrapped access key to the document, if possible
@@ -42,11 +50,75 @@ export async function fetchWrappedKey(
       [X_REWRAP_ADDITIONAL_CONTEXT]: rewrapAdditionalContextHeader,
     };
   }
+  let response: RewrapResponse;
   try {
-    return await platform.v1.access.rewrap({ signedRequestToken }, options);
+    response = await platform.v1.access.rewrap({ signedRequestToken }, options);
   } catch (e) {
-    throw new NetworkError(`[${platformUrl}] [Rewrap] ${extractRpcErrorMessage(e)}`);
+    handleRpcRewrapError(e, platformUrl);
+  }
+  return response;
+}
+
+export function handleRpcRewrapError(e: unknown, platformUrl: string): never {
+  if (e instanceof ConnectError) {
+    console.log('Error is a ConnectError with code:', e.code);
+    switch (e.code) {
+      case Code.InvalidArgument: // 400 Bad Request
+        throw new InvalidFileError(`400 for [${platformUrl}]: rewrap bad request [${e.message}]`);
+      case Code.PermissionDenied: // 403 Forbidden
+        throw new PermissionDeniedError(`403 for [${platformUrl}]; rewrap permission denied`);
+      case Code.Unauthenticated: // 401 Unauthorized
+        throw new UnauthenticatedError(`401 for [${platformUrl}]; rewrap auth failure`);
+      case Code.Internal:
+      case Code.Unimplemented:
+      case Code.DataLoss:
+      case Code.Unknown:
+      case Code.DeadlineExceeded:
+      case Code.Unavailable: // >=500 Server Error
+        throw new ServiceError(
+          `${e.code} for [${platformUrl}]: rewrap failure due to service error [${e.message}]`
+        );
+      default:
+        throw new NetworkError(`[${platformUrl}] [Rewrap] ${e.message}`);
+    }
+  }
+  throw new NetworkError(`[${platformUrl}] [Rewrap] ${extractRpcErrorMessage(e)}`);
+}
+
+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])) {
+    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])) {
+    // 401 Unauthorized
+    throw new UnauthenticatedError(`401 for [${platformUrl}]; rewrap auth failure`);
+  }
+  if (
+    e.includes(Code[Code.Internal]) ||
+    e.includes(Code[Code.Unimplemented]) ||
+    e.includes(Code[Code.DataLoss]) ||
+    e.includes(Code[Code.Unknown]) ||
+    e.includes(Code[Code.DeadlineExceeded]) ||
+    e.includes(Code[Code.Unavailable])
+  ) {
+    // >=500
+    throw new ServiceError(`500+ [${platformUrl}]: rewrap failure due to service error [${e}]`);
   }
+  throw new NetworkError(`[${platformUrl}] [Rewrap] ${e}`);
 }
 
 export async function fetchKeyAccessServers(

package/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;
+    }
+  }
 }
 
 /**

package/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';

package/src/nanotdf/Client.ts

@@ -1,4 +1,8 @@
-import * as base64 from '../encodings/base64.js';
+import { create, toJsonString } from '@bufbuild/protobuf';
+import {
+  UnsignedRewrapRequest_WithPolicyRequestSchema,
+  UnsignedRewrapRequestSchema,
+} from '../platform/kas/kas_pb.js';
 import { generateKeyPair, keyAgreement } from '../nanotdf-crypto/index.js';
 import getHkdfSalt from './helpers/getHkdfSalt.js';
 import DefaultParams from './models/DefaultParams.js';
@@ -8,13 +12,16 @@ import {
   KasPublicKeyInfo,
   OriginAllowList,
 } from '../access.js';
+import { handleRpcRewrapErrorString } from '../../src/access/access-rpc.js';
 import { AuthProvider, isAuthProvider, reqSignature } from '../auth/providers.js';
 import { ConfigurationError, DecryptError, TdfError, UnsafeUrlError } from '../errors.js';
 import {
   cryptoPublicToPem,
   getRequiredObligationFQNs,
   pemToCryptoPublicKey,
+  upgradeRewrapResponseV1,
   validateSecureUrl,
+  getPlatformUrlFromKasEndpoint,
 } from '../utils.js';
 
 export interface ClientConfig {
@@ -260,18 +267,35 @@ export default class Client {
       throw new ConfigurationError('Signer key has not been set or generated');
     }
 
-    const requestBodyStr = JSON.stringify({
-      algorithm: DefaultParams.defaultECAlgorithm,
-      // nano keyAccess minimum, header is used for nano
+    const unsignedRequest = create(UnsignedRewrapRequestSchema, {
+      clientPublicKey: await cryptoPublicToPem(ephemeralKeyPair.publicKey),
+      requests: [
+        create(UnsignedRewrapRequest_WithPolicyRequestSchema, {
+          keyAccessObjects: [
+            {
+              keyAccessObjectId: 'kao-0', // only one kao, no bulk
+              keyAccessObject: {
+                header: new Uint8Array(nanoTdfHeader),
+                kasUrl: '',
+                protocol: Client.KAS_PROTOCOL,
+                keyType: Client.KEY_ACCESS_REMOTE,
+              },
+            },
+          ],
+          algorithm: DefaultParams.defaultECAlgorithm,
+        }),
+      ],
       keyAccess: {
-        type: Client.KEY_ACCESS_REMOTE,
-        url: '',
+        header: new Uint8Array(nanoTdfHeader),
+        kasUrl: '',
         protocol: Client.KAS_PROTOCOL,
-        header: base64.encodeArrayBuffer(nanoTdfHeader),
+        keyType: Client.KEY_ACCESS_REMOTE,
       },
-      clientPublicKey: await cryptoPublicToPem(ephemeralKeyPair.publicKey),
+      algorithm: DefaultParams.defaultECAlgorithm,
     });
 
+    const requestBodyStr = toJsonString(UnsignedRewrapRequestSchema, unsignedRequest);
+
     const jwtPayload = { requestBody: requestBodyStr };
 
     const signedRequestToken = await reqSignature(jwtPayload, requestSignerKeyPair.privateKey, {
@@ -285,9 +309,37 @@ export default class Client {
       this.authProvider,
       this.fulfillableObligationFQNs
     );
+    // Upgrade any V1 responses to V2
+    upgradeRewrapResponseV1(rewrapResp);
+
+    const result = rewrapResp.responses?.[0]?.results?.[0];
+    if (!result) {
+      // This should not happen - KAS should always return at least one response and one result
+      // or the upgradeRewrapResponseV1 should have created them
+      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': {
+        entityWrappedKey = result.result.value;
+        break;
+      }
+      case 'error': {
+        handleRpcRewrapErrorString(
+          result.result.value,
+          getPlatformUrlFromKasEndpoint(kasRewrapUrl),
+          requiredObligations
+        );
+      }
+      default: {
+        throw new DecryptError('KAS rewrap response missing wrapped key');
+      }
+    }
 
     // Extract the iv and ciphertext
-    const entityWrappedKey = rewrapResp.entityWrappedKey;
     const ivLength =
       clientVersion == Client.SDK_INITIAL_RELEASE ? Client.INITIAL_RELEASE_IV_SIZE : Client.IV_SIZE;
     const iv = entityWrappedKey.subarray(0, ivLength);
@@ -366,7 +418,7 @@ export default class Client {
     }
 
     return {
-      requiredObligations: getRequiredObligationFQNs(rewrapResp),
+      requiredObligations,
       unwrappedKey: unwrappedKey,
     };
   }

package/src/utils.ts

@@ -3,7 +3,12 @@ import { exportSPKI, importX509 } from 'jose';
 import { base64 } from './encodings/index.js';
 import { pemCertToCrypto, pemPublicToCrypto } from './nanotdf-crypto/pemPublicToCrypto.js';
 import { ConfigurationError } from './errors.js';
-import { RewrapResponse } from './platform/kas/kas_pb.js';
+import {
+  RewrapResponse,
+  PolicyRewrapResultSchema,
+  KeyAccessRewrapResultSchema,
+} from './platform/kas/kas_pb.js';
+import { create } from '@bufbuild/protobuf';
 import { ConnectError } from '@connectrpc/connect';
 
 const REQUIRED_OBLIGATIONS_METADATA_KEY = 'X-Required-Obligations';
@@ -255,3 +260,32 @@ export function getRequiredObligationFQNs(response: RewrapResponse) {
 
   return [...requiredObligations.values()];
 }
+
+/**
+ * Upgrades a RewrapResponse from v1 format to v2.
+ * Note: This mutates the response in place.
+ */
+export function upgradeRewrapResponseV1(response: RewrapResponse) {
+  if (response.responses.length > 0) {
+    return;
+  }
+  if (response.entityWrappedKey.length === 0) {
+    return;
+  }
+
+  response.responses = [
+    create(PolicyRewrapResultSchema, {
+      policyId: 'policy',
+      results: [
+        create(KeyAccessRewrapResultSchema, {
+          keyAccessObjectId: 'kao-0',
+          status: 'permit',
+          result: {
+            case: 'kasWrappedKey',
+            value: response.entityWrappedKey,
+          },
+        }),
+      ],
+    }),
+  ];
+}

package/src/version.ts

@@ -1,7 +1,7 @@
 /**
  * Exposes the released version number of the `@opentdf/sdk` package
  */
-export const version = '0.5.0'; // x-release-please-version
+export const version = '0.6.0'; // x-release-please-version
 
 /**
  * A string name used to label requests as coming from this library client.

package/tdf3/src/tdf.ts

@@ -8,7 +8,16 @@ import {
   fetchWrappedKey,
   publicKeyAlgorithmToJwa,
 } from '../../src/access.js';
+import { create, toJsonString } from '@bufbuild/protobuf';
+import {
+  KeyAccessSchema,
+  UnsignedRewrapRequestSchema,
+  UnsignedRewrapRequest_WithPolicyRequestSchema,
+  UnsignedRewrapRequest_WithPolicySchema,
+  UnsignedRewrapRequest_WithKeyAccessObjectSchema,
+} from '../../src/platform/kas/kas_pb.js';
 import { type AuthProvider, reqSignature } from '../../src/auth/auth.js';
+import { handleRpcRewrapErrorString } from '../../src/access/access-rpc.js';
 import { allPool, anyPool } from '../../src/concurrency.js';
 import { base64, hex } from '../../src/encodings/index.js';
 import {
@@ -55,7 +64,11 @@ import { ZipReader, ZipWriter, keyMerge, concatUint8, buffToString } from './uti
 import { CentralDirectory } from './utils/zip-reader.js';
 import { ztdfSalt } from './crypto/salt.js';
 import { Payload } from './models/payload.js';
-import { getRequiredObligationFQNs } from '../../src/utils.js';
+import {
+  getRequiredObligationFQNs,
+  upgradeRewrapResponseV1,
+  getPlatformUrlFromKasEndpoint,
+} from '../../src/utils.js';
 
 // TODO: input validation on manifest JSON
 const DEFAULT_SEGMENT_SIZE = 1024 * 1024;
@@ -189,11 +202,6 @@ export type RewrapRequest = {
 
 export type KasPublicKeyFormat = 'pkcs8' | 'jwks';
 
-export type RewrapResponse = {
-  entityWrappedKey: string;
-  sessionPublicKey: string;
-};
-
 /**
  * If we have KAS url but not public key we can fetch it from KAS, fetching
  * the value from `${kas}/kas_public_key`.
@@ -783,13 +791,50 @@ async function unwrapKey({
 
     const clientPublicKey = ephemeralEncryptionKeys.publicKey;
 
-    const requestBodyStr = JSON.stringify({
+    // Convert keySplitInfo to protobuf KeyAccess
+    const keyAccessProto = create(KeyAccessSchema, {
+      ...(keySplitInfo.type && { keyType: keySplitInfo.type }),
+      ...(keySplitInfo.url && { kasUrl: keySplitInfo.url }),
+      ...(keySplitInfo.protocol && { protocol: keySplitInfo.protocol }),
+      ...(keySplitInfo.wrappedKey && {
+        wrappedKey: new Uint8Array(base64.decodeArrayBuffer(keySplitInfo.wrappedKey)),
+      }),
+      ...(keySplitInfo.policyBinding && { policyBinding: keySplitInfo.policyBinding }),
+      ...(keySplitInfo.kid && { kid: keySplitInfo.kid }),
+      ...(keySplitInfo.sid && { splitId: keySplitInfo.sid }),
+      ...(keySplitInfo.encryptedMetadata && { encryptedMetadata: keySplitInfo.encryptedMetadata }),
+      ...(keySplitInfo.ephemeralPublicKey && {
+        ephemeralPublicKey: keySplitInfo.ephemeralPublicKey,
+      }),
+    });
+
+    // Create the protobuf request
+    const unsignedRequest = create(UnsignedRewrapRequestSchema, {
+      clientPublicKey,
+      requests: [
+        create(UnsignedRewrapRequest_WithPolicyRequestSchema, {
+          keyAccessObjects: [
+            create(UnsignedRewrapRequest_WithKeyAccessObjectSchema, {
+              keyAccessObjectId: 'kao-0',
+              keyAccessObject: keyAccessProto,
+            }),
+          ],
+          ...(manifest.encryptionInformation.policy && {
+            policy: create(UnsignedRewrapRequest_WithPolicySchema, {
+              id: 'policy',
+              body: manifest.encryptionInformation.policy,
+            }),
+          }),
+        }),
+      ],
+      // include deprecated fields for backward compatibility
       algorithm: 'RS256',
-      keyAccess: keySplitInfo,
+      keyAccess: keyAccessProto,
       policy: manifest.encryptionInformation.policy,
-      clientPublicKey,
     });
 
+    const requestBodyStr = toJsonString(UnsignedRewrapRequestSchema, unsignedRequest);
+
     const jwtPayload = { requestBody: requestBodyStr };
     const signedRequestToken = await reqSignature(jwtPayload, dpopKeys.privateKey);
 
@@ -799,39 +844,67 @@ async function unwrapKey({
       authProvider,
       fulfillableObligations
     );
-    const { entityWrappedKey, metadata, sessionPublicKey } = rewrapResp;
+    // Upgrade V1 response to V2 format if needed
+    upgradeRewrapResponseV1(rewrapResp);
+    const { sessionPublicKey } = rewrapResp;
     const requiredObligations = getRequiredObligationFQNs(rewrapResp);
-
-    if (wrappingKeyAlgorithm === 'ec:secp256r1') {
-      const serverEphemeralKey: CryptoKey = await pemPublicToCrypto(sessionPublicKey);
-      const ekr = ephemeralEncryptionKeysRaw as CryptoKeyPair;
-      const kek = await keyAgreement(ekr.privateKey, serverEphemeralKey, {
-        hkdfSalt: await ztdfSalt,
-        hkdfHash: 'SHA-256',
-      });
-      const wrappedKeyAndNonce = entityWrappedKey;
-      const iv = wrappedKeyAndNonce.slice(0, 12);
-      const wrappedKey = wrappedKeyAndNonce.slice(12);
-
-      const dek = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, kek, wrappedKey);
-
-      return {
-        key: new Uint8Array(dek),
-        metadata,
-        requiredObligations,
-      };
+    // Assume only one response and one result for now (V1 style)
+    const result = rewrapResp.responses?.[0]?.results?.[0];
+    if (!result) {
+      // This should not happen - KAS should always return at least one response and one result
+      // or the upgradeRewrapResponseV1 should have created them
+      throw new DecryptError('KAS rewrap response missing expected response or result');
     }
-    const key = Binary.fromArrayBuffer(entityWrappedKey);
-    const decryptedKeyBinary = await cryptoService.decryptWithPrivateKey(
-      key,
-      ephemeralEncryptionKeys.privateKey
-    );
+    const metadata = result.metadata;
+    // Handle the different cases of result.result
+    switch (result.result.case) {
+      case 'kasWrappedKey': {
+        const entityWrappedKey = result.result.value;
+
+        if (wrappingKeyAlgorithm === 'ec:secp256r1') {
+          const serverEphemeralKey: CryptoKey = await pemPublicToCrypto(sessionPublicKey);
+          const ekr = ephemeralEncryptionKeysRaw as CryptoKeyPair;
+          const kek = await keyAgreement(ekr.privateKey, serverEphemeralKey, {
+            hkdfSalt: await ztdfSalt,
+            hkdfHash: 'SHA-256',
+          });
+          const wrappedKeyAndNonce = entityWrappedKey;
+          const iv = wrappedKeyAndNonce.slice(0, 12);
+          const wrappedKey = wrappedKeyAndNonce.slice(12);
 
-    return {
-      key: new Uint8Array(decryptedKeyBinary.asByteArray()),
-      metadata,
-      requiredObligations,
-    };
+          const dek = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, kek, wrappedKey);
+
+          return {
+            key: new Uint8Array(dek),
+            metadata,
+            requiredObligations,
+          };
+        }
+        const key = Binary.fromArrayBuffer(entityWrappedKey);
+        const decryptedKeyBinary = await cryptoService.decryptWithPrivateKey(
+          key,
+          ephemeralEncryptionKeys.privateKey
+        );
+
+        return {
+          key: new Uint8Array(decryptedKeyBinary.asByteArray()),
+          metadata,
+          requiredObligations,
+        };
+      }
+
+      case 'error': {
+        handleRpcRewrapErrorString(
+          result.result.value,
+          getPlatformUrlFromKasEndpoint(url),
+          requiredObligations
+        );
+      }
+
+      default: {
+        throw new DecryptError('KAS rewrap response missing wrapped key');
+      }
+    }
   }
 
   let poolSize = 1;