ksef_client 0.1.0.rc1 → 0.1.0

data/lib/ksef/auth/authorization_policy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # The optional `AuthorizationPolicy` of an {TokenRequest} — a whitelist restricting
+    # which client IPs may use the resulting `accessToken`.
+    #
+    # Its own class rather than a Hash inside {TokenRequest} because the schema treats it
+    # as a distinct structure with its own rules: three list kinds, each capped at ten
+    # entries, in a fixed order, wrapped in an `AllowedIps` element that is mandatory once
+    # the policy is present (docs/REFERENCE.md §4.1).
+    #
+    # The IP values are deliberately **not** pattern-checked here. v2.1's patterns are
+    # correct and the schema will catch a malformed address, whereas v2.0's are broken
+    # outright (§14.4) — duplicating either in Ruby would mean maintaining a second,
+    # divergent source of truth for no gain.
+    class AuthorizationPolicy
+      MAX_IPS = 10
+
+      # Ordered as the schema sequences them; the caller's Hash order is irrelevant.
+      IP_ELEMENTS = { addresses: "Ip4Address", ranges: "Ip4Range", masks: "Ip4Mask" }.freeze
+
+      # The same three lists as JSON, for the KSeF-token flow's `authorizationPolicy`.
+      # Both authentication methods accept the policy; only their encodings differ, so the
+      # rules above are shared rather than restated. The OpenAPI contract caps each of
+      # these arrays at ten entries too, which independently corroborates {MAX_IPS}.
+      IP_FIELDS = { addresses: :ip4Addresses, ranges: :ip4Ranges, masks: :ip4Masks }.freeze
+
+      attr_reader :addresses, :ranges, :masks
+
+      # @return [AuthorizationPolicy, nil] passes `nil` and an existing policy through
+      # @raise [Ksef::ValidationError] on an unknown key
+      def self.coerce(value)
+        return value if value.nil? || value.is_a?(self)
+
+        unknown = value.keys - IP_ELEMENTS.keys
+        unless unknown.empty?
+          raise ValidationError,
+                "Unknown allowed_ips key(s) #{unknown.map(&:inspect).join(", ")}. " \
+                "Permitted: #{IP_ELEMENTS.keys.map(&:inspect).join(", ")}."
+        end
+
+        new(**value)
+      end
+
+      def initialize(addresses: [], ranges: [], masks: [])
+        @addresses = Array(addresses).freeze
+        @ranges = Array(ranges).freeze
+        @masks = Array(masks).freeze
+        validate!
+        freeze
+      end
+
+      # @return [Array<Array(String, String)>] `[element name, value]` pairs in schema order
+      def entries
+        IP_ELEMENTS.flat_map { |key, name| public_send(key).map { |value| [name, value] } }
+      end
+
+      # @return [Hash] the contract's `AllowedIps`, omitting the lists that are empty —
+      #   all three are nullable, and sending `[]` says nothing the absence does not
+      def to_h
+        IP_FIELDS.each_with_object({}) do |(key, field), json|
+          values = public_send(key)
+          json[field] = values unless values.empty?
+        end
+      end
+
+      def empty? = addresses.empty? && ranges.empty? && masks.empty?
+
+      private
+
+      def validate!
+        # AllowedIps is mandatory inside AuthorizationPolicy, so an empty policy cannot be
+        # made schema-valid. Saying so beats emitting a document KSeF will reject.
+        raise ValidationError, "allowed_ips was given but lists no addresses" if empty?
+
+        IP_ELEMENTS.each_key { |key| check_count(key, public_send(key)) }
+      end
+
+      def check_count(key, list)
+        return if list.size <= MAX_IPS
+
+        raise ValidationError,
+              "allowed_ips[#{key.inspect}] has #{list.size} entries; the schema permits #{MAX_IPS}"
+      end
+    end
+  end
+end

data/lib/ksef/auth/challenge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # The response to `POST /auth/challenge` — the prologue to both authentication methods.
+    #
+    # `timestamp_ms` is not decoration: the KSeF-token flow encrypts `{token}|{timestampMs}`
+    # and the timestamp acts as a nonce, so it must be the server's value rather than a
+    # locally generated one (docs/REFERENCE.md §4.5).
+    Challenge = Data.define(:challenge, :timestamp, :timestamp_ms, :client_ip)
+
+    # Reopened rather than using a `Data.define` block, matching {Ksef::FA3::Invoice}: a
+    # constant inside that block would be defined on `Object`, not on the class.
+    class Challenge
+      # Ten minutes from issue (§4).
+      LIFETIME = 600
+
+      # Length 36, `\d{8}-CR-[A-F0-9]{10}-[A-F0-9]{10}-[A-F0-9]{2}` (§4.1). Lives here
+      # rather than on the request documents because it describes a *challenge*, and both
+      # authentication methods consume the same one — the XAdES document and the KSeF-token
+      # JSON body would otherwise each carry their own copy.
+      FORMAT = /\A\d{8}-CR-[A-F0-9]{10}-[A-F0-9]{10}-[A-F0-9]{2}\z/
+
+      # Checked before a request is spent on the challenge, since a malformed or
+      # copy-pasted one is the cheapest failure to catch locally.
+      #
+      # @param value [String]
+      # @raise [Ksef::ValidationError]
+      def self.validate_format!(value)
+        return value if value.is_a?(String) && FORMAT.match?(value)
+
+        raise ValidationError,
+              "Challenge #{value.inspect} is malformed. Expected 36 characters as " \
+              "YYYYMMDD-CR-XXXXXXXXXX-XXXXXXXXXX-XX with uppercase hex, exactly as returned by " \
+              "POST /auth/challenge."
+      end
+
+      def self.from(payload)
+        new(
+          challenge: payload["challenge"],
+          timestamp: Ksef::Auth.time(payload["timestamp"]),
+          timestamp_ms: payload["timestampMs"],
+          client_ip: payload["clientIp"]
+        )
+      end
+
+      # Worth checking before spending a signature on a challenge that has already lapsed.
+      def expires_at = timestamp && (timestamp + LIFETIME)
+      def expired?(now = Time.now) = !expires_at.nil? && expires_at <= now
+      def to_s = challenge.to_s
+    end
+  end
+end

data/lib/ksef/auth/client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ksef
+  module Auth
+    # The six authentication endpoint calls: the five HTTP steps of §4.2's flow — its
+    # sixth step, signing, is offline — plus `POST /auth/ksef-token` for the other
+    # authentication method (docs/REFERENCE.md §4.2, §4.5).
+    #
+    # Deliberately thin: it maps requests and responses and does nothing else. Deciding
+    # *which* credential to present, and caching the result, belongs a layer up in
+    # {Ksef::Client}, which does exactly that.
+    #
+    # Namespaced `Ksef::Auth::Client` rather than folded into `Ksef::Client` so that each
+    # subsystem's endpoints stay together, matching how the official clients are organised.
+    #
+    # Three of these calls are **unauthenticated** — the challenge and both authentication
+    # submissions declare no `security` in the contract. Of the rest, {#status} and
+    # {#redeem} take the temporary *authentication* token and {#refresh} takes the refresh
+    # token, so the bearer is passed per call rather than held by the instance.
+    class Client
+      # Polling defaults. There is deliberately no timeout: on DEMO and PROD the operation
+      # legitimately stays "in progress" while the certificate's status is checked with its
+      # issuer over OCSP/CRL, and the docs say the duration depends on that issuer. A client
+      # that gives up after a fixed interval reports failure for authentications that were
+      # about to succeed (§4.2).
+      POLL_INTERVAL = 2
+
+      # @param connection [Faraday::Connection] usually from {Ksef::HTTP::Connection.build}
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # @return [Challenge]
+      def challenge
+        Challenge.from(post("auth/challenge").body)
+      end
+
+      # Submits the XAdES-signed `AuthTokenRequest`. Returns `202 Accepted`; the operation
+      # is asynchronous from here.
+      #
+      # @param signed_xml [String]
+      # @param verify_certificate_chain [Boolean, nil] the contract's optional query flag
+      # @return [Initiation]
+      def submit_xades(signed_xml, verify_certificate_chain: nil)
+        response = @connection.post("auth/xades-signature") do |request|
+          request.params["verifyCertificateChain"] = verify_certificate_chain unless verify_certificate_chain.nil?
+          request.headers["Content-Type"] = "application/xml"
+          request.body = signed_xml
+        end
+        Initiation.from(response.body)
+      end
+
+      # Submits a KSeF-token authentication. Like {#submit_xades} this takes an
+      # already-built request — {Token#authentication_request} assembles it, because the
+      # encryption depends on which published key was selected and that is not this
+      # layer's decision.
+      #
+      # A `400` here carries `21111` for a bad challenge or `21470` for a stale key
+      # identifier; the latter is worth wrapping in
+      # {Ksef::Crypto::PublicKeys#with_key_rotation}.
+      #
+      # @param request [Hash] the contract's `InitTokenAuthenticationRequest`
+      # @return [Initiation]
+      def submit_ksef_token(request)
+        Initiation.from(post("auth/ksef-token", body: request).body)
+      end
+
+      # @param token [String, TokenInfo] the *authentication* token from {#submit_xades}
+      # @return [OperationStatus]
+      def status(reference_number, token:)
+        OperationStatus.from(get("auth/#{reference_number}", token: token).body)
+      end
+
+      # Exchanges a completed authentication for the token pair. **Single-use** — a second
+      # call with the same authentication token is a 400, so this is never auto-retried
+      # (it is a POST, which the retry policy already excludes).
+      #
+      # @return [Tokens]
+      def redeem(token:)
+        Tokens.from(post("auth/token/redeem", token: token).body)
+      end
+
+      # @return [TokenInfo] a fresh access token
+      def refresh(refresh_token:)
+        TokenInfo.from(post("auth/token/refresh", token: refresh_token).body["accessToken"])
+      end
+
+      # Polls until the operation stops being in progress.
+      #
+      # @param interval [Numeric] seconds between polls
+      # @param sleeper [#call] injected for tests; receives the interval
+      # @yieldparam status [OperationStatus] after each poll, for progress reporting
+      # @return [OperationStatus] the terminal status, successful or not
+      def wait_until_complete(reference_number, token:, interval: POLL_INTERVAL, sleeper: method(:sleep))
+        loop do
+          current = status(reference_number, token: token)
+          yield current if block_given?
+          return current if current.terminal?
+
+          sleeper.call(interval)
+        end
+      end
+
+      # As {#wait_until_complete}, but insists on success.
+      #
+      # @raise [Ksef::AuthenticationError] carrying the server's own wording and details
+      def authenticate!(reference_number, token:, **, &)
+        result = wait_until_complete(reference_number, token: token, **, &)
+        return result if result.success?
+
+        detail = result.details.empty? ? "" : " (#{result.details.join("; ")})"
+        raise AuthenticationError,
+              "Authentication #{reference_number} failed with status #{result.code}: #{result.explain}#{detail}"
+      end
+
+      private
+
+      def get(path, token: nil)
+        @connection.get(path) { |request| authorize(request, token) }
+      end
+
+      def post(path, token: nil, body: nil)
+        @connection.post(path) do |request|
+          authorize(request, token)
+          request.body = body unless body.nil?
+        end
+      end
+
+      # The bearer differs per call: the authentication token for status and redemption,
+      # the refresh token for refresh, and none at all for the first two. A {TokenInfo} or
+      # a bare String both work — but the value has to be pulled out explicitly, because
+      # `TokenInfo#to_s` redacts itself and interpolating one would send "[REDACTED]".
+      def authorize(request, token)
+        return if token.nil?
+
+        value = token.is_a?(TokenInfo) ? token.token : token.to_s
+        request.headers["Authorization"] = "Bearer #{value}"
+      end
+    end
+  end
+end

data/lib/ksef/auth/initiation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # The `202 Accepted` from `POST /auth/xades-signature` — the contract's
+    # `AuthenticationInitResponse`.
+    #
+    # The token here is the short-lived *authentication* token, not an access token. It
+    # authorises exactly two follow-up calls: checking the operation's status, and redeeming
+    # it for the real pair. Confusing the two is the obvious mistake in this flow (docs/REFERENCE.md §4.2).
+    Initiation = Data.define(:reference_number, :authentication_token) do
+      def self.from(payload)
+        new(
+          reference_number: payload["referenceNumber"],
+          authentication_token: TokenInfo.from(payload["authenticationToken"])
+        )
+      end
+
+      def token = authentication_token&.token
+    end
+  end
+end

data/lib/ksef/auth/operation_status.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ksef
+  module Auth
+    # The response to `GET /auth/{referenceNumber}` — the contract's
+    # `AuthenticationOperationStatusResponse`.
+    OperationStatus = Data.define(
+      :code, :description, :details, :authentication_method, :started_at,
+      :token_redeemed, :last_refresh_at, :refresh_token_valid_until
+    ) do
+      def self.from(payload)
+        status = payload["status"] || {}
+        new(
+          code: status["code"],
+          description: status["description"],
+          details: Array(status["details"]).freeze,
+          authentication_method: payload["authenticationMethod"],
+          started_at: Ksef::Auth.time(payload["startDate"]),
+          token_redeemed: payload["isTokenRedeemed"],
+          last_refresh_at: Ksef::Auth.time(payload["lastTokenRefreshDate"]),
+          refresh_token_valid_until: Ksef::Auth.time(payload["refreshTokenValidUntil"])
+        )
+      end
+
+      def in_progress? = Status.in_progress?(code)
+      def success? = Status.success?(code)
+      def terminal? = Status.terminal?(code)
+      def retryable? = Status.retryable?(code)
+
+      # Prefers the server's own wording; falls back to our table when it sends none.
+      def explain = description.to_s.empty? ? Status.describe(code) : description
+    end
+  end
+end

data/lib/ksef/auth/schema/schemat_auth_v2-0.xsd

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsd:schema 
+    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+    xmlns:tns="http://ksef.mf.gov.pl/auth/token/2.0" 
+    targetNamespace="http://ksef.mf.gov.pl/auth/token/2.0" 
+    elementFormDefault="qualified" attributeFormDefault="unqualified">
+    <xsd:element name="AuthTokenRequest">
+        <xsd:complexType>
+            <xsd:sequence>
+                <xsd:element name="Challenge">
+                    <xsd:simpleType>
+                        <xsd:restriction base="xsd:token">
+                            <xsd:length value="36"/>
+                            <xsd:pattern value="\d{8}-CR-[A-F0-9]{10}-[A-F0-9]{10}-[A-F0-9]{2}"/>
+                        </xsd:restriction>
+                    </xsd:simpleType>
+                </xsd:element>
+                <xsd:element name="ContextIdentifier" type="tns:TContextIdentifier"/>
+                <xsd:element name="SubjectIdentifierType" type="tns:SubjectIdentifierTypeEnum"/>
+                <xsd:element name="AuthorizationPolicy" minOccurs="0">
+                    <xsd:complexType>
+                        <xsd:sequence>
+                            <xsd:element name="AllowedIps">
+                                <xsd:complexType>
+                                    <xsd:sequence minOccurs="1" maxOccurs="1">
+                                        <xsd:element name="Ip4Address" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                        <xsd:element name="Ip4Range" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}-((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                        <xsd:element name="Ip4Mask" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}\/(0|[1-9]|1[0-9]|2[0-9]|3[0-2])$"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                    </xsd:sequence>
+                                </xsd:complexType>
+                            </xsd:element>
+                        </xsd:sequence>
+                    </xsd:complexType>
+                </xsd:element>
+            </xsd:sequence>
+        </xsd:complexType>
+    </xsd:element>
+    <xsd:simpleType name="SubjectIdentifierTypeEnum">
+        <xsd:restriction base="xsd:token">
+            <xsd:enumeration value="certificateSubject"/>
+            <xsd:enumeration value="certificateFingerprint"/>
+        </xsd:restriction>
+    </xsd:simpleType>    
+    
+    <xsd:complexType name="TContextIdentifier">
+        <xsd:choice>
+            <xsd:element name="Nip" type="tns:TNIP">
+                <xsd:annotation>
+                    <xsd:documentation>Numer Identyfikacyjny NIP</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="InternalId" type="tns:TIID">
+                <xsd:annotation>
+                    <xsd:documentation>Identyfikator wewnętrzny</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="NipVatUe" type="tns:TNipVatUE">
+                <xsd:annotation>
+                    <xsd:documentation>Kontekst złożony, będący połaczniem numeru NIP oraz numeru Vat UE</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="PeppolId" type="tns:TPeppolId">
+                <xsd:annotation>
+                    <xsd:documentation>Identyfikator dostawcy usług Peppol</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+        </xsd:choice>
+    </xsd:complexType>
+    
+    <xsd:simpleType name="TIID">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}-\d{5}"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TNIP">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TNipVatUE">
+        <xsd:restriction base="xsd:string">
+            <!-- based on: https://ec.europa.eu/taxation_customs/vies/#/faq   Q11 -->
+            <xsd:pattern value="([1-9]((\d[1-9])|([1-9]\d))\d{7}-((AT)(U\d{8})|(BE)([01]{1}\d{9})|(BG)(\d{9,10})|(CY)(\d{8}[A-Z])|(CZ)(\d{8,10})|(DE)(\d{9})|(DK)(\d{8})|(EE)(\d{9})|(EL)(\d{9})|(ES)([A-Z]\d{8}|\d{8}[A-Z]|[A-Z]\d{7}[A-Z])|(FI)(\d{8})|(FR)[A-Z0-9]{2}\d{9}|(HR)(\d{11})|(HU)(\d{8})|(IE)(\d{7}[A-Z]{2}|\d[A-Z0-9+*]\d{5}[A-Z])|(IT)(\d{11})|(LT)(\d{9}|\d{12})|(LU)(\d{8})|(LV)(\d{11})|(MT)(\d{8})|(NL)([A-Z0-9+*]{12})|(PT)(\d{9})|(RO)(\d{2,10})|(SE)(\d{12})|(SI)(\d{8})|(SK)(\d{10})|(XI)((\d{9}|(\d{12}))|(GD|HA)(\d{3}))))$"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TPeppolId">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="^P[A-Z]{2}[0-9]{6}$"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+</xsd:schema>

data/lib/ksef/auth/schema/schemat_auth_v2-1.xsd

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsd:schema 
+    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+    xmlns:tns="http://ksef.mf.gov.pl/auth/token/2.1" 
+    targetNamespace="http://ksef.mf.gov.pl/auth/token/2.1" 
+    elementFormDefault="qualified" attributeFormDefault="unqualified">
+    <xsd:element name="AuthTokenRequest">
+        <xsd:complexType>
+            <xsd:sequence>
+                <xsd:element name="Challenge">
+                    <xsd:simpleType>
+                        <xsd:restriction base="xsd:token">
+                            <xsd:length value="36"/>
+                            <xsd:pattern value="\d{8}-CR-[A-F0-9]{10}-[A-F0-9]{10}-[A-F0-9]{2}"/>
+                        </xsd:restriction>
+                    </xsd:simpleType>
+                </xsd:element>
+                <xsd:element name="ContextIdentifier" type="tns:TContextIdentifier"/>
+                <xsd:element name="SubjectIdentifierType" type="tns:SubjectIdentifierTypeEnum"/>
+                <xsd:element name="AuthorizationPolicy" minOccurs="0">
+                    <xsd:complexType>
+                        <xsd:sequence>
+                            <xsd:element name="AllowedIps">
+                                <xsd:complexType>
+                                    <xsd:sequence minOccurs="1" maxOccurs="1">
+                                        <xsd:element name="Ip4Address" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                        <xsd:element name="Ip4Range" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])-((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                        <xsd:element name="Ip4Mask" minOccurs="0" maxOccurs="10">
+                                            <xsd:simpleType>
+                                                <xsd:restriction base="xsd:token">
+                                                    <xsd:pattern value="((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])/(0|[1-9]|[12][0-9]|3[0-2])"/>
+                                                </xsd:restriction>
+                                            </xsd:simpleType>
+                                        </xsd:element>
+                                    </xsd:sequence>
+                                </xsd:complexType>
+                            </xsd:element>
+                        </xsd:sequence>
+                    </xsd:complexType>
+                </xsd:element>
+            </xsd:sequence>
+        </xsd:complexType>
+    </xsd:element>
+    <xsd:simpleType name="SubjectIdentifierTypeEnum">
+        <xsd:restriction base="xsd:token">
+            <xsd:enumeration value="certificateSubject"/>
+            <xsd:enumeration value="certificateFingerprint"/>
+        </xsd:restriction>
+    </xsd:simpleType>	
+    
+    <xsd:complexType name="TContextIdentifier">
+        <xsd:choice>
+            <xsd:element name="Nip" type="tns:TNIP">
+                <xsd:annotation>
+                    <xsd:documentation>Numer Identyfikacyjny NIP</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="InternalId" type="tns:TIID">
+                <xsd:annotation>
+                    <xsd:documentation>Identyfikator wewnętrzny</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="NipVatUe" type="tns:TNipVatUE">
+                <xsd:annotation>
+                    <xsd:documentation>Kontekst złożony, będący połaczniem numeru NIP oraz numeru Vat UE</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+            <xsd:element name="PeppolId" type="tns:TPeppolId">
+                <xsd:annotation>
+                    <xsd:documentation>Identyfikator dostawcy usług Peppol</xsd:documentation>
+                </xsd:annotation>
+            </xsd:element>
+        </xsd:choice>
+    </xsd:complexType>
+    
+    <xsd:simpleType name="TIID">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}-\d{5}"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TNIP">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TNipVatUE">
+        <xsd:restriction base="xsd:string">
+            <!-- based on: https://ec.europa.eu/taxation_customs/vies/#/faq   Q11 -->
+            <xsd:pattern value="([1-9]((\d[1-9])|([1-9]\d))\d{7}-((AT)(U\d{8})|(BE)([01]{1}\d{9})|(BG)(\d{9,10})|(CY)(\d{8}[A-Z])|(CZ)(\d{8,10})|(DE)(\d{9})|(DK)(\d{8})|(EE)(\d{9})|(EL)(\d{9})|(ES)([A-Z]\d{8}|\d{8}[A-Z]|[A-Z]\d{7}[A-Z])|(FI)(\d{8})|(FR)[A-Z0-9]{2}\d{9}|(HR)(\d{11})|(HU)(\d{8})|(IE)(\d{7}[A-Z]{2}|\d[A-Z0-9+*]\d{5}[A-Z])|(IT)(\d{11})|(LT)(\d{9}|\d{12})|(LU)(\d{8})|(LV)(\d{11})|(MT)(\d{8})|(NL)([A-Z0-9+*]{12})|(PT)(\d{9})|(RO)(\d{2,10})|(SE)(\d{12})|(SI)(\d{8})|(SK)(\d{10})|(XI)((\d{9}|(\d{12}))|(GD|HA)(\d{3}))))$"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+    <xsd:simpleType name="TPeppolId">
+        <xsd:restriction base="xsd:string">
+            <xsd:pattern value="^P[A-Z]{2}[0-9]{6}$"/>
+        </xsd:restriction>
+    </xsd:simpleType>
+</xsd:schema>