@cross-deck/node 1.10.1 → 1.12.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.0] — 2026-07-01
+
+**Added — `blockEventId`: the Crossdeck-hosted block page (v2 preview).**
+On a block, `resolve()` and `gate()` now return `blockEventId` — the id of the
+canonical block interstitial Crossdeck hosts for that exact verdict. The
+recommended dead-end becomes one line:
+
+```ts
+if (blocked && blockEventId) {
+  res.redirect(`https://api.cross-deck.com/v1/trust/page/${blockEventId}`);
+}
+```
+
+Crossdeck serves the branded "Access paused" page — a verification receipt
+(application name, timestamp, the quotable `reference`) and a **Contact
+support** action that mails the project owner's real recorded email — so you
+never hand-build, fork, or drift the block screen. The id is opaque
+(`cd_blk_…`, no PII in the URL) and present only on an explicit block;
+fail-open behaviour is unchanged (never redirect on error/timeout).
+`ResolveResult` and `GateVerdict` carry the new optional field — additive,
+non-breaking. Still `@experimental` until the Crossdeck v2 launch.
+
+## [1.11.0] — 2026-06-30
+
+**Added — block `reference` and `supportEmail` on the trust surface (still v2 preview).**
+`resolve()` and `gate()` now surface two fields on a block:
+
+- `reference` — a short, opaque, human-quotable support handle (the "Ray ID", `xxxx-xxxx`).
+  Show it on your suspended screen; Crossdeck stores the same string on the block event, so
+  support resolves a quoted reference to the exact block in the admin Caught feed.
+- `supportEmail` — the email you registered with Crossdeck at signup, so your suspended
+  screen's "Contact support" reaches the real operator by default instead of a placeholder.
+
+Both were typed on `ResolveResult` / `GateVerdict` but the client previously **dropped**
+them when building the result object — now passed through. Additive, non-breaking. Opaque +
+non-PII (never the score or rule logic).
+
 ## [1.10.1] — 2026-06-30
 
 **Fixed — the blocking surface now works for the documented paths (still v2 preview).**

package/README.md

@@ -223,16 +223,29 @@ Blocking is **entitlements, inverted**: `getEntitlements()` asks *"can this user
 There are three doors. Pick by who's at it:
 
 ```ts
+// The Crossdeck-hosted block page — the recommended dead-end for doors 1 + 2. One
+// constant today; swaps to https://block.cross-deck.com when the alias goes live.
+const BLOCK_PAGE = "https://api.cross-deck.com/v1/trust/page";
+
 // 1. A user you ALREADY KNOW — a bare userId rides the backbone (no token, no setup).
 //    Crossdeck matches on the email it already holds. The common case.
-const { blocked, blockReason } = await crossdeck.resolve({ userId, ip: req.ip });
-if (blocked) { await signOut(); return showSuspended(blockReason); }
+const { blocked, blockEventId } = await crossdeck.resolve({ userId, ip: req.ip });
+if (blocked) {
+  await signOut();
+  return blockEventId
+    ? res.redirect(`${BLOCK_PAGE}/${blockEventId}`) // Crossdeck serves the branded page
+    : res.redirect("/suspended");                   // rare: mint unavailable → your fallback
+}
 // or just the boolean:  if (await crossdeck.isBlocked({ userId })) …
 
 // 2. A BRAND-NEW signup Crossdeck has never seen — block by the two strings you have
 //    at signup, their email + ip. Call it BEFORE you create the account.
 const gate = await crossdeck.gate({ email, ip: req.ip });
-if (gate.action === "block") return rejectSignup(gate.blockReason);
+if (gate.action === "block") {
+  return gate.blockEventId
+    ? res.redirect(`${BLOCK_PAGE}/${gate.blockEventId}`)
+    : rejectSignup(gate.blockReason);
+}
 
 // 3. A PUBLIC PAGE — "is the owner of this page blocked?" (no session token). Poll on a
 //    short TTL to invalidate your cache; the ip is the owner's CREATION ip.
@@ -240,6 +253,15 @@ const owner = await crossdeck.getOwnerStatus({ userId: ownerId });
 if (owner.blocked) await takePageOffline(ownerId);
 ```
 
+**Why redirect instead of building your own screen?** Crossdeck hosts the canonical block
+interstitial — "Access paused", a verification receipt (application name, timestamp, an
+opaque `reference` the person can quote to support), and a **Contact support** action that
+mails the project owner's real recorded email. One page, centrally maintained, updated for
+every integrator at once — you never fork it, restyle it, or let it drift. Redirect **only
+on an explicit block** (`blocked === true` / `action === "block"`): on error or timeout the
+SDK fails open and you let the user through — never send a real user to a block page over
+a network blip.
+
 **Recommended server pattern (no issuer registration):** if your backend runs Firebase
 Admin, verify the ID token **locally** for the authoritative uid, then send that as a bare
 `userId` — you keep the cryptographic proof on your side and Crossdeck needs zero setup:

package/dist/auto-events/index.d.mts

@@ -1,4 +1,4 @@
-import { x as CrossdeckServer } from '../crossdeck-server-BpBVFC4O.mjs';
+import { x as CrossdeckServer } from '../crossdeck-server-CuTGwrwx.mjs';
 import 'node:events';
 
 /**

package/dist/auto-events/index.d.ts

@@ -1,4 +1,4 @@
-import { x as CrossdeckServer } from '../crossdeck-server-BpBVFC4O.js';
+import { x as CrossdeckServer } from '../crossdeck-server-CuTGwrwx.js';
 import 'node:events';
 
 /**

package/dist/{crossdeck-server-BpBVFC4O.d.mts → crossdeck-server-CuTGwrwx.d.mts}

@@ -183,8 +183,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.10.1";
-    readonly bundledIn: "@cross-deck/node@1.10.1";
+    readonly sdkVersion: "1.12.0";
+    readonly bundledIn: "@cross-deck/node@1.12.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -472,6 +472,26 @@ interface BlockVerdict {
     blockReason: string | null;
     /** The exact rule that fired: `"domain:spartan.net"` | `"ip:1.2.3.4"` | `"manual"` | null. */
     blockedKey: string | null;
+    /**
+     * Human-quotable support handle for this verdict (the "Ray ID"), formatted `xxxx-xxxx`.
+     * Show it on your suspended screen ("reference: blocklist:domain · a1f9-7c2e"); Crossdeck
+     * stores the same string on the block event, so support resolves it in the Caught feed.
+     */
+    reference?: string | null;
+    /**
+     * The recorded support contact (the project owner's signup email), present only when
+     * blocked — render it as the suspended screen's "Contact support" so appeals reach the
+     * real operator by default. Override with a dedicated address if you have one.
+     */
+    supportEmail?: string | null;
+    /**
+     * The id of the CD-hosted block interstitial minted for THIS verdict — present only when
+     * blocked. The recommended dead-end is one line:
+     * `redirect(\`https://api.cross-deck.com/v1/trust/page/${blockEventId}\`)` — Crossdeck
+     * serves the canonical branded page (receipt + reference + faithful support contact), so
+     * you never hand-build or fork the block screen. Opaque (`cd_blk_…`), no PII in the URL.
+     */
+    blockEventId?: string | null;
     /**
      * True when this is the fail-open default (Crossdeck unreachable / identity unresolved).
      * `blocked` is `false`; log it for observability, never treat it as a real "not blocked".
@@ -546,6 +566,12 @@ interface GateVerdict {
     blockReason: string | null;
     /** The exact rule/key that fired, when blocked. */
     blockedKey: string | null;
+    /** Human-quotable support handle (the "Ray ID"), formatted `xxxx-xxxx` — show it on the blocked screen. */
+    reference?: string | null;
+    /** Recorded support contact (project owner's signup email), present only on `block` — the blocked screen's "Contact support" default. */
+    supportEmail?: string | null;
+    /** CD-hosted block-page id (`cd_blk_…`), present only on `block` — redirect the rejected signup to `https://api.cross-deck.com/v1/trust/page/${blockEventId}` and Crossdeck serves the canonical branded dead-end. */
+    blockEventId?: string | null;
     /** True when this is the fail-open default (Crossdeck unreachable). `allow` is `true`. */
     degraded?: boolean;
 }

package/dist/{crossdeck-server-BpBVFC4O.d.ts → crossdeck-server-CuTGwrwx.d.ts}

@@ -183,8 +183,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.10.1";
-    readonly bundledIn: "@cross-deck/node@1.10.1";
+    readonly sdkVersion: "1.12.0";
+    readonly bundledIn: "@cross-deck/node@1.12.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -472,6 +472,26 @@ interface BlockVerdict {
     blockReason: string | null;
     /** The exact rule that fired: `"domain:spartan.net"` | `"ip:1.2.3.4"` | `"manual"` | null. */
     blockedKey: string | null;
+    /**
+     * Human-quotable support handle for this verdict (the "Ray ID"), formatted `xxxx-xxxx`.
+     * Show it on your suspended screen ("reference: blocklist:domain · a1f9-7c2e"); Crossdeck
+     * stores the same string on the block event, so support resolves it in the Caught feed.
+     */
+    reference?: string | null;
+    /**
+     * The recorded support contact (the project owner's signup email), present only when
+     * blocked — render it as the suspended screen's "Contact support" so appeals reach the
+     * real operator by default. Override with a dedicated address if you have one.
+     */
+    supportEmail?: string | null;
+    /**
+     * The id of the CD-hosted block interstitial minted for THIS verdict — present only when
+     * blocked. The recommended dead-end is one line:
+     * `redirect(\`https://api.cross-deck.com/v1/trust/page/${blockEventId}\`)` — Crossdeck
+     * serves the canonical branded page (receipt + reference + faithful support contact), so
+     * you never hand-build or fork the block screen. Opaque (`cd_blk_…`), no PII in the URL.
+     */
+    blockEventId?: string | null;
     /**
      * True when this is the fail-open default (Crossdeck unreachable / identity unresolved).
      * `blocked` is `false`; log it for observability, never treat it as a real "not blocked".
@@ -546,6 +566,12 @@ interface GateVerdict {
     blockReason: string | null;
     /** The exact rule/key that fired, when blocked. */
     blockedKey: string | null;
+    /** Human-quotable support handle (the "Ray ID"), formatted `xxxx-xxxx` — show it on the blocked screen. */
+    reference?: string | null;
+    /** Recorded support contact (project owner's signup email), present only on `block` — the blocked screen's "Contact support" default. */
+    supportEmail?: string | null;
+    /** CD-hosted block-page id (`cd_blk_…`), present only on `block` — redirect the rejected signup to `https://api.cross-deck.com/v1/trust/page/${blockEventId}` and Crossdeck serves the canonical branded dead-end. */
+    blockEventId?: string | null;
     /** True when this is the fail-open default (Crossdeck unreachable). `allow` is `true`. */
     degraded?: boolean;
 }

package/dist/index.cjs

@@ -387,7 +387,7 @@ function byteLength(s) {
 var https = __toESM(require("https"));
 
 // src/_version.ts
-var SDK_VERSION = "1.10.1";
+var SDK_VERSION = "1.12.0";
 var SDK_NAME = "@cross-deck/node";
 
 // src/_diagnostic-telemetry.ts
@@ -3207,6 +3207,9 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         blocked: raw.blocked === true,
         blockReason: raw.blockReason ?? null,
         blockedKey: raw.blockedKey ?? null,
+        reference: raw.reference ?? null,
+        supportEmail: raw.supportEmail ?? null,
+        blockEventId: raw.blockEventId ?? null,
         status: typeof raw.status === "string" ? raw.status : "active",
         entitlements: Array.isArray(raw.entitlements) ? raw.entitlements.filter((e) => typeof e === "string") : [],
         crossdeckCustomerId: raw.crossdeckCustomerId ?? raw.user?.id ?? null,
@@ -3316,7 +3319,10 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         action,
         allow: raw.allow !== false && action !== "block",
         blockReason: raw.blockReason ?? null,
-        blockedKey: raw.blockedKey ?? null
+        blockedKey: raw.blockedKey ?? null,
+        reference: raw.reference ?? null,
+        supportEmail: raw.supportEmail ?? null,
+        blockEventId: raw.blockEventId ?? null
       };
     } catch (err) {
       this.debug.emit(
@@ -4774,8 +4780,8 @@ function normaliseSecrets(input) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/node@1.10.1";
-var SDK_VERSION2 = "1.10.1";
+var BUNDLED_IN = "@cross-deck/node@1.12.0";
+var SDK_VERSION2 = "1.12.0";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -4897,7 +4903,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "documentation-honesty",
@@ -4929,7 +4935,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.1",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "error-envelope-shape",
@@ -4968,7 +4974,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "flush-interval-parity",
@@ -5013,7 +5019,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "idempotency-key-deterministic",
@@ -5118,7 +5124,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "invalid-input-rejected-natively",
@@ -5174,7 +5180,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-06-11",
     "firstRegisteredIn": "swift trap-on-input class fix \u2014 first machine-tested Swift release",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "node-pii-scrubber",
@@ -5213,7 +5219,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.1",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "node-shutdown-awaits-flush",
@@ -5246,7 +5252,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.4",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "sdk-error-codes-catalogue",
@@ -5291,7 +5297,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "sync-purchases-funnel-parity",
@@ -5324,7 +5330,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   },
   {
     "id": "verifier-timestamp-mandatory",
@@ -5378,7 +5384,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.2",
-    "bundledIn": "@cross-deck/node@1.10.1"
+    "bundledIn": "@cross-deck/node@1.12.0"
   }
 ]);