{"id":23421143,"url":"https://github.com/nhsdigital/pseudonymisation_service","last_synced_at":"2025-04-12T14:04:11.795Z","repository":{"id":39635522,"uuid":"269590084","full_name":"NHSDigital/pseudonymisation_service","owner":"NHSDigital","description":"A Rails API service providing data pseudonymisation","archived":false,"fork":false,"pushed_at":"2024-12-13T09:57:49.000Z","size":330724,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-26T08:37:29.656Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/NHSDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"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,"zenodo":null}},"created_at":"2020-06-05T09:43:13.000Z","updated_at":"2024-12-13T09:57:49.000Z","dependencies_parsed_at":"2024-12-05T13:40:54.266Z","dependency_job_id":"f063d376-ddb0-41bb-8727-4fb8d1fb327b","html_url":"https://github.com/NHSDigital/pseudonymisation_service","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpseudonymisation_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpseudonymisation_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpseudonymisation_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpseudonymisation_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/pseudonymisation_service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248578857,"owners_count":21127713,"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":[],"created_at":"2024-12-23T02:14:09.088Z","updated_at":"2025-04-12T14:04:11.757Z","avatar_url":"https://github.com/NHSDigital.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NDR Pseudonymisation Service [![Build Status](https://github.com/publichealthengland/pseudonymisation_service/workflows/Test/badge.svg)](https://github.com/publichealthengland/pseudonymisation_service/actions?query=workflow%3Atest)\n\nThe `pseudonymisation_service` project is a Rails API-only application from PHE's National Disease Registration team that allows identifiers to be submitted, and pseudonymised versions to be returned.\n\n## Usage\n\nThe easiest way to use the pseudonymisation service is through a `NdrPseudonymise::Client` object,\nprovided by the `ndr_pseudonymise` gem. This provides Ruby access to the three endpoints (described below, in \"Endpoints\").\n\n## Basic Table Structure\n\nUsers can use pseudonymisation keys when a key grant has been given,\nand any usage is then logged.\n\n```\n+------+      +----------+      +---------------------+\n| User | ---\u003e | KeyGrant | \u003c--- | PseudonymisationKey |\n+------+      +----------+      +---------------------+\n     |                            |\n     |        +----------+        |\n     +------\u003e | UsageLog | \u003c------+\n              +----------+\n```\n\n## Secrets Management\n\nThis project uses Rails' per-environment credentials API. Stored using are:\n* pseudonymisation key secret salts\n* per-environment identifier-logging encryption keys\n* database credentials\n\nFor testing, the test environment credentials file and key file have been committed,\nand can be viewed/updated using:\n\n```\n$ rails credentials:edit --environment test\n```\n\nTo edit the credentials on the server (where the application user has read-only acces),\nyou need to do the following (as a `deployer`, who can write to the filesystem):\n\n```\n$ export PATH=\"~pseudo_live/.rbenv/bin:~pseudo_live/.rbenv/shims:${PATH}\"\n$ read -rsp '\u003e ' RAILS_MASTER_KEY\n$ export RAILS_MASTER_KEY\n$ cd ~pseudo_live/pseudonymisation_service/current\n$ RAILS_ENV=production bundle exec rails credentials:edit\n```\n\nTo supply the unlock key to an ad-hoc production rake task, you can use the following:\n\n```\n$ RAILS_ENV=production rails credentials:unlock do:some:admin:task\n```\n\n## Authentication\n\nUsers are authenticated with tokens supplied in the request headers.\nTo set up a user, run:\n\n```\n$ rails users:create\n```\n\nA token can be (re)generated for a user using:\n\n```\n$ rails users:generate_token[the_username]\n```\n\nUsers' key grants can be managed using the following tasks:\n\n```\n$ rails users:grants:list[the_username]\n$ rails users:grants:add[the_username]\n$ rails users:grants:revoke[the_username]\n```\n\n## Key Generation\n\nTo add new keys, first put salts into the `credentials.yml.enc`.\nNote that the application must be restarted to reload the encrypted credentials.\n\nThen, create `PseudonymistionKey` records from a Rails console:\n\n```ruby\nprimary_key   = PseudonymisationKey.create!(name: 'primary_test_key')\nsecondary_key = PseudonymisationKey.create!(name: 'repseudo_test_key', parent_key: primary_key)\n\ncompound_key = PseudonymisationKey.create!(\n  key_type: 'compound',\n  name: 'compound_test_key',\n  start_key: primary_key,\n  end_key: secondary_key\n)\n```\n\nGrants can then be done using the `users:grants:add` task.\n\n## Endpoints\n\nThe service currently offers three endpoints, listed below.\n\n### GET /keys\n\n`GET` requests to `/keys` will return a JSON-encoded list of pseudonymisation keys availble to the current user.\n\n```\ncurl -sH 'Authorization: Bearer user:token' site.dev/api/v1/keys\n```\n```json\n[\n  {\n    \"name\": \"test key1\",\n    \"supported_variants\": [\n      1,\n      2\n    ]\n  },\n  {\n    \"name\": \"test key3\",\n    \"supported_variants\": [\n      1,\n      2\n    ]\n  }\n]\n```\n\n### GET /variants\n\n`GET` requests to `/variants` will return a JSON-encoded list of variants available to the current user, along with required identifier fields.\n\n```\ncurl -sH 'Authorization: Bearer user:token' site.dev/api/v1/variants\n```\n```json\n[\n  {\n    \"variant\": 1,\n    \"required_identifiers\": [\n      \"nhs_number\"\n    ]\n  },\n  {\n    \"variant\": 2,\n    \"required_identifiers\": [\n      \"birth_date\",\n      \"postcode\"\n    ]\n  }\n]\n```\n\n### POST /pseudonymise\n\n`POST` requests to `/pseudonymise` will return JSON-encoded pseudonymised identifiers for supplied `\"identifiers\"`.\nIn addition, `\"variants\"` and `\"key_names\"` can be supplied, but if they are omitted sensible default choices are made.\n\n```\ncurl -sH 'Authorization: Bearer user:token' \\\n     --header \"Content-Type:application/json\" \\\n     --data '{\"identifiers\":{\"nhs_number\":\"1234567890\"},\"context\":\"README demo\"}' \\\n     site.dev/api/v1/pseudonymise\n```\n```json\n[\n  {\n    \"key_name\": \"test key1\",\n    \"variant\": 1,\n    \"identifiers\": {\n      \"nhs_number\": \"1234567890\"\n    },\n    \"context\": \"README demo\",\n    \"pseudoid\": \"1e03fdf3...\"\n  },\n  {\n    \"key_name\": \"test key3\",\n    \"variant\": 1,\n    \"identifiers\": {\n      \"nhs_number\": \"1234567890\"\n    },\n    \"context\": \"README demo\",\n    \"pseudoid\": \"8cc142ecb...\"\n  }\n]\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies, set up a database, and start a web server. You'll need to have PostgreSQL installed already.\n\nTests can be run with `bin/rake`.\n\n## Contributing\n\n1. Fork it ( https://github.com/publichealthengland/pseudonymisation_service/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\nPlease note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fpseudonymisation_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fpseudonymisation_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fpseudonymisation_service/lists"}