@nanoflags/sdk 0.3.0 → 0.4.0

package/README.md

@@ -10,7 +10,11 @@ learn about new revisions, and to send sampled telemetry. An accessor never perf
 - Entry points: `@nanoflags/sdk` (Node, browsers, edge runtimes), `@nanoflags/sdk/react`, and
   `@nanoflags/sdk/node` (test-session propagation with `AsyncLocalStorage`).
 - v2 adds [signature verification](#signature-verification) and [test sessions](#test-sessions).
-  Both are opt-in; existing code keeps working unchanged.
+- **0.4** verifies signatures **by default** when `baseUrl` is the hosted edge (`https://edge.nanoflags.io`), with
+  the production public keys embedded in the SDK, and refuses unsigned bundles there (see
+  [Signature verification](#signature-verification)). It also refuses bundles produced for a newer evaluation engine
+  (`bundle.engine`, see [Engine version](#engine-version)) and stops reconnecting when the edge reports that the
+  environment was deleted. Self-hosted edges (any other `baseUrl`) behave as in 0.3 unless `verify` is set.
 
 ## Install
 
@@ -107,7 +111,7 @@ createClient({
   bootstrap?: Bundle,
   store?: { get(): Promise<string | null>; set(v: string): Promise<void> } | false,
   events?: { enabled?: boolean /* true */, sampleRate?: number /* 0.1 */, flushIntervalMs?: number /* 10000 */, reportIntervalMs?: number /* 60000 */, redact?: (ctx) => object } | false,
-  verify?: { publicKeys: JsonWebKey[] | "fetch", require?: boolean },
+  verify?: { publicKeys?: JsonWebKey[] | "fetch", require?: boolean } | false, // default: see Signature verification
   fetch?: typeof fetch,
 })
 ```
@@ -122,7 +126,7 @@ createClient({
 | `evaluate(key, fallback, ctx?)` | The engine `Evaluation`: `value`, `reason`, `ruleIndex`, `ruleId`, `inRollout`, `bucket`, `revision`, `trace`. No type check. |
 | `session(token, { service? })` | `Promise<SessionEvaluator>` for a test session. Never rejects. See [Test sessions](#test-sessions). |
 | `useSession(token \| null)` / `sessionHeaders()` | Browser only: join or leave a test session for this page session; headers for downstream calls. |
-| `on("update" \| "error", cb)` | Returns an unsubscribe function. `update` receives `{ revision, previousRevision, checksum, source, transport, latencyMs }` (see [Updates](#updates)). `error` receives a `NanoFlagsError` with `code`: `network`, `unauthorized`, `http`, `invalid_bundle`, `store`, `config`, `signature`, `session`. |
+| `on("update" \| "error", cb)` | Returns an unsubscribe function. `update` receives `{ revision, previousRevision, checksum, source, transport, latencyMs }` (see [Updates](#updates)). `error` receives a `NanoFlagsError` with `code`: `network`, `unauthorized`, `http`, `invalid_bundle`, `store`, `config`, `signature`, `session`, `engine` (bundle for a newer engine, refused), `environment_deleted`. |
 | `refresh()` / `flush()` / `close()` | Revalidate now / send queued telemetry now / stop all background work. |
 
 ## Fallbacks and staleness
@@ -149,7 +153,9 @@ A **disabled** flag is not a fallback case: it returns the flag's configured `of
   that bundle; the SDK keeps retrying (after a failure: 1 s, 2 s, 4 s … up to the poll interval).
 
 The SDK never discards a working bundle because of an error, and never replaces a bundle with an older
-one served as last-known-good. If a key is revoked, the client reports `error` (`code: "unauthorized"`)
+one served as last-known-good. If the environment is deleted, the edge closes the live socket with code `4004`: the client reports
+`error` (`code: "environment_deleted"`), turns `stale`, keeps evaluating the last bundle and stops reconnecting
+(only the regular poll continues, which then reports the key as rejected). If a key is revoked, the client reports `error` (`code: "unauthorized"`)
 and keeps evaluating the last bundle as `stale` — revocation stops updates, it does not erase
 configuration that already reached a process.
 
@@ -194,8 +200,17 @@ carries the signature, key id and environment id). A push that does not verify c
 
 ## Signature verification
 
-Published bundles are signed by the NanoFlags publisher with Ed25519. With `verify`, the SDK checks
-the signature **before** a new bundle replaces the one in use:
+Published bundles are signed by the NanoFlags publisher with Ed25519. The SDK checks the signature **before** a new
+bundle replaces the one in use.
+
+**Default (0.4):**
+
+| `baseUrl` | `verify` not set | |
+| --- | --- | --- |
+| `https://edge.nanoflags.io` | verified against the embedded production keys (`OFFICIAL_SIGNING_KEYS`), `require: true` | pushed (WebSocket) and fetched bundles must be signed and verify |
+| any other edge | not verified (as in 0.3) | configure `verify` for a self-hosted edge |
+
+`verify: false` turns verification off explicitly. To configure it yourself:
 
 ```ts
 const flags = createClient({
@@ -207,34 +222,48 @@ const flags = createClient({
 });
 ```
 
-- A response with `X-NanoFlags-Signed: true` is verified against the canonical string
+- A response with `X-NanoFlags-Signed: true` (and every pushed bundle) is verified against the canonical string
   `nanoflags-bundle-v1\n<environment id>\n<revision>\n<checksum>\n<sha256 hex of the bundle JSON text>`
-  (the bundle text exactly as the edge sent it), using WebCrypto.
+  (the bundle text exactly as the edge sent it), using WebCrypto, with the key whose `kid` the edge names
+  (`X-NanoFlags-Key-Id`, or `kid` in the push).
 - **Bad signature → the update is rejected.** The previous bundle stays in use, `status` does not
   change, and `error` fires with `code: "signature"`. The SDK retries on its normal schedule.
 - **Unsigned bundles** (the edge sends `X-NanoFlags-Signed: false` while the publisher is catching up,
-  typically for under a minute after a publish) are accepted unless `require: true`. With `require`
-  they are rejected the same way, so a new revision arrives only once it is signed. Without `require`,
-  someone who can alter responses can also strip the signature — set `require: true` when you verify
-  for security rather than for integrity checking.
-- `publicKeys: "fetch"` loads the keys once from `GET /v1/keys` on the same edge (reloaded at most once
-  a minute when a bundle names an unknown key id). This detects corruption and tampering in storage
-  and caches, but the keys are only as trustworthy as the edge that served them. **Pin the keys in
-  your build** if the edge itself is in your threat model.
+  typically for well under a minute after a publish) are rejected when `require` is true — the default on the hosted
+  edge: the bundle in use stays, `error` (`signature`) fires, and the SDK fetches again with a short backoff (1 s,
+  2 s, 4 s … up to the poll interval) until the signed revision is there. With `require: false` (the default for
+  other edges) they are accepted; then someone who can alter responses can also strip the signature.
+- **Keys and rotation.** Keys are selected by `kid` and cached. With the embedded keys, a bundle signed with a key id
+  the SDK does not know (the hosted edge rotated its key after this SDK version was built) makes the SDK load
+  `GET /v1/keys` once and verify against those keys as well; an id that is still unknown is rejected, and the reload
+  is not repeated within a minute. `publicKeys: "fetch"` loads all keys from `GET /v1/keys` (again when an unknown
+  key id appears, at most once a minute) — this detects corruption and tampering in storage and caches, but fetched
+  keys are only as trustworthy as the edge that served them. Explicitly pinned `publicKeys` are never extended from
+  the network: **pin the keys in your build** if the edge itself is in your threat model, and add the new key before
+  a rotation (the edge lists the old key as `status: "retiring"` during the overlap).
 - After the first verified bundle the client remembers the environment id and rejects bundles signed
   for a different environment.
 - A persisted bundle (see below) is stored with its signature and verified again when restored; with
   `require`, an unsigned stored copy is ignored. A `bootstrap` bundle is trusted as given.
   With `publicKeys: "fetch"` a stored copy can only be verified once the keys were loaded, so an
-  offline start does not restore it; pinned keys do not have this limitation.
+  offline start does not restore it; pinned and embedded keys do not have this limitation.
 - Only public keys are accepted. A JWK with a private part (`d`) is ignored and reported as a `config`
   error. Private signing keys and admin keys never belong in an application.
 - Requires Ed25519 in WebCrypto: Node 20+, current Chrome, Firefox and Safari, Cloudflare Workers,
-  Deno, Bun. Where it is missing, signed bundles are rejected (they cannot be checked).
+  Deno, Bun. Where it is missing, signed bundles are rejected (they cannot be checked) — on the hosted edge pass
+  `verify: false` for such runtimes (Node 18) if you accept that.
 
 Not covered: test-session bundles (`GET /v1/session`) are not signed, and verification says nothing
 about *freshness* — it does not stop an attacker from withholding updates.
 
+## Engine version
+
+Bundles produced by the publisher carry `engine`, the version of the evaluation engine they were produced for
+(`1` today; `SUPPORTED_ENGINE_VERSION` is what this SDK evaluates). A bundle with a **newer** `engine` — a rule format
+this SDK does not understand — is refused wherever it comes from (fetch, push, store, `bootstrap`): the bundle in use
+stays, `status` does not change, and `error` fires with `code: "engine"`. Upgrade the SDK to receive it. Bundles
+without the field (older revisions, the edge's unsigned fallback) are evaluated as engine 1.
+
 ## Test sessions
 
 A test session pins a configuration snapshot and a synthetic context to a token (`nf_ts_…`, created in

package/dist/{index-DZj6xbyg.d.cts → index-D5qa8ji-.d.cts}

@@ -51,6 +51,11 @@ interface Segment {
 }
 interface Bundle {
   schema: 1;
+  /**
+   * Engine version the bundle was produced for (`ENGINE_VERSION` of the publisher). Absent in bundles from before it
+   * existed (treated as 1). SDKs refuse a bundle whose `engine` is newer than the engine they ship.
+   */
+  engine?: number;
   project: string;
   environment: string;
   /** Published revision number. 0 means "draft / never published". */
@@ -98,14 +103,35 @@ interface Store {
 interface VerifyOptions {
   /**
    * Public Ed25519 keys as JWK (`{ kty: "OKP", crv: "Ed25519", x, kid? }`), or `"fetch"` to load them
-   * once from `GET /v1/keys` on the configured edge. Pinning keys in your build is stronger than
-   * `"fetch"`: fetched keys are only as trustworthy as the connection they arrived over.
+   * once from `GET /v1/keys` on the configured edge (again, at most once a minute, when a bundle names an unknown
+   * key id). Pinning keys in your build is stronger than `"fetch"`: fetched keys are only as trustworthy as the
+   * connection they arrived over. Omitted: the embedded production keys for `https://edge.nanoflags.io`, `"fetch"`
+   * for any other edge.
+   */
+  publicKeys?: readonly JsonWebKey[] | "fetch";
+  /**
+   * Also reject bundles that carry no signature (the edge's unsigned fallback, `X-NanoFlags-Signed: false`): the SDK
+   * keeps its bundle and fetches again shortly instead. Default true for `https://edge.nanoflags.io`, false otherwise.
    */
-  publicKeys: JsonWebKey[] | "fetch";
-  /** Also reject bundles that carry no signature. Default false. */
   require?: boolean;
 }
-declare const SDK_VERSION = "0.3.0";
+/**
+ * The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+ *
+ * With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+ * (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+ * happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+ * the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+ */
+declare const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+declare const OFFICIAL_SIGNING_KEYS: readonly (JsonWebKey & {
+  kid: string;
+})[];
+declare const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+declare const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+declare const CLOSE_ENVIRONMENT_DELETED = 4004;
 /** Header that carries a test-session token between services. */
 declare const SESSION_HEADER = "x-nanoflags-session";
 type ClientStatus = "not-ready" | "ready" | "stale";
@@ -173,8 +199,12 @@ interface ClientOptions {
    * Verify bundle signatures before a new bundle replaces the current one. A bundle whose signature
    * does not verify is rejected: the previous bundle stays in use and an `error` (`code: "signature"`)
    * is emitted. Without `require`, bundles the edge marks as unsigned are still accepted.
+   *
+   * Default: with `baseUrl` = `https://edge.nanoflags.io` the SDK verifies against the embedded production keys
+   * (`OFFICIAL_SIGNING_KEYS`, plus `GET /v1/keys` once when a bundle names an unknown key id) with `require: true`;
+   * with any other `baseUrl` nothing is verified unless configured. `false` turns verification off explicitly.
    */
-  verify?: VerifyOptions;
+  verify?: VerifyOptions | false;
   fetch?: typeof fetch;
 }
 /** The flag accessors shared by the client and by session-scoped evaluators. */
@@ -262,11 +292,11 @@ interface NanoFlagsClient {
   readonly version: number;
 }
 declare class NanoFlagsError extends Error {
-  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session";
+  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted";
   readonly httpStatus?: number | undefined;
-  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session", httpStatus?: number | undefined);
+  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted", httpStatus?: number | undefined);
 }
 /** A session token is opaque; it only has to be safe to put in a header. */
 declare function isSessionToken(v: unknown): v is string;
 declare function createClient(options: ClientOptions): NanoFlagsClient;
-export { JsonValue as C, Evaluation as S, isSessionToken as _, LIVE_PROTOCOL as a, Bundle as b, SDK_VERSION as c, SessionOptions as d, Transport as f, createClient as g, WebSocketLike as h, FlagEvaluator as i, SESSION_HEADER as l, WebSocketConstructor as m, ClientStatus as n, NanoFlagsClient as o, UpdateEvent as p, EventsOptions as r, NanoFlagsError as s, ClientOptions as t, SessionEvaluator as u, VerifyOptions as v, Reason as w, Context as x, Store as y };
+export { Store as C, JsonValue as D, Evaluation as E, Reason as O, VerifyOptions as S, Context as T, WebSocketLike as _, FlagEvaluator as a, OFFICIAL_EDGE_URL as b, NanoFlagsError as c, SUPPORTED_ENGINE_VERSION as d, SessionEvaluator as f, WebSocketConstructor as g, UpdateEvent as h, EventsOptions as i, SDK_VERSION as l, Transport as m, ClientOptions as n, LIVE_PROTOCOL as o, SessionOptions as p, ClientStatus as r, NanoFlagsClient as s, CLOSE_ENVIRONMENT_DELETED as t, SESSION_HEADER as u, createClient as v, Bundle as w, OFFICIAL_SIGNING_KEYS as x, isSessionToken as y };

package/dist/{index-DZj6xbyg.d.ts → index-D5qa8ji-.d.ts}

@@ -51,6 +51,11 @@ interface Segment {
 }
 interface Bundle {
   schema: 1;
+  /**
+   * Engine version the bundle was produced for (`ENGINE_VERSION` of the publisher). Absent in bundles from before it
+   * existed (treated as 1). SDKs refuse a bundle whose `engine` is newer than the engine they ship.
+   */
+  engine?: number;
   project: string;
   environment: string;
   /** Published revision number. 0 means "draft / never published". */
@@ -98,14 +103,35 @@ interface Store {
 interface VerifyOptions {
   /**
    * Public Ed25519 keys as JWK (`{ kty: "OKP", crv: "Ed25519", x, kid? }`), or `"fetch"` to load them
-   * once from `GET /v1/keys` on the configured edge. Pinning keys in your build is stronger than
-   * `"fetch"`: fetched keys are only as trustworthy as the connection they arrived over.
+   * once from `GET /v1/keys` on the configured edge (again, at most once a minute, when a bundle names an unknown
+   * key id). Pinning keys in your build is stronger than `"fetch"`: fetched keys are only as trustworthy as the
+   * connection they arrived over. Omitted: the embedded production keys for `https://edge.nanoflags.io`, `"fetch"`
+   * for any other edge.
+   */
+  publicKeys?: readonly JsonWebKey[] | "fetch";
+  /**
+   * Also reject bundles that carry no signature (the edge's unsigned fallback, `X-NanoFlags-Signed: false`): the SDK
+   * keeps its bundle and fetches again shortly instead. Default true for `https://edge.nanoflags.io`, false otherwise.
    */
-  publicKeys: JsonWebKey[] | "fetch";
-  /** Also reject bundles that carry no signature. Default false. */
   require?: boolean;
 }
-declare const SDK_VERSION = "0.3.0";
+/**
+ * The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+ *
+ * With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+ * (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+ * happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+ * the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+ */
+declare const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+declare const OFFICIAL_SIGNING_KEYS: readonly (JsonWebKey & {
+  kid: string;
+})[];
+declare const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+declare const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+declare const CLOSE_ENVIRONMENT_DELETED = 4004;
 /** Header that carries a test-session token between services. */
 declare const SESSION_HEADER = "x-nanoflags-session";
 type ClientStatus = "not-ready" | "ready" | "stale";
@@ -173,8 +199,12 @@ interface ClientOptions {
    * Verify bundle signatures before a new bundle replaces the current one. A bundle whose signature
    * does not verify is rejected: the previous bundle stays in use and an `error` (`code: "signature"`)
    * is emitted. Without `require`, bundles the edge marks as unsigned are still accepted.
+   *
+   * Default: with `baseUrl` = `https://edge.nanoflags.io` the SDK verifies against the embedded production keys
+   * (`OFFICIAL_SIGNING_KEYS`, plus `GET /v1/keys` once when a bundle names an unknown key id) with `require: true`;
+   * with any other `baseUrl` nothing is verified unless configured. `false` turns verification off explicitly.
    */
-  verify?: VerifyOptions;
+  verify?: VerifyOptions | false;
   fetch?: typeof fetch;
 }
 /** The flag accessors shared by the client and by session-scoped evaluators. */
@@ -262,11 +292,11 @@ interface NanoFlagsClient {
   readonly version: number;
 }
 declare class NanoFlagsError extends Error {
-  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session";
+  readonly code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted";
   readonly httpStatus?: number | undefined;
-  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session", httpStatus?: number | undefined);
+  constructor(message: string, code: "network" | "unauthorized" | "http" | "invalid_bundle" | "store" | "config" | "signature" | "session" | "engine" | "environment_deleted", httpStatus?: number | undefined);
 }
 /** A session token is opaque; it only has to be safe to put in a header. */
 declare function isSessionToken(v: unknown): v is string;
 declare function createClient(options: ClientOptions): NanoFlagsClient;
-export { JsonValue as C, Evaluation as S, isSessionToken as _, LIVE_PROTOCOL as a, Bundle as b, SDK_VERSION as c, SessionOptions as d, Transport as f, createClient as g, WebSocketLike as h, FlagEvaluator as i, SESSION_HEADER as l, WebSocketConstructor as m, ClientStatus as n, NanoFlagsClient as o, UpdateEvent as p, EventsOptions as r, NanoFlagsError as s, ClientOptions as t, SessionEvaluator as u, VerifyOptions as v, Reason as w, Context as x, Store as y };
+export { Store as C, JsonValue as D, Evaluation as E, Reason as O, VerifyOptions as S, Context as T, WebSocketLike as _, FlagEvaluator as a, OFFICIAL_EDGE_URL as b, NanoFlagsError as c, SUPPORTED_ENGINE_VERSION as d, SessionEvaluator as f, WebSocketConstructor as g, UpdateEvent as h, EventsOptions as i, SDK_VERSION as l, Transport as m, ClientOptions as n, LIVE_PROTOCOL as o, SessionOptions as p, ClientStatus as r, NanoFlagsClient as s, CLOSE_ENVIRONMENT_DELETED as t, SESSION_HEADER as u, createClient as v, Bundle as w, OFFICIAL_SIGNING_KEYS as x, isSessionToken as y };

package/dist/index.cjs

@@ -1,8 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-B58PLGGE.cjs");
+const require_src = require("./src-IVd-Wps4.cjs");
+exports.CLOSE_ENVIRONMENT_DELETED = require_src.CLOSE_ENVIRONMENT_DELETED;
 exports.LIVE_PROTOCOL = require_src.LIVE_PROTOCOL;
 exports.NanoFlagsError = require_src.NanoFlagsError;
+exports.OFFICIAL_EDGE_URL = require_src.OFFICIAL_EDGE_URL;
+exports.OFFICIAL_SIGNING_KEYS = require_src.OFFICIAL_SIGNING_KEYS;
 exports.SDK_VERSION = require_src.SDK_VERSION;
 exports.SESSION_HEADER = require_src.SESSION_HEADER;
+exports.SUPPORTED_ENGINE_VERSION = require_src.SUPPORTED_ENGINE_VERSION;
 exports.createClient = require_src.createClient;
 exports.isSessionToken = require_src.isSessionToken;

package/dist/index.d.cts

@@ -9,5 +9,5 @@
  * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
  * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
  */
-import { C as JsonValue, S as Evaluation, _ as isSessionToken, a as LIVE_PROTOCOL, b as Bundle, c as SDK_VERSION, d as SessionOptions, f as Transport, g as createClient, h as WebSocketLike, i as FlagEvaluator, l as SESSION_HEADER, m as WebSocketConstructor, n as ClientStatus, o as NanoFlagsClient, p as UpdateEvent, r as EventsOptions, s as NanoFlagsError, t as ClientOptions, u as SessionEvaluator, v as VerifyOptions, w as Reason, x as Context, y as Store } from "./index-DZj6xbyg.cjs";
-export { type Bundle, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, type Reason, SDK_VERSION, SESSION_HEADER, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };
+import { C as Store, D as JsonValue, E as Evaluation, O as Reason, S as VerifyOptions, T as Context, _ as WebSocketLike, a as FlagEvaluator, b as OFFICIAL_EDGE_URL, c as NanoFlagsError, d as SUPPORTED_ENGINE_VERSION, f as SessionEvaluator, g as WebSocketConstructor, h as UpdateEvent, i as EventsOptions, l as SDK_VERSION, m as Transport, n as ClientOptions, o as LIVE_PROTOCOL, p as SessionOptions, r as ClientStatus, s as NanoFlagsClient, t as CLOSE_ENVIRONMENT_DELETED, u as SESSION_HEADER, v as createClient, w as Bundle, x as OFFICIAL_SIGNING_KEYS, y as isSessionToken } from "./index-D5qa8ji-.cjs";
+export { type Bundle, CLOSE_ENVIRONMENT_DELETED, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, OFFICIAL_EDGE_URL, OFFICIAL_SIGNING_KEYS, type Reason, SDK_VERSION, SESSION_HEADER, SUPPORTED_ENGINE_VERSION, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };

package/dist/index.d.ts

@@ -9,5 +9,5 @@
  * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
  * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
  */
-import { C as JsonValue, S as Evaluation, _ as isSessionToken, a as LIVE_PROTOCOL, b as Bundle, c as SDK_VERSION, d as SessionOptions, f as Transport, g as createClient, h as WebSocketLike, i as FlagEvaluator, l as SESSION_HEADER, m as WebSocketConstructor, n as ClientStatus, o as NanoFlagsClient, p as UpdateEvent, r as EventsOptions, s as NanoFlagsError, t as ClientOptions, u as SessionEvaluator, v as VerifyOptions, w as Reason, x as Context, y as Store } from "./index-DZj6xbyg.js";
-export { type Bundle, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, type Reason, SDK_VERSION, SESSION_HEADER, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };
+import { C as Store, D as JsonValue, E as Evaluation, O as Reason, S as VerifyOptions, T as Context, _ as WebSocketLike, a as FlagEvaluator, b as OFFICIAL_EDGE_URL, c as NanoFlagsError, d as SUPPORTED_ENGINE_VERSION, f as SessionEvaluator, g as WebSocketConstructor, h as UpdateEvent, i as EventsOptions, l as SDK_VERSION, m as Transport, n as ClientOptions, o as LIVE_PROTOCOL, p as SessionOptions, r as ClientStatus, s as NanoFlagsClient, t as CLOSE_ENVIRONMENT_DELETED, u as SESSION_HEADER, v as createClient, w as Bundle, x as OFFICIAL_SIGNING_KEYS, y as isSessionToken } from "./index-D5qa8ji-.js";
+export { type Bundle, CLOSE_ENVIRONMENT_DELETED, ClientOptions, ClientStatus, type Context, type Evaluation, EventsOptions, FlagEvaluator, type JsonValue, LIVE_PROTOCOL, NanoFlagsClient, NanoFlagsError, OFFICIAL_EDGE_URL, OFFICIAL_SIGNING_KEYS, type Reason, SDK_VERSION, SESSION_HEADER, SUPPORTED_ENGINE_VERSION, SessionEvaluator, SessionOptions, type Store, Transport, UpdateEvent, type VerifyOptions, WebSocketConstructor, WebSocketLike, createClient, isSessionToken };

package/dist/index.js

@@ -1 +1 @@
-export { t as LIVE_PROTOCOL, n as NanoFlagsError, r as SDK_VERSION, i as SESSION_HEADER, a as createClient, o as isSessionToken } from "./src-DUF_NkBY.js";
+export { t as CLOSE_ENVIRONMENT_DELETED, n as LIVE_PROTOCOL, r as NanoFlagsError, l as OFFICIAL_EDGE_URL, u as OFFICIAL_SIGNING_KEYS, i as SDK_VERSION, a as SESSION_HEADER, o as SUPPORTED_ENGINE_VERSION, s as createClient, c as isSessionToken } from "./src-CVTvEKbT.js";

package/dist/node.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-B58PLGGE.cjs");
+const require_src = require("./src-IVd-Wps4.cjs");
 // src/node.ts
 /**
 * @nanoflags/sdk/node — test-session propagation for Node servers.

package/dist/node.d.cts

@@ -1,4 +1,4 @@
-import { d as SessionOptions, i as FlagEvaluator, l as SESSION_HEADER, o as NanoFlagsClient, u as SessionEvaluator } from "./index-DZj6xbyg.cjs";
+import { a as FlagEvaluator, f as SessionEvaluator, p as SessionOptions, s as NanoFlagsClient, u as SESSION_HEADER } from "./index-D5qa8ji-.cjs";
 type SessionClient = Pick<NanoFlagsClient, "session"> & FlagEvaluator & Pick<NanoFlagsClient, "revision">;
 /** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
 export declare function withSession<T>(token: string | null | undefined, fn: () => T): T;

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { d as SessionOptions, i as FlagEvaluator, l as SESSION_HEADER, o as NanoFlagsClient, u as SessionEvaluator } from "./index-DZj6xbyg.js";
+import { a as FlagEvaluator, f as SessionEvaluator, p as SessionOptions, s as NanoFlagsClient, u as SESSION_HEADER } from "./index-D5qa8ji-.js";
 type SessionClient = Pick<NanoFlagsClient, "session"> & FlagEvaluator & Pick<NanoFlagsClient, "revision">;
 /** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
 export declare function withSession<T>(token: string | null | undefined, fn: () => T): T;

package/dist/node.js

@@ -1,4 +1,4 @@
-import { i as SESSION_HEADER, o as isSessionToken } from "./src-DUF_NkBY.js";
+import { a as SESSION_HEADER, c as isSessionToken } from "./src-CVTvEKbT.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 // src/node.ts
 /**

package/dist/react.d.cts

@@ -2,7 +2,7 @@
  * @nanoflags/sdk/react — bindings built on useSyncExternalStore.
  * Components re-render when the bundle or the client status changes; evaluation stays local.
  */
-import { C as JsonValue, n as ClientStatus, o as NanoFlagsClient, x as Context } from "./index-DZj6xbyg.cjs";
+import { D as JsonValue, T as Context, r as ClientStatus, s as NanoFlagsClient } from "./index-D5qa8ji-.cjs";
 import { ReactElement, ReactNode } from "react";
 export interface NanoFlagsProviderProps {
   client: NanoFlagsClient;

package/dist/react.d.ts

@@ -2,7 +2,7 @@
  * @nanoflags/sdk/react — bindings built on useSyncExternalStore.
  * Components re-render when the bundle or the client status changes; evaluation stays local.
  */
-import { C as JsonValue, n as ClientStatus, o as NanoFlagsClient, x as Context } from "./index-DZj6xbyg.js";
+import { D as JsonValue, T as Context, r as ClientStatus, s as NanoFlagsClient } from "./index-D5qa8ji-.js";
 import { ReactElement, ReactNode } from "react";
 export interface NanoFlagsProviderProps {
   client: NanoFlagsClient;

package/dist/{src-B58PLGGE.cjs → src-CVTvEKbT.js}

@@ -1,4 +1,3 @@
-// ../engine/src/index.ts
 const encoder$1 = new TextEncoder();
 /** MurmurHash3 x86 32-bit over UTF-8 bytes. Used for distribution only — never for security. */
 function murmur3(input, seed = 0) {
@@ -264,6 +263,27 @@ function evaluate(bundle, flagKey, ctx, fallback) {
 function fmt(v) {
 	return typeof v === "string" ? v : JSON.stringify(v);
 }
+/** True when this engine can evaluate `bundle` (its `engine` is absent or not newer than `ENGINE_VERSION`). */
+function supportsEngine(bundle) {
+	const e = bundle.engine;
+	return e === void 0 || typeof e === "number" && Number.isInteger(e) && e >= 1 && e <= 1;
+}
+// src/keys.ts
+/**
+* The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+*
+* With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+* (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+* happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+* the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+*/
+const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+const OFFICIAL_SIGNING_KEYS = Object.freeze([Object.freeze({
+	kty: "OKP",
+	crv: "Ed25519",
+	x: "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U",
+	kid: "k1"
+})]);
 // src/store.ts
 const DB = "nanoflags";
 const OBJECT_STORE = "bundles";
@@ -496,7 +516,11 @@ function rawMember(text, member) {
 * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
 * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
 */
-const SDK_VERSION = "0.3.0";
+const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+const CLOSE_ENVIRONMENT_DELETED = 4004;
 /** Header that carries a test-session token between services. */
 const SESSION_HEADER = "x-nanoflags-session";
 /** WebSocket subprotocol of `/v1/live`. The key travels as a second protocol entry, never in the URL. */
@@ -539,6 +563,9 @@ function isBundle(v) {
 	const b = v;
 	return b.schema === 1 && typeof b.revision === "number" && typeof b.flags === "object" && b.flags !== null && !Array.isArray(b.flags) && typeof b.segments === "object" && b.segments !== null;
 }
+function engineError(b) {
+	return new NanoFlagsError(`Bundle r${String(b.revision)} needs evaluation engine ${JSON.stringify(b.engine)}; this SDK supports up to 1. Upgrade @nanoflags/sdk. The configuration in use is unchanged.`, "engine");
+}
 function typeOf(v) {
 	return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
 }
@@ -583,15 +610,38 @@ function createClient(options) {
 	let liveOpen = false;
 	let liveAttempt = 0;
 	let liveTimer = null;
+	/** The edge closed the socket with 4004: the environment was deleted. No more reconnects. */
+	let environmentDeleted = false;
 	/** Highest revision adopted from a push: a slower HTTP answer must never replace it with something older. */
 	let liveRevision = 0;
 	let pushChain = Promise.resolve();
 	let lastReportAt = 0;
 	const usedAttrs = /* @__PURE__ */ new WeakMap();
-	const verifyOpt = options.verify;
+	/**
+	* Effective verification: `keys` to verify with (`"fetch"` = only `/v1/keys`), `require` = refuse unsigned bundles,
+	* `refetch` = an unknown key id loads `/v1/keys` once (official edge with the embedded keys, or `"fetch"`).
+	*/
+	const official = baseUrl === OFFICIAL_EDGE_URL;
+	const verifyOpt = (() => {
+		const v = options.verify;
+		if (v === false) return null;
+		if (v === void 0 || v === null) return official ? {
+			keys: OFFICIAL_SIGNING_KEYS,
+			require: true,
+			refetch: true
+		} : null;
+		const keys = v.publicKeys === "fetch" ? "fetch" : Array.isArray(v.publicKeys) ? v.publicKeys : official ? OFFICIAL_SIGNING_KEYS : "fetch";
+		return {
+			keys,
+			require: v.require ?? official,
+			refetch: keys === "fetch" || official && v.publicKeys === void 0
+		};
+	})();
 	const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
-	let keysPromise = null;
-	let keysLoadedAt = 0;
+	let pinnedKeys = null;
+	let fetchedKeys = [];
+	let keysFetchedAt = 0;
+	let keysFetching = null;
 	let pinnedEnvironment = null;
 	let sig = null;
 	let rawText = null;
@@ -667,6 +717,7 @@ function createClient(options) {
 			if (!raw || closed) return;
 			const p = JSON.parse(raw);
 			if (p.v !== 1 || p.id !== id || !isBundle(p.bundle)) return;
+			if (!supportsEngine(p.bundle)) return void emitError(engineError(p.bundle));
 			if (bundle && bundle.revision >= p.bundle.revision) return;
 			let restored = p.bundle;
 			let restoredSig = null;
@@ -752,20 +803,38 @@ function createClient(options) {
 			clearTimeout(t);
 		}
 	}
-	function loadKeys(kid) {
-		if (!verifyOpt) return Promise.resolve([]);
-		const start = () => {
-			keysLoadedAt = Date.now();
-			const p = verifyOpt.publicKeys === "fetch" ? fetchKeys() : importPublicKeys(Array.isArray(verifyOpt.publicKeys) ? verifyOpt.publicKeys : []);
-			keysPromise = p;
+	/**
+	* Keys to verify a signature by `kid` with: the pinned / embedded keys, plus those fetched from `/v1/keys`. With
+	* `refetch`, a key id none of them has (rotation) loads `/v1/keys` once — again at most once a minute.
+	*/
+	async function loadKeys(kid) {
+		if (!verifyOpt) return [];
+		let base = [];
+		if (verifyOpt.keys !== "fetch") {
+			const p = pinnedKeys ??= importPublicKeys(verifyOpt.keys);
 			p.catch(() => {
-				if (keysPromise === p) keysPromise = null;
+				if (pinnedKeys === p) pinnedKeys = null;
 			});
-			return p;
-		};
-		if (!keysPromise) return start();
-		if (verifyOpt.publicKeys !== "fetch" || kid === null) return keysPromise;
-		return keysPromise.then((keys) => keys.some((k) => k.kid === kid) || Date.now() - keysLoadedAt < KEYS_REFETCH_MS ? keys : start());
+			base = await p;
+		}
+		const all = () => [...base, ...fetchedKeys];
+		if (!verifyOpt.refetch) return base;
+		const known = all();
+		if (known.length > 0 && (kid === null || known.some((k) => k.kid === kid))) return known;
+		if (keysFetchedAt !== 0 && Date.now() - keysFetchedAt < KEYS_REFETCH_MS) return known;
+		keysFetching ??= fetchKeys().then((keys) => {
+			fetchedKeys = keys;
+			keysFetchedAt = Date.now();
+		}).finally(() => {
+			keysFetching = null;
+		});
+		try {
+			await keysFetching;
+		} catch (e) {
+			if (base.length === 0) throw e;
+			keysFetchedAt = Date.now();
+		}
+		return all();
 	}
 	/** Returns the bundle to adopt, or throws a NanoFlagsError with code "signature". */
 	async function checkSignature(res, text, body) {
@@ -776,7 +845,7 @@ function createClient(options) {
 		};
 		const reject = (why) => new NanoFlagsError(`Bundle r${body.bundle.revision} was rejected: ${why} The configuration in use is unchanged.`, "signature");
 		if (res.headers.get("X-NanoFlags-Signed") !== "true") {
-			if (verifyOpt.require) throw reject("it is not signed and `verify.require` is set.");
+			if (verifyOpt.require) throw reject("it is not signed (the edge is still distributing it) and unsigned bundles are refused (`verify.require`); fetching again shortly.");
 			return {
 				bundle: body.bundle,
 				sig: null,
@@ -860,6 +929,7 @@ function createClient(options) {
 			const verified = await checkSignature(res, text, body);
 			if (closed) return;
 			const next = verified.bundle;
+			if (!supportsEngine(next)) throw engineError(next);
 			failures = 0;
 			if (servedStale && bundle && bundle.revision >= next.revision) {
 				setStatus("stale");
@@ -878,6 +948,7 @@ function createClient(options) {
 			persist();
 		} catch (e) {
 			if (closed) return;
+			if (e instanceof NanoFlagsError && e.code === "engine") return void emitError(e);
 			failures++;
 			if (e instanceof NanoFlagsError && e.code === "signature") return void emitError(e);
 			if (e instanceof NanoFlagsError && e.code === "unauthorized") dropLive();
@@ -924,7 +995,7 @@ function createClient(options) {
 		} catch {}
 	}
 	function startStream() {
-		if (closed || options.streaming === false || !doFetch || streamActive) return;
+		if (closed || options.streaming === false || !doFetch || streamActive || environmentDeleted) return;
 		streamActive = true;
 		const ES = typeof EventSource === "function" ? EventSource : void 0;
 		if (ES && isBrowserKey) {
@@ -1023,6 +1094,7 @@ function createClient(options) {
 			parsed = null;
 		}
 		if (!isBundle(parsed) || parsed.revision !== revision) return void emitError(new NanoFlagsError("The edge pushed an invalid bundle; it was ignored.", "invalid_bundle"));
+		if (!supportsEngine(parsed)) return void emitError(engineError(parsed));
 		if (bundle && revision < bundle.revision) return;
 		failures = 0;
 		if (bundle && revision === bundle.revision) {
@@ -1051,7 +1123,7 @@ function createClient(options) {
 		} catch {}
 	}
 	function connectLive() {
-		if (closed || !liveWanted || socket) return;
+		if (closed || !liveWanted || socket || environmentDeleted) return;
 		let ws;
 		try {
 			ws = new WS(liveUrl, [LIVE_PROTOCOL, `key.${sdkKey}`]);
@@ -1121,11 +1193,21 @@ function createClient(options) {
 			if (typeof m !== "object" || m === null || Array.isArray(m)) return;
 			pushChain = pushChain.then(() => applyPush(m)).catch(() => void 0);
 		};
-		ws.onclose = end;
+		ws.onclose = (event) => {
+			if (event?.code === 4004) environmentDeleted = true;
+			end();
+		};
 		ws.onerror = end;
 	}
 	function liveEnded(opened, openMs, rotating) {
 		if (closed) return;
+		if (environmentDeleted) {
+			stopStream();
+			if (bundle) setStatus("stale");
+			emitError(new NanoFlagsError("The environment of this SDK key was deleted. The last configuration stays in use; it will not be updated.", "environment_deleted"));
+			schedulePoll();
+			return;
+		}
 		if (rotating) return connectLive();
 		liveAttempt = opened && openMs > 3e4 ? 1 : liveAttempt + 1;
 		if (!opened) startStream();
@@ -1439,7 +1521,10 @@ function createClient(options) {
 		}
 	};
 	if (options.bootstrap !== void 0) {
-		if (isBundle(options.bootstrap)) adopt(options.bootstrap, {
+		if (isBundle(options.bootstrap) && !supportsEngine(options.bootstrap)) {
+			const err = engineError(options.bootstrap);
+			queueMicrotask(() => emitError(err));
+		} else if (isBundle(options.bootstrap)) adopt(options.bootstrap, {
 			etag: null,
 			checksum: null,
 			status: "ready",
@@ -1447,7 +1532,7 @@ function createClient(options) {
 		});
 		else queueMicrotask(() => emitError(new NanoFlagsError("The bootstrap bundle is invalid and was ignored.", "invalid_bundle")));
 	}
-	if (verifyOpt && Array.isArray(verifyOpt.publicKeys) && verifyOpt.publicKeys.some((k) => !isPublicEd25519Jwk(k))) queueMicrotask(() => emitError(new NanoFlagsError("`verify.publicKeys` must contain public Ed25519 JWKs only. Other entries (including private keys) were ignored.", "config")));
+	if (verifyOpt && Array.isArray(verifyOpt.keys) && verifyOpt.keys.some((k) => !isPublicEd25519Jwk(k))) queueMicrotask(() => emitError(new NanoFlagsError("`verify.publicKeys` must contain public Ed25519 JWKs only. Other entries (including private keys) were ignored.", "config")));
 	if (typeof sdkKey !== "string" || sdkKey === "" || baseUrl === "") {
 		queueMicrotask(() => emitError(new NanoFlagsError("`sdkKey` and `baseUrl` are required.", "config")));
 		resolveReady();
@@ -1468,39 +1553,4 @@ function createClient(options) {
 	if (doc && typeof addEventListener === "function") addEventListener("online", onOnline);
 	return client;
 }
-Object.defineProperty(exports, "LIVE_PROTOCOL", {
-	enumerable: true,
-	get: function() {
-		return LIVE_PROTOCOL;
-	}
-});
-Object.defineProperty(exports, "NanoFlagsError", {
-	enumerable: true,
-	get: function() {
-		return NanoFlagsError;
-	}
-});
-Object.defineProperty(exports, "SDK_VERSION", {
-	enumerable: true,
-	get: function() {
-		return SDK_VERSION;
-	}
-});
-Object.defineProperty(exports, "SESSION_HEADER", {
-	enumerable: true,
-	get: function() {
-		return SESSION_HEADER;
-	}
-});
-Object.defineProperty(exports, "createClient", {
-	enumerable: true,
-	get: function() {
-		return createClient;
-	}
-});
-Object.defineProperty(exports, "isSessionToken", {
-	enumerable: true,
-	get: function() {
-		return isSessionToken;
-	}
-});
+export { SESSION_HEADER as a, isSessionToken as c, SDK_VERSION as i, OFFICIAL_EDGE_URL as l, LIVE_PROTOCOL as n, SUPPORTED_ENGINE_VERSION as o, NanoFlagsError as r, createClient as s, CLOSE_ENVIRONMENT_DELETED as t, OFFICIAL_SIGNING_KEYS as u };

package/dist/{src-DUF_NkBY.js → src-IVd-Wps4.cjs}

@@ -1,4 +1,3 @@
-// ../engine/src/index.ts
 const encoder$1 = new TextEncoder();
 /** MurmurHash3 x86 32-bit over UTF-8 bytes. Used for distribution only — never for security. */
 function murmur3(input, seed = 0) {
@@ -264,6 +263,27 @@ function evaluate(bundle, flagKey, ctx, fallback) {
 function fmt(v) {
 	return typeof v === "string" ? v : JSON.stringify(v);
 }
+/** True when this engine can evaluate `bundle` (its `engine` is absent or not newer than `ENGINE_VERSION`). */
+function supportsEngine(bundle) {
+	const e = bundle.engine;
+	return e === void 0 || typeof e === "number" && Number.isInteger(e) && e >= 1 && e <= 1;
+}
+// src/keys.ts
+/**
+* The hosted NanoFlags edge and the public halves of its bundle-signing keys (Ed25519, safe to embed).
+*
+* With `baseUrl` equal to `OFFICIAL_EDGE_URL` the SDK verifies every bundle against these keys by default
+* (`verify.require` defaults to true there). A bundle signed with a key id that is not listed here — a rotation that
+* happened after this SDK version was built — makes the SDK load `GET /v1/keys` from the edge once and verify against
+* the keys it lists as well. Rotation procedure: RUNTIME.md, "Signing-key rotation".
+*/
+const OFFICIAL_EDGE_URL = "https://edge.nanoflags.io";
+const OFFICIAL_SIGNING_KEYS = Object.freeze([Object.freeze({
+	kty: "OKP",
+	crv: "Ed25519",
+	x: "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U",
+	kid: "k1"
+})]);
 // src/store.ts
 const DB = "nanoflags";
 const OBJECT_STORE = "bundles";
@@ -496,7 +516,11 @@ function rawMember(text, member) {
 * the edge pushes the signed bundle itself — no request follows), the SSE stream (`/v1/stream`,
 * a notification followed by a conditional fetch), and polling (`/v1/bundle`).
 */
-const SDK_VERSION = "0.3.0";
+const SDK_VERSION = "0.4.0";
+/** Newest bundle format (`bundle.engine`) this SDK can evaluate. Newer bundles are refused; the previous one stays in use. */
+const SUPPORTED_ENGINE_VERSION = 1;
+/** WebSocket close code of the edge for an environment that was deleted: the SDK stops reconnecting. */
+const CLOSE_ENVIRONMENT_DELETED = 4004;
 /** Header that carries a test-session token between services. */
 const SESSION_HEADER = "x-nanoflags-session";
 /** WebSocket subprotocol of `/v1/live`. The key travels as a second protocol entry, never in the URL. */
@@ -539,6 +563,9 @@ function isBundle(v) {
 	const b = v;
 	return b.schema === 1 && typeof b.revision === "number" && typeof b.flags === "object" && b.flags !== null && !Array.isArray(b.flags) && typeof b.segments === "object" && b.segments !== null;
 }
+function engineError(b) {
+	return new NanoFlagsError(`Bundle r${String(b.revision)} needs evaluation engine ${JSON.stringify(b.engine)}; this SDK supports up to 1. Upgrade @nanoflags/sdk. The configuration in use is unchanged.`, "engine");
+}
 function typeOf(v) {
 	return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
 }
@@ -583,15 +610,38 @@ function createClient(options) {
 	let liveOpen = false;
 	let liveAttempt = 0;
 	let liveTimer = null;
+	/** The edge closed the socket with 4004: the environment was deleted. No more reconnects. */
+	let environmentDeleted = false;
 	/** Highest revision adopted from a push: a slower HTTP answer must never replace it with something older. */
 	let liveRevision = 0;
 	let pushChain = Promise.resolve();
 	let lastReportAt = 0;
 	const usedAttrs = /* @__PURE__ */ new WeakMap();
-	const verifyOpt = options.verify;
+	/**
+	* Effective verification: `keys` to verify with (`"fetch"` = only `/v1/keys`), `require` = refuse unsigned bundles,
+	* `refetch` = an unknown key id loads `/v1/keys` once (official edge with the embedded keys, or `"fetch"`).
+	*/
+	const official = baseUrl === OFFICIAL_EDGE_URL;
+	const verifyOpt = (() => {
+		const v = options.verify;
+		if (v === false) return null;
+		if (v === void 0 || v === null) return official ? {
+			keys: OFFICIAL_SIGNING_KEYS,
+			require: true,
+			refetch: true
+		} : null;
+		const keys = v.publicKeys === "fetch" ? "fetch" : Array.isArray(v.publicKeys) ? v.publicKeys : official ? OFFICIAL_SIGNING_KEYS : "fetch";
+		return {
+			keys,
+			require: v.require ?? official,
+			refetch: keys === "fetch" || official && v.publicKeys === void 0
+		};
+	})();
 	const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
-	let keysPromise = null;
-	let keysLoadedAt = 0;
+	let pinnedKeys = null;
+	let fetchedKeys = [];
+	let keysFetchedAt = 0;
+	let keysFetching = null;
 	let pinnedEnvironment = null;
 	let sig = null;
 	let rawText = null;
@@ -667,6 +717,7 @@ function createClient(options) {
 			if (!raw || closed) return;
 			const p = JSON.parse(raw);
 			if (p.v !== 1 || p.id !== id || !isBundle(p.bundle)) return;
+			if (!supportsEngine(p.bundle)) return void emitError(engineError(p.bundle));
 			if (bundle && bundle.revision >= p.bundle.revision) return;
 			let restored = p.bundle;
 			let restoredSig = null;
@@ -752,20 +803,38 @@ function createClient(options) {
 			clearTimeout(t);
 		}
 	}
-	function loadKeys(kid) {
-		if (!verifyOpt) return Promise.resolve([]);
-		const start = () => {
-			keysLoadedAt = Date.now();
-			const p = verifyOpt.publicKeys === "fetch" ? fetchKeys() : importPublicKeys(Array.isArray(verifyOpt.publicKeys) ? verifyOpt.publicKeys : []);
-			keysPromise = p;
+	/**
+	* Keys to verify a signature by `kid` with: the pinned / embedded keys, plus those fetched from `/v1/keys`. With
+	* `refetch`, a key id none of them has (rotation) loads `/v1/keys` once — again at most once a minute.
+	*/
+	async function loadKeys(kid) {
+		if (!verifyOpt) return [];
+		let base = [];
+		if (verifyOpt.keys !== "fetch") {
+			const p = pinnedKeys ??= importPublicKeys(verifyOpt.keys);
 			p.catch(() => {
-				if (keysPromise === p) keysPromise = null;
+				if (pinnedKeys === p) pinnedKeys = null;
 			});
-			return p;
-		};
-		if (!keysPromise) return start();
-		if (verifyOpt.publicKeys !== "fetch" || kid === null) return keysPromise;
-		return keysPromise.then((keys) => keys.some((k) => k.kid === kid) || Date.now() - keysLoadedAt < KEYS_REFETCH_MS ? keys : start());
+			base = await p;
+		}
+		const all = () => [...base, ...fetchedKeys];
+		if (!verifyOpt.refetch) return base;
+		const known = all();
+		if (known.length > 0 && (kid === null || known.some((k) => k.kid === kid))) return known;
+		if (keysFetchedAt !== 0 && Date.now() - keysFetchedAt < KEYS_REFETCH_MS) return known;
+		keysFetching ??= fetchKeys().then((keys) => {
+			fetchedKeys = keys;
+			keysFetchedAt = Date.now();
+		}).finally(() => {
+			keysFetching = null;
+		});
+		try {
+			await keysFetching;
+		} catch (e) {
+			if (base.length === 0) throw e;
+			keysFetchedAt = Date.now();
+		}
+		return all();
 	}
 	/** Returns the bundle to adopt, or throws a NanoFlagsError with code "signature". */
 	async function checkSignature(res, text, body) {
@@ -776,7 +845,7 @@ function createClient(options) {
 		};
 		const reject = (why) => new NanoFlagsError(`Bundle r${body.bundle.revision} was rejected: ${why} The configuration in use is unchanged.`, "signature");
 		if (res.headers.get("X-NanoFlags-Signed") !== "true") {
-			if (verifyOpt.require) throw reject("it is not signed and `verify.require` is set.");
+			if (verifyOpt.require) throw reject("it is not signed (the edge is still distributing it) and unsigned bundles are refused (`verify.require`); fetching again shortly.");
 			return {
 				bundle: body.bundle,
 				sig: null,
@@ -860,6 +929,7 @@ function createClient(options) {
 			const verified = await checkSignature(res, text, body);
 			if (closed) return;
 			const next = verified.bundle;
+			if (!supportsEngine(next)) throw engineError(next);
 			failures = 0;
 			if (servedStale && bundle && bundle.revision >= next.revision) {
 				setStatus("stale");
@@ -878,6 +948,7 @@ function createClient(options) {
 			persist();
 		} catch (e) {
 			if (closed) return;
+			if (e instanceof NanoFlagsError && e.code === "engine") return void emitError(e);
 			failures++;
 			if (e instanceof NanoFlagsError && e.code === "signature") return void emitError(e);
 			if (e instanceof NanoFlagsError && e.code === "unauthorized") dropLive();
@@ -924,7 +995,7 @@ function createClient(options) {
 		} catch {}
 	}
 	function startStream() {
-		if (closed || options.streaming === false || !doFetch || streamActive) return;
+		if (closed || options.streaming === false || !doFetch || streamActive || environmentDeleted) return;
 		streamActive = true;
 		const ES = typeof EventSource === "function" ? EventSource : void 0;
 		if (ES && isBrowserKey) {
@@ -1023,6 +1094,7 @@ function createClient(options) {
 			parsed = null;
 		}
 		if (!isBundle(parsed) || parsed.revision !== revision) return void emitError(new NanoFlagsError("The edge pushed an invalid bundle; it was ignored.", "invalid_bundle"));
+		if (!supportsEngine(parsed)) return void emitError(engineError(parsed));
 		if (bundle && revision < bundle.revision) return;
 		failures = 0;
 		if (bundle && revision === bundle.revision) {
@@ -1051,7 +1123,7 @@ function createClient(options) {
 		} catch {}
 	}
 	function connectLive() {
-		if (closed || !liveWanted || socket) return;
+		if (closed || !liveWanted || socket || environmentDeleted) return;
 		let ws;
 		try {
 			ws = new WS(liveUrl, [LIVE_PROTOCOL, `key.${sdkKey}`]);
@@ -1121,11 +1193,21 @@ function createClient(options) {
 			if (typeof m !== "object" || m === null || Array.isArray(m)) return;
 			pushChain = pushChain.then(() => applyPush(m)).catch(() => void 0);
 		};
-		ws.onclose = end;
+		ws.onclose = (event) => {
+			if (event?.code === 4004) environmentDeleted = true;
+			end();
+		};
 		ws.onerror = end;
 	}
 	function liveEnded(opened, openMs, rotating) {
 		if (closed) return;
+		if (environmentDeleted) {
+			stopStream();
+			if (bundle) setStatus("stale");
+			emitError(new NanoFlagsError("The environment of this SDK key was deleted. The last configuration stays in use; it will not be updated.", "environment_deleted"));
+			schedulePoll();
+			return;
+		}
 		if (rotating) return connectLive();
 		liveAttempt = opened && openMs > 3e4 ? 1 : liveAttempt + 1;
 		if (!opened) startStream();
@@ -1439,7 +1521,10 @@ function createClient(options) {
 		}
 	};
 	if (options.bootstrap !== void 0) {
-		if (isBundle(options.bootstrap)) adopt(options.bootstrap, {
+		if (isBundle(options.bootstrap) && !supportsEngine(options.bootstrap)) {
+			const err = engineError(options.bootstrap);
+			queueMicrotask(() => emitError(err));
+		} else if (isBundle(options.bootstrap)) adopt(options.bootstrap, {
 			etag: null,
 			checksum: null,
 			status: "ready",
@@ -1447,7 +1532,7 @@ function createClient(options) {
 		});
 		else queueMicrotask(() => emitError(new NanoFlagsError("The bootstrap bundle is invalid and was ignored.", "invalid_bundle")));
 	}
-	if (verifyOpt && Array.isArray(verifyOpt.publicKeys) && verifyOpt.publicKeys.some((k) => !isPublicEd25519Jwk(k))) queueMicrotask(() => emitError(new NanoFlagsError("`verify.publicKeys` must contain public Ed25519 JWKs only. Other entries (including private keys) were ignored.", "config")));
+	if (verifyOpt && Array.isArray(verifyOpt.keys) && verifyOpt.keys.some((k) => !isPublicEd25519Jwk(k))) queueMicrotask(() => emitError(new NanoFlagsError("`verify.publicKeys` must contain public Ed25519 JWKs only. Other entries (including private keys) were ignored.", "config")));
 	if (typeof sdkKey !== "string" || sdkKey === "" || baseUrl === "") {
 		queueMicrotask(() => emitError(new NanoFlagsError("`sdkKey` and `baseUrl` are required.", "config")));
 		resolveReady();
@@ -1468,4 +1553,63 @@ function createClient(options) {
 	if (doc && typeof addEventListener === "function") addEventListener("online", onOnline);
 	return client;
 }
-export { createClient as a, SESSION_HEADER as i, NanoFlagsError as n, isSessionToken as o, SDK_VERSION as r, LIVE_PROTOCOL as t };
+Object.defineProperty(exports, "CLOSE_ENVIRONMENT_DELETED", {
+	enumerable: true,
+	get: function() {
+		return CLOSE_ENVIRONMENT_DELETED;
+	}
+});
+Object.defineProperty(exports, "LIVE_PROTOCOL", {
+	enumerable: true,
+	get: function() {
+		return LIVE_PROTOCOL;
+	}
+});
+Object.defineProperty(exports, "NanoFlagsError", {
+	enumerable: true,
+	get: function() {
+		return NanoFlagsError;
+	}
+});
+Object.defineProperty(exports, "OFFICIAL_EDGE_URL", {
+	enumerable: true,
+	get: function() {
+		return OFFICIAL_EDGE_URL;
+	}
+});
+Object.defineProperty(exports, "OFFICIAL_SIGNING_KEYS", {
+	enumerable: true,
+	get: function() {
+		return OFFICIAL_SIGNING_KEYS;
+	}
+});
+Object.defineProperty(exports, "SDK_VERSION", {
+	enumerable: true,
+	get: function() {
+		return SDK_VERSION;
+	}
+});
+Object.defineProperty(exports, "SESSION_HEADER", {
+	enumerable: true,
+	get: function() {
+		return SESSION_HEADER;
+	}
+});
+Object.defineProperty(exports, "SUPPORTED_ENGINE_VERSION", {
+	enumerable: true,
+	get: function() {
+		return SUPPORTED_ENGINE_VERSION;
+	}
+});
+Object.defineProperty(exports, "createClient", {
+	enumerable: true,
+	get: function() {
+		return createClient;
+	}
+});
+Object.defineProperty(exports, "isSessionToken", {
+	enumerable: true,
+	get: function() {
+		return isSessionToken;
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanoflags/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "NanoFlags JavaScript/TypeScript SDK: local, synchronous flag evaluation with background updates (Node, browsers, edge runtimes, React).",
   "keywords": [
     "feature-flags",