Star
Build

Secure mode

Client keys are public, so without a check anyone could ask "what flags does the CEO's account get?". Secure mode has your backend sign each user's context, and featurekit refuses contexts it didn't sign.

It's required in every environment marked isProduction, and optional elsewhere. The server SDK doesn't need it: a server key is already secret.

Set it up

  1. Give the control plane a secret control plane

    SECURE_MODE_SECRET=$(openssl rand -hex 32)

    At least 32 characters. Without it, a production environment refuses every client request with SECURE_MODE_UNCONFIGURED rather than serving unsigned contexts.

  2. Sign contexts in your backend your backend Where the session is already trusted. featurekit-server/secure-mode loads only node:crypto.

    import { signContext, contextHash } from "featurekit-server/secure-mode";
    
          app.get("/api/flags-signature", requireSession, (req, res) => {
            const context = { key: req.user.id, plan: req.user.plan };
            const expiresAt = Math.floor(Date.now() / 1000) + 3600;
            res.json({
              context,
              expiresAt,
              signature: signContext(context.key, expiresAt, SECRETS, contextHash(context)),
            });
          });

    SECRETS is the same value as SECURE_MODE_SECRET, split on commas.

  3. Pass it to the client SDK browser

    const { context, signature, expiresAt } = await (await fetch("/api/flags-signature")).json();
    
          const flags = new FeaturekitClient({
            clientKey: "fk_clt_…",
            baseUrl: "https://flags.acme.com",
            context,
            contextSignature: signature,
            contextSignatureExpiresAt: expiresAt,
            onSignatureExpiring: async () => {
              const fresh = await (await fetch("/api/flags-signature")).json();
              return { signature: fresh.signature, expiresAt: fresh.expiresAt };
            },
          });

Sign the attributes, not just the key

Passing contextHash(context) covers every attribute. Without it, the signature only proves who the user is, and they could send { key: "u-ana", plan: "enterprise" } with their own valid signature and be evaluated as an enterprise customer.

Expiry

A signature lasts until expiresAt. A captured one can be replayed until then, which is why it expires at all: a signature over the key alone would be a credential that never expires. The server refuses any expiresAt further out than SECURE_MODE_MAX_TTL_SECONDS (24 hours by default) before it even checks the signature. Refresh before expiry with onSignatureExpiring.

What the SDK does on each error

ErrorThe client SDK…
SIGNATURE_EXPIREDKeeps serving the values it has and asks onSignatureExpiring for a fresh pair. Expiry isn't an identity change.
SIGNATURE_INVALID, SIGNATURE_MISSINGDrops to your defaults. Never silently retries unsigned.
SIGNATURE_TTL_TOO_LONGRefused outright. Sign with a shorter lifetime.
SECURE_MODE_UNCONFIGURED (500)The server needs signatures but has no secret, and refuses rather than serving unsigned. Set SECURE_MODE_SECRET.

Rotating the secret

Signing uses the first secret, verification tries all of them, so rotation is two ordinary deploys:

  1. SECURE_MODE_SECRET=new,old, then deploy the control plane and your signers.
  2. Once everything signs with the new one, SECURE_MODE_SECRET=new and deploy again.

Rotating in one step invalidates every signature at once, and every browser drops to defaults until it signs again.

Other languages

signature      = hex(HMAC_SHA256(secret, "{key}:{expiresAt}:{attributesHash}"))
      attributesHash = first 32 hex characters of SHA-256 of the canonical context JSON
                       (object keys sorted at every level, no whitespace)

      {"key":"u-ana","plan":"free","tenureMonths":2}

Opting an environment out

To allow unsigned contexts in a specific production environment, list its id in UNSIGNED_CONTEXT_ENVIRONMENT_IDS. It's an explicit list so the exception is visible in your configuration, not a default.