Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(desktop): r1-h3 retain inherited members at visibility boundaries

Mc584fc735b4f
diff --git a/desktop-app/ui/src/gfs/__fixtures__/gfsProducerFixtures.ts b/desktop-app/ui/src/gfs/__fixtures__/gfsProducerFixtures.ts
index 62e9b8275..c8d4fa9d6 100644
--- a/desktop-app/ui/src/gfs/__fixtures__/gfsProducerFixtures.ts
+++ b/desktop-app/ui/src/gfs/__fixtures__/gfsProducerFixtures.ts
@@ -40,7 +40,9 @@ import {
type GfsAccessibleResource,
type GfsChildView,
GfsClient,
+ type GfsGrantListItem,
type GfsHeldAffordances,
+ type GfsShareListItem,
type GfsTransport,
type ResolvedGfsResource,
} from '../../../../src/gfs/uriHandler.js'
@@ -352,3 +354,98 @@ export async function affordancesTransportFailureMessage(): Promise<string> {
return error.message
}
}
+
+// ── ACL list fixtures (R1-H3 inherited-access walk) ──────────────────────────
+// Appended without touching the H1/H8 helpers above; distinct names.
+
+/**
+ * Run grant rows through the real `GfsClient.listGrants` (envelope unwrap +
+ * items-array validation) and the IPC structured-clone boundary — the exact
+ * value `window.clerum.gfs.listGrants` resolves with in production. Bound to
+ * the renderer `.d.ts` return type so producer/renderer drift fails the
+ * typecheck, like the builders above.
+ */
+export async function grantsListPage(
+ items: GfsGrantListItem[]
+): Promise<Awaited<ReturnType<typeof window.clerum.gfs.listGrants>>> {
+ const client = new GfsClient(stubTransport({ items }))
+ return structuredClone(await client.listGrants({ resourceId: 'fixture-parent' }, SESSION_TOKEN))
+}
+
+/** Same as `grantsListPage` for the shares list. */
+export async function sharesListPage(
+ items: GfsShareListItem[]
+): Promise<Awaited<ReturnType<typeof window.clerum.gfs.listShares>>> {
+ const client = new GfsClient(stubTransport({ items }))
+ return structuredClone(await client.listShares({ resourceId: 'fixture-parent' }, SESSION_TOKEN))
+}
+
+/**
+ * The Error message a GfsClient read route rejects with when the server answers
+ * a non-2xx — derived, not hand-written (T1), at the same honest seam as
+ * `resolveDeniedMessage`/`affordancesFailureMessage`: a temp HTTP endpoint
+ * returns the gfsc error envelope, the real `httpClient.requestJson` mints the
+ * `ApiError`, and `surfaceGfsGrantError` appends the vetted `httpStatus=` (and
+ * `retryAfterSeconds=`) markers the renderer classifies on. Generalized over
+ * the invoked client method; the ACL wrappers below keep call sites readable.
+ */
+export async function gfsRouteFailureMessage(
+ invoke: (client: GfsClient) => Promise<unknown>,
+ status = 403,
+ body: { code: string; message: string } = {
+ code: 'forbidden',
+ message: 'not authorized',
+ }
+): Promise<string> {
+ const server = createServer((_req, res) => {
+ res.writeHead(status, { 'content-type': 'application/json' })
+ res.end(JSON.stringify({ ok: false, error: body }))
+ })
+ await new Promise<void>(resolve => server.listen(0, '127.0.0.1', () => resolve()))
+ try {
+ const address = server.address()
+ const port = typeof address === 'object' && address ? address.port : 0
+ const client = new GfsClient({
+ baseUrl: `http://127.0.0.1:${port}`,
+ requestJson,
+ fetchBytes: async () => new ArrayBuffer(0),
+ })
+ await invoke(client)
+ throw new Error(`expected the gfs route to reject with a ${status} failure`)
+ } catch (error) {
+ if (!(error instanceof Error)) return String(error)
+ return error.message
+ } finally {
+ await new Promise<void>(resolve => server.close(() => resolve()))
+ }
+}
+
+/** Producer-derived grants-list rejection (default: a 403 manage_acl denial). */
+export async function listGrantsFailureMessage(
+ status = 403,
+ body: { code: string; message: string } = {
+ code: 'manage_acl_required',
+ message: 'viewing the access list requires manage_acl',
+ }
+): Promise<string> {
+ return gfsRouteFailureMessage(
+ client => client.listGrants({ resourceId: 'fixture-parent' }, SESSION_TOKEN),
+ status,
+ body
+ )
+}
+
+/** Producer-derived shares-list rejection (default: a 403 manage_acl denial). */
+export async function listSharesFailureMessage(
+ status = 403,
+ body: { code: string; message: string } = {
+ code: 'manage_acl_required',
+ message: 'viewing the share list requires manage_acl',
+ }
+): Promise<string> {
+ return gfsRouteFailureMessage(
+ client => client.listShares({ resourceId: 'fixture-parent' }, SESSION_TOKEN),
+ status,
+ body
+ )
+}
diff --git a/desktop-app/ui/src/gfs/__tests__/inheritedAccess.test.ts b/desktop-app/ui/src/gfs/__tests__/inheritedAccess.test.ts
index f01ef0aab..adcb958d2 100644
--- a/desktop-app/ui/src/gfs/__tests__/inheritedAccess.test.ts
+++ b/desktop-app/ui/src/gfs/__tests__/inheritedAccess.test.ts
@@ -1,5 +1,14 @@
// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+ grantsListPage,
+ listGrantsFailureMessage,
+ listSharesFailureMessage,
+ resolveDeniedMessage,
+ resolveResource,
+ resolvedDirectory,
+ sharesListPage,
+} from '../__fixtures__/gfsProducerFixtures'
import { deriveGfsInheritedAccess } from '../inheritedAccess'
/** Walk shape: file → team-docs (inheriting grants) → drive root (share). */
@@ -98,9 +107,10 @@ describe('deriveGfsInheritedAccess', () => {
: []
)
- const items = await deriveGfsInheritedAccess(FILE_ID)
+ const result = await deriveGfsInheritedAccess(FILE_ID)
- expect(items).toEqual([
+ expect(result.coverage).toBe('complete')
+ expect(result.items).toEqual([
{
subject: { type: 'user', id: 'miguel' },
permissions: ['read', 'write'],
@@ -133,53 +143,320 @@ describe('deriveGfsInheritedAccess', () => {
])
})
- it('fails the derivation when a required ancestor cannot be resolved', async () => {
- const listGrants = vi.fn(async () => {
- throw new Error('403 manage_acl_required')
+ // R1-H3: a 403 resolve above the readable chain is an expected privacy
+ // boundary, not a derivation failure — the rows folded from the readable
+ // chain are retained and the coverage tells the UI which notice to show.
+ it('retains known rows with read-boundary coverage when resolve 403s above the readable chain', async () => {
+ const rootDenied = await resolveDeniedMessage(`gfs://main/${ROOT_ID.replace(/-/g, '')}`, {
+ code: 'forbidden',
+ message: 'not authorized to read this resource',
})
+ const listGrants = vi.fn(async () =>
+ grantsListPage([
+ {
+ id: 'g1',
+ drive: 'main',
+ resourceId: FOLDER_ID,
+ subject: { type: 'user', id: 'miguel' },
+ permissions: ['read', 'write'],
+ inherit: true,
+ },
+ ])
+ )
installClerumGfs(
async uri => {
if (uri.endsWith(FILE_ID.replace(/-/g, ''))) {
return resolveView(FILE_ID, 'report.md', FOLDER_ID, 'file')
}
if (uri.endsWith(FOLDER_ID.replace(/-/g, ''))) {
- throw new Error('403 forbidden')
+ return resolveView(FOLDER_ID, 'team-docs', ROOT_ID)
}
- return null
+ throw new Error(rootDenied)
},
listGrants,
- async () => []
+ async () => sharesListPage([])
)
- await expect(deriveGfsInheritedAccess(FILE_ID)).rejects.toThrow(
- 'inherited_access_derivation_failed'
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('read-boundary')
+ expect(result.items).toEqual([
+ {
+ subject: { type: 'user', id: 'miguel' },
+ permissions: ['read', 'write'],
+ inheritedFrom: ['team-docs'],
+ sources: [
+ {
+ resourceId: FOLDER_ID,
+ name: 'team-docs',
+ permissions: ['read', 'write'],
+ grantId: 'g1',
+ shareIds: [],
+ },
+ ],
+ },
+ ])
+ // The unreadable boundary is never asked for its ACL rows.
+ expect(listGrants).toHaveBeenCalledTimes(1)
+ })
+
+ // R1-H3: grants and shares settle INDEPENDENTLY. A 403 on one family keeps
+ // the other family's rows, and the walk continues upward because the
+ // readable ancestor's parent id is already known from its resolve.
+ it('folds the healthy family and continues past an ACL-denied family', async () => {
+ const folder = await resolveResource(
+ resolvedDirectory(FOLDER_ID, 'team-docs', { parentResourceId: ROOT_ID })
+ )
+ const root = await resolveResource(resolvedDirectory(ROOT_ID, '', { parentResourceId: null }))
+ const grantsDenied = await listGrantsFailureMessage()
+ installClerumGfs(
+ async uri => {
+ if (uri.endsWith(FILE_ID.replace(/-/g, ''))) {
+ return resolveResource(
+ resolvedDirectory(FILE_ID, 'report.md', { parentResourceId: FOLDER_ID })
+ )
+ }
+ if (uri.endsWith(FOLDER_ID.replace(/-/g, ''))) return folder
+ if (uri.endsWith(ROOT_ID.replace(/-/g, ''))) return root
+ return null
+ },
+ async resourceId => {
+ if (resourceId === FOLDER_ID) throw new Error(grantsDenied)
+ return grantsListPage([
+ {
+ id: 'g-root',
+ drive: 'main',
+ resourceId: ROOT_ID,
+ subject: { type: 'user', id: 'marcela' },
+ permissions: ['read'],
+ inherit: true,
+ },
+ ])
+ },
+ async resourceId =>
+ resourceId === FOLDER_ID
+ ? sharesListPage([
+ {
+ id: 's1',
+ drive: 'main',
+ resourceId: FOLDER_ID,
+ subject: { type: 'team', id: 'research' },
+ permissions: ['read'],
+ includeDescendants: true,
+ },
+ ])
+ : sharesListPage([])
+ )
+
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('acl-limited')
+ // The folder's SHARES survived its grants denial; the root was still
+ // visited because the folder's parent was known from its resolve.
+ expect(result.items).toEqual([
+ {
+ subject: { type: 'team', id: 'research' },
+ permissions: ['read'],
+ inheritedFrom: ['team-docs'],
+ sources: [
+ {
+ resourceId: FOLDER_ID,
+ name: 'team-docs',
+ permissions: ['read'],
+ grantId: null,
+ shareIds: ['s1'],
+ },
+ ],
+ },
+ {
+ subject: { type: 'user', id: 'marcela' },
+ permissions: ['read'],
+ inheritedFrom: ['main'],
+ sources: [
+ {
+ resourceId: ROOT_ID,
+ name: 'main',
+ permissions: ['read'],
+ grantId: 'g-root',
+ shareIds: [],
+ },
+ ],
+ },
+ ])
+ })
+
+ it('stops with unavailable coverage but retained rows when an ACL read is rate limited', async () => {
+ const grantsLimited = await listGrantsFailureMessage(429, {
+ code: 'rate_limited',
+ message: 'too many requests',
+ })
+ installClerumGfs(
+ async uri => {
+ if (uri.endsWith(FILE_ID.replace(/-/g, ''))) {
+ return resolveView(FILE_ID, 'report.md', FOLDER_ID, 'file')
+ }
+ if (uri.endsWith(FOLDER_ID.replace(/-/g, ''))) {
+ return resolveView(FOLDER_ID, 'team-docs', ROOT_ID)
+ }
+ return null
+ },
+ async () => {
+ throw new Error(grantsLimited)
+ },
+ async resourceId =>
+ resourceId === FOLDER_ID
+ ? [
+ {
+ id: 's1',
+ drive: 'main',
+ resourceId: FOLDER_ID,
+ subject: { type: 'team', id: 'research' },
+ permissions: ['read'],
+ includeDescendants: true,
+ },
+ ]
+ : []
)
- expect(listGrants).not.toHaveBeenCalled()
+
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('unavailable')
+ expect(result.items).toEqual([
+ {
+ subject: { type: 'team', id: 'research' },
+ permissions: ['read'],
+ inheritedFrom: ['team-docs'],
+ sources: [
+ {
+ resourceId: FOLDER_ID,
+ name: 'team-docs',
+ permissions: ['read'],
+ grantId: null,
+ shareIds: ['s1'],
+ },
+ ],
+ },
+ ])
})
- it('fails the derivation when a resolved ancestor ACL cannot be listed', async () => {
+ it.each(['resolve', 'grants', 'shares'] as const)(
+ 'rethrows a session 401 from %s instead of classifying it as a boundary',
+ async family => {
+ const message =
+ family === 'resolve'
+ ? await resolveDeniedMessage(
+ `gfs://main/${FOLDER_ID.replace(/-/g, '')}`,
+ {
+ code: 'unauthorized',
+ message: 'session rejected',
+ },
+ 401
+ )
+ : family === 'grants'
+ ? await listGrantsFailureMessage(401, {
+ code: 'unauthorized',
+ message: 'session rejected',
+ })
+ : await listSharesFailureMessage(401, {
+ code: 'unauthorized',
+ message: 'session rejected',
+ })
+ installClerumGfs(
+ async uri => {
+ if (uri.endsWith(FILE_ID.replace(/-/g, ''))) {
+ return resolveView(FILE_ID, 'report.md', FOLDER_ID, 'file')
+ }
+ throw new Error(message)
+ },
+ async () => {
+ throw new Error(message)
+ },
+ async () => {
+ throw new Error(message)
+ }
+ )
+
+ await expect(deriveGfsInheritedAccess(FILE_ID)).rejects.toThrow('httpStatus=401')
+ }
+ )
+
+ it('reports a parent cycle as unavailable without losing folded rows', async () => {
installClerumGfs(
async uri => {
if (uri.endsWith(FILE_ID.replace(/-/g, ''))) {
return resolveView(FILE_ID, 'report.md', FOLDER_ID, 'file')
}
if (uri.endsWith(FOLDER_ID.replace(/-/g, ''))) {
+ // ROOT's parent points back at FOLDER — a corrupted chain.
return resolveView(FOLDER_ID, 'team-docs', ROOT_ID)
}
if (uri.endsWith(ROOT_ID.replace(/-/g, ''))) {
- return resolveView(ROOT_ID, '', null)
+ return resolveView(ROOT_ID, '', FOLDER_ID)
}
return null
},
- async () => {
- throw new Error('403 manage_acl_required')
+ async resourceId =>
+ resourceId === FOLDER_ID
+ ? [
+ {
+ id: 'g1',
+ drive: 'main',
+ resourceId: FOLDER_ID,
+ subject: { type: 'user', id: 'miguel' },
+ permissions: ['read'],
+ inherit: true,
+ },
+ ]
+ : [],
+ async () => []
+ )
+
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('unavailable')
+ expect(result.items).toHaveLength(1)
+ expect(result.items[0]?.subject).toEqual({ type: 'user', id: 'miguel' })
+ })
+
+ it('reports the depth cap instead of inventing root completion', async () => {
+ // An endless parent chain (depth0 → depth1 → …) never repeats and never
+ // reaches a null parent: the walk must report the cap, never 'complete'.
+ // Ids carry no dashes — the walk rid-strips them before resolving.
+ const targetDepthParent = 'depth0'
+ installClerumGfs(
+ async uri => {
+ const rid = uri.split('/').at(-1) ?? ''
+ if (rid === FILE_ID.replace(/-/g, '')) {
+ return resolveView(FILE_ID, 'report.md', targetDepthParent, 'file')
+ }
+ const match = /^depth(\d+)$/.exec(rid)
+ if (match) return resolveView(rid, `folder-${match[1]}`, `depth${Number(match[1]) + 1}`)
+ return null
},
+ async () => [],
async () => []
)
- await expect(deriveGfsInheritedAccess(FILE_ID)).rejects.toThrow(
- 'inherited_access_derivation_failed'
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('unavailable')
+ expect(result.items).toEqual([])
+ })
+
+ it('maps an unreadable target to read-boundary with no rows', async () => {
+ const targetDenied = await resolveDeniedMessage(`gfs://main/${FILE_ID.replace(/-/g, '')}`)
+ installClerumGfs(
+ async () => {
+ throw new Error(targetDenied)
+ },
+ async () => [],
+ async () => []
)
+
+ const result = await deriveGfsInheritedAccess(FILE_ID)
+
+ expect(result.coverage).toBe('read-boundary')
+ expect(result.items).toEqual([])
})
it('merges one subject inherited through multiple folders into a single strongest-source row', async () => {
@@ -212,10 +489,11 @@ describe('deriveGfsInheritedAccess', () => {
async () => []
)
- const items = await deriveGfsInheritedAccess(FILE_ID)
+ const result = await deriveGfsInheritedAccess(FILE_ID)
- expect(items).toHaveLength(1)
- const merged = items[0]
+ expect(result.coverage).toBe('complete')
+ expect(result.items).toHaveLength(1)
+ const merged = result.items[0]
expect(merged?.permissions.sort()).toEqual(['read', 'share', 'write'])
expect(merged?.inheritedFrom).toEqual(['team-docs', 'main'])
// R1-H1: EVERY contributing folder is kept, nearest first — the nearest
@@ -280,10 +558,11 @@ describe('deriveGfsInheritedAccess', () => {
: []
)
- const items = await deriveGfsInheritedAccess(FILE_ID)
+ const result = await deriveGfsInheritedAccess(FILE_ID)
- expect(items).toHaveLength(1)
- expect(items[0]?.sources).toEqual([
+ expect(result.coverage).toBe('complete')
+ expect(result.items).toHaveLength(1)
+ expect(result.items[0]?.sources).toEqual([
{
resourceId: FOLDER_ID,
name: 'team-docs',
diff --git a/desktop-app/ui/src/gfs/delegation.types.ts b/desktop-app/ui/src/gfs/delegation.types.ts
index a692a0a4e..aa9da3017 100644
--- a/desktop-app/ui/src/gfs/delegation.types.ts
+++ b/desktop-app/ui/src/gfs/delegation.types.ts
@@ -95,3 +95,24 @@ export interface GfsInheritedAccessItem {
/** Every contributing ancestor folder, nearest first (R1-H1). */
sources: GfsInheritedAccessSource[]
}
+
+/**
+ * Terminal coverage of one inherited-access walk (R1-H3, permissions.md T1).
+ * Every non-`complete` state still carries the rows folded so far — known
+ * authorized sources are retained and stay editable; the state only decides
+ * which notice the dialog shows.
+ */
+export type GfsInheritedCoverageState =
+ | 'complete'
+ /** Resolve 403 above the readable chain: an expected privacy boundary. */
+ | 'read-boundary'
+ /** A readable ancestor's grants/shares list answered 403 (no manage_acl). */
+ | 'acl-limited'
+ /** missing / rate-limited / retryable / error / cycle / depth-cap. */
+ | 'unavailable'
+
+/** `deriveGfsInheritedAccess` result: retained rows plus honest coverage. */
+export interface GfsInheritedAccessResult {
+ items: GfsInheritedAccessItem[]
+ coverage: GfsInheritedCoverageState
+}
diff --git a/desktop-app/ui/src/gfs/inheritedAccess.ts b/desktop-app/ui/src/gfs/inheritedAccess.ts
index be79ed4da..baf25b991 100644
--- a/desktop-app/ui/src/gfs/inheritedAccess.ts
+++ b/desktop-app/ui/src/gfs/inheritedAccess.ts
@@ -1,5 +1,8 @@
+import { classifyGfsAclReadFailure, worstGfsCoverageClass } from '@clerum/gfs-interaction-policy'
+import type { GfsCoverageClass } from '@clerum/gfs-interaction-policy'
import { GFS_BREADCRUMB_MAX_DEPTH } from '@constants/gfsBrowser'
-import type { GfsInheritedAccessItem } from './delegation.types'
+import { parseHttpStatus } from '@lib/gfsGrantErrors'
+import type { GfsInheritedAccessItem, GfsInheritedAccessResult } from './delegation.types'
import { inheritedSubjectKey, mergeInheritedAccessItem } from './inheritedAccessMerge'
export { planInheritedRoleChange, strongestInheritedSource } from './inheritedAccessMerge'
@@ -10,15 +13,23 @@ export { planInheritedRoleChange, strongestInheritedSource } from './inheritedAc
* inheritance is reconstructed by walking the ancestor folders (the same
* resolve-based walk the breadcrumb trail uses) and keeping the rows that
* apply to descendants: grants with inherit=true and shares with
- * includeDescendants=true — the server's allow() rule. Derivation is
- * all-or-nothing: if a required ancestor or its ACL cannot be read, callers
- * must show an incomplete-access notice rather than an empty/partial result.
- * Rows are merged per subject through the shared pure core
- * (`@clerum/gfs-interaction-policy`, via the app adapter in
- * `inheritedAccessMerge.ts`, property tested in R1-M4); EVERY contributing
- * ancestor folder is kept as an editable source, so a confirmed removal
- * revokes all of them and a confirmed downgrade lowers each one above the
- * target role (R1-H1).
+ * includeDescendants=true — the server's allow() rule. Rows are merged per
+ * subject through the shared pure core (`@clerum/gfs-interaction-policy`, via
+ * the app adapter in `inheritedAccessMerge.ts`); EVERY contributing ancestor
+ * folder is kept as an editable source, so a confirmed removal revokes all of
+ * them and a confirmed downgrade lowers each one above the target role
+ * (R1-H1).
+ *
+ * Coverage (R1-H3, permissions.md T1): the walk NEVER discards rows it has
+ * already folded. A resolve 403 above the readable chain is an expected
+ * privacy boundary (stop, keep rows, `read-boundary`); grants and shares
+ * settle INDEPENDENTLY per ancestor, so one family's 403 keeps the other
+ * family's rows and the walk continues (`acl-limited`) — the readable
+ * ancestor's parent id is already known from its resolve. Any other failure
+ * (404/410, 429, transport, cycle, depth cap) stops the walk with the folded
+ * rows and `unavailable`. HTTP 401 from any family is rethrown RAW: a session
+ * death is never classified as a quiet boundary and keeps traveling the
+ * controller's existing fail-closed error path.
*/
const DEFAULT_DRIVE = 'main'
@@ -32,61 +43,148 @@ function ridOf(resourceId: string): string {
* control-ui/components/gfsInheritedAccess.ts):
* - BOUNDED in depth: at most GFS_BREADCRUMB_MAX_DEPTH ancestors are visited
* (the control-ui path walk caps itself with the same number via
- * GFS_INHERITED_WALK_MAX_DEPTH).
- * - COMPLETE or FAILED: every ancestor must resolve and both ACL lists must
- * load. Any failure throws the same derivation error used by Control UI;
- * the UI can then distinguish incomplete data from no inherited access.
+ * GFS_INHERITED_WALK_MAX_DEPTH). Hitting the cap with a parent still
+ * remaining reports `unavailable` — it never invents root completion.
+ * - RETAINING: rows folded before a stop are always returned; only the
+ * coverage state differs.
* - Desktop follows parent resource IDs and Control UI follows canonical
- * paths, but both surfaces use the same failure rule.
+ * paths; the shared failure classes come from the shared policy.
*/
export async function deriveGfsInheritedAccess(
resourceId: string,
drive: string = DEFAULT_DRIVE
-): Promise<GfsInheritedAccessItem[]> {
- const target = await window.clerum.gfs.resolve(`gfs://${drive}/${ridOf(resourceId)}`)
+): Promise<GfsInheritedAccessResult> {
const bySubject = new Map<string, GfsInheritedAccessItem>()
- const seenResourceIds = new Set([target.resourceId])
- let parentResourceId = target.parentResourceId
+ const seenResourceIds = new Set<string>()
+ const classes: GfsCoverageClass[] = []
+ let readBoundary = false
+ let aclDenied = false
+ let stopped = false
- while (parentResourceId && seenResourceIds.size - 1 < GFS_BREADCRUMB_MAX_DEPTH) {
+ /** Vetted status marker from the main-process client; null when none. */
+ const statusOf = (error: unknown): number | null =>
+ parseHttpStatus(error instanceof Error ? error.message : String(error ?? ''))
+
+ /** Classify a resolve failure; a session 401 rethrows the original error. */
+ const resolveFailureClass = (error: unknown): GfsCoverageClass => {
+ if (statusOf(error) === 401) throw error
+ return classifyGfsAclReadFailure(error)
+ }
+
+ /** Classify an ACL-list failure (same 401 rule as resolve). */
+ const aclFailureClass = resolveFailureClass
+
+ let targetParentId: string | null
+ try {
+ const target = await window.clerum.gfs.resolve(`gfs://${drive}/${ridOf(resourceId)}`)
+ seenResourceIds.add(target.resourceId)
+ targetParentId = target.parentResourceId
+ } catch (error) {
+ // The dialog's own target maps through the same table: a 403 is a
+ // read boundary with no rows; anything else is `unavailable`; a 401
+ // rethrows (resolveFailureClass).
+ const failureClass = resolveFailureClass(error)
+ classes.push(failureClass)
+ if (failureClass === 'denied') readBoundary = true
+ targetParentId = null
+ stopped = true
+ }
+ let parentResourceId = targetParentId
+
+ while (!stopped && parentResourceId && seenResourceIds.size - 1 < GFS_BREADCRUMB_MAX_DEPTH) {
if (seenResourceIds.has(parentResourceId)) {
- throw new Error('inherited_access_derivation_failed')
+ // Corrupted chain: report it, keep what was folded, never complete.
+ classes.push('error')
+ stopped = true
+ break
}
seenResourceIds.add(parentResourceId)
let parent: Awaited<ReturnType<typeof window.clerum.gfs.resolve>>
try {
parent = await window.clerum.gfs.resolve(`gfs://${drive}/${ridOf(parentResourceId)}`)
- } catch {
- throw new Error('inherited_access_derivation_failed')
+ } catch (error) {
+ const failureClass = resolveFailureClass(error)
+ classes.push(failureClass)
+ if (failureClass === 'denied') readBoundary = true
+ stopped = true
+ break
+ }
+ if (parent.kind !== 'directory') {
+ classes.push('error')
+ stopped = true
+ break
+ }
+
+ // The two ACL families settle INDEPENDENTLY (permissions.md T1): one
+ // family's denial never drops the other family's rows, and a 403 keeps
+ // the walk moving because this ancestor's parent id is already known.
+ const settled = await Promise.allSettled([
+ window.clerum.gfs.listGrants(parent.resourceId, drive),
+ window.clerum.gfs.listShares(parent.resourceId, drive),
+ ])
+ // A session 401 from EITHER family rethrows before anything is folded.
+ for (const outcome of settled) {
+ if (outcome.status === 'rejected' && statusOf(outcome.reason) === 401) throw outcome.reason
+ }
+ const grants = settled[0].status === 'fulfilled' ? settled[0].value : null
+ const shares = settled[1].status === 'fulfilled' ? settled[1].value : null
+ const failures = settled.filter(
+ (outcome): outcome is PromiseRejectedResult => outcome.status === 'rejected'
+ )
+ let mustStop = false
+ if (failures.length > 0) {
+ const failureClass = worstGfsCoverageClass(
+ failures.map(failure => aclFailureClass(failure.reason))
+ )
+ classes.push(failureClass)
+ if (failureClass === 'denied') {
+ // ACL-limited on this folder: contribute nothing from the denied
+ // family/families, keep the fulfilled one, continue upward.
+ aclDenied = true
+ } else {
+ // Any other family failure stops the walk — AFTER the fulfilled
+ // family of THIS folder folds (rows are never discarded, only the
+ // upward walk ends).
+ mustStop = true
+ }
}
- if (parent.kind !== 'directory') throw new Error('inherited_access_derivation_failed')
// The drive root carries an empty name; its label falls back to the drive.
const folderLabel = parent.name || drive
- try {
- const [grants, shares] = await Promise.all([
- window.clerum.gfs.listGrants(parent.resourceId, drive),
- window.clerum.gfs.listShares(parent.resourceId, drive),
- ])
- for (const grant of grants) {
- if (!grant.inherit) continue
- merge(grant.subject, grant.permissions, grant.id, [], parent.resourceId, folderLabel)
- }
- for (const share of shares) {
- if (!share.includeDescendants) continue
- merge(share.subject, share.permissions, null, [share.id], parent.resourceId, folderLabel)
- }
- } catch {
- // A missing ACL read can hide inherited access, so do not return a
- // partial result that looks complete.
- throw new Error('inherited_access_derivation_failed')
+ for (const grant of grants ?? []) {
+ if (!grant.inherit) continue
+ merge(grant.subject, grant.permissions, grant.id, [], parent.resourceId, folderLabel)
+ }
+ for (const share of shares ?? []) {
+ if (!share.includeDescendants) continue
+ merge(share.subject, share.permissions, null, [share.id], parent.resourceId, folderLabel)
+ }
+ if (mustStop) {
+ stopped = true
+ break
}
parentResourceId = parent.parentResourceId
}
- return [...bySubject.values()]
+ if (!stopped && parentResourceId) {
+ // The loop exited at the depth cap with a parent still unknown — report
+ // the cap, never "complete".
+ classes.push('depth-cap')
+ }
+
+ const worst = worstGfsCoverageClass(classes)
+ const coverage =
+ worst !== 'complete' && worst !== 'denied'
+ ? 'unavailable'
+ : readBoundary
+ ? 'read-boundary'
+ : aclDenied
+ ? 'acl-limited'
+ : 'complete'
+
+ return { items: [...bySubject.values()], coverage }
/** Folds one inheriting row into the per-subject map via the pure core. */
function merge(
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
index 410ad28a7..79ec58caa 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/useGfsBrowserController.test.tsx
@@ -2712,6 +2712,7 @@ function ManageProbe() {
<div data-testid="grants-count">{ctrl.grants.length}</div>
<div data-testid="shares-count">{ctrl.shares.length}</div>
<div data-testid="inherited-error">{ctrl.inheritedAccessError ?? 'none'}</div>
+ <div data-testid="inherited-coverage">{ctrl.inheritedCoverage ?? 'none'}</div>
<button type="button" onClick={() => swallow(ctrl.openUri('gfs://main/root'))}>
open root
</button>
@@ -3144,7 +3145,10 @@ describe('useGfsBrowserController — grants list / revoke / inherit (#826)', ()
// R1-M3 — a total inherited-derivation failure (the file itself cannot be
// re-resolved for the walk) must surface as controller error state instead
// of silently collapsing to an empty list.
- it('exposes inheritedAccessError when the derivation fails entirely', async () => {
+ // R1-H3: a classified mid-walk failure no longer throws — the coverage
+ // state ('unavailable') tells the dialog which notice to show, and only a
+ // raw session 401 still surfaces through inheritedAccessError.
+ it('exposes inheritedCoverage unavailable when a mid-walk resolve fails', async () => {
let resolveCalls = 0
Object.defineProperty(window, 'clerum', {
configurable: true,
@@ -3189,7 +3193,58 @@ describe('useGfsBrowserController — grants list / revoke / inherit (#826)', ()
})
await waitFor(() =>
- expect(screen.getByTestId('inherited-error').textContent).toBe('Error: 500 resolve_failed')
+ expect(screen.getByTestId('inherited-coverage').textContent).toBe('unavailable')
)
+ expect(screen.getByTestId('inherited-error').textContent).toBe('none')
+ })
+
+ it('still surfaces the raw inheritedAccessError for a session 401', async () => {
+ let resolveCalls = 0
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ gfs: {
+ listAccessible: vi.fn(async () => ({ items: [], nextCursor: null })),
+ resolve: vi.fn(async () => {
+ resolveCalls += 1
+ if (resolveCalls > 1) throw new Error('Error: 401 Unauthorized httpStatus=401')
+ return {
+ resourceId: 'file-1',
+ parentResourceId: 'folder-1',
+ gfsUri: 'gfs://main/file-1',
+ name: 'report.txt',
+ kind: 'file',
+ version: 1,
+ }
+ }),
+ listChildren: vi.fn(async () => ({ items: [], nextCursor: null })),
+ affordances: vi.fn(async () => ({
+ held: ['read', 'manage_acl'],
+ canDelegate: true,
+ grantableBits: ['read'],
+ canCreateShare: false,
+ })),
+ listGrants: vi.fn(async () => []),
+ listShares: vi.fn(async () => []),
+ },
+ },
+ })
+
+ render(<ManageProbe />, { wrapper: Harness })
+
+ await act(async () => {
+ screen.getByRole('button', { name: 'open root' }).click()
+ })
+ await waitFor(() => expect(screen.getByTestId('current').textContent).toBe('file-1'))
+ await act(async () => {
+ screen.getByRole('button', { name: 'open manage' }).click()
+ })
+
+ await waitFor(() =>
+ expect(screen.getByTestId('inherited-error').textContent).toBe(
+ 'Error: 401 Unauthorized httpStatus=401'
+ )
+ )
+ expect(screen.getByTestId('inherited-coverage').textContent).toBe('none')
})
})
diff --git a/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts b/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
index bbd933ce4..2063937d0 100644
--- a/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
+++ b/desktop-app/ui/src/hooks/domain/useGfsBrowserController.ts
@@ -523,11 +523,13 @@ export function useGfsBrowserController(options: GfsBrowserControllerOptions = {
Boolean(sessionScope) && Boolean(current) && grantsListEnabled && accessState === 'active',
})
// Inherited access (ancestor folders' inheriting grants/shares) is derived
- // client-side because the grants/shares GETs list only direct rows. Only
- // FILE dialogs consume the derivation — folder dialogs keep their
- // direct-only behavior. A derivation failure only means no inherited rows
- // render — the direct grants/shares surfaces keep their own error
- // reporting. Gated to the Manage dialog like the direct listings.
+ // client-side because the grants/shares GETs list only direct rows. FILES
+ // AND FOLDERS consume the derivation (the walk is kind-agnostic). A stop is
+ // reported as coverage (R1-H3): rows folded before the stop are retained
+ // with `inheritedCoverage` telling the dialog which notice to show; only a
+ // raw session 401 (or a throw the walk cannot classify) reaches
+ // `inheritedAccessError`. Gated to the Manage dialog like the direct
+ // listings.
const inheritedAccessQuery = useQuery({
queryKey: desktopQueryKeys.gfsInheritedAccess(
sessionScope ?? 'anonymous',
@@ -535,9 +537,6 @@ export function useGfsBrowserController(options: GfsBrowserControllerOptions = {
DRIVE
),
queryFn: () => deriveGfsInheritedAccess(current!.resourceId, DRIVE),
- // FILES AND FOLDERS: a folder Manage dialog must show the identities its
- // ancestors grant (the walk is kind-agnostic — it resolves the target and
- // follows parent resource ids), so only the dialog + session gates apply.
enabled:
Boolean(sessionScope) && Boolean(current) && grantsListEnabled && accessState === 'active',
})
@@ -884,9 +883,15 @@ export function useGfsBrowserController(options: GfsBrowserControllerOptions = {
[authorityPending, sharesQuery.data]
)
const inheritedAccess = useMemo(
- () => (authorityPending || accessState === 'revoked' ? [] : (inheritedAccessQuery.data ?? [])),
+ () =>
+ authorityPending || accessState === 'revoked' ? [] : (inheritedAccessQuery.data?.items ?? []),
[accessState, authorityPending, inheritedAccessQuery.data]
)
+ // R1-H3: coverage of the walk that produced `inheritedAccess` (null while
+ // never loaded). The scope/revoked guard above intentionally does NOT apply:
+ // coverage describes the observation, and a revoked session empties the
+ // rows through that guard instead.
+ const inheritedCoverage = inheritedAccessQuery.data?.coverage ?? null
const accessibleErrorMessage = accessibleQuery.error ? toMessage(accessibleQuery.error) : null
// The timestamp is a dependency in its own right, not decoration. It is the
// only thing that distinguishes two consecutive failures carrying the same
@@ -1363,16 +1368,18 @@ export function useGfsBrowserController(options: GfsBrowserControllerOptions = {
sharesError: sharesQuery.error,
loadingShares: sharesQuery.isFetching,
refreshShares,
- // Client-derived ancestor access for FILE Manage dialogs: normal-looking
- // toggleable rows whose edits route through the parent-folder
- // confirmation. Per-ancestor failures inside the derivation stay silent;
- // a total failure is reported through inheritedAccessError.
+ // Client-derived ancestor access for FILE AND FOLDER Manage dialogs:
+ // normal-looking toggleable rows whose edits route through the
+ // parent-folder confirmation. Rows folded before a walk stop are always
+ // retained (R1-H3); the stop itself is reported through
+ // inheritedCoverage/inheritedAccessError.
inheritedAccess,
+ inheritedCoverage,
loadingInheritedAccess: inheritedAccessQuery.isFetching,
- // A TOTAL derivation failure surfaces as this message; the Share dialog
- // renders a quiet notice because "no inherited rows" would silently read
- // as "no one else has access". Per-ancestor best-effort skipping stays
- // silent by design.
+ // Only an UNCLASSIFIED throw (today: a raw session 401) surfaces here; the
+ // dialog renders a quiet notice because "no inherited rows" would silently
+ // read as "no one else has access". Walk stops with classified coverage
+ // are reported through inheritedCoverage instead.
inheritedAccessError: inheritedAccessQuery.error ? toMessage(inheritedAccessQuery.error) : null,
refreshInheritedAccess,
revokeShare: (shareId: string) => revokeShareMutation.mutateAsync(shareId),
diff --git a/desktop-app/ui/src/pages/FilesPage.tsx b/desktop-app/ui/src/pages/FilesPage.tsx
index a133c35a8..9f35c9b46 100644
--- a/desktop-app/ui/src/pages/FilesPage.tsx
+++ b/desktop-app/ui/src/pages/FilesPage.tsx
@@ -110,6 +110,12 @@ function hasDraggedGfsResource(event: ReactDragEvent<HTMLElement>): boolean {
const INHERITED_DERIVATION_NOTICE =
'Inherited access could not be loaded. Members with access from a parent folder may be missing.'
+// R1-H3 coverage notices (permissions.md T1 / inherited-permissions spec §7):
+// a privacy boundary and an ACL-limited ancestor are normal states, not load
+// failures, so they must not wear the failure notice above — and vice versa.
+const INHERITED_READ_BOUNDARY_NOTICE = 'There may be access from parent folders you cannot see.'
+const INHERITED_ACL_LIMITED_NOTICE =
+ 'Sharing details on some parent folders are not visible to you.'
function delegationSubjectOptions(
directory: TeamDirectoryResult | undefined
@@ -509,11 +515,20 @@ export function FilesPage({
const canManageCurrent = !accessRevoked && hasBit(affordances, 'manage_acl')
const currentIsFolder = current?.kind === 'directory'
const currentIsFile = current?.kind === 'file'
- // A total inherited-derivation failure becomes a quiet notice in the Share
+ // An incomplete inherited derivation becomes a quiet notice in the Share
// dialog: an empty derived list alone would silently read as "no one else
- // has access" (R1-M3). Applies to FILES AND FOLDERS; per-ancestor
- // best-effort skipping stays silent.
- const inheritedAccessNotice = ctrl.inheritedAccessError ? INHERITED_DERIVATION_NOTICE : null
+ // has access" (R1-M3). R1-H3: rows folded before a walk stop are still
+ // rendered — the notice only discloses what is missing, choosing accurate
+ // copy per coverage state (boundary states are not load failures).
+ const inheritedAccessNotice = ctrl.inheritedAccessError
+ ? INHERITED_DERIVATION_NOTICE
+ : ctrl.inheritedCoverage === 'read-boundary'
+ ? INHERITED_READ_BOUNDARY_NOTICE
+ : ctrl.inheritedCoverage === 'acl-limited'
+ ? INHERITED_ACL_LIMITED_NOTICE
+ : ctrl.inheritedCoverage === 'unavailable'
+ ? INHERITED_DERIVATION_NOTICE
+ : null
const currentPreviewAvailable = currentIsFile && isGfsPreviewFile(current?.name ?? '')
const droppedUploadRestriction = useMemo(() => {
if (!current) {
diff --git a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
index a0c678566..994f5727d 100644
--- a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
+++ b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
@@ -1904,6 +1904,72 @@ describe('FilesPage', () => {
).toContain('Editor')
})
+ // R1-H3: a visibility boundary keeps the known rows AND shows the accurate
+ // boundary notice — not the load-failure copy — on the existing banner.
+ it('renders retained inherited rows alongside the read-boundary notice', async () => {
+ installInheritedDirectoryMocks()
+ hookMock.useGfsBrowserController.mockReturnValue(
+ inheritedFileController({
+ inheritedCoverage: 'read-boundary',
+ inheritedAccessError: null,
+ })
+ )
+
+ renderFilesPage()
+ await openManageDialog('report.txt')
+
+ const manageDialog = await screen.findByRole('dialog', { name: 'Share file report.txt' })
+ const row = await within(manageDialog).findByTestId('gfs-access-row-inherited-user:user-2')
+ expect(within(row).getByText('Test Two')).toBeTruthy()
+ expect(
+ within(manageDialog).getByText('There may be access from parent folders you cannot see.')
+ ).toBeTruthy()
+ // A boundary is not a load failure — the failure copy must not appear.
+ expect(within(manageDialog).queryByText(/could not be loaded/)).toBeNull()
+ // Known authorized sources stay editable (no blanket partial read-only).
+ expect(
+ within(row).getByRole('button', { name: 'Access role for Test Two' }).textContent
+ ).toContain('Editor')
+ })
+
+ it('renders the acl-limited notice without hiding known rows', async () => {
+ installInheritedDirectoryMocks()
+ hookMock.useGfsBrowserController.mockReturnValue(
+ inheritedFileController({
+ inheritedCoverage: 'acl-limited',
+ inheritedAccessError: null,
+ })
+ )
+
+ renderFilesPage()
+ await openManageDialog('report.txt')
+
+ const manageDialog = await screen.findByRole('dialog', { name: 'Share file report.txt' })
+ expect(within(manageDialog).findByTestId('gfs-access-row-inherited-user:user-2')).toBeTruthy()
+ expect(
+ within(manageDialog).getByText(
+ 'Sharing details on some parent folders are not visible to you.'
+ )
+ ).toBeTruthy()
+ })
+
+ it('renders the load-failure notice for unavailable coverage', async () => {
+ installInheritedDirectoryMocks()
+ hookMock.useGfsBrowserController.mockReturnValue(
+ inheritedFileController({
+ inheritedCoverage: 'unavailable',
+ inheritedAccessError: null,
+ })
+ )
+
+ renderFilesPage()
+ await openManageDialog('report.txt')
+
+ const manageDialog = await screen.findByRole('dialog', { name: 'Share file report.txt' })
+ expect(within(manageDialog).getByText(/Inherited access could not be loaded/)).toBeTruthy()
+ expect(within(manageDialog).queryByText(/cannot see\./)).toBeNull()
+ })
+
it('confirms an inherited role change against the parent folder and applies it there', async () => {
installInheritedDirectoryMocks()
const parentGrant = (window.clerum.gfs as unknown as { grant: ReturnType<typeof vi.fn> }).grant