@stacksjs/server 0.75.226 → 0.75.230

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './proxy';
 export * from './redirects';
 export * from './rewrites';
 export * from './security-headers';
+export * from './shadowed-defaults';

package/dist/index.js

@@ -1 +1 @@
-export{config as server}from"./config";export*from"./controllers/base";export*from"./imports";export*from"./maintenance";export*from"./proxy";export*from"./redirects";export*from"./rewrites";export*from"./security-headers";
+export{config as server}from"./config";export*from"./controllers/base";export*from"./imports";export*from"./maintenance";export*from"./proxy";export*from"./redirects";export*from"./rewrites";export*from"./security-headers";export*from"./shadowed-defaults";

package/dist/shadowed-defaults.d.ts

@@ -0,0 +1,60 @@
+import { path } from '@stacksjs/path';
+/** A short, stable fingerprint of a default's contents. */
+export declare function defaultFingerprint(contents: Uint8Array | string): string;
+/**
+ * List the application files that shadow a framework security default.
+ *
+ * `appDir` is the application's `app/`, `defaultsDir` the framework's
+ * `defaults/app/`. A listed file the framework no longer ships is not a
+ * shadow and is skipped. A modified override carrying
+ * `stacks-reviewed-default: <fingerprint>` for the current default is
+ * treated as reviewed and left out. Never throws: an unreadable file is
+ * skipped, since a diagnostic must not stop a boot.
+ */
+export declare function findShadowedSecurityDefaults(appDir: string, defaultsDir: string, files?: readonly string[]): ShadowedSecurityDefault[];
+/** One readable warning for a list of shadowed defaults. */
+export declare function describeShadowedSecurityDefaults(entries: readonly ShadowedSecurityDefault[]): string;
+/**
+ * Warn once per process about app files shadowing security defaults.
+ *
+ * Called from the API server entries. Cheap (a stat per listed file, and a
+ * read only for the ones the app has) and never throws. Returns what it found,
+ * which is empty when silenced or already run.
+ */
+export declare function warnShadowedSecurityDefaults(options?: WarnShadowedSecurityDefaultsOptions): ShadowedSecurityDefault[];
+/**
+ * The framework defaults whose job is security, as paths relative to `app/`.
+ *
+ * Authentication, session and token issuance, password reset, request
+ * forgery, cross-origin policy, rate limiting, signed URLs and the
+ * authorization middleware. Helpers the auth actions import by relative path
+ * are listed too: a copied action resolves its helper from `app/` as well.
+ *
+ * Keep it explicit. A default not listed here can still be overridden; it just
+ * does not warn.
+ */
+export declare const SECURITY_DEFAULT_FILES: readonly string[];
+/**
+ * The comment an application adds to a modified override once it has been
+ * reviewed against the current default, followed by the default's fingerprint.
+ *
+ * Tied to the default's content, not to a flag: when the framework changes
+ * that default, the fingerprint stops matching and the warning returns, which
+ * is the moment a review is needed again.
+ */
+export declare const SHADOWED_DEFAULT_REVIEW_MARKER: 'stacks-reviewed-default:';
+/** Environment variable that turns the boot warning off. */
+export declare const SHADOWED_DEFAULTS_ENV: 'STACKS_SHADOWED_DEFAULTS_WARN';
+export declare interface ShadowedSecurityDefault {
+  path: string
+  kind: 'identical' | 'modified'
+  appFile: string
+  defaultFile: string
+  fingerprint: string
+}
+export declare interface WarnShadowedSecurityDefaultsOptions {
+  appDir?: string
+  defaultsDir?: string
+  warn?: (message: string) => void
+  force?: boolean
+}

package/dist/shadowed-defaults.js

@@ -0,0 +1,2 @@
+import{createHash}from"node:crypto";import{existsSync,readFileSync,statSync}from"node:fs";import{join}from"node:path";import process from"node:process";import{log}from"@stacksjs/logging/runtime";import{path}from"@stacksjs/path";import{frameworkDefaultsDir}from"./imports";export const SECURITY_DEFAULT_FILES=Object.freeze(["Middleware/Auth.ts","Middleware/Guest.ts","Middleware/Csrf.ts","Middleware/Cors.ts","Middleware/Throttle.ts","Middleware/Signed.ts","Middleware/Abilities.ts","Middleware/Can.ts","Middleware/Permission.ts","Middleware/Role.ts","Middleware/EnsureEmailIsVerified.ts","Actions/Auth/LoginAction.ts","Actions/Auth/LogoutAction.ts","Actions/Auth/LogoutAllAction.ts","Actions/Auth/RegisterAction.ts","Actions/Auth/RefreshTokenAction.ts","Actions/Auth/VerifyTwoFactorLoginAction.ts","Actions/Auth/VerifyEmailAction.ts","Actions/Auth/MagicLinkSendAction.ts","Actions/Auth/MagicLinkConsumeAction.ts","Actions/Auth/PasskeyAuthenticationAction.ts","Actions/Auth/VerifyAuthenticationAction.ts","Actions/Auth/SocialRedirectAction.ts","Actions/Auth/SocialCallbackAction.ts","Actions/Auth/SessionHandoffAction.ts","Actions/Auth/social-flow.ts","Actions/Auth/token-request.ts","Actions/Auth/CreateTokenAction.ts","Actions/Auth/RevokeTokenAction.ts","Actions/Auth/OAuthAuthorizationAction.ts","Actions/Auth/OAuthTokenAction.ts","Actions/Auth/oauth-request.ts","Actions/Password/SendPasswordResetEmailAction.ts","Actions/Password/VerifyResetTokenAction.ts","Actions/Password/PasswordResetAction.ts"]),SHADOWED_DEFAULT_REVIEW_MARKER="stacks-reviewed-default:",SHADOWED_DEFAULTS_ENV="STACKS_SHADOWED_DEFAULTS_WARN";export function defaultFingerprint(contents){return createHash("sha256").update(contents).digest("hex").slice(0,16)}function isFile(file){try{return statSync(file).isFile()}catch{return!1}}function sameBytes(a,b){if(a.byteLength!==b.byteLength)return!1;for(let i=0;i<a.byteLength;i++)if(a[i]!==b[i])return!1;return!0}export function findShadowedSecurityDefaults(appDir,defaultsDir,files=SECURITY_DEFAULT_FILES){const found=[];for(const relative of files){const appFile=join(appDir,relative),defaultFile=join(defaultsDir,relative);try{if(!isFile(appFile)||!isFile(defaultFile))continue;const own=readFileSync(appFile),framework=readFileSync(defaultFile),fingerprint=defaultFingerprint(framework);if(sameBytes(own,framework)){found.push({path:relative,kind:"identical",appFile,defaultFile,fingerprint});continue}if(own.toString("utf8").includes(`${SHADOWED_DEFAULT_REVIEW_MARKER} ${fingerprint}`))continue;found.push({path:relative,kind:"modified",appFile,defaultFile,fingerprint})}catch{}}return found}export function describeShadowedSecurityDefaults(entries){const lines=entries.map((entry)=>{if(entry.kind==="identical")return`  - app/${entry.path} is an unchanged copy of the framework default. Delete it to receive security fixes.`;return`  - app/${entry.path} differs from the framework default (${entry.defaultFile}). Review it against the current default; once reviewed, add the comment \`// ${SHADOWED_DEFAULT_REVIEW_MARKER} ${entry.fingerprint}\` to it.`});return[`[security] ${entries.length} app/ file${entries.length===1?"":"s"} shadow${entries.length===1?"s":""} a framework security default, so framework security fixes to ${entries.length===1?"it do":"them do"} not reach this app:`,...lines,`  Set ${SHADOWED_DEFAULTS_ENV}=false to silence this warning.`].join(`
+`)}let warned=!1;export function warnShadowedSecurityDefaults(options={}){if(warned&&!options.force)return[];warned=!0;if(String(process.env[SHADOWED_DEFAULTS_ENV]??"").toLowerCase()==="false")return[];try{const appDir=options.appDir??path.appPath(),defaultsDir=options.defaultsDir??frameworkDefaultsDir("app");if(!appDir||!defaultsDir||!existsSync(appDir)||!existsSync(defaultsDir))return[];const found=findShadowedSecurityDefaults(appDir,defaultsDir);if(found.length>0)(options.warn??((message)=>log.warn(message)))(describeShadowedSecurityDefaults(found));return found}catch{return[]}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/server",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.226",
+  "version": "0.75.230",
   "description": "Local development and production-ready.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,21 +58,21 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/auth": "0.75.226",
+    "@stacksjs/auth": "0.75.230",
     "@stacksjs/bun-router": "^0.1.24",
-    "@stacksjs/config": "0.75.226",
-    "@stacksjs/events": "0.75.226",
-    "@stacksjs/i18n": "0.75.226",
-    "@stacksjs/logging": "0.75.226",
-    "@stacksjs/orm": "0.75.226",
-    "@stacksjs/path": "0.75.226",
-    "@stacksjs/payments": "0.75.226",
-    "@stacksjs/router": "0.75.226",
-    "@stacksjs/storage": "0.75.226",
+    "@stacksjs/config": "0.75.230",
+    "@stacksjs/events": "0.75.230",
+    "@stacksjs/i18n": "0.75.230",
+    "@stacksjs/logging": "0.75.230",
+    "@stacksjs/orm": "0.75.230",
+    "@stacksjs/path": "0.75.230",
+    "@stacksjs/payments": "0.75.230",
+    "@stacksjs/router": "0.75.230",
+    "@stacksjs/storage": "0.75.230",
     "bun-plugin-auto-imports": "^0.4.4"
   },
   "devDependencies": {
-    "@stacksjs/validation": "0.75.226",
+    "@stacksjs/validation": "0.75.230",
     "better-dx": "^0.2.24"
   }
 }