Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

19.2 KB
Raw Blame
/**
 * ghost · OAuth 凭证声明(source: 'oauth')校验与确认框条目。
 * 独立文件(不并入 ghost.test.ts):OAuth 契约(2026-07-13 通用声明式定案)
 * 的专属回归面——authorizeUrl / tokenUrl 域名钉白名单、scopes 上限、保留
 * 参数拒绝、identity 声明、确认框展示授权域名与 scopes 原文。
 */
import { describe, expect, it } from 'vitest';

import {
  GHOST_OAUTH_CLIENT_ID_ALTERNATIVES_MAX,
  GHOST_OAUTH_RESERVED_AUTHORIZE_PARAMS,
  GHOST_OAUTH_SCOPES_MAX,
  ghostPermissionItems,
  validateGhostManifest,
  type GhostManifest,
} from '../ghost.js';

/** 带 network 槽 + oauth 凭证的最小合法清单。 */
function oauthManifest(overrides?: {
  secret?: Record<string, unknown>;
  oauth?: Record<string, unknown> | undefined;
}): Record<string, unknown> {
  return {
    schemaVersion: 2,
    id: 'g-oauth',
    name: 'OAuth 意识',
    version: '1.0.0',
    entry: 'main.js',
    slots: ['network'],
    settingsHtml: 'settings.html',
    network: {
      hosts: ['accounts.example.com', 'api.example.com'],
      secrets: [
        {
          key: 'acct',
          label: 'Example 账号',
          source: 'oauth',
          inject: { header: 'Authorization', format: 'Bearer {value}' },
          ...(overrides && Object.hasOwn(overrides, 'oauth')
            ? overrides.oauth !== undefined
              ? { oauth: overrides.oauth }
              : {}
            : {
                oauth: {
                  authorizeUrl: 'https://accounts.example.com/authorize',
                  tokenUrl: 'https://accounts.example.com/token',
                  scopes: ['read.a', 'write.b'],
                },
              }),
          ...(overrides?.secret ?? {}),
        },
      ],
    },
  };
}

describe('ghost · oauth 凭证声明校验', () => {
  it('合法声明通过,归一化保留 oauth 详单', () => {
    const result = validateGhostManifest(oauthManifest());
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    const secret = result.manifest.network?.secrets?.[0];
    expect(secret?.source).toBe('oauth');
    expect(secret?.oauth?.authorizeUrl).toBe('https://accounts.example.com/authorize');
    expect(secret?.oauth?.scopes).toEqual(['read.a', 'write.b']);
  });

  it('source: oauth 而缺 oauth 详单 → 拒', () => {
    expect(validateGhostManifest(oauthManifest({ oauth: undefined })).ok).toBe(false);
  });

  it('非 oauth 来源声明 oauth 详单 → 拒', () => {
    const m = oauthManifest();
    const secret = (m.network as { secrets: Record<string, unknown>[] }).secrets[0];
    delete secret.source;
    expect(validateGhostManifest(m).ok).toBe(false);
  });

  it('oauth 与 exchange 互斥', () => {
    const result = validateGhostManifest(
      oauthManifest({
        secret: {
          exchange: { url: 'https://api.example.com/token', bodyFormat: '{"k":"{value}"}', tokenPath: 't' },
        },
      }),
    );
    expect(result.ok).toBe(false);
    if (!result.ok) expect(result.reason).toContain('exchange');
  });

  it('authorizeUrl / tokenUrl / identity.url 域名必须命中 hosts 白名单', () => {
    for (const field of ['authorizeUrl', 'tokenUrl'] as const) {
      const oauth: Record<string, unknown> = {
        authorizeUrl: 'https://accounts.example.com/authorize',
        tokenUrl: 'https://accounts.example.com/token',
      };
      oauth[field] = 'https://evil.com/x';
      expect(validateGhostManifest(oauthManifest({ oauth })).ok, field).toBe(false);
    }
    expect(
      validateGhostManifest(
        oauthManifest({
          oauth: {
            authorizeUrl: 'https://accounts.example.com/authorize',
            tokenUrl: 'https://accounts.example.com/token',
            identity: { url: 'https://evil.com/me', labelPath: 'email' },
          },
        }),
      ).ok,
    ).toBe(false);
  });

  it('http / 带端口 / 内嵌凭证的端点 → 拒', () => {
    for (const bad of [
      'http://accounts.example.com/authorize',
      'https://accounts.example.com:8443/authorize',
      'https://u:[email protected]/authorize',
    ]) {
      expect(
        validateGhostManifest(
          oauthManifest({ oauth: { authorizeUrl: bad, tokenUrl: 'https://accounts.example.com/token' } }),
        ).ok,
        bad,
      ).toBe(false);
    }
  });

  it('scopes:超上限 / 含空白 / 重复 → 拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, scopes: Array.from({ length: GHOST_OAUTH_SCOPES_MAX + 1 }, (_, i) => `s${i}`) } }),
      ).ok,
    ).toBe(false);
    expect(validateGhostManifest(oauthManifest({ oauth: { ...base, scopes: ['bad scope'] } })).ok).toBe(false);
    expect(validateGhostManifest(oauthManifest({ oauth: { ...base, scopes: ['dup', 'dup'] } })).ok).toBe(false);
  });

  it('extraAuthorizeParams:保留参数 / 非法键名 / 超长值 → 拒;合法参数通过', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    for (const reserved of GHOST_OAUTH_RESERVED_AUTHORIZE_PARAMS) {
      expect(
        validateGhostManifest(oauthManifest({ oauth: { ...base, extraAuthorizeParams: { [reserved]: 'x' } } })).ok,
        reserved,
      ).toBe(false);
    }
    expect(
      validateGhostManifest(oauthManifest({ oauth: { ...base, extraAuthorizeParams: { 'Bad-Key': 'x' } } })).ok,
    ).toBe(false);
    expect(
      validateGhostManifest(oauthManifest({ oauth: { ...base, extraAuthorizeParams: { ok_key: 'x'.repeat(201) } } })).ok,
    ).toBe(false);
    const good = validateGhostManifest(
      oauthManifest({
        oauth: { ...base, extraAuthorizeParams: { access_type: 'offline', prompt: 'consent' } },
      }),
    );
    expect(good.ok).toBe(true);
  });

  it('内置 client 凭证:合法通过并保留;孤儿 secret / 含空白 / 超长拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    const good = validateGhostManifest(
      oauthManifest({ oauth: { ...base, clientId: 'cid-1.apps.example.com', clientSecret: 'GOCSPX-abc' } }),
    );
    expect(good.ok).toBe(true);
    if (good.ok) {
      expect(good.manifest.network?.secrets?.[0]?.oauth?.clientId).toBe('cid-1.apps.example.com');
      expect(good.manifest.network?.secrets?.[0]?.oauth?.clientSecret).toBe('GOCSPX-abc');
    }
    expect(validateGhostManifest(oauthManifest({ oauth: { ...base, clientSecret: 'orphan' } })).ok).toBe(false);
    expect(validateGhostManifest(oauthManifest({ oauth: { ...base, clientId: 'has space' } })).ok).toBe(false);
    expect(validateGhostManifest(oauthManifest({ oauth: { ...base, clientId: 'x'.repeat(201) } })).ok).toBe(false);
  });

  it('identity.labelPath 形状校验(点分路径)', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, identity: { url: 'https://api.example.com/me', labelPath: 'user.email' } } }),
      ).ok,
    ).toBe(true);
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, identity: { url: 'https://api.example.com/me', labelPath: 'a..b' } } }),
      ).ok,
    ).toBe(false);
  });

  it('identity.displayTemplate:占位符校验(至少一个合法点分路径;纯静态 / 坏路径 / 超长 → 拒)', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    const withTemplate = (displayTemplate: unknown): ReturnType<typeof oauthManifest> =>
      oauthManifest({
        oauth: {
          ...base,
          identity: { url: 'https://api.example.com/me', labelPath: 'user_id', displayTemplate },
        },
      });
    const ok = validateGhostManifest(withTemplate('{team} · {user}'));
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.identity?.displayTemplate).toBe('{team} · {user}');
    }
    // 未声明模板 = 归一化后不带该字段(展示回落 labelPath 值)。
    const plain = validateGhostManifest(
      oauthManifest({ oauth: { ...base, identity: { url: 'https://api.example.com/me', labelPath: 'email' } } }),
    );
    expect(plain.ok).toBe(true);
    if (plain.ok) {
      expect(plain.manifest.network?.secrets?.[0]?.oauth?.identity?.displayTemplate).toBeUndefined();
    }
    expect(validateGhostManifest(withTemplate('no placeholder')).ok).toBe(false);
    expect(validateGhostManifest(withTemplate('{a..b}')).ok).toBe(false);
    expect(validateGhostManifest(withTemplate('{}')).ok).toBe(false);
    expect(validateGhostManifest(withTemplate('')).ok).toBe(false);
    expect(validateGhostManifest(withTemplate(42)).ok).toBe(false);
    expect(validateGhostManifest(withTemplate(`{user}${'x'.repeat(200)}`)).ok).toBe(false);
  });

  it('identity.avatarPath:合法点分路径通过并保留;坏路径 / 非字符串 / 超长 → 拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    const withAvatarPath = (avatarPath: unknown): ReturnType<typeof oauthManifest> =>
      oauthManifest({
        oauth: {
          ...base,
          identity: { url: 'https://api.example.com/me', labelPath: 'user_id', avatarPath },
        },
      });
    const ok = validateGhostManifest(withAvatarPath('data.avatar_thumb'));
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.identity?.avatarPath).toBe('data.avatar_thumb');
    }
    // 未声明 = 归一化后不带该字段(账号无头像,设置页回落首字圆片)。
    const plain = validateGhostManifest(
      oauthManifest({ oauth: { ...base, identity: { url: 'https://api.example.com/me', labelPath: 'email' } } }),
    );
    expect(plain.ok).toBe(true);
    if (plain.ok) {
      expect(plain.manifest.network?.secrets?.[0]?.oauth?.identity?.avatarPath).toBeUndefined();
    }
    expect(validateGhostManifest(withAvatarPath('a..b')).ok).toBe(false);
    expect(validateGhostManifest(withAvatarPath(42)).ok).toBe(false);
    expect(validateGhostManifest(withAvatarPath('x'.repeat(129))).ok).toBe(false);
  });

  it('oauth 凭证同样要求 settingsHtml(client 凭证与连接按钮由意识设置页收单)', () => {
    const m = oauthManifest();
    delete m.settingsHtml;
    expect(validateGhostManifest(m).ok).toBe(false);
  });

  it('redirectPort:合法端口通过并保留;越界 / 非整数 → 拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
    };
    const ok = validateGhostManifest(oauthManifest({ oauth: { ...base, redirectPort: 53682 } }));
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.redirectPort).toBe(53682);
    }
    for (const bad of [80, 1023, 65536, 0, -1, 1.5, '53682']) {
      expect(
        validateGhostManifest(oauthManifest({ oauth: { ...base, redirectPort: bad } })).ok,
        `redirectPort=${String(bad)} 应拒`,
      ).toBe(false);
    }
  });

  it('tokenBroker 无 redirectPort 仍可从共用读路径解析;新包约束由 Host 准入点承担', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
      clientId: 'builtin-client-id',
    };
    const missingPort = validateGhostManifest(
      oauthManifest({ oauth: { ...base, tokenBroker: 'jira' } }),
    );
    expect(missingPort.ok).toBe(true);
    if (missingPort.ok) {
      expect(missingPort.manifest.network?.secrets?.[0]?.oauth).toMatchObject({
        tokenBroker: 'jira',
      });
      expect(
        missingPort.manifest.network?.secrets?.[0]?.oauth?.redirectPort,
      ).toBeUndefined();
    }

    // 这两个对照防止兼容调整误伤原本合法的显式端口与普通 OAuth。
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, tokenBroker: 'jira', redirectPort: 17872 } }),
      ).ok,
    ).toBe(true);
    expect(validateGhostManifest(oauthManifest({ oauth: base })).ok).toBe(true);
  });

  it('tokenBroker:合法 slug 通过并保留;非法形状 / 与 clientSecret 互斥 → 拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
      clientId: 'builtin-client-id',
      redirectPort: 17872,
    };
    // broker 模式典型组合:内置 clientId + 无 clientSecret + pkce:false。
    const ok = validateGhostManifest(
      oauthManifest({ oauth: { ...base, tokenBroker: 'jira', pkce: false } }),
    );
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      const oa = ok.manifest.network?.secrets?.[0]?.oauth;
      expect(oa?.tokenBroker).toBe('jira');
      expect(oa?.pkce).toBe(false);
      expect(oa?.clientSecret).toBeUndefined();
    }
    for (const bad of ['Jira', '9jira', 'a'.repeat(33), '', 'jira jira']) {
      expect(
        validateGhostManifest(oauthManifest({ oauth: { ...base, tokenBroker: bad } })).ok,
        `tokenBroker=${JSON.stringify(bad)} 应拒`,
      ).toBe(false);
    }
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, clientSecret: 'sec', tokenBroker: 'jira' } }),
      ).ok,
    ).toBe(false);
  });

  it('clientIdAlternatives:仅 broker + 默认 clientId 可用,合法值保留且重复/非法值拒绝', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
      clientId: 'cn-client-id',
      tokenBroker: 'slack',
      redirectPort: 17872,
    };
    const ok = validateGhostManifest(
      oauthManifest({ oauth: { ...base, clientIdAlternatives: ['global-client-id'] } }),
    );
    expect(ok.ok, ok.ok ? '' : ok.reason).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.clientIdAlternatives).toEqual([
        'global-client-id',
      ]);
    }

    for (const clientIdAlternatives of [
      [],
      ['cn-client-id'],
      ['global-client-id', 'global-client-id'],
      ['has space'],
      ['x'.repeat(201)],
      [42],
      Array.from({ length: GHOST_OAUTH_CLIENT_ID_ALTERNATIVES_MAX + 1 }, (_, i) => `client-${i}`),
    ]) {
      expect(
        validateGhostManifest(oauthManifest({ oauth: { ...base, clientIdAlternatives } })).ok,
        JSON.stringify(clientIdAlternatives),
      ).toBe(false);
    }
    expect(
      validateGhostManifest(
        oauthManifest({
          oauth: {
            ...base,
            clientId: undefined,
            clientIdAlternatives: ['global-client-id'],
          },
        }),
      ).ok,
      '缺默认 clientId 应拒',
    ).toBe(false);
    expect(
      validateGhostManifest(
        oauthManifest({
          oauth: {
            ...base,
            tokenBroker: undefined,
            clientIdAlternatives: ['global-client-id'],
          },
        }),
      ).ok,
      '非 broker 模式应拒',
    ).toBe(false);
  });

  it('brokerBounce:必须与 tokenBroker、redirectPort 成套;路径形状校验;合法归一化保留', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
      clientId: 'builtin-client-id',
      pkce: false,
    };
    const bounce = { path: '/slack-mcp/bounce', callbackPath: '/slack-mcp/callback' };

    // 合法(全套声明)通过并归一化保留。
    const ok = validateGhostManifest(
      oauthManifest({ oauth: { ...base, tokenBroker: 'slack', redirectPort: 17872, brokerBounce: bounce } }),
    );
    expect(ok.ok, ok.ok ? '' : ok.reason).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.brokerBounce).toEqual(bounce);
    }

    // 缺 tokenBroker / 缺 redirectPort → 拒(三者是一套约定)。
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, redirectPort: 17872, brokerBounce: bounce } }),
      ).ok,
      '缺 tokenBroker 应拒',
    ).toBe(false);
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, tokenBroker: 'slack', brokerBounce: bounce } }),
      ).ok,
      '缺 redirectPort 应拒',
    ).toBe(false);

    // 路径形状:不以 / 开头、带 query、含 .. 段、超长、非字符串 → 拒(path 与 callbackPath 同规则)。
    for (const badPath of [
      'slack-mcp/bounce',
      '/bounce?x=1',
      '/a/../b',
      '/',
      `/${'a'.repeat(128)}`,
      42,
    ]) {
      for (const field of ['path', 'callbackPath'] as const) {
        expect(
          validateGhostManifest(
            oauthManifest({
              oauth: {
                ...base,
                tokenBroker: 'slack',
                redirectPort: 17872,
                brokerBounce: { ...bounce, [field]: badPath },
              },
            }),
          ).ok,
          `brokerBounce.${field}=${JSON.stringify(badPath)} 应拒`,
        ).toBe(false);
      }
    }
    // 非对象形态 → 拒。
    expect(
      validateGhostManifest(
        oauthManifest({ oauth: { ...base, tokenBroker: 'slack', redirectPort: 17872, brokerBounce: '/x' } }),
      ).ok,
    ).toBe(false);
  });

  it('scopeDelimiter:"," 通过并保留;其它值(";" / 空格 / 空串)→ 拒', () => {
    const base = {
      authorizeUrl: 'https://accounts.example.com/authorize',
      tokenUrl: 'https://accounts.example.com/token',
      scopes: ['read.a', 'write.b'],
    };
    const ok = validateGhostManifest(oauthManifest({ oauth: { ...base, scopeDelimiter: ',' } }));
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.network?.secrets?.[0]?.oauth?.scopeDelimiter).toBe(',');
    }
    for (const bad of [';', ' ', '', ', ']) {
      expect(
        validateGhostManifest(oauthManifest({ oauth: { ...base, scopeDelimiter: bad } })).ok,
        `scopeDelimiter=${JSON.stringify(bad)} 应拒`,
      ).toBe(false);
    }
  });
});
describe('ghost · oauth 确认框条目', () => {
  it('展示授权域名 + scopes 原文逐条', () => {
    const result = validateGhostManifest(oauthManifest());
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    const items = ghostPermissionItems(result.manifest as GhostManifest);
    const oauthItem = items.find((i) => i.key === 'network:secret:acct');
    expect(oauthItem).toBeDefined();
    expect(oauthItem).toMatchObject({
      kind: 'network',
      labelKey: 'networkSecretOauth',
      labelArgs: { name: 'Example 账号', host: 'accounts.example.com' },
      detailKey: 'networkSecretOauthDetail',
    });
    expect(oauthItem?.detail).toBe('read.a\nwrite.b');
  });

  it('无 scopes 时不带 detail(不渲染空段)', () => {
    const result = validateGhostManifest(
      oauthManifest({
        oauth: {
          authorizeUrl: 'https://accounts.example.com/authorize',
          tokenUrl: 'https://accounts.example.com/token',
        },
      }),
    );
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    const item = ghostPermissionItems(result.manifest as GhostManifest).find(
      (i) => i.key === 'network:secret:acct',
    );
    expect(item?.detail).toBeUndefined();
  });
});