@ploaness/governance 1.0.0

package/dist/network-policy.js

@@ -0,0 +1,173 @@
+// The determinism rule that a test reaches no network beyond the machine it runs on, expressed as a
+// decision rather than as prose in the agent guide.
+//
+// The rule was checkable all along: a test that leaves the machine has to go through a socket, a
+// resolver, or fetch, and each of those hands the destination to the runtime before anything is sent.
+// What was missing was somewhere to put the verdict. This module is that place, and it performs no I/O -
+// the caller reads `os.networkInterfaces()` and intercepts the entry points, then asks here.
+//
+// The decision is host-shaped rather than allowlist-shaped on purpose. There is no setting that widens
+// it, because "the database this suite needs happens to live elsewhere" is the exact case the rule
+// exists to reject: a service that exists only outside the machine is exercised through a local
+// component that implements its protocol.
+import { isRecord } from './json-shapes.js';
+/** The sentence of the governing standard this module decides, quoted back in every refusal. */
+export const NETWORK_RULE = 'A test reaches no network beyond the machine it runs on.';
+/** The resolver entry points, every one of which queries a nameserver rather than reading a hosts file. */
+export const RESOLVER_METHODS = [
+    'resolve',
+    'resolve4',
+    'resolve6',
+    'resolveAny',
+    'resolveCaa',
+    'resolveCname',
+    'resolveMx',
+    'resolveNaptr',
+    'resolveNs',
+    'resolvePtr',
+    'resolveSoa',
+    'resolveSrv',
+    'resolveTxt',
+    'reverse',
+];
+// The prefix an IPv4 address wears when it is carried inside an IPv6 one.
+const IPV4_MAPPED_PREFIX = '::ffff:';
+const IPV4_LOOPBACK = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+const ZONE_SEPARATOR = '%';
+const OPENING_BRACKET = '[';
+const CLOSING_BRACKET = ']';
+const DOT = '.';
+// `localhost` and, per RFC 6761, every name beneath it. Written as two string tests rather than as one
+// alternation, because the pattern that expresses it backtracks super-linearly on a long name.
+const LOCALHOST = 'localhost';
+const isLocalhostName = (host) => host === LOCALHOST || host.endsWith(`.${LOCALHOST}`);
+// The unspecified address and the two spellings of the IPv6 loopback. Both name this machine.
+const LOOPBACK_LITERALS = new Set([
+    '::1',
+    '0:0:0:0:0:0:0:1',
+    '0.0.0.0',
+    '::',
+    '0:0:0:0:0:0:0:0',
+]);
+// One canonical spelling for a host, so an address read off this machine's interfaces and a host a test
+// wrote compare as equals: lower case, no brackets around an IPv6 literal, no zone identifier, no
+// trailing dot, and an IPv4-mapped IPv6 address reduced to the IPv4 address it carries.
+// Written with string operations rather than with patterns: every pattern that expresses the same three
+// trims backtracks super-linearly on a long host, and a host is attacker-shaped input in a suite that
+// reads a URL out of a fixture.
+const canonicalHost = (host) => {
+    const lowered = host
+        .toLowerCase()
+        .replaceAll(OPENING_BRACKET, '')
+        .replaceAll(CLOSING_BRACKET, '');
+    const withoutZone = lowered.split(ZONE_SEPARATOR)[0] ?? '';
+    const rooted = withoutZone.endsWith(DOT) ? withoutZone.slice(0, -1) : withoutZone;
+    return rooted.startsWith(IPV4_MAPPED_PREFIX) ? rooted.slice(IPV4_MAPPED_PREFIX.length) : rooted;
+};
+const isLoopback = (host) => IPV4_LOOPBACK.test(host) || LOOPBACK_LITERALS.has(host) || isLocalhostName(host);
+/**
+ * The addresses that name this machine, read out of an `os.networkInterfaces()` result.
+ *
+ * A test that connects to the box's own routable address is still on the machine it runs on, so those
+ * addresses join the loopback range rather than being refused with everything else.
+ * @param interfaces the interface map, as `os.networkInterfaces()` returns it.
+ * @returns every address it carries, in the canonical spelling {@link isMachineLocalHost} compares against.
+ */
+export const localAddresses = (interfaces) => new Set(Object.values(interfaces)
+    .flatMap((entries) => entries ?? [])
+    .map((entry) => canonicalHost(entry.address)));
+/**
+ * Whether a host names the machine the test runs on.
+ *
+ * A name that is not one of the localhost spellings is refused on its face rather than resolved, because
+ * a resolution is itself the thing being refused. That is why a bare service name such as `postgres`,
+ * and a docker gateway such as `host.docker.internal`, do not pass: neither can be shown to be this
+ * machine without asking a nameserver.
+ * @param host the host as the caller wrote it, or undefined when the caller named none.
+ * @param local the addresses this machine carries, from {@link localAddresses}.
+ * @returns true when the reach stays on this machine.
+ */
+export const isMachineLocalHost = (host, local) => {
+    if (host === undefined || host.length === 0) {
+        return true;
+    }
+    const canonical = canonicalHost(host);
+    return isLoopback(canonical) || local.has(canonical);
+};
+/**
+ * The host a URL names.
+ *
+ * Undefined when the value names no host - a relative path, which under a DOM environment is the page's
+ * own origin and reaches nothing, or a string that is not a URL at all.
+ * @param rawUrl the value a test passed to fetch.
+ * @returns the host, or undefined.
+ */
+export const hostOfUrl = (rawUrl) => {
+    try {
+        return new URL(rawUrl).hostname;
+    }
+    catch {
+        return undefined;
+    }
+};
+// A string first argument is a pipe or socket path rather than a port, which is the same reading Node
+// itself applies: anything that is not a number names a path.
+const isPipeName = (value) => Number.isNaN(Number(value));
+const describePort = (port) => typeof port === 'number' || typeof port === 'string' ? String(port) : '';
+const fromOptions = (options) => {
+    const socketPath = options['path'];
+    if (typeof socketPath === 'string') {
+        return { api: 'connect', host: undefined, destination: socketPath };
+    }
+    const declaredHost = options['host'];
+    const host = typeof declaredHost === 'string' ? declaredHost : undefined;
+    return {
+        api: 'connect',
+        host,
+        destination: `${host ?? LOCALHOST}:${describePort(options['port'])}`,
+    };
+};
+/**
+ * Read one `net.Socket.prototype.connect` call, whichever of its three forms the caller used.
+ *
+ * A unix socket reports no host, because a path is not a network: the two ends are the same machine by
+ * construction, and refusing one would break every test that talks to a local service over a socket file.
+ * @param callArguments the arguments the call was made with.
+ * @returns the attempt, normalised.
+ */
+export const describeSocketTarget = (callArguments) => {
+    const [first, second] = callArguments;
+    if (isRecord(first)) {
+        return fromOptions(first);
+    }
+    if (typeof first === 'string' && isPipeName(first)) {
+        return { api: 'connect', host: undefined, destination: first };
+    }
+    const host = typeof second === 'string' ? second : undefined;
+    return {
+        api: 'connect',
+        host,
+        destination: `${host ?? LOCALHOST}:${describePort(first)}`,
+    };
+};
+const OFF_MACHINE_REASON = 'that host is not this machine';
+const RESOLVER_REASON = 'a resolver query is a packet to a nameserver, which no hosts file answers';
+const refusal = (attempt, reason) => `${NETWORK_RULE} A test reached ${attempt.destination} through ${attempt.api}, and ${reason}. ` +
+    'Run a real component on this machine and point the test at it.';
+/**
+ * Decide one attempted reach.
+ *
+ * A resolver query is refused whatever host it names, loopback included. The resolver family bypasses
+ * the hosts file and sends a packet to a nameserver, so `resolve4('localhost')` leaves the machine as
+ * surely as any other name does.
+ * @param attempt the reach to judge.
+ * @param local the addresses this machine carries, from {@link localAddresses}.
+ * @returns undefined when the reach is allowed, or the message a refusal should carry.
+ */
+export const findNetworkEscape = (attempt, local) => {
+    if (attempt.api === 'resolve') {
+        return refusal(attempt, RESOLVER_REASON);
+    }
+    return isMachineLocalHost(attempt.host, local) ? undefined : refusal(attempt, OFF_MACHINE_REASON);
+};
+//# sourceMappingURL=network-policy.js.map

package/dist/network-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-policy.js","sourceRoot":"","sources":["../src/network-policy.ts"],"names":[],"mappings":"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"}

package/dist/paired-assets.d.ts

@@ -0,0 +1,34 @@
+import type { ManagedAsset } from './asset-policy.js';
+/** A root file and the shipped body generated from it. */
+export interface PairedAsset {
+    /** The path in the ploaness repository, which is the editable source. */
+    readonly rootPath: string;
+    /** The generated body, relative to the assets package root. */
+    readonly assetPath: string;
+}
+/** The contents of both sides of one pair, read by the caller so this module stays pure. */
+export interface PairedAssetState {
+    readonly pair: PairedAsset;
+    /** The root file's content, or undefined when the root file is missing. */
+    readonly rootContent: string | undefined;
+    /** The generated body's content, or undefined when the body is missing. */
+    readonly assetContent: string | undefined;
+}
+/** A pair whose two sides no longer agree. */
+export interface PairedAssetDrift {
+    readonly rootPath: string;
+    readonly reason: string;
+}
+/**
+ * Derive the root-to-body pairs from the manifest catalogue.
+ * @param assets the parsed manifest entries.
+ * @returns one pair per PINNED or SEED entry that ploaness generates from a root file.
+ */
+export declare const pairedAssets: (assets: readonly ManagedAsset[]) => readonly PairedAsset[];
+/**
+ * Report every pair whose generated body has drifted from its root file.
+ * @param states both sides of every pair, already read.
+ * @returns one drift per disagreeing pair; empty means every consumer receives what this repository holds.
+ */
+export declare const findPairedAssetDrift: (states: readonly PairedAssetState[]) => readonly PairedAssetDrift[];
+//# sourceMappingURL=paired-assets.d.ts.map

package/dist/paired-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paired-assets.d.ts","sourceRoot":"","sources":["../src/paired-assets.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAiCrD,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,YAAY,EAAE,KAAG,SAAS,WAAW,EAY9E,CAAA;AAkBL;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,gBAAgB,EAAE,KAClC,SAAS,gBAAgB,EAIxB,CAAA"}

package/dist/paired-assets.js

@@ -0,0 +1,63 @@
+/** Where an `.asset` body lives inside the assets package, relative to that package's root. */
+const ASSET_DIRECTORY = 'files';
+/** The suffix npm forces on a packed body: a packed `.npmrc` is stripped and a `.gitignore` renamed. */
+const ASSET_SUFFIX = '.asset';
+// Some paths are authored where they are shipped rather than copied from a root file, all because
+// ploaness is not a consumer of itself.
+//
+// `.ploaness/agent-guide.md` maps the guideline onto the harness for a consumer, and ploaness has no
+// `.ploaness/` directory. `.dockerignore` bounds what a Docker build sends to the daemon, and ploaness
+// builds no image, so a copy at this root would be a file no tool here reads. The managed sweeps under
+// `tests/e2e` drive a Payload application, and ploaness is a library with no application to drive;
+// pairing one with a root file would mean keeping a Next.js project in this repository for a spec to
+// compile against. What proves those bodies instead is the third verification leg AGENTS.md already
+// requires: a real consumer runs them.
+//
+// `src/proxy.ts` is the security-header baseline, and it is authored here for the same reason as the
+// sweeps: it is Next middleware, and there is no Next application in this repository for a root copy of
+// it to compile against.
+//
+// A SECTION entry is likewise unpaired: its body is the managed block, not a copy of any whole file.
+const ASSET_AUTHORED_PATHS = new Set([
+    '.ploaness/agent-guide.md',
+    '.dockerignore',
+    'tests/e2e/a11y.e2e.spec.ts',
+    'tests/e2e/security-headers.e2e.spec.ts',
+    'tests/e2e/access-boundary.e2e.spec.ts',
+    'src/proxy.ts',
+]);
+/**
+ * Derive the root-to-body pairs from the manifest catalogue.
+ * @param assets the parsed manifest entries.
+ * @returns one pair per PINNED or SEED entry that ploaness generates from a root file.
+ */
+export const pairedAssets = (assets) => assets
+    .filter((asset) => (asset.disposition === 'PINNED' || asset.disposition === 'SEED') &&
+    !ASSET_AUTHORED_PATHS.has(asset.path))
+    .map((asset) => ({
+    rootPath: asset.path,
+    assetPath: `${ASSET_DIRECTORY}/${asset.path}${ASSET_SUFFIX}`,
+}));
+const driftReason = (state) => {
+    if (state.rootContent === undefined) {
+        return (`no root file to generate ${state.pair.assetPath} from; add it, or declare ` +
+            'the path as authored directly as an asset');
+    }
+    if (state.assetContent === undefined) {
+        return `${state.pair.assetPath} is missing; regenerate it with \`pnpm run build\``;
+    }
+    return state.rootContent === state.assetContent
+        ? undefined
+        : `${state.pair.assetPath} no longer matches ${state.pair.rootPath}; consumers would ` +
+            'receive stale content. Regenerate it with `pnpm run build`';
+};
+/**
+ * Report every pair whose generated body has drifted from its root file.
+ * @param states both sides of every pair, already read.
+ * @returns one drift per disagreeing pair; empty means every consumer receives what this repository holds.
+ */
+export const findPairedAssetDrift = (states) => states.flatMap((state) => {
+    const reason = driftReason(state);
+    return reason === undefined ? [] : [{ rootPath: state.pair.rootPath, reason }];
+});
+//# sourceMappingURL=paired-assets.js.map

package/dist/paired-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paired-assets.js","sourceRoot":"","sources":["../src/paired-assets.ts"],"names":[],"mappings":"AAaA,+FAA+F;AAC/F,MAAM,eAAe,GAAW,OAAO,CAAA;AAEvC,wGAAwG;AACxG,MAAM,YAAY,GAAW,QAAQ,CAAA;AAErC,kGAAkG;AAClG,wCAAwC;AACxC,EAAE;AACF,qGAAqG;AACrG,uGAAuG;AACvG,uGAAuG;AACvG,mGAAmG;AACnG,qGAAqG;AACrG,oGAAoG;AACpG,uCAAuC;AACvC,EAAE;AACF,qGAAqG;AACrG,wGAAwG;AACxG,yBAAyB;AACzB,EAAE;AACF,qGAAqG;AACrG,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAS;IAChE,0BAA0B;IAC1B,eAAe;IACf,4BAA4B;IAC5B,wCAAwC;IACxC,uCAAuC;IACvC,cAAc;CACf,CAAC,CAAA;AAyBF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAA+B,EAA0B,EAAE,CACtF,MAAM;KACH,MAAM,CACL,CAAC,KAAmB,EAAW,EAAE,CAC/B,CAAC,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,CAAC;IAChE,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CACxC;KACA,GAAG,CACF,CAAC,KAAmB,EAAe,EAAE,CAAC,CAAC;IACrC,QAAQ,EAAE,KAAK,CAAC,IAAI;IACpB,SAAS,EAAE,GAAG,eAAe,IAAI,KAAK,CAAC,IAAI,GAAG,YAAY,EAAE;CAC7D,CAAC,CACH,CAAA;AAEL,MAAM,WAAW,GAAG,CAAC,KAAuB,EAAsB,EAAE;IAClE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,CACL,4BAA4B,KAAK,CAAC,IAAI,CAAC,SAAS,4BAA4B;YAC5E,2CAA2C,CAC5C,CAAA;IACH,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,oDAAoD,CAAA;IACpF,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,KAAK,KAAK,CAAC,YAAY;QAC7C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,sBAAsB,KAAK,CAAC,IAAI,CAAC,QAAQ,oBAAoB;YAClF,4DAA4D,CAAA;AACpE,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,MAAmC,EACN,EAAE,CAC/B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAuB,EAA+B,EAAE;IACtE,MAAM,MAAM,GAAuB,WAAW,CAAC,KAAK,CAAC,CAAA;IACrD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;AAChF,CAAC,CAAC,CAAA"}

package/dist/payload-access.d.ts

@@ -0,0 +1,9 @@
+import { type PayloadViolation } from './payload-source.js';
+export declare const findUndeclaredAccess: (source: string) => readonly PayloadViolation[];
+/** Report an auth collection that leaves the login-attempt cap and lock time to Payload's defaults. */
+export declare const findUnhardenedAuth: (source: string) => readonly PayloadViolation[];
+/** Report a config whose drafts are readable by an unauthenticated client. */
+export declare const findAnonymousDraftReads: (source: string) => readonly PayloadViolation[];
+/** Report an upload collection that accepts whatever file type Payload's defaults allow. */
+export declare const findUnrestrictedUploads: (source: string) => readonly PayloadViolation[];
+//# sourceMappingURL=payload-access.d.ts.map

package/dist/payload-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-access.d.ts","sourceRoot":"","sources":["../src/payload-access.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AA4E5B,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAkB3E,CAAA;AAkCJ,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAG1E,CAAA;AA2CH,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAa/E,CAAA;AA6BH,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAG/E,CAAA"}

package/dist/payload-access.js

@@ -0,0 +1,168 @@
+// The access-control half of the Payload rules: who a collection or a global lets in, and what it
+// leaves to the framework's defaults.
+//
+// These rules are separated from the Local API rules in `payload-policy.ts` because they share a
+// question the others do not ask - "which object literal IS this config" - and because together the two
+// halves passed the file size cap. Every one of them is a security decision that Payload will silently
+// make on the project's behalf if the project does not make it first.
+import { configBody, depthOneBlockKeys, depthOneValue, } from './payload-source.js';
+import { lineOf, NOT_FOUND, topLevelKeys } from './source-text.js';
+// The three ways a Payload config is declared, all of them idiomatic:
+//
+//   const Users: CollectionConfig = { ... }          the annotation
+//   const Users: CollectionConfig<'users'> = { ... } the annotation, with the slug as a type argument
+//   const Users = { ... } satisfies CollectionConfig the inferred form
+//
+// Only the first was matched for a long time, because the lookahead that stopped `CollectionConfigs`
+// from matching also excluded `<`, and nothing looked for `satisfies` at all. A collection written
+// either of the other two ways passed every rule below without one of them ever reading it - which is
+// the worst failure a gate can have, because it is indistinguishable from a pass.
+const declarationPattern = (typeName) => new RegExp(String.raw `(:|satisfies)\s*${typeName}(?=[<=,)\s]|$)`, 'g');
+/** The operations a collection must decide for itself rather than inherit. */
+const COLLECTION_OPERATIONS = ['create', 'read', 'update', 'delete'];
+/** A global has no create or delete: it exists from the moment it is configured. */
+const GLOBAL_OPERATIONS = ['read', 'update'];
+const CONFIG_KINDS = [
+    {
+        label: 'CollectionConfig',
+        declaration: declarationPattern('CollectionConfig'),
+        operations: COLLECTION_OPERATIONS,
+    },
+    {
+        label: 'GlobalConfig',
+        declaration: declarationPattern('GlobalConfig'),
+        operations: GLOBAL_OPERATIONS,
+    },
+];
+const SATISFIES = 'satisfies';
+// EVERY config in the file, not the first. `search` returned one offset, so a module exporting two
+// collections - or a collection beside a global - had its second config judged by nothing at all. The
+// Local API rules already iterated their matches; these did not, and the asymmetry was invisible
+// because a file with one config, which is most of them, behaves identically either way.
+const findConfigs = (source, kind) => [...source.matchAll(kind.declaration)].flatMap((match) => {
+    const body = configBody(source, match.index, match[1] === SATISFIES);
+    return body === undefined ? [] : [{ marker: match.index, body }];
+});
+const eachConfig = (source, judge) => CONFIG_KINDS.flatMap((kind) => findConfigs(source, kind).flatMap((found) => judge(kind, found)));
+// Payload fills the missing operations in during sanitisation, so a partial access block is invisible
+// the moment the app boots - and its default for a non-auth collection is public read. Checking that
+// the word `access` appears somewhere in the file, which is what this rule used to do, accepted a block
+// that declared one operation out of four.
+export const findUndeclaredAccess = (source) => eachConfig(source, (kind, found) => {
+    const declared = depthOneBlockKeys(found.body, 'access');
+    const missing = kind.operations.filter((operation) => !declared.includes(operation));
+    return missing.length === 0
+        ? []
+        : [
+            {
+                line: lineOf(source, found.marker),
+                rule: 'require-complete-access',
+                reason: `a ${kind.label} must declare access for ${kind.operations.join(', ')}; ` +
+                    `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} left to the Payload ` +
+                    'defaults, which allow public read',
+            },
+        ];
+});
+// Payload locks nothing by default: without a login-attempt cap and a lock time, an auth collection
+// accepts guesses at whatever rate a client can make them. `auth: true` is the bare enable, so it is
+// the case this rule most needs to catch.
+const AUTH_HARDENING_KEYS = ['maxLoginAttempts', 'lockTime'];
+const COLLECTION = 'CollectionConfig';
+const unhardenedAuthIn = (source, found) => {
+    const value = depthOneValue(found.body, 'auth');
+    if (value === undefined) {
+        return [];
+    }
+    const declared = value.trimStart().startsWith('{')
+        ? topLevelKeys(value, 0)
+        : [];
+    const missing = AUTH_HARDENING_KEYS.filter((key) => !declared.includes(key));
+    return missing.length === 0
+        ? []
+        : [
+            {
+                line: lineOf(source, found.marker),
+                rule: 'require-auth-hardening',
+                reason: `an auth collection must declare ${AUTH_HARDENING_KEYS.join(' and ')}; ` +
+                    `${missing.join(' and ')} left to the Payload defaults means a login attempt is never ` +
+                    'capped and an account is never locked',
+            },
+        ];
+};
+/** Report an auth collection that leaves the login-attempt cap and lock time to Payload's defaults. */
+export const findUnhardenedAuth = (source) => eachConfig(source, (kind, found) => kind.label === COLLECTION ? unhardenedAuthIn(source, found) : []);
+// A draft is unpublished content. With versions.drafts enabled, `?draft=true` serves it to whoever the
+// read rule admits - so a read that is unconditionally true publishes every draft to anyone.
+const DRAFTS_ENABLED = /drafts\s*:\s*(?:true|\{)/;
+// The inline always-true read.
+//
+// The return type is optional in the pattern and effectively mandatory in a governed project, which is
+// the whole reason it appears here. `explicit-function-return-type` makes a conforming project write
+// `read: (): boolean => true`, and a pattern demanding `()` immediately before `=>` matched none of
+// those - so this rule reported nothing on the only spelling the harness permits. `[^=]*` cannot run
+// past the arrow it precedes, which keeps the optional part from swallowing the match.
+const ALWAYS_TRUE_READ = /read\s*:\s*\(\s*\)\s*(?::[^=]*)?=>\s*true/;
+// Where the access block's own braces close, so the search below cannot run past them into the fields.
+const blockEnd = (access, open) => {
+    const body = configBody(access.slice(open), 0, false);
+    return body === undefined ? access.length : open + body.length;
+};
+// The read is looked for inside the access block alone. `depthOneValue` returns everything from the
+// key's colon to the end of the enclosing literal, so testing it whole meant a FIELD-level
+// `read: () => true` - which grants nothing beyond that one field - was reported as though the
+// collection itself were open to anyone.
+//
+// Only the inline form is decidable here, and the lint pass forbids that form in a config file, so a
+// conforming project writes `read: anyone` and this rule stays silent on it. What covers the conforming
+// case is the managed access-boundary sweep, which asks the running application what it grants rather
+// than reading the source. This rule reaches a config declared outside the linted directories.
+const isDraftExposed = (body) => {
+    const versions = depthOneValue(body, 'versions');
+    if (versions === undefined || !DRAFTS_ENABLED.test(versions)) {
+        return false;
+    }
+    const access = depthOneValue(body, 'access');
+    if (access === undefined) {
+        return false;
+    }
+    const open = access.indexOf('{');
+    return open !== NOT_FOUND && ALWAYS_TRUE_READ.test(access.slice(0, blockEnd(access, open)));
+};
+/** Report a config whose drafts are readable by an unauthenticated client. */
+export const findAnonymousDraftReads = (source) => eachConfig(source, (kind, found) => isDraftExposed(found.body)
+    ? [
+        {
+            line: lineOf(source, found.marker),
+            rule: 'no-anonymous-draft-reads',
+            reason: `a ${kind.label} with drafts enabled must not grant an unconditionally true read; ` +
+                'an unauthenticated client would fetch unpublished drafts through ?draft=true',
+        },
+    ]
+    : []);
+// `mimeTypes` defaults to undefined, so an upload collection takes whatever a client sends until the
+// project says otherwise. Served from the application's own origin, an uploaded SVG is script that runs
+// as the site, which is why the restriction is required rather than advised. No size cap is asked for
+// here: Payload takes that at the config root rather than on the collection.
+const UPLOAD_RESTRICTION = 'mimeTypes';
+const unrestrictedUploadIn = (source, found) => {
+    const value = depthOneValue(found.body, 'upload');
+    if (value === undefined) {
+        return [];
+    }
+    const declared = value.trimStart().startsWith('{')
+        ? topLevelKeys(value, 0)
+        : [];
+    return declared.includes(UPLOAD_RESTRICTION)
+        ? []
+        : [
+            {
+                line: lineOf(source, found.marker),
+                rule: 'require-upload-restrictions',
+                reason: `an upload collection must declare ${UPLOAD_RESTRICTION}; left undeclared it accepts ` +
+                    'any file, and an SVG served from this origin is script that runs as the site',
+            },
+        ];
+};
+/** Report an upload collection that accepts whatever file type Payload's defaults allow. */
+export const findUnrestrictedUploads = (source) => eachConfig(source, (kind, found) => kind.label === COLLECTION ? unrestrictedUploadIn(source, found) : []);
+//# sourceMappingURL=payload-access.js.map

package/dist/payload-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-access.js","sourceRoot":"","sources":["../src/payload-access.ts"],"names":[],"mappings":"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"}

package/dist/payload-policy.d.ts

@@ -0,0 +1,18 @@
+import type { PayloadViolation } from './payload-source.js';
+/**
+ * The rules that are about the language rather than about Payload.
+ *
+ * Reaching for a parent-relative import instead of the path alias is a defect in any package. Held
+ * inside the Payload rule set it ran only where Payload did, so a frontend beside the CMS - the place a
+ * deep relative import is most likely, since it has no Payload to anchor on - was never checked.
+ * @param source the file's text.
+ * @returns one violation per offending line.
+ */
+export declare const findSourceViolations: (source: string) => readonly PayloadViolation[];
+/**
+ * The rules that are about Payload itself, which only a Payload package can break.
+ * @param source the file's text.
+ * @returns one violation per offending line.
+ */
+export declare const findPayloadViolations: (source: string) => readonly PayloadViolation[];
+//# sourceMappingURL=payload-policy.d.ts.map

package/dist/payload-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-policy.d.ts","sourceRoot":"","sources":["../src/payload-policy.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AA6H3D;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAC/B,CAAA;AAEhD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,SAAS,gBAAgB,EAY/E,CAAA"}

package/dist/payload-policy.js

@@ -0,0 +1,124 @@
+// Payload-specific source policy: the rules that exist only because the project is a Payload CMS
+// application, and therefore the part of ploaness that a generic JavaScript harness cannot supply.
+//
+// ploaness governs a language and a framework; this module is the framework half. The rules here target
+// Payload defects that a type checker and a generic linter both miss: a Local API read that pulls an
+// unbounded relationship graph out of the database, and an access check that is deliberately bypassed.
+// The access-control rules - the ones about a decision left UNWRITTEN rather than written wrongly - are
+// in `payload-access.ts`, and the source reader both halves are decided by is in `payload-source.ts`.
+//
+// These rules were previously five GritQL files run as Biome plugins. Biome resolves a plugin path
+// relative to the config that declares it, which does not survive being extended from node_modules, so
+// they are reimplemented here instead. The move also makes them unit-testable, which they were not.
+import { findAnonymousDraftReads, findUndeclaredAccess, findUnhardenedAuth, findUnrestrictedUploads, } from './payload-access.js';
+import { balancedArguments, lineOf, occurrences, stripComments, topLevelSlice, } from './source-text.js';
+// The Local API reads that must declare their bound. `find` returns a page, so either `depth` or `limit`
+// bounds it; the single-document and global reads return one document, so only `depth` applies.
+const BOUNDED_CALLS = [
+    {
+        call: '.find(',
+        required: ['depth', 'limit'],
+        rule: 'no-unbounded-find',
+        reason: 'bound payload.find() with an explicit depth and/or limit, or it pulls an unbounded relationship graph',
+    },
+    {
+        call: '.findByID(',
+        required: ['depth'],
+        rule: 'no-unbounded-findbyid',
+        reason: 'bound payload.findByID() with an explicit depth to cap relationship population',
+    },
+    {
+        call: '.findGlobal(',
+        required: ['depth'],
+        rule: 'no-unbounded-findglobal',
+        reason: 'bound payload.findGlobal() with an explicit depth to cap relationship population',
+    },
+];
+// Only a call on an identifier that is recognisably the Payload instance is judged, so an unrelated
+// `array.find(...)` is never touched. `req` may itself be reached through a chain - `ctx.req.payload`
+// inside a hook is as much the Payload instance as `req.payload` - and excluding a preceding dot meant
+// every such call went unjudged. The chain is admitted only in front of `req`, so a property named
+// `payload` on some unrelated object is still left alone.
+const PAYLOAD_RECEIVER = /(?:^|[^\w$.])(?:payload|(?:[\w$]+\.)*req\.payload|this\.payload)$/;
+const declaresKey = (topLevel, key) => new RegExp(String.raw `(^|[\s,])${key}\s*:`).test(topLevel);
+// An unterminated call, an options variable rather than a literal, or an object spread all make the
+// bound impossible to decide statically. Staying silent there keeps the gate free of false positives;
+// the reviewer still sees the call.
+const unboundedCallAt = (source, rule, found) => {
+    if (!PAYLOAD_RECEIVER.test(source.slice(0, found))) {
+        return undefined;
+    }
+    const argumentText = balancedArguments(source, found + rule.call.length - 1);
+    if (argumentText === undefined || !argumentText.includes('{') || argumentText.includes('...')) {
+        return undefined;
+    }
+    const topLevel = topLevelSlice(argumentText);
+    if (rule.required.some((key) => declaresKey(topLevel, key))) {
+        return undefined;
+    }
+    return { line: lineOf(source, found), rule: rule.rule, reason: rule.reason };
+};
+const findUnboundedCalls = (source) => BOUNDED_CALLS.flatMap((rule) => occurrences(source, rule.call)
+    .map((found) => unboundedCallAt(source, rule, found))
+    .filter((violation) => violation !== undefined));
+const OVERRIDE_ACCESS = /overrideAccess\s*:\s*true/g;
+const findOverrideAccess = (source) => [...source.matchAll(OVERRIDE_ACCESS)].map((match) => ({
+    line: lineOf(source, match.index),
+    rule: 'no-override-access',
+    reason: 'overrideAccess: true bypasses Payload access control; pass req so the access rules run, or drop the override',
+}));
+// Anchored on the keyword that immediately precedes the specifier rather than on the statement that
+// opens it. Requiring the whole statement to fit on one line missed a multi-line brace list, which is
+// how a long import is normally written, and requiring `from` missed both a side-effect import and the
+// dynamic `import('../x')` form. Comments are already blanked, so a `from` reached here is code.
+const RELATIVE_IMPORT = /\b(?:from|import)\s*(?:\(\s*)?['"](\.\.\/[^'"]*)['"]/g;
+// Test helpers live outside the `@/` alias root, and the Payload admin import map is generated. The
+// exemption is anchored at a path boundary so `../helpersOfMine` is not excused by `../helpers`.
+//
+// The ascent repeats, because its LENGTH was never part of that reason. Anchored at exactly one `../`,
+// the exemption reached a spec sitting directly under `tests/` and no deeper - so a suite whose
+// directories mirror `src/`, which is the ordinary layout, could not import the helpers the exemption
+// exists to admit. What still discriminates is the segment the climb LANDS on: `../../../helpers/x` is
+// a helper root reached from depth, while `../../../src/helpers/x` climbed into source and is reported.
+const RELATIVE_IMPORT_EXEMPT = /^(?:\.\.\/)+(?:helpers|importMap)(?:\/|$)/;
+const findDeepRelativeImports = (source) => [...source.matchAll(RELATIVE_IMPORT)].flatMap((match) => {
+    const specifier = match[1] ?? '';
+    return RELATIVE_IMPORT_EXEMPT.test(specifier)
+        ? []
+        : [
+            {
+                line: lineOf(source, match.index),
+                rule: 'no-deep-relative-imports',
+                reason: `use the "@/" path alias instead of the parent-relative import "${specifier}"`,
+            },
+        ];
+});
+/**
+ * The rules that are about the language rather than about Payload.
+ *
+ * Reaching for a parent-relative import instead of the path alias is a defect in any package. Held
+ * inside the Payload rule set it ran only where Payload did, so a frontend beside the CMS - the place a
+ * deep relative import is most likely, since it has no Payload to anchor on - was never checked.
+ * @param source the file's text.
+ * @returns one violation per offending line.
+ */
+export const findSourceViolations = (source) => findDeepRelativeImports(stripComments(source));
+/**
+ * The rules that are about Payload itself, which only a Payload package can break.
+ * @param source the file's text.
+ * @returns one violation per offending line.
+ */
+export const findPayloadViolations = (source) => {
+    // Every rule reads the code, never the prose around it. A comment that names a banned construct in
+    // order to explain why the code avoids it must not be reported as that construct.
+    const code = stripComments(source);
+    return [
+        ...findUnboundedCalls(code),
+        ...findOverrideAccess(code),
+        ...findUndeclaredAccess(code),
+        ...findUnhardenedAuth(code),
+        ...findAnonymousDraftReads(code),
+        ...findUnrestrictedUploads(code),
+    ];
+};
+//# sourceMappingURL=payload-policy.js.map