@rvoh/psychic 3.1.3 → 3.2.1

package/dist/esm/src/helpers/validateOpenApiSchema.js

@@ -1,4 +1,4 @@
-import { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 /**
  * @internal
@@ -99,7 +99,7 @@ export function createValidator(schema, options = {}) {
         ...options,
         init: undefined,
     };
-    const ajv = new Ajv({
+    const ajv = new Ajv2020({
         removeAdditional: false,
         useDefaults: true,
         strict: false,

package/dist/esm/src/i18n/provider.js

@@ -12,6 +12,15 @@ export default class I18nProvider {
      *
      * @param allLocales - the list of all locales in your app. something like `{ en: { ... }, ['en-UK']: { ... }, es: { ... }, ... }`
      * @param singleLocaleKey - the key from the allLocales object that you want to use as your type base. i.e. 'en'
+     *
+     * Output-encoding note: interpolated values are substituted verbatim into the
+     * translation string. There is no HTML escaping at this layer — Psychic emits
+     * JSON, and the client renderer (React / Vue / Svelte / etc.) is responsible
+     * for context-appropriate escaping when the translated string enters a DOM.
+     * Do not pipe translated strings through `dangerouslySetInnerHTML` / `v-html` /
+     * `{@html}`. For rich-text translations, use structured dictionaries instead
+     * of HTML inside translation values. See `psychic-guides` → Security →
+     * Output Encoding & i18n.
      * */
     static provide(allLocales, singleLocaleKey) {
         return function i18n(locale, i18nPathString, interpolations) {

package/dist/esm/src/openapi-renderer/SerializerOpenapiRenderer.js

@@ -51,11 +51,15 @@ export default class SerializerOpenapiRenderer {
         alreadyExtractedDescendantSerializers[this.serializer.globalName] = true;
         const referencedSerializersAndOpenapiSchemaBodyShorthand = this._renderedOpenapi(alreadyExtractedDescendantSerializers);
         if (this.allOfSiblings.length) {
-            const openapi = referencedSerializersAndOpenapiSchemaBodyShorthand.openapi;
+            // Property-level locks live only at the `allOf` wrapper (never on the
+            // inline branch or the `$ref`'d siblings) so that all branches'
+            // properties are visible to `unevaluatedProperties` for the union check.
             return {
                 ...referencedSerializersAndOpenapiSchemaBodyShorthand,
                 openapi: {
-                    allOf: [openapi, ...this.allOfSiblings],
+                    type: 'object',
+                    allOf: [referencedSerializersAndOpenapiSchemaBodyShorthand.openapi, ...this.allOfSiblings],
+                    unevaluatedProperties: false,
                 },
             };
         }
@@ -98,7 +102,13 @@ export default class SerializerOpenapiRenderer {
                 type: 'object',
                 required: sort(uniq(requiredProperties.map(property => this.setCase(property)))),
                 properties: sortObjectByKey(referencedSerializersAndAttributes.attributes),
-                additionalProperties: false,
+                // Property-level locks (`additionalProperties` / `unevaluatedProperties`)
+                // are not emitted on leaf schemas: when a leaf is composed via `$ref`
+                // inside an `allOf`, neither keyword sees properties contributed by
+                // sibling branches, so a per-leaf lock incorrectly rejects flattened
+                // properties. Strictness is enforced at the `allOf`-wrapper level
+                // (`unevaluatedProperties: false`) when flattening occurs, and at the
+                // validation-pipeline level for top-level schemas.
             },
         };
     }

package/dist/esm/src/psychic-app/index.js

@@ -166,30 +166,45 @@ export default class PsychicApp {
     /**
      * @internal
      *
-     * adds the necessary package manager prefix to the psy command provided
-     * i.e. `psyCmd('sync')`
+     * Returns the argv-form invocation for a `psy` subcommand, ready to pass
+     * to `DreamCLI.spawn(command, { args })`. Example: `psyCmd('sync')` →
+     * `{ command: 'pnpm', args: ['psy', 'sync'] }` (under pnpm).
      */
-    psyCmd(cmd) {
-        return PackageManager.run(`psy ${cmd}`);
+    psyCmd(cmd, args = []) {
+        return PackageManager.run('psy', [cmd, ...args]);
     }
     /**
-     * prints a warning in the console if the encryption key
-     * is not valid for the provided algorithm.
+     * Throws (in production) or prints a warning (in non-production) if the
+     * encryption key is not valid for the provided algorithm.
+     *
+     * In production, a misconfigured key is a security hazard — the app would
+     * appear to boot successfully, then fail at runtime the first time a cookie
+     * is encrypted or decrypted, potentially leaving users with mysterious
+     * session errors long after the deploy. Fail-closed at boot instead.
+     *
+     * In development, continue to warn so that onboarding flows (where a
+     * placeholder key may briefly be in place while the env is being set up)
+     * are not broken by a hard failure.
      *
      * @param encryptionIdentifier - currently must be 'cookies', though this may change in the future
      * @param key - the encryption key you want to check
      * @param algorithm - the encryption algorithm you want to check
      */
     static checkEncryptionKey(encryptionIdentifier, key, algorithm) {
-        if (!Encrypt.validateKey(key, algorithm))
-            console.warn(`
+        if (Encrypt.validateKey(key, algorithm))
+            return;
+        const message = `
 Your current key value for ${encryptionIdentifier} encryption is invalid.
 Try setting it to something valid, like:
   ${Encrypt.generateKey(algorithm)}
 
 (This was done by calling:
   Encrypt.generateKey('${algorithm}')
-`);
+`;
+        if (EnvInternal.isProduction) {
+            throw new Error(message);
+        }
+        console.warn(message);
     }
     /**
      * Returns the cached psychic application if it has been set.
@@ -249,7 +264,32 @@ Try setting it to something valid, like:
     get corsOptions() {
         return this._corsOptions;
     }
+    _redirectAllowedHosts = Object.freeze([]);
+    /**
+     * Hostnames allowlisted for absolute-URL redirects issued via
+     * controller `redirect()` / `found()` / `movedPermanently()` / etc.
+     * Same-origin relative paths are always permitted; absolute URLs are
+     * rejected unless their hostname appears here (case-insensitive). The
+     * default is an empty allowlist, meaning external redirects fail-closed.
+     */
+    get redirectAllowedHosts() {
+        return this._redirectAllowedHosts;
+    }
     _jsonOptions;
+    /**
+     * Options passed through to `koa-bodyparser`. When unset, the upstream
+     * defaults apply — notably `jsonLimit: '1mb'` and `formLimit: '56kb'`,
+     * which cap request-body size at the framework boundary and defend against
+     * unbounded-payload memory DoS even when no edge (WAF / API Gateway)
+     * enforces a cap.
+     *
+     * Configure via `psy.set('json', { jsonLimit: '256kb' })` to tighten.
+     * Values are spread-merged, so partial overrides preserve untouched limits.
+     *
+     * See https://github.com/koajs/bodyparser for the full option list
+     * (`jsonLimit`, `formLimit`, `textLimit`, `xmlLimit`, `enableTypes`,
+     * `strict`, `detectJSON`, etc.).
+     */
     get jsonOptions() {
         return this._jsonOptions;
     }
@@ -369,7 +409,6 @@ Try setting it to something valid, like:
     }
     _baseDefaultResponseHeaders = {
         ['cache-control']: 'max-age=0, private, must-revalidate',
-        ['SameSite']: 'Strict',
     };
     _defaultResponseHeaders = {};
     get defaultResponseHeaders() {
@@ -505,6 +544,9 @@ Try setting it to something valid, like:
             case 'cors':
                 this._corsOptions = { ...this.corsOptions, ...value };
                 break;
+            case 'redirectAllowedHosts':
+                this._redirectAllowedHosts = Object.freeze([...value]);
+                break;
             case 'cookie':
                 this._cookieOptions = {
                     ...this.cookieOptions,

package/dist/esm/src/router/helpers.js

@@ -4,7 +4,10 @@ import CannotInferControllerFromTopLevelRouteError from '../error/router/cannot-
 import pascalizeFileName from '../helpers/pascalizeFileName.js';
 import PsychicApp from '../psychic-app/index.js';
 export function routePath(routePath) {
-    return `/${routePath.replace(/^\//, '')}`;
+    const normalized = `/${routePath.replace(/^\//, '')}`;
+    if (normalized === '/')
+        return normalized;
+    return normalized.replace(/\/+$/, '');
 }
 export function resourcePath(routePath) {
     return `/${routePath}/:id`;

package/dist/esm/src/router/index.js

@@ -72,7 +72,8 @@ export default class PsychicRouter {
     prefixPathWithNamespaces(str) {
         if (!this.currentNamespaces.length)
             return str;
-        return '/' + this.currentNamespacePaths.join('/') + '/' + str;
+        const prefix = '/' + this.currentNamespacePaths.join('/');
+        return str ? `${prefix}/${str}` : prefix;
     }
     crud(httpMethod, path, controllerOrMiddleware, action) {
         this.checkPathForInvalidChars(path);

package/dist/esm/src/server/index.js

@@ -86,7 +86,14 @@ export default class PsychicServer {
     setSecureDefaultHeaders() {
         // Koa doesn't send x-powered-by by default, no need to disable it.
         this.koaApp.use(async (ctx, next) => {
+            // Prevent MIME-sniffing; browsers must honor the declared Content-Type
+            // even if an endpoint accidentally serves something looking like HTML.
             ctx.set('X-Content-Type-Options', 'nosniff');
+            // Block cross-origin pages from embedding this response as a resource
+            // (<script src>, <img>, <link>, etc.), which raises the bar for
+            // speculative cross-origin reads (Spectre / XS-Leaks class). Applies
+            // to API responses regardless of Content-Type.
+            ctx.set('Cross-Origin-Resource-Policy', 'same-origin');
             if (EnvInternal.isProduction) {
                 ctx.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
             }
@@ -155,8 +162,16 @@ export default class PsychicServer {
         this.koaApp = new Koa();
     }
     initializeCors() {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-        this.koaApp.use(cors(PsychicApp.getOrFail().corsOptions));
+        const corsOptions = PsychicApp.getOrFail().corsOptions;
+        // When the app hasn't called psy.set('cors', ...), don't mount @koa/cors
+        // at all. @koa/cors with undefined options defaults `origin` to '*' and
+        // would emit Access-Control-Allow-Origin: * on every response — a
+        // foot-gun for an API serving user-scoped data. Not mounting leaves the
+        // response with no CORS headers, which the browser treats as same-origin
+        // only. Apps opt in to cross-origin by configuring cors explicitly.
+        if (corsOptions === undefined)
+            return;
+        this.koaApp.use(cors(corsOptions));
     }
     initializeJSON() {
         this.koaApp.use(koaBodyparser(PsychicApp.getOrFail().jsonOptions));

package/dist/esm/src/server/params.js

@@ -89,6 +89,44 @@ export default class Params {
         }
         return returnObj;
     }
+    /**
+     * ### .extract
+     *
+     * Typed + runtime-enforced allowlist extraction. Equivalent to
+     * {@link Params.for} with `only` moved to a required positional argument.
+     * Use from a controller via {@link PsychicController.extractParams}.
+     *
+     * The `allowed` array is constrained to `DreamParamSafeColumnNames<I>` at
+     * the type level, so protected columns (primary key, timestamps, belongs-to
+     * foreign keys, polymorphic type fields, STI `type` column, and any column
+     * in `explicitUnsafeParamColumns`) are TypeScript compile errors. At
+     * runtime, the existing intersection in `paramNamesForDreamClass` strips
+     * any column not also in the model's `paramSafeColumnsOrFallback()` set,
+     * so TS-bypass attempts still fail closed.
+     */
+    static extract(params, dreamClass, allowed, opts) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return Params.for(params, dreamClass, { ...(opts ?? {}), only: allowed });
+    }
+    /**
+     * ### .extractImplicit
+     *
+     * Implicit-allowlist extraction driven by the model's `paramSafeColumns`
+     * declaration (or, when undeclared, the framework's default-safe fallback
+     * from `paramSafeColumnsOrFallback()`). Equivalent to {@link Params.for}
+     * without `only`. Use from a controller via
+     * {@link PsychicController.extractImplicitParams}.
+     *
+     * Prefer {@link Params.extract} when the caller can enumerate the allowed
+     * columns at the call site — it makes the allowlist visible to reviewers
+     * at the point of use. Reach for this method when the model-level
+     * `paramSafeColumns` declaration is the canonical allowlist and duplicating
+     * it at each call site would create maintenance drift.
+     */
+    static extractImplicit(params, dreamClass, opts) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return Params.for(params, dreamClass, (opts ?? {}));
+    }
     static restrict(params, allowed) {
         if (params === null || params === undefined)
             return {};

package/dist/esm/src/session/index.js

@@ -18,6 +18,12 @@ export default class Session {
             ...opts,
             secure: opts.secure ?? EnvInternal.isProduction,
             httpOnly: opts.httpOnly ?? true,
+            // Psychic is a pure JSON API backend — it never renders HTML, so there
+            // is no link-click-navigates-to-Psychic UX that would need Lax. Strict
+            // blocks ALL cross-site cookie sending, which is the correct default
+            // for an API: the cookie should only ride requests that originated
+            // from our own client code, never from third-party pages.
+            sameSite: opts.sameSite ?? 'strict',
             maxAge: opts.maxAge
                 ? cookieMaxAgeFromCookieOpts(opts.maxAge)
                 : (PsychicApp.getOrFail().cookieOptions?.maxAge ?? cookieMaxAgeFromCookieOpts()),

package/dist/esm/src/watcher/Watcher.js

@@ -27,7 +27,8 @@ export default class Watcher {
                     const psy = PsychicApp.getOrFail();
                     this.syncing = true;
                     try {
-                        await DreamCLI.spawn(psy.psyCmd('sync'));
+                        const { command, args } = psy.psyCmd('sync');
+                        await DreamCLI.spawn(command, { args });
                     }
                     catch (err) {
                         DreamCLI.logger.log(`ERROR!`, { logPrefixColor: 'red' });

package/dist/types/src/bin/helpers/OpenApiSpecDiff.d.ts

@@ -81,7 +81,8 @@ export declare class OpenApiSpecDiff {
     /**
      * Detects oasdiff output that indicates no reportable changes for the
      * given subcommand. Newer oasdiff versions print informational messages
-     * like "No changes detected" or "No changes to report, but the specs are
+     * like "No changes detected", "No changes to report, but the specs are
+     * different", or "No breaking changes to report, but the specs are
      * different" to stdout rather than returning empty output.
      */
     private isNoChangesOutput;

package/dist/types/src/bin/index.d.ts

@@ -10,6 +10,8 @@ export default class PsychicBin {
         modelName?: string;
         tableName?: string;
         softDelete: boolean;
+        withExtractParams?: boolean;
+        withExtractImplicitParams?: boolean;
     }): Promise<void>;
     static printRoutes(): void;
     static printControllerHierarchy(controllersPath?: string): void;

package/dist/types/src/cli/helpers/PackageManager.d.ts

@@ -1,8 +1,12 @@
+export interface PackageManagerCommand {
+    command: string;
+    args: string[];
+}
 export default class PackageManager {
     static get packageManager(): "pnpm" | "yarn" | "npm";
     static add(dependencyOrDependencies: string | string[], { dev }?: {
         dev?: boolean;
-    }): string;
-    static run(cmd: string): string;
-    static exec(cmd: string): string;
+    }): PackageManagerCommand;
+    static run(cmd: string, args?: string[]): PackageManagerCommand;
+    static exec(cmd: string, args?: string[]): PackageManagerCommand;
 }

package/dist/types/src/cli/index.d.ts

@@ -32,6 +32,8 @@ export default class PsychicCLI {
             tableName?: string;
             modelName?: string;
             softDelete: boolean;
+            withExtractParams?: boolean;
+            withExtractImplicitParams?: boolean;
         };
         columnsWithTypes: string[];
     }): Promise<void>;

package/dist/types/src/controller/index.d.ts

@@ -5,7 +5,7 @@ import Koa from 'koa';
 import { ControllerHook } from '../controller/hooks.js';
 import { HttpStatusCodeInt, HttpStatusSymbol } from '../error/http/status-codes.js';
 import OpenapiEndpointRenderer from '../openapi-renderer/endpoint.js';
-import { ParamsCastOptions, ParamsForOpts, ValidatedAllowsNull, ValidatedReturnType } from '../server/params.js';
+import { ExtractParamsOpts, ParamsCastOptions, ParamsForOpts, ValidatedAllowsNull, ValidatedReturnType } from '../server/params.js';
 import Session, { CustomSessionCookieOptions } from '../session/index.js';
 type SerializerResult = {
     [key: string]: any;
@@ -251,10 +251,18 @@ export default class PsychicController {
     castParam<const EnumType extends readonly string[], OptsType extends StrictInterface<OptsType, ParamsCastOptions<EnumType>>, const ExpectedType extends PsychicParamsPrimitiveLiteral | RegExp | OpenapiSchemaBody>(key: string, expectedType: ExpectedType, opts?: OptsType): ValidatedAllowsNull<ExpectedType, OptsType> extends infer T ? T extends ValidatedAllowsNull<ExpectedType, OptsType> ? T extends true ? ValidatedReturnType<ExpectedType, OptsType> | null | undefined : ValidatedReturnType<ExpectedType, OptsType> : never : never;
     private _castParam;
     /**
-     * Captures and validates parameters for the provided Dream model. Will exclude
-     * parameters that are not considered "safe" by default (based on the model's paramSafeColumns).
-     * Uses `castParam` for each parameter and will raise an exception if any parameter
-     * fails validation.
+     * @deprecated Prefer {@link extractParams} (explicit allowlist at the call
+     * site) or {@link extractImplicitParams} (same implicit-allowlist behavior,
+     * new name). Security-relevant: on models with permission-bearing fields,
+     * `paramsFor(Model)` without `only` extracts every column in
+     * `paramSafeColumnsOrFallback()` — which may be too broad unless the model
+     * declares `paramSafeColumns` explicitly. `extractParams` makes the
+     * allowlist visible to reviewers at the call site.
+     *
+     * Captures and validates parameters for the provided Dream model. Will
+     * exclude parameters that are not considered "safe" by default (based on
+     * the model's paramSafeColumns). Uses `castParam` for each parameter and
+     * will raise an exception if any parameter fails validation.
      *
      * @param dreamClass - The Dream model class to retrieve params for
      * @param opts - Optional configuration object
@@ -269,17 +277,11 @@ export default class PsychicController {
      * ```ts
      * class MyController extends ApplicationController {
      *   public create() {
-     *     // Get safe params for User model (excludes sensitive fields like createdAt)
-     *     const userParams = this.paramsFor(User)
-     *
-     *     // Restrict to only specific fields
-     *     const restrictedParams = this.paramsFor(User, { only: ['email', 'name'] })
+     *     // Preferred: explicit allowlist via extractParams
+     *     const safe = this.extractParams(User, ['email', 'name'])
      *
-     *     // Include normally excluded fields
-     *     const extendedParams = this.paramsFor(User, { including: ['createdAt'] })
-     *
-     *     // Extract from nested key
-     *     const nestedParams = this.paramsFor(User, { key: 'user' })
+     *     // Equivalent of the legacy `this.paramsFor(User)` under the new name:
+     *     const viaModel = this.extractImplicitParams(User)
      *   }
      * }
      * ```
@@ -289,6 +291,77 @@ export default class PsychicController {
     }> : Partial<{
         [K in ParamSafeColumns[number & keyof ParamSafeColumns] & string]: DreamParamSafeAttributes<InstanceType<T>>[K & keyof DreamParamSafeAttributes<InstanceType<T>>];
     }>, ReturnPayload extends ForOpts['array'] extends true ? ReturnPartialType[] : ReturnPartialType>(this: PsychicController, dreamClass: T, opts?: ForOpts): ReturnPayload;
+    /**
+     * Captures and validates parameters for the provided Dream model using an
+     * explicit, required allowlist. This is the recommended primitive for
+     * controllers handling user-editable models — the allowlist is visible at
+     * the call site, so reviewers can see exactly which fields are accepted
+     * from the request.
+     *
+     * The `allowed` array is compile-time constrained to
+     * `DreamParamSafeColumnNames<InstanceType<T>>`, so protected columns
+     * (primary key, timestamps, belongs-to foreign keys, polymorphic type
+     * fields, STI `type` column, and any column in `explicitUnsafeParamColumns`)
+     * are TypeScript errors. At runtime, the intersection against the model's
+     * `paramSafeColumnsOrFallback()` further strips anything a caller bypasses
+     * the type system to include.
+     *
+     * Use {@link extractImplicitParams} when the model's declared
+     * `paramSafeColumns` is the canonical allowlist and duplicating it at each
+     * call site would create drift.
+     *
+     * @param dreamClass - The Dream model class to retrieve params for
+     * @param allowed - Required. The columns permitted from the request.
+     * @param opts - Optional configuration
+     * @param opts.key - Extract params from a nested key in the params object instead of root level
+     * @param opts.array - If true, expects and returns an array of param objects
+     * @returns A typed object containing the validated and casted params
+     * @throws {ParamValidationError} When any parameter validation fails
+     *
+     * @example
+     * ```ts
+     * class BalloonsController extends ApplicationController {
+     *   public create() {
+     *     const params = this.extractParams(Balloon, ['name', 'color'])
+     *     const balloon = await Balloon.create(params)
+     *   }
+     * }
+     * ```
+     */
+    extractParams<T extends typeof Dream, I extends InstanceType<T>, const AllowedArray extends readonly (keyof DreamParamSafeAttributes<I>)[], OptsType extends StrictInterface<OptsType, ExtractParamsOpts>, ParamSafeAttrs extends DreamParamSafeAttributes<I>, ReturnPartial extends Partial<{
+        [K in AllowedArray[number] & keyof ParamSafeAttrs]: ParamSafeAttrs[K & keyof ParamSafeAttrs];
+    }>, ReturnPayload extends OptsType['array'] extends true ? ReturnPartial[] : ReturnPartial>(this: PsychicController, dreamClass: T, allowed: AllowedArray, opts?: OptsType): ReturnPayload;
+    /**
+     * Captures and validates parameters for the provided Dream model using the
+     * model's declared `paramSafeColumns` (or, when undeclared, the framework's
+     * default-safe fallback from `paramSafeColumnsOrFallback()`).
+     *
+     * Prefer {@link extractParams} when the caller can enumerate the allowed
+     * columns at the call site — explicit allowlists are more visible to
+     * reviewers. Reach for `extractImplicitParams` when the model-level
+     * declaration is the canonical allowlist and you want to avoid duplicating
+     * it at every call site.
+     *
+     * @param dreamClass - The Dream model class to retrieve params for
+     * @param opts - Optional configuration
+     * @param opts.key - Extract params from a nested key in the params object instead of root level
+     * @param opts.array - If true, expects and returns an array of param objects
+     * @returns A typed object containing the validated and casted params
+     * @throws {ParamValidationError} When any parameter validation fails
+     *
+     * @example
+     * ```ts
+     * class AdminBalloonsController extends ApplicationController {
+     *   public create() {
+     *     const params = this.extractImplicitParams(Balloon)
+     *     const balloon = await Balloon.create(params)
+     *   }
+     * }
+     * ```
+     */
+    extractImplicitParams<T extends typeof Dream, I extends InstanceType<T>, OptsType extends StrictInterface<OptsType, ExtractParamsOpts>, ParamSafeColumnsOverride extends I['paramSafeColumns' & keyof I] extends never ? undefined : I['paramSafeColumns' & keyof I] & string[], ParamSafeColumns extends ParamSafeColumnsOverride extends string[] | Readonly<string[]> ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[], ParamSafeAttrs extends DreamParamSafeAttributes<I>, ReturnPartial extends Partial<{
+        [K in ParamSafeColumns[number & keyof ParamSafeColumns] & string]: ParamSafeAttrs[K & keyof ParamSafeAttrs];
+    }>, ReturnPayload extends OptsType['array'] extends true ? ReturnPartial[] : ReturnPartial>(this: PsychicController, dreamClass: T, opts?: OptsType): ReturnPayload;
     /**
      * Gets a cookie value from the request and casts it to the specified type.
      *

package/dist/types/src/encrypt/internal-encrypt.d.ts

@@ -1,6 +1,4 @@
 export default class InternalEncrypt {
     static encryptCookie(data: any): string | null;
-    static decryptCookie(data: any): unknown;
-    private static doEncryption;
-    private static doDecryption;
+    static decryptCookie<RetType>(data: any): RetType | null;
 }

package/dist/types/src/error/devtools/LaunchDevServerRequiresDevelopmentOrTest.d.ts

@@ -0,0 +1,5 @@
+export default class LaunchDevServerRequiresDevelopmentOrTest extends Error {
+    private cmd;
+    constructor(cmd: string);
+    get message(): string;
+}

package/dist/types/src/error/http/InternalServerError.d.ts

@@ -1,4 +1,8 @@
 import HttpError from './index.js';
+/**
+ * 500 Internal Server Error. `data` is for server-side diagnostics only:
+ * it is logged but never sent to the client.
+ */
 export default class HttpStatusInternalServerError extends HttpError {
     get status(): number;
 }

package/dist/types/src/error/openapi/OpenApiSpecDiffRequiresDevelopmentOrTest.d.ts

@@ -0,0 +1,3 @@
+export default class OpenApiSpecDiffRequiresDevelopmentOrTest extends Error {
+    get message(): string;
+}

package/dist/types/src/generate/controller.d.ts

@@ -1,4 +1,5 @@
-export default function generateController({ fullyQualifiedControllerName, fullyQualifiedModelName, actions, columnsWithTypes, resourceSpecs, owningModel, singular, }: {
+import { ParamExtractionStrategy } from './helpers/generateControllerContent.js';
+export default function generateController({ fullyQualifiedControllerName, fullyQualifiedModelName, actions, columnsWithTypes, resourceSpecs, owningModel, singular, paramExtractionStrategy, }: {
     fullyQualifiedControllerName: string;
     fullyQualifiedModelName?: string;
     actions: string[];
@@ -6,4 +7,5 @@ export default function generateController({ fullyQualifiedControllerName, fully
     resourceSpecs?: boolean;
     owningModel?: string | undefined;
     singular: boolean;
+    paramExtractionStrategy?: ParamExtractionStrategy | undefined;
 }): Promise<void>;

package/dist/types/src/generate/helpers/generateControllerContent.d.ts

@@ -1,4 +1,5 @@
-export default function generateControllerContent({ ancestorName, ancestorImportStatement, fullyQualifiedControllerName, fullyQualifiedModelName, actions, omitOpenApi, owningModel, forAdmin, forInternal, singular, }: {
+export type ParamExtractionStrategy = 'explicit' | 'implicit';
+export default function generateControllerContent({ ancestorName, ancestorImportStatement, fullyQualifiedControllerName, fullyQualifiedModelName, actions, omitOpenApi, owningModel, forAdmin, forInternal, singular, columnsWithTypes, paramExtractionStrategy, }: {
     ancestorName: string;
     ancestorImportStatement: string;
     fullyQualifiedControllerName: string;
@@ -9,4 +10,6 @@ export default function generateControllerContent({ ancestorName, ancestorImport
     forAdmin: boolean;
     forInternal?: boolean;
     singular: boolean;
+    columnsWithTypes?: string[];
+    paramExtractionStrategy?: ParamExtractionStrategy | undefined;
 }): string;

package/dist/types/src/generate/helpers/paramSafeColumnNamesFromCliTokens.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Derive the param-safe column names from the `columnsWithTypes` CLI tokens
+ * supplied to `psy g:resource`. Filters the same set Dream's
+ * `defaultParamSafeColumns()` filters at runtime
+ * (`dream/src/Dream.ts:826-844`) — accepted deliberate duplication, since
+ * the generator runs before a live model class exists (greenfield) and
+ * therefore cannot introspect via `ModelClass.paramSafeColumnsOrFallback()`.
+ *
+ * Delegates token parsing + camelCase normalization to the shared
+ * `parseAttribute` helper so the casing emitted into generated controllers
+ * matches what every other generator emits. Then drops the additional
+ * reserved names that `parseAttribute` does not filter on its own.
+ *
+ * Omits:
+ *   - Reserved camelCase names: `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`
+ *   - Type annotation `:belongs_to` (foreign keys)
+ *   - Name suffix `_type` (polymorphic type discriminators)
+ *   - Name suffix `_id` (polymorphic foreign keys)
+ */
+export default function paramSafeColumnNamesFromCliTokens(tokens: string[]): string[];

package/dist/types/src/generate/helpers/parseAttribute.d.ts

@@ -0,0 +1,18 @@
+export interface ParsedAttribute {
+    attributeName: string;
+    attributeType: string;
+    isArray: boolean;
+    enumValues?: string | undefined;
+}
+/**
+ * Parse a `name:type[:enumName:enumValues]` CLI token into its camelCase
+ * attribute name and metadata. Returns `null` for tokens that should be
+ * dropped from the generated artifact (polymorphic `_type`/`_id` columns,
+ * `deletedAt`, or malformed tokens missing a name or type).
+ *
+ * Centralized so generators (controller scaffolds, resource specs, the
+ * paramSafe column allowlist) share one canonical interpretation of the
+ * tokens — and one canonical casing (camelCase) for the resulting attribute
+ * name.
+ */
+export default function parseAttribute(attribute: string): ParsedAttribute | null;

package/dist/types/src/generate/resource.d.ts

@@ -12,6 +12,8 @@ export default function generateResource({ route, fullyQualifiedModelName, optio
         tableName?: string;
         modelName?: string;
         softDelete: boolean;
+        withExtractParams?: boolean;
+        withExtractImplicitParams?: boolean;
     };
     columnsWithTypes: string[];
 }): Promise<void>;

package/dist/types/src/helpers/isSafeRedirectTarget.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns true when `target` is a safe destination for an HTTP redirect.
+ *
+ * A safe target is either:
+ *   - a same-origin relative path beginning with a single `/` (not `//`, not `/\`),
+ *     with no control characters (CR/LF/NUL/etc.) that would enable response-splitting
+ *   - an absolute `http:` or `https:` URL whose hostname exactly matches an entry in
+ *     `opts.allowedHosts` (case-insensitive, port-insensitive — use explicit
+ *     entries with a port if port-restriction is desired at a deeper layer)
+ *
+ * Everything else is rejected, including:
+ *   - `javascript:`, `data:`, `vbscript:`, `file:` and other non-http(s) schemes
+ *   - scheme-relative URLs (`//evil.com`) and their backslash variants (`/\evil.com`)
+ *   - absolute URLs to hostnames not in the allowlist (even with userinfo tricks
+ *     like `http://allowed.com@evil.com/…` — WHATWG URL parses the host as `evil.com`)
+ *   - any input containing ASCII control characters, leading/trailing whitespace,
+ *     or raw NULs
+ *
+ * The allowlist is purposely restrictive (no wildcards yet). Applications that
+ * legitimately redirect to external destinations register hosts via
+ * `PsychicApp.set('redirectAllowedHosts', ['oauth.example.com'])`.
+ */
+export default function isSafeRedirectTarget(target: unknown, opts: {
+    allowedHosts: readonly string[];
+}): boolean;

package/dist/types/src/helpers/validateOpenApiSchema.d.ts

@@ -1,4 +1,5 @@
-import { Ajv, type ErrorObject, type JSONSchemaType, type ValidateFunction } from 'ajv';
+import { type ErrorObject, type JSONSchemaType, type ValidateFunction } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 /**
  * @internal
  *
@@ -72,8 +73,8 @@ export interface ValidationError {
     message: string;
     params?: Record<string, unknown>;
 }
-export type AjvValidationOpts = ConstructorParameters<typeof Ajv>[0];
+export type AjvValidationOpts = ConstructorParameters<typeof Ajv2020>[0];
 export type ValidateOpenapiSchemaOptions = AjvValidationOpts & CustomOpenapiValidationOptions;
 export interface CustomOpenapiValidationOptions {
-    init?: (ajv: Ajv) => void;
+    init?: (ajv: Ajv2020) => void;
 }