@nfcard/validation 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nfcard/validation",
+  "version": "0.1.0",
+  "description": "Shared Zod validation schemas for the NFCard product family.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@nfcard/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/fox-hole/nfcard-shared.git",
+    "directory": "validation"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup src/index.ts --format esm --dts --clean"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,634 @@
+import { describe, expect, it } from 'vitest';
+import {
+  cardElementsSchema,
+  comboIdSchema,
+  configurationCreateSchema,
+  contactExchangeSchema,
+  createOrderSchema,
+  digitalConfigSchema,
+  hubConfigSchema,
+  materialSchema,
+  physicalConfigSchema,
+  profileCreateSchema,
+  profileVisibilitySchema,
+  sanitizeHttpUrl,
+  sanitizeText,
+  signupWithProfileSchema,
+  socialLinksSchema,
+  userDataSchema,
+  validateConfiguration,
+  validateDigitalConfig,
+  validatePhysicalConfig,
+  validateUserData,
+  webAddressSchema,
+} from './index.js';
+
+// ── helpers ─────────────────────────────────────────────────────
+
+const validUserData = {
+  firstName: 'János',
+  lastName: 'Kovács',
+  email: 'a@b.co',
+  phone: '+36 20 123 4567',
+  phoneCountryCode: 'HU',
+  position: 'CEO',
+  location: 'Budapest',
+  company: 'Foxhole',
+  website: 'www.foxhome.hu',
+  bio: 'short bio',
+};
+
+const validCardElements = {
+  showName: true,
+  showPosition: false,
+  showEmail: true,
+  showPhone: false,
+  showCompany: false,
+  showLogo: false,
+  showQr: false,
+  showPhoto: false,
+};
+
+const validPhysicalConfig = {
+  material: 'plastic' as const,
+  comboId: 'A1' as const,
+  frontElements: validCardElements,
+  backElements: validCardElements,
+};
+
+const validDigitalConfig = {
+  templateId: 'minimal' as const,
+  accentColor: '#F47B20',
+  fontKey: 'inter',
+  showAvatar: true,
+};
+
+// ── sanitizeText ────────────────────────────────────────────────
+
+describe('sanitizeText', () => {
+  it('strips HTML / script tags (keeps non-tag inner text — verified)', () => {
+    // The regex strips `<…>` markup but does not blacklist tag *contents*
+    // because this output is plain-text only, never re-injected as HTML.
+    expect(sanitizeText('<b>bold</b> text')).toBe('bold text');
+    expect(sanitizeText('<img src=x onerror=alert(1)>')).toBe('');
+    // Script-tag contents come through as inert text — the angle brackets
+    // (the only attack vector for HTML injection) are gone.
+    expect(sanitizeText('<script>alert(1)</script>hello')).toBe(
+      'alert(1)hello',
+    );
+    expect(sanitizeText('<script>alert(1)</script>hello')).not.toMatch(/[<>]/);
+  });
+
+  it('strips control characters', () => {
+    expect(sanitizeText('hello\x00world')).toBe('helloworld');
+    expect(sanitizeText('a\nb\tc')).toBe('abc');
+  });
+
+  it('caps length at the default 50', () => {
+    const long = 'a'.repeat(200);
+    expect(sanitizeText(long).length).toBe(50);
+  });
+
+  it('honours a custom max', () => {
+    expect(sanitizeText('a'.repeat(100), 10).length).toBe(10);
+  });
+
+  it('returns empty for non-string input', () => {
+    expect(sanitizeText(null)).toBe('');
+    expect(sanitizeText(undefined)).toBe('');
+    expect(sanitizeText(42)).toBe('');
+    expect(sanitizeText({})).toBe('');
+  });
+
+  it('trims whitespace', () => {
+    expect(sanitizeText('   hello   ')).toBe('hello');
+  });
+});
+
+// ── sanitizeHttpUrl ─────────────────────────────────────────────
+
+describe('sanitizeHttpUrl', () => {
+  it('accepts a plain https URL and keeps it', () => {
+    expect(sanitizeHttpUrl('https://foxhome.hu/')).toBe('https://foxhome.hu/');
+  });
+
+  it('upgrades http to https', () => {
+    expect(sanitizeHttpUrl('http://foxhome.hu/')).toBe('https://foxhome.hu/');
+  });
+
+  it('prefixes https:// onto a bare hostname', () => {
+    expect(sanitizeHttpUrl('foxhome.hu/x')).toBe('https://foxhome.hu/x');
+  });
+
+  it.each([
+    'javascript:alert(1)',
+    'JaVaScRiPt:alert(1)',
+    'data:text/html,<script>alert(1)</script>',
+    'vbscript:msgbox(1)',
+    'file:///etc/passwd',
+    'ftp://foxhome.hu',
+    'mailto:a@b.c',
+  ])('rejects dangerous / non-http scheme: %s', (raw) => {
+    expect(sanitizeHttpUrl(raw)).toBe('');
+  });
+
+  it.each([
+    '<script>alert(1)</script>',
+    'https://x.com" onclick="alert(1)',
+    "https://x.com' onmouseover='alert(1)",
+    'https://x.com`x`',
+    'https://x.com\\..\\..',
+  ])('strips HTML/quote/control chars before parsing: %s', (raw) => {
+    const out = sanitizeHttpUrl(raw);
+    // Either rejected outright or sanitized — never contains the
+    // dangerous chars.
+    expect(out).not.toMatch(/[<>"'`\\]/);
+  });
+
+  it('rejects values over 2048 chars', () => {
+    const long = 'https://foxhome.hu/' + 'a'.repeat(2050);
+    expect(sanitizeHttpUrl(long)).toBe('');
+  });
+
+  it('rejects a hostname without a dot', () => {
+    expect(sanitizeHttpUrl('https://localhost/')).toBe('');
+  });
+
+  it('rejects non-string input', () => {
+    expect(sanitizeHttpUrl(null)).toBe('');
+    expect(sanitizeHttpUrl(undefined)).toBe('');
+    expect(sanitizeHttpUrl(42)).toBe('');
+  });
+
+  it('rejects an unparseable value', () => {
+    expect(sanitizeHttpUrl('::::')).toBe('');
+  });
+});
+
+// ── webAddressSchema ────────────────────────────────────────────
+
+describe('webAddressSchema', () => {
+  it.each(['', 'foxhome.hu', 'www.foxhome.hu', 'https://foxhome.hu'])(
+    'accepts: %s',
+    (v) => {
+      expect(webAddressSchema.safeParse(v).success).toBe(true);
+    },
+  );
+
+  it.each(['javascript:alert(1)', 'mailto:a@b.c', 'not a url'])(
+    'rejects: %s',
+    (v) => {
+      expect(webAddressSchema.safeParse(v).success).toBe(false);
+    },
+  );
+});
+
+// ── socialLinksSchema ───────────────────────────────────────────
+
+describe('socialLinksSchema', () => {
+  it('sanitizes every link field to a safe https URL or empty', () => {
+    const out = socialLinksSchema.parse({
+      facebook: 'https://facebook.com/foxhome',
+      linkedin: 'javascript:alert(1)',
+      instagram: '',
+      x: 'http://x.com/foxhome', // upgraded
+      youtube: 'youtube.com/@channel',
+      tiktok: undefined,
+      customUrl: '<script>x</script>https://foo.bar',
+      customUrlLabel: '<b>My link</b>',
+    });
+    expect(out.facebook).toBe('https://facebook.com/foxhome');
+    expect(out.linkedin).toBe('');
+    expect(out.instagram).toBe('');
+    expect(out.x.startsWith('https://')).toBe(true);
+    expect(out.youtube).toBe('https://youtube.com/@channel');
+    expect(out.tiktok).toBe('');
+    expect(out.customUrl).not.toMatch(/script/i);
+    expect(out.customUrlLabel).toBe('My link'); // tags stripped, kept
+  });
+});
+
+// ── userDataSchema ──────────────────────────────────────────────
+
+describe('userDataSchema / validateUserData', () => {
+  it('accepts a well-formed payload', () => {
+    const r = validateUserData(validUserData);
+    expect(r.success).toBe(true);
+  });
+
+  it('requires email', () => {
+    const r = validateUserData({ ...validUserData, email: 'not-an-email' });
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.errors.email).toBeDefined();
+  });
+
+  it('rejects an invalid phone format', () => {
+    const r = validateUserData({ ...validUserData, phone: 'abcdef' });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects an oversized firstName', () => {
+    const r = validateUserData({
+      ...validUserData,
+      firstName: 'a'.repeat(101),
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('accepts empty optional fields', () => {
+    const r = validateUserData({
+      email: 'a@b.co',
+      firstName: '',
+      lastName: '',
+      phone: '',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects a website with javascript: scheme', () => {
+    const r = validateUserData({
+      ...validUserData,
+      website: 'javascript:alert(1)',
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── materialSchema ──────────────────────────────────────────────
+
+describe('materialSchema', () => {
+  // Mirrors the Material union in @nfcard/types. `wood` was renamed to
+  // `bamboo` in FOXHOLE-685 / launch tiers Phase A — the schema must
+  // not accept the legacy value any more.
+  it.each(['plastic', '3dprint_standard', 'metal', 'bamboo'])(
+    'accepts %s',
+    (m) => {
+      expect(materialSchema.safeParse(m).success).toBe(true);
+    },
+  );
+
+  it.each(['wood', 'aluminium', '', 'BAMBOO'])('rejects %s', (m) => {
+    expect(materialSchema.safeParse(m).success).toBe(false);
+  });
+});
+
+// ── comboIdSchema ───────────────────────────────────────────────
+
+describe('comboIdSchema', () => {
+  it.each(['A1', 'A2', 'B1', 'B2', 'C1', 'C2', 'D1', 'D2', 'E1', 'E2'])(
+    'accepts %s',
+    (id) => {
+      expect(comboIdSchema.safeParse(id).success).toBe(true);
+    },
+  );
+
+  it('rejects unknown ids', () => {
+    expect(comboIdSchema.safeParse('Z9').success).toBe(false);
+    expect(comboIdSchema.safeParse('').success).toBe(false);
+  });
+});
+
+// ── cardElementsSchema ──────────────────────────────────────────
+
+describe('cardElementsSchema', () => {
+  it('requires every flag to be a boolean', () => {
+    expect(cardElementsSchema.safeParse(validCardElements).success).toBe(true);
+    expect(
+      cardElementsSchema.safeParse({ ...validCardElements, showName: 'yes' })
+        .success,
+    ).toBe(false);
+  });
+});
+
+// ── physicalConfigSchema ────────────────────────────────────────
+
+describe('physicalConfigSchema / validatePhysicalConfig', () => {
+  it('accepts a plastic config without a colour', () => {
+    expect(validatePhysicalConfig(validPhysicalConfig).success).toBe(true);
+  });
+
+  it('requires a colour for non-plastic materials', () => {
+    const r = validatePhysicalConfig({
+      ...validPhysicalConfig,
+      material: '3dprint_standard',
+    });
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.errors['colour']).toBeDefined();
+  });
+
+  it('accepts a non-plastic config with a valid hex colour', () => {
+    const r = validatePhysicalConfig({
+      ...validPhysicalConfig,
+      material: '3dprint_standard',
+      colour: '#F47B20',
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects a malformed hex colour', () => {
+    const r = validatePhysicalConfig({
+      ...validPhysicalConfig,
+      material: 'metal',
+      colour: 'red',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects a malformed qrTargetUrl', () => {
+    const r = validatePhysicalConfig({
+      ...validPhysicalConfig,
+      qrTargetUrl: 'not-a-url',
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── digitalConfigSchema ─────────────────────────────────────────
+
+describe('digitalConfigSchema / validateDigitalConfig', () => {
+  it('accepts the minimal happy path', () => {
+    expect(validateDigitalConfig(validDigitalConfig).success).toBe(true);
+  });
+
+  it('rejects a malformed accentColor', () => {
+    const r = validateDigitalConfig({
+      ...validDigitalConfig,
+      accentColor: 'orange',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects an unknown templateId', () => {
+    const r = validateDigitalConfig({
+      ...validDigitalConfig,
+      templateId: 'futuristic',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects an empty fontKey', () => {
+    const r = validateDigitalConfig({ ...validDigitalConfig, fontKey: '' });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── configurationCreateSchema ───────────────────────────────────
+
+describe('validateConfiguration', () => {
+  it('accepts a complete configuration', () => {
+    const r = validateConfiguration({
+      sessionId: '550e8400-e29b-41d4-a716-446655440000',
+      userData: validUserData,
+      physicalConfig: validPhysicalConfig,
+      digitalConfig: validDigitalConfig,
+      quantity: 5,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('defaults quantity to 1 when omitted', () => {
+    const r = configurationCreateSchema.safeParse({
+      sessionId: '550e8400-e29b-41d4-a716-446655440000',
+      userData: validUserData,
+      physicalConfig: validPhysicalConfig,
+      digitalConfig: validDigitalConfig,
+    });
+    expect(r.success).toBe(true);
+    if (r.success) expect(r.data.quantity).toBe(1);
+  });
+
+  it('rejects a non-uuid sessionId', () => {
+    const r = validateConfiguration({
+      sessionId: 'not-a-uuid',
+      userData: validUserData,
+      physicalConfig: validPhysicalConfig,
+      digitalConfig: validDigitalConfig,
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects quantity above 1000', () => {
+    const r = validateConfiguration({
+      sessionId: '550e8400-e29b-41d4-a716-446655440000',
+      userData: validUserData,
+      physicalConfig: validPhysicalConfig,
+      digitalConfig: validDigitalConfig,
+      quantity: 1001,
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+// ── profileCreateSchema ─────────────────────────────────────────
+
+describe('profileCreateSchema', () => {
+  it('accepts a minimal profile', () => {
+    const r = profileCreateSchema.safeParse({
+      label: 'Personal',
+      userData: { ...validUserData, email: '' }, // email optional on profiles
+      digitalConfig: validDigitalConfig,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an invalid accessPin (letters)', () => {
+    const r = profileCreateSchema.safeParse({
+      label: 'Personal',
+      userData: { ...validUserData, email: '' },
+      digitalConfig: validDigitalConfig,
+      accessPin: 'abcd',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects too-short accessPin', () => {
+    const r = profileCreateSchema.safeParse({
+      label: 'Personal',
+      userData: { ...validUserData, email: '' },
+      digitalConfig: validDigitalConfig,
+      accessPin: '12',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects missing label', () => {
+    const r = profileCreateSchema.safeParse({
+      userData: { ...validUserData, email: '' },
+      digitalConfig: validDigitalConfig,
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe('profileVisibilitySchema', () => {
+  it.each(['public', 'private', 'link_only'])('accepts %s', (v) => {
+    expect(profileVisibilitySchema.safeParse(v).success).toBe(true);
+  });
+
+  it('does NOT accept pending_verification from user input', () => {
+    // FOXHOLE-684: server-managed state, never accepted from a request.
+    expect(profileVisibilitySchema.safeParse('pending_verification').success).toBe(
+      false,
+    );
+  });
+});
+
+// ── signupWithProfileSchema ─────────────────────────────────────
+
+describe('signupWithProfileSchema', () => {
+  const baseSignup = {
+    email: 'a@b.co',
+    password: 'longenough',
+    acceptedTerms: true,
+    userData: { ...validUserData, email: '' },
+    digitalConfig: validDigitalConfig,
+  };
+
+  it('accepts a valid signup body', () => {
+    expect(signupWithProfileSchema.safeParse(baseSignup).success).toBe(true);
+  });
+
+  it('rejects acceptedTerms: false', () => {
+    const r = signupWithProfileSchema.safeParse({
+      ...baseSignup,
+      acceptedTerms: false,
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('rejects a too-short password', () => {
+    const r = signupWithProfileSchema.safeParse({
+      ...baseSignup,
+      password: 'short',
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it('defaults preferredLanguage to hu', () => {
+    const r = signupWithProfileSchema.safeParse(baseSignup);
+    expect(r.success).toBe(true);
+    if (r.success) expect(r.data.preferredLanguage).toBe('hu');
+  });
+});
+
+// ── createOrderSchema ───────────────────────────────────────────
+
+describe('createOrderSchema', () => {
+  it('accepts a uuid configurationId', () => {
+    expect(
+      createOrderSchema.safeParse({
+        configurationId: '550e8400-e29b-41d4-a716-446655440000',
+      }).success,
+    ).toBe(true);
+  });
+
+  it('rejects a non-uuid configurationId', () => {
+    expect(
+      createOrderSchema.safeParse({ configurationId: 'not-a-uuid' }).success,
+    ).toBe(false);
+  });
+
+  it('accepts an optional discountCode', () => {
+    const r = createOrderSchema.safeParse({
+      configurationId: '550e8400-e29b-41d4-a716-446655440000',
+      discountCode: 'SUMMER10',
+    });
+    expect(r.success).toBe(true);
+  });
+});
+
+// ── contactExchangeSchema ───────────────────────────────────────
+
+describe('contactExchangeSchema', () => {
+  it('accepts name + email + phone', () => {
+    expect(
+      contactExchangeSchema.safeParse({
+        name: 'Anna',
+        email: 'a@b.co',
+        phone: '+36 20 123 4567',
+      }).success,
+    ).toBe(true);
+  });
+
+  it('requires name', () => {
+    expect(
+      contactExchangeSchema.safeParse({ email: 'a@b.co' }).success,
+    ).toBe(false);
+  });
+
+  it('accepts name only (email + phone optional)', () => {
+    expect(contactExchangeSchema.safeParse({ name: 'Anna' }).success).toBe(
+      true,
+    );
+  });
+
+  it('rejects a malformed email', () => {
+    expect(
+      contactExchangeSchema.safeParse({ name: 'Anna', email: 'not-an-email' })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects an oversized notes field', () => {
+    expect(
+      contactExchangeSchema.safeParse({
+        name: 'Anna',
+        notes: 'a'.repeat(501),
+      }).success,
+    ).toBe(false);
+  });
+});
+
+// ── hubConfigSchema ─────────────────────────────────────────────
+
+describe('hubConfigSchema', () => {
+  it('accepts an empty config (every field optional)', () => {
+    expect(hubConfigSchema.safeParse({}).success).toBe(true);
+  });
+
+  it('accepts a fully-populated config', () => {
+    expect(
+      hubConfigSchema.safeParse({
+        displayName: 'Foxhole',
+        subtitle: 'Cards',
+        avatarMode: 'monogram',
+        avatarUrl: 'https://cdn/x.png',
+        monogramText: 'FX',
+        accentColor: '#F47B20',
+        backgroundColor: '#FFFFFF',
+        textColor: '#000000',
+        tileBackgroundColor: '#EEEEEE',
+        tileBorderColor: '#CCCCCC',
+        fontKey: 'inter',
+        footerText: 'Powered by Foxhole',
+      }).success,
+    ).toBe(true);
+  });
+
+  it('rejects a malformed hex colour', () => {
+    expect(
+      hubConfigSchema.safeParse({ accentColor: 'orange' }).success,
+    ).toBe(false);
+  });
+
+  it.each([
+    'javascript:alert(1)',
+    'data:text/html,<script>alert(1)</script>',
+    'vbscript:msgbox(1)',
+    'file:///etc/passwd',
+    'mailto:a@b.c',
+    'ftp://foxhome.hu',
+  ])('rejects avatarUrl with non-http(s) scheme: %s', (avatarUrl) => {
+    expect(hubConfigSchema.safeParse({ avatarUrl }).success).toBe(false);
+  });
+
+  it('accepts a plain https avatarUrl', () => {
+    expect(
+      hubConfigSchema.safeParse({ avatarUrl: 'https://cdn/x.png' }).success,
+    ).toBe(true);
+  });
+
+  it('accepts an empty avatarUrl', () => {
+    expect(hubConfigSchema.safeParse({ avatarUrl: '' }).success).toBe(true);
+  });
+});