{"id":22221984,"url":"https://github.com/fabiospampinato/safex","last_synced_at":"2025-11-10T09:02:08.992Z","repository":{"id":183819869,"uuid":"669804944","full_name":"fabiospampinato/safex","owner":"fabiospampinato","description":"A language for writing safe expressions, in a tiny subset of JavaScript.","archived":false,"fork":false,"pushed_at":"2024-04-05T00:09:45.000Z","size":42,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-14T18:25:37.185Z","etag":null,"topics":["expression","filter","get","javascript","language","read","safe"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/fabiospampinato.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":null,"support":null,"governance":null}},"created_at":"2023-07-23T13:39:50.000Z","updated_at":"2024-07-31T21:37:11.000Z","dependencies_parsed_at":"2023-07-25T23:41:36.919Z","dependency_job_id":null,"html_url":"https://github.com/fabiospampinato/safex","commit_stats":null,"previous_names":["fabiospampinato/safex"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fsafex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fsafex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fsafex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fsafex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiospampinato","download_url":"https://codeload.github.com/fabiospampinato/safex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817017,"owners_count":17824200,"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":["expression","filter","get","javascript","language","read","safe"],"created_at":"2024-12-02T23:16:26.270Z","updated_at":"2025-11-10T09:02:08.932Z","avatar_url":"https://github.com/fabiospampinato.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Safex\n\nA language for writing safe expressions, in a tiny subset of JavaScript.\n\n## Goals\n\nThis library follows these design goals:\n\n- Only a tiny subset of JavaScript is implemented, a subset that can be executed safely.\n- Every feature that is implemented works exactly like it would in JavaScript.\n- The library itself is implemented defensively, if there are bugs in it almost certainly they won't enable arbitrary code execution.\n\n## Language\n\nThe following features of JavaScript are supported:\n\n- **Read-only variables**: you can provide arbitrary read-only variables to your expressions.\n- **Restricted function calls**: you can provide arbitrary functions that your expressions are allowed to call.\n- **Property accesses**: `a.b.c`, `a[b][c]`.\n- **Primitive values**: `true`, `false`, `null`, `undefined`, `bigint`, `number`, `string`.\n- **Comparison operators**: `==`, `!=`, `===`, `!==`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=`.\n- **Arithmetic operators**: `+`, `-`, `*`, `/`, `%`, `**`.\n- **Bitwise operators**: `\u0026`, `|`, `^`, `~`, `\u003c\u003c`, `\u003e\u003e`, `\u003e\u003e\u003e`.\n- **Logical operators**: `!`, `\u0026\u0026`, `||`, `??`.\n- **Group operator**: `(...)`.\n\nThe following features of JavaScript are instead _not_ supported:\n\n- **Assignments**: no assignment operators are supported, your variables can't be mutated.\n- **Increment/decrement**: no postfix/prefix increment/decrement operators are supported either.\n- **`new` operator**: `new` can be used to execute unintentionally-exposed functions, so it's not supported.\n- **New variables**: safe expressions can't declare new variables.\n- **Arbitrary function calls**: no arbitrary function calls can be performed, only functions you explicitly list can be called.\n- **Loops**: not even loops can be created.\n\n## Security\n\nWhile the language by itself is safe to execute, it's important to note that in order for it to be useful it supports giving expressions explicit access to a set of variables you control. And in order to be an actual subset of JavaScript it must indirectly support some very dynamic parts of the language, like getters and `Proxy` instances.\n\nIf you want to make this library useless you can give your expressions access to a variable like this:\n\n```js\nconst footgun = new Proxy ( {}, {\n  get ( target, key ) {\n    eval ( key );\n  }\n});\n```\n\nWhich the no longer safe expressions could then use like this to execute arbitrary code:\n\n```ts\nfootgun['alert(1)']\n```\n\nAdditionally function calls to explicitly-provided functions are allowed, so providing this context object to your expressions is unsafe:\n\n```js\n{ eval }\n```\n\nNote how a function must be explicitly listed to be callable by the expression:\n\n```js\n// This will throw, \"min\" was not explicitly provided\nsafex.exec ( 'Math.min ( 1, 2 )', { Math } );\n// This is allowed,\"min\" was explicitly provided\nsafex.exec ( 'min ( 1, 2 )', { min: Math.min } );\n```\n\nBasically executing a function in general is unsafe, and there are a lot of ways to execute a function in JavaScript, even with the allowed language being this restrictive, for example:\n\n- Coercing objects or functions to primitives could call `Symbol.toPrimitive`, `toString` and `valueOf` on them.\n- Accessing a property could cause a function call if that property is actually a getter.\n- Accessing a property could cause a function call if the property is being accessed on a `Proxy` object.\n\nUnless you do weird stuff expressions executed via this library will be safe, but it's important to understand that you can shoot yourself in the foot by providing usafe variables to your expressions.\n\n## Install\n\n```sh\nnpm install --save safex\n```\n\n## Usage\n\n```ts\nimport safex from 'safex';\n\n// Execute an expression without pre-compiling it, which is slower if you need to execute it multiple times\n\nsafex.exec ( '128 / 2' ); // =\u003e 64\nsafex.exec ( 'activeView === \"search\"', { activeView: 'search' } ); // =\u003e true\nsafex.exec ( 'isFoo \u0026\u0026 ( isBar || baz \u003c 3 )', { isFoo: true, isBar: false, baz: 123 } ); // =\u003e false\n\n// Compile an expression, parsing it once, which is faster if you need to execute it multiple times with different variables\n\nconst expression = safex.compile ( 'isFoo || isBar' );\n\nexpression ({ isFoo: 1, isBar: 2 }); // =\u003e 1\nexpression ({ isFoo: 0, isBar: 2 }); // =\u003e 2\n\n// Validate that an expression is actually valid syntactically\n\nsafex.validate ( '( -1 ) ** 2' ); // =\u003e true\nsafex.validate ( '-1 ** 2' ); // =\u003e false\nsafex.validate ( 'eval ( \"alert(1)\" )' ); // =\u003e false\n\n// Low-level function that parse an expression into an AST\n\nconst ast = safex.parse ( '1 + 2' ) // =\u003e { type: 'root', children: [{ type: 'addition', children: [{ type: 'number', value: 1 }, { type: 'number', value: 2 }] }] }\n```\n\n## License\n\nMIT © Fabio Spampinato\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fsafex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiospampinato%2Fsafex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fsafex/lists"}