@scayle/h3-session 0.3.4

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# @scayle/h3-session
+
+## 0.3.4
+
+### Patch Changes
+
+- Add license file
+
+## 0.3.3
+
+### Patch Changes
+
+- New cookie settings should apply to existing cookies
+
+## 0.3.2
+
+### Patch Changes
+
+- Fix loading sessions created by express-session
+
+## 0.3.1
+
+### Patch Changes
+
+- raise required h3 peerDependency version to v1.8.0 and use only fixed dependencies
+
+## 0.3.0
+
+### Minor Changes
+
+- Support typing the session data
+
+### Patch Changes
+
+- Remove unused proxy option
+
+## 0.2.1
+
+### Patch Changes
+
+- Bump the compilation target to ES2022
+
+## 0.2.0
+
+### Minor Changes
+
+- Add h3-session package

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 SCAYLE GmbH
+
+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,150 @@
+# @scayle/h3-session
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+
+Persistent sessions for [h3](https://github.com/unjs/h3). Based on [express-session](https://www.npmjs.com/package/express-session).
+
+## Installation
+
+```bash
+# Using pnpm
+pnpm add @scayle/h3-session
+
+# Using yarn
+yarn add @scayle/h3-session
+
+# Using npm
+npm install @scayle/h3-session
+```
+
+## Usage
+
+```ts
+import { useSession, UnstorageSessionStore } from '@scayle/h3-session'
+import { createStorage } from 'unstorage'
+
+const DEFAULT_TTL = 60 * 60 * 24
+
+const redisStore = UnstorageSessionStore(
+  createStorage({
+    driver: redisDriver({
+      host: 'localhost',
+      port: 6379,
+    }),
+  }),
+  {
+    ttl: DEFAULT_TTL,
+  },
+)
+
+export default defineEventHandler(async (event) => {
+  await useSession(event, {
+    store: redisStore,
+    secret: 'my-secret',
+  })
+
+  const sessionId = event.context.sessionId
+  const sessionData = event.context.session.data
+})
+```
+
+## useSession options
+
+The following options can be passed as the second argument to `useSession`. `store` and `secret` must be defined.
+
+```ts
+interface H3SessionOptions {
+  // Where session data will be stored
+  store: SessionStore
+
+  // Settings for configuring the session cookie
+  // Cookies are serialized with [`cookie-es`](https://github.com/unjs/cookie-es).
+  // The default value is { path: '/', httpOnly: true, secure: true, maxAge: null }.
+  cookie?: {
+    domain?: string
+    expires?: Date
+    httpOnly?: boolean
+    maxAge?: number
+    path?: string
+    sameSite?: true | false | 'lax' | 'none' | 'strict'
+    secure?: boolean
+  }
+
+  // The name of the session cookie. Defaults to 'connect.sid'
+  name?: string
+
+  // Function to generate a session ID. Defaults to randomUUID
+  genid?: (event: H3Event) => string
+
+  // Function to generate new session data
+  generate?: () => SessionDataT
+
+  // Should the session be automatically saved on initialization?
+  saveUninitialized?: boolean
+
+  // Secret(s) to use for cookie signing
+  secret: string | string[]
+}
+```
+
+## Session object
+
+`useSession` attaches a `Session` object to `event.context.session`. The `Session` object has several methods along with an `id` property containing the session's ID, a `data` property which contains the session's data and a `cookie` property representing the session's cookie.
+
+### Session.save()
+
+Save the session to the store. Unlike `express-session`, session data is not saved automatically when it is changed, so this function should be called after modifying the session or at the end of the request.
+
+### Session.reload()
+
+Reload the session's data from the store.
+
+### Session.destroy()
+
+Destroy the session by removing its data from the store and deleting the cookie.
+
+### Session.regenerate()
+
+Recreate the session with a new ID and empty data.
+
+## SessionCookie
+
+The `cookie` property on the session can be used to control the session's cookie. Any of the cookie serialization options such as `maxAge` or `domain` can be edited and will affect the `Set-Cookie` header sent in the response. Additionally, `setSessionId(sid: string)` can be called to update the cookie's value with a new session ID.
+
+## SessionStore
+
+Any object implementing the `SessionStore` interface can be used as the `store` option.
+
+There is an included `UnstorageSessionStore` class to create `SessionStore` backed by an [`unstorage`](https://unstorage.unjs.io/) provider. To avoid accumulating dead sessions, use a driver (such as redis) which supports the `ttl` option.
+
+A reference to the store is added to `event.context.sessionStore` to enable manual management of the session data. (e.g. clearing all saved sessions)
+
+## Cookie signing
+
+The value of the session cookie is a signed variant of the session's ID. The format is `s:[sessionID].[signature]`. e.g. `s:7247d6e9-8ddb-4005-988b-9aa82bd7d6d5.lERU16bdv6tojUNeM8V2UOARyNxHNaWKIYi4bLRxx7o`. This matches the format used by `express-session`, so existing sessions can be preserved when migrating.
+
+The secret used for signing cookies is set in the options of `useSession`. It can be a `string` or `string[]`. When specified as an array, the last item will be used for signing new session cookies, but all secrets will be used to verify existing cookies. This allows changing the signing secret without invalidating existing sessions.
+
+## Typing
+
+The type of the session data can be specified by augmenting the `SessionDataT` interface.
+
+```ts
+declare module '@scayle/h3-session' {
+  export interface SessionDataT {
+    userId: string
+    token: string
+  }
+}
+```
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@scayle/h3-session/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
+[npm-version-href]: https://npmjs.com/package/@scayle/h3-session
+[npm-downloads-src]: https://img.shields.io/npm/dm/@scayle/h3-session.svg?style=flat&colorA=18181B&colorB=28CF8D
+[npm-downloads-href]: https://npmjs.com/package/@scayle/h3-session
+[license-src]: https://img.shields.io/npm/l/@scayle/h3-session.svg?style=flat&colorA=18181B&colorB=28CF8D
+[license-href]: https://npmjs.com/package/@scayle/h3-session

package/dist/index.js

@@ -0,0 +1,158 @@
+// A session implementation for h3 based on express-session
+import { getCookie, setCookie } from 'h3';
+import { defu } from 'defu';
+import { subtle, randomUUID } from 'uncrypto';
+import { Session } from './session';
+/**
+ * Verify that a cookie was signed with one of the secrets
+ * If it's valid, return the embedded message
+ *
+ * @param value a cookie value in the format `s:[value].[signature]`
+ * @param secrets an array of secret strings to verify with
+ */
+async function unsignCookie(value, secrets) {
+    // Validate cookie format
+    const matches = /s:([^.]*)\.(.*)/.exec(value);
+    if (!matches) {
+        return false;
+    }
+    const [, message, signature] = matches;
+    const encoder = new TextEncoder();
+    const messageUint8Array = encoder.encode(message);
+    const signatureUint8Array = Uint8Array.from(Buffer.from(signature, 'base64'));
+    for (let i = 0; i < secrets.length; i++) {
+        const keyUint8Array = encoder.encode(secrets[i]);
+        const cryptoKey = await subtle.importKey('raw', keyUint8Array, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        const result = await subtle.verify('HMAC', cryptoKey, signatureUint8Array, messageUint8Array);
+        if (result) {
+            return message;
+        }
+    }
+    return false;
+}
+/**
+ * Creates a signed cookie value in the format `s:[value].[signature]`
+ * @param value
+ * @param secret
+ */
+async function signCookie(value, secret) {
+    // Convert the value and secret to Uint8Array
+    const encoder = new TextEncoder();
+    const messageUint8Array = encoder.encode(value);
+    const keyUint8Array = encoder.encode(secret);
+    // Import the secret as a CryptoKey
+    const cryptoKey = await subtle.importKey('raw', keyUint8Array, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await subtle.sign('HMAC', cryptoKey, messageUint8Array);
+    // Encode in base64
+    const b64Signature = Buffer.from(signature)
+        .toString('base64')
+        .replace(/=+$/, '');
+    return `s:${value}.${b64Signature}`;
+}
+function validateConfig(config) {
+    if (!config.store) {
+        throw new Error('[h3-session] Session store is required!');
+    }
+    if (!config.secret) {
+        throw new Error('[h3-session] Session secret is required!');
+    }
+}
+/**
+ * Attach a session to an H3Event
+ * @param event
+ * @param config
+ */
+export async function useSession(event, config) {
+    // Skip if session is already attached
+    if (event.context.session) {
+        return;
+    }
+    validateConfig(config);
+    // Populate default config values
+    const sessionConfig = defu(config, {
+        name: 'connect.sid',
+        genid: (_event) => {
+            return randomUUID();
+        },
+        generate: () => ({}),
+        cookie: { path: '/', httpOnly: true, secure: true, maxAge: null },
+        saveUninitialized: false,
+    });
+    const { store } = sessionConfig;
+    const generate = async () => {
+        return await Promise.resolve({
+            id: sessionConfig.genid(event),
+            data: sessionConfig.generate(),
+        });
+    };
+    const createSessionCookie = async (sid) => {
+        let signedCookie;
+        const cookie = {
+            ...sessionConfig.cookie,
+            // Default to a max age of one day
+            maxAge: sessionConfig.cookie.maxAge || 60 * 60 * 24,
+            setSessionId: async (sid) => {
+                signedCookie = await signCookie(sid, normalizedSecrets[normalizedSecrets.length - 1]);
+                setCookie(event, sessionConfig.name, signedCookie, cookie);
+            },
+        };
+        await cookie.setSessionId(sid);
+        // Update the Set-Cookie header whenever a property on the cookie object changes
+        // We can't hook into the onBeforeResponse, so this is the best alternative
+        return new Proxy(cookie, {
+            set(target, property, value) {
+                // @ts-ignore
+                target[property] = value;
+                setCookie(event, sessionConfig.name, signedCookie, cookie);
+                return true;
+            },
+        });
+    };
+    // Secret can be a string or array, normalize to an array
+    const normalizedSecrets = Array.isArray(sessionConfig.secret)
+        ? sessionConfig.secret
+        : [sessionConfig.secret];
+    // Check the request for a session cookie
+    const rawCookie = getCookie(event, sessionConfig.name);
+    // Extract the ID from the cookie
+    const sessionId = rawCookie
+        ? await unsignCookie(rawCookie, normalizedSecrets)
+        : null;
+    // Load the session data from the store
+    let sessionData;
+    if (sessionId) {
+        sessionData = await store.get(sessionId);
+    }
+    async function createNewSession() {
+        const { id, data } = await generate();
+        const cookie = await createSessionCookie(id);
+        event.context.session = new Session(id, data, store, generate, cookie);
+        if (sessionConfig.saveUninitialized) {
+            await event.context.session.save();
+        }
+        // Set sessionId on event context
+        event.context.sessionId = id;
+    }
+    async function createExistingSession(id, data) {
+        const cookie = await createSessionCookie(id);
+        if (store.touch) {
+            // touch existing sessions to refresh their TTLs
+            await store.touch(id, data);
+        }
+        event.context.session = new Session(id, data, store, generate, cookie);
+        // Set sessionId on event context
+        event.context.sessionId = id;
+    }
+    // Create the session data and a new ID if it does not exist
+    if (!sessionId || !sessionData) {
+        await createNewSession();
+    }
+    else {
+        await createExistingSession(sessionId, sessionData);
+    }
+    // expose session store
+    event.context.sessionStore = store;
+}
+export * from './session';
+export * from './unstorage-store';
+//# sourceMappingURL=index.js.map

package/dist/session.js

@@ -0,0 +1,37 @@
+export class Session {
+    #id;
+    #store;
+    data;
+    #generate;
+    cookie;
+    constructor(id, data, store, generate, cookie) {
+        this.data = data;
+        this.#id = id;
+        this.#store = store;
+        this.#generate = generate;
+        this.cookie = cookie;
+    }
+    get id() {
+        return this.#id;
+    }
+    async save() {
+        await this.#store.set(this.#id, { ...this.data, cookie: this.cookie });
+    }
+    async reload() {
+        this.data =
+            (await this.#store.get(this.#id)) ?? (await this.#generate()).data;
+    }
+    async destroy() {
+        // Delete the cookie by setting maxAge to 0
+        this.cookie.maxAge = 0;
+        await this.#store.destroy(this.#id);
+    }
+    async regenerate() {
+        await this.#store.destroy(this.#id);
+        const { data, id } = await this.#generate();
+        this.data = data;
+        this.#id = id;
+        await Promise.all([this.cookie.setSessionId(id), this.save()]);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/unstorage-store.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+const CookieSchema = z.object({
+    domain: z.string().optional(),
+    expires: z.coerce.date().optional(),
+    httpOnly: z.boolean().optional(),
+    maxAge: z.number().optional(),
+    path: z.string().optional(),
+    sameSite: z.enum(['lax', 'none', 'strict']).or(z.boolean()).optional(),
+    secure: z.boolean().optional(),
+});
+export class UnstorageSessionStore {
+    storage;
+    prefix;
+    ttl;
+    constructor(storage, options) {
+        this.storage = storage;
+        this.prefix = options?.prefix ?? 'sess';
+        this.ttl = options?.ttl ?? 60 * 60 * 24;
+    }
+    /**
+     * Destroy the session with the specified session ID
+     * @param sid the un-prefixed session ID
+     */
+    async destroy(sid) {
+        await this.storage.removeItem(this.getKey(sid));
+    }
+    /**
+     * Get the session with the specified session ID
+     * @param sid the un-prefixed session ID
+     */
+    async get(sid) {
+        const item = await this.storage.getItem(this.getKey(sid));
+        // If the cookie saved in the storage is not valid, delete it
+        if (item && item.cookie) {
+            try {
+                item.cookie = CookieSchema.parse(item.cookie);
+            }
+            catch (e) {
+                delete item.cookie;
+            }
+        }
+        return item ?? undefined;
+    }
+    /**
+     * Save the session with the specified session ID
+     * If the session has expired (has a TTL <= 0) it is deleted.
+     * @param sid the un-prefixed session ID
+     * @param data the session data
+     */
+    async set(sid, data) {
+        const ttl = this.getTTL(data);
+        if (ttl > 0) {
+            await this.storage.setItem(this.getKey(sid), data, { ttl });
+        }
+        else {
+            await this.destroy(sid);
+        }
+    }
+    /**
+     * Update a session's TTL
+     * @param sid the un-prefixed session ID
+     * @param data the session data
+     */
+    async touch(sid, data) {
+        // For now, it seems the best way to bump the TTL through the unstorage
+        // interface is by re-saving the data
+        await this.set(sid, data);
+    }
+    /**
+     * Remove all saved sessions
+     */
+    async clear() {
+        return await this.storage.clear(this.prefix);
+    }
+    /**
+     * Fetch all saved sessions.
+     */
+    async all() {
+        const keys = await this.getAllKeys();
+        const values = await this.storage.getItems(keys);
+        return values.map(({ value }) => {
+            return value;
+        });
+    }
+    /**
+     * Returns the number of saved sessions
+     */
+    async length() {
+        const keys = await this.getAllKeys();
+        return keys.length;
+    }
+    async getAllKeys() {
+        return await this.storage.getKeys(this.prefix);
+    }
+    getKey(key) {
+        return [this.prefix, key].join(':');
+    }
+    /**
+     * Get the TTL for the session, either from the TTL function if it exists
+     * or falling back to the default TTL value.
+     * @param session
+     * @private
+     */
+    getTTL(session) {
+        if (typeof this.ttl === 'function') {
+            return this.ttl(session);
+        }
+        return this.ttl;
+    }
+}
+//# sourceMappingURL=unstorage-store.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@scayle/h3-session",
+  "version": "0.3.4",
+  "description": "Persistent sessions for h3",
+  "author": "SCAYLE Commerce Engine",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "CHANGELOG.md",
+    "./dist/*.js"
+  ],
+  "scripts": {
+    "build": "yarn tsc -p tsconfig.json",
+    "format": "prettier --ignore-unknown --log-level warn --check .",
+    "format:fix": "prettier --ignore-unknown --log-level warn --write .",
+    "lint": "eslint . --format gitlab",
+    "lint:fix": "eslint . --fix"
+  },
+  "peerDependencies": {
+    "h3": "^1.8.0"
+  },
+  "dependencies": {
+    "defu": "6.1.3",
+    "uncrypto": "0.1.3",
+    "unstorage": "1.9.0",
+    "zod": "3.22.4"
+  },
+  "devDependencies": {
+    "@changesets/types": "5.2.1",
+    "@scayle/eslint-config-storefront": "3.2.5",
+    "@scayle/prettier-config-storefront": "2.0.2",
+    "eslint": "8.52.0",
+    "eslint-formatter-gitlab": "5.0.0",
+    "h3": "1.8.2",
+    "prettier": "3.0.0",
+    "typescript": "5.2.2"
+  },
+  "volta": {
+    "node": "20.9.0"
+  }
+}