@beignet/core 0.0.51 → 0.0.53

package/src/encryption/index.ts

@@ -0,0 +1,198 @@
+import "../server-only.js";
+
+/** Non-secret, authenticated metadata. Supply the same expected context on reads. */
+export type EncryptionContext = Readonly<Record<string, string>>;
+
+/** Options shared by string encryption and decryption. */
+export interface EncryptionValueOptions {
+  /** Plaintext for encrypt; the complete encrypted value for decrypt. */
+  value: string;
+  /** Bind the value to its purpose, tenant, or record. This is not authorization. */
+  context?: EncryptionContext;
+}
+
+/** Server-side authenticated string encryption. */
+export interface EncryptionPort {
+  /** Encrypt a string; persist the complete returned value. */
+  encrypt(options: EncryptionValueOptions): Promise<string>;
+  /** Authenticate and decrypt a value with the same expected context. */
+  decrypt(options: EncryptionValueOptions): Promise<string>;
+}
+
+/** Configuration for the built-in AES-256-GCM implementation. */
+export interface CreateEncryptionOptions {
+  /** A base64: prefixed, canonical Base64 encoding of 32 random bytes. */
+  key: string;
+  /** Decryption-only keys in the same format. New writes always use key. */
+  previousKeys?: readonly string[];
+}
+
+/** Malformed, unauthenticated, or undecryptable ciphertext. Contains no input. */
+export class EncryptionDecryptionError extends Error {
+  /** Stable error name, independent of the decryption failure's cause. */
+  readonly name = "EncryptionDecryptionError";
+
+  constructor() {
+    super("Unable to decrypt encrypted value.");
+  }
+}
+
+const envelopePrefix = "beignet:enc:v1:";
+const ivLength = 12;
+const tagLength = 16;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+function encodeBase64(bytes: Uint8Array): string {
+  // Bound each spread so large values do not overflow the argument stack.
+  const chunks: string[] = [];
+  for (let offset = 0; offset < bytes.length; offset += 8192) {
+    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 8192)));
+  }
+  return btoa(chunks.join(""));
+}
+
+function decodeBase64(value: string): Uint8Array<ArrayBuffer> {
+  if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+    throw new Error("Invalid Base64 encoding.");
+  }
+  const bytes = Uint8Array.from(atob(value), (character) =>
+    character.charCodeAt(0),
+  );
+  if (encodeBase64(bytes) !== value)
+    throw new Error("Noncanonical Base64 encoding.");
+  return bytes;
+}
+
+function decodeKey(value: string, label: string): Uint8Array<ArrayBuffer> {
+  try {
+    if (
+      typeof value !== "string" ||
+      value.length !== 51 ||
+      !value.startsWith("base64:")
+    )
+      throw new Error();
+    const bytes = decodeBase64(value.slice(7));
+    if (bytes.length !== 32) throw new Error();
+    return bytes;
+  } catch {
+    throw new TypeError(
+      `${label} must be base64: followed by the Base64 encoding of 32 bytes. Use generateEncryptionKey().`,
+    );
+  }
+}
+
+function authenticatedData(
+  context: EncryptionContext | undefined,
+): Uint8Array<ArrayBuffer> {
+  if (
+    context !== undefined &&
+    (context === null ||
+      typeof context !== "object" ||
+      (Object.getPrototypeOf(context) !== Object.prototype &&
+        Object.getPrototypeOf(context) !== null))
+  ) {
+    throw new TypeError(
+      "Encryption context must be a plain record of strings.",
+    );
+  }
+  const entries = Object.entries(context ?? {}).sort(([left], [right]) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+  if (entries.some(([, value]) => typeof value !== "string")) {
+    throw new TypeError("Encryption context values must be strings.");
+  }
+  return encoder.encode(JSON.stringify([envelopePrefix, entries]));
+}
+
+/** Generate a new 256-bit key. Store it in a server secret store; never log it. */
+export function generateEncryptionKey(): string {
+  return `base64:${encodeBase64(crypto.getRandomValues(new Uint8Array(32)))}`;
+}
+
+/**
+ * Create authenticated string encryption using Web Crypto AES-256-GCM.
+ * Configuration is validated synchronously. Each write uses a random 96-bit IV
+ * and a 128-bit authentication tag. Previous keys are used only for reads.
+ * No environment variables are read and no plaintext, keys, or context are logged.
+ */
+export function createEncryption(
+  options: CreateEncryptionOptions,
+): EncryptionPort {
+  const current = decodeKey(options?.key, "Encryption key");
+  if (
+    options.previousKeys !== undefined &&
+    !Array.isArray(options.previousKeys)
+  ) {
+    throw new TypeError("Encryption previousKeys must be an array of keys.");
+  }
+  const rawKeys = [
+    current,
+    ...Array.from(options.previousKeys ?? [], (key, index) =>
+      decodeKey(key, `Encryption previousKeys[${index}]`),
+    ),
+  ];
+  const importedKeys: Array<Promise<CryptoKey> | undefined> = [];
+  const getKey = (index: number): Promise<CryptoKey> => {
+    const existing = importedKeys[index];
+    if (existing) return existing;
+    const imported = crypto.subtle.importKey(
+      "raw",
+      rawKeys[index],
+      "AES-GCM",
+      false,
+      ["encrypt", "decrypt"],
+    );
+    importedKeys[index] = imported;
+    return imported;
+  };
+
+  return {
+    async encrypt({ value, context }) {
+      if (typeof value !== "string")
+        throw new TypeError("Encryption value must be a string.");
+      const additionalData = authenticatedData(context);
+      const iv = crypto.getRandomValues(new Uint8Array(ivLength));
+      const ciphertext = new Uint8Array(
+        await crypto.subtle.encrypt(
+          { name: "AES-GCM", iv, additionalData, tagLength: tagLength * 8 },
+          await getKey(0),
+          // JSON preserves all JavaScript strings, including lone UTF-16 surrogates.
+          encoder.encode(JSON.stringify(value)),
+        ),
+      );
+      const envelope = new Uint8Array(iv.length + ciphertext.length);
+      envelope.set(iv);
+      envelope.set(ciphertext, iv.length);
+      return `${envelopePrefix}${encodeBase64(envelope)}`;
+    },
+    async decrypt(options) {
+      try {
+        const { value, context } = options;
+        if (typeof value !== "string" || !value.startsWith(envelopePrefix))
+          throw new Error();
+        const envelope = decodeBase64(value.slice(envelopePrefix.length));
+        if (envelope.length < ivLength + tagLength + 2) throw new Error();
+        const additionalData = authenticatedData(context);
+        const iv = envelope.slice(0, ivLength);
+        const ciphertext = envelope.slice(ivLength);
+        for (let index = 0; index < rawKeys.length; index++) {
+          try {
+            const plaintext = await crypto.subtle.decrypt(
+              { name: "AES-GCM", iv, additionalData, tagLength: tagLength * 8 },
+              await getKey(index),
+              ciphertext,
+            );
+            const parsed: unknown = JSON.parse(decoder.decode(plaintext));
+            if (typeof parsed === "string") return parsed;
+          } catch {
+            // Try only the configured key ring; never return unauthenticated data.
+          }
+        }
+      } catch {
+        // All decryption failures share one non-sensitive public error.
+      }
+      throw new EncryptionDecryptionError();
+    },
+  };
+}

package/src/events/index.ts

@@ -7,8 +7,21 @@ import {
 } from "../tracing/index.js";
 import {
   isEventPayloadParsed,
-  markEventPayloadParsed,
+  isEventPayloadTransportStable,
+  markEventPayloadTransportStable,
 } from "./payload-state.js";
+import {
+  EventTransportError,
+  type EventTransportValue,
+  eventTransportValuesEqual,
+  toEventTransportValue,
+} from "./transport.js";
+
+export {
+  EventTransportError,
+  type EventTransportErrorReason,
+  type EventTransportValue,
+} from "./transport.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -299,6 +312,18 @@ export class EventValidationError extends Error {
   }
 }
 
+/**
+ * Parsed runtime value and canonical JSON value for one event publication.
+ */
+export interface PreparedEventPayload<E extends EventPayloadDef> {
+  /** Parsed Standard Schema output delivered to in-process listeners. */
+  readonly payload: InferEventPayload<E>;
+  /** Canonical JSON value written by serialized transports. */
+  readonly transportValue: EventTransportValue;
+  /** Complete publish metadata to forward to in-process subscribers. */
+  readonly publishOptions: EventPublishOptions;
+}
+
 function formatPath(path: StandardSchemaV1.Issue["path"]): string {
   if (!path?.length) return "";
 
@@ -345,7 +370,9 @@ async function parsePayload<Schema extends StandardSchemaV1>(
  * Define a typed event.
  *
  * Event payloads are validated before publishing through `publishEvent(...)`
- * and before registered listeners run.
+ * and before registered listeners run. Producer helpers also require parsed
+ * output to be plain JSON that remains unchanged when validated again after a
+ * transport round trip.
  */
 export function defineEvent<
   Name extends string,
@@ -388,7 +415,101 @@ export async function parseEventPayload<E extends EventPayloadDef>(
 }
 
 /**
- * Validate an event payload and publish it through an event bus.
+ * Parse an event payload and prove that its canonical JSON survives transport.
+ *
+ * Custom event-bus providers must call this before publishing. The returned
+ * runtime payload is suitable for in-process listeners; `transportValue` is
+ * the exact JSON-safe value to encode for a serialized transport.
+ */
+export async function prepareEventPayloadForTransport<
+  E extends EventPayloadDef,
+>(
+  event: E,
+  payload: unknown,
+  options?: EventPublishOptions,
+): Promise<PreparedEventPayload<E>> {
+  const parsed = isEventPayloadParsed(event, payload, options)
+    ? (payload as InferEventPayload<E>)
+    : await parseEventPayload(event, payload);
+  const transportValue = toEventTransportValue(event.name, parsed);
+  let canonicalPayload = parsed;
+  let transportStateIsCurrent = false;
+
+  try {
+    transportStateIsCurrent = isEventPayloadTransportStable(
+      event,
+      parsed,
+      transportValue,
+      options,
+    );
+  } catch {
+    // Revalidate if a mutated or proxied payload can no longer be compared.
+  }
+
+  if (!transportStateIsCurrent) {
+    let reparsed: InferEventPayload<E>;
+    try {
+      reparsed = await parseEventPayload(event, transportValue);
+    } catch (error) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        message:
+          "is not transport-stable: its canonical JSON failed validation when decoded again. Event schemas must accept their own canonical JSON output.",
+        cause: error,
+      });
+    }
+
+    let reparsedTransportValue: EventTransportValue;
+    try {
+      reparsedTransportValue = toEventTransportValue(event.name, reparsed);
+    } catch (error) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        path: error instanceof EventTransportError ? error.path : undefined,
+        message:
+          "is not transport-stable: validating its canonical JSON produced a value that is not JSON-safe.",
+        cause: error,
+      });
+    }
+
+    if (!eventTransportValuesEqual(transportValue, reparsedTransportValue)) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        message:
+          "is not transport-stable: its canonical JSON changed when validated again. Event schema transforms must be idempotent.",
+      });
+    }
+    canonicalPayload = reparsed;
+  }
+
+  try {
+    return {
+      payload: canonicalPayload,
+      transportValue,
+      publishOptions: markEventPayloadTransportStable(
+        event,
+        canonicalPayload,
+        transportValue,
+        options,
+      ),
+    };
+  } catch (error) {
+    throw new EventTransportError({
+      eventName: event.name,
+      reason: "not-stable",
+      message:
+        "is not transport-stable: its canonical output could not be inspected consistently.",
+      cause: error,
+    });
+  }
+}
+
+/**
+ * Validate an event payload, prove transport stability, and publish it through
+ * an event bus.
  */
 export async function publishEvent<E extends EventPayloadDef>(
   eventBus: EventBusLike,
@@ -396,8 +517,12 @@ export async function publishEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options?: EventPublishOptions,
 ): Promise<void> {
-  const parsed = await parseEventPayload(event, payload);
-  await eventBus.publish(event, parsed, markEventPayloadParsed(options));
+  const prepared = await prepareEventPayloadForTransport(
+    event,
+    payload,
+    options,
+  );
+  await eventBus.publish(event, prepared.payload, prepared.publishOptions);
 }
 
 function assertReadyTimeoutMs(value: number): void {
@@ -490,9 +615,11 @@ export function registerListeners<Ctx>(
           listener.event,
           async (rawPayload, publishOptions) => {
             try {
-              const payload = isEventPayloadParsed(publishOptions)
-                ? rawPayload
-                : await parseEventPayload(listener.event, rawPayload);
+              const prepared = await prepareEventPayloadForTransport(
+                listener.event,
+                rawPayload,
+                publishOptions,
+              );
               const traceAttributes = {
                 "beignet.listener.name": listener.name,
                 "beignet.event.name": listener.event.name,
@@ -504,14 +631,14 @@ export function registerListeners<Ctx>(
                   name: `beignet.listener ${listener.name}`,
                   type: "listener",
                   kind: "consumer",
-                  parent: parseTraceCarrier(publishOptions?.trace),
+                  parent: parseTraceCarrier(prepared.publishOptions.trace),
                   attributes: traceAttributes,
                   metricAttributes: traceAttributes,
                 },
                 run: (ctx) =>
                   listener.handle({
                     event: listener.event,
-                    payload,
+                    payload: prepared.payload,
                     ctx,
                   }),
               });

package/src/events/payload-state.ts

@@ -1,24 +1,223 @@
 import type { EventPublishOptions } from "./index.js";
+import type { EventTransportValue } from "./transport.js";
 
 const PARSED_EVENT_PAYLOAD = Symbol.for("beignet.eventPayload.parsed");
+const TRANSPORT_STABLE_EVENT_PAYLOAD = Symbol.for(
+  "beignet.eventPayload.transportStable",
+);
 
 type ParsedEventPublishOptions = EventPublishOptions & {
-  [PARSED_EVENT_PAYLOAD]?: true;
+  [PARSED_EVENT_PAYLOAD]?: object;
+  [TRANSPORT_STABLE_EVENT_PAYLOAD]?: object;
 };
 
+interface ParsedPayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: unknown;
+}
+
+type PayloadSnapshot =
+  | { readonly kind: "primitive"; readonly value: unknown }
+  | {
+      readonly kind: "array";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly items: readonly PayloadSnapshot[];
+    }
+  | {
+      readonly kind: "object";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly entries: readonly (readonly [string, PayloadSnapshot])[];
+    };
+
+interface TransportStablePayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: PayloadSnapshot;
+  readonly fingerprint: string;
+}
+
+interface EventPayloadIdentity {
+  readonly name: string;
+  readonly payload: {
+    readonly "~standard": {
+      readonly validate: unknown;
+    };
+  };
+}
+
+const transportStablePayloadStates = new WeakMap<
+  object,
+  TransportStablePayloadState
+>();
+const parsedPayloadStates = new WeakMap<object, ParsedPayloadState>();
+
+function transportFingerprint(value: EventTransportValue): string {
+  return JSON.stringify(value);
+}
+
+function capturePayloadSnapshot(value: unknown): PayloadSnapshot {
+  if (value === null || typeof value !== "object") {
+    return { kind: "primitive", value };
+  }
+  if (Array.isArray(value)) {
+    const items: PayloadSnapshot[] = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable array state must contain data properties.",
+        );
+      }
+      items.push(capturePayloadSnapshot(descriptor.value));
+    }
+    return {
+      kind: "array",
+      value,
+      prototype: Object.getPrototypeOf(value),
+      items,
+    };
+  }
+  return {
+    kind: "object",
+    value,
+    prototype: Object.getPrototypeOf(value),
+    entries: Reflect.ownKeys(value).map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (typeof key !== "string" || !descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable payload state must contain data properties.",
+        );
+      }
+      return [key, capturePayloadSnapshot(descriptor.value)] as const;
+    }),
+  };
+}
+
+function matchesPayloadSnapshot(
+  snapshot: PayloadSnapshot,
+  value: unknown,
+): boolean {
+  if (snapshot.kind === "primitive") return Object.is(snapshot.value, value);
+  if (snapshot.value !== value || value === null || typeof value !== "object") {
+    return false;
+  }
+  if (Object.getPrototypeOf(value) !== snapshot.prototype) return false;
+  if (snapshot.kind === "array") {
+    return (
+      Array.isArray(value) &&
+      value.length === snapshot.items.length &&
+      snapshot.items.every((item, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          value,
+          String(index),
+        );
+        return (
+          descriptor !== undefined &&
+          "value" in descriptor &&
+          matchesPayloadSnapshot(item, descriptor.value)
+        );
+      })
+    );
+  }
+  if (Array.isArray(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  return (
+    keys.length === snapshot.entries.length &&
+    snapshot.entries.every(([key, item], index) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return (
+        keys[index] === key &&
+        descriptor !== undefined &&
+        "value" in descriptor &&
+        matchesPayloadSnapshot(item, descriptor.value)
+      );
+    })
+  );
+}
+
 export function markEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
   options?: EventPublishOptions,
 ): EventPublishOptions {
+  const token = {};
+  parsedPayloadStates.set(token, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
   return {
     ...options,
-    [PARSED_EVENT_PAYLOAD]: true,
+    [PARSED_EVENT_PAYLOAD]: token,
   } as ParsedEventPublishOptions;
 }
 
-export function isEventPayloadParsed(options?: EventPublishOptions): boolean {
+export function isEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    PARSED_EVENT_PAYLOAD
+  ];
+  const state = token ? parsedPayloadStates.get(token) : undefined;
+  return (
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    Object.is(state.payload, payload)
+  );
+}
+
+export function markEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): EventPublishOptions {
+  const parsedToken = {};
+  parsedPayloadStates.set(parsedToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
+  const stableToken = {};
+  transportStablePayloadStates.set(stableToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload: capturePayloadSnapshot(payload),
+    fingerprint: transportFingerprint(transportValue),
+  });
+  return {
+    ...options,
+    [PARSED_EVENT_PAYLOAD]: parsedToken,
+    [TRANSPORT_STABLE_EVENT_PAYLOAD]: stableToken,
+  } as ParsedEventPublishOptions;
+}
+
+export function isEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    TRANSPORT_STABLE_EVENT_PAYLOAD
+  ];
+  const state = token ? transportStablePayloadStates.get(token) : undefined;
   return (
-    (options as ParsedEventPublishOptions | undefined)?.[
-      PARSED_EVENT_PAYLOAD
-    ] === true
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    matchesPayloadSnapshot(state.payload, payload) &&
+    state.fingerprint === transportFingerprint(transportValue)
   );
 }