@codyswann/lisa 2.169.0 → 2.171.0

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

@@ -0,0 +1,320 @@
+---
+name: harper-auth
+description: This skill should be used when adding or debugging Harper (HarperDB/Fabric) authentication and authorization - roles.yaml, user and role Operations API calls, Basic auth, JWT operation tokens, exported-resource permissions, and Resource context.user checks. Pairs with harper-config-yaml, harper-resources, harper-rest-queries, and harper-operations.
+---
+
+# Harper Auth
+
+## Overview
+
+Harper uses role-based access control. Every user has one role, and that role
+decides which databases, tables, attributes, and operations the user can access.
+Use declarative `roles.yaml` for application-owned roles and the Operations API
+for environment-owned users, password changes, role audits, and token issuance.
+
+Cross-check extension wiring in [[harper-config-yaml]] before editing roles:
+custom `config.yaml` files replace Harper's default config, so `roles` must be
+re-declared alongside `rest`, `graphqlSchema`, and `jsResource` when the app needs
+all of them. Cross-check endpoint/resource behavior in [[harper-resources]] and
+query filters in [[harper-rest-queries]].
+
+## Role model
+
+Harper has built-in roles and custom roles:
+
+| Role type | Use it for | Notes |
+| --- | --- | --- |
+| `super_user` | Operators, deploy automation, emergency admin work | Full access to operations and data. Do not use for app clients. |
+| `structure_user` | Schema/database administration without full data access | Scope narrowly when used; normal app users usually should not need it. |
+| Custom role | Application clients, readers, editors, service accounts | Permissions are explicit. Missing database/table entries mean no access. |
+
+Prefer least-privilege custom roles for application traffic. A public read client,
+an editor/admin client, and a deploy/operator client should normally be separate
+users with separate roles.
+
+## Enable role files
+
+Keep roles in the component root, typically `harper-app/roles.yaml`, and enable
+the built-in `roles` extension in `harper-app/config.yaml`:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+```
+
+Because `config.yaml` is not merged with Harper's defaults, keep every extension
+the component needs in this file. Removing `roles` silently stops role-file
+reconciliation; removing `rest` or `jsResource` can make the secured endpoint
+disappear while the role still exists.
+
+## Declare roles in `roles.yaml`
+
+Use `roles.yaml` for roles that should be versioned with the app. On startup,
+Harper creates missing declared roles and updates existing declared roles to match
+the file.
+
+Example: public readers can read orders, but only admins can write:
+
+```yaml
+public_reader:
+  super_user: false
+  app:
+    Orders:
+      read: true
+      insert: false
+      update: false
+      delete: false
+      attributes:
+        id:
+          read: true
+        status:
+          read: true
+        publicTotal:
+          read: true
+
+order_admin:
+  super_user: false
+  app:
+    Orders:
+      read: true
+      insert: true
+      update: true
+      delete: false
+      attributes:
+        internalNotes:
+          read: true
+          insert: true
+          update: true
+```
+
+Rules:
+
+- Database keys such as `app` must match the database names in `schema.graphql`.
+- Table keys such as `Orders` must match the table type names, not necessarily the
+  exported REST path.
+- Table-level `read`, `insert`, `update`, and `delete` are the outer gate.
+- Attribute permissions narrow field-level access. They cannot grant a capability
+  that the table-level permission denies.
+- If a database or table is omitted from the role, that role has no access to it.
+
+Use role files for stable app permissions. Use Operations API calls when changing
+users, rotating credentials, or inspecting what the deployed system actually has.
+
+## Manage users and roles with Operations API
+
+User and role mutations require a `super_user` caller. Send JSON `POST` requests
+to the Operations API, usually port `9925` locally:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"list_roles"}'
+```
+
+Create a user for a declared role:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "add_user",
+    "username": "public-client",
+    "password": "replace-with-generated-secret",
+    "role": "public_reader",
+    "active": true
+  }'
+```
+
+Change a user's role or password:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "alter_user",
+    "username": "public-client",
+    "role": "order_admin",
+    "active": true
+  }'
+```
+
+Remove a user before removing a role:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"drop_user","username":"public-client"}'
+```
+
+Avoid committing real passwords, tokens, or generated secrets. For local examples,
+use environment variables or throwaway development credentials.
+
+## Basic auth and JWT operation tokens
+
+Harper accepts Basic auth for Operations API and secured REST calls:
+
+```bash
+curl -i http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD"
+```
+
+For clients that should not send Basic auth on every request, create JWT tokens
+with `create_authentication_tokens`. This operation is intentionally unauthenticated
+but requires the target username and password:
+
+```bash
+tokens="$(
+  curl -sS http://localhost:9925/ \
+    -H 'Content-Type: application/json' \
+    --data '{
+      "operation": "create_authentication_tokens",
+      "username": "'"$PUBLIC_USERNAME"'",
+      "password": "'"$PUBLIC_PASSWORD"'"
+    }'
+)"
+
+operation_token="$(jq -r '.operation_token' <<<"$tokens")"
+refresh_token="$(jq -r '.refresh_token' <<<"$tokens")"
+```
+
+Use the operation token as a bearer token:
+
+```bash
+curl -i http://localhost:9926/app/orders/ \
+  -H "Authorization: Bearer $operation_token"
+```
+
+Refresh an expired operation token with the refresh token:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $refresh_token" \
+  --data '{"operation": "refresh_operation_token"}'
+```
+
+Treat operation tokens and refresh tokens as credentials. Never log them, commit
+them, paste them into tickets, or store them in browser-accessible app config.
+
+## Exported resources and `context.user`
+
+Exported tables and custom Resources inherit the caller's role permissions.
+If a role cannot read or write the underlying table, Harper should deny the REST
+or GraphQL request before app logic treats it as successful.
+
+Use custom Resource checks when the rule depends on request identity, tenant
+ownership, or business state that is not expressible in `roles.yaml`:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(target, data, context) {
+    const user = context.user;
+    if (!user) {
+      const error = new Error('Authentication required');
+      error.statusCode = 401;
+      throw error;
+    }
+
+    if (user.role !== 'order_admin') {
+      const error = new Error('Forbidden');
+      error.statusCode = 403;
+      throw error;
+    }
+
+    return super.post(target, await data, context);
+  }
+}
+```
+
+Pass `context` through when delegating to tables or other resources:
+
+```javascript
+await tables.OrderEvents.post(
+  target,
+  {
+    orderId,
+    type: 'created',
+    createdBy: context.user?.username,
+  },
+  context,
+);
+```
+
+Guidance:
+
+- Use `roles.yaml` for coarse table/attribute access and Resource logic for
+  request-specific policy.
+- Do not trust client-provided role, user id, tenant id, or permission claims.
+  Read identity from `context.user`.
+- Do not put `context` in module-level state; it belongs to one request.
+- Do not use `requestWithoutAuthentication` for normal application routes. If a
+  webhook must bypass Harper auth, verify its signature first and keep its table
+  writes narrowly scoped.
+
+## Verification matrix
+
+Run the local app, create the test users, and check unauthenticated, reader, and
+admin behavior against the same endpoint:
+
+```bash
+harper dev harper-app
+
+# Unauthenticated request should be denied.
+curl -i http://localhost:9926/app/orders/
+
+# Reader can read.
+curl -i http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD"
+
+# Reader cannot write.
+curl -i -X POST http://localhost:9926/app/orders/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"ord_1","status":"new"}'
+
+# Admin can write.
+curl -i -X POST http://localhost:9926/app/orders/ \
+  -u "$ADMIN_USERNAME:$ADMIN_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"ord_1","status":"new"}'
+```
+
+Expected results:
+
+| Caller | Read | Write |
+| --- | --- | --- |
+| No credentials | `401` or auth denial | `401` or auth denial |
+| `public_reader` | `200` | `403` or permission denial |
+| `order_admin` | `200` | `200` or expected validation response |
+
+Also verify metadata with a restricted user when debugging permissions:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$PUBLIC_USERNAME:$PUBLIC_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"user_info"}'
+```
+
+If the status code is unexpected, check in this order:
+
+1. `config.yaml` still enables `roles`, `rest`, `graphqlSchema`, and `jsResource`.
+2. `roles.yaml` database/table names match the schema.
+3. The user is active and assigned to the intended role.
+4. The route being tested is the exported table/resource path you meant to secure.
+5. Resource code passes `context` through to `super` and nested table calls.
+
+## Sources
+
+- [Users & Roles Configuration](https://docs.harperdb.io/reference/v5/users-and-roles/configuration)
+- [Operations Reference](https://docs.harperdb.io/reference/v5/operations-api/operations)
+- [Components Overview](https://docs.harperdb.io/reference/v5/components/overview)

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

@@ -0,0 +1,265 @@
+---
+name: harper-caching
+description: This skill should be used when implementing Harper (HarperDB/Fabric) caching tables, external-source caches, TTL expiration, stale revalidation, invalidation, and cache verification. Use it when caching an upstream API, database, or expensive computation in Harper instead of hand-rolling in-memory maps. Pairs with harper-resources, harper-schema-graphql, harper-rest-queries, and harper-operations.
+---
+
+# Harper Caching
+
+## Overview
+
+Harper can use a local table as a durable cache for an external source. The table
+stores records, enforces schema/index behavior, exposes normal REST/GraphQL
+routes, and calls the source Resource only when a record is missing, expired, or
+explicitly invalidated.
+
+Use a caching table when the cached data should survive process restarts,
+participate in Harper queries, or stay coherent across Fabric nodes. Do not keep
+API responses in a module-level `Map` unless the data is deliberately
+process-local, disposable, and not part of the application data model.
+
+Cross-check the table declaration in [[harper-schema-graphql]] and the Resource
+method conventions in [[harper-resources]] before editing. If cached records are
+queried by filters, sort keys, or relationships, also align indexes and query
+shape with [[harper-rest-queries]].
+
+## Declare the cache table
+
+Declare a normal `@table` and expose it with `@export` when callers should reach
+the cache over REST or GraphQL. Use the `expiration` argument on `@table` for the
+default time-to-live, in seconds:
+
+```graphql
+type WeatherSnapshot @table(expiration: 300) @export(name: "weather") {
+  locationId: String @primaryKey
+  city: String @indexed
+  temperatureF: Float
+  conditions: String
+  sourceUpdatedAt: Long
+  fetchedAt: Long
+}
+```
+
+Guidance:
+
+- Keep the primary key stable and derived from the upstream identity. For an
+  external REST API, a normalized URL slug, vendor id, or compound key string is
+  usually better than an auto-generated id.
+- Index attributes used by cache reads (`city`, `tenantId`, `category`, `status`)
+  so callers do not fetch broad collections and filter in JavaScript.
+- Store upstream freshness metadata such as `sourceUpdatedAt`, `etag`, or
+  `fetchedAt` when verification, debugging, or conditional revalidation needs it.
+- Keep TTL at the table level unless the upstream response controls freshness per
+  record. Per-record expiration belongs in the source Resource context.
+
+## Wire `sourcedFrom`
+
+Implement a source Resource that fetches the upstream record, then attach it to
+the table with `sourcedFrom`. In Lisa template projects, write TypeScript under
+`src/` and rebuild the generated Harper assets; do not edit `resources.js` by
+hand.
+
+```javascript
+export class WeatherApiSource extends Resource {
+  static loadAsInstance = false;
+
+  async get(target) {
+    const id = target.id;
+    const response = await fetch(
+      `https://api.example.com/weather/${encodeURIComponent(id)}`,
+      {
+        headers: { Accept: 'application/json' },
+      },
+    );
+
+    if (response.status === 404) {
+      const error = new Error(`Weather location not found: ${id}`);
+      error.statusCode = 404;
+      throw error;
+    }
+
+    if (!response.ok) {
+      const error = new Error(`Weather upstream failed: ${response.status}`);
+      error.statusCode = 502;
+      throw error;
+    }
+
+    const data = await response.json();
+
+    return {
+      locationId: id,
+      city: data.city,
+      temperatureF: data.temperatureF,
+      conditions: data.conditions,
+      sourceUpdatedAt: Date.parse(data.updatedAt),
+      fetchedAt: Date.now(),
+    };
+  }
+}
+
+tables.WeatherSnapshot.sourcedFrom(WeatherApiSource);
+```
+
+When a requested record is missing or stale, Harper calls the source `get()` and
+caches the returned record in the local table. Concurrent requests for the same
+missing or stale record share the same upstream load, which avoids a cache
+stampede for a single key.
+
+## TTL and eviction
+
+Use `expiration` for the TTL: after that many seconds, the cached entry is stale
+and the next read reloads it from the source. If a project cannot express the
+default in schema, `sourcedFrom` can also receive options:
+
+```javascript
+tables.WeatherSnapshot.sourcedFrom(WeatherApiSource, {
+  expiration: 300,
+  eviction: 3600,
+  scanInterval: 60,
+});
+```
+
+Option meanings:
+
+| Option | Use |
+| --- | --- |
+| `expiration` | Default TTL in seconds before the cached record is stale. |
+| `eviction` | Seconds after expiration before Harper may physically remove the record. |
+| `scanInterval` | Seconds between scans for expired records. |
+
+Prefer schema directives for stable application behavior because the data model
+and default freshness policy stay together. Use `sourcedFrom` options when the
+cache attachment is intentionally dynamic or the downstream Harper version lacks
+the needed schema directive.
+
+## Conditional revalidation
+
+When the upstream provides `ETag`, `Last-Modified`, or `Cache-Control`, pass that
+freshness model through the source Resource instead of overwriting good cached
+data with every revalidation.
+
+```javascript
+export class WeatherApiSource extends Resource {
+  static loadAsInstance = false;
+
+  async get(target) {
+    const context = this.getContext();
+    const headers = new Headers({ Accept: 'application/json' });
+
+    if (context.replacingVersion) {
+      headers.set(
+        'If-Modified-Since',
+        new Date(context.replacingVersion).toUTCString(),
+      );
+    }
+
+    const response = await fetch(
+      `https://api.example.com/weather/${encodeURIComponent(target.id)}`,
+      { headers },
+    );
+
+    if (response.status === 304) {
+      return context.replacingRecord;
+    }
+
+    const maxAge = response.headers
+      .get('Cache-Control')
+      ?.match(/max-age=(\d+)/)?.[1];
+
+    if (maxAge) {
+      context.expiresAt = Date.now() + Number(maxAge) * 1000;
+    }
+
+    context.lastModified = response.headers.get('Last-Modified');
+    return response.json();
+  }
+}
+```
+
+Use `allowStaleWhileRevalidate(entry, id)` on the cached table when stale data is
+acceptable during refresh:
+
+```javascript
+export class WeatherSnapshot extends tables.WeatherSnapshot {
+  static loadAsInstance = false;
+
+  allowStaleWhileRevalidate(entry, id) {
+    return Date.now() - entry.expiresAt < 60_000;
+  }
+}
+```
+
+Return `false` or omit the method when callers must wait for a fresh value.
+
+## Explicit invalidation
+
+Use invalidation when an admin action, webhook, scheduled refresh, or upstream
+write makes the cached record stale before its TTL.
+
+```javascript
+await tables.WeatherSnapshot.invalidate('nyc');
+```
+
+The next `get()` for that id reloads from the source. If the project Harper
+version or resource shape does not expose `invalidate()`, use an explicit delete
+or overwrite path and document the behavior:
+
+```javascript
+await tables.WeatherSnapshot.delete('nyc');
+await tables.WeatherSnapshot.get('nyc');
+```
+
+For write-through caches, implement `put`, `patch`, or `delete` on the source
+Resource only when those operations should update the upstream system. Otherwise,
+reject writes or keep cache mutation behind an operator-only Resource so clients
+do not accidentally diverge from the source of truth.
+
+## Fabric coherence
+
+In a Fabric deployment, treat every node as capable of serving a read while cache
+state is replicating:
+
+- Keep `get()` deterministic and idempotent. A second node may reload the same
+  stale key.
+- Do not store request-local data, credentials, or tenant state in module-level
+  variables. Read identity from Resource context and pass context through when
+  calling other resources.
+- Pick TTLs that tolerate replication delay. Very short TTLs can turn a cache
+  into repeated upstream traffic across nodes.
+- After invalidation, verify from the route or node that matters for the caller.
+  Cross-node visibility may lag until replication catches up.
+- Use Harper storage reclamation settings for disk-pressure eviction tuning, not
+  as a substitute for application freshness rules.
+
+## Local verification recipe
+
+Prove both cache fill and cache hit behavior against a running Harper app:
+
+1. Add a temporary upstream counter, fixture server log, or test-only header that
+   shows how many times the source Resource fetched the upstream id.
+2. Build and boot the app (`bun run build`, then the project Harper dev command).
+3. Request the same id twice:
+
+```bash
+curl -sS http://localhost:9926/weather/nyc | jq .
+curl -sS http://localhost:9926/weather/nyc | jq .
+```
+
+4. Confirm the upstream was called once, the second response came from the table,
+   and the record contains `fetchedAt` or equivalent freshness evidence.
+5. Invalidate or delete the id, request it again, and confirm the upstream count
+   increments:
+
+```bash
+curl -sS -X DELETE http://localhost:9926/weather/nyc
+curl -sS http://localhost:9926/weather/nyc | jq .
+```
+
+6. If TTL behavior matters, lower `expiration` in a local-only test fixture,
+   wait past the TTL, and verify either blocking refresh or stale-while-revalidate
+   behavior matches the Resource implementation.
+
+## Sources
+
+- [Harper v4 Resource API](https://docs.harperdb.io/reference/v4/resources/resource-api)
+- [Harper v5 Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Harper storage tuning](https://docs.harperdb.io/reference/v5/database/storage-tuning)