kryptheon-night 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# Kryptheon Night Shift
+
+Attacks a copy of your database and tells you, in plain English, what got in.
+
+```
+npx kryptheon-night
+```
+
+That is the whole thing. No account, no signup, no config file. It asks you
+for one line from your Supabase dashboard, tells you exactly what it is about
+to do, waits for you to say yes, and then takes two or three minutes.
+
+**It never touches your live app.** It reads the *shape* of your database —
+table names, columns, and the rules about who may see what — rebuilds that
+shape in a temporary space, puts two made-up people in it, and attacks *that*.
+Not one of your rows is read, changed or copied. The temporary space is
+deleted when it finishes, and also if it crashes.
+
+Your connection string stays on your computer. Nothing is uploaded anywhere.
+There is no server on our side to upload it to.
+
+## What you need
+
+One line from Supabase, called the connection string.
+
+**Supabase** — supabase.com/dashboard → your project → the gear icon
+(Project Settings) at the bottom left → Database → scroll to
+"Connection string" → the **URI** tab → Copy. Then replace `[YOUR-PASSWORD]`
+in it with your database password, which is on that same page.
+
+**Lovable, Bolt, v0** — your app is running on Supabase underneath. Open the
+Supabase project it made for you and follow the lines above.
+
+**Neon** — console.neon.tech → your project → Connection Details.
+
+If you paste the wrong thing — the project URL, an API key, the line with
+`[YOUR-PASSWORD]` still in it — it says so and tells you where the right one
+is. It does not just fail.
+
+## What you get back
+
+Four questions, asked against the copy:
+
+| attack | the question |
+|---|---|
+| **Impersonation** | can a stranger, or another customer, read this? |
+| **Tampering** | can a stranger add, change or delete your data? |
+| **Collision** | can the same thing exist twice? |
+| **Interruption** | can a half-finished write survive? |
+
+A problem reads like this:
+
+    CRITICAL   customers
+
+    Your customers table can be read by anyone.
+
+    Anyone on the internet, without logging in and without an account, can
+    read this table. I did it myself just now and got back 2 rows,
+    including email addresses, phone numbers and names.
+
+    The table has row level security switched on, so it looks protected,
+    but the rule attached to it allows every request. That is why nothing
+    in your dashboard flags it.
+
+    Paste this into Lovable, Claude or Cursor:
+
+      My app has a security problem.
+      ...
+
+And every report ends with **what was not tested, and why** — because an
+attack that never ran comes back looking exactly like an attack that was
+refused, and only one of those is good news.
+
+Nothing found is never reported as "you are safe". It is reported as *these
+attacks, this time, lost*.
+
+## Prove the fix worked
+
+Paste the fix into Lovable or Cursor, let it deploy, then:
+
+```
+npx kryptheon-night --recheck
+```
+
+It runs the same attacks again and compares. A problem that *disappeared* is
+not the same as a problem that was *fixed* — if a table could not be tested
+this time, or is no longer there, it says so rather than crediting you with a
+fix. Close everything, with nothing left untested, and it hands out a badge.
+
+## Three answers, three exit codes
+
+| exit | meaning |
+|---|---|
+| `0` | every attack that ran, lost |
+| `1` | something got through |
+| `2` | it could not run — wrong string, wrong schema name, nothing to attack |
+
+## Running it unattended
+
+```
+KN_DATABASE_URL="postgresql://..."  npx kryptheon-night --yes
+```
+
+`--yes` skips the "may I?" question, and is only for scripts. With no
+keyboard attached and no `--yes`, it stops rather than connecting: the consent
+screen is not worth printing if it is not honoured.
+
+Other options, none of them necessary:
+
+    --schema NAME    the part of the database your app lives in. Leave it
+                     out; it is "public" for almost everyone
+    --recheck        run the same attacks again and say what is really fixed
+    --help
+
+## Deliberately not reported
+
+The **lost update** — two withdrawals of 100 from a balance of 100 that both
+go through. Every Postgres database behaves that way unless the app asks it
+not to, so whether yours is affected depends on code this tool never sees.
+Flagging it would mean flagging every app with a number in it.
+
+## The promise, and how it is kept
+
+> We never touch your live app.
+
+Not a policy — a structural guard. `writeSchema` refuses to run any statement
+that does not name the throwaway copy, so nothing outside it can be written
+even by accident. `untouched.check.js` photographs every function, privilege,
+table, column, policy, role and row in the database, runs a real scan, and
+fails if a single one changed.
+
+It found two real violations the day it was written: the copy builder was
+replacing the customer's own `auth.uid()` function, and opening their `auth`
+schema to `anon`. Both on a live database, while every other check was green.
+
+## Working on it
+
+```
+npm install
+npm run check:dry                                      # no database needed
+KN_DATABASE_URL="postgresql://..."  npm run check      # all of it
+```
+
+`check:dry` is the packaging, the wording of every failure, the consent
+screen, the report and the re-check — sixty checks that need nothing but
+Node. `npm run check` adds fourteen suites that each run against a real
+Postgres.
+
+See [CHECKING.md](CHECKING.md) — what each suite is guarding, the bugs they
+caught, and why a check that leaves the database different from how it found
+it is not a check.
+
+`scan.js` is the same engine with the arguments on the command line
+(`node scan.js "<connection string>" public`). That is the door the checks use
+and it has not changed.
+
+If your network blocks outbound 5432, set `KN_PRELOAD` to a module that swaps
+the driver for one reaching Postgres over 443.