{"id":28711728,"url":"https://github.com/curveball/session","last_synced_at":"2025-06-14T22:10:26.608Z","repository":{"id":37587723,"uuid":"147651866","full_name":"curveball/session","owner":"curveball","description":"Cookie-based sessions for Curveball","archived":false,"fork":false,"pushed_at":"2024-11-06T21:19:49.000Z","size":572,"stargazers_count":3,"open_issues_count":3,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-06-09T13:56:53.358Z","etag":null,"topics":["cookie","curveball","hacktoberfest","http","session"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curveball.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-06T09:40:51.000Z","updated_at":"2024-11-06T21:19:15.000Z","dependencies_parsed_at":"2024-01-17T23:57:06.929Z","dependency_job_id":"c27de05b-435f-48f8-9d01-adae5749d5c3","html_url":"https://github.com/curveball/session","commit_stats":{"total_commits":112,"total_committers":6,"mean_commits":"18.666666666666668","dds":0.2142857142857143,"last_synced_commit":"effcd25afbc76734e4caa77a56b4ce063358a638"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/curveball/session","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fsession","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fsession/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fsession/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fsession/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curveball","download_url":"https://codeload.github.com/curveball/session/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fsession/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259890461,"owners_count":22927374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookie","curveball","hacktoberfest","http","session"],"created_at":"2025-06-14T22:10:24.686Z","updated_at":"2025-06-14T22:10:26.594Z","avatar_url":"https://github.com/curveball.png","language":"TypeScript","readme":"Curveball Session Middleware\n============================\n\nThis package adds support for sessions to the [Curveball][1] framework.\n\nFeatures:\n\n* It's lazy. It will only start a session if there is something in the store.\n* It will also automatically wipe the session data if session data was emptied.\n* It provides features for generating and validating CSRF tokens.\n\nInstallation\n------------\n\n    npm install @curveball/session\n\nUpgrading from versions 0.5 and below\n-------------------------------------\n\nIf you are upgrading from a 0.5.x release or earlier, this package introduces\na BC break since 0.6.\n\nIn 0.5 session data was available in `ctx.state.session` and\n`ctx.state.sessionId`, but this has been moved to `ctx.session` and\n`ctx.sessionId`.\n\n\nGetting started\n---------------\n\n### Adding the middleware\n\n```typescript\nimport session from '@curveball/session';\n\napp.use(session({\n  store: 'memory',\n});\n```\n\nThis will add the in-memory session store to curveball. This store is mostly\nmeant for testing.\n\nHere is another example with more options:\n\n```typescript\nimport session from '@curveball/session';\n\napp.use(session({\n  store: 'memory',\n  cookieName: 'MY_SESSION',\n  expiry: 7200,\n  cookieOptions: {\n    secure: true,\n    path: '/',\n    sameSite: true,\n  },\n});\n```\n\n* `cookieName` - Updates the name of the HTTP Cookie. It's `CB` by default.\n* `expiry` - The number of seconds of inactivity before the session disappears.\n  this is 3600 seconds by default. It only pertains to the longevity of the\n  session in the store, it doesn't influence cookie parameters.\n* `cookieOptions` - If set, override cookie options from the default. The list\n  of supported options can be found in the documentation of the [cookie\n  package][3].\n\n### Using the session store\n\nIn your own controllers and middlewares, you can set and update session data\nvia the `ctx.session` property.\n\n```typescript\napp.use( ctx =\u003e {\n\n  // Running this will create the session\n  ctx.session = { userId: 5 };\n  ctx.response.body = 'Hello world';\n\n});\n```\n\n### Deleting a session\n\nTo delete an open session, just clear the session data:\n\n```typescript\napp.use( ctx =\u003e {\n\n  // Running this will create the session\n  ctx.session = null;\n\n});\n```\n\n### Re-generate a session id.\n\nIf you clear the session id, but there is still data, the middleware will\nremove the old session and automatically create a new session id:\n\n```typescript\napp.use( ctx =\u003e {\n\n  // This will kill the old session and start a new one with the same data.\n  ctx.sessionId = null;\n\n});\n```\n\n### CSRF token support\n\nTo obtain a CSRF token for forms, the middleware provides a `getCsrf()` function:\n\n```typescript\napp.use( async ctx =\u003e {\n\n  // Obtain a CSRF token for HTML forms:\n  const csrfToken = await ctx.getCsrf();\n\n});\n```\n\nIt's recommended to embed this token in HTML forms as such:\n\n```html\n\u003cinput type=\"hidden\" name=\"csrf-token\" value=\"....token goes here\" /\u003e\n```\n\nThen on `POST` requests, you can easily validate the token with the `validateCsrf`\nfunction. If the token was incorrect, this will automatically result in a 403\nerror:\n\n```typescript\napp.use(route.post('/form-submit', ctx =\u003e {\n\n  // Throws error if csrf-token was not supplied or incorrect\n  ctx.validateCsrf();\n\n}));\n```\n\n\nAPI\n---\n\nIt's desirable to create your own stores for product usage. Eventually this\nproject will probably add a few more default stores.\n\nUntil then, you must implement the following interface:\n\n```typescript\ninterface SessionStore {\n\n  set(id: string, values: SessionValues, expire: number): Promise\u003cvoid\u003e;\n  get(id: string): Promise\u003cSessionValues\u003e,\n  delete(id: string): Promise\u003cvoid\u003e,\n  newSessionId(): Promise\u003cstring\u003e,\n\n}\n```\n\n`SessionValues` is simply a key-\u003evalue object. `expire` is expressed as a unix\ntimestamp.\n\n[1]: https://github.com/curveball/\n[2]: https://www.npmjs.com/package/cookie\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurveball%2Fsession","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurveball%2Fsession","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurveball%2Fsession/lists"}