@hoajs/secure-headers 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v0.1.0 / 2025-10-29
+
+- init

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+## @hoajs/secure-headers
+
+SecureHeaders middleware for Hoa.
+
+## Installation
+
+```bash
+$ npm i @hoajs/secure-headers --save
+```
+
+## Quick Start
+
+```js
+import { Hoa } from 'hoa'
+import { secureHeaders } from '@hoajs/secure-headers'
+
+const app = new Hoa()
+app.use(secureHeaders())
+
+app.use(async (ctx) => {
+  ctx.res.body = `Hello, Hoa!`
+})
+
+export default app
+```
+
+## Documentation
+
+The documentation is available on [hoa-js.com](https://hoa-js.com/middleware/secure-headers.html)
+
+## Test (100% coverage)
+
+```sh
+$ npm test
+```
+
+## License
+
+MIT

package/dist/cjs/index.d.cts

@@ -0,0 +1,170 @@
+import { HoaContext, HoaMiddleware } from 'hoa';
+
+type ContentSecurityPolicyDirectiveValueFunction = (ctx: HoaContext) => string;
+type ContentSecurityPolicyDirectiveValue = string | ContentSecurityPolicyDirectiveValueFunction;
+interface ContentSecurityPolicyOptions {
+    useDefaults?: boolean;
+    directives?: Record<string, null | Iterable<ContentSecurityPolicyDirectiveValue> | typeof dangerouslyDisableDefaultSrc>;
+    reportOnly?: boolean;
+}
+interface ContentSecurityPolicy {
+    (options?: Readonly<ContentSecurityPolicyOptions>): HoaMiddleware;
+    getDefaultDirectives: typeof getDefaultDirectives;
+    dangerouslyDisableDefaultSrc: typeof dangerouslyDisableDefaultSrc;
+}
+declare const dangerouslyDisableDefaultSrc: unique symbol;
+declare const getDefaultDirectives: () => Record<string, Iterable<ContentSecurityPolicyDirectiveValue>>;
+declare const contentSecurityPolicy: ContentSecurityPolicy;
+
+interface CrossOriginEmbedderPolicyOptions {
+    policy?: 'require-corp' | 'credentialless' | 'unsafe-none';
+}
+declare function crossOriginEmbedderPolicy(options?: Readonly<CrossOriginEmbedderPolicyOptions>): HoaMiddleware;
+
+interface CrossOriginOpenerPolicyOptions {
+    policy?: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none';
+}
+declare function crossOriginOpenerPolicy(options?: Readonly<CrossOriginOpenerPolicyOptions>): HoaMiddleware;
+
+interface CrossOriginResourcePolicyOptions {
+    policy?: 'same-origin' | 'same-site' | 'cross-origin';
+}
+declare function crossOriginResourcePolicy(options?: Readonly<CrossOriginResourcePolicyOptions>): HoaMiddleware;
+
+declare function originAgentCluster(): HoaMiddleware;
+
+type ReferrerPolicyToken = 'no-referrer' | 'no-referrer-when-downgrade' | 'same-origin' | 'origin' | 'strict-origin' | 'origin-when-cross-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | '';
+interface ReferrerPolicyOptions {
+    policy?: ReferrerPolicyToken | ReferrerPolicyToken[];
+}
+declare function referrerPolicy(options?: Readonly<ReferrerPolicyOptions>): HoaMiddleware;
+
+interface StrictTransportSecurityOptions {
+    maxAge?: number;
+    includeSubDomains?: boolean;
+    preload?: boolean;
+}
+declare function strictTransportSecurity(options?: Readonly<StrictTransportSecurityOptions>): HoaMiddleware;
+
+declare function xContentTypeOptions(): HoaMiddleware;
+
+interface XDnsPrefetchControlOptions {
+    allow?: boolean;
+}
+declare function xDnsPrefetchControl(options?: Readonly<XDnsPrefetchControlOptions>): HoaMiddleware;
+
+declare function xDownloadOptions(): HoaMiddleware;
+
+interface XFrameOptionsOptions {
+    action?: 'deny' | 'sameorigin';
+}
+declare function xFrameOptions(options?: Readonly<XFrameOptionsOptions>): HoaMiddleware;
+
+interface XPermittedCrossDomainPoliciesOptions {
+    permittedPolicies?: 'none' | 'master-only' | 'by-content-type' | 'all';
+}
+declare function xPermittedCrossDomainPolicies(options?: Readonly<XPermittedCrossDomainPoliciesOptions>): HoaMiddleware;
+
+declare function xXssProtection(): HoaMiddleware;
+
+type PermissionsPolicyDirective = StandardizedFeatures | ProposedFeatures | ExperimentalFeatures;
+/**
+ * These features have been declared in a published version of the respective specification.
+ */
+type StandardizedFeatures = 'accelerometer' | 'ambientLightSensor' | 'attributionReporting' | 'autoplay' | 'battery' | 'bluetooth' | 'camera' | 'chUa' | 'chUaArch' | 'chUaBitness' | 'chUaFullVersion' | 'chUaFullVersionList' | 'chUaMobile' | 'chUaModel' | 'chUaPlatform' | 'chUaPlatformVersion' | 'chUaWow64' | 'computePressure' | 'crossOriginIsolated' | 'directSockets' | 'displayCapture' | 'encryptedMedia' | 'executionWhileNotRendered' | 'executionWhileOutOfViewport' | 'fullscreen' | 'geolocation' | 'gyroscope' | 'hid' | 'identityCredentialsGet' | 'idleDetection' | 'keyboardMap' | 'magnetometer' | 'microphone' | 'midi' | 'navigationOverride' | 'payment' | 'pictureInPicture' | 'publickeyCredentialsGet' | 'screenWakeLock' | 'serial' | 'storageAccess' | 'syncXhr' | 'usb' | 'webShare' | 'windowManagement' | 'xrSpatialTracking';
+/**
+ * These features have been proposed, but the definitions have not yet been integrated into their respective specs.
+ */
+type ProposedFeatures = 'clipboardRead' | 'clipboardWrite' | 'gamepad' | 'sharedAutofill' | 'speakerSelection';
+/**
+ * These features generally have an explainer only but may be available for experimentation by web developers.
+ */
+type ExperimentalFeatures = 'allScreensCapture' | 'browsingTopics' | 'capturedSurfaceControl' | 'conversionMeasurement' | 'digitalCredentialsGet' | 'focusWithoutUserActivation' | 'joinAdInterestGroup' | 'localFonts' | 'runAdAuction' | 'smartCard' | 'syncScript' | 'trustTokenRedemption' | 'unload' | 'verticalScroll';
+type PermissionsPolicyValue = '*' | 'self' | 'src' | 'none' | string;
+type PermissionPolicyOptions = Partial<Record<PermissionsPolicyDirective, PermissionsPolicyValue[] | boolean>>;
+declare function permissionPolicy(options?: PermissionPolicyOptions): HoaMiddleware;
+
+type SecureHeadersOptions = {
+    contentSecurityPolicy?: ContentSecurityPolicyOptions | boolean;
+    crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyOptions | boolean;
+    crossOriginOpenerPolicy?: CrossOriginOpenerPolicyOptions | boolean;
+    crossOriginResourcePolicy?: CrossOriginResourcePolicyOptions | boolean;
+    originAgentCluster?: boolean;
+    referrerPolicy?: ReferrerPolicyOptions | boolean;
+    permissionPolicy?: PermissionPolicyOptions;
+} & ({
+    strictTransportSecurity?: StrictTransportSecurityOptions | boolean;
+    hsts?: never;
+} | {
+    hsts?: StrictTransportSecurityOptions | boolean;
+    strictTransportSecurity?: never;
+}) & ({
+    xContentTypeOptions?: boolean;
+    noSniff?: never;
+} | {
+    noSniff?: boolean;
+    xContentTypeOptions?: never;
+}) & ({
+    xDnsPrefetchControl?: XDnsPrefetchControlOptions | boolean;
+    dnsPrefetchControl?: never;
+} | {
+    dnsPrefetchControl?: XDnsPrefetchControlOptions | boolean;
+    xDnsPrefetchControl?: never;
+}) & ({
+    xDownloadOptions?: boolean;
+    ieNoOpen?: never;
+} | {
+    ieNoOpen?: boolean;
+    xDownloadOptions?: never;
+}) & ({
+    xFrameOptions?: XFrameOptionsOptions | boolean;
+    frameguard?: never;
+} | {
+    frameguard?: XFrameOptionsOptions | boolean;
+    xFrameOptions?: never;
+}) & ({
+    xPermittedCrossDomainPolicies?: XPermittedCrossDomainPoliciesOptions | boolean;
+    permittedCrossDomainPolicies?: never;
+} | {
+    permittedCrossDomainPolicies?: XPermittedCrossDomainPoliciesOptions | boolean;
+    xPermittedCrossDomainPolicies?: never;
+}) & ({
+    xPoweredBy?: boolean;
+    hidePoweredBy?: never;
+} | {
+    hidePoweredBy?: boolean;
+    xPoweredBy?: never;
+}) & ({
+    xXssProtection?: boolean;
+    xssFilter?: never;
+} | {
+    xssFilter?: boolean;
+    xXssProtection?: never;
+});
+interface SecureHeaders {
+    (options?: SecureHeadersOptions): HoaMiddleware;
+    contentSecurityPolicy: typeof contentSecurityPolicy;
+    crossOriginEmbedderPolicy: typeof crossOriginEmbedderPolicy;
+    crossOriginOpenerPolicy: typeof crossOriginOpenerPolicy;
+    crossOriginResourcePolicy: typeof crossOriginResourcePolicy;
+    originAgentCluster: typeof originAgentCluster;
+    referrerPolicy: typeof referrerPolicy;
+    strictTransportSecurity: typeof strictTransportSecurity;
+    xContentTypeOptions: typeof xContentTypeOptions;
+    xDnsPrefetchControl: typeof xDnsPrefetchControl;
+    xDownloadOptions: typeof xDownloadOptions;
+    xFrameOptions: typeof xFrameOptions;
+    xPermittedCrossDomainPolicies: typeof xPermittedCrossDomainPolicies;
+    xXssProtection: typeof xXssProtection;
+    permissionPolicy: typeof permissionPolicy;
+    dnsPrefetchControl: typeof xDnsPrefetchControl;
+    frameguard: typeof xFrameOptions;
+    hsts: typeof strictTransportSecurity;
+    ieNoOpen: typeof xDownloadOptions;
+    noSniff: typeof xContentTypeOptions;
+    permittedCrossDomainPolicies: typeof xPermittedCrossDomainPolicies;
+    xssFilter: typeof xXssProtection;
+}
+declare const secureHeaders: SecureHeaders;
+
+export { type SecureHeadersOptions, contentSecurityPolicy, crossOriginEmbedderPolicy, crossOriginOpenerPolicy, crossOriginResourcePolicy, secureHeaders as default, xDnsPrefetchControl as dnsPrefetchControl, xFrameOptions as frameguard, strictTransportSecurity as hsts, xDownloadOptions as ieNoOpen, xContentTypeOptions as noSniff, originAgentCluster, permissionPolicy, xPermittedCrossDomainPolicies as permittedCrossDomainPolicies, referrerPolicy, secureHeaders, strictTransportSecurity, xContentTypeOptions, xDnsPrefetchControl, xDownloadOptions, xFrameOptions, xPermittedCrossDomainPolicies, xXssProtection, xXssProtection as xssFilter };