@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/contracts/base.ts

@@ -0,0 +1,107 @@
+import { VerificationConfigSchema, type VerificationConfig } from './verificationConfig'
+import { PublicAskAiWidgetSettingsSchema, type AskAiWidgetSettings } from './askAiSettings'
+import { z } from 'zod'
+import { PublicConsentInstallationSchema, type ConsentInstallation } from './consent'
+import { PublicFeedbackWidgetSettingsSchema, type FeedbackWidgetSettings } from './feedbackSettings'
+
+/** Visitor-feature wire version; independent of bridge and Site Kit package versions. */
+export const FEATURE_CONTRACT_VERSION = 1
+
+export type FeatureKey = 'search' | 'askAi' | 'feedback' | 'consent'
+export type PageContext = { path: string; title?: string }
+export type FeatureFlags = Record<FeatureKey, boolean>
+export type PublicFeatureBase = {
+  version: 1
+  verification?: VerificationConfig
+  revision: number
+  enabled: FeatureFlags
+  askAi?: AskAiWidgetSettings
+  feedback?: FeedbackWidgetSettings
+  consent?: ConsentInstallation
+}
+export type FeatureErrorCode =
+  | 'invalid_request'
+  | 'unauthorized'
+  | 'verification_required'
+  | 'forbidden'
+  | 'not_found'
+  | 'conflict'
+  | 'too_large'
+  | 'rate_limited'
+  | 'budget_exceeded'
+  | 'unavailable'
+  | 'incompatible_version'
+export type FeatureError = {
+  version: 1
+  error: { code: FeatureErrorCode; message: string; requestId: string; retryAfter?: number }
+}
+
+export const FeatureFlagsSchema = z.strictObject({
+  search: z.boolean().default(false),
+  askAi: z.boolean().default(false),
+  feedback: z.boolean().default(false),
+  consent: z.boolean().default(false),
+})
+
+const PAGE_ORIGIN = 'https://page-context.invalid'
+const isRelativePath = (path: string): boolean =>
+  path.startsWith('/') && !path.startsWith('//') && !/[\\\u0000-\u001f\u007f-\u009f]/.test(path)
+
+const PagePathSchema = z
+  .string()
+  .max(2048)
+  .refine(
+    isRelativePath,
+    'Expected a root-relative path without backslashes or control characters.',
+  )
+  .transform((path) => new URL(path, PAGE_ORIGIN).pathname)
+  .pipe(z.string().max(2048).refine(isRelativePath, 'Expected a root-relative pathname.'))
+
+/** Request context is strict: callers cannot smuggle tenant identity or other reserved fields. */
+export const PageContextSchema = z.strictObject({
+  path: PagePathSchema,
+  title: z.string().max(200).optional(),
+})
+
+/** Readers tolerate additive response fields, while validating every known field. */
+export const PublicFeatureBaseSchema = z.looseObject({
+  version: z.literal(FEATURE_CONTRACT_VERSION),
+  revision: z.int().nonnegative(),
+  verification: VerificationConfigSchema.optional(),
+  enabled: FeatureFlagsSchema.loose(),
+  askAi: PublicAskAiWidgetSettingsSchema.optional(),
+  feedback: PublicFeedbackWidgetSettingsSchema.optional(),
+  consent: PublicConsentInstallationSchema.optional(),
+  readiness: z
+    .object({
+      search: z.object({
+        ready: z.boolean(),
+        state: z.enum(['setup', 'ready', 'indexing', 'failed', 'snapshot']),
+      }),
+    })
+    .optional(),
+})
+
+export const FeatureErrorCodeSchema = z.enum([
+  'invalid_request',
+  'unauthorized',
+  'verification_required',
+  'forbidden',
+  'not_found',
+  'conflict',
+  'too_large',
+  'rate_limited',
+  'budget_exceeded',
+  'unavailable',
+  'incompatible_version',
+])
+
+export const FeatureErrorSchema = z.looseObject({
+  version: z.literal(FEATURE_CONTRACT_VERSION),
+  error: z.looseObject({
+    code: FeatureErrorCodeSchema,
+    message: z.string(),
+    requestId: z.string(),
+    retryAfter: z.number().nonnegative().optional(),
+  }),
+})

package/src/features/contracts/consent.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod'
+
+export type ConsentState = {
+  version: 1
+  necessary: true
+  preferences: boolean
+  analytics: boolean
+  marketing: boolean
+  ready: boolean
+}
+export type ConsentAdapter = {
+  read(): ConsentState
+  subscribe(listener: (state: ConsentState) => void): () => void
+  openPreferences(): void
+}
+export type ConsentCategory = 'preferences' | 'analytics' | 'marketing'
+export type ManagedIntegration = {
+  id: string
+  src: string
+  category: ConsentCategory
+  attributes?: Record<string, string>
+  revocation: 'stop' | 'reload'
+}
+export type ConsentInstallation = {
+  provider: 'none' | 'cookiescript' | 'custom'
+  scriptURL?: string
+  integrations: ManagedIntegration[]
+  googleMode: 'basic' | 'advanced'
+}
+export type IntegrationDriver = {
+  start(integration: ManagedIntegration): Promise<void>
+  stop(id: string): Promise<'stopped' | 'reload-required'>
+}
+
+/** Always allocate a new snapshot so consumers cannot mutate shared denial. */
+export function deniedConsentState(): ConsentState {
+  return { version: 1, necessary: true, preferences: false, analytics: false, marketing: false, ready: false }
+}
+export const ConsentStateSchema = z.strictObject({
+  version: z.literal(1), necessary: z.literal(true),
+  preferences: z.boolean(), analytics: z.boolean(), marketing: z.boolean(), ready: z.boolean(),
+}).transform((state): ConsentState => state.ready ? state : deniedConsentState())
+
+/** URL parsing must not silently discard raw controls, fragments, or backslashes. */
+const HTTPSURLSchema = z.string().max(2048).refine((source) => {
+  if (/[\s\\#]/.test(source)) return false
+  try {
+    const url = new URL(source)
+    return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !source.includes('@')
+  } catch { return false }
+}, 'Expected an HTTPS URL without userinfo, fragments, whitespace or backslashes.')
+  .transform((source) => new URL(source).href)
+
+export function isCookieScriptURL(source: string): boolean {
+  const parsed = HTTPSURLSchema.safeParse(source)
+  return parsed.success && /^https:\/\/(?:cdn|dev-cdn)\.cookie-script\.com\/s\/[a-fA-F0-9]{32}\.js$/.test(parsed.data)
+}
+const ElementIdSchema = z.string().min(1).max(128).regex(/^[A-Za-z][A-Za-z0-9_:.-]*$/)
+// Only standard attributes are shipped. No data-* key is approved for this release.
+const AttributesSchema = z.strictObject({
+  id: ElementIdSchema.optional(),
+  charset: z.string().max(40).regex(/^[A-Za-z0-9._-]+$/).transform((value) => value.toLowerCase()).optional(),
+  crossorigin: z.enum(['anonymous', 'use-credentials']).optional(),
+  integrity: z.string().max(1024).refine((value) => value.split(' ').every((token) =>
+    /^sha256-[A-Za-z0-9+/]{43}=$/.test(token) ||
+    /^sha384-[A-Za-z0-9+/]{64}$/.test(token) ||
+    /^sha512-[A-Za-z0-9+/]{86}==$/.test(token)), 'Expected SHA-256, SHA-384 or SHA-512 SRI digests.').optional(),
+})
+const IntegrationFields = z.strictObject({
+  id: z.string().trim().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/),
+  src: HTTPSURLSchema,
+  category: z.enum(['preferences', 'analytics', 'marketing']),
+  attributes: AttributesSchema.optional(),
+  revocation: z.enum(['stop', 'reload']),
+})
+export const ManagedIntegrationSchema = IntegrationFields
+const InstallationFields = z.strictObject({
+  provider: z.enum(['none', 'cookiescript', 'custom']),
+  scriptURL: HTTPSURLSchema.optional(),
+  integrations: z.array(ManagedIntegrationSchema).max(100).default([]),
+  googleMode: z.enum(['basic', 'advanced']).default('basic'),
+})
+function validateInstallation(value: ConsentInstallation, context: z.RefinementCtx) {
+  if (value.provider !== 'none' && !value.scriptURL) {
+    context.addIssue({ code: 'custom', path: ['scriptURL'], message: 'An active provider requires an installation URL.' })
+  } else if (value.provider === 'none' && value.scriptURL) {
+    context.addIssue({ code: 'custom', path: ['scriptURL'], message: 'No provider cannot install a script.' })
+  } else if (value.provider === 'cookiescript' && !isCookieScriptURL(value.scriptURL!)) {
+    context.addIssue({ code: 'custom', path: ['scriptURL'], message: 'Use a direct global CookieScript production or staging installation; geographic wrappers are unsupported.' })
+  }
+  const ids = new Set<string>()
+  value.integrations.forEach((integration, index) => {
+    if (ids.has(integration.id)) context.addIssue({ code: 'custom', path: ['integrations', index, 'id'], message: 'Integration IDs must be unique within the site.' })
+    ids.add(integration.id)
+  })
+}
+export const ConsentInstallationSchema = InstallationFields.superRefine(validateInstallation)
+/** Readers tolerate additive fields but retain only known validated installation data. */
+export const PublicConsentInstallationSchema = InstallationFields.loose().extend({
+  integrations: z.array(IntegrationFields.loose().transform((row) => ManagedIntegrationSchema.parse({
+    id: row.id, src: row.src, category: row.category, revocation: row.revocation,
+    ...(row.attributes ? { attributes: row.attributes } : {}),
+  }))).max(100).default([]),
+}).superRefine(validateInstallation).transform((row) => ConsentInstallationSchema.parse({
+  provider: row.provider, ...(row.scriptURL ? { scriptURL: row.scriptURL } : {}),
+  integrations: row.integrations, googleMode: row.googleMode,
+}))
+
+export type ManagedIntegrationClassification =
+  | { kind: 'ga4'; measurementId: string }
+  | { kind: 'contentsquare'; tagId: string }
+  | { kind: 'custom' }
+/** Shared by permissions and drivers. Caller IDs and known hosts confer no authority. */
+export function classifyManagedIntegration(input: unknown): ManagedIntegrationClassification {
+  const parsed = ManagedIntegrationSchema.safeParse(input)
+  if (!parsed.success) return { kind: 'custom' }
+  const row = parsed.data
+  if (row.category !== 'analytics' ||
+    (row.attributes?.charset !== undefined && row.attributes.charset !== 'utf-8') ||
+    (row.attributes?.crossorigin !== undefined && row.attributes.crossorigin !== 'anonymous')) return { kind: 'custom' }
+  // The 1–32 suffix bound is a U90 supported-input limit, not vendor certification.
+  const ga = /^https:\/\/www\.googletagmanager\.com\/gtag\/js\?id=(G-[A-Z0-9]{1,32})$/.exec(row.src)
+  if (ga) return { kind: 'ga4', measurementId: ga[1] }
+  const cs = /^https:\/\/t\.contentsquare\.net\/uxa\/([a-f0-9]{13})\.js$/.exec(row.src)
+  if (cs && row.revocation === 'reload') return { kind: 'contentsquare', tagId: cs[1] }
+  return { kind: 'custom' }
+}
+
+function customConfiguration(installation?: ConsentInstallation): string {
+  if (!installation) return JSON.stringify({ provider: null, integrations: [] })
+  const normalized = ConsentInstallationSchema.parse(installation)
+  return JSON.stringify({
+    provider: normalized.provider === 'custom' ? normalized.scriptURL : null,
+    integrations: normalized.integrations.filter((row) => classifyManagedIntegration(row).kind === 'custom')
+      .sort((a, b) => a.id.localeCompare(b.id)).map((row) => ({
+        id: row.id, src: row.src, category: row.category, revocation: row.revocation,
+        attributes: Object.fromEntries(Object.entries(row.attributes ?? {}).sort(([a], [b]) => a.localeCompare(b))),
+      })),
+  })
+}
+export type ConsentConfiguration = { enabled: boolean; installation?: ConsentInstallation }
+/** The protected writer and all feature toggles must use this same before/after check. */
+export function consentChangeRequiresCodeWrite(before: ConsentConfiguration, after: ConsentConfiguration): boolean {
+  const oldCustom = customConfiguration(before.installation)
+  const newCustom = customConfiguration(after.installation)
+  const wasActive = before.enabled && !!before.installation && before.installation.provider !== 'none'
+  const willBeActive = after.enabled && !!after.installation && after.installation.provider !== 'none'
+  const activates = (!before.enabled && after.enabled) || (!wasActive && willBeActive)
+  return oldCustom !== newCustom || (activates && newCustom !== customConfiguration())
+}

package/src/features/contracts/feedback.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { PageContextSchema } from './base'
+
+export const FEEDBACK_FORM_KEY = 'feedback'
+export const FEEDBACK_FORM_SLUG = 'u90-feedback'
+
+/** Presentation may hide or relabel questions; their wire meanings remain fixed. */
+export const FeedbackInputSchema = z
+  .strictObject({
+    requestId: z.uuid(),
+    page: PageContextSchema,
+    rating: z
+      .union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)])
+      .optional(),
+    comment: z.string().trim().min(1).max(2000).optional(),
+  })
+  .refine((input) => input.rating !== undefined || input.comment !== undefined, {
+    message: 'Supply a rating or a useful comment.',
+  })
+
+export type FeedbackInput = z.output<typeof FeedbackInputSchema>
+export type FeedbackReceipt = { submissionId: string; receivedAt: string }

package/src/features/contracts/feedbackSettings.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+/** Stock presentation only: answer types and the five-point scale stay fixed. */
+const Fields = z.strictObject({
+  launcherLabel: z.string().trim().min(1).max(80).default('Feedback'),
+  title: z.string().trim().min(1).max(120).default('How was this page?'),
+  ratingLabel: z.string().trim().min(1).max(120).default('Rate this page'),
+  commentLabel: z.string().trim().min(1).max(120).default('Tell us more'),
+  commentPlaceholder: z.string().max(200).default('What worked well, or what could be better?'),
+  submitLabel: z.string().trim().min(1).max(80).default('Send feedback'),
+  successMessage: z.string().trim().min(1).max(200).default('Thank you for your feedback.'),
+  showRating: z.boolean().default(true),
+  showComment: z.boolean().default(true),
+})
+export const FeedbackWidgetSettingsSchema = Fields.refine(
+  (options) => options.showRating || options.showComment,
+  'Keep at least one question visible.',
+)
+export type FeedbackWidgetSettings = z.infer<typeof FeedbackWidgetSettingsSchema>
+
+export const FeedbackWidgetSettingsPatchSchema = z
+  .strictObject(
+    Object.fromEntries(
+      Object.entries(Fields.shape).map(([key, value]) => [key, value.removeDefault().optional()]),
+    ) as {
+      [K in keyof typeof Fields.shape]: z.ZodOptional<
+        ReturnType<(typeof Fields.shape)[K]['removeDefault']>
+      >
+    },
+  )
+  .refine(
+    (value) =>
+      Object.keys(value).length > 0 && Object.values(value).every((entry) => entry !== undefined),
+  )
+/** Explicit known keys only; storage or upstream extras never become public display config. */
+export function publicFeedbackWidgetSettings(input: unknown): FeedbackWidgetSettings {
+  const row = input && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+  return FeedbackWidgetSettingsSchema.parse(
+    Object.fromEntries(
+      Object.keys(Fields.shape)
+        .filter((key) => row[key] !== undefined)
+        .map((key) => [key, row[key]]),
+    ),
+  )
+}
+
+/** Additive public responses are tolerated; only the known fields survive parsing. */
+export const PublicFeedbackWidgetSettingsSchema = Fields.loose()
+  .refine((options) => options.showRating || options.showComment)
+  .transform(publicFeedbackWidgetSettings)

package/src/features/contracts/index.ts

@@ -0,0 +1,61 @@
+export {
+  FEATURE_CONTRACT_VERSION,
+  FeatureErrorCodeSchema,
+  FeatureErrorSchema,
+  FeatureFlagsSchema,
+  PageContextSchema,
+  PublicFeatureBaseSchema,
+} from './base'
+export type {
+  FeatureError,
+  FeatureErrorCode,
+  FeatureFlags,
+  FeatureKey,
+  PageContext,
+  PublicFeatureBase,
+} from './base'
+
+export { FeedbackInputSchema, FEEDBACK_FORM_KEY, FEEDBACK_FORM_SLUG } from './feedback'
+export type { FeedbackInput, FeedbackReceipt } from './feedback'
+
+export {
+  FeedbackWidgetSettingsSchema,
+  FeedbackWidgetSettingsPatchSchema,
+  publicFeedbackWidgetSettings,
+} from './feedbackSettings'
+export type { FeedbackWidgetSettings } from './feedbackSettings'
+
+export {
+  ConsentStateSchema,
+  ConsentInstallationSchema,
+  PublicConsentInstallationSchema,
+  ManagedIntegrationSchema,
+  deniedConsentState,
+  isCookieScriptURL,
+  classifyManagedIntegration,
+  consentChangeRequiresCodeWrite,
+} from './consent'
+export type {
+  ConsentState,
+  ConsentAdapter,
+  ConsentCategory,
+  ConsentInstallation,
+  ManagedIntegration,
+  IntegrationDriver,
+  ManagedIntegrationClassification,
+  ConsentConfiguration,
+} from './consent'
+
+export * from './knowledge'
+export * from './search'
+export * from './knowledgePolicy'
+export * from './askAi'
+
+export {
+  AskAiWidgetSettingsSchema,
+  AskAiWidgetSettingsPatchSchema,
+  publicAskAiWidgetSettings,
+} from './askAiSettings'
+export type { AskAiWidgetSettings } from './askAiSettings'
+
+export * from './verification'

package/src/features/contracts/knowledge.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+export const KNOWLEDGE_LIMITS = {
+  documents: 1000,
+  bytes: 5 * 1024 * 1024,
+  text: 60000,
+  title: 200,
+  path: 2048,
+} as const
+export const KnowledgeKeySchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-zA-Z0-9][a-zA-Z0-9:_-]*$/)
+export const KnowledgeHashSchema = z.string().regex(/^[a-f0-9]{64}$/)
+export const KnowledgeTitleSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(KNOWLEDGE_LIMITS.title)
+  .refine((v) => !/[<>\u0000-\u001f\u007f]/.test(v))
+/** Canonical website pathname: no origin, query, fragment, traversal or encoded separators. */
+export const KnowledgePathSchema = z
+  .string()
+  .max(KNOWLEDGE_LIMITS.path)
+  .refine((v) => {
+    if (
+      !v.startsWith('/') ||
+      v.includes('//') ||
+      (v.length > 1 && v.endsWith('/')) ||
+      /%2f|%5c|%2e/i.test(v) ||
+      /[\\?#\u0000-\u0020\u007f]/.test(v)
+    )
+      return false
+    try {
+      const decoded = decodeURIComponent(v)
+      return (
+        !/[\\?#\u0000-\u0020\u007f]/.test(decoded) &&
+        !/%[a-f0-9]{2}/i.test(decoded) &&
+        !decoded.startsWith('//') &&
+        !decoded.split('/').some((s) => s === '.' || s === '..') &&
+        new URL(v, 'https://knowledge.invalid').pathname === v
+      )
+    } catch {
+      return false
+    }
+  })
+const common = {
+  id: KnowledgeKeySchema,
+  title: KnowledgeTitleSchema,
+  fingerprint: KnowledgeHashSchema,
+}
+export const PublishedKnowledgeDocumentSchema = z.strictObject({
+  ...common,
+  path: KnowledgePathSchema,
+  text: z.string().max(KNOWLEDGE_LIMITS.text),
+  kind: z.enum(['page', 'entry']),
+})
+export const KnowledgeReferenceSchema = z.union([
+  z.strictObject({ ...common, kind: z.enum(['page', 'entry']), path: KnowledgePathSchema }),
+  z.strictObject({ ...common, kind: z.literal('faq'), path: KnowledgePathSchema.nullable() }),
+])
+const hitFields = { excerpt: z.string().max(1000), text: z.string().max(KNOWLEDGE_LIMITS.text) }
+export const KnowledgeHitSchema = z.union([
+  KnowledgeReferenceSchema.options[0].extend(hitFields),
+  KnowledgeReferenceSchema.options[1].extend(hitFields),
+])
+export const SourceFlagsSchema = z.strictObject({
+  searchable: z.boolean(),
+  answerable: z.boolean(),
+})
+export const SnapshotProvenanceSchema = z.strictObject({
+  deploymentId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/),
+  sourceHash: KnowledgeHashSchema,
+})
+export const KnowledgeSnapshotSchema = z
+  .strictObject({
+    sourceKey: KnowledgeKeySchema,
+    generation: z.int().positive().max(Number.MAX_SAFE_INTEGER),
+    provenance: SnapshotProvenanceSchema,
+    documents: z.array(PublishedKnowledgeDocumentSchema).max(KNOWLEDGE_LIMITS.documents),
+  })
+  .superRefine((v, ctx) => {
+    if (new TextEncoder().encode(JSON.stringify(v)).byteLength > KNOWLEDGE_LIMITS.bytes)
+      ctx.addIssue({ code: 'custom', message: 'Snapshot exceeds 5 MiB.' })
+    for (const key of ['id', 'path'] as const)
+      if (new Set(v.documents.map((d) => d[key])).size !== v.documents.length)
+        ctx.addIssue({ code: 'custom', message: `Duplicate document ${key}.` })
+  })
+export type PublishedKnowledgeDocument = z.infer<typeof PublishedKnowledgeDocumentSchema>
+export type KnowledgeSnapshot = z.infer<typeof KnowledgeSnapshotSchema>
+export type KnowledgeReference = z.infer<typeof KnowledgeReferenceSchema>
+export type KnowledgeHit = KnowledgeReference & { excerpt: string; text: string }
+export type SourceFlags = z.infer<typeof SourceFlagsSchema>