@remix-run/session-middleware 0.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+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,99 @@
+# session-middleware
+
+Middleware for managing sessions with [`@remix-run/fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) via securely signed cookies.
+
+## Installation
+
+```sh
+npm install @remix-run/session-middleware
+```
+
+## Usage
+
+```ts
+import { createRouter } from '@remix-run/fetch-router'
+import { createCookie } from '@remix-run/cookie'
+import { createCookieStorage } from '@remix-run/session/cookie-storage'
+import { session } from '@remix-run/session-middleware'
+
+let sessionCookie = createCookie('__session', {
+  secrets: ['s3cr3t'], // session cookies must be signed!
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+})
+
+let sessionStorage = createCookieStorage()
+
+let router = createRouter({
+  middleware: [session(sessionCookie, sessionStorage)],
+})
+
+router.get('/', (context) => {
+  context.session.set('count', Number(context.session.get('count') ?? 0) + 1)
+  return new Response(`Count: ${context.session.get('count')}`)
+})
+```
+
+The middleware:
+
+- Reads the session from the cookie on incoming requests
+- Makes it available as `context.session`
+- Automatically saves session changes and sets the cookie on responses
+
+Note: The session cookie must be signed for security. This prevents tampering with the session data on the client.
+
+### Login/Logout Flow
+
+A basic login/logout flow could look like this:
+
+```ts
+import * as res from '@remix-run/fetch-router/response-helpers'
+import { html } from '@remix-run/html-template'
+
+router.get('/login', ({ session }) => {
+  let error = session.get('error')
+  return res.html(
+    html` <div>
+      <h1>Login</h1>
+      ${typeof error === 'string' ? <div class="error">${error}</div> : null}
+      <form method="POST" action="/login">
+        <input type="text" name="username" placeholder="Username" />
+        <input type="password" name="password" placeholder="Password" />
+        <button type="submit">Login</button>
+      </form>
+    </div>`,
+  )
+})
+
+router.post('/login', ({ session, formData }) => {
+  let username = formData.get('username')
+  let password = formData.get('password')
+
+  let user = authenticateUser(username, password)
+  if (!user) {
+    session.flash('error', 'Invalid username or password')
+    return res.redirect('/login')
+  }
+
+  session.set('userId', user.id)
+  session.regenerateId()
+
+  return res.redirect('/dashboard')
+})
+
+router.post('/logout', ({ session }) => {
+  session.destroy()
+  return res.redirect('/')
+})
+```
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`session`](https://github.com/remix-run/remix/tree/main/packages/session) - Session management and storage
+- [`cookie`](https://github.com/remix-run/remix/tree/main/packages/cookie) - Cookie parsing and serialization
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { session } from './lib/session.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { session } from "./lib/session.js";

package/dist/lib/session.d.ts

@@ -0,0 +1,11 @@
+import type { Cookie } from '@remix-run/cookie';
+import type { SessionStorage } from '@remix-run/session';
+import type { Middleware } from '@remix-run/fetch-router';
+/**
+ * Middleware that manages `context.session` based on the session cookie.
+ * @param cookie The session cookie to use
+ * @param storage The storage backend for session data
+ * @returns The session middleware
+ */
+export declare function session(cookie: Cookie, storage: SessionStorage): Middleware;
+//# sourceMappingURL=session.d.ts.map

package/dist/lib/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/lib/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,CA4B3E"}

package/dist/lib/session.js

@@ -0,0 +1,28 @@
+/**
+ * Middleware that manages `context.session` based on the session cookie.
+ * @param cookie The session cookie to use
+ * @param storage The storage backend for session data
+ * @returns The session middleware
+ */
+export function session(cookie, storage) {
+    if (!cookie.signed) {
+        throw new Error('Session cookie must be signed');
+    }
+    return async (context, next) => {
+        if (context.sessionStarted) {
+            throw new Error('Existing session found, refusing to overwrite');
+        }
+        let cookieValue = await cookie.parse(context.headers.get('Cookie'));
+        let session = await storage.read(cookieValue);
+        context.session = session;
+        let response = await next();
+        if (session !== context.session) {
+            throw new Error('Cannot save session that was initialized by another middleware/handler');
+        }
+        let setCookieValue = await storage.save(session);
+        if (setCookieValue != null) {
+            response.headers.set('Set-Cookie', await cookie.serialize(setCookieValue));
+        }
+        return response;
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@remix-run/session-middleware",
+  "version": "0.0.0",
+  "description": "Middleware for managing sessions with cookie-based storage",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remix-run/remix.git",
+    "directory": "packages/session-middleware"
+  },
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/session-middleware#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3",
+    "@remix-run/fetch-router": "0.9.0",
+    "@remix-run/headers": "0.17.0",
+    "@remix-run/cookie": "0.4.1",
+    "@remix-run/session": "0.2.1"
+  },
+  "peerDependencies": {
+    "@remix-run/cookie": "^0.4.1",
+    "@remix-run/fetch-router": "^0.9.0",
+    "@remix-run/session": "^0.2.1"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "session",
+    "cookie",
+    "session-management"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { session } from './lib/session.ts'
+

package/src/lib/session.ts

@@ -0,0 +1,41 @@
+import type { Cookie } from '@remix-run/cookie'
+import type { SessionStorage } from '@remix-run/session'
+
+import type { Middleware } from '@remix-run/fetch-router'
+
+/**
+ * Middleware that manages `context.session` based on the session cookie.
+ * @param cookie The session cookie to use
+ * @param storage The storage backend for session data
+ * @returns The session middleware
+ */
+export function session(cookie: Cookie, storage: SessionStorage): Middleware {
+  if (!cookie.signed) {
+    throw new Error('Session cookie must be signed')
+  }
+
+  return async (context, next) => {
+    if (context.sessionStarted) {
+      throw new Error('Existing session found, refusing to overwrite')
+    }
+
+    let cookieValue = await cookie.parse(context.headers.get('Cookie'))
+    let session = await storage.read(cookieValue)
+
+    context.session = session
+
+    let response = await next()
+
+    if (session !== context.session) {
+      throw new Error('Cannot save session that was initialized by another middleware/handler')
+    }
+
+    let setCookieValue = await storage.save(session)
+    if (setCookieValue != null) {
+      response.headers.set('Set-Cookie', await cookie.serialize(setCookieValue))
+    }
+
+    return response
+  }
+}
+