@codyswann/lisa 2.168.0 → 2.170.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-operations/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: harper-operations
+description: This skill should be used when operating, monitoring, or debugging a Harper (HarperDB/Fabric) component after it builds or deploys - Operations API calls, component inventory, log retrieval, health checks, job lookup, local 500 debugging, and escalation boundaries. Pairs with harper-build-and-deploy, harper-config-yaml, harper-resources, and harper-rest-queries.
+---
+
+# Harper Operations
+
+## Overview
+
+Use Harper's Operations API when the app built or deployed but runtime behavior is
+unknown: a REST endpoint returns 500, a component did not load, logs show worker
+errors, a table shape differs from the expected schema, or a deploy job needs to be
+checked. The Operations API is the administrative surface; application REST
+endpoints are the user-facing data/resource surface.
+
+Cross-check deploy packaging and Fabric topology in [[harper-build-and-deploy]].
+Cross-check active extensions and config replacement behavior in
+[[harper-config-yaml]]. Cross-check custom Resource method ownership in
+[[harper-resources]] and query shape in [[harper-rest-queries]].
+
+## Endpoint, auth, and request shape
+
+Operations API requests are JSON `POST` requests to the operations endpoint. Harper
+listens on port `9925` at the root path by default:
+
+```bash
+curl -sS http://<harper-host>:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"system_information"}'
+```
+
+For local development:
+
+```bash
+curl -sS http://localhost:9925/ \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{"operation":"get_components"}'
+```
+
+Authentication options:
+
+- Basic auth: `Authorization: Basic ...`, or `curl -u "$USER:$PASS"`.
+- JWT operation token: `Authorization: Bearer <token>` from
+  `create_authentication_tokens`.
+- CLI: `harper login <target>` for persistent remote auth, or environment
+  credentials such as `HARPER_CLI_USERNAME` / `HARPER_CLI_PASSWORD`.
+
+Most operational reads require a `super_user` or a role explicitly allowed to run
+the named operation. If an operation is denied, check role `operations` permissions
+before assuming the endpoint or component is broken.
+
+## High-value operations
+
+| Operation | Use it for | Example |
+| --- | --- | --- |
+| `get_components` | Confirm component names, files, and configuration loaded from `harper-config.yaml`. | `{"operation":"get_components"}` |
+| `describe_all` | See all database/table definitions and record counts visible to the caller. | `{"operation":"describe_all"}` |
+| `describe_table` | Confirm table/database names, attributes, and primary key shape. | `{"operation":"describe_table","database":"data","table":"Product"}` |
+| `system_information` | Capture runtime, host, and process information for health/debug reports. | `{"operation":"system_information"}` |
+| `read_log` | Read Harper's primary `hdb.log` with level/time/filter controls. | `{"operation":"read_log","level":"error","limit":50,"order":"desc"}` |
+| `search_jobs_by_start_date` | Find background jobs when deploys, imports, or long operations are involved. | `{"operation":"search_jobs_by_start_date","from_date":"2026-06-16T00:00:00.000+0000","to_date":"2026-06-17T00:00:00.000+0000"}` |
+| `get_job` | Inspect one known job id returned by a search or operation response. | `{"operation":"get_job","id":"<job-id>"}` |
+| `get_configuration` | Find runtime paths such as `rootPath`, `componentsRoot`, ports, and logging config. | `{"operation":"get_configuration"}` |
+
+Use CLI shortcuts when the operation only needs flat key/value arguments:
+
+```bash
+harper get_components target="$HARPER_TARGET" json=true
+harper describe_all target="$HARPER_TARGET" json=true
+harper read_log target="$HARPER_TARGET" level=error limit=50 order=desc json=true
+```
+
+If the CLI cannot represent the nested request body, use `curl` against the
+Operations API directly.
+
+## Reading logs
+
+`read_log` reads the primary Harper log (`hdb.log`) and is restricted to
+`super_user` roles unless a custom role grants it. Useful parameters include
+`level`, `from`, `until`, `limit`, `order`, and `filter`.
+
+Recent errors:
+
+```bash
+curl -sS "$HARPER_TARGET" \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "read_log",
+    "level": "error",
+    "limit": 50,
+    "order": "desc"
+  }'
+```
+
+Filter by component, route, or correlation id:
+
+```bash
+curl -sS "$HARPER_TARGET" \
+  -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "operation": "read_log",
+    "filter": "orders",
+    "from": "2026-06-16 00:00:00",
+    "limit": 100,
+    "order": "desc"
+  }'
+```
+
+In local `harper dev`, also watch the terminal output. The dev command restarts
+worker threads on file changes and prints console/log output close to the failing
+request. Use `harper run` or a deployed local instance when you need to restart the
+main thread, not only workers.
+
+## Logging from Resources
+
+For Resource methods, log enough to identify the request path, authenticated user
+or tenant id, and failing branch without emitting secrets or whole request bodies.
+Prefer structured, searchable messages:
+
+```javascript
+export class Orders extends tables.Orders {
+  static async post(data, context) {
+    const input = await data;
+    console.info('orders.post received', {
+      orderId: input.id,
+      userId: context.user?.id,
+    });
+
+    try {
+      return await super.post(input, context);
+    } catch (error) {
+      console.error('orders.post failed', {
+        orderId: input.id,
+        message: error?.message,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+Guidance:
+
+- Use `console.info` or `console.debug` for normal trace points, and
+  `console.warn` / `console.error` for actionable failures.
+- Never log passwords, tokens, cookies, API keys, raw Authorization headers, or
+  full personal data payloads.
+- Include a request id or deterministic entity id when the caller can provide one.
+- Remove noisy temporary logs once the root cause is fixed, or lower them to debug.
+
+## Debugging a 500 endpoint
+
+When a deployed REST endpoint returns 500, follow this path before changing code:
+
+1. Identify the exact endpoint, method, payload, authenticated user, target URL,
+   and timestamp. Save a reproducible `curl` command with headers scrubbed.
+2. Confirm the component is installed and named as expected:
+
+   ```bash
+   harper get_components target="$HARPER_TARGET" json=true
+   ```
+
+3. Read recent errors around the failing timestamp:
+
+   ```bash
+   harper read_log target="$HARPER_TARGET" level=error limit=100 order=desc json=true
+   ```
+
+4. Check table/resource shape when the failure mentions a missing table, attribute,
+   index, relationship, or schema directive:
+
+   ```bash
+   curl -sS "$HARPER_TARGET" \
+     -u "$HARPER_USERNAME:$HARPER_PASSWORD" \
+     -H 'Content-Type: application/json' \
+     --data '{"operation":"describe_all"}'
+   ```
+
+5. Reproduce locally with the same built artifact path:
+
+   ```bash
+   bun run build
+   harper dev harper-app
+   curl -i http://localhost:9926/<project>/<resource-path>
+   ```
+
+6. Isolate the smallest Resource method or table call involved. If the route uses a
+   custom Resource, call its underlying table/search operation directly when safe,
+   then add one temporary log at the branch boundary that chooses the failing path.
+7. Fix source files, not generated deploy artifacts. Rebuild and repeat the same
+   local `curl`, then repeat the deployed smoke path after redeploy.
+
+Treat the incident as unresolved until the same request path returns the expected
+status and the logs no longer show the error.
+
+## Health and deploy checks
+
+After deploy or restart, check:
+
+- Component inventory: `get_components` includes the expected project and files.
+- System/runtime info: `system_information` returns from the target node.
+- Configuration: `get_configuration` shows the expected operations/API ports,
+  `rootPath`, `componentsRoot`, and logging configuration.
+- Schema/data shape: `describe_all` or `describe_table` matches the expected
+  database/table definitions and exported tables.
+- Logs: `read_log` has no new error entries for the deploy/restart window.
+- Jobs: `search_jobs_by_start_date` and `get_job` show background work completed
+  when deploy, import, backup, or long-running data operations were involved.
+- Public smoke: the project-specific HTTP smoke command passes from the same route
+  users will hit. For Fabric, verify through the public route and any direct
+  node/region route the project exposes.
+
+## What is not available
+
+Do not invent observability that the target does not expose:
+
+- If there is no Fabric credential or operations role, you cannot prove remote
+  component state; ask for credentials or a trusted operator readback.
+- If the app does not emit a request id, logs may not be attributable to one HTTP
+  request. Reproduce in a narrow time window or add a safe correlation id first.
+- If a Fabric project hides direct node/region URLs, verify through the public
+  route and record that node-level proof is unavailable.
+- If Harper returns an auth/permission denial for `read_log`,
+  `system_information`, or component operations, treat it as an access blocker,
+  not as evidence that logs or components are empty.
+- Third-party APM, trace collection, and performance tuning are outside this
+  skill. Capture Harper-native facts first, then escalate to the project's
+  runbook or platform owner.
+
+## Sources
+
+- [Operations API Overview](https://docs.harperdb.io/reference/v5/operations-api/overview)
+- [Operations Reference](https://docs.harperdb.io/reference/v5/operations-api/operations)
+- [Logging Operations](https://docs.harperdb.io/reference/v5/logging/operations)
+- [Applications / Component Operations](https://docs.harperdb.io/reference/v5/components/applications)