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:

```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.