atlas-auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80f3e5a3fa6f404e3416096b1315e90babd798263583e3f61a47a33c59bf21b6
+  data.tar.gz: 9f243710f91725c971972e8216e54348dd23009bb60ec0189929b168d7f0775c
+SHA512:
+  metadata.gz: 00ed1612a4c79bc241ec64c2d1a9d49cd637292c1da84baaf8efbb480ed1afcf344f1ad556aca5825a0ddb629da8f6ad095f1dc6fa90f1303e710ad79c23f4c7
+  data.tar.gz: 4e11a62f2eb27a06a15f8512d4d0a9bc85083fc7cdbf058754113b1112affb1be4dc37345c494625cb514ab57a48cd9bd01782b1178e77c13a973ad87c96e3af

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Atlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# Atlas Ruby SDK
+
+The official **Ruby backend SDK** for [Atlas](https://atlasauth.net) — a typed client over the `sk_` Backend API (BAPI), plus local session-token verification. It is the Ruby peer of the TypeScript `@atlasauth/backend` and Python `atlas-backend` SDKs and covers the full management surface (all 45 resource namespaces).
+
+> This is a **server-side** SDK. It uses your instance **secret key** (`sk_...`) and must never ship to a browser or mobile app. For client-side sign-in flows use the JS, Swift, Kotlin, or Flutter SDKs.
+
+## Install
+
+```ruby
+# Gemfile
+gem "atlas-auth"
+```
+
+```sh
+bundle install
+# or
+gem install atlas-auth
+```
+
+Requires Ruby 3.0+. The only runtime dependency is [`jwt`](https://rubygems.org/gems/jwt) (for session-token verification); everything else is standard library.
+
+## Quickstart
+
+```ruby
+require "atlas"
+
+atlas = Atlas::Client.new(ENV.fetch("ATLAS_SECRET_KEY")) # "sk_live_..."
+
+# Create a user
+user = atlas.users.create(email_address: "ada@example.com", password: "•••••••")
+
+# Read one, list many
+atlas.users.get(user["id"])
+page = atlas.users.list(limit: 20)
+
+# Walk every page of a cursor-paginated list
+Atlas.paginate(atlas.organizations).each { |org| puts org["name"] }
+all_users = Atlas.collect(atlas.users, status: "active")
+```
+
+### Configuration
+
+```ruby
+Atlas::Client.new(
+  "sk_live_...",
+  api_url: "https://api.atlasauth.net", # default: https://api.atlasauth.net
+  open_timeout: 30,
+  read_timeout: 30,
+)
+```
+
+Every request is authenticated with `Authorization: Bearer <secret_key>`; the key is never logged or placed in a URL.
+
+### Idempotency
+
+Write operations accept an `idempotency_key:` so a retried request is applied at most once:
+
+```ruby
+atlas.users.create({ email_address: "ada@example.com" }, idempotency_key: "signup-42")
+```
+
+## Errors
+
+Any non-2xx response raises a typed `Atlas::APIError` carrying the HTTP status and the full `{ errors: [...] }` envelope. Status codes map to subclasses so you can rescue precisely:
+
+```ruby
+begin
+  atlas.users.get("user_missing")
+rescue Atlas::NotFoundError => e
+  e.status      # => 404
+  e.code        # => "NOT_FOUND"   (first error's stable code)
+  e.errors      # => [{ "code" => "NOT_FOUND", "message" => "..." }]
+rescue Atlas::APIError => e
+  # BadRequestError, AuthenticationError, PermissionError, ConflictError,
+  # RateLimitError, ServerError, ... all inherit from APIError.
+end
+```
+
+## Session-token verification
+
+Verify Atlas session JWTs **locally** — no round trip per request. The JWKS is cached in-process with kid-miss refetch throttled to once per minute (§7.3).
+
+```ruby
+backend = Atlas::Backend.new(
+  jwks_url: "https://api.atlasauth.net/v1/jwks",
+  issuer:   "https://your-instance.atlasauth.net",
+  authorized_parties: ["https://app.example.com"], # optional azp allowlist
+)
+
+result = backend.verify(session_jwt)
+if result.ok?
+  result.claims["sub"]                          # the user id
+  result.protect(permission: "org:billing:manage")
+else
+  result.reason                                 # :invalid, :malformed, :no_keys, :unauthorized_party
+end
+
+# From a request's headers (Authorization: Bearer <jwt> or the __session cookie):
+backend.authenticate_request(request.headers)
+```
+
+`verify` is the fast local path. `verify_online` asks Atlas whether the session is still live (a round trip; fails closed on an outage).
+
+### Rails
+
+Wire a shared client in an initializer:
+
+```ruby
+# config/initializers/atlas.rb
+ATLAS = Atlas::Client.new(Rails.application.credentials.atlas_secret_key)
+BACKEND = Atlas::Backend.new(
+  jwks_url: "https://api.atlasauth.net/v1/jwks",
+  issuer:   "https://your-instance.atlasauth.net",
+)
+```
+
+Then verify in a `before_action` and branch on `BACKEND.authenticate_request(request.headers)`.
+
+## Resources
+
+All 45 namespaces are available on the client: `users`, `sessions`, `organizations`, `roles`, `permissions`, `oauth_clients`, `resource_servers`, `sso_connections`, `scim_tokens`, `scim_provisioning`, `domains`, `waitlist`, `allowlist`, `blocklist`, `attack_protection`, `actor_tokens`, `invitations`, `webhooks`, `sign_in_tokens`, `audit_logs`, `jwt_templates`, `api_keys`, `oauth_providers`, `sso_onboarding`, `fga`, `rate_limit_policy`, `risk_based_mfa`, `bot_signals`, `network_acls`, `managed_waf`, `log_streams`, `branding`, `email_templates`, `sms_templates`, `localizations`, `actions`, `billing`, `messaging`, `import_export`, `data_subject_requests`, `radius_clients`, `lti_platforms`, `instance`, `instance_security`, `tokens`.
+
+## Development
+
+```sh
+bundle install
+rake test        # or: ruby -Ilib -Itest test/client_test.rb
+```
+
+## License
+
+MIT

data/lib/atlas/authorization.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Atlas
+  # Raised by +protect+ when a claims set fails an authorization condition. An
+  # app maps this to a 401/403. Mirrors +@atlas/authz+'s +ForbiddenError+.
+  class ForbiddenError < Error
+    # @return [Symbol] why the check failed (:unauthenticated, :permission, :role, ...).
+    attr_reader :reason
+    # @return [Hash] the condition that was evaluated.
+    attr_reader :condition
+
+    def initialize(reason, condition = {})
+      @reason = reason
+      @condition = condition
+      super("Forbidden: #{reason}")
+    end
+  end
+
+  # The shared authorization primitive — the Ruby peer of +@atlas/authz+.
+  #
+  # A condition is a hash; an empty condition means "signed in". Supported keys
+  # (string or symbol):
+  #   * +:permission+       — the claims must grant this org permission.
+  #   * +:role+             — the claims' org role must equal this.
+  #   * +:any_permission+   — at least one of these permissions is granted.
+  #   * +:all_permissions+  — every one of these permissions is granted.
+  module Authorization
+    module_function
+
+    # True when the claims satisfy the condition.
+    def has_from_claims?(claims, condition = {})
+      evaluate(claims, condition)[:allowed]
+    end
+
+    # Evaluate a condition, returning +{ allowed:, reason: }+.
+    def evaluate(claims, condition = {})
+      condition ||= {}
+      permission = fetch(condition, :permission)
+      role = fetch(condition, :role)
+      any_permission = fetch(condition, :any_permission)
+      all_permissions = fetch(condition, :all_permissions)
+
+      # Empty condition: signed in is enough.
+      if permission.nil? && role.nil? && any_permission.nil? && all_permissions.nil?
+        return { allowed: true, reason: nil }
+      end
+
+      granted = Array(fetch(claims, :org_permissions))
+      org_role = fetch(claims, :org_role)
+
+      return deny(:permission) if permission && !granted.include?(permission)
+      return deny(:role) if role && org_role != role
+      if any_permission && (Array(any_permission) & granted).empty?
+        return deny(:permission)
+      end
+      if all_permissions && !(Array(all_permissions) - granted).empty?
+        return deny(:permission)
+      end
+
+      { allowed: true, reason: nil }
+    end
+
+    def deny(reason)
+      { allowed: false, reason: reason }
+    end
+
+    # Look a key up under both its symbol and string form.
+    def fetch(hash, key)
+      return nil unless hash
+
+      if hash.key?(key)
+        hash[key]
+      elsif hash.key?(key.to_s)
+        hash[key.to_s]
+      end
+    end
+  end
+end

data/lib/atlas/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+
+require_relative "resources/users"
+require_relative "resources/sessions"
+require_relative "resources/organizations"
+require_relative "resources/roles"
+require_relative "resources/oauth_clients"
+require_relative "resources/resource_servers"
+require_relative "resources/sso_connections"
+require_relative "resources/scim_tokens"
+require_relative "resources/domains"
+require_relative "resources/waitlist"
+require_relative "resources/restrictions"
+require_relative "resources/attack_protection"
+require_relative "resources/actor_tokens"
+require_relative "resources/invitations"
+require_relative "resources/webhooks"
+require_relative "resources/sign_in_tokens"
+require_relative "resources/audit_logs"
+require_relative "resources/jwt_templates"
+require_relative "resources/api_keys"
+require_relative "resources/oauth_providers"
+require_relative "resources/sso_onboarding"
+require_relative "resources/scim_provisioning"
+require_relative "resources/fga"
+require_relative "resources/rate_limit"
+require_relative "resources/risk_based_mfa"
+require_relative "resources/bot_signals"
+require_relative "resources/network_acls"
+require_relative "resources/managed_waf"
+require_relative "resources/log_streams"
+require_relative "resources/branding"
+require_relative "resources/email_templates"
+require_relative "resources/sms_templates"
+require_relative "resources/localizations"
+require_relative "resources/actions"
+require_relative "resources/billing"
+require_relative "resources/messaging"
+require_relative "resources/import_export"
+require_relative "resources/data_subject_requests"
+require_relative "resources/radius_clients"
+require_relative "resources/lti_platforms"
+require_relative "resources/instance"
+require_relative "resources/instance_security"
+require_relative "resources/tokens"
+
+module Atlas
+  # The typed management client for the Atlas Backend API — the secret-key
+  # surface, the Ruby peer of TypeScript's +createAtlasClient+.
+  #
+  # Each namespace is one memoized accessor handing the shared, config-bound
+  # transport to a resource class, so this file reads as a table of contents for
+  # the whole surface.
+  #
+  #   atlas = Atlas::Client.new("sk_live_...")
+  #   user  = atlas.users.create(email_address: "ada@example.com")
+  #   Atlas.paginate(atlas.organizations).each { |org| puts org["name"] }
+  class Client
+    # @param secret_key [String] the instance secret key (+sk_...+). Sent as
+    #   +Authorization: Bearer <key>+ on every request; never logged, never in a URL.
+    # @param api_url [String] base URL of the instance's Backend API.
+    # @param http [#call, nil] injectable requester (tests, custom transport).
+    # @param open_timeout [Numeric] connect timeout, seconds.
+    # @param read_timeout [Numeric] read timeout, seconds.
+    def initialize(secret_key, api_url: DEFAULT_API_URL, http: nil,
+                   open_timeout: 30, read_timeout: 30)
+      @transport = Transport.new(
+        secret_key: secret_key, api_url: api_url, http: http,
+        open_timeout: open_timeout, read_timeout: read_timeout
+      )
+    end
+
+    # @return [Atlas::Transport] the underlying config-bound transport.
+    attr_reader :transport
+
+    def users            = @users ||= Resources::Users.new(@transport)
+    def sessions         = @sessions ||= Resources::Sessions.new(@transport)
+    def organizations    = @organizations ||= Resources::Organizations.new(@transport)
+    def roles            = @roles ||= Resources::Roles.new(@transport)
+    def permissions      = @permissions ||= Resources::Permissions.new(@transport)
+    def oauth_clients     = @oauth_clients ||= Resources::OAuthClients.new(@transport)
+    def resource_servers  = @resource_servers ||= Resources::ResourceServers.new(@transport)
+    def sso_connections   = @sso_connections ||= Resources::SsoConnections.new(@transport)
+    def scim_tokens       = @scim_tokens ||= Resources::ScimTokens.new(@transport)
+    def domains           = @domains ||= Resources::Domains.new(@transport)
+    def waitlist          = @waitlist ||= Resources::Waitlist.new(@transport)
+    def allowlist         = @allowlist ||= Resources::Restriction.new(@transport, "/v1/allowlist_identifiers")
+    def blocklist         = @blocklist ||= Resources::Restriction.new(@transport, "/v1/blocklist_identifiers")
+    def attack_protection = @attack_protection ||= Resources::AttackProtection.new(@transport)
+    def actor_tokens      = @actor_tokens ||= Resources::ActorTokens.new(@transport)
+    def invitations       = @invitations ||= Resources::Invitations.new(@transport)
+    def webhooks          = @webhooks ||= Resources::Webhooks.new(@transport)
+    def sign_in_tokens    = @sign_in_tokens ||= Resources::SignInTokens.new(@transport)
+    def audit_logs        = @audit_logs ||= Resources::AuditLogs.new(@transport)
+    def jwt_templates     = @jwt_templates ||= Resources::JwtTemplates.new(@transport)
+    def api_keys          = @api_keys ||= Resources::ApiKeys.new(@transport)
+    def oauth_providers   = @oauth_providers ||= Resources::OAuthProviders.new(@transport)
+    def sso_onboarding    = @sso_onboarding ||= Resources::SsoOnboarding.new(@transport)
+    def scim_provisioning = @scim_provisioning ||= Resources::ScimProvisioning.new(@transport)
+    def fga               = @fga ||= Resources::Fga.new(@transport)
+    def rate_limit_policy = @rate_limit_policy ||= Resources::RateLimitPolicy.new(@transport)
+    def risk_based_mfa    = @risk_based_mfa ||= Resources::RiskBasedMfa.new(@transport)
+    def bot_signals       = @bot_signals ||= Resources::BotSignals.new(@transport)
+    def network_acls      = @network_acls ||= Resources::NetworkAcls.new(@transport)
+    def managed_waf       = @managed_waf ||= Resources::ManagedWaf.new(@transport)
+    def log_streams       = @log_streams ||= Resources::LogStreams.new(@transport)
+    def branding          = @branding ||= Resources::Branding.new(@transport)
+    def email_templates   = @email_templates ||= Resources::EmailTemplates.new(@transport)
+    def sms_templates     = @sms_templates ||= Resources::SmsTemplates.new(@transport)
+    def localizations     = @localizations ||= Resources::Localizations.new(@transport)
+    def actions           = @actions ||= Resources::Actions.new(@transport)
+    def billing           = @billing ||= Resources::Billing.new(@transport)
+    def messaging         = @messaging ||= Resources::Messaging.new(@transport)
+    def import_export     = @import_export ||= Resources::ImportExport.new(@transport)
+    def data_subject_requests = @data_subject_requests ||= Resources::DataSubjectRequests.new(@transport)
+    def radius_clients    = @radius_clients ||= Resources::RadiusClients.new(@transport)
+    def lti_platforms     = @lti_platforms ||= Resources::LtiPlatforms.new(@transport)
+    def instance          = @instance ||= Resources::Instance.new(@transport)
+    def instance_security = @instance_security ||= Resources::InstanceSecurity.new(@transport)
+    def tokens            = @tokens ||= Resources::Tokens.new(@transport)
+  end
+end

data/lib/atlas/error.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Atlas
+  # Base class for every error the SDK raises. Rescue +Atlas::Error+ to catch
+  # anything the gem can throw.
+  class Error < StandardError; end
+
+  # Raised before a request goes out when the client is misconfigured
+  # (e.g. a missing secret key).
+  class ConfigurationError < Error; end
+
+  # Raised on any non-2xx response from the Backend API.
+  #
+  # Atlas answers a failed BAPI call with the §9.1 envelope:
+  #
+  #   { "errors": [ { "code", "message", "param?", "meta?" } ] }
+  #
+  # +code+ is the stable, machine-readable part of that contract — integrators
+  # branch on it (+LAST_ADMIN+, +NOT_FOUND+, +SCOPE_MISSING+, ...) — so it is
+  # surfaced first-class here rather than buried in a parsed body. The raw
+  # +errors+ array and the HTTP +status+ are both kept so a caller can inspect
+  # +param+/+meta+ (e.g. a rate limit's +retry_after+) when they need to.
+  class APIError < Error
+    # @return [Integer] HTTP status of the failed response.
+    attr_reader :status
+
+    # @return [Array<Hash>] the full §9.1 error envelope, in order. Each item
+    #   carries string keys "code", "message", and optionally "param"/"meta".
+    attr_reader :errors
+
+    def initialize(status, errors, message = nil)
+      @status = status
+      @errors = errors || []
+      first = @errors.first
+      super(message || (first && (first["message"] || first[:message])) ||
+        "Atlas API request failed with status #{status}")
+    end
+
+    # The first error's stable code — the field callers branch on most.
+    # @return [String, nil]
+    def code
+      first = @errors.first
+      first && (first["code"] || first[:code])
+    end
+
+    # True when any error in the envelope carries the given stable code.
+    def has_code?(code)
+      @errors.any? { |e| (e["code"] || e[:code]) == code }
+    end
+
+    # A short human summary for logs. Never includes the secret key.
+    def to_s
+      "#{self.class.name}: status=#{@status} code=#{code.inspect} #{super}"
+    end
+  end
+
+  # 400 — the request was malformed or a parameter was invalid.
+  class BadRequestError < APIError; end
+  # 401 — the secret key is missing, wrong, or revoked.
+  class AuthenticationError < APIError; end
+  # 403 — authenticated but not permitted (e.g. scope missing).
+  class PermissionError < APIError; end
+  # 404 — the resource does not exist for this instance.
+  class NotFoundError < APIError; end
+  # 409 — a conflict/terminal-state error (e.g. re-actioning a DSAR).
+  class ConflictError < APIError; end
+  # 422 — the request was well-formed but semantically rejected.
+  class UnprocessableEntityError < APIError; end
+  # 429 — rate limited. Inspect +errors.first["meta"]["retry_after"]+.
+  class RateLimitError < APIError; end
+  # 5xx — an Atlas-side failure.
+  class ServerError < APIError; end
+
+  module ErrorFactory
+    # Map an HTTP status onto the most specific error class.
+    STATUS_MAP = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError
+    }.freeze
+
+    # Build the right typed error from a status + parsed error items.
+    def self.build(status, errors)
+      klass = STATUS_MAP[status] || (status >= 500 ? ServerError : APIError)
+      klass.new(status, errors)
+    end
+  end
+end