omniauth-carta 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1102ede87797f5363ec6d747c970aa3f10d7f5d05df1677cc0e16119ee404408
+  data.tar.gz: 935505ac178ca89e9076886c496465169f029439028d2b78e958e2585d3a8b35
+SHA512:
+  metadata.gz: da2ffe66956d0da878acd243a31bc76462e01acaf2a16a02b7ea8f0c073fdfc2237d17c1f3107824687a69b14ef8b7df29f95cbbca5976ce453a0d310d4a956f
+  data.tar.gz: 9835272275b508ba9f460e0f1dc43c97d5840868ad9bc91355fc568113246d07ac3e03072539d94430d5095b3f2ae6e9c684b501d936f75cec7584e97354f45c

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-09-09
+
+- Add the Carta OmniAuth OAuth2 strategy with HTTP Basic token exchange.
+- Fetch UserInfo for stable subject IDs and optional profile/email fields.
+- Enable S256 PKCE and preserve OmniAuth state and request CSRF protection.
+- Support custom endpoints, scopes, and callback URLs.
+- Add Minitest fixtures, middleware integration tests, and Ruby CI.
+- Preserve Carta-returned scopes in the auth hash credentials.
+- Preserve refresh tokens even when the token response omits expiry information.
+- Verify playground endpoint overrides with API scopes and document the working Rails configuration.
+- Document scope reauthorization, resource permissions, and the application-owned API/refresh boundary.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Flombaum
+
+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,196 @@
+# OmniAuth Carta
+
+An [OmniAuth OAuth2](https://github.com/omniauth/omniauth-oauth2) strategy for authenticating Carta users in Ruby and Rails applications. Requires Ruby 3.2+ and OmniAuth 2 (provided by the OAuth2 dependency).
+
+The strategy exchanges authorization codes, fetches Carta's UserInfo, and returns the standard OmniAuth auth hash. It enables S256 PKCE and state verification by default.
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "omniauth-carta", "~> 0.1.0"
+```
+
+Run `bundle install`. Source code and issues are hosted on [GitHub](https://github.com/aviflombaum/omniauth-carta).
+
+## Register with Carta
+
+Register an authorization-code application in the [Carta Developer Portal](https://developers.app.carta.com/). Enable `openid`, `profile`, and `email` for the default configuration. Register your exact callback URL, such as `https://your-app.example/auth/carta/callback`, and obtain the client ID and secret. Keep secrets in your application's credentials or environment.
+
+See Carta's [authorization guide](https://docs.carta.com/api-platform/guides/guides/authorization/using-the-authorization-code-flow/) and [OIDC guide](https://docs.carta.com/api-platform/guides/references/oidc/).
+
+## Rails
+
+Add Rails' OmniAuth request CSRF integration:
+
+```ruby
+# Gemfile
+gem "omniauth-rails_csrf_protection", "~> 1.0"
+```
+
+Configure the middleware:
+
+```ruby
+# config/initializers/omniauth.rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :carta, Rails.application.credentials.dig(:carta, :client_id),
+    Rails.application.credentials.dig(:carta, :client_secret)
+end
+```
+
+Start authentication with a POST form. Keep Turbo from treating the external redirect as a fetch:
+
+```erb
+<%= button_to "Connect Carta", "/auth/carta", method: :post, data: { turbo: false } %>
+```
+
+Route the callback and failure endpoint to your application:
+
+```ruby
+# config/routes.rb
+get "/auth/carta/callback", to: "carta_sessions#create"
+get "/auth/failure", to: "carta_sessions#failure"
+```
+
+In `CartaSessionsController#create`, read `request.env.fetch("omniauth.auth")`. Find or create your application account using the provider and UID together; perform account linking according to your application's policy. Store the application's user ID in the session and any Carta tokens in encrypted server-side storage. The failure action should display a generic retry message, without rendering raw provider error details. API-only Rails apps also need cookie/session middleware for OmniAuth.
+
+## Plain Ruby / Rack
+
+Require `omniauth-carta`, install session middleware before `OmniAuth::Builder`, and register `provider :carta, client_id, client_secret`. Render a POST form with a token from `Rack::Protection::AuthenticityToken.token(env["rack.session"])`. OmniAuth's default request validation checks that token; leave it enabled.
+
+The runnable [Rack example](examples/rack/config.ru) demonstrates the complete form, callback, session, and failure flow:
+
+```sh
+cd examples/rack
+bundle install
+export CARTA_CLIENT_ID=your-client-id
+export CARTA_CLIENT_SECRET=your-client-secret
+export SESSION_SECRET=$(ruby -rsecurerandom -e 'puts SecureRandom.hex(64)')
+bundle exec rackup -p 9292
+```
+
+Register `http://localhost:9292/auth/carta/callback` with your Carta development application and open `http://localhost:9292`. The example displays the UID but does not persist accounts or tokens. Use HTTPS and secure cookies in production.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `scope` | `"openid profile email"` | Space-delimited requested scopes |
+| `pkce` | `true` | S256 proof key for code exchange |
+| `userinfo_url` | `"/o/userinfo/"` | Relative to client site, or an absolute URL |
+| `callback_url` | Generated from host and callback path | Explicit registered redirect URI |
+| `client_options[:site]` | `"https://login.app.carta.com"` | OAuth host |
+| `client_options[:authorize_url]` | `"/o/authorize/"` | Authorization endpoint |
+| `client_options[:token_url]` | `"/o/access_token/"` | Token endpoint |
+| `client_options[:auth_scheme]` | `:basic_auth` | Client authentication method |
+
+Standard OmniAuth options such as `name`, `path_prefix`, `callback_path`, `authorize_params`, and `setup` also apply. Generated callback URLs omit request query parameters so the token exchange uses the same redirect URI. Use an explicit `callback_url` if the registered URI includes a query string. Configure your application's trusted proxy/host settings correctly when generating URLs behind a proxy.
+
+Add only the API scopes your application needs, keeping `openid` for identity lookup:
+
+```ruby
+provider :carta, ENV.fetch("CARTA_CLIENT_ID"), ENV.fetch("CARTA_CLIENT_SECRET"),
+  scope: "openid profile email read_issuer_info"
+```
+
+Scope values must be enabled for your registered Carta application. `profile` and `email` are optional; `openid` is required to use UserInfo. API permissions remain subject to the consenting user's Carta roles. See [Carta's scope reference](https://docs.carta.com/api-platform/guides/references/scopes/).
+
+### Playground
+
+New Carta applications use playground credentials until production promotion and approval. This strategy defaults to production, so configure playground endpoints explicitly. The following endpoint configuration was verified with a Rails integration; confirm it against your Developer Portal's Playground tab:
+
+```ruby
+provider :carta, ENV.fetch("CARTA_CLIENT_ID"), ENV.fetch("CARTA_CLIENT_SECRET"),
+  client_options: {
+    site: "https://login.playground.carta.team",
+    authorize_url: "https://login.playground.carta.team/o/authorize/",
+    token_url: "https://login.playground.carta.team/o/access_token/"
+  },
+  userinfo_url: "https://login.playground.carta.team/o/userinfo/"
+```
+
+The same `/auth/carta/callback` path works in either environment. Its full URL must exactly match the callback registered with the corresponding Carta application, including scheme, hostname, path, and any trailing slash. The client secret is used during token exchange, so an authorization-page rejection can indicate that playground credentials were sent to production or that the registered redirect URI does not match.
+
+Use trusted HTTPS endpoint configuration. See [Carta's playground guide](https://docs.carta.com/api-platform/guides/getting-started/playground-environment/).
+
+## Auth hash
+
+An illustrative successful callback provides:
+
+```ruby
+{
+  "provider" => "carta",
+  "uid" => "carta-user-123", # UserInfo sub; stable identity, not email
+  "info" => {
+    "name" => "Alex Example",
+    "first_name" => "Alex",
+    "last_name" => "Example",
+    "email" => "alex@example.com"
+  },
+  "credentials" => {
+    "token" => "ACCESS_TOKEN",
+    "refresh_token" => "REFRESH_TOKEN",
+    "expires_at" => 1_800_000_000,
+    "expires" => true,
+    "scope" => "openid profile email"
+  },
+  "extra" => {
+    "raw_info" => {
+      "sub" => "carta-user-123",
+      "name" => "Alex Example",
+      "given_name" => "Alex",
+      "family_name" => "Example",
+      "email" => "alex@example.com"
+    }
+  }
+}
+```
+
+Profile fields depend on granted scopes and available claims; missing fields are omitted. UserInfo is fetched once per authentication. A missing or invalid `sub` fails authentication. Credentials follow `omniauth-oauth2` conventions. A returned refresh token is preserved even when expiry information is absent. `scope` contains the space-delimited scopes returned in Carta's token response when present; the strategy does not substitute configured/requested scopes when the response omits it. An omitted scope field is not evidence that access was denied. Record requested scopes separately if you need them for diagnostics.
+
+Identity comes from an authenticated HTTPS UserInfo request. The strategy does not decode, expose, or validate ID tokens and is not a full OIDC relying-party implementation. Do not treat an unverified ID token or an email address as proof of account ownership.
+
+## Using Carta API permissions
+
+Identity scopes (`openid profile email`) allow sign-in; they do not authorize portfolio imports. For example, browsing investor companies requires:
+
+```ruby
+scope: "openid profile email read_investor_firms read_investor_funds read_investor_investments"
+```
+
+Add the read scopes needed for cap tables, securities, or valuations to your application's request. Enabling a scope in the Carta portal does not add it to an existing access token: reconnect the user after expanding the requested scopes. A successful OAuth callback does not guarantee access to every API resource; resource access also depends on the consenting user's permissions and selected resources. Handle API authorization failures in your application.
+
+Keep Carta API clients, pagination, fund/company mappings, import persistence, and refresh coordination in the consuming application. This gem's contract is the OAuth strategy and auth hash. The Rails integration verified investor firms/funds/investments, shareholder portfolios, and managed issuers through separate application-level API calls; those resources are not part of the gem.
+
+## Refreshing API access
+
+OmniAuth handles login; your application manages subsequent API calls and token refresh. Reuse the OAuth2 client with the same endpoint configuration:
+
+```ruby
+strategy = OmniAuth::Strategies::Carta.new(nil,
+  ENV.fetch("CARTA_CLIENT_ID"), ENV.fetch("CARTA_CLIENT_SECRET"))
+token = OAuth2::AccessToken.new(strategy.client, stored_access_token,
+  refresh_token: stored_refresh_token, expires_at: stored_expires_at)
+renewed = token.refresh!
+# Atomically persist renewed.token, renewed.refresh_token, and renewed.expires_at.
+# Preserve the stored refresh token if a token response omits its replacement.
+```
+
+Use your playground options when constructing that client for development. Carta rotates refresh tokens; serialize refreshes for a given connection and persist the new pair together. If refresh is rejected or expired, ask the user to authorize again. Do not put access/refresh tokens in cookies or browser storage. See the [refresh flow](https://docs.carta.com/api-platform/guides/guides/authorization/using-the-authorization-code-flow/#refresh-token-flow).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake          # Minitest + WebMock; no real network calls
+bundle exec rake build    # pkg/omniauth-carta-0.1.0.gem
+```
+
+Tests use synthetic [JSON fixtures](test/fixtures), not captured credentials. They exercise the real middleware, token HTTP requests, PKCE/state, CSRF protection, identity mapping, endpoint overrides, errors, and token rotation. CI is configured for Ruby 3.2, 3.3, 3.4, and 4.0. See [implementation plans](plans/README.md) for decisions and verification results.
+
+Live playground OAuth and subsequent API access were verified in a consuming Rails application on 2026-09-09. Production sign-in has not been verified. Automated tests use synthetic fixtures; they do not establish that a particular Carta application is provisioned correctly.
+
+## License
+
+[MIT](LICENSE.txt). This is an independent integration, not an official Carta SDK.

data/lib/omniauth/carta/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module Carta
+    VERSION = "0.1.0"
+  end
+end

data/lib/omniauth/strategies/carta.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "omniauth-oauth2"
+
+module OmniAuth
+  module Strategies
+    class Carta < OmniAuth::Strategies::OAuth2
+      option :name, "carta"
+      option :scope, "openid profile email"
+      option :pkce, true
+      option :userinfo_url, "/o/userinfo/"
+      option :client_options,
+             site: "https://login.app.carta.com",
+             authorize_url: "/o/authorize/",
+             token_url: "/o/access_token/",
+             auth_scheme: :basic_auth
+
+      uid { raw_info.fetch("sub") }
+
+      info do
+        {
+          name: raw_info["name"],
+          first_name: raw_info["given_name"],
+          last_name: raw_info["family_name"],
+          email: raw_info["email"]
+        }.compact
+      end
+
+      # Extend the inherited OAuth2 credentials without changing token/expiry fields.
+      credentials do
+        hash = {}
+        hash["refresh_token"] = access_token.refresh_token if access_token.refresh_token
+        scope = access_token.params["scope"]
+        hash["scope"] = scope if scope.is_a?(String)
+        hash
+      end
+
+      extra do
+        { raw_info: raw_info }
+      end
+
+      def raw_info
+        @raw_info ||= begin
+          response = access_token.get(options.userinfo_url, headers: { "Accept" => "application/json" }).parsed
+          unless response.is_a?(Hash) && response["sub"].is_a?(String) && !response["sub"].strip.empty?
+            raise CallbackError.new(:invalid_userinfo, "Carta UserInfo must contain a non-empty string sub")
+          end
+          response
+        end
+      end
+
+      def callback_url
+        options[:callback_url] || (full_host + callback_path)
+      end
+
+      protected
+
+      # omniauth-oauth2 1.9 assumes a stored state exists, including on replay.
+      def secure_compare(left, right)
+        return false unless left.is_a?(String) && right.is_a?(String)
+
+        super
+      end
+    end
+  end
+end

data/lib/omniauth-carta.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omniauth/carta/version"
+require "omniauth/strategies/carta"

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-carta
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Avi Flombaum
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: An OmniAuth OAuth2 strategy for Carta using its UserInfo endpoint, with
+  PKCE support.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/omniauth-carta.rb
+- lib/omniauth/carta/version.rb
+- lib/omniauth/strategies/carta.rb
+homepage: https://github.com/aviflombaum/omniauth-carta
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/aviflombaum/omniauth-carta
+  changelog_uri: https://github.com/aviflombaum/omniauth-carta/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/aviflombaum/omniauth-carta/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Carta OAuth2 authentication for OmniAuth
+test_files: []