{"id":26817671,"url":"https://github.com/arvid-berndtsson/typesecure","last_synced_at":"2026-02-19T15:03:23.409Z","repository":{"id":283900274,"uuid":"953235315","full_name":"arvid-berndtsson/typesecure","owner":"arvid-berndtsson","description":"A focused TypeScript cryptography package that provides secure encryption and hashing utilities with strong typing and runtime validation using Zod.","archived":false,"fork":false,"pushed_at":"2026-02-15T22:41:41.000Z","size":278,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T05:41:31.674Z","etag":null,"topics":["cryptography","cybersecurity","encryption","hashing","password","security","typesafe","typescript","zod"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/typesecure","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/arvid-berndtsson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-22T21:56:47.000Z","updated_at":"2026-02-15T22:41:02.000Z","dependencies_parsed_at":"2026-02-16T00:03:11.855Z","dependency_job_id":null,"html_url":"https://github.com/arvid-berndtsson/typesecure","commit_stats":null,"previous_names":["arvid-berndtsson/typesecure"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/arvid-berndtsson/typesecure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvid-berndtsson%2Ftypesecure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvid-berndtsson%2Ftypesecure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvid-berndtsson%2Ftypesecure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvid-berndtsson%2Ftypesecure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arvid-berndtsson","download_url":"https://codeload.github.com/arvid-berndtsson/typesecure/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvid-berndtsson%2Ftypesecure/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29506317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cryptography","cybersecurity","encryption","hashing","password","security","typesafe","typescript","zod"],"created_at":"2025-03-30T04:17:12.666Z","updated_at":"2026-02-19T15:03:23.401Z","avatar_url":"https://github.com/arvid-berndtsson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# typesecure\n\n`typesecure` is a **classification-first security core** for TypeScript projects.\n\nInstead of starting with crypto primitives, it starts with what actually causes most security incidents in web apps: **data leaving the boundary it should never cross** (logs, analytics, error trackers, headers, client bundles, etc).\n\nYou “type” your data as `public | pii | secret | token | credential`, and `typesecure` helps you **enforce** safe handling using TypeScript + runtime checks.\n\n## Features\n\n- **Classification types**: `PublicString`, `PIIString`, `SecretString`, `TokenString`, `CredentialString`.\n- **Runtime validation**: Zod-backed constructors (`secretText()`, `piiText()`, ...).\n- **Redaction**: `redact()` and `safeJsonStringify()` prevent secret/PII leakage.\n- **Policy enforcement**: `defaultPolicy()`, `assertAllowed()`, `audit()` help block unsafe crossings.\n\n## Good for / Use when\n\n- **You need to stop leaks early**: preventing secrets/PII from ending up in logs, analytics, error trackers, or client bundles.\n- **You want safe defaults**: making insecure behavior harder than secure behavior.\n- **You want guardrails at the boundary**: before logging, emitting telemetry, making network calls, or writing to storage.\n\n## Not a fit / Don’t use when\n\n- **You need a full security platform** (hosted policy registry, enterprise controls). `typesecure` is a library.\n- **You need production-grade crypto primitives**. Use well-reviewed, purpose-built libraries and treat crypto carefully.\n- **You only want compile-time types with zero runtime behavior**. `typesecure` deliberately includes runtime checks/redaction.\n\n## Installation\n\nRequires Node.js `\u003e=18.18.0`.\n\n```bash\n# Using npm\nnpm install typesecure\n\n# Using yarn\nyarn add typesecure\n\n# Using pnpm\npnpm add typesecure\n```\n\n## Usage\n\n### Classification-first data handling\n\n```typescript\nimport {\n  piiText,\n  secretText,\n  token,\n  publicText,\n  redact,\n  safeJsonStringify,\n  defaultPolicy,\n  assertAllowed,\n  policyLog,\n} from \"typesecure\";\n\nconst userEmail = piiText(\"user@example.com\");\nconst sessionToken = token(\"abc.def.ghi\");\nconst dbPassword = secretText(process.env.DB_PASSWORD ?? \"\");\n\n// Redact before logging / serialization\nconsole.log(redact({ userEmail, sessionToken, dbPassword }));\nconsole.log(\n  safeJsonStringify({ userEmail, sessionToken, dbPassword }, undefined, 2),\n);\n\n// Enforce policy before a boundary crossing\nconst policy = defaultPolicy();\nassertAllowed(policy, \"network\", { sessionToken }); // allowed\n// assertAllowed(policy, 'log', { dbPassword }); // throws\n\n// Safe logging helper with enforcement\npolicyLog(policy, console, \"info\", publicText(\"login_ok\"), { userEmail });\n```\n\n### Express / Next.js examples\n\n```typescript\n// Express middleware example\nimport {\n  safeLoggerAdapter,\n  defaultPolicy,\n  assertAllowed,\n  token,\n} from \"typesecure\";\n\nconst log = safeLoggerAdapter(console);\nconst policy = defaultPolicy();\n\napp.use((req, _res, next) =\u003e {\n  const auth = req.headers.authorization?.replace(/^Bearer\\s+/i, \"\");\n  if (auth) {\n    const t = token(auth);\n    assertAllowed(policy, \"network\", { t });\n    log.info({ route: req.path, auth: t }); // will be redacted\n  }\n  next();\n});\n```\n\n## API Reference\n\n### Classification\n\n- `publicText(value: string): PublicString`\n- `piiText(value: string): PIIString`\n- `secretText(value: string): SecretString`\n- `token(value: string): TokenString`\n- `credential(value: string): CredentialString`\n- `reveal(value): string` (intentionally explicit)\n\n### Redaction\n\n- `redact(value): value` (deep traversal)\n- `redactText(value): string` (mask sensitive fragments in plain text)\n- `detectText(value): StringDetection[]` (return ranges/kinds for audit workflows)\n- `safeJsonStringify(value): string`\n- `safeLoggerAdapter(consoleLike)`\n- Redaction options:\n  - `guessByKey` (default `true`): redact suspicious keys like `password`, `token`, `apiKey`.\n  - `guessByValue` (default `true`): auto-detect and redact sensitive-looking values.\n  - `useDefaultValueDetector` (default `true`): keep built-in rule-based detectors on/off.\n  - `stringDetectors`: add custom detectors (for NER/ML or domain-specific logic).\n  - `minDetectionConfidence` (default `0`): ignore low-confidence custom detections.\n- Value detection masks only the sensitive fragments inside a larger string (instead of replacing the whole text), including:\n  - PII: email, phone, SSN, date of birth (`YYYY-MM-DD`), IPv4 address, payment card numbers (Luhn-validated).\n  - Secrets/tokens: JWTs, private key PEM blocks, GitHub tokens, AWS access keys, Stripe secret keys, OpenAI-style `sk-...` keys, credential pairs (`user:pass`), high-entropy token-like strings.\n\nExample custom detector (NER/ML-style integration):\n\n```typescript\nconst out = redact(\n  { text: \"Customer Jane Doe uses jane@example.com\" },\n  {\n    stringDetectors: [\n      (value) =\u003e {\n        const name = \"Jane Doe\";\n        const idx = value.indexOf(name);\n        return idx \u003e= 0\n          ? [{ start: idx, end: idx + name.length, kind: \"pii\", confidence: 0.92, source: \"ml.ner\" }]\n          : [];\n      },\n    ],\n    minDetectionConfidence: 0.8,\n  },\n);\n```\n\n### Policy\n\n- `defaultPolicy(): Policy`\n- `assertAllowed(policy, action, data): void`\n- `audit(policy, action, data): AuditEvent`\n- `policyLog(policy, logger, level, ...args): void`\n\n## Security Considerations\n\nSecurity is as much about **preventing leaks** as it is about cryptographic correctness. `typesecure` focuses on preventing accidental secret/PII exposure across common boundaries.\n\nIf you need cryptography for production-grade requirements, prefer well-reviewed primitives and consult a security professional. For production applications with high security requirements, consider:\n\n1. Consulting a security professional\n2. Using specialized security libraries\n3. Keeping dependencies updated\n4. Implementing proper key management\n5. Using hardware security modules (HSMs) for key storage when possible\n6. Conducting regular security audits\n7. Following the latest NIST recommendations\n\n## Development\n\nTo contribute to this project:\n\n1. Clone the repository\n2. Install dependencies with `pnpm install`\n3. Run tests with `pnpm test`\n4. Build the package with `pnpm build`\n5. Run Enron dataset integration tests with `pnpm test:data`\n\n### Optional: external dataset setup\n\nFor larger redaction/policy experiments (Enron + Synthea FHIR), fetch datasets locally:\n\n```bash\npnpm data:setup\n```\n\nThis command downloads and extracts to:\n\n- `data/enron-maildir`\n- `data/synthea_sample_data_fhir_latest`\n\nNotes:\n\n- `data/` is gitignored and not published to npm.\n- `pnpm test` excludes dataset suites by default.\n- `pnpm test:data` runs Enron dataset tests with verbose output.\n- `pnpm test:data:synthea` runs Synthea-specific dataset tests.\n- `pnpm test:data:all` runs all dataset suites.\n- You can override source URLs with `ENRON_URL=...` and/or `SYNTHEA_FHIR_URL=...`.\n- You can change destination with `DATA_DIR=/path/to/data`.\n\nDataset sources:\n\n- Enron: [https://www.cs.cmu.edu/~enron/](https://www.cs.cmu.edu/~enron/)\n- Synthea: [https://github.com/synthetichealth/synthea-sample-data/](https://github.com/synthetichealth/synthea-sample-data/)\n\nThis project uses TypeScript for type safety, Jest for testing, and ESLint for code quality.\n\n## Dataset Acknowledgements\n\nWe use these public datasets for redaction and policy testing:\n\n- [CMU Enron Email Dataset](https://www.cs.cmu.edu/~enron/)\n- [Synthea Sample Data](https://github.com/synthetichealth/synthea-sample-data/)\n\nPersonal note: I am especially interested in the historical context around Enron, including how it was able to happen and the improvements in governance and controls that followed.\n\n## License\n\nMIT © [Arvid Berndtsson](https://github.com/arvid-berndtsson)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvid-berndtsson%2Ftypesecure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farvid-berndtsson%2Ftypesecure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvid-berndtsson%2Ftypesecure/lists"}