@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/runtime/introduction-policy.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  bindingStrengthForVerifiedVia,
+  buildIntroductionActions,
+  isHandshakeOffered,
+  isWorkspaceVouchedIdentity,
+  parseRequesterSignals,
+  resolveTrustBinding,
+  serializeRequesterSignals,
+  VERIFIED_VIA_CHANNEL_CLAIM,
+  VERIFIED_VIA_MANUAL,
+} from "./introduction-policy.js";
+
+describe("requester signal serialization", () => {
+  test("round-trips set signals and omits unset ones", () => {
+    const raw = serializeRequesterSignals({ isBot: true, isStranger: true });
+    expect(raw).toBeDefined();
+    expect(parseRequesterSignals(raw)).toEqual({
+      isBot: true,
+      isStranger: true,
+    });
+  });
+
+  test("preserves explicit false — a positive platform resolution", () => {
+    const raw = serializeRequesterSignals({
+      isBot: false,
+      isStranger: false,
+      isRestricted: false,
+    });
+    expect(raw).toBeDefined();
+    expect(parseRequesterSignals(raw)).toEqual({
+      isBot: false,
+      isStranger: false,
+      isRestricted: false,
+    });
+  });
+
+  test("returns undefined when no signal is set", () => {
+    expect(serializeRequesterSignals({})).toBeUndefined();
+    expect(
+      serializeRequesterSignals({ isBot: undefined, isStranger: undefined }),
+    ).toBeUndefined();
+  });
+
+  test("parse fails closed on malformed input", () => {
+    expect(parseRequesterSignals("not json")).toEqual({});
+    expect(parseRequesterSignals('"a string"')).toEqual({});
+    expect(parseRequesterSignals(null)).toEqual({});
+    expect(parseRequesterSignals(undefined)).toEqual({});
+    // Non-boolean values never become signals; explicit booleans survive.
+    expect(parseRequesterSignals('{"isBot":"yes","isStranger":false}')).toEqual(
+      { isStranger: false },
+    );
+  });
+});
+
+/** Explicit positive resolution: Slack vouched this is a regular member. */
+const SLACK_MEMBER = { isStranger: false, isRestricted: false } as const;
+
+describe("workspace vouching", () => {
+  test("slack member with positive signals is workspace-vouched", () => {
+    expect(isWorkspaceVouchedIdentity("slack", SLACK_MEMBER)).toBe(true);
+    expect(
+      isWorkspaceVouchedIdentity("slack", { ...SLACK_MEMBER, isBot: true }),
+    ).toBe(true);
+  });
+
+  // Regression (fail-open guard): absent signals — users.info timeout or
+  // cache miss — must NOT be treated as workspace-vouched.
+  test("unknown signals fail toward NOT vouched", () => {
+    expect(isWorkspaceVouchedIdentity("slack", {})).toBe(false);
+    expect(isWorkspaceVouchedIdentity("slack", { isStranger: false })).toBe(
+      false,
+    );
+    expect(isWorkspaceVouchedIdentity("slack", { isRestricted: false })).toBe(
+      false,
+    );
+  });
+
+  test("slack strangers and restricted guests are not vouched", () => {
+    expect(
+      isWorkspaceVouchedIdentity("slack", {
+        isStranger: true,
+        isRestricted: false,
+      }),
+    ).toBe(false);
+    expect(
+      isWorkspaceVouchedIdentity("slack", {
+        isStranger: false,
+        isRestricted: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("non-slack channels carry no workspace identity", () => {
+    expect(isWorkspaceVouchedIdentity("telegram", SLACK_MEMBER)).toBe(false);
+    expect(isWorkspaceVouchedIdentity("phone", SLACK_MEMBER)).toBe(false);
+    expect(isWorkspaceVouchedIdentity(undefined, SLACK_MEMBER)).toBe(false);
+  });
+});
+
+describe("handshake policy", () => {
+  test("never offered for bots, on any channel", () => {
+    expect(isHandshakeOffered("slack", { isBot: true })).toBe(false);
+    expect(isHandshakeOffered("slack", { isBot: true, isStranger: true })).toBe(
+      false,
+    );
+    expect(isHandshakeOffered("telegram", { isBot: true })).toBe(false);
+  });
+
+  test("not offered for workspace-vouched slack members", () => {
+    expect(isHandshakeOffered("slack", SLACK_MEMBER)).toBe(false);
+  });
+
+  test("not offered on voice", () => {
+    expect(isHandshakeOffered("phone", {})).toBe(false);
+  });
+
+  test("leads for externals, strangers, and identity-less channels", () => {
+    expect(isHandshakeOffered("slack", { isStranger: true })).toBe(true);
+    expect(isHandshakeOffered("slack", { isRestricted: true })).toBe(true);
+    // Unknown signals (users.info failure) fail toward the handshake.
+    expect(isHandshakeOffered("slack", {})).toBe(true);
+    expect(isHandshakeOffered("telegram", {})).toBe(true);
+    expect(isHandshakeOffered("email", {})).toBe(true);
+  });
+});
+
+describe("introduction action lists", () => {
+  test("workspace member: direct trust leads, no code option", () => {
+    expect(
+      buildIntroductionActions("slack", SLACK_MEMBER).map((a) => a.id),
+    ).toEqual(["trust", "leave_unverified", "block"]);
+  });
+
+  test("bot: trust only — the code option is never rendered", () => {
+    for (const channel of ["slack", "telegram", "whatsapp"]) {
+      const ids = buildIntroductionActions(channel, {
+        isBot: true,
+        isStranger: true,
+      }).map((a) => a.id);
+      expect(ids).not.toContain("verify_code");
+      expect(ids).toEqual(["trust", "leave_unverified", "block"]);
+    }
+  });
+
+  test("external: handshake leads, trust is 'Trust anyway'", () => {
+    const actions = buildIntroductionActions("slack", { isStranger: true });
+    expect(actions.map((a) => a.id)).toEqual([
+      "verify_code",
+      "trust",
+      "leave_unverified",
+      "block",
+    ]);
+    expect(actions[0].label).toBe("Verify with a code");
+    expect(actions[1].label).toBe("Trust anyway");
+  });
+});
+
+describe("binding strength", () => {
+  test("trust on a workspace member records internal_workspace_match via manual", () => {
+    expect(resolveTrustBinding("slack", SLACK_MEMBER)).toEqual({
+      bindingStrength: "internal_workspace_match",
+      verifiedVia: VERIFIED_VIA_MANUAL,
+    });
+  });
+
+  // Regression (fail-open guard): unknown signals must never earn
+  // workspace-match provenance.
+  test("trust with unknown signals records inbound_channel_claim", () => {
+    expect(resolveTrustBinding("slack", {})).toEqual({
+      bindingStrength: "inbound_channel_claim",
+      verifiedVia: VERIFIED_VIA_CHANNEL_CLAIM,
+    });
+  });
+
+  // Regression (LUM-2670 ladder honesty): a trusted-anyway external must NOT
+  // carry the same binding strength as a code-verified contact.
+  test("trust-anyway on an external records inbound_channel_claim, NOT verified_handshake", () => {
+    for (const [channel, signals] of [
+      ["slack", { isStranger: true }],
+      ["slack", { isRestricted: true }],
+      ["telegram", {}],
+    ] as const) {
+      const binding = resolveTrustBinding(channel, signals);
+      expect(binding.bindingStrength).toBe("inbound_channel_claim");
+      expect(binding.bindingStrength).not.toBe("verified_handshake");
+      expect(binding.verifiedVia).toBe(VERIFIED_VIA_CHANNEL_CLAIM);
+      // The persisted provenance must not collapse into the code-verified or
+      // workspace-vouched values.
+      expect(binding.verifiedVia).not.toBe("challenge");
+      expect(bindingStrengthForVerifiedVia(binding.verifiedVia)).toBe(
+        "inbound_channel_claim",
+      );
+    }
+  });
+
+  test("verifiedVia provenance maps onto the ladder", () => {
+    expect(bindingStrengthForVerifiedVia("challenge")).toBe(
+      "verified_handshake",
+    );
+    expect(bindingStrengthForVerifiedVia("manual")).toBe(
+      "internal_workspace_match",
+    );
+    expect(bindingStrengthForVerifiedVia("manual_channel_claim")).toBe(
+      "inbound_channel_claim",
+    );
+    // Pre-ladder provenance keeps its own audit meaning.
+    expect(bindingStrengthForVerifiedVia("invite")).toBeNull();
+    expect(bindingStrengthForVerifiedVia("bootstrap")).toBeNull();
+    expect(bindingStrengthForVerifiedVia(null)).toBeNull();
+  });
+});

package/src/runtime/introduction-policy.ts

@@ -0,0 +1,284 @@
+/**
+ * Introduction-card policy (Lane A trust-setting).
+ *
+ * When a new contact first appears, the guardian resolves their trust level on
+ * a single introduction card with four outcomes:
+ *
+ *   | Action             | Outcome              | verifiedVia              |
+ *   | ------------------ | -------------------- | ------------------------ |
+ *   | `trust`            | trusted_contact      | manual / channel-claim   |
+ *   | `verify_code`      | trusted_contact      | challenge (post-handshake) |
+ *   | `leave_unverified` | unverified_contact   | —                        |
+ *   | `block`            | revoked              | —                        |
+ *
+ * The verification handshake is a signal-driven exception, not the default:
+ * which actions are offered (and which leads) is derived from the platform's
+ * own identity confidence — never from per-individual-contact rules.
+ *
+ * This module is the single source of truth for:
+ *   - the requester identity signals persisted on canonical access requests,
+ *   - the binding-strength ladder derived from `verifiedVia` provenance,
+ *   - the signal-driven action list every card surface renders.
+ *
+ * Binding strength is provenance/audit only — it never enters the capability
+ * layer (`trusted_contact` ≡ `unverified_contact` on capabilities).
+ */
+
+import type { ApprovalAction } from "./channel-approval-types.js";
+
+// ---------------------------------------------------------------------------
+// Requester identity signals
+// ---------------------------------------------------------------------------
+
+/**
+ * Platform-provided identity signals for the requester, captured at
+ * access-request creation so decision-time policy (binding strength, bot
+ * coercion) reads the same facts the card was rendered from.
+ *
+ * Each signal is tri-state: `true` / `false` are positive platform
+ * resolutions (Slack `users.info` succeeded and said so); `undefined` means
+ * the platform could not vouch either way (lookup failure, channel without
+ * workspace identity). Policy must treat `undefined` as NOT vouched.
+ */
+export interface RequesterIdentitySignals {
+  /** The requester is a bot / integration account (Slack `is_bot`, Telegram `is_bot`). */
+  isBot?: boolean;
+  /** Slack: external user from another workspace (Slack Connect). */
+  isStranger?: boolean;
+  /** Slack: guest / restricted account. */
+  isRestricted?: boolean;
+}
+
+const SIGNAL_KEYS = [
+  "isBot",
+  "isStranger",
+  "isRestricted",
+] as const satisfies ReadonlyArray<keyof RequesterIdentitySignals>;
+
+/**
+ * Coerce an untrusted value to a tri-state identity-signal boolean: explicit
+ * booleans pass through (both are positive platform resolutions), everything
+ * else is unknown. Shared by the persisted-signal parser and the
+ * access-request payload schema so the tri-state rule cannot drift.
+ */
+export function coerceSignalBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function compactSignals(
+  record: Partial<Record<(typeof SIGNAL_KEYS)[number], unknown>>,
+): RequesterIdentitySignals {
+  const compact: RequesterIdentitySignals = {};
+  for (const key of SIGNAL_KEYS) {
+    const value = coerceSignalBoolean(record[key]);
+    if (value !== undefined) {
+      compact[key] = value;
+    }
+  }
+  return compact;
+}
+
+/**
+ * Serialize signals for the `requester_signals` column. Explicit `false` is
+ * preserved — it is a positive "platform vouches this is a regular member"
+ * fact, distinct from an absent (unknown) signal. Returns undefined when no
+ * signal was resolved at all.
+ */
+export function serializeRequesterSignals(
+  signals: RequesterIdentitySignals,
+): string | undefined {
+  const compact = compactSignals(signals);
+  return Object.keys(compact).length > 0 ? JSON.stringify(compact) : undefined;
+}
+
+/** Parse the persisted `requester_signals` column. Malformed values fail closed to no signals. */
+export function parseRequesterSignals(
+  raw: string | null | undefined,
+): RequesterIdentitySignals {
+  if (!raw) {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+    return compactSignals(parsed as Record<string, unknown>);
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Binding strength ladder
+// ---------------------------------------------------------------------------
+
+/**
+ * Binding-strength ladder: how strongly the contact's channel identity is
+ * bound to the person/agent the guardian believes they are.
+ *
+ *   verified_handshake > internal_workspace_match > inbound_channel_claim
+ *
+ * - `verified_handshake` — the contact proved control of the channel by
+ *   returning a verification code (`verifiedVia: "challenge"`).
+ * - `internal_workspace_match` — the platform already authenticated the
+ *   identity inside the guardian's own workspace (Slack member or workspace
+ *   app); the guardian vouches directly (`verifiedVia: "manual"`).
+ * - `inbound_channel_claim` — the guardian trusts an identity the platform is
+ *   NOT vouching for (external / Slack-Connect / restricted guest / channels
+ *   without workspace identity). Recorded as
+ *   `verifiedVia: "manual_channel_claim"` so a trusted-anyway external never
+ *   carries the same provenance as a code-verified contact.
+ */
+export type BindingStrength =
+  | "verified_handshake"
+  | "internal_workspace_match"
+  | "inbound_channel_claim";
+
+/** verifiedVia written when the guardian direct-trusts a workspace-vouched identity. */
+export const VERIFIED_VIA_MANUAL = "manual";
+
+/** verifiedVia written when the guardian trusts an identity the platform is not vouching for. */
+export const VERIFIED_VIA_CHANNEL_CLAIM = "manual_channel_claim";
+
+/** verifiedVia written by the gateway when a verification code is redeemed. */
+export const VERIFIED_VIA_CHALLENGE = "challenge";
+
+/**
+ * Derive the binding strength recorded by a `verifiedVia` provenance value.
+ * Returns null for provenance outside the introduction ladder (e.g. "invite",
+ * "bootstrap"), which predate it and keep their own audit meaning.
+ */
+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;
+  }
+}
+
+/**
+ * Whether the platform itself vouches for the requester's identity inside the
+ * guardian's workspace. Only Slack carries workspace identity today: a
+ * non-stranger, non-restricted member (human or workspace app) is
+ * authenticated by Slack. Every other channel is an inbound channel claim.
+ *
+ * Requires POSITIVE signals: `isStranger` and `isRestricted` must be an
+ * explicit `false` (Slack `users.info` resolved the user and vouched).
+ * Absent signals — a lookup failure or timeout — fail toward NOT vouched, so
+ * a Slack-Connect user in a degraded path never gets a one-tap Trust default
+ * or `manual` (workspace-match) provenance.
+ */
+export function isWorkspaceVouchedIdentity(
+  sourceChannel: string | undefined,
+  signals: RequesterIdentitySignals,
+): boolean {
+  return (
+    sourceChannel === "slack" &&
+    signals.isStranger === false &&
+    signals.isRestricted === false
+  );
+}
+
+/**
+ * Resolve the trust-decision binding for a direct **Trust** action: the
+ * binding strength the decision records and the `verifiedVia` provenance that
+ * persists it. A trusted-anyway external must NOT record
+ * `verified_handshake`-equivalent provenance.
+ */
+export function resolveTrustBinding(
+  sourceChannel: string | undefined,
+  signals: RequesterIdentitySignals,
+): { bindingStrength: BindingStrength; verifiedVia: string } {
+  if (isWorkspaceVouchedIdentity(sourceChannel, signals)) {
+    return {
+      bindingStrength: "internal_workspace_match",
+      verifiedVia: VERIFIED_VIA_MANUAL,
+    };
+  }
+  return {
+    bindingStrength: "inbound_channel_claim",
+    verifiedVia: VERIFIED_VIA_CHANNEL_CLAIM,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Signal-driven action list
+// ---------------------------------------------------------------------------
+
+/**
+ * A single introduction-card action option, shared by every card renderer.
+ * `emphasis` is the surface-agnostic weight each renderer translates to its
+ * platform token (Slack `primary`/`danger`, Surface `primary`/`destructive`),
+ * so the emphasis policy lives here rather than per renderer.
+ */
+export interface IntroductionActionOption {
+  id: Extract<
+    ApprovalAction,
+    "trust" | "verify_code" | "leave_unverified" | "block"
+  >;
+  label: string;
+  emphasis: "primary" | "secondary" | "destructive";
+}
+
+/**
+ * Whether the verification handshake is offered for this requester.
+ *
+ * The handshake is the exception, not the default:
+ * - never for bots/integrations — a bot cannot return a code;
+ * - not for workspace-vouched identities — the platform already
+ *   authenticated them;
+ * - not on voice — a phone call has no text handshake path;
+ * - offered everywhere else: it leads for identities nobody is vouching for.
+ */
+export function isHandshakeOffered(
+  sourceChannel: string | undefined,
+  signals: RequesterIdentitySignals,
+): boolean {
+  if (signals.isBot === true) {
+    return false;
+  }
+  if (sourceChannel === "phone") {
+    return false;
+  }
+  return !isWorkspaceVouchedIdentity(sourceChannel, signals);
+}
+
+/**
+ * Build the ordered introduction-card action list for a requester. The first
+ * action is the emphasized default:
+ *
+ *   workspace member / bot / voice:  [ Trust ] [ Leave unverified ] [ Block ]
+ *   external / stranger / guest:     [ Verify with a code ] [ Trust anyway ]
+ *                                    [ Leave unverified ] [ Block ]
+ *
+ * The code option is NEVER rendered for a bot.
+ */
+export function buildIntroductionActions(
+  sourceChannel: string | undefined,
+  signals: RequesterIdentitySignals,
+): IntroductionActionOption[] {
+  const tail: IntroductionActionOption[] = [
+    {
+      id: "leave_unverified",
+      label: "Leave unverified",
+      emphasis: "secondary",
+    },
+    { id: "block", label: "Block", emphasis: "destructive" },
+  ];
+  if (isHandshakeOffered(sourceChannel, signals)) {
+    return [
+      { id: "verify_code", label: "Verify with a code", emphasis: "primary" },
+      { id: "trust", label: "Trust anyway", emphasis: "secondary" },
+      ...tail,
+    ];
+  }
+  return [{ id: "trust", label: "Trust", emphasis: "primary" }, ...tail];
+}