@rvoh/psychic 3.1.3 → 3.2.1

package/dist/types/src/i18n/provider.d.ts

@@ -9,6 +9,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<const AllLocales, const SingleLocaleKey extends keyof AllLocales & string, LocalesEnum extends string = (typeof I18nDefaultLocales)[number], SingleLocaleShape = AllLocales[SingleLocaleKey]>(allLocales: AllLocales, singleLocaleKey: SingleLocaleKey): (locale: LocalesEnum, i18nPathString: DottedLanguageObjectStringPaths<SingleLocaleShape> & string, interpolations?: Record<string, string | number>) => string;
 }

package/dist/types/src/psychic-app/index.d.ts

@@ -101,13 +101,23 @@ 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: string): string;
+    psyCmd(cmd: string, args?: string[]): import("../cli/helpers/PackageManager.js").PackageManagerCommand;
     /**
-     * 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
@@ -144,7 +154,30 @@ export default class PsychicApp {
     get httpServerOptions(): http.ServerOptions<typeof http.IncomingMessage, typeof http.ServerResponse> | https.ServerOptions<typeof http.IncomingMessage, typeof http.ServerResponse>;
     private _corsOptions;
     get corsOptions(): cors.Options;
+    private _redirectAllowedHosts;
+    /**
+     * 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(): readonly string[];
     private _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(): bodyParser.Options;
     private _cookieOptions;
     get cookieOptions(): {
@@ -222,10 +255,10 @@ export default class PsychicApp {
     plugin(cb: (app: PsychicApp) => void | Promise<void>): void;
     on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, ctx: Koa.Context) => void | Promise<void> : T extends 'server:init:before-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'cli:start' ? (program: Command) => void | Promise<void> : T extends 'cli:sync' ? () => any : (conf: PsychicApp) => void | Promise<void>): void;
     set(option: 'openapi', name: string, value: NamedPsychicOpenapiOptions): void;
-    set<Opt extends PsychicAppOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'httpServerOptions' ? http.ServerOptions | https.ServerOptions : Opt extends 'encryption' ? PsychicAppEncryptionOptions : Opt extends 'cors' ? cors.Options : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'importExtension' ? GeneratorImportStyle : Opt extends 'sessionCookieName' ? string : Opt extends 'json' ? bodyParser.Options : Opt extends 'logger' ? PsychicLogger : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : never): void;
+    set<Opt extends PsychicAppOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'httpServerOptions' ? http.ServerOptions | https.ServerOptions : Opt extends 'encryption' ? PsychicAppEncryptionOptions : Opt extends 'cors' ? cors.Options : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'importExtension' ? GeneratorImportStyle : Opt extends 'sessionCookieName' ? string : Opt extends 'json' ? bodyParser.Options : Opt extends 'logger' ? PsychicLogger : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : Opt extends 'redirectAllowedHosts' ? readonly string[] : never): void;
     override<Override extends keyof PsychicAppOverrides>(override: Override, value: PsychicAppOverrides[Override]): void;
 }
-export type PsychicAppOption = 'appName' | 'apiOnly' | 'apiRoot' | 'httpServerOptions' | 'importExtension' | 'encryption' | 'sessionCookieName' | 'cookie' | 'cors' | 'defaultResponseHeaders' | 'inflections' | 'json' | 'logger' | 'openapi' | 'packageManager' | 'paths' | 'port' | 'routes' | 'saltRounds' | 'ssl';
+export type PsychicAppOption = 'appName' | 'apiOnly' | 'apiRoot' | 'httpServerOptions' | 'importExtension' | 'encryption' | 'sessionCookieName' | 'cookie' | 'cors' | 'defaultResponseHeaders' | 'inflections' | 'json' | 'logger' | 'openapi' | 'packageManager' | 'paths' | 'port' | 'redirectAllowedHosts' | 'routes' | 'saltRounds' | 'ssl';
 export interface PsychicAppSpecialHooks {
     cliSync: (() => any)[];
     serverInitBeforeMiddleware: ((server: PsychicServer) => void | Promise<void>)[];

package/dist/types/src/server/params.d.ts

@@ -24,6 +24,42 @@ export default class Params {
     }> : Partial<{
         [K in ParamSafeColumns[number & keyof ParamSafeColumns] & string & keyof ParamSafeAttrs]: ParamSafeAttrs[K & keyof ParamSafeAttrs];
     }>, ReturnPayload extends ForOpts['array'] extends true ? ReturnPartialType[] : ReturnPartialType>(params: object, dreamClass: T, forOpts?: ForOpts): ReturnPayload;
+    /**
+     * ### .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<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>(params: object, dreamClass: T, allowed: AllowedArray, opts?: OptsType): ReturnPayload;
+    /**
+     * ### .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<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>(params: object, dreamClass: T, opts?: OptsType): ReturnPayload;
     static restrict<T extends typeof Params>(this: T, params: PsychicParamsPrimitive | PsychicParamsDictionary | PsychicParamsDictionary[], allowed: string[]): PsychicParamsDictionary;
     /**
      * ### .cast
@@ -102,6 +138,16 @@ interface ParamsForOptsBase<OnlyArray> {
 export interface ParamsForOpts<OnlyArray> extends ParamsForOptsBase<OnlyArray> {
     key?: string;
 }
+/**
+ * Options for {@link Params.extract} / {@link Params.extractImplicit} and the
+ * corresponding controller methods. Mirrors {@link ParamsForOpts} minus
+ * `only` — the explicit allowlist moved to a required positional argument on
+ * `extractParams`, and `extractImplicitParams` has no allowlist argument.
+ */
+export interface ExtractParamsOpts {
+    array?: boolean;
+    key?: string;
+}
 export interface OpenAPIDreamModelRequestBodyModifications<OnlyArray, IncludingArray> extends ParamsForOptsBase<OnlyArray> {
     combining?: OpenapiSchemaPropertiesShorthand;
     including?: IncludingArray;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "3.1.3",
+  "version": "3.2.1",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -75,7 +75,7 @@
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
     "@koa/router": "^15.3.0",
-    "@rvoh/dream": "^2.7.0",
+    "@rvoh/dream": "^2.9.0",
     "@types/koa": "^3.0.1",
     "@types/koa-bodyparser": "^4.3.12",
     "@types/koa-conditional-get": "^2.0.3",
@@ -92,7 +92,7 @@
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
     "@koa/router": "^15.3.1",
-    "@rvoh/dream": "^2.7.0",
+    "@rvoh/dream": "^2.9.0",
     "@rvoh/dream-spec-helpers": "^2.1.1",
     "@rvoh/psychic-spec-helpers": "3.0.0",
     "@types/koa": "^3.0.1",
@@ -141,7 +141,8 @@
   "packageManager": "pnpm@10.26.0+sha512.3b3f6c725ebe712506c0ab1ad4133cf86b1f4b687effce62a9b38b4d72e3954242e643190fc51fa1642949c735f403debd44f5cb0edd657abe63a8b6a7e1e402",
   "pnpm": {
     "overrides": {
-      "diff": ">=8.0.3"
+      "diff": ">=8.0.3",
+      "path-to-regexp": ">=8.4.0"
     }
   }
 }