VANISHKEY AGENT INTERFACE v2
================================

canonical: https://vanishkey.com
client: https://vanishkey.com/vk-agent.mjs
storage: redis-only ciphertext with native TTL
encryption: AES-256-GCM, performed by the sending agent
identifier_entropy: 256 bits
authentication_context: protocol version + secret identifier
secret_ttl: 3600 seconds maximum, set atomically with the Redis write
read_budget: 1
on_reveal: atomic GET + DELETE

PURPOSE
-------
Use VanishKey to pass passwords, tokens, recovery codes, and private text
between agents or between an agent and a human. Never put plaintext secrets in
URLs, command-line arguments, logs, chat messages, or shell history.

FAST PATH (NODE.JS 22+)
-----------------------
1. Download the dependency-free client:

   curl -fsS https://vanishkey.com/vk-agent.mjs -o vk-agent.mjs

2. Feed a UTF-8 secret over stdin. The command prints only the one-time URL:

   printf '%s' "$SECRET_FROM_A_SAFE_SOURCE" | \
     node vk-agent.mjs create

3. Send the COMPLETE URL, including its #fragment, to the intended recipient.

4. A receiving agent can reveal and consume it:

   node vk-agent.mjs reveal \
     'https://vanishkey.com/s/SECRET_ID#DECRYPTION_KEY'

The create command also supports:

   --email recipient@example.com
   --base https://another-vanishkey-host.example
   --json

All unopened secrets expire after 1 hour. The expiration cannot be extended.

`--email` asks VanishKey to deliver the complete one-time link through its
Mailgun sending identity. This is explicit opt-in: the URL-fragment key passes
transiently through VanishKey and Mailgun to construct the email. VanishKey
does not store the recipient address or link, and tracking is disabled.

SECURITY RULES
--------------
- Plaintext is encrypted locally before any request.
- New links use a 256-bit random identifier and a 256-bit AES key.
- AES-GCM additional authenticated data binds the ciphertext to protocol v1
  and its exact identifier, so a payload cannot be transplanted to another URL.
- The AES key exists only after # in the generated URL. URL fragments are not
  sent to the VanishKey server by HTTP clients or browsers.
- Exception: direct email (`--email` or the website's direct-email form)
  explicitly sends the complete URL through VanishKey and Mailgun for delivery.
- The server stores only cipherText and iv under a namespaced Redis key.
- The Redis SET applies NX and a 3,600-second EX TTL atomically. Application
  callers cannot request a longer lifetime.
- Opening the reveal page does not consume a secret. Deliberate POST does.
- Reveal atomically retrieves and deletes the ciphertext. A second read is 404.
- Do not preflight or preview a link by calling the reveal endpoint.
- Do not retry reveal after a transport timeout unless the recipient accepts
  that the first request may already have consumed the payload.

HTTP PROTOCOL
-------------
Create:

  POST /api/secrets
  Content-Type: application/json

  {
    "id": "<43 base64url characters / 32 random bytes>",
    "cipherText": "<base64url AES-256-GCM ciphertext plus auth tag>",
    "iv": "<16 base64url characters / 12 random bytes>",
    "expiryHours": 1
  }

Success:

  HTTP 201
  { "id": "<same id>" }

Reveal and consume:

  POST /api/secrets/<id>/reveal
  Content-Type: application/json
  {}

Success:

  HTTP 200
  { "cipherText": "<base64url>", "iv": "<base64url>" }

Gone, expired, or unknown:

  HTTP 404

The sender constructs:

  https://vanishkey.com/s/<id>#v1.<base64url 32-byte AES key>

The fragment key MUST NOT be included in an API request.

For a v1 link, AES-GCM additional authenticated data is the UTF-8 encoding of:

  vanishkey:v1:<id>

Legacy unversioned links remain revealable only for their existing TTL.

DISCOVERY
---------
Humans: https://vanishkey.com
Agents: https://vanishkey.com/agent.txt
LLMs: https://vanishkey.com/llms.txt
Health: https://vanishkey.com/api/health