@gspothq/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# gspot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+gspot lints AI-generated code and writes rules for AI coding agents.
+
+## Install
+
+Commit your work, then run:
+
+```sh
+npm install --save-dev --save-exact @gspothq/cli
+git add package.json package-lock.json
+git commit -m "build: Add gspot"
+npx gspot init
+npx gspot install
+npx gspot check
+```
+
+The [install guide](https://generativespotting.com/guides/install/) covers other package managers and mise. The
+[gspot guides and reference](https://generativespotting.com/) cover everything else.

package/configurations/database/postgres/manifest.toml

@@ -0,0 +1,114 @@
+allowed_words = ["PostgreSQL", "Postgres"]
+[configuration]
+title = "Postgres"
+requires = ["sql"]
+description = "Postgres migrations: squawk for the changes that lock or break, ordered versions, and migrations that never change after they run. The schema checks ask for row security, explicit grants, and an index under every foreign key."
+
+[detect]
+dependencies = ["pg", "postgres", "psycopg", "asyncpg", "@neondatabase/serverless"]
+content = { "prisma/schema.prisma" = '(?:^|\n)[\t ]*provider[\t ]*=[\t ]*"postgresql"' }
+
+[files]
+paths = ["db/migrations/*.sql", "migrations/*.sql", "**/supabase/migrations/*.sql"]
+
+[[tool]]
+name = "squawk"
+version = "2.64.0"
+min_version = "2.0.0"
+mise = "github:sbdchd/squawk"
+npm = "squawk-cli"
+github = { name = "sbdchd/squawk", version = "v2.64.0" }
+[[tool.replace]]
+file = ".squawk.toml"
+shared = false
+
+[[tool.replace]]
+file = "squawk.toml"
+shared = false
+
+[[tool_file]]
+target = ".gspot/config/squawk.toml"
+tool = "squawk"
+per_scope = true
+rule_keys = ["excluded_rules"]
+
+[[check]]
+name = "squawk"
+files = { paths = ["{setting:postgres.migrations_folder}/**/*.sql"] }
+example = "A migration adding a constraint that requires a disruptive table scan can report a migration-safety finding. Follow the reported rule to separate creation and validation or otherwise reduce the lock, then review the migration against the deployment database."
+level = "recommended"
+stage = "commit"
+command = ["squawk", "--config", "{tool_file:squawk}", "--reporter", "json", "{files}"]
+output = { format = "json", line_base = 0, fields = { file = "file", line = "line", column = "column", rule = "rule_name", message = "message" } }
+summary = "Reads every migration for the change that locks a table, rewrites it, or breaks the running application."
+why = "A migration that takes an exclusive lock on a large table stops the application for as long as it runs."
+help = "Follow the help squawk prints for the rule. Turn one rule off with gspot ignore postgres/squawk --rule `<name>` --reason \"`<why>`\"."
+
+[[check]]
+name = "migration-order"
+example = "A new migration numbered before the latest committed migration reports an ordering finding. Give the new migration a version later than the committed maximum without renaming already applied migrations."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every migration has a version, that no two share one, and that a new migration sorts after the committed ones."
+why = "A migration that sorts before one already applied never runs on the databases that are ahead of it."
+help = "Rename the new migration with a version later than the newest committed one."
+
+[[check]]
+name = "edited-migrations"
+example = "Editing an already committed migration reports a frozen-history finding. Preserve the intended change as a new migration, restore the original migration bytes, and rerun. Do not rewrite a migration already applied to shared databases."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that no migration at or before postgres.frozen_through differs from its committed text."
+why = "A migration that ran never runs again, so an edit to it changes new databases only and the environments drift apart."
+help = "Restore the file with git checkout, and write the change as a new migration."
+
+[[check]]
+name = "row-level-security"
+example = "A newly created table without row-level security reports a missing-RLS finding. Add `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` for the table."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every table in a client schema turns on row level security."
+why = "A table in an exposed schema with no row security is readable and writable by every client that holds the public key."
+help = "Enable row level security on the table."
+
+[[check]]
+name = "grants"
+example = "The statement `GRANT ALL ON TABLE public.items TO app_reader;` reports a broad grant. If the role only reads rows, use `GRANT SELECT ON TABLE public.items TO app_reader;`."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Refuses a grant of every privilege in a migration."
+why = "Granting everything includes truncating the table, adding triggers, and every privilege a later Postgres adds, which nobody meant to give."
+help = "Name the privileges the role needs, such as `SELECT` alone."
+
+[[check]]
+name = "definer-search-path"
+example = "A `SECURITY DEFINER` function without an explicit safe search path reports a finding. Add `SET search_path = ''` to the definition and schema-qualify the objects used in its body."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every SECURITY DEFINER function sets its search_path."
+why = "A definer function runs with its owner's rights, and a caller who controls the search path chooses the objects it touches."
+help = "Give the function an empty `search_path` in its definition, and qualify every name inside it."
+
+[[check]]
+name = "foreign-key-indexes"
+example = "A foreign key on `orders.customer_id` without an index starting with that column reports a missing index. Add `CREATE INDEX orders_customer_id_idx ON orders (customer_id);` in the migration set."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Checks that an index, a primary key, or a unique key leads with every foreign key column."
+why = "Deleting a parent row scans the whole child table when the foreign key has no index."
+help = "Create an index that starts with the foreign key column."
+
+[[naming.override]]
+paths = ["**/migrations/**"]
+categories = ["directories"]
+allow_digits = true
+reason = "Migration directories use the migration tool timestamp names."
+
+[defaults]
+"tools.sqlfluff.dialect" = "postgres"

package/configurations/database/postgres/rules/POSTGRES.md

@@ -0,0 +1,78 @@
+# Postgres
+
+Migrations, tables, row security, functions, grants, data migrations, and tests of a Postgres
+database. Use the roles and schemas the application declares.
+
+## Migrations
+
+- Create a blank migration with the project's migration command, then edit the generated file.
+- Repair migration history only when the user asks for that task.
+- Make every durable change through a migration. Never use a web console or SQL editor on a remote database.
+- Use idempotent data definition language (DDL) only when the public interface promises repeated execution and you verify existing definitions. Do not hide schema drift with `IF NOT EXISTS`.
+
+## Tables
+
+- Use UUIDv7 keys when rows need time order.
+- Use `TIMESTAMPTZ` for timestamps. Mutable rows that need audit columns get `created_at` and
+  `updated_at`, which the declared timestamp trigger or write owner updates.
+- Index common filters, ordering columns, and frequent row security predicates.
+- Durable invariants live in the database as generated columns, uniqueness, and check
+  constraints, not only in client validation.
+
+## Row-level security
+
+- Every policy names its roles with `TO`, unless every role belongs in it.
+- Wrap the identity function of an ownership check in a scalar subquery, so the planner evaluates
+  it once per statement instead of once per row.
+- `UPDATE` needs both a `SELECT` policy and an `UPDATE` policy.
+
+| Operation   | Policy expression                                                               |
+| ----------- | ------------------------------------------------------------------------------- |
+| Read rows   | `USING` selects visible existing rows                                           |
+| Insert rows | `WITH CHECK` validates the proposed row; an insert policy has no `USING` clause |
+| Update rows | `USING` selects existing rows and `WITH CHECK` validates their new values       |
+| Delete rows | `USING` selects rows that may be deleted                                        |
+
+- Permissive policies broaden access and restrictive policies add conditions; review how every
+  policy for the role combines.
+- Check resource ownership and tenant membership. Check proposed values too, so an update cannot
+  move a row into another user's or tenant's scope.
+- Handle an unauthenticated identity explicitly, and limit anonymous access to the rows and
+  operations the public API exposes.
+- Authorize from trusted claims and current membership data, never from user-editable template
+  metadata, and account for stale claims after a membership change.
+- Grants and row level security (RLS) provide separate controls: restrict table and schema privileges, then limit rows with
+  policies. RLS does not cover `TRUNCATE`.
+- A `USING (true)` policy fits only a public or service-only table, and the
+  migration says why.
+- A privileged service role still needs explicit table grants, never a bypass for precise ones.
+- A view that clients can read sets `security_invoker = true` on Postgres 15 and later to respect
+  the RLS of its tables. Otherwise, revoke access to it or keep it in a private schema.
+
+## Functions and grants
+
+- Declare functions `SECURITY INVOKER`, the default. Use `SECURITY DEFINER` only for a function that must
+  cross RLS or role boundaries, and its comment says why.
+- Start every object from least privilege: `REVOKE ALL ON <object> FROM PUBLIC` and from broad roles.
+- Grant execute with the full function signature, only to the roles that need it. A trigger
+  function gets no direct execute grant.
+- Grant schema usage only to roles that resolve objects in it, `SELECT` only for a real read path,
+  and write access by column list.
+- Avoid dynamic SQL. When the operation requires it, quote identifiers and values safely and constrain the
+  input domain.
+- Raise exceptions with a meaningful SQLSTATE class when clients or tests branch on it.
+
+## Data migrations
+
+Durable rows live in migrations, not in seed files.
+
+## Tests
+
+- pgTAP tests cover schema, constraints, grants, triggers, RLS, functions, and other behavior a
+  migration owns.
+- Integration tests run against a local database and exercise client flows, auth, and RLS. They
+  never mock grants or policies away, because they verify the database behavior.
+- A schema change that another project consumes regenerates the types and updates the dependent
+  tests.
+
+Name pgTAP files for the table or function under test.

package/configurations/framework/astro/eslint-presets.json

@@ -0,0 +1,138 @@
+{
+    "recommended": {
+        "package": "eslint-plugin-astro",
+        "version": "1.7.0",
+        "source": "configs.flat/recommended",
+        "blocks": [
+            { "parser": false },
+            { "files": ["*.astro", "**/*.astro"], "parser": true, "rules": {} },
+            { "files": ["**/*.astro/*.js", "*.astro/*.js"], "parser": false, "rules": { "prettier/prettier": "off" } },
+            { "files": ["**/*.astro/*.ts", "*.astro/*.ts"], "parser": true, "rules": { "prettier/prettier": "off" } },
+            {
+                "parser": false,
+                "rules": {
+                    "astro/missing-client-only-directive-value": "error",
+                    "astro/no-conflict-set-directives": "error",
+                    "astro/no-deprecated-astro-canonicalurl": "error",
+                    "astro/no-deprecated-astro-fetchcontent": "error",
+                    "astro/no-deprecated-astro-resolve": "error",
+                    "astro/no-deprecated-getentrybyslug": "error",
+                    "astro/no-unused-define-vars-in-style": "error",
+                    "astro/valid-compile": "error"
+                }
+            }
+        ]
+    },
+    "accessibility": {
+        "package": "eslint-plugin-astro",
+        "version": "1.7.0",
+        "source": "configs.flat/jsx-a11y-recommended",
+        "blocks": [
+            { "parser": false },
+            { "files": ["*.astro", "**/*.astro"], "parser": true, "rules": {} },
+            { "files": ["**/*.astro/*.js", "*.astro/*.js"], "parser": false, "rules": { "prettier/prettier": "off" } },
+            { "files": ["**/*.astro/*.ts", "*.astro/*.ts"], "parser": true, "rules": { "prettier/prettier": "off" } },
+            {
+                "parser": false,
+                "rules": {
+                    "astro/jsx-a11y/alt-text": "error",
+                    "astro/jsx-a11y/anchor-ambiguous-text": "off",
+                    "astro/jsx-a11y/anchor-has-content": "error",
+                    "astro/jsx-a11y/anchor-is-valid": "error",
+                    "astro/jsx-a11y/aria-activedescendant-has-tabindex": "error",
+                    "astro/jsx-a11y/aria-props": "error",
+                    "astro/jsx-a11y/aria-proptypes": "error",
+                    "astro/jsx-a11y/aria-role": "error",
+                    "astro/jsx-a11y/aria-unsupported-elements": "error",
+                    "astro/jsx-a11y/autocomplete-valid": "error",
+                    "astro/jsx-a11y/click-events-have-key-events": "error",
+                    "astro/jsx-a11y/control-has-associated-label": [
+                        "off",
+                        {
+                            "ignoreElements": ["audio", "canvas", "embed", "input", "textarea", "tr", "video"],
+                            "ignoreRoles": [
+                                "grid",
+                                "listbox",
+                                "menu",
+                                "menubar",
+                                "radiogroup",
+                                "row",
+                                "tablist",
+                                "toolbar",
+                                "tree",
+                                "treegrid"
+                            ],
+                            "includeRoles": ["alert", "dialog"]
+                        }
+                    ],
+                    "astro/jsx-a11y/heading-has-content": "error",
+                    "astro/jsx-a11y/html-has-lang": "error",
+                    "astro/jsx-a11y/iframe-has-title": "error",
+                    "astro/jsx-a11y/img-redundant-alt": "error",
+                    "astro/jsx-a11y/interactive-supports-focus": [
+                        "error",
+                        { "tabbable": ["button", "checkbox", "link", "searchbox", "spinbutton", "switch", "textbox"] }
+                    ],
+                    "astro/jsx-a11y/label-has-associated-control": "error",
+                    "astro/jsx-a11y/label-has-for": "off",
+                    "astro/jsx-a11y/media-has-caption": "error",
+                    "astro/jsx-a11y/mouse-events-have-key-events": "error",
+                    "astro/jsx-a11y/no-access-key": "error",
+                    "astro/jsx-a11y/no-autofocus": "error",
+                    "astro/jsx-a11y/no-distracting-elements": "error",
+                    "astro/jsx-a11y/no-interactive-element-to-noninteractive-role": [
+                        "error",
+                        { "tr": ["none", "presentation"], "canvas": ["img"] }
+                    ],
+                    "astro/jsx-a11y/no-noninteractive-element-interactions": [
+                        "error",
+                        {
+                            "handlers": [
+                                "onClick",
+                                "onError",
+                                "onLoad",
+                                "onMouseDown",
+                                "onMouseUp",
+                                "onKeyPress",
+                                "onKeyDown",
+                                "onKeyUp"
+                            ],
+                            "alert": ["onKeyUp", "onKeyDown", "onKeyPress"],
+                            "body": ["onError", "onLoad"],
+                            "dialog": ["onKeyUp", "onKeyDown", "onKeyPress"],
+                            "iframe": ["onError", "onLoad"],
+                            "img": ["onError", "onLoad"]
+                        }
+                    ],
+                    "astro/jsx-a11y/no-noninteractive-element-to-interactive-role": [
+                        "error",
+                        {
+                            "ul": ["listbox", "menu", "menubar", "radiogroup", "tablist", "tree", "treegrid"],
+                            "ol": ["listbox", "menu", "menubar", "radiogroup", "tablist", "tree", "treegrid"],
+                            "li": ["menuitem", "menuitemradio", "menuitemcheckbox", "option", "row", "tab", "treeitem"],
+                            "table": ["grid"],
+                            "td": ["gridcell"],
+                            "fieldset": ["radiogroup", "presentation"]
+                        }
+                    ],
+                    "astro/jsx-a11y/no-noninteractive-tabindex": [
+                        "error",
+                        { "tags": [], "roles": ["tabpanel"], "allowExpressionValues": true }
+                    ],
+                    "astro/jsx-a11y/no-redundant-roles": "error",
+                    "astro/jsx-a11y/no-static-element-interactions": [
+                        "error",
+                        {
+                            "allowExpressionValues": true,
+                            "handlers": ["onClick", "onMouseDown", "onMouseUp", "onKeyPress", "onKeyDown", "onKeyUp"]
+                        }
+                    ],
+                    "astro/jsx-a11y/role-has-required-aria-props": "error",
+                    "astro/jsx-a11y/role-supports-aria-props": "error",
+                    "astro/jsx-a11y/scope": "error",
+                    "astro/jsx-a11y/tabindex-no-positive": "error"
+                }
+            }
+        ]
+    }
+}

package/configurations/framework/astro/manifest.toml

@@ -0,0 +1,95 @@
+
+
+[configuration]
+title = "Astro"
+requires = ["javascript"]
+suggests = ["typescript", "css"]
+description = "Astro components: ESLint reads the frontmatter, the markup, and the scripts together with the recommended and accessibility rules of the Astro plugin as errors, and astro check reports type errors in every component."
+
+[detect]
+dependencies = ["astro"]
+extensions = [".astro"]
+
+[files]
+extensions = [".astro"]
+filenames = ["astro.config.mjs", "astro.config.ts"]
+
+[[tool]]
+name = "eslint-plugin-astro"
+rule_prefix = "astro"
+kind = "library"
+version = "1.7.0"
+npm = "eslint-plugin-astro"
+
+[tool.eslint]
+extensions = [".astro"]
+
+[[tool]]
+name = "eslint-plugin-jsx-a11y"
+
+[[tool]]
+name = "astro-check"
+version = "0.9.10"
+npm = "@astrojs/check"
+version_command = ["astro", "check", "--version"]
+
+[[tool]]
+name = "prettier-plugin-astro"
+kind = "library"
+version = "1.0.1"
+npm = "prettier-plugin-astro"
+
+[tool.prettier]
+entry = "dist/index.js"
+extensions = [".astro"]
+
+[[tool.prettier.overrides]]
+files = "*.astro"
+
+[tool.prettier.overrides.options]
+parser = "astro"
+
+[[check]]
+name = "astro-check"
+example = "A component whose frontmatter holds `const count: number = 'three';` reports `ts(2322)`. Give the value the declared type, such as `const count: number = 3;`."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+command = ["astro-check", "astro", "check", "--minimumSeverity", "warning", "--minimumFailingSeverity", "warning"]
+exit_codes = [1]
+summary = "Runs astro check over the scope: the type errors and warnings of every Astro component."
+why = "The TypeScript compiler cannot read a component file, so a type error inside one ships unless the Astro checker reads it."
+help = "Read the first error astro check prints and fix that component; later errors are often the same mistake."
+
+[check.files]
+extensions = [".astro"]
+
+[check.output]
+format = "regex"
+pattern = "^(?<file>[^:\\s][^:]*\\.astro):(?<line>\\d+):(?<column>\\d+) - (?:error|warning) (?<rule>[a-z-]+\\(\\d+\\)): (?<message>.*)$"
+
+[eslint]
+all_level_rules = ["astro/no-unused-css-selector", "astro/prefer-class-list-directive", "astro/prefer-object-class-list", "astro/prefer-split-class-list"]
+
+[eslint.presets.recommended]
+package = "eslint-plugin-astro"
+source = "configs.flat/recommended"
+
+[eslint.presets.accessibility]
+package = "eslint-plugin-astro"
+source = "configs.flat/jsx-a11y-recommended"
+
+[[eslint.rules_off]]
+rules = ["gspot/no-trivial-files"]
+files = ["**/*.astro", "**/*.astro/*.ts", "**/*.astro/*.js"]
+reason = "A component is markup, never a file that only forwards: a script that only imports a module is how Astro bundles client code, and Astro reads the props of a component from the Props type in its own frontmatter."
+
+[defaults]
+"tools.eslint.import_extension" = "extensionless"
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["eslint-plugin-astro", "eslint-plugin-jsx-a11y"]

package/configurations/framework/astro/rules/ASTRO.md

@@ -0,0 +1,39 @@
+# Astro
+
+These rules cover Astro components, islands, markup, routing, and the data a page loads.
+
+## Components
+
+<!-- level: all -->
+
+- Keep the frontmatter to data: read the props, load what the page needs, and compute values.
+  Move a helper longer than a few lines into a module.
+
+## Frontmatter and props
+
+- Declare the props as `type Props = { … }` in the frontmatter and read them from `Astro.props`.
+- The frontmatter runs on the server. A value reaches the browser only through the markup or the props of an island.
+
+## Islands
+
+- Ship HTML by default. Add a `client:` directive only to a component that needs the browser.
+- Pick the most deferred directive that works: `client:visible` or `client:idle` before `client:load`.
+- `client:only` names the framework of the component, such as `client:only="react"`.
+- Astro serializes island props, so pass plain data. A function or a class instance does not survive the trip.
+
+## Markup
+
+- Load a local image through `astro:assets`.
+- Astro bundles a `<script>` without attributes into a module. Keep `is:inline` for code that must run before the page renders.
+
+## Routing and data
+
+- A page under `src/pages/` names its route by its path. A dynamic route of a static site exports `getStaticPaths`.
+- Load content through a content collection with a schema, so a missing field fails the build.
+- Read a secret on the server only, from a variable without the `PUBLIC_` prefix. Every visitor can read a `PUBLIC_` variable.
+
+## References
+
+- [Astro components](https://docs.astro.build/en/basics/astro-components/).
+- [Client directives](https://docs.astro.build/en/reference/directives-reference/#client-directives).
+- [Content collections](https://docs.astro.build/en/guides/content-collections/).

package/configurations/framework/expo/manifest.toml

@@ -0,0 +1,43 @@
+[configuration]
+title = "Expo"
+requires = ["react-native"]
+description = "Expo applications: rules for public environment variables and DOM exports, plus Expo Doctor's project and SDK compatibility checks. React Native supplies the native component and style rules."
+
+[detect]
+dependencies = ["expo"]
+
+[files]
+filenames = ["app.json", "app.config.js", "app.config.ts", "eas.json"]
+
+[[tool]]
+name = "eslint-plugin-expo"
+rule_prefix = "expo"
+kind = "library"
+version = "1.1.0"
+npm = "eslint-plugin-expo"
+
+[[tool]]
+name = "expo-doctor"
+version = "1.20.4"
+npm = "expo-doctor"
+
+[[check]]
+name = "doctor"
+tool = "expo-doctor"
+example = "An Expo project whose installed `react-native` differs from the version its Expo SDK expects reports a failed Doctor check. Install the expected version with `npx expo install --check` and rerun."
+level = "recommended"
+stage = "push"
+runs = "scope"
+needs = ["network"]
+summary = "Runs Expo Doctor in the selected Expo scope and reports each failed check with its issues."
+why = "A native package on the wrong version for the Expo SDK builds and then crashes on the device."
+help = "Read the issues and advice Expo Doctor prints for the failed check, then run npx expo install --check."
+
+[eslint]
+all_level_rules = ["expo/prefer-box-shadow"]
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["eslint-plugin-expo"]

package/configurations/framework/express/manifest.toml

@@ -0,0 +1,17 @@
+[configuration]
+title = "Express"
+requires = ["javascript"]
+suggests = ["openapi"]
+description = "An Express service: the Semgrep rules for request handling, an OpenAPI document that lints and matches its source."
+
+[detect]
+dependencies = ["express"]
+
+[[eslint.selectors]]
+selector = "CallExpression[callee.property.name=/^(json|send)$/] ObjectExpression > Property[key.name=/^(message|error)$/] > TemplateLiteral.value[expressions.length>0]"
+message = "A message a client reads names no identifier; put the value in its own field."
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true

package/configurations/framework/express/rules/EXPRESS.md

@@ -0,0 +1,73 @@
+# Express
+
+Routes, middleware, errors, and body parsing in an Express service, on top of the HTTP rules.
+
+## Routes and middleware
+
+<!-- level: all -->
+
+Express requires no layout, schema library, or response envelope. Use the contracts the project
+already has instead of adding competing ones.
+
+```ts
+// Bad: the route validates by hand, queries the database, and relays a provider response.
+router.post('/orders', async (req, res) => {
+    const { accountId, itemIds } = req.body;
+    if (!Array.isArray(itemIds)) {
+        res.status(400).json({ error: 'Bad items' });
+        return;
+    }
+    const account = await db.accounts.find(accountId);
+    const response = await fetch(paymentUrl, { method: 'POST', body: JSON.stringify({ account, itemIds }) });
+    res.json(await response.json());
+});
+```
+
+```ts
+// Good: middleware validates and authenticates; the route makes one domain call.
+router.post('/orders', authenticate, validateBody(submitOrderSchema), async (req, res) => {
+    const order = await submitOrder(res.locals.accountId, res.locals.body);
+    res.status(201).json(order);
+});
+```
+
+- Middleware can enforce ownership. It reaches the database for product behavior only through auth
+  or ownership helpers built for that boundary.
+- A permission check that depends on domain state belongs in a module; a transport-level one
+  belongs in ownership middleware.
+
+## Errors
+
+- Express 5 forwards the rejection of a promise that a route or middleware returns, so return the
+  promise and add no wrapper that repeats this. Express 4 needs the project's async handler or an
+  explicit `next(error)`.
+- Callback-based asynchronous work passes its errors to `next(error)` in both versions.
+- Error middleware keeps its four-argument signature, even when the function does not use an argument.
+- After the response sends its headers, error middleware calls `next(error)` instead of writing a
+  second response.
+- The not-found handler comes after every route.
+
+## Body parsing and proxies
+
+Parsing a body takes work, so mount a JSON parser with a small default limit, and a larger one only on
+the route that needs it.
+
+```ts
+// Bad: every endpoint inherits an oversized JSON parser.
+app.use(express.json({ limit: '50mb' }));
+
+// Good: a larger limit only where the endpoint needs it.
+app.use('/imports', express.json({ limit: '5mb' }), importsRouter);
+app.use(express.json({ limit: '100kb' }));
+```
+
+Enable `trust proxy` only when you know the deployment topology. Select the proxies whose
+forwarding headers you trust.
+
+## References
+
+| Topic          | Primary source                                                                   |
+| -------------- | -------------------------------------------------------------------------------- |
+| Error handling | [Express error handling](https://expressjs.com/en/guide/error-handling/)         |
+| Security       | [Production security](https://expressjs.com/en/advanced/best-practice-security/) |
+| Proxies        | [Express behind proxies](https://expressjs.com/en/guide/behind-proxies.html)     |