@vellumai/vellum-gateway 0.10.11-dev.202607221933.baa2119 → 0.10.11-dev.202607222129.31c06e5

package/node_modules/@vellumai/gateway-client/src/__tests__/binding-strength-contract.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Tests for the shared binding-strength vocabulary: the display ladder and the
+ * enforcement order (demotion guard — LUM-2505).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  bindingStrengthForVerifiedVia,
+  isBindingDemotion,
+  knownStrengthRank,
+  VERIFIED_VIA_CHALLENGE,
+  VERIFIED_VIA_CHANNEL_CLAIM,
+  VERIFIED_VIA_MANUAL,
+} from "../binding-strength-contract.js";
+
+describe("knownStrengthRank", () => {
+  test("unverified (null / undefined / empty) ranks 0", () => {
+    expect(knownStrengthRank(null)).toBe(0);
+    expect(knownStrengthRank(undefined)).toBe(0);
+    expect(knownStrengthRank("")).toBe(0);
+  });
+
+  test("inbound channel claim ranks 1", () => {
+    expect(knownStrengthRank(VERIFIED_VIA_CHANNEL_CLAIM)).toBe(1);
+  });
+
+  test("workspace-vouched (manual) ranks 2", () => {
+    expect(knownStrengthRank(VERIFIED_VIA_MANUAL)).toBe(2);
+  });
+
+  test("proven / possession values all rank 3", () => {
+    expect(knownStrengthRank(VERIFIED_VIA_CHALLENGE)).toBe(3);
+    expect(knownStrengthRank("invite")).toBe(3);
+    expect(knownStrengthRank("voice")).toBe(3);
+    expect(knownStrengthRank("bootstrap")).toBe(3);
+    // Guardian auto-registration bindings (createGuardianBinding writers).
+    expect(knownStrengthRank("platform_auto_register")).toBe(3);
+    expect(knownStrengthRank("webhook_registration")).toBe(3);
+  });
+
+  test("unrecognized non-empty provenance is unknown (null)", () => {
+    expect(knownStrengthRank("guardian_approval")).toBeNull();
+    expect(knownStrengthRank("something_new")).toBeNull();
+  });
+});
+
+describe("bindingStrengthForVerifiedVia (display ladder)", () => {
+  test("maps the three introduction-card provenances", () => {
+    expect(bindingStrengthForVerifiedVia(VERIFIED_VIA_CHALLENGE)).toBe(
+      "verified_handshake",
+    );
+    expect(bindingStrengthForVerifiedVia(VERIFIED_VIA_MANUAL)).toBe(
+      "internal_workspace_match",
+    );
+    expect(bindingStrengthForVerifiedVia(VERIFIED_VIA_CHANNEL_CLAIM)).toBe(
+      "inbound_channel_claim",
+    );
+  });
+
+  test("returns null for provenance outside the ladder (card UI relies on this)", () => {
+    expect(bindingStrengthForVerifiedVia("invite")).toBeNull();
+    expect(bindingStrengthForVerifiedVia("bootstrap")).toBeNull();
+    expect(bindingStrengthForVerifiedVia("voice")).toBeNull();
+    expect(bindingStrengthForVerifiedVia(null)).toBeNull();
+    expect(bindingStrengthForVerifiedVia(undefined)).toBeNull();
+  });
+});
+
+describe("isBindingDemotion", () => {
+  test("a lower-strength source demoting a higher-strength binding is refused", () => {
+    // challenge (3) is the strongest — nothing weaker may overwrite it.
+    expect(isBindingDemotion(VERIFIED_VIA_CHALLENGE, VERIFIED_VIA_MANUAL)).toBe(
+      true,
+    );
+    expect(
+      isBindingDemotion(VERIFIED_VIA_CHALLENGE, VERIFIED_VIA_CHANNEL_CLAIM),
+    ).toBe(true);
+    // manual (2) may not be demoted to an inbound claim (1).
+    expect(
+      isBindingDemotion(VERIFIED_VIA_MANUAL, VERIFIED_VIA_CHANNEL_CLAIM),
+    ).toBe(true);
+    // A proven value demoted to null/unverified is a demotion too.
+    expect(isBindingDemotion(VERIFIED_VIA_CHALLENGE, null)).toBe(true);
+    // Guardian auto-registration bindings are proven — a later manual attest
+    // or channel claim can never demote them.
+    expect(
+      isBindingDemotion("platform_auto_register", VERIFIED_VIA_MANUAL),
+    ).toBe(true);
+    expect(
+      isBindingDemotion("webhook_registration", VERIFIED_VIA_CHANNEL_CLAIM),
+    ).toBe(true);
+  });
+
+  test("equal-tier writes and lateral proven swaps are not demotions", () => {
+    expect(isBindingDemotion(VERIFIED_VIA_CHALLENGE, "invite")).toBe(false);
+    expect(isBindingDemotion("invite", VERIFIED_VIA_CHALLENGE)).toBe(false);
+    expect(isBindingDemotion(VERIFIED_VIA_MANUAL, VERIFIED_VIA_MANUAL)).toBe(
+      false,
+    );
+  });
+
+  test("upgrades are not demotions", () => {
+    expect(
+      isBindingDemotion(VERIFIED_VIA_CHANNEL_CLAIM, VERIFIED_VIA_CHALLENGE),
+    ).toBe(false);
+    expect(isBindingDemotion(null, VERIFIED_VIA_CHANNEL_CLAIM)).toBe(false);
+    expect(isBindingDemotion(VERIFIED_VIA_MANUAL, VERIFIED_VIA_CHALLENGE)).toBe(
+      false,
+    );
+  });
+
+  test("unknown provenance on either side is never a demotion (fail-open)", () => {
+    expect(isBindingDemotion(VERIFIED_VIA_CHALLENGE, "guardian_approval")).toBe(
+      false,
+    );
+    expect(
+      isBindingDemotion("guardian_approval", VERIFIED_VIA_CHANNEL_CLAIM),
+    ).toBe(false);
+    expect(isBindingDemotion("unknown_a", "unknown_b")).toBe(false);
+  });
+});

package/node_modules/@vellumai/gateway-client/src/binding-strength-contract.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared binding-strength vocabulary for the contact channel `verified_via`
+ * provenance column.
+ *
+ * Two distinct notions live here, both keyed on the free-text `verified_via`
+ * audit value:
+ *
+ *  1. The 3-tier *display* ladder (`BindingStrength` +
+ *     `bindingStrengthForVerifiedVia`) the introduction card renders from. It
+ *     covers only the three introduction-card provenances and returns `null`
+ *     for everything else — the card UI depends on that exact shape.
+ *
+ *  2. The *enforcement* order (`knownStrengthRank` + `isBindingDemotion`) the
+ *     gateway ACL write path uses to refuse demotions (LUM-2505): a total,
+ *     conservative ranking over every real `verified_via` value, so a
+ *     lower-strength source can never silently overwrite a higher-strength
+ *     active binding.
+ *
+ * This lives in the shared package — not `assistant/` — because the gateway
+ * owns the contact ACL and is where the demotion guard runs. The assistant
+ * re-exports the display helpers from `runtime/introduction-policy.ts`, so its
+ * card/provenance call sites are unchanged.
+ *
+ * No import from `assistant/` or `gateway/`: pure vocabulary.
+ */
+
+// ---------------------------------------------------------------------------
+// verified_via constants
+// ---------------------------------------------------------------------------
+
+/** `verified_via` written by the gateway when a verification code is redeemed. */
+export const VERIFIED_VIA_CHALLENGE = "challenge";
+
+/** `verified_via` written when the guardian direct-trusts a workspace-vouched identity. */
+export const VERIFIED_VIA_MANUAL = "manual";
+
+/** `verified_via` written when the guardian trusts an identity the platform is not vouching for. */
+export const VERIFIED_VIA_CHANNEL_CLAIM = "manual_channel_claim";
+
+// ---------------------------------------------------------------------------
+// Display ladder (introduction card)
+// ---------------------------------------------------------------------------
+
+/**
+ * Binding-strength ladder the introduction card renders:
+ *
+ *   verified_handshake > internal_workspace_match > inbound_channel_claim
+ *
+ * - `verified_handshake` — the contact proved control of the channel by
+ *   returning a verification code (`verified_via: "challenge"`).
+ * - `internal_workspace_match` — the platform authenticated the identity inside
+ *   the guardian's own workspace; the guardian vouches directly
+ *   (`verified_via: "manual"`).
+ * - `inbound_channel_claim` — the guardian trusts an identity the platform is
+ *   NOT vouching for (`verified_via: "manual_channel_claim"`).
+ */
+export type BindingStrength =
+  | "verified_handshake"
+  | "internal_workspace_match"
+  | "inbound_channel_claim";
+
+/**
+ * Derive the display binding strength for a `verified_via`. Returns `null` for
+ * provenance outside the introduction ladder (e.g. `invite`, `bootstrap`),
+ * which predate it and keep their own audit meaning — the introduction card UI
+ * relies on this exact shape.
+ *
+ * This is the DISPLAY ladder, not the enforcement order: use
+ * {@link knownStrengthRank} / {@link isBindingDemotion} for the demotion guard.
+ */
+export function bindingStrengthForVerifiedVia(
+  verifiedVia: string | null | undefined,
+): BindingStrength | null {
+  switch (verifiedVia) {
+    case VERIFIED_VIA_CHALLENGE:
+      return "verified_handshake";
+    case VERIFIED_VIA_MANUAL:
+      return "internal_workspace_match";
+    case VERIFIED_VIA_CHANNEL_CLAIM:
+      return "inbound_channel_claim";
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Enforcement order (demotion guard — LUM-2505)
+// ---------------------------------------------------------------------------
+
+/**
+ * `verified_via` values where the actor demonstrably controls the channel (a
+ * code/token/possession proof) or the binding is a guardian binding (bootstrap
+ * or platform/webhook auto-registration). They share the top enforcement rank:
+ * none may be silently demoted, and a lateral swap between them is not a
+ * demotion. Every real production writer of `verified_via` that outranks
+ * `manual` must appear here, or the demotion guard would treat it as unknown
+ * (incomparable) and let a `manual` re-attest quietly demote it.
+ */
+const PROVEN_VERIFIED_VIA: ReadonlySet<string> = new Set([
+  VERIFIED_VIA_CHALLENGE, // returned a verification code
+  "invite", // redeemed an invite code / token
+  "voice", // returned a voice (DTMF) code
+  "bootstrap", // guardian binding (also protected by the guardian-downgrade guard)
+  "platform_auto_register", // guardian binding auto-registered by the platform
+  "webhook_registration", // guardian binding registered via a provider webhook
+]);
+
+/**
+ * Total, conservative strength rank for a `verified_via`, used by the gateway
+ * ACL write path to refuse demotions. Higher = stronger. Grouped into coarse
+ * tiers that hold under ANY intra-tier ordering the pending Slack-permissions
+ * PRD (D4) may land on:
+ *
+ *   3  proven / possession — {@link PROVEN_VERIFIED_VIA}.
+ *   2  workspace-vouched — the platform authenticated the identity but the
+ *      actor did not actively prove control here (`manual`).
+ *   1  inbound channel claim — nobody vouches; the guardian trusted an
+ *      unproven claim (`manual_channel_claim`).
+ *   0  unverified — no verification at all (`null` / empty).
+ *
+ * Returns `null` for an unrecognized non-empty provenance ("unknown"). The
+ * demotion guard treats unknown as incomparable and never refuses on it, so a
+ * forward-compatible new `verified_via` value is never mistaken for a demotion.
+ */
+export function knownStrengthRank(
+  verifiedVia: string | null | undefined,
+): number | null {
+  if (verifiedVia == null || verifiedVia === "") return 0;
+  if (PROVEN_VERIFIED_VIA.has(verifiedVia)) return 3;
+  if (verifiedVia === VERIFIED_VIA_MANUAL) return 2;
+  if (verifiedVia === VERIFIED_VIA_CHANNEL_CLAIM) return 1;
+  return null;
+}
+
+/**
+ * Whether writing `incomingVia` over an existing `existingVia` binding would
+ * LOWER its strength — the demotion the gateway ACL write path refuses
+ * (LUM-2505).
+ *
+ * True only when BOTH provenances are known and the incoming rank is strictly
+ * lower than the existing. Unknown provenance on either side is incomparable
+ * and never counts as a demotion (fail-open), so the guard blocks only provable
+ * downgrades and never breaks a new/unrecognized `verified_via`. Equal ranks
+ * (including lateral swaps within the proven tier) and upgrades are not
+ * demotions.
+ */
+export function isBindingDemotion(
+  existingVia: string | null | undefined,
+  incomingVia: string | null | undefined,
+): boolean {
+  const existing = knownStrengthRank(existingVia);
+  const incoming = knownStrengthRank(incomingVia);
+  if (existing == null || incoming == null) return false;
+  return incoming < existing;
+}

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -321,3 +321,17 @@ export type {
   ResolvedChannelPermission,
   RiskThreshold,
 } from "./channel-permission-contract.js";
+
+// Binding-strength vocabulary for the contact `verified_via` provenance —
+// display ladder (introduction card) + the enforcement order the gateway ACL
+// write path uses to refuse demotions (LUM-2505).
+export {
+  bindingStrengthForVerifiedVia,
+  isBindingDemotion,
+  knownStrengthRank,
+  VERIFIED_VIA_CHALLENGE,
+  VERIFIED_VIA_CHANNEL_CLAIM,
+  VERIFIED_VIA_MANUAL,
+} from "./binding-strength-contract.js";
+
+export type { BindingStrength } from "./binding-strength-contract.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.10.11-dev.202607221933.baa2119",
+  "version": "0.10.11-dev.202607222129.31c06e5",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/contact-handlers.test.ts

@@ -8,7 +8,15 @@
  * running daemon.
  */
 
-import { describe, test, expect, beforeAll, beforeEach, afterAll, mock } from "bun:test";
+import {
+  describe,
+  test,
+  expect,
+  beforeAll,
+  beforeEach,
+  afterAll,
+  mock,
+} from "bun:test";
 
 import "./test-preload.js";
 
@@ -80,10 +88,7 @@ const mirrorIpcCalls: { method: string; body: unknown }[] = [];
 mock.module("../ipc/assistant-client.js", () => ({
   IpcHandlerError: class extends Error {},
   IpcTransportError: class extends Error {},
-  ipcCallAssistant: async (
-    method: string,
-    params?: { body?: unknown },
-  ) => {
+  ipcCallAssistant: async (method: string, params?: { body?: unknown }) => {
     mirrorIpcCalls.push({ method, body: params?.body });
     return { ok: true };
   },
@@ -164,7 +169,13 @@ function seedContact(id: string, role: "guardian" | "contact" = "guardian") {
     .run();
 }
 
-function seedChannel(opts: { id: string; contactId: string; status?: string }) {
+function seedChannel(opts: {
+  id: string;
+  contactId: string;
+  status?: string;
+  verifiedVia?: string | null;
+  verifiedAt?: number | null;
+}) {
   const now = Date.now();
   getGatewayDb()
     .insert(contactChannels)
@@ -176,6 +187,8 @@ function seedChannel(opts: { id: string; contactId: string; status?: string }) {
       isPrimary: false,
       status: opts.status ?? "unverified",
       policy: "allow",
+      verifiedAt: opts.verifiedAt ?? null,
+      verifiedVia: opts.verifiedVia ?? null,
       interactionCount: 0,
       createdAt: now,
       updatedAt: now,
@@ -457,7 +470,7 @@ describe("upsert_verified_channel IPC handler", () => {
     expect(row!.status).toBe("blocked");
   });
 
-  test("round-trips verifiedVia=\"invite\" (free string, not the restricted enum)", async () => {
+  test('round-trips verifiedVia="invite" (free string, not the restricted enum)', async () => {
     const res = (await upsertVerifiedChannelHandler({
       type: "vellum",
       address: "addr-invite",
@@ -477,3 +490,92 @@ describe("upsert_verified_channel IPC handler", () => {
     expect(row!.verifiedVia).toBe("invite");
   });
 });
+
+describe("upsert_verified_channel binding-strength guard (LUM-2505)", () => {
+  test("refuses to demote an active challenge binding to a manual_channel_claim", async () => {
+    seedContact("c1", "contact");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedVia: "challenge",
+      verifiedAt: 500,
+    });
+
+    const res = (await upsertVerifiedChannelHandler({
+      type: "vellum",
+      address: "addr-ch1",
+      externalChatId: "chat-1",
+      verifiedVia: "manual_channel_claim",
+    })) as { ok: boolean; verified: boolean; channel: { verifiedVia: string } };
+
+    // The write still succeeds, but the stronger provenance is preserved.
+    expect(res.ok).toBe(true);
+    expect(res.verified).toBe(true);
+    expect(res.channel.verifiedVia).toBe("challenge");
+
+    const row = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(row!.verifiedVia).toBe("challenge");
+    expect(row!.verifiedAt).toBe(500);
+    expect(row!.status).toBe("active");
+  });
+
+  test("refuses to demote an active challenge binding to a manual attest", async () => {
+    seedContact("c1", "contact");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedVia: "challenge",
+      verifiedAt: 500,
+    });
+
+    const res = (await upsertVerifiedChannelHandler({
+      type: "vellum",
+      address: "addr-ch1",
+      externalChatId: "chat-1",
+      verifiedVia: "manual",
+    })) as { ok: boolean; channel: { verifiedVia: string } };
+
+    expect(res.channel.verifiedVia).toBe("challenge");
+
+    const row = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(row!.verifiedVia).toBe("challenge");
+  });
+
+  test("still applies an upgrade (manual_channel_claim -> challenge)", async () => {
+    seedContact("c1", "contact");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedVia: "manual_channel_claim",
+      verifiedAt: 500,
+    });
+
+    const res = (await upsertVerifiedChannelHandler({
+      type: "vellum",
+      address: "addr-ch1",
+      externalChatId: "chat-1",
+      verifiedVia: "challenge",
+    })) as { ok: boolean; verified: boolean; channel: { verifiedVia: string } };
+
+    expect(res.verified).toBe(true);
+    expect(res.channel.verifiedVia).toBe("challenge");
+
+    const row = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(row!.verifiedVia).toBe("challenge");
+  });
+});

package/src/__tests__/contact-store-mark-channel-verified.test.ts

@@ -270,7 +270,7 @@ describe("ContactStore.markChannelVerified", () => {
     expect(result!.channel.verifiedVia).toBe("manual");
   });
 
-  test("upgrades a previously challenge-verified channel to manual", async () => {
+  test("refuses to demote a challenge-verified channel to manual (LUM-2505)", async () => {
     seedContact("c1");
     seedChannel({
       id: "ch1",
@@ -280,12 +280,33 @@ describe("ContactStore.markChannelVerified", () => {
       verifiedVia: "challenge",
     });
 
-    const before = Date.now();
+    // A `manual` attest (e.g. a roster "Link account") must not lower the
+    // stronger `challenge` proof on an active binding — the existing binding
+    // stands as an idempotent no-op.
     const result = await new ContactStore().markChannelVerified("ch1");
     expect(result).not.toBeNull();
+    expect(result!.didWrite).toBe(false);
+    expect(result!.channel.verifiedVia).toBe("challenge");
+    expect(result!.channel.verifiedAt).toBe(500);
+  });
+
+  test("applies an upgrade: manual -> challenge on an active channel", async () => {
+    seedContact("c1");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedAt: 500,
+      verifiedVia: "manual",
+    });
+
+    const result = await new ContactStore().markChannelVerified(
+      "ch1",
+      "challenge",
+    );
+    expect(result).not.toBeNull();
     expect(result!.didWrite).toBe(true);
-    expect(result!.channel.verifiedVia).toBe("manual");
-    expect(result!.channel.verifiedAt!).toBeGreaterThanOrEqual(before);
+    expect(result!.channel.verifiedVia).toBe("challenge");
   });
 
   test("re-activates a non-active channel that previously had verifiedAt", async () => {
@@ -511,9 +532,7 @@ describe("ContactStore.markChannelVerified", () => {
 
     // Exactly one gateway channel row: the existing gateway row is verified in
     // place, keyed by (type,address).
-    expect(
-      getGatewayDb().select().from(contactChannels).all().length,
-    ).toBe(1);
+    expect(getGatewayDb().select().from(contactChannels).all().length).toBe(1);
   });
 
   test("legacy cross-contact: resolves the gateway row by (type,address) even under a different contact", async () => {
@@ -548,6 +567,75 @@ describe("ContactStore.markChannelVerified", () => {
   });
 });
 
+describe("ContactStore.upsertContact binding-strength guard (LUM-2505)", () => {
+  test("does not demote an active challenge channel via a weaker verifiedVia upsert", async () => {
+    seedContact("c1", "contact");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedAt: 500,
+      verifiedVia: "challenge",
+      address: "addr-ch1",
+    });
+
+    await new ContactStore().upsertContact({
+      id: "c1",
+      channels: [
+        {
+          type: "vellum",
+          address: "addr-ch1",
+          status: "active",
+          verifiedVia: "manual_channel_claim",
+          verifiedAt: 999,
+        },
+      ],
+    });
+
+    const row = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(row!.verifiedVia).toBe("challenge");
+    expect(row!.verifiedAt).toBe(500);
+    expect(row!.status).toBe("active");
+  });
+
+  test("applies an upgrade via upsert (manual_channel_claim -> challenge)", async () => {
+    seedContact("c1", "contact");
+    seedChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "active",
+      verifiedAt: 500,
+      verifiedVia: "manual_channel_claim",
+      address: "addr-ch1",
+    });
+
+    await new ContactStore().upsertContact({
+      id: "c1",
+      channels: [
+        {
+          type: "vellum",
+          address: "addr-ch1",
+          status: "active",
+          verifiedVia: "challenge",
+          verifiedAt: 999,
+        },
+      ],
+    });
+
+    const row = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(row!.verifiedVia).toBe("challenge");
+    expect(row!.verifiedAt).toBe(999);
+  });
+});
+
 describe("ContactStore.markChannelRevoked", () => {
   test("revokes a channel by its gateway id", async () => {
     seedContact("c1", "contact");
@@ -588,9 +676,7 @@ describe("ContactStore.markChannelRevoked", () => {
 
     // Exactly one gateway channel row: the existing gateway row is revoked in
     // place, keyed by (type,address).
-    expect(
-      getGatewayDb().select().from(contactChannels).all().length,
-    ).toBe(1);
+    expect(getGatewayDb().select().from(contactChannels).all().length).toBe(1);
   });
 });
 

package/src/db/contact-store.ts

@@ -2,6 +2,7 @@ import { type Database } from "bun:sqlite";
 
 import { and, desc, eq, gt, ne, sql } from "drizzle-orm";
 
+import { isBindingDemotion } from "@vellumai/gateway-client";
 import {
   type AssistantContactMetadata,
   type ContactRead,
@@ -723,6 +724,25 @@ export class ContactStore {
     if (!gwChannel) return null;
     const gwChannelId = gwChannel.id;
 
+    // Binding-strength guard (LUM-2505): never demote an active binding's
+    // provenance. A lower-strength verifiedVia (e.g. a `manual` roster attest)
+    // over an already-active, higher-strength channel (e.g. `challenge`) is
+    // refused — the stronger existing binding stands, as an idempotent no-op.
+    if (
+      gwChannel.status === "active" &&
+      isBindingDemotion(gwChannel.verifiedVia, verifiedVia)
+    ) {
+      log.warn(
+        {
+          channelId: gwChannelId,
+          existingVerifiedVia: gwChannel.verifiedVia,
+          incomingVerifiedVia: verifiedVia,
+        },
+        "markChannelVerified: refusing binding-strength demotion; preserving stronger verified_via",
+      );
+      return { channel: gwChannel, didWrite: false };
+    }
+
     const now = Date.now();
     const raw = (this.db as unknown as { $client: Database }).$client;
     const result = raw
@@ -1545,9 +1565,27 @@ export class ContactStore {
           if (ch.blockedReason !== undefined)
             updateSet.blockedReason = ch.blockedReason;
         }
-        if (ch.verifiedAt !== undefined) updateSet.verifiedAt = ch.verifiedAt;
-        if (ch.verifiedVia !== undefined)
-          updateSet.verifiedVia = ch.verifiedVia;
+        // Binding-strength guard (LUM-2505): a lower-strength verifiedVia must
+        // not demote an active binding. When it would, preserve the stronger
+        // existing verified_via/verified_at; benign field updates still apply.
+        if (
+          existing.status === "active" &&
+          ch.verifiedVia !== undefined &&
+          isBindingDemotion(existing.verifiedVia, ch.verifiedVia)
+        ) {
+          log.warn(
+            {
+              channelId: existing.id,
+              existingVerifiedVia: existing.verifiedVia,
+              incomingVerifiedVia: ch.verifiedVia,
+            },
+            "syncChannels: refusing binding-strength demotion; preserving stronger verified_via",
+          );
+        } else {
+          if (ch.verifiedAt !== undefined) updateSet.verifiedAt = ch.verifiedAt;
+          if (ch.verifiedVia !== undefined)
+            updateSet.verifiedVia = ch.verifiedVia;
+        }
         if (ch.inviteId !== undefined) updateSet.inviteId = ch.inviteId;
         this.db
           .update(contactChannels)

package/src/feature-flag-registry.json

@@ -1,6 +1,15 @@
 {
   "version": 1,
   "flags": [
+    {
+      "id": "in-chat-onboarding-tour",
+      "scope": "client",
+      "key": "in-chat-onboarding-tour",
+      "label": "In-Chat Onboarding Tour",
+      "description": "Multivariate experiment for the eyes-led in-chat onboarding tour. control = straight to chat after research onboarding (current behavior); tour = the extended tour auto-plays on first workspace entry, and the header replay button shows. Targeted via LaunchDarkly (planned 70% tour / 30% control).",
+      "defaultEnabled": "control",
+      "values": ["control", "tour"]
+    },
     {
       "id": "user-hosted-enabled",
       "scope": "client",

package/src/verification/contact-helpers.ts

@@ -15,6 +15,8 @@ import { existsSync } from "node:fs";
 
 import { and, eq, sql } from "drizzle-orm";
 
+import { isBindingDemotion } from "@vellumai/gateway-client";
+
 import { getGatewayDb } from "../db/connection.js";
 import {
   contactChannels as gwContactChannels,
@@ -82,6 +84,10 @@ export async function findContactChannelByAddress(
  * legacy/unmirrored channel may carry a different gateway id than the
  * assistant id, and a blind id-keyed update would silently affect 0 rows.
  *
+ * `verifiedAt` defaults to `now`; the caller passes an explicit value to
+ * preserve an existing timestamp when the binding-strength guard keeps a
+ * stronger `verifiedVia` (see {@link applyVerifiedChannelGatewayWrites}).
+ *
  * Returns true if a gateway row was updated or inserted; false if the only
  * matching row is blocked/revoked (so nothing was written).
  */
@@ -93,6 +99,7 @@ function writeVerifiedGatewayChannel(params: {
   externalChatId: string;
   verifiedVia: string;
   now: number;
+  verifiedAt?: number;
   allowRevokedReactivation?: boolean;
 }): boolean {
   const {
@@ -103,6 +110,7 @@ function writeVerifiedGatewayChannel(params: {
     externalChatId,
     verifiedVia,
     now,
+    verifiedAt,
     allowRevokedReactivation,
   } = params;
   const gwDb = getGatewayDb();
@@ -111,7 +119,7 @@ function writeVerifiedGatewayChannel(params: {
     policy: "allow",
     address,
     externalChatId,
-    verifiedAt: now,
+    verifiedAt: verifiedAt ?? now,
     verifiedVia,
     revokedReason: null,
     blockedReason: null,
@@ -523,8 +531,11 @@ export function applyVerifiedChannelGatewayWrites(params: {
   // The gateway is the source of truth: a blocked/revoked gateway row rejects
   // the verification, gating BOTH the existing-channel update and the
   // new-insert path so no active mirror is created for a blocked actor. A
-  // missing gateway row is the legitimate happy path (legacy/unmirrored).
-  const gwStatus = gatewayChannelStatus(sourceChannel, address);
+  // missing gateway row is the legitimate happy path (legacy/unmirrored). The
+  // same authoritative read carries the existing binding provenance for the
+  // demotion guard below.
+  const gwRow = getGatewayChannelByKey(sourceChannel, address);
+  const gwStatus = gwRow?.status ?? null;
   if (
     gwStatus === "blocked" ||
     (gwStatus === "revoked" && !allowRevokedReactivation)
@@ -536,6 +547,33 @@ export function applyVerifiedChannelGatewayWrites(params: {
     return { verified: false };
   }
 
+  // Binding-strength guard (LUM-2505): a lower-strength source must never
+  // demote the recorded provenance of an already-active binding. When the
+  // incoming write would weaken the ladder, preserve the stronger existing
+  // `verified_via` / `verified_at`; the write still refreshes identity/ACL
+  // fields, it just cannot lower the proof. Only active bindings are protected
+  // — reactivation from revoked is invite-gated (a proven, top-tier
+  // `verified_via`) and keeps the incoming provenance.
+  let effectiveVerifiedVia = verifiedVia;
+  let effectiveVerifiedAt: number | undefined;
+  if (
+    gwRow &&
+    gwRow.status === "active" &&
+    isBindingDemotion(gwRow.verifiedVia, verifiedVia)
+  ) {
+    effectiveVerifiedVia = gwRow.verifiedVia ?? verifiedVia;
+    effectiveVerifiedAt = gwRow.verifiedAt ?? undefined;
+    log.warn(
+      {
+        sourceChannel,
+        address,
+        existingVerifiedVia: gwRow.verifiedVia,
+        incomingVerifiedVia: verifiedVia,
+      },
+      "Refusing binding-strength demotion: preserving stronger existing verified_via",
+    );
+  }
+
   if (existing) {
     const row = existing;
 
@@ -575,8 +613,9 @@ export function applyVerifiedChannelGatewayWrites(params: {
       type: sourceChannel,
       address,
       externalChatId,
-      verifiedVia,
+      verifiedVia: effectiveVerifiedVia,
       now,
+      verifiedAt: effectiveVerifiedAt,
       allowRevokedReactivation,
     });
     // The pre-check passed, so a write is expected. A false means a
@@ -651,8 +690,9 @@ export function applyVerifiedChannelGatewayWrites(params: {
     type: sourceChannel,
     address,
     externalChatId,
-    verifiedVia,
+    verifiedVia: effectiveVerifiedVia,
     now,
+    verifiedAt: effectiveVerifiedAt,
     allowRevokedReactivation,
   });
   // A blocked/revoked gateway row appeared after the pre-check — reject