@beignet/core 0.0.52 → 0.0.54

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @beignet/core
 
+## 0.0.54
+
+### Patch Changes
+
+- b71b34f: Add typed, authorized browser broadcasting with bounded SSE connections, memory
+  and Redis providers, reconnect reconciliation, React Query invalidation,
+  initiating-client exclusion, notification delivery, and transactional inbox
+  scaffolding. Raw routes now preserve context added by route hooks.
+
+## 0.0.53
+
+### Patch Changes
+
+- 6ef881c: Reject incompatible default route-binder inputs at compile time and classify
+  type-erased runtime mismatches as framework-owned validation errors. Generated
+  resource cursors now remain optional at the request boundary and normalize to
+  nullable repository pagination state inside the use case.
+- e1a559d: Add authenticated string encryption through EncryptionPort and createEncryption, with optional context binding, decryption through previous keys, and non-sensitive failure errors. Add beignet encryption key for key generation, server import checks, and guidance for rotation and recovery.
+- edebbea: Add `@beignet/react-form`, a TanStack Form adapter that installs a contract body schema as a Standard Schema validator, types the `onServer` error slot, and maps client errors with `serverErrorMap`. `beignet lint` keeps the form packages out of domain and use-case code, `beignet doctor` expects `client/forms.ts` for either form adapter, and `beignet make feature --with ui` refuses to add React Hook Form components to an app that depends on `@beignet/react-form`.
+
 ## 0.0.52
 
 ### Patch Changes

package/README.md

@@ -11,7 +11,7 @@
 This package provides Beignet's framework primitives: contracts, server runtime,
 typed client, use cases, agent capabilities, ports, domain helpers, app errors, config, events,
 idempotency, locks, outbox, mail, notifications, payments, search, webhooks,
-feature flags, error reporting, schedules, uploads, entitlements, pagination
+feature flags, error reporting, encryption, broadcasting, schedules, uploads, entitlements, pagination
 helpers, testing helpers, and OpenAPI generation.
 
 ## Installation
@@ -50,11 +50,15 @@ name the framework area they depend on.
 | --- | --- |
 | `@beignet/core/agent-capabilities` | Typed agent capability definitions, registries, validation, and execution |
 | `@beignet/core/application` | Use case builder and test helpers |
+| `@beignet/core/broadcasting` | Browser-safe typed channel definitions and transport validation |
+| `@beignet/core/broadcasting/server` | BroadcastPort, authorization bindings, registry, and authenticated origins |
+| `@beignet/core/broadcasting/client` | Multiplexed streaming browser client with reconnect reconciliation |
 | `@beignet/core/client` | Typed HTTP client |
 | `@beignet/core/client-only` | Static lint marker for modules intended for client-side imports |
 | `@beignet/core/config` | Environment config validation |
 | `@beignet/core/contracts` | HTTP contract builders, types, path helpers, and contract metadata |
 | `@beignet/core/domain` | Entities, value objects, and domain events |
+| `@beignet/core/encryption` | Authenticated string encryption, EncryptionPort, and key generation |
 | `@beignet/core/entitlements` | Product access decision types, helpers, and static entitlement adapter |
 | `@beignet/core/error-reporting` | Error reporting port, memory adapter, no-op adapter, and helpers |
 | `@beignet/core/errors` | Error catalogs and response helpers |
@@ -85,6 +89,49 @@ name the framework area they depend on.
 | `@beignet/core/uploads/client` | Browser upload client for server and direct uploads |
 | `@beignet/core/webhooks` | Inbound webhook definitions, verifiers, memory test verifier, and HMAC verifier |
 
+## Encryption
+
+Use `createEncryption(...)` in server infra and expose `EncryptionPort` through
+your app ports. It uses Web Crypto AES-256-GCM with a random 96-bit IV and a
+128-bit authentication tag for each write.
+
+```typescript
+import { createEncryption } from "@beignet/core/encryption";
+import { env } from "@/lib/env";
+
+// Supply a persistent server secret from your validated environment config.
+const encryption = createEncryption({
+  key: env.ENCRYPTION_KEY,
+  previousKeys: env.ENCRYPTION_PREVIOUS_KEYS,
+});
+const context = { purpose: "integration-token", tenantId: "tenant-1" };
+const encrypted = await encryption.encrypt({ value: "example-token", context });
+const token = await encryption.decrypt({ value: encrypted, context });
+```
+
+Generate a persistent key with `beignet encryption key` or
+`generateEncryptionKey()`: canonical `base64:` plus 32 random bytes. All keys
+are validated synchronously. `key` encrypts new writes; `previousKeys` is an
+optional array used only for decryption. The methods accept strings and return
+`Promise<string>`. Optional `context` is a plain string record authenticated
+with the value; supply the same expected context when decrypting. It does not
+replace authorization.
+
+Store the complete opaque ciphertext in a text column. Malformed values,
+tampering, wrong keys, and context mismatches reject with
+`EncryptionDecryptionError` and a non-sensitive message. There is no plaintext
+fallback. The API emits no logs or telemetry.
+
+Keep keys outside client bundles and logs. Rotation does not rewrite existing
+data. Distribute a new decryption key to all readers before switching writes,
+retain old keys while records and backups require them, and test recovery.
+Losing a required key makes its ciphertext unreadable. This is field encryption,
+not password hashing or streaming file encryption. See the
+[encryption guide](https://beignetjs.com/encryption) for port wiring, rotation,
+recovery, and KMS boundaries.
+
+## Import boundaries
+
 Use boundary markers as side-effect imports so local linting and formatting do
 not treat them as unused symbols:
 
@@ -1132,7 +1179,7 @@ contracts should stay on explicit paths; catch-all contract patterns such as
 For routes that cannot be contracts at all — third-party callback endpoints
 with externally defined request shapes, signature-verified webhooks,
 streaming endpoints that own body consumption —
-`server.rawRoute({ name, method, path, metadata }).handle(fn)` builds a
+`server.rawRoute({ name, method, path, metadata, hooks }).handle(fn)` builds a
 handler that still runs the whole pipeline (hooks, context creation,
 instrumentation, framework error mapping) without contract parsing or
 validation. The request body stays unconsumed for the handler, `metadata`
@@ -2226,6 +2273,13 @@ explicit `input: (parts) => ...` mapper. When the use case `.input(...)`
 schema is the contract's sole request schema by reference, the server skips
 the use case's input re-parse — one schema, one parse.
 
+The route definition checks the inferred default binder input against the use
+case input type. Incompatible concrete shapes are compile errors with a prompt
+to add an explicit `input` mapper. If route types are deliberately erased and
+the default input still fails use-case validation at runtime, the server
+returns a framework-owned `500 USE_CASE_INPUT_VALIDATION_ERROR` rather than
+passing the failure through the app's unhandled-error mapper.
+
 Use `{ contract, handle }` as the escape hatch for response headers,
 streaming, and multi-status responses. `defineRoute` remains
 available for full handlers that read hook-added `ctx` fields.
@@ -2687,10 +2741,70 @@ field requiredness, descriptions, and constraints.
 - [`@beignet/next`](https://beignetjs.com/server) - Next.js server adapter
 - [`@beignet/react-query`](https://beignetjs.com/react-query) - TanStack Query integration
 - [`@beignet/react-hook-form`](https://beignetjs.com/react-hook-form) - React Hook Form integration
+- [`@beignet/react-form`](https://beignetjs.com/react-form) - TanStack Form integration
 - [`@beignet/react-uploads`](https://beignetjs.com/react-uploads) - React upload state and progress hooks
 - [`@beignet/nuqs`](https://beignetjs.com/nuqs) - URL query state integration with nuqs
 - [`@beignet/devtools`](https://beignetjs.com/devtools) - Local request, provider, and audit timeline
 
+## Broadcasting
+
+Define browser-safe channels with `defineChannel(name, { params, events })` from
+`@beignet/core/broadcasting`. Parameters parse to flat string records; event
+schemas produce stable canonical JSON. `BroadcastValidationError` rejects
+invalid data and non-idempotent transforms.
+
+On the server, import `BroadcastPort` and `createBroadcasting<AppContext>()`
+from `@beignet/core/broadcasting/server`. Its `defineChannelBinding` requires an
+explicit authorization callback for every channel, and `defineChannelRegistry`
+rejects duplicate names. Use memory or Redis providers and expose the registry
+with `createBroadcastRoute` from `@beignet/web` or `@beignet/next`.
+
+```ts
+import { defineChannel } from "@beignet/core/broadcasting";
+import { z } from "zod";
+
+export const changes = defineChannel("issues.changes", {
+  params: z.object({ workspaceId: z.string() }),
+  events: { changed: z.object({ issueId: z.string() }) },
+});
+```
+
+`broadcast.publish(changes, { params, event: "changed", data })` resolves on
+provider acceptance. `broadcast.subscribe(changes, { params, onEvent,
+onDisconnect })` returns `{ ready, unsubscribe }`; await readiness and cleanup.
+Publish after commit, or record a publication job in the transaction's outbox
+when the attempt must be retryable. Browser delivery is ephemeral.
+
+`createBroadcastClient({ url, headers?, credentials?, fetch? })` from
+`@beignet/core/broadcasting/client` shares one streaming Fetch connection.
+Subscribe with `{ params, onEvent, onSync, onError?, onStatusChange? }` and use
+`onSync` to refetch after initial readiness and recovery. Each subscription
+exposes `unsubscribe()` and `getStatus()`. The client also exposes `getStatus()`,
+`resume()`, `close()`, and `getRequestHeaders()` for opt-in origin exclusion.
+Create a fresh client on user/workspace changes. Callbacks that already started
+remain application-owned work after unsubscribe.
+
+`resolveBroadcastOrigin({ headers, principalId, tenantId, namespace })` binds
+the optional client header to authenticated server identity. Forward a captured
+origin through a job as `broadcastOrigin`, validate with `broadcastOriginSchema`
+when using Standard Schema directly, and pass it as `excludeOrigin` to publish.
+Use the same resolver on the stream endpoint. Missing, malformed, or anonymous
+origins disable exclusion. Default redaction hides origin headers and fields.
+
+`defineBroadcastNotificationChannel({ channel, render })` from
+`@beignet/core/notifications` publishes rendered notifications through the port;
+return `undefined` to skip. Existing preferences and per-channel retries apply.
+A sent result means provider acceptance. Persistent inbox writes and their
+publication jobs must share an app-owned transaction; independent notification
+channels have no execution ordering guarantee.
+
+The browser protocol has no replay IDs. Limits are 20 subscriptions, an 8 KiB
+encoded request, 64 KiB event data, 1 MiB buffers, 25-second heartbeats,
+10-second readiness waits, and streams renewed within 60 seconds. Terminal 4xx
+responses block until explicit resume; 429/5xx retry with jitter and respect
+`Retry-After`. Retry deadlines survive subscription changes. See the
+[broadcasting guide](https://beignetjs.com/broadcasting).
+
 ## License
 
 MIT

package/dist/broadcasting/client.d.ts

@@ -0,0 +1,38 @@
+import { type ChannelDefinition, type InferChannelEvent, type InferChannelParams } from "./index.js";
+export type BroadcastClientStatus = "connecting" | "connected" | "reconnecting" | "blocked" | "closed";
+/** Safe connection/protocol failure; application callback errors are reported separately. */
+export declare class BroadcastClientError extends Error {
+    readonly retryable: boolean;
+    readonly status?: number | undefined;
+    constructor(message: string, retryable: boolean, status?: number | undefined);
+}
+export interface BroadcastClientSubscription {
+    unsubscribe(): void;
+    getStatus(): BroadcastClientStatus;
+}
+export interface BroadcastClient {
+    subscribe<C extends ChannelDefinition>(channel: C, options: {
+        params: InferChannelParams<C>;
+        onEvent: (event: InferChannelEvent<C>) => void | Promise<void>;
+        /** Refetch authoritative state after initial readiness and every recovered connection. */
+        onSync: () => void | Promise<void>;
+        onError?: (error: unknown) => void;
+        onStatusChange?: (status: BroadcastClientStatus) => void;
+    }): BroadcastClientSubscription;
+    /** Merge these optional headers into the app's typed HTTP client to opt into exclusion. */
+    getRequestHeaders(): Record<string, string>;
+    getStatus(): BroadcastClientStatus;
+    /** Explicit app action after credentials/access change. Renewals never unblock denied subscriptions. */
+    resume(): void;
+    close(): void;
+}
+export interface BroadcastClientOptions {
+    url: string;
+    /** Resolved afresh for every request. Never place credentials in the URL. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    credentials?: RequestCredentials;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+/** One multiplexed streaming Fetch connection per instance. Create an instance per app auth session. */
+export declare function createBroadcastClient(options: BroadcastClientOptions): BroadcastClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/broadcasting/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/broadcasting/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAGxB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,WAAW,GACX,cAAc,GACd,SAAS,GACT,QAAQ,CAAC;AAEb,6FAA6F;AAC7F,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAFxB,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,OAAO,EAClB,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,IAAI,CAAC;IACpB,SAAS,IAAI,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,CAAC,SAAS,iBAAiB,EACnC,OAAO,EAAE,CAAC,EACV,OAAO,EAAE;QACP,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/D,0FAA0F;QAC1F,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;QACnC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;KAC1D,GACA,2BAA2B,CAAC;IAC/B,2FAA2F;IAC3F,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,SAAS,IAAI,qBAAqB,CAAC;IACnC,wGAAwG;IACxG,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAyDD,wGAAwG;AACxG,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAglBjB"}