atlas-auth 0.1.0

data/lib/atlas/resources/users.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/users+ — the user directory, plus emails, identities, MFA, sessions,
+    # OAuth access tokens, and consent grants.
+    class Users < Base
+      # +GET /v1/users+ — cursor-paginated.
+      def list(params = {})
+        request(method: :get, path: "/v1/users", query: params)
+      end
+
+      def get(id)
+        request(method: :get, path: "/v1/users/#{enc(id)}")
+      end
+
+      def create(body, idempotency_key: nil)
+        request(method: :post, path: "/v1/users", body: body, idempotency_key: idempotency_key)
+      end
+
+      def update(id, body)
+        request(method: :patch, path: "/v1/users/#{enc(id)}", body: body)
+      end
+
+      # +PUT /v1/users/:id/metadata+ — replaces the named bags wholesale.
+      def replace_metadata(id, body)
+        request(method: :put, path: "/v1/users/#{enc(id)}/metadata", body: body)
+      end
+
+      def ban(id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/ban")
+      end
+
+      def unban(id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/unban")
+      end
+
+      def lock(id, body = {})
+        request(method: :post, path: "/v1/users/#{enc(id)}/lock", body: body)
+      end
+
+      def unlock(id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/unlock")
+      end
+
+      def delete(id)
+        request(method: :delete, path: "/v1/users/#{enc(id)}")
+      end
+
+      def reset_mfa(id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/reset_mfa")
+      end
+
+      def delete_mfa_factor(id, factor_id)
+        request(method: :delete, path: "/v1/users/#{enc(id)}/mfa/#{enc(factor_id)}")
+      end
+
+      def list_sessions(id)
+        request(method: :get, path: "/v1/users/#{enc(id)}/sessions")
+      end
+
+      def revoke_sessions(id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/sessions/revoke")
+      end
+
+      def add_email(id, body)
+        request(method: :post, path: "/v1/users/#{enc(id)}/email_addresses", body: body)
+      end
+
+      def verify_email(id, email_id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/email_addresses/#{enc(email_id)}/verify")
+      end
+
+      def set_primary_email(id, email_id)
+        request(method: :post, path: "/v1/users/#{enc(id)}/email_addresses/#{enc(email_id)}/primary")
+      end
+
+      # +GET /v1/users/:id/oauth_access_tokens/:provider+ — a live provider credential.
+      def get_oauth_access_token(id, provider)
+        request(method: :get, path: "/v1/users/#{enc(id)}/oauth_access_tokens/#{enc(provider)}")
+      end
+
+      # +GET /v1/users/:id/identities+ — base Atlas identity + one per linked account.
+      def list_identities(id)
+        request(method: :get, path: "/v1/users/#{enc(id)}/identities")
+      end
+
+      # +POST /v1/users/:id/identities+ — merge a secondary user INTO this one.
+      def link_identity(id, body, idempotency_key: nil)
+        request(method: :post, path: "/v1/users/#{enc(id)}/identities", body: body, idempotency_key: idempotency_key)
+      end
+
+      # +POST /v1/users/:id/external_accounts/connect+ — backend-initiated connect flow.
+      def connect_external_account(id, body, idempotency_key: nil)
+        request(method: :post, path: "/v1/users/#{enc(id)}/external_accounts/connect", body: body, idempotency_key: idempotency_key)
+      end
+
+      # +DELETE /v1/users/:id/identities/:identity_id+ — extract a linked identity into a new user.
+      def unlink_identity(id, identity_id)
+        request(method: :delete, path: "/v1/users/#{enc(id)}/identities/#{enc(identity_id)}")
+      end
+
+      # +GET /v1/users/:id/grants+ — the OAuth clients this user has authorized.
+      def list_grants(id)
+        request(method: :get, path: "/v1/users/#{enc(id)}/grants")
+      end
+
+      # +DELETE /v1/users/:id/grants+ — revoke every consent grant the user holds.
+      def revoke_all_grants(id)
+        request(method: :delete, path: "/v1/users/#{enc(id)}/grants")
+      end
+
+      # +DELETE /v1/grants/:id+ — revoke ONE consent grant (instance-scoped).
+      def revoke_grant(grant_id)
+        request(method: :delete, path: "/v1/grants/#{enc(grant_id)}")
+      end
+    end
+  end
+end

data/lib/atlas/resources/waitlist.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/waitlist_entries+ — the sign-up waitlist and its approve/deny decisions.
+    class Waitlist < Base
+      def list(params = {})
+        request(method: :get, path: "/v1/waitlist_entries", query: params)
+      end
+
+      # Approve or deny a waitlist entry.
+      def decide(id, body)
+        request(method: :post, path: "/v1/waitlist_entries/#{enc(id)}/decide", body: body)
+      end
+    end
+  end
+end

data/lib/atlas/resources/webhooks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Atlas
+  module Resources
+    # +/v1/webhook_endpoints+ — outbound webhook endpoints and their delivery log.
+    class Webhooks < Base
+      # +webhooks.endpoints+ — CRUD over endpoints.
+      def endpoints
+        @endpoints ||= Endpoints.new(@transport)
+      end
+
+      # Delivery log for an endpoint.
+      def deliveries(id)
+        request(method: :get, path: "/v1/webhook_endpoints/#{enc(id)}/deliveries")
+      end
+
+      class Endpoints < Base
+        def list
+          request(method: :get, path: "/v1/webhook_endpoints")
+        end
+
+        # Create reveals the signing secret (+whsec_...+) exactly once.
+        def create(body, idempotency_key: nil)
+          request(method: :post, path: "/v1/webhook_endpoints", body: body, idempotency_key: idempotency_key)
+        end
+
+        def delete(id)
+          request(method: :delete, path: "/v1/webhook_endpoints/#{enc(id)}")
+        end
+      end
+    end
+  end
+end

data/lib/atlas/transport.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "error"
+
+module Atlas
+  # The default BAPI origin, overridable per instance via +api_url+.
+  DEFAULT_API_URL = "https://api.atlasauth.net"
+
+  # The shared HTTP core every resource namespace calls.
+  #
+  # One place decides how a BAPI request is authenticated, serialized, and how a
+  # failure becomes an {Atlas::APIError} — so a namespace method is a one-liner
+  # naming a method, a path, and its shapes.
+  #
+  # The HTTP mechanism is injectable: pass +http:+ any object responding to
+  # +call(method, url, headers, body)+ and returning +[status_integer,
+  # body_string]+. Tests use this to run with no network; the default is a
+  # {Atlas::NetHTTPRequester} built on Ruby's stdlib +Net::HTTP+.
+  class Transport
+    # Sentinel meaning "no body key was supplied", distinct from an explicit
+    # empty hash (which is serialized to +{}+ with a content-type, matching the
+    # TypeScript SDK's +body !== undefined+ gate).
+    OMIT = :__atlas_omit__
+
+    def initialize(secret_key:, api_url: DEFAULT_API_URL, http: nil,
+                   open_timeout: 30, read_timeout: 30)
+      raise ConfigurationError, "Atlas::Client requires a secret_key." if secret_key.nil? || secret_key.empty?
+
+      @secret_key = secret_key
+      @base = api_url || DEFAULT_API_URL
+      @http = http || NetHTTPRequester.new(open_timeout: open_timeout, read_timeout: read_timeout)
+    end
+
+    # Perform a request and return the parsed JSON (a Hash/Array), the raw text
+    # when +raw:+ is true, or +nil+ for an empty/204 body.
+    #
+    # @raise [Atlas::APIError] on any non-2xx response.
+    def request(method:, path:, query: nil, body: OMIT, idempotency_key: nil, raw: false)
+      url = join_url(@base, path) + serialize_query(query)
+
+      headers = {
+        "authorization" => "Bearer #{@secret_key}",
+        "accept" => "application/json"
+      }
+
+      payload = nil
+      unless body.equal?(OMIT)
+        headers["content-type"] = "application/json"
+        payload = JSON.generate(body)
+      end
+      headers["idempotency-key"] = idempotency_key if idempotency_key
+
+      status, text = @http.call(method.to_s.upcase, url, headers, payload)
+
+      raise to_api_error(status, text) unless status.between?(200, 299)
+
+      return nil if status == 204 || text.nil? || text.empty?
+      return text if raw
+
+      JSON.parse(text)
+    end
+
+    private
+
+    def join_url(base, path)
+      "#{base.sub(%r{/+\z}, '')}#{path.start_with?('/') ? path : "/#{path}"}"
+    end
+
+    # Serialize a query hash to a string, dropping nil, spreading arrays,
+    # rendering booleans as "true"/"false" — mirroring the TS/Python transports.
+    def serialize_query(query)
+      return "" if query.nil? || query.empty?
+
+      parts = []
+      query.each do |key, value|
+        next if value.nil?
+
+        values = value.is_a?(Array) ? value : [value]
+        values.each do |v|
+          next if v.nil?
+
+          rendered = v == true ? "true" : v == false ? "false" : v.to_s
+          parts << "#{encode(key.to_s)}=#{encode(rendered)}"
+        end
+      end
+      parts.empty? ? "" : "?#{parts.join('&')}"
+    end
+
+    def encode(str)
+      URI.encode_www_form_component(str)
+    end
+
+    # Parse a non-2xx body into the §9.1 envelope, or synthesize one, and pick
+    # the most specific typed error class for the status.
+    def to_api_error(status, text)
+      errors = []
+      message = nil
+      if text && !text.empty?
+        begin
+          parsed = JSON.parse(text)
+          envelope = parsed.is_a?(Hash) ? parsed["errors"] : nil
+          if envelope.is_a?(Array) && !envelope.empty?
+            errors = envelope
+          else
+            message = text[0, 500]
+          end
+        rescue JSON::ParserError
+          message = text[0, 500]
+        end
+      end
+      if errors.empty?
+        errors = [{ "code" => "UNKNOWN",
+                    "message" => message || "Atlas API request failed with status #{status}" }]
+      end
+      ErrorFactory.build(status, errors)
+    end
+  end
+
+  # The default requester: percent-encodes nothing extra, follows no redirects,
+  # and speaks plain +Net::HTTP+. Kept tiny and dependency-free so the gem runs
+  # anywhere stdlib does.
+  class NetHTTPRequester
+    METHODS = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PATCH" => Net::HTTP::Patch,
+      "PUT" => Net::HTTP::Put,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    def initialize(open_timeout: 30, read_timeout: 30)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # @return [Array(Integer, String)] the HTTP status and the raw body text.
+    def call(method, url, headers, body)
+      uri = URI.parse(url)
+      klass = METHODS.fetch(method) { raise ArgumentError, "Unsupported HTTP method: #{method}" }
+
+      request = klass.new(uri.request_uri)
+      headers.each { |k, v| request[k] = v }
+      request.body = body if body
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      response = http.request(request)
+      [response.code.to_i, response.body.to_s]
+    end
+  end
+end

data/lib/atlas/verifier.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "authorization"
+require_relative "jwks_cache"
+
+module Atlas
+  # §7.3: five seconds either side, matching the server's minting tolerance.
+  CLOCK_SKEW_SECONDS = 5
+
+  # The outcome of a verification. A success carries the claims and the bound
+  # +has?+ / +protect+ helpers; a failure carries a coarse +reason+.
+  class VerifyResult
+    # @return [Boolean]
+    attr_reader :ok
+    # @return [Hash, nil] the verified claims (string-keyed), on success.
+    attr_reader :claims
+    # @return [Symbol, nil] :malformed, :invalid, :no_keys, :unauthorized_party.
+    attr_reader :reason
+
+    def self.success(claims)
+      new(ok: true, claims: claims)
+    end
+
+    def self.failure(reason)
+      new(ok: false, reason: reason)
+    end
+
+    def initialize(ok:, claims: nil, reason: nil)
+      @ok = ok
+      @claims = claims
+      @reason = reason
+    end
+
+    def ok?
+      @ok
+    end
+
+    # True when the claims satisfy the condition (empty condition = "signed in").
+    # Always false on a failed verification.
+    def has?(condition = {})
+      @ok && Authorization.has_from_claims?(@claims, condition)
+    end
+
+    # Assert the condition; returns the claims on success, raises
+    # {Atlas::ForbiddenError} otherwise.
+    def protect(condition = {})
+      raise ForbiddenError.new(:unauthenticated, condition) unless @ok
+
+      outcome = Authorization.evaluate(@claims, condition)
+      raise ForbiddenError.new(outcome[:reason], condition) unless outcome[:allowed]
+
+      @claims
+    end
+  end
+
+  # §7.3 verification by customer backends.
+  #
+  # Verifies signature, exp/nbf with 5s clock-skew tolerance, iss, and optionally
+  # azp against an allowlist. The default path is LOCAL, against cached JWKS —
+  # it never calls Atlas on the hot path, so Atlas's availability never becomes
+  # the customer's. +verify_online+ is the documented slow path.
+  class Backend
+    # @param jwks_url [String] the instance's JWKS URL.
+    # @param issuer [String] expected +iss+. Required.
+    # @param authorized_parties [Array<String>, nil] optional +azp+ allowlist.
+    # @param secret_key [String, nil] required only for +verify_online+.
+    # @param bapi_base_url [String, nil] required only for +verify_online+.
+    # @param http [#call, nil] injectable requester for +verify_online+.
+    # @param fetch_impl [#call, nil] injectable JWKS fetcher (tests).
+    # @param now [#call, nil] clock returning epoch milliseconds (tests).
+    def initialize(jwks_url:, issuer:, authorized_parties: nil, secret_key: nil,
+                   bapi_base_url: nil, http: nil, fetch_impl: nil, now: nil)
+      require_jwt!
+      @issuer = issuer
+      @authorized_parties = authorized_parties
+      @secret_key = secret_key
+      @bapi_base_url = bapi_base_url
+      @http = http
+      @jwks = JwksCache.new(url: jwks_url, fetch_impl: fetch_impl, now: now)
+    end
+
+    # Verify locally. No network call unless the +kid+ is unknown, and at most
+    # one of those a minute.
+    # @return [VerifyResult]
+    def verify(token)
+      return VerifyResult.failure(:malformed) if token.nil? || token.split(".").length != 3
+
+      keys = @jwks.get(Atlas.read_kid(token))
+      return VerifyResult.failure(:no_keys) if keys.nil? || keys["keys"].nil? || keys["keys"].empty?
+
+      begin
+        jwk_set = JWT::JWK::Set.new(keys)
+        payload, = JWT.decode(
+          token, nil, true,
+          algorithms: ["RS256"],
+          iss: @issuer,
+          verify_iss: true,
+          jwks: jwk_set,
+          # exp/nbf tolerance, matching the server's minting skew.
+          leeway: CLOCK_SKEW_SECONDS
+        )
+        claims = payload
+      rescue JWT::DecodeError, StandardError
+        # One reason for every failure — telling a caller which check failed
+        # helps a forger more than a developer.
+        return VerifyResult.failure(:invalid)
+      end
+
+      # §13.1 token-confusion guard: reject an OP access/id token replayed as a
+      # session. An absent token_use/aud is a valid (legacy) session.
+      token_use = claims["token_use"]
+      return VerifyResult.failure(:invalid) if (!token_use.nil? && token_use != "session") || !claims["aud"].nil?
+
+      if @authorized_parties && !@authorized_parties.empty?
+        azp = claims["azp"]
+        return VerifyResult.failure(:unauthorized_party) if azp.nil? || !@authorized_parties.include?(azp)
+      end
+
+      VerifyResult.success(claims)
+    end
+
+    # §7.3 the documented slow path: ask Atlas whether the session is still live.
+    # Costs a round trip on every call. Fails CLOSED on an outage.
+    # @return [VerifyResult]
+    def verify_online(token)
+      local = verify(token)
+      return local unless local.ok?
+
+      if @secret_key.nil? || @bapi_base_url.nil?
+        raise ConfigurationError,
+              "verify_online needs secret_key and bapi_base_url. Without them it " \
+              "would silently fall back to local verification."
+      end
+
+      begin
+        status, text = post_verify(token)
+        return VerifyResult.failure(:invalid) unless status.between?(200, 299)
+
+        body = JSON.parse(text)
+        body["verified"] ? local : VerifyResult.failure(:invalid)
+      rescue StandardError
+        # The caller reached for verify_online precisely because a stale answer
+        # was unacceptable, so an outage returns a failure, never the local pass.
+        VerifyResult.failure(:invalid)
+      end
+    end
+
+    # Verify whatever a request carries. Accepts a Hash of headers (string keys)
+    # or any object responding to +get(name)+. The Authorization header wins over
+    # a +__session+ cookie.
+    # @return [VerifyResult]
+    def authenticate_request(headers)
+      header = read_header(headers, "authorization")
+      cookie = read_header(headers, "cookie")
+
+      bearer = header&.start_with?("Bearer ") ? header[7..] : nil
+      from_cookie = cookie ? read_cookie(cookie, "__session") : nil
+
+      token = bearer || from_cookie
+      return VerifyResult.failure(:malformed) if token.nil?
+
+      verify(token)
+    end
+
+    private
+
+    def require_jwt!
+      require "jwt"
+    rescue LoadError
+      raise Atlas::Error,
+            "Token verification needs the `jwt` gem. Add `gem \"jwt\"` to your Gemfile."
+    end
+
+    def post_verify(token)
+      url = "#{@bapi_base_url.sub(%r{/+\z}, '')}/v1/tokens/verify"
+      headers = {
+        "authorization" => "Bearer #{@secret_key}",
+        "content-type" => "application/json"
+      }
+      payload = JSON.generate({ token: token })
+      if @http
+        @http.call("POST", url, headers, payload)
+      else
+        NetHTTPRequester.new.call("POST", url, headers, payload)
+      end
+    end
+
+    def read_header(headers, name)
+      if headers.respond_to?(:get)
+        headers.get(name)
+      elsif headers.respond_to?(:[])
+        headers[name] || headers[name.downcase] || headers[name.to_sym]
+      end
+    end
+
+    def read_cookie(header, name)
+      header.split(";").each do |part|
+        key, *rest = part.strip.split("=")
+        return rest.join("=") if key == name
+      end
+      nil
+    end
+  end
+
+  # §8.2 standalone helpers for code that already holds a claims hash.
+  module_function
+
+  def has_permission?(claims, permission)
+    Authorization.has_from_claims?(claims, permission: permission)
+  end
+
+  def has_role?(claims, role)
+    Authorization.has_from_claims?(claims, role: role)
+  end
+
+  def has?(claims, condition = {})
+    Authorization.has_from_claims?(claims, condition)
+  end
+
+  def protect(claims, condition = {})
+    outcome = Authorization.evaluate(claims, condition)
+    raise ForbiddenError.new(outcome[:reason], condition) unless outcome[:allowed]
+
+    claims
+  end
+end

data/lib/atlas/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Atlas
+  # The gem version. Tracks the TypeScript/Python backend SDK line.
+  VERSION = "0.1.0"
+end

data/lib/atlas.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# atlas-auth — the official Ruby backend SDK for Atlas.
+#
+# A typed client over the +sk_+ Backend API (BAPI), the Ruby peer of the
+# TypeScript +@atlasauth/backend+ and Python +atlas-backend+ SDKs, plus §7.3 local
+# session-token verification.
+#
+#   require "atlas"
+#
+#   atlas = Atlas::Client.new("sk_live_...")
+#   user  = atlas.users.create(email_address: "ada@example.com")
+#   Atlas.paginate(atlas.organizations).each { |org| puts org["name"] }
+#
+#   backend = Atlas::Backend.new(
+#     jwks_url: "https://api.atlasauth.net/v1/jwks",
+#     issuer:   "https://your-instance.atlasauth.net",
+#   )
+#   result = backend.verify(session_jwt)
+#   result.protect(permission: "org:billing:manage") if result.ok?
+module Atlas
+end
+
+require_relative "atlas/version"
+require_relative "atlas/error"
+require_relative "atlas/transport"
+require_relative "atlas/pagination"
+require_relative "atlas/authorization"
+require_relative "atlas/jwks_cache"
+require_relative "atlas/verifier"
+require_relative "atlas/handshake"
+require_relative "atlas/client"
+
+module Atlas
+  # Convenience constructor mirroring the TS +createAtlasClient+ factory.
+  #
+  #   atlas = Atlas.client("sk_live_...")
+  def self.client(secret_key, **options)
+    Client.new(secret_key, **options)
+  end
+end