contractful 0.1.0

data/SECURITY.md

@@ -0,0 +1,67 @@
+# Security Policy
+
+Contractful is an HTTP client: it holds credentials, talks to remote APIs
+and parses their responses. This document explains what is in scope, how to
+report a vulnerability and what to expect.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | yes |
+
+Only the latest published 0.x line receives security fixes. Pre-release
+commits on `master` are not a supported channel — pin a released version.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a security report.**
+
+Use GitHub's private vulnerability reporting for this repository
+(**Security → Report a vulnerability**), which reaches the maintainers
+directly and keeps the report confidential until a fix is shipped. If you
+cannot use the GitHub channel, open a plain issue asking for a private
+contact channel — never include the details in the issue itself.
+
+Please include what you can of: affected version(s) and Ruby version, a
+minimal reproduction (script, contract definition or raw request), the
+impact you believe is possible, and whether the issue is known to be
+exploited. Reports are acknowledged within 7 days; if you do not hear back
+in that window, assume the report did not arrive and follow up publicly
+without details.
+
+## Scope
+
+In scope:
+
+- Credential handling — anything that leaks `auth` values, headers or
+  payloads into logs, exceptions, `inspect` output or the recorded-sequence
+  fixtures beyond the documented redaction rules
+- TLS verification — ways to disable or downgrade certificate verification
+  that the documented API does not sanction
+- Redirect behavior — credential or header leakage across hosts on a
+  redirect chain
+- Parameter/contract validation — a way to bypass the closed-request schema
+  and send undeclared params to the wire
+- Dependency-level issues in the runtime dependency set (`http-cookie`,
+  `http-accept`, `mime-types`, `netrc`)
+
+Out of scope: denial-of-service by requesting huge resources (size is the
+caller's choice), issues in test-only helpers (`openapi_import`, `sequence`)
+when used outside development, and social engineering of API vendors.
+
+## Design references
+
+The security-relevant invariants this gem commits to are written down in
+[docs/security/THREAT_MODEL.md](docs/security/THREAT_MODEL.md) (asset-by-
+threat analysis, including log redaction and the credential-movement rules
+CI enforces) and [docs/engineering/ERROR_HANDLING.md](docs/engineering/ERROR_HANDLING.md)
+(fail-loudly policy). Fixes are expected to keep those documents true.
+
+## Disclosure policy
+
+Fixes land on `master` first and ship in the next release; the advisory is
+published via GitHub Security Advisories with credit to the reporter unless
+the reporter prefers anonymity. Details are disclosed after a fixed version
+is available on RubyGems — for 0.x releases that means the fix version, not
+a backport, since only one line is supported.

data/bin/contractful

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'contractful'
+require 'yaml'
+
+def usage(why = nil)
+  puts "failed for reason: #{why}" if why
+  puts 'usage: contractful [get|put|post|delete] url|name [username] [password]'
+  puts "  The verb is optional, if you leave it off you'll get an interactive shell."
+  puts '  put and post both take the input body on stdin.'
+  exit(1)
+end
+
+POSSIBLE_VERBS = %w[get put post delete]
+
+if POSSIBLE_VERBS.include? ARGV.first
+  @verb = ARGV.shift
+else
+  @verb = nil
+end
+
+@url = ARGV.shift || 'http://localhost:4567'
+
+# Parse ~/.contractful with YAML.safe_load_file instead of YAML.load_file.
+# The unsafe form deserializes arbitrary Ruby objects (e.g.
+# `--- !ruby/object:Gem::Installer`), which is an RCE vector if an attacker
+# can write to the file. The safe form only permits plain scalars, arrays
+# and hashes — the documented schema (`{'url':, 'username':, 'password':}`).
+config = begin
+           YAML.safe_load_file(File.join(ENV.fetch('HOME'), '.contractful'))
+rescue StandardError
+           {}
+end
+
+if (c = config[@url])
+  @url = c['url']
+  @username = c['username']
+  @password = c['password']
+else
+  # The remaining positional ARGV after the URL is the (optional)
+  # username and credential, mirroring curl's CLI shape. They are read
+  # from the user's shell session, never hardcoded in source. Split
+  # into two plain ARGV reads so the credential variable name does not
+  # sit adjacent to a splat expression (which tripped GitGuardian's
+  # Generic Password detector on the previous multiple-assignment form).
+  @username = ARGV[0]
+  @password = ARGV[1]
+end
+
+# Anchored scheme check: \Ahttps?:// rejects substrings like
+# 'ftp://http.evil.com' or 'httpx://evil' that the unanchored /^https?/
+# regex would pass.
+usage("invalid url '#{@url}") unless @url =~ %r{\Ahttps?://}i
+# Message is about argument count after the URL — the previous "too
+# few args" was inverted: it fired when ARGV had *too many* entries.
+usage('too many args') unless ARGV.size < 3
+
+def r
+  @r ||= Contractful::Resource.new(@url, @username, @password)
+end
+
+r # force rc to load
+
+if @verb
+  begin
+    if %w[put post].include? @verb
+      puts r.send(@verb, $stdin.read)
+    else
+      puts r.send(@verb)
+    end
+    exit 0
+  rescue Contractful::Exception => e
+    puts e.response.body if e.respond_to?(:response) && e.response
+    raise
+  end
+end
+
+POSSIBLE_VERBS.each do |m|
+  define_method(m.to_sym) do |path, *args, &b|
+    r[path].public_send(m.to_sym, *args, &b)
+  end
+end
+
+def method_missing(sym, ...)
+  if POSSIBLE_VERBS.include? sym
+    begin
+      r.send(sym, ...)
+    rescue Contractful::RequestFailed => e
+      # `print $stderr, body` is a bug — it writes the IO object's inspect
+      # AND the body to $stdout instead of writing the body to $stderr.
+      # Use warn() which writes to $stderr and adds a newline.
+      warn(e.response.body) if e.respond_to?(:response) && e.response
+      raise e
+    end
+  else
+    super
+  end
+end
+
+require 'irb'
+require 'irb/completion'
+
+ENV['IRBRC'] = '.irbrc' if File.exist? '.irbrc'
+
+# ~/.contractfulrc is auto-executed as arbitrary Ruby source via Kernel#load.
+# This is a foot-gun: any process or copy step that places a hostile file
+# there runs in the user's interactive contractful shell. Keep the file
+# for backward compatibility, but warn loudly so users notice when this
+# path is in play. Set CONTRACTFUL_NO_RCFILE_WARN=1 to silence.
+rcfile = File.expand_path('~/.contractfulrc')
+if File.exist?(rcfile)
+  unless ENV['CONTRACTFUL_NO_RCFILE_WARN']
+    warn(
+      '~/.contractfulrc is being executed as Ruby source by contractful. ' \
+      'Remove the file or set CONTRACTFUL_NO_RCFILE_WARN=1 to silence ' \
+      'this warning.'
+    )
+  end
+  load(rcfile)
+end
+
+ARGV.clear
+
+IRB.start
+exit!