msteams-mcp 0.27.2 → 0.28.0

package/dist/api/assignments-api.test.js

@@ -0,0 +1,302 @@
+/**
+ * Unit tests for the EDU Assignments API client.
+ *
+ * Mocks the HTTP layer and the auth guard so we exercise the real URL/filter
+ * building and response parsing without a live session.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { httpRequest } from '../utils/http.js';
+import { requireAssignmentsTokenAsync } from '../utils/auth-guards.js';
+import { ok, err } from '../types/result.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { invalidateAccessToken } from '../auth/token-extractor.js';
+import { listMyAssignments, getAssignment, actOnSubmission } from './assignments-api.js';
+vi.mock('../utils/http.js', () => ({ httpRequest: vi.fn() }));
+vi.mock('../utils/auth-guards.js', () => ({
+    requireAssignmentsTokenAsync: vi.fn(),
+}));
+vi.mock('../auth/token-extractor.js', () => ({ invalidateAccessToken: vi.fn() }));
+const mockHttp = vi.mocked(httpRequest);
+const mockToken = vi.mocked(requireAssignmentsTokenAsync);
+function httpOk(data) {
+    return ok({ status: 200, headers: new Headers(), data });
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockToken.mockResolvedValue(ok('fake-token'));
+});
+describe('listMyAssignments', () => {
+    it('parses assignments and the caller submission with a merged grade outcome', async () => {
+        mockHttp.mockResolvedValue(httpOk({
+            value: [
+                {
+                    id: 'a1',
+                    classId: 'c1',
+                    displayName: 'Causes of climate change',
+                    status: 'assigned',
+                    dueDateTime: '2026-09-23T23:59:59Z',
+                    allowLateSubmissions: true,
+                    grading: { maxPoints: 5 },
+                    instructions: { content: '<p>Read chapter 3</p>' },
+                    webUrl: 'https://teams.microsoft.com/l/...',
+                    submissions: [
+                        {
+                            id: 's1',
+                            status: 'returned',
+                            submittedDateTime: '2026-09-22T10:00:00Z',
+                            returnedDateTime: '2026-09-24T09:00:00Z',
+                            outcomes: [
+                                { '@odata.type': '#...educationPointsOutcome', points: { points: 4 }, publishedPoints: { points: 4 } },
+                                { '@odata.type': '#...educationFeedbackOutcome', feedback: { text: { content: 'Good work' } } },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        }));
+        const result = await listMyAssignments();
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.value.returned).toBe(1);
+        const a = result.value.assignments[0];
+        expect(a).toMatchObject({
+            id: 'a1',
+            classId: 'c1',
+            displayName: 'Causes of climate change',
+            maxPoints: 5,
+            instructions: '<p>Read chapter 3</p>',
+        });
+        expect(a.submission).toMatchObject({
+            id: 's1',
+            status: 'returned',
+            outcome: { points: 4, publishedPoints: 4, feedback: 'Good work' },
+        });
+    });
+    it("builds the 'active' filter and default query params by default", async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [] }));
+        await listMyAssignments();
+        const url = mockHttp.mock.calls[0][0];
+        const qs = new URL(url).searchParams;
+        expect(qs.get('$filter')).toBe("status eq microsoft.education.assignments.api.educationAssignmentStatus'assigned' and isCompleted eq false");
+        expect(qs.get('$top')).toBe('25');
+        expect(qs.get('$orderby')).toBe('dueDateTime asc,createdDateTime asc');
+        expect(qs.get('$expand')).toBe('submissions($expand=outcomes)');
+    });
+    it("omits the filter for statusFilter 'all' and honours top", async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [] }));
+        await listMyAssignments({ statusFilter: 'all', top: 10 });
+        const qs = new URL(mockHttp.mock.calls[0][0]).searchParams;
+        expect(qs.has('$filter')).toBe(false);
+        expect(qs.get('$top')).toBe('10');
+    });
+    it("builds the 'completed' filter", async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [] }));
+        await listMyAssignments({ statusFilter: 'completed' });
+        const qs = new URL(mockHttp.mock.calls[0][0]).searchParams;
+        expect(qs.get('$filter')).toBe('isCompleted eq true');
+    });
+    it('handles assignments with no submissions or outcomes', async () => {
+        mockHttp.mockResolvedValue(httpOk({
+            value: [{ id: 'a1', classId: 'c1', displayName: 'No submission yet' }],
+        }));
+        const result = await listMyAssignments();
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.value.assignments[0].submission).toBeUndefined();
+        expect(result.value.assignments[0].maxPoints).toBeUndefined();
+    });
+    it('propagates an auth error from the token guard without calling http', async () => {
+        mockToken.mockResolvedValue(err(createError(ErrorCode.AUTH_REQUIRED, 'no token')));
+        const result = await listMyAssignments();
+        expect(result.ok).toBe(false);
+        expect(mockHttp).not.toHaveBeenCalled();
+    });
+});
+describe('getAssignment', () => {
+    it('reads grades from the submissions collection, not the assignment expand', async () => {
+        mockHttp.mockImplementation(async (url) => String(url).includes('/submissions')
+            ? httpOk({ value: [{ id: 's1', status: 'returned', outcomes: [
+                            { '@odata.type': '#microsoft.education.assignments.api.educationPointsOutcome', points: { points: 8 } },
+                        ] }] })
+            : httpOk({ id: 'a1', classId: 'c1', displayName: 'Detail', submissions: [{ id: 's1', status: 'returned', outcomes: [] }] }));
+        const result = await getAssignment('c1', 'a1');
+        expect(result).toMatchObject({ ok: true, value: { submission: { id: 's1', status: 'returned', outcome: { points: 8 } } } });
+        const urls = mockHttp.mock.calls.map(call => new URL(call[0]));
+        expect(urls.map(u => u.pathname)).toEqual([
+            '/api/v1.0/edu/classes/c1/assignments/a1',
+            '/api/v1.0/edu/classes/c1/assignments/a1/submissions',
+        ]);
+        expect(urls[1].searchParams.get('$expand')).toBe('outcomes,resources,submittedResources');
+    });
+    it('returns teacher attachments and the student\'s own files', async () => {
+        const file = (type, name, id) => ({
+            id: `r-${id}`, resource: { '@odata.type': `#microsoft.education.assignments.api.education${type}Resource`, displayName: name,
+                fileUrl: `https://graph.microsoft.com/v1.0/drives/b!d/items/${id}` }
+        });
+        mockHttp.mockImplementation(async (url) => String(url).includes('/submissions')
+            ? httpOk({ value: [{ id: 's1', status: 'working', resources: [file('Word', 'My copy.docx', 'mine')], submittedResources: [] }] })
+            : httpOk({ id: 'a1', classId: 'c1', displayName: 'Detail', resources: [
+                    { ...file('PowerPoint', 'Lesson.pptx', 'ppt'), distributeForStudentWork: false },
+                    { ...file('Word', 'Worksheet.docx', 'doc'), distributeForStudentWork: true },
+                    { id: 'r-form', resource: { '@odata.type': '#microsoft.education.assignments.api.educationFormResource', displayName: 'Quiz', viewUrl: 'https://forms.office.com/x' } },
+                ] }));
+        const result = await getAssignment('c1', 'a1');
+        expect(result).toMatchObject({ ok: true, value: {
+                attachments: [
+                    { id: 'r-ppt', name: 'Lesson.pptx', type: 'powerpoint', fileUrl: 'https://graph.microsoft.com/v1.0/drives/b!d/items/ppt' },
+                    { name: 'Worksheet.docx', type: 'word', copiedForEachStudent: true },
+                    { name: 'Quiz', type: 'form', url: 'https://forms.office.com/x', fileUrl: undefined },
+                ],
+                submission: { attachments: [{ name: 'My copy.docx', type: 'word', fileUrl: 'https://graph.microsoft.com/v1.0/drives/b!d/items/mine' }], submittedAttachments: [] },
+            } });
+        const urls = mockHttp.mock.calls.map(call => new URL(call[0]));
+        expect(urls[0].searchParams.get('$expand')).toBe('resources');
+        expect(urls[1].searchParams.get('$expand')).toBe('outcomes,resources,submittedResources');
+    });
+    it('fails rather than hiding the submission when it cannot be read', async () => {
+        mockHttp.mockImplementation(async (url) => String(url).includes('/submissions')
+            ? err(createError(ErrorCode.API_ERROR, 'HTTP 500'))
+            : httpOk({ id: 'a1', classId: 'c1', displayName: 'Detail' }));
+        expect(await getAssignment('c1', 'a1')).toMatchObject({ ok: false, error: { code: ErrorCode.API_ERROR } });
+    });
+});
+describe('actOnSubmission', () => {
+    it('POSTs to the submit endpoint for submit', async () => {
+        mockHttp.mockResolvedValue(httpOk({ id: 's1', status: 'submitted' }));
+        const result = await actOnSubmission('submit', 'c1', 'a1', 's1');
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.value).toMatchObject({ action: 'submit', submissionId: 's1', status: 'submitted' });
+        const [url, opts] = mockHttp.mock.calls[0];
+        expect(url).toContain('/submissions/s1/submit');
+        expect(opts.method).toBe('POST');
+    });
+    it('POSTs to the unsubmit endpoint for unsubmit', async () => {
+        mockHttp.mockResolvedValue(httpOk({ id: 's1', status: 'working' }));
+        await actOnSubmission('unsubmit', 'c1', 'a1', 's1');
+        const [url, opts] = mockHttp.mock.calls[0];
+        expect(url).toContain('/submissions/s1/unsubmit');
+        expect(opts.method).toBe('POST');
+    });
+    it('PATCHes the view endpoint for view', async () => {
+        mockHttp.mockResolvedValue(httpOk({ id: 's1', status: 'working' }));
+        await actOnSubmission('view', 'c1', 'a1', 's1');
+        const [url, opts] = mockHttp.mock.calls[0];
+        expect(url).toContain('/submissions/s1/view');
+        expect(opts.method).toBe('PATCH');
+    });
+});
+describe('Assignments regression cases', () => {
+    it('exposes and follows server pagination without rebuilding its cursor', async () => {
+        const nextLink = 'https://assignments.edu.cloud.microsoft/api/v1.0/edu/me/work?$skiptoken=opaque&$top=25';
+        mockHttp.mockResolvedValueOnce(httpOk({ value: [{ id: 'a1' }], '@odata.nextLink': nextLink }));
+        const first = await listMyAssignments();
+        expect(first).toMatchObject({ ok: true, value: { nextLink: new URL(nextLink).toString() } });
+        mockHttp.mockResolvedValueOnce(httpOk({ value: [{ id: 'a2' }] }));
+        expect(await listMyAssignments({ nextLink })).toMatchObject({ ok: true, value: { assignments: [{ id: 'a2' }] } });
+        expect(mockHttp.mock.calls[1][0]).toBe(new URL(nextLink).toString());
+    });
+    it('offers an offset continuation for a full page without nextLink', async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [{ id: 'a1' }] }));
+        const result = await listMyAssignments({ top: 1 });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(new URL(result.value.nextLink).searchParams.get('$skip')).toBe('1');
+    });
+    it('stops instead of looping when the service ignores a synthesised $skip', async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [{ id: 'a1' }] }));
+        const first = await listMyAssignments({ top: 1 });
+        if (!first.ok)
+            throw new Error('expected first page');
+        expect(await listMyAssignments({ nextLink: first.value.nextLink })).toMatchObject({
+            ok: false, error: { code: ErrorCode.API_ERROR, retryable: false },
+        });
+    });
+    it('keeps offering offset pages while $skip advances the results', async () => {
+        mockHttp.mockResolvedValueOnce(httpOk({ value: [{ id: 'a1' }] }));
+        const first = await listMyAssignments({ top: 1 });
+        if (!first.ok)
+            throw new Error('expected first page');
+        mockHttp.mockResolvedValueOnce(httpOk({ value: [{ id: 'a2' }] }));
+        const second = await listMyAssignments({ nextLink: first.value.nextLink });
+        expect(second).toMatchObject({ ok: true, value: { assignments: [{ id: 'a2' }] } });
+        if (second.ok)
+            expect(new URL(second.value.nextLink).searchParams.get('$skip')).toBe('2');
+    });
+    it('reports the status slice the continuation actually queries', async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [] }));
+        const first = await listMyAssignments({ statusFilter: 'completed', top: 1 });
+        const link = new URL(mockHttp.mock.calls[0][0]);
+        link.searchParams.set('$skiptoken', 'opaque');
+        expect(first).toMatchObject({ ok: true, value: { statusFilter: 'completed' } });
+        expect(await listMyAssignments({ statusFilter: 'active', nextLink: link.toString() }))
+            .toMatchObject({ ok: true, value: { statusFilter: 'completed' } });
+    });
+    it.each([
+        'https://evil.example/api/v1.0/edu/me/work',
+        'https://assignments.edu.cloud.microsoft/api/v1.0/edu/classes/c1',
+        'https://assignments.edu.cloud.microsoft/api/v1.0/edu/me/work?$top=2.5',
+    ])('rejects unsafe continuations: %s', async (nextLink) => {
+        expect(await listMyAssignments({ nextLink })).toMatchObject({ ok: false, error: { code: ErrorCode.INVALID_INPUT } });
+        expect(mockHttp).not.toHaveBeenCalled();
+        expect(mockToken).not.toHaveBeenCalled();
+    });
+    it.each(['../other', 's1?x=y', '.', '%2e%2e', 's1#fragment'])('rejects malformed IDs: %s', async (id) => {
+        expect(await actOnSubmission('submit', 'c1', 'a1', id)).toMatchObject({ ok: false, error: { code: ErrorCode.INVALID_INPUT } });
+        expect(await getAssignment(id, 'a1')).toMatchObject({ ok: false });
+        expect(mockHttp).not.toHaveBeenCalled();
+    });
+    it('rejects fractional page sizes before auth or HTTP', async () => {
+        expect(await listMyAssignments({ top: 2.5 })).toMatchObject({ ok: false, error: { code: ErrorCode.INVALID_INPUT } });
+        expect(mockToken).not.toHaveBeenCalled();
+    });
+    it('invalidates a rejected token on a 401 without triggering Teams re-login', async () => {
+        mockHttp.mockResolvedValue(err(createError(ErrorCode.AUTH_EXPIRED, 'HTTP 401')));
+        expect(await listMyAssignments()).toMatchObject({ ok: false, error: { code: ErrorCode.API_ERROR, retryable: true } });
+        expect(invalidateAccessToken).toHaveBeenCalledWith('fake-token');
+    });
+    it('does not trigger login for permission failures', async () => {
+        mockHttp.mockResolvedValue(err(createError(ErrorCode.AUTH_REQUIRED, 'HTTP 403')));
+        expect(await listMyAssignments()).toMatchObject({ ok: false, error: { code: ErrorCode.ACCESS_DENIED, retryable: false } });
+        expect(invalidateAccessToken).not.toHaveBeenCalled();
+    });
+    it('verifies turn-in with a separate GET and never replays the POST', async () => {
+        mockHttp.mockResolvedValueOnce(httpOk('')).mockResolvedValueOnce(httpOk({ id: 's1', status: 'submitted' }));
+        expect(await actOnSubmission('submit', 'c1', 'a1', 's1')).toMatchObject({ ok: true, value: { status: 'submitted' } });
+        expect(mockHttp.mock.calls[0][1]).toMatchObject({ method: 'POST', maxRetries: 1 });
+        expect(mockHttp.mock.calls[1][0]).toMatch(/\/submissions\/s1$/);
+        expect(mockHttp.mock.calls[1][1]).toMatchObject({ method: 'GET' });
+    });
+    it.each(['<html>Login</html>', { id: 's1', status: 'working' }, { id: 'other', status: 'submitted' }])('does not report unconfirmed turn-in as success', async (data) => {
+        mockHttp.mockResolvedValueOnce(httpOk({ id: 's1', status: 'submitted' })).mockResolvedValueOnce(httpOk(data));
+        expect(await actOnSubmission('submit', 'c1', 'a1', 's1')).toMatchObject({ ok: false, error: { code: ErrorCode.API_ERROR, retryable: false } });
+    });
+    it('does not trigger automatic mutation replay if verification needs authentication', async () => {
+        mockHttp.mockResolvedValueOnce(httpOk({ id: 's1', status: 'submitted' }))
+            .mockResolvedValueOnce(err(createError(ErrorCode.AUTH_EXPIRED, 'HTTP 401')));
+        expect(await actOnSubmission('submit', 'c1', 'a1', 's1')).toMatchObject({ ok: false, error: { code: ErrorCode.API_ERROR, retryable: false } });
+        expect(invalidateAccessToken).toHaveBeenCalledWith('fake-token');
+    });
+    it('does not report an HTML view response as success', async () => {
+        mockHttp.mockResolvedValue(httpOk('<html>Login</html>'));
+        expect(await actOnSubmission('view', 'c1', 'a1', 's1')).toMatchObject({ ok: false });
+    });
+    it('does not surface a 401 on a mutation as an auth error the server would replay', async () => {
+        mockHttp.mockResolvedValue(err(createError(ErrorCode.AUTH_EXPIRED, 'HTTP 401')));
+        expect(await actOnSubmission('submit', 'c1', 'a1', 's1')).toMatchObject({ ok: false, error: { code: ErrorCode.API_ERROR } });
+        expect(mockHttp).toHaveBeenCalledTimes(1);
+    });
+    it('marks a timed-out mutation as uncertain rather than inviting a retry', async () => {
+        mockHttp.mockResolvedValue(err(createError(ErrorCode.TIMEOUT, 'Timed out', { retryable: true })));
+        expect(await actOnSubmission('submit', 'c1', 'a1', 's1')).toMatchObject({ ok: false, error: { code: ErrorCode.TIMEOUT, retryable: false } });
+        expect(mockHttp).toHaveBeenCalledTimes(1);
+    });
+    it('does not invent another cursor page after the server ends pagination', async () => {
+        mockHttp.mockResolvedValue(httpOk({ value: [{ id: 'a1' }] }));
+        const result = await listMyAssignments({ nextLink: 'https://assignments.edu.cloud.microsoft/api/v1.0/edu/me/work?$skiptoken=last&$top=1' });
+        expect(result).toMatchObject({ ok: true, value: { nextLink: undefined } });
+    });
+});

package/dist/api/csa-api.js

@@ -20,8 +20,8 @@ export async function getFavorites() {
         return authResult;
     }
     const { auth, csaToken } = authResult.value;
-    const { region, baseUrl } = getApiConfig();
-    const url = CSA_API.conversationFolders(region, baseUrl);
+    const { csaRegion, baseUrl } = getApiConfig();
+    const url = CSA_API.conversationFolders(csaRegion, baseUrl);
     const response = await httpRequest(url, {
         method: 'GET',
         headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
@@ -94,7 +94,7 @@ async function modifyFavorite(conversationId, action) {
         return authResult;
     }
     const { auth, csaToken } = authResult.value;
-    const { region, baseUrl } = getApiConfig();
+    const { csaRegion, baseUrl } = getApiConfig();
     // Get current folder state
     const currentState = await getFavorites();
     if (!currentState.ok) {
@@ -103,7 +103,7 @@ async function modifyFavorite(conversationId, action) {
     if (!currentState.value.folderId) {
         return err(createError(ErrorCode.NOT_FOUND, 'Could not find Favorites folder'));
     }
-    const url = CSA_API.conversationFolders(region, baseUrl);
+    const url = CSA_API.conversationFolders(csaRegion, baseUrl);
     const response = await httpRequest(url, {
         method: 'POST',
         headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
@@ -135,8 +135,8 @@ export async function getMyTeamsAndChannels() {
         return authResult;
     }
     const { auth, csaToken } = authResult.value;
-    const { region, baseUrl } = getApiConfig();
-    const url = CSA_API.teamsList(region, baseUrl);
+    const { csaRegion, baseUrl } = getApiConfig();
+    const url = CSA_API.teamsList(csaRegion, baseUrl);
     const response = await httpRequest(url, {
         method: 'GET',
         headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
@@ -156,8 +156,8 @@ export async function getCustomEmojis() {
         return authResult;
     }
     const { auth, csaToken } = authResult.value;
-    const { region, baseUrl } = getApiConfig();
-    const url = CSA_API.customEmojis(region, baseUrl);
+    const { csaRegion, baseUrl } = getApiConfig();
+    const url = CSA_API.customEmojis(csaRegion, baseUrl);
     const response = await httpRequest(url, {
         method: 'GET',
         headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),

package/dist/api/graph-files-api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * File downloads via Microsoft Graph.
+ *
+ * Accepts either form Teams hands out:
+ * - Graph drive-item URLs (`https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}`),
+ *   used by assignment attachments;
+ * - SharePoint/OneDrive web URLs (direct file paths, `Doc.aspx` viewer links,
+ *   sharing links), used by shared chat and channel files. These are resolved
+ *   through Graph's shares API (`/shares/u!{base64url}/driveItem`).
+ *
+ * As the Teams Assignments client does, we read the item's
+ * `@microsoft.graph.downloadUrl` (a short-lived, pre-authenticated SharePoint
+ * link) and stream it to disk.
+ *
+ * Auth: the Teams client's own Graph token (`Files.ReadWrite.All`), obtained on
+ * demand via `requireGraphTokenAsync()`. Like Assignments, it is optional: a
+ * failure never surfaces as AUTH_REQUIRED/AUTH_EXPIRED, so it can't trigger the
+ * server's auto-login.
+ */
+import { type Result } from '../types/result.js';
+export interface DownloadedFile {
+    name: string;
+    outputPath: string;
+    size: number;
+    contentType: string;
+    sha256: string;
+}
+/**
+ * Downloads a file to `outputPath` (absolute; parent must exist; never
+ * overwrites). `url` is a Graph drive-item URL or a SharePoint/OneDrive web
+ * URL. Streams to disk, verifies the byte count against Graph's reported size,
+ * and removes the partial file on any failure.
+ */
+export declare function downloadFile(url: string, outputPath: string): Promise<Result<DownloadedFile>>;

package/dist/api/graph-files-api.js

@@ -0,0 +1,169 @@
+/**
+ * File downloads via Microsoft Graph.
+ *
+ * Accepts either form Teams hands out:
+ * - Graph drive-item URLs (`https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}`),
+ *   used by assignment attachments;
+ * - SharePoint/OneDrive web URLs (direct file paths, `Doc.aspx` viewer links,
+ *   sharing links), used by shared chat and channel files. These are resolved
+ *   through Graph's shares API (`/shares/u!{base64url}/driveItem`).
+ *
+ * As the Teams Assignments client does, we read the item's
+ * `@microsoft.graph.downloadUrl` (a short-lived, pre-authenticated SharePoint
+ * link) and stream it to disk.
+ *
+ * Auth: the Teams client's own Graph token (`Files.ReadWrite.All`), obtained on
+ * demand via `requireGraphTokenAsync()`. Like Assignments, it is optional: a
+ * failure never surfaces as AUTH_REQUIRED/AUTH_EXPIRED, so it can't trigger the
+ * server's auto-login.
+ */
+import { open, unlink } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { httpRequest } from '../utils/http.js';
+import { ok, err } from '../types/result.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { requireGraphTokenAsync } from '../utils/auth-guards.js';
+import { invalidateAccessToken } from '../auth/token-extractor.js';
+import { DOWNLOAD_INACTIVITY_TIMEOUT_MS } from '../constants.js';
+/** Graph drive items are requested as-is; the Graph token only ever goes to Graph. */
+const DRIVE_ITEM_URL = /^https:\/\/graph\.microsoft\.com\/v1\.0\/drives\/[A-Za-z0-9!_-]+\/items\/[A-Za-z0-9!_-]+$/;
+/** SharePoint/OneDrive hosts: web URLs to resolve, and the only download-link hosts. */
+const SHAREPOINT_HOST = /\.sharepoint(?:-mil)?\.(?:com|us|de|cn)$/;
+/**
+ * Map an accepted URL to the Graph drive-item URL to request, or null. A
+ * SharePoint URL is only ever sent to Graph, base64url-encoded as a share ID.
+ */
+function toDriveItemUrl(url) {
+    if (DRIVE_ITEM_URL.test(url))
+        return url;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.port || !SHAREPOINT_HOST.test(parsed.hostname)) {
+        return null;
+    }
+    return `https://graph.microsoft.com/v1.0/shares/u!${Buffer.from(url).toString('base64url')}/driveItem`;
+}
+/**
+ * Downloads a file to `outputPath` (absolute; parent must exist; never
+ * overwrites). `url` is a Graph drive-item URL or a SharePoint/OneDrive web
+ * URL. Streams to disk, verifies the byte count against Graph's reported size,
+ * and removes the partial file on any failure.
+ */
+export async function downloadFile(url, outputPath) {
+    const itemUrl = toDriveItemUrl(url);
+    if (!itemUrl) {
+        return err(createError(ErrorCode.INVALID_INPUT, 'url must be a Microsoft Graph drive-item URL (https://graph.microsoft.com/v1.0/drives/{id}/items/{id}) or an HTTPS SharePoint/OneDrive file URL (*.sharepoint.com)'));
+    }
+    if (!isAbsolute(outputPath)) {
+        return err(createError(ErrorCode.INVALID_INPUT, 'outputPath must be an absolute file path'));
+    }
+    const tokenResult = await requireGraphTokenAsync();
+    if (!tokenResult.ok)
+        return tokenResult;
+    const params = new URLSearchParams({ '$select': 'name,size,file,currentUserRole,content.downloadUrl' });
+    const meta = await httpRequest(`${itemUrl}?${params.toString()}`, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${tokenResult.value}`, Accept: 'application/json' },
+    });
+    if (!meta.ok) {
+        if (meta.error.code === ErrorCode.AUTH_EXPIRED) {
+            invalidateAccessToken(tokenResult.value);
+            return err(createError(ErrorCode.API_ERROR, 'Microsoft Graph rejected its access token; it has been discarded, so a retry will request a new one.', { retryable: true }));
+        }
+        if (meta.error.code === ErrorCode.AUTH_REQUIRED) {
+            return err(createError(ErrorCode.ACCESS_DENIED, `You don't have access to this file: ${meta.error.message}`, { retryable: false }));
+        }
+        if (meta.error.code === ErrorCode.NOT_FOUND) {
+            return err(createError(ErrorCode.NOT_FOUND, 'File not found. It may have been moved or deleted, or the URL is not a file you can access.', { retryable: false }));
+        }
+        return meta;
+    }
+    const item = meta.value.data;
+    if (!item?.file) {
+        return err(createError(ErrorCode.INVALID_INPUT, 'This item is not a file (it may be a folder)', { retryable: false }));
+    }
+    if (item.currentUserRole?.blocksDownload) {
+        return err(createError(ErrorCode.ACCESS_DENIED, 'The owner has blocked downloading this file', { retryable: false }));
+    }
+    const downloadUrl = item['@microsoft.graph.downloadUrl'];
+    let downloadHost = '';
+    try {
+        downloadHost = downloadUrl ? new URL(downloadUrl).hostname : '';
+    }
+    catch { /* handled below */ }
+    if (!downloadUrl?.startsWith('https://') || !SHAREPOINT_HOST.test(downloadHost)) {
+        return err(createError(ErrorCode.API_ERROR, 'Microsoft Graph did not return a SharePoint download link for this file', { retryable: false }));
+    }
+    const saved = await streamToFile(downloadUrl, outputPath, item.size);
+    if (!saved.ok)
+        return saved;
+    return ok({
+        name: item.name ?? '',
+        outputPath,
+        size: saved.value.size,
+        contentType: saved.value.contentType ?? item.file.mimeType ?? 'application/octet-stream',
+        sha256: saved.value.sha256,
+    });
+}
+/** Stream a pre-authenticated link to a new file, with an inactivity timeout. */
+async function streamToFile(url, outputPath, expectedSize) {
+    let file;
+    try {
+        // Exclusive creation: never overwrite an existing file or follow a symlink.
+        file = await open(outputPath, 'wx', 0o600);
+    }
+    catch (error) {
+        return err(createError(ErrorCode.INVALID_INPUT, `Could not create ${outputPath}: ${error instanceof Error ? error.message : String(error)}`, { retryable: false, suggestions: ['The parent directory must exist and the file must not already exist'] }));
+    }
+    const controller = new AbortController();
+    let timer = setTimeout(() => controller.abort(), DOWNLOAD_INACTIVITY_TIMEOUT_MS);
+    const touch = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(), DOWNLOAD_INACTIVITY_TIMEOUT_MS);
+    };
+    let complete = false;
+    try {
+        // No Authorization header: the link is pre-authenticated. Refuse redirects
+        // so a sign-in page can never be saved as file contents.
+        const response = await fetch(url, { redirect: 'error', signal: controller.signal });
+        if (!response.ok || !response.body) {
+            return err(createError(ErrorCode.API_ERROR, `File download failed: HTTP ${response.status}`, { retryable: response.status >= 500 }));
+        }
+        const hash = createHash('sha256');
+        let size = 0;
+        const meter = new Transform({
+            transform(chunk, _encoding, callback) {
+                touch();
+                hash.update(chunk);
+                size += chunk.length;
+                callback(null, chunk);
+            },
+        });
+        await pipeline(Readable.fromWeb(response.body), meter, file.createWriteStream());
+        if (expectedSize !== undefined && size !== expectedSize) {
+            return err(createError(ErrorCode.API_ERROR, `Download was incomplete: received ${size} of ${expectedSize} bytes`, { retryable: true }));
+        }
+        complete = true;
+        return ok({ size, sha256: hash.digest('hex'), contentType: response.headers.get('content-type') ?? undefined });
+    }
+    catch (error) {
+        const timedOut = controller.signal.aborted;
+        return err(createError(timedOut ? ErrorCode.TIMEOUT : ErrorCode.NETWORK_ERROR, timedOut
+            ? `File download stalled for ${DOWNLOAD_INACTIVITY_TIMEOUT_MS / 1000}s and was cancelled`
+            : `File download failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true }));
+    }
+    finally {
+        clearTimeout(timer);
+        await file.close().catch(() => { });
+        if (!complete)
+            await unlink(outputPath).catch(() => { });
+    }
+}

package/dist/api/graph-files-api.test.d.ts

@@ -0,0 +1 @@
+export {};