@durable-streams/server 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@durable-streams/server",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Node.js reference server implementation for Durable Streams",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
@@ -40,14 +40,14 @@
     "@neophi/sieve-cache": "^1.0.0",
     "lmdb": "^3.3.0",
     "@durable-streams/client": "0.2.4",
-    "@durable-streams/state": "0.2.6"
+    "@durable-streams/state": "0.2.7"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsdown": "^0.9.0",
     "typescript": "^5.0.0",
     "vitest": "^4.0.0",
-    "@durable-streams/server-conformance-tests": "0.3.1"
+    "@durable-streams/server-conformance-tests": "0.3.2"
   },
   "files": [
     "dist",

package/src/crypto.ts

@@ -0,0 +1,217 @@
+/**
+ * Cryptographic utilities for webhook signatures and callback tokens.
+ */
+
+import {
+  createHash,
+  createHmac,
+  createPublicKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign,
+  timingSafeEqual,
+  verify as verifySignature,
+} from "node:crypto"
+import type { JsonWebKey as NodeJsonWebKey } from "node:crypto"
+
+export interface WebhookPublicJwk {
+  kty: `OKP`
+  crv: `Ed25519`
+  x: string
+  kid: string
+  use: `sig`
+  alg: `EdDSA`
+}
+
+export interface WebhookJwks {
+  keys: Array<WebhookPublicJwk>
+}
+
+/**
+ * Generate a unique wake ID.
+ */
+export function generateWakeId(): string {
+  return `w_${randomBytes(12).toString(`hex`)}`
+}
+
+const WEBHOOK_KEYPAIR = generateKeyPairSync(`ed25519`)
+const WEBHOOK_PUBLIC_JWK = buildWebhookPublicJwk()
+
+function buildWebhookPublicJwk(): WebhookPublicJwk {
+  const exported = WEBHOOK_KEYPAIR.publicKey.export({ format: `jwk` }) as {
+    kty?: string
+    crv?: string
+    x?: string
+  }
+
+  if (exported.kty !== `OKP` || exported.crv !== `Ed25519` || !exported.x) {
+    throw new Error(`Failed to export Ed25519 webhook signing key`)
+  }
+
+  const thumbprintInput = JSON.stringify({
+    crv: exported.crv,
+    kty: exported.kty,
+    x: exported.x,
+  })
+  const kid = `ds_${createHash(`sha256`)
+    .update(thumbprintInput)
+    .digest(`base64url`)}`
+
+  return {
+    kty: `OKP`,
+    crv: `Ed25519`,
+    x: exported.x,
+    kid,
+    use: `sig`,
+    alg: `EdDSA`,
+  }
+}
+
+export function getWebhookSigningKeyId(): string {
+  return WEBHOOK_PUBLIC_JWK.kid
+}
+
+export function getWebhookJwks(): WebhookJwks {
+  return {
+    keys: [{ ...WEBHOOK_PUBLIC_JWK }],
+  }
+}
+
+/**
+ * Sign a webhook payload for the Webhook-Signature header.
+ * Format: t=<timestamp>,kid=<key_id>,ed25519=<base64url_signature>
+ */
+export function signWebhookPayload(body: string): string {
+  const timestamp = Math.floor(Date.now() / 1000)
+  const payload = `${timestamp}.${body}`
+  const signature = sign(
+    null,
+    Buffer.from(payload),
+    WEBHOOK_KEYPAIR.privateKey
+  ).toString(`base64url`)
+  return `t=${timestamp},kid=${WEBHOOK_PUBLIC_JWK.kid},ed25519=${signature}`
+}
+
+/**
+ * Verify a webhook signature.
+ */
+export function verifyWebhookSignature(
+  body: string,
+  signatureHeader: string,
+  jwks: WebhookJwks = getWebhookJwks(),
+  toleranceSeconds = 300
+): boolean {
+  const match = signatureHeader.match(
+    /^t=(\d+),kid=([^,]+),ed25519=([A-Za-z0-9_-]+)$/
+  )
+  if (!match) return false
+
+  const [, timestamp, kid, signature] = match
+  const ts = parseInt(timestamp!, 10)
+
+  const now = Math.floor(Date.now() / 1000)
+  if (Math.abs(now - ts) > toleranceSeconds) return false
+
+  const jwk = jwks.keys.find((key) => key.kid === kid)
+  if (!jwk) return false
+
+  try {
+    const publicKey = createPublicKey({
+      key: jwk as unknown as NodeJsonWebKey,
+      format: `jwk`,
+    })
+    return verifySignature(
+      null,
+      Buffer.from(`${timestamp}.${body}`),
+      publicKey,
+      Buffer.from(signature!, `base64url`)
+    )
+  } catch {
+    return false
+  }
+}
+
+// Token signing key — generated per server instance
+const TOKEN_KEY = randomBytes(32)
+
+/**
+ * Generate a signed callback token.
+ * Token format: base64url(json_payload).base64url(hmac_signature)
+ * Payload: { consumer_id, epoch, exp }
+ */
+export function generateCallbackToken(
+  consumerId: string,
+  epoch: number
+): string {
+  const payload = {
+    sub: consumerId,
+    epoch,
+    exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour TTL
+    jti: randomBytes(8).toString(`hex`),
+  }
+  const payloadStr = Buffer.from(JSON.stringify(payload)).toString(`base64url`)
+  const sig = createHmac(`sha256`, TOKEN_KEY)
+    .update(payloadStr)
+    .digest(`base64url`)
+  return `${payloadStr}.${sig}`
+}
+
+/** Seconds before expiry at which a token should be refreshed. */
+const TOKEN_REFRESH_THRESHOLD = 300 // 5 minutes
+
+/**
+ * Validate a callback token. Returns the decoded payload or null.
+ * On success, includes `exp` (unix seconds) so callers can decide
+ * whether the token needs refreshing.
+ */
+export function validateCallbackToken(
+  token: string,
+  consumerId: string
+):
+  | { valid: true; exp: number; epoch: number }
+  | { valid: false; code: `TOKEN_INVALID` | `TOKEN_EXPIRED` } {
+  const parts = token.split(`.`)
+  if (parts.length !== 2) {
+    return { valid: false, code: `TOKEN_INVALID` }
+  }
+
+  const [payloadStr, sig] = parts
+
+  const expectedSig = createHmac(`sha256`, TOKEN_KEY)
+    .update(payloadStr!)
+    .digest(`base64url`)
+
+  try {
+    if (!timingSafeEqual(Buffer.from(sig!), Buffer.from(expectedSig))) {
+      return { valid: false, code: `TOKEN_INVALID` }
+    }
+  } catch {
+    return { valid: false, code: `TOKEN_INVALID` }
+  }
+
+  let payload: { sub: string; epoch: number; exp: number }
+  try {
+    payload = JSON.parse(Buffer.from(payloadStr!, `base64url`).toString())
+  } catch {
+    return { valid: false, code: `TOKEN_INVALID` }
+  }
+
+  if (payload.sub !== consumerId) {
+    return { valid: false, code: `TOKEN_INVALID` }
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+  if (now > payload.exp) {
+    return { valid: false, code: `TOKEN_EXPIRED` }
+  }
+
+  return { valid: true, exp: payload.exp, epoch: payload.epoch }
+}
+
+/**
+ * Check whether a token is close enough to expiry that it should be refreshed.
+ */
+export function tokenNeedsRefresh(exp: number): boolean {
+  const now = Math.floor(Date.now() / 1000)
+  return exp - now <= TOKEN_REFRESH_THRESHOLD
+}