calmlens 0.18.3 → 0.20.0

data/lib/calmlens/testing/fake_api.rb

@@ -59,11 +59,15 @@ module CalmLens
       MAX_DECISION_NOTE_LENGTH = 1499
       RESOURCES = %w[original rendered placeholder].freeze
       MIN_PART = 5 * 1024 * 1024
-      MIN_MULTIPART_IMAGE = 10 * 1024 * 1024
       MAX_MULTIPART_IMAGE = 20 * 1024 * 1024
+      # Like the API: an upload has at most this many parts.
+      MAX_PARTS = 10_000
       # The ThumbHash the mock gives every classified image, standing in for one computed from its
       # pixels. The `placeholder` resource serves it as a PNG, like the CDN.
       THUMBHASH = '1QcSHQRnh493V4dIh4eXh1h4kJUI'
+      # The built-in presets the mock knows, by display name.
+      PRESET_NAMES = { 'general-community' => 'General', 'children-platform' => 'Kids',
+                       'education-support' => 'Learning and support', 'wholesome-community' => 'Teen-safe' }.freeze
       # Like the API: 1 to 255 printable ASCII characters, without a space at either end.
       IDEMPOTENCY_KEY = /\A[\x21-\x7e](?:[\x20-\x7e]{0,253}[\x21-\x7e])?\z/
       # Content a browser could run as a document, which the CDN serves as a download.
@@ -83,6 +87,10 @@ module CalmLens
         @grants = grants
         @state = State.new(assets: {}, folders: {}, content: {}, events: [], lenses: {}, uploads: {}, idempotency: {},
                            hash_lists: {}, hash_list_entries: {})
+        # Stored policies (the API's shape without `projectIds` and `preset.latestVersion`, plus their
+        # reset `baseline`) and the one the project moderates with.
+        @policies = {}
+        @project_policy_id = nil
         @request_count = 0
       end
 
@@ -232,6 +240,47 @@ module CalmLens
       # A request the API's schema refuses: `validation/<issue>` with HTTP 400 and the field.
       def invalid!(code, path) = raise(Failure.new(code, "Invalid #{path}", details: { 'path' => path }, status: 400))
 
+      # Like the API's schema (METADATA_ITEM_SCHEMA): metadata is nil or a list of `{id, value}`
+      # Hashes with a String `id` and any JSON `value`.
+      def check_metadata(metadata)
+        return if metadata.nil?
+
+        invalid!('validation/invalid-type', 'metadata') unless metadata.is_a?(Array)
+        metadata.each_with_index do |item, index|
+          invalid!('validation/invalid-type', "metadata.#{index}") unless item.is_a?(Hash)
+          invalid!('validation/invalid-type', "metadata.#{index}.id") unless item['id'].is_a?(String)
+          invalid!('validation/invalid-value', "metadata.#{index}.value") unless item.key?('value')
+        end
+      end
+
+      # Like the API's schema, checked before the asset is looked up: asset updates take no null
+      # name, and signed URLs no null field.
+      def check_asset_body(method, action, json)
+        case [method, action]
+        in ['PATCH', nil]
+          check_metadata(json['metadata'])
+          invalid!('validation/invalid-type', 'name') if json.key?('name') && json['name'].nil?
+        in ['POST', 'signed-url']
+          %w[viewerClaims resource lens transform expiresInSeconds].each do |key|
+            next unless json.key?(key) && json[key].nil?
+
+            invalid!(key == 'resource' ? 'validation/invalid-value' : 'validation/invalid-type', key)
+          end
+        else nil
+        end
+      end
+
+      # Like the API: an upload's metadata is checked, then its MIME type, which must be one the
+      # API can moderate (`upload/invalid-mime-type` with `details.mimeType`).
+      def check_upload(options)
+        check_metadata(options['metadata'])
+        type = options['contentType']
+        return if type.nil? || Internal.accepted_upload_mime_type?(type)
+
+        fail!(ErrorCodes::INVALID_UPLOAD_MIME_TYPE, "#{type} is not a valid upload file type",
+              details: { 'mimeType' => type })
+      end
+
       # Like the API's query schema: an integer from 1 to `max`.
       def check_range(value, path, max)
         invalid!('validation/too-small', path) if !value.is_a?(Numeric) || value < 1
@@ -245,10 +294,11 @@ module CalmLens
         parts = uri.path.split('/').reject(&:empty?).map { |part| URI.decode_www_form_component(part) }
         query = URI.decode_www_form(uri.query.to_s).to_h.to_h { |key, value| [key, query_value(key, value)] }
         content_type = header(headers, 'Content-Type')
-        json = content_type == 'application/json' && body ? JSON.parse(body) : {}
+        upload = header(headers, 'X-CalmLens-Upload')
+        # A raw upload's body is the file itself, whatever its type.
+        json = content_type == 'application/json' && body && upload.nil? ? JSON.parse(body) : {}
         # HTTP stacks trim header values, so the API sees the key without surrounding whitespace.
         key = header(headers, 'Idempotency-Key')&.to_s&.gsub(/\A[ \t\r\n]+|[ \t\r\n]+\z/, '')
-        upload = header(headers, 'X-CalmLens-Upload')
         return dispatch(method, parts, query, json, body, upload) unless key && method == 'POST'
 
         fail!(ErrorCodes::INVALID_IDEMPOTENCY_KEY) unless key.match?(IDEMPOTENCY_KEY)
@@ -304,6 +354,10 @@ module CalmLens
         in ['POST', ['folders'], _] then create_folder(json)
         in ['GET', ['hash-lists'], _] then page(project_hash_lists, query, JSON.generate([@project_id]))
         in ['POST', ['hash-lists'], _] then create_hash_list(json)
+        in ['GET', ['policies'], _] then policy_list
+        in ['POST', ['policies'], _] then create_policy(json)
+        in ['PUT', ['policy'], _] then show_policy(assign_policy(json))
+        in [_, ['policies', String => policy_id, *rest], _] then policy(method, policy_id, rest, json)
         in ['GET', ['assets'], _] then list(query)
         in ['GET', ['assets', 'search'], _] then search(query)
         in ['POST', ['assets', 'batch'], _] then batch(json)
@@ -399,11 +453,12 @@ module CalmLens
       def project_folders = @state.folders.values.select { |item| item['projectId'] == @project_id }
 
       # Like the API: without a cursor, no events and a `nextCursor` for now; with one, up to `pageSize`
-      # events added since, oldest first. `nextCursor` is never nil.
+      # events added since, oldest first. `nextCursor` is never nil. The mock's key holds every permission,
+      # so no event type is excluded.
       def events(query)
         size = check_range(query.fetch('pageSize', DEFAULT_PAGE_SIZE), 'pageSize', MAX_PAGE_SIZE)
         feed = @state.events
-        return { 'items' => [], 'nextCursor' => "mock_#{feed.size}", 'hasMore' => false } unless query['cursor']
+        return { 'items' => [], 'nextCursor' => "mock_#{feed.size}", 'hasMore' => false, 'excludedTypes' => [] } unless query['cursor']
 
         match = query['cursor'].to_s.match(/\Amock_(\d+)\z/)
         position = match && Integer(match[1], 10)
@@ -411,7 +466,7 @@ module CalmLens
 
         taken = feed[position, size]
         following = position + taken.size
-        { 'items' => taken, 'nextCursor' => "mock_#{following}", 'hasMore' => following < feed.size }
+        { 'items' => taken, 'nextCursor' => "mock_#{following}", 'hasMore' => following < feed.size, 'excludedTypes' => [] }
       end
 
       # Saves lenses in order, like the API: an unchanged definition returns the stored lens, a
@@ -429,7 +484,7 @@ module CalmLens
         end
 
         same = %w[name type active].all? { |key| old[key] == definition[key] } &&
-               old['description'] == definition['description'] && canonical(old['transforms']) == canonical(definition['transforms'])
+               old['description'] == definition['description'] && canonical(old['transform']) == canonical(definition['transform'])
         return old if same && old['version'] == definition['version']
         if definition['version'].to_i > old['version'].to_i
           return @state.lenses[old['identifier']] =
@@ -494,6 +549,7 @@ module CalmLens
       end
 
       def create_asset(options, queue, url: nil, data: nil, open: false)
+        check_upload(options)
         check_folder(options['folderId']) if options['folderId']
         if options['externalId'] && project_assets.any? { |item| item['externalId'] == options['externalId'] }
           fail!(ErrorCodes::DUPLICATE_EXTERNAL_ID)
@@ -533,12 +589,9 @@ module CalmLens
         }
       end
 
-      # Like the API: image uploads in parts total 10 MiB (checked at the last part) to 20 MiB.
-      def image_size_error(type, size, final)
-        return unless type == 'image'
-        return ErrorCodes::MULTIPART_IMAGE_TOO_LARGE if size > MAX_MULTIPART_IMAGE
-
-        ErrorCodes::MULTIPART_IMAGE_TOO_SMALL if final && size < MIN_MULTIPART_IMAGE
+      # Like the API: image uploads in parts total at most 20 MiB, at any size below that.
+      def image_size_error(type, size, _final)
+        ErrorCodes::MULTIPART_IMAGE_TOO_LARGE if type == 'image' && size > MAX_MULTIPART_IMAGE
       end
 
       # Like the API: the parts may not overshoot a declared total, and must reach it at the end.
@@ -557,6 +610,7 @@ module CalmLens
       # In the API's order: a declared total, then a single final part as the whole upload, then the
       # part itself. The queue mode and declared total are saved with an open upload.
       def start_multipart(query, data)
+        check_upload(query)
         total = query['totalSizeInBytes']
         type = kind(query['contentType'].to_s, nil)
         final = query['isFinal'] == true
@@ -695,6 +749,7 @@ module CalmLens
 
       def asset(method, parts, query, json, body)
         id = parts[1]
+        check_asset_body(method, parts[2], json)
         item = @state.assets[id]
         fail!(ErrorCodes::ASSET_NOT_FOUND) unless item && item['projectId'] == @project_id
         case [method, parts[2]]
@@ -793,7 +848,7 @@ module CalmLens
         fail!(ErrorCodes::UPLOAD_NOT_OPEN) unless item['upload']['status'] == 'uploading'
         number = query['partNumber']
         expected = item['upload']['partsReceived'].to_i + 1
-        unless number == expected
+        unless number == expected && number <= MAX_PARTS
           fail!(ErrorCodes::INVALID_UPLOAD_PART_NUMBER, "Expected part #{expected}",
                 details: { 'expectedPartNumber' => expected, 'receivedPartNumber' => number })
         end
@@ -877,6 +932,120 @@ module CalmLens
         touch(item.merge!('parentId' => parent_id))
       end
 
+      # Policies: the project starts on the organisation's own General preset policy, following
+      # automatic updates. The mock holds no built-in preset settings: a preset's settings are
+      # `{ 'categorySettings' => {} }` at version 1, and uploads are never decided by a policy.
+      def new_policy(name, settings, description: '', automatic_updates: false, preset: nil)
+        now = @now.call
+        item = { 'id' => @create_id.call('pol'), 'name' => name, 'description' => description, 'settings' => settings,
+                 'revision' => 1, 'automaticUpdates' => automatic_updates, 'preset' => preset,
+                 'baseline' => deep_copy(settings), 'createdAt' => now, 'updatedAt' => now }
+        @policies[item['id']] = item
+      end
+
+      def ensure_policies
+        return if @project_policy_id
+
+        preset = { 'id' => 'general-community', 'version' => 1, 'own' => true }
+        @project_policy_id = new_policy(PRESET_NAMES['general-community'], { 'categorySettings' => {} },
+                                        automatic_updates: true, preset: preset)['id']
+      end
+
+      # A stored policy as the API shows it.
+      def show_policy(item)
+        shown = item.except('baseline')
+        shown['preset'] = item['preset'].merge('latestVersion' => 1) if item['preset']
+        shown.merge('projectIds' => item['id'] == @project_policy_id ? [@project_id] : [])
+      end
+
+      def find_policy(id)
+        ensure_policies
+        @policies[id] || fail!(ErrorCodes::POLICY_NOT_FOUND)
+      end
+
+      def policy_list
+        ensure_policies
+        { 'policies' => @policies.values.map { |item| show_policy(item) }, 'projectPolicyId' => @project_policy_id }
+      end
+
+      def create_policy(json)
+        ensure_policies
+        name, preset_id, settings = json.values_at('name', 'presetId', 'settings')
+        named = name.is_a?(String) && !name.strip.empty?
+        if settings.nil? == preset_id.nil? || (preset_id && !PRESET_NAMES.key?(preset_id)) || (preset_id.nil? && !named)
+          fail!(ErrorCodes::INVALID_VALUE, 'Send settings with a name, or presetId')
+        end
+        description = json['description'].is_a?(String) ? json['description'] : ''
+        item = if preset_id
+                 origin = { 'id' => preset_id, 'version' => 1, 'own' => false }
+                 new_policy(named ? name.strip : PRESET_NAMES[preset_id], { 'categorySettings' => {} },
+                            description: description, preset: origin)
+               else
+                 new_policy(name.strip, settings, description: description)
+               end
+        # Like the API, a new policy is 201 Created.
+        respond(201, deep_copy(show_policy(item)))
+      end
+
+      def assign_policy(json)
+        item = find_policy(json['policyId'].to_s)
+        @project_policy_id = item['id']
+        item
+      end
+
+      # Saves new values under the next revision, once `revision` is the current one.
+      def save_policy(item, revision, values)
+        fail!(ErrorCodes::POLICY_REVISION_CONFLICT) unless revision.is_a?(Integer) && revision == item['revision']
+
+        item.merge!(values, 'revision' => item['revision'] + 1, 'updatedAt' => @now.call)
+        show_policy(item)
+      end
+
+      def policy(method, id, rest, json)
+        item = find_policy(id)
+        case [method, rest]
+        in ['GET', []] then show_policy(item)
+        in ['PATCH', []] then update_policy(item, json)
+        in ['DELETE', []]
+          fail!(ErrorCodes::POLICY_IN_USE) if item['id'] == @project_policy_id
+          @policies.delete(id)
+          {}
+        in ['POST', ['preset']] then apply_policy_preset(item, json)
+        in ['PUT', ['automatic-updates']] then set_policy_automatic_updates(item, json)
+        else route_not_found!(method, ['policies', id, *rest])
+        end
+      end
+
+      def update_policy(item, json)
+        values = %w[name description].select { |key| json[key].is_a?(String) }
+                                     .to_h { |key| [key, key == 'name' ? json[key].strip : json[key]] }
+        values['settings'] = json['settings'] if json.key?('settings')
+        # Saving a policy that follows its preset pins it as a copy.
+        save_policy(item, json['revision'], values.merge('automaticUpdates' => false))
+      end
+
+      def apply_policy_preset(item, json)
+        preset = item['preset']
+        fail!(ErrorCodes::POLICY_NO_PRESET) if preset.nil? || item['automaticUpdates']
+        fail!(ErrorCodes::POLICY_PRESET_VERSION_CONFLICT) unless json['presetVersion'] == preset['version']
+        # The mock's presets have one release, so an update never has a newer one to apply.
+        fail!(ErrorCodes::POLICY_PRESET_UPDATE_UNAVAILABLE) if json['operation'] == 'update'
+
+        save_policy(item, json['revision'], 'settings' => deep_copy(item['baseline']))
+      end
+
+      def set_policy_automatic_updates(item, json)
+        enabled = json['enabled'] == true
+        preset = item['preset']
+        fail!(ErrorCodes::POLICY_AUTOMATIC_UPDATES_UNAVAILABLE) if preset.nil? || !preset['own'] || item['automaticUpdates'] == enabled
+        fail!(ErrorCodes::POLICY_REVISION_CONFLICT) unless json['revision'] == item['revision']
+        fail!(ErrorCodes::POLICY_PRESET_VERSION_CONFLICT) unless json['presetVersion'] == 1
+
+        values = { 'automaticUpdates' => enabled }
+        values.merge!('name' => PRESET_NAMES[preset['id']], 'description' => '', 'settings' => deep_copy(item['baseline'])) if enabled
+        save_policy(item, json['revision'], values)
+      end
+
       # Hash lists and their entries. Uploads are not compared with them.
       def project_hash_lists = @state.hash_lists.values.select { |item| item['projectId'] == @project_id }
 
@@ -1042,13 +1211,27 @@ module CalmLens
       # private asset needs an API key with `assets:download` for its folder.
       def serve(method, relative)
         path, query = relative.split('#', 2).first.split('?', 2)
-        segments = path.split('/').reject(&:empty?).map { |part| URI.decode_www_form_component(part) }
-        _, project, identifier, resource = segments
+        raw_segments = path.split('/').reject(&:empty?)
+        _, project, identifier, resource = raw_segments.map { |part| URI.decode_www_form_component(part) }
+        # Like the CDN, the selector after the resource is read first, and lenses and transforms
+        # apply only to the rendered resource.
+        begin
+          lens, options = TransformRules.parse_selector(raw_segments.drop(4).join('/'))
+        rescue ArgumentError
+          return invalid_transform
+        end
+        return invalid_transform if resource == 'original' && (lens || options)
+
         item = project == @project_id && project_assets.find { |asset| [asset['id'], asset['externalId']].include?(identifier) }
         return error('asset/not-found', 'Asset not found', status: 404) unless item && RESOURCES.include?(resource)
-
         return placeholder(method, item) if resource == 'placeholder'
 
+        deliver(method, item, URI.decode_www_form(query.to_s).to_h, options)
+      end
+
+      # Serves a found asset's content after the delivery, age and access checks, then the
+      # transform options' schema check.
+      def deliver(method, item, params, options)
         moderation = item['classification']['moderation']['status']
         stored = @state.content[item['id']]
         if stored.nil? || item['upload']['status'] == 'uploading' || %w[blocked purged].include?(moderation) ||
@@ -1056,9 +1239,7 @@ module CalmLens
           return not_available
         end
 
-        params = URI.decode_www_form(query.to_s).to_h
-        opted_in = viewer_age_confirmed?(params)
-        if moderation == 'age-restricted' && !opted_in
+        if moderation == 'age-restricted' && !viewer_age_confirmed?(params)
           return error('viewer/age-confirmation-required', 'Age confirmation required',
                        status: 403)
         end
@@ -1069,6 +1250,9 @@ module CalmLens
                        'This API key needs assets:download permission for this asset’s folder.', status: 403)
         end
 
+        refused = options ? TransformRules.check(options).flatten : []
+        return error('asset/invalid-transform-options', "Invalid transform options: #{refused.join(', ')}", status: 400) if refused.any?
+
         type = stored['type'].to_s.empty? ? 'application/octet-stream' : stored['type']
         cdn_response(method, stored['parts'].sort.map(&:last).join.b,
                      viewer_delivery_headers(item, type, restricted, params))
@@ -1084,6 +1268,8 @@ module CalmLens
         headers
       end
 
+      def invalid_transform = error('asset/invalid-transform', 'Invalid transform selector', status: 400)
+
       def not_available = error('asset/not-available', 'Asset is not available', status: 403)
 
       # Like the CDN's placeholder handler: an image's ThumbHash, public whatever the asset's

data/lib/calmlens/testing/test_image_grid.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module CalmLens
+  # The image grid behind the signed test images (test_inputs.rb).
+  module TestInputs
+    # The test image grid of packages/shared/src/TestImageGrid.ts, painted byte for byte: an odd
+    # N×N grid with an alternating black-and-white ring, two Gray-coded bits per interior cell as
+    # one of four luma levels (colour in chroma only), and Reed–Solomon parity over GF(256).
+    # @api private
+    module Grid
+      # Target luma of the four data levels.
+      LEVELS = [72, 128, 184, 240].freeze
+      SYMBOL_LEVEL = [0, 1, 3, 2].freeze
+      PARITY = 32
+      # Category colours, carried in the chroma only.
+      COLORS = {
+        'sexual' => [232, 80, 160], 'violence' => [224, 56, 64], 'self-harm' => [24, 168, 152],
+        'harassment' => [240, 128, 48], 'hate' => [144, 80, 216], 'criminal-activity' => [224, 184, 40],
+        'personal-information' => [48, 128, 224], 'profanity' => [136, 192, 48]
+      }.freeze
+      NEUTRAL = [144, 152, 160].freeze
+
+      # GF(256) with the polynomial 0x11d and generator 2.
+      EXP = Array.new(512, 0)
+      LOG = Array.new(256, 0)
+      x = 1
+      255.times do |i|
+        EXP[i] = x
+        LOG[x] = i
+        x <<= 1
+        x ^= 0x11d if x.anybits?(256)
+      end
+      (255...512).each { |i| EXP[i] = EXP[i - 255] }
+      [EXP, LOG].each(&:freeze)
+
+      module_function
+
+      def mul(left, right) = left.zero? || right.zero? ? 0 : EXP[LOG[left] + LOG[right]]
+
+      # g(x) = (x - a^0)...(x - a^31), highest coefficient first.
+      GENERATOR = PARITY.times.reduce([1]) do |g, i|
+        following = Array.new(g.size + 1, 0)
+        g.each_with_index do |coefficient, j|
+          following[j] ^= coefficient
+          following[j + 1] ^= mul(coefficient, EXP[i])
+        end
+        following
+      end.freeze
+
+      def parity(block)
+        parity = Array.new(PARITY, 0)
+        block.each do |byte|
+          factor = byte ^ parity[0]
+          parity = parity.drop(1) << 0
+          PARITY.times { |j| parity[j] ^= mul(GENERATOR[j + 1], factor) } unless factor.zero?
+        end
+        parity
+      end
+
+      # The codeword bytes a grid of `cells` holds, its block lengths and its data bytes.
+      def layout(cells)
+        capacity = (cells - 2) * (cells - 2) / 4
+        blocks = (capacity + 254) / 255
+        lengths = Array.new(blocks) { |index| (capacity / blocks) + (index < capacity % blocks ? 1 : 0) }
+        [capacity, lengths, capacity - (blocks * PARITY)]
+      end
+
+      # The colour's chroma on the level's luma, scaled by the largest s/16 that keeps every
+      # channel in 0-255. Each scaled difference is truncated toward zero (not floored).
+      def pixel(colour, level)
+        target = LEVELS[level]
+        own = ((77 * colour[0]) + (150 * colour[1]) + (29 * colour[2])) >> 8
+        16.downto(0) do |scale|
+          pixel = colour.map do |channel|
+            difference = channel - own
+            magnitude = (difference.abs * scale) >> 4
+            difference.negative? ? target - magnitude : target + magnitude
+          end
+          return pixel if pixel.all? { |channel| channel.between?(0, 255) }
+        end
+      end
+
+      # The data cell's colour: the palette blended between opposite corners, in integers.
+      def blend(palette, column, row, cells)
+        span = cells - 1
+        denominator = span * span
+        position = ((column * (span - row)) + ((span - column) * row)) * (palette.size - 1)
+        start = position / denominator
+        remainder = position - (start * denominator)
+        finish = palette[[start + 1, palette.size - 1].min]
+        palette[start].each_with_index.map do |channel, c|
+          ((channel * (denominator - remainder)) + (finish[c] * remainder)) / denominator
+        end
+      end
+
+      # Paints `data` (a binary String) as a grid of the categories' colours: [width, RGBA String].
+      def paint(data, categories)
+        cells = (15..127).step(2).find { |size| layout(size)[2] >= data.bytesize }
+        raise Internal.invalid('Test scenario is too large for a test image') unless cells
+
+        stream = codeword_stream(data, cells)
+        palette = categories.uniq.map { |category| COLORS.fetch(category) }
+        palette = [NEUTRAL] if palette.empty?
+        pixels = Array.new(cells * cells) { |cell| [*cell_pixel(stream, palette, cell, cells), 255].pack('C4') }
+        cell_size = 2 * (512 / 2 / cells)
+        rows = Array.new(cells) { |row| pixels[row * cells, cells].map { |pixel| pixel * cell_size }.join * cell_size }
+        [cells * cell_size, rows.join.b]
+      end
+
+      # The padded data with each block's parity, the blocks interleaved byte by byte and whitened, so
+      # a uniform area never reads as the all-zero codeword.
+      def codeword_stream(data, cells)
+        _, lengths, data_bytes = layout(cells)
+        padded = data.bytes + Array.new(data_bytes - data.bytesize) { |i| i.odd? ? 0x11 : 0xec }
+        offset = 0
+        codewords = lengths.map do |length|
+          block = padded[offset, length - PARITY]
+          offset += block.size
+          block + parity(block)
+        end
+        stream = Array.new(lengths.max) { |i| codewords.filter_map { |codeword| codeword[i] } }.flatten
+        stream.each_with_index.map { |byte, i| byte ^ (((i * 151) + 77) & 255) }
+      end
+
+      # A cell's RGB: the ring alternates black and white; data cells hold two bits each.
+      def cell_pixel(stream, palette, cell, cells)
+        row, column = cell.divmod(cells)
+        return [(row + column).odd? ? 255 : 0] * 3 if [row, column].any? { |at| at.zero? || at == cells - 1 }
+
+        symbol = ((row - 1) * (cells - 2)) + column - 1
+        index = symbol >> 2
+        level = index < stream.size ? SYMBOL_LEVEL[(stream[index] >> (6 - (2 * (symbol & 3)))) & 3] : 0
+        pixel(blend(palette, column, row, cells), level)
+      end
+    end
+
+    # The PNG encoding of test images.
+    # @api private
+    module Png
+      module_function
+
+      # 8-bit RGBA rows without filtering in stored deflate blocks, so every SDK writes the same bytes.
+      def png(width, height, rgba)
+        stride = width * 4
+        raw = Array.new(height) { |row| "\0".b + rgba.byteslice(row * stride, stride) }.join
+        zlib = "\x78\x01".b
+        blocks = (0...raw.bytesize).step(65_535).map { |offset| raw.byteslice(offset, 65_535) }
+        blocks.each_with_index do |block, index|
+          zlib << [index == blocks.size - 1 ? 1 : 0, block.bytesize, block.bytesize ^ 0xffff].pack('Cvv') << block
+        end
+        zlib << [Zlib.adler32(raw)].pack('N')
+        chunk = ->(type, body) { [body.bytesize].pack('N') + type.b + body + [Zlib.crc32(type.b + body)].pack('N') }
+        "\x89PNG\r\n\x1a\n".b + chunk.call('IHDR', [width, height, 8, 6, 0, 0, 0].pack('NNC5')) +
+          chunk.call('IDAT', zlib) + chunk.call('IEND', ''.b)
+      end
+    end
+    private_constant :Grid, :Png
+  end
+end

data/lib/calmlens/testing/test_input_scenario.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'classification'
+
+module CalmLens
+  # The scenario checks behind the signed test inputs (test_inputs.rb).
+  module TestInputs
+    # Checks test input scenarios and writes them as the backend's canonical JSON.
+    # @api private
+    module Scenario
+      ACTIONS = %w[allow limit age-restrict block].freeze
+      REGIONAL_ACTIONS = %w[limit age-restrict block].freeze
+      # The qualifiers a scenario may list for each category: all but those the input type sets.
+      ALLOWED_QUALIFIERS = MockClassification::QUALIFIERS.transform_values do |list|
+        (list - MockClassification::INPUT_QUALIFIERS).freeze
+      end.freeze
+
+      module_function
+
+      # A checked scenario's JSON in the backend's key order. Every string is a validated ASCII token.
+      def canonical_json(value)
+        case value
+        when Hash then "{#{value.map { |key, item| "\"#{key}\":#{canonical_json(item)}" }.join(',')}}"
+        when Array then "[#{value.map { |item| canonical_json(item) }.join(',')}]"
+        when Float then js_number(value)
+        else "\"#{value}\""
+        end
+      end
+
+      # A score as JavaScript's JSON.stringify writes it: the shortest round-tripping digits, in
+      # exponent form below 1e-6, and 0 for -0.
+      def js_number(value)
+        return '0' if value.zero?
+
+        mantissa, exponent = value.to_s.split('e')
+        whole, fraction = mantissa.split('.')
+        digits = whole + fraction.to_s
+        point = whole.size + exponent.to_i
+        stripped = digits.sub(/\A0+/, '')
+        point -= digits.size - stripped.size
+        digits = stripped.sub(/0+\z/, '')
+        if value < 1e-6
+          "#{digits[0]}#{".#{digits[1..]}" if digits.size > 1}e#{point - 1}"
+        elsif point <= 0 then "0.#{'0' * -point}#{digits}"
+        elsif point >= digits.size then digits + ('0' * (point - digits.size))
+        else "#{digits[0, point]}.#{digits[point..]}"
+        end
+      end
+
+      # Checks a scenario and returns it with camelCase String keys in canonical order.
+      def validate(input)
+        input = fields(input, 'scenario', %w[regionalActions unassessedCategories instances], %w[instances])
+        instances = array(input['instances'], 'instances', 128).map { |instance| check_instance(instance) }
+        with_action = instances.count { |instance| instance.key?('action') }
+        check([0, instances.size].include?(with_action), 'Set an action for every instance or omit all actions')
+        checked = {}
+        if input.key?('regionalActions')
+          checked['regionalActions'] = array(input['regionalActions'], 'regionalActions', REGIONS.size).each_with_object([]) do |item, done|
+            item = fields(item, 'regional action', %w[region action], %w[region action])
+            check(REGIONS.include?(item['region']) && done.none? { |other| other['region'] == item['region'] },
+                  "Regional actions need unique regions from #{REGIONS.join(', ')} (got #{item['region'].inspect})")
+            check(REGIONAL_ACTIONS.include?(item['action']), "Regional action must be one of #{REGIONAL_ACTIONS.join(', ')}")
+            done << { 'region' => item['region'], 'action' => item['action'] }
+          end
+        end
+        if input.key?('unassessedCategories')
+          unassessed = array(input['unassessedCategories'], 'unassessedCategories', MockClassification::CATEGORIES.size)
+          unassessed.each_with_index do |category, index|
+            check(MockClassification::CATEGORIES.include?(category) && !unassessed[0, index].include?(category) &&
+                    instances.none? { |instance| instance['category'] == category },
+                  "Unassessed categories must be unique categories without instances (got #{category.inspect})")
+          end
+          checked['unassessedCategories'] = unassessed
+        end
+        checked.merge('instances' => instances)
+      end
+
+      def check_instance(instance)
+        instance = fields(instance, 'instance', %w[category score action qualifiers], %w[category qualifiers])
+        category = instance['category']
+        allowed = ALLOWED_QUALIFIERS[category] if category.is_a?(String)
+        check(allowed, "Unknown category #{category.inspect}")
+        checked = { 'category' => category }
+        if instance.key?('score')
+          score = instance['score']
+          check(score.is_a?(Numeric) && score.real? && score.to_f.between?(0, 1), 'Score must be a number from 0 to 1')
+          checked['score'] = score.to_f
+        end
+        if instance.key?('action')
+          check(ACTIONS.include?(instance['action']), "Action must be one of #{ACTIONS.join(', ')}")
+          checked['action'] = instance['action']
+        end
+        qualifiers = array(instance['qualifiers'], 'qualifiers', 64)
+        qualifiers.each_with_index do |qualifier, index|
+          check(allowed.include?(qualifier) && !qualifiers[0, index].include?(qualifier),
+                "Choose unique #{category} qualifiers; input-type qualifiers are automatic (got #{qualifier.inspect})")
+        end
+        checked.merge('qualifiers' => qualifiers)
+      end
+
+      # A Hash's entries by camelCase key, refusing unknown, duplicate and missing keys.
+      def fields(value, name, allowed, required)
+        check(value.is_a?(Hash), "A test #{name} must be a Hash (got #{value.class})")
+        result = {}
+        value.each do |key, item|
+          field = Internal.camelize(key) if key.is_a?(String) || key.is_a?(Symbol)
+          check(allowed.include?(field), "Unknown test #{name} field #{key.inspect}")
+          check(!result.key?(field), "Test #{name} field #{field} is given twice")
+          result[field] = item
+        end
+        missing = required - result.keys
+        check(missing.empty?, "A test #{name} needs #{missing.join(', ')}")
+        result
+      end
+
+      def array(value, name, max)
+        check(value.is_a?(Array), "#{name} must be an Array")
+        check(value.size <= max, "#{name} has at most #{max} items")
+        value.dup
+      end
+
+      def check(condition, message) = condition || raise(Internal.invalid(message))
+    end
+
+    private_constant :Scenario
+  end
+end