@harperfast/template-react-ts-studio 1.12.2 → 1.12.4

package/.agents/skills/harper-best-practices/rules/checking-authentication.md

@@ -7,146 +7,77 @@ metadata:
     - >-
       reference/v5/resources/resource-api.md#`getCurrentUser(): User |
       undefined`
+    - 'reference/v5/resources/resource-api.md#`getContext(): Context`'
     - reference/v5/resources/resource-api.md#Session and Login from a Resource
-    - reference/v5/security/jwt-authentication.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: fdd9ec3b11011490
+    - reference/v5/security/jwt-authentication.md#Create Authentication Tokens
+    - reference/v5/security/jwt-authentication.md#Using the Operation Token
+    - reference/v5/security/jwt-authentication.md#Refreshing the Operation Token
+    - reference/v5/security/jwt-authentication.md#Scoped Tokens (Inline Role)
+    - >-
+      reference/v5/security/jwt-authentication.md#Issuing Tokens from a Custom
+      Resource
+    - reference/v5/security/jwt-authentication.md#Token Expiry Configuration
+    - reference/v5/security/jwt-authentication.md#When to Use JWT Auth
+    - reference/v5/security/jwt-authentication.md#Security Notes
+  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
+  inputHash: 1837f39fdfe06fac
 ---
 
 # Checking Authentication
 
-Instructions for the agent to follow when handling user authentication and session management inside Harper Resources.
+Instructions for the agent to handle user authentication, sessions, and JWT token issuance in Harper Resources.
 
 ## When to Use
 
-Apply this rule when implementing authentication checks, login/logout flows, or token issuance inside a custom Resource. Use it any time a Resource needs to identify the current user, establish a session, or issue JWTs to clients. See [custom-resources.md](custom-resources.md) for the general Resource authoring pattern.
+Apply this rule when implementing login/logout flows, reading the current authenticated user, issuing or refreshing JWT tokens, or minting scoped tokens from a custom Resource. Use it whenever a Resource must gate behavior on identity or credentials. See [custom-resources.md](custom-resources.md) for the broader Resource authoring model.
 
 ## How It Works
 
-1. **Check the current user** with `getCurrentUser()`. Call it inside any Resource method to retrieve the authenticated user or `undefined` if no user is authenticated. Guard protected endpoints by returning a `401` when the result is `undefined`.
-
-   ```javascript
-   async get(target) {
-     const user = this.getCurrentUser();
-     if (!user) return new Response(null, { status: 401 });
-     return { username: user.username, role: user.role };
-   }
-   ```
-
-   The returned object exposes `username`, `role`, and `role.permission` flags.
-
-2. **Enable sessions** before using session-based login. Set `authentication.enableSessions: true` in `harperdb-config.yaml`:
-
-   ```yaml
-   authentication:
-     enableSessions: true
-   ```
-
-3. **Access login and session helpers** via `getContext()`. The context object exposes `context.login` and `context.session` for sign-in/out flows.
-   - Call `context.login(username, password)` to verify credentials and establish a session cookie on success.
-   - To end a session, delete it via `context.session.delete(context.session.id)`.
-
-4. **Implement sign-in and sign-out Resources** using the context helpers:
-
-   ```javascript
-   export class SignIn extends Resource {
-   	async post(_target, data) {
-   		const context = this.getContext();
-   		try {
-   			await context.login(data.username, data.password);
-   		} catch {
-   			return new Response('Invalid credentials', { status: 403 });
-   		}
-   		return new Response('Logged in', { status: 200 });
-   	}
-   }
-
-   export class SignOut extends Resource {
-   	async post() {
-   		const context = this.getContext();
-   		if (!context.session) return new Response(null, { status: 401 });
-   		await context.session.delete(context.session.id);
-   		return new Response('Logged out', { status: 200 });
-   	}
-   }
-   ```
-
-5. **Issue JWTs for non-browser clients** (CLI tools, mobile apps, service-to-service). Cookie-based sessions are intended for browser clients. For other clients, mint tokens programmatically using `server.operation()`:
-
-   ```javascript
-   import { Resource, server } from 'harper';
-
-   export class IssueTokens extends Resource {
-   	static async get(_target, context) {
-   		const { operation_token, refresh_token } = await server.operation(
-   			{ operation: 'create_authentication_tokens' },
-   			context,
-   			true,
-   		);
-   		return { operation_token, refresh_token };
-   	}
-
-   	static async post(_target, data) {
-   		const { username, password } = await data;
-   		if (!username || !password) {
-   			return new Response('username and password required', { status: 400 });
-   		}
-   		const { operation_token, refresh_token } = await server.operation({
-   			operation: 'create_authentication_tokens',
-   			username,
-   			password,
-   		});
-   		return { operation_token, refresh_token };
-   	}
-   }
-
-   export class RefreshJWT extends Resource {
-   	static async post(_target, data) {
-   		const { refresh_token } = await data;
-   		if (!refresh_token) {
-   			return new Response('refresh_token required', { status: 400 });
-   		}
-   		const { operation_token } = await server.operation({
-   			operation: 'refresh_operation_token',
-   			refresh_token,
-   		});
-   		return { operation_token };
-   	}
-   }
-   ```
-
-   Pass `true` as the third argument to `server.operation()` when the operation should run as the current authenticated user. Omit it or pass `false` when the operation supplies its own credentials.
-
-6. **Configure JWT token expiry** in `harperdb-config.yaml` under the `authentication` section:
-
-   ```yaml
-   authentication:
-     operationTokenTimeout: 1d
-     refreshTokenTimeout: 30d
-   ```
-
-   Duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`).
+### 1. Reading the Current Authenticated User
 
-## Examples
+**In an instance method**, call `getCurrentUser()` to get the user associated with the current request, or `undefined` if unauthenticated. The returned object exposes `username`, `role`, and `role.permission` flags.
 
-**Protecting a resource endpoint and returning user info:**
+**In a static verb**, read the user from the `context` argument instead — `context.user`:
 
 ```javascript
-async get(target) {
-  const user = this.getCurrentUser();
-  if (!user) return new Response(null, { status: 401 });
-  return { username: user.username, role: user.role };
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
 }
 ```
 
-**Full session-based sign-in/sign-out flow:**
+### 2. Reading the Full Context
+
+**In an instance method**, call `getContext()` to retrieve the current context, which includes:
+
+- `user` — User object with username, role, and authorization information
+- `transaction` — The current transaction
+
+**In a static verb**, the context is the trailing argument:
+
+- `(target, context)` for `get`/`delete`
+- `(target, data, context)` for `put`/`patch`/`post`
+
+When triggered by HTTP, the context also exposes `url`, `method`, `headers`, `responseHeaders`, `pathname`, `host`, `ip`, `body`, `data`, `lastModified`, and `requestContext`.
+
+### 3. Handling Sessions and Login
+
+Enable sessions in `harper-config.yaml`:
+
+```yaml
+authentication:
+  enableSessions: true
+```
+
+Use `context.login` in a static `post` verb to verify credentials and establish a session cookie:
 
 ```javascript
 export class SignIn extends Resource {
-	async post(_target, data) {
-		const context = this.getContext();
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
 		try {
-			await context.login(data.username, data.password);
+			await context.login(username, password);
 		} catch {
 			return new Response('Invalid credentials', { status: 403 });
 		}
@@ -155,18 +86,161 @@ export class SignIn extends Resource {
 }
 
 export class SignOut extends Resource {
-	async post() {
-		const context = this.getContext();
-		if (!context.session) return new Response(null, { status: 401 });
-		await context.session.delete(context.session.id);
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
 		return new Response('Logged out', { status: 200 });
 	}
 }
 ```
 
-**JWT token refresh endpoint:**
+- `context.login(username, password)` verifies credentials and sets the session cookie on success.
+- To end a session, call `context.session.update({ user: null })` — `update` is the session's only mutator.
+- `context.session` is an empty object (not `undefined`) when sessions are enabled and no session cookie is present; test `context?.session?.user` to detect an established session.
+- Cookie-based sessions are for browser clients. For non-browser clients, use JWT issuance.
+
+### 4. Creating Authentication Tokens
+
+Call `create_authentication_tokens` with credentials in the body — no `Authorization` header is required when `username` and `password` are supplied:
+
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "username",
+	"password": "password"
+}
+```
+
+Response:
+
+```json
+{
+	"operation_token": "<jwt-operation-token>",
+	"refresh_token": "<jwt-refresh-token>"
+}
+```
+
+Pass the `operation_token` as a `Bearer` token on subsequent requests:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <operation_token>' \
+  --data-raw '{
+      "operation": "search_by_hash",
+      "schema": "dev",
+      "table": "dog",
+      "hash_values": [1],
+      "get_attributes": ["*"]
+  }'
+```
+
+### 5. Refreshing the Operation Token
+
+When the `operation_token` expires, pass the `refresh_token` as `Bearer <refresh_token>` and call `refresh_operation_token`:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <refresh_token>' \
+  --data-raw '{
+    "operation": "refresh_operation_token"
+  }'
+```
+
+Response:
+
+```json
+{
+	"operation_token": "<new-jwt-operation-token>"
+}
+```
+
+When both tokens have expired, call `create_authentication_tokens` again with username and password.
+
+### 6. Minting Scoped Tokens
+
+A `super_user` can mint a scoped token with embedded permissions using `create_authentication_tokens` with an inline `role`. The minter must be authenticated; no `password` may be included in the body. Use `add_role`-style `permission` structure:
+
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "reporting-service",
+	"role": {
+		"permission": {
+			"operations": ["read_only"],
+			"dev": {
+				"tables": {
+					"dog": {
+						"read": true,
+						"insert": false,
+						"update": false,
+						"delete": false,
+						"attribute_permissions": []
+					}
+				}
+			}
+		}
+	},
+	"expires_in": "7d"
+}
+```
+
+Authenticate the mint request with Basic Authentication or an existing `super_user` `operation_token`:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Basic <base64 of super_user:password>' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "reporting-service",
+      "role": { "permission": { "operations": ["read_only"] } },
+      "expires_in": "7d"
+  }'
+```
+
+Key constraints for scoped tokens:
+
+- `username` is attribution only and must not name an existing user.
+- No refresh token is issued; no user record is created.
+- Scoped tokens cannot be revoked before expiry — choose `expires_in` carefully and prefer short lifetimes.
+- `super_user` and `cluster_user` are always forced to `false` in the embedded role.
+- In **mixed-version** clusters, only nodes with scoped-token support accept these tokens; older nodes reject them with 401.
+
+### 7. Issuing Tokens from a Custom Resource
+
+Use `server.operation()` to mint tokens programmatically inside a Resource. Pass `authorize: true` as the **third argument** when the operation should run as the current authenticated user:
 
 ```javascript
+import { Resource, server } from 'harper';
+
+export class IssueTokens extends Resource {
+	static async get(_target, context) {
+		// Issue tokens for the current authenticated user
+		const { operation_token, refresh_token } = await server.operation(
+			{ operation: 'create_authentication_tokens' },
+			context,
+			true, // third argument: authorize as current user
+		);
+		return { operation_token, refresh_token };
+	}
+
+	static async post(_target, data) {
+		// Issue tokens from credentials supplied in the body
+		const { username, password } = await data;
+		if (!username || !password) {
+			return new Response('username and password required', { status: 400 });
+		}
+		const { operation_token, refresh_token } = await server.operation({
+			operation: 'create_authentication_tokens',
+			username,
+			password,
+		});
+		return { operation_token, refresh_token };
+	}
+}
+
 export class RefreshJWT extends Resource {
 	static async post(_target, data) {
 		const { refresh_token } = await data;
@@ -182,9 +256,73 @@ export class RefreshJWT extends Resource {
 }
 ```
 
+Omit the third argument (or pass `false`) when the operation supplies its own credentials.
+
+### 8. Configuring Token Expiry
+
+Set timeouts in `harper-config.yaml` under the `authentication` section:
+
+```yaml
+authentication:
+  operationTokenTimeout: 1d # Default: 1 day
+  refreshTokenTimeout: 30d # Default: 30 days
+```
+
+Valid duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`). The `expires_in` field on scoped token minting accepts the same format.
+
+## Examples
+
+### Full Sign-In / Sign-Out Resource
+
+```javascript
+export class SignIn extends Resource {
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
+		try {
+			await context.login(username, password);
+		} catch {
+			return new Response('Invalid credentials', { status: 403 });
+		}
+		return new Response('Logged in', { status: 200 });
+	}
+}
+
+export class SignOut extends Resource {
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
+		return new Response('Logged out', { status: 200 });
+	}
+}
+```
+
+### Reading the Current Authenticated User in a Static Verb
+
+```javascript
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
+}
+```
+
+### Minting Tokens via cURL
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "username",
+      "password": "password"
+  }'
+```
+
 ## Notes
 
-- `getCurrentUser()` and `getContext()` are instance methods; call them with `this` inside non-static Resource methods.
-- `enableSessions` must be `true` in config before `context.login` or `context.session` will function.
-- Cookie-based sessions target browser clients. Use JWT issuance via `server.operation()` for all other client types.
-- When both `operation_token` and `refresh_token` have expired, the client must call `create_authentication_tokens` again with credentials.
+- JWT authentication is **preferred over Basic Auth** when you want to avoid sending credentials on every request, your client can store tokens, or you have multiple sequential requests. For simple or **server-to-server** scenarios, use **Basic Authentication**.
+- Always use **HTTPS** in production to protect tokens in transit.
+- Treat tokens like passwords. If a token is compromised, it remains valid until expiry — use shorter `operationTokenTimeout` values in high-security environments.
+- `context.login` and `context.session` require `enableSessions: true` in `harperdb-config.yaml`; they are for browser clients only.
+- The `server.operation()` third argument (`authorize: true`) attributes the operation to — and permission-checks against — the current authenticated user. Omit it when supplying credentials directly in the operation body.
+- In **mixed-version** clusters, scoped tokens are only accepted by nodes that support them; older nodes return 401.

package/.agents/skills/harper-best-practices/rules/custom-resources.md

@@ -6,9 +6,9 @@ metadata:
   sources:
     - reference/v5/resources/overview.md#Custom External Data Source
     - reference/v5/resources/overview.md#Exporting Resources as Endpoints
-    - reference/v5/components/javascript-environment.md#Module Loading
-  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
-  inputHash: df69870433c0b3e5
+    - reference/v5/components/javascript-environment.md#Module Formats
+  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
+  inputHash: 86858206e33925f0
 ---
 
 # Custom Resources
@@ -17,11 +17,11 @@ Instructions for the agent to follow when defining custom REST endpoints with Ja
 
 ## When to Use
 
-Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed resource or when a specific URL shape is required.
 
 ## How It Works
 
-1. **Import `Resource` from `harper`**: Always import from the `harper` package rather than relying on globals.
+1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
 
    ```javascript
    import { tables, Resource } from 'harper';
@@ -39,7 +39,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-3. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
+3. **Use `async` static methods to call external services**: Return or forward the response directly.
 
    ```javascript
    export class MyExternalData extends Resource {
@@ -57,7 +57,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+4. **Export the class to expose it as an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
 
    | Export form                                 | URL             | Notes                                                           |
    | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
@@ -68,12 +68,17 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
    | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
 
-   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
 
-5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+   ```javascript
+   server.resources.set('my-path', Foo);
+   ```
+
+6. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
 
    ```javascript
    export class Widget extends Resource {
+   	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
    	static path = '/widget/:id/action/:action';
    	static get(target) {
    		return { id: target.id, action: target.action };
@@ -81,22 +86,11 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
-
-6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
-
-   ```javascript
-   server.resources.set('my-path', Foo);
-   ```
-
-7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
-   ```javascript
-   tables.MyCache.sourcedFrom(MyExternalData);
-   ```
+7. **Resolve path precedence correctly**: Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats a `:param`, which beats a `*` wildcard, compared left to right.
 
 ## Examples
 
-### External API wrapper with GET and PUT
+**Wrapping an external API and using it as a cache source:**
 
 ```javascript
 import { tables, Resource } from 'harper';
@@ -119,19 +113,9 @@ export class MyExternalData extends Resource {
 tables.MyCache.sourcedFrom(MyExternalData);
 ```
 
-### Path parameters with `static path`
+**Catch-all wildcard path:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Widget extends Resource {
-	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
-	static path = '/widget/:id/action/:action';
-	static get(target) {
-		return { id: target.id, action: target.action };
-	}
-}
-
 export class Files extends Resource {
 	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
 	static path = '/files/*rest';
@@ -141,25 +125,24 @@ export class Files extends Resource {
 }
 ```
 
-### Programmatic registration
+**Root-relative fixed route:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Foo extends Resource {
+export class AcmeChallenge extends Resource {
+	static path = '/.well-known/acme-challenge/:token';
 	static get(target) {
-		return { data: doSomething() };
+		return { token: target.token };
 	}
 }
-
-server.resources.set('my-path', Foo);
 ```
 
 ## Notes
 
-- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
-- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
-- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
-- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+- A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
+- A leading `./` or a bare name in `static path` resolves relative to the component directory.
+- A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- `static path` takes precedence over the export name when both are present.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as URI templates.
+- When a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
 - Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
-- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.