@beignet/core 0.0.52 → 0.0.54

package/dist/broadcasting/index.js

@@ -0,0 +1,87 @@
+import { eventTransportValuesEqual, toEventTransportValue, } from "../events/transport.js";
+/** Fixed protocol limits shared by clients, endpoints, and providers. */
+export const broadcastLimits = Object.freeze({
+    subscriptions: 20,
+    requestBytes: 8_192,
+    payloadBytes: 65_536,
+    bufferedBytes: 1_048_576,
+    maxLifetimeMs: 60_000,
+    heartbeatMs: 25_000,
+    readyTimeoutMs: 10_000,
+});
+/** Invalid channel configuration or untrusted protocol input. */
+export class BroadcastValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BroadcastValidationError";
+    }
+}
+const namePattern = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+export function defineChannel(name, options) {
+    if (!namePattern.test(name))
+        throw new BroadcastValidationError("Invalid broadcast channel name");
+    const events = Object.entries(options.events);
+    if (!events.length || events.some(([event]) => !namePattern.test(event))) {
+        throw new BroadcastValidationError(`Channel ${name} needs valid event names`);
+    }
+    return Object.freeze({
+        kind: "channel",
+        name,
+        params: options.params,
+        events: Object.freeze({ ...options.events }),
+    });
+}
+/** Validate both sides of a transport boundary; schema transforms must be stable. */
+async function parseStable(schema, input, label) {
+    try {
+        const parsed = await schema["~standard"].validate(input);
+        if (parsed.issues)
+            throw new BroadcastValidationError(`Invalid ${label}`);
+        const canonical = toEventTransportValue(label, parsed.value);
+        const second = await schema["~standard"].validate(canonical);
+        if (second.issues ||
+            !eventTransportValuesEqual(canonical, toEventTransportValue(label, second.value))) {
+            throw new BroadcastValidationError(`Unstable transport schema for ${label}`);
+        }
+        return canonical;
+    }
+    catch (error) {
+        if (error instanceof BroadcastValidationError)
+            throw error;
+        throw new BroadcastValidationError(`Invalid ${label}`);
+    }
+}
+/** Provider and transport boundary validation. Uses parsed, canonical parameters. */
+export async function parseChannelParams(channel, input) {
+    const parsed = await parseStable(channel.params, input, `${channel.name} parameters`);
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed) ||
+        Object.values(parsed).some((value) => typeof value !== "string")) {
+        throw new BroadcastValidationError(`Channel ${channel.name} parameters must be a flat string record`);
+    }
+    if (new TextEncoder().encode(JSON.stringify(parsed)).byteLength >
+        broadcastLimits.requestBytes) {
+        throw new BroadcastValidationError(`Channel ${channel.name} parameters are too large`);
+    }
+    return parsed;
+}
+/** Provider and browser boundary validation. Event names select their schema. */
+export async function parseChannelEvent(channel, input) {
+    if (!Object.hasOwn(channel.events, input.event))
+        throw new BroadcastValidationError(`Unknown event on channel ${channel.name}`);
+    const data = await parseStable(channel.events[input.event], input.data, `${channel.name}.${input.event}`);
+    if (new TextEncoder().encode(JSON.stringify(data)).byteLength >
+        broadcastLimits.payloadBytes) {
+        throw new BroadcastValidationError(`Channel ${channel.name} payload is too large`);
+    }
+    return { event: input.event, data };
+}
+/** Collision-free identity independent of parameter property order. Parse parameters first. */
+export function channelKey(channel, params) {
+    return JSON.stringify([
+        channel,
+        Object.entries(params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ]);
+}
+//# sourceMappingURL=index.js.map

package/dist/broadcasting/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/broadcasting/index.ts"],"names":[],"mappings":"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"}

package/dist/broadcasting/server.d.ts

@@ -0,0 +1,83 @@
+import "../server-only.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type ChannelDefinition, type InferChannelEvent, type InferChannelParams } from "./index.js";
+/** Server-authenticated scope captured at the originating HTTP boundary. JSON-safe for jobs. */
+export interface BroadcastOrigin {
+    readonly version: 1;
+    readonly clientId: string;
+    readonly scope: string;
+}
+/** Validate an origin already captured by a trusted server for a job payload. */
+export declare const broadcastOriginSchema: StandardSchemaV1<unknown, BroadcastOrigin>;
+/** Never derive principal, tenant, or namespace from the optional client header. */
+export declare function resolveBroadcastOrigin(options: {
+    headers: Headers;
+    principalId?: string | null;
+    tenantId?: string | null;
+    namespace: string;
+}): BroadcastOrigin | undefined;
+export type BroadcastPublication<C extends ChannelDefinition> = InferChannelEvent<C> & {
+    params: InferChannelParams<C>;
+    excludeOrigin?: BroadcastOrigin;
+};
+/** Readiness proves initial subscription only. Continuity loss requires reconnect and refetch. */
+export interface BroadcastSubscription {
+    readonly ready: Promise<void>;
+    unsubscribe(): Promise<void>;
+}
+export interface BroadcastPort {
+    /** Resolves when accepted by the provider, including when nobody is subscribed. */
+    publish<C extends ChannelDefinition>(channel: C, publication: BroadcastPublication<C>): Promise<void>;
+    subscribe<C extends ChannelDefinition>(channel: C, options: {
+        params: InferChannelParams<C>;
+        onEvent: (event: InferChannelEvent<C>, metadata: {
+            excludeOrigin?: BroadcastOrigin;
+        }) => void;
+        onDisconnect: () => void;
+    }): BroadcastSubscription;
+}
+/** Internal transport envelope carried by broadcast providers, never a browser payload. */
+export interface BroadcastEnvelope {
+    version: 1;
+    channel: string;
+    params: Record<string, string>;
+    event: string;
+    data: unknown;
+    excludeOrigin?: BroadcastOrigin;
+}
+/** Low-level adapter contract. Subscription callbacks must be isolated from publishers. */
+export interface BroadcastTransport {
+    publish(key: string, envelope: BroadcastEnvelope): Promise<void>;
+    subscribe(key: string, options: {
+        onMessage: (envelope: unknown) => void;
+        onDisconnect: () => void;
+    }): BroadcastSubscription;
+}
+/** Shared validation and cleanup for provider implementations. */
+export declare function createBroadcastPort(transport: BroadcastTransport): BroadcastPort;
+export interface ChannelBinding<Ctx> {
+    readonly kind: "channel-binding";
+    readonly channel: ChannelDefinition;
+    authorize: (args: {
+        ctx: Ctx;
+        params: Record<string, string>;
+    }) => void | Promise<void>;
+}
+export interface ChannelRegistry<Ctx> {
+    readonly kind: "channel-registry";
+    readonly bindings: readonly ChannelBinding<Ctx>[];
+    get(name: string): ChannelBinding<Ctx> | undefined;
+}
+/** Bind every channel explicitly, including public channels. */
+export declare function createBroadcasting<Ctx>(): {
+    defineChannelBinding: <C extends ChannelDefinition>(channel: C, options: {
+        authorize: (args: {
+            ctx: Ctx;
+            params: InferChannelParams<C>;
+        }) => void | Promise<void>;
+    }) => ChannelBinding<Ctx>;
+    defineChannelRegistry: (bindings: readonly ChannelBinding<Ctx>[]) => ChannelRegistry<Ctx>;
+};
+/** Validate a configurable deadline without allowing an unbounded stream. */
+export declare function broadcastLifetime(value?: number): number;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/broadcasting/server.ts"],"names":[],"mappings":"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"}

package/dist/broadcasting/server.js

@@ -0,0 +1,213 @@
+import "../server-only.js";
+import { BroadcastValidationError, broadcastLimits, channelKey, parseChannelEvent, parseChannelParams, } from "./index.js";
+const clientIdPattern = /^[a-zA-Z0-9_-]{22,128}$/;
+function parseOrigin(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value;
+    if (candidate.version !== 1 ||
+        typeof candidate.clientId !== "string" ||
+        !clientIdPattern.test(candidate.clientId) ||
+        typeof candidate.scope !== "string" ||
+        candidate.scope.length === 0 ||
+        candidate.scope.length > 2_048)
+        return undefined;
+    return { version: 1, clientId: candidate.clientId, scope: candidate.scope };
+}
+/** Validate an origin already captured by a trusted server for a job payload. */
+export const broadcastOriginSchema = {
+    "~standard": {
+        version: 1,
+        vendor: "beignet",
+        validate(value) {
+            const origin = parseOrigin(value);
+            return origin
+                ? { value: origin }
+                : { issues: [{ message: "Invalid broadcast origin" }] };
+        },
+    },
+};
+/** Never derive principal, tenant, or namespace from the optional client header. */
+export function resolveBroadcastOrigin(options) {
+    if (!options.principalId || !options.namespace)
+        return undefined;
+    return parseOrigin({
+        version: 1,
+        clientId: options.headers.get("X-Beignet-Broadcast-Client"),
+        scope: JSON.stringify([
+            options.namespace,
+            options.tenantId ?? null,
+            options.principalId,
+        ]),
+    });
+}
+/** Shared validation and cleanup for provider implementations. */
+export function createBroadcastPort(transport) {
+    return {
+        async publish(channel, publication) {
+            const params = await parseChannelParams(channel, publication.params);
+            const event = await parseChannelEvent(channel, publication);
+            const excludeOrigin = publication.excludeOrigin === undefined
+                ? undefined
+                : parseOrigin(publication.excludeOrigin);
+            if (publication.excludeOrigin !== undefined && !excludeOrigin)
+                throw new BroadcastValidationError("Invalid broadcast origin");
+            await transport.publish(channelKey(channel.name, params), {
+                version: 1,
+                channel: channel.name,
+                params,
+                ...event,
+                ...(excludeOrigin ? { excludeOrigin } : {}),
+            });
+        },
+        subscribe(channel, options) {
+            let stopped = false;
+            let failed = false;
+            let subscription;
+            let queued = 0;
+            let queuedBytes = 0;
+            let pending = Promise.resolve();
+            let cancel;
+            let cleanup;
+            const release = () => (cleanup ??= subscription?.unsubscribe() ?? Promise.resolve());
+            const disconnect = () => {
+                if (stopped || failed)
+                    return;
+                failed = true;
+                try {
+                    options.onDisconnect();
+                }
+                catch {
+                    /* Consumer callbacks cannot break provider lifecycle. */
+                }
+            };
+            const initialize = (async () => {
+                const params = await parseChannelParams(channel, options.params);
+                if (stopped)
+                    return;
+                const key = channelKey(channel.name, params);
+                subscription = transport.subscribe(key, {
+                    onDisconnect: disconnect,
+                    onMessage(value) {
+                        if (stopped || failed)
+                            return;
+                        let bytes;
+                        try {
+                            bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+                        }
+                        catch {
+                            disconnect();
+                            return;
+                        }
+                        if (bytes >
+                            broadcastLimits.payloadBytes +
+                                broadcastLimits.requestBytes +
+                                16_384 ||
+                            queuedBytes + bytes > broadcastLimits.bufferedBytes) {
+                            disconnect();
+                            return;
+                        }
+                        if (++queued > 128) {
+                            disconnect();
+                            return;
+                        }
+                        queuedBytes += bytes;
+                        pending = pending
+                            .then(async () => {
+                            if (stopped || failed)
+                                return;
+                            if (!value || typeof value !== "object")
+                                throw new BroadcastValidationError("Invalid broadcast envelope");
+                            const envelope = value;
+                            if (envelope.version !== 1 || envelope.channel !== channel.name)
+                                throw new BroadcastValidationError("Invalid broadcast envelope");
+                            const receivedParams = await parseChannelParams(channel, envelope.params);
+                            if (channelKey(channel.name, receivedParams) !== key)
+                                throw new BroadcastValidationError("Broadcast channel mismatch");
+                            const event = await parseChannelEvent(channel, envelope);
+                            const excludeOrigin = envelope.excludeOrigin === undefined
+                                ? undefined
+                                : parseOrigin(envelope.excludeOrigin);
+                            if (envelope.excludeOrigin !== undefined && !excludeOrigin)
+                                throw new BroadcastValidationError("Invalid broadcast origin");
+                            if (!stopped && !failed)
+                                await options.onEvent(event, { excludeOrigin });
+                        })
+                            .catch(disconnect)
+                            .finally(() => {
+                            queued--;
+                            queuedBytes -= bytes;
+                        });
+                    },
+                });
+                await subscription.ready;
+                if (stopped)
+                    await release();
+                if (failed)
+                    throw new Error("Broadcast subscription lost continuity before readiness");
+            })();
+            let timeout;
+            const ready = Promise.race([
+                initialize,
+                new Promise((_, reject) => {
+                    cancel = () => reject(new Error("Broadcast subscription cancelled"));
+                    timeout = setTimeout(() => reject(new Error("Broadcast subscription readiness timed out")), broadcastLimits.readyTimeoutMs);
+                }),
+            ])
+                .catch((error) => {
+                stopped = true;
+                void release().catch(() => undefined);
+                throw error;
+            })
+                .finally(() => {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                cancel = undefined;
+            });
+            // Callers still observe rejection through ready; early cancellation must not leak a rejection.
+            void ready.catch(() => undefined);
+            return {
+                ready,
+                async unsubscribe() {
+                    stopped = true;
+                    cancel?.();
+                    await ready.catch(() => undefined);
+                    await release();
+                },
+            };
+        },
+    };
+}
+/** Bind every channel explicitly, including public channels. */
+export function createBroadcasting() {
+    function defineChannelBinding(channel, options) {
+        return Object.freeze({
+            kind: "channel-binding",
+            channel,
+            authorize: ({ ctx, params, }) => options.authorize({ ctx, params: params }),
+        });
+    }
+    function defineChannelRegistry(bindings) {
+        const byName = new Map();
+        for (const binding of bindings) {
+            if (byName.has(binding.channel.name))
+                throw new BroadcastValidationError(`Duplicate channel ${binding.channel.name}`);
+            byName.set(binding.channel.name, binding);
+        }
+        return Object.freeze({
+            kind: "channel-registry",
+            bindings: Object.freeze([...bindings]),
+            get: (name) => byName.get(name),
+        });
+    }
+    return { defineChannelBinding, defineChannelRegistry };
+}
+/** Validate a configurable deadline without allowing an unbounded stream. */
+export function broadcastLifetime(value = broadcastLimits.maxLifetimeMs) {
+    if (!Number.isInteger(value) ||
+        value < 1 ||
+        value > broadcastLimits.maxLifetimeMs)
+        throw new BroadcastValidationError("Broadcast maxLifetimeMs must be between 1 and 60000");
+    return value;
+}
+//# sourceMappingURL=server.js.map

package/dist/broadcasting/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/broadcasting/server.ts"],"names":[],"mappings":"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"}

package/dist/encryption/index.d.ts

@@ -0,0 +1,40 @@
+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 declare class EncryptionDecryptionError extends Error {
+    /** Stable error name, independent of the decryption failure's cause. */
+    readonly name = "EncryptionDecryptionError";
+    constructor();
+}
+/** Generate a new 256-bit key. Store it in a server secret store; never log it. */
+export declare function generateEncryptionKey(): string;
+/**
+ * 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 declare function createEncryption(options: CreateEncryptionOptions): EncryptionPort;
+//# sourceMappingURL=index.d.ts.map

package/dist/encryption/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/encryption/index.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAmB,CAAC;AAE3B,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,wEAAwE;IACxE,QAAQ,CAAC,IAAI,+BAA+B;;CAK7C;AAsED,mFAAmF;AACnF,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CA6EhB"}

package/dist/encryption/index.js

@@ -0,0 +1,134 @@
+import "../server-only.js";
+/** Malformed, unauthenticated, or undecryptable ciphertext. Contains no input. */
+export class EncryptionDecryptionError extends Error {
+    /** Stable error name, independent of the decryption failure's cause. */
+    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) {
+    // Bound each spread so large values do not overflow the argument stack.
+    const chunks = [];
+    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) {
+    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, label) {
+    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) {
+    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() {
+    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) {
+    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 = [];
+    const getKey = (index) => {
+        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 = 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();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/encryption/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/encryption/index.ts"],"names":[],"mappings":"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"}

package/dist/notifications/index.d.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ChannelDefinition } from "../broadcasting/index.js";
+import type { BroadcastPort, BroadcastPublication } from "../broadcasting/server.js";
 import { type JobDef, type JobDispatcher, type JobHook, type JobRetryOptions, type JobTimeoutDuration } from "../jobs/index.js";
 import type { SendMailOptions } from "../mail/index.js";
 import type { ProviderInstrumentationTarget } from "../providers/index.js";
@@ -557,6 +559,18 @@ export declare function createQueuedNotificationsProvider<Name extends string, C
  * example when a recipient does not have an email address.
  */
 export declare function defineMailNotificationChannel<Payload extends StandardSchema, Ctx extends MailNotificationContext>(render: MailNotificationRenderer<Payload, Ctx>): NotificationChannelHandler<Payload, Ctx>;
+/** 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 declare 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>;
 /**
  * Create an in-memory notification port for tests and examples.
  *