@relayfile/core 0.8.6 → 0.8.8

package/dist/acl.d.ts

@@ -18,6 +18,16 @@ export interface ParsedPermissionRule {
     kind: "scope" | "agent" | "workspace" | "public";
     value: string;
 }
+export interface ScopeMatchContext {
+    workspaceId: string;
+    requestedPath?: string;
+    action?: "read" | "write" | "manage";
+}
+export interface PermissionEvaluationOptions {
+    scopeMatches?: (scope: string, claims: TokenClaims | null, context: ScopeMatchContext) => boolean;
+    requestedPath?: string;
+    action?: "read" | "write" | "manage";
+}
 export declare function parsePermissionRule(raw: string): ParsedPermissionRule | null;
 /**
  * Evaluate ACL rules against agent claims.
@@ -30,5 +40,5 @@ export declare function parsePermissionRule(raw: string): ParsedPermissionRule |
  * 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 filePermissionAllows(permissions: string[] | undefined, workspaceId: string, claims: TokenClaims | null, options?: PermissionEvaluationOptions): boolean;
 export declare function resolveFilePermissions(storage: StorageAdapter, path: string, includeTarget: boolean): string[];

package/dist/acl.js

@@ -57,7 +57,7 @@ export function parsePermissionRule(raw) {
  * 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) {
+export function filePermissionAllows(permissions, workspaceId, claims, options = {}) {
     if (!permissions || permissions.length === 0) {
         return true;
     }
@@ -75,7 +75,13 @@ export function filePermissionAllows(permissions, workspaceId, claims) {
                 match = true;
                 break;
             case "scope":
-                match = claims?.scopes.has(rule.value) ?? false;
+                match = options.scopeMatches
+                    ? options.scopeMatches(rule.value, claims, {
+                        workspaceId,
+                        requestedPath: options.requestedPath,
+                        action: options.action,
+                    })
+                    : (claims?.scopes.has(rule.value) ?? false);
                 break;
             case "agent":
                 match = claims?.agentName === rule.value;

package/dist/acl.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/acl.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import { exportWorkspaceJson } from "./export.js";
+import { queryFiles } from "./query.js";
+import { listTree } from "./tree.js";
+import { filePermissionAllows } from "./acl.js";
+function claimsWith(scopes) {
+    return {
+        workspaceId: "ws_test",
+        agentName: "agent_test",
+        scopes: new Set(scopes),
+    };
+}
+function file(path, permissions = []) {
+    return {
+        path,
+        revision: "rev_1",
+        contentType: "text/markdown",
+        content: "body",
+        encoding: "utf-8",
+        provider: "github",
+        lastEditedAt: "2026-05-31T00:00:00.000Z",
+        semantics: {
+            permissions,
+        },
+    };
+}
+function storage(files) {
+    const byPath = new Map(files.map((entry) => [entry.path, entry]));
+    return {
+        getFile: (path) => byPath.get(path) ?? null,
+        listFiles: () => files,
+        putFile: () => undefined,
+        deleteFile: () => undefined,
+        appendEvent: () => undefined,
+        listEvents: () => ({ items: [], nextCursor: null }),
+        getRecentEvents: () => [],
+        getOperation: () => null,
+        putOperation: () => undefined,
+        listOperations: () => ({ items: [], nextCursor: null }),
+        nextRevision: () => "rev_2",
+        nextOperationId: () => "op_1",
+        nextEventId: () => "evt_1",
+        enqueueWriteback: () => undefined,
+        getPendingWritebacks: () => [],
+        getWorkspaceId: () => "ws_test",
+    };
+}
+describe("ACL scope matching", () => {
+    it("keeps exact scope matching as the default", () => {
+        const claims = claimsWith(["relayfile:fs:read:/github/*"]);
+        expect(filePermissionAllows(["scope:relayfile:fs:read:/github/LAYOUT.md"], "ws_test", claims)).toBe(false);
+        expect(filePermissionAllows(["scope:relayfile:fs:read:/github/*"], "ws_test", claims)).toBe(true);
+    });
+    it("lets callers inject path-aware scope matching for tree, query, and export", () => {
+        const claims = claimsWith(["relayfile:fs:read:/github/*"]);
+        const rows = [
+            file("/.relayfile.acl", ["scope:relayfile:fs:read:/github/LAYOUT.md"]),
+            file("/github/LAYOUT.md"),
+        ];
+        const repo = storage(rows);
+        const scopeMatches = vi.fn((scope, tokenClaims, context) => scope === "relayfile:fs:read:/github/LAYOUT.md" &&
+            tokenClaims?.scopes.has("relayfile:fs:read:/github/*") === true &&
+            context.action === "read" &&
+            context.requestedPath === "/github/LAYOUT.md");
+        expect(listTree(repo, { path: "/github", depth: 1 }, claims).entries).toEqual([]);
+        const aclOptions = { scopeMatches };
+        expect(listTree(repo, { path: "/github", depth: 1 }, claims, aclOptions).entries.map((entry) => entry.path)).toEqual(["/github/LAYOUT.md"]);
+        expect(queryFiles(repo, { path: "/github" }, claims, aclOptions).items.map((entry) => entry.path)).toEqual(["/github/LAYOUT.md"]);
+        expect(exportWorkspaceJson(repo, claims, aclOptions).map((entry) => entry.path)).toEqual([
+            "/github/LAYOUT.md",
+        ]);
+        expect(scopeMatches).toHaveBeenCalled();
+    });
+});

package/dist/export.d.ts

@@ -7,10 +7,10 @@
  *   - patch export
  */
 import type { StorageAdapter, FileRow } from "./storage.js";
-import type { TokenClaims } from "./acl.js";
+import type { PermissionEvaluationOptions, 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 exportWorkspaceJson(storage: StorageAdapter, claims: TokenClaims | null, aclOptions?: PermissionEvaluationOptions): FileRow[];
+export declare function exportWorkspacePatch(storage: StorageAdapter, claims: TokenClaims | null, aclOptions?: PermissionEvaluationOptions): string;
+export declare function exportWorkspaceTarGzip(storage: StorageAdapter, claims: TokenClaims | null, aclOptions?: PermissionEvaluationOptions): Promise<ArrayBuffer>;
 export declare function buildUnifiedPatch(files: FileRow[]): string;
 export declare function buildTarGzip(files: FileRow[]): Promise<ArrayBuffer>;

package/dist/export.js

@@ -7,20 +7,24 @@
  *   - patch export
  */
 import { filePermissionAllows, resolveFilePermissions } from "./acl.js";
-export function exportWorkspaceJson(storage, claims) {
+export function exportWorkspaceJson(storage, claims, aclOptions = {}) {
     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))
+        .filter((row) => filePermissionAllows(resolveFilePermissions(storage, row.path, true), workspaceId, claims, {
+        ...aclOptions,
+        action: aclOptions.action ?? "read",
+        requestedPath: row.path,
+    }))
         .map((row) => materializeFile(storage, row));
 }
-export function exportWorkspacePatch(storage, claims) {
-    return buildUnifiedPatch(exportWorkspaceJson(storage, claims));
+export function exportWorkspacePatch(storage, claims, aclOptions = {}) {
+    return buildUnifiedPatch(exportWorkspaceJson(storage, claims, aclOptions));
 }
-export async function exportWorkspaceTarGzip(storage, claims) {
-    return buildTarGzip(exportWorkspaceJson(storage, claims));
+export async function exportWorkspaceTarGzip(storage, claims, aclOptions = {}) {
+    return buildTarGzip(exportWorkspaceJson(storage, claims, aclOptions));
 }
 export function buildUnifiedPatch(files) {
     if (files.length === 0) {

package/dist/query.d.ts

@@ -7,7 +7,7 @@
  *   - cursor pagination
  */
 import type { StorageAdapter, Paginated, PaginationOptions } from "./storage.js";
-import { type TokenClaims } from "./acl.js";
+import { type PermissionEvaluationOptions, type TokenClaims } from "./acl.js";
 export interface QueryOptions extends PaginationOptions {
     path?: string;
     provider?: string;
@@ -27,4 +27,4 @@ export interface QueryResultItem {
     relations?: string[];
     comments?: string[];
 }
-export declare function queryFiles(storage: StorageAdapter, options: QueryOptions, claims: TokenClaims | null): Paginated<QueryResultItem>;
+export declare function queryFiles(storage: StorageAdapter, options: QueryOptions, claims: TokenClaims | null, aclOptions?: PermissionEvaluationOptions): Paginated<QueryResultItem>;

package/dist/query.js

@@ -7,7 +7,7 @@
  *   - cursor pagination
  */
 import { filePermissionAllows, resolveFilePermissions, } from "./acl.js";
-export function queryFiles(storage, options, claims) {
+export function queryFiles(storage, options, claims, aclOptions = {}) {
     const base = normalizePath(options.path ?? "/");
     const provider = normalizeProvider(options.provider);
     const relation = options.relation?.trim() ?? "";
@@ -47,7 +47,11 @@ export function queryFiles(storage, options, claims) {
         if (!propertiesMatch(semantics.properties, expectedProperties)) {
             continue;
         }
-        if (!filePermissionAllows(effectivePermissions, workspaceId, claims)) {
+        if (!filePermissionAllows(effectivePermissions, workspaceId, claims, {
+            ...aclOptions,
+            action: aclOptions.action ?? "read",
+            requestedPath: row.path,
+        })) {
             continue;
         }
         items.push({

package/dist/tree.d.ts

@@ -9,7 +9,7 @@
  *   - ancestor/descendant path utilities
  */
 import type { StorageAdapter, PaginationOptions } from "./storage.js";
-import { type TokenClaims } from "./acl.js";
+import { type PermissionEvaluationOptions, type TokenClaims } from "./acl.js";
 export interface TreeEntry {
     path: string;
     type: "file" | "dir";
@@ -30,6 +30,6 @@ export interface ListTreeOptions extends PaginationOptions {
     path?: string;
     depth?: number;
 }
-export declare function listTree(storage: StorageAdapter, options: ListTreeOptions, claims: TokenClaims | null): TreeResult;
+export declare function listTree(storage: StorageAdapter, options: ListTreeOptions, claims: TokenClaims | null, aclOptions?: PermissionEvaluationOptions): TreeResult;
 export declare function ancestorDirectories(path: string): string[];
 export declare function joinPath(dir: string, filename: string): string;

package/dist/tree.js

@@ -9,7 +9,7 @@
  *   - ancestor/descendant path utilities
  */
 import { filePermissionAllows, resolveFilePermissions, } from "./acl.js";
-export function listTree(storage, options, claims) {
+export function listTree(storage, options, claims, aclOptions = {}) {
     const base = normalizePath(options.path ?? "/");
     const maxDepth = options.depth && options.depth > 0 ? options.depth : 1;
     const workspaceId = storage.getWorkspaceId();
@@ -19,7 +19,11 @@ export function listTree(storage, options, claims) {
         if (filePath === base || !isWithinBase(filePath, base)) {
             continue;
         }
-        if (!filePermissionAllows(resolveFilePermissions(storage, filePath, true), workspaceId, claims)) {
+        if (!filePermissionAllows(resolveFilePermissions(storage, filePath, true), workspaceId, claims, {
+            ...aclOptions,
+            action: aclOptions.action ?? "read",
+            requestedPath: filePath,
+        })) {
             continue;
         }
         const rest = filePath.slice(base === "/" ? 1 : base.length + 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/core",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Shared business logic for relayfile — file operations, ACL, queries, events, and writeback lifecycle",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",