naro-cli 0.9.1 → 0.11.0

package/README.md

@@ -124,7 +124,16 @@ naro backend keys --reveal         Print the service key (a secret; needs databa
 naro backend keys rotate --service Replace a key (--anon or --service); the old one stops
                                    working at once (asks first)
 naro backend auth                  Sign-in settings: email, Google, GitHub, redirects,
-                                   and the callback URL to register for each production host
+                                   the callback URL to register for each production host,
+                                   sign-ups and the minimum password length
+naro backend auth signups off      Nobody signs up on their own (on opens them again)
+naro backend auth password --min-length 10
+                                   The fewest characters a new password takes (6–128)
+naro backend users                 The project's users: id, username, email, verified, created
+naro backend users create --username admin --password-stdin < password.txt
+                                   A confirmed account (--email too, or instead); works
+                                   while sign-ups are closed
+naro backend users delete admin    By id, username or email; ends its sessions (asks first)
 naro backend auth email set --provider resend --from "App <no-reply@example.com>" --api-key-stdin < resend-key.txt
                                    Confirmation and password reset emails from your Resend account
 naro backend auth oauth set github --client-id Iv1.abc --client-secret-stdin < github-secret.txt
@@ -135,12 +144,19 @@ naro backend auth redirects remove https://app.example.com/auth/
                                    Exits 1, changing nothing, when it is not in the list
 naro backend auth require-verification on
                                    Refuse sign-in until the email is confirmed (needs email)
-naro policy list                   Per-table rules and conditions of the Data API
+naro policy list [--table todos]   Row-level security policies, as CREATE POLICY
+naro policy create 'CREATE POLICY "own todos" ON todos TO authenticated USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid())'
+naro policy create --file policies.sql
+                                   CREATE POLICY and DROP POLICY statements, run in order;
+                                   --allow-unindexed accepts a subquery on the outer row
+                                   that no index serves (refused otherwise)
+naro policy drop "own todos" --table todos
+                                   DROP POLICY (asks first)
 naro policy set todos --select owner --insert owner --update owner --delete owner --owner user_id
 naro policy set posts --select-when 'or(is_public.eq.true,user_id.eq.auth.uid())' --insert-when 'user_id.eq.auth.uid()'
 naro policy set posts --from-file policy.json
-                                   The policy as JSON, conditions and all
-naro policy remove todos           Back to deny (asks first)
+                                   Shorthand: writes the policies naro_select … naro_delete
+naro policy remove todos           Drop every policy on the table: back to deny (asks first)
 
 naro promote <deployment-id>       Publish a build to production
 naro rollback [deployment-id]      Back to the previous production build
@@ -216,11 +232,28 @@ A column is `name:type[:modifier…]`:
 Every primary key but a single `integer` one is `NOT NULL`; a foreign key must
 point at its table's primary key or a unique column. `--owner user_id` adds
 `user_id TEXT NOT NULL` and, when the backend is on and ready, an owner policy for all
-four actions; any other new table is closed to the Data API until you run
-`naro policy set` (the command says so). Policies are kept by table name: a
-drop removes the table's policy whenever the project has a backend, on or off
-(the command says so), and a rename leaves the old one behind — the command
-prints what to run.
+four actions; any other new table is closed to the Data API until you give it
+a policy (`naro policy create` or `naro policy set`; the command says so).
+Policies are kept by table name: a drop removes the table's policies whenever
+the project has a backend, on or off (the command says so). A rename leaves
+them under the old name, where they apply to no table — the command prints
+what to run to move them. Move them then: the next time `naro db table`
+creates a table as that name or renames one to it, renaming the table back
+included, the policies stored under the name are removed first, so a new
+table never inherits an earlier one's (a table made by `naro db push` or
+`naro db query` gets them as they are). Whatever a command removes it prints
+so it can be made again: as `CREATE POLICY` statements, which
+`naro policy create` takes back, and — for owner rules, whose owner column
+`CREATE POLICY` cannot say — as the `naro policy set <table> … --owner <column>`
+command that sets them again. A statement that cannot be shown as it is (a
+control character, or a line break inside a string) prints as a `--` comment
+in its place; `--json` has the exact text.
+
+A policy reads columns and, in a subquery, other tables. When a rename or a
+drop takes one of them away, the Data API answers `500 POLICY_INVALID` to the
+requests that policy applies to — on another table, when the policy of `docs`
+reads `members`. The command names each policy the change breaks and why;
+`--dry-run` names them before anything is applied.
 
 SQLite cannot add a PRIMARY KEY, UNIQUE or NOT-NULL-without-default column, or
 drop a primary key, a unique or indexed column, or a table another table
@@ -316,10 +349,12 @@ message that the worker may still expect the new key — run
 `naro backend enable`; the CLI prints that hint (JSON `hint`) and exits 1.
 For a few seconds during a rotation the worker can already refuse the old key.
 
-`naro backend auth` sets up email and social sign-in with the project's own
-accounts — Naro runs no shared sender. Email (confirmation and password reset
-links) needs a Resend API key and a `from` address; Google and GitHub need
-the project's own OAuth app. `naro backend auth` prints a callback URL for
+Sign-in is naro Auth, the project's own (like Supabase Auth). Email and
+password sign-up and sign-in work as soon as the backend is on, with nothing
+to set up. `naro backend auth` adds the rest with the project's own
+accounts — Naro runs no shared sender. Sending email (confirmation and
+password reset links) needs a Resend API key and a `from` address; Google
+and GitHub need the project's own OAuth app. `naro backend auth` prints a callback URL for
 each production host — `https://<project>.naro.sh/_naro/v1/auth/callback/<provider>`
 and the same path on each custom domain. Register, as the app's redirect URI,
 the one for the origin your app passes to `createClient({ url })`: the
@@ -347,25 +382,192 @@ code or reset token rides in the URL fragment, which any script on the page
 — or an open redirect like `/logout?next=…` — can pass on: allow a path of
 sign-in pages rather than a whole origin. Each change uploads
 the Naro worker again; when that upload stops, the change is saved all the
-same and the command exits 1 with `BACKEND_PROVISION_FAILED` — run
-`naro backend enable` to finish. `require-verification on` needs email set
+same and the command exits 1 with `BACKEND_PROVISION_FAILED`, saying
+whether the worker runs it yet — run `naro backend enable` to finish. Until
+then `naro backend auth` shows the saved settings with a warning that the
+worker may still run older ones (`applied: false` with `--json`), so a
+`signups off` that did not upload never reads back as simply closed.
+`require-verification on` needs email set
 up (`VERIFICATION_NEEDS_EMAIL`), and email cannot be removed while it is on.
 
-Policies are default deny: a table without one refuses every anon and
-signed-in request. Each of `--select`, `--insert`, `--update` and `--delete`
-takes `none`, `public`, `authenticated` or `owner`; `owner` lets a signed-in
-user reach only rows whose `--owner` column holds their user id, and fills
-that column in on insert. What a `policy set` leaves out keeps its stored
-value. A change is live within about 10 seconds. `naro gen types` reads the
-policies too: with `--insert owner --owner user_id`, `user_id` is optional in
-the generated `Insert` even when it is `NOT NULL` with no default — run it
+For an app only its admins sign in to, close sign-ups and create the
+accounts yourself — with sign-ups closed, `authenticated` in a policy means
+exactly the users you made:
+
+```bash
+naro backend auth signups off
+naro backend users create --username admin --password-stdin < password.txt
+```
+
+`signups off` makes every sign-up answer `403 SIGNUPS_DISABLED` ("Sign-ups
+are closed for this project."), and a first Google or GitHub sign-in too;
+users that exist keep signing in. `naro backend users create` takes
+`--username`, `--email` or both, and the password from stdin
+(`--password-stdin`: a pipe, or a hidden prompt in a terminal). `--password
+<p>` works too, with a warning on stderr: it lands in shell history. The
+account is confirmed and signs in at once — by username with
+`naro.auth.signIn({ username, password })` — also while sign-ups are closed
+and while sign-in waits for a confirmed email; a username-only account has
+`email: null`. The output never carries the password. `naro backend users`
+lists every user (id, username, email, verified, created; `--json` for all
+fields), and `naro backend users delete <id|username|email>` removes one and
+ends its sessions — it asks first, and without a terminal needs `--yes`
+(`CONFIRMATION_REQUIRED` otherwise, exit 1, nothing deleted). A username is
+3–30 letters, digits, `_` and `.`, in any case. The backend's refusals pass
+through: `409 USERNAME_TAKEN` "That username is already taken.",
+`422 USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL`, `400 PASSWORD_TOO_SHORT`
+"Use at least {n} characters.", `429 WRITE_QUOTA_EXCEEDED`.
+
+While sign-ups are open, a sign-up with a username someone has answers
+`409 USERNAME_TAKEN`, so anyone can learn which usernames exist, as fast as
+sign-up's per-address rate limit allows. With sign-ups closed, every
+sign-up answers `403 SIGNUPS_DISABLED` first.
+
+`naro backend auth password --min-length <n>` sets the fewest characters a
+new password takes, 6 to 128 (6 by default). Sign-up, password reset and
+`users create` refuse a shorter one with "Use at least {n} characters.";
+sign-in never checks it, so passwords set before keep working. Both
+settings re-upload the Naro worker, like the other `naro backend auth`
+changes, and `naro backend auth` shows them (`Sign-ups:`, `Minimum password
+length:`).
+
+A backend turned on before user management answers the `users` commands
+`409 BACKEND_OUTDATED`: run `naro backend enable` once to update this
+project's backend, then run the command again.
+
+### Row-level security
+
+Policies are Postgres's row-level security, as in Supabase. A table without a
+policy refuses every anon and signed-in request; the service key skips
+policies. Write them as `CREATE POLICY`, a change is live within about 10
+seconds, and `naro policy list` prints them back as SQL:
+
+```sql
+-- Each signed-in user reads and changes their own todos.
+CREATE POLICY "own todos" ON todos TO authenticated
+  USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid());
+
+-- Anyone reads published posts.
+CREATE POLICY "published posts" ON posts FOR SELECT USING (published);
+
+-- Members read their team's docs. The subquery reads members through
+-- members' own select policies, so members needs one.
+CREATE POLICY "own memberships" ON members FOR SELECT TO authenticated
+  USING (user_id = auth.uid());
+CREATE POLICY "team docs" ON docs FOR SELECT TO authenticated
+  USING (EXISTS (SELECT 1 FROM members m
+                 WHERE m.team_id = docs.team_id AND m.user_id = auth.uid()));
+
+-- Deleted docs stay hidden, whatever else lets them through.
+CREATE POLICY "hide deleted" ON docs AS RESTRICTIVE FOR SELECT
+  USING (deleted_at IS NULL);
+```
+
+A request passes when at least one permissive policy for its command and role
+passes and every restrictive one does. `FOR ALL` (the default) is every
+command; `TO public` (the default) is anon and signed-in users. As in
+Postgres:
+
+- select reaches the rows the select policies pass;
+- insert writes a row only when it passes `WITH CHECK`, and with `.select()`
+  the select policies too;
+- update reaches the rows its `USING` and the select policies pass, and each
+  changed row must pass `WITH CHECK` (`USING` when there is none) and the
+  select policies — so an update that moves a row out of what select shows,
+  like a soft delete, is refused;
+- delete reaches the rows its `USING` and the select policies pass.
+
+A row outside `USING` is skipped without a word. A written row that misses a
+check writes nothing and answers `403 PERMISSION_DENIED` "New row violates
+row-level security policy for table todos." (with the name of a restrictive
+policy it missed). With no permissive policy for the command, the request is
+refused — `403 PERMISSION_DENIED` "This request is not allowed by the update
+policy of todos." — where Postgres would answer no rows.
+
+Expressions: columns, literals, comparisons, `AND`/`OR`/`NOT`, `IS [NOT] NULL`,
+`IS [NOT] DISTINCT FROM`, `[NOT] IN (…)`, `[NOT] LIKE`/`ILIKE`, `BETWEEN`,
+`EXISTS (SELECT …)` and `IN (SELECT …)`, `auth.uid()`, `auth.role()`,
+`auth.jwt() ->> 'sub' | 'role' | 'email' | 'email_verified'`, and `lower`,
+`upper`, `coalesce`, `length`, `now()`. Supabase's `(select auth.uid())` reads
+as `auth.uid()`. A subquery's table is read through its own select policies;
+policies that would expand themselves are refused ("Infinite recursion
+detected in policy for relation members."). A statement's policies bind at
+most 50 values and write at most 50,000 bytes of SQL, leaving the rest of
+D1's 100 values and 100,000 bytes to the request. A `LIKE` or `ILIKE` pattern
+is at most 50 bytes of UTF-8, which is D1's limit; `LIKE` counts each `*`,
+`?` and `[` as 3.
+
+A subquery that reads the outer row (`m.team_id = docs.team_id`) runs once for
+every row the statement looks at, so it needs an index to find its rows: the
+control plane refuses such a policy until a column its WHERE compares with `=`
+(or `IN`) to a value from outside it starts an index, and names the index to
+create — `naro db index create members team_id`. `--allow-unindexed` accepts
+it anyway; every run then reads the whole table.
+
+For anon, `auth.uid()` is NULL and `auth.jwt()` holds only `role` `'anon'`, as
+in Supabase, and NULL logic is Postgres's: `auth.uid() IS NULL` is true for
+anon, `user_id = auth.uid()` and its `NOT` match no row, and a `NOT EXISTS`
+over another table's policy reads that policy the same way. Target anon with
+`TO anon` or `auth.role() = 'anon'`. `auth.jwt() ->> 'email'` is the user's
+address only once it is verified, and NULL before — sign-up signs a user in
+before the address is confirmed, so an unverified one is only what was typed;
+`email_verified` says which. It is the text `'true'` or `'false'`: write
+`(auth.jwt() ->> 'email_verified') = 'true'`. `IS TRUE`, `IS FALSE`, `NOT x`
+and a value alone read a number or boolean column; on a claim, `auth.uid()`,
+a string, a function or a TEXT column they are refused, with the comparison
+to write — as text, `'true'` would read as false. So is comparing text with
+`TRUE` or `FALSE` — `<> false`, `= true`, `IN (true)`, `BETWEEN`,
+`IS DISTINCT FROM`, also through `coalesce` — since the text `'true'` is not
+`TRUE`: `<> false` would hold for everyone.
+
+Where naro differs from Postgres: no policy for a command is a 403, not zero
+rows; row-level security is always on; roles are only `anon` and
+`authenticated`, with no `security definer` functions; comparisons follow
+SQLite (column affinity and collation), and `lower`, `upper` and `ILIKE` fold
+ASCII only; `now()` is UTC text as `CURRENT_TIMESTAMP` stores it.
+
+`naro policy create --file` parses every statement first, so a syntax error
+sends none; then it runs them in order and stops at the first one refused,
+keeping those before it. `naro policy list` prints what `naro policy create`
+takes back, except the owner comment below. A policy whose name, table or
+string holds a control character (a line break, an escape) is not printed as
+a statement — with the character replaced it would create a different policy
+— but as a `--` comment that says so; `naro policy list --json` has its exact
+text.
+
+`naro policy drop <name>` takes the name as you type it: the policy of exactly
+that name, or else the one of its ASCII lower case. `CREATE POLICY MyPolicy`
+stores `mypolicy`, as in Postgres, and `naro policy drop MyPolicy --table
+todos` drops it; a policy created as `"MyPolicy"` is the one dropped when both
+exist.
+
+`naro policy set` is shorthand: it writes the policies `naro_select`,
+`naro_insert`, `naro_update` and `naro_delete` of a table and leaves its other
+policies alone. Each of `--select`, `--insert`, `--update` and `--delete`
+takes `none` (drops that policy), `public`, `authenticated` or `owner`;
+`owner` lets a signed-in user reach only rows whose `--owner` column holds
+their user id, and fills that column in on insert — a Naro extension SQL
+cannot say, so `naro policy list` prints it as a `-- naro: owner` comment.
+What a `policy set` leaves out keeps its stored value. `naro gen types` reads
+the policies too: with `--insert owner --owner user_id`, `user_id` is optional
+in the generated `Insert` even when it is `NOT NULL` with no default — run it
 again after changing a policy.
 
-Instead of a rule, an action can hold a condition on the row, like a Supabase
-row-level security policy, written in the filter syntax of `naro-js`'s
-`.or()` (commas are AND) with `auth.uid()` for the signed-in user's id —
-unquoted; `"auth.uid()"` is the text, and `auth.uid` without `()` is refused
-rather than read as text:
+A backend turned on before named policies answers the commands that write a
+policy — `naro policy create`, `naro policy drop` and `naro policy set` — with
+`409 BACKEND_OUTDATED`:
+``The project backend is older than named policies. Run `naro backend enable` to update it, then try again.``
+`naro backend enable` uploads the current backend and turns the stored rules
+into named policies; it also turns a backend that is off back on, so run
+`naro backend disable` again afterwards if it should stay off. `naro policy
+list` and `naro policy remove` work in the meantime.
+
+`naro policy set` refuses with `409 POLICY_EXISTS` when the table's `naro_<action>` policy is not one it wrote (for example one made with `naro policy create`): `Policy <name> on <table> is not one naro policy set wrote. Change it with naro policy create, or drop it first: naro policy drop <name> --table <table>.` A `naro_<action>` policy that cannot be read as stored (the table answers `500 POLICY_INVALID`) is not refused: setting a rule replaces it, and `none` drops it.
+
+Instead of a rule, an action can hold a condition on the row, written in the
+filter syntax of `naro-js`'s `.or()` (commas are AND) with `auth.uid()` for
+the signed-in user's id — unquoted; `"auth.uid()"` is the text, and
+`auth.uid` without `()` is refused rather than read as text:
 
 - `--select-when` and `--delete-when`: the rows reads and deletes reach.
 - `--insert-when`: what every new row must meet.
@@ -377,10 +579,9 @@ rather than read as text:
   so `not(and(is_public.eq.1,user_id.eq.auth.uid()))` matches every row that is
   not public, anon included — write what a condition lets in.
 
-When any row of an insert or an update misses its condition, nothing is
-written and the Data API answers `403 PERMISSION_DENIED` ("The new row does not
-meet the insert policy of posts."). A check reads a row as it will be stored
-and compares it with the column's collation (`COLLATE NOCASE`, `RTRIM`). So:
+A check — `WITH CHECK`, and the select policies an update's new row must
+pass — reads a row as it will be stored and compares it with the column's
+collation (`COLLATE NOCASE`, `RTRIM`). So:
 
 - a number column it reads takes numbers, booleans and null, not strings, and
   cannot be compared with `like` or `ilike`;
@@ -391,28 +592,21 @@ and compares it with the column's collation (`COLLATE NOCASE`, `RTRIM`). So:
   another expression must be sent;
 - it cannot read a generated column or a virtual table's column.
 
-One policy's conditions use at most 50 values together (an update's check
-counts each column it reads once more), leaving 50 of D1's 100 per statement
-for the request — 48 for a write with a check, which also binds the table's
-schema to make sure it checks against the table as it is now. `--from-file`
-takes the PUT body, or a policy object from `--json`
+The 50 values count an update's check once more for each column it reads, and
+a write with a check binds the table's schema too (48 left), to make sure it
+checks against the table as it is now. `--from-file` takes the PUT body, or a
+policy object from `--json`
 (`naro policy set posts --json | jq .policy > policy.json`), where
 `auth.uid()` is `{"auth":"uid"}`; its `table`, if it has one, must name the
 table being set. It cannot be combined with the other policy options.
-`naro policy list` prints each condition in filter syntax that reads back as
-the same condition, or as JSON where filter syntax cannot say it exactly
-(`deleted_at.eq.null` would be the text `"null"`, and `= NULL` is not
-`IS NULL`); `--json` gives the exact JSON.
-
-Two things a condition does not do for you. An update or delete is held to its
-own condition only, not to select's, unless it asks for rows back with
-`.select()`. With an update condition broader than select's, a caller can tell
-rows it cannot select apart without `.select()`: an update that sets a value
-the check refuses answers 403 when a hidden row matches its filters and 200
-when none does, so filter by filter it learns what those rows hold. Keep
-update and delete conditions no broader than select's. And an `--update-check`
-you give replaces the default: without `user_id.eq.auth.uid()` in it, a user
-can give a row away by changing its `user_id`. Write
+`naro policy set` prints the table's rules — each condition in filter syntax
+that reads back as the same condition, or as JSON where filter syntax cannot
+say it exactly (`deleted_at.eq.null` would be the text `"null"`, and `= NULL`
+is not `IS NULL`) — and then its policies as `CREATE POLICY`.
+
+An `--update-check` you give replaces the default: without
+`user_id.eq.auth.uid()` in it, a user can give a row away by changing its
+`user_id`. Write
 `--update-when 'user_id.eq.auth.uid()' --update-check 'user_id.eq.auth.uid(),status.eq.draft'`.
 
 ## Machine-readable output (CI / AI agents)
@@ -437,6 +631,7 @@ Failures carry stable codes (`NOT_LOGGED_IN`, `PROJECT_NOT_LINKED`,
 `ENV_NOT_FOUND`, `DOMAIN_NOT_FOUND`, `DOMAIN_NOT_READY`,
 `BACKEND_DISABLED`, `BACKEND_NOT_READY`, `BACKEND_BUSY`,
 `BACKEND_ROTATION_FAILED`, `BACKEND_PROVISION_FAILED`, `POLICY_NOT_FOUND`,
+`POLICY_EXISTS`,
 `VALIDATION_FAILED`, `CONFIRMATION_REQUIRED`, `CANCELED`, …). A destructive
 command run non-interactively without `--yes` fails with
 `CONFIRMATION_REQUIRED` instead of silently doing nothing:
@@ -452,7 +647,8 @@ command run non-interactively without `--yes` fails with
 
 `--yes` (or `-y`) suppresses every prompt — destructive actions
 (production rollback/promote, env/domain removal, database reset, backend key
-rotation, policy removal) run unconfirmed, so use it deliberately in automation.
+rotation, policy removal and drop) run unconfirmed, so use it deliberately in
+automation.
 
 ## CI authentication
 

package/dist/artifact-types.d.ts

@@ -21,6 +21,11 @@ export interface DeploymentArtifact {
     assetsConfig?: {
         notFoundHandling: "single-page-application" | "404-page";
     };
+    /**
+     * Next.js routes ("/posts/[id]") for Speed Insights, read from the app's
+     * folders. Absent for other frameworks.
+     */
+    routes?: string[];
 }
 /** Mirrors the build log shape from the internal build package. */
 export interface BuildLog {