@vellumai/assistant 0.3.18 → 0.3.20

package/src/__tests__/inbound-invite-redemption.test.ts

@@ -0,0 +1,367 @@
+/**
+ * Integration tests for the inbound invite redemption intercept.
+ *
+ * Validates that non-members with valid `/start iv_<token>` payloads are
+ * granted access without guardian approval, and that invalid/expired/revoked
+ * tokens produce the correct deterministic refusal messages.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Test isolation: in-memory SQLite via temp directory
+// ---------------------------------------------------------------------------
+
+const testDir = mkdtempSync(join(tmpdir(), 'inbound-invite-redemption-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+  normalizeAssistantId: (id: string) => id === 'self' ? 'self' : id,
+  readHttpToken: () => 'test-bearer-token',
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../security/secret-ingress.js', () => ({
+  checkIngressForSecrets: () => ({ blocked: false }),
+}));
+
+mock.module('../config/env.js', () => ({
+  getGatewayInternalBaseUrl: () => 'http://127.0.0.1:7830',
+}));
+
+// Mock the credential metadata store so the Telegram transport adapter
+// resolves without touching the filesystem.
+mock.module('../tools/credentials/metadata-store.js', () => ({
+  getCredentialMetadata: () => undefined,
+  upsertCredentialMetadata: () => {},
+  deleteCredentialMetadata: () => {},
+  listCredentialMetadata: () => [],
+}));
+
+const emitSignalCalls: Array<Record<string, unknown>> = [];
+mock.module('../notifications/emit-signal.js', () => ({
+  emitNotificationSignal: async (params: Record<string, unknown>) => {
+    emitSignalCalls.push(params);
+    return {
+      signalId: 'mock-signal-id',
+      deduplicated: false,
+      dispatched: true,
+      reason: 'mock',
+      deliveryResults: [],
+    };
+  },
+}));
+
+const deliverReplyCalls: Array<{ url: string; payload: Record<string, unknown> }> = [];
+mock.module('../runtime/gateway-client.js', () => ({
+  deliverChannelReply: async (url: string, payload: Record<string, unknown>) => {
+    deliverReplyCalls.push({ url, payload });
+  },
+}));
+
+mock.module('../runtime/approval-message-composer.js', () => ({
+  composeApprovalMessage: () => 'mock approval message',
+  composeApprovalMessageGenerative: async () => 'mock generative message',
+}));
+
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
+import { createInvite, revokeInvite } from '../memory/ingress-invite-store.js';
+import { findMember, upsertMember } from '../memory/ingress-member-store.js';
+import { handleChannelInbound } from '../runtime/routes/channel-routes.js';
+
+initializeDb();
+
+afterAll(() => {
+  resetDb();
+  try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TEST_BEARER_TOKEN = 'test-token';
+let msgCounter = 0;
+
+function resetState(): void {
+  const db = getDb();
+  db.run('DELETE FROM assistant_ingress_members');
+  db.run('DELETE FROM assistant_ingress_invites');
+  db.run('DELETE FROM channel_inbound_events');
+  db.run('DELETE FROM conversations');
+  db.run('DELETE FROM channel_guardian_approval_requests');
+  db.run('DELETE FROM channel_guardian_bindings');
+  db.run('DELETE FROM notification_events');
+  emitSignalCalls.length = 0;
+  deliverReplyCalls.length = 0;
+  msgCounter = 0;
+}
+
+function buildInboundRequest(overrides: Record<string, unknown> = {}): Request {
+  msgCounter++;
+  const body: Record<string, unknown> = {
+    sourceChannel: 'telegram',
+    interface: 'telegram',
+    externalChatId: 'chat-invite-test',
+    externalMessageId: `msg-invite-${Date.now()}-${msgCounter}`,
+    content: '/start iv_sometoken',
+    senderExternalUserId: 'user-invite-123',
+    senderName: 'Invite User',
+    senderUsername: 'invite_user',
+    replyCallbackUrl: 'http://localhost:7830/deliver/telegram',
+    sourceMetadata: {
+      commandIntent: { type: 'start', payload: 'iv_sometoken' },
+    },
+    ...overrides,
+  };
+
+  return new Request('http://localhost:8080/channels/inbound', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Gateway-Origin': TEST_BEARER_TOKEN,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+/**
+ * Build a request with a specific invite token, using the structured
+ * commandIntent that the gateway produces for `/start <payload>`.
+ */
+function buildInviteRequest(rawToken: string, overrides: Record<string, unknown> = {}): Request {
+  return buildInboundRequest({
+    content: `/start iv_${rawToken}`,
+    sourceMetadata: {
+      commandIntent: { type: 'start', payload: `iv_${rawToken}` },
+    },
+    ...overrides,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('inbound invite redemption intercept', () => {
+  beforeEach(resetState);
+
+  test('non-member with valid invite token becomes active member without guardian approval', async () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    const req = buildInviteRequest(rawToken);
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.accepted).toBe(true);
+    expect(json.inviteRedemption).toBe('redeemed');
+    expect(json.memberId).toEqual(expect.any(String));
+    expect(json.denied).toBeUndefined();
+
+    // Verify the user is now an active member
+    const member = findMember({
+      assistantId: 'self',
+      sourceChannel: 'telegram',
+      externalUserId: 'user-invite-123',
+    });
+    expect(member).not.toBeNull();
+    expect(member!.status).toBe('active');
+
+    // Verify a welcome reply was delivered
+    expect(deliverReplyCalls.length).toBe(1);
+    const replyText = (deliverReplyCalls[0].payload as Record<string, unknown>).text;
+    expect(replyText).toContain("Welcome! You've been granted access via invite link.");
+  });
+
+  test('non-member with invalid token gets refusal text', async () => {
+    const req = buildInviteRequest('completely-bogus-token-xyz');
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBe(true);
+    expect(json.inviteRedemption).toBe('invalid_token');
+
+    // Verify refusal reply was delivered
+    expect(deliverReplyCalls.length).toBe(1);
+    const replyText = (deliverReplyCalls[0].payload as Record<string, unknown>).text;
+    expect(replyText).toContain('no longer valid');
+
+    // Verify the user was NOT made a member
+    const member = findMember({
+      assistantId: 'self',
+      sourceChannel: 'telegram',
+      externalUserId: 'user-invite-123',
+    });
+    expect(member).toBeNull();
+  });
+
+  test('non-member with expired token gets appropriate message', async () => {
+    const { rawToken } = createInvite({
+      sourceChannel: 'telegram',
+      maxUses: 1,
+      expiresInMs: -1, // already expired
+    });
+
+    const req = buildInviteRequest(rawToken);
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBe(true);
+    expect(json.inviteRedemption).toBe('expired');
+
+    expect(deliverReplyCalls.length).toBe(1);
+    const replyText = (deliverReplyCalls[0].payload as Record<string, unknown>).text;
+    expect(replyText).toContain('no longer valid');
+  });
+
+  test('non-member with revoked token gets refusal text', async () => {
+    const { rawToken, invite } = createInvite({
+      sourceChannel: 'telegram',
+      maxUses: 5,
+    });
+    revokeInvite(invite.id);
+
+    const req = buildInviteRequest(rawToken);
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBe(true);
+    expect(json.inviteRedemption).toBe('revoked');
+
+    expect(deliverReplyCalls.length).toBe(1);
+    const replyText = (deliverReplyCalls[0].payload as Record<string, unknown>).text;
+    expect(replyText).toContain('no longer valid');
+  });
+
+  test('existing /start gv_<token> guardian bootstrap flow is unaffected', async () => {
+    // Send a /start gv_ command — should not be intercepted by the invite flow.
+    // Without a valid bootstrap session, it should be denied at the ACL gate.
+    const req = buildInboundRequest({
+      content: '/start gv_some_bootstrap_token',
+      sourceMetadata: {
+        commandIntent: { type: 'start', payload: 'gv_some_bootstrap_token' },
+      },
+    });
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    // Should be denied as a non-member (bootstrap token is invalid/no session)
+    expect(json.denied).toBe(true);
+    expect(json.reason).toBe('not_a_member');
+    // Should NOT have invite redemption fields
+    expect(json.inviteRedemption).toBeUndefined();
+  });
+
+  test('duplicate Telegram webhook deliveries do not double-redeem', async () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    const sharedMessageId = `msg-dedup-${Date.now()}`;
+    const makeReq = () => buildInviteRequest(rawToken, {
+      externalMessageId: sharedMessageId,
+    });
+
+    // First delivery
+    const resp1 = await handleChannelInbound(makeReq(), undefined, TEST_BEARER_TOKEN);
+    const json1 = await resp1.json() as Record<string, unknown>;
+    expect(json1.inviteRedemption).toBe('redeemed');
+
+    // Second delivery (duplicate webhook)
+    const resp2 = await handleChannelInbound(makeReq(), undefined, TEST_BEARER_TOKEN);
+    const json2 = await resp2.json() as Record<string, unknown>;
+    // Dedup kicks in — the message is treated as a duplicate and no second
+    // redemption attempt occurs.
+    expect(json2.duplicate).toBe(true);
+
+    // Only one welcome reply was delivered
+    expect(deliverReplyCalls.length).toBe(1);
+  });
+
+  test('existing active member sending normal message is unaffected', async () => {
+    // Pre-create an active member
+    upsertMember({
+      assistantId: 'self',
+      sourceChannel: 'telegram',
+      externalUserId: 'user-active-member',
+      externalChatId: 'chat-active',
+      status: 'active',
+      policy: 'allow',
+    });
+
+    // Active member sends a normal message (no invite token)
+    const req = buildInboundRequest({
+      content: 'Hello, just a normal message!',
+      senderExternalUserId: 'user-active-member',
+      externalChatId: 'chat-active',
+      sourceMetadata: {},
+    });
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    // Should be accepted normally, not denied, not invite-redeemed
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBeUndefined();
+    expect(json.inviteRedemption).toBeUndefined();
+  });
+
+  test('channel mismatch returns appropriate message', async () => {
+    // Create an invite for SMS, but try to redeem via Telegram
+    const { rawToken } = createInvite({ sourceChannel: 'sms', maxUses: 5 });
+
+    const req = buildInviteRequest(rawToken);
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBe(true);
+    expect(json.inviteRedemption).toBe('channel_mismatch');
+
+    expect(deliverReplyCalls.length).toBe(1);
+    const replyText = (deliverReplyCalls[0].payload as Record<string, unknown>).text;
+    expect(replyText).toContain('not valid for this channel');
+  });
+
+  test('already-active member with invite token gets acknowledgement', async () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    // Pre-create an active member that will click the invite link
+    upsertMember({
+      assistantId: 'self',
+      sourceChannel: 'telegram',
+      externalUserId: 'user-already-active',
+      externalChatId: 'chat-invite-test',
+      status: 'active',
+      policy: 'allow',
+    });
+
+    const req = buildInviteRequest(rawToken, {
+      senderExternalUserId: 'user-already-active',
+    });
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    // Active members pass through the ACL gate, so the invite intercept
+    // does not fire. The message proceeds to normal processing.
+    expect(json.accepted).toBe(true);
+    expect(json.denied).toBeUndefined();
+  });
+});

package/src/__tests__/invite-redemption-service.test.ts

@@ -0,0 +1,306 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+const testDir = mkdtempSync(join(tmpdir(), 'invite-redemption-service-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+import { getSqlite, initializeDb, resetDb } from '../memory/db.js';
+import { createInvite, revokeInvite as revokeStoreFn } from '../memory/ingress-invite-store.js';
+import { upsertMember } from '../memory/ingress-member-store.js';
+import { type InviteRedemptionOutcome,redeemInvite } from '../runtime/invite-redemption-service.js';
+
+initializeDb();
+
+afterAll(() => {
+  resetDb();
+  try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
+});
+
+function resetTables() {
+  getSqlite().run('DELETE FROM assistant_ingress_members');
+  getSqlite().run('DELETE FROM assistant_ingress_invites');
+}
+
+describe('invite-redemption-service', () => {
+  beforeEach(resetTables);
+
+  test('redeems a valid invite and returns typed outcome', () => {
+    const { rawToken, invite } = createInvite({ sourceChannel: 'telegram', maxUses: 1 });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome.ok).toBe(true);
+    expect(outcome).toEqual({
+      ok: true,
+      type: 'redeemed',
+      memberId: expect.any(String),
+      inviteId: invite.id,
+    });
+  });
+
+  test('returns invalid_token for a bogus token', () => {
+    const outcome = redeemInvite({
+      rawToken: 'totally-bogus-token',
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'invalid_token' });
+  });
+
+  test('returns expired for an expired invite', () => {
+    // Create an invite that expired 1 ms ago
+    const { rawToken } = createInvite({
+      sourceChannel: 'telegram',
+      maxUses: 1,
+      expiresInMs: -1,
+    });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'expired' });
+  });
+
+  test('returns revoked for a revoked invite', () => {
+    const { rawToken, invite } = createInvite({
+      sourceChannel: 'telegram',
+      maxUses: 1,
+    });
+    revokeStoreFn(invite.id);
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'revoked' });
+  });
+
+  test('returns max_uses_reached when invite is fully consumed', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 1 });
+
+    // First redemption should succeed
+    const first = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+    expect(first.ok).toBe(true);
+
+    // Second attempt should fail — the invite is now fully redeemed
+    const second = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-2',
+    });
+
+    expect(second).toEqual({ ok: false, reason: 'max_uses_reached' });
+  });
+
+  test('returns channel_mismatch when redeeming on wrong channel', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 1 });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'sms',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'channel_mismatch' });
+  });
+
+  test('returns missing_identity when no externalUserId or externalChatId', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 1 });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'missing_identity' });
+  });
+
+  test('returns already_member when user is already an active member', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    // Pre-create an active member
+    upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'existing-user',
+      status: 'active',
+    });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'existing-user',
+    });
+
+    expect(outcome.ok).toBe(true);
+    expect((outcome as Extract<InviteRedemptionOutcome, { type: 'already_member' }>).type).toBe('already_member');
+    expect((outcome as Extract<InviteRedemptionOutcome, { type: 'already_member' }>).memberId).toEqual(expect.any(String));
+  });
+
+  test('returns invalid_token for a blocked member to avoid leaking membership status', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    // Pre-create a blocked member — simulates a guardian-initiated block
+    upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'blocked-user',
+      status: 'blocked',
+    });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'blocked-user',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'invalid_token' });
+  });
+
+  test('does not return already_member for a revoked member', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 5 });
+
+    // Pre-create a revoked member
+    const member = upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'revoked-user',
+      status: 'revoked',
+    });
+    expect(member.status).toBe('revoked');
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'revoked-user',
+    });
+
+    // Should redeem, not return already_member
+    expect(outcome.ok).toBe(true);
+    expect((outcome as Extract<InviteRedemptionOutcome, { type: 'redeemed' }>).type).toBe('redeemed');
+  });
+
+  test('raw token is not present in the outcome object', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'telegram', maxUses: 1 });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'user-1',
+    });
+
+    // Verify the raw token does not appear anywhere in the serialized outcome
+    const serialized = JSON.stringify(outcome);
+    expect(serialized).not.toContain(rawToken);
+  });
+
+  test('channel enforcement blocks cross-channel redemption (voice invite via slack)', () => {
+    const { rawToken } = createInvite({ sourceChannel: 'voice', maxUses: 1 });
+
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'slack',
+      externalUserId: 'user-1',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'channel_mismatch' });
+  });
+
+  test('returns invalid_token for an active member with a bogus token (no membership probing)', () => {
+    // Pre-create an active member
+    upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'probed-user',
+      status: 'active',
+    });
+
+    // Attempt to redeem with a bogus token — must NOT leak membership status
+    const outcome = redeemInvite({
+      rawToken: 'completely-bogus-token',
+      sourceChannel: 'telegram',
+      externalUserId: 'probed-user',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'invalid_token' });
+  });
+
+  test('returns expired for an active member with an expired invite token', () => {
+    // Create an expired invite
+    const { rawToken } = createInvite({
+      sourceChannel: 'telegram',
+      maxUses: 5,
+      expiresInMs: -1,
+    });
+
+    // Pre-create an active member
+    upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'expired-token-user',
+      status: 'active',
+    });
+
+    // Expired token must return expired, not already_member
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'expired-token-user',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'expired' });
+  });
+
+  test('returns channel_mismatch for an active member with a valid token for a different channel', () => {
+    // Create an invite for SMS
+    const { rawToken } = createInvite({
+      sourceChannel: 'sms',
+      maxUses: 5,
+    });
+
+    // Pre-create an active member on telegram
+    upsertMember({
+      sourceChannel: 'telegram',
+      externalUserId: 'cross-channel-user',
+      status: 'active',
+    });
+
+    // Valid token for wrong channel must return channel_mismatch, not already_member
+    const outcome = redeemInvite({
+      rawToken,
+      sourceChannel: 'telegram',
+      externalUserId: 'cross-channel-user',
+    });
+
+    expect(outcome).toEqual({ ok: false, reason: 'channel_mismatch' });
+  });
+});