@aglyn/aglyn 1.0.0-beta.143

package/src/lib/foundation/definitions/shared.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2023 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export { };
+
+//# sourceMappingURL=shared.js.map

package/src/lib/foundation/definitions/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/shared.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2023 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport type Payload<T = any> = { payload: T }\nexport type PayloadData<T extends Dictionary = any> = T\nexport type PayloadParams<T> = { [K in keyof T]: T[K] }\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID,WAAuD"}

package/src/lib/foundation/definitions/write-deny-coverage.util.d.ts

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Shared parsing for the write-deny coverage guards (AGL-1355, AGL-1361).
+ *
+ * Extracted from `org-write-deny-coverage.spec.ts` when the same property was
+ * extended to `hosts/{hostId}` and `marketplaceListings/{listingId}`. Three
+ * documents, three different rule shapes, one parser — a second copy of this
+ * would be a second thing to keep true, which is the disease these guards
+ * exist to treat.
+ *
+ * Deliberately PURE: every function takes source text and returns data, with
+ * no file I/O and no imports. That keeps the module free of `node:fs` (this
+ * lib is bundled for the browser) and makes each helper testable on a string
+ * literal. The specs own the reading.
+ *
+ * Not exported from the foundation barrel — nothing at runtime should reach
+ * for it.
+ */
+/**
+ * Comments are stripped from every source before parsing. Prose in this repo
+ * quotes rules fragments and field names constantly — the org block's own
+ * comment names all four AGL-1354 keys, and the listing block's names half its
+ * deny-list — so parsing with comments in place would read the explanation of
+ * a hole as the fix for it.
+ *
+ * A single left-to-right scan, NOT two regex passes, and that distinction is
+ * load-bearing (AGL-2004). The previous version removed block comments first
+ * and line comments second, so a line comment that merely QUOTED a path opened
+ * a block comment that was never meant to exist:
+ *
+ *     // the name, so `hosts/<hostId>/datasets/*` stayed a client-writable
+ *
+ * The `/` before `*` reads as an opening delimiter, and the strip then ran to
+ * the next closing delimiter 571 lines away, swallowing real rule text — and
+ * with it two closing braces, which left the block walker unable to find the
+ * end of the root `match` and threw `never closes`. Every deny-coverage guard
+ * in this directory failed to RUN, which is the worst way for a guard to fail:
+ * the suite is red, so nobody reads it as coverage, but the thing it protects
+ * (the AGL-1775 `registers` deny-list) is unwatched until someone does.
+ *
+ * Scanning once fixes it in both directions: whichever delimiter appears first
+ * wins, so `/*` inside a line comment is just text, and `//` inside a block
+ * comment cannot eat the block's own terminator.
+ */
+export declare function stripComments(source: string): string;
+/**
+ * Quoted strings, blanked. `org-permissions.ts` declares permission KEYS
+ * spelled `'org.settings'` and `'org.auditLog'`, which read exactly like a
+ * field access — the first run of the org guard demanded the rules deny two
+ * fields that do not exist. Template literals are left alone: a real read can
+ * legitimately live inside `${…}`.
+ */
+export declare function stripQuotedStrings(source: string): string;
+/**
+ * Firestore path variables (`{orgId}`, `{document=**}`) carry braces that a
+ * block-depth walker reads as nesting. Rewriting them to angle brackets makes
+ * the rules parseable by brace counting without losing the path text — which
+ * matters, because `{document=**}` IS the wildcard these guards have to see.
+ */
+export declare function normalizePathVariables(rules: string): string;
+/**
+ * The text of a `{ … }` block, keeping only what sits at the block's own
+ * depth. Nested blocks — sub-`match` rules, inline object types — are dropped,
+ * so a nested `allow` or a nested property can never be mistaken for one
+ * belonging to the block asked for.
+ *
+ * `header` must end with the opening brace.
+ */
+export declare function topLevelBody(source: string, header: string): string;
+/**
+ * The FULL text of a `{ … }` block, nested blocks INCLUDED.
+ *
+ * The opposite of `topLevelBody`, and needed for the opposite question. That
+ * one answers "what does THIS block say", so it drops nested bodies — which is
+ * exactly right for a deny-list on one document, and exactly wrong for
+ * `hosts/{hostId}`, whose subcollection rules all live in nested `match`
+ * blocks. AGL-1367 lived in one of them.
+ *
+ * `header` must end with the opening brace.
+ */
+export declare function rawBlockBody(source: string, header: string): string;
+/** The subcollection write rules of `hosts/{hostId}`, as the rules state them. */
+export interface ParsedSubcollectionRules {
+    /** The `subcollection in […]` exclusion list of each catch-all allow. */
+    excluded: {
+        create: string[];
+        update: string[];
+        delete: string[];
+    };
+    /** Collections with a dedicated `match` block, which can RE-GRANT. */
+    dedicated: string[];
+    /** Excluded from all three AND re-granted by nothing: denied outright. */
+    serverOnly: string[];
+}
+/**
+ * Parse the host catch-all's three exclusion lists (AGL-1367).
+ *
+ * Membership in ONE list is not denial and never was — `variables` is
+ * create-excluded and freely updatable, `webhooks` is create-excluded and
+ * freely updatable on purpose (the soft delete is how a capped site frees a
+ * slot). And a dedicated `match` block RE-GRANTS, because Firestore ORs its
+ * allows and the LOOSER one wins: `screens`, `layouts` and `collections` all
+ * sit in three lists and stay editor-writable through the blocks above.
+ *
+ * So "denied outright" is the intersection of the three lists MINUS everything
+ * with a block of its own. That subtraction is the reason a dedicated
+ * `allow write: if false` block would not have closed AGL-1367 — a deny can
+ * never win an OR.
+ */
+export declare function parseHostSubcollectionRules(rulesSource: string): ParsedSubcollectionRules;
+/**
+ * Split an expression on `||` at parenthesis depth 0 only.
+ *
+ * A naive `split('||')` tears a branch apart at any nested alternation, and
+ * both of the documents AGL-1361 added have one. The host rule's client branch
+ * is `(… && !hasAny(L1) && (role == 'admin' || !hasAny(L2)))` — its deny-list
+ * is TIERED, six keys no site member may touch plus `disabledPlugins` which
+ * only a site admin may — and a naive split drops L2 into a branch of its own
+ * where nothing looks for it. The listing block's `function listingManager()`
+ * produces the mirror problem, matching two branches instead of one.
+ */
+export declare function splitTopLevelOr(expression: string): string[];
+/** The keys of the FIRST `hasAny([...])` literal in a rules branch. */
+export declare function hasAnyKeys(branch: string): string[];
+/**
+ * The keys of EVERY `hasAny([...])` literal in a branch, flattened.
+ *
+ * The org rule has one list per branch; the host rule has two in a single
+ * branch, because its deny-list is TIERED — six keys no site member may
+ * touch, and `disabledPlugins` which only a site admin may. `hasAnyKeys`
+ * returns the first list alone, so a host guard built on it would have
+ * silently believed `disabledPlugins` was unprotected.
+ */
+export declare function allHasAnyKeys(branch: string): string[];
+/**
+ * Top-level property names declared on an interface.
+ *
+ * `header` is the full declaration line up to and including the brace, because
+ * the three documents do not share a shape: `AglynOrgBilling` and `AglynHost`
+ * both `extends AglynDocument`, while `MarketplaceListing` extends nothing.
+ */
+export declare function declaredFields(source: string, header: string): string[];
+/** A parsed `allow update` rule for one document. */
+export interface ParsedUpdateRule {
+    /** Every key denied to the client branch, across all its `hasAny` lists. */
+    denied: string[];
+    /** Every OR'd branch of the single `allow update` statement. */
+    branches: string[];
+    /** Depth-0 statements of the document's `match` block. */
+    statements: string[];
+    /** Depth-0 `match` headers under `/databases/{database}/documents`. */
+    topLevelMatches: string[];
+}
+/**
+ * Parse the single `allow update` of one top-level document block.
+ *
+ * `matchHeader` is post-`normalizePathVariables`, e.g.
+ * `match /hosts/<hostId> {`. `clientPredicate` names the branch that a CLIENT
+ * reaches — `canManageOrg()`, `canWriteHostContent(hostId)`, `listingManager()`
+ * — as opposed to the staff branches, which are trusted by design.
+ */
+export declare function parseUpdateRule(rulesSource: string, matchHeader: string, clientPredicate: string): ParsedUpdateRule;
+/**
+ * Field names in an object literal a document is seeded with.
+ *
+ * `anchor` is a regex source locating the write; the literal's own braces are
+ * matched by depth rather than `[^}]*`, because a seed can legitimately carry
+ * a nested object (the host seed writes `screens: {}`) and a lazy class would
+ * truncate the field list at the first inner brace — silently shrinking one of
+ * the guard's sources rather than failing.
+ */
+export declare function seedFields(source: string, anchor: RegExp): string[] | null;
+/**
+ * Field names a document of `collection` is seeded with, in either shape a
+ * seed write takes in this codebase (AGL-2100).
+ *
+ * The original parser understood only the CHAINED form —
+ * `collection('hosts').doc(id).set({ … })` — because that is what every seed
+ * route looked like when it was written. AGL-2063 rewrote the host create into
+ * a transactional claim, which necessarily splits the chain: the ref has to be
+ * built BEFORE `runTransaction` opens so the transaction body can both read
+ * and write it, leaving `const hostRef = …doc(hostId)` in one statement and
+ * `tx.set(hostRef, { … })` in another. The chained anchor then matched
+ * nothing, `seedFields` returned null, and the guard threw — asserting nothing
+ * about any of the four sources of the host field set until it was fixed.
+ *
+ * So resolve the REF BINDING rather than teaching the guard one more literal
+ * spelling. Any `set`/`create` whose first argument is a ref bound to this
+ * collection is a seed write, which covers `tx.`, `batch.` and a bare
+ * `ref.set()` alike, and does not care what wraps them.
+ *
+ * Anchoring on the WRITE and not on the binding matters: the binding is
+ * followed by the transaction callback's own `{`, so a binding-anchored parse
+ * would happily return the arrow body's contents as the field list — a
+ * silently wrong answer, which is worse than the throw.
+ *
+ * Returns null when neither shape is present, so the caller still throws.
+ */
+export declare function seedFieldsOfCollection(source: string, collection: string): string[] | null;
+/**
+ * Top-level fields of `binding` that the modules in `sources` read.
+ *
+ * Directory-wide on purpose. A per-file list would be one more thing to keep
+ * up to date, and a NEW resolver reading a NEW field is covered the moment it
+ * is written — the only way this stays true without anyone tending it.
+ *
+ * The document is identified by IDENTIFIER NAME, not by type — this is a text
+ * scan, and it has no way to know what a local called `host` actually holds.
+ * So an unrelated binding of the same name contributes its property reads too.
+ * That direction is safe (a spurious field fails loudly and gets classified by
+ * a human, and can never HIDE a real one), and it is deliberately left alone,
+ * because the filter that would suppress it is the filter that could suppress
+ * a real read. See {@link isMethodCallAt} for the one case that is not safe to
+ * leave — it produced a name no human could classify.
+ */
+export declare function readFieldsOf(sources: Array<string>, binding: string): string[];
+/**
+ * Comments stripped from a TYPESCRIPT source, with string literals respected.
+ *
+ * `stripComments` above scans rules files, where no string ever contains a
+ * comment delimiter. TypeScript sources are not that: `apps/console/app/api/
+ * media/upload-url/route.ts` builds a download URL from a template literal
+ * containing `https://`, and a scan that does not know it is inside a string
+ * reads that `//` as a line comment and deletes the rest of the line. On a
+ * guard that parses an object literal out of a route, that is not a crash —
+ * it is a SHORTER field list, silently, which is the failure mode AGL-2004
+ * described one level down.
+ *
+ * A separate function rather than a widened `stripComments`, because the two
+ * inputs have genuinely different grammars and three shipped guards depend on
+ * the rules-file behaviour exactly as it is. Same single left-to-right scan,
+ * with quotes as a third state.
+ */
+export declare function stripTypeScriptComments(source: string): string;