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/pglombardo/PasswordPusher 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.

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits

_{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 pglombardo/PasswordPusher repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pglombardo/PasswordPusher.

What it runs against: a local clone of pglombardo/PasswordPusher — 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 pglombardo/PasswordPusher | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pglombardo/PasswordPusher. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pglombardo/PasswordPusher.git
#   cd PasswordPusher
#
# 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 pglombardo/PasswordPusher and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

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

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "app/assets/config/manifest.js" \\
  && ok "app/assets/config/manifest.js" \\
  || miss "missing critical file: app/assets/config/manifest.js"
test -f ".github/workflows/ruby-tests.yml" \\
  && ok ".github/workflows/ruby-tests.yml" \\
  || miss "missing critical file: .github/workflows/ruby-tests.yml"
test -f "Configuration.md" \\
  && ok "Configuration.md" \\
  || miss "missing critical file: Configuration.md"
test -f "UPGRADE-2.0.md" \\
  && ok "UPGRADE-2.0.md" \\
  || miss "missing critical file: UPGRADE-2.0.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/pglombardo/PasswordPusher"
  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).

Password Pusher is a Rails-based web application for securely sharing sensitive data (passwords, text, files, URLs) through self-destructing, expiring links. Core capability: recipients get one-time-view links that automatically expire after configurable view counts or time duration, with optional passphrase protection, AES encryption at rest, and full audit logging of who accessed what and when. Monolithic Rails application under /app with standard structure: app/assets for frontend (HTML, JS, CSS/SCSS), app/controllers for business logic, app/models for domain entities (passwords, audit logs, users). Configuration via environment variables and .env files; Docker deployment supported via Dockerfile and docker-compose.yml in .devcontainer. Database migrations and schema managed through Rails conventions.

Security-conscious teams and individuals who need to share secrets without email/chat exposure; sysadmins and DevOps engineers deploying self-hosted instances for compliance; organizations requiring audit trails for sensitive data sharing with MFA and role-based access control.

Production-ready and actively maintained. The project has 2K+ GitHub stars, recently released v2.0 with significant refactoring, runs comprehensive CI/CD via GitHub Actions (ruby-tests.yml, brakeman security scanning, dependabot automation), and maintains Docker image with 10K+ pulls. Commit recency and active issue triage indicate healthy ongoing development.

Low-to-moderate risk for self-hosting: single maintainer (pglombardo) creates availability risk, though the codebase is stable and well-tested. Dependency management is active (dependabot automerge enabled), but a Rails monolith with encrypted data means version upgrades require care. The v2.0 migration shows breaking changes were introduced, so check UPGRADE-2.0.md before updating production instances.

v2.0 recently released with significant changes documented in UPGRADE-2.0.md. Active CI/CD workflows running ruby-tests, brakeman security scanning, and dependabot updates. GitHub Actions configured for Docker container builds, release drafting, and notifications. Development uses .devcontainer for standardized local environment setup.

Clone and set up locally: git clone https://github.com/pglombardo/PasswordPusher.git && cd PasswordPusher && bundle install (Ruby/Bundler based on Gemfile). Use devcontainer: open .devcontainer/devcontainer.json in VS Code for containerized dev, or docker-compose -f .devcontainer/docker-compose.yml up. Check .ruby-version for required Ruby version and Configuration.md for env vars.

Daily commands: Development server: rails server (or bundle exec rails s from Procfile.dev). Hot-reload assets with importmap or esbuild. Full stack with docker-compose: docker-compose -f .devcontainer/docker-compose.yml up. Production: Docker image pglombardo/pwpush or Kubernetes via Helm (referenced in workflows). See Procfile for production dyno types.

• Gemfile — Defines all Ruby dependencies including Rails, authentication, encryption, and audit logging—understanding this reveals the tech stack and key libraries.
• app/assets/config/manifest.js — Configures asset pipeline and bundling; critical for understanding how CSS, JS, and images are served in production.
• .github/workflows/ruby-tests.yml — CI/CD pipeline for automated testing—shows how code quality and security are validated before merge.
• Configuration.md — Comprehensive deployment and runtime configuration guide; essential for understanding environment variables and feature flags.
• UPGRADE-2.0.md — Migration guide for v2.0; mandatory reading for contributors working with existing self-hosted instances.
• .rubocop.yml — Ruby code style and linting rules; enforces consistency across all contributions.
• .erb_lint.yml — HTML/ERB template linting rules; ensures view layer consistency and accessibility.

Add a New Secret Type (e.g., File Sharing)

1. Create a new model inheriting from Secret base class in app/models/ (app/models/file_secret.rb)
2. Add database migration in db/migrate/ with file storage columns and encryption setup (db/migrate/[timestamp]_create_file_secrets.rb)
3. Add controller actions (create, show, download) in app/controllers/ (app/controllers/file_secrets_controller.rb)
4. Create view template for file upload form in app/views/file_secrets/ (app/views/file_secrets/new.html.erb)
5. Add integration test validating encryption, expiration, and deletion in spec/ (spec/requests/file_secrets_spec.rb)
6. Update routing in config/routes.rb to mount new resource (config/routes.rb)

Add a New Language Translation

1. Create new locale YAML file following Rails i18n convention (config/locales/es.yml)
2. Copy English locale keys (config/locales/en.yml) and translate values to target language (config/locales/[language].yml)
3. Register locale in Rails config and add to language switcher helper (config/application.rb)
4. Update view templates to use t() helper for all user-facing strings (app/views/layouts/application.html.erb)
5. Add language option to user preferences and test locale switching (spec/features/language_switching_spec.rb)

Add a New Audit Log Event Type

1. Extend AuditLog model with new event enum value in app/models/ (app/models/audit_log.rb)
2. Create an auditable service that logs events (e.g., SecretViewedEvent) (app/services/audit_events/secret_viewed_event.rb)
3. Integrate audit service call into relevant controller action or background job (app/controllers/secrets_controller.rb)
4. Add view column and formatting helper for new event in audit log index/show (app/views/audit_logs/index.html.erb)
5. Write test covering event creation, storage, and display (spec/services/audit_events/secret_viewed_event_spec.rb)

Add a New Theme

1. Create new CSS file in app/assets/stylesheets/themes/ following Bootswatch pattern (app/assets/stylesheets/themes/my_theme.css)
2. Define SCSS variables for colors, fonts, and spacing in root variables (app/assets/stylesheets/themes/my_theme.css)
3. Add theme option to user preferences model and database migration (app/models/user.rb)
4. Update application layout to conditionally load theme CSS based on user preference (app/views/layouts/application.html.erb)
5. Add theme thumbnail image and listing to theme selector UI (app/assets/images/themes/my_theme_preview.png)

• Ruby on Rails — Monolithic web framework providing rapid development of CRUD endpoints, ORM, asset pipeline, and built-in security (CSRF, SQL injection prevention). Ideal for a single-page secret sharing service with minimal custom infrastructure.
• PostgreSQL — Durable relational database with ACID guarantees; essential for storing encrypted secrets, audit logs, and user data where data loss is unacceptable. Supports JSON fields for flexible audit metadata.
• Docker & Docker Compose — Containerization ensures consistent dev-to-prod parity. Docker Compose simplifies local setup with Redis, PostgreSQL

Database migrations are mandatory on deploy (UPGRADE-2.0.md hints at schema changes in v2). Rails credentials/master.key required for decryption at runtime; set via Rails credentials or ENV vars. Background job workers (Procfile.dev implies Sidekiq or similar) needed for scheduled expiry deletion—background jobs not running means expired secrets won't auto-delete. ERB linting enforced (.erb_lint.yml), so template changes may fail CI without lint fixes. Encryption keys must be rotated carefully; old encrypted records become inaccessible if keys change without migration.

• End-to-end encryption with passphrase-derived keys — Password Pusher stores encrypted secrets; understanding AES encryption, salt/IV, and how passphrases derive keys is essential to grasping why secrets are safe at rest
• Token bucket / view-count expiry patterns — Core feature: links expire after N views or T seconds; implementing this cleanly requires atomic view counters and scheduled cleanup jobs
• Audit logging & non-repudiation — Password Pusher logs access with IP/user details for compliance; understanding immutable audit trails and privacy trade-offs is critical for security-focused projects
• Rails credentials & key derivation — Secrets are encrypted using Rails master.key; the devcontainer and production setup both hinge on secure key management and injection
• Soft delete & data retention policies — Expired secrets must be securely wiped, not just marked deleted; GDPR/compliance implications of data retention and scheduled purge jobs
• Two-factor authentication (TOTP) — Optional MFA support with PWP__REQUIRE_MFA=true suggests TOTP (time-based one-time passwords) integration; understanding RFC 6238 is useful for auth features
• API versioning & backward compatibility — v2.0 introduced breaking changes; the project ships with JSON API for integrations; version negotiation and migration paths are important for ecosystem health

• owasp/SecretSharing — OWASP-endorsed secret-sharing reference implementation; understand threat model alignment
• m1guelpf/plumbum — Lightweight self-destructing secret URL alternative; compare minimalist approach to Password Pusher's feature-rich Rails stack
• spicetify/spicetify-cli — Not directly related but demonstrates Go CLI tooling that integrates with Password Pusher API (tools & extensions mentioned in README)
• dani-garcia/vaultwarden — Self-hostable secrets management; potential integration point for teams needing Password Pusher + password vault together
• pglombardo/pwpush-cli — Official CLI companion tool for Password Pusher API; reference for how to consume the JSON API

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 integration tests for audit logging functionality

The repo emphasizes 'full audit logs' as a core feature in the README, but there's no clear audit log test coverage visible in the file structure. Creating integration tests would ensure the audit trail feature works correctly across password views, deletions, and expirations—critical for a security-focused tool.

• [ ] Review existing test files in app/test or spec/ directory (not shown in file list)
• [ ] Create integration test file for audit log creation on password creation/view/expiration
• [ ] Add tests verifying audit log entries are immutable and cannot be deleted
• [ ] Test audit log filtering and pagination if those features exist
• [ ] Add test for proper timestamp and IP/user agent logging on each access

Implement GitHub Action workflow for security scanning (SAST/dependency check)

While brakeman.yml exists for Rails security linting, there's no dedicated workflow for container/dependency scanning in the visible workflows. Given the sensitive nature of password handling, adding automated security scanning for Docker images and Ruby dependencies would significantly improve the security posture.

• [ ] Create new workflow file .github/workflows/security-scan.yml
• [ ] Add Trivy or similar tool to scan Docker container images (referenced in docker-containers.yml workflow)
• [ ] Integrate Dependabot alerts with automated scanning in the workflow
• [ ] Add SBOM (Software Bill of Materials) generation for transparency
• [ ] Link results to security advisories in SECURITY.md

Add API documentation and OpenAPI/Swagger spec generation

The repo structure shows a Rails app with API capabilities (inferred from 'securely share' and audit tracking), but no visible OpenAPI spec or API documentation in the file list. Documenting the REST API with Swagger/OpenAPI would enable better integrations and lower the barrier for contributors building on the API.

• [ ] Add 'rswag' or 'grape-swagger' gem to Gemfile for OpenAPI spec generation
• [ ] Create spec/requests/ directory with RSpec API documentation tests (following Rails conventions)
• [ ] Generate OpenAPI schema covering password creation, retrieval, and audit log endpoints
• [ ] Add generated spec to docs/ or public/ directory for serving via /api/docs endpoint
• [ ] Document authentication, rate limiting, and request/response examples in the spec

• Add missing test coverage for app/models/audit_log.rb (mentioned in file structure but no tests visible in CI config details); implement scenarios for audit retention policies
• Extend internationalization: the README claims 31 languages but config/locales/ directory structure not fully visible; audit missing locale files and add Spanish/French/German locale completeness
• Improve Docker documentation: docker-compose.yml exists but no Compose quick-start guide in README; add 'docker-compose up' one-liner and environment variable template for first-time users

PasswordPusher demonstrates good security awareness with Brakeman integration, Dependabot automation, and a responsible disclosure policy. However, without visibility into application code, dependency versions, and configuration files, comprehensive security assessment is limited. Key concerns include: lack of visible security header configuration, potential credential exposure in configuration, Docker

• High · Missing Security Headers Configuration — config/ directory (not visible in provided structure). No visible security headers configuration (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security) in the provided file structure. Rails applications should implement robust HTTP security headers. Fix: Configure security headers middleware or use gems like 'secure_headers' to set CSP, HSTS, X-Frame-Options, X-Content-Type-Options, and other protective headers.
• Medium · Dependency Management - No Gemfile.lock Content Provided — Gemfile, Gemfile.lock. While Gemfile and Gemfile.lock are present, the content is not provided for analysis. Known vulnerable gem versions cannot be identified. Rails applications frequently have dependencies with CVEs. Fix: Regularly run 'bundle audit' or use Dependabot (which is configured) to identify and patch vulnerable dependencies. Pin gem versions and monitor security advisories.
• Medium · Brakeman Static Analysis - Limited Automation Evidence — .github/workflows/brakeman.yml. While brakeman.yml workflow is configured, there's no evidence of continuous security scanning results being enforced or blocking merges. This is a security tool that detects Rails-specific vulnerabilities. Fix: Ensure Brakeman results fail CI/CD pipelines for critical/high severity issues. Configure to block PRs if vulnerabilities are found.
• Medium · Sensitive Data in Version Control — .gitignore, config/ directory. While .gitignore is present, there's a risk of credential leakage if environment-specific secrets are not properly excluded. Configuration files like config/database.yml, config/secrets.yml, or .env files must be ignored. Fix: Verify .gitignore properly excludes: *.key, .pem, .env, config/secrets.yml, config/database.yml, config/credentials.yml.enc keys, and any API tokens or credentials.
• Medium · Docker Image Security — .dockerignore, .devcontainer/docker-compose.yml, Dockerfile (not provided). Docker containers (.dockerignore, docker-compose.yml visible) are part of the infrastructure. Without viewing the Dockerfile, potential issues could include: running as root, using base images without security updates, or exposing sensitive build args. Fix: Use minimal base images (alpine/distroless), scan images with Trivy/Snyk, run containers as non-root user, and implement image signing/verification.
• Low · Public Information Disclosure — SECURITY.md. Security.md file is publicly visible with reporting instructions. While good practice, it confirms this is a security-sensitive application and may attract security researchers. Fix: This is actually a best practice. Continue maintaining clear security reporting guidelines and monitor the provided vulnerability reporting channel.
• Medium · Password/Credential Expiration Feature - Implementation Verification Needed — app/ (models, controllers - not provided). The application's core feature is managing password expiration and deletion. No code visibility provided to verify: secure deletion (overwriting memory), proper encryption at rest, and secure transmission (HTTPS enforcement). Fix: Verify: 1) HTTPS only enforcement 2) Encryption of sensitive data at rest 3) Secure deletion (not just soft deletes) 4) No logging of sensitive payloads 5) CSRF protection enabled
• Medium · Audit Logging - Data Retention Risk — app/ (audit log implementation - not provided). Application maintains audit logs of who, what, and when. Risk exists if audit logs contain sensitive data or are retained indefinitely without proper access controls. Fix: Ensure: 1) Audit logs don't contain payload data 2) Logs are encrypted 3) Access is role-based and audited 4) Log retention policies are defined 5) Logs are immutable

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.