masks-server 0.7.0

data/app/models/masks/server/provider_preset.rb

@@ -0,0 +1,234 @@
+module Masks
+  module Server
+    class ProviderPreset
+      class Unusable < StandardError; end
+
+      VARIABLES = {
+        "domain" => /\A[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\d{1,5})?\z/i,
+        "tenant" => /\A[a-z0-9][a-z0-9.-]{0,127}\z/i,
+        "realm" => /\A[A-Za-z0-9_-]{1,64}\z/
+      }.freeze
+
+      SETTINGS = %i[
+        protocol issuer authorization_url token_url userinfo_url emails_url jwks_uri
+        scopes subject_claim claims trusts_email token_auth_method response_mode authorize_params name_id_format
+        delegated_scopes delegation_params resource_url
+      ].freeze
+
+      ALL = [
+        {
+          key: "google", name: "Google", protocol: "oidc",
+          issuer: "https://accounts.google.com",
+          authorization_url: "https://accounts.google.com/o/oauth2/v2/auth",
+          token_url: "https://oauth2.googleapis.com/token",
+          userinfo_url: "https://openidconnect.googleapis.com/v1/userinfo",
+          jwks_uri: "https://www.googleapis.com/oauth2/v3/certs",
+          trusts_email: true,
+          delegated_scopes: "https://www.googleapis.com/auth/drive.readonly",
+          delegation_params: { "access_type" => "offline", "prompt" => "consent" },
+          guide: "https://console.cloud.google.com/apis/credentials"
+        },
+        {
+          key: "microsoft", name: "Microsoft", protocol: "oidc",
+          issuer: "https://login.microsoftonline.com/{tenant}/v2.0",
+          asks: %w[tenant],
+          delegated_scopes: "offline_access Files.Read.All",
+          guide: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade"
+        },
+        {
+          key: "apple", name: "Apple", protocol: "oidc",
+          issuer: "https://appleid.apple.com",
+          authorization_url: "https://appleid.apple.com/auth/authorize",
+          token_url: "https://appleid.apple.com/auth/token",
+          jwks_uri: "https://appleid.apple.com/auth/keys",
+          scopes: "name email",
+          response_mode: "form_post",
+          token_auth_method: "signed_secret",
+          trusts_email: true,
+          needs: %w[team_id key_id private_key],
+          guide: "https://developer.apple.com/account/resources/identifiers/list/serviceId"
+        },
+        {
+          key: "github", name: "GitHub", protocol: "oauth2",
+          authorization_url: "https://github.com/login/oauth/authorize",
+          token_url: "https://github.com/login/oauth/access_token",
+          userinfo_url: "https://api.github.com/user",
+          emails_url: "https://api.github.com/user/emails",
+          scopes: "read:user user:email",
+          subject_claim: "id",
+          claims: { "preferred_username" => "login", "name" => "name", "picture" => "avatar_url", "profile" => "html_url" },
+          trusts_email: true,
+          guide: "https://github.com/settings/developers"
+        },
+        {
+          key: "gitlab", name: "GitLab", protocol: "oidc",
+          issuer: "https://{domain}",
+          asks: %w[domain],
+          defaults: { "domain" => "gitlab.com" },
+          trusts_email: true,
+          guide: "https://gitlab.com/-/user_settings/applications"
+        },
+        {
+          key: "slack", name: "Slack", protocol: "oidc",
+          issuer: "https://slack.com",
+          authorization_url: "https://slack.com/openid/connect/authorize",
+          token_url: "https://slack.com/api/openid.connect.token",
+          userinfo_url: "https://slack.com/api/openid.connect.userInfo",
+          jwks_uri: "https://slack.com/openid/connect/keys",
+          trusts_email: true,
+          guide: "https://api.slack.com/apps"
+        },
+        {
+          key: "linkedin", name: "LinkedIn", protocol: "oidc",
+          issuer: "https://www.linkedin.com/oauth",
+          authorization_url: "https://www.linkedin.com/oauth/v2/authorization",
+          token_url: "https://www.linkedin.com/oauth/v2/accessToken",
+          userinfo_url: "https://api.linkedin.com/v2/userinfo",
+          jwks_uri: "https://www.linkedin.com/oauth/openid/jwks",
+          trusts_email: true,
+          guide: "https://www.linkedin.com/developers/apps"
+        },
+        {
+          key: "discord", name: "Discord", protocol: "oauth2",
+          authorization_url: "https://discord.com/oauth2/authorize",
+          token_url: "https://discord.com/api/oauth2/token",
+          userinfo_url: "https://discord.com/api/users/@me",
+          scopes: "identify email",
+          subject_claim: "id",
+          claims: { "email_verified" => "verified", "preferred_username" => "username", "name" => "global_name" },
+          trusts_email: true,
+          guide: "https://discord.com/developers/applications"
+        },
+        {
+          key: "facebook", name: "Facebook", protocol: "oauth2",
+          authorization_url: "https://www.facebook.com/v23.0/dialog/oauth",
+          token_url: "https://graph.facebook.com/v23.0/oauth/access_token",
+          userinfo_url: "https://graph.facebook.com/v23.0/me?fields=id,name,email,first_name,last_name,picture",
+          scopes: "public_profile email",
+          subject_claim: "id",
+          claims: { "given_name" => "first_name", "family_name" => "last_name", "picture" => "picture.data.url" },
+          guide: "https://developers.facebook.com/apps"
+        },
+        {
+          key: "x", name: "X", protocol: "oauth2",
+          authorization_url: "https://x.com/i/oauth2/authorize",
+          token_url: "https://api.x.com/2/oauth2/token",
+          userinfo_url: "https://api.x.com/2/users/me?user.fields=profile_image_url",
+          scopes: "users.read tweet.read",
+          subject_claim: "data.id",
+          claims: { "preferred_username" => "data.username", "name" => "data.name", "picture" => "data.profile_image_url" },
+          token_auth_method: "client_secret_basic",
+          guide: "https://developer.x.com/en/portal/projects-and-apps"
+        },
+        {
+          key: "okta", name: "Okta", protocol: "oidc",
+          issuer: "https://{domain}",
+          asks: %w[domain],
+          guide: "https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm"
+        },
+        {
+          key: "auth0", name: "Auth0", protocol: "oidc",
+          issuer: "https://{domain}",
+          asks: %w[domain],
+          guide: "https://manage.auth0.com/#/applications"
+        },
+        {
+          key: "keycloak", name: "Keycloak", protocol: "oidc",
+          issuer: "https://{domain}/realms/{realm}",
+          asks: %w[domain realm],
+          guide: "https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients"
+        },
+        {
+          key: "entra-saml", name: "Microsoft Entra (SAML)", protocol: "saml",
+          claims: {
+            "email" => "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+            "given_name" => "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+            "family_name" => "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
+            "name" => "http://schemas.microsoft.com/identity/claims/displayname"
+          },
+          needs: %w[metadata],
+          guide: "https://learn.microsoft.com/entra/identity/enterprise-apps/add-application-portal-setup-sso"
+        },
+        {
+          key: "okta-saml", name: "Okta (SAML)", protocol: "saml",
+          claims: { "given_name" => "firstName", "family_name" => "lastName" },
+          needs: %w[metadata],
+          guide: "https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm"
+        },
+        {
+          key: "google-workspace-saml", name: "Google Workspace (SAML)", protocol: "saml",
+          name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+          needs: %w[metadata],
+          guide: "https://support.google.com/a/answer/12032922"
+        },
+        {
+          key: "notion", name: "Notion (MCP)", protocol: "mcp",
+          resource_url: "https://mcp.notion.com/mcp",
+          needs: [],
+          guide: "https://developers.notion.com/docs/mcp"
+        },
+        { key: "mcp", name: "MCP server", protocol: "mcp", custom: true, needs: %w[resource_url] },
+        { key: "oidc", name: "OpenID Connect", protocol: "oidc", custom: true },
+        { key: "oauth2", name: "OAuth 2.0", protocol: "oauth2", custom: true },
+        { key: "saml", name: "SAML 2.0", protocol: "saml", custom: true, needs: %w[metadata] }
+      ].map(&:freeze).freeze
+
+      class << self
+        def all
+          ALL.map { |definition| new(definition) }
+        end
+
+        def find(key)
+          definition = ALL.find { |held| held[:key] == key.to_s }
+
+          definition && new(definition)
+        end
+      end
+
+      attr_reader :definition
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def key = definition[:key]
+      def name = definition[:name]
+      def protocol = definition[:protocol]
+      def asks = definition.fetch(:asks, [])
+      def needs = definition.fetch(:needs, %w[client_secret])
+      def defaults = definition.fetch(:defaults, {})
+      def guide = definition[:guide]
+      def trusts_email = definition.fetch(:trusts_email, false)
+      def custom? = definition.fetch(:custom, false)
+      def delegated_scopes = Scopes.list(definition[:delegated_scopes])
+      def delegates? = protocol == Provider::MCP
+
+      def attributes(values = {})
+        given = defaults.merge(values.to_h.stringify_keys.slice(*asks).compact_blank)
+
+        asks.each do |variable|
+          raise Unusable, "#{name} needs a #{variable}" if given[variable].blank?
+          raise Unusable, "#{given[variable]} is not a usable #{variable}" unless given[variable].to_s.match?(VARIABLES.fetch(variable))
+        end
+
+        SETTINGS.each_with_object(preset: key) do |setting, held|
+          value = definition[setting]
+          next if value.nil?
+
+          held[setting] = value.is_a?(String) ? interpolate(value, given) : value
+        end
+      end
+
+      private
+
+        def interpolate(value, given)
+          value.gsub(/\{(\w+)\}/) do
+            variable = Regexp.last_match(1)
+            held = given.fetch(variable).to_s
+
+            variable == "domain" ? held.downcase : held
+          end
+        end
+    end
+  end
+end

data/app/models/masks/server/provisioning_token.rb

@@ -0,0 +1,35 @@
+module Masks
+  module Server
+    class ProvisioningToken < Token
+      LONGEST = 1.year
+
+      def self.issue!(label:, by:, expires_in: nil, organization: nil)
+        lifetime = [ expires_in&.seconds || LONGEST, LONGEST ].min
+
+        mint!(
+          organization: organization,
+          payload: { "label" => label.to_s.strip.presence || "Provisioning", "issued_by" => by&.uuid }.compact,
+          expires_at: lifetime.from_now
+        )
+      end
+
+      def label
+        held("label")
+      end
+
+      def issued_by
+        Actor.find_by(uuid: held("issued_by")) if held("issued_by")
+      end
+
+      def used_at
+        held("used_at")&.then { |value| Time.zone.parse(value) }
+      end
+
+      def used!
+        return if used_at && used_at > 5.minutes.ago
+
+        update_columns(payload: (payload || {}).merge("used_at" => Time.current.iso8601))
+      end
+    end
+  end
+end

data/app/models/masks/server/pushed_request.rb

@@ -0,0 +1,39 @@
+module Masks
+  module Server
+    class PushedRequest < Token
+      include CarriesAuthorization
+
+      PREFIX = "urn:ietf:params:oauth:request_uri:".freeze
+
+      def self.lifetime
+        90.seconds
+      end
+
+      def self.push!(authorization)
+        mint!(**attributes_for(authorization))
+      end
+
+      def self.urn?(value)
+        value.to_s.start_with?(PREFIX)
+      end
+
+      def self.claim_urn(value, client:)
+        return nil unless urn?(value)
+
+        secret = value.to_s.delete_prefix(PREFIX)
+
+        return nil unless redeem(secret)&.pushed_by?(client)
+
+        claim(secret)
+      end
+
+      def request_uri
+        "#{PREFIX}#{secret}"
+      end
+
+      def pushed_by?(client)
+        client.present? && client_id == client.id
+      end
+    end
+  end
+end

data/app/models/masks/server/received_signal.rb

@@ -0,0 +1,131 @@
+module Masks
+  module Server
+    class ReceivedSignal
+      class Refused < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          super(message)
+          @code = code
+        end
+      end
+
+      TYPE = "secevent+jwt".freeze
+      MEMORY = 7.days
+      LEEWAY = 60
+      SIGNED_OUT = %w[
+        https://schemas.openid.net/secevent/caep/event-type/session-revoked
+        https://schemas.openid.net/secevent/caep/event-type/credential-change
+        https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
+        https://schemas.openid.net/secevent/risc/event-type/account-disabled
+        https://schemas.openid.net/secevent/risc/event-type/account-purged
+        https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required
+      ].freeze
+
+      attr_reader :provider, :claims
+
+      def initialize(token, issuer:)
+        @token = token.to_s.strip
+        @issuer = issuer
+      end
+
+      def receive!
+        @provider = sender
+        @claims = verified
+
+        audience!
+        fresh!
+        once!
+
+        signed_out.each { |type, actors| actors.each { |actor| sign_out!(actor, type) } }
+
+        self
+      end
+
+      private
+
+        def unverified
+          @unverified ||= JWT.decode(@token, nil, false)
+        rescue JWT::DecodeError
+          raise Refused.new("invalid_request", "the body is not a security event token")
+        end
+
+        def sender
+          issued_by = unverified.first["iss"].to_s.chomp("/")
+
+          Provider.active.where(protocol: Provider::OIDC, receives_signals: true).find_by(issuer: issued_by) ||
+            raise(Refused.new("invalid_issuer", "no provider here sends signals as #{issued_by.truncate(100)}"))
+        end
+
+        def verified
+          held, header = provider.federation.verify_signed(@token)
+
+          raise Refused.new("invalid_request", "a security event token is typed #{TYPE}") unless header["typ"].to_s.casecmp?(TYPE)
+          raise Refused.new("invalid_request", "a security event token carries events") unless held["events"].is_a?(Hash)
+
+          held
+        rescue Provider::Untrusted, Provider::Refused, Provider::Unreachable => e
+          raise Refused.new("invalid_key", e.message)
+        end
+
+        def audience!
+          accepted = [ @issuer.url, "#{@issuer.url}/ssf/events" ]
+
+          return if Array(claims["aud"]).intersect?(accepted)
+
+          raise Refused.new("invalid_audience", "that security event token is meant for another receiver")
+        end
+
+        def fresh!
+          issued = claims["iat"]
+
+          raise Refused.new("invalid_request", "a security event token carries iat") unless issued.is_a?(Integer)
+          return if issued.between?((Time.current - MEMORY).to_i, (Time.current + LEEWAY).to_i)
+
+          raise Refused.new("invalid_request", "that security event token was not issued within the last #{MEMORY.inspect}")
+        end
+
+        def once!
+          jti = claims["jti"].to_s
+
+          raise Refused.new("invalid_request", "a security event token carries a jti") if jti.empty?
+          return if Replay.first?("signal", jti, within: provider.id, expires_in: MEMORY)
+
+          raise Refused.new("invalid_request", "that security event token has already been received")
+        end
+
+        def signed_out
+          claims["events"].slice(*SIGNED_OUT).to_h do |type, body|
+            subject = (body.is_a?(Hash) && body["subject"]) || claims["sub_id"]
+
+            [ type, accounts(subject) ]
+          end
+        end
+
+        def accounts(subject)
+          return [] unless subject.is_a?(Hash)
+
+          connections =
+            case subject["format"] || subject["subject_type"]
+            when "iss_sub", "iss-sub"
+              return [] unless subject["iss"].to_s.chomp("/") == provider.issuer
+
+              Connection.live.where(provider: provider, subject: subject["sub"].to_s)
+            when "email"
+              Connection.live.where(provider: provider, email: subject["email"].to_s.downcase)
+            else
+              Connection.none
+            end
+
+          Actor.where(id: connections.select(:actor_id)).to_a
+        end
+
+        def sign_out!(actor, type)
+          actor.sign_out_everywhere!
+
+          Event.record!(Event::SIGNAL_RECEIVED, actor: actor, by: nil, provider: provider.key,
+                                                event: type, jti: claims["jti"])
+        end
+    end
+  end
+end

data/app/models/masks/server/recoveries.rb

@@ -0,0 +1,40 @@
+module Masks
+  module Server
+    module Recoveries
+      def self.request(identifier:, journey:)
+        actor = Actor.locate(identifier)
+
+        return false unless mailable?(actor)
+
+        deliver(PasswordReset.open!(actor: actor), actor, journey)
+        noted(actor, nil)
+        true
+      end
+
+      def self.open(actor:, journey:)
+        reset = PasswordReset.open!(actor: actor, by: journey.by)
+        noted(actor, journey.by)
+
+        return { delivered: false, url: reset.url(Current.origin) } unless mailable?(actor)
+
+        deliver(reset, actor, journey)
+
+        { delivered: true, url: nil }
+      end
+
+      def self.noted(actor, by)
+        Event.record!(Event::PASSWORD_RESET_REQUESTED, actor: actor, by: by)
+      end
+
+      def self.mailable?(actor)
+        ActorMailer.deliverable? && actor.present? && actor.activated? && actor.email.present?
+      end
+
+      def self.deliver(reset, actor, journey)
+        ActorMailer.password_reset(actor, reset.url(Current.origin), journey: journey).deliver_later
+
+        reset.delivered!
+      end
+    end
+  end
+end

data/app/models/masks/server/refresh_token.rb

@@ -0,0 +1,19 @@
+module Masks
+  module Server
+    class RefreshToken < Token
+      def self.lifetime
+        30.days
+      end
+
+      def self.mint!(**attributes)
+        super.tap { |token| token.actor&.active! }
+      end
+
+      def revoke!
+        transaction do
+          super + family.where(kind: AccessToken.sti_name).live.update_all(consumed_at: Time.current, updated_at: Time.current)
+        end
+      end
+    end
+  end
+end

data/app/models/masks/server/relying_party.rb

@@ -0,0 +1,76 @@
+module Masks
+  module Server
+    class RelyingParty
+      TIMEOUT = 120_000
+
+      def self.for(tenant = Current.tenant, origin = Current.origin)
+        new(tenant, origin)
+      end
+
+      attr_reader :tenant, :origin
+
+      def initialize(tenant, origin)
+        @tenant = tenant
+        @origin = origin
+      end
+
+      def id
+        URI.parse(origin).host
+      end
+
+      def party
+        @party ||= WebAuthn::RelyingParty.new(
+          allowed_origins: [ URI.parse(origin).then { |uri| "#{uri.scheme}://#{uri.authority}" } ],
+          name: tenant&.name.presence || id,
+          id: id
+        )
+      end
+
+      def registration_options(actor, user_verification: "preferred", resident_key: "preferred")
+        party.options_for_registration(
+          user: {
+            id: handle_for(actor),
+            name: actor.email.presence || actor.nickname,
+            display_name: actor.name.presence || actor.identifier
+          },
+          exclude: Passkey.where(actor_id: actor.id).pluck(:external_id),
+          authenticator_selection: {
+            resident_key: resident_key,
+            user_verification: user_verification
+          }
+        )
+      end
+
+      def authentication_options(actor = nil)
+        party.options_for_authentication(
+          allow: actor ? Passkey.where(actor_id: actor.id).pluck(:external_id) : [],
+          user_verification: "preferred"
+        )
+      end
+
+      def verify_registration(response, challenge)
+        credential = WebAuthn::Credential.from_create(response, relying_party: party)
+        credential.verify(challenge)
+        credential
+      end
+
+      def verify_authentication(response, challenge, passkey)
+        credential = WebAuthn::Credential.from_get(response, relying_party: party)
+
+        credential.verify(
+          challenge,
+          public_key: passkey.public_key,
+          sign_count: passkey.sign_count
+        )
+
+        credential
+      end
+
+      def handle_for(actor)
+        actor.webauthn_id.presence || actor.tap { |held|
+          held.update!(webauthn_id: WebAuthn.generate_user_id)
+        }.webauthn_id
+      end
+    end
+  end
+end

data/app/models/masks/server/replay.rb

@@ -0,0 +1,11 @@
+module Masks
+  module Server
+    module Replay
+      def self.first?(kind, id, expires_in:, within: nil)
+        key = [ kind, Current.tenant&.id, within, Digest::SHA256.hexdigest(id.to_s) ].compact.join(":")
+
+        ::Rails.cache.write(key, true, expires_in: expires_in, unless_exist: true)
+      end
+    end
+  end
+end

data/app/models/masks/server/request_object.rb

@@ -0,0 +1,84 @@
+module Masks
+  module Server
+    class RequestObject
+      class Refused < StandardError; end
+
+      TYPE = "oauth-authz-req+jwt".freeze
+      TYPES = [ TYPE, "application/#{TYPE}", "jwt", nil ].freeze
+      SUBJECT = "that request object".freeze
+      CARRIED = %w[
+        response_type redirect_uri scope state nonce code_challenge code_challenge_method
+        prompt max_age acr_values organization resource claims authorization_details dpop_jkt
+      ].freeze
+
+      def self.unpack!(authorization, issuer:)
+        new(authorization.request_object, client: authorization.client, client_id: authorization.client_id, issuer: issuer).authorization
+      end
+
+      def initialize(token, client:, client_id:, issuer:)
+        @token = token.to_s
+        @client = client
+        @client_id = client_id.to_s
+        @issuer = issuer
+      end
+
+      def authorization
+        claims = verified
+
+        Authorization.new(**claims.slice(*CARRIED).symbolize_keys, client_id: client_id, signed: true)
+      end
+
+      private
+
+        attr_reader :token, :client, :client_id, :issuer
+
+        def verified
+          raise Refused, "client_id is required beside a request object" if client_id.blank?
+          raise Refused, "no client is registered with that client_id" if client.nil?
+          raise Refused, "this client has registered no keys to sign a request object with" unless client.keys?
+
+          claims, header = keys.decode(token, subject: SUBJECT)
+
+          typed!(header)
+          named!(claims)
+          keys.timely!(claims, subject: SUBJECT)
+          recent!(claims)
+          contained!(claims)
+          keys.once!(claims, kind: "request-object", subject: SUBJECT) if claims["jti"].present?
+
+          claims
+        rescue ClientKeys::Refused => e
+          raise Refused, e.message
+        end
+
+        def keys
+          @keys ||= ClientKeys.new(client)
+        end
+
+        def typed!(header)
+          held = header["typ"]&.to_s&.downcase
+
+          raise Refused, "a request object is typed #{TYPE}, not #{header['typ']}" unless TYPES.include?(held)
+        end
+
+        def named!(claims)
+          raise Refused, "a request object's iss must be the client that signed it" unless claims["iss"] == client.client_id
+          raise Refused, "the client_id inside a request object must match the one beside it" unless claims["client_id"] == client_id
+
+          unless Array(claims["aud"]).map { |one| one.to_s.chomp("/") }.include?(issuer.url)
+            raise Refused, "a request object must be addressed to #{issuer.url}"
+          end
+        end
+
+        def recent!(claims)
+          return unless claims["nbf"].is_a?(Numeric) && claims["nbf"] < Time.current.to_i - ClientKeys::LONGEST.to_i
+
+          raise Refused, "#{SUBJECT} was made more than #{ClientKeys::LONGEST.inspect} ago"
+        end
+
+        def contained!(claims)
+          raise Refused, "a request object may not carry another request" if claims.key?("request") || claims.key?("request_uri")
+        end
+    end
+  end
+end