@codyswann/lisa 2.191.14 → 2.192.1

package/plugins/src/harper-fabric/skills/harper-auth/SKILL.md

@@ -260,6 +260,54 @@ Guidance:
   webhook must bypass Harper auth, verify its signature first and keep its table
   writes narrowly scoped.
 
+## Session cookies are `SameSite=None` — guard state-changing POSTs
+
+Harper hardcodes the session cookie's `SameSite=None` attribute on HTTPS. The
+browser therefore attaches the session cookie to **cross-site** requests, so a
+same-origin app cannot rely on `SameSite` to block CSRF on cookie-authenticated,
+state-changing routes (`POST`/`PUT`/`PATCH`/`DELETE`).
+
+Add an app-side origin check in the resource before mutating. Reject requests
+whose `Origin` (or `Referer` fallback) is not an allowed origin:
+
+```javascript
+const ALLOWED_ORIGINS = new Set([
+  'https://app.example.com',
+]);
+
+function requireSameOrigin(context) {
+  const headers = context.requestContext?.headers ?? context.headers;
+  const origin =
+    headers?.get?.('origin') ??
+    headers?.get?.('referer');
+  const ok =
+    typeof origin === 'string' &&
+    [...ALLOWED_ORIGINS].some((allowed) => origin.startsWith(allowed));
+  if (!ok) {
+    const error = new Error('Cross-origin request rejected');
+    error.statusCode = 403; // Harper reads statusCode, not status
+    throw error;
+  }
+}
+
+export class Watchlists extends tables.Watchlists {
+  static async post(target, data, context) {
+    requireSameOrigin(context);
+    // ...authorization and write
+    return super.post(target, await data, context);
+  }
+}
+```
+
+Guidance:
+
+- Call the check on every cookie-authenticated state-changing route. Read-only
+  `GET` handlers and token/`Authorization: Bearer` APIs (not cookie-driven) do
+  not need it.
+- Prefer an allowlist of exact origins over substring matching that a lookalike
+  host could satisfy.
+- This is defense the app owns; Harper will not add it for you.
+
 ## Verification matrix
 
 Run the local app, create the test users, and check unauthenticated, reader, and

package/plugins/src/harper-fabric/skills/harper-build-and-deploy/SKILL.md

@@ -50,15 +50,30 @@ What the build actually does:
 
 Generated Harper deploy artifacts usually include:
 
-- `harper-app/resources.js`
-- `harper-app/resource-*.js`
+- `harper-app/*.js` — every compiled module the build emits to the harper-app
+  root (`resources.js`, `resource-*.js`, and any other output such as a route
+  negotiation module). The single-star does **not** cross a directory separator,
+  so it does not match hand-written shims one level down.
 - `harper-app/web/**`
 - `harper-app/lib/**`
 
+The guard surfaces (`generated-artifact-globs.txt` for the PreToolUse block hook,
+`.gitignore`, `.prettierignore`, the ESLint/oxlint/knip ignores, and
+`tsconfig.eslint.json`) all key off `harper-app/*.js` so a newly-named compiled
+module is protected automatically. **Name compiled resource modules
+`resource-*.ts`** so their JS output is unambiguously generated.
+
+If you keep a *hand-written* `.js` at the harper-app root (e.g. an SEO shell),
+the root-level rule would otherwise treat it as generated: re-include it with a
+`!harper-app/<file>.js` line below the managed gitignore block, and add it to
+`.lisa/harper-generated-artifact-allowlist.txt` so the block hook lets you edit
+it. Hand-written shims nested under `harper-app/<route>/index.js` need no
+exemption — the root-level rule never matches them.
+
 Every lint, format, dead-code, search, or generated-artifact guard must ignore
-those generated paths unless it is explicitly validating the build output itself.
-When a new generated path appears, add it to every relevant ignore surface in the
-same change; partial ignores fail later gates in non-obvious ways.
+generated paths unless it is explicitly validating the build output itself. When
+a new generated *directory* appears, add it to every relevant ignore surface in
+the same change; partial ignores fail later gates in non-obvious ways.
 
 - **TypeScript under `src/` is source.** `bun run build` produces the deployable
   Harper assets from it.

package/plugins/src/harper-fabric/skills/harper-resources/SKILL.md

@@ -74,6 +74,41 @@ See [[harper-config-yaml]] for the extension wiring, [[harper-schema-graphql]] f
 how the schema defines the tables resources extend, and [[harper-realtime]] when
 `subscribe`, `publish`, or WebSocket behavior is part of the feature.
 
+## Throwing HTTP status errors
+
+Harper's thrown-error response writer reads **`error.statusCode`** (falling back
+to `500`). A plain `error.status` is **ignored** — throw an error with only
+`status` set and every intended `4xx` is served as a `500`. Verified on
+harperdb 4.7.32.
+
+Always set `statusCode` (keep `status` too only if callers or tests read it):
+
+```javascript
+static async post(target, data, context) {
+  if (!context.user) {
+    const error = new Error('Authentication required');
+    error.statusCode = 401; // NOT `error.status` — Harper reads statusCode
+    throw error;
+  }
+  // ...
+}
+```
+
+A shared helper keeps every throw site correct:
+
+```javascript
+function throwStatus(message, status) {
+  // Set both: `statusCode` is what Harper serves; `status` is kept for
+  // returned-response symmetry and any caller/test that reads it.
+  throw Object.assign(new Error(message), { status, statusCode: status });
+}
+```
+
+The `harper-require-statuscode-on-thrown-error` ast-grep rule flags errors that
+carry `status` without `statusCode`. Pass `context` through to `super` and nested
+table calls so authorization and the request transaction stay aligned — see
+[[harper-rest-queries]] for context propagation and iterator draining.
+
 ## Project conventions (TS is source)
 
 - **Write resources in TypeScript under `src/`. `harper-app/resources.js` is a

package/plugins/src/harper-fabric/skills/harper-rest-queries/SKILL.md

@@ -121,6 +121,38 @@ const products = await tables.Products.search({
 });
 ```
 
+## Sort with no conditions crashes the planner
+
+A `search()` that carries a `sort` but an **empty `conditions: []`** array throws
+at runtime — the planner cannot seed the btree scan from the sort attribute. This
+is a latent `500` the first time an unfiltered, sorted collection page is
+requested (verified on harperdb 4.7.32).
+
+```javascript
+// ✗ crashes: sort with nothing to seed the scan
+tables.Advisor.search({
+  conditions: [],
+  sort: { attribute: 'lastName' },
+});
+```
+
+Seed a floor/sentinel condition on the sort attribute so the planner has an index
+range to walk, then apply the sort:
+
+```javascript
+// ✓ floor condition on the sort attribute seeds the scan
+tables.Advisor.search({
+  conditions: [
+    { attribute: 'lastName', comparator: 'greater_than_equal', value: '' },
+  ],
+  sort: { attribute: 'lastName' },
+});
+```
+
+Centralize this in the page helper (`searchPageAndCount`) rather than duplicating
+a sentinel at each call site. The `harper-no-empty-conditions-with-sort` ast-grep
+rule flags the crashing shape.
+
 ## Relationship queries
 
 Relationship attributes can be queried with dot syntax when the relationship is
@@ -200,9 +232,14 @@ Useful query keys:
 | `select` | Projection list. Keep admin-only fields out of public responses. |
 | `explain` | Debug execution order and index usage while tuning. |
 
-`search()` can return an `AsyncIterable`. When iterating manually or stopping
-early, drain it or call the iterator's `return()` in `finally` so Harper can
-release the read transaction:
+`search()` can return an `AsyncIterable`. An early `return`/`break` out of a
+`for await (... of tables.X.search(...))` loop abandons the iterator before the
+scan completes and **leaks the open read transaction** (verified on
+harperdb 4.7.32). When iterating manually or stopping early, drain it or call the
+iterator's `return()` in `finally` so Harper releases the read transaction — or
+bound the query (`search({ ..., limit: 1 })`) when you only need the first row.
+The `harper-no-early-return-in-search-loop` ast-grep rule flags early exits from
+these loops:
 
 ```javascript
 const iterator = tables.Products