# Hekate Receipt Signer Setup

This runbook moves public Hekate web receipts from `none.private_beta.v1` to
`ed25519.signer.v1`.

It does not create mainnet certification, enterprise certification, or a
guarantee of agent safety. It only enables portable Ed25519 receipt signatures
for Hekate Lite preflight responses.

## 1. Generate key material

Run locally:

```bash
npm run hekate:receipt-keygen
```

The command prints three Vercel env values:

```txt
HEKATE_RECEIPT_ED25519_PRIVATE_KEY_PEM
HEKATE_RECEIPT_KEY_ID
HEKATE_RECEIPT_SIGNER_ID
```

Store the private key in a password manager. Do not commit it, paste it into
chat, attach it to tickets, or put it into `.env` files that may be synced.

## 2. Add Vercel production env vars

In Vercel, open the `hekategate.com` project:

```txt
Settings
  Environment Variables
    Add HEKATE_RECEIPT_ED25519_PRIVATE_KEY_PEM
    Add HEKATE_RECEIPT_KEY_ID
    Add HEKATE_RECEIPT_SIGNER_ID
```

Set scope to `Production`. Add the same values to `Preview` only if preview
deployments should issue verifiable receipts too.

## 3. Redeploy

Redeploy the web project after adding env vars. New preflight receipts should
then include:

```json
{
  "signature_scheme": "ed25519.signer.v1",
  "signer_id": "hekate_web_receipts_prod",
  "signature": "ed25519:...",
  "signature_public_key": "-----BEGIN PUBLIC KEY-----..."
}
```

The trust endpoint should expose the public key:

```bash
curl https://hekategate.com/v1/agentsec/trust
curl https://hekategate.com/v1/receipts/signing-status
curl https://hekategate.com/.well-known/agentsec-jwks.json
```

Expected:

```json
{
  "signature_scheme": "ed25519.signer.v1",
  "keys": [
    {
      "key_id": "hekate_receipts_...",
      "signer_id": "hekate_web_receipts_prod",
      "status": "active"
    }
  ]
}
```

The signing-status endpoint is intentionally secret-free. It should show
`signature_scheme: "ed25519.signer.v1"` and `production_signature_available:
true` before web receipts are treated as portable issuer proof.

## 4. Local conformance check

Run an in-memory self-test:

```bash
npm run hekate:receipt-signer:conformance -- --self-test
```

For a real local key, export the private key in your shell and run:

```bash
npm run hekate:receipt-signer:conformance
```

Passing output:

```json
{
  "ok": true,
  "signature_scheme": "ed25519.signer.v1",
  "production_signature": true
}
```

## 5. Production smoke test

After deploy, call a preflight endpoint:

```bash
curl -s https://hekategate.com/v1/mcp/preflight \
  -H "content-type: application/json" \
  -d '{"tools":[{"name":"github.list_issues","capabilities":["repo_read"],"scopes":["repo:read"]}],"policy":{"max_risk":"medium"}}'
```

Then submit the returned `receipt` to:

```bash
curl -s https://hekategate.com/v1/receipts/verify \
  -H "content-type: application/json" \
  -d '{"receipt":{...}}'
```

Expected:

```json
{
  "valid": true,
  "production_signature": true
}
```

## Rotation

Generate a new key, add a new `HEKATE_RECEIPT_KEY_ID`, redeploy, and keep the
old public key available to verifiers until old receipts age out of their
retention window.

## Boundary

Ed25519 receipt signing proves that Hekate issued a specific receipt over a
specific evidence hash and policy hash. It does not prove that the external
agent, tool, payment rail, or on-chain workflow is safe forever.