From 1ff0ad8da65141782b1c4fa1669d87435a646df3 Mon Sep 17 00:00:00 2001 From: dillonstreator Date: Fri, 6 Nov 2026 16:20:25 -0600 Subject: [PATCH] feat(server): protect verification hash and delete token at rest A Redis dump exposed `h` and `dt` in plaintext, which was enough to burn or delete a secret and gave legacy password links a fast offline guessing oracle. Store `h` as an HMAC-SHA256 digest keyed from ENCRYPTION_KEY and bound to the vault ID. The digest is deterministic, so the Lua script still compares atomically and no distributed lock is needed. The stored format selects the comparison, so a stolen digest can't be submitted as `h`. Encrypt `dt` rather than digesting it because webhook payloads return the original value to the creator. Existing entries keep working until they expire. Closes #69 --- .../encrypt-verification-hash-at-rest.md | 6 + README.md | 2 +- SPECIFICATION.md | 16 ++- docker-compose.yaml | 2 +- packages/core/src/api.ts | 2 +- packages/core/src/encryption/machine.test.ts | 30 ++++- packages/core/src/encryption/machine.ts | 22 +++ packages/core/src/vault.ts | 2 +- packages/server/src/app.test.ts | 125 +++++++++++++++++- packages/server/src/vault/redis.ts | 37 +++++- 10 files changed, 229 insertions(+), 15 deletions(-) create mode 100644 .changeset/encrypt-verification-hash-at-rest.md diff --git a/.changeset/encrypt-verification-hash-at-rest.md b/.changeset/encrypt-verification-hash-at-rest.md new file mode 100644 index 0000000..1500cd8 --- /dev/null +++ b/.changeset/encrypt-verification-hash-at-rest.md @@ -0,0 +1,6 @@ +--- +'@crypt.fyi/core': minor +'@crypt.fyi/server': minor +--- + +Stop storing verification hashes and delete tokens in plaintext in Redis. Hashes are now stored as a keyed digest bound to the vault ID, and delete tokens are encrypted. Existing entries keep working until they expire. Changing `ENCRYPTION_KEY` now makes all unexpired secrets unreadable, not only those with IP restrictions or webhooks. diff --git a/README.md b/README.md index 5e4ee7a..067f461 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ API_URL=https://{your-domain-here} ENCRYPTION_KEY=$(openssl rand -base64 32) docker compose up --build ``` -`ENCRYPTION_KEY` encrypts IP restrictions and webhook URLs at rest in Redis. Keep it stable across restarts (e.g. in a `.env` file next to `docker-compose.yaml`); changing it makes existing secrets with those options unreadable. +`ENCRYPTION_KEY` protects verification hashes, delete tokens, IP restrictions and webhook URLs at rest in Redis. Keep it stable across restarts (e.g. in a `.env` file next to `docker-compose.yaml`); changing it makes all existing secrets unreadable until they expire. `API_URL` is read when the web container starts, so changing it only needs a restart (`docker compose up -d`), not a rebuild. It must be a plain `http(s)://host[:port][/path]` URL; the container refuses to start otherwise. diff --git a/SPECIFICATION.md b/SPECIFICATION.md index 3ea2567..dbd1b5f 100644 --- a/SPECIFICATION.md +++ b/SPECIFICATION.md @@ -129,7 +129,7 @@ Abstract - MUST handle only encrypted data operations - MUST NOT receive or process URLs containing decryption keys - - MUST only receive hashed keys for verification (SHA-512) + - MUST only receive hashed keys for verification (see Section 3.2) - MUST operate independently from web server This separation ensures that even if the web server logs are @@ -168,7 +168,9 @@ Abstract ### 3.2. Hash Functions Implementations MUST use: - - SHA-512 for key verification hash (key + optional password) + - SHA-512 for key verification hash without a password (key only), and + for legacy links + - Argon2id for key verification hash with a password (key + password) - SHA3-512 for key derivation in ML-KEM-768-2 ### 3.3. Compression @@ -184,7 +186,7 @@ Abstract ```json { "c": "", - "h": "", + "h": "", "m": { "compression": { "algorithm": "zlib:pako" | "none" @@ -276,13 +278,19 @@ Abstract - Implementation MUST NOT use persistent storage - ephemeral Redis storage only - Data MUST be securely deleted upon expiration or burning + - The verification hash MUST NOT be stored in plaintext; servers MUST store + a keyed digest (HMAC-SHA-256) bound to the vault ID, so a datastore dump + alone cannot be replayed to read or burn an entry + - Delete tokens MUST NOT be stored in plaintext; servers MUST store them + encrypted so they can be returned in webhook payloads ### 6.3. Access Control - IP address restrictions MAY use CIDR notation - Implementations MUST NOT allow more than 3 IP restrictions per vault entry - - Key authentication MUST use SHA-512 hash verification + - Key authentication MUST use the verification hash defined in + Section 3.2 ### 6.4. Transport Security diff --git a/docker-compose.yaml b/docker-compose.yaml index ad63391..b29689c 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -26,7 +26,7 @@ services: environment: - REDIS_URL=redis://redis:6379 - PORT=${SERVER_PORT:-4321} - # Encrypts IP restrictions and webhook URLs at rest in Redis. + # Protects verification hashes, delete tokens, IP restrictions and webhook URLs at rest in Redis. - ENCRYPTION_KEY=${ENCRYPTION_KEY:?ENCRYPTION_KEY is required (e.g. openssl rand -base64 32)} ports: - '${SERVER_PORT:-4321}:${SERVER_PORT:-4321}' diff --git a/packages/core/src/api.ts b/packages/core/src/api.ts index 25ae6db..74b75cd 100644 --- a/packages/core/src/api.ts +++ b/packages/core/src/api.ts @@ -19,7 +19,7 @@ export const readVaultParamsSchema = z.object({ export type ReadVaultParams = z.infer; export const readVaultQuerySchema = z.object({ - h: z.string().describe('sha512 hash of the encryption key + optional password'), + h: z.string().describe('verification hash of the encryption key + optional password'), }); export type ReadVaultQuery = z.infer; diff --git a/packages/core/src/encryption/machine.test.ts b/packages/core/src/encryption/machine.test.ts index 5f9d321..d34c710 100644 --- a/packages/core/src/encryption/machine.test.ts +++ b/packages/core/src/encryption/machine.test.ts @@ -1,6 +1,33 @@ -import { encrypt, decrypt } from './machine'; +import { encrypt, decrypt, digest, isDigest, isEncrypted } from './machine'; import { encrypt as gcmEncrypt } from './gcm'; +describe('machine digest', () => { + const key = 'a-high-entropy-machine-key-0123456789'; + + it('is deterministic and prefixed', () => { + const a = digest('value', key, 'ctx'); + expect(a).toBe(digest('value', key, 'ctx')); + expect(isDigest(a)).toBe(true); + expect(a).not.toContain('value'); + }); + + it('changes with the value, key and context', () => { + const base = digest('value', key, 'ctx'); + expect(digest('other', key, 'ctx')).not.toBe(base); + expect(digest('value', 'another-key', 'ctx')).not.toBe(base); + expect(digest('value', key, 'other-ctx')).not.toBe(base); + }); + + it('keeps context and value unambiguous', () => { + expect(digest('bc', key, 'a')).not.toBe(digest('c', key, 'ab')); + }); + + it('does not treat hex hashes or random tokens as digests or ciphertext', () => { + expect(isDigest('abc123')).toBe(false); + expect(isEncrypted('abc123')).toBe(false); + }); +}); + describe('machine cipher', () => { const key = 'a-high-entropy-machine-key-0123456789'; @@ -8,6 +35,7 @@ describe('machine cipher', () => { const plaintext = 'https://hooks.example.com/webhook?x=1'; const enc = await encrypt(plaintext, key); expect(enc.startsWith('m1:')).toBe(true); + expect(isEncrypted(enc)).toBe(true); expect(await decrypt(enc, key)).toBe(plaintext); }); diff --git a/packages/core/src/encryption/machine.ts b/packages/core/src/encryption/machine.ts index 10f49d8..8c13ae7 100644 --- a/packages/core/src/encryption/machine.ts +++ b/packages/core/src/encryption/machine.ts @@ -17,6 +17,7 @@ import { gcm as aesGcm } from '@noble/ciphers/aes'; import { hkdf } from '@noble/hashes/hkdf'; +import { hmac } from '@noble/hashes/hmac'; import { sha256 } from '@noble/hashes/sha2'; import { randomBytes, concatBytes, utf8ToBytes } from '@noble/hashes/utils'; import { Buffer } from '../buffer'; @@ -29,9 +30,30 @@ const KEY_LENGTH = 32; const SCHEME_PREFIX = 'm1:'; const HKDF_INFO = utf8ToBytes('crypt.fyi/machine-metadata'); +const DIGEST_PREFIX = 'hm1:'; +// A separate HKDF info keeps digest keys independent of the encryption keys +// derived from the same machine key. +const DIGEST_HKDF_INFO = utf8ToBytes('crypt.fyi/machine-digest'); + const deriveKey = (key: string, salt: Uint8Array): Uint8Array => hkdf(sha256, utf8ToBytes(key), salt, HKDF_INFO, KEY_LENGTH); +export const isEncrypted = (value: string): boolean => value.startsWith(SCHEME_PREFIX); + +export const isDigest = (value: string): boolean => value.startsWith(DIGEST_PREFIX); + +/** + * Deterministic keyed digest, for values that must be compared where the machine + * key isn't available (such as inside a Redis script). `context` scopes the + * digest to one use and must not contain a NUL byte, which separates it from + * `value` so the pair is encoded unambiguously. + */ +export const digest = (value: string, key: string, context: string): string => { + const digestKey = hkdf(sha256, utf8ToBytes(key), undefined, DIGEST_HKDF_INFO, KEY_LENGTH); + const message = concatBytes(utf8ToBytes(context), new Uint8Array([0]), utf8ToBytes(value)); + return DIGEST_PREFIX + Buffer.from(hmac(sha256, digestKey, message)).toString('base64'); +}; + export const encrypt: Encrypt = async (content, key) => { try { const salt = randomBytes(SALT_LENGTH); diff --git a/packages/core/src/vault.ts b/packages/core/src/vault.ts index 6a840e5..cc411fe 100644 --- a/packages/core/src/vault.ts +++ b/packages/core/src/vault.ts @@ -24,7 +24,7 @@ export type ProcessingMetadata = z.infer; export const vaultValueSchema = z.object({ c: z.string().describe('encrypted content'), - h: z.string().describe('sha256 hash of the encryption key + optional password'), + h: z.string().describe('verification hash of the encryption key + optional password'), m: processingMetadataSchema.optional(), b: z.boolean().describe('burn after reading'), dt: z.string().describe('delete token'), diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts index d29e4a4..b596c51 100644 --- a/packages/server/src/app.test.ts +++ b/packages/server/src/app.test.ts @@ -6,7 +6,7 @@ import type { AddressInfo } from 'node:net'; import { pino } from 'pino'; import { createRedisVault } from './vault/redis.js'; import { createTokenGenerator } from './vault/tokens.js'; -import { createNopWebhookSender } from './webhook.js'; +import { createNopWebhookSender, type Message } from './webhook.js'; import { Redis } from 'ioredis'; import { Client } from 'undici'; import { machine, type CreateVaultRequest } from '@crypt.fyi/core'; @@ -378,6 +378,129 @@ describe('app', () => { expect(decryptedWhU).toBe('https://example.com/webhook'); }); + describe('verification hash and delete token at rest', () => { + const m = { encryption: { algorithm: 'aes-256-gcm' as const } }; + const createEntry = async (body: Partial = {}) => { + const response = await testContext.client.request({ + method: 'POST', + path: '/vault', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + c: 'secret-content', + b: false, + h: 'abc123', + ttl: 60_000, + m, + ...body, + } satisfies CreateVaultRequest), + }); + expect(response.statusCode).toBe(201); + return (await response.body.json()) as { id: string; dt: string }; + }; + const read = (id: string, h: string) => + testContext.client.request({ + method: 'GET', + path: `/vault/${id}?h=${encodeURIComponent(h)}`, + }); + const remove = (id: string, dt: string) => + testContext.client.request({ + method: 'DELETE', + path: `/vault/${id}`, + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ dt }), + }); + const stored = async (id: string) => + JSON.parse((await testContext.redis.get(`vault:${id}`))!) as Record; + + it('stores neither value in plaintext', async () => { + const { id, dt } = await createEntry(); + const raw = (await testContext.redis.get(`vault:${id}`))!; + + expect(raw).not.toContain('abc123'); + expect(raw).not.toContain(dt); + expect(machine.isDigest((await stored(id)).h as string)).toBe(true); + expect(machine.isEncrypted((await stored(id)).dt as string)).toBe(true); + }); + + it('verifies with the original hash and rejects the stored digest', async () => { + const { id } = await createEntry(); + const { h: storedH } = await stored(id); + + expect((await read(id, storedH as string)).statusCode).toBe(400); + expect((await read(id, 'abc123')).statusCode).toBe(200); + }); + + it('does not let a stored delete token delete the entry', async () => { + const { id, dt } = await createEntry(); + const { dt: storedDt } = await stored(id); + + expect((await remove(id, storedDt as string)).statusCode).toBe(404); + expect((await remove(id, dt)).statusCode).toBe(200); + }); + + it('produces different digests for the same hash on different entries', async () => { + const [a, b] = await Promise.all([createEntry(), createEntry()]); + expect((await stored(a.id)).h).not.toBe((await stored(b.id)).h); + }); + + it('still serves entries written before this scheme', async () => { + const seed = async (id: string, dt: string) => + testContext.redis.set( + `vault:${id}`, + JSON.stringify({ c: 'c', h: 'legacyhash', b: false, dt, ttl: 60_000, cd: Date.now(), m }), + 'PX', + 60_000, + ); + + await seed('legacy-read', 'legacy-dt-1'); + expect((await read('legacy-read', 'wrong')).statusCode).toBe(400); + expect((await read('legacy-read', 'legacyhash')).statusCode).toBe(200); + await testContext.redis.del('vault:legacy-read'); + + await seed('legacy-delete', 'legacy-dt-2'); + expect((await remove('legacy-delete', 'nope')).statusCode).toBe(404); + expect((await remove('legacy-delete', 'legacy-dt-2')).statusCode).toBe(200); + }); + + it('sends the original delete token to webhooks', async () => { + const messages: Message[] = []; + const vault = createRedisVault( + testContext.redis, + createTokenGenerator({ vaultEntryIdentifierLength: 20, vaultEntryDeleteTokenLength: 20 }), + { send: async (message) => void messages.push(message) }, + 'foobar', + ); + const { id, dt } = await vault.set({ + c: 'c', + h: 'abc123', + b: false, + ttl: 60_000, + m, + wh: { u: 'https://example.com/webhook', r: true, fpk: false, fip: false, b: false }, + }); + + await vault.get(id, 'abc123', '127.0.0.1'); + + expect(messages).toHaveLength(1); + expect(messages[0]?.dt).toBe(dt); + }); + + it('fails without using up attempts when the encryption key has changed', async () => { + const { id } = await createEntry({ fc: 1 }); + const rotated = createRedisVault( + testContext.redis, + createTokenGenerator({ vaultEntryIdentifierLength: 20, vaultEntryDeleteTokenLength: 20 }), + createNopWebhookSender(), + 'a-different-key', + ); + + await expect(rotated.get(id, 'abc123', '127.0.0.1')).rejects.toThrow(); + + expect((await stored(id)).fc).toBe(1); + expect((await read(id, 'abc123')).statusCode).toBe(200); + }); + }); + it('deletes vault entry', async () => { const createResponse = await testContext.client.request({ method: 'POST', diff --git a/packages/server/src/vault/redis.ts b/packages/server/src/vault/redis.ts index d2f5060..9ff6084 100644 --- a/packages/server/src/vault/redis.ts +++ b/packages/server/src/vault/redis.ts @@ -24,6 +24,11 @@ const parseResult = async (result: string, encryptionKey: string) => { // ignore - this maintains backward compatibility with existing vault entries that don't have ips encrypted } } + // Entries written before delete tokens were encrypted hold them in plaintext + // and stay readable until they expire (at most the max TTL). + if (typeof jsonParsed.dt === 'string' && machine.isEncrypted(jsonParsed.dt)) { + jsonParsed.dt = await machine.decrypt(jsonParsed.dt, encryptionKey); + } return vaultValueSchema.parse(jsonParsed); }; @@ -34,6 +39,9 @@ export const createRedisVault = ( encryptionKey: string, ): Vault => { const getKey = (id: string) => `vault:${id}`; + // Binding the digest to the entry id stops a digest being moved between + // entries and hides whether two entries share a verification hash. + const digestH = (id: string, h: string) => machine.digest(h, encryptionKey, `vault-h:${id}`); return { async set(value) { @@ -42,9 +50,12 @@ export const createRedisVault = ( const key = getKey(id); - const [encryptedIps, encryptedWhU] = await Promise.all([ + // The delete token is encrypted rather than digested because webhook + // payloads must carry the original value back to the creator. + const [encryptedIps, encryptedWhU, encryptedDt] = await Promise.all([ ips ? machine.encrypt(ips, encryptionKey) : undefined, wh ? machine.encrypt(wh.u, encryptionKey) : undefined, + machine.encrypt(dt, encryptionKey), ]); // Single atomic SET with NX + PX: only creates the key if absent AND sets @@ -54,10 +65,10 @@ export const createRedisVault = ( key, JSON.stringify({ c, - h, + h: digestH(id, h), b, fc, - dt, + dt: encryptedDt, ttl, cd: Date.now(), m, @@ -84,7 +95,17 @@ export const createRedisVault = ( return undefined; } - const { ips, c, b, ttl, cd, dt, wh, m } = await parseResult(result, encryptionKey); + const { + h: storedH, + ips, + c, + b, + ttl, + cd, + dt, + wh, + m, + } = await parseResult(result, encryptionKey); if (!isIpAllowed(ip, ips)) { if (wh?.fip) { void webhookSender.send({ @@ -99,6 +120,12 @@ export const createRedisVault = ( return undefined; } + // The stored format decides the comparison, never the request. Accepting + // either form would let someone holding a Redis dump submit the stored + // digest as `h`. Entries without a digest predate this scheme and expire + // within the max TTL. + const expectedH = machine.isDigest(storedH) ? digestH(id, h) : h; + const outcome = (await redis.eval( // https://redis.io/docs/latest/develop/interact/programmability/lua-api/ // https://redis.io/docs/latest/develop/interact/programmability/lua-api/#cjson-library @@ -167,7 +194,7 @@ export const createRedisVault = ( `, 1, key, - h, + expectedH, )) as string | null; if (!outcome) { return undefined;