From b447fcc43906b38423aa06e96d70e394ff933ae6 Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Tue, 6 Oct 2026 16:25:51 -0400 Subject: [PATCH 1/5] Show in the explain panel how a realm treats callers who aren't signed in, who each grant opened to them writes as, and each grant's own issues Co-Authored-By: Claude Opus 5.5 --- realm-policy/realm-policy.gts | 126 ++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/realm-policy/realm-policy.gts b/realm-policy/realm-policy.gts index 7c7a6d45b..b90bcebcf 100644 --- a/realm-policy/realm-policy.gts +++ b/realm-policy/realm-policy.gts @@ -543,6 +543,39 @@ interface ExplanationViewSignature { Args: { explanation: PolicyExplanation }; } +// What an explanation reports about callers who aren't signed in: how the +// realm limits and blocks them, and for a grant that opts in to them, the +// user its writes are made as. Read where present, so the panel answers the +// same on a platform that doesn't report them. +interface AnonymousAccessDetail { + limit: { requests: number; windowSeconds: number }; + limitFrom: 'realm' | 'platform'; + invalidBlocklistEntries: string[]; +} +interface GrantAnonymousDetail { + actingUserKey?: string; + actingUser?: string; + actingUserFailure?: 'key-missing' | 'not-a-matrix-id' | 'no-write'; +} +type ExplainedGrantDetail = PolicyExplanation['rules'][number]['grants'][number] & { + anonymous?: GrantAnonymousDetail; + issues?: DraftIssue[]; +}; + +// Why an acting-user key names no one a write may be made as, in the words a +// policy author reads it in. +const ACTING_USER_FAILURES: Record< + NonNullable, + (key: string) => string +> = { + 'key-missing': (key) => + `this realm's settings have no "${key}", so it admits none of them.`, + 'not-a-matrix-id': (key) => + `this realm's "${key}" setting isn't a user ID, so it admits none of them.`, + 'no-write': (key) => + `the user this realm's "${key}" setting names can't write to the realm, so it admits none of them.`, +}; + class ExplanationView extends GlimmerComponent { get explanation() { return this.args.explanation; @@ -553,6 +586,49 @@ class ExplanationView extends GlimmerComponent { return (search ? SEARCH_REASONS[reason] : undefined) ?? REASONS[reason]; } + get anonymousAccess(): AnonymousAccessDetail | undefined { + return ( + this.explanation as PolicyExplanation & { + anonymous?: AnonymousAccessDetail; + } + ).anonymous; + } + + get anonymousLimit(): string { + let access = this.anonymousAccess; + if (!access) { + return ''; + } + let { requests, windowSeconds } = access.limit; + return `${requests} requests per ${windowSeconds} seconds from one address, ${ + access.limitFrom === 'realm' ? 'set by this realm' : 'the platform default' + }`; + } + + get invalidBlocklist(): string { + return (this.anonymousAccess?.invalidBlocklistEntries ?? []) + .map((entry) => `"${entry}"`) + .join(', '); + } + + grantDetail = ( + grant: PolicyExplanation['rules'][number]['grants'][number], + ): ExplainedGrantDetail => grant as ExplainedGrantDetail; + + // Who a grant opened to callers who aren't signed in makes their writes + // as, or why it admits none of them. + actingUserLine = (anonymous: GrantAnonymousDetail): string => { + let opened = "Open to people who aren't signed in"; + let key = anonymous.actingUserKey; + if (!key) { + return `${opened}.`; + } + if (anonymous.actingUserFailure) { + return `${opened}, but ${ACTING_USER_FAILURES[anonymous.actingUserFailure](key)}`; + } + return `${opened}, writing as ${anonymous.actingUser} (the realm's "${key}" setting).`; + }; + // What the realm's own permissions let the actor do. Write without read // is a shape the realm accepts, so it is named rather than read as both. get aclStanding(): string { @@ -665,6 +741,18 @@ class ExplanationView extends GlimmerComponent { {{this.explanation.refusal.code}} {{/if}} + {{#if this.anonymousAccess}} +
Limit
+
{{this.anonymousLimit}}
+ {{#if this.anonymousAccess.invalidBlocklistEntries.length}} +
Blocklist
+
+ Some entries aren't an address or a range ({{this.invalidBlocklist}}), + so this realm turns away everyone who isn't signed in until + they're fixed. +
+ {{/if}} + {{/if}} {{#if this.explanation.search}}
@@ -741,6 +829,28 @@ class ExplanationView extends GlimmerComponent { data-test-explanation-admitting >allowed it {{/if}} + {{#let (this.grantDetail grant) as |detail|}} + {{#if detail.anonymous}} +

{{this.actingUserLine detail.anonymous}}

+ {{/if}} + {{#each detail.issues as |issue|}} +
+ {{issue.severity}} + +
+ {{/each}} + {{/let}} {{/each}} @@ -815,6 +925,22 @@ class ExplanationView extends GlimmerComponent { .matched-grant.admitting { font-weight: 600; } + .grant-note, + .grant-issue { + flex-basis: 100%; + margin: 0; + font-size: var(--boxel-font-size-xs); + font-weight: normal; + color: var(--muted-foreground, var(--boxel-450)); + } + .grant-issue { + display: flex; + align-items: baseline; + gap: var(--boxel-sp-xs); + } + .facts .warning { + color: var(--warning-foreground, var(--boxel-dark)); + } .type-name { font-weight: 600; margin-right: var(--boxel-sp-xs); From 783dc306f296eb575fcdf95363ab79f285ada51c Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Tue, 6 Oct 2026 16:51:37 -0400 Subject: [PATCH 2/5] Mark the blocklist row as a warning, say whose writes an anonymous grant makes, and count limits in the singular Co-Authored-By: Claude Opus 5.5 --- realm-policy/realm-policy.gts | 37 ++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/realm-policy/realm-policy.gts b/realm-policy/realm-policy.gts index 3209d307b..369a4ed25 100644 --- a/realm-policy/realm-policy.gts +++ b/realm-policy/realm-policy.gts @@ -750,6 +750,11 @@ type ExplainedGrantDetail = PolicyExplanation['rules'][number]['grants'][number] issues?: DraftIssue[]; }; +// `1 request`, `2 requests`. +function counted(count: number, noun: string): string { + return `${count} ${noun}${count === 1 ? '' : 's'}`; +} + // Why an acting-user key names no one a write may be made as, in the words a // policy author reads it in. const ACTING_USER_FAILURES: Record< @@ -757,11 +762,11 @@ const ACTING_USER_FAILURES: Record< (key: string) => string > = { 'key-missing': (key) => - `this realm's settings have no "${key}", so it admits none of them.`, + `this realm's settings have no "${key}", so this grant admits none of them.`, 'not-a-matrix-id': (key) => - `this realm's "${key}" setting isn't a user ID, so it admits none of them.`, + `this realm's "${key}" setting isn't a user ID, so this grant admits none of them.`, 'no-write': (key) => - `the user this realm's "${key}" setting names can't write to the realm, so it admits none of them.`, + `the user this realm's "${key}" setting names can't write to the realm, so this grant admits none of them.`, }; class ExplanationView extends GlimmerComponent { @@ -788,7 +793,10 @@ class ExplanationView extends GlimmerComponent { return ''; } let { requests, windowSeconds } = access.limit; - return `${requests} requests per ${windowSeconds} seconds from one address, ${ + return `${counted(requests, 'request')} per ${counted( + windowSeconds, + 'second', + )} from one address, ${ access.limitFrom === 'realm' ? 'set by this realm' : 'the platform default' }`; } @@ -805,6 +813,9 @@ class ExplanationView extends GlimmerComponent { // Who a grant opened to callers who aren't signed in makes their writes // as, or why it admits none of them. + // The line says whose writes it means, since an explanation about a + // signed-in caller lists these grants too, and that caller's own writes are + // made as themselves. actingUserLine = (anonymous: GrantAnonymousDetail): string => { let opened = "Open to people who aren't signed in"; let key = anonymous.actingUserKey; @@ -814,7 +825,10 @@ class ExplanationView extends GlimmerComponent { if (anonymous.actingUserFailure) { return `${opened}, but ${ACTING_USER_FAILURES[anonymous.actingUserFailure](key)}`; } - return `${opened}, writing as ${anonymous.actingUser} (the realm's "${key}" setting).`; + if (!anonymous.actingUser) { + return `${opened}; their writes are made as whoever this realm's "${key}" setting names.`; + } + return `${opened}; their writes are made as ${anonymous.actingUser} (this realm's "${key}" setting).`; }; // What the realm's own permissions let the actor do. Write without read @@ -934,7 +948,13 @@ class ExplanationView extends GlimmerComponent {
{{this.anonymousLimit}}
{{#if this.anonymousAccess.invalidBlocklistEntries.length}}
Blocklist
-
+
+ warning Some entries aren't an address or a range ({{this.invalidBlocklist}}), so this realm turns away everyone who isn't signed in until they're fixed. @@ -1119,6 +1139,8 @@ class ExplanationView extends GlimmerComponent { margin: 0; font-size: var(--boxel-font-size-xs); font-weight: normal; + } + .grant-note { color: var(--muted-foreground, var(--boxel-450)); } .grant-issue { @@ -1126,9 +1148,6 @@ class ExplanationView extends GlimmerComponent { align-items: baseline; gap: var(--boxel-sp-xs); } - .facts .warning { - color: var(--warning-foreground, var(--boxel-dark)); - } .type-name { font-weight: 600; margin-right: var(--boxel-sp-xs); From 40c30d9b2aab73fec3dcc8561d5cad27dbc013c0 Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Tue, 6 Oct 2026 16:56:36 -0400 Subject: [PATCH 3/5] Explain a visitor turned away by an invalid blocklist entry Co-Authored-By: Claude Opus 5.5 --- realm-policy/realm-policy.gts | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/realm-policy/realm-policy.gts b/realm-policy/realm-policy.gts index 369a4ed25..a8aba0d33 100644 --- a/realm-policy/realm-policy.gts +++ b/realm-policy/realm-policy.gts @@ -392,9 +392,13 @@ export class PolicyRule extends FieldDef { } // What each reason an explanation gives means, in the words a policy author -// reads it in. `reads-actor` is named here as well as through the explanation -// type, so the map covers it whichever platform version this realm runs on. -const REASONS: Record = { +// reads it in. `reads-actor` and `blocklist-invalid` are named here as well as +// through the explanation type, so the map covers them whichever platform +// version this realm runs on. +const REASONS: Record< + PolicyExplanation['reason'] | 'reads-actor' | 'blocklist-invalid', + string +> = { acl: "The realm's own permissions already allow this, so the policy isn't needed.", granted: 'A grant in this policy allows it.', 'no-grant': "No rule for this card's type grants this operation.", @@ -414,6 +418,8 @@ const REASONS: Record = { "Someone who isn't signed in is turned away before the policy is checked.", 'reads-actor': "This operation depends on who is asking, and someone who isn't signed in can't be identified, so a grant that opens it to them doesn't apply.", + 'blocklist-invalid': + "This realm's blocklist has an entry that isn't an address or a range, so it turns away everyone who isn't signed in before the policy is checked.", 'policy-unloadable': "The realm's policy couldn't be loaded.", }; From 3772fda53600d4b69f6210f601281b1dd0756429 Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Tue, 6 Oct 2026 17:09:12 -0400 Subject: [PATCH 4/5] Format the explained-grant type as prettier wants it Co-Authored-By: Claude Opus 5.5 --- realm-policy/realm-policy.gts | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/realm-policy/realm-policy.gts b/realm-policy/realm-policy.gts index a8aba0d33..cbfd8136e 100644 --- a/realm-policy/realm-policy.gts +++ b/realm-policy/realm-policy.gts @@ -751,10 +751,11 @@ interface GrantAnonymousDetail { actingUser?: string; actingUserFailure?: 'key-missing' | 'not-a-matrix-id' | 'no-write'; } -type ExplainedGrantDetail = PolicyExplanation['rules'][number]['grants'][number] & { - anonymous?: GrantAnonymousDetail; - issues?: DraftIssue[]; -}; +type ExplainedGrantDetail = + PolicyExplanation['rules'][number]['grants'][number] & { + anonymous?: GrantAnonymousDetail; + issues?: DraftIssue[]; + }; // `1 request`, `2 requests`. function counted(count: number, noun: string): string { From 708a03324f6c0d3b8dceda9a200f4244e07bef5a Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Tue, 6 Oct 2026 17:18:24 -0400 Subject: [PATCH 5/5] Keep a grant issue's warning label on one line, and format the limit line as prettier wants it Co-Authored-By: Claude Opus 5.5 --- realm-policy/realm-policy.gts | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/realm-policy/realm-policy.gts b/realm-policy/realm-policy.gts index cbfd8136e..29602f0f8 100644 --- a/realm-policy/realm-policy.gts +++ b/realm-policy/realm-policy.gts @@ -804,7 +804,9 @@ class ExplanationView extends GlimmerComponent { windowSeconds, 'second', )} from one address, ${ - access.limitFrom === 'realm' ? 'set by this realm' : 'the platform default' + access.limitFrom === 'realm' + ? 'set by this realm' + : 'the platform default' }`; } @@ -1056,12 +1058,12 @@ class ExplanationView extends GlimmerComponent { class='grant-issue' data-test-explanation-grant-issue={{issue.code}} > - {{issue.severity}} + {{issue.severity}} {{/each}} @@ -1155,6 +1157,10 @@ class ExplanationView extends GlimmerComponent { align-items: baseline; gap: var(--boxel-sp-xs); } + .issue-label { + flex-shrink: 0; + white-space: nowrap; + } .type-name { font-weight: 600; margin-right: var(--boxel-sp-xs);