@learncard/helpers 1.3.12 → 1.4.0

package/src/credential-format.ts

@@ -5,6 +5,7 @@ import type {
     StoredCredential,
     StoredCredentialEnvelope,
     VC,
+    VP,
 } from '@learncard/types';
 import { isStoredCredentialEnvelope } from '@learncard/types';
 
@@ -485,8 +486,8 @@ const projectJwtVcCompactToVc = (compact: string): VC | undefined => {
  * `read.get` result without branching themselves).
  */
 export const resolveStorageReadResult = (
-    value: VC | StoredCredentialEnvelope | undefined
-): VC | StoredCredentialEnvelope | undefined => {
+    value: VC | VP | StoredCredentialEnvelope | undefined
+): VC | VP | StoredCredentialEnvelope | undefined => {
     if (!value) return value;
     if (!isStoredCredentialEnvelope(value)) return value;
     const projected = projectEnvelopeToDisplayVc(value);
@@ -499,8 +500,8 @@ const inferW3cVersionFromContext = (vc: unknown): 'w3c-vc-2.0' | 'w3c-vc-1.1' =>
     const contexts = Array.isArray(contextRaw)
         ? contextRaw
         : contextRaw !== undefined
-        ? [contextRaw]
-        : [];
+          ? [contextRaw]
+          : [];
     const isV2 = contexts.some(
         c => typeof c === 'string' && c.includes('w3.org/ns/credentials/v2')
     );

package/src/environment.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+export type EnvironmentSource = {
+    project: string;
+    source: string;
+    examplePath: string;
+};
+
+export class EnvironmentConfigurationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'EnvironmentConfigurationError';
+    }
+}
+
+export const requiredEnvironmentString = z.string().trim().min(1, 'Required but missing');
+
+export const optionalEnvironmentString = z.preprocess(
+    value => (value === '' ? undefined : value),
+    requiredEnvironmentString.optional()
+);
+
+export const optionalEnvironmentUrl = z.preprocess(
+    value => (value === '' ? undefined : value),
+    z.url('Expected a valid URL').optional()
+);
+
+/**
+ * Deployment manifests historically use both true/false and 1/0. These are the complete
+ * accepted spellings; every other value fails validation.
+ */
+export const environmentBoolean = z
+    .enum(['true', 'false', '1', '0'])
+    .transform(value => value === 'true' || value === '1');
+
+export const optionalEnvironmentBoolean = z.preprocess(
+    value => (value === '' || value === undefined ? undefined : value),
+    environmentBoolean.optional()
+);
+
+export const environmentPort = z.coerce.number().int().min(1).max(65_535);
+
+export const optionalEnvironmentPort = z.preprocess(
+    value => (value === '' || value === undefined ? undefined : value),
+    environmentPort.optional()
+);
+
+export const parseEnvironment = <Schema extends z.ZodType>(
+    schema: Schema,
+    raw: Record<string, unknown>,
+    context: EnvironmentSource
+): z.output<Schema> => {
+    const result = schema.safeParse(raw);
+
+    if (result.success) return result.data;
+
+    const issues = result.error.issues
+        .map(issue => {
+            const key = issue.path.length ? issue.path.map(String).join('.') : '(environment)';
+
+            return `${key}\n  ${issue.message}`;
+        })
+        .join('\n\n');
+
+    throw new EnvironmentConfigurationError(
+        [
+            `Invalid ${context.project} configuration`,
+            '',
+            issues,
+            '',
+            `Configuration source: ${context.source}`,
+            `Copy ${context.examplePath} to .env and correct the values above.`,
+        ].join('\n')
+    );
+};

package/src/index.ts

@@ -9,7 +9,7 @@ import type { DataTransformer } from '@trpc/server';
 export const isHex = (str: string) => /^[0-9a-f]+$/i.test(str);
 
 /** Determines whether or not an object is an encrypted JWE */
-export const isEncrypted = (item: Record<string, any>): item is JWE => {
+export const isEncrypted = (item: unknown): item is JWE => {
     return JWEValidator.safeParse(item).success;
 };
 
@@ -17,7 +17,7 @@ export const isEncrypted = (item: Record<string, any>): item is JWE => {
  * tRPC data transformer that handles RegExp serialization/deserialization
  */
 export const RegExpTransformer: DataTransformer = {
-    serialize(object: any): any {
+    serialize(object) {
         return JSON.stringify(object, (_key, value) => {
             if (value instanceof RegExp) return value.toString(); // Converts to format /pattern/flags
 
@@ -25,7 +25,7 @@ export const RegExpTransformer: DataTransformer = {
         });
     },
 
-    deserialize(object: any): any {
+    deserialize(object) {
         // Old clients will for some reason already be deserialized, so this checks for that to retain
         // backwards compat
         if (typeof object !== 'string') return object;
@@ -51,14 +51,14 @@ export const RegExpTransformer: DataTransformer = {
 /**
  * Determines if a credential uses VC 2.0 format by checking the context array
  */
-export const isVC2Format = (credential: UnsignedVC | VC): boolean => {
-    if (!credential['@context'] || !Array.isArray(credential['@context'])) {
-        return false;
-    }
+export const isVC2Format = (credential: unknown): boolean => {
+    if (!credential || typeof credential !== 'object' || !('@context' in credential)) return false;
+
+    const context = credential['@context'];
 
-    return credential['@context'].some(
-        context => context === 'https://www.w3.org/ns/credentials/v2'
-    );
+    return Array.isArray(context)
+        ? context.some(value => value === 'https://www.w3.org/ns/credentials/v2')
+        : context === 'https://www.w3.org/ns/credentials/v2';
 };
 
 /** Unwraps a boost credential from a CertifiedBoostCredential, if it is one */
@@ -86,6 +86,7 @@ export * from './Utilities';
 export * from './app-install';
 export * from './credential-format';
 export * from './did';
+export * from './environment';
 
 // ADR-0001 Phase 1: format-tagged credential storage projector
 export * from './credential-format';