@relayfile/core 0.1.0

package/dist/storage.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Storage adapter interface.
+ *
+ * All core logic functions accept a storage adapter — they never do I/O directly.
+ * Implementors provide the actual storage (DO SQLite, Go in-memory, Postgres, etc.).
+ *
+ * Methods return plain data. Errors are signaled via return values, not exceptions.
+ */
+export interface FileRow {
+    path: string;
+    revision: string;
+    contentType: string;
+    /** Content body. May be inline or a ref key depending on storage backend. */
+    content: string;
+    encoding: string;
+    provider: string;
+    lastEditedAt: string;
+    semantics: FileSemantics;
+}
+export interface FileSemantics {
+    properties?: Record<string, string>;
+    relations?: string[];
+    permissions?: string[];
+    comments?: string[];
+}
+export interface EventRow {
+    eventId: string;
+    type: string;
+    path: string;
+    revision: string;
+    origin: string;
+    provider: string;
+    correlationId: string;
+    timestamp: string;
+}
+export interface OperationRow {
+    opId: string;
+    path: string;
+    revision: string;
+    action: string;
+    provider: string;
+    status: string;
+    attemptCount: number;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+    correlationId: string;
+}
+export interface WritebackItem {
+    id: string;
+    workspaceId: string;
+    path: string;
+    revision: string;
+    correlationId: string;
+}
+export interface EnvelopeRow {
+    envelopeId: string;
+    workspaceId: string;
+    provider: string;
+    deliveryId: string;
+    deliveryIds?: string[];
+    receivedAt: string;
+    headers?: Record<string, string>;
+    payload: Record<string, unknown>;
+    correlationId: string;
+    status: string;
+    attemptCount: number;
+    lastError: string | null;
+}
+export interface PaginationOptions {
+    cursor?: string;
+    limit?: number;
+}
+export interface Paginated<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+export interface EnvelopeQueryOptions extends PaginationOptions {
+    workspaceId?: string;
+    provider?: string;
+    status?: string;
+}
+export interface StorageAdapter {
+    getFile(path: string): FileRow | null;
+    listFiles(): FileRow[];
+    putFile(file: FileRow): void;
+    deleteFile(path: string): void;
+    loadFileContent?(file: FileRow): {
+        content: string;
+        encoding?: string;
+    } | string;
+    appendEvent(event: EventRow): void;
+    listEvents(options: PaginationOptions & {
+        provider?: string;
+    }): Paginated<EventRow>;
+    getRecentEvents(limit: number): EventRow[];
+    getOperation(opId: string): OperationRow | null;
+    putOperation(op: OperationRow): void;
+    listOperations(options: PaginationOptions & {
+        status?: string;
+        action?: string;
+        provider?: string;
+    }): Paginated<OperationRow>;
+    nextRevision(): string;
+    nextOperationId(): string;
+    nextEventId(): string;
+    enqueueWriteback(item: WritebackItem): void;
+    getPendingWritebacks(): WritebackItem[];
+    getEnvelopeByDelivery?(workspaceId: string, provider: string, deliveryId: string): EnvelopeRow | null;
+    putEnvelope?(envelope: EnvelopeRow): void;
+    putEnvelopeDeliveryAlias?(workspaceId: string, provider: string, deliveryId: string, envelopeId: string): void;
+    listEnvelopes?(options: EnvelopeQueryOptions): Paginated<EnvelopeRow>;
+    getWorkspaceId(): string;
+}

package/dist/storage.js

@@ -0,0 +1,9 @@
+/**
+ * Storage adapter interface.
+ *
+ * All core logic functions accept a storage adapter — they never do I/O directly.
+ * Implementors provide the actual storage (DO SQLite, Go in-memory, Postgres, etc.).
+ *
+ * Methods return plain data. Errors are signaled via return values, not exceptions.
+ */
+export {};

package/dist/tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tree listing and directory traversal.
+ *
+ * Extract from workspace.ts:
+ *   - listTree() / handleListTree()
+ *   - directory inference from file paths
+ *   - depth limiting
+ *   - cursor pagination
+ *   - ancestor/descendant path utilities
+ */
+import type { StorageAdapter, PaginationOptions } from "./storage.js";
+import { type TokenClaims } from "./acl.js";
+export interface TreeEntry {
+    path: string;
+    type: "file" | "dir";
+    revision?: string;
+    provider?: string;
+    size?: number;
+    updatedAt?: string;
+    propertyCount?: number;
+    relationCount?: number;
+    commentCount?: number;
+}
+export interface TreeResult {
+    path: string;
+    entries: TreeEntry[];
+    nextCursor: string | null;
+}
+export interface ListTreeOptions extends PaginationOptions {
+    path?: string;
+    depth?: number;
+}
+export declare function listTree(storage: StorageAdapter, options: ListTreeOptions, claims: TokenClaims | null): TreeResult;
+export declare function ancestorDirectories(path: string): string[];
+export declare function joinPath(dir: string, filename: string): string;

package/dist/tree.js

@@ -0,0 +1,106 @@
+/**
+ * Tree listing and directory traversal.
+ *
+ * Extract from workspace.ts:
+ *   - listTree() / handleListTree()
+ *   - directory inference from file paths
+ *   - depth limiting
+ *   - cursor pagination
+ *   - ancestor/descendant path utilities
+ */
+import { filePermissionAllows, resolveFilePermissions, } from "./acl.js";
+export function listTree(storage, options, claims) {
+    const base = normalizePath(options.path ?? "/");
+    const maxDepth = options.depth && options.depth > 0 ? options.depth : 1;
+    const workspaceId = storage.getWorkspaceId();
+    const entryMap = new Map();
+    for (const row of storage.listFiles()) {
+        const filePath = normalizePath(row.path);
+        if (filePath === base || !isWithinBase(filePath, base)) {
+            continue;
+        }
+        if (!filePermissionAllows(resolveFilePermissions(storage, filePath, true), workspaceId, claims)) {
+            continue;
+        }
+        const rest = filePath.slice(base === "/" ? 1 : base.length + 1);
+        if (!rest) {
+            continue;
+        }
+        const parts = rest.split("/").filter(Boolean);
+        for (let level = 1; level <= Math.min(parts.length, maxDepth); level += 1) {
+            const childPath = joinPath(base, parts.slice(0, level).join("/"));
+            if (level === parts.length) {
+                entryMap.set(childPath, {
+                    path: childPath,
+                    type: "file",
+                    revision: row.revision,
+                    provider: row.provider,
+                    size: encodedSize(row.content, row.encoding),
+                    updatedAt: row.lastEditedAt,
+                    propertyCount: Object.keys(row.semantics.properties ?? {}).length,
+                    relationCount: row.semantics.relations?.length ?? 0,
+                    commentCount: row.semantics.comments?.length ?? 0,
+                });
+            }
+            else if (!entryMap.has(childPath)) {
+                entryMap.set(childPath, {
+                    path: childPath,
+                    type: "dir",
+                    revision: "dir",
+                });
+            }
+        }
+    }
+    let entries = Array.from(entryMap.values()).sort((left, right) => left.path.localeCompare(right.path));
+    if (options.cursor) {
+        const index = entries.findIndex((entry) => entry.path === options.cursor);
+        if (index >= 0) {
+            entries = entries.slice(index + 1);
+        }
+    }
+    return {
+        path: base,
+        entries,
+        nextCursor: null,
+    };
+}
+export function ancestorDirectories(path) {
+    const normalized = normalizePath(path);
+    const parts = normalized.split("/").filter(Boolean);
+    const dirs = ["/"];
+    let current = "";
+    for (let index = 0; index < Math.max(0, parts.length - 1); index += 1) {
+        current = joinPath(current || "/", parts[index] ?? "");
+        dirs.push(current);
+    }
+    return dirs;
+}
+export function joinPath(dir, filename) {
+    const normalizedDir = normalizePath(dir);
+    return normalizedDir === "/"
+        ? normalizePath(`/${filename}`)
+        : normalizePath(`${normalizedDir}/${filename}`);
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return "/";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : "/";
+}
+function isWithinBase(path, base) {
+    return base === "/" ? path.startsWith("/") : path.startsWith(`${base}/`);
+}
+function encodedSize(content, encoding) {
+    if (encoding === "base64") {
+        try {
+            return Uint8Array.from(atob(content), (char) => char.charCodeAt(0))
+                .byteLength;
+        }
+        catch {
+            return content.length;
+        }
+    }
+    return new TextEncoder().encode(content).byteLength;
+}

package/dist/utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared utility functions used across core modules.
+ *
+ * Centralises helpers that were previously copy-pasted in
+ * files.ts, query.ts, tree.ts, operations.ts, acl.ts, and writeback.ts.
+ */
+/**
+ * Normalize a file path: ensure leading slash, strip trailing slashes,
+ * and resolve `.` and `..` segments to prevent path traversal attacks.
+ */
+export declare function normalizePath(path: string): string;

package/dist/utils.js

@@ -0,0 +1,32 @@
+/**
+ * Shared utility functions used across core modules.
+ *
+ * Centralises helpers that were previously copy-pasted in
+ * files.ts, query.ts, tree.ts, operations.ts, acl.ts, and writeback.ts.
+ */
+/**
+ * Normalize a file path: ensure leading slash, strip trailing slashes,
+ * and resolve `.` and `..` segments to prevent path traversal attacks.
+ */
+export function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return "/";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    // Split into segments and resolve . and .. to prevent path traversal
+    const segments = [];
+    for (const segment of prefixed.split("/")) {
+        if (segment === "." || segment === "") {
+            continue;
+        }
+        if (segment === "..") {
+            segments.pop();
+        }
+        else {
+            segments.push(segment);
+        }
+    }
+    const resolved = "/" + segments.join("/");
+    return resolved.length > 1 ? resolved.replace(/\/+$/, "") : "/";
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Webhook envelope normalization and processing.
+ *
+ * Extract from workspace.ts:
+ *   - generic webhook ingestion
+ *   - envelope normalization
+ *   - deduplication by delivery_id
+ *   - coalescing within time window
+ *   - suppression for loop prevention
+ *   - stale event filtering
+ *   - file materialization from webhook data
+ *
+ * This module stays pure. It only operates over plain storage records and
+ * optional callbacks for suppression/staleness policy.
+ */
+import type { StorageAdapter, EnvelopeRow, EnvelopeQueryOptions, Paginated, FileSemantics } from "./storage.js";
+export interface IngestWebhookInput {
+    provider: string;
+    eventType?: string;
+    path?: string;
+    data?: Record<string, unknown>;
+    deliveryId?: string;
+    timestamp?: string;
+    headers?: Record<string, string>;
+    correlationId?: string;
+}
+export interface IngestResult {
+    status: string;
+    envelopeId: string;
+    correlationId: string;
+}
+export interface EnvelopeEvent {
+    type: string;
+    path: string;
+    timestamp: string;
+    content?: string;
+    contentType?: string;
+    encoding?: string;
+    semantics?: FileSemantics;
+    data?: Record<string, unknown>;
+}
+export interface ApplyEnvelopeOptions {
+    now?: () => string;
+    shouldSuppress?: (envelope: EnvelopeRow, event: EnvelopeEvent) => boolean;
+    isStale?: (envelope: EnvelopeRow, event: EnvelopeEvent) => boolean;
+    /**
+     * Optional ACL enforcement callback. When provided, called before file
+     * writes with the target path. Return `true` to allow, `false` to deny.
+     * If denied, the envelope is marked as "ignored".
+     */
+    isPathWriteAllowed?: (path: string) => boolean;
+}
+export interface ApplyEnvelopeResult {
+    status: "processed" | "ignored" | "suppressed" | "stale" | "rejected";
+    eventType: string | null;
+    path: string | null;
+    revision: string | null;
+    reason?: string;
+}
+export interface IngestWebhookOptions {
+    now?: () => string;
+    generateEnvelopeId?: () => string;
+    coalesceWindowMs?: number;
+    /**
+     * Optional signature verification callback. When provided, called with the
+     * raw input before processing. Return `true` if the payload signature is
+     * valid, `false` to reject the webhook. Callers should implement
+     * HMAC/RSA verification in this callback at the HTTP handler layer.
+     */
+    signatureVerifier?: (input: IngestWebhookInput) => boolean;
+}
+export interface WebhookStorageAdapter extends StorageAdapter {
+    getEnvelopeByDelivery(workspaceId: string, provider: string, deliveryId: string): EnvelopeRow | null;
+    putEnvelope(envelope: EnvelopeRow): void;
+    putEnvelopeDeliveryAlias?(workspaceId: string, provider: string, deliveryId: string, envelopeId: string): void;
+    listEnvelopes(options: EnvelopeQueryOptions): Paginated<EnvelopeRow>;
+}
+export declare function ingestWebhook(storage: StorageAdapter, input: IngestWebhookInput, options?: IngestWebhookOptions): IngestResult;
+export declare function normalizeEnvelope(input: IngestWebhookInput, now?: () => string): Partial<EnvelopeRow>;
+export declare function normalizeEnvelopeEvent(envelope: Pick<EnvelopeRow, "payload" | "receivedAt">): EnvelopeEvent | null;
+export declare function normalizeEnvelopePath(envelope: Pick<EnvelopeRow, "payload">): string | null;
+export declare function applyWebhookEnvelope(storage: StorageAdapter, envelope: EnvelopeRow, options?: ApplyEnvelopeOptions): ApplyEnvelopeResult;