calmlens 0.1.0

data/lib/calmlens/webhooks.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+
+# Webhook header names, signature tolerance, event type and verification helpers.
+module CalmLens
+  # Header carrying the delivery ID. Retries of one delivery repeat it: use it to skip duplicates.
+  WEBHOOK_DELIVERY_HEADER = 'x-calmlens-delivery'
+  # Header carrying the Unix time (seconds) the delivery was signed.
+  WEBHOOK_TIMESTAMP_HEADER = 'x-calmlens-timestamp'
+  # Header carrying `v1=<hex HMAC-SHA256>` signatures, comma-separated.
+  WEBHOOK_SIGNATURE_HEADER = 'x-calmlens-signature'
+  # Deliveries whose timestamp is further than this from the receiver's clock are rejected.
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300
+
+  # A verified webhook delivery: `{id, type, createdAt, projectId, data}`, where `data` holds the
+  # event's `severity`, `title`, `description`, `assetId`, `asset` and `facts`.
+  #
+  # @!attribute id [String] the event ID.
+  # @!attribute type [String] such as `asset.approved`. New types may appear: ignore unknown ones.
+  # @!attribute created_at [Integer] milliseconds since the epoch.
+  # @!attribute project_id [String]
+  # @!attribute data [Hash{String => Object}] the event fields, with the API's camelCase keys.
+  WebhookEvent = Struct.new(:id, :type, :created_at, :project_id, :data, keyword_init: true) do
+    # @return [String, nil]
+    def asset_id = data['assetId']
+
+    # @return [Array<Hash>] `{'key', 'value', 'url'?}` entries registered for the event type.
+    def facts = data['facts'].is_a?(Array) ? data['facts'] : []
+
+    # @return [Boolean] true for a test send from the portal or CLI.
+    def test? = facts.any? { |fact| fact.is_a?(Hash) && fact['key'] == 'test' && fact['value'] == true }
+  end
+
+  # Webhook signing and verification. Always verify the exact bytes received: read the raw body
+  # (`request.raw_post` in Rails, `request.body.read` in Rack and Sinatra) before parsing it.
+  module Webhooks
+    module_function
+
+    # Builds the `x-calmlens-signature` value for a body, for example to test your receiver.
+    # @param payload [String] the raw body
+    # @param timestamp [String, Integer] Unix seconds
+    # @param secret [String]
+    # @return [String] `v1=<hex>`
+    def signature_header(payload:, timestamp:, secret:)
+      raw = raw_body(payload)
+      raise Internal.invalid('secret must be a non-empty String') unless secret.is_a?(String) && !secret.empty?
+
+      "v1=#{OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp.to_s.b}.".b + raw)}"
+    end
+
+    # Checks a delivery's signature and freshness in constant time.
+    # @param payload [String] the raw request body, exactly as received
+    # @param signature [String, nil] the `x-calmlens-signature` header
+    # @param timestamp [String, nil] the `x-calmlens-timestamp` header
+    # @param secret [String] the webhook's signing secret
+    # @param tolerance_seconds [Integer]
+    # @param now [Integer] Unix seconds
+    # @return [Boolean]
+    # @raise [InvalidArgumentError] when payload is not a String, such as an already parsed Hash.
+    def verify(payload:, signature:, timestamp:, secret:, tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+               now: Time.now.to_i)
+      raw = raw_body(payload)
+      stamp = timestamp.to_s.strip
+      return false if !secret.is_a?(String) || secret.empty? || signature.to_s.empty? || !stamp.match?(/\A[0-9]+\z/)
+      return false if (now.floor - stamp.to_i).abs > tolerance_seconds
+
+      expected = signature_header(payload: raw, timestamp: stamp, secret: secret).delete_prefix('v1=')
+      signature.to_s.split(',').map(&:strip).select { |entry| entry.start_with?('v1=') }.any? do |entry|
+        candidate = entry.delete_prefix('v1=').downcase
+        candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(candidate, expected)
+      end
+    end
+
+    # Verifies a delivery, then parses it.
+    # @param (see #verify)
+    # @return [WebhookEvent]
+    # @raise [WebhookVerificationError] `sdk/invalid-webhook-signature` when verification fails, or
+    #   `sdk/invalid-webhook-payload` when the verified body is not an event.
+    def parse_event(payload:, signature:, timestamp:, secret:,
+                    tolerance_seconds: WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, now: Time.now.to_i)
+      unless verify(payload: payload, signature: signature, timestamp: timestamp, secret: secret,
+                    tolerance_seconds: tolerance_seconds, now: now)
+        raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_SIGNATURE,
+                                           'Webhook signature or timestamp did not verify')
+      end
+
+      decode_event(payload)
+    end
+
+    def decode_event(payload)
+      body = JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
+      unless body.is_a?(Hash) && body['id'].is_a?(String) && body['type'].is_a?(String) && body['createdAt'].is_a?(Integer) &&
+             body['projectId'].is_a?(String) && body['data'].is_a?(Hash)
+        raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not a CalmLens event')
+      end
+
+      WebhookEvent.new(id: body['id'], type: body['type'], created_at: body['createdAt'],
+                       project_id: body['projectId'], data: body['data'])
+    rescue JSON::ParserError, EncodingError => e
+      raise WebhookVerificationError.new(SdkErrorCodes::INVALID_WEBHOOK_PAYLOAD, 'Webhook body is not JSON'), cause: e
+    end
+
+    def raw_body(payload)
+      return payload.b if payload.is_a?(String)
+
+      raise Internal.invalid("Webhook payload must be the raw body String, not a #{payload.class}. " \
+                             'Read request.raw_post (Rails) or request.body.read (Rack, Sinatra) before parsing.')
+    end
+    private_class_method :decode_event, :raw_body
+  end
+
+  # @see Webhooks.signature_header
+  def self.create_webhook_signature_header(...) = Webhooks.signature_header(...)
+
+  # @see Webhooks.verify
+  def self.verify_webhook_signature(...) = Webhooks.verify(...)
+
+  # @see Webhooks.parse_event
+  def self.parse_webhook_event(...) = Webhooks.parse_event(...)
+end

data/lib/calmlens.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# CalmLens server-side SDK: moderation, uploads, events, webhooks and CDN delivery.
+# Start with {CalmLens::ServerClient}; see {CalmLens::Webhooks} to receive deliveries.
+module CalmLens
+end
+
+require_relative 'calmlens/version'
+require_relative 'calmlens/error_codes'
+require_relative 'calmlens/errors'
+require_relative 'calmlens/internal'
+require_relative 'calmlens/transforms'
+require_relative 'calmlens/response'
+require_relative 'calmlens/transport'
+require_relative 'calmlens/upload_body'
+require_relative 'calmlens/session'
+require_relative 'calmlens/resource'
+require_relative 'calmlens/assets'
+require_relative 'calmlens/folders'
+require_relative 'calmlens/text'
+require_relative 'calmlens/upload_tokens'
+require_relative 'calmlens/events'
+require_relative 'calmlens/cdn'
+require_relative 'calmlens/lenses'
+require_relative 'calmlens/server_client'
+require_relative 'calmlens/webhooks'

data/sig/calmlens.rbs

@@ -0,0 +1,273 @@
+# Public API of the calmlens gem. Request and response shapes are in sig/types.rbs and error codes
+# in sig/error_codes.rbs.
+module CalmLens
+  VERSION: String
+
+  WEBHOOK_DELIVERY_HEADER: String
+  WEBHOOK_TIMESTAMP_HEADER: String
+  WEBHOOK_SIGNATURE_HEADER: String
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS: Integer
+
+  module SdkErrorCodes
+    INVALID_ARGUMENT: String
+    INVALID_CONFIG: String
+    TRANSPORT_ERROR: String
+    TIMEOUT: String
+    INVALID_RESPONSE: String
+    HTTP_ERROR: String
+    RESPONSE_TOO_LARGE: String
+    INVALID_WEBHOOK_SIGNATURE: String
+    INVALID_WEBHOOK_PAYLOAD: String
+  end
+
+  class Error < StandardError
+    attr_reader code: String
+    # Extra details from the API error body (any JSON), plus `"network" => true` for API errors.
+    attr_reader details: Hash[String, json_value]
+    attr_reader status: Integer?
+    attr_reader request_id: String?
+    attr_reader headers: Hash[String, String]
+    def initialize: (String code, ?String? message, ?details: Hash[String, json_value], ?status: Integer?,
+                     ?headers: Hash[String, String], ?request_id: String?) -> void
+    def retry_after: () -> Float?
+    def not_found?: () -> bool
+    def retryable?: () -> bool
+    def self.build: (String code, ?String? message, ?status: Integer?, ?details: Hash[String, json_value],
+                     ?headers: Hash[String, String], ?request_id: String?) -> Error
+  end
+  class APIError < Error end
+  class BadRequestError < APIError end
+  class AuthenticationError < APIError end
+  class PermissionDeniedError < APIError end
+  class NotFoundError < APIError end
+  class ConflictError < APIError end
+  class RateLimitError < APIError end
+  class ServerError < APIError end
+  class ConnectionError < Error end
+  class TimeoutError < ConnectionError end
+  class InvalidResponseError < Error end
+  class InvalidArgumentError < Error end
+  class ConfigurationError < InvalidArgumentError end
+  class WebhookVerificationError < Error end
+
+  class Response
+    attr_reader status: Integer
+    attr_reader headers: Hash[String, String]
+    # Give `body:` for a complete body, or a reader block that yields each String chunk to the
+    # block it receives. RBS cannot describe a block that takes a block, hence `(?)`.
+    def initialize: (status: Integer | String, ?headers: Hash[String | Symbol, String | Array[String]], ?body: String?)
+                    ?{ (?) -> void } -> void
+    def request_id: () -> String?
+    def content_type: () -> String?
+    def content_length: () -> Integer?
+    def success?: () -> bool
+    def each_chunk: () { (String chunk) -> void } -> nil
+                  | () -> Enumerator[String, nil]
+    def body: (?limit: Integer?) -> String
+  end
+
+  module Transport
+    class Request < Struct[untyped]
+      attr_accessor method: String
+      attr_accessor url: String
+      attr_accessor headers: Hash[String, String]
+      attr_accessor body: (String | _Reader)?
+      attr_accessor open_timeout: number
+      attr_accessor timeout: number
+      def initialize: (method: String, url: String, headers: Hash[String, String], body: (String | _Reader)?,
+                       open_timeout: number, timeout: number) -> void
+    end
+
+    interface _Reader
+      def read: (?Integer? length, ?String? buffer) -> String?
+    end
+
+    # A custom transport receives each request and either yields a {Response} to the block (and
+    # returns the block's result) or returns a response: a {Response}, or any object with `status`
+    # (or `code`), `headers` (or `to_hash`) and `body`. The return value is untyped because the
+    # client only inspects it when the transport did not yield.
+    interface _Transport
+      def call: (Request request) { (Response response) -> untyped } -> untyped
+    end
+
+    class NetHTTP
+      def initialize: () -> void
+      # Returns the block's result.
+      def call: [T] (Request request) { (Response response) -> T } -> T?
+      def close: () -> void
+    end
+  end
+
+  class ServerClient
+    DEFAULT_BASE_URL: String
+    DEFAULT_CDN_BASE_URL: String
+    attr_reader assets: Assets
+    attr_reader folders: Folders
+    attr_reader text: Text
+    attr_reader upload_tokens: UploadTokens
+    attr_reader events: Events
+    attr_reader cdn: CDN
+    attr_reader project_id: String
+    attr_reader base_url: String
+    attr_reader cdn_base_url: String
+    def initialize: (api_key: String, project_id: String, ?base_url: String, ?cdn_base_url: String, ?timeout: number,
+                     ?open_timeout: number, ?max_retries: Integer, ?retry_base_delay: number,
+                     ?transport: Transport::_Transport?) -> void
+    def close: () -> nil
+    def ensure_lenses: (ensure_lenses_options options) -> Array[lens]
+    def ensure_lens: (ensure_lens_options options) -> lens
+  end
+
+  class Resource
+    # Resources are created by {ServerClient}; the session is internal.
+    private def initialize: (untyped session) -> void
+  end
+
+  class Assets < Resource
+    # Moderation statuses that carry a decision.
+    DECIDED_MODERATION_STATUSES: Array[String]
+    # Processing statuses after which no decision arrives without a retry.
+    FINISHED_PROCESSING_STATUSES: Array[String]
+
+    def search: (asset_search_options options) -> asset_search_response
+    def list: (?list_assets_options options) -> asset_page
+    def each: (?list_assets_options options) { (asset) -> void } -> nil
+            | (?list_assets_options options) -> Enumerator[asset, nil]
+    def list_children: (list_asset_children_options options) -> asset_page
+    def each_child: (list_asset_children_options options) { (asset) -> void } -> nil
+                  | (list_asset_children_options options) -> Enumerator[asset, nil]
+    def retrieve: (asset_id_options options) -> asset
+    def wait_for_decision: (wait_for_decision_options options) -> asset
+    def update: (update_asset_options options) -> asset
+    def retry: (asset_id_options options) -> asset
+    def delete_content: (asset_id_options options) -> asset
+    def delete: (asset_id_options options) -> nil
+    def move: (move_asset_options options) -> asset
+    def create_signed_url: (create_signed_url_options options) -> signed_url
+    def create: (upload_options options) -> asset
+    def moderate: (upload_options options) -> asset
+    def upload_part: (upload_part_options options) -> asset
+  end
+
+  class Folders < Resource
+    def list: (?list_folders_options options) -> Array[folder]
+    def create: (create_folder_options options) -> folder
+    def retrieve: (folder_id_options options) -> folder
+    def update: (update_folder_options options) -> folder
+    def move: (move_folder_options options) -> folder
+    def delete: (folder_id_options options) -> nil
+  end
+
+  class UploadTokens < Resource
+    TOKEN_PREFIX: String
+    SIGNING_CONTEXT: String
+    DEFAULT_TTL_SECONDS: Integer
+    MAX_TTL_SECONDS: Integer
+    private def initialize: (untyped session, String api_key) -> void
+    def sign: (sign_upload_token_options options) -> signed_upload_token
+  end
+
+  class Text < Resource
+    private def initialize: (untyped session, Assets assets) -> void
+    def moderate: (moderate_text_options options) -> asset
+  end
+
+  class Events < Resource
+    def list: (?list_events_options options) -> events_page
+    def each_page: (?list_events_options options) { (events_page) -> void } -> nil
+                 | (?list_events_options options) -> Enumerator[events_page, nil]
+    def each: (?list_events_options options) { (event) -> void } -> nil
+            | (?list_events_options options) -> Enumerator[event, nil]
+  end
+
+  class CDN < Resource
+    def get_asset_url: (asset_url_options options) -> String
+    def serve: (serve_options options) -> Response
+             | [T] (serve_options options) { (Response) -> T } -> T
+  end
+
+  class WebhookEvent < Struct[untyped]
+    attr_accessor id: String
+    attr_accessor type: event_type
+    # Milliseconds since the Unix epoch.
+    attr_accessor created_at: Integer
+    attr_accessor project_id: String
+    attr_accessor data: webhook_event_data
+    def initialize: (id: String, type: event_type, created_at: Integer, project_id: String, data: webhook_event_data) -> void
+    def asset_id: () -> String?
+    def facts: () -> Array[event_fact]
+    def test?: () -> bool
+  end
+
+  module Webhooks
+    def self.signature_header: (payload: String, timestamp: String | Integer, secret: String) -> String
+    def self.verify: (payload: String, signature: String?, timestamp: String?, secret: String, ?tolerance_seconds: Integer,
+                      ?now: number) -> bool
+    def self.parse_event: (payload: String, signature: String?, timestamp: String?, secret: String,
+                           ?tolerance_seconds: Integer, ?now: number) -> WebhookEvent
+  end
+
+  def self.create_webhook_signature_header: (payload: String, timestamp: String | Integer, secret: String) -> String
+  def self.verify_webhook_signature: (payload: String, signature: String?, timestamp: String?, secret: String,
+                                      ?tolerance_seconds: Integer, ?now: number) -> bool
+  def self.parse_webhook_event: (payload: String, signature: String?, timestamp: String?, secret: String,
+                                 ?tolerance_seconds: Integer, ?now: number) -> WebhookEvent
+
+  # require 'calmlens/testing'
+  module Testing
+    # The mock's in-memory records. Change them to arrange a test, such as setting an asset's `moderation.status`.
+    class State < Struct[untyped]
+      attr_accessor assets: Hash[String, asset]
+      attr_accessor folders: Hash[String, folder]
+      # Stored bytes by asset ID, with each part's bytes by part number.
+      attr_accessor content: Hash[String, { "type" => String, "parts" => Hash[Integer, String] }]
+      attr_accessor events: Array[event]
+      attr_accessor lenses: Hash[String, lens]
+    end
+  end
+
+  class MockServerClient < ServerClient
+    class Request < Struct[untyped]
+      attr_accessor method: String
+      attr_accessor url: String
+      attr_accessor path: String
+      attr_accessor query: Hash[String, String]
+      attr_accessor headers: Hash[String, String]
+      attr_accessor body: String?
+      def json: () -> json_value
+    end
+
+    interface _Clock
+      # The current time in milliseconds since the Unix epoch.
+      def call: () -> Integer
+    end
+
+    interface _IdFactory
+      def call: () -> String
+    end
+
+    # Where a mock upload ends up: `pending` (still processing), `approved` or `rejected`
+    # (processing done with that decision), or `failed` (processing failed, retryable).
+    type outcome = "pending" | "approved" | "rejected" | "failed"
+
+    # An outcome, fields to deep-merge into the asset, or a callable that receives a copy of the
+    # asset and returns either.
+    type analyzed_outcome = outcome | Hash[String, json_input] | _AnalyzedOutcome
+
+    interface _AnalyzedOutcome
+      def call: (asset asset) -> (String | Hash[String, json_input])
+    end
+
+    def initialize: (?project_id: String, ?base_url: String, ?cdn_base_url: String, ?now: _Clock, ?create_id: _IdFactory,
+                     ?queued_outcome: outcome, ?analyzed_outcome: analyzed_outcome, ?timeout: number,
+                     ?open_timeout: number, ?max_retries: Integer, ?retry_base_delay: number) -> void
+    def state: () -> Testing::State
+    # `body` is any JSON value, encoded as the response body.
+    def enqueue: (body: json_input, ?status: Integer, ?headers: Hash[String, String]) -> self
+    def enqueue_raw: (body: String, ?status: Integer, ?headers: Hash[String, String]) -> self
+    def enqueue_error: (Exception error) -> self
+    def enqueue_event: (mock_event_input event) -> event
+    def requests: () -> Array[Request]
+    def remaining_responses: () -> Integer
+  end
+end

data/sig/error_codes.rbs

@@ -0,0 +1,67 @@
+# Mirrors lib/calmlens/error_codes.rb, which packages/sdk-contract/generate.ts generates from
+# packages/shared/src/PublicErrorCodes.ts. test/signature_test.rb fails when the two differ.
+module CalmLens
+  module ErrorCodes
+    INVALID_CURSOR: String
+    MISSING_TOKEN: String
+    INVALID_API_KEY: String
+    API_KEY_PROJECT_MISMATCH: String
+    API_KEY_NOT_ACCEPTED: String
+    FILE_TOO_LARGE: String
+    IMAGE_REQUIRES_MULTIPART_UPLOAD: String
+    MULTIPART_IMAGE_TOO_SMALL: String
+    MULTIPART_IMAGE_TOO_LARGE: String
+    IMAGE_EXCEEDED_MAX_DIMENSIONS: String
+    UPLOAD_LIMIT_EXCEEDED: String
+    SPEND_LIMIT_REACHED: String
+    INVALID_UPLOAD_MIME_TYPE: String
+    INVALID_EVENT_CURSOR: String
+    INVALID_UPLOAD_PAYLOAD: String
+    USE_UPLOAD_PART: String
+    UPLOAD_NOT_OPEN: String
+    INVALID_UPLOAD_PART_NUMBER: String
+    UPLOAD_MISSING: String
+    UPLOAD_SIZE_MISMATCH: String
+    INVALID_IDEMPOTENCY_KEY: String
+    IDEMPOTENCY_KEY_REUSED: String
+    IDEMPOTENT_REQUEST_IN_PROGRESS: String
+    ASSET_NOT_FOUND: String
+    PROJECT_NOT_FOUND: String
+    ASSET_UPDATE_FAILED: String
+    ASSET_SAFETY_HELD: String
+    ASSET_NOT_RETRYABLE: String
+    ASSET_CONTENT_UNAVAILABLE: String
+    SUPPORT_TICKET_NOT_FOUND: String
+    DUPLICATE_EXTERNAL_ID: String
+    FOLDER_NOT_FOUND: String
+    DUPLICATE_FOLDER_NAME: String
+    FOLDER_NOT_EMPTY: String
+    FOLDER_PARENT_CYCLE: String
+    LENS_VERSION_CONFLICT: String
+    UPLOAD_PRESET_NOT_FOUND: String
+    UPLOAD_PRESET_DISABLED: String
+    UPLOAD_PRESET_TOKEN_REQUIRED: String
+    REMOTE_URL_NOT_ALLOWED: String
+    WEBSITE_RATE_LIMIT_EXCEEDED: String
+    UPLOAD_PRESET_CONTENT_TYPE_NOT_ALLOWED: String
+    UPLOAD_PRESET_TOO_LARGE: String
+    UPLOAD_PRESET_DAILY_LIMIT_REACHED: String
+    UPLOAD_PRESET_ORIGIN_NOT_ALLOWED: String
+    UPLOAD_PRESET_FIELD_NOT_ALLOWED: String
+    UPLOAD_TOKEN_INVALID: String
+    UPLOAD_TOKEN_EXPIRED: String
+    UPLOAD_TOKEN_USED: String
+    INVALID_REMOTE_URL: String
+    REMOTE_URL_UNAVAILABLE: String
+    APPEAL_NOT_FOUND: String
+    APPEAL_JUDGMENT_NOT_FOUND: String
+    APPEAL_ASSET_NOT_FOUND: String
+    APPEAL_PERMISSION_DENIED: String
+    APPEAL_ALREADY_REVIEWED: String
+    APPEAL_DECISION_CHANGED: String
+    APPEAL_INVALID_ACTION: String
+    APPEAL_SAFETY_HELD: String
+    APPEAL_CONTENT_UNAVAILABLE: String
+    STATUSES: Hash[String, Integer]
+  end
+end