k9o 1.4.0 → 1.5.0

data/lib/k9o/ed25519.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module K9o
+  # Ed25519 signature verification (RFC 8032). Uses the openssl library when the Ruby in use can verify Ed25519, and
+  # an in-process implementation (plain integer arithmetic) otherwise, so the answer never depends on the build of
+  # OpenSSL underneath Ruby.
+  module Ed25519
+    P = (2**255) - 19
+    L = (2**252) + 27_742_317_777_372_353_535_851_937_790_883_648_493
+    D = (-121_665 * 121_666.pow(P - 2, P)) % P
+    SQRT_M1 = 2.pow((P - 1) / 4, P)
+    BASE_Y = (4 * 5.pow(P - 2, P)) % P
+
+    module_function
+
+    # True when +signature+ (64 bytes) is a valid Ed25519 signature of +message+ under +public_key+ (32 bytes).
+    # Malformed input answers false.
+    def verify(public_key, message, signature)
+      public_key = public_key.b
+      message = message.b
+      signature = signature.b
+      return false unless public_key.bytesize == 32 && signature.bytesize == 64
+
+      if native?
+        verify_native(public_key, message, signature)
+      else
+        Pure.verify(public_key, message, signature)
+      end
+    end
+
+    # True when this Ruby's openssl can verify Ed25519 signatures.
+    def native?
+      return @native unless @native.nil?
+
+      @native = begin
+        OpenSSL::PKey.respond_to?(:new_raw_public_key) &&
+          OpenSSL::PKey.new_raw_public_key('ED25519', ("\x00".b * 31) + "\x01".b).respond_to?(:verify)
+      rescue StandardError
+        false
+      end
+    end
+
+    def verify_native(public_key, message, signature)
+      OpenSSL::PKey.new_raw_public_key('ED25519', public_key).verify(nil, signature, message)
+    rescue OpenSSL::PKey::PKeyError, ArgumentError
+      false
+    end
+
+    # RFC 8032 section 5.1 in plain integers (extended coordinates).
+    module Pure
+      P = Ed25519::P
+      L = Ed25519::L
+      D = Ed25519::D
+      IDENTITY = [0, 1, 1, 0].freeze
+
+      module_function
+
+      def verify(public_key, message, signature)
+        a_point = decode_point(public_key)
+        return false if a_point.nil?
+
+        r_bytes = signature.byteslice(0, 32)
+        s = int_le(signature.byteslice(32, 32))
+        return false unless s < L
+        return false if decode_point(r_bytes).nil?
+
+        k = int_le(sha512(r_bytes + public_key + message)) % L
+        # [s]B - [k]A must equal R.
+        check = add(scalar_mult(base, s), scalar_mult(negate(a_point), k))
+        encode_point(check) == r_bytes
+      end
+
+      # The 32-byte public key for a 32-byte seed. Exposed so tests can sign with a fresh key.
+      def public_key(seed)
+        encode_point(scalar_mult(base, expand(seed).first))
+      end
+
+      # A 64-byte signature of +message+ by +seed+. Exposed so tests can sign; callers verify with Ed25519.verify.
+      def sign(seed, message)
+        a, prefix = expand(seed)
+        pub = encode_point(scalar_mult(base, a))
+        r = int_le(sha512(prefix + message)) % L
+        r_bytes = encode_point(scalar_mult(base, r))
+        k = int_le(sha512(r_bytes + pub + message)) % L
+        r_bytes + le32((r + (k * a)) % L)
+      end
+
+      def expand(seed)
+        h = sha512(seed)
+        a = int_le(h.byteslice(0, 32))
+        a &= (1 << 254) - 8
+        a |= 1 << 254
+        [a, h.byteslice(32, 32)]
+      end
+
+      def sha512(data)
+        OpenSSL::Digest::SHA512.digest(data)
+      end
+
+      def int_le(bytes)
+        bytes.unpack('C*').each_with_index.sum { |byte, i| byte << (8 * i) }
+      end
+
+      def le32(int)
+        Array.new(32) { |i| (int >> (8 * i)) & 0xff }.pack('C*')
+      end
+
+      def base
+        x = recover_x(Ed25519::BASE_Y, 0)
+        [x, Ed25519::BASE_Y, 1, (x * Ed25519::BASE_Y) % P]
+      end
+
+      def recover_x(y, sign)
+        return nil if y >= P
+
+        x2 = ((y * y) - 1) * ((D * y * y) + 1).pow(P - 2, P) % P
+        if x2.zero?
+          return sign.zero? ? 0 : nil
+        end
+
+        x = x2.pow((P + 3) / 8, P)
+        x = (x * Ed25519::SQRT_M1) % P unless ((x * x) - x2) % P == 0
+        return nil unless ((x * x) - x2) % P == 0
+
+        x = P - x if (x & 1) != sign
+        x
+      end
+
+      def decode_point(bytes)
+        return nil unless bytes.bytesize == 32
+
+        y = int_le(bytes)
+        sign = y >> 255
+        y &= (1 << 255) - 1
+        x = recover_x(y, sign)
+        return nil if x.nil?
+
+        [x, y, 1, (x * y) % P]
+      end
+
+      def encode_point(point)
+        x, y, z, = point
+        zinv = z.pow(P - 2, P)
+        xa = (x * zinv) % P
+        ya = (y * zinv) % P
+        le32(ya | ((xa & 1) << 255))
+      end
+
+      def add(p1, p2)
+        x1, y1, z1, t1 = p1
+        x2, y2, z2, t2 = p2
+        a = ((y1 - x1) * (y2 - x2)) % P
+        b = ((y1 + x1) * (y2 + x2)) % P
+        c = (2 * t1 * t2 * D) % P
+        d = (2 * z1 * z2) % P
+        e = b - a
+        f = d - c
+        g = d + c
+        h = b + a
+        [(e * f) % P, (g * h) % P, (f * g) % P, (e * h) % P]
+      end
+
+      def negate(point)
+        x, y, z, t = point
+        [(-x) % P, y, z, (-t) % P]
+      end
+
+      def scalar_mult(point, scalar)
+        result = IDENTITY
+        addend = point
+        while scalar.positive?
+          result = add(result, addend) if scalar.odd?
+          addend = add(addend, addend)
+          scalar >>= 1
+        end
+        result
+      end
+    end
+  end
+end

data/lib/k9o/end_users.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module K9o
+  # End users: k9o.end_users.*, the people who sign in to the project's own apps.
+  #
+  #   list(status:, q:, limit:, cursor:)       GET /@<slug>/end-users
+  #   get(id)                                  GET /@<slug>/end-users/<id>
+  #   role_grants.list(end_user_id:)           GET    /@<slug>/end-user-role-grants
+  #   role_grants.grant(end_user_id:, role:)   POST   /@<slug>/end-user-role-grants
+  #   role_grants.revoke(grant_id)             DELETE /@<slug>/end-user-role-grants/<grant_id>
+  #
+  # Listing and reading end users needs the project admin role. Role grants are created and revoked by project
+  # admins; reading them is open to a wider set of project roles.
+  class EndUsers
+    STATUSES = %w[active locked deleted all].freeze
+
+    attr_reader :role_grants
+
+    def initialize(config)
+      @config = config
+      @role_grants = EndUserRoleGrants.new(config)
+    end
+
+    # End users, newest first, one page at a time. +status+ is active, locked, deleted or all (default: active and
+    # locked); +q+ is an email prefix; +limit+ is 1 to 200 (default 50).
+    def list(status: nil, q: nil, limit: nil, cursor: nil)
+      ApprovalChecks.check_limit(limit)
+      query = {}
+      query['status'] = ApprovalChecks.enum!(status, STATUSES, 'status') unless status.nil?
+      query['q'] = q unless q.nil?
+      query['limit'] = limit unless limit.nil?
+      query['cursor'] = cursor unless cursor.nil?
+      HttpTransport.request(config: @config, method: 'GET', path: path('end-users'), query: query)
+    end
+
+    # One end user. An unknown id is a 404 K9O_END_USER_NOT_FOUND.
+    def get(id)
+      HttpTransport.request(config: @config, method: 'GET',
+                            path: path("end-users/#{ApprovalChecks.id_segment(id, 'end user')}"))
+    end
+
+    private
+
+    def path(tail)
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'end_users'), tail)
+    end
+  end
+
+  # A role is a free string (1 to 128 characters), not a fixed list.
+  class EndUserRoleGrants
+    def initialize(config)
+      @config = config
+    end
+
+    # The active grants, oldest first. Not paginated. +data+ is the array of grants (the gateway wraps it in
+    # { 'grants' => [...] }). An unknown +end_user_id+ answers an empty list.
+    def list(end_user_id: nil)
+      query = {}
+      query['endUserId'] = end_user_id unless end_user_id.nil?
+      unwrap(HttpTransport.request(config: @config, method: 'GET', path: path, query: query), 'grants')
+    end
+
+    # Give an end user a role; +data+ is the grant. Granting a role the user already holds is a 400
+    # K9O_INVALID_FIELD_VALUE; an unknown end user is a 404 K9O_NOT_FOUND. A revoked role can be granted again.
+    def grant(end_user_id:, role:)
+      body = { 'endUserId' => text!(end_user_id, 'end_user_id', 64), 'role' => text!(role, 'role', 128) }
+      unwrap(HttpTransport.request(config: @config, method: 'POST', path: path, body: body), 'grant')
+    end
+
+    # Revoke a grant (it is kept, marked revoked). +data+ is { 'revoked' => true|false, 'revokedAt' => ... }; an
+    # unknown or already revoked id is not an error, it answers revoked false and revokedAt nil.
+    def revoke(grant_id)
+      HttpTransport.request(config: @config, method: 'DELETE',
+                            path: path("/#{ApprovalChecks.id_segment(grant_id, 'grant')}"))
+    end
+
+    private
+
+    def unwrap(envelope, key)
+      Envelope.new(data: envelope.data.is_a?(Hash) ? envelope.data[key] : envelope.data, meta: envelope.meta)
+    end
+
+    def text!(value, what, max)
+      return value if value.is_a?(String) && !value.empty? && value.length <= max
+
+      raise ApprovalChecks.invalid("#{what} must be a string of 1 to #{max} characters")
+    end
+
+    def path(tail = '')
+      UrlGrammar.project_path(Studio.require_project_slug(@config, 'end_users'), "end-user-role-grants#{tail}")
+    end
+  end
+end

data/lib/k9o/envelope.rb

@@ -20,9 +20,10 @@ module K9o
 
   # Meta accessor sugar.
   class Meta
-    attr_reader :cursor, :subscription, :idempotency, :warnings, :cost, :timing, :context
+    attr_reader :cursor, :subscription, :idempotency, :warnings, :cost, :timing, :context, :approval
 
-    def initialize(cursor: nil, subscription: nil, idempotency: nil, warnings: [], cost: {}, timing: nil, context: nil)
+    def initialize(cursor: nil, subscription: nil, idempotency: nil, warnings: [], cost: {}, timing: nil, context: nil,
+                   approval: nil)
       @cursor = cursor
       @subscription = subscription
       @idempotency = idempotency
@@ -30,6 +31,7 @@ module K9o
       @cost = cost
       @timing = timing
       @context = context
+      @approval = approval
     end
 
     def self.from_wire(wire)
@@ -38,11 +40,12 @@ module K9o
       idem = wire['idempotency'] ? MetaIdempotency.new(replayed: !!wire['idempotency']['replayed']) : nil
       warnings = (wire['warnings'] || []).map { |w| MetaWarning.new(code: w['code'] || '', message: w['message'] || '') }
       timing = wire['timing'] ? MetaTiming.new(total_ms: wire['timing']['totalMs'].to_i) : nil
-      context = wire['context'] && wire['context']['requestId'] ? MetaContext.new(request_id: wire['context']['requestId']) : nil
+      context = wire['context'] && wire['context']['requestId'] ? MetaContext.new(request_id: wire['context']['requestId'], project_id: wire['context']['projectId']) : nil
       Meta.new(
         cursor: cursor, subscription: sub, idempotency: idem,
         warnings: warnings, cost: wire['cost'] || {},
-        timing: timing, context: context
+        timing: timing, context: context,
+        approval: wire['approval'].is_a?(Hash) ? wire['approval'] : nil
       )
     end
   end
@@ -60,5 +63,17 @@ module K9o
   MetaIdempotency = Struct.new(:replayed, keyword_init: true)
   MetaWarning = Struct.new(:code, :message, keyword_init: true)
   MetaTiming = Struct.new(:total_ms, keyword_init: true)
-  MetaContext = Struct.new(:request_id, keyword_init: true)
+  MetaContext = Struct.new(:request_id, :project_id, keyword_init: true)
+end
+
+module K9o
+  # A binary download answer: the bytes exactly as sent and the content type the gateway named (or nil).
+  class Download
+    attr_reader :body, :content_type
+
+    def initialize(body:, content_type: nil)
+      @body = body
+      @content_type = content_type
+    end
+  end
 end

data/lib/k9o/functions.rb

@@ -9,11 +9,14 @@ module K9o
   class Functions
     ARTIFACT_CONTENT_TYPES = { 'wasm' => 'application/wasm', 'tar' => 'application/x-tar' }.freeze
 
+    attr_reader :triggers
+
     def initialize(config)
       @config = config
+      @triggers = FunctionTriggers.new(config)
     end
 
-    # POST /@<slug>/functions/artifacts with the raw bytes: a WebAssembly module for the gateway tier (up to 16 MiB,
+    # POST /@<slug>/functions/artifacts with the raw bytes: a WebAssembly module for the gateway tier (for the platform operator; a project's deploy to it is refused) (up to 16 MiB,
     # +kind+ 'wasm') or an OCI image archive for the sandbox tier (up to 256 MiB, +kind+ 'tar'). Uploading the same
     # bytes again returns the same key. The envelope's data is { 'artifactKey' => String }.
     def upload_artifact(bytes, kind)
@@ -30,8 +33,9 @@ module K9o
     end
 
     # POST /@<slug>/functions — deploy or redeploy from an uploaded artifact.
-    #   runtime: bun python go java kotlin dotnet swift php ruby rust tinygo zig assemblyscript
-    #   tier:    'gateway' (WebAssembly) or 'sandbox' (OCI image archive)
+    #   Functions run in the sandbox. tier: 'sandbox' (OCI image archive); runtime: bun python go java kotlin dotnet
+    #   swift php ruby rust zig. 'gateway' (WebAssembly) is for the platform operator and is refused for a customer
+    #   deploy; tinygo and assemblyscript run only there, so they cannot be deployed to a project.
     #   artifact_key: the key +upload_artifact+ returned; version: label for this deploy (1 to 64 characters)
     def deploy(name:, runtime:, tier:, artifact_key:, version:, description: nil)
       slug = require_project_slug
@@ -87,4 +91,79 @@ module K9o
       ::URI.encode_www_form_component(s)
     end
   end
+
+  # Event triggers: k9o.functions.triggers.* run a function when a record is inserted, updated, deleted or upserted
+  # in a collection. They need the project admin role. For triggers on a timetable see +k9o.schedules+.
+  #
+  #   list(name)                                   GET    /@<slug>/functions/<name>/triggers
+  #   create(name, collection:, events:, ...)      POST   /@<slug>/functions/<name>/triggers
+  #   update(name, trigger_id, **fields)           PATCH  /@<slug>/functions/<name>/triggers/<id>
+  #   delete(name, trigger_id)                     DELETE /@<slug>/functions/<name>/triggers/<id>   (204, no body)
+  class FunctionTriggers
+    EVENTS = %w[insert update delete upsert].freeze
+    COLLECTION_RE = /\A[a-zA-Z_][a-zA-Z0-9_]{0,127}\z/.freeze
+    UPDATE_FIELDS = %i[events filter enabled log_ok_invocations].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # Every trigger of the function, newest first. Not paginated.
+    def list(name)
+      call('GET', path(name))
+    end
+
+    # Create an event trigger; answers 201 with the trigger. +events+ lists 1 to 4 of insert, update, delete, upsert.
+    # +filter+ is a predicate Hash over the record; leave it out to fire on every matching event.
+    def create(name, collection:, events:, filter: nil, enabled: nil, log_ok_invocations: nil)
+      unless collection.is_a?(String) && COLLECTION_RE.match?(collection)
+        raise ApprovalChecks.invalid('collection must match ^[a-zA-Z_][a-zA-Z0-9_]*$ (1 to 128 characters)',
+                                     collection: collection)
+      end
+
+      body = { 'collection' => collection, 'events' => check_events(events) }
+      body['filter'] = filter unless filter.nil?
+      body['enabled'] = enabled unless enabled.nil?
+      body['logOkInvocations'] = log_ok_invocations unless log_ok_invocations.nil?
+      call('POST', path(name), body: body)
+    end
+
+    # Change a trigger; send at least one of +events+, +filter+, +enabled+, +log_ok_invocations+. A Hash +filter+
+    # replaces the filter and an explicit +filter: nil+ clears it. The collection cannot be changed.
+    def update(name, trigger_id, **fields)
+      unknown = fields.keys - UPDATE_FIELDS
+      raise ApprovalChecks.invalid("unknown field: #{unknown.join(', ')}") unless unknown.empty?
+      raise ApprovalChecks.invalid("patch needs at least one of: #{UPDATE_FIELDS.join(', ')}") if fields.empty?
+
+      body = {}
+      body['events'] = check_events(fields[:events]) if fields.key?(:events)
+      body['filter'] = fields[:filter] if fields.key?(:filter)
+      body['enabled'] = fields[:enabled] if fields.key?(:enabled)
+      body['logOkInvocations'] = fields[:log_ok_invocations] if fields.key?(:log_ok_invocations)
+      call('PATCH', path(name, "/#{ApprovalChecks.id_segment(trigger_id, 'trigger')}"), body: body)
+    end
+
+    # Delete a trigger. Answers 204, so +data+ is nil; deleting again is a 404.
+    def delete(name, trigger_id)
+      call('DELETE', path(name, "/#{ApprovalChecks.id_segment(trigger_id, 'trigger')}"))
+    end
+
+    private
+
+    def check_events(events)
+      list = events.is_a?(Array) ? events.map { |e| e.is_a?(Symbol) ? e.to_s : e } : nil
+      return list if list && list.size.between?(1, 4) && list.all? { |e| EVENTS.include?(e) }
+
+      raise ApprovalChecks.invalid('events must list 1 to 4 of insert, update, delete, upsert', events: events)
+    end
+
+    def call(method, route, body: nil)
+      HttpTransport.request(config: @config, method: method, path: route, body: body)
+    end
+
+    def path(name, tail = '')
+      slug = Studio.require_project_slug(@config, 'functions')
+      UrlGrammar.project_path(slug, "functions/#{ApprovalChecks.id_segment(name, 'function')}/triggers#{tail}")
+    end
+  end
 end

data/lib/k9o/gate.rb

@@ -15,17 +15,26 @@ module K9o
     end
 
     # POST /@<slug>/gate/signin { email, password }
+    #
+    # Asks the project which region holds the email first (POST /@<slug>/gate/locate, the email only, no credential),
+    # then sends the password to that region's host if it is a host of your own org and apex, else to the base URL.
+    # A 429 or 503 from that step raises as any gateway error does, nothing else is sent, and it is safe to retry.
     def sign_in(email:, password:)
-      HttpTransport.request(
+      origin = Locate.origin_for(@config, email, gate_path('locate'))
+      out = HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('signin'),
-        body: { 'email' => email, 'password' => password }
+        body: { 'email' => email, 'password' => password }, origin: origin
       )
+      Locate.remember(session_refresh_token(out), origin)
+      out
     end
 
     # POST /@<slug>/gate/signout { refreshToken } — the refresh token is required (the gateway answers 400 without it).
     def sign_out(refresh_token:)
-      HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'),
-                            body: { 'refreshToken' => refresh_token })
+      out = HttpTransport.request(config: @config, method: 'POST', path: gate_path('signout'),
+                                  body: { 'refreshToken' => refresh_token }, origin: Locate.hint(refresh_token))
+      Locate.forget(refresh_token)
+      out
     end
 
     # GET /@<slug>/gate/whoami
@@ -33,23 +42,53 @@ module K9o
       HttpTransport.request(config: @config, method: 'GET', path: gate_path('whoami'))
     end
 
+    # POST /@<slug>/auth/sessions/revoke-all
+    #
+    # Ends every live session of the signed-in end user, on every device, this one included. Call it with the end
+    # user's access token as the client's `api_key` (the token `whoami` uses), not a refresh token. The answer's `data`
+    # is `{ revokedCount }`. Each ended session's next refresh raises a KError with code `K9O_SESSION_EXPIRED` and a
+    # `reason` of `"revoked"` in its `context`; access tokens already issued keep working until they expire. An
+    # operator's token raises `K9O_TRUST_ZONE_VIOLATION` (403), and a token issued for another project
+    # `K9O_PROJECT_SCOPE_MISMATCH` (403).
+    def revoke_all_sessions
+      HttpTransport.request(config: @config, method: 'POST', path: project_path('auth/sessions/revoke-all'))
+    end
+
     # POST /@<slug>/gate/refresh { refreshToken }
+    #
+    # The answer's `data` is `{ accessToken, refreshToken, expiresAt }`. The refresh token you sent stops working: store
+    # the returned `refreshToken` before the next refresh, and refresh one at a time per session. A second call with a
+    # secret that was already used is a replay: the session is revoked and the call raises a KError with code
+    # `K9O_SESSION_EXPIRED` and a `reason` of `"replay"` in its `context`. The newer secret then gets `"revoked"`. The
+    # other reasons are `"inactive"` and `"max_length"`; sign in again.
     def refresh_token(refresh_token:)
-      HttpTransport.request(
+      out = HttpTransport.request(
         config: @config, method: 'POST', path: gate_path('refresh'),
-        body: { 'refreshToken' => refresh_token }
+        body: { 'refreshToken' => refresh_token }, origin: Locate.hint(refresh_token)
       )
+      Locate.rotate(refresh_token, out.respond_to?(:data) ? out.data : nil)
+      out
     end
 
     private
 
+    def session_refresh_token(envelope)
+      data = envelope.respond_to?(:data) ? envelope.data : nil
+      session = data.is_a?(Hash) ? data['session'] : nil
+      session.is_a?(Hash) ? session['refreshToken'] : nil
+    end
+
     def gate_path(action)
+      project_path("gate/#{action}")
+    end
+
+    def project_path(suffix)
       raise KError.new(
         code: 'K9O_MISSING_PROJECT_CONTEXT',
         message: 'k9o.gate operations require project_slug bound on the client',
         context: {}
       ) if @config.project_slug.nil? || @config.project_slug.empty?
-      UrlGrammar.project_path(@config.project_slug, "gate/#{action}")
+      UrlGrammar.project_path(@config.project_slug, suffix)
     end
   end
 end