@lunora/runtime 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { RankDirection, RankPageRow, DatabaseWriterLike } from '@lunora/do';
 export type { RankDirection as RankPageDirection, RankPageRowKey as RankPageKey, RankPageRow, ShardRankPageResult } from '@lunora/do';
 import { WorkflowsRestClient } from '@lunora/workflow';
+import { LunoraError as LunoraError$1, ErrorBody } from '@lunora/errors';
 /**
 * Turn-key incremental-sync source helpers for warehouse connectors
 * (Fivetran custom functions, Airbyte incremental sources).
@@ -110,6 +111,38 @@ declare const toFivetranResponse: (page: ConnectorSyncPage, primaryKey?: Record<
 * @param emittedAt epoch-ms stamped on each `RECORD` (default `Date.now()`).
 */
 declare const toAirbyteMessages: (page: ConnectorSyncPage, emittedAt?: number) => AirbyteMessage[];
+/**
+* The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
+* the framework mount seams rely on — `waitUntil` for fire-and-forget work that
+* must outlive the response, and `passThroughOnException` for the top-level
+* error posture.
+*
+* It is deliberately **not** a package. `@lunora/runtime` is the leaf server
+* runtime and `@lunora/nuxt` is a framework integration that intentionally does
+* not depend on `@lunora/runtime`'s worker types, yet both need this exact
+* shape: the runtime to build/forward the worker `fetch`, Nuxt to forward an
+* inbound request to the user's composed worker. Each imports this file by
+* relative path and the bundler (packem/rollup) inlines it: no runtime
+* dependency edge is created, the helper is duplicated only in emitted output,
+* never in source. One source of truth, zero deps. See AGENTS.md → "Top-level
+* `shared/` — bundler-inlined source".
+*
+* Both methods are **optional**: a real Cloudflare `ExecutionContext` always
+* supplies them, but a host that mounts Lunora as a sub-handler (Nitro/H3, a
+* non-Cloudflare preview, a unit test) may hand over a partial context or none
+* at all. Callers therefore invoke them defensively (`ctx.waitUntil?.(…)`) or
+* fall back to {@link NOOP_EXECUTION_CONTEXT}.
+*/
+interface ExecutionContextLike {
+  passThroughOnException?: () => void;
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+* No-op `ExecutionContext` used when the host runtime didn't supply one (a
+* non-Cloudflare preview, or a unit test), so the worker's `fetch` always
+* receives a valid third argument.
+*/
+declare const NOOP_EXECUTION_CONTEXT: ExecutionContextLike;
 /** A timestamp as better-auth stores it: epoch-ms, an ISO string, or absent. */
 type AuthTimestamp = null | number | string;
 /**
@@ -164,6 +197,43 @@ interface AuthCapabilities {
   passkey: boolean;
   twoFactor: boolean;
 }
+/** One user-settable extra field for the create-user form, derived from the merged `user` table. */
+interface AuthUserFieldSpec {
+  name: string;
+  plugin?: string;
+  required: boolean;
+  type: "boolean" | "date" | "number" | "string";
+  unique: boolean;
+}
+/**
+* Rich, read-only description of the deployment's auth configuration — enabled
+* plugins, sign-in methods, user-settable fields, organization sub-features, and
+* session / rate-limit policy — for the studio's config panel and dynamic
+* create-user form. Never carries a secret.
+*/
+interface AuthConfigInfo {
+  capabilities: AuthCapabilities;
+  emailAndPassword: boolean;
+  organization: {
+    enabled: boolean;
+    roles: boolean;
+    teams: boolean;
+  };
+  plugins: string[];
+  rateLimit: {
+    enabled: boolean;
+    max?: number;
+    window?: number;
+  };
+  session: {
+    cookieCache?: boolean;
+    expiresIn?: number;
+    freshAge?: number;
+    updateAge?: number;
+  };
+  socialProviders: string[];
+  userFields: AuthUserFieldSpec[];
+}
 /** Filtering / paging options forwarded to {@link AuthAdmin.listUsers} from the users endpoint's query string. */
 interface ListAuthUsersOptions {
   filterField?: string;
@@ -188,6 +258,15 @@ interface ListAuthUsersOptions {
 * implementation is a trusted server-side operator, not an end-user API.
 */
 interface AuthAdmin {
+  addMember?: (input: {
+    organizationId: string;
+    role?: string;
+    userId: string;
+  }) => Promise<Record<string, unknown>>;
+  addTeamMember?: (input: {
+    teamId: string;
+    userId: string;
+  }) => Promise<Record<string, unknown>>;
   banUser?: (input: {
     expiresInSeconds?: number;
     reason?: string;
@@ -197,6 +276,23 @@ interface AuthAdmin {
     invitationId: string;
   }) => Promise<void>;
   capabilities?: () => Promise<AuthCapabilities>;
+  config?: () => Promise<AuthConfigInfo>;
+  createOrganization?: (input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    ownerId?: string;
+    slug?: string;
+  }) => Promise<Record<string, unknown>>;
+  createOrgRole?: (input: {
+    organizationId: string;
+    permission: Record<string, string[]>;
+    role: string;
+  }) => Promise<Record<string, unknown>>;
+  createTeam?: (input: {
+    name: string;
+    organizationId: string;
+  }) => Promise<Record<string, unknown>>;
   createUser?: (input: {
     data?: Record<string, unknown>;
     email: string;
@@ -204,6 +300,12 @@ interface AuthAdmin {
     password?: string;
     role?: string | string[];
   }) => Promise<AuthUser>;
+  deleteOrganization?: (input: {
+    organizationId: string;
+  }) => Promise<void>;
+  deleteOrgRole?: (input: {
+    roleId: string;
+  }) => Promise<void>;
   deletePasskey?: (input: {
     passkeyId: string;
   }) => Promise<void>;
@@ -213,6 +315,12 @@ interface AuthAdmin {
   impersonateUser?: (input: {
     userId: string;
   }) => Promise<AuthImpersonation>;
+  inviteMember?: (input: {
+    email: string;
+    inviterId?: string;
+    organizationId: string;
+    role?: string;
+  }) => Promise<Record<string, unknown>>;
   listAccounts?: (input: {
     userId: string;
   }) => Promise<Record<string, unknown>[]>;
@@ -230,6 +338,11 @@ interface AuthAdmin {
     limit?: number;
     offset?: number;
   }) => Promise<AuthPage<Record<string, unknown>>>;
+  listOrgRoles?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
   listPasskeys?: (input: {
     userId: string;
   }) => Promise<Record<string, unknown>[]>;
@@ -238,10 +351,26 @@ interface AuthAdmin {
     offset?: number;
     userId?: string;
   }) => Promise<AuthPage<AuthSession>>;
+  listTeamMembers?: (options: {
+    limit?: number;
+    offset?: number;
+    teamId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
+  listTeams?: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<Record<string, unknown>>>;
   listUsers: (options: ListAuthUsersOptions) => Promise<AuthPage<AuthUser>>;
   removeMember?: (input: {
     memberId: string;
   }) => Promise<void>;
+  removeTeam?: (input: {
+    teamId: string;
+  }) => Promise<void>;
+  removeTeamMember?: (input: {
+    teamMemberId: string;
+  }) => Promise<void>;
   removeUser?: (input: {
     userId: string;
   }) => Promise<void>;
@@ -266,6 +395,25 @@ interface AuthAdmin {
     accountId: string;
     userId: string;
   }) => Promise<void>;
+  updateMemberRole?: (input: {
+    memberId: string;
+    role: string | string[];
+  }) => Promise<Record<string, unknown>>;
+  updateOrganization?: (input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    organizationId: string;
+    slug?: string;
+  }) => Promise<Record<string, unknown>>;
+  updateOrgRole?: (input: {
+    permission: Record<string, string[]>;
+    roleId: string;
+  }) => Promise<Record<string, unknown>>;
+  updateTeam?: (input: {
+    name: string;
+    teamId: string;
+  }) => Promise<Record<string, unknown>>;
   updateUser?: (input: {
     data: Record<string, unknown>;
     userId: string;
@@ -305,6 +453,182 @@ 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).
+*/
+/** One KV namespace as the studio's KV browser surfaces it. */
+interface KvNamespaceSummary {
+  /** The wrangler/env binding name, e.g. `"MY_KV"`. */
+  binding: string;
+}
+/** One key entry as the KV admin browser surfaces it. */
+interface KvKeyEntry {
+  /** Absolute expiration (Unix seconds), when set. */
+  expiration?: number;
+  /** Per-key metadata set at write time, or absent when none. */
+  metadata?: unknown;
+  /** The key name. */
+  name: string;
+}
+/** A paginated page of KV keys as the admin browser returns it. */
+interface KvKeyListResult {
+  /** Opaque cursor for the next page; absent when the listing is complete. */
+  cursor?: string;
+  /** The keys on this page. */
+  keys: KvKeyEntry[];
+  /** True when this is the final page. */
+  listComplete: boolean;
+}
+/** A KV value together with its stored metadata. */
+interface KvValueResult {
+  /** Per-key metadata, or `null` when none. */
+  metadata: unknown;
+  /** The stored value as a string, or `null` when the key is absent. */
+  value: null | string;
+}
+/**
+* The introspector the worker wires for the studio's KV browser. Build it from
+* the env's bound KV namespaces. Omit it and the `/_lunora/admin/kv/*`
+* endpoints respond `KV_NOT_CONFIGURED`.
+*/
+interface KvIntrospector {
+  /** Delete a key from a namespace. No-op when the key is absent. */
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  /** Read a value (as text) and its metadata from a namespace key. */
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResult>;
+  /** List keys in a namespace, optionally filtered by prefix and paginated. */
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResult>;
+  /** List the registered KV namespaces (binding names). */
+  listNamespaces: () => Promise<KvNamespaceSummary[]>;
+  /** Write a value (as text) with optional absolute expiration / relative TTL and metadata. */
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** The worker internals the KV routes reach through injection rather than closure. */
+/**
 * Observability hooks for the Lunora runtime.
 *
 * A user-supplied {@link ObservabilitySink} receives one event per dispatched
@@ -420,6 +744,14 @@ declare const emitRpcEvent: (sink: ObservabilitySink | undefined, event: Observa
 */
 declare const emitLogEvent: (sink: ObservabilitySink | undefined, event: LogEvent, context?: ObservabilitySinkContext) => void;
 /**
+* Cloudflare Durable Object jurisdictions restrict where a DO runs and persists
+* data, for data-residency / compliance regimes (GDPR, FedRAMP, US data
+* residency). The set is open — Cloudflare adds values over time — so this is a
+* widening union rather than a closed enum.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/**
 * Structural projection of the bits of `DurableObjectNamespace` the runtime
 * needs. Real workers-types defines a much wider surface; this lets us pass
 * unit-test doubles without coupling to `@cloudflare/workers-types`.
@@ -437,10 +769,29 @@ interface ShardNamespaceLike {
     fetch: (request: Request) => Promise<Response>;
   };
   idFromName: (name: string) => unknown;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Every ID and stub created
+  * from the returned namespace is pinned to `jurisdiction`. Optional because
+  * older workers-types releases (and unit-test doubles) may not expose it;
+  * {@link applyJurisdiction} fails closed when a jurisdiction is requested
+  * but this method is absent.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ShardNamespaceLike;
 }
 interface ResolvedShard {
   fetch: (request: Request) => Promise<Response>;
 }
+/**
+* Return a jurisdiction-restricted view of `namespace`, or `namespace`
+* unchanged when no jurisdiction is configured.
+*
+* Fail-closed: if a jurisdiction is requested but the binding does not expose
+* `.jurisdiction()` (an older workers-types, or a misconfigured test double),
+* this throws rather than silently routing to the un-pinned global namespace —
+* silently dropping a residency constraint would let data land outside the
+* compliance boundary the caller asked for.
+*/
+declare const applyJurisdiction: (namespace: ShardNamespaceLike, jurisdiction?: DurableObjectJurisdiction) => ShardNamespaceLike;
 /** Look up a shard stub by name, preferring `getByName` when present. */
 declare const resolveShard: (namespace: ShardNamespaceLike, shardKey: string) => ResolvedShard;
 /**
@@ -959,31 +1310,17 @@ interface ShardTrafficFanOutResult {
   shards: ReadonlyArray<ShardTrafficEntry>;
 }
 declare const createQueryCoordinator: (options: QueryCoordinatorOptions) => QueryCoordinator;
-/**
-* Secure-by-default HTTP edge for the Lunora worker.
-*
-* The worker's top-level `fetch` (see `./create-worker`) is the single choke
-* point every response passes through — RPC, auth, admin, `httpRoute` handlers,
-* and the SSR fallback alike. This module supplies what is applied there:
-* `decorateResponse` adds baseline security headers plus, for allowed
-* cross-origin requests, the matching `Access-Control-Allow-*` headers (never
-* overwriting a header the inner handler set); `handleCorsPreflight` answers
-* `OPTIONS` preflights for allowlisted origins; `enforceOrigin` is a CSRF guard
-* that rejects state-changing, cookie-authenticated requests from untrusted
-* origins.
-*
-* Every layer is on by default and individually disable-able through the
-* `SecurityOptions` passed to `createWorker`. Resolution (`resolveSecurity`) is
-* pure and platform-agnostic — it touches only the global `Request`/`Response`/
-* `Headers`/`URL`, so it unit-tests under plain Node without workerd.
-*/
 /** Per-header overrides for {@link SecurityHeadersOptions}. `false` omits the header. */
 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. */
@@ -1032,7 +1369,7 @@ interface SecurityOptions {
 interface ResolvedHeaders {
   coop: string | undefined;
   csp: {
-    htmlToo: boolean;
+    htmlValue: string | undefined;
     value: string;
   } | undefined;
   enabled: boolean;
@@ -1095,6 +1432,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
@@ -1130,10 +1485,6 @@ interface RpcEnvelope {
   functionPath: string;
   shardKey?: string;
 }
-interface ExecutionContextLike {
-  passThroughOnException: () => void;
-  waitUntil: (promise: Promise<unknown>) => void;
-}
 type Route = (request: Request, env: unknown, context: ExecutionContextLike) => Promise<Response> | Response;
 /**
 * Context handed to HTTP-action handlers. Built per request by the worker; its
@@ -1168,35 +1519,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.
@@ -1472,6 +1794,12 @@ interface ScheduledControllerLike {
 */
 type CronHandler = (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void> | void;
 /**
+* A Cloudflare Queues push-consumer handler — the worker's `queue()` entry
+* forwards each delivered `MessageBatch` (typed `unknown` here to keep the
+* runtime decoupled from `@lunora/queue`'s structural batch type).
+*/
+type QueueConsumerHandler = (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
+/**
 * A single code-defined cron job, shaped like an entry of the generated
 * `LUNORA_CRONS` map. `functionPath` is the `"namespace:fn"` to run, `args` its
 * bound arguments, and `name` the human label from the `cronJobs()` builder.
@@ -1553,6 +1881,22 @@ interface BackupManifest {
   tables?: string;
 }
 interface WorkerOptions {
+  /**
+  * An additional, async authorization gate for the `/_lunora/admin/*` plane
+  * (the Studio's HTTP + WS endpoints), OR-ed with the static {@link WorkerOptions.adminToken}
+  * bearer. When it resolves `true` for a request, that request is treated as
+  * admin-authorized even without the bearer; when it resolves `false` (or is
+  * unset) the bearer remains the only path. Evaluated once per admin request
+  * and never on the RPC/WebSocket data hot path.
+  *
+  * The intended producer is `@lunora/cloudflare-access`'s `accessAdminGate(...)`,
+  * which verifies the request's `Cf-Access-Jwt-Assertion` JWT and applies an
+  * `isAdmin(claims)` predicate — so the Studio can sit behind Cloudflare Access
+  * instead of (or alongside) a shared admin token. It takes only the request
+  * (verification needs static team-domain/aud config + the remote JWKS, no env
+  * binding), so it composes without threading async through every admin route.
+  */
+  adminGate?: (request: Request) => boolean | Promise<boolean>;
   /**
   * Admin bearer token expected by the export/import endpoints. When unset,
   * the endpoints respond with `ADMIN_FORBIDDEN` — the same posture the
@@ -1560,17 +1904,25 @@ 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 per
+  * operation: naming a non-default shard (a potential cross-tenant hop) is
+  * rejected with a `403` (`FORBIDDEN_SHARD`) unless
+  * {@link WorkerOptions.authorizeShard} is configured, and a fan-out
+  * envelope is rejected (`FORBIDDEN_FANOUT`) unless
+  * {@link WorkerOptions.authorizeFanOut} is. 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. The flag is consulted per operation: it has no effect
+  * on an operation whose own `authorize*` callback is configured (that
+  * callback gates directly), but configuring only one of the two callbacks
+  * does NOT cover the other operation.
+  *
+  * 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;
   /**
@@ -1737,11 +2089,51 @@ 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.
   */
   importGlobals?: GlobalImportFunction;
   /**
+  * Restrict every Durable Object this worker reaches — shard DOs, the
+  * scheduler DO, the fan-out coordinator, subscriptions — to a Cloudflare
+  * data-residency jurisdiction (`"eu"`, `"us"`, `"fedramp"`). The runtime
+  * derives a jurisdiction-pinned subnamespace from {@link WorkerOptions.shardDO}
+  * and {@link WorkerOptions.schedulerDO} once, so all routing inherits it.
+  *
+  * Fail-closed: if the bound namespace does not expose `.jurisdiction()`
+  * (an older `@cloudflare/workers-types`), the worker throws rather than
+  * silently routing to the un-pinned global namespace. Omit it for the
+  * default, un-pinned behaviour.
+  *
+  * ⚠️ Set once, before the first deploy — changing it strands data. A DO name
+  * maps to a *different* ID per jurisdiction, so toggling this on an existing
+  * deployment makes every shard/scheduler call resolve to a new, empty DO; the
+  * prior data stays in the old jurisdiction and is unreachable (no in-place
+  * migration). Usually set via the schema's `.jurisdiction(...)`, which codegen
+  * threads here.
+  * @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /**
+  * Introspector for Workers KV namespaces, backing the studio's KV browser
+  * via `GET /_lunora/admin/kv/namespaces`, `GET /_lunora/admin/kv/keys`,
+  * `GET|PUT|DELETE /_lunora/admin/kv/value`. Build it from the env's bound
+  * KV namespaces with `createKvIntrospector` from `@lunora/bindings/kv`.
+  * Omit it and those endpoints respond `KV_NOT_CONFIGURED`.
+  */
+  kvIntrospector?: KvIntrospector;
+  /**
   * Optional telemetry sink. When supplied, the worker emits one
   * `onRpc` event per dispatched RPC (single-shard forward or fan-out)
   * with duration / ok / error / shardKey or fanOut metadata. Sink
@@ -1796,6 +2188,14 @@ interface WorkerOptions {
   */
   queryCoordinator?: QueryCoordinator;
   /**
+  * Cloudflare Queues push-consumer handler — the worker's `queue(batch, …)`
+  * entry forwards every delivered `MessageBatch` here. Built by codegen from
+  * `lunora/queues.ts` (via `@lunora/queue`'s `dispatchQueueBatch`, which routes
+  * by `batch.queue` to the matching `defineQueue` handler), so the runtime
+  * stays decoupled from the queue package. Omitted when no push queues exist.
+  */
+  queue?: QueueConsumerHandler;
+  /**
   * Resolve the calling identity from the inbound RPC request. Called once
   * per RPC (and per fan-out) before the request is forwarded to the
   * shard. The returned `userId` becomes `ctx.auth.userId` on the shard
@@ -1918,6 +2318,12 @@ interface RpcContext {
 */
 interface LunoraWorker {
   fetch: (request: Request, env: unknown, context: ExecutionContextLike) => Promise<Response>;
+  /**
+  * Cloudflare Queues consumer entry — present only when the app declares push
+  * queues. Forwards each delivered `MessageBatch` to the configured
+  * {@link WorkerOptions.queue} handler; a no-op when none is set.
+  */
+  queue?: (batch: unknown, env: unknown, context: ExecutionContextLike) => Promise<void>;
   scheduled: (controller: ScheduledControllerLike, env: unknown, context: ExecutionContextLike) => Promise<void>;
   /**
   * In-process query/mutation dispatch for SSR loaders co-located in this
@@ -2019,6 +2425,55 @@ type FrameworkWorkerOptionsInput = ((env: unknown) => FrameworkWorkerOptions) |
 * @param optionsInput Lunora options minus `httpRouter`, or an `(env) => options` factory.
 */
 declare const withFrameworkWorker: (host: FrameworkHostHandler, optionsInput: FrameworkWorkerOptionsInput) => LunoraWorker;
+/**
+* Options for {@link createLunoraHandler}. Either an `(env) => options` factory
+* (full control — for bindings that only exist at request time), or a partial
+* {@link FrameworkWorkerOptions} object whose `shardDO` defaults to the
+* conventional `env.SHARD` binding. Pass nothing for the common case.
+*/
+type LunoraHandlerOptions = ((env: unknown) => FrameworkWorkerOptions) | Partial<FrameworkWorkerOptions>;
+/**
+* Resolve per-request Lunora worker options. A factory is called with the
+* request `env`; a partial object has its `shardDO` defaulted to `env.SHARD` so
+* the common case needs no configuration. Throws a clear error when no shard
+* namespace can be found — a wiring mistake, not a runtime condition to swallow.
+*/
+declare const resolveLunoraOptions: (options: LunoraHandlerOptions, env: unknown) => FrameworkWorkerOptions;
+/**
+* Build a framework-neutral request handler for Lunora's realtime plane
+* (`/_lunora/rpc`, `/_lunora/ws`, `/_lunora/admin/*`). This is the **one shared
+* seam** every web-standard framework integration mounts — Hono, Nitro/h3,
+* Elysia, or any WinterCG host running on Cloudflare Workers — so each is a
+* 1–2 line bridge (`(request, env, ctx) => Response`) rather than a bespoke
+* adapter package.
+*
+* Mount it under `/_lunora/*` (or whatever path you reserve) inside your app's
+* router; everything else stays your framework's. The host supplies, per
+* request: a Web `Request`, the Cloudflare `env` (carrying the `SHARD` Durable
+* Object namespace), and — when available — the `ExecutionContext`. The
+* `101 Switching Protocols` WebSocket-upgrade `Response` (with its `webSocket`)
+* is returned verbatim, so the framework streams the socket through unchanged.
+*
+* ```ts
+* // Hono
+* const lunora = createLunoraHandler();
+* app.use("/_lunora/*", (c) => lunora(c.req.raw, c.env, c.executionCtx));
+*
+* // Nitro / h3
+* const lunora = createLunoraHandler();
+* export default defineEventHandler((event) => {
+*   const { ctx, env } = event.context.cloudflare;
+*   return lunora(toWebRequest(event), env, ctx);
+* });
+* ```
+*
+* `shardDO` defaults to `env.SHARD`; pass `options` (or an `(env) => options`
+* factory) to add `auth`, `crons`, a `security` posture, or a custom namespace.
+* A new worker is composed per request because the options (and the `SHARD`
+* binding they default from) are only known once `env` arrives.
+* @param options Partial worker options (default `shardDO: env.SHARD`), or an `(env) => options` factory.
+*/
+declare const createLunoraHandler: (options?: LunoraHandlerOptions) => ((request: Request, env: unknown, context?: ExecutionContextLike) => Promise<Response>);
 /** Re-exported helper so callers can roundtrip envelopes in tests. */
 declare const defineRpcEnvelope: (envelope: RpcEnvelope) => RpcEnvelope;
 /**
@@ -2082,6 +2537,12 @@ interface DynamicShardRegistryOptions {
   * only if you run multiple isolated registries in one environment.
   */
   instanceName?: string;
+  /**
+  * Pin the registry DO to a Cloudflare data-residency jurisdiction. Pass the
+  * same value as the worker's `jurisdiction` so the registry co-locates with
+  * the shards it tracks. Omit for the un-pinned global namespace.
+  */
+  jurisdiction?: DurableObjectJurisdiction;
   /** DO namespace binding (`env.SHARD_REGISTRY`). */
   namespace: ShardNamespaceLike;
 }
@@ -2104,18 +2565,30 @@ interface DynamicShardRegistry extends ShardRegistry {
 }
 declare const createDynamicShardRegistry: (options: DynamicShardRegistryOptions) => DynamicShardRegistry;
 interface LunoraErrorBody {
-  error: {
-    code: string;
-    message: string;
-  };
+  error: ErrorBody;
 }
 /**
-* Error type recognised by the runtime's error middleware. Anything thrown
-* that isn't a `LunoraError` is mapped to a generic 500 with code `INTERNAL`.
+* Convert any thrown value into a JSON error response.
+*
+* Delegates the envelope + redaction to `@lunora/errors`' {@link toErrorBody} —
+* a non-internal `LunoraError` (from `@lunora/server`, this runtime, or the
+* `@lunora/do` data layer) is echoed with its `code`/`message`/`hint`/`docsUrl`;
+* an internal-coded error keeps its status but its message is redacted; anything
+* else becomes a generic `INTERNAL` 500. All of these share the unified shape
+* recognized by `isLunoraError`.
 */
-declare class LunoraError extends Error {
-  readonly code: string;
-  readonly status: number;
+declare const toErrorResponse: (error: unknown) => Response;
+/**
+* Transport-level error for the worker entry. A thin ergonomic wrapper over the
+* shared `@lunora/errors` `LunoraError` that keeps the runtime's historical
+* `(message, { code, status })` signature — the runtime mints these with
+* dispatch-specific codes (`METHOD_NOT_ALLOWED`, `*_NOT_CONFIGURED`, …) and an
+* explicit status, so they don't need a central catalog entry. Because it is a
+* real `LunoraError`, it carries the unified wire shape and is recognized by
+* `isLunoraError` everywhere. Anything thrown that isn't a `LunoraError`
+* is mapped to a generic 500 with code `INTERNAL`.
+*/
+declare class LunoraError extends LunoraError$1 {
   constructor(message: string, options?: {
     cause?: unknown;
     code?: string;
@@ -2123,10 +2596,6 @@ declare class LunoraError extends Error {
   });
   toResponse(): Response;
 }
-/** Shape recognised by the runtime's structural error checks. */
-
-/** Convert any thrown value into a JSON error response. */
-declare const toErrorResponse: (error: unknown) => Response;
 /** Shared shape for sinks that can be limited to error events only. */
 interface OnlyErrorsOption {
   /** When true, only events with `ok === false` are forwarded. */
@@ -2256,4 +2725,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 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 LunoraWorker, type MergeStrategy, type MigrationFanOutRequest, type MigrationFanOutResult, 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, combineSinks, composeWorker, consoleSink, createCrossShardRelationCapabilities, createDynamicShardRegistry, createQueryCoordinator, createStaticShardRegistry, createWorker, decorateResponse, defineRpcEnvelope, emitLogEvent, emitRpcEvent, enforceOrigin, handleCorsPreflight, mergeStrategyForAggregate, resolveSecurity, resolveShard, sentrySink, toAirbyteMessages, toErrorResponse, toFivetranResponse, webhookSink, withFrameworkWorker };
+export { type AdminTableResolver, type AirbyteMessage, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, type AnalyticsEngineSinkOptions, type AuthAdmin, type AuthCapabilities, type AuthConfigInfo, type AuthImpersonation, type AuthIntrospector, type AuthPage, type AuthSession, type AuthUser, type AuthUserFieldSpec, 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 KvIntrospector, type KvKeyEntry, type KvKeyListResult, type KvNamespaceSummary, type KvValueResult, 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 };