{"id":25168284,"url":"https://github.com/stelescuraul/rls","last_synced_at":"2025-04-09T22:10:48.438Z","repository":{"id":37544268,"uuid":"362833644","full_name":"stelescuraul/rls","owner":"stelescuraul","description":"Row level security (RLS) package for TypeORM and NestJS","archived":false,"fork":false,"pushed_at":"2024-12-31T12:56:31.000Z","size":1350,"stargazers_count":65,"open_issues_count":10,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T22:10:44.389Z","etag":null,"topics":["nestjs","rls","rowlevelsecurity","typeorm","typeorm-rls","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stelescuraul.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2021-04-29T13:50:47.000Z","updated_at":"2025-03-23T21:31:22.000Z","dependencies_parsed_at":"2024-05-13T17:11:03.188Z","dependency_job_id":"291841ad-d379-46c0-8faa-2efcd001bebe","html_url":"https://github.com/stelescuraul/rls","commit_stats":{"total_commits":151,"total_committers":6,"mean_commits":"25.166666666666668","dds":0.2185430463576159,"last_synced_commit":"9a8204a380db52548a02579600c30dfe2ca5ef40"},"previous_names":["avallone-io/rls"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelescuraul%2Frls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelescuraul%2Frls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelescuraul%2Frls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stelescuraul%2Frls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stelescuraul","download_url":"https://codeload.github.com/stelescuraul/rls/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119294,"owners_count":21050755,"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":["nestjs","rls","rowlevelsecurity","typeorm","typeorm-rls","typescript"],"created_at":"2025-02-09T07:16:35.208Z","updated_at":"2025-04-09T22:10:48.419Z","avatar_url":"https://github.com/stelescuraul.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build And Test](https://github.com/Avallone-io/rls/actions/workflows/build-and-test.yml/badge.svg?branch=master)](https://github.com/Avallone-io/rls/actions/workflows/build-and-test.yml)\n[![.github/workflows/release.yml](https://github.com/Avallone-io/rls/actions/workflows/release.yml/badge.svg?branch=master)](https://github.com/Avallone-io/rls/actions/workflows/release.yml)\n\n# Description\n\nRow level security utilitary package to apply to NestJS and TypeORM.\n\nThis solution does not work by having multiple connections to database (eg: one connection / tenant). Instead, this solution works by applying the database policies for RLS as described in [this aws blog post](https://aws.amazon.com/blogs/database/multi-tenant-data-isolation-with-postgresql-row-level-security/) (under the **_Alternative approach_**).\n\n# Install\n\n\u003e $ npm install @avallone-io/rls\n\n# Usage\n\nTo create a RLSConnection instance you'll need the original connection to db. Setup the typeorm config as usual, then wrap its connection into a **RLSConnection** instance, for each request.\n\nThis will run a `set \"rls.tenant_id\"` and `set \"rls.actor_id\"` for each request and will reset them after the query is executed.\n\n---\n\n**RLS Policies**\n\nYour database policies will **have to** make use of `rls.tenant_id` and `rls.actor_id` in order to apply the isolation. Policy example:\n\n```sql\nCREATE POLICY tenant_isolation ON public.\"category\" for ALL\nUSING (\"tenant_id\" = current_setting('rls.tenant_id'))\nwith check (\"tenant_id\" = current_setting('rls.tenant_id'));\n```\n\n---\n\n## Express/KOA\n\nFor example, assuming an express application:\n\n```typescript\napp.use((req, res, next) =\u003e {\n  const dataSource = await new DataSource({...}).initialize(); // create a datasource and initialize it\n\n  // get tenantId and actorId from somewhere (headers/token etc)\n  const rlsConnection = new RLSConnection(dataSource, {\n    actorId,\n    tenantId,\n  });\n\n  res.locals.connection = rlsConnection;\n  next();\n});\n\n// your handlers\nconst userRepo = res.locals.connection.getRepository(User);\nawait userRepo.find(); // will return only the results where the db rls policy applies\n```\n\nIn the above example, you'll have to work with the supplied connection. Calling TypeORM function directly will work with the original DataSource object which is not RLS aware.\n\n## NestJS integration\n\nIf you are using NestJS, this library provides helpers for making your connections and queries tenant aware.\n\nCreate your TypeORM config and load the TypeORM module using `.forRoot`. Then you'll need to load the `RLSModule` with `.forRoot` where you'll define where to take the `tenantId` and `actorId` from. The second part is that you now need to replace the `TypeOrmModule.forFeature` with `RLSModule.forFeature`. This should be a 1-to-1 replacement.\nYou can inject non-entity dependent Modules and Providers. First array imports modules, second array injects providers.\n\nWhen using `RLSModule.forRoot` it will set your `scope` to `REQUEST`! Be sure you understand the implications of this and especially read about the request-scoped authentication strategy on [Nestjs docs](https://docs.nestjs.com/security/authentication#request-scoped-strategies).\n\nThe `RLSModule.forRoot` accepts the factory funtion as async or non-async function.\n\n```typescript\napp.controller.ts\n\n@Module({\n  imports: [\n    TypeOrmModule.forRoot(...),\n    RLSModule.forRoot([/*Module*/], [/*Service*/], async (req: Request, /*serviceInstance*/) =\u003e {\n      // You can take the tenantId and actorId from headers/tokens etc\n      const tenantId = req.headers['tenant_id'];\n      const actorId = req.headers['actor_id'];\n\n      return {\n        actorId,\n        tenantId,\n      };\n    }),\n    RLSModule.forFeature([Post, Category]) // \u003c- this\n  ],\n  controllers: [AppController],\n  providers: [AppService],\n})\nexport class AppModule {}\n```\n\nNow you can use the normal module injection for repositories, services etc.\n\nTo inject the RLS connection within a service, you can do by using `@Inject(TENANT_CONNECTION)` where `TENANT_CONNECTION` is imported from `@avallone-io/rls`.\n\n```typescript\nexport class AppService {\n  constructor(\n    @InjectRepository(Category)\n    private categoryRepo: Repository\u003cCategory\u003e,\n    @Inject(TENANT_CONNECTION)\n    private connection: RLSConnection,\n  ) {}\n\n  // you can now use categoryRepo as normal but it will\n  // be scoped for RLS. Same with the connection.\n}\n```\n\nSame as before, do not use the TypeORM functions directly from the `dataSource` as that will give you the default connection to the database, not the wrapped instance.\n\nFor more specific examples, check the `test/nestjs/src`.\n\n# Typeorm \u003ev0.3.0\nSince typeorm v0.3.0, the Connection class has been replaced by DataSource. This module still uses Connection as its language which is also helpful now to differenciate between the actual database connection (typeorm DataSource) and RLS wrapper (RLSConnection). However, if you want to be on par with typeorm terminalogy, there is an alias for `RLSConnection` called `RLSDataSource`. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstelescuraul%2Frls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstelescuraul%2Frls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstelescuraul%2Frls/lists"}