secure-keys 1.1.6 → 1.2.0

data/README.md

@@ -1,140 +1,168 @@
-<div style="display: flex; gap: 10px; padding-bottom: 20px;">
-  <img src="https://img.shields.io/badge/version-1.1.6-cyan" alt="SecureKeys version">
+# Secure Key Generator for iOS Projects
 
+<div style="display: flex; gap: 10px; padding-bottom: 20px;">
+  <img src="https://img.shields.io/badge/version-1.2.0-cyan" alt="SecureKeys version">
   <img src="https://img.shields.io/badge/iOS-^13.0-blue" alt="iOS version 13.0">
-
   <img src="https://img.shields.io/badge/Ruby-^3.3.6-red" alt="Ruby version 3.3.6">
-
 </div>
 
-# Secure Key Generator for iOS projects
-
-Utility to generate a `xcframework` for handling secure keys in iOS projects.
+`secure-keys` is a Ruby CLI that generates a `SecureKeys.xcframework` for iOS apps. It reads secret values from macOS Keychain on local machines or environment variables in CI, encrypts those values with AES-256-GCM, writes a Swift API, builds an XCFramework, and optionally adds that framework to an Xcode target.
 
-### Prerequisites
+## Requirements
 
-- Ruby 3.3.6 or higher
-- iOS 13.0 or higher
-- macOS 11.0 or higher
+- macOS 11.0 or later
+- Ruby 3.3 or later
+- Xcode command line tools
+- iOS 13.0 or later
 
-### Installation
+## Installation
 
-You can install the `SecureKeys` utility using Homebrew using the following command:
+Install with Homebrew:
 
 ```bash
 brew tap derian-cordoba/secure-keys
-
 brew install derian-cordoba/secure-keys/secure-keys
 ```
 
-For more details, you can visit the [homebrew-secure-keys](https://github.com/derian-cordoba/homebrew-secure-keys) repository.
-
-Another way, you can install the `SecureKeys` utility using `gem` command:
+Install with RubyGems:
 
 ```bash
 gem install secure-keys
 ```
 
-If you using `bundler` you can add the `secure-keys` gem to the `Gemfile`:
+Install with Bundler:
 
 ```ruby
 gem 'secure-keys'
 ```
 
-Then, you can install the gem using:
-
 ```bash
 bundle install
 ```
 
-For more information about the gem, you can visit the [secure-keys](https://rubygems.org/gems/secure-keys) page.
+## Quick Start
+
+From an iOS project root:
+
+```bash
+security add-generic-password -a "secure-keys" -s "secure-keys" -w "apiKey,githubToken"
+security add-generic-password -a "secure-keys" -s "apiKey" -w "your-api-key"
+security add-generic-password -a "secure-keys" -s "githubToken" -w "your-github-token"
+
+secure-keys
+```
+
+The command creates `.secure-keys/SecureKeys.xcframework`.
 
-## Usage
+Use the generated framework from Swift:
 
-As first step, you need to determine the keys that you want to use in your iOS project. You can define the keys from Keychain or env variables.
+```swift
+import SecureKeys
 
-The source is determined by the current platform **local or CI / cloud** using the `CI` environment variable.
+let apiKey = SecureKey.apiKey.decryptedValue
+let githubToken = key(for: .githubToken)
+```
 
-If the `CI` environment variable is set to `true`, the keys are read from the environment variables. Otherwise, the keys are read from the Keychain.
+## How Secret Generation Works
 
-You can configure your keys like this:
+`secure-keys` does not create third-party API keys for providers such as GitHub, Firebase, Stripe, or AWS. Those secrets must be created in their owning service first.
 
-### From Keychain
+The tool generates an iOS framework that contains encrypted copies of the secret values you provide:
 
-1. You need to define the `secure-keys` record in the Keychain with the key name and the key value.
+1. Resolve the secret source:
+   - Local runs use macOS Keychain unless CI mode is enabled.
+   - CI runs use environment variables.
+2. Read the configured list of secret names.
+3. Read each secret value by name.
+4. Generate a random AES-256-GCM key for this build.
+5. Encrypt each secret value.
+6. Write a Swift `SecureKey` enum with encrypted byte arrays.
+7. Build `.secure-keys/SecureKeys.xcframework`.
+8. Remove temporary Swift package files.
 
-The value for this key should be all the key names separated by a comma.
+## Local Configuration With Keychain
+
+The default Keychain service and account identifier is `secure-keys`.
+
+Store the list of secret names:
 
 ```bash
 security add-generic-password -a "secure-keys" -s "secure-keys" -w "githubToken,apiKey"
 ```
 
-If you want to use another keychain identifier, you can define an env variable named `SECURE_KEYS_IDENTIFIER` to set the keychain identifier.
+Store each secret value under the same Keychain service:
+
+```bash
+security add-generic-password -a "secure-keys" -s "githubToken" -w "your-github-token"
+security add-generic-password -a "secure-keys" -s "apiKey" -w "your-api-key"
+```
+
+Use a custom Keychain identifier:
 
 ```bash
-export SECURE_KEYS_IDENTIFIER="your-keychain-identifier"
+export SECURE_KEYS_IDENTIFIER="my-app-secrets"
 
 security add-generic-password -a "$SECURE_KEYS_IDENTIFIER" -s "$SECURE_KEYS_IDENTIFIER" -w "githubToken,apiKey"
+security add-generic-password -a "$SECURE_KEYS_IDENTIFIER" -s "githubToken" -w "your-github-token"
+security add-generic-password -a "$SECURE_KEYS_IDENTIFIER" -s "apiKey" -w "your-api-key"
 ```
 
-2. You can add new keys using the `security` command.
+Use a custom delimiter:
 
 ```bash
-security add-generic-password -a "secure-keys" -s "apiKey" -w "your-api-key"
+export SECURE_KEYS_DELIMITER="|"
+security add-generic-password -a "secure-keys" -s "secure-keys" -w "githubToken|apiKey"
 ```
 
-Using custom keychain identifier:
+## CI Configuration With Environment Variables
+
+CI mode is enabled automatically when common CI variables are present, including `CI=true` and `GITHUB_ACTIONS=true`. You can also force it:
 
 ```bash
-security add-generic-password -a "$SECURE_KEYS_IDENTIFIER" -s "apiKey" -w "your-api-key"
+secure-keys --ci
 ```
 
-### Environment variables
-
-1. You can define the keys in the `.env` file or export the keys as environment variables.
+Set the list of secret names in `SECURE_KEYS_IDENTIFIER`:
 
 ```bash
 export SECURE_KEYS_IDENTIFIER="github-token,api_key,firebaseToken"
+```
+
+Set each secret value as an environment variable. Secret names are looked up exactly first, then normalized by converting `-` to `_` and uppercasing.
 
+```bash
 export GITHUB_TOKEN="your-github-token"
 export API_KEY="your-api-key"
 export FIREBASETOKEN="your-firebase-token"
 ```
 
-> The key names are formatted in uppercase and replace the `-` with `_`.
-
-> [!IMPORTANT]
-> If you want to use another demiliter, you can define an env variable named `SECURE_KEYS_DELIMITER` to set the delimiter.
+The `SECURE_KEYS_` prefix is also supported for secret values:
 
 ```bash
-export SECURE_KEYS_DELIMITER="|"
-
-export SECURE_KEYS_IDENTIFIER="github-token|api_key|firebaseToken"
+export SECURE_KEYS_API_KEY="your-api-key"
 ```
 
-### Ruby script
-
-To generate the `SecureKeys.xcframework` use the `secure-keys` command in the iOS project root directory.
-
-Using global gem:
+You can store the list in a dedicated environment variable instead:
 
 ```bash
-secure-keys
+export CUSTOM_SECRET_LIST="github-token,api_key"
+secure-keys --ci --identifier CUSTOM_SECRET_LIST
 ```
 
-Using bundler:
+Use a custom delimiter in CI:
 
 ```bash
-bundle exec secure-keys
+export SECURE_KEYS_DELIMITER="|"
+export SECURE_KEYS_IDENTIFIER="github-token|api_key|firebaseToken"
 ```
 
-To get more information about the command, you can use the `--help` option.
+## CLI Reference
 
 ```bash
 secure-keys --help
+```
 
-# Output
-
+```text
 Usage: secure-keys [--options]
 
     -h, --help                       Use the provided commands to select the params
@@ -147,172 +175,356 @@ Usage: secure-keys [--options]
         --xcframework                Add the xcframework to the target
 ```
 
-To avoid defining the `SECURE_KEYS_IDENTIFIER` and `SECURE_KEYS_DELIMITER` env variables, you can use the `--identifier` and `--delimiter` options.
+Examples:
+
+```bash
+secure-keys
+secure-keys --verbose
+secure-keys --ci --identifier CUSTOM_SECRET_LIST
+secure-keys --identifier "my-app-secrets" --delimiter "|"
+secure-keys -i "my-app-secrets" -d "|"
+```
+
+## Xcode Integration
+
+Generate the framework only:
+
+```bash
+secure-keys
+```
+
+Generate and add the framework to an Xcode target:
 
 ```bash
-secure-keys --identifier "your-keychain-or-env-variable-identifier" --delimiter "|"
+secure-keys --xcframework --target "YourTargetName" --add
+```
+
+Replace an existing framework reference:
+
+```bash
+secure-keys --xcframework --target "YourTargetName" --replace
 ```
 
-Also, you can use the short options:
+Add an already generated framework without rebuilding:
 
 ```bash
-secure-keys -i "your-keychain-or-env-variable-identifier" -d "|"
+secure-keys --no-generate --xcframework --target "YourTargetName"
 ```
 
-### iOS project
+Select a project explicitly:
+
+```bash
+secure-keys --xcframework --target "YourTargetName" --xcodeproj "/path/to/YourProject.xcodeproj"
+```
 
-Within the iOS project, you can use the `SecureKeys` target dependency like:
+The same options can be configured with environment variables:
+
+```bash
+export SECURE_KEYS_XCFRAMEWORK_TARGET="YourTargetName"
+export SECURE_KEYS_XCFRAMEWORK_ADD=true
+export SECURE_KEYS_XCFRAMEWORK_REPLACE=false
+export SECURE_KEYS_XCFRAMEWORK_XCODEPROJ="/path/to/YourProject.xcodeproj"
+
+secure-keys --xcframework
+```
+
+Short environment variable names are also supported:
+
+```bash
+export XCFRAMEWORK_TARGET="YourTargetName"
+export XCFRAMEWORK_ADD=true
+export XCFRAMEWORK_REPLACE=false
+export XCFRAMEWORK_XCODEPROJ="/path/to/YourProject.xcodeproj"
+```
+
+### Manual Xcode Setup
+
+If you do not use `--xcframework`, add the framework manually:
+
+1. Open the Xcode project target.
+2. Open `General`.
+3. Add `.secure-keys/SecureKeys.xcframework` to `Frameworks, Libraries, and Embedded Content`.
+4. Open `Build Settings`.
+5. Add `$(SRCROOT)/.secure-keys` to `Framework Search Paths`.
+
+## Swift API
+
+The generated framework exposes `SecureKey`, `key(for:)`, `key(_:)`, and a `String.secretKey` helper.
 
 ```swift
 import SecureKeys
 
-// Using key directly in the code
 let apiKey = SecureKey.apiKey.decryptedValue
+let githubToken = key(for: .githubToken)
+let sameGithubToken = key(.githubToken)
+let keyFromString: SecureKey = "apiKey".secretKey
+let valueFromString = "apiKey".secretKey.decryptedValue
+let staticValue = String.key(for: .apiKey)
+```
 
-// Using key from `SecureKey` enum
-let someKey: String = key(for: .someKey)
+Generated key names are camelized for Swift enum cases:
 
-// Alternative way to use key from `SecureKey` enum
-let someKey: String = key(.someKey)
+```text
+api-key      -> SecureKey.apiKey
+githubToken  -> SecureKey.githubToken
+```
 
-// Using raw value from `SecureKey` enum
-let apiKey: SecureKey = "apiKey".secretKey
+## Output Files
 
-// Using raw value from `SecureKey` enum with decrypted value
-let apiKey: String = "apiKey".secretKey.decryptedValue
+The main output is:
 
-// Using `key` method to get the key
-let apiKey: String = .key(for: .apiKey)
+```text
+.secure-keys/SecureKeys.xcframework
 ```
 
-## How to install the `SecureKeys.xcframework` in the iOS project
+Temporary Swift package and build files are created under `.secure-keys` during generation and removed after the framework is built.
+
+## Security Notes
+
+- Do not commit `.secure-keys/SecureKeys.xcframework` unless your release process intentionally requires it.
+- Do not commit `.env` files or raw secret values.
+- Treat app-bundled secrets as obfuscation, not as a perfect security boundary. A determined attacker can inspect a shipped app binary.
+- Prefer server-side secret usage for highly sensitive credentials.
+- Use environment-specific keys for development, staging, and production.
+- Rotate keys regularly and revoke leaked credentials immediately.
+
+## Secret Scanning and Validation
+
+`secure-keys` ships both a CLI and a Ruby API for validating individual secret values and scanning source files or git diffs for accidentally exposed credentials.
 
-### Automatically
+### CLI
 
-> [!IMPORTANT]
-> You can see more information about the command using the `--help` option.
+Scan the current directory:
 
 ```bash
-secure-keys --xcframework --help
+secure-keys validate scan
+```
 
-# Output
-Usage: secure-keys --xcframework [--options]
+Scan a specific path:
 
-    -h, --help                       Use the provided commands to select the params
-        --[no-]add                   Add the SecureKeys XCFramework to the Xcode project (default: true)
-    -t, --target TARGET              The target to add the xcframework
-    -r, --replace                    Replace the existing xcframework in the Xcode project (default: false)
-    -x, --xcodeproj XCODEPROJ        The Xcode project path (default: the first found Xcode project)
+```bash
+secure-keys validate scan ./src
 ```
 
-From the `secure-keys` command, you can use the `--xcframework` option to add the `SecureKeys.xcframework` to the iOS project.
+Scan only staged git changes (useful as a pre-commit hook):
 
 ```bash
-secure-keys --xcframework --target "YourTargetName" --add
+secure-keys validate scan --staged
 ```
 
-If you want to add the `SecureKeys.xcframework` to an iOS that already contains the `SecureKeys` source code, you can use the `--replace` option.
+Save the report as JSON:
 
 ```bash
-secure-keys --xcframework --target "YourTargetName" --replace
+secure-keys validate scan --output report.json
 ```
 
-> [!IMPORTANT]
-> If you don't need to generate the `SecureKeys.xcframework` every time, you can use the `--no-generate` option.
+Override the file extensions and exclusions:
 
 ```bash
-secure-keys --no-generate --xcframework --target "YourTargetName"
+secure-keys validate scan --extensions .rb,.swift,.go --excludes vendor,tmp,build
 ```
 
-Also, you can specify your Xcode project path using the `--xcodeproj` option.
+Enable verbose output:
 
 ```bash
-secure-keys --xcframework --target "YourTargetName" --xcodeproj "/path/to/your/project.xcodeproj"
+secure-keys validate scan --verbose
 ```
 
-> [!IMPORTANT]
-> By default, the xcodeproj path would be the first found Xcode project.
+Full option reference:
 
-If you don't want to use the CLI options, you can configure some env variable to interact with the `secure-keys` command.
+```text
+Usage: secure-keys validate scan [path] [--options]
 
-```bash
-# e.g (Large version)
-export SECURE_KEYS_XCFRAMEWORK_TARGET="YourTargetName"
-export SECURE_KEYS_XCFRAMEWORK_ADD=true
-export SECURE_KEYS_XCFRAMEWORK_REPLACE=true
-export SECURE_KEYS_XCFRAMEWORK_XCODEPROJ="/path/to/your/project.xcodeproj"
+    -h, --help          Show help for the scan subcommand
+        --staged        Scan staged git changes instead of a directory (default: false)
+    -o, --output FILE   Save the scan report as JSON to FILE
+        --extensions    Comma-separated file extensions to scan (e.g. .rb,.swift)
+        --excludes      Comma-separated directory names to exclude from the scan
+        --verbose       Enable verbose output (default: false)
+```
 
-# e.g (Short version)
-export XCFRAMEWORK_TARGET="YourTargetName"
-export XCFRAMEWORK_ADD=true
-export XCFRAMEWORK_REPLACE=true
-export XCFRAMEWORK_XCODEPROJ="/path/to/your/project.xcodeproj"
+Exit codes:
 
-# Run the command
-secure-keys --xcframework
+| Code | Meaning |
+|---|---|
+| `0` | Scan completed with no findings |
+| `1` | One or more secrets were detected |
+
+### Validating a Secret
+
+`SecureKeys::Validation::Validator` checks a single value against a set of security rules and returns a `ValidationResult`.
+
+```ruby
+require 'validation/validator'
+
+validator = SecureKeys::Validation::Validator.new
+result    = validator.validate(key: :api_key, value: ENV['API_KEY'])
+
+puts result.summary          # ✅ api_key — no issues  /  ❌ api_key — 2 issue(s)
+puts result.valid?           # true / false
+puts result.severity_level   # :ok | :warning | :error | :critical
+result.print                 # formatted report to stdout
+```
+
+Available validation options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `check_entropy` | Boolean | `false` | Flag low-entropy (repetitive) values |
+| `allow_production` | Boolean | `false` | Skip the production-key warning |
+| `warn_on_pattern` | Boolean | `false` | Emit an informational notice when a pattern matches |
+
+```ruby
+result = validator.validate(
+  key: :stripe_key,
+  value: ENV['STRIPE_KEY'],
+  options: { check_entropy: true, warn_on_pattern: true }
+)
+```
+
+Detect the type of a secret value:
+
+```ruby
+info = validator.detect_type(value: 'ghp_abc...')
+# => { type: :github_token, description: "GitHub Personal Access Token", severity: :high, ... }
+```
+
+Get provider-specific security recommendations:
+
+```ruby
+validator.recommendations(key: :githubToken)
+# => ["Use GitHub Personal Access Tokens with minimal required scopes", ...]
+```
+
+### Scanning Files for Exposed Secrets
+
+`SecureKeys::Validation::Scanner` scans source files or git diffs for credentials that match any of the 25+ built-in patterns.
+
+Scan a directory:
+
+```ruby
+require 'validation/scanner'
+
+scanner = SecureKeys::Validation::Scanner.new
+result  = scanner.scan_directory(path: '.')
+
+puts result.clean?        # true if no findings
+puts result.files_count   # number of files scanned
+
+result.findings.each { |f| puts f.to_s }
+result.print if !result.clean?
+```
+
+Scan only staged git changes (useful in a pre-commit hook):
+
+```ruby
+result = scanner.scan_git_diff                    # staged only (default)
+result = scanner.scan_git_diff(staged_only: false) # staged + unstaged
+```
+
+Customize the scan at initialization or per call:
+
+```ruby
+scanner = SecureKeys::Validation::Scanner.new(
+  options: {
+    extensions: ['.rb', '.swift', '.go'],
+    excludes:   ['vendor', 'node_modules', '.git'],
+    max_depth:  5
+  }
+)
 ```
 
-### Manually
+Filter findings by severity:
+
+```ruby
+result.by_severity(severity: :critical).each { |f| puts f.to_s }
+```
 
-1. From the iOS project, click on the project target, select the `General` tab, and scroll down to the `Frameworks, Libraries, and Embedded Content` section.
+### Detected Patterns
 
-![Project Target](/docs/assets/add-xcframework-to-ios-project/first-step.png)
+The scanner recognizes the following secret types out of the box:
 
-2. Click on the `Add Other...` button and click on the `Add Files...` option.
+| Pattern | Severity |
+|---|---|
+| GitHub personal / OAuth / App / refresh token | high |
+| AWS access key ID | critical |
+| AWS secret access key | critical |
+| Google Cloud API key | high |
+| Google OAuth token | high |
+| Stripe secret key (live / test) | critical |
+| Stripe publishable / restricted key | medium / high |
+| Slack bot / app / webhook token | high / medium |
+| JWT token | medium |
+| PEM / RSA / EC / OpenSSH private key | critical |
+| Generic API key assignment | medium |
+| Generic secret / password assignment | medium |
+| Firebase API key | medium |
+| Twilio API key / Account SID | high / low |
+| SendGrid API key | high |
+| Mailchimp API key | medium |
+| Square access token | high |
+| PayPal Braintree access token | critical |
+| Heroku API key | high |
+| Base64-encoded secret | low |
+| Suspicious assignment (catch-all) | low |
 
-![Add Files](/docs/assets/add-xcframework-to-ios-project/second-step.png)
+### Validation Configuration
 
-3. Navigate to the `keys` directory and select the `SecureKeys.xcframework` folder.
+All thresholds can be overridden with environment variables. Both the bare name and the `SECURE_KEYS_` prefix are supported.
 
-![Select SecureKeys.xcframework](/docs/assets/add-xcframework-to-ios-project/third-step.png)
+| Environment variable | Default | Description |
+|---|---|---|
+| `SECURE_KEYS_API_KEY_LENGTH` | `20` | Minimum API key length |
+| `SECURE_KEYS_TOKEN_LENGTH` | `20` | Minimum token length |
+| `SECURE_KEYS_SECRET_LENGTH` | `16` | Minimum secret length |
+| `SECURE_KEYS_PASSWORD_LENGTH` | `12` | Minimum password length |
+| `SECURE_KEYS_KEY_LENGTH` | `16` | Minimum generic key length |
+| `SECURE_KEYS_SCAN_EXTENSIONS` | `.swift,.rb,.py,.js,...` | Comma-separated file extensions to scan |
+| `SECURE_KEYS_SCAN_EXCLUDES` | `.git,node_modules,Pods,...` | Comma-separated names to exclude |
+| `SECURE_KEYS_MAX_SCAN_DEPTH` | `10` | Maximum directory traversal depth |
+| `SECURE_KEYS_MIN_ENTROPY_THRESHOLD` | `3.0` | Shannon entropy threshold for `check_entropy` |
 
-> Now the `SecureKeys.xcframework` is added to the iOS project.
+## Troubleshooting
 
-![Select SecureKeys.xcframework](/docs/assets/add-xcframework-to-ios-project/third-step-result.png)
+`Error fetching the key from Keychain`
 
-4. Click on the `Build settings` tab and search for the `Search Paths` section.
+Verify the Keychain service, account, and identifier values. For the default configuration, the list must be stored with account `secure-keys` and service `secure-keys`.
 
-![Search Paths](/docs/assets/add-xcframework-to-ios-project/fourth-step.png)
+`Error fetching the key from ENV variables`
 
-> Add the path to the `SecureKeys.xcframework` in the `Framework Search Paths` section.
+Verify CI mode is enabled and that each configured key has a matching environment variable. For example, `github-token` maps to `GITHUB_TOKEN`.
+
+`xcodebuild` fails
+
+Verify Xcode command line tools are installed and selected:
 
 ```bash
-$(inherited)
-$(SRCROOT)/.secure-keys
+xcode-select -p
 ```
 
-## How it works
+`SecureKeys.xcframework` is not found by Xcode
 
-The process when the script is executed is:
+Verify `$(SRCROOT)/.secure-keys` is present in `Framework Search Paths` and that the framework is attached to the correct target.
 
-1. Create a `.secure-keys` directory.
-2. Create a temporary `Swift Package` in the `.secure-keys` directory.
-3. Copy the `SecureKeys` source code to the temporary `Swift Package`.
+## Development
 
-   ```swift
-   public enum SecureKey {
+Install dependencies:
 
-       // MARK: - Cases
+```bash
+bundle install
+```
 
-       case apiKey
-       case someKey
-       case unknown
+Run the test suite:
 
-       // MARK: - Properties
+```bash
+bundle exec rspec
+```
 
-       /// The decrypted value of the key
-       public var decryptedValue: String {
-           switch self {
-               case .apiKey: [1, 2, 4].decrypt(key: [248, 53, 26], iv: [148, 55, 47], tag: [119, 81])
-               case .someKey: [1, 2, 4].decrypt(key: [248, 53, 26], iv: [148, 55, 47], tag: [119, 81])
-               case .unknown: fatalError("Unknown key \(rawValue)")
-           }
-       }
-   }
-   ```
+Run the local CLI:
 
-4. Generate the `SecureKeys.xcframework` using the temporary `Swift Package`.
-5. Remove the temporary `Swift Package`.
+```bash
+bundle exec ./bin/secure-keys --help
+```
 
 ## License