@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/client/verb-rate.limiter.js

@@ -0,0 +1,358 @@
+// The rate limit on `access.client`'s server calls of `signIn`, `signUp` and
+// `resetPassword`. Better Auth limits its routes in its router, before a route runs;
+// a server call to Better Auth's API skips the router, and with it the limit. So a
+// Server Action that signs a user in would let anyone guess passwords as fast as the
+// server answers. `call` asks this limiter first.
+//
+// It is Better Auth's own limit, from Better Auth's `rateLimit` options: on when they
+// turn it on (`enabled`, production by default), in the same storage
+// (`customStorage`, `secondaryStorage`, the database's `rateLimit` table, or memory).
+// It counts each call in two buckets, and refuses it when either is full:
+//
+// - by client address, with the rule Better Auth's router applies to the route
+//   (its built-in rules: 3 tries in 10 seconds on `/sign-in/*` and `/sign-up/*`; a
+//   plugin's rules; `customRules`; else `window` and `max`). The address is read
+//   from the request's headers as Better Auth reads it (`advanced.ipAddress`: its
+//   headers, `trustedProxies`, `ipv6Subnet`), under the key Better Auth's router
+//   uses for the route, so with the database, a secondary or a custom storage a
+//   client's calls and its requests to the route share one budget. In memory they
+//   do not: Better Auth's memory store is its module's own, and this one is
+//   Access's. A call whose address cannot be read shares one bucket per route, as
+//   Better Auth's do, and none with `disableIpTracking`.
+// - by target: the identifier the call names (the email, as the sign-in route
+//   normalizes it; a password reset's token), as the audit log's HMAC of it, so
+//   guesses on one account from many addresses are counted together. It counts
+//   failures, not tries: a call is counted when it is let through (so parallel
+//   guesses cannot all pass one read), and a call that succeeds clears the count,
+//   so failures by others never keep the account's owner out for long. Its rule is
+//   10 failures, each within 5 minutes of the one before
+//   ({@link TARGET_FAILURES}); with `customStorage`, which can count but not
+//   clear, the target's count is kept in this process's memory.
+//
+// A refused call throws Better Auth's own 429 (`TOO_MANY_REQUESTS`, with
+// `X-Retry-After`), and the audit log records it as a refused sign-in, reason
+// `rate-limited`.
+import { signInTarget } from "../audit/audit.log.js";
+/**
+ * The target bucket's rule: 10 failed tries on one account, each within 5 minutes
+ * of the one before. Looser than the address rule, since anyone can spend it on
+ * someone else's account; a success clears it. NIST SP 800-63B (5.2.2) caps failed
+ * tries on one account at 100 before other measures; this stays well under it.
+ */
+const TARGET_FAILURES = { window: 300, max: 10 };
+/** Better Auth's built-in rules for the routes `call` reaches (better-auth 1.7.12 to 1.7.14). */
+const BUILT_IN = (path) => path.startsWith("/sign-in") || path.startsWith("/sign-up")
+    ? { window: 10, max: 3 }
+    : undefined;
+/**
+ * A `customRules` key as Better Auth matches it: `*` is any run within one path
+ * segment, `**` any run of segments, everything else itself.
+ */
+const matches = (pattern, path) => {
+    if (!pattern.includes("*")) {
+        return pattern === path;
+    }
+    let source = "";
+    for (let at = 0; at < pattern.length; at += 1) {
+        const char = pattern[at];
+        if (char === "*" && pattern[at + 1] === "*") {
+            source += ".*";
+            at += 1;
+        }
+        else if (char === "*") {
+            source += "[^/]*";
+        }
+        else {
+            source += char.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${source}$`).test(path);
+};
+/** The first rule a plugin of the app's declares for a route, as Better Auth's router takes it. */
+const pluginRule = (plugins, path) => {
+    for (let at = 0; plugins !== undefined && at < plugins.length; at += 1) {
+        const rules = plugins[at]?.rateLimit;
+        for (let index = 0; rules !== undefined && index < rules.length; index += 1) {
+            const entry = rules[index];
+            if (entry?.pathMatcher(path) === true) {
+                return { window: entry.window, max: entry.max };
+            }
+        }
+    }
+    return undefined;
+};
+/** The rule for a route, as Better Auth's router resolves it; `undefined` when a custom rule turns it off. */
+const ruleOf = async (context, path, request) => {
+    let rule = BUILT_IN(path) ?? {
+        window: context.rateLimit.window,
+        max: context.rateLimit.max,
+    };
+    const plugin = pluginRule(context.options.plugins, path);
+    if (plugin !== undefined) {
+        rule = plugin;
+    }
+    const custom = context.rateLimit.customRules;
+    if (custom !== undefined) {
+        let given;
+        for (const pattern of Object.keys(custom)) {
+            if (matches(pattern, path)) {
+                given = custom[pattern];
+                break;
+            }
+        }
+        const resolved = typeof given === "function"
+            ? await given(request, rule)
+            : given;
+        if (resolved === false) {
+            return undefined;
+        }
+        if (resolved !== undefined && resolved !== null) {
+            const { window, max } = resolved;
+            rule = { window, max };
+        }
+    }
+    return rule;
+};
+/** Seconds until a bucket last counted at `last` opens again. */
+const retryAfterOf = (last, window) => Math.ceil((last + window * 1000 - Date.now()) / 1000);
+const memory = new Map();
+const MEMORY_MAX_ENTRIES = 100_000;
+/** How many of the oldest buckets one sweep looks at, and how many counts apart the sweeps are. */
+const SWEEP = { visit: 1000, every: 100 };
+let counted = 0;
+/**
+ * Drops expired buckets from the oldest end, looking at no more than `visit` of
+ * them, and the oldest ones past the cap: the cost of a count stays bounded, never
+ * the store's size.
+ */
+const sweep = (now, visit) => {
+    let over = memory.size - MEMORY_MAX_ENTRIES;
+    let seen = 0;
+    for (const key of memory.keys()) {
+        if (seen >= visit && over <= 0) {
+            return;
+        }
+        seen += 1;
+        const bucket = memory.get(key);
+        if (over > 0 || (bucket !== undefined && now >= bucket.expiresAt)) {
+            memory.delete(key);
+            over -= 1;
+        }
+    }
+};
+const memoryConsume = (defaultWindow) => async (key, rule) => {
+    const now = Date.now();
+    counted += 1;
+    sweep(now, counted % SWEEP.every === 0 ? SWEEP.visit : 0);
+    const entry = memory.get(key);
+    if (entry !== undefined && now >= entry.expiresAt) {
+        memory.delete(key);
+    }
+    const row = entry !== undefined && now < entry.expiresAt ? entry.row : undefined;
+    const expiresAt = now + (rule.window || defaultWindow) * 1000;
+    if (row !== undefined && now - row.lastRequest < rule.window * 1000) {
+        if (row.count >= rule.max) {
+            return {
+                allowed: false,
+                retryAfter: retryAfterOf(row.lastRequest, rule.window),
+            };
+        }
+    }
+    const count = row === undefined || now - row.lastRequest >= rule.window * 1000
+        ? 1
+        : row.count + 1;
+    // Set again at the end, so the order stays oldest first.
+    memory.delete(key);
+    memory.set(key, { row: { key, count, lastRequest: now }, expiresAt });
+    return { allowed: true, retryAfter: null };
+};
+/** The database storage: Better Auth's `rateLimit` table, counted as its router counts it. */
+const databaseConsume = (context) => {
+    const db = context.adapter;
+    const model = "rateLimit";
+    const read = async (key) => {
+        const [row] = (await db.findMany({
+            model,
+            where: [{ field: "key", value: key }],
+        }));
+        if (row !== undefined) {
+            row.lastRequest = Number(row.lastRequest);
+        }
+        return row;
+    };
+    const consume = async (key, rule) => {
+        const windowMs = rule.window * 1000;
+        const row = await read(key);
+        const now = Date.now();
+        if (row === undefined) {
+            try {
+                await db.create({ model, data: { key, count: 1, lastRequest: now } });
+                return { allowed: true, retryAfter: null };
+            }
+            catch (error) {
+                if ((await read(key)) === undefined) {
+                    throw error;
+                }
+                return consume(key, rule);
+            }
+        }
+        if (now - row.lastRequest >= windowMs) {
+            const reset = await db.incrementOne({
+                model,
+                where: [
+                    { field: "key", value: key },
+                    { field: "lastRequest", operator: "lte", value: row.lastRequest },
+                ],
+                increment: {},
+                set: { count: 1, lastRequest: now },
+            });
+            return reset ? { allowed: true, retryAfter: null } : consume(key, rule);
+        }
+        const counted = await db.incrementOne({
+            model,
+            where: [
+                { field: "key", value: key },
+                { field: "lastRequest", operator: "gt", value: now - windowMs },
+                { field: "count", operator: "lt", value: rule.max },
+            ],
+            increment: { count: 1 },
+            set: { lastRequest: now },
+        });
+        if (counted) {
+            return { allowed: true, retryAfter: null };
+        }
+        const fresh = await read(key);
+        if (fresh === undefined || now - fresh.lastRequest >= windowMs) {
+            return consume(key, rule);
+        }
+        return {
+            allowed: false,
+            retryAfter: retryAfterOf(fresh.lastRequest, rule.window),
+        };
+    };
+    return consume;
+};
+/** The prefix of every target bucket's key. */
+const TARGET_PREFIX = "aventara-access/failures|";
+/** How often, at most, one limiter prunes the database's target buckets. */
+const PRUNE_EVERY_MS = 60_000;
+const memoryStorage = (defaultWindow) => ({
+    consume: memoryConsume(defaultWindow),
+    clear: async (key) => memory.delete(key),
+});
+/**
+ * The storage Better Auth's options name, as its router picks it (`address`), and
+ * the one the target bucket counts and clears in: the same, except a custom
+ * storage, which cannot clear, leaves the target's count to memory.
+ */
+const storageOf = (context) => {
+    const defaultWindow = context.options.rateLimit?.window ?? 10;
+    const custom = context.options.rateLimit?.customStorage;
+    if (custom !== undefined) {
+        return {
+            address: {
+                consume: (key, rule) => custom.consume(key, rule),
+                clear: async () => undefined,
+            },
+            target: memoryStorage(defaultWindow),
+        };
+    }
+    let storage;
+    if (context.rateLimit.storage === "secondary-storage") {
+        const secondary = context.options.secondaryStorage;
+        const increment = secondary?.increment;
+        if (secondary === undefined || increment === undefined) {
+            throw new TypeError("Secondary-storage rate limiting requires SecondaryStorage.increment.");
+        }
+        storage = {
+            consume: async (key, rule) => (await increment(key, rule.window || defaultWindow)) <= rule.max
+                ? { allowed: true, retryAfter: null }
+                : { allowed: false, retryAfter: rule.window },
+            clear: async (key) => secondary.delete(key),
+        };
+    }
+    else if (context.rateLimit.storage === "memory") {
+        storage = memoryStorage(defaultWindow);
+    }
+    else {
+        storage = {
+            consume: databaseConsume(context),
+            clear: (key) => context.adapter.deleteMany({
+                model: "rateLimit",
+                where: [{ field: "key", value: key }],
+            }),
+            // Each identifier a caller names makes a row: one that failed once and
+            // was never cleared would stay, so a caller naming random identifiers
+            // would grow the table without end.
+            prune: (before) => context.adapter.deleteMany({
+                model: "rateLimit",
+                where: [
+                    { field: "key", operator: "starts_with", value: TARGET_PREFIX },
+                    { field: "lastRequest", operator: "lt", value: before },
+                ],
+            }),
+        };
+    }
+    return { address: storage, target: storage };
+};
+/**
+ * The limiter: throws Better Auth's 429 when the call's address has used up the
+ * route's rule or its target has failed too often, and logs the refusal. Otherwise
+ * it answers what clears the target's count, which `call` runs once the call has
+ * succeeded: a refused call keeps its count.
+ */
+export const verbRateLimiter = (input) => {
+    let prunedAt = Number.NEGATIVE_INFINITY;
+    return async (call) => {
+        const context = await input.context();
+        if (!context.rateLimit.enabled) {
+            return undefined;
+        }
+        const rule = await ruleOf(context, call.path, call.request);
+        if (rule === undefined) {
+            return undefined;
+        }
+        const storage = storageOf(context);
+        const ip = input.ipOf(call.headers, context.options);
+        const tracked = context.options.advanced?.ipAddress?.disableIpTracking !== true;
+        const target = await signInTarget(call.identifier, context.secret);
+        const refuse = async (retryAfter, window) => {
+            await input.auditLog?.record({
+                at: new Date(),
+                kind: "sign-in-failed",
+                userId: null,
+                route: call.path,
+                reason: "rate-limited",
+                origin: "client",
+                ...(target === undefined ? {} : { target }),
+            });
+            return new input.refusal("TOO_MANY_REQUESTS", { message: "Too many requests. Please try again later." }, { "X-Retry-After": String(retryAfter ?? window) });
+        };
+        if (ip !== null || tracked) {
+            // Better Auth's router's key for the route, so the two share a bucket.
+            const decision = await storage.address.consume(`${ip ?? "no-trusted-ip"}|${call.path}`, rule);
+            if (!decision.allowed) {
+                throw await refuse(decision.retryAfter, rule.window);
+            }
+        }
+        if (target === undefined) {
+            return undefined;
+        }
+        const now = Date.now();
+        if (storage.target.prune !== undefined &&
+            now - prunedAt >= PRUNE_EVERY_MS) {
+            prunedAt = now;
+            await storage.target
+                .prune(now - TARGET_FAILURES.window * 1000)
+                .catch(() => undefined);
+        }
+        const key = `${TARGET_PREFIX}${target}|${call.path}`;
+        const decision = await storage.target.consume(key, TARGET_FAILURES);
+        if (!decision.allowed) {
+            throw await refuse(decision.retryAfter, TARGET_FAILURES.window);
+        }
+        return async () => {
+            await storage.target.clear(key);
+        };
+    };
+};

package/dist/foreign/foreign-facts.d.ts

@@ -0,0 +1,30 @@
+import { type AccessSchemaResourceFacts } from "../policies-contract.js";
+/** The format marker of every foreign facts file. */
+export declare const FOREIGN_FORMAT = "aventara-access/foreign@1";
+/** The foreign facts file's name, beside the namespace's pulled policies file. */
+export declare const FOREIGN_FILE = "foreign.json";
+/** One foreign Resource's entry: the owner's schema facts, marked with the owner. */
+export type AccessForeignEntry = AccessSchemaResourceFacts & {
+    readonly foreign: string;
+};
+/** The foreign facts file `avaccess pull --foreign` writes. */
+export type AccessForeignFacts = {
+    /** `"aventara-access/foreign@1"`. */
+    readonly format: string;
+    /** The namespace that reads these Resources. */
+    readonly namespace: string;
+    /** One entry per foreign Resource, by name. */
+    readonly schema: {
+        readonly [resource: string]: AccessForeignEntry;
+    };
+};
+/**
+ * Checks that `file` is a foreign facts file: its format, its reading namespace, and
+ * each entry a schema entry marked foreign to another namespace, as the engine would
+ * check it in a policies file.
+ */
+export declare const checkForeignFacts: (file: unknown) => AccessForeignFacts;
+/** The foreign facts' canonical text: its members, and each entry's, sorted as a policies file's are. */
+export declare const canonicalForeignFacts: (file: AccessForeignFacts) => string;
+/** The foreign facts' hash: `sha256:<hex>`, the same for the same entries in any order. */
+export declare const foreignFactsHash: (file: AccessForeignFacts) => string;

package/dist/foreign/foreign-facts.js

@@ -0,0 +1,75 @@
+// The foreign facts file, format `aventara-access/foreign@1`: what `avaccess pull
+// --foreign <Resource,…>` brings into a project, so the rules can read another
+// namespace's Resources in conditions. It holds one schema entry per Resource,
+// as the owner's current file states it and marked `{ "foreign": "<owner>" }`, with
+// the relations to Resources the file does not hold left out. `avaccess schema`
+// adds these entries to the model it writes; until they are pulled the Resources are
+// absent from the rules' types.
+//
+// The file is pinned in `avAccess.lock.json` (`foreign`) and checked by `avaccess
+// verify`, as every pulled file is. Its hash is the hash of the policies file that
+// holds the same entries and no rule, so one function decides "the same facts".
+import { AccessError } from "../access/access.error.js";
+import { canonicalJson } from "../canonical-json.writer.js";
+import { checkPolicies, isRecord } from "../policies.compiler.js";
+import { canonicalPolicies, policiesHash } from "../policies.hash.js";
+import { POLICIES_FORMAT, } from "../policies-contract.js";
+/** The format marker of every foreign facts file. */
+export const FOREIGN_FORMAT = "aventara-access/foreign@1";
+/** The foreign facts file's name, beside the namespace's pulled policies file. */
+export const FOREIGN_FILE = "foreign.json";
+const MEMBERS = ["format", "namespace", "schema"];
+/** The policies file with the same schema entries and no rule: what the facts are checked and hashed as. */
+const asPolicies = (facts) => ({
+    format: POLICIES_FORMAT,
+    namespace: facts.namespace,
+    claims: {},
+    schema: facts.schema,
+    roles: {},
+    govern: {},
+    grants: [],
+    denies: [],
+});
+const invalid = (message) => {
+    throw new AccessError("ACCESS_POLICIES_INVALID", `foreign facts: ${message}`);
+};
+/**
+ * Checks that `file` is a foreign facts file: its format, its reading namespace, and
+ * each entry a schema entry marked foreign to another namespace, as the engine would
+ * check it in a policies file.
+ */
+export const checkForeignFacts = (file) => {
+    if (!isRecord(file)) {
+        return invalid("a foreign facts file is a JSON object");
+    }
+    if (file.format !== FOREIGN_FORMAT) {
+        invalid(`format is ${JSON.stringify(file.format) ?? "missing"}, expected "${FOREIGN_FORMAT}"`);
+    }
+    const unknown = Object.keys(file).filter((key) => !MEMBERS.includes(key));
+    if (unknown.length > 0) {
+        invalid(`a foreign facts file has \`format\`, \`namespace\` and \`schema\`; it does not take ${unknown.map((key) => `\`${key}\``).join(", ")}`);
+    }
+    if (!isRecord(file.schema) || Object.keys(file.schema).length === 0) {
+        invalid("`schema` holds one entry per foreign Resource, and at least one");
+    }
+    for (const [resource, entry] of Object.entries(file.schema)) {
+        if (!isRecord(entry) || typeof entry.foreign !== "string") {
+            invalid(`${resource} is not marked { "foreign": "<owner>" }: every entry is another namespace's`);
+        }
+    }
+    try {
+        checkPolicies(asPolicies(file));
+    }
+    catch (error) {
+        invalid(String(error.message).replace(/^Aventara Access: /, ""));
+    }
+    return file;
+};
+/** The foreign facts' canonical text: its members, and each entry's, sorted as a policies file's are. */
+export const canonicalForeignFacts = (file) => canonicalJson({
+    format: file.format,
+    namespace: file.namespace,
+    schema: JSON.parse(canonicalPolicies(asPolicies(file))).schema,
+});
+/** The foreign facts' hash: `sha256:<hex>`, the same for the same entries in any order. */
+export const foreignFactsHash = (file) => policiesHash(asPolicies(checkForeignFacts(file)));

package/dist/foreign/foreign.merger.d.ts

@@ -0,0 +1,10 @@
+import type { AccessSchema } from "../access-schema.js";
+import type { AccessForeignFacts } from "./foreign-facts.js";
+/** The model with the foreign Resources marked, and what was left out and why. */
+type ForeignMerge = {
+    readonly schema: AccessSchema;
+    readonly skipped: readonly string[];
+};
+/** `schema` (the ORM's reading) with the Resources `facts` holds marked foreign. */
+export declare const mergeForeign: (schema: AccessSchema, facts: AccessForeignFacts, source: string) => ForeignMerge;
+export {};

package/dist/foreign/foreign.merger.js

@@ -0,0 +1,52 @@
+// The foreign facts, into the model `avaccess schema` writes. A Resource the facts
+// hold is read from the service's own ORM schema (its field types are there, and the
+// service's ORM needs the model to join through it) and marked `{ foreign: "<owner>" }`;
+// it keeps only the fields the owner's file lists, and only the relations to
+// Resources the model holds. One the ORM schema does not model is left out and
+// reported: the service could not query through it.
+//
+// A model of the ORM schema the facts do not hold stays the service's own, and a
+// push that names one another namespace owns is refused (`ACCESS_OWNERSHIP`).
+/** `schema` (the ORM's reading) with the Resources `facts` holds marked foreign. */
+export const mergeForeign = (schema, facts, source) => {
+    const skipped = [];
+    const resources = {};
+    for (const [name, resource] of Object.entries(schema.resources)) {
+        resources[name] = resource;
+    }
+    for (const [name, entry] of Object.entries(facts.schema)) {
+        const read = Object.hasOwn(resources, name) ? resources[name] : undefined;
+        if (read === undefined) {
+            skipped.push(`${name}: pulled as namespace "${entry.foreign}"'s, and ${source} has no model for it, so the service could not read through it; add the model (over "${entry.foreign}"'s table) to read it; left out`);
+            continue;
+        }
+        const fields = {};
+        for (const [field, definition] of Object.entries(read.fields)) {
+            if (entry.fields.includes(field)) {
+                fields[field] = definition;
+            }
+            else {
+                skipped.push(`${name}.${field}: namespace "${entry.foreign}"'s file does not list it; left out`);
+            }
+        }
+        resources[name] = {
+            fields,
+            identifiers: read.identifiers.filter((identifier) => identifier.every((field) => Object.hasOwn(fields, field))),
+            foreign: entry.foreign,
+        };
+    }
+    // A relation to a Resource the model no longer holds has nothing to lead to.
+    for (const [name, resource] of Object.entries(resources)) {
+        const fields = {};
+        for (const [field, definition] of Object.entries(resource.fields)) {
+            if (definition.kind === "relation" &&
+                !Object.hasOwn(resources, definition.target)) {
+                skipped.push(`${name}.${field}: a relation to ${definition.target}, which the model does not hold; left out`);
+                continue;
+            }
+            fields[field] = definition;
+        }
+        resources[name] = { ...resource, fields };
+    }
+    return { schema: { enums: schema.enums, resources }, skipped };
+};

package/dist/foreign-references.check.d.ts

@@ -0,0 +1,12 @@
+import type { AccessPolicies } from "./policies-contract.js";
+/**
+ * The warnings for `policies` hosted by a framework that serves the Resources in
+ * `held`, one per writing role and foreign target, each naming every reference
+ * that role may write to it unconstrained.
+ */
+export declare const foreignReferenceWarnings: (policies: AccessPolicies, held: ReadonlySet<string>) => readonly string[];
+/**
+ * Emits `policies`' warnings under a framework that serves the Resources in
+ * `held`, each once per process and namespace.
+ */
+export declare const warnForeignReferences: (policies: AccessPolicies, held: ReadonlySet<string>) => void;

package/dist/foreign-references.check.js

@@ -0,0 +1,134 @@
+// A check of the rules against the framework that hosts them: a role that may
+// create or update a row holding a reference (a to-one relation's reference fields)
+// to a foreign Resource, with no condition of the write grant through that
+// relation. A foreign Resource is read in conditions and never granted on, so the
+// engine lists it in `unheld` and Aventara holds no written reference to it to the
+// caller's read scope (which is `false` for every caller there): the write grant
+// alone decides which row may be linked. A grant that reads nothing through the
+// relation lets the caller link any row of the foreign Resource by its identifier.
+//
+// A grant constrains the link when one of the conditions checked on the row the
+// write leaves reads the relation: on a create, its `where`, its `in`, and the row
+// condition of a subject role held on the writing Resource; on an update, those and
+// its `after` (an update grant's `where` is checked on the row it leaves too). A
+// condition reads the relation when it filters through it (`{ campaign: { … } }`)
+// or compares its reference field with `equals` or `in` (`{ campaignId: me.id }`),
+// itself or in every branch of an `OR` or any part of an `AND`; one under a `NOT`,
+// or a `not` / `notIn` comparison, excludes rows and leaves every other one
+// linkable. "Constrains" says nothing of whether the condition is the right one:
+// it only finds the grants that check nothing.
+//
+// It runs when the framework hosts the engine (`hosted({ held })`), as
+// ACCESS_REFERENCE_UNREADABLE does, for the writing Resources the framework serves
+// (`held`). It warns and never refuses: the engine answers exactly as before. Not
+// warned about: a reference the grant's `write.except` locks.
+import { emitAccessWarning } from "./access-warning.emitter.js";
+import { ownOf } from "./scope.resolver.js";
+const WARNING_CODE = "ACCESS_FOREIGN_REFERENCE_UNCHECKED";
+/** Whether `predicate`, holding on a row, limits which row its `relation` links. */
+const constrains = (predicate, relation, fields) => {
+    if (predicate === undefined) {
+        return false;
+    }
+    switch (predicate.op) {
+        case "false":
+            return true;
+        case "and":
+            return predicate.args.some((arg) => constrains(arg, relation, fields));
+        case "or":
+            return (predicate.args.length > 0 &&
+                predicate.args.every((arg) => constrains(arg, relation, fields)));
+        case "cmp":
+            return (fields.includes(predicate.field) &&
+                (predicate.cmp === "eq" || predicate.cmp === "in"));
+        case "rel":
+            return predicate.relation === relation && predicate.where.op !== "true";
+        default:
+            return false;
+    }
+};
+/** The row condition of `subject` when it is a role held on rows of `resource`. */
+const subjectRowCondition = (policies, subject, resource) => {
+    const definition = ownOf(policies.roles, subject);
+    return definition !== undefined &&
+        "on" in definition &&
+        definition.on === resource
+        ? definition.where
+        : undefined;
+};
+/** Whether `grant`, for `subject`, constrains the link `relation` makes on `action`. */
+const grantConstrains = (policies, grant, subject, resource, action, relation, fields) => grant.in === relation ||
+    constrains(grant.where, relation, fields) ||
+    (action === "update" && constrains(grant.after, relation, fields)) ||
+    constrains(subjectRowCondition(policies, subject, resource), relation, fields);
+const listed = (names) => names.length < 2
+    ? names.join("")
+    : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+/**
+ * The warnings for `policies` hosted by a framework that serves the Resources in
+ * `held`, one per writing role and foreign target, each naming every reference
+ * that role may write to it unconstrained.
+ */
+export const foreignReferenceWarnings = (policies, held) => {
+    const found = new Map();
+    for (const grant of policies.grants) {
+        const actions = grant.actions.filter((action) => action === "create" || action === "update");
+        if (actions.length === 0) {
+            continue;
+        }
+        const locked = new Set(grant.write?.except ?? []);
+        const resources = grant.resource === "*" ? Object.keys(policies.schema) : [grant.resource];
+        for (const resource of resources) {
+            const facts = ownOf(policies.schema, resource);
+            if (facts === undefined ||
+                facts.foreign !== undefined ||
+                !held.has(resource)) {
+                continue;
+            }
+            for (const [relation, fact] of Object.entries(facts.relations)) {
+                const fields = fact.referenceFields;
+                const owner = ownOf(policies.schema, fact.target)?.foreign;
+                if (owner === undefined ||
+                    fact.cardinality !== "one" ||
+                    fields === undefined ||
+                    locked.has(relation) ||
+                    fields.some((field) => locked.has(field))) {
+                    continue;
+                }
+                for (const writer of grant.subjects) {
+                    if (actions.every((action) => grantConstrains(policies, grant, writer, resource, action, relation, fields))) {
+                        continue;
+                    }
+                    const key = `${writer}\u0000${fact.target}`;
+                    const entry = found.get(key) ?? {
+                        writer,
+                        target: fact.target,
+                        owner,
+                        relation,
+                        references: [],
+                    };
+                    for (const field of fields) {
+                        const name = `${resource}.${field}`;
+                        if (!entry.references.includes(name)) {
+                            entry.references.push(name);
+                        }
+                    }
+                    found.set(key, entry);
+                }
+            }
+        }
+    }
+    return [...found.values()].map(({ writer, target, owner, relation, references }) => {
+        const one = references.length === 1;
+        return `${writer} may write ${listed(references)}, ${one ? "a reference" : "references"} to Resource "${target}", which namespace "${owner}" owns (foreign), and no condition of the write grant reads that relation, so any row of "${target}" can be linked by its identifier. Aventara does not hold a reference to a foreign Resource to what the caller may read: the write grant decides which row may be linked. Constrain it through the relation (a \`where\` on a create grant, an \`after\` on an update grant, e.g. \`{ ${relation}: { … } }\`), or leave the reference out of the write (\`write: { except: [...] }\`).`;
+    });
+};
+/**
+ * Emits `policies`' warnings under a framework that serves the Resources in
+ * `held`, each once per process and namespace.
+ */
+export const warnForeignReferences = (policies, held) => {
+    for (const message of foreignReferenceWarnings(policies, held)) {
+        emitAccessWarning(WARNING_CODE, policies.namespace, message);
+    }
+};