CONTRACTS.md 5.6 KB

Internal provider contract

ES modules, Node 24. All persisted content is considered untrusted plain text.

record = { source: 'web-api'|'graph'|'browser'|'demo', accountId: string, kind: 'chat'|'message'|'event'|'activity', externalId: string, parentId?: string, title?: string, text?: string, occurredAt?: ISO string|null, updatedAt?: ISO string|null, webUrl?: string|null, deleted?: boolean, removedFromView?: boolean, raw?: object }

Graph message externalId namespaces the chat ID and message ID (message IDs are not globally unique). Calendar delta @removed sets removedFromView=true instead of asserting remote deletion; unknown view removals are ignored, known records retain their previously archived content. A later normal event clears removedFromView. Message deletedDateTime still maps to deleted=true.

Store API (synchronous SQLite): upsertRecord(record) returns {changed:boolean,id:number}; getState(key) returns parsed value or null; setState(key,value); addLog(level,message,details?); listRecords({kind?,source?,accountId?,q?,limit?,offset?}) returns {items,total}; stats(); close(). Record identity is source+accountId+kind+externalId. JSON payload is stored locally; no content included in logs. Changes produce historical versions and a locally derived activity ONLY for Graph message/event records. Browser activity remains an observed feed entry, not derived activity.

Version 0.4.0: upsertRecord(record, {ingestion: 'live'|'history'|'import'|'unknown'}), default unknown. Actual record changes append change_log atomically with their version. First live observation of a new API message is tracked separately so an identical live read after history ingestion can notify once without creating a fake version. Existing import/unknown records and records predating the change log are not promoted to live notifications. Internal fixed-query helpers readRows/readOne/execute are never exposed as arbitrary MCP SQL.

createAiService({store,network?}) provides safe queries; createMcpServer({query,webhooks?}) supplies protocol tools/resources/prompts. createMcpHttpHandler requires the outer server to authenticate the dedicated MCP token and validate Host/Origin. createWebhookService({store}) is idle until start(); only the main service starts it. See MCP and WebHooks for public contracts and delivery semantics.

Graph module exports createGraphProvider({store, config}) returning {status(), beginLogin(), completeLogin(query), logout(), sync(), start(), stop()}. status is synchronous and contains only nonsecret state. beginLogin returns Promise<{url}>. completeLogin accepts URLSearchParams and validates state, PKCE, expiry. config contains clientId, tenantId (default organizations), redirectUri (http://localhost:4318/auth/callback), pollIntervalMs (30000), calendarPastDays (30), calendarFutureDays (90), dataDir. Tokens stay in memory by default. start schedules polling; sync returns summary. Provider constructor must work when clientId is missing and status explains configuration. Tests may inject fetch/MSAL through module exports or constructor options.

Browser extension POSTs http://127.0.0.1:4318/api/extension/events, header Authorization: Bearer <pairing token>, JSON {accountId: <explicit non-empty user profile label>, records:[{kind, externalId, parentId?, title?, text?, occurredAt?, updatedAt?, webUrl?, raw?}], page:{url,title,signedIn,view,coverage}}. Server enforces source=browser, prefixes accountId with browser:, validates shapes, maximum 200 records/request and 1 MiB. Never collect credentials, cookies, authorization headers or input values. Page raw data contains only observed DOM content and provenance. Account label is configured by user (must be unique per account); do not guess account identity. Extension token is only authorized on ingestion; not read APIs. Browser sends heartbeat with empty records too. Default endpoint fixed at 127.0.0.1:4318; options can change loopback HTTP port only. Options page connects via /api/extension/ping with same bearer token; ping is POST.

Version 0.1.1 adds authenticated POST /api/extension/status: {accountId,version,enabled:boolean,teamsTabCount:integer,readyTabCount:integer,error:string}. Counts must be 0..10000 and ready<=total. Diagnostics contain no captured page text or credentials. Ping records transport pairing; status records extension/script diagnostics; events (even an empty records array) records actual page heartbeats. GET /api/status exposes these separately as pairing, extension, and browser, never fabricating page connection from ping alone.

Browser extension implements login by opening https://teams.microsoft.com/v2/ in the normal browser and recording login visibility status. Credentials/MFA are handled by Microsoft. Capture is explicitly enabled by user, per profile label, and restricted to Teams pages; default disabled. Visible loaded DOM only, with clear limitations in options and popup. Browser source captures all three supported views (chat/messages, calendar events, activity feed) using a separately testable parser. No remote API replay or token extraction.

Dashboard uses /api/status, /api/records, /api/logs GET and /api/graph/login, /api/graph/logout, /api/sync, /api/demo, /api/pairing/rotate POST with X-Local-Token from same-origin status. Local server serves only exact localhost/127.0.0.1 Host+port, same-origin browser requests and extension ingestion with token. /api/status reports dashboard CSRF token, extension pairing token, graph status, browser heartbeat, stats. GET /api/export returns NDJSON attachment; filter params match records. All UI renders textContent, never graph or captured HTML.