atlas-auth 0.1.0

data/lib/atlas/handshake.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "securerandom"
+require "digest"
+require "base64"
+
+require_relative "error"
+require_relative "transport"
+
+module Atlas
+  # A fresh session minted by redeeming a cross-property handshake nonce.
+  #
+  # These are the cookie VALUES a satellite's Rack/Rails handler sets as its own
+  # first-party cookies: +jwt+ as +__session+ (script-readable, short-lived) and
+  # +refresh_token+ as +__atlas_rt+ (HttpOnly).
+  #
+  # @!attribute [r] jwt
+  #   @return [String] the +__session+ JWT value.
+  # @!attribute [r] refresh_token
+  #   @return [String] the +__atlas_rt+ refresh value (set HttpOnly).
+  # @!attribute [r] session_id
+  #   @return [String] the session id ("" when the server omits it).
+  # @!attribute [r] expires_in
+  #   @return [Integer] seconds until the +__session+ JWT expires.
+  HandshakeSession = Struct.new(:jwt, :refresh_token, :session_id, :expires_in, keyword_init: true)
+
+  # Cross-property SSO handshake — the second property's server-side redeem step.
+  #
+  # When a satellite (a property on a DIFFERENT registrable domain than the main
+  # app) has no local session, a middleware bounces the browser through
+  # +GET {fapi_origin}/v1/client/handshake+, which — if the user has an Atlas
+  # session — redirects back with
+  # +?__atlas_hs=ok&__atlas_hu=<user_id>&__atlas_hn=<nonce>+. These helpers read
+  # those params and exchange the single-use nonce for a fresh session,
+  # server-to-server, so the tokens come back in the response BODY (never a URL).
+  #
+  # PKCE binding (RFC 7636, S256). The +__atlas_hn+ nonce rides the return URL,
+  # which lands in access logs, +Referer+ headers, and browser history — so the
+  # nonce alone MUST NOT be a bearer credential. Before bouncing to the handshake
+  # we mint a PKCE pair with {create_pkce_pair}: the +challenge+ (a SHA-256 hash)
+  # travels on the loggable outbound URL as +code_challenge+, while the +verifier+
+  # is stashed server-side in an HttpOnly cookie (+__atlas_hv+, path +/+, ~300s)
+  # that never appears in any URL. At redeem we send the +verifier+ back in the
+  # request BODY; the Atlas server hashes it and checks it matches the challenge
+  # it recorded against the nonce. An attacker who scrapes the nonce out of a log
+  # can't redeem it without the verifier, which was never logged. (The Atlas
+  # server now REQUIRES +code_verifier+ on redeem — an unbound redeem fails.)
+  #
+  # Same-registrable-domain SUBDOMAINS don't need this — the handshake sets a
+  # parent-domain cookie directly; this is only the cross-domain path.
+  #
+  # Framework-agnostic usage in a satellite's route handler (Rack/Rails/Sinatra):
+  #
+  #   params = Atlas::Handshake.read_handshake_params(request.url)
+  #   if params
+  #     session = Atlas::Handshake.redeem_handshake(
+  #       fapi_origin:     "https://id.atlasauth.net",
+  #       publishable_key: "pk_live_...",
+  #       user_id:         params[:user_id],
+  #       nonce:           params[:nonce],
+  #       # The verifier we stashed in __atlas_hv when we bounced out (below):
+  #       code_verifier:   request.cookies["__atlas_hv"],
+  #     )
+  #     if session
+  #       # Set the satellite's OWN first-party cookies:
+  #       response.set_cookie("__session",
+  #         value: session.jwt, path: "/", same_site: :lax, secure: true)
+  #       response.set_cookie("__atlas_rt",
+  #         value: session.refresh_token, path: "/",
+  #         httponly: true, same_site: :lax, secure: true)
+  #       response.delete_cookie("__atlas_hv") # single-use; done with it.
+  #     end
+  #     # else: nonce was bad/expired/used — fall through to sign-in.
+  #   end
+  #
+  # A middleware that TRIGGERS the handshake mints a PKCE pair, stashes the
+  # verifier, and redirects once to
+  # +{fapi_origin}/v1/client/handshake?publishable_key={pk}&redirect_url={current_url}&code_challenge={challenge}+
+  # only when there is no local session AND the +__atlas_hs+ query param is absent
+  # (its presence means we already came back from the handshake), so it can never
+  # loop:
+  #
+  #   pkce = Atlas::Handshake.create_pkce_pair
+  #   response.set_cookie("__atlas_hv",
+  #     value: pkce[:verifier], path: "/", max_age: 300,
+  #     httponly: true, same_site: :lax, secure: true)
+  #   url = "#{fapi_origin}/v1/client/handshake" \
+  #     "?publishable_key=#{pk}" \
+  #     "&redirect_url=#{CGI.escape(current_url)}" \
+  #     "&code_challenge=#{pkce[:challenge]}"
+  #   redirect_to url
+  module Handshake
+    module_function
+
+    # Mint a PKCE pair (RFC 7636, S256) for one handshake round-trip.
+    #
+    # The handshake nonce travels back to the satellite on a query string, so it
+    # is written to access logs, leaked in +Referer+ headers, and kept in browser
+    # history. If the nonce alone could be redeemed, anyone who reads one of those
+    # logs holds a usable credential. PKCE fixes that by splitting the secret in
+    # two: the +challenge+ (an irreversible SHA-256 hash) is what rides the
+    # loggable outbound URL as +code_challenge+, and the +verifier+ (the
+    # pre-image) is stashed server-side in an HttpOnly cookie (+__atlas_hv+) that
+    # never touches a URL. At redeem the verifier is sent in the request BODY and
+    # the Atlas server hashes it and checks it against the challenge it bound to
+    # the nonce — so a scraped nonce is inert without the verifier, which was
+    # never logged.
+    #
+    # +verifier+ is 32 bytes of {SecureRandom} base64url-encoded without padding
+    # (43 chars, well inside RFC 7636's 43–128 range). +challenge+ is the
+    # base64url-no-padding SHA-256 digest of the verifier's ASCII bytes (the S256
+    # transform). Both use +padding: false+ because RFC 7636 §3 forbids the
+    # trailing +=+ and requires the URL-safe alphabet.
+    #
+    # @return [Hash{Symbol=>String}] +{ verifier:, challenge: }+ — send
+    #   +challenge+ on the outbound handshake URL as +code_challenge+, stash
+    #   +verifier+ HttpOnly, and pass it back to {redeem_handshake} as
+    #   +code_verifier+.
+    def create_pkce_pair
+      verifier = Base64.urlsafe_encode64(SecureRandom.random_bytes(32), padding: false)
+      challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      { verifier: verifier, challenge: challenge }
+    end
+
+    # Redeem a handshake nonce for a fresh session.
+    #
+    # POSTs to +{fapi_origin}/v1/client/handshake/redeem+ with header
+    # +X-Publishable-Key: {publishable_key}+ and JSON body
+    # +{ "user_id" => user_id, "nonce" => nonce, "code_verifier" => code_verifier }+.
+    #
+    # @param fapi_origin [String] origin of the Atlas Frontend API,
+    #   e.g. +https://id.atlasauth.net+.
+    # @param publishable_key [String] the instance publishable key (+pk_...+).
+    # @param user_id [String] the +__atlas_hu+ value from the return URL.
+    # @param nonce [String] the single-use +__atlas_hn+ nonce from the return URL.
+    # @param code_verifier [String, nil] the PKCE verifier stashed (in the
+    #   +__atlas_hv+ HttpOnly cookie) when the handshake was triggered — the
+    #   pre-image of the +code_challenge+ that rode the outbound URL. The Atlas
+    #   server now REQUIRES this: a redeem without the verifier that matches the
+    #   bound challenge fails, and this returns +nil+ like any other bad-nonce.
+    # @param http [#call, nil] injectable requester matching the Transport seam —
+    #   +call(method, url, headers, body) -> [status_integer, body_string]+.
+    #   Defaults to {Atlas::NetHTTPRequester}.
+    #
+    # @return [Atlas::HandshakeSession, nil] the fresh session, or +nil+ when the
+    #   nonce is missing/expired/already used, the verifier doesn't bind, or the
+    #   request could not complete. A bad nonce is a normal "signed-out" signal —
+    #   this NEVER raises on an auth failure or a transport error, so it can't
+    #   take the page down.
+    def redeem_handshake(fapi_origin:, publishable_key:, user_id:, nonce:, code_verifier: nil, http: nil)
+      requester = http || NetHTTPRequester.new
+      url = "#{fapi_origin.sub(%r{/+\z}, '')}/v1/client/handshake/redeem"
+      headers = {
+        "content-type" => "application/json",
+        "accept" => "application/json",
+        "x-publishable-key" => publishable_key
+      }
+      payload = JSON.generate(
+        { "user_id" => user_id, "nonce" => nonce, "code_verifier" => code_verifier }
+      )
+
+      status, text = requester.call("POST", url, headers, payload)
+      return nil unless status.is_a?(Integer) && status.between?(200, 299)
+
+      data = parse_json(text)
+      return nil unless data.is_a?(Hash)
+
+      jwt = data["jwt"]
+      refresh_token = data["refresh_token"]
+      return nil if jwt.nil? || jwt.empty? || refresh_token.nil? || refresh_token.empty?
+
+      HandshakeSession.new(
+        jwt: jwt,
+        refresh_token: refresh_token,
+        session_id: data["session_id"] || "",
+        expires_in: (data["expires_in"] || 0).to_i
+      )
+    rescue StandardError
+      # A transport error is indistinguishable, to the user, from a signed-out
+      # state — return nil and let the caller fall back to sign-in.
+      nil
+    end
+
+    # Extract the handshake params from a return URL or query string.
+    #
+    # @param url_or_query [String] a full URL, a query string, or a bare
+    #   +key=value&...+ fragment.
+    # @return [Hash{Symbol=>String}, nil] +{ user_id:, nonce: }+ when
+    #   +__atlas_hs == "ok"+ and both +__atlas_hu+ and +__atlas_hn+ are present;
+    #   +nil+ otherwise.
+    def read_handshake_params(url_or_query)
+      return nil if url_or_query.nil?
+
+      query = url_or_query.include?("?") ? url_or_query[(url_or_query.index("?") + 1)..] : url_or_query
+      query = query.sub(/#.*\z/, "") if query # drop any fragment
+      return nil if query.nil? || query.empty?
+
+      params = {}
+      URI.decode_www_form(query).each { |key, value| params[key] = value }
+
+      return nil unless params["__atlas_hs"] == "ok"
+
+      user_id = params["__atlas_hu"]
+      nonce = params["__atlas_hn"]
+      return nil if user_id.nil? || user_id.empty? || nonce.nil? || nonce.empty?
+
+      { user_id: user_id, nonce: nonce }
+    rescue StandardError
+      nil
+    end
+
+    def parse_json(text)
+      return nil if text.nil? || text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # Convenience mirrors on the top-level module, matching the standalone auth
+  # helpers (+Atlas.has_permission?+, +Atlas.protect+, ...).
+  module_function
+
+  # @see Atlas::Handshake.create_pkce_pair
+  def create_pkce_pair
+    Handshake.create_pkce_pair
+  end
+
+  # @see Atlas::Handshake.redeem_handshake
+  def redeem_handshake(**kwargs)
+    Handshake.redeem_handshake(**kwargs)
+  end
+
+  # @see Atlas::Handshake.read_handshake_params
+  def read_handshake_params(url_or_query)
+    Handshake.read_handshake_params(url_or_query)
+  end
+end

data/lib/atlas/jwks_cache.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+require "net/http"
+require "uri"
+
+module Atlas
+  # §7.3: "JWKS cached in-process with kid-miss refetch (max 1/min) so key
+  # rotation needs no deploys."
+  #
+  # The rate limit on the refetch is the security property, not a politeness.
+  # Without it, an attacker sends tokens carrying random +kid+ values and every
+  # one forces an outbound request to the JWKS endpoint — turning any
+  # unauthenticated caller into a traffic amplifier. The cache's job is as much
+  # to refuse to fetch as it is to fetch.
+  class JwksCache
+    # §7.3: at most one refetch per minute, however many misses arrive.
+    REFETCH_INTERVAL_MS = 60_000
+    # §7.3 serves +Cache-Control: max-age=3600+; honoured rather than ignored.
+    DEFAULT_TTL_MS = 3_600_000
+
+    # Exposed so a caller can assert the rate limit actually bit.
+    # One of :fresh, :cached, :refetched, :throttled, :failed.
+    attr_reader :last_outcome
+
+    # @param url [String] the instance JWKS URL.
+    # @param fetch_impl [#call] optional +call(url) -> [status, body]+ for tests.
+    # @param now [#call] optional clock returning epoch milliseconds.
+    def initialize(url:, fetch_impl: nil, now: nil, ttl_ms: DEFAULT_TTL_MS,
+                   refetch_interval_ms: REFETCH_INTERVAL_MS)
+      @url = url
+      @fetch_impl = fetch_impl
+      @now = now
+      @ttl_ms = ttl_ms
+      @refetch_interval_ms = refetch_interval_ms
+      @cached = nil
+      @fetched_at = 0
+      @last_attempt_at = 0
+      @last_outcome = :fresh
+      @mutex = Mutex.new
+    end
+
+    # The JWKS to verify against, refetching if this +kid+ is unknown. Returns
+    # whatever is cached when a refetch is throttled or fails — a stale JWKS
+    # still verifies every token signed by a key it contains.
+    #
+    # @return [Hash, nil] a +{ "keys" => [...] }+ hash, or nil if never fetched.
+    def get(kid = nil)
+      @mutex.synchronize do
+        now = current_time
+        expired = @cached.nil? || (now - @fetched_at) >= @ttl_ms
+        kid_miss = !@cached.nil? && !key?(kid)
+
+        if !expired && !kid_miss
+          @last_outcome = :cached
+          return @cached
+        end
+
+        if kid_miss && !expired && (now - @last_attempt_at) < @refetch_interval_ms
+          @last_outcome = :throttled
+          return @cached
+        end
+
+        @last_attempt_at = now
+        begin
+          body = fetch_jwks
+          raise "JWKS is malformed" unless body.is_a?(Hash) && body["keys"].is_a?(Array)
+
+          @cached = body
+          @fetched_at = now
+          @last_outcome = kid_miss ? :refetched : :fresh
+          @cached
+        rescue StandardError
+          # Keep serving what we have. A JWKS outage should degrade to "new keys
+          # do not work yet", not "nobody can authenticate".
+          @last_outcome = :failed
+          @cached
+        end
+      end
+    end
+
+    # Test and diagnostic surface — never used for a security decision.
+    def snapshot
+      { keys: @cached ? @cached["keys"].length : 0, fetched_at: @fetched_at }
+    end
+
+    private
+
+    def current_time
+      @now ? @now.call : (Time.now.to_f * 1000).to_i
+    end
+
+    def key?(kid)
+      return false if @cached.nil?
+      return !@cached["keys"].empty? if kid.nil?
+
+      @cached["keys"].any? { |k| k["kid"] == kid }
+    end
+
+    def fetch_jwks
+      if @fetch_impl
+        status, text = @fetch_impl.call(@url)
+        raise "JWKS fetch failed (#{status})" unless status.between?(200, 299)
+
+        return JSON.parse(text)
+      end
+
+      uri = URI.parse(@url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      request = Net::HTTP::Get.new(uri.request_uri)
+      request["accept"] = "application/json"
+      response = http.request(request)
+      raise "JWKS fetch failed (#{response.code})" unless response.code.to_i.between?(200, 299)
+
+      JSON.parse(response.body.to_s)
+    end
+  end
+
+  # Read the +kid+ from a JWT header without verifying anything.
+  def self.read_kid(jwt)
+    header = jwt.to_s.split(".").first
+    return nil if header.nil? || header.empty?
+
+    decoded = Base64.urlsafe_decode64(pad_base64(header))
+    parsed = JSON.parse(decoded)
+    parsed["kid"].is_a?(String) ? parsed["kid"] : nil
+  rescue StandardError
+    nil
+  end
+
+  # Base64url strings from JWTs are unpadded; restore padding before decoding.
+  def self.pad_base64(str)
+    str += "=" * ((4 - (str.length % 4)) % 4)
+    str
+  end
+end

data/lib/atlas/pagination.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Atlas
+  # Cursor-pagination helpers.
+  #
+  # Walk every page of a cursor-paginated BAPI list, yielding items one at a
+  # time. Works with any resource +list+ that takes +limit+/+starting_after+
+  # (plus any route-specific filters) and returns a
+  # +{ "data", "has_more", "next_cursor" }+ page — +users.list+,
+  # +organizations.list+, +invitations.list+, +audit_logs.list+, +waitlist.list+.
+  #
+  #   Atlas.paginate(client.users).each { |user| puts user["id"] }
+  #   Atlas.paginate(client.users, status: "active").to_a
+  #
+  # Kept as free functions rather than bolted onto every return value: the page
+  # is the primitive most callers want, and a caller who needs the whole set
+  # opts into the extra round trips explicitly.
+  module Pagination
+    module_function
+
+    # Yield every item across every cursor page. Returns an Enumerator when no
+    # block is given, so +.each+, +.map+, +.lazy+, +.first(n)+ all work.
+    #
+    # @param resource [#list] anything exposing a +list(params)+ method.
+    # @param params [Hash] filters passed through on every page request.
+    def paginate(resource, params = {}, &block)
+      return enum_for(:paginate, resource, params) unless block_given?
+
+      cursor = params[:starting_after] || params["starting_after"]
+      loop do
+        page = resource.list(params.merge(starting_after: cursor))
+        (page["data"] || []).each(&block)
+        cursor = page["next_cursor"]
+        break if !page["has_more"] || cursor.nil?
+      end
+    end
+
+    # Collect every page of a cursor-paginated list into a single array.
+    def collect(resource, params = {})
+      paginate(resource, params).to_a
+    end
+  end
+
+  # Convenience delegators so callers write +Atlas.paginate(...)+.
+  def self.paginate(resource, params = {}, &block)
+    Pagination.paginate(resource, params, &block)
+  end
+
+  def self.collect(resource, params = {})
+    Pagination.collect(resource, params)
+  end
+end

data/lib/atlas/resources/actions.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/actions+ — tenant code run in the hardened isolate at auth triggers,
+    # plus the per-trigger binding lists.
+    class Actions < Base
+      def list
+        request(method: :get, path: "/v1/actions")
+      end
+
+      def create(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/actions", body: body, idempotency_key: idempotency_key)
+      end
+
+      def get(id)
+        request(method: :get, path: "/v1/actions/#{enc(id)}")
+      end
+
+      def update(id, body)
+        request(method: :patch, path: "/v1/actions/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        request(method: :delete, path: "/v1/actions/#{enc(id)}")
+      end
+
+      # Dry-run against a sample event in the sandbox; nothing is persisted.
+      def test(id, event = {})
+        request(method: :post, path: "/v1/actions/#{enc(id)}/test", body: { event: event })
+      end
+
+      # The actions bound to a trigger, in run order.
+      def get_bindings(trigger)
+        request(method: :get, path: "/v1/actions/bindings/#{enc(trigger)}")
+      end
+
+      # Replace a trigger's ordered binding set.
+      def set_bindings(trigger, action_ids)
+        request(method: :put, path: "/v1/actions/bindings/#{enc(trigger)}", body: { action_ids: action_ids })
+      end
+    end
+  end
+end

data/lib/atlas/resources/actor_tokens.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/actor_tokens+ — impersonation tokens (act-as another subject).
+    class ActorTokens < Base
+      def create(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/actor_tokens", body: body, idempotency_key: idempotency_key)
+      end
+
+      def revoke(id)
+        request(method: :post, path: "/v1/actor_tokens/#{enc(id)}/revoke")
+      end
+    end
+  end
+end

data/lib/atlas/resources/api_keys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/api_keys+ — end-user API keys a tenant mints for its own subjects.
+    class ApiKeys < Base
+      # Optionally narrowed to one subject via +subject_type+/+subject_id+.
+      def list(query = nil)
+        request(method: :get, path: "/v1/api_keys", query: query)
+      end
+
+      # Mint a key. The secret is returned once, here.
+      def create(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/api_keys", body: body, idempotency_key: idempotency_key)
+      end
+
+      # Check a presented secret. Rate-limited — it is an online credential check.
+      def verify(secret)
+        request(method: :post, path: "/v1/api_keys/verify", body: { secret: secret })
+      end
+
+      def get(id)
+        request(method: :get, path: "/v1/api_keys/#{enc(id)}")
+      end
+
+      def update(id, body)
+        request(method: :patch, path: "/v1/api_keys/#{enc(id)}", body: body)
+      end
+
+      # Revoke a key. It stays queryable but never authenticates again.
+      def delete(id)
+        request(method: :delete, path: "/v1/api_keys/#{enc(id)}")
+      end
+    end
+  end
+end

data/lib/atlas/resources/attack_protection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/attack_protection+ — brute-force, breached-password, and related gates.
+    class AttackProtection < Base
+      def get
+        request(method: :get, path: "/v1/attack_protection")
+      end
+
+      def update(body)
+        request(method: :patch, path: "/v1/attack_protection", body: body)
+      end
+    end
+  end
+end

data/lib/atlas/resources/audit_logs.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/audit_logs+ — the instance audit trail, cursor-paginated.
+    class AuditLogs < Base
+      def list(params = {})
+        request(method: :get, path: "/v1/audit_logs", query: params)
+      end
+    end
+  end
+end

data/lib/atlas/resources/base.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Atlas
+  module Resources
+    # Shared base for every resource namespace. Holds the config-bound transport
+    # and forwards +#request+, so each namespace method stays a one-liner naming
+    # a verb, a path, and its shapes.
+    class Base
+      def initialize(transport)
+        @transport = transport
+      end
+
+      private
+
+      # Forward to the transport. Keeps +Transport::OMIT+ as the default body so
+      # a method that names no body sends none (no content-type), matching the
+      # reference SDKs.
+      def request(method:, path:, query: nil, body: Atlas::Transport::OMIT,
+                  idempotency_key: nil, raw: false)
+        @transport.request(
+          method: method, path: path, query: query, body: body,
+          idempotency_key: idempotency_key, raw: raw
+        )
+      end
+
+      # Percent-encode a single path segment (an id, slug, provider name).
+      def enc(segment)
+        URI.encode_www_form_component(segment.to_s)
+      end
+    end
+  end
+end

data/lib/atlas/resources/billing.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/billing+ — the plans a tenant defines for its users, and the read-only
+    # subscription view.
+    class Billing < Base
+      def list_plans
+        request(method: :get, path: "/v1/billing/plans")
+      end
+
+      def create_plan(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/billing/plans", body: body, idempotency_key: idempotency_key)
+      end
+
+      def get_plan(id)
+        request(method: :get, path: "/v1/billing/plans/#{enc(id)}")
+      end
+
+      def update_plan(id, body)
+        request(method: :patch, path: "/v1/billing/plans/#{enc(id)}", body: body)
+      end
+
+      def delete_plan(id)
+        request(method: :delete, path: "/v1/billing/plans/#{enc(id)}")
+      end
+
+      def list_subscriptions(params = nil)
+        request(method: :get, path: "/v1/billing/subscriptions", query: params)
+      end
+    end
+  end
+end

data/lib/atlas/resources/bot_signals.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/bot_signals+ — export the anti-bot signal lake and its training labels,
+    # and add analyst labels.
+    class BotSignals < Base
+      # Page the signal lake, newest first, for an incremental pull.
+      def list(query = nil)
+        request(method: :get, path: "/v1/bot_signals", query: query)
+      end
+
+      # Page the training labels, newest first.
+      def list_labels(query = nil)
+        request(method: :get, path: "/v1/bot_labels", query: query)
+      end
+
+      # Attach a training label to a user / device / ip_hash / attempt.
+      def create_label(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/bot_labels", body: body, idempotency_key: idempotency_key)
+      end
+    end
+  end
+end