When the bouncer is load-bearing

Observing versus deciding

Most analytics installs are observational. If the SDK is down you lose a chart, and nobody's Tuesday is ruined. Hank's is not that. Crossdeck answers a question the product cannot proceed without — may this person do this? — so the install is engineered as infrastructure rather than instrumentation, and it shows in the choices.

The clearest one is where the client is created. It is not lazy.

// Node is the bouncer at the door. A bouncer who only turns up when somebody
// knocks is not a bouncer — and everything that will sit behind this one
// (entitlement decisions, Trust, the signup gate) needs it already standing
// there, warm, with its handlers wired, before the first request arrives.

That comment records a real bug being closed: the client had been constructed on first use, behind a flag that was deliberately off, so it never booted, never wired its process handlers and never sent a heartbeat. Booting is not enforcing. The SDK is up from server start whether or not entitlement decides anything that request.

One key, and no local clock

Hank has a single entitlement key. A trial and a paid subscription resolve to the same one; what separates them is provenance carried on the record, not a second key and not a date the app works out for itself.

export const ENT = { PRO: "pro" } as const;

const hint = { userId: mailbox };
await cd.getEntitlements(hint);              // warm + refresh
const pro = cd.isEntitled(hint, ENT.PRO);    // sync; honours validUntil
const rec = cd.listEntitlements(hint).find((e) => e.key === ENT.PRO);

isEntitled() is synchronous, so the access check on a hot path never awaits a network call. getEntitlements() is what warms and refreshes it.

The reason the distinction matters is written into the code as a user-facing failure, not a technical one: read it wrong and a customer on day 2 of a trial is told Hank is active, never sees a countdown, and finds out the trial existed on the morning it ends.

There is also a comment about the key itself that is worth quoting exactly, because it is the failure mode nobody catches in review: Crossdeck follows our name character for character, and a mismatched key reads false exactly like a genuine non-grant — a silently locked-out customer.

The cold container problem

Cloud Run is serverless. A container can start with an empty cache, and a Crossdeck blip overlapping that window would read a paying customer as un-entitled — a false no at the worst possible moment.

So the SDK is given a durable store. It is only ever touched from async paths, which is what keeps isEntitled() synchronous while still giving a cold container last-known-good to serve.

const entitlementStore: EntitlementStore = {
  async load(key) { /* read the snapshot from Firestore */ },
  async save(key, value) { /* write it back */ },
};

const cd = new CrossdeckServer({
  secretKey,                       // from the environment, never in the file
  appId: "app_node_…",
  errorCapture: { onUncaughtException: false, onUnhandledRejection: false },
  entitlementStore,
});

Sandbox versus production is inferred from the key prefix (cd_sk_test_ / cd_sk_live_) rather than a separate environment flag — so there is no second switch to fall out of step with the credential.

The absence of a token is the signal

Crossdeck Trust runs on the signup door. The panel in the browser mints a single-use attestation proving a real browser was present; a server-to-server bot cannot mint one. The interesting part is what that means logically — the missing token is the evidence, not the present one.

const verdict = await cd.gate({ email, ip, token });

return NextResponse.json({
  action: verdict.action,
  allow: verdict.allow,
  reference: verdict.reference ?? null,
});

Keyed on the thing nobody can re-create

Crossdeck asks for your environment's strongest UID. Most teams reach for the auth uid. Hank does not, and the reasoning is the most transferable thing in this install: a work address of several years is the thing nobody recreates; a Firebase uid is one signup away. So the connected mailbox is the identity, and the login rides along as a trait.

It is stamped once, at first connection, rather than derived each time — because if it were re-derived, connecting a second inbox could silently change which customer the account resolves to, and a paying customer would read as un-entitled while their card is still being charged.

One more detail, and it is the kind that costs a day when it bites: Crossdeck matches crossdeck_ref against the value passed to identify() as an exact string. No format inspection, no shape validation. Which means Wes@Pinet.co.za and wes@pinet.co.za are two different customers. Hank normalises once, on the way in, and every reader takes the stored value verbatim.

Owning the crash handlers on purpose

The Node SDK auto-wires uncaughtException and unhandledRejection on construction. Hank turns both off and wires them itself — leaving the SDK's on alongside its own would capture every error twice. wrapFetch, the automatic capture of failed outbound HTTP, stays on.

The uncaughtException path is the one worth copying. Node's own documentation says process state is undefined after it fires, so Hank captures, gives the queue a short window to drain, then exits non-zero so Cloud Run replaces the container rather than serving from a broken one — with a two-second cap so a wedged transport cannot block shutdown forever.

And when the secret key is missing in production, it is not a silent condition. It logs that the server SDK is not running and that errors, analytics and entitlement resolution are all blind — because a door that is not there looks exactly like a door that is open.

Why this install is worth reading

• One entitlement, every surface, and no client allowed an opinion. Subscribe on the web, be entitled on the Mac and the phone — because the rail is an input and the ledger is the answer. This is the thing most cross-platform products charge their customers twice for.
• Crossdeck is in the critical path, and is built like it. Eager boot, a durable store behind a synchronous check, fail-open gating, loud failure when unconfigured.
• Both SDKs, with a clean division. The browser handles page views and identity; every decision that matters is made server-side, where the customer cannot reach it.
• The wiring was sequenced, not bundled. Boot, then identify, then gate — three steps with three contracts. The provider component deliberately does not identify anyone, because folding the steps together is how the order gets done wrong.
• Identity is a product decision before it is a technical one. Choosing the mailbox over the auth uid is what makes trial eligibility and abuse limits survive a re-signup.

One thing this install taught us

The Trust route carries a comment we would rather not have earned:

The Crossdeck write-up says cd.trust.gate(…). The installed SDK puts gate directly on CrossdeckServer. Checked against the shipped types rather than the docs.

— app/api/trust/gate/route.ts

A developer had to disbelieve our documentation and read our type definitions to get the call right. That is our bug, it is logged, and it is on this page because a case study that only shows the parts that went well is an advertisement.

The same install, documented

• Entitlements — keys, isEntitled(), and how a rail resolves to a grant.
• Node SDK — server-side boot, error capture and the entitlement store.
• Crossdeck Trust — what the panel mints and why a missing token is evidence.
• How identity works — choosing the id that a re-signup cannot reset.
• Capture an error — process handlers, flushing, and what to own yourself.