Remove mainnet seed phrases and build credential security framework#251
Merged
Remove mainnet seed phrases and build credential security framework#251
Conversation
Provide a safe template so contributors can create their own settings/Mainnet.toml without copying real mnemonics. The example includes guidance on keeping private keys out of version control.
Mirrors the Mainnet example with testnet-specific settings and a link to the Stacks testnet faucet for funding test accounts.
Explain the purpose of each configuration file, how to create local copies from the templates, and the security rules that prevent accidental mnemonic exposure.
Group the Clarinet credential entries with explanatory comments and add catch-all patterns for PEM, key, p12, and secret files that should never be committed.
Point contributors toward the .example files when they need mainnet or testnet credentials, reducing the risk of copying devnet keys to production.
Define rules that flag mnemonic phrases, Stacks private keys, and generic high-entropy secrets while allowlisting the devnet config and example templates.
Scan staged diffs for BIP-39 mnemonic patterns and run gitleaks when available. The hook can be installed by copying it into .git/hooks/pre-commit.
Run gitleaks on every push and pull request to main, using the project-level .gitleaks.toml configuration. Catches secrets that slip past the local pre-commit hook.
Add frontend network and URL variables, clarify the mnemonic handling expectations, and note that the .env file is covered by .gitignore.
Cover the disclosure process, smart contract and frontend security controls, credential management expectations, and the wallet rotation advisory for compromised mnemonics.
Check that settings/Mainnet.toml is present and does not still contain placeholder text. Print actionable instructions when the file is missing or incomplete.
Add a safety check that refuses to proceed when the credential file is under version control, preventing accidental pushes of live mnemonics.
Reject mnemonics that are not 12 or 24 words, catching truncated or malformed passphrases before they reach the wallet derivation step.
Propagate the clarinet exit code so CI pipelines and operators can distinguish a failed deployment from a successful one.
Include the deployment time in the output for audit trails and post-mortem correlation.
Prevent .vercel/ and .netlify/ from being committed when developers use the CLI tools locally.
Explain how to fork, install dependencies, configure network credentials, and submit pull requests. Reference the pre-commit hook and security disclosure process.
Reflect the new scripts/hooks directory, example config files, and the settings README so contributors can find the credential setup documentation.
Document the gitignore strategy, pre-commit hook, gitleaks CI scan, and timelock pause control. Link to SECURITY.md for the full policy.
Provide scripts/setup-hooks.sh so contributors can install the pre-commit secret scanner without manual file copying.
Describe the smart contract layer, frontend structure, hosting setup, wallet integration, and security boundaries referenced by the README.
Record all credential security improvements made in this branch under the Unreleased section.
Outline the five-phase development plan from core platform through governance and advanced features, marking completed items and current focus areas.
Prompt contributors to confirm no secrets are included, post conditions are enforced, and environment variables are documented before requesting review.
Standardize bug reports with reproduction steps, expected vs actual behavior, and wallet/browser/network details.
Remind reporters to use private disclosure for sensitive issues while providing a structured format for security reports.
Check that Mainnet.toml, Testnet.toml, and .env are not tracked, scan tracked files for mnemonic and private-key patterns, and verify gitignore entries are present.
Add a parallel job that checks gitignore rules and scans for mnemonic patterns using the project verification script.
Explain the immutability constraint, extension contract pattern, ownership transfer migration path, timelock mechanics, and emergency response for compromised keys or vulnerabilities.
Document each script and hook, and highlight the security expectations around mnemonic handling and credential validation.
Provide a structured format for feature proposals with problem statement, proposed solution, and alternatives considered.
Require maintainer review on changes to credentials config, gitignore, security docs, contracts, and CI workflows.
Reject RECIPIENT values that do not match the SP-prefixed mainnet principal pattern, catching typos before they reach the network.
Sanitize 64-character hex strings from error messages to prevent accidental key exposure in terminal logs or CI output.
Provide a single entry point for the supplementary docs folder and link back to all root-level documentation files.
# Conflicts: # .env.example # CHANGELOG.md # README.md # scripts/README.md # scripts/test-contract.cjs
…ed-phrases # Conflicts: # CHANGELOG.md # README.md # SECURITY.md # docs/CONTRACT-UPGRADE-STRATEGY.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive credential security hardening for the TipStream repository.
Ensures mainnet mnemonics are never committed, adds detection tooling at
multiple layers (local hook, CI pipeline, verification script), and creates
the missing project documentation.
Related Issue
Closes #222
Changes
Credential Templates
settings/Mainnet.toml.exampleandTestnet.toml.examplewith placeholder values.env.examplewith deployment-specific variablesDevnet.tomlheaderSecret Scanning
.gitleaks.tomlconfiguration for BIP-39 mnemonic and key detectionscripts/hooks/pre-committo block mnemonic patterns in staged files.github/workflows/secret-scan.yml)scripts/verify-no-secrets.shfor on-demand credential auditingDeployment Safety
scripts/deploy.shvalidates Mainnet.toml presence, placeholder removal, and git trackingscripts/test-con-scripts/test-con-scripts/test-con-scripts/test-con- `scripts/utput sanitizes private keys from log messagesDocumentation
SECURITY.mdwith vulnerability reporting and wallet rotation advisoryARCHITECTURE.mdwith system design and data flowCONTRIBUTING.mdwith setup and PR workflowCHANGELOG.mdfollowing Keep a Changelog formatROADMAP.mdwith phased milestone plandocs/CONTRACT-UPGRADE- Createdocs/CONTRACT-UPGRADE- Createdocs/CONTRACT-UPGRADE- Cgs/- Createdocs/scripts/README.mddirectory guidesRepository Configuration
.- Expand.- Expand.- Expand.- Expand.- Expand.- Expand `.- ExPR template with security checklistCODEOWNERSfor automatic review on security-sensitive pathsTesting
cd frontend && npm run build)scripts/verify-no-secrets.shpassessettings/Mainnet.tomlis not tracked by gitSecuri## Securi## Securi## Securi## Securi## Securi## Securi## Securi## Securi## Securinditions are set to Deny on any new contract calls