feat: add security.txt (RFC 9116) and canary.txt support
Implemented two major new discovery file formats: ## security.txt (RFC 9116 - Industry Standard) - Standardized security contact information - Required fields: Contact, Expires, Canonical - Optional fields: Encryption, Acknowledgments, Policy, Hiring, Languages - Auto-expiration calculation (1 year by default) - Proper mailto: prefix handling - Located at /.well-known/security.txt ## canary.txt (NEW SPECIFICATION) - First standardized format for warrant canaries - Machine-readable transparency statements - Auto-expiring based on update frequency - Support for multiple statement types (NSL, FISA, gag orders, etc.) - Optional blockchain proof - Personnel duress statement - See CANARY_SPEC.md for full specification - Located at /.well-known/canary.txt Changes: - Added SecurityConfig and CanaryConfig type definitions - Created generators for both formats with smart defaults - Added API route handlers with virtual module config - Updated integration to inject /.well-known/ routes - Added to cache configuration (security: 24h, canary: 1h) - Exported new types for TypeScript users - Updated CLAUDE.md with feature priorities - Created comprehensive CANARY_SPEC.md specification document Testing: Both features verified in test project with full configuration. All files generate correctly with proper formatting and validation.
This commit is contained in:
parent
c7b47bba5c
commit
6de34f55a9
8 changed files with 682 additions and 1 deletions
272
CANARY_SPEC.md
Normal file
272
CANARY_SPEC.md
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
# canary.txt Specification
|
||||
|
||||
**Version:** 1.0.0-draft
|
||||
**Status:** Proposal
|
||||
**Author:** Ryan Malloy
|
||||
**Date:** 2025-11-03
|
||||
|
||||
## Abstract
|
||||
|
||||
This document defines `canary.txt`, a standard format for warrant canaries - public statements that organizations publish to indicate they have NOT received secret government requests (national security letters, gag orders, etc.).
|
||||
|
||||
## Motivation
|
||||
|
||||
Warrant canaries currently exist in various ad-hoc formats across websites, making them:
|
||||
- Hard to discover
|
||||
- Difficult to verify programmatically
|
||||
- Inconsistent in format
|
||||
- Challenging to monitor at scale
|
||||
|
||||
A standardized format enables:
|
||||
- Automated monitoring services
|
||||
- Browser extensions that alert users
|
||||
- Transparency dashboards
|
||||
- Cryptographic verification
|
||||
- Historical tracking
|
||||
|
||||
## Specification
|
||||
|
||||
### Location
|
||||
|
||||
The canary file MUST be located at one of:
|
||||
- `/.well-known/canary.txt` (RECOMMENDED)
|
||||
- `/canary.txt` (ACCEPTABLE)
|
||||
|
||||
### Format
|
||||
|
||||
The file MUST be plain text (text/plain; charset=utf-8).
|
||||
|
||||
### Required Fields
|
||||
|
||||
```
|
||||
Canonical-URL: https://example.com/.well-known/canary.txt
|
||||
Issued: 2025-11-03T00:00:00Z
|
||||
Expires: 2026-11-03T00:00:00Z
|
||||
```
|
||||
|
||||
**Canonical-URL:** The authoritative URL for this canary
|
||||
**Issued:** ISO 8601 timestamp when this canary was published
|
||||
**Expires:** ISO 8601 timestamp when this canary expires
|
||||
|
||||
### Statement Section
|
||||
|
||||
The canary MUST include a clear statement:
|
||||
|
||||
```
|
||||
Statement: As of 2025-11-03, Example Inc has NOT received:
|
||||
- National Security Letters (NSLs)
|
||||
- FISA court orders
|
||||
- Gag orders preventing disclosure
|
||||
- Secret government requests for user data
|
||||
- Requests to install surveillance capabilities
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
```
|
||||
Organization: Example Inc
|
||||
Contact: legal@example.com
|
||||
Verification: https://example.com/canary-verification.asc
|
||||
Frequency: monthly
|
||||
Previous-Canary: https://example.com/.well-known/canary-2025-10.txt
|
||||
```
|
||||
|
||||
**Organization:** Legal entity name
|
||||
**Contact:** Email for canary-related inquiries
|
||||
**Verification:** URL to PGP signature or blockchain proof
|
||||
**Frequency:** Update frequency (daily, weekly, monthly, quarterly)
|
||||
**Previous-Canary:** Link to previous canary (for continuity)
|
||||
|
||||
### PGP Signature (Recommended)
|
||||
|
||||
Canaries SHOULD be PGP-signed for authenticity:
|
||||
|
||||
```
|
||||
-----BEGIN PGP SIGNED MESSAGE-----
|
||||
Hash: SHA512
|
||||
|
||||
Canonical-URL: https://example.com/.well-known/canary.txt
|
||||
Issued: 2025-11-03T00:00:00Z
|
||||
Expires: 2026-11-03T00:00:00Z
|
||||
|
||||
Statement: As of 2025-11-03, Example Inc has NOT received:
|
||||
- National Security Letters (NSLs)
|
||||
- FISA court orders
|
||||
...
|
||||
|
||||
-----BEGIN PGP SIGNATURE-----
|
||||
...
|
||||
-----END PGP SIGNATURE-----
|
||||
```
|
||||
|
||||
### Blockchain Proof (Optional)
|
||||
|
||||
For additional verification, include:
|
||||
|
||||
```
|
||||
Blockchain-Proof: bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:blockhash
|
||||
Blockchain-Timestamp: 2025-11-03T00:00:00Z
|
||||
```
|
||||
|
||||
## Example: Minimal Canary
|
||||
|
||||
```
|
||||
Canonical-URL: https://example.com/.well-known/canary.txt
|
||||
Issued: 2025-11-03T00:00:00Z
|
||||
Expires: 2026-02-03T00:00:00Z
|
||||
Organization: Example Inc
|
||||
Contact: transparency@example.com
|
||||
|
||||
Statement: As of 2025-11-03, Example Inc has NOT received any:
|
||||
- National Security Letters
|
||||
- FISA court orders
|
||||
- Gag orders
|
||||
- Secret government requests
|
||||
|
||||
This canary will be updated quarterly. Absence of an update
|
||||
should be considered significant.
|
||||
```
|
||||
|
||||
## Example: Maximum Security Canary
|
||||
|
||||
```
|
||||
-----BEGIN PGP SIGNED MESSAGE-----
|
||||
Hash: SHA512
|
||||
|
||||
Canonical-URL: https://example.com/.well-known/canary.txt
|
||||
Issued: 2025-11-03T00:00:00Z
|
||||
Expires: 2025-12-03T00:00:00Z
|
||||
Organization: Privacy-First Corp
|
||||
Contact: canary@privacyfirst.example
|
||||
Verification: https://privacyfirst.example/pgp-public.asc
|
||||
Frequency: monthly
|
||||
Previous-Canary: https://privacyfirst.example/.well-known/canary-2025-10.txt
|
||||
Blockchain-Proof: bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048
|
||||
Blockchain-Timestamp: 2025-11-03T00:05:23Z
|
||||
|
||||
Statement: As of 2025-11-03, Privacy-First Corp has NOT:
|
||||
- Received any National Security Letters (NSLs)
|
||||
- Received any FISA court orders
|
||||
- Received any gag orders preventing disclosure
|
||||
- Been compelled to modify our software or services
|
||||
- Been compelled to install surveillance capabilities
|
||||
- Received requests to weaken encryption
|
||||
- Been prohibited from updating this canary
|
||||
|
||||
This statement is updated monthly on the first business day.
|
||||
Any absence of an update within 35 days should be considered
|
||||
a removal of this canary.
|
||||
|
||||
Key Personnel Statement: All key personnel with access to
|
||||
infrastructure remain free and under no duress.
|
||||
|
||||
-----BEGIN PGP SIGNATURE-----
|
||||
iQIzBAEBCgAdFiEE...
|
||||
-----END PGP SIGNATURE-----
|
||||
```
|
||||
|
||||
## Machine-Readable Format (.well-known/canary.json)
|
||||
|
||||
For programmatic consumption:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"canonical_url": "https://example.com/.well-known/canary.txt",
|
||||
"issued": "2025-11-03T00:00:00Z",
|
||||
"expires": "2026-11-03T00:00:00Z",
|
||||
"organization": "Example Inc",
|
||||
"contact": "transparency@example.com",
|
||||
"frequency": "monthly",
|
||||
"statements": [
|
||||
{
|
||||
"type": "nsl",
|
||||
"received": false,
|
||||
"description": "National Security Letters"
|
||||
},
|
||||
{
|
||||
"type": "fisa",
|
||||
"received": false,
|
||||
"description": "FISA court orders"
|
||||
},
|
||||
{
|
||||
"type": "gag",
|
||||
"received": false,
|
||||
"description": "Gag orders"
|
||||
}
|
||||
],
|
||||
"verification": {
|
||||
"pgp_signature_url": "https://example.com/canary-verification.asc",
|
||||
"pgp_fingerprint": "1234 5678 9ABC DEF0 1234 5678 9ABC DEF0 1234 5678",
|
||||
"blockchain": {
|
||||
"network": "bitcoin",
|
||||
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
|
||||
"tx_hash": "blockhash"
|
||||
}
|
||||
},
|
||||
"previous_canary": "https://example.com/.well-known/canary-2025-10.txt"
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring & Verification
|
||||
|
||||
### Automated Monitoring
|
||||
|
||||
Services can:
|
||||
1. Fetch canary regularly
|
||||
2. Verify PGP signature
|
||||
3. Check expiration dates
|
||||
4. Alert on missing/changed canaries
|
||||
5. Track historical versions
|
||||
|
||||
### Browser Extension Concept
|
||||
|
||||
A browser extension could:
|
||||
- Display canary status icon
|
||||
- Alert when canary expires/changes
|
||||
- Show canary history
|
||||
- Verify signatures
|
||||
|
||||
## Legal Considerations
|
||||
|
||||
**IMPORTANT:** Consult legal counsel before implementing a warrant canary.
|
||||
- Effectiveness varies by jurisdiction
|
||||
- May not be legally tested in all countries
|
||||
- Should not be sole transparency mechanism
|
||||
- Consider comprehensive transparency reports
|
||||
|
||||
## Security Properties
|
||||
|
||||
1. **Passive Statement:** Says what has NOT happened
|
||||
2. **Absence is Signal:** Missing canary = possible receipt of order
|
||||
3. **Cryptographic Proof:** PGP prevents forgery
|
||||
4. **Blockchain Anchoring:** Proves existence at point in time
|
||||
5. **Continuous Verification:** Automated monitoring detects changes
|
||||
|
||||
## Limitations
|
||||
|
||||
- Legal effectiveness uncertain in many jurisdictions
|
||||
- Sophisticated adversaries may compel deceptive updates
|
||||
- Does not guarantee absence of other surveillance
|
||||
- Should complement, not replace, other transparency measures
|
||||
|
||||
## References
|
||||
|
||||
- RFC 8615: Well-Known URIs
|
||||
- RFC 9116: security.txt
|
||||
- EFF: Warrant Canary FAQ
|
||||
- Warrant Canary Watch
|
||||
|
||||
## Contributing
|
||||
|
||||
This is a draft specification. Feedback welcome at:
|
||||
- GitHub: [repository URL]
|
||||
- Email: ryan@supported.systems
|
||||
|
||||
## License
|
||||
|
||||
This specification is released under CC0 1.0 Universal (Public Domain).
|
||||
|
||||
---
|
||||
|
||||
**Status:** This is a PROPOSED standard, not yet ratified by any standards body.
|
||||
Loading…
Add table
Add a link
Reference in a new issue