@taifoon/n8n-nodes-typesafe 0.1.0

package/docs/KEY_POLICY.md

@@ -0,0 +1,58 @@
+# Key policy and rotation
+
+**Direct connection (the default): one secret.** Your TypeSafe key lives in n8n's encrypted credential store and is sent as a bearer token to `api.typesafe.ai` over TLS. Nobody else is in the path. Rotate it in TypeSafe's console and paste the new value into the credential; that is the whole procedure. Everything below concerns the OPTIONAL Taifoon gateway connection.
+
+Three secrets exist in the gateway system. This page says where each one lives, who can see it, how it is
+rotated, and what happens when one leaks. The node itself holds none of them outside n8n's
+encrypted credential store.
+
+| Secret | Owner | Lives | Never |
+|---|---|---|---|
+| **Taifoon principal key** (`tfn_live_…`) | you | n8n credential store (encrypted at rest with your instance's `N8N_ENCRYPTION_KEY`) | in a workflow JSON, an expression, a log, or git |
+| **Your TypeSafe key** | you | n8n credential store; sent per request over TLS in `x-typesafe-key` | stored, logged or echoed by Taifoon. It exists on the deck for the duration of one call |
+| **The house TypeSafe key** | Taifoon | the deck's 0600 env file on the production host | sent to any browser, node or client. It funds each principal's three trial calls and nothing else |
+
+## What crosses the wire
+
+`POST /api/login {key}` exchanges the principal key for an httpOnly, Secure, SameSite=Lax session
+cookie valid for 12 hours. n8n caches that session as an expirable token and logs in again when it is
+refused. Every later request carries the cookie and, only for `model: "jev"` after the trial, your
+TypeSafe key in one header. Responses never contain a key; the deck's log lines (call and billing)
+carry latency, tokens, USD and outcome, and never a key or your state.
+
+## Rotation
+
+**Your TypeSafe key.** Rotate it in TypeSafe's console, paste the new value into the n8n credential,
+save. Nothing on Taifoon's side needs updating, because Taifoon never stored the old one. Rotate on a
+schedule you would use for any vendor key (90 days is a reasonable default) and immediately on any of:
+a teammate leaving, a workflow export shared outside your team, a credential test run on a machine
+you do not control.
+
+**Your Taifoon principal key.** Ask the operator to rotate it (`POST /agents/<id>/rotate-key` at the
+identity door). The old key stops working at once; existing 12-hour sessions made with it expire on
+their own and can be cut short by the operator. Update the n8n credential. Your licence, trial count
+and spend ledger are attached to your principal, not to the key string, so they survive rotation.
+
+**The house key.** Taifoon's to rotate: replace it in the deck's env file and restart the deck. Trial
+calls pause for the length of the restart. No user action is needed.
+
+## If a key leaks
+
+| Leaked | Blast radius | Do this |
+|---|---|---|
+| your TypeSafe key | spend on YOUR TypeSafe quota, by anyone, until rotated | rotate in TypeSafe's console now; review their usage page |
+| your Taifoon key | calls billed to your Taifoon key up to its DAILY token ceiling; your three trial calls; read access to the deck as you | ask the operator to rotate; the ceiling bounds the damage per day |
+| the house key | Taifoon's TypeSafe quota | Taifoon rotates; trial calls resume after |
+
+A Taifoon key cannot be used to read anyone's TypeSafe key: the deck has none to read.
+
+## Policy the deck enforces, so you do not have to trust the node
+
+- The first **three** `jev` calls a principal ever makes are funded by Taifoon. The count is per
+  principal, persisted, and a call that fails upstream is handed back.
+- After that, a `jev` call needs **both** the `jev` licence on your principal's grant and your own
+  TypeSafe key. A missing piece is a `402` that names it. There is no silent fallback to the house key.
+- Every call is metered per key **and** per model, persisted across restarts, against a daily ceiling.
+- Login throttles: ten refused keys in five minutes from one address rests the door for that window.
+- An answer that does not validate is never repaired or defaulted; with **Fail Closed** on (the
+  default) the node stops the item instead of passing a null downstream.

package/docs/SECURE_KEYS.md

@@ -0,0 +1,81 @@
+# Supplying keys securely
+
+Three ways to give this node a TypeSafe key, from simplest to most locked-down. All three keep the
+key encrypted at rest and none of them needs a fork of this package.
+
+## 1 · The credential form (most users)
+
+**Credentials → New → TypeSafe API**, paste the key, save. n8n encrypts every credential at rest with
+your instance's `N8N_ENCRYPTION_KEY`. The key goes from your browser to your n8n over TLS, and from
+your n8n to `api.typesafe.ai` over TLS. Nobody else is in the path, including us.
+
+## 2 · Operator-provisioned, users never see the key (teams)
+
+n8n can pre-fill a credential type for the whole instance from a **secrets file**. Users pick
+"TypeSafe API" and it works; the key is never typed, displayed or exported by them.
+
+`credentials-overwrite.json`, **minified** (n8n requires no spaces or newlines), keyed by the
+credential TYPE name this package registers:
+
+```json
+{"typeSafeApi":{"apiKey":"<your TypeSafe key>","baseUrl":"https://api.typesafe.ai"}}
+```
+
+```yaml
+# docker-compose.yaml
+services:
+  n8n:
+    image: docker.n8n.io/n8nio/n8n:<pin a version>
+    environment:
+      CREDENTIALS_OVERWRITE_DATA_FILE: /run/secrets/n8n_credentials_overwrite
+      N8N_ENCRYPTION_KEY_FILE: /run/secrets/n8n_encryption_key
+    secrets: [n8n_credentials_overwrite, n8n_encryption_key]
+secrets:
+  n8n_credentials_overwrite: { file: ./secrets/credentials-overwrite.json }   # chmod 600, never in git
+  n8n_encryption_key:        { file: ./secrets/encryption_key }               # chmod 600, BACK IT UP off the host
+```
+
+The `_FILE` suffix works on any n8n setting and exists precisely so secrets stay out of environment
+variables, which leak into `docker inspect`, process listings, crash dumps and CI logs. On Kubernetes,
+mount a `Secret` at the same paths.
+
+For the optional Taifoon gateway the type name is `taifoonGatewayApi`
+(`{"taifoonGatewayApi":{"deckUrl":"https://deck.taifoon.dev","principalKey":"…","typesafeKey":"…"}}`).
+
+## 3 · A vault (n8n Enterprise)
+
+n8n's External Secrets feature reads credentials from HashiCorp Vault, AWS, GCP, Azure or Infisical at
+run time. It is an Enterprise feature; if you have it, reference the secret in the credential field
+and this node needs no change.
+
+## Why there is no `.env` support inside the node
+
+A node that reads `process.env` or the file system cannot be verified by n8n, and for good reason: a
+community package would then be able to read every other secret on your instance. Option 2 gives you
+the same operational result (configure once, in a file, outside the UI) through n8n's own mechanism,
+with the published package. If you fork the node to read a `.env`, you lose updates and verification
+and gain nothing.
+
+## Never send us a key
+
+You do not need to give Taifoon a TypeSafe key, ever. On the direct connection we are not in the path.
+On the optional gateway connection your key travels per request over TLS in one header, is used for
+that call, and is never stored, logged or echoed. There is deliberately no form, email address or chat
+where we accept keys. If anyone asks you for one in our name, it is not us.
+
+If two organisations ever must hand a secret to each other, do it with public-key encryption to the
+recipient (for example [age](https://age-encryption.org): `age -r <recipient public key>`), never in
+chat, email, a ticket or a repository, and rotate it afterwards. Prefer not needing to: each side
+holding its own vendor key is the design here.
+
+## Rotation and loss
+
+| Event | Do this |
+|---|---|
+| Routine | Rotate the TypeSafe key in TypeSafe's console every 90 days; update the credential or the secrets file; restart n8n if you use the file. |
+| A workflow export, screenshot or log may have shown it | Rotate now. n8n never exports credential values in workflow JSON, but Code nodes and error messages can. |
+| Someone with instance access leaves | Rotate the key, and consider rotating `N8N_ENCRYPTION_KEY` (re-save credentials after). |
+| `N8N_ENCRYPTION_KEY` is lost | Every stored credential is unreadable. Re-enter them. This is why the key needs an off-host backup. |
+
+This node never writes a key into an execution record: HTTP errors are reduced to a status and the
+service's own message, with key-shaped strings redacted, before n8n stores them.

package/docs/TRANSLATION.md

@@ -0,0 +1,53 @@
+# What the translation layer can and cannot do
+
+**Languages:** English, Spanish, German, French, Portuguese, Italian, Polish, Dutch, Russian, Japanese, Arabic. The tables below show the English words; every language has the equivalent pack in `translate.ts`. European packs match whole words (Unicode-aware, so accents are safe). Japanese and Arabic match anywhere, because Japanese has no spaces between words and Arabic attaches particles; for the same reason a one-letter particle is never used as a marker. A colon, in any language, always starts the option list.
+
+The node sits between a workflow, which speaks JSON items and branches, and a System One model, which
+speaks typed questions and probabilities. It translates in both directions, in plain code.
+
+## Forward: a task becomes typed questions (the Translate operation)
+
+Rules, applied per clause, in this order:
+
+| The clause contains | Becomes | Details |
+|---|---|---|
+| a selection verb: classify, categorise, route, pick, choose, select, label, tag, assign, triage, sort, "which of", "one of", "decide which …" | **choice** | Options are taken from the task itself: after a colon or after *into / as / between / among / one of*, split on commas, slashes, pipes and "or". 2 to 50. |
+| a rating verb: rate, score, rank, grade, "how severe / likely / urgent / relevant …", severity, priority, quality, "on a scale", "out of N" | **score** | A named numeric scale ("from 1 to 5", "out of 10", up to ten levels) becomes that many levels; otherwise a four-level rubric *None / Low / Medium / High* that you should replace. |
+| anything else | **noul** | Rewritten as a question; lead-ins such as "check if" and "determine whether" are removed. Returns the probability the statement is true. |
+
+Compound tasks are split on new lines, list markers at the start of a line, semicolons, and sentence
+boundaries (never inside a decimal). Up to 12 clauses; the default battery is 8.
+
+What it refuses to do, deliberately:
+
+- **It never invents options.** "Classify this ticket" with no categories comes back as a choice
+  marked `needs_input`, and is left out of the runnable battery. `ready` is `false`.
+- **It asks no model.** The same task always compiles to the same battery, it costs nothing, and
+  every question carries `explain`: the rule that produced it.
+- **It does not write your rubric.** A score without a named scale gets a generic one and says so.
+
+## Backward: answers become branches (the Routing map on Ask)
+
+| Question kind | Threshold keys | Outcome |
+|---|---|---|
+| noul | `gte`, `lte` on the probability | pass / fail |
+| choice | `minConfidence`; `in` (accepted options) | below `minConfidence` → **review**; outside `in` → fail |
+| score | `min`, `max` on the level | pass / fail |
+
+`branch` is **review** if any decision is review, **pass** only if every routed question passed,
+otherwise **fail**. An answer that did not validate is always **review**: nothing fails open. The
+node exposes the three as real outputs, so they are wires on the canvas.
+
+Translate returns thresholds only as `suggestedRouting` and leaves `routing` EMPTY: the branch is the AND of every routed question, so auto-filled thresholds made a calm refund ticket "fail" for not being urgent (measured in n8n). Copy in only what you mean to gate on. A score is a zero-based level index.
+
+Suggested thresholds are starting points, not fits. A System One model's probabilities
+are calibrated on its vendor's distribution, not on your items. Measured on our own benchmark, Jev
+matched or beat Claude on every thresholded decision while its raw calibration was worse: **fit each
+threshold on your own labelled items, and leave a question unrouted until you have.**
+
+## State
+
+With `jev`, state is any JSON up to 96,000 characters: `{{ JSON.stringify($json) }}` sends the whole
+incoming item. Compute first, judge second: do arithmetic in a Code node and send the result; ask the
+model for judgment, never for a sum. House models (`algotrada`, `auditor`) need a flat object of
+numbers and short symbols, answer noul and choice only, and return an uncalibrated boolean.

package/docs/WORKFLOWS.md

@@ -0,0 +1,30 @@
+# Workflows
+
+Each pattern below is one Taifoon TypeSafe node plus ordinary n8n nodes. All of them follow the same
+three moves: **compute** the state upstream, **ask** every question that might matter in one call
+(they are answered in parallel and in isolation, so ten cost about what one does), **route** on
+thresholds that live on the canvas.
+
+| Workflow | Trigger → state | Questions | Routing |
+|---|---|---|---|
+| **Support triage** | Helpdesk webhook → the ticket JSON | noul *is a refund requested?* · choice *team: billing, technical, sales, abuse* · score *urgency 1 to 5* | Pass → assign to team queue · Review (low confidence) → human inbox · Fail → auto-reply |
+| **Lead qualification** | CRM new lead → lead + enrichment | score *fit against your ICP rubric* · noul *is the budget stated?* · choice *segment* | score ≥ 3 → sales · else nurture |
+| **Invoice guard** | Inbox attachment → extracted fields + last 5 invoices | noul *duplicate of a previous one?* · noul *amount out of pattern?* | any pass → hold for approval |
+| **Content moderation** | Form submit → text | choice *ok, spam, abusive, off-topic* · score *severity* | confidence < 0.6 → Review, never auto-ban |
+| **LLM guardrail** | Before and after an LLM node → the prompt or the reply | noul *contains personal data?* · noul *instruction injection?* | fail closed: stop the item |
+| **Alert de-noising** | Monitoring webhook → alert + last hour of context | noul *is this a repeat of a known flap?* · score *customer impact* | page only when impact ≥ High |
+| **Strategy gate** (trading) | Schedule → indicators computed in a Code node | one noul per gate of your state machine | every gate must pass; Review → stand down |
+
+The importable example is `examples/typed-gate.workflow.json`.
+
+## Operating notes
+
+- **Latency.** Jev answers a 4 to 8 question battery in 0.3 to 0.8 s. `auditor` takes about a minute.
+  The edge cuts any request at 100 s.
+- **Cost.** About 450 to 550 input tokens per battery, 0.00002 USD on Jev. Output is free.
+- **Retries.** A `503` means the lane is unavailable and nothing was charged; n8n's *Retry On Fail*
+  with backoff is the right response. A `402` is not retryable: it names what is missing.
+- **Observability.** Use **List Lanes** on a schedule to alert on trial exhaustion, spend against the
+  daily ceiling, and lane health. The deck logs every call and every charge on its own side.
+- **Batching.** One item is one request. For many items, keep n8n's batching on and the deck's daily
+  ceiling in mind; TypeSafe allows 1,200 requests a minute.

package/index.js

@@ -0,0 +1 @@
+// n8n loads nodes and credentials from the n8n attribute in package.json

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@taifoon/n8n-nodes-typesafe",
+  "version": "0.1.0",
+  "description": "TypeSafe for n8n: ask Jev (a System One model) yes/no, pick-one and rate-it questions about any workflow item and route on calibrated answers. Works directly with your own TypeSafe key; includes a task-to-questions translator and Pass / Fail / Review outputs.",
+  "keywords": [
+    "n8n-community-node-package",
+    "typesafe",
+    "jev",
+    "system-one",
+    "taifoon",
+    "decision",
+    "classification",
+    "routing",
+    "ai"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/taifoon-io/n8n-nodes-typesafe#readme",
+  "author": {
+    "name": "Taifoon",
+    "url": "https://github.com/taifoon-io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taifoon-io/n8n-nodes-typesafe.git"
+  },
+  "engines": {
+    "node": ">=20.15"
+  },
+  "main": "index.js",
+  "scripts": {
+    "build": "n8n-node build",
+    "dev": "n8n-node dev",
+    "lint": "n8n-node lint",
+    "lint:fix": "n8n-node lint --fix",
+    "release": "n8n-node release",
+    "prepublishOnly": "n8n-node prerelease"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "strict": true,
+    "credentials": [
+      "dist/credentials/TypeSafeApi.credentials.js",
+      "dist/credentials/TaifoonGatewayApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/TaifoonTypeSafe/TaifoonTypeSafe.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@n8n/node-cli": "^0.23.0",
+    "eslint": "^9.39.5",
+    "typescript": "5.9.2"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/taifoon-io/n8n-nodes-typesafe/issues"
+  }
+}