@fluxmail/core 0.19.0 → 0.20.0

package/dist/searchCursor.js

@@ -0,0 +1,113 @@
+import { createHash, createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+import { EmailError } from './errors.js';
+const CURSOR_VERSION = 1;
+const CURSOR_LIFETIME_MS = 60 * 60 * 1_000;
+const MAX_CURSOR_BYTES = 16 * 1_024;
+const HKDF_CONTEXT = 'fluxmail/search-page-token/v1';
+function canonicalQuery(query) {
+    const entries = Object.entries(query)
+        .filter(([, value]) => value !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right));
+    return JSON.stringify(Object.fromEntries(entries));
+}
+export function emailQueryHash(query) {
+    return createHash('sha256').update(canonicalQuery(query)).digest('base64url');
+}
+/**
+ * Node only, so it ships as `@fluxmail/core/search-cursor` instead of the root export.
+ *
+ * Wraps a provider's page token in a signed, expiring cursor bound to the account, query and
+ * page options, so a token can't be replayed against a different search.
+ */
+export class SearchCursorCodec {
+    key;
+    invalidCursor;
+    constructor(secret, options = {}) {
+        this.key = Buffer.from(hkdfSync('sha256', secret, Buffer.alloc(0), HKDF_CONTEXT, 32));
+        this.invalidCursor =
+            options.invalidCursor ?? (() => new EmailError('invalid_request', 'Invalid or expired search page token.'));
+    }
+    encode(binding, now = Date.now()) {
+        const payload = {
+            v: CURSOR_VERSION,
+            accountId: binding.accountId,
+            provider: binding.provider,
+            queryHash: emailQueryHash(binding.query),
+            pageSize: binding.pageSize,
+            ...(binding.includeSnippet !== undefined ? { includeSnippet: binding.includeSnippet } : {}),
+            ...(binding.includeSearchContext ? { includeSearchContext: true } : {}),
+            providerToken: binding.providerToken,
+            issuedAt: now,
+            expiresAt: now + CURSOR_LIFETIME_MS,
+        };
+        const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const signature = createHmac('sha256', this.key).update(encodedPayload).digest('base64url');
+        const token = `${encodedPayload}.${signature}`;
+        if (Buffer.byteLength(token) > MAX_CURSOR_BYTES) {
+            throw new EmailError('invalid_request', 'The provider returned a search page token that is too large.');
+        }
+        return token;
+    }
+    decode(token, binding, now = Date.now()) {
+        if (Buffer.byteLength(token) > MAX_CURSOR_BYTES)
+            throw this.invalidCursor();
+        const parts = token.split('.');
+        if (parts.length !== 2 || !parts[0] || !parts[1])
+            throw this.invalidCursor();
+        const [encodedPayload, encodedSignature] = parts;
+        if (!/^[A-Za-z0-9_-]+$/.test(encodedPayload) || !/^[A-Za-z0-9_-]+$/.test(encodedSignature)) {
+            throw this.invalidCursor();
+        }
+        let suppliedSignature;
+        try {
+            suppliedSignature = Buffer.from(encodedSignature, 'base64url');
+        }
+        catch {
+            throw this.invalidCursor();
+        }
+        if (suppliedSignature.toString('base64url') !== encodedSignature)
+            throw this.invalidCursor();
+        const expectedSignature = createHmac('sha256', this.key).update(encodedPayload).digest();
+        if (suppliedSignature.length !== expectedSignature.length)
+            throw this.invalidCursor();
+        if (!timingSafeEqual(suppliedSignature, expectedSignature))
+            throw this.invalidCursor();
+        let payload;
+        try {
+            const bytes = Buffer.from(encodedPayload, 'base64url');
+            if (bytes.toString('base64url') !== encodedPayload)
+                throw new Error();
+            payload = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            throw this.invalidCursor();
+        }
+        if (!payload ||
+            payload.v !== CURSOR_VERSION ||
+            typeof payload.accountId !== 'string' ||
+            !['gmail', 'outlook', 'imap'].includes(payload.provider) ||
+            typeof payload.queryHash !== 'string' ||
+            !Number.isInteger(payload.pageSize) ||
+            (payload.includeSnippet !== undefined && typeof payload.includeSnippet !== 'boolean') ||
+            (payload.includeSearchContext !== undefined && typeof payload.includeSearchContext !== 'boolean') ||
+            typeof payload.providerToken !== 'string' ||
+            !payload.providerToken ||
+            !Number.isFinite(payload.issuedAt) ||
+            !Number.isFinite(payload.expiresAt) ||
+            payload.expiresAt !== payload.issuedAt + CURSOR_LIFETIME_MS ||
+            payload.issuedAt > now ||
+            payload.expiresAt <= now) {
+            throw this.invalidCursor();
+        }
+        if (payload.accountId !== binding.accountId ||
+            payload.provider !== binding.provider ||
+            payload.queryHash !== emailQueryHash(binding.query) ||
+            payload.pageSize !== binding.pageSize ||
+            payload.includeSnippet !== binding.includeSnippet ||
+            (payload.includeSearchContext ?? false) !== (binding.includeSearchContext ?? false)) {
+            throw this.invalidCursor();
+        }
+        return payload.providerToken;
+    }
+}
+//# sourceMappingURL=searchCursor.js.map

package/dist/searchCursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchCursor.js","sourceRoot":"","sources":["../src/searchCursor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxmail/core",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Unified email types and provider interface for Fluxmail",
   "license": "Elastic-2.0",
   "repository": {
@@ -19,6 +19,14 @@
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "default": "./dist/mcp/index.js"
+    },
+    "./mcp/pdf": {
+      "types": "./dist/mcp/pdf.d.ts",
+      "default": "./dist/mcp/pdf.js"
+    },
+    "./search-cursor": {
+      "types": "./dist/searchCursor.d.ts",
+      "default": "./dist/searchCursor.js"
     }
   },
   "files": [