astro-discovery/CANARY_SPEC.md

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:

{
  "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.