@virtru/dsp-sdk 0.2.3 → 0.3.0

package/src/lib/utils.ts

@@ -4,10 +4,35 @@
  * Your use of this file is governed by the Virtu Terms of Service <https://www.virtru.com/terms-of-service/>.
  */
 
-import type { AuthProvider } from '@opentdf/sdk';
-import type { Interceptor as Inter } from '@connectrpc/connect';
+import type {AuthProvider} from '@opentdf/sdk';
+import {AuthProviders, OpenTDF, PermissionDeniedError, type Source} from '@opentdf/sdk';
+import {PlatformClient} from '@opentdf/sdk/platform';
+import {ActiveStateEnum} from '@opentdf/sdk/platform/common/common_pb.js';
+import type {Certificate} from '../gen/virtru/policy/objects_pb';
+import type {Interceptor as Inter} from '@connectrpc/connect';
+import * as asn1js from 'asn1js';
+import * as pkijs from 'pkijs';
+import {MAX_CERT_BYTES, MAX_CERTS} from "./consts";
+import {DSPClient} from './client';
+
 export type Interceptor = Inter;
 
+export type ObligationFeatureMap = {
+  fully_qualified_names: string[];
+};
+
+export type SupportedObligations = {
+  watermark?: ObligationFeatureMap;
+  prevent_download?: ObligationFeatureMap;
+};
+
+export type GetUserEntitlementsResponse = {
+  entitlements: {
+    entityId: string;
+    attributeValueFqns: string[];
+  }[];
+};
+
 /**
  * Creates an interceptor that adds authentication headers to outgoing requests.
  *
@@ -21,7 +46,7 @@ export type Interceptor = Inter;
  */
 
 export function createAuthInterceptor(authProvider: AuthProvider): Interceptor {
-  const authInterceptor: Interceptor = (next) => async (req) => {
+  return (next) => async (req) => {
     const url = new URL(req.url);
     const pathOnly = url.pathname;
     // Signs only the path of the url in the request
@@ -39,5 +64,436 @@ export function createAuthInterceptor(authProvider: AuthProvider): Interceptor {
 
     return await next(req);
   };
-  return authInterceptor;
+}
+
+/** Creates a new instance of an OIDC Auth Provider consumed by the TDF Clients */
+export async function createAuthProvider(options: {
+  oidc: {
+    clientId: string;
+    tokenEndpoint: string;
+    userInfoEndpoint: string;
+  };
+  refreshToken: string;
+}): Promise<AuthProviders.OIDCRefreshTokenProvider> {
+  const { oidc, refreshToken } = options;
+
+  return await AuthProviders.refreshAuthProvider({
+    clientId: oidc.clientId,
+    exchange: 'refresh',
+    refreshToken: refreshToken,
+    // TODO(DSPX-1559): Clean up these URLs.
+    oidcOrigin: 'https://only-required-for-back-compat.invalid',
+    oidcTokenEndpoint: oidc.tokenEndpoint,
+    oidcUserInfoEndpoint: oidc.userInfoEndpoint,
+  });
+}
+
+export async function createOpenTDFClient(options: {
+  oidc: {
+    clientId: string;
+    tokenEndpoint: string;
+    userInfoEndpoint: string;
+  };
+  platformEndpoint: string;
+  refreshToken: string;
+  obligations: string[];
+}) {
+  const { platformEndpoint, obligations, ...authProviderOptions } = options;
+  return new OpenTDF({
+    authProvider: await createAuthProvider(authProviderOptions),
+    platformUrl: platformEndpoint,
+    policyEndpoint: platformEndpoint,
+    defaultCreateOptions: {
+      defaultKASEndpoint: `${platformEndpoint}/kas`,
+    },
+    defaultReadOptions: {
+      fulfillableObligationFQNs: obligations,
+      // NOTE(DSP-249): Disabling assertion verification until all generated assertions are supported.
+      noVerify: true,
+    },
+    disableDPoP: true,
+  });
+}
+
+export const getObligations = async (
+  ciphertext: ArrayBuffer,
+  options: {
+    oidc: {
+      clientId: string;
+      tokenEndpoint: string;
+      userInfoEndpoint: string;
+    };
+    platformEndpoint: string;
+    refreshToken: string;
+    obligations: string[];
+  }
+): Promise<string[]> => {
+  const client = await createOpenTDFClient(options);
+  const source: Source = {
+    type: 'buffer',
+    location: new Uint8Array(ciphertext),
+  };
+  const tdfReader = client.open({ source });
+  let obligations: string[] = [];
+  try {
+    obligations = (await tdfReader.obligations()).fqns;
+  } catch (error) {
+    if (error instanceof PermissionDeniedError) {
+      obligations = error.requiredObligations || [];
+    }
+    // Swallow other errors and return empty obligations.
+  }
+  return obligations;
+};
+
+export async function getUserEntitlements(options: {
+  oidc: {
+    clientId: string;
+    tokenEndpoint: string;
+    userInfoEndpoint: string;
+  };
+  platformEndpoint: string;
+  refreshToken: string;
+}) {
+  const authProvider = await createAuthProvider({
+    oidc: options.oidc,
+    refreshToken: options.refreshToken,
+  });
+  const accessToken = await authProvider.oidcAuth.get();
+  const userEntitlementsResponse = await fetch(`${options.platformEndpoint}/shared/entitlements`, {
+    body: JSON.stringify({}),
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+  });
+
+  return (await userEntitlementsResponse.json()) as GetUserEntitlementsResponse;
+}
+
+export const flattenObligations = (obligations: SupportedObligations): string[] =>
+  Object.values(obligations).flatMap((feature: ObligationFeatureMap) => feature?.fully_qualified_names || []);
+
+/**
+ * Helper function to retrieve certificates for a specific namespace with pagination handling.
+ *
+ * This function automatically handles pagination to retrieve all certificates for a namespace,
+ * making multiple requests if necessary.
+ *
+ * @param dspClient - The DSP client instance.
+ * @param namespaceId - The namespace UUID.
+ * @returns A promise that resolves to an array of certificates for the namespace.
+ * @throws If there is an error retrieving the certificates from the CertificateService.
+ */
+async function getCertificatesForNamespace(
+  dspClient: DSPClient,
+  namespaceId: string
+): Promise<Certificate[]> {
+  const certificates: Certificate[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const response = await dspClient.v1.certificateService.listCertificatesByNamespace({
+      namespaceId,
+      pagination: { limit, offset },
+    });
+
+    if (response.certificates?.length > 0) {
+      certificates.push(...response.certificates);
+    }
+
+    // Check for more pages
+    if (response.pagination?.nextOffset && response.pagination.nextOffset > 0) {
+      offset = response.pagination.nextOffset;
+    } else {
+      break;
+    }
+  }
+
+  return certificates;
+}
+
+/**
+ * Retrieves all trusted certificates from active namespaces in the platform.
+ *
+ * This function uses the new CertificateService API to retrieve certificates from all active
+ * namespaces. It automatically handles pagination to ensure all certificates are retrieved.
+ *
+ * The function performs the following steps:
+ * 1. Creates an authenticated auth provider with DPoP signing keys
+ * 2. Lists all active namespaces using the PlatformClient
+ * 3. For each namespace, retrieves all associated certificates using the CertificateService
+ * 4. Aggregates and returns all certificates from all namespaces
+ *
+ * @param options - The options object containing the platform endpoint, OIDC configuration, and refresh token.
+ * @param options.oidc - The OIDC configuration object.
+ * @param options.oidc.clientId - The OIDC client ID.
+ * @param options.oidc.tokenEndpoint - The OIDC token endpoint URL.
+ * @param options.oidc.userInfoEndpoint - The OIDC user info endpoint URL.
+ * @param options.platformEndpoint - The base URL of the platform.
+ * @param options.refreshToken - The refresh token for authentication.
+ * @returns A promise that resolves to an array of trusted certificates from all active namespaces.
+ * @throws If there is an error retrieving namespaces or certificates.
+ *
+ * @example
+ * ```typescript
+ * const certificates = await getTrustedCertificates({
+ *   oidc: {
+ *     clientId: 'my-client-id',
+ *     tokenEndpoint: 'https://auth.example.com/token',
+ *     userInfoEndpoint: 'https://auth.example.com/userinfo',
+ *   },
+ *   platformEndpoint: 'https://platform.example.com',
+ *   refreshToken: 'my-refresh-token',
+ * });
+ * ```
+ */
+export async function getTrustedCertificates(options: {
+  oidc: {
+    clientId: string;
+    tokenEndpoint: string;
+    userInfoEndpoint: string;
+  };
+  platformEndpoint: string;
+  refreshToken: string;
+}): Promise<Certificate[]> {
+  function generateSigningKeyPair() {
+    return crypto.subtle.generateKey(
+      {
+        name: 'ECDSA',
+        namedCurve: 'P-256',
+      },
+      true,
+      ['sign', 'verify']
+    );
+  }
+
+  const authProvider = await createAuthProvider({
+    oidc: options.oidc,
+    refreshToken: options.refreshToken,
+  });
+  await authProvider.updateClientPublicKey(await generateSigningKeyPair());
+
+  // Create both clients
+  const platform = new PlatformClient({
+    authProvider,
+    platformUrl: options.platformEndpoint,
+  });
+
+  const dspClient = new DSPClient({
+    platformUrl: options.platformEndpoint,
+    authProvider,
+  });
+
+  const certificates: Certificate[] = [];
+
+  try {
+    // Get active namespaces (still using namespace API)
+    const namespaces = await platform.v1.namespace.listNamespaces({
+      state: ActiveStateEnum.ACTIVE,
+    });
+
+    // Get certificates using new CertificateService API
+    for (const namespace of namespaces.namespaces) {
+      const namespaceCerts = await getCertificatesForNamespace(
+        dspClient,
+        namespace.id
+      );
+      certificates.push(...namespaceCerts);
+    }
+  } catch (error) {
+    console.error('Error retrieving namespace certificates:', error);
+    throw error;
+  }
+
+  return certificates;
+}
+
+/**
+ * Helper to get a string representation of a pkijs Name.
+ */
+function getNameStringSafe(name: pkijs.RelativeDistinguishedNames | undefined): string {
+  if (!name) return '';
+  try {
+    // pkijs Name to string can be derived from typesAndValues
+    const parts = (name.typesAndValues || []).map((tv: any) => {
+      const type = tv?.type ?? 'unknownType';
+      // tv.value is an ASN.1 value; best-effort toString fallback
+      let value: string;
+      try {
+        const block = tv?.value?.valueBlock;
+        const v = block?.value;
+        value = typeof v === 'string' ? v : String(tv?.value);
+      } catch {
+        value = '<?>';
+      }
+      return `${type}=${value}`;
+    });
+    return parts.join(', ');
+  } catch {
+    return '';
+  }
+}
+
+export type JWSValidationResult = {
+  valid: boolean;
+  validationResult: Record<string, string[]>;
+};
+
+function base64ToArrayBuffer(b64: string): ArrayBuffer {
+  const normalized = b64.replace(/\s+/g, '');
+  // Basic sanity check; allow trailing '=' padding
+  if (!/^[-A-Za-z0-9+/]*=*$/.test(normalized)) {
+    throw new Error('Invalid base64 characters');
+  }
+  // Optional size guard (approx: 3/4 of base64 length is bytes)
+  const approxBytes = Math.floor((normalized.length * 3) / 4);
+  if (approxBytes === 0) {
+    throw new Error('Empty base64 data');
+  }
+  if (approxBytes > MAX_CERT_BYTES) {
+    throw new Error(`Certificate exceeds maximum allowed size of ${MAX_CERT_BYTES} bytes`);
+  }
+  const binaryString = atob(normalized);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer; // bytes is freshly allocated; buffer is tightly packed
+}
+
+function pemToArrayBuffer(pem: string): ArrayBuffer {
+  const base64Der = pem
+    .replace(/-----BEGIN CERTIFICATE-----/g, '')
+    .replace(/-----END CERTIFICATE-----/g, '')
+    .replace(/\r?\n|\r|\s/g, '');
+  return base64ToArrayBuffer(base64Der);
+}
+
+/**
+ * Validate that a certificate chain from JWS x5c header chains to a trusted root.
+ *
+ * This function is designed to be portable and can be moved to another repository.
+ * It validates that the certificate chain presented in a JWS x5c header builds a
+ * valid chain to one of the provided trusted root certificates.
+ *
+ * Expectations and behavior:
+ * - `x5c` must be ordered leaf-first and contain base64-encoded DER certs.
+ * - `trustedRootCertificates` should contain PEM-encoded root certificates.
+ * - Performs basic input size checks and safe base64 decoding.
+ * - Uses PKI.js `CertificateChainValidationEngine` for comprehensive path validation
+ *   (validity dates, signatures, policies when present, etc.).
+ * - Returns detailed error messages including the leaf subject/issuer and parsing warnings.
+ *
+ * @param x5c - Array of base64-encoded DER certificates from JWS header (leaf first)
+ * @param trustedRootCertificates - Array of Certificate objects containing trusted roots in PEM format
+ * @returns Object with validation result and warnings
+ * @throws {Error} if validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await validateJWSCertificateChain(
+ *     jwsHeader.x5c,
+ *     namespaceCertificates
+ *   );
+ *   console.log('Chain validates to trusted root', result.validationResult.warnings);
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ * }
+ * ```
+ */
+export async function validateJWSCertificateChain(
+  x5c: string[],
+  trustedRootCertificates: Certificate[]
+): Promise<JWSValidationResult> {
+  const warnings: string[] = [];
+
+  try {
+    // Validate inputs
+    if (!Array.isArray(x5c) || x5c.length === 0) {
+      throw new Error('No certificates provided in x5c array');
+    }
+    if (x5c.length > MAX_CERTS) {
+      throw new Error(`Too many certificates in x5c (max ${MAX_CERTS})`);
+    }
+    if (!Array.isArray(trustedRootCertificates) || trustedRootCertificates.length === 0) {
+      throw new Error('No trusted root certificates provided');
+    }
+
+    // Parse chain certs (base64 DER)
+    const chainCertificates: pkijs.Certificate[] = [];
+    for (let i = 0; i < x5c.length; i++) {
+      const certBase64 = x5c[i];
+      try {
+        const certBuffer = base64ToArrayBuffer(certBase64);
+        const asn1 = asn1js.fromBER(certBuffer);
+        if (asn1.offset === -1) {
+          throw new Error(`Invalid DER encoding for certificate at x5c[${i}]`);
+        }
+        chainCertificates.push(new pkijs.Certificate({ schema: asn1.result }));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        throw new Error(`Failed to parse certificate at x5c[${i}]: ${msg}`);
+      }
+    }
+
+    // Parse trusted roots (PEM)
+    const trustedCerts: pkijs.Certificate[] = [];
+    for (let i = 0; i < trustedRootCertificates.length; i++) {
+      const rootCert = trustedRootCertificates[i];
+      try {
+        const pem = (rootCert as any).pem as string | undefined;
+        if (!pem || pem.trim().length === 0) {
+          warnings.push(`Trusted root at index ${i} has no PEM data; skipping`);
+          continue;
+        }
+        const certBuffer = pemToArrayBuffer(pem);
+        const asn1 = asn1js.fromBER(certBuffer);
+        if (asn1.offset === -1) {
+          warnings.push(`Trusted root at index ${i} has invalid DER; skipping`);
+          continue;
+        }
+        trustedCerts.push(new pkijs.Certificate({ schema: asn1.result }));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        warnings.push(`Failed to parse trusted root at index ${i}: ${msg}`);
+      }
+    }
+
+    if (trustedCerts.length === 0) {
+      throw new Error('No valid trusted root certificates could be parsed');
+    }
+
+    // Build and verify certificate chain using PKI.js
+    const chainEngine = new pkijs.CertificateChainValidationEngine({
+      trustedCerts,
+      certs: chainCertificates,
+      checkDate: new Date(),
+    });
+
+    const verificationResult = await chainEngine.verify();
+    if (!verificationResult.result) {
+      // Compose detailed message
+      const leaf = chainCertificates[0];
+      const leafSubject = getNameStringSafe(leaf.subject);
+      const leafIssuer = getNameStringSafe(leaf.issuer);
+      const baseMsg = verificationResult.resultMessage || 'Certificate chain validation failed';
+      throw new Error(`${baseMsg} (leaf subject='${leafSubject}', issuer='${leafIssuer}')`);
+    }
+
+    return {
+      valid: true,
+      validationResult: {
+        warnings,
+        errors: [],
+      },
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : 'Unknown error';
+    const warnSuffix = warnings.length ? `; warnings: ${warnings.join(' | ')}` : '';
+    throw new Error(`Validation error: ${msg}${warnSuffix}`);
+  }
 }