@harperfast/template-react-ts-studio 1.12.3 → 1.12.5

package/.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md

@@ -19,14 +19,14 @@ Use this skill when you need to define new data structures or modify existing on
 2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
 4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
-   - `GET /{TableName}`: Describes the schema itself.
+   - `GET /{TableName}`: Describes the resource itself — table, database, and declared attributes. No trailing slash.
    - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
-   - `GET /{TableName}/{id}`: Retrieves a single record by its ID.
-   - `POST /{TableName}/`: Creates a new record.
-   - `PUT /{TableName}/{id}`: Updates an existing record.
-   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
-   - `DELETE /{TableName}/`: Deletes all records or filtered records.
-   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
+   - `GET /{TableName}/{id}`: Retrieves a single record by its primary key.
+   - `POST /{TableName}/`: Creates a record and returns `201` with the Harper-assigned primary key in the `Location` response header (the bare key, not a URL). **The trailing slash is required** — `POST /{TableName}` returns `404`, and `POST /{TableName}/{id}` returns `405`.
+   - `PUT /{TableName}/{id}`: Creates **or replaces** the record at `{id}` (upsert). **Properties omitted from the body are removed** — send the complete record, or use `PATCH` to change a subset. Three exceptions survive the replacement: an `@updatedTime` attribute is re-stamped with the time of the write, a `@createdTime` attribute keeps its original value, and the primary key is forced to match the `{id}` in the URL, so a mismatched key in the body cannot create a second record.
+   - `PATCH /{TableName}/{id}`: Merges the request body into the existing record, preserving unspecified properties. The merge is **shallow** — a nested object in the body replaces the stored one wholesale rather than being deep-merged.
+   - `DELETE /{TableName}/{id}`: Deletes a single record by its primary key.
+   - `DELETE /{TableName}/`: Deletes every record matching the query parameters. **With no query parameters it matches — and deletes — every record in the table.** Always pass a filter unless emptying the table is the intent.
 5. **Consider Table Extensions**: If you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema.
 
 ## Examples

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

@@ -7,6 +7,7 @@ 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#Create Authentication Tokens
     - reference/v5/security/jwt-authentication.md#Using the Operation Token
@@ -18,8 +19,8 @@ metadata:
     - 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: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: 084363f039abfe73
+  sourceCommit: 9e6ecf87dd25bb488ad44dc2876ca6439ccd682e
+  inputHash: 1837f39fdfe06fac
 ---
 
 # Checking Authentication
@@ -28,207 +29,100 @@ Instructions for the agent to handle user authentication, sessions, and JWT toke
 
 ## When to Use
 
-Apply this rule when implementing login/logout flows, protecting Resource endpoints by checking the current user, issuing or refreshing JWT tokens, or configuring token expiry in Harper. Use it whenever a custom Resource needs to authenticate callers or mint credentials for downstream consumers. See [custom-resources.md](custom-resources.md) for the broader Resource authoring context.
+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 authenticated user**: Call `getCurrentUser()` inside any Resource method. It returns the user object (with `username`, `role`, and `role.permission`) or `undefined` if unauthenticated. Guard endpoints by returning a 401 when no user is present.
-
-   ```javascript
-   async get(target) {
-     const user = this.getCurrentUser();
-     if (!user) return new Response(null, { status: 401 });
-     return { username: user.username, role: user.role };
-   }
-   ```
-
-2. **Enable sessions before using login/logout**: Set `authentication.enableSessions: true` in `harperdb-config.yaml`. Without this, `context.login` and `context.session` are unavailable.
-
-3. **Implement login via `getContext()`**: Call `this.getContext()` to obtain the request context, then call `context.login(username, password)` to verify credentials and establish a session cookie.
-
-   ```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 });
-   	}
-   }
-   ```
-
-4. **Implement logout**: Delete the session via `context.session.delete(context.session.id)`.
-
-   ```javascript
-   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 });
-   	}
-   }
-   ```
-
-   Cookie-based sessions are intended for browser clients. For non-browser clients, use JWT issuance (steps below).
-
-5. **Create authentication tokens**: Call `create_authentication_tokens` with credentials. No `Authorization` header is required for this operation.
-
-   ```json
-   {
-   	"operation": "create_authentication_tokens",
-   	"username": "username",
-   	"password": "password"
-   }
-   ```
-
-   Response:
-
-   ```json
-   {
-   	"operation_token": "<jwt-operation-token>",
-   	"refresh_token": "<jwt-refresh-token>"
-   }
-   ```
-
-6. **Use the operation token**: Pass it as a `Bearer` token in the `Authorization` header 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": ["*"]
-     }'
-   ```
-
-7. **Refresh an expired operation token**: When the `operation_token` expires, use `refresh_operation_token` and pass the `refresh_token` as `Bearer <refresh_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.
-
-8. **Mint scoped tokens for limited access**: A super user can embed an inline role in `create_authentication_tokens` using the same `permission` structure as `add_role`. Include `expires_in` to control lifetime. Do not include a `password` field. The `username` is attribution only and must not match an existing user.
-
-   ```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"
-   }
-   ```
-
-   Key constraints for scoped tokens:
-   - No refresh token is issued; no user record is created.
-   - Scoped tokens cannot be revoked before expiry — choose short `expires_in` values.
-   - `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 return 401.
-
-9. **Issue tokens from a custom Resource using `server.operation`**: Import `server` from `harper` and call `server.operation()` to mint tokens programmatically. Pass `true` as the **third argument** to run the operation as the current authenticated user; omit it when supplying credentials directly.
-
-   ```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 };
-   	}
-   }
-   ```
-
-10. **Configure token expiry**: Set timeouts in `harper-config.yaml` under the `authentication` section. Values follow the `jsonwebtoken` duration string format (e.g., `1d`, `12h`, `60m`).
-
-    ```yaml
-    authentication:
-      operationTokenTimeout: 1d # Default: 1 day
-      refreshTokenTimeout: 30d # Default: 30 days
-    ```
+### 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.
 
-### Full JWT flow via cURL
+**In a static verb**, read the user from the `context` argument instead — `context.user`:
 
-```bash
-# Step 1: Create tokens
-curl --location --request POST 'http://localhost:9925' \
-  --header 'Content-Type: application/json' \
-  --data-raw '{
-      "operation": "create_authentication_tokens",
-      "username": "username",
-      "password": "password"
-  }'
+```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 };
+}
+```
+
+### 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 {
+	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 });
+	}
+}
+```
+
+- `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:
 
-# Step 2: Use operation token
+```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>' \
@@ -239,8 +133,13 @@ curl --location --request POST 'http://localhost:9925' \
       "hash_values": [1],
       "get_attributes": ["*"]
   }'
+```
+
+### 5. Refreshing the Operation Token
 
-# Step 3: Refresh when operation token expires
+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>' \
@@ -249,14 +148,138 @@ curl --location --request POST 'http://localhost:9925' \
   }'
 ```
 
-### Session-based login/logout Resource
+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;
+		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 };
+	}
+}
+```
+
+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 {
-	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 });
 		}
@@ -265,20 +288,41 @@ 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 });
 	}
 }
 ```
 
+### 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
 
-- JWT authentication is **preferred over Basic Auth** when you want to avoid sending credentials on every request, when the client can store tokens, or when making multiple sequential requests. For simple or server-to-server scenarios, use Basic Authentication.
+- 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.
-- `enableSessions` must be `true` in config before `context.login` or `context.session` will work.
-- The `third argument` (`true`) to `server.operation` controls whether the operation runs as the current authenticated user. Omit it when the operation body supplies its own credentials.
-- Scoped tokens have a 12KB limit when encoded into an `Authorization` header.
+- `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.