@beignet/core 0.0.52 → 0.0.54

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/notifications/index.ts

@@ -1,4 +1,9 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ChannelDefinition } from "../broadcasting/index.js";
+import type {
+  BroadcastPort,
+  BroadcastPublication,
+} from "../broadcasting/server.js";
 import {
   createJobs,
   type JobDef,
@@ -1345,6 +1350,33 @@ export function defineMailNotificationChannel<
   };
 }
 
+/** Deliver a typed browser hint through the existing notification delivery pipeline.
+ * `sent` means provider acceptance, including when the recipient is offline.
+ * Return undefined to skip. Persistent inbox writes and their outbox ordering belong to the app.
+ */
+export function defineBroadcastNotificationChannel<
+  C extends ChannelDefinition,
+  Payload extends StandardSchema,
+  Ctx extends { ports: { broadcast: BroadcastPort } },
+>(options: {
+  channel: C;
+  render: (
+    args: NotificationChannelHandleArgs<Payload, Ctx>,
+  ) => MaybePromise<BroadcastPublication<NoInfer<C>> | undefined>;
+}): NotificationChannelHandler<Payload, Ctx> {
+  return async (args) => {
+    const publication = await options.render(args);
+    if (!publication)
+      return {
+        channel: args.channel,
+        status: "skipped",
+        reason: "No broadcast was returned.",
+      };
+    await args.ctx.ports.broadcast.publish(options.channel, publication);
+    return { channel: args.channel, status: "sent" };
+  };
+}
+
 /**
  * Create an in-memory notification port for tests and examples.
  *

package/src/ports/redaction.ts

@@ -28,6 +28,9 @@ export const DEFAULT_SENSITIVE_KEYS = [
   "accesskey",
   "jwt",
   "session",
+  "x-beignet-broadcast-client",
+  "broadcastorigin",
+  "excludeorigin",
 ] as const;
 
 /**

package/src/server/request-executor.ts

@@ -83,6 +83,7 @@ import {
 } from "./route-matching.js";
 import type { TrustedRequestInfo } from "./trusted-proxy.js";
 import { InvalidRequestUrlError } from "./trusted-proxy-internal.js";
+import { UseCaseRouteInputValidationError } from "./use-case-route.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -282,6 +283,24 @@ export function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof UseCaseRouteInputValidationError) {
+        return {
+          ctx,
+          response: errorResponse(
+            500,
+            currentError.code,
+            currentError.message,
+            {
+              contractName: currentError.contractName,
+              useCaseName: currentError.useCaseName,
+              location: "useCaseInput",
+            },
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       if (currentError instanceof InvalidRequestUrlError) {
         return {
           ctx,

package/src/server/server.ts

@@ -29,6 +29,7 @@ import { createContextFinalizer, resolveServerContext } from "./context.js";
 import type { ContractLike, ResolveContract } from "./contract-like.js";
 import { resolveContract } from "./contract-like.js";
 import type {
+  AddedCtxFromHooks,
   Handler,
   HttpRequestLike,
   HttpResponse,
@@ -312,7 +313,11 @@ export interface ServerInstance<
    * are not added to the route registry; mount the returned handler at the
    * route's own path.
    */
-  rawRoute: (init: RawRouteInit) => RawRouteBuilder<Ctx>;
+  rawRoute: <
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    init: RawRouteInit & { hooks?: Hooks },
+  ) => RawRouteBuilder<Ctx & AddedCtxFromHooks<Hooks>>;
   /**
    * Build a fully assembled request context from a framework-neutral request.
    *
@@ -960,9 +965,9 @@ export async function createServer<
           finalPorts,
           contextRuntime,
           rawRouteContract(init),
-          fn,
+          fn as Handler<Ctx, HttpContractConfig>,
           hooks,
-          [],
+          (init.hooks ?? []) as readonly RouteHook<unknown, object>[],
           { rawRoute: true },
         );
         // The adapter owns routing for raw routes — the handler is mounted

package/src/server/use-case-route.ts

@@ -149,20 +149,143 @@ export type UseCaseRouteInputParts<C extends HttpContractConfig> = {
   body: InferBody<C>;
 };
 
+type SegmentPathParam<Segment extends string> = Segment extends `:${infer Name}`
+  ? Name
+  : Segment extends `[${infer Name}]`
+    ? Name
+    : never;
+
+type PathParamNames<Path extends string> = string extends Path
+  ? never
+  : Path extends `${infer Segment}/${infer Rest}`
+    ? SegmentPathParam<Segment> | PathParamNames<Rest>
+    : SegmentPathParam<Path>;
+
+type EmptyBinderInput = Record<never, never>;
+
+declare const UNMERGEABLE_BINDER_INPUT: unique symbol;
+
+type UnmergeableBinderInput = {
+  readonly [UNMERGEABLE_BINDER_INPUT]: true;
+};
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type BinderObject<T> =
+  IsAny<T> extends true
+    ? UnmergeableBinderInput
+    : [T] extends [object]
+      ? [Extract<T, readonly unknown[]>] extends [never]
+        ? T
+        : UnmergeableBinderInput
+      : UnmergeableBinderInput;
+
+type MergeBinderObjects<LowerPrecedence, HigherPrecedence> = [
+  BinderObject<LowerPrecedence>,
+] extends [UnmergeableBinderInput]
+  ? UnmergeableBinderInput
+  : [BinderObject<HigherPrecedence>] extends [UnmergeableBinderInput]
+    ? UnmergeableBinderInput
+    : Omit<
+        BinderObject<LowerPrecedence>,
+        keyof BinderObject<HigherPrecedence>
+      > &
+        BinderObject<HigherPrecedence>;
+
+type InferredPathInput<C extends HttpContractConfig> = string extends C["path"]
+  ? UnmergeableBinderInput
+  : [PathParamNames<C["path"]>] extends [never]
+    ? EmptyBinderInput
+    : { [K in PathParamNames<C["path"]>]: string };
+
+type BinderPathInput<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1
+    ? InferOutput<C["pathParams"]>
+    : InferredPathInput<C>;
+
+type BinderQueryInput<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1
+    ? InferOutput<C["query"]>
+    : EmptyBinderInput;
+
+type BinderBodyInput<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1
+    ? InferOutput<C["body"]>
+    : EmptyBinderInput;
+
+type HasPathSchema<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1 ? true : false;
+
+type HasQuerySchema<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1 ? true : false;
+
+type HasBodySchema<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1 ? true : false;
+
+type HasInferredPathInput<C extends HttpContractConfig> =
+  string extends C["path"]
+    ? true
+    : [PathParamNames<C["path"]>] extends [never]
+      ? false
+      : true;
+
+type MergedBinderInput<C extends HttpContractConfig> = MergeBinderObjects<
+  MergeBinderObjects<BinderQueryInput<C>, BinderBodyInput<C>>,
+  BinderPathInput<C>
+>;
+
+/**
+ * Input produced when a binder route omits an explicit `input` mapper.
+ *
+ * A sole declared request schema passes through unchanged when the literal
+ * path has no additional inferred parameters. Every other supported default
+ * binding merges object inputs with path over body over query precedence.
+ */
+type DefaultBinderRouteInput<C extends HttpContractConfig> =
+  HasPathSchema<C> extends true
+    ? HasQuerySchema<C> extends true
+      ? MergedBinderInput<C>
+      : HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : BinderPathInput<C>
+    : HasQuerySchema<C> extends true
+      ? HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderQueryInput<C>
+      : HasBodySchema<C> extends true
+        ? HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderBodyInput<C>
+        : BinderPathInput<C>;
+
+type UseCaseRouteInputMode = "default" | "mapped";
+
 /**
  * Constraint that checks a use case against the route that binds it.
  *
  * Produces a readable branded mismatch object on the `useCase` property when
- * the use case requires a context the server does not provide, or when its
- * output does not match the contract's declared success response schema.
+ * the use case requires a context the server does not provide, when its
+ * output does not match the contract's declared success response schema, or
+ * when the default binder input does not satisfy the use case input.
  */
-export type UseCaseFitsRoute<Ctx, C extends HttpContractConfig, UC> = [
+export type UseCaseFitsRoute<
   Ctx,
-] extends [UseCaseRouteCtx<UC>]
+  C extends HttpContractConfig,
+  UC,
+  InputMode extends UseCaseRouteInputMode = "default",
+> = [Ctx] extends [UseCaseRouteCtx<UC>]
   ? [UseCaseRouteOutput<UC>] extends [
       SuccessBodyFromKeys<C["responses"], Success2xxKeys<C["responses"]>>,
     ]
-    ? unknown
+    ? InputMode extends "mapped"
+      ? unknown
+      : [DefaultBinderRouteInput<C>] extends [UseCaseRouteInput<UC>]
+        ? unknown
+        : {
+            "~beignetError": "default binder input does not match the use case input; add an input mapper";
+          }
     : {
         "~beignetError": "useCase output does not match the contract's success response schema";
       }
@@ -185,21 +308,34 @@ type UseCaseRouteShape<
    * Route-scoped hooks that run after group hooks and before the use case.
    */
   hooks?: Hooks;
-  /**
-   * Use case bound directly to the contract.
-   */
-  useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
-  /**
-   * Map parsed request parts to the use case input.
-   *
-   * A sole declared path, query, or body schema is passed through unchanged
-   * when no additional path, query, or object body values are present.
-   * Otherwise `defaultBinderInput` merges query, body, and path objects (path
-   * wins collisions) and never merges headers.
-   */
-  input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
   handle?: never;
-} & BinderStatusOption<C>;
+} & (
+  | {
+      /**
+       * Use case bound directly to the contract. The default binder input
+       * must satisfy the use case input type.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
+      input?: never;
+    }
+  | {
+      /**
+       * Use case bound directly to the contract through an explicit input
+       * mapper.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC, "mapped">;
+      /**
+       * Map parsed request parts to the use case input.
+       *
+       * A sole declared path, query, or body schema is passed through
+       * unchanged when no additional path, query, or object body values are
+       * present. Otherwise `defaultBinderInput` merges query, body, and path
+       * objects (path wins collisions) and never merges headers.
+       */
+      input: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+    }
+) &
+  BinderStatusOption<C>;
 
 /**
  * Route registration that binds a contract directly to a use case.
@@ -271,11 +407,25 @@ export type ValidatedRouteInput<Ctx, E> = E extends {
     ? {
         contract: CL;
         hooks?: HooksOf<E>;
-        useCase: UC &
-          UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
-        input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
         handle?: never;
-      } & BinderStatusOption<C>
+      } & (
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
+            input?: never;
+          }
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<
+                Ctx & AddedCtxFromHooks<HooksOf<E>>,
+                C,
+                UC,
+                "mapped"
+              >;
+            input: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+          }
+      ) &
+        BinderStatusOption<C>
     : unknown
   : unknown;
 
@@ -322,6 +472,49 @@ export type RuntimeUseCaseRouteDef = {
   status?: number;
 };
 
+type UseCaseInputValidationFailure = Error & {
+  name: "UseCaseValidationError";
+  phase: "input";
+  useCaseName: string;
+};
+
+function isUseCaseInputValidationFailure(
+  error: unknown,
+  useCaseName: string,
+): error is UseCaseInputValidationFailure {
+  if (!(error instanceof Error)) return false;
+  const candidate = error as Partial<UseCaseInputValidationFailure>;
+  return (
+    candidate.name === "UseCaseValidationError" &&
+    candidate.phase === "input" &&
+    candidate.useCaseName === useCaseName
+  );
+}
+
+/**
+ * Internal framework error raised when a type-erased binder route produces an
+ * input that the bound use case rejects.
+ */
+export class UseCaseRouteInputValidationError extends Error {
+  readonly code = "USE_CASE_INPUT_VALIDATION_ERROR";
+  readonly contractName: string;
+  readonly useCaseName: string;
+
+  constructor(args: {
+    contractName: string;
+    useCaseName: string;
+    cause: UseCaseInputValidationFailure;
+  }) {
+    super(
+      `Default binder input for contract "${args.contractName}" does not satisfy use case "${args.useCaseName}". Add an explicit input mapper.`,
+      { cause: args.cause },
+    );
+    this.name = "UseCaseRouteInputValidationError";
+    this.contractName = args.contractName;
+    this.useCaseName = args.useCaseName;
+  }
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -458,10 +651,24 @@ export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
         : defaultBinderInput(parts);
     const run = passSingle && trustedRun ? trustedRun : def.useCase.run;
 
-    return {
-      status,
-      body: await run.call(def.useCase, { ctx, input }),
-    };
+    try {
+      return {
+        status,
+        body: await run.call(def.useCase, { ctx, input }),
+      };
+    } catch (error) {
+      if (
+        !def.input &&
+        isUseCaseInputValidationFailure(error, def.useCase.name)
+      ) {
+        throw new UseCaseRouteInputValidationError({
+          contractName: contract.name,
+          useCaseName: def.useCase.name,
+          cause: error,
+        });
+      }
+      throw error;
+    }
   };
 
   return {