@nage-api/testing 1.0.0-beta.2

package/dist/packs/authz-bypass.pack.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * The authorization-bypass pack (PLAN.md §15.2, §19).
+ *
+ * Every case here is an attack that works against a plausible implementation.
+ * They are collected in the kit rather than in `@nage-api/auth` so that anything
+ * else making an access decision — a realtime room policy, a driver's ownership
+ * scoping, a generated resource's guard — is held to the same standard.
+ *
+ * The harness is deliberately abstract: `attempt(credential, target)` returns
+ * whether access was granted. That reduces every authorization surface to the
+ * one question the pack cares about, and keeps the pack free of HTTP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeAuthzBypass = void 0;
+/**
+ * The ways a grant string can look like another one.
+ *
+ * Each is a comparison someone has actually written: `includes` instead of
+ * `===`, a case-insensitive compare, a value that survived a `trim()`, and a
+ * prefix that a `startsWith`/`endsWith` check accepts.
+ */
+function lookAlikesOf(grant) {
+    return [`${grant}-readonly`, grant.toUpperCase(), ` ${grant}`, `x${grant}`];
+}
+const LOOK_ALIKE_VARIANTS = 4;
+const describeAuthzBypass = (api, harness) => {
+    const { describe, it, expect } = api;
+    describe(`${harness.name}: authorization bypass`, () => {
+        it('should allow the principal that legitimately has access', async () => {
+            // The control. Without it, an implementation that denies everything would
+            // pass every other case in the pack.
+            const result = await harness.attempt(harness.authorised, harness.target);
+            expect(result.allowed).toBe(true);
+        });
+        it('should refuse a request with no credential', async () => {
+            const result = await harness.attempt(undefined, harness.target);
+            expect(result.allowed).toBe(false);
+        });
+        it('should refuse a principal without the required grant', async () => {
+            const result = await harness.attempt(harness.unauthorised, harness.target);
+            expect(result.allowed).toBe(false);
+        });
+        it('should refuse a principal with no roles and no permissions', async () => {
+            const result = await harness.attempt({ ...harness.unauthorised, roles: [], permissions: [] }, harness.target);
+            expect(result.allowed).toBe(false);
+        });
+        /**
+         * Whether the grants on the credential are what this surface compares.
+         *
+         * A surface that re-derives grants from a store — a resolver in front of a
+         * guard — cannot be attacked by varying the credential's grants at all, and
+         * that immunity is exactly what the forged-claims case asserts. Probing for
+         * it keeps the look-alike cases from reporting a bypass the shape of the
+         * surface makes impossible: strip every grant from an otherwise authorised
+         * principal, and a surface that still allows was never reading them.
+         */
+        const readsGrantsFromCredential = async () => {
+            const stripped = await harness.attempt({ ...harness.authorised, roles: [], permissions: [] }, harness.target);
+            return !stripped.allowed;
+        };
+        it('should not accept a role that merely looks like the required one', async () => {
+            // Substring and case matching are the two ways a grant check is written
+            // wrong: `admin` should not be satisfied by `administrator-readonly`,
+            // `ADMIN`, or ` admin`.
+            //
+            // The impostor inherits the *authorised* identity, not the unauthorised
+            // one. That matters more than it looks: a guard that consults a store as
+            // well as the claims refuses an unauthorised id on the store check, so the
+            // grant comparison is never reached and the case passes for the wrong
+            // reason — while the same guard still grants `admin` to a stored principal
+            // whose role is `administrator-readonly`.
+            if (!(await readsGrantsFromCredential()))
+                return;
+            const rolesAlone = await harness.attempt({ ...harness.authorised, permissions: [] }, harness.target);
+            // Permissions are cleared for the same reason: an implementation that
+            // grants on either channel would be satisfied by the permission and never
+            // compare the role. If roles alone do not grant, there is no role
+            // comparison to attack here — the combined case below covers that guard.
+            if (!rolesAlone.allowed)
+                return;
+            for (const role of harness.authorised.roles) {
+                for (const impostor of lookAlikesOf(role)) {
+                    const result = await harness.attempt({ ...harness.authorised, roles: [impostor], permissions: [] }, harness.target);
+                    expect(result.allowed).toBe(false);
+                }
+            }
+        });
+        it('should not accept a permission that merely looks like the required one', async () => {
+            if (!(await readsGrantsFromCredential()))
+                return;
+            const permissionsAlone = await harness.attempt({ ...harness.authorised, roles: [] }, harness.target);
+            if (!permissionsAlone.allowed)
+                return;
+            for (const permission of harness.authorised.permissions) {
+                for (const impostor of lookAlikesOf(permission)) {
+                    const result = await harness.attempt({ ...harness.authorised, roles: [], permissions: [impostor] }, harness.target);
+                    expect(result.allowed).toBe(false);
+                }
+            }
+        });
+        it('should not accept look-alikes of every grant at once', async () => {
+            // Valid whatever the guard's semantics, and never vacuous: the control case
+            // has already established this principal is otherwise allowed, and every
+            // grant it holds is replaced by a look-alike here. This is the case that
+            // still bites for a guard requiring a role *and* a permission, where each
+            // single-channel probe above is inconclusive.
+            if (!(await readsGrantsFromCredential()))
+                return;
+            for (let variant = 0; variant < LOOK_ALIKE_VARIANTS; variant += 1) {
+                const result = await harness.attempt({
+                    ...harness.authorised,
+                    roles: harness.authorised.roles.map((role) => lookAlikesOf(role)[variant] ?? role),
+                    // `Permission` is a `${string}:${string}` template type, and a
+                    // look-alike deliberately violates that shape — which is the point of
+                    // the case, so the cast is the assertion.
+                    permissions: harness.authorised.permissions.map((permission) => (lookAlikesOf(permission)[variant] ?? permission)),
+                }, harness.target);
+                expect(result.allowed).toBe(false);
+            }
+        });
+        it('should not name the missing grant in the refusal', async () => {
+            // Telling a caller which role they lack maps the permission model out for
+            // them one request at a time.
+            const result = await harness.attempt(harness.unauthorised, harness.target);
+            const message = result.message ?? '';
+            for (const role of harness.authorised.roles)
+                expect(message).not.toContain(role);
+            for (const permission of harness.authorised.permissions) {
+                expect(message).not.toContain(permission);
+            }
+        });
+        it('should not name the target in the refusal', async () => {
+            // Which resources exist is not something an unauthorised caller may
+            // enumerate by reading error messages.
+            const result = await harness.attempt(harness.unauthorised, harness.target);
+            expect(result.message ?? '').not.toContain(harness.target);
+        });
+        const forgedClaims = harness.forgedClaims;
+        if (forgedClaims !== undefined) {
+            it('should ignore claims the store does not back', async () => {
+                // A signed token proves who you are, not what you may still do. This is
+                // the case that separates checking the token from checking the truth.
+                const result = await harness.attempt(forgedClaims, harness.target);
+                expect(result.allowed).toBe(false);
+            });
+        }
+        const ownTarget = harness.ownTarget;
+        if (ownTarget !== undefined) {
+            it('should allow a principal to reach what they own', async () => {
+                const result = await harness.attempt(harness.unauthorised, ownTarget);
+                expect(result.allowed).toBe(true);
+            });
+            it('should refuse a principal reaching somebody else’s resource', async () => {
+                const result = await harness.attempt(harness.unauthorised, harness.target);
+                expect(result.allowed).toBe(false);
+            });
+        }
+    });
+};
+exports.describeAuthzBypass = describeAuthzBypass;
+//# sourceMappingURL=authz-bypass.pack.js.map

package/dist/packs/error-non-leakage.pack.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The error non-leakage pack (PLAN.md §17, §19).
+ *
+ * §17's whole premise is two audiences: the client gets a code and a safe
+ * message, the log gets everything. The defect that premise exists to prevent is
+ * the legacy `ErrorResponse`, which echoed `error.message` on a 500 and shipped
+ * SQL and upstream payloads to callers.
+ *
+ * A package registers this pack against its own error types, and the pack
+ * asserts the separation holds — including for the cases that are easy to get
+ * right once and lose later: a `cause` chain, a `meta` bag, and a nested detail.
+ */
+import type { Pack } from '../test-api.js';
+/** What a package supplies to run the pack. */
+export interface ErrorNonLeakageHarness {
+    /** Name used in the suite description, e.g. `@nage-api/core errors`. */
+    readonly name: string;
+    /**
+     * Build an error that carries every sensitive channel at once: an operator
+     * detail, a `meta` bag and a `cause`.
+     */
+    buildLeakyError(secrets: {
+        detail: string;
+        metaValue: string;
+        causeMessage: string;
+    }): unknown;
+    /** Project the error to what a client would receive. */
+    toClientPayload(error: unknown): unknown;
+    /** The client-safe message, if the implementation exposes one separately. */
+    safeMessageOf?(error: unknown): string;
+    /**
+     * Serialise the error the way the application's logger would.
+     *
+     * Optional: when supplied, the pack additionally asserts the operator *does*
+     * get the detail — a redaction that swallowed everything would otherwise pass
+     * every leak test while making the system undebuggable.
+     */
+    toLogRecord?(error: unknown): unknown;
+}
+/**
+ * Register the pack.
+ *
+ * ```ts
+ * describeErrorNonLeakage({ describe, it, beforeEach, afterEach, expect }, harness);
+ * ```
+ */
+export declare const describeErrorNonLeakage: Pack<ErrorNonLeakageHarness>;
+//# sourceMappingURL=error-non-leakage.pack.d.ts.map

package/dist/packs/error-non-leakage.pack.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The error non-leakage pack (PLAN.md §17, §19).
+ *
+ * §17's whole premise is two audiences: the client gets a code and a safe
+ * message, the log gets everything. The defect that premise exists to prevent is
+ * the legacy `ErrorResponse`, which echoed `error.message` on a 500 and shipped
+ * SQL and upstream payloads to callers.
+ *
+ * A package registers this pack against its own error types, and the pack
+ * asserts the separation holds — including for the cases that are easy to get
+ * right once and lose later: a `cause` chain, a `meta` bag, and a nested detail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeErrorNonLeakage = void 0;
+const no_leak_js_1 = require("./no-leak.js");
+const SECRETS = {
+    detail: 'postgres://app:Sup3rSecretPassw0rd@db.internal:5432/app',
+    metaValue: 'AKIA-EXAMPLE-ACCESS-KEY-ID',
+    causeMessage: 'ORA-00933: SQL command not properly ended near TABLE users',
+};
+/**
+ * Register the pack.
+ *
+ * ```ts
+ * describeErrorNonLeakage({ describe, it, beforeEach, afterEach, expect }, harness);
+ * ```
+ */
+const describeErrorNonLeakage = (api, harness) => {
+    const { describe, it, expect } = api;
+    describe(`${harness.name}: error non-leakage`, () => {
+        it('should keep the operator detail out of the client payload', () => {
+            const error = harness.buildLeakyError(SECRETS);
+            // The specific defect: the legacy envelope echoed `error.message`.
+            (0, no_leak_js_1.expectNoSecrets)(harness.toClientPayload(error), [SECRETS.detail], 'client payload');
+        });
+        it('should keep the meta bag out of the client payload', () => {
+            const error = harness.buildLeakyError(SECRETS);
+            (0, no_leak_js_1.expectNoSecrets)(harness.toClientPayload(error), [SECRETS.metaValue], 'client payload');
+        });
+        it('should keep the cause chain out of the client payload', () => {
+            // A cause is the easiest channel to forget: it is not an own property, so
+            // a redaction written against `Object.entries` misses it entirely.
+            const error = harness.buildLeakyError(SECRETS);
+            (0, no_leak_js_1.expectNoSecrets)(harness.toClientPayload(error), [SECRETS.causeMessage], 'client payload');
+        });
+        it('should leak nothing when every channel is checked at once', () => {
+            const error = harness.buildLeakyError(SECRETS);
+            const result = (0, no_leak_js_1.scanForLeaks)(harness.toClientPayload(error), Object.values(SECRETS));
+            expect(result.leaked).toBe(false);
+        });
+        it('should still expose a client-safe message', () => {
+            // A payload with no message at all is not a pass: a client needs
+            // something to show, and "" invites callers to fall back to the code.
+            const error = harness.buildLeakyError(SECRETS);
+            const payload = harness.toClientPayload(error);
+            expect(typeof payload.message).toBe('string');
+            expect(payload.message.length).toBeGreaterThan(0);
+            expect(typeof payload.code).toBe('string');
+        });
+        if (harness.safeMessageOf !== undefined) {
+            it('should keep the safe message free of secrets too', () => {
+                const error = harness.buildLeakyError(SECRETS);
+                // Called on the harness rather than pulled into a local, so an
+                // implementation whose `safeMessageOf` reads `this` still works.
+                (0, no_leak_js_1.expectNoSecrets)(harness.safeMessageOf?.(error), Object.values(SECRETS), 'safe message');
+            });
+        }
+        if (harness.toLogRecord !== undefined) {
+            it('should give the operator the detail the client was denied', () => {
+                // The other half of §17. A redaction that dropped everything would pass
+                // every test above while making production undebuggable.
+                const error = harness.buildLeakyError(SECRETS);
+                const logged = (0, no_leak_js_1.scanForLeaks)(harness.toLogRecord?.(error), [SECRETS.detail], 'log record');
+                expect(logged.leaked).toBe(true);
+            });
+        }
+    });
+};
+exports.describeErrorNonLeakage = describeErrorNonLeakage;
+//# sourceMappingURL=error-non-leakage.pack.js.map

package/dist/packs/no-leak.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Asserting that a value does not carry a secret (PLAN.md §19: "error
+ * non-leakage"; §12, §17).
+ *
+ * This is the single most reusable assertion in the kit, because the same defect
+ * appears everywhere: a password in a validation error, a connection string in a
+ * health response, a token in a log line, a refresh token in an audit event.
+ * Each package has its own version of "check the error does not contain the
+ * password"; this is that check, written once and made thorough.
+ *
+ * Thorough means three things a hand-rolled `expect(x).not.toContain(secret)`
+ * usually misses:
+ *
+ *  - **non-enumerable properties.** `Error.message` and `Error.stack` do not
+ *    appear in `JSON.stringify(error)`, so the naive check passes on an error
+ *    whose message is the password.
+ *  - **encodings.** A secret can survive as base64 or URL-encoded text.
+ *  - **cycles.** A serializer that throws on a cyclic object turns a security
+ *    assertion into an unrelated failure.
+ */
+/** Everything a value could be hiding a secret in. */
+export interface LeakScanResult {
+    readonly leaked: boolean;
+    /** Which secrets were found, and where. */
+    readonly findings: readonly {
+        secret: string;
+        location: string;
+        encoding: string;
+    }[];
+    /** The text that was searched, for a failure message. */
+    readonly scanned: string;
+}
+/**
+ * Flatten anything into searchable text, including the parts `JSON.stringify`
+ * leaves out.
+ */
+export declare function serialiseDeep(value: unknown, seen?: WeakSet<object>, depth?: number): string;
+/**
+ * Scan a value for any of `secrets`.
+ *
+ * @param location a label used in the failure message, e.g. `response body`
+ */
+export declare function scanForLeaks(value: unknown, secrets: readonly string[], location?: string): LeakScanResult;
+/**
+ * Throw if `value` carries any of `secrets`.
+ *
+ * Framework-agnostic: it throws a plain `Error`, so it works in any runner and
+ * inside a pack that has no `expect`.
+ */
+export declare function expectNoSecrets(value: unknown, secrets: readonly string[], location?: string): void;
+/** Replace every encoding of every secret with a marker of the same shape. */
+export declare function mask(text: string, secrets: readonly string[]): string;
+/** Secrets that show up in almost every fixture; a convenience default. */
+export declare const COMMON_TEST_SECRETS: readonly string[];
+//# sourceMappingURL=no-leak.d.ts.map

package/dist/packs/no-leak.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Asserting that a value does not carry a secret (PLAN.md §19: "error
+ * non-leakage"; §12, §17).
+ *
+ * This is the single most reusable assertion in the kit, because the same defect
+ * appears everywhere: a password in a validation error, a connection string in a
+ * health response, a token in a log line, a refresh token in an audit event.
+ * Each package has its own version of "check the error does not contain the
+ * password"; this is that check, written once and made thorough.
+ *
+ * Thorough means three things a hand-rolled `expect(x).not.toContain(secret)`
+ * usually misses:
+ *
+ *  - **non-enumerable properties.** `Error.message` and `Error.stack` do not
+ *    appear in `JSON.stringify(error)`, so the naive check passes on an error
+ *    whose message is the password.
+ *  - **encodings.** A secret can survive as base64 or URL-encoded text.
+ *  - **cycles.** A serializer that throws on a cyclic object turns a security
+ *    assertion into an unrelated failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMON_TEST_SECRETS = void 0;
+exports.serialiseDeep = serialiseDeep;
+exports.scanForLeaks = scanForLeaks;
+exports.expectNoSecrets = expectNoSecrets;
+exports.mask = mask;
+/** Secrets shorter than this are too likely to appear by chance to check. */
+const MIN_SECRET_LENGTH = 4;
+/**
+ * Flatten anything into searchable text, including the parts `JSON.stringify`
+ * leaves out.
+ */
+function serialiseDeep(value, seen = new WeakSet(), depth = 0) {
+    if (depth > 8)
+        return '';
+    if (value === null || value === undefined)
+        return String(value);
+    // Narrowed positively, one primitive kind at a time. A negative
+    // `typeof value !== 'object'` does not narrow `unknown` at all, so `String()`
+    // would still be receiving `unknown` — and `String(someSymbol)` throws a
+    // TypeError, which turns a leak assertion into an unrelated failure.
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'symbol')
+        return value.toString();
+    if (typeof value === 'function')
+        return value.name;
+    if (typeof value !== 'object')
+        return '';
+    if (seen.has(value))
+        return '[cycle]';
+    seen.add(value);
+    if (value instanceof Error) {
+        // `message`, `stack` and `cause` are non-enumerable or symbol-adjacent, so
+        // a JSON round trip drops exactly the fields most likely to hold a leak.
+        const parts = [value.name, value.message, value.stack ?? ''];
+        const cause = value.cause;
+        if (cause !== undefined)
+            parts.push(serialiseDeep(cause, seen, depth + 1));
+        for (const [key, nested] of Object.entries(value)) {
+            parts.push(key, serialiseDeep(nested, seen, depth + 1));
+        }
+        return parts.join(' ');
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serialiseDeep(item, seen, depth + 1)).join(' ');
+    }
+    if (value instanceof Map) {
+        return [...value.entries()]
+            .map(([key, nested]) => `${serialiseDeep(key, seen, depth + 1)} ${serialiseDeep(nested, seen, depth + 1)}`)
+            .join(' ');
+    }
+    if (value instanceof Set) {
+        return [...value].map((item) => serialiseDeep(item, seen, depth + 1)).join(' ');
+    }
+    return Object.entries(value)
+        .map(([key, nested]) => `${key} ${serialiseDeep(nested, seen, depth + 1)}`)
+        .join(' ');
+}
+/** Encodings a secret could survive in. */
+function encodingsOf(secret) {
+    const variants = [{ encoding: 'plain', text: secret }];
+    variants.push({ encoding: 'base64', text: Buffer.from(secret, 'utf8').toString('base64') });
+    variants.push({ encoding: 'base64url', text: Buffer.from(secret, 'utf8').toString('base64url') });
+    const encoded = encodeURIComponent(secret);
+    if (encoded !== secret)
+        variants.push({ encoding: 'url', text: encoded });
+    return variants.filter((variant) => variant.text.length >= MIN_SECRET_LENGTH);
+}
+/**
+ * Scan a value for any of `secrets`.
+ *
+ * @param location a label used in the failure message, e.g. `response body`
+ */
+function scanForLeaks(value, secrets, location = 'value') {
+    const scanned = serialiseDeep(value);
+    const findings = [];
+    for (const secret of secrets) {
+        if (secret.length < MIN_SECRET_LENGTH)
+            continue;
+        for (const variant of encodingsOf(secret)) {
+            if (scanned.includes(variant.text)) {
+                findings.push({ secret, location, encoding: variant.encoding });
+            }
+        }
+    }
+    return { leaked: findings.length > 0, findings, scanned };
+}
+/**
+ * Throw if `value` carries any of `secrets`.
+ *
+ * Framework-agnostic: it throws a plain `Error`, so it works in any runner and
+ * inside a pack that has no `expect`.
+ */
+function expectNoSecrets(value, secrets, location = 'value') {
+    const result = scanForLeaks(value, secrets, location);
+    if (!result.leaked)
+        return;
+    const described = result.findings
+        .map((finding) => `${finding.secret.slice(0, 3)}… (${finding.encoding})`)
+        .join(', ');
+    throw new Error(`${location} leaked ${String(result.findings.length)} secret(s): ${described}. ` +
+        // The excerpt is masked first. A CI log is where secrets go to live
+        // forever, and a *failing* leak assertion must not be the thing that puts
+        // one there — which is exactly what printing the raw scanned text did.
+        `Searched text began: ${mask(result.scanned, secrets).slice(0, 200)}`);
+}
+/** Replace every encoding of every secret with a marker of the same shape. */
+function mask(text, secrets) {
+    let masked = text;
+    for (const secret of secrets) {
+        if (secret.length < MIN_SECRET_LENGTH)
+            continue;
+        for (const variant of encodingsOf(secret)) {
+            masked = masked.split(variant.text).join(`[${variant.encoding}:redacted]`);
+        }
+    }
+    return masked;
+}
+/** Secrets that show up in almost every fixture; a convenience default. */
+exports.COMMON_TEST_SECRETS = [
+    'Correct-Horse-9',
+    'changeme',
+    'super-secret',
+    'hunter2',
+];
+//# sourceMappingURL=no-leak.js.map

package/dist/packs/query-allow-list.pack.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The query allow-list pack (PLAN.md §12, §14.2, §19).
+ *
+ * The query DSL is what made the legacy framework productive, and it was also
+ * the way a client could filter and sort by any column that existed —
+ * `password_hash`, `deleted_at`, another tenant's `user_id` — and ask for
+ * `limit: -1`. §12 makes both a per-model allow-list and an enforced `maxLimit`
+ * mandatory.
+ *
+ * A driver or a policy implementation registers this pack, and the pack tries
+ * every shape of bypass. That is the value of it living here: when someone finds
+ * a new bypass, adding one case protects every implementation at once.
+ */
+import type { Pack } from '../test-api.js';
+export interface QueryAllowListHarness {
+    readonly name: string;
+    /** A field the policy allows for filtering and sorting. */
+    readonly allowedField: string;
+    /** A field that exists on the model but must never be reachable. */
+    readonly forbiddenField: string;
+    /** The configured ceiling on `limit`. */
+    readonly maxLimit: number;
+    /**
+     * Parse a raw query as a client would have sent it.
+     *
+     * Should throw for anything the policy refuses; the pack asserts on *whether*
+     * it threw, not on the error's type, so it fits any implementation.
+     */
+    parse(raw: Record<string, unknown>): unknown;
+    /** Operators the policy allows on `allowedField`. */
+    readonly allowedOperators?: readonly string[];
+    /** Operators that must be refused, e.g. a raw-SQL escape hatch. */
+    readonly forbiddenOperators?: readonly string[];
+}
+export declare const describeQueryAllowList: Pack<QueryAllowListHarness>;
+//# sourceMappingURL=query-allow-list.pack.d.ts.map

package/dist/packs/query-allow-list.pack.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * The query allow-list pack (PLAN.md §12, §14.2, §19).
+ *
+ * The query DSL is what made the legacy framework productive, and it was also
+ * the way a client could filter and sort by any column that existed —
+ * `password_hash`, `deleted_at`, another tenant's `user_id` — and ask for
+ * `limit: -1`. §12 makes both a per-model allow-list and an enforced `maxLimit`
+ * mandatory.
+ *
+ * A driver or a policy implementation registers this pack, and the pack tries
+ * every shape of bypass. That is the value of it living here: when someone finds
+ * a new bypass, adding one case protects every implementation at once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeQueryAllowList = void 0;
+const describeQueryAllowList = (api, harness) => {
+    const { describe, it, expect } = api;
+    const parses = (raw) => {
+        expect(() => harness.parse(raw)).not.toThrow();
+    };
+    const refuses = (raw) => {
+        expect(() => harness.parse(raw)).toThrow();
+    };
+    describe(`${harness.name}: query allow-list`, () => {
+        it('should accept an allowed field', () => {
+            parses({ where: { [harness.allowedField]: 'value' } });
+        });
+        it('should refuse a field outside the allow-list', () => {
+            // The legacy behaviour: any column that existed was filterable, including
+            // the ones holding credentials.
+            refuses({ where: { [harness.forbiddenField]: 'value' } });
+        });
+        it('should refuse a forbidden field in a sort', () => {
+            // Sorting leaks ordering information even when the column is not selected:
+            // sort by `password_hash` and you learn its distribution.
+            refuses({ sort: [{ field: harness.forbiddenField, direction: 'asc' }] });
+        });
+        it('should refuse a forbidden field nested inside a logical group', () => {
+            // A check that only looks at the top level of `where` misses this.
+            refuses({
+                where: {
+                    and: [{ [harness.allowedField]: 'ok' }, { [harness.forbiddenField]: 'sneaky' }],
+                },
+            });
+        });
+        it('should refuse a forbidden field in a deeply nested group', () => {
+            refuses({
+                where: {
+                    or: [{ and: [{ or: [{ [harness.forbiddenField]: 'deep' }] }] }],
+                },
+            });
+        });
+        it('should refuse an unbounded limit', () => {
+            // `limit: -1` was the legacy way to ask for the whole table.
+            refuses({ limit: -1 });
+        });
+        it('should refuse a limit above the ceiling', () => {
+            refuses({ limit: harness.maxLimit + 1 });
+        });
+        it('should accept a limit at the ceiling', () => {
+            // The boundary itself must be allowed, or the ceiling is off by one.
+            parses({ limit: harness.maxLimit });
+        });
+        it('should refuse a non-numeric limit', () => {
+            refuses({ limit: 'all' });
+        });
+        it('should refuse a negative offset', () => {
+            refuses({ offset: -5 });
+        });
+        it('should refuse a prototype-polluting field name', () => {
+            // `__proto__` as a filter key is how a where-clause builder that assigns
+            // into a fresh object ends up mutating `Object.prototype`.
+            refuses({ where: { __proto__: { polluted: true } } });
+            refuses({ where: { constructor: 'x' } });
+        });
+        for (const operator of harness.allowedOperators ?? []) {
+            it(`should accept the ${operator} operator on an allowed field`, () => {
+                parses({ where: { [harness.allowedField]: { [operator]: 'value' } } });
+            });
+        }
+        for (const operator of harness.forbiddenOperators ?? []) {
+            it(`should refuse the ${operator} operator`, () => {
+                refuses({ where: { [harness.allowedField]: { [operator]: 'value' } } });
+            });
+        }
+    });
+};
+exports.describeQueryAllowList = describeQueryAllowList;
+//# sourceMappingURL=query-allow-list.pack.js.map

package/dist/packs/upload-validation.pack.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The upload validation pack (PLAN.md §12, §19).
+ *
+ * A file arriving from a client carries three attacker-controlled claims — the
+ * name, the extension and the `Content-Type` — and one thing that is not a
+ * claim: the bytes. The pack asserts an implementation trusts only the bytes.
+ *
+ * The malicious matrix lives here rather than in `@nage-api/storage`'s own suite so
+ * that a second implementation (an S3 driver with its own pre-signed-upload
+ * validation, say) is held to the same standard rather than to a paraphrase.
+ */
+import type { Pack } from '../test-api.js';
+/** A file the pack will try to sneak past an implementation. */
+export interface MaliciousFile {
+    readonly label: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly content: Buffer;
+    readonly why: string;
+}
+export interface UploadValidationHarness {
+    readonly name: string;
+    /**
+     * Validate a file. Should throw for anything it refuses.
+     *
+     * The pack asserts on refusal, not on the error type, so any implementation
+     * fits.
+     */
+    validate(input: {
+        filename: string;
+        contentType: string;
+        content: Buffer;
+    }): unknown;
+    /** A file the implementation is configured to accept, for the control case. */
+    readonly accepted: {
+        filename: string;
+        contentType: string;
+        content: Buffer;
+    };
+    /** Extra cases specific to this implementation. */
+    readonly additional?: readonly MaliciousFile[];
+}
+/** Files that must never be accepted, whatever they claim to be. */
+export declare const MALICIOUS_UPLOADS: readonly MaliciousFile[];
+export declare const describeUploadValidation: Pack<UploadValidationHarness>;
+//# sourceMappingURL=upload-validation.pack.d.ts.map