{"id":27979277,"url":"https://github.com/apeleghq/ts-safeid","last_synced_at":"2025-09-11T09:33:41.827Z","repository":{"id":148504954,"uuid":"620394328","full_name":"ApelegHQ/ts-safeid","owner":"ApelegHQ","description":"Enumeration-resistant stable IDs","archived":false,"fork":false,"pushed_at":"2024-09-11T17:10:55.000Z","size":210,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-06T01:36:32.068Z","etag":null,"topics":["encryption-decryption","middleware","mitigation","timing-attacks","uuid"],"latest_commit_sha":null,"homepage":"https://apeleg.com/blog/posts/2023/03/30/enumeration-timing-uuids/","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/ApelegHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["Exact-Realty"]}},"created_at":"2023-03-28T15:39:51.000Z","updated_at":"2024-09-11T17:11:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"9d4de21c-8095-46b6-822b-a31ef0bf3fea","html_url":"https://github.com/ApelegHQ/ts-safeid","commit_stats":null,"previous_names":["apeleghq/ts-safeid"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ApelegHQ/ts-safeid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApelegHQ%2Fts-safeid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApelegHQ%2Fts-safeid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApelegHQ%2Fts-safeid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApelegHQ%2Fts-safeid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ApelegHQ","download_url":"https://codeload.github.com/ApelegHQ/ts-safeid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApelegHQ%2Fts-safeid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274609465,"owners_count":25316621,"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","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["encryption-decryption","middleware","mitigation","timing-attacks","uuid"],"created_at":"2025-05-08T02:51:44.298Z","updated_at":"2025-09-11T09:33:41.787Z","avatar_url":"https://github.com/ApelegHQ.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Exact-Realty"],"categories":[],"sub_categories":[],"readme":"# TypeScript library for encrypted IDs\r\n\r\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-safeid\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-safeid)\r\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-safeid\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-safeid)\r\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-safeid\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-safeid)\r\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-safeid\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-safeid)\r\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-safeid\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-safeid)\r\n\r\n## Motivation\r\n\r\nApplications often need to present IDs to users or other applications to refer to concrete resources. For example, an API might provide a user a path like `http://api.example/foo/123e4567-e89b-12d3-a456-426655440000` to fetch a resource of type `foo` named `123e4567-e89b-12d3-a456-426655440000`.\r\n\r\nHowever, doing so may open the application up to enumeration and other timing attacks. Mitigating these attacks can be difficult, especially if one has little control over the whole process (e.g., how the backend database looks up IDs).\r\n\r\n## Solution\r\n\r\nThis no-dependency library uses AES-GCM, a symmetric AEAD cypher, to provide stable IDs that are unique to the application generating them and thus cannot be generated or guessed by users. These opaque IDs neutralise enumeration attacks.\r\n\r\nAn ID like `123e4567-e89b-12d3-a456-426655440000` is converted to something like `5DkIrKPTmkFPDs4fyI2VTLH1gBGihiKRx4-THjEIwYDmT-Yz`.\r\n\r\nUsing these IDs incurs in an overhead of about 26.67 bytes for the IV and that authentication tag, plus an overhead of about 33.3% for the binary representation of the ID.\r\n\r\nOnly UUIDs are implemented, although it is possible to use this library for other types of ID. Since UUIDs can be compactly represented in 16 bytes, this means that a 36-byte UUID (text representation) will result in a 48-byte after being run through this library.\r\n\r\n## How to use\r\n\r\n### Overview: before use\r\n\r\nFirst, generate a unique and strong secret key for your application (a 16-byte random string should suffice). This will be used to generate and validate IDs, so it is important that this value remain secret.\r\n\r\nBefore transmitting the internal representation of an ID to a user or another system, call the *encrypt* method. When receiving an ID from a user, call the *decrypt* method to recover the internal representation.\r\n\r\nBelow there are more concrete examples of these steps.\r\n\r\n### Installing\r\n\r\n```sh\r\nnpm i '@apeleghq/safeid'\r\n```\r\n\r\n### Getting started\r\n\r\n#### Importing the module\r\n\r\nIn the file you have your configuration, first import this plugin\r\n\r\n```js\r\nconst { SEncryptId, SDecryptId, UuidSafeId } = require('@apeleghq/safeid');\r\n```\r\n\r\nOr using ES module syntax:\r\n\r\n```js\r\nimport { SEncryptId, SDecryptId, UuidSafeId } from '@apeleghq/safeid';\r\n```\r\n\r\n#### Initialising an instance\r\n\r\nA secret key is required to encrypt and decrypt IDs.\r\n\r\n```js\r\nconst key = Buffer.from('TEST KEY - USE YOUR OWN KEY HERE');\r\n```\r\n\r\nThen, generate a `UuidSafeId` instance\r\n\r\n```js\r\nconst safeUuid = await UuidSafeId(key);\r\n```\r\n\r\nTo encrypt an ID (to provide to an external system):\r\n\r\n```js\r\n// This will be an internal ID to protect\r\nconst id = 'ffffffff-ffff-4fff-afff-ffffffffffff';\r\nconst encrypted = await safeUuid[SEncryptId](id);\r\n// At this point, `encrypted` might contain a string like '0fmlbuVpXDQfKZE16S3paq6ttYp-w7F57v9iq6dRzvLdDeZN'\r\n```\r\n\r\nThen, to recover the internal representation:\r\n\r\n```js\r\n// Note that this promise may reject if the ID doesn't pass validation\r\nconst decrypted = await safeUuid[SDecryptId](encrypted);\r\n// At this point, `decrypted` will contain the internal ID representation, like 'ffffffff-ffff-4fff-afff-ffffffffffff'.\r\n```\r\n\r\n### Advanced usage\r\n\r\nAlthough only UUIDs are supported out of the box, it is possible to define custom ID types. This is done by calling the `setup` method with an object that defines a few helpers for encoding and decoding.\r\n\r\nSee the following example (TypeScript) for a custom ID type that consists of a 6-digit to 8-digit number:\r\n\r\n```ts\r\nimport type { TIdHelper } from '@apeleghq/safeid';\r\nimport {\r\n\tSFromBuffer,\r\n\tsetup,\r\n\tSToBuffer,\r\n\tSValidByteLengthRange,\r\n} from './genericSafeId';\r\n\r\nconst idRegex = /^[0-9]{6,8}$/;\r\n\r\nconst helper: TIdHelper = {\r\n\t// Lower and upper bound for ID length (optional)\r\n\t[SValidByteLengthRange]: [6, 8],\r\n\t// Convert a string to a buffer for encoding (for encryption)\r\n\t[SToBuffer]: (clearId: string) =\u003e {\r\n\t\tif (!idRegex.test(clearId)) {\r\n\t\t\tthrow new Error('Invalid ID format (expected number of 6 to 8 digits)');\r\n\t\t}\r\n\r\n\t\t// ID is stored as an encoded string. Using another representation will be more efficient\r\n\t\tconst binaryId = new TextEncoder().encode(clearId);\r\n \r\n\t\treturn binaryId.buffer;\r\n\t},\r\n\t// Convert a buffer to a string for decoding (for decryption)\r\n\t[SFromBuffer]: (buffer: ArrayBuffer) =\u003e {\r\n\t\t// Sanity check: is the length what we expect?\r\n\t\tif (buffer.byteLength \u003c 6 || buffer.byteLength \u003e 8) {\r\n\t\t\tthrow new Error(\r\n\t\t\t\t'Invalid raw ID after decryption (invalid length)',\r\n\t\t\t);\r\n\t\t}\r\n\r\n\t\t// Decode the byte-encodeed ID to a string\r\n\t\tconst id = new TextDecoder().decode(buffer);\r\n\r\n\t\t// Sanity check: is this a valid ID?\r\n\t\tif (!idRegex.test(id)) {\r\n\t\t\tthrow new Error('Invalid ID after decryption');\r\n\t\t}\r\n\r\n\t\treturn id;\r\n\t},\r\n};\r\n\r\n// Export this module to be used in our application\r\nexport const NumericIdSafeId = setup(helper);\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapeleghq%2Fts-safeid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapeleghq%2Fts-safeid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapeleghq%2Fts-safeid/lists"}