@relayfile/core 0.1.0

package/dist/acl.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ACL permission resolution and enforcement.
+ *
+ * Extract from workspace.ts:
+ *   - resolveFilePermissions() — walk ancestor dirs for .relayfile.acl markers
+ *   - parsePermissionRule() — parse "scope:X", "deny:agent:Y", "public", etc.
+ *   - filePermissionAllows() — evaluate allow/deny rules against agent claims
+ */
+import type { StorageAdapter } from "./storage.js";
+export declare const DIRECTORY_PERMISSION_MARKER = ".relayfile.acl";
+export interface TokenClaims {
+    workspaceId: string;
+    agentName: string;
+    scopes: Set<string>;
+}
+export interface ParsedPermissionRule {
+    effect: "allow" | "deny";
+    kind: "scope" | "agent" | "workspace" | "public";
+    value: string;
+}
+export declare function parsePermissionRule(raw: string): ParsedPermissionRule | null;
+/**
+ * Evaluate ACL rules against agent claims.
+ *
+ * Security model: **default-open**. When no permissions array is provided
+ * (or it is empty), access is allowed — this is intentional so that files
+ * without explicit ACL markers remain accessible. When enforceable rules
+ * exist but none match the caller's claims, access is **denied**.
+ *
+ * Callers that need a default-deny posture should ensure every path has
+ * at least one ACL marker in its ancestor directories.
+ */
+export declare function filePermissionAllows(permissions: string[] | undefined, workspaceId: string, claims: TokenClaims | null): boolean;
+export declare function resolveFilePermissions(storage: StorageAdapter, path: string, includeTarget: boolean): string[];

package/dist/acl.js

@@ -0,0 +1,163 @@
+/**
+ * ACL permission resolution and enforcement.
+ *
+ * Extract from workspace.ts:
+ *   - resolveFilePermissions() — walk ancestor dirs for .relayfile.acl markers
+ *   - parsePermissionRule() — parse "scope:X", "deny:agent:Y", "public", etc.
+ *   - filePermissionAllows() — evaluate allow/deny rules against agent claims
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const DIRECTORY_PERMISSION_MARKER = ".relayfile.acl";
+// ---------------------------------------------------------------------------
+// Functions — agent-3: extract from workspace.ts
+// ---------------------------------------------------------------------------
+export function parsePermissionRule(raw) {
+    let rule = raw.trim();
+    if (!rule) {
+        return null;
+    }
+    let effect = "allow";
+    const lower = rule.toLowerCase();
+    if (lower.startsWith("allow:")) {
+        rule = rule.slice("allow:".length).trim();
+    }
+    else if (lower.startsWith("deny:")) {
+        effect = "deny";
+        rule = rule.slice("deny:".length).trim();
+    }
+    const normalized = rule.toLowerCase();
+    if (normalized === "public" || normalized === "any" || normalized === "*") {
+        return { effect, kind: "public", value: "*" };
+    }
+    const [kindRaw, ...rest] = rule.split(":");
+    const kind = kindRaw?.trim().toLowerCase();
+    const value = rest.join(":").trim();
+    if (!kind || !value) {
+        return null;
+    }
+    if (kind !== "scope" && kind !== "agent" && kind !== "workspace") {
+        return null;
+    }
+    return {
+        effect,
+        kind,
+        value,
+    };
+}
+/**
+ * Evaluate ACL rules against agent claims.
+ *
+ * Security model: **default-open**. When no permissions array is provided
+ * (or it is empty), access is allowed — this is intentional so that files
+ * without explicit ACL markers remain accessible. When enforceable rules
+ * exist but none match the caller's claims, access is **denied**.
+ *
+ * Callers that need a default-deny posture should ensure every path has
+ * at least one ACL marker in its ancestor directories.
+ */
+export function filePermissionAllows(permissions, workspaceId, claims) {
+    if (!permissions || permissions.length === 0) {
+        return true;
+    }
+    let enforceableRuleSeen = false;
+    let allowMatch = false;
+    for (const raw of permissions) {
+        const rule = parsePermissionRule(raw);
+        if (!rule) {
+            continue;
+        }
+        enforceableRuleSeen = true;
+        let match = false;
+        switch (rule.kind) {
+            case "public":
+                match = true;
+                break;
+            case "scope":
+                match = claims?.scopes.has(rule.value) ?? false;
+                break;
+            case "agent":
+                match = claims?.agentName === rule.value;
+                break;
+            case "workspace":
+                match = workspaceId === rule.value;
+                break;
+        }
+        if (!match) {
+            continue;
+        }
+        if (rule.effect === "deny") {
+            return false;
+        }
+        allowMatch = true;
+    }
+    if (allowMatch) {
+        return true;
+    }
+    return !enforceableRuleSeen;
+}
+export function resolveFilePermissions(storage, path, includeTarget) {
+    const target = normalizePath(path);
+    const permissions = [];
+    for (const dir of ancestorDirectories(target)) {
+        const markerPath = joinPath(dir, DIRECTORY_PERMISSION_MARKER);
+        if (markerPath === target) {
+            continue;
+        }
+        const marker = storage.getFile(markerPath);
+        if (!marker) {
+            continue;
+        }
+        if ((marker.semantics.permissions?.length ?? 0) === 0) {
+            continue;
+        }
+        permissions.push(...(marker.semantics.permissions ?? []));
+    }
+    if (includeTarget) {
+        const file = storage.getFile(target);
+        if (file && (file.semantics.permissions?.length ?? 0) > 0) {
+            permissions.push(...(file.semantics.permissions ?? []));
+        }
+    }
+    return permissions;
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed) {
+        return "/";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    const parts = prefixed.split("/");
+    const resolved = [];
+    for (const part of parts) {
+        if (part === "." || part === "") {
+            continue;
+        }
+        else if (part === "..") {
+            resolved.pop();
+        }
+        else {
+            resolved.push(part);
+        }
+    }
+    const result = "/" + resolved.join("/");
+    return result.length > 1 ? result.replace(/\/+$/, "") : "/";
+}
+function joinPath(base, child) {
+    const normalizedBase = normalizePath(base);
+    return normalizedBase === "/"
+        ? normalizePath(`/${child}`)
+        : normalizePath(`${normalizedBase}/${child}`);
+}
+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;
+}

package/dist/events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Event recording and feed.
+ *
+ * Extract from workspace.ts:
+ *   - event creation during writes/deletes
+ *   - event feed listing with pagination
+ *   - recent events retrieval (for WebSocket catch-up)
+ */
+import type { StorageAdapter, EventRow, Paginated, PaginationOptions } from "./storage.js";
+export interface CreateEventInput {
+    type: string;
+    path: string;
+    revision: string;
+    origin: string;
+    provider: string;
+    correlationId: string;
+    timestamp?: string;
+}
+export declare function createEvent(storage: StorageAdapter, input: CreateEventInput): EventRow;
+export declare function listEvents(storage: StorageAdapter, options: PaginationOptions & {
+    provider?: string;
+}): Paginated<EventRow>;
+export declare function getRecentEvents(storage: StorageAdapter, limit: number): EventRow[];

package/dist/events.js

@@ -0,0 +1,39 @@
+/**
+ * Event recording and feed.
+ *
+ * Extract from workspace.ts:
+ *   - event creation during writes/deletes
+ *   - event feed listing with pagination
+ *   - recent events retrieval (for WebSocket catch-up)
+ */
+export function createEvent(storage, input) {
+    const event = {
+        eventId: storage.nextEventId(),
+        type: input.type,
+        path: input.path,
+        revision: input.revision,
+        origin: input.origin,
+        provider: normalizeProvider(input.provider),
+        correlationId: input.correlationId || "",
+        timestamp: input.timestamp ?? new Date().toISOString(),
+    };
+    storage.appendEvent(event);
+    return event;
+}
+export function listEvents(storage, options) {
+    const provider = normalizeProvider(options.provider);
+    return storage.listEvents({
+        provider: provider || undefined,
+        cursor: options.cursor || undefined,
+        limit: clampLimit(options.limit),
+    });
+}
+export function getRecentEvents(storage, limit) {
+    return storage.getRecentEvents(clampLimit(limit));
+}
+function normalizeProvider(provider) {
+    return provider?.trim().toLowerCase() ?? "";
+}
+function clampLimit(limit) {
+    return Math.max(1, Math.min(limit ?? 200, 1000));
+}

package/dist/export.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Workspace export logic.
+ *
+ * Extract from workspace.ts:
+ *   - JSON export (file list with metadata)
+ *   - tar export (gzipped archive)
+ *   - patch export
+ */
+import type { StorageAdapter, FileRow } from "./storage.js";
+import type { TokenClaims } from "./acl.js";
+export type ExportFormat = "json" | "tar" | "patch";
+export declare function exportWorkspaceJson(storage: StorageAdapter, claims: TokenClaims | null): FileRow[];
+export declare function exportWorkspacePatch(storage: StorageAdapter, claims: TokenClaims | null): string;
+export declare function exportWorkspaceTarGzip(storage: StorageAdapter, claims: TokenClaims | null): Promise<ArrayBuffer>;
+export declare function buildUnifiedPatch(files: FileRow[]): string;
+export declare function buildTarGzip(files: FileRow[]): Promise<ArrayBuffer>;

package/dist/export.js

@@ -0,0 +1,137 @@
+/**
+ * Workspace export logic.
+ *
+ * Extract from workspace.ts:
+ *   - JSON export (file list with metadata)
+ *   - tar export (gzipped archive)
+ *   - patch export
+ */
+import { filePermissionAllows, resolveFilePermissions } from "./acl.js";
+export function exportWorkspaceJson(storage, claims) {
+    const workspaceId = storage.getWorkspaceId();
+    return storage
+        .listFiles()
+        .slice()
+        .sort((left, right) => left.path.localeCompare(right.path))
+        .filter((row) => filePermissionAllows(resolveFilePermissions(storage, row.path, true), workspaceId, claims))
+        .map((row) => materializeFile(storage, row));
+}
+export function exportWorkspacePatch(storage, claims) {
+    return buildUnifiedPatch(exportWorkspaceJson(storage, claims));
+}
+export async function exportWorkspaceTarGzip(storage, claims) {
+    return buildTarGzip(exportWorkspaceJson(storage, claims));
+}
+export function buildUnifiedPatch(files) {
+    if (files.length === 0) {
+        return "";
+    }
+    return files
+        .map((file) => {
+        const lines = file.content.split("\n");
+        return [
+            `--- ${file.path}`,
+            `+++ ${file.path}`,
+            "@@",
+            ...lines.map((line) => `+${line}`),
+        ].join("\n");
+    })
+        .join("\n");
+}
+export async function buildTarGzip(files) {
+    const chunks = [];
+    for (const file of files) {
+        const content = file.encoding === "base64"
+            ? Uint8Array.from(atob(file.content), (char) => char.charCodeAt(0))
+            : new TextEncoder().encode(file.content);
+        const header = buildTarHeader(file.path.replace(/^\/+/, ""), content.byteLength, file.lastEditedAt);
+        chunks.push(header);
+        chunks.push(content);
+        const remainder = content.byteLength % 512;
+        if (remainder > 0) {
+            chunks.push(new Uint8Array(512 - remainder));
+        }
+    }
+    chunks.push(new Uint8Array(1024));
+    const tar = concatBytes(chunks);
+    const sourceBody = new Response(toArrayBuffer(tar)).body;
+    if (!sourceBody) {
+        throw new Error("failed to create readable stream for tar archive");
+    }
+    const compressed = new Response(sourceBody.pipeThrough(new CompressionStream("gzip")));
+    return compressed.arrayBuffer();
+}
+function cloneSemantics(file) {
+    return {
+        properties: file.semantics.properties
+            ? { ...file.semantics.properties }
+            : undefined,
+        relations: file.semantics.relations
+            ? [...file.semantics.relations]
+            : undefined,
+        permissions: file.semantics.permissions
+            ? [...file.semantics.permissions]
+            : undefined,
+        comments: file.semantics.comments ? [...file.semantics.comments] : undefined,
+    };
+}
+function materializeFile(storage, file) {
+    const loaded = storage.loadFileContent?.(file);
+    const contentState = typeof loaded === "string"
+        ? { content: loaded, encoding: file.encoding }
+        : loaded ?? { content: file.content, encoding: file.encoding };
+    return {
+        ...file,
+        content: contentState.content,
+        encoding: contentState.encoding ?? file.encoding,
+        semantics: cloneSemantics(file),
+    };
+}
+function buildTarHeader(name, size, updatedAt) {
+    const header = new Uint8Array(512);
+    writeTarString(header, 0, 100, name.slice(0, 100));
+    writeTarOctal(header, 100, 8, 0o644);
+    writeTarOctal(header, 108, 8, 0);
+    writeTarOctal(header, 116, 8, 0);
+    writeTarOctal(header, 124, 12, size);
+    writeTarOctal(header, 136, 12, Math.floor((updatedAt ? Date.parse(updatedAt) : Date.now()) / 1000));
+    for (let index = 148; index < 156; index += 1) {
+        header[index] = 0x20;
+    }
+    header[156] = "0".charCodeAt(0);
+    writeTarString(header, 257, 6, "ustar");
+    writeTarString(header, 263, 2, "00");
+    const checksum = header.reduce((sum, byte) => sum + byte, 0);
+    writeTarChecksum(header, checksum);
+    return header;
+}
+function writeTarString(buffer, offset, length, value) {
+    const bytes = new TextEncoder().encode(value);
+    buffer.set(bytes.slice(0, length), offset);
+}
+function writeTarOctal(buffer, offset, length, value) {
+    const octal = value.toString(8).padStart(length - 1, "0");
+    writeTarString(buffer, offset, length - 1, octal.slice(-length + 1));
+    buffer[offset + length - 1] = 0;
+}
+function writeTarChecksum(buffer, checksum) {
+    const octal = checksum.toString(8).padStart(6, "0");
+    writeTarString(buffer, 148, 6, octal);
+    buffer[154] = 0;
+    buffer[155] = 0x20;
+}
+function concatBytes(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function toArrayBuffer(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+}

package/dist/files.d.ts

@@ -0,0 +1,66 @@
+/**
+ * File CRUD operations.
+ *
+ * Extract from workspace.ts:
+ *   - handleWriteFile → writeFile()
+ *   - handleReadFile → readFile()
+ *   - handleDeleteFile → deleteFile()
+ *   - normalizeIfMatchHeader → normalizeIfMatch()
+ *   - revision conflict detection
+ *   - content encoding normalization/validation
+ *   - provider inference from path
+ */
+import type { StorageAdapter, FileRow, FileSemantics } from "./storage.js";
+import { normalizePath } from "./utils.js";
+export interface WriteFileRequest {
+    path: string;
+    ifMatch: string;
+    content: string;
+    contentType?: string;
+    encoding?: string;
+    semantics?: FileSemantics;
+    correlationId?: string;
+}
+export interface WriteFileResult {
+    opId: string;
+    status: string;
+    targetRevision: string;
+    writeback: {
+        provider: string;
+        state: string;
+    };
+}
+export interface ConflictError {
+    type: "conflict";
+    expectedRevision: string;
+    currentRevision: string;
+    currentContentPreview?: string;
+}
+export interface DeleteFileRequest {
+    path: string;
+    ifMatch: string;
+    correlationId?: string;
+}
+export type WriteResult = {
+    ok: true;
+    result: WriteFileResult;
+} | {
+    ok: false;
+    error: "not_found" | "missing_precondition" | "invalid_input" | ConflictError;
+};
+export type DeleteResult = {
+    ok: true;
+    result: WriteFileResult;
+} | {
+    ok: false;
+    error: "not_found" | "missing_precondition" | "invalid_input" | ConflictError;
+};
+export declare function normalizeIfMatch(value: string): string;
+export { normalizePath };
+export declare function inferProvider(path: string): string;
+export declare function writeFile(storage: StorageAdapter, req: WriteFileRequest): WriteResult;
+export declare function readFile(storage: StorageAdapter, path: string): FileRow | null;
+export declare function deleteFile(storage: StorageAdapter, req: DeleteFileRequest): DeleteResult;
+export declare const DEFAULT_CONTENT_TYPE = "text/markdown";
+export declare const MAX_FILE_BYTES: number;
+export declare function encodedSize(content: string, encoding: "utf-8" | "base64"): number;