If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/curtis0x/fake-s3 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 3y ago

• 31+ active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live curtis0x/fake-s3 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/curtis0x/fake-s3.

What it runs against: a local clone of curtis0x/fake-s3 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in curtis0x/fake-s3 | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | Last commit ≤ 1152 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of curtis0x/fake-s3. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/curtis0x/fake-s3.git
#   cd fake-s3
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of curtis0x/fake-s3 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "curtis0x/fake-s3(\\.git)?\\b" \\
  && ok "origin remote is curtis0x/fake-s3" \\
  || miss "origin remote is not curtis0x/fake-s3 (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1152 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1122d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/curtis0x/fake-s3"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Fake S3 is a lightweight Ruby server that implements the Amazon S3 API locally for development and testing, eliminating the need for actual AWS calls. It simulates core S3 operations (PUT, GET, LIST, COPY, MBUCKET) with minimal dependencies and a file-system backend, allowing developers to test S3 integration code in sandbox environments without network calls or AWS costs. Monolithic Ruby gem structure: lib/fakes3/ contains core logic split by concern (bucket.rb, file_store.rb, server.rb, xml_adapter.rb for request parsing), bin/fakes3 provides CLI entry point, test/ contains integration tests against real S3 clients. Static assets (logo.png, button.svg) are served for documentation/branding.

Backend engineers and DevOps teams who need to test S3-dependent applications (Ruby, Python, or any S3-compatible client) in CI/CD pipelines or local development without AWS credentials or network access. Also useful for teams running integration tests that need deterministic S3 behavior.

Moderately mature: the project has a stable Ruby implementation with test coverage across multiple S3 clients (aws-sdk, boto, s3cmd, right_aws), uses semantic versioning (fakes3.gemspec), and has CI infrastructure (GitHub Actions templates visible in .github/). However, licensing requirement (Super Source key) and last-commit age are not visible in provided data, making full maturity assessment incomplete—likely stable for development/testing use cases.

Low-to-moderate risk for testing use only: the project is deliberately scoped as a development tool, not production-grade, so incomplete S3 API coverage is expected and documented. Key risk is single-maintainer dependency (curtis0x organization); no visible dependency security auditing in Gemfile.lock context. The licensing requirement (Super Source) adds friction for casual contributors but ensures sustainability.

Unable to determine from provided file list alone—no recent commit timestamps, open issues, or PR listings visible. Check GitHub Actions workflow files in .github/ and recent commits on main branch for active development signals.

Clone and install:

git clone https://github.com/curtis0x/fake-s3.git
cd fake-s3
bundle install

Run the server:

bundle exec fakes3 -r /tmp/fakes3_root -p 4567 --license YOUR_LICENSE_KEY

(License key obtainable free from https://supso.org/projects/fake-s3 for individuals/small companies)

Daily commands: Development:

bundle exec rake test        # Run full test suite across s3cmd, boto, aws-sdk
bundle exec fakes3 -r . -p 4567 --license KEY  # Start server on port 4567

Docker:

docker build -t fakes3 .
docker run -p 4567:4567 -v /data:/mnt/fakes3_root fakes3 -r /mnt/fakes3_root -p 4567 --license KEY

• lib/fakes3/server.rb: Core HTTP request router and handler logic—all S3 operations are dispatched here
• lib/fakes3/bucket.rb: Models S3 bucket abstraction and object listing/filtering logic
• lib/fakes3/file_store.rb: Filesystem persistence layer—handles actual file I/O and object storage
• lib/fakes3/xml_adapter.rb: S3 XML response serialization—critical for client compatibility
• lib/fakes3/xml_parser.rb: S3 request body parsing (e.g., multipart form data, versioning configs)
• test/aws_sdk_commands_test.rb: Primary integration test suite for AWS SDK compatibility—run this to validate changes
• bin/fakes3: CLI entry point and argument parsing—defines server startup interface

Adding S3 operations: extend lib/fakes3/server.rb (HTTP route handlers) and lib/fakes3/bucket_query.rb (query parameter parsing). Fixing client compatibility: add test case to test/aws_sdk_commands_test.rb or test/s3cmd_test.rb, then update lib/fakes3/xml_adapter.rb response formatting. Storage logic: modify lib/fakes3/file_store.rb and lib/fakes3/s3_object.rb for metadata/persistence changes.

Licensing requirement: --license flag is mandatory on startup (enforced in lib/fakes3/cli.rb); server will not start without valid Super Source key. File permissions: filesystem storage requires write access to specified root directory (-r flag); ensure process user has permissions. Rate limiting: rate_limitable_file.rb may have hardcoded limits—check if your test workload exceeds them. XML parsing strictness: some S3 clients send non-standard request formats; xml_parser.rb may reject them silently.

• XML Response Serialization for REST APIs — Fake S3 must serialize objects, bucket listings, and error responses as XML matching AWS S3's exact format; xml_adapter.rb is the critical contract point for client compatibility
• Virtual-hosted-style vs. Path-style S3 URIs — Clients can address buckets as either bucket.s3.amazonaws.com/key or s3.amazonaws.com/bucket/key; server.rb must route both formats correctly
• Multipart Upload and Form Data Parsing — S3 PUT operations use multipart/form-data encoding; xml_parser.rb must handle this efficiently without third-party HTTP libs to keep dependencies minimal
• Rate Limiting and Bandwidth Throttling — rate_limitable_file.rb simulates S3 bandwidth caps for realistic testing; necessary to catch client-side timeout/retry bugs before production
• Filesystem-backed Object Storage — file_store.rb maps S3 object hierarchy to directory trees; critical to understand path traversal prevention and metadata persistence patterns
• S3 ETag Generation (MD5 or CRC32C) — Clients use ETags for cache validation and multipart upload verification; s3_object.rb must generate ETags matching S3's algorithm to avoid spurious 412 Precondition Failed errors
• Bucket Query Parameters and Filtering — bucket_query.rb parses LIST parameters (prefix, delimiter, marker, max-keys) to implement prefix-based partitioning; core for efficient object enumeration in large buckets

• localstack/localstack — Full AWS service mock (including S3) in Docker; heavier but covers entire AWS API surface vs. Fake S3's lightweight single-service focus
• adobe/S3Mock — Java-based S3 mock with Testcontainers support; alternative for JVM-based projects
• moto/moto — Python mock for AWS services including S3; closer feature parity to Fake S3 but in Python ecosystem (note: Fake S3 has test/boto_test.py using moto-style patterns)
• jubos/fake-s3-ruby-sdk — Potential companion repo for AWS Ruby SDK integration examples and monkey-patching patterns
• aws/aws-sdk-ruby — Official AWS Ruby SDK that Fake S3 mocks; check test/aws_sdk_commands_test.rb for integration patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for S3 multipart upload operations

The test suite (test/*.rb) has tests for basic S3 commands, but multipart upload is a critical S3 feature used by the AWS SDK for large files. The existing tests (aws_sdk_v2_commands_test.rb, s3_commands_test.rb) don't appear to cover the complete multipart upload lifecycle (InitiateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload). This is a high-value gap since multipart operations are commonly used in production S3 workflows.

• [ ] Create test/multipart_upload_test.rb with tests for InitiateMultipartUpload, UploadPart, CompleteMultipartUpload, and AbortMultipartUpload
• [ ] Test edge cases like uploading parts out of order, completing without all parts, and aborting mid-upload
• [ ] Add assertions for proper XML response format and ETag handling in multipart scenarios
• [ ] Verify integration with existing file_store.rb and s3_object.rb classes to ensure multipart state is persisted correctly

Implement request signing/authentication validation in server.rb

The README mentions a license key requirement (--license YOUR_LICENSE_KEY) but lib/fakes3/server.rb and lib/fakes3/cli.rb don't show any actual license validation or AWS Signature request verification. Adding proper AWS Signature v4 validation would make Fake S3 more realistic for testing authentication flows and prevent accidental use in production. This is a concrete security/testing improvement.

• [ ] Add signature validation logic to lib/fakes3/server.rb that verifies AWS Signature v4 headers (Authorization, X-Amz-Date, etc.)
• [ ] Create a new file lib/fakes3/signature_validator.rb to handle signature verification against a configurable secret key
• [ ] Update lib/fakes3/cli.rb to accept and pass through AWS secret key from the license or config
• [ ] Add test/signature_validation_test.rb with test cases for valid/invalid signatures and missing auth headers

Add support and tests for S3 bucket versioning and lifecycle policies

The lib/fakes3/bucket.rb and lib/fakes3/bucket_query.rb files handle basic bucket operations, but versioning and lifecycle policies are important S3 features that many applications rely on. The test files don't contain any tests for GetBucketVersioning, PutBucketVersioning, or lifecycle operations. Adding these features would significantly improve test coverage for real-world S3 usage patterns.

• [ ] Extend lib/fakes3/bucket.rb to support version_id tracking and storage of multiple object versions
• [ ] Implement GetBucketVersioning and PutBucketVersioning handlers in lib/fakes3/server.rb
• [ ] Add basic lifecycle policy storage to lib/fakes3/bucket.rb (parse and store lifecycle XML without enforcement)
• [ ] Create test/bucket_versioning_test.rb with tests for enabling versioning, retrieving multiple versions, and listing versions via GetObjectVersions

• Add test coverage for lib/fakes3/sorted_object_list.rb—currently no dedicated test file visible; implement tests for LIST operation ordering edge cases (lexicographic vs. timestamp sorting).
• Implement S3 CORS (Cross-Origin Resource Sharing) OPTIONS request handling in lib/fakes3/server.rb; check test/s3_commands_test.rb for existing CORS tests and add missing route handler.
• Document supported S3 operations in README.md with matrix of (operation, supported_parameters, known_limitations); currently only mentions 'put, get, list, copy, make bucket' without specifics.

• Critical · Outdated Alpine Base Image with Known Vulnerabilities — Dockerfile (line 1: FROM alpine:3.4). Dockerfile uses Alpine 3.4, which was released in 2016 and is severely outdated. This image contains numerous unpatched security vulnerabilities affecting core system libraries (openssl, libc, etc.). Alpine 3.4 reached end-of-life years ago and receives no security updates. Fix: Update to the latest stable Alpine version (currently 3.19 or 3.20). Review and update all dependencies with 'apk add --no-cache' after the base image update to ensure compatibility.
• High · Outdated Ruby Version — Dockerfile (line 3: RUN apk add --no-cache ... ruby). The Dockerfile installs 'ruby' from Alpine 3.4 repositories, which would be Ruby 2.2.x or earlier. This version is long out of support and contains multiple security vulnerabilities including DoS and arbitrary code execution issues. No security patches are available. Fix: Use a modern Ruby base image or specify an explicit recent Ruby version. Consider using ruby:3.2-alpine or ruby:3.3-alpine as a base image instead of building on Alpine 3.4.
• High · Outdated Python Installation with Vulnerable Dependencies — Dockerfile (line 3: RUN pip install boto s3cmd). The Dockerfile installs 'py-pip' and 'python' from Alpine 3.4, installing outdated versions of Python and pip. The installed dependencies 'boto' and 's3cmd' from this era contain multiple known security vulnerabilities. No security updates are available for these versions. Fix: Update to Python 3.11+ and upgrade boto to boto3, s3cmd to the latest version. Test compatibility before deployment.
• High · Missing License Key Validation — lib/fakes3/cli.rb (inferred), README.md. The README indicates a license key requirement (--license YOUR_LICENSE_KEY), but static analysis suggests minimal validation of this key. No validation logic is apparent in the provided file structure. This could allow unauthorized usage or bypass of licensing requirements. Fix: Implement robust license key validation with cryptographic verification. Consider using signed tokens or contacting an external verification service.
• High · Insecure XML Processing — lib/fakes3/xml_adapter.rb, lib/fakes3/xml_parser.rb. The presence of 'lib/fakes3/xml_adapter.rb' and 'lib/fakes3/xml_parser.rb' suggests XML parsing functionality. Without reviewing the implementation, XML parsers commonly suffer from XXE (XML External Entity) injection attacks if not properly configured, especially in older Ruby versions. Fix: Ensure XML parsers are configured with entity expansion disabled. Use 'Nokogiri' with safe defaults: Nokogiri::XML::Document.parse(input) { |config| config.strict.noent = false }
• Medium · Potential Path Traversal Vulnerability — lib/fakes3/file_store.rb. The 'lib/fakes3/file_store.rb' suggests file system storage operations based on S3 object keys. S3 object keys can contain directory traversal sequences (../, etc.). If not properly validated, this could allow reading/writing files outside the intended bucket directory. Fix: Implement strict path validation to prevent traversal attacks. Use 'File.expand_path' and verify the final path is within the intended bucket directory. Reject keys containing '..' or leading '/'.
• Medium · No HTTPS/TLS Configuration — lib/fakes3/cli.rb, lib/fakes3/server.rb. The fake S3 server appears to run over plain HTTP based on the CLI interface (port specification without SSL options). Development tools often lack SSL/TLS, allowing credentials and data to be transmitted in cleartext if exposed to network traffic. Fix: Add optional TLS support with --ssl, --cert, and --key parameters. At minimum, document that this should only be used in isolated development environments.
• Medium · Missing Input Validation on Bucket/Object Names — undefined. The 'lib/fakes3/bucket.rb' and 'lib/fakes3/s3 Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.