@nfcard/validation 0.22.2 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.22.2",
+  "version": "0.24.0",
   "description": "Shared Zod validation schemas for the NFCard product family.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@nfcard/types": "0.16.1"
+    "@nfcard/types": "0.18.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/profileBackground.test.ts

@@ -0,0 +1,116 @@
+/**
+ * NFCARD-641 (564d/S4) Phase 1 — the profile background write gate.
+ *
+ * Lenient by design, like tipJar/booking/ctaButtons: a malformed background is
+ * dropped to `undefined` rather than 400-ing the whole profile save. The tests
+ * that matter are therefore the ones proving it drops rather than *mangles* —
+ * a half-applied gradient would render as a surprise nobody asked for.
+ */
+import { describe, expect, it } from 'vitest'
+import { digitalConfigSchema, profileBackgroundSchema } from './index'
+
+const base = {
+  templateId: 'classic' as const,
+  accentColor: '#F47B20',
+  fontKey: 'inter',
+  showAvatar: true,
+}
+
+describe('profileBackgroundSchema', () => {
+  it('accepts a solid background', () => {
+    expect(profileBackgroundSchema.parse({ kind: 'solid' })).toEqual({ kind: 'solid' })
+  })
+
+  it('accepts a two-stop gradient and keeps both stops', () => {
+    expect(
+      profileBackgroundSchema.parse({ kind: 'gradient', from: '#101820', to: '#F47B20' }),
+    ).toEqual({ kind: 'gradient', from: '#101820', to: '#F47B20' })
+  })
+
+  it('🔴 drops a HALF-valid gradient rather than inventing the missing stop', () => {
+    // Storing `{from}` with no `to` would render as a gradient to… something.
+    // Both stops or nothing.
+    expect(profileBackgroundSchema.parse({ kind: 'gradient', from: '#101820' })).toBeUndefined()
+    expect(profileBackgroundSchema.parse({ kind: 'gradient', to: '#101820' })).toBeUndefined()
+    expect(
+      profileBackgroundSchema.parse({ kind: 'gradient', from: '#101820', to: 'red' }),
+    ).toBeUndefined()
+    expect(
+      profileBackgroundSchema.parse({ kind: 'gradient', from: 'nothex', to: '#101820' }),
+    ).toBeUndefined()
+  })
+
+  it('🔴 rejects any non-hex stop — nothing user-typed reaches the CSS', () => {
+    for (const hostile of [
+      'red',
+      '#fff',
+      '#1018200',
+      'var(--brand)',
+      'url(javascript:alert(1))',
+      '#101820; background: url(x)',
+      'rgb(0,0,0)',
+    ]) {
+      expect(
+        profileBackgroundSchema.parse({ kind: 'gradient', from: hostile, to: '#101820' }),
+        hostile,
+      ).toBeUndefined()
+    }
+  })
+
+  it('normalises the angle into [0,360) so the render never defends against it', () => {
+    const at = (angleDeg: unknown) =>
+      profileBackgroundSchema.parse({ kind: 'gradient', from: '#101820', to: '#F47B20', angleDeg })
+    expect(at(160)).toMatchObject({ angleDeg: 160 })
+    expect(at(0)).toMatchObject({ angleDeg: 0 })
+    expect(at(-40)).toMatchObject({ angleDeg: 320 })
+    expect(at(400)).toMatchObject({ angleDeg: 40 })
+    expect(at(160.4)).toMatchObject({ angleDeg: 160 })
+    // Not a usable number → omit the key entirely and let the render default.
+    for (const bad of ['160', NaN, Infinity, null, {}]) {
+      expect(at(bad), String(bad)).not.toHaveProperty('angleDeg')
+    }
+  })
+
+  it('drops an unknown kind, and anything that is not an object', () => {
+    expect(profileBackgroundSchema.parse({ kind: 'image', url: 'https://x/y.png' })).toBeUndefined()
+    expect(profileBackgroundSchema.parse({ kind: 'gradient' })).toBeUndefined()
+    for (const v of [null, undefined, 'gradient', 42, []]) {
+      expect(profileBackgroundSchema.parse(v), String(v)).toBeUndefined()
+    }
+  })
+
+  it('does not yet accept an image — that is NFCARD-645', () => {
+    // Pinned deliberately: shipping the type without the sanitiser would be an
+    // unguarded URL on the render path.
+    expect(
+      profileBackgroundSchema.parse({ kind: 'image', url: 'https://cdn.example.com/a.jpg' }),
+    ).toBeUndefined()
+  })
+})
+
+describe('digitalConfigSchema × background', () => {
+  it('every profile that exists today still validates — background is optional', () => {
+    const parsed = digitalConfigSchema.parse(base)
+    expect(parsed.background).toBeUndefined()
+  })
+
+  it('carries a valid gradient through', () => {
+    const parsed = digitalConfigSchema.parse({
+      ...base,
+      background: { kind: 'gradient', from: '#101820', to: '#F47B20', angleDeg: 160 },
+    })
+    expect(parsed.background).toEqual({
+      kind: 'gradient',
+      from: '#101820',
+      to: '#F47B20',
+      angleDeg: 160,
+    })
+  })
+
+  it('a malformed background does not fail the whole save', () => {
+    // The lenient contract: the profile still saves, minus the background.
+    const parsed = digitalConfigSchema.parse({ ...base, background: { kind: 'gradient', from: 'x' } })
+    expect(parsed.background).toBeUndefined()
+    expect(parsed.templateId).toBe('classic')
+  })
+})

package/src/profileLayout.test.ts

@@ -0,0 +1,158 @@
+/**
+ * NFCARD-656 — write-side guards for `DigitalConfig.layout`.
+ *
+ * The abuse cases matter more than the happy path here: every style value
+ * eventually composes into a CSS rule block, so the assertion of record is
+ * "nothing non-primitive survives the schema", with the injection-shaped
+ * strings spelled out.
+ */
+import { describe, expect, it } from 'vitest'
+import { CANONICAL_OBJECT_ORDER, ctaObjectIndex, type ProfileLayout } from '@nfcard/types'
+import { MAX_CTA_BUTTONS, digitalConfigSchema } from './index'
+import { profileLayoutSchema, safeProfileLayout } from './profileLayout'
+
+const okLayout: ProfileLayout = {
+  v: 1,
+  sectionOrder: ['identity', 'social', 'contact', 'bio', 'actions', 'cta', 'footer'],
+  objectOrder: {
+    social: ['social-x', 'social-linkedin'],
+    actions: ['act-share', 'act-save', 'act-exchange'],
+  },
+  objects: {
+    name: { style: { color: '#112233', sizeStep: 'lg', weight: 'bold' } },
+    avatar: { style: { crop: { x: 0.5, y: 0.25, zoom: 1.6 }, borderColor: '#ffffff', borderPx: 3 } },
+    'cta-0': { style: { bg: '#16a34a', variant: 'solid' } },
+    booking: { style: { variant: 'outline' } },
+  },
+  ownedObjects: [{ id: 'ft-abcd', kind: 'freeText', section: 'bio', text: 'Hello there' }],
+}
+
+describe('profileLayoutSchema — accepts real intent', () => {
+  it('parses a full document and the result is a ProfileLayout', () => {
+    const parsed = profileLayoutSchema.parse(okLayout)
+    const typed: ProfileLayout = parsed
+    expect(typed.objectOrder?.social).toEqual(['social-x', 'social-linkedin'])
+  })
+
+  it('parses the boring derived document and the empty-intent forms', () => {
+    expect(profileLayoutSchema.parse({ v: 1 })).toEqual({ v: 1 })
+    expect(profileLayoutSchema.safeParse({ v: 1, objectOrder: {} }).success).toBe(true)
+  })
+
+  it('order entries tolerate well-formed ids this vintage does not know (skew safety)', () => {
+    const r = profileLayoutSchema.safeParse({
+      v: 1,
+      objectOrder: { social: ['social-threads', 'social-x'] },
+    })
+    expect(r.success).toBe(true)
+  })
+})
+
+describe('profileLayoutSchema — rejects abuse', () => {
+  const bad = (layout: unknown) => profileLayoutSchema.safeParse(layout).success
+
+  it('version and unknown keys', () => {
+    expect(bad({ v: 2 })).toBe(false)
+    expect(bad({ v: 1, extra: true })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: {}, accent: {} } } })).toBe(false)
+  })
+
+  it('sectionOrder: duplicates and unknown sections', () => {
+    expect(bad({ v: 1, sectionOrder: ['social', 'social'] })).toBe(false)
+    expect(bad({ v: 1, sectionOrder: ['hero'] })).toBe(false)
+  })
+
+  it('objectOrder: malformed ids and oversize lists', () => {
+    expect(bad({ v: 1, objectOrder: { social: ['a.b'] } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { social: ['x'.repeat(33)] } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { social: Array.from({ length: 25 }, (_, i) => `id-${i}`) } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { unknownSection: ['social-x'] } })).toBe(false)
+  })
+
+  it('objects: unknown ids, non-stylable kinds, injection-shaped values', () => {
+    expect(bad({ v: 1, objects: { 'not-a-thing': { style: {} } } })).toBe(false)
+    // contactRow is arrangeable but not stylable in v1 — storing a style the
+    // render never reads is the defect, not a feature.
+    expect(bad({ v: 1, objects: { 'contact-email': { style: { bg: '#112233' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { color: 'red;}{' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { color: '#12345' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { avatar: { style: { borderPx: 99 } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { avatar: { style: { crop: { x: 0.5, y: 0.5, zoom: 9 } } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { 'cta-0': { style: { bg: 'url(javascript:1)' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { fontKey: '../evil' } } } })).toBe(false)
+  })
+
+  it('objects: the override cap and the distinct-font cap', () => {
+    const many = Object.fromEntries(
+      Array.from({ length: 65 }, (_, i) => [`ft-over${String(i).padStart(4, '0')}`, { style: {} }]),
+    )
+    expect(bad({ v: 1, objects: many })).toBe(false)
+
+    const fonts = Object.fromEntries(
+      ['name', 'role', 'bio', 'ft-aaaa', 'ft-bbbb'].map((id, i) => [
+        id,
+        { style: { fontKey: `font-${i}` } },
+      ]),
+    )
+    expect(bad({ v: 1, objects: fonts })).toBe(false)
+  })
+
+  it('ownedObjects: caps, duplicate ids, non-hosting sections, dissolving text', () => {
+    const ft = (id: string, section = 'bio', text = 'ok') => ({ id, kind: 'freeText', section, text })
+    expect(bad({ v: 1, ownedObjects: Array.from({ length: 6 }, (_, i) => ft(`ft-num${i}x`)) })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd'), ft('ft-abcd')] })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd', 'contact')] })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd', 'bio', '<b></b>')] })).toBe(false)
+  })
+
+  it('freeText text is sanitised, not just bounded', () => {
+    const r = profileLayoutSchema.parse({
+      v: 1,
+      ownedObjects: [
+        { id: 'ft-abcd', kind: 'freeText', section: 'bio', text: '  <b>Szia</b> világ  ' },
+      ],
+    })
+    expect(r.ownedObjects?.[0].text).toBe('Szia világ')
+  })
+})
+
+describe('digitalConfigSchema integration', () => {
+  const baseConfig = {
+    templateId: 'classic',
+    accentColor: '#16a34a',
+    fontKey: 'inter',
+    showAvatar: true,
+  }
+
+  it('validates existing profiles unchanged (no layout key)', () => {
+    expect(digitalConfigSchema.safeParse(baseConfig).success).toBe(true)
+  })
+
+  it('accepts and KEEPS a valid layout — the strip-mode guard the web store needs', () => {
+    const r = digitalConfigSchema.parse({ ...baseConfig, layout: okLayout })
+    expect(r.layout?.objectOrder?.social).toEqual(['social-x', 'social-linkedin'])
+  })
+
+  it('rejects a config whose layout is malformed rather than silently dropping it', () => {
+    expect(digitalConfigSchema.safeParse({ ...baseConfig, layout: { v: 7 } }).success).toBe(false)
+  })
+})
+
+describe('safeProfileLayout (render-side gate)', () => {
+  it('null/undefined/garbage → null; valid → data', () => {
+    expect(safeProfileLayout(undefined)).toBeNull()
+    expect(safeProfileLayout(null)).toBeNull()
+    expect(safeProfileLayout('layout')).toBeNull()
+    expect(safeProfileLayout({ v: 2 })).toBeNull()
+    expect(safeProfileLayout({ v: 1 })).toEqual({ v: 1 })
+  })
+})
+
+describe('cross-package constants stay in lockstep', () => {
+  it('CANONICAL_OBJECT_ORDER.cta carries exactly MAX_CTA_BUTTONS cta slots', () => {
+    // types cannot import validation, so the canonical array hard-codes five
+    // slots; this is the test that keeps the two declarations honest.
+    const ctaSlots = CANONICAL_OBJECT_ORDER.cta.filter((id) => ctaObjectIndex(id) !== null)
+    expect(ctaSlots.length).toBe(MAX_CTA_BUTTONS)
+  })
+})

package/src/profileLayout.ts

@@ -0,0 +1,265 @@
+/**
+ * NFCARD-656 — the write-side schema for `DigitalConfig.layout`, the stored
+ * object/section document. The vocabulary (section ids, object ids, kinds,
+ * caps) lives in @nfcard/types; this file only decides what a WRITE may
+ * contain.
+ *
+ * Posture, and why it differs between the two order surfaces:
+ *  · `objects` (style overrides) is STRICT — every key must name an object
+ *    this schema's vintage knows, because styles are rendered into CSS and
+ *    an un-dispatchable style cannot be validated per kind. Version skew is
+ *    covered by the deploy order (api ships before web, so the accepting
+ *    schema is never older than the writing client).
+ *  · `sectionOrder` / `objectOrder` entries are validated by SHAPE only
+ *    (charset + length). An order entry naming nothing is harmless by
+ *    construction — `resolveObjectOrder` filters to what is present at
+ *    render — and rejecting it would turn "the user once ordered a thing
+ *    that later disappeared" into a 400 on an unrelated save.
+ *
+ * ⚠ NOT the XSS boundary. FreeText is rendered through Nunjucks with
+ * autoescape ON (FOXHOLE-587); the hygiene here (tag/control strip, caps)
+ * is defense-in-depth, same standing as the rest of @nfcard/validation.
+ */
+import { z } from 'zod'
+import {
+  MAX_DISTINCT_OBJECT_FONTS,
+  MAX_FREE_TEXT_LENGTH,
+  MAX_LAYOUT_OBJECT_OVERRIDES,
+  MAX_OBJECT_ORDER_LENGTH,
+  MAX_OWNED_OBJECTS,
+  FREE_TEXT_ID_RE,
+  PROFILE_SECTIONS,
+  PROFILE_SECTION_IDS,
+  objectKindOf,
+  type ProfileLayout,
+  type ProfileObjectKind,
+  type ProfileSectionId,
+} from '@nfcard/types'
+// ⚠ Deliberate import cycle (index.ts imports this file for
+// `digitalConfigSchema.layout`). It is init-safe: `sanitizeText` is a
+// hoisted function DECLARATION referenced only inside parse-time closures,
+// never called while modules initialise. Importing it beats re-implementing
+// it — a second, weaker copy of a sanitizer is the recurring 624/626/627
+// failure mode.
+import { sanitizeText } from './index'
+
+const HEX_RE = /^#[0-9A-Fa-f]{6}$/
+
+/** Order entries and override keys share the token grammar's id budget. */
+const OBJECT_ID_SHAPE_RE = /^[A-Za-z0-9_-]{1,32}$/
+
+export const textObjectStyleSchema = z
+  .object({
+    color: z.string().regex(HEX_RE).optional(),
+    sizeStep: z.enum(['sm', 'md', 'lg']).optional(),
+    align: z.enum(['start', 'center']).optional(),
+    weight: z.enum(['normal', 'bold']).optional(),
+    italic: z.boolean().optional(),
+    underline: z.boolean().optional(),
+    // Resolved through the api's font map at render; an unknown key falls
+    // back to the template pairing, so membership is not validated here.
+    fontKey: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[A-Za-z0-9-]+$/)
+      .optional(),
+  })
+  .strict()
+
+export const imageObjectStyleSchema = z
+  .object({
+    crop: z
+      .object({
+        x: z.number().min(0).max(1),
+        y: z.number().min(0).max(1),
+        zoom: z.number().min(1).max(3),
+      })
+      .strict()
+      .optional(),
+    borderColor: z.string().regex(HEX_RE).optional(),
+    borderPx: z.number().int().min(0).max(8).optional(),
+    shape: z.enum(['circle', 'rounded', 'square']).optional(),
+  })
+  .strict()
+
+export const buttonObjectStyleSchema = z
+  .object({
+    bg: z.string().regex(HEX_RE).optional(),
+    variant: z.enum(['solid', 'soft', 'outline']).optional(),
+  })
+  .strict()
+
+/**
+ * Which style vocabulary each kind accepts. `contactRow` and `socialLink`
+ * are deliberately ABSENT in v1: no template renders a style for them yet,
+ * and a schema that stores what the server never reads is the EditTextSheet
+ * lesson in write form. Additive to extend.
+ */
+const STYLE_SCHEMA_FOR_KIND: Partial<Record<ProfileObjectKind, z.ZodTypeAny>> = {
+  text: textObjectStyleSchema,
+  freeText: textObjectStyleSchema,
+  image: imageObjectStyleSchema,
+  ctaButton: buttonObjectStyleSchema,
+  linkOut: buttonObjectStyleSchema,
+  action: buttonObjectStyleSchema,
+}
+
+const orderListSchema = z
+  .array(z.string().regex(OBJECT_ID_SHAPE_RE))
+  .max(MAX_OBJECT_ORDER_LENGTH)
+
+const freeTextObjectSchema = z
+  .object({
+    id: z.string().regex(FREE_TEXT_ID_RE),
+    kind: z.literal('freeText'),
+    section: z.enum(PROFILE_SECTION_IDS),
+    text: z
+      .string()
+      .max(2000) // raw guard; the transform caps to the real bound below
+      .transform((v) => sanitizeText(v, MAX_FREE_TEXT_LENGTH)),
+  })
+  .strict()
+
+export const profileLayoutSchema = z
+  .object({
+    v: z.literal(1),
+    sectionOrder: z
+      .array(z.enum(PROFILE_SECTION_IDS))
+      .max(PROFILE_SECTION_IDS.length)
+      .optional(),
+    objectOrder: z
+      .object(
+        Object.fromEntries(
+          PROFILE_SECTION_IDS.map((id) => [id, orderListSchema.optional()]),
+        ) as Record<ProfileSectionId, z.ZodOptional<typeof orderListSchema>>,
+      )
+      .strict()
+      .partial()
+      .optional(),
+    objects: z.record(z.string().regex(OBJECT_ID_SHAPE_RE), z.unknown()).optional(),
+    ownedObjects: z.array(freeTextObjectSchema).max(MAX_OWNED_OBJECTS).optional(),
+  })
+  .strict()
+  .superRefine((layout, ctx) => {
+    // A duplicated section is a client bug — loud beats silently reordered.
+    if (layout.sectionOrder) {
+      const seen = new Set(layout.sectionOrder)
+      if (seen.size !== layout.sectionOrder.length) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['sectionOrder'],
+          message: 'duplicate section id',
+        })
+      }
+    }
+
+    if (layout.objects) {
+      const keys = Object.keys(layout.objects)
+      if (keys.length > MAX_LAYOUT_OBJECT_OVERRIDES) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['objects'],
+          message: `more than ${MAX_LAYOUT_OBJECT_OVERRIDES} overrides`,
+        })
+        return
+      }
+      const fonts = new Set<string>()
+      for (const key of keys) {
+        const kind = objectKindOf(key)
+        if (!kind) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key],
+            message: 'unknown object id',
+          })
+          continue
+        }
+        const styleSchema = STYLE_SCHEMA_FOR_KIND[kind]
+        const override = layout.objects[key]
+        const overrideParsed = z
+          .object({ style: z.unknown().optional() })
+          .strict()
+          .safeParse(override)
+        if (!overrideParsed.success) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key],
+            message: 'override must be { style? }',
+          })
+          continue
+        }
+        const style = overrideParsed.data.style
+        if (style === undefined) continue
+        if (!styleSchema) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key, 'style'],
+            message: `kind '${kind}' is not stylable`,
+          })
+          continue
+        }
+        const parsed = styleSchema.safeParse(style)
+        if (!parsed.success) {
+          for (const issue of parsed.error.issues) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ['objects', key, 'style', ...issue.path],
+              message: issue.message,
+            })
+          }
+          continue
+        }
+        const fontKey = (parsed.data as { fontKey?: string }).fontKey
+        if (fontKey) fonts.add(fontKey)
+      }
+      if (fonts.size > MAX_DISTINCT_OBJECT_FONTS) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['objects'],
+          message: `more than ${MAX_DISTINCT_OBJECT_FONTS} distinct fonts`,
+        })
+      }
+    }
+
+    if (layout.ownedObjects) {
+      const ids = new Set<string>()
+      layout.ownedObjects.forEach((obj, i) => {
+        if (ids.has(obj.id)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'id'],
+            message: 'duplicate freeText id',
+          })
+        }
+        ids.add(obj.id)
+        if (!PROFILE_SECTIONS[obj.section].hosts.includes('freeText')) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'section'],
+            message: `section '${obj.section}' does not host freeText`,
+          })
+        }
+        if (obj.text.length === 0) {
+          // Post-sanitise emptiness: a tags-only submission dissolves here.
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'text'],
+            message: 'empty after sanitisation',
+          })
+        }
+      })
+    }
+  })
+
+/**
+ * Render-side gate: a stored layout that no longer parses (a vintage this
+ * build predates, a hand-corrupted blob) renders as CANONICAL rather than
+ * failing the whole page. Mirrors the lenient posture of
+ * `resolveRenderBackground` — the public page never 500s over decoration.
+ */
+export function safeProfileLayout(value: unknown): ProfileLayout | null {
+  if (value === undefined || value === null) return null
+  const parsed = profileLayoutSchema.safeParse(value)
+  return parsed.success ? (parsed.data as ProfileLayout) : null
+}