@lunora/runtime 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/index.d.mts

@@ -337,6 +337,116 @@ interface FunctionArgumentDescriptor {
 * kind only — enough for a signature view without a deep recursive walk.
 */
 /**
+* Identity resolved from the inbound request by `WorkerOptions.resolveIdentity`.
+*
+* The `userId` field is special — it becomes `ctx.auth.userId` inside the
+* Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
+* forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
+*
+* Return `null` to signal that the request is anonymous; the runtime will
+* skip both `x-lunora-userid` and `x-lunora-identity` headers, and
+* `ctx.auth.userId` will be `undefined` on the shard side.
+*/
+interface ResolvedIdentity {
+  /** Arbitrary additional claims. Must be JSON-serialisable. */
+  [key: string]: unknown;
+  /**
+  * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
+  * absent), the runtime forwards it as the socket's credential expiry — the
+  * DO drops the socket once it lapses. Used only on the WebSocket path.
+  */
+  exp?: number;
+  /**
+  * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
+  * both are present. Forwarded as the socket's expiry on the WebSocket path
+  * so the DO drops the socket once it lapses; omit for non-expiring sessions.
+  */
+  expiresAtMs?: number;
+  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
+  userId: string;
+}
+/**
+* A verifier that turns an inbound request into a {@link ResolvedIdentity} (or
+* `null` for anonymous). Structurally identical to `WorkerOptions.resolveIdentity`,
+* so `.auth()`'s better-auth session resolver, a signed-preview-link verifier, a
+* per-tenant bearer check, an upstream-JWT reader, … are all just `IdentityResolver`s
+* — the identity layer is generic over every scheme, not coupled to any one.
+*/
+type IdentityResolver = (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
+/** Error policy for {@link composeIdentityResolvers} when a participant resolver throws. */
+type ComposeIdentityResolversErrorMode = "fail-closed" | "skip";
+/** Options for {@link composeIdentityResolvers}. */
+interface ComposeIdentityResolversOptions {
+  /**
+  * What to do when a resolver throws. `"fail-closed"` (default, safe)
+  * re-throws so a broken verifier fails the request rather than silently
+  * falling through to a weaker one; `"skip"` swallows the error and tries the
+  * next resolver (use only when a resolver's failure genuinely means "not my
+  * scheme").
+  */
+  readonly onError?: ComposeIdentityResolversErrorMode;
+}
+/**
+* Compose several {@link IdentityResolver}s into one, first-match-wins: each is
+* tried in order and the first that returns a non-null identity short-circuits.
+* Generic over every scheme — the better-auth session resolver (obtained via the
+* builder's `derived.resolveIdentity` escape hatch) is just one entry in the list,
+* so composition never means losing it.
+*
+* A resolver that throws is handled per {@link ComposeIdentityResolversOptions.onError}
+* (default `"fail-closed"`: the error propagates).
+*/
+declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
+/**
+* A thin, generic helper over {@link composeIdentityResolvers} for the per-route case:
+* pick a resolver by `new URL(request.url).pathname`. Keys are matched by longest
+* path prefix; `"*"` is the fallback. Still fully generic — a route→resolver map,
+* with no portal / preview / tenant concepts baked in (those live in the app's
+* own resolvers).
+* @example
+* routeIdentityResolvers({ "/admin": adminResolver, "/partner": partnerResolver, "*": sessionResolver })
+*/
+declare const routeIdentityResolvers: (routes: Record<string, IdentityResolver>) => IdentityResolver;
+/** The result of validating a candidate identity against an {@link IdentityContractLike}. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
+/**
+* Structural view of `@lunora/server`'s `IdentityContract` (from `defineIdentity`).
+* Kept structural so `@lunora/runtime` stays free of an `@lunora/server` dependency.
+* Keep the `onInvalid` union and `validate`/`IdentityValidation` shapes in sync with
+* `@lunora/server`'s `IdentityContract` — they are projected by hand, not imported.
+* The generated worker entry passes the app's `defineIdentity(...)` result here;
+* the worker validates every resolver's returned claims against it at the trust
+* boundary before they become `ctx.auth`.
+*/
+interface IdentityContractLike {
+  /** Reject policy applied when validation fails: downgrade to anonymous, or reject the request (401). */
+  readonly onInvalid: "anonymous" | "reject";
+  /** Validate resolver-returned claims against the declared contract. */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/**
+* The trust-boundary identity gate. Given the worker's `resolveIdentity` and an
+* optional `defineIdentity(...)` contract, return a resolver that validates every
+* resolved identity against the declared claims BEFORE it becomes `ctx.auth`.
+*
+* Claims arrive from untrusted tokens; a forged / malformed set is either
+* downgraded to anonymous (`onInvalid: "anonymous"`, the safe default — the bad
+* identity never reaches a policy as valid) or rejected with a `401`
+* (`onInvalid: "reject"`), rather than flowing in as an unchecked cast. A valid
+* identity is returned unchanged, so undeclared claims are forwarded verbatim.
+*
+* When no contract is configured (or there is no `resolveIdentity`), the original
+* resolver is returned untouched — zero overhead and byte-identical behaviour.
+* Only the public data paths (RPC / WebSocket / HTTP-action / server-query) use
+* the wrapped resolver; the admin path keeps the raw one (admin is gated by the
+* bearer / Access, not the app's identity contract).
+*/
+/**
 * Observability hooks for the Lunora runtime.
 *
 * A user-supplied {@link ObservabilitySink} receives one event per dispatched
@@ -1040,9 +1150,13 @@ declare const createQueryCoordinator: (options: QueryCoordinatorOptions) => Quer
 interface SecurityHeadersOptions {
   /**
   * `Content-Security-Policy`. Omitted (`undefined`) applies a restrictive
-  * default to **non-HTML** responses only, so an SSR page is never broken by
-  * a policy it didn't opt into. Pass a string to apply that policy to every
-  * response (HTML included); `false` to never send one.
+  * `default-src 'none'` policy to **non-HTML** responses, and a conservative
+  * hardening policy to **HTML** responses (`base-uri 'none'; frame-ancestors
+  * 'self'; object-src 'none'`) — this does NOT set `default-src`/`script-src`,
+  * so it never blocks an SSR page's own scripts/styles/images/fetches, it only
+  * locks down the `base` element, framing (mirroring the `SAMEORIGIN`
+  * X-Frame-Options default), and legacy plugins. Pass a string to apply that
+  * exact policy to every response (HTML included); `false` to never send one.
   */
   csp?: string | false;
   /** `X-Frame-Options` (clickjacking). Defaults to `SAMEORIGIN`. `false` omits it. */
@@ -1091,7 +1205,7 @@ interface SecurityOptions {
 interface ResolvedHeaders {
   coop: string | undefined;
   csp: {
-    htmlToo: boolean;
+    htmlValue: string | undefined;
     value: string;
   } | undefined;
   enabled: boolean;
@@ -1154,6 +1268,24 @@ declare const resolveSecurity: (security: SecurityOptions | undefined, env?: Rec
 * @returns a `403` Response when the origin is untrusted, or `undefined` when the request is allowed.
 */
 declare const enforceOrigin: (request: Request, resolved: ResolvedSecurity) => Response | undefined;
+/**
+* CSRF defense for the WebSocket upgrade (Cross-Site WebSocket Hijacking).
+*
+* A WS handshake is an HTTP `GET`, so {@link enforceOrigin}'s safe-method
+* exemption never fires for it — yet the browser auto-attaches the session
+* cookie to the handshake and WebSocket connections are NOT governed by
+* CORS/SOP. Without an explicit `Origin` check any page can open
+* `wss://app/_lunora/ws`, authenticate as the logged-in victim, and read the
+* victim's live queries + issue mutations as them. This guard closes that hole.
+*
+* Scoped to cookie-bearing upgrades — the only vector CSWSH can ride (a browser
+* attaches cookies but never a bearer token). Bearer/token/server-to-server
+* upgrades (no `Cookie`) are exempt. A browser ALWAYS sends `Origin` on a WS
+* handshake, so a missing/untrusted `Origin` on a cookie-bearing upgrade fails
+* closed (mirrors {@link enforceOrigin}).
+* @returns a `403` Response when the upgrade origin is untrusted, or `undefined` when it is allowed.
+*/
+
 /**
 * Answer a CORS preflight (`OPTIONS` carrying `Access-Control-Request-Method`)
 * for an allowlisted origin with a `204`. Returns `undefined` for non-preflight
@@ -1223,35 +1355,6 @@ interface HttpRouterLike {
   fetch(request: Request, env?: unknown, context?: ExecutionContextLike): Promise<Response> | Response;
 }
 /**
-* Identity resolved from the inbound request by {@link WorkerOptions.resolveIdentity}.
-*
-* The `userId` field is special — it becomes `ctx.auth.userId` inside the
-* Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
-* forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
-*
-* Return `null` to signal that the request is anonymous; the runtime will
-* skip both `x-lunora-userid` and `x-lunora-identity` headers, and
-* `ctx.auth.userId` will be `undefined` on the shard side.
-*/
-interface ResolvedIdentity {
-  /** Arbitrary additional claims. Must be JSON-serialisable. */
-  [key: string]: unknown;
-  /**
-  * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
-  * absent), the runtime forwards it as the socket's credential expiry — the
-  * DO drops the socket once it lapses. Used only on the WebSocket path.
-  */
-  exp?: number;
-  /**
-  * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
-  * both are present. Forwarded as the socket's expiry on the WebSocket path
-  * so the DO drops the socket once it lapses; omit for non-expiring sessions.
-  */
-  expiresAtMs?: number;
-  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
-  userId: string;
-}
-/**
 * Per-table sharding metadata the admin import endpoint needs to route rows.
 * Structural so this package stays free of `@lunora/server`. The codegen-
 * generated worker entry passes a thin projection of the user's schema.
@@ -1637,17 +1740,21 @@ interface WorkerOptions {
   */
   adminToken?: string;
   /**
-  * Acknowledge — explicitly — that sharded and fan-out access may be
-  * exercised by any caller (including unauthenticated ones) because no
-  * authorization callback is configured. When neither {@link WorkerOptions.authorizeShard}
-  * nor {@link WorkerOptions.authorizeFanOut} is set, naming a non-default shard or sending
-  * a fan-out envelope is authorization-open: this is the historical posture,
-  * preserved for backward compatibility. The runtime emits a single loud
-  * `console.warn` the first time such a request is seen so the gap is
-  * visible in logs. Set this to `true` to assert the posture is intentional
-  * and silence that warning. It does NOT change behaviour — it is purely an
-  * acknowledgement flag — and has no effect once an `authorize*` callback is
-  * configured.
+  * Opt into an authorization-open posture for sharded and fan-out access.
+  *
+  * By default (this flag unset/`false`) the runtime FAILS CLOSED: when
+  * neither {@link WorkerOptions.authorizeShard} nor {@link WorkerOptions.authorizeFanOut}
+  * is configured, naming a non-default shard (a potential cross-tenant hop)
+  * or sending a fan-out envelope is rejected with a `403`
+  * (`FORBIDDEN_SHARD`/`FORBIDDEN_FANOUT`). Set this to `true` to allow such
+  * requests from any caller (including unauthenticated ones) — appropriate
+  * only when every table is protected by per-row RLS. The runtime then emits
+  * a single `console.warn` so the open posture stays visible in logs. Has no
+  * effect once an `authorize*` callback is configured (those gate directly).
+  *
+  * NOTE: this is a behaviour change from earlier alphas, where the same
+  * situation was warn-once-then-allow. Apps that relied on client-chosen
+  * shard keys without an `authorize*` callback must set this flag explicitly.
   */
   allowUnauthenticatedShardAccess?: boolean;
   /**
@@ -1814,6 +1921,17 @@ interface WorkerOptions {
   */
   httpRouter?: HttpRouterLike;
   /**
+  * The declared identity claim contract (`defineIdentity(...)` from
+  * `@lunora/server`), passed by the generated worker entry. When present, the
+  * worker validates every `resolveIdentity` result against it at the trust
+  * boundary (on the public data paths — RPC / WebSocket / HTTP-action /
+  * server-query, never the admin path) *before* the claims become `ctx.auth`.
+  * A resolver output that violates the contract is downgraded to anonymous or
+  * rejected with a `401`, per the contract's `onInvalid`. Omitted → no
+  * validation, and the identity stays the historical untyped claim bag.
+  */
+  identity?: IdentityContractLike;
+  /**
   * Insert `.global()` rows for the admin import endpoint. When omitted,
   * rows targeting global tables are reported as hard errors.
   */
@@ -2423,4 +2541,4 @@ declare const analyticsEngineSink: (options: AnalyticsEngineSinkOptions) => Obse
 */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
 declare const VERSION: string;
-export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.d.ts

@@ -337,6 +337,116 @@ interface FunctionArgumentDescriptor {
 * kind only — enough for a signature view without a deep recursive walk.
 */
 /**
+* Identity resolved from the inbound request by `WorkerOptions.resolveIdentity`.
+*
+* The `userId` field is special — it becomes `ctx.auth.userId` inside the
+* Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
+* forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
+*
+* Return `null` to signal that the request is anonymous; the runtime will
+* skip both `x-lunora-userid` and `x-lunora-identity` headers, and
+* `ctx.auth.userId` will be `undefined` on the shard side.
+*/
+interface ResolvedIdentity {
+  /** Arbitrary additional claims. Must be JSON-serialisable. */
+  [key: string]: unknown;
+  /**
+  * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
+  * absent), the runtime forwards it as the socket's credential expiry — the
+  * DO drops the socket once it lapses. Used only on the WebSocket path.
+  */
+  exp?: number;
+  /**
+  * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
+  * both are present. Forwarded as the socket's expiry on the WebSocket path
+  * so the DO drops the socket once it lapses; omit for non-expiring sessions.
+  */
+  expiresAtMs?: number;
+  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
+  userId: string;
+}
+/**
+* A verifier that turns an inbound request into a {@link ResolvedIdentity} (or
+* `null` for anonymous). Structurally identical to `WorkerOptions.resolveIdentity`,
+* so `.auth()`'s better-auth session resolver, a signed-preview-link verifier, a
+* per-tenant bearer check, an upstream-JWT reader, … are all just `IdentityResolver`s
+* — the identity layer is generic over every scheme, not coupled to any one.
+*/
+type IdentityResolver = (request: Request, env: unknown) => Promise<ResolvedIdentity | null> | ResolvedIdentity | null;
+/** Error policy for {@link composeIdentityResolvers} when a participant resolver throws. */
+type ComposeIdentityResolversErrorMode = "fail-closed" | "skip";
+/** Options for {@link composeIdentityResolvers}. */
+interface ComposeIdentityResolversOptions {
+  /**
+  * What to do when a resolver throws. `"fail-closed"` (default, safe)
+  * re-throws so a broken verifier fails the request rather than silently
+  * falling through to a weaker one; `"skip"` swallows the error and tries the
+  * next resolver (use only when a resolver's failure genuinely means "not my
+  * scheme").
+  */
+  readonly onError?: ComposeIdentityResolversErrorMode;
+}
+/**
+* Compose several {@link IdentityResolver}s into one, first-match-wins: each is
+* tried in order and the first that returns a non-null identity short-circuits.
+* Generic over every scheme — the better-auth session resolver (obtained via the
+* builder's `derived.resolveIdentity` escape hatch) is just one entry in the list,
+* so composition never means losing it.
+*
+* A resolver that throws is handled per {@link ComposeIdentityResolversOptions.onError}
+* (default `"fail-closed"`: the error propagates).
+*/
+declare const composeIdentityResolvers: (resolvers: ReadonlyArray<IdentityResolver>, options?: ComposeIdentityResolversOptions) => IdentityResolver;
+/**
+* A thin, generic helper over {@link composeIdentityResolvers} for the per-route case:
+* pick a resolver by `new URL(request.url).pathname`. Keys are matched by longest
+* path prefix; `"*"` is the fallback. Still fully generic — a route→resolver map,
+* with no portal / preview / tenant concepts baked in (those live in the app's
+* own resolvers).
+* @example
+* routeIdentityResolvers({ "/admin": adminResolver, "/partner": partnerResolver, "*": sessionResolver })
+*/
+declare const routeIdentityResolvers: (routes: Record<string, IdentityResolver>) => IdentityResolver;
+/** The result of validating a candidate identity against an {@link IdentityContractLike}. */
+type IdentityValidation = {
+  ok: true;
+} | {
+  error: string;
+  ok: false;
+};
+/**
+* Structural view of `@lunora/server`'s `IdentityContract` (from `defineIdentity`).
+* Kept structural so `@lunora/runtime` stays free of an `@lunora/server` dependency.
+* Keep the `onInvalid` union and `validate`/`IdentityValidation` shapes in sync with
+* `@lunora/server`'s `IdentityContract` — they are projected by hand, not imported.
+* The generated worker entry passes the app's `defineIdentity(...)` result here;
+* the worker validates every resolver's returned claims against it at the trust
+* boundary before they become `ctx.auth`.
+*/
+interface IdentityContractLike {
+  /** Reject policy applied when validation fails: downgrade to anonymous, or reject the request (401). */
+  readonly onInvalid: "anonymous" | "reject";
+  /** Validate resolver-returned claims against the declared contract. */
+  validate: (identity: Record<string, unknown>) => IdentityValidation;
+}
+/**
+* The trust-boundary identity gate. Given the worker's `resolveIdentity` and an
+* optional `defineIdentity(...)` contract, return a resolver that validates every
+* resolved identity against the declared claims BEFORE it becomes `ctx.auth`.
+*
+* Claims arrive from untrusted tokens; a forged / malformed set is either
+* downgraded to anonymous (`onInvalid: "anonymous"`, the safe default — the bad
+* identity never reaches a policy as valid) or rejected with a `401`
+* (`onInvalid: "reject"`), rather than flowing in as an unchecked cast. A valid
+* identity is returned unchanged, so undeclared claims are forwarded verbatim.
+*
+* When no contract is configured (or there is no `resolveIdentity`), the original
+* resolver is returned untouched — zero overhead and byte-identical behaviour.
+* Only the public data paths (RPC / WebSocket / HTTP-action / server-query) use
+* the wrapped resolver; the admin path keeps the raw one (admin is gated by the
+* bearer / Access, not the app's identity contract).
+*/
+/**
 * Observability hooks for the Lunora runtime.
 *
 * A user-supplied {@link ObservabilitySink} receives one event per dispatched
@@ -1040,9 +1150,13 @@ declare const createQueryCoordinator: (options: QueryCoordinatorOptions) => Quer
 interface SecurityHeadersOptions {
   /**
   * `Content-Security-Policy`. Omitted (`undefined`) applies a restrictive
-  * default to **non-HTML** responses only, so an SSR page is never broken by
-  * a policy it didn't opt into. Pass a string to apply that policy to every
-  * response (HTML included); `false` to never send one.
+  * `default-src 'none'` policy to **non-HTML** responses, and a conservative
+  * hardening policy to **HTML** responses (`base-uri 'none'; frame-ancestors
+  * 'self'; object-src 'none'`) — this does NOT set `default-src`/`script-src`,
+  * so it never blocks an SSR page's own scripts/styles/images/fetches, it only
+  * locks down the `base` element, framing (mirroring the `SAMEORIGIN`
+  * X-Frame-Options default), and legacy plugins. Pass a string to apply that
+  * exact policy to every response (HTML included); `false` to never send one.
   */
   csp?: string | false;
   /** `X-Frame-Options` (clickjacking). Defaults to `SAMEORIGIN`. `false` omits it. */
@@ -1091,7 +1205,7 @@ interface SecurityOptions {
 interface ResolvedHeaders {
   coop: string | undefined;
   csp: {
-    htmlToo: boolean;
+    htmlValue: string | undefined;
     value: string;
   } | undefined;
   enabled: boolean;
@@ -1154,6 +1268,24 @@ declare const resolveSecurity: (security: SecurityOptions | undefined, env?: Rec
 * @returns a `403` Response when the origin is untrusted, or `undefined` when the request is allowed.
 */
 declare const enforceOrigin: (request: Request, resolved: ResolvedSecurity) => Response | undefined;
+/**
+* CSRF defense for the WebSocket upgrade (Cross-Site WebSocket Hijacking).
+*
+* A WS handshake is an HTTP `GET`, so {@link enforceOrigin}'s safe-method
+* exemption never fires for it — yet the browser auto-attaches the session
+* cookie to the handshake and WebSocket connections are NOT governed by
+* CORS/SOP. Without an explicit `Origin` check any page can open
+* `wss://app/_lunora/ws`, authenticate as the logged-in victim, and read the
+* victim's live queries + issue mutations as them. This guard closes that hole.
+*
+* Scoped to cookie-bearing upgrades — the only vector CSWSH can ride (a browser
+* attaches cookies but never a bearer token). Bearer/token/server-to-server
+* upgrades (no `Cookie`) are exempt. A browser ALWAYS sends `Origin` on a WS
+* handshake, so a missing/untrusted `Origin` on a cookie-bearing upgrade fails
+* closed (mirrors {@link enforceOrigin}).
+* @returns a `403` Response when the upgrade origin is untrusted, or `undefined` when it is allowed.
+*/
+
 /**
 * Answer a CORS preflight (`OPTIONS` carrying `Access-Control-Request-Method`)
 * for an allowlisted origin with a `204`. Returns `undefined` for non-preflight
@@ -1223,35 +1355,6 @@ interface HttpRouterLike {
   fetch(request: Request, env?: unknown, context?: ExecutionContextLike): Promise<Response> | Response;
 }
 /**
-* Identity resolved from the inbound request by {@link WorkerOptions.resolveIdentity}.
-*
-* The `userId` field is special — it becomes `ctx.auth.userId` inside the
-* Durable Object. Any other keys (`email`, `name`, custom roles, etc.) are
-* forwarded verbatim as `ctx.auth.getIdentity()`'s return value.
-*
-* Return `null` to signal that the request is anonymous; the runtime will
-* skip both `x-lunora-userid` and `x-lunora-identity` headers, and
-* `ctx.auth.userId` will be `undefined` on the shard side.
-*/
-interface ResolvedIdentity {
-  /** Arbitrary additional claims. Must be JSON-serialisable. */
-  [key: string]: unknown;
-  /**
-  * JWT-standard expiry in epoch SECONDS. When present (and `expiresAtMs` is
-  * absent), the runtime forwards it as the socket's credential expiry — the
-  * DO drops the socket once it lapses. Used only on the WebSocket path.
-  */
-  exp?: number;
-  /**
-  * Credential expiry in epoch MILLISECONDS. Preferred over `exp` when
-  * both are present. Forwarded as the socket's expiry on the WebSocket path
-  * so the DO drops the socket once it lapses; omit for non-expiring sessions.
-  */
-  expiresAtMs?: number;
-  /** Stable user identifier (e.g. `"user_2k3..."` or `"u_42"`). */
-  userId: string;
-}
-/**
 * Per-table sharding metadata the admin import endpoint needs to route rows.
 * Structural so this package stays free of `@lunora/server`. The codegen-
 * generated worker entry passes a thin projection of the user's schema.
@@ -1637,17 +1740,21 @@ interface WorkerOptions {
   */
   adminToken?: string;
   /**
-  * Acknowledge — explicitly — that sharded and fan-out access may be
-  * exercised by any caller (including unauthenticated ones) because no
-  * authorization callback is configured. When neither {@link WorkerOptions.authorizeShard}
-  * nor {@link WorkerOptions.authorizeFanOut} is set, naming a non-default shard or sending
-  * a fan-out envelope is authorization-open: this is the historical posture,
-  * preserved for backward compatibility. The runtime emits a single loud
-  * `console.warn` the first time such a request is seen so the gap is
-  * visible in logs. Set this to `true` to assert the posture is intentional
-  * and silence that warning. It does NOT change behaviour — it is purely an
-  * acknowledgement flag — and has no effect once an `authorize*` callback is
-  * configured.
+  * Opt into an authorization-open posture for sharded and fan-out access.
+  *
+  * By default (this flag unset/`false`) the runtime FAILS CLOSED: when
+  * neither {@link WorkerOptions.authorizeShard} nor {@link WorkerOptions.authorizeFanOut}
+  * is configured, naming a non-default shard (a potential cross-tenant hop)
+  * or sending a fan-out envelope is rejected with a `403`
+  * (`FORBIDDEN_SHARD`/`FORBIDDEN_FANOUT`). Set this to `true` to allow such
+  * requests from any caller (including unauthenticated ones) — appropriate
+  * only when every table is protected by per-row RLS. The runtime then emits
+  * a single `console.warn` so the open posture stays visible in logs. Has no
+  * effect once an `authorize*` callback is configured (those gate directly).
+  *
+  * NOTE: this is a behaviour change from earlier alphas, where the same
+  * situation was warn-once-then-allow. Apps that relied on client-chosen
+  * shard keys without an `authorize*` callback must set this flag explicitly.
   */
   allowUnauthenticatedShardAccess?: boolean;
   /**
@@ -1814,6 +1921,17 @@ interface WorkerOptions {
   */
   httpRouter?: HttpRouterLike;
   /**
+  * The declared identity claim contract (`defineIdentity(...)` from
+  * `@lunora/server`), passed by the generated worker entry. When present, the
+  * worker validates every `resolveIdentity` result against it at the trust
+  * boundary (on the public data paths — RPC / WebSocket / HTTP-action /
+  * server-query, never the admin path) *before* the claims become `ctx.auth`.
+  * A resolver output that violates the contract is downgraded to anonymous or
+  * rejected with a `401`, per the contract's `onInvalid`. Omitted → no
+  * validation, and the identity stays the historical untyped claim bag.
+  */
+  identity?: IdentityContractLike;
+  /**
   * Insert `.global()` rows for the admin import endpoint. When omitted,
   * rows targeting global tables are reported as hard errors.
   */
@@ -2423,4 +2541,4 @@ declare const analyticsEngineSink: (options: AnalyticsEngineSinkOptions) => Obse
 */
 declare const combineSinks: (...sinks: ObservabilitySink[]) => ObservabilitySink;
 declare const VERSION: string;
-export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type BackupManifest, type BackupStore, type ComposeIdentityResolversErrorMode, type ComposeIdentityResolversOptions, type ConnectorChange, type ConnectorSyncPage, type CorsOptions, type CronHandler, type CronJobDispatch, type CronJobInfo, type CrossShardCounter, type CrossShardReader, type CrossShardRelationCapabilities, type CrossShardRelationOptions, type CsrfOptions, DEFAULT_REGISTRY_CACHE_TTL_MS, type DurableObjectJurisdiction, type DynamicShardRegistry, type DynamicShardRegistryOptions, type ExecutionContextLike, type ExportFanOutRequest, type ExportFanOutResult, type FanOutRequest, type FanOutResult, type FanOutSpec, type FivetranResponse, type FrameworkHostHandler, type FrameworkWorkerOptions, type FrameworkWorkerOptionsInput, type FunctionDescriptor, type FunctionRegistryEntry, type FunctionRegistryLike, type GlobalExportFunction as GlobalExportFn, type GlobalImportFunction as GlobalImportFn, type GlobalIntrospector, type GlobalTableInfo as GlobalTableInfoMeta, type GlobalTablePage as GlobalTablePageMeta, type HttpActionContext, type HttpActionLike, type HttpRouterLike, type IdentityContractLike, type IdentityResolver, type IdentityValidation, type ImportFanOutRequest, type ImportFanOutResult, type ListAuthUsersOptions, type LogEvent, type LogLevel, LunoraError, type LunoraErrorBody, type LunoraHandlerOptions, type LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, NOOP_EXECUTION_CONTEXT, type ObservabilityEvent, type ObservabilitySink, type ObservabilitySinkContext, type QueryCoordinator, type QueryCoordinatorOptions, type RankFanOutRequest, type RankFanOutResult, type RankPageFanOutRequest, type RankPageFanOutResult, type ResolvedSecurity, type ResolvedShard, type Route, type RpcContext, type RpcEnvelope, SHARD_REGISTRY_DO_NAME, type ScheduledControllerLike, type SecurityHeadersOptions, type SecurityOptions, type SentrySinkOptions, type ShardError, type ShardExportOutcome, type ShardImportOutcome, type ShardMigrationOutcome, type ShardNamespaceLike, type ShardRankOutcome, type ShardRankPageOutcome, type ShardRegistry, type ShardTrafficEntry, type ShardTrafficFanOutRequest, type ShardTrafficFanOutResult, type ShardingInfo, type StorageListFunction as StorageListFn, type StorageObject, VERSION, type VectorIndexSummary, type VectorIntrospector, type VectorQueryMatch, type WebhookSinkOptions, type WorkerOptions, analyticsEngineSink, applyJurisdiction, combineSinks, composeIdentityResolvers, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createLunoraHandler, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveLunoraOptions, resolveSecurity, resolveShard, routeIdentityResolvers, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 export { toAirbyteMessages, toFivetranResponse } from './packem_shared/toAirbyteMessages-DrHdplb4.mjs';
-export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-BNYeYQqL.mjs';
+export { composeWorker, createLunoraHandler, createWorker, defineRpcEnvelope, resolveLunoraOptions, withFrameworkWorker } from './packem_shared/composeWorker-M4mPqTJx.mjs';
 export { createCrossShardRelationCapabilities } from './packem_shared/createCrossShardRelationCapabilities-C0KOf7er.mjs';
 export { DEFAULT_REGISTRY_CACHE_TTL_MS, SHARD_REGISTRY_DO_NAME, createDynamicShardRegistry } from './packem_shared/DEFAULT_REGISTRY_CACHE_TTL_MS-ocax8v0n.mjs';
 export { LunoraError, toErrorResponse } from './packem_shared/LunoraError-CL0aOtpo.mjs';
@@ -7,8 +7,9 @@ export { emitLogEvent, emitRpcEvent } from './packem_shared/emitLogEvent-pEdtqAK
 export { analyticsEngineSink, combineSinks, consoleSink, sentrySink, webhookSink } from './packem_shared/analyticsEngineSink-DqEvrQs0.mjs';
 export { createQueryCoordinator, createStaticShardRegistry, mergeStrategyForAggregate } from './packem_shared/createQueryCoordinator-ZeZYUPNu.mjs';
 export { applyJurisdiction, resolveShard } from './packem_shared/applyJurisdiction-BkZtTkct.mjs';
-export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-DbISh_Wi.mjs';
+export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity } from './packem_shared/decorateResponse-HRXo-oOD.mjs';
 export { NOOP_EXECUTION_CONTEXT } from './packem_shared/NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
+export { composeIdentityResolvers, routeIdentityResolvers } from './packem_shared/composeIdentityResolvers-YjvUKisc.mjs';
 
 const VERSION = "0.0.0";
 

package/dist/packem_shared/composeIdentityResolvers-YjvUKisc.mjs

@@ -0,0 +1,55 @@
+import { LunoraError } from './LunoraError-CL0aOtpo.mjs';
+
+const composeIdentityResolvers = (resolvers, options = {}) => {
+  const onError = options.onError ?? "fail-closed";
+  return async (request, env) => {
+    for (const resolver of resolvers) {
+      let resolved;
+      try {
+        resolved = await resolver(request, env);
+      } catch (error) {
+        if (onError === "skip") {
+          continue;
+        }
+        throw error;
+      }
+      if (resolved) {
+        return resolved;
+      }
+    }
+    return null;
+  };
+};
+const routeIdentityResolvers = (routes) => {
+  const prefixes = Object.keys(routes).filter((key) => key !== "*").toSorted((a, b) => b.length - a.length);
+  return (request, env) => {
+    const { pathname } = new URL(request.url);
+    const matched = prefixes.find((prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`));
+    const resolver = matched === void 0 ? routes["*"] : routes[matched];
+    if (resolver === void 0) {
+      return null;
+    }
+    return resolver(request, env);
+  };
+};
+const wrapResolverWithContract = (baseResolveIdentity, contract) => {
+  if (contract === void 0 || baseResolveIdentity === void 0) {
+    return baseResolveIdentity;
+  }
+  return async (request, env) => {
+    const resolved = await baseResolveIdentity(request, env);
+    if (!resolved) {
+      return resolved;
+    }
+    const result = contract.validate(resolved);
+    if (result.ok) {
+      return resolved;
+    }
+    if (contract.onInvalid === "reject") {
+      throw new LunoraError(`identity claims failed the declared contract: ${result.error}`, { code: "UNAUTHENTICATED", status: 401 });
+    }
+    return null;
+  };
+};
+
+export { composeIdentityResolvers, routeIdentityResolvers, wrapResolverWithContract };

package/dist/packem_shared/{composeWorker-BNYeYQqL.mjs → composeWorker-M4mPqTJx.mjs}

@@ -1,8 +1,10 @@
 import { NOOP_EXECUTION_CONTEXT } from './NOOP_EXECUTION_CONTEXT-CCTu0Bf1.mjs';
 import { LunoraError, toErrorResponse, isStructuralLunoraError, isStructuralConflictError } from './LunoraError-CL0aOtpo.mjs';
+import { wrapResolverWithContract } from './composeIdentityResolvers-YjvUKisc.mjs';
+export { composeIdentityResolvers, routeIdentityResolvers } from './composeIdentityResolvers-YjvUKisc.mjs';
 import { emitRpcEvent } from './emitLogEvent-pEdtqAK8.mjs';
 import { resolveShard, applyJurisdiction } from './applyJurisdiction-BkZtTkct.mjs';
-import { resolveSecurity, handleCorsPreflight, enforceOrigin, decorateResponse } from './decorateResponse-DbISh_Wi.mjs';
+import { resolveSecurity, handleCorsPreflight, enforceOrigin, decorateResponse, enforceWebSocketOrigin } from './decorateResponse-HRXo-oOD.mjs';
 
 const RELAY_NAME_INFIX = "::relay::";
 const relayName = (ownerKey, index) => `${ownerKey}${RELAY_NAME_INFIX}${String(index)}`;
@@ -248,15 +250,15 @@ const buildAuthAdminRoutes = (deps) => {
       }
       const candidate = error;
       const code = typeof candidate.code === "string" ? candidate.code : "AUTH_ADMIN_ERROR";
-      const message = typeof candidate.message === "string" ? candidate.message : "auth admin operation failed";
-      throw new LunoraError(message, { code, status: AUTH_ADMIN_ERROR_STATUS[code] ?? 400 });
+      console.error("[lunora] auth admin operation failed:", error);
+      throw new LunoraError("auth admin operation failed", { code, status: AUTH_ADMIN_ERROR_STATUS[code] ?? 400 });
     }
   };
   const handle = async (request, descriptor) => {
+    deps.assertAdmin(request);
     if (request.method !== descriptor.http) {
       throw new LunoraError(`Auth admin endpoint requires ${descriptor.http}`, { code: "METHOD_NOT_ALLOWED", status: 405 });
     }
-    deps.assertAdmin(request);
     const admin = deps.getAuthAdmin();
     if (admin === void 0) {
       throw new LunoraError("auth endpoints require an `authAdmin` on the worker", { code: "AUTH_NOT_CONFIGURED", status: 400 });
@@ -1742,9 +1744,18 @@ const parseEnvelope = async (request) => {
     throw new LunoraError("RPC `shardKey` must be a string", { code: "BAD_REQUEST", status: 400 });
   }
   const envelope = body;
+  const fanOut = validateFanOut(envelope.fanOut);
+  const args = envelope.args ?? {};
+  if (fanOut && envelope.functionPath.startsWith("__lunora_relation__:")) {
+    const requestedTable = args.table;
+    if (typeof requestedTable === "string" && requestedTable !== fanOut.table) {
+      throw new LunoraError("RPC `args.table` must match the authorized `fanOut.table` for a relation fan-out", { code: "BAD_REQUEST", status: 400 });
+    }
+    args.table = fanOut.table;
+  }
   return {
-    args: envelope.args ?? {},
-    fanOut: validateFanOut(envelope.fanOut),
+    args,
+    fanOut,
     functionPath: envelope.functionPath,
     shardKey: envelope.shardKey
   };
@@ -1836,6 +1847,7 @@ const checkAdminWsToken = (request, expected) => {
 };
 const createWorker = (options) => {
   const defaultShard = options.defaultShardKey ?? "__root__";
+  const publicResolveIdentity = wrapResolverWithContract(options.resolveIdentity, options.identity);
   const shardDO = applyJurisdiction(options.shardDO, options.jurisdiction);
   const schedulerDO = options.schedulerDO === void 0 ? void 0 : applyJurisdiction(options.schedulerDO, options.jurisdiction);
   let envAdminToken;
@@ -1861,18 +1873,24 @@ const createWorker = (options) => {
     }
     return context;
   };
-  const hasAnyShardAuth = Boolean(options.authorizeShard) || Boolean(options.authorizeFanOut);
   let warnedUnauthenticatedShardAccess = false;
-  const warnUnauthenticatedShardAccessOnce = (kind) => {
-    if (hasAnyShardAuth || options.allowUnauthenticatedShardAccess || warnedUnauthenticatedShardAccess) {
+  const guardUnauthenticatedShardAccess = (kind) => {
+    if (!options.allowUnauthenticatedShardAccess) {
+      const callback = kind === "fan-out" ? "authorizeFanOut" : "authorizeShard";
+      throw new LunoraError(
+        `${kind} access is default-denied: configure \`${callback}\` on the worker, or set \`allowUnauthenticatedShardAccess: true\` to explicitly allow unauthenticated ${kind} access (relying solely on per-row RLS).`,
+        { code: kind === "fan-out" ? "FORBIDDEN_FANOUT" : "FORBIDDEN_SHARD", status: 403 }
+      );
+    }
+    if (warnedUnauthenticatedShardAccess) {
       return;
     }
     warnedUnauthenticatedShardAccess = true;
     console.warn(
       [
-        `[lunora] SECURITY: received ${kind} access but neither \`authorizeShard\` nor \`authorizeFanOut\` is configured — `,
+        `[lunora] SECURITY: serving ${kind} access with \`allowUnauthenticatedShardAccess: true\` and no \`authorizeShard\`/\`authorizeFanOut\` — `,
         `any caller (including unauthenticated ones) can target any shard / fan out across the table. `,
-        `Configure \`authorizeShard\`/\`authorizeFanOut\`, or set \`allowUnauthenticatedShardAccess: true\` to acknowledge this posture and silence this warning.`
+        `This is safe only if every table is protected by per-row RLS. Configure \`authorizeShard\`/\`authorizeFanOut\` to gate it.`
       ].join("")
     );
   };
@@ -1884,20 +1902,20 @@ const createWorker = (options) => {
     resolveForwardContext: resolveAdminForwardContext,
     shardDO
   });
-  const dispatchToShard = async (functionPath, args, shardKey) => {
+  const dispatchToShard = async (functionPath, args, shardKey, mutationId) => {
     if (options.authorizeShard) {
       const allowed = await options.authorizeShard(null, shardKey);
       if (!allowed) {
         throw new LunoraError("Forbidden shard", { code: "FORBIDDEN_SHARD", status: 403 });
       }
     }
+    const headers = { "content-type": "application/json", "x-lunora-system": "1" };
+    if (mutationId !== void 0 && mutationId.length > 0) {
+      headers["x-lunora-mutation-id"] = mutationId;
+    }
     const forwarded = new Request("https://shard.internal/rpc", {
-      // `x-lunora-system` marks this as a trusted server-initiated dispatch
-      // so the shard may run `internal` functions (scheduled/cron jobs are
-      // typically internal). Authorization was already enforced above; this
-      // header is set only here, never on the client RPC path.
       body: JSON.stringify({ args, functionPath }),
-      headers: { "content-type": "application/json", "x-lunora-system": "1" },
+      headers,
       method: "POST"
     });
     return forwardToShard(shardDO, shardKey, forwarded);
@@ -2013,7 +2031,8 @@ const createWorker = (options) => {
     }
     const args = candidate.args ?? {};
     const shardKey = typeof candidate.shardKey === "string" && candidate.shardKey.length > 0 ? candidate.shardKey : defaultShard;
-    const response = await dispatchToShard(candidate.functionPath, args, shardKey);
+    const mutationId = typeof candidate.id === "string" && candidate.id.length > 0 ? candidate.id : void 0;
+    const response = await dispatchToShard(candidate.functionPath, args, shardKey, mutationId);
     await releasePoolSlot(candidate);
     return response;
   };
@@ -2108,7 +2127,7 @@ const createWorker = (options) => {
     requireAdminOption
   });
   const buildHttpActionContext = async (request, env) => {
-    const { claims, headers, userId } = await resolveForwardContext(request, env, options.resolveIdentity);
+    const { claims, headers, userId } = await resolveForwardContext(request, env, publicResolveIdentity);
     const run = async (reference, args = {}) => {
       const functionPath = reference.__lunoraRef;
       if (typeof functionPath !== "string") {
@@ -2156,15 +2175,19 @@ const createWorker = (options) => {
     if (request.headers.get("Upgrade") !== "websocket") {
       throw new LunoraError("WebSocket upgrade header missing", { code: "BAD_REQUEST", status: 426 });
     }
+    const blockedUpgrade = enforceWebSocketOrigin(request, resolvedSecurity);
+    if (blockedUpgrade) {
+      return blockedUpgrade;
+    }
     const shardKey = url.searchParams.get("shard") ?? defaultShard;
-    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, options.resolveIdentity);
+    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, publicResolveIdentity);
     if (options.authorizeShard) {
       const allowed = await options.authorizeShard(identity, shardKey);
       if (!allowed) {
         throw new LunoraError("Forbidden shard", { code: "FORBIDDEN_SHARD", status: 403 });
       }
     } else if (shardKey !== defaultShard) {
-      warnUnauthenticatedShardAccessOnce("shard");
+      guardUnauthenticatedShardAccess("shard");
     }
     const upgradeHeaders = new Headers(request.headers);
     upgradeHeaders.delete("x-lunora-userid");
@@ -2193,29 +2216,34 @@ const createWorker = (options) => {
     }
     return forwardToShard(shardDO, shardKey, new Request(request, { headers: upgradeHeaders }));
   };
+  const authorizeFanOutEnvelope = async (fanOut, functionPath, identity) => {
+    if (options.authorizeFanOut) {
+      const allowed = await options.authorizeFanOut(identity, fanOut.table, functionPath);
+      if (!allowed) {
+        throw new LunoraError("Forbidden fan-out", { code: "FORBIDDEN_FANOUT", status: 403 });
+      }
+      return;
+    }
+    if (functionPath.startsWith("__lunora_relation__:")) {
+      throw new LunoraError("reverse cross-backend relation reads (`__lunora_relation__:*`) require `authorizeFanOut` to be configured on the worker", {
+        code: "FORBIDDEN_FANOUT",
+        status: 403
+      });
+    }
+    if (options.authorizeShard) {
+      throw new LunoraError("Fan-out requires `authorizeFanOut` to be configured on the worker when `authorizeShard` is set", {
+        code: "FORBIDDEN_FANOUT",
+        status: 403
+      });
+    }
+    guardUnauthenticatedShardAccess("fan-out");
+  };
   const authorizeRpcEnvelope = async (envelope, identity) => {
+    if (!envelope.fanOut && envelope.functionPath.startsWith("__lunora_admin__:")) {
+      return;
+    }
     if (envelope.fanOut) {
-      if (options.authorizeFanOut) {
-        const allowed = await options.authorizeFanOut(identity, envelope.fanOut.table, envelope.functionPath);
-        if (!allowed) {
-          throw new LunoraError("Forbidden fan-out", { code: "FORBIDDEN_FANOUT", status: 403 });
-        }
-      } else if (envelope.functionPath.startsWith("__lunora_relation__:")) {
-        throw new LunoraError(
-          "reverse cross-backend relation reads (`__lunora_relation__:*`) require `authorizeFanOut` to be configured on the worker",
-          {
-            code: "FORBIDDEN_FANOUT",
-            status: 403
-          }
-        );
-      } else if (options.authorizeShard) {
-        throw new LunoraError("Fan-out requires `authorizeFanOut` to be configured on the worker when `authorizeShard` is set", {
-          code: "FORBIDDEN_FANOUT",
-          status: 403
-        });
-      } else {
-        warnUnauthenticatedShardAccessOnce("fan-out");
-      }
+      await authorizeFanOutEnvelope(envelope.fanOut, envelope.functionPath, identity);
       return;
     }
     if (options.authorizeShard) {
@@ -2225,7 +2253,7 @@ const createWorker = (options) => {
         throw new LunoraError("Forbidden shard", { code: "FORBIDDEN_SHARD", status: 403 });
       }
     } else if (envelope.shardKey !== void 0 && envelope.shardKey !== defaultShard) {
-      warnUnauthenticatedShardAccessOnce("shard");
+      guardUnauthenticatedShardAccess("shard");
     }
   };
   const dispatchSingleShard = async (functionPath, args, shardKey, forwardedHeaders, sinkContext) => {
@@ -2282,7 +2310,7 @@ const createWorker = (options) => {
         status: 400
       });
     }
-    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, options.resolveIdentity);
+    const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, publicResolveIdentity);
     await authorizeRpcEnvelope(envelope, identity);
     {
       const rpcStartedAt = Date.now();
@@ -2457,7 +2485,7 @@ const createWorker = (options) => {
       if (typeof functionPath !== "string") {
         throw new LunoraError("serverQuery: expected a function reference from the generated `api`", { code: "BAD_REQUEST", status: 400 });
       }
-      const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, options.resolveIdentity);
+      const { headers: forwardedHeaders, identity } = await resolveForwardContext(request, env, publicResolveIdentity);
       await authorizeRpcEnvelope({ functionPath, shardKey: callOptions.shardKey }, identity);
       const shardKey = callOptions.shardKey ?? defaultShard;
       return await dispatchSingleShard(functionPath, args, shardKey, forwardedHeaders);

package/dist/packem_shared/{decorateResponse-DbISh_Wi.mjs → decorateResponse-HRXo-oOD.mjs}

@@ -1,4 +1,13 @@
 const DEFAULT_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
+const htmlCspFor = (frameOptions) => {
+  const parts = ["base-uri 'none'", "object-src 'none'"];
+  if (frameOptions === "DENY") {
+    parts.push("frame-ancestors 'none'");
+  } else if (frameOptions === "SAMEORIGIN") {
+    parts.push("frame-ancestors 'self'");
+  }
+  return parts.join("; ");
+};
 const DEFAULT_PERMISSIONS_POLICY = "accelerometer=(), autoplay=(), camera=(), display-capture=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()";
 const DEFAULT_CORS_HEADERS = ["Authorization", "Content-Type", "X-D1-Bookmark", "X-Lunora-Mutation-Id"];
 const DEFAULT_CORS_METHODS = ["DELETE", "GET", "HEAD", "PATCH", "POST", "PUT"];
@@ -13,14 +22,14 @@ const resolveHstsHeader = (hsts) => {
   const includeSubDomains = config.includeSubDomains ?? true;
   return `max-age=${String(maxAge)}${includeSubDomains ? "; includeSubDomains" : ""}${config.preload ? "; preload" : ""}`;
 };
-const resolveCspHeader = (csp) => {
+const resolveCspHeader = (csp, htmlDefault) => {
   if (csp === false) {
     return void 0;
   }
   if (typeof csp === "string") {
-    return { htmlToo: true, value: csp };
+    return { htmlValue: csp, value: csp };
   }
-  return { htmlToo: false, value: DEFAULT_CSP };
+  return { htmlValue: htmlDefault, value: DEFAULT_CSP };
 };
 const resolveHeaders = (input) => {
   if (input === false) {
@@ -35,11 +44,12 @@ const resolveHeaders = (input) => {
     };
   }
   const options = input === void 0 || input === true ? {} : input;
+  const frameOptions = options.frameOptions === false ? void 0 : options.frameOptions ?? "SAMEORIGIN";
   return {
     coop: "same-origin",
-    csp: resolveCspHeader(options.csp),
+    csp: resolveCspHeader(options.csp, htmlCspFor(frameOptions)),
     enabled: true,
-    frameOptions: options.frameOptions === false ? void 0 : options.frameOptions ?? "SAMEORIGIN",
+    frameOptions,
     hsts: resolveHstsHeader(options.hsts),
     permissionsPolicy: options.permissionsPolicy === false ? void 0 : options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY,
     referrerPolicy: options.referrerPolicy === false ? void 0 : options.referrerPolicy ?? "strict-origin-when-cross-origin"
@@ -65,6 +75,11 @@ const resolveCors = (input) => {
   if (typeof origins === "function") {
     isAllowed = origins;
     isExplicitlyAllowed = origins;
+    if (allowCredentials) {
+      console.warn(
+        "@lunora/runtime: security.cors combines a custom `allowedOrigins` predicate with `allowCredentials: true`. Ensure the predicate matches ONLY trusted origins by exact equality — an over-broad predicate (e.g. `() => true`, or `endsWith`/`includes` checks) reflects any origin with credentials, defeating the allowlist and the CSRF guard."
+      );
+    }
   } else {
     const originsList = origins;
     if (originsList.includes("*") && allowCredentials) {
@@ -152,6 +167,20 @@ const enforceOrigin = (request, resolved) => {
     { headers: { "content-type": "application/json" }, status: 403 }
   );
 };
+const enforceWebSocketOrigin = (request, resolved) => {
+  if (!resolved.csrf.enabled || !request.headers.get("cookie")) {
+    return void 0;
+  }
+  const selfOrigin = new URL(request.url).origin;
+  const source = originOf(request.headers.get("origin"));
+  if (source !== void 0 && isTrustedOrigin(source, selfOrigin, resolved)) {
+    return void 0;
+  }
+  return Response.json(
+    { error: { code: "FORBIDDEN_ORIGIN", message: "cross-origin websocket upgrade rejected" } },
+    { headers: { "content-type": "application/json" }, status: 403 }
+  );
+};
 const corsResponseHeaders = (origin, cors) => {
   const headers = new Headers();
   headers.set("access-control-allow-origin", origin);
@@ -199,8 +228,11 @@ const applyBaselineHeaders = (headers, request, response, config) => {
   if (config.coop !== void 0) {
     setIfAbsent(headers, "cross-origin-opener-policy", config.coop);
   }
-  if (config.csp !== void 0 && (config.csp.htmlToo || !isHtmlResponse(response))) {
-    setIfAbsent(headers, "content-security-policy", config.csp.value);
+  if (config.csp !== void 0) {
+    const cspValue = isHtmlResponse(response) ? config.csp.htmlValue : config.csp.value;
+    if (cspValue !== void 0) {
+      setIfAbsent(headers, "content-security-policy", cspValue);
+    }
   }
 };
 const applyCorsHeaders = (headers, request, cors) => {
@@ -230,4 +262,4 @@ const decorateResponse = (response, request, resolved) => {
   return new Response(response.body, { headers, status: response.status, statusText: response.statusText });
 };
 
-export { decorateResponse, enforceOrigin, handleCorsPreflight, resolveSecurity };
+export { decorateResponse, enforceOrigin, enforceWebSocketOrigin, handleCorsPreflight, resolveSecurity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "Lunora Worker runtime: the RPC router, shard resolver, and query coordinator",
   "keywords": [
     "cloudflare",