m365-agent-cli 1.2.0

package/src/lib/graph-constants.ts

@@ -0,0 +1,12 @@
+import { validateUrl } from './url-validation';
+
+export const GRAPH_BASE_URL = validateUrl(
+  process.env.GRAPH_BASE_URL || 'https://graph.microsoft.com/v1.0',
+  'GRAPH_BASE_URL'
+);
+
+/** Microsoft Graph beta root (Planner favorites, roster, delta — subject to change). */
+export const GRAPH_BETA_URL = validateUrl(
+  process.env.GRAPH_BETA_URL || 'https://graph.microsoft.com/beta',
+  'GRAPH_BETA_URL'
+);

package/src/lib/graph-directory.ts

@@ -0,0 +1,116 @@
+import { callGraph, fetchAllPages, GraphApiError, type GraphResponse, graphError } from './graph-client.js';
+
+export interface Person {
+  id: string;
+  displayName: string;
+  givenName?: string;
+  surname?: string;
+  jobTitle?: string;
+  scoredEmailAddresses?: { address: string; name?: string }[];
+  userPrincipalName?: string;
+  department?: string;
+}
+
+export interface User {
+  id: string;
+  displayName: string;
+  givenName?: string;
+  surname?: string;
+  jobTitle?: string;
+  mail?: string;
+  userPrincipalName?: string;
+  department?: string;
+}
+
+export interface Group {
+  id: string;
+  displayName: string;
+  description?: string;
+  mail?: string;
+  groupTypes?: string[];
+}
+
+export async function searchPeople(token: string, query: string): Promise<GraphResponse<Person[]>> {
+  const escapedQuery = query.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const searchParam = encodeURIComponent(`"${escapedQuery}"`);
+  let result: GraphResponse<{ value: Person[] }>;
+  try {
+    result = await callGraph<{ value: Person[] }>(token, `/me/people?$search=${searchParam}`);
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to search people');
+  }
+  if (!result.ok || !result.data) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: true, data: result.data.value };
+}
+
+export async function searchUsers(token: string, query: string): Promise<GraphResponse<User[]>> {
+  const escapedQuery = query.replace(/'/g, "''");
+  const filter = encodeURIComponent(`startswith(displayName,'${escapedQuery}')`);
+  let result: GraphResponse<{ value: User[] }>;
+  try {
+    result = await callGraph<{ value: User[] }>(token, `/users?$filter=${filter}&$count=true`, {
+      headers: {
+        ConsistencyLevel: 'eventual'
+      }
+    });
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to search users');
+  }
+  if (!result.ok || !result.data) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: true, data: result.data.value };
+}
+
+export async function searchGroups(token: string, query: string): Promise<GraphResponse<Group[]>> {
+  const escapedQuery = query.replace(/'/g, "''");
+  const filter = encodeURIComponent(`startswith(displayName,'${escapedQuery}')`);
+  let result: GraphResponse<{ value: Group[] }>;
+  try {
+    result = await callGraph<{ value: Group[] }>(token, `/groups?$filter=${filter}&$count=true`, {
+      headers: {
+        ConsistencyLevel: 'eventual'
+      }
+    });
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to search groups');
+  }
+  if (!result.ok || !result.data) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: true, data: result.data.value };
+}
+
+export async function expandGroup(token: string, groupId: string): Promise<GraphResponse<User[]>> {
+  const result = await fetchAllPages<any>(
+    token,
+    `/groups/${encodeURIComponent(groupId)}/members?$top=100`,
+    'Failed to expand group'
+  );
+
+  if (!result.ok || !result.data) {
+    return { ok: false, error: result.error };
+  }
+
+  const userMembers = result.data.filter((member: any) => {
+    const odataType = member['@odata.type'];
+    return (
+      (typeof odataType === 'string' && odataType.toLowerCase().endsWith('.user')) ||
+      typeof member.mail === 'string' ||
+      typeof member.userPrincipalName === 'string'
+    );
+  }) as User[];
+
+  return { ok: true, data: userMembers };
+}

package/src/lib/graph-event.ts

@@ -0,0 +1,134 @@
+import { callGraph, GraphApiError, type GraphResponse, graphError } from './graph-client.js';
+import { graphUserPath } from './graph-user-path.js';
+
+export interface ForwardEventOptions {
+  token: string;
+  eventId: string;
+  toRecipients: string[];
+  comment?: string;
+  /** User UPN or id for delegated calendar (omit for /me) */
+  user?: string;
+}
+
+export async function forwardEvent(options: ForwardEventOptions): Promise<GraphResponse<void>> {
+  const { token, eventId, toRecipients, comment, user } = options;
+
+  const recipientsList = toRecipients.map((email) => ({
+    emailAddress: { address: email }
+  }));
+
+  const body: { toRecipients: { emailAddress: { address: string } }[]; comment?: string } = {
+    toRecipients: recipientsList
+  };
+
+  if (comment) {
+    body.comment = comment;
+  }
+
+  try {
+    return await callGraph<void>(
+      token,
+      `${graphUserPath(user, `events/${encodeURIComponent(eventId)}/forward`)}`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body)
+      },
+      false
+    );
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to forward event');
+  }
+}
+
+export interface ProposeNewTimeOptions {
+  token: string;
+  eventId: string;
+  startDateTime: string;
+  endDateTime: string;
+  timeZone?: string;
+  user?: string;
+}
+
+export async function proposeNewTime(options: ProposeNewTimeOptions): Promise<GraphResponse<void>> {
+  const { token, eventId, startDateTime, endDateTime, timeZone = 'UTC', user } = options;
+
+  const body = {
+    proposedNewTime: {
+      start: { dateTime: startDateTime, timeZone },
+      end: { dateTime: endDateTime, timeZone }
+    },
+    sendResponse: true
+  };
+
+  try {
+    return await callGraph<void>(
+      token,
+      `${graphUserPath(user, `events/${encodeURIComponent(eventId)}/tentativelyAccept`)}`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body)
+      },
+      false
+    );
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to propose new time');
+  }
+}
+
+export interface EventInvitationResponseOptions {
+  token: string;
+  eventId: string;
+  comment?: string;
+  /** Default true (send response to organizer). */
+  sendResponse?: boolean;
+  user?: string;
+}
+
+export async function acceptEventInvitation(options: EventInvitationResponseOptions): Promise<GraphResponse<void>> {
+  return postEventAction(options, 'accept');
+}
+
+export async function declineEventInvitation(options: EventInvitationResponseOptions): Promise<GraphResponse<void>> {
+  return postEventAction(options, 'decline');
+}
+
+/** Tentatively accept without proposing a new time (Graph POST .../tentativelyAccept). */
+export async function tentativelyAcceptEventInvitation(
+  options: EventInvitationResponseOptions
+): Promise<GraphResponse<void>> {
+  return postEventAction(options, 'tentativelyAccept');
+}
+
+async function postEventAction(
+  options: EventInvitationResponseOptions,
+  action: 'accept' | 'decline' | 'tentativelyAccept'
+): Promise<GraphResponse<void>> {
+  const { token, eventId, comment, user } = options;
+  const sendResponse = options.sendResponse !== false;
+
+  const body: { comment?: string; sendResponse: boolean } = { sendResponse };
+  if (comment) body.comment = comment;
+
+  try {
+    return await callGraph<void>(
+      token,
+      `${graphUserPath(user, `events/${encodeURIComponent(eventId)}/${action}`)}`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body)
+      },
+      false
+    );
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to respond to event');
+  }
+}

package/src/lib/graph-schedule.ts

@@ -0,0 +1,173 @@
+import { callGraph, GraphApiError, type GraphResponse, graphError, graphResult } from './graph-client.js';
+import { graphUserPath } from './graph-user-path.js';
+
+export interface GetScheduleRequest {
+  schedules: string[];
+  startTime: {
+    dateTime: string;
+    timeZone: string;
+  };
+  endTime: {
+    dateTime: string;
+    timeZone: string;
+  };
+  availabilityViewInterval?: number;
+}
+
+export interface ScheduleInformation {
+  scheduleId: string;
+  availabilityView?: string;
+  scheduleItems?: Array<{
+    isPrivate?: boolean;
+    status?: string;
+    subject?: string;
+    location?: string;
+    isMeeting?: boolean;
+    isRecurring?: boolean;
+    isException?: boolean;
+    isReminderSet?: boolean;
+    start?: {
+      dateTime: string;
+      timeZone: string;
+    };
+    end?: {
+      dateTime: string;
+      timeZone: string;
+    };
+  }>;
+  workingHours?: {
+    daysOfWeek?: string[];
+    startTime?: string;
+    endTime?: string;
+    timeZone?: {
+      name?: string;
+    };
+  };
+  error?: {
+    message?: string;
+    responseCode?: string;
+  };
+}
+
+export interface GetScheduleResponse {
+  value: ScheduleInformation[];
+}
+
+export async function getSchedule(
+  token: string,
+  request: GetScheduleRequest,
+  user?: string
+): Promise<GraphResponse<GetScheduleResponse>> {
+  let result: GraphResponse<GetScheduleResponse>;
+  try {
+    result = await callGraph<GetScheduleResponse>(token, graphUserPath(user, 'calendar/getSchedule'), {
+      method: 'POST',
+      body: JSON.stringify(request),
+      headers: {
+        Prefer: 'outlook.timezone="UTC"'
+      }
+    });
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to get schedule');
+  }
+
+  if (!result.ok || !result.data) {
+    return graphError(result.error?.message || 'Failed to get schedule', result.error?.code, result.error?.status);
+  }
+  return graphResult(result.data);
+}
+
+export interface AttendeeBase {
+  type: 'required' | 'optional' | 'resource';
+  emailAddress: {
+    address: string;
+    name?: string;
+  };
+}
+
+export interface TimeConstraint {
+  activityDomain?: 'work' | 'personal' | 'unrestricted' | 'unknown';
+  timeSlots: Array<{
+    start: {
+      dateTime: string;
+      timeZone: string;
+    };
+    end: {
+      dateTime: string;
+      timeZone: string;
+    };
+  }>;
+}
+
+export interface FindMeetingTimesRequest {
+  attendees?: AttendeeBase[];
+  locationConstraint?: {
+    isRequired?: boolean;
+    suggestLocation?: boolean;
+    locations?: Array<{
+      resolveAvailability?: boolean;
+      displayName?: string;
+      locationEmailAddress?: string;
+    }>;
+  };
+  timeConstraint?: TimeConstraint;
+  meetingDuration?: string; // e.g. "PT30M"
+  returnSuggestionReasons?: boolean;
+  minimumAttendeePercentage?: number;
+  isOrganizerOptional?: boolean;
+  maxCandidates?: number;
+}
+
+export interface MeetingTimeSuggestion {
+  meetingTimeSlot?: {
+    start?: { dateTime: string; timeZone: string };
+    end?: { dateTime: string; timeZone: string };
+  };
+  confidence?: number;
+  organizerAvailability?: string;
+  attendeeAvailability?: Array<{
+    availability?: string;
+    attendee?: AttendeeBase;
+  }>;
+  locations?: Array<{ displayName?: string; locationEmailAddress?: string }>;
+  suggestionReason?: string;
+}
+
+export interface FindMeetingTimesResponse {
+  emptySuggestionsReason?: string;
+  meetingTimeSuggestions?: MeetingTimeSuggestion[];
+}
+
+export async function findMeetingTimes(
+  token: string,
+  request: FindMeetingTimesRequest,
+  user?: string
+): Promise<GraphResponse<FindMeetingTimesResponse>> {
+  let result: GraphResponse<FindMeetingTimesResponse>;
+  try {
+    result = await callGraph<FindMeetingTimesResponse>(token, graphUserPath(user, 'findMeetingTimes'), {
+      method: 'POST',
+      body: JSON.stringify(request),
+      headers: {
+        Prefer: 'outlook.timezone="UTC"'
+      }
+    });
+  } catch (err) {
+    if (err instanceof GraphApiError) {
+      return graphError(err.message, err.code, err.status);
+    }
+    return graphError(err instanceof Error ? err.message : 'Failed to find meeting times');
+  }
+
+  if (!result.ok || !result.data) {
+    return graphError(
+      result.error?.message || 'Failed to find meeting times',
+      result.error?.code,
+      result.error?.status
+    );
+  }
+  return graphResult(result.data);
+}

package/src/lib/graph-subscriptions.ts

@@ -0,0 +1,94 @@
+import { resolveGraphAuth } from './graph-auth.js';
+import { callGraph, type GraphResponse, graphError } from './graph-client.js';
+
+export interface Subscription {
+  id: string;
+  resource: string;
+  applicationId?: string;
+  changeType: string;
+  clientState?: string;
+  notificationUrl: string;
+  expirationDateTime: string;
+  creatorId?: string;
+}
+
+async function getAuthToken(token?: string, identity?: string): Promise<string> {
+  const auth = await resolveGraphAuth({ token, identity });
+  if (!auth.success || !auth.token) {
+    throw new Error(auth.error || 'Failed to authenticate to Graph API');
+  }
+  return auth.token;
+}
+
+export async function createSubscription(
+  resource: string,
+  changeType: string,
+  notificationUrl: string,
+  expirationDateTime: string,
+  clientState?: string,
+  token?: string,
+  identity?: string
+): Promise<GraphResponse<Subscription>> {
+  try {
+    const authToken = await getAuthToken(token, identity);
+    const body: Record<string, string> = {
+      changeType,
+      notificationUrl,
+      resource,
+      expirationDateTime
+    };
+    if (clientState) {
+      body.clientState = clientState;
+    }
+
+    return await callGraph<Subscription>(authToken, '/subscriptions', {
+      method: 'POST',
+      body: JSON.stringify(body)
+    });
+  } catch (err: any) {
+    return graphError(err.message, err.code, err.status);
+  }
+}
+
+export async function listSubscriptions(token?: string, identity?: string): Promise<GraphResponse<Subscription[]>> {
+  try {
+    const authToken = await getAuthToken(token, identity);
+    const res = await callGraph<{ value: Subscription[] }>(authToken, '/subscriptions', {
+      method: 'GET'
+    });
+    if (!res.ok) return res as unknown as GraphResponse<Subscription[]>;
+    return { ok: true, data: res.data!.value };
+  } catch (err: any) {
+    return graphError(err.message, err.code, err.status);
+  }
+}
+
+export async function deleteSubscription(id: string, token?: string, identity?: string): Promise<GraphResponse<void>> {
+  try {
+    const authToken = await getAuthToken(token, identity);
+    return await callGraph<void>(authToken, `/subscriptions/${encodeURIComponent(id)}`, {
+      method: 'DELETE'
+    });
+  } catch (err: any) {
+    return graphError(err.message, err.code, err.status);
+  }
+}
+
+export async function renewSubscription(
+  id: string,
+  expirationDateTime: string,
+  token?: string,
+  identity?: string
+): Promise<GraphResponse<void>> {
+  try {
+    const authToken = await getAuthToken(token, identity);
+    return await callGraph<void>(authToken, `/subscriptions/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: JSON.stringify({
+        expirationDateTime
+      })
+    });
+  } catch (err: any) {
+    return graphError(err.message, err.code, err.status);
+  }
+}

package/src/lib/graph-user-path.ts

@@ -0,0 +1,13 @@
+/**
+ * Build `/me/...` or `/users/{upnOrId}/...` paths for Microsoft Graph delegation.
+ *
+ * @param user - User UPN, SMTP address, or object ID. Omit or empty for `/me`.
+ * @param suffix - Path after `me` or `users/{id}` (no leading slash), e.g. `mailboxSettings`, `calendar/getSchedule`.
+ */
+export function graphUserPath(user: string | undefined, suffix: string): string {
+  const s = suffix.replace(/^\//, '');
+  if (!user?.trim()) {
+    return `/me/${s}`;
+  }
+  return `/users/${encodeURIComponent(user.trim())}/${s}`;
+}

package/src/lib/jwt-utils.ts

@@ -0,0 +1,34 @@
+const VALID_TENANT_ID =
+  /^(?:common|organizations|consumers|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+)$/;
+
+export function getMicrosoftTenantPathSegment(): string {
+  const rawTenant = process.env.EWS_TENANT_ID?.trim() || 'common';
+  if (!VALID_TENANT_ID.test(rawTenant)) {
+    throw new Error(
+      'Invalid EWS_TENANT_ID. Use common/organizations/consumers, a valid tenant UUID, or a domain name.'
+    );
+  }
+  return rawTenant;
+}
+
+export function getJwtExpiration(token: string): number | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return payload.exp ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isValidJwtStructure(token: string): boolean {
+  const parts = token.split('.');
+  if (parts.length !== 3) return false;
+  try {
+    Buffer.from(parts[1], 'base64url').toString();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/markdown.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test';
+import { markdownToHtml } from './markdown.js';
+
+describe('markdownToHtml', () => {
+  it('sanitizes javascript urls in markdown links', () => {
+    const html = markdownToHtml('[click](javascript:alert(1))');
+    expect(html).toContain('<a href="#">click</a>');
+    expect(html).not.toContain('javascript:');
+  });
+
+  it('sanitizes obfuscated javascript urls in markdown links', () => {
+    const html = markdownToHtml('[click](java\nscript:alert(1))');
+    expect(html).toContain('<a href="#">click</a>');
+    expect(html).not.toContain('javascript:');
+  });
+
+  it('escapes html in link labels and urls', () => {
+    const html = markdownToHtml('[<b>hi</b>](https://example.com?q=%3Cscript%3E)');
+    expect(html).toContain('<a href="https://example.com?q=%3Cscript%3E">&lt;b&gt;hi&lt;/b&gt;</a>');
+  });
+});