@tuongaz/seeflow 0.1.102 → 0.1.104

package/src/share-envelope.ts

@@ -0,0 +1,152 @@
+/**
+ * Live Share WebSocket envelope schema and helpers.
+ *
+ * Every frame on the relay wire — host->relay and relay->peer — is shaped
+ * exactly like the design doc's envelope (v=1, typed `type`, optional `id`
+ * for rpc correlation, `from` connId, optional `to`, opaque `payload`).
+ * The relay is a dumb router and never inspects `payload`; validation
+ * happens at the host (this module) and the peer canvas.
+ *
+ * `parseEnvelope` returns a discriminated `{ ok }` result so the transport
+ * can drop invalid frames without throwing inside the WS read loop.
+ * `makeEnvelope` constructs outbound frames with `from='host'` by default
+ * so callers don't have to repeat it.
+ */
+
+import { z } from 'zod';
+
+export const ENVELOPE_TYPES = [
+  'auth-host',
+  'auth-peer',
+  'rpc',
+  'rpc-result',
+  'sse',
+  'sse-snapshot',
+  'presence',
+  'file-request',
+  'file-bytes',
+  'file-redirect',
+  'file-upload-intent',
+  'file-upload-done',
+  'node-patched',
+  'files-manifest',
+  'kick',
+] as const;
+
+export const EnvelopeTypeSchema = z.enum(ENVELOPE_TYPES);
+
+export const EnvelopeSchema = z.object({
+  v: z.literal(1),
+  type: EnvelopeTypeSchema,
+  id: z.string().optional(),
+  from: z.string(),
+  to: z.string().optional(),
+  payload: z.unknown(),
+});
+
+export type EnvelopeType = z.infer<typeof EnvelopeTypeSchema>;
+export type Envelope = z.infer<typeof EnvelopeSchema>;
+
+// File frame payload schemas. Vendored copy of the cloud relay's per-type
+// schemas (`cloud/lambda/share/shared/envelope.ts`) so the host can validate
+// inbound file-request frames and shape outbound file-bytes / file-redirect /
+// file-upload-intent / file-upload-done / files-manifest replies with the same
+// invariants the relay enforces. Keep these aligned with the cloud copy.
+const NodeIdSchema = z.string().regex(/^node-[A-Za-z0-9]{10}$/);
+const Sha256HexSchema = z.string().length(64);
+
+export const FileRequestPayloadSchema = z.object({
+  reqId: z.string().min(1),
+  nodeId: z.string(),
+  relPath: z.string(),
+});
+export type FileRequestPayload = z.infer<typeof FileRequestPayloadSchema>;
+
+export const FileBytesPayloadSchema = z.object({
+  reqId: z.string(),
+  seq: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+  base64: z.string(),
+  contentType: z.string().optional(),
+  sha256: z.string(),
+  eof: z.boolean(),
+});
+export type FileBytesPayload = z.infer<typeof FileBytesPayloadSchema>;
+
+export const FileRedirectPayloadSchema = z.object({
+  reqId: z.string(),
+  getUrl: z.string().url(),
+  sha256: z.string(),
+  expiresAt: z.number().int().nonnegative(),
+});
+export type FileRedirectPayload = z.infer<typeof FileRedirectPayloadSchema>;
+
+// Host-serve variant: the host asks the relay to mint a presigned PUT so it
+// can stream a >256 KB file via S3 instead of inline WS chunks. `role` is set
+// to `'host-serve'` to distinguish from peer-originated uploads (US-061).
+export const FileUploadIntentPayloadSchema = z.object({
+  reqId: z.string(),
+  filename: z.string().min(1).max(255),
+  size: z.number().int().nonnegative().max(1_073_741_824),
+  contentType: z.string(),
+  nodeId: NodeIdSchema,
+  sha256: Sha256HexSchema,
+  role: z.enum(['host-serve', 'peer-upload']).optional(),
+});
+export type FileUploadIntentPayload = z.infer<typeof FileUploadIntentPayloadSchema>;
+
+export const FileUploadDonePayloadSchema = z.object({
+  reqId: z.string(),
+  key: z.string(),
+  sha256: z.string(),
+});
+export type FileUploadDonePayload = z.infer<typeof FileUploadDonePayloadSchema>;
+
+export const FilesManifestEntrySchema = z.object({
+  nodeId: z.string(),
+  relPath: z.string(),
+  size: z.number().int().nonnegative(),
+  etag: z.string(),
+});
+export type FilesManifestEntry = z.infer<typeof FilesManifestEntrySchema>;
+
+export const FilesManifestPayloadSchema = z.object({
+  entries: z.array(FilesManifestEntrySchema),
+});
+export type FilesManifestPayload = z.infer<typeof FilesManifestPayloadSchema>;
+
+export function parseEnvelope(
+  raw: unknown,
+): { ok: true; envelope: Envelope } | { ok: false; reason: string } {
+  const result = EnvelopeSchema.safeParse(raw);
+  if (result.success) {
+    return { ok: true, envelope: result.data };
+  }
+  // Surface the first issue path/message so the transport's console.warn
+  // is actionable without leaking the payload itself.
+  const first = result.error.issues[0];
+  const reason = first ? `${first.path.join('.') || '<root>'}: ${first.message}` : 'invalid';
+  return { ok: false, reason };
+}
+
+export interface MakeEnvelopeOpts {
+  id?: string;
+  from?: string;
+  to?: string;
+}
+
+export function makeEnvelope<T extends EnvelopeType>(
+  type: T,
+  payload: unknown,
+  opts: MakeEnvelopeOpts = {},
+): Envelope {
+  const env: Envelope = {
+    v: 1,
+    type,
+    from: opts.from ?? 'host',
+    payload,
+  };
+  if (opts.id !== undefined) env.id = opts.id;
+  if (opts.to !== undefined) env.to = opts.to;
+  return env;
+}

package/src/share-file-request.ts

@@ -0,0 +1,353 @@
+/**
+ * Host-side `file-request` handler. The relay routes inbound `file-request`
+ * envelopes (peer -> host) here; the handler either responds inline with a
+ * single `file-bytes` frame (<=256 KB) or stages the file in the relay's
+ * ephemeral S3 bucket via `file-upload-intent` and replies with a
+ * `file-redirect` URL.
+ *
+ * Design choice: S3 staging is preferred over multi-chunk WS streaming for
+ * oversize files because the relay rate-limits `file-bytes` at 5 MB / 60 s per
+ * peer (US-058); large assets would otherwise stall. Staged objects live for
+ * <=60 s (the staging bucket has a 1-day lifecycle but presigned URLs expire
+ * in 60 s) so bytes never persist past the read.
+ *
+ * Errors reply with both a sentinel `file-bytes { eof:true, sha256:'' }` so
+ * the peer's `/files/<path>` proxy can return 4xx, AND an `rpc-result
+ * { id:reqId, ok:false, reason }` so peer rpc callers see a structured error.
+ *
+ * Rate-limit: at most 30 concurrent in-flight file-requests per peer; excess
+ * are rejected immediately with `reason: 'too-many-in-flight'`.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fsPromises from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import type { FlowEntry, Registry } from './registry.ts';
+import {
+  type Envelope,
+  type FileBytesPayload,
+  type FileRedirectPayload,
+  FileRequestPayloadSchema,
+  type FileUploadIntentPayload,
+  makeEnvelope,
+} from './share-envelope.ts';
+import { resolveNodeFile } from './share-file-resolver.ts';
+
+const INLINE_LIMIT_BYTES = 256 * 1024;
+const MAX_INFLIGHT_PER_PEER = 30;
+
+// Extension -> content type allowlist. Anything not in the map falls back to
+// `application/octet-stream`. Lowercased keys; we lowercase the extension at
+// lookup so `.PNG` resolves the same as `.png`.
+const CONTENT_TYPE_MAP: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.md': 'text/markdown',
+  '.txt': 'text/plain',
+  '.json': 'application/json',
+};
+
+export function contentTypeFor(filename: string): string {
+  const ext = extname(filename).toLowerCase();
+  return CONTENT_TYPE_MAP[ext] ?? 'application/octet-stream';
+}
+
+export interface UploadIntentReply {
+  // `getUrl`+`expiresAt` are returned alongside `putUrl` so the host can
+  // immediately reply with `file-redirect` after the PUT succeeds. The cloud
+  // relay currently embeds only `putUrl` (US-058); the wiring layer is
+  // responsible for materialising matching getUrl/expiresAt either by
+  // re-using the staging key with a second presigner call or by extending the
+  // relay reply. Tests inject this dep wholesale.
+  putUrl: string;
+  getUrl: string;
+  expiresAt: number;
+  key: string;
+}
+
+export type RequestUploadIntent = (payload: {
+  reqId: string;
+  filename: string;
+  size: number;
+  contentType: string;
+  sha256: string;
+  nodeId: string;
+  role: 'host-serve';
+}) => Promise<UploadIntentReply>;
+
+export type PutToS3 = (
+  url: string,
+  bytes: Buffer,
+  contentType: string,
+) => Promise<{ ok: boolean; status: number }>;
+
+export interface FileRequestDeps {
+  registry: Registry;
+  // Sends outbound envelopes through the active transport. Defaults wire to
+  // share.ts's existing `broadcast` closure when integrated.
+  broadcast: (envelope: Envelope) => void;
+  // S3 staging path. Both deps must be provided to enable the oversize path;
+  // if either is absent, oversize requests reply with `reason: 'too-large'`
+  // and the peer falls back to a 413.
+  requestUploadIntent?: RequestUploadIntent;
+  putToS3?: PutToS3;
+  // Test overrides — production callers leave these on the node:fs defaults.
+  readFile?: (p: string) => Promise<Buffer>;
+  fileExists?: (p: string) => Promise<boolean>;
+}
+
+export interface FileRequestHandler {
+  handle(envelope: Envelope): Promise<void>;
+  // Exposed for tests so they can assert the in-flight counter is released
+  // after each request settles.
+  inflightCount(peerConnId: string): number;
+}
+
+const defaultFileExists = async (p: string): Promise<boolean> => {
+  try {
+    const s = await fsPromises.stat(p);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+};
+
+const defaultReadFile = (p: string): Promise<Buffer> => fsPromises.readFile(p) as Promise<Buffer>;
+
+// Iterate all registered flow entries and return the first whose resolved
+// per-node path exists on disk. nodeIds are globally unique (10-char base62
+// shortIds) so collisions across flows are astronomically unlikely; the
+// existence probe disambiguates if it ever happens.
+type LocateResult =
+  | { kind: 'ok'; entry: FlowEntry; absPath: string }
+  | { kind: 'bad-node-id' }
+  | { kind: 'traversal' }
+  | { kind: 'not-found' };
+
+async function locateNodeFile(
+  registry: Registry,
+  nodeId: string,
+  relPath: string,
+  fileExists: (p: string) => Promise<boolean>,
+): Promise<LocateResult> {
+  const entries = registry.list();
+  if (entries.length === 0) return { kind: 'not-found' };
+
+  // Run the resolver against the first entry to surface the static-shape
+  // errors (bad nodeId / traversal). These depend only on nodeId+relPath, so
+  // any registry entry yields the same verdict.
+  const first = entries[0];
+  if (first) {
+    const r = resolveNodeFile({
+      repoPath: first.repoPath,
+      flowPath: first.flowPath,
+      nodeId,
+      relPath,
+    });
+    if ('error' in r) {
+      if (r.error === 'bad-node-id') return { kind: 'bad-node-id' };
+      return { kind: 'traversal' };
+    }
+  }
+
+  for (const entry of entries) {
+    const r = resolveNodeFile({
+      repoPath: entry.repoPath,
+      flowPath: entry.flowPath,
+      nodeId,
+      relPath,
+    });
+    if ('error' in r) continue;
+    if (await fileExists(r.absPath)) {
+      return { kind: 'ok', entry, absPath: r.absPath };
+    }
+  }
+  return { kind: 'not-found' };
+}
+
+export function createFileRequestHandler(deps: FileRequestDeps): FileRequestHandler {
+  const readFile = deps.readFile ?? defaultReadFile;
+  const fileExists = deps.fileExists ?? defaultFileExists;
+  const inflightPerPeer = new Map<string, number>();
+
+  const sendErrorReply = (replyTo: string, reqId: string, reason: string) => {
+    // Send the sentinel file-bytes so the peer's /files proxy returns 4xx,
+    // then the structured rpc-result with the actual reason. Order matters
+    // for the peer-side state machine in US-063 (proxy resolves on the
+    // file-bytes sentinel, rpc callers resolve on the rpc-result).
+    const sentinel: FileBytesPayload = {
+      reqId,
+      seq: 0,
+      total: 0,
+      base64: '',
+      sha256: '',
+      eof: true,
+    };
+    deps.broadcast(makeEnvelope('file-bytes', sentinel, { to: replyTo }));
+    deps.broadcast(makeEnvelope('rpc-result', { ok: false, reason }, { to: replyTo, id: reqId }));
+  };
+
+  const respondInline = (
+    replyTo: string,
+    reqId: string,
+    bytes: Buffer,
+    contentType: string,
+    sha256: string,
+  ) => {
+    const payload: FileBytesPayload = {
+      reqId,
+      seq: 0,
+      total: 1,
+      base64: bytes.toString('base64'),
+      contentType,
+      sha256,
+      eof: true,
+    };
+    deps.broadcast(makeEnvelope('file-bytes', payload, { to: replyTo }));
+  };
+
+  const respondRedirect = (
+    replyTo: string,
+    reqId: string,
+    intent: UploadIntentReply,
+    sha256: string,
+  ) => {
+    const payload: FileRedirectPayload = {
+      reqId,
+      getUrl: intent.getUrl,
+      sha256,
+      expiresAt: intent.expiresAt,
+    };
+    deps.broadcast(makeEnvelope('file-redirect', payload, { to: replyTo }));
+  };
+
+  const handle = async (envelope: Envelope): Promise<void> => {
+    const replyTo = envelope.from;
+    const parsed = FileRequestPayloadSchema.safeParse(envelope.payload);
+    if (!parsed.success) {
+      // We can't address the rpc-result without a reqId. Pull a best-effort id
+      // from the raw payload (relay never inspects it, so anything goes) and
+      // fall back to a literal `'invalid'` so the wire schema's min(1) holds.
+      const rawReqId =
+        envelope.payload &&
+        typeof envelope.payload === 'object' &&
+        'reqId' in envelope.payload &&
+        typeof (envelope.payload as { reqId?: unknown }).reqId === 'string' &&
+        (envelope.payload as { reqId: string }).reqId.length > 0
+          ? (envelope.payload as { reqId: string }).reqId
+          : 'invalid';
+      sendErrorReply(replyTo, rawReqId, 'bad-payload');
+      return;
+    }
+    const { reqId, nodeId, relPath } = parsed.data;
+
+    const current = inflightPerPeer.get(replyTo) ?? 0;
+    if (current >= MAX_INFLIGHT_PER_PEER) {
+      sendErrorReply(replyTo, reqId, 'too-many-in-flight');
+      return;
+    }
+    inflightPerPeer.set(replyTo, current + 1);
+
+    try {
+      const located = await locateNodeFile(deps.registry, nodeId, relPath, fileExists);
+      if (located.kind === 'bad-node-id') {
+        sendErrorReply(replyTo, reqId, 'bad-node-id');
+        return;
+      }
+      if (located.kind === 'traversal') {
+        sendErrorReply(replyTo, reqId, 'traversal');
+        return;
+      }
+      if (located.kind === 'not-found') {
+        sendErrorReply(replyTo, reqId, 'not-found');
+        return;
+      }
+
+      let bytes: Buffer;
+      try {
+        bytes = await readFile(located.absPath);
+      } catch (err) {
+        console.warn('[share] file-request read failed:', {
+          nodeId,
+          reason: err instanceof Error ? err.message : String(err),
+        });
+        sendErrorReply(replyTo, reqId, 'read-failed');
+        return;
+      }
+
+      const sha256 = createHash('sha256').update(bytes).digest('hex');
+      const filename = basename(located.absPath);
+      const contentType = contentTypeFor(filename);
+
+      if (bytes.length <= INLINE_LIMIT_BYTES) {
+        respondInline(replyTo, reqId, bytes, contentType, sha256);
+        return;
+      }
+
+      // Oversize path: stage to S3 and reply with redirect.
+      if (!deps.requestUploadIntent || !deps.putToS3) {
+        sendErrorReply(replyTo, reqId, 'too-large');
+        return;
+      }
+      const intentPayload: FileUploadIntentPayload = {
+        reqId,
+        filename,
+        size: bytes.length,
+        contentType,
+        sha256,
+        nodeId,
+        role: 'host-serve',
+      };
+      let intent: UploadIntentReply;
+      try {
+        intent = await deps.requestUploadIntent({
+          reqId: intentPayload.reqId,
+          filename: intentPayload.filename,
+          size: intentPayload.size,
+          contentType: intentPayload.contentType,
+          sha256: intentPayload.sha256,
+          nodeId: intentPayload.nodeId,
+          role: 'host-serve',
+        });
+      } catch (err) {
+        console.warn('[share] file-request intent failed:', {
+          nodeId,
+          reason: err instanceof Error ? err.message : String(err),
+        });
+        sendErrorReply(replyTo, reqId, 'intent-failed');
+        return;
+      }
+      let putResult: { ok: boolean; status: number };
+      try {
+        putResult = await deps.putToS3(intent.putUrl, bytes, contentType);
+      } catch (err) {
+        console.warn('[share] file-request s3 put threw:', {
+          nodeId,
+          reason: err instanceof Error ? err.message : String(err),
+        });
+        sendErrorReply(replyTo, reqId, 'put-failed');
+        return;
+      }
+      if (!putResult.ok) {
+        sendErrorReply(replyTo, reqId, `put-status-${putResult.status}`);
+        return;
+      }
+      respondRedirect(replyTo, reqId, intent, sha256);
+    } finally {
+      const next = (inflightPerPeer.get(replyTo) ?? 1) - 1;
+      if (next <= 0) inflightPerPeer.delete(replyTo);
+      else inflightPerPeer.set(replyTo, next);
+    }
+  };
+
+  return {
+    handle,
+    inflightCount: (peerConnId) => inflightPerPeer.get(peerConnId) ?? 0,
+  };
+}

package/src/share-file-resolver.ts

@@ -0,0 +1,68 @@
+import * as nodePath from 'node:path';
+
+export type ResolveError = 'bad-node-id' | 'traversal' | 'outside-flow-dir';
+
+export type ResolveNodeFileResult = { absPath: string } | { error: ResolveError };
+
+export interface ResolveNodeFileOptions {
+  repoPath: string;
+  flowPath: string;
+  nodeId: string;
+  relPath: string;
+}
+
+const NODE_ID_RE = /^node-[A-Za-z0-9]{10}$/;
+
+// Map a peer-supplied `{ nodeId, relPath }` request into a guaranteed-safe
+// absolute path under `<repoPath>/<dirname(flowPath)>/nodes/<nodeId>/`. Mirrors
+// the per-node upload sink at api.ts /projects/.../nodes/:nodeId/files/upload:
+// for manifest-driven projects the base dir is `<flowDir>/nodes/<id>/`; for
+// legacy single-flow registrations (flow.json at the project root, flowDir==='.')
+// it collapses to `<repoPath>/nodes/<id>/`. Refuses any input that escapes that
+// per-node scope.
+export const resolveNodeFile = (
+  opts: ResolveNodeFileOptions,
+  pathMod: typeof nodePath = nodePath,
+): ResolveNodeFileResult => {
+  const { repoPath, flowPath, nodeId, relPath } = opts;
+
+  if (!NODE_ID_RE.test(nodeId)) {
+    return { error: 'bad-node-id' };
+  }
+
+  if (typeof relPath !== 'string' || relPath.length === 0) {
+    return { error: 'traversal' };
+  }
+  // Refuse absolute paths in either separator style so a host running on POSIX
+  // still rejects a `C:\…` or `\\server\share` payload from a win32 peer (and
+  // vice-versa). Win32 absoluteness covers drive letters and UNC paths.
+  if (relPath.startsWith('/') || relPath.startsWith('\\')) {
+    return { error: 'traversal' };
+  }
+  if (pathMod.isAbsolute(relPath) || nodePath.win32.isAbsolute(relPath)) {
+    return { error: 'traversal' };
+  }
+
+  // After normalize, any remaining `..` segment means the relPath tries to
+  // escape its node folder. Split on BOTH separators so a posix host catches
+  // `..\\evil` and a win32 host catches `../evil`.
+  const normalized = pathMod.normalize(relPath);
+  const segments = normalized.split(/[/\\]/);
+  if (segments.some((segment) => segment === '..')) {
+    return { error: 'traversal' };
+  }
+
+  const flowDir = pathMod.dirname(flowPath);
+  const baseDir =
+    flowDir === '.'
+      ? pathMod.join(repoPath, 'nodes', nodeId)
+      : pathMod.join(repoPath, flowDir, 'nodes', nodeId);
+
+  const absPath = pathMod.resolve(baseDir, relPath);
+
+  if (absPath !== baseDir && !absPath.startsWith(baseDir + pathMod.sep)) {
+    return { error: 'outside-flow-dir' };
+  }
+
+  return { absPath };
+};