tungsten-runtime 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df110fa13841d1574e906b26ac0c64eef7102be30ccbfce2789dd462c165b657
-  data.tar.gz: 20106e7943dfa350c6818fb6cc5f9187139fe98b592c33ccd5cf217e73dee1c0
+  metadata.gz: b6555377e7e8580de6fa660f16a5a9b764a61b5206b992f20c5c65dc3791d3af
+  data.tar.gz: af2cbf8b640fb487fd53f630f15fd6f7905490eab697c27b4432160233ed95fa
 SHA512:
-  metadata.gz: a930ac5449418b2597860bd6b925ff3930a293f8649efa0c4a2c8ad1d7b0aa2a3afb87fffc18d61d958a607be36c6bd59ab65bdf74fa7c8eb55ebde92ebb4adb
-  data.tar.gz: 6a834eb1ecce40a9cf7c570efa61dc8d4d68814cc23b1a66f2039c300f94510f4c81c75be77d1c0bedf3173b586cef8d7105fb1cb936d58c7a030762b9a7a39f
+  metadata.gz: 841805313c667ee7c2d258ce86424918a14840f75c5eff15790f63a1686ad7c7dcf1e17ca1fb78117efc1139abbc46cc4cda8412251ee6a9ccceb0410b9cfb79
+  data.tar.gz: 06134745fdcd13043ac3318059f33605489ec999d88da4333e67b2d2c3d38964b9c6ad7ccfd09ca7379eafe6c62528be491c66ae595d7ecfddc3f2535bfb3778

data/README.md

@@ -35,7 +35,7 @@ responsible for authorization and server-side idempotency.
 Select `FileIdempotencyStore` through the client's idempotency-store option to
 reuse keys after a restart and coordinate automatic key allocation across
 processes. The version-1 JSON file and `<path>.lock` owner lease interoperate
-with the TypeScript, Python, Go, Rust, Java, C# and Ruby stores.
+with the TypeScript, Python, Go, Rust, Java, C#, Ruby and Dart stores.
 
 ```ruby
 options = Tungsten::Runtime::ClientOptions.new(
@@ -59,16 +59,198 @@ token immediately before commit and removes only its own lease. Use a filesystem
 that supports exclusive creation and atomic rename; this is not a distributed
 transaction service. Losing this file can cause a new key for a previous intent.
 
+## Credential transport
+
+Credentials require HTTPS by default, including OAuth client-credentials, code
+exchange and refresh endpoints. Non-loopback HTTP returns `AUTH_FAILED` before
+sending credentials. Migrate authenticated HTTP services to HTTPS, or explicitly
+opt in with `allow_insecure_http: true` in client options for intentional insecure transport.
+This permits cleartext credentials; enable it only for a trusted environment.
+
+The local-development exception covers `localhost` (also with a trailing dot),
+literal IPv4 `127/8`, and IPv6 `::1`. Subdomains, unspecified addresses and
+IPv4-mapped IPv6 addresses require the explicit override. DNS resolution does not
+grant an exception. Anonymous HTTP requests remain supported.
+
+## Managed OAuth authorization
+
+In unreleased 0.2.0, `client.oauth(scheme).authorization_url` begins a managed
+authorization attempt. Configure the scheme with `flow: "authorizationCode"`,
+`client_id`, `redirect_uri`, and a `client_secret` only when the provider requires
+one. Qualify the provider's S256 support and issuer response before enabling them:
+
+```ruby
+flow = client.oauth("browser") # Use the generated API's scheme name.
+binding = SecureRandom.hex(32) # Keep with the owning session or callback listener.
+started = flow.authorization_url(
+  session_binding: binding,
+  s256_supported: true,
+  issuer_defense: Tungsten::Runtime::IssuerDefense.issuer_response("https://issuer.example")
+)
+raise "Authorization could not begin" unless started.ok?
+attempt = started.value
+# Open attempt.url in the browser. Retain attempt.attempt_handle with binding.
+# callback_url is the full URL received by that same owning listener.
+completed = flow.exchange_code(
+  attempt_handle: attempt.attempt_handle,
+  callback_url: callback_url,
+  session_binding: binding
+)
+raise "Authorization did not complete" unless completed.ok?
+# Authenticated generated calls can now use the selected token.
+```
+
+Each attempt owns fresh cryptographic state and an S256 verifier. It captures
+immutable copies of the issuer defense, endpoints, client, redirect, scopes,
+resource, audience, account context and extra parameters. Managed completion
+requires the handle, owning binding and full callback URL; it rejects duplicate
+fields, malformed escapes, redirect or issuer mismatches, and replay before a
+token request. Registered redirect text must match exactly, including any
+registered query values. HTTP(S) redirects need a host; qualified absolute app
+schemes are supported. Endpoint and extra parameters cannot override protected
+OAuth fields. Descriptor or credential changes invalidate captured work.
+
+`IssuerDefense.distinct_redirect(qualification)` is an explicit alternative for
+an application that has qualified a redirect unique to that issuer/client.
+The qualification is an application assertion; the runtime cannot establish
+provider support or discover issuer metadata. An invalid callback or binding
+leaves an otherwise valid attempt available; a validated denial consumes it.
+Cancel with `cancel_authorization(attempt_handle: ..., session_binding: ...)`.
+Attempts expire after ten minutes of monotonic time. One owned expiry thread per
+active client releases idle attempts and exits when there are no live deadlines.
+Cancel attempts and call `logout` when their owning session ends.
+
+One client admits at most 32 attempts and 32 active token/read/refresh/cleanup
+owners, including waiting refresh followers. An in-flight attempt retains its
+slot through synchronous transport/store settlement after cancellation or expiry.
+There are at most 32 captured authorization-code scheme names; changing the set
+requires a new client. Captured configuration is limited to 32 KiB of UTF-8 text,
+with at most 64 scopes and 64 extra fields. A callback is limited to 16 KiB and
+64 fields. Limits are checked before collection copies and URL decoding. Ruby
+objects, URL/form encoding and parser copies add overhead beyond those budgets.
+
+Code and refresh responses default to 64 KiB. Set the positive safe integer
+`max_oauth_token_response_bytes` client option for a provider needing a different
+finite cap. Each stored token string and metadata string is bounded separately
+by that cap, so retaining a previous refresh token does not reduce the new access
+token allowance. Token bodies, HTTP decoding and JSON parsing can allocate more
+than the accepted byte cap. The monotonic token job deadline covers admitted
+reads, dispatch and final store predicates. A custom synchronous hook that
+ignores its deadline may block its owner until it settles; it cannot authorize
+a late token send or final mutation after a known expired deadline.
+
+`refresh` and automatic refresh share fenced work. `logout` fences the local
+generation before cleanup, invalidates pending attempts, and deselects stored
+credentials even if cleanup fails or has no admission slot. A separate mutation
+epoch prevents older refresh success or rejection from replacing or deleting a
+newer login, even when token strings are identical. Independent login attempts
+remain usable; the last successfully committed completion selects credentials.
+A cancel/logout winning the final pre-dispatch gate sends nothing. After that
+gate a request may reach the provider; persistence remains fenced. Logout does
+not revoke provider tokens or promise physical zeroization of Ruby strings.
+
+The default `MemoryTokenStore` supplies atomic `set_if_current(scheme, token)`
+and `delete_if_current(scheme)` methods. A custom managed store must implement
+both, yield its current `StoredToken` to the supplied predicate **exactly once**
+at the final serialized mutation, and commit without an intervening wait. The
+predicate may advance a session epoch: speculative checks, retries, or calling
+it before an asynchronous operation are invalid. Return `true` only after the
+mutation commits. If a write fails after the predicate, preserve the old token;
+older refresh work may be conservatively invalidated. No store or application
+callbacks run under the manager lock. A store committing then holding its return
+can still cause the caller to report failure after cancellation or a deadline;
+that does not roll back a completed commit. Shared multi-account adapters need
+their own partitioning and coordination; per-client memory behavior does not
+qualify them.
+
+Migration: primitive URL/code/verifier calls are now explicitly named
+`low_level_authorization_url`, `low_level_exchange_code` and `low_level_refresh`.
+Those escapes leave state, PKCE, issuer, callback validation, replay and store
+coordination to the caller. `pkce` remains a primitive utility; managed begin
+generates its own pair. Direct store `set`/`delete` and low-level methods bypass
+managed epochs and must not be mixed into managed session guarantees. Helpers,
+options and token holders redact `inspect`/`to_s`; URLs, handles, callback URLs
+and bindings are still secrets when explicitly accessed and must not be logged.
+
+## Opening authorization URLs safely
+
+OAuth authorization helpers return URL data; they do not open a browser. Treat
+provider endpoints and returned URLs as untrusted input. Apply your application's
+URL policy and use a browser or native URL API that treats the complete target as
+literal data. Never interpolate the URL into PowerShell, CMD, POSIX shell or other
+command source, and do not pass it to an opener that does so internally.
+
+Scheme validation alone does not prevent command injection: an ordinary HTTPS
+URL can contain shell expansion characters. Managed OAuth endpoint checks are
+protocol validation, not shell escaping. Explicit low-level compatibility helpers
+retain application-owned URL policy, including custom schemes; their results
+need the same safe integration boundary. Do not silently route a rejected URL or
+failed browser launch through a shell fallback.
+
+These boundaries do not qualify third-party openers, custom integrations or real
+provider/listener behavior. Qualify the application's complete launch path on
+each supported platform, including Windows and WSL.
+
 ## Limits
 
-Set `ClientOptions.new(max_response_bytes: ...)` to opt into an ordinary-response byte cap;
-a call option with the same name overrides it. The value must be a positive
-safe integer (at most 9007199254740991); unset keeps the existing unbounded
-behavior. Content-Length is checked before reading, and actual bytes are
-counted even without that header. Overflow closes the body and returns
-`UNEXPECTED_RESPONSE` with code `RESPONSE_TOO_LARGE` and `retryable: never`.
-A mutation may have taken effect: inspect API state before retrying. The cap
-does not limit a successful SSE stream; use its event and collection limits.
+Multipart bodies: a field whose OpenAPI `encoding` entry declares a
+`contentType` is sent with that media type (the first entry without
+wildcards); a file part's own media type wins. The entry's `headers` are not
+sent (the TypeScript, Python and Rust runtimes send those with a fixed
+value), and neither is positional or nested multipart encoding. Unreleased
+0.2.0 only.
+
+The OAuth 2.0 device authorization flow (OpenAPI 3.2 `deviceAuthorization`) is
+not run by the client: configure the scheme with an access token obtained
+through it.
+
+A tagged union with an OpenAPI 3.2 discriminator `defaultMapping` decodes a
+hash whose tag is missing, not a string or claimed by no other variant as the
+default variant's model. Schema validation of the response checks it against
+that variant's own field types. Without `defaultMapping` such a hash is
+returned as it is.
+
+In unreleased 0.2.0, `deadline_ms` (on `ClientOptions` or the call options) sets a total deadline
+for one logical call, separate from the per-attempt `timeout_ms`. It is measured on a monotonic
+clock and covers authentication, idempotency-key reservation, every attempt (each one's
+`timeout_ms` is cut to the time left), retry waits, response bodies and verification; for `pages`,
+`poll` and `run_macro` it covers the whole traversal, poll or macro, and nested work cannot restart
+it. No attempt starts after it expires: the call fails with `code` `DEADLINE_EXCEEDED`, and a
+mutation that was already sent reports `OUTCOME_UNKNOWN`, never a blind replay. A retry wait or
+poll interval that would end after the deadline is not waited for. For `stream` it bounds
+connecting and each reconnect, never an open stream (use `idle_timeout_ms`). With a deadline,
+authentication, a shared OAuth token refresh and idempotency-key reservation run on a helper
+thread that is waited for only until the deadline and never killed, so other callers still get a
+shared refresh's result; it stays bounded by its own timeout, and a custom store that blocks keeps
+its thread busy. Default: no total deadline.
+
+In unreleased 0.2.0, ordinary buffered responses default to **4 MiB (4,194,304 bytes) per response**.
+Set `ClientOptions.new(max_response_bytes: ...)` to choose a finite client cap; the call option with the same
+native name overrides it. Omitted/null values inherit the default or client cap,
+not an unlimited mode. Values must be positive safe integers (at most
+9007199254740991), validated before authentication, storage and preview effects.
+This covers ordinary success/error bodies, server previews, each page and each
+verification read. A page cap does not bound collecting many pages.
+
+Content-Length can reject an oversized representation early; actual delivered
+bytes are counted even without it. HEAD/204/205/304 metadata alone does not
+consume the budget, but any body bytes a transport delivers are still counted.
+Overflow closes the owned body and returns `UNEXPECTED_RESPONSE`, code
+`RESPONSE_TOO_LARGE`, with `retryable: never`. A mutation may have taken effect:
+inspect API state before retrying. The cap is separate from OAuth token-response
+and successful SSE event/collection budgets.
+
+The default HTTP stack supplies decoded bytes when it decompresses a response.
+The cap limits accepted body bytes; parsers, copies and HTTP decoders can allocate
+more. Custom transports must stream nonempty bodies and honor cancellation;
+their own buffering, decoding and settlement behavior need separate qualification.
+
+Schema `min_length`/`max_length` count Unicode code points (a surrogate pair is one, a lone
+surrogate is one), as JSON Schema does. A schema `pattern` is an ECMAScript expression run on
+Onigmo. One Onigmo cannot compile is accepted and reported through `on_diagnostic` as
+`PATTERN_UNCHECKED` (path, pattern and reason, never the value; once per path and pattern per
+call). Ruby matching has no time or length limit. Calling `Schema#validate` directly is silent unless
+you pass a notes array.
 
 The runtime is synchronous and opens a new HTTP connection for each
 attempt; it does not pool persistent connections.

data/lib/tungsten/runtime/auth.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # SPDX-License-Identifier: Apache-2.0
 
+require "ipaddr"
+
 module Tungsten
   module Runtime
     # Auth resolution: an operation's security is an OR of AND-sets of
@@ -9,6 +11,36 @@ module Tungsten
     # `satisfies` list when every part it needs for this request is
     # configured.
     class ClientCore
+      INSECURE_HTTP_AUTH = "Refusing to send credentials over non-loopback HTTP. Use HTTPS, or set ClientOptions.allow_insecure_http = true for intentional insecure transport. Nothing was sent."
+
+      def credential_header?(name, preserved_idempotency = false)
+        (!preserved_idempotency && Util.looks_sensitive?(name)) ||
+          %w[authorization proxy-authorization cookie].include?(name.downcase) ||
+          Array(@api["auth"]).any? do |scheme|
+            (scheme["kind"] == "api_key" && scheme["in"] == "header" && scheme["wire"].to_s.casecmp?(name)) ||
+              (scheme["kind"] == "composite" && Array(scheme["parts"]).any? do |part|
+                part["kind"] == "header" && part["from_config"].to_s.empty? && part["name"].to_s.casecmp?(name)
+              end)
+          end
+      end
+
+      def insecure_http?(url)
+        return false if @allow_insecure_http
+
+        parsed = URI.parse(url.to_s)
+        host = parsed.hostname.to_s.downcase
+        return false if parsed.scheme&.downcase != "http" || %w[localhost localhost.].include?(host)
+
+        begin
+          ip = IPAddr.new(host)
+          loopback = ip.ipv4? ? (ip.to_i >> 24) == 127 : ip.to_i == 1
+          !loopback
+        rescue IPAddr::InvalidAddressError
+          true
+        end
+      rescue URI::InvalidURIError
+        false
+      end
       # The headers, cookies and query parameters credentials add.
       AuthPlan = Struct.new(:headers, :cookies, :query) do
         def self.empty = new([], [], [])
@@ -23,7 +55,7 @@ module Tungsten
 
       private
 
-      def safe_method?(method) = %w[GET HEAD OPTIONS TRACE].include?(method)
+      def safe_method?(method) = %w[GET HEAD OPTIONS TRACE QUERY].include?(method)
 
       def composite_key(part)
         case part["kind"]
@@ -212,7 +244,7 @@ module Tungsten
       end
 
       # The credentials for an operation.
-      def resolve_auth(op, method)
+      def resolve_auth(op, method, credential_error = nil)
         empty = AuthResult.new(AuthPlan.empty, Util::Secrets.new, nil, nil)
         return empty if op.security.empty?
 
@@ -232,6 +264,7 @@ module Tungsten
             existing ? existing[1] = sat : sats << [key, sat]
           end
           if missing.empty?
+            return AuthResult.new(nil, nil, nil, credential_error) if !sats.empty? && credential_error
             out = AuthResult.new(AuthPlan.empty, Util::Secrets.new, nil, nil)
             sats.each do |_, sat|
               problem = apply(sat, out)