@harperfast/template-react-ts-studio 0.10.0 → 0.12.0

package/AGENTS.md

@@ -4,7 +4,7 @@ This repository contains "skills" that guide AI agents in developing Harper appl
 
 ## Available Skills
 
-- [Adding Tables](skills/adding-tables.md): Learn how to define schemas and enable automatic REST APIs for your database tables.
+- [Adding Tables with Schemas](skills/adding-tables-with-schemas.md): Learn how to define schemas and enable automatic REST APIs for your database tables with schema .graphql files in Harper.
 - [Automatic REST APIs](skills/automatic-rest-apis.md): Details on the CRUD endpoints automatically generated for exported tables.
 - [Querying REST APIs](skills/querying-rest-apis.md): How to use filters, operators, sorting, and pagination in REST requests.
 - [Programmatic Table Requests](skills/programmatic-table-requests.md): How to use filters, operators, sorting, and pagination in programmatic table requests.
@@ -15,4 +15,4 @@ This repository contains "skills" that guide AI agents in developing Harper appl
 - [TypeScript Type Stripping](skills/typescript-type-stripping.md): Using TypeScript directly without build tools via Node.js Type Stripping.
 - [Handling Binary Data](skills/handling-binary-data.md): How to store and serve binary data like images or MP3s.
 - [Serving Web Content](skills/serving-web-content): Two ways to serve web content from a Harper application.
-- [Checking Authentication](skills/checking-authentication.md): How to use `this.getCurrentUser()` to verify user identity and roles.
+- [Checking Authentication](skills/checking-authentication.md): How to use sessions to verify user identity and roles.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-react-ts-studio",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/resources/README.md

@@ -0,0 +1,11 @@
+# Resources
+
+The [schemas you define in .GraphQL files](../skills/adding-tables-with-schemas.md) will [automatically stand-up REST APIs](../skills/automatic-rest-apis.md).
+
+But you can [extend your tables with custom logic](../skills/extending-tables.md) and [create your own resources](../skills/custom-resources.md) in this directory.
+
+## Want to read more?
+
+Check out the rest of the "skills" documentation!
+
+[AGENTS.md](../AGENTS.md)

package/schemas/README.md

@@ -0,0 +1,11 @@
+# Schemas
+
+Your schemas are defined in `.graphql` files within this `schemas` directory. These files contain the structure and types for your database tables, allowing Harper to automatically generate REST APIs for CRUD operations.
+
+Take a look at the [Adding Tables with Schemas](../skills/adding-tables-with-schemas.md) to learn more!
+
+## Want to read more?
+
+Check out the rest of the "skills" documentation!
+
+[AGENTS.md](../AGENTS.md)

package/skills/checking-authentication.md

@@ -1,52 +1,186 @@
-# Checking Authentication in HarperDB
+# Checking Authentication and Sessions in this app (HarperDB Resources)
 
-Custom resources and table resource overrides often need to restrict access based on the current user's identity or role. HarperDB provides the `this.getCurrentUser()` method within resource classes to access information about the authenticated user making the request.
+This project uses HarperDB Resource classes with cookie-backed sessions to enforce authentication and authorization. Below are the concrete patterns used across resources like `resources/me.ts`, `resources/signIn.ts`, `resources/signOut.ts`, and protected endpoints such as `resources/downloadAlbumArtwork.ts`.
 
-## Using `this.getCurrentUser()`
+Important: To actually enforce sessions (even on localhost), HarperDB must not auto-authorize the local loopback as the superuser. Ensure the following in your HarperDB config (see `~/hdb/harperdb-config.yaml`):
 
-The `this.getCurrentUser()` method returns an object containing details about the authenticated user, such as their username and role. If the request is unauthenticated, it may return `null` or `undefined`.
+```yaml
+authentication:
+  authorizeLocal: false
+  enableSessions: true
+```
 
-### Example: Role-Based Access Control
+With `authorizeLocal: true`, all local requests would be auto-authorized as the superuser, bypassing these checks. We keep it off to ensure session checks are respected.
 
-You can check the user's role to determine if they have permission to perform a specific action.
+## Public vs protected routes
 
-```typescript
-import { RequestTargetOrId, Resource } from 'harperdb';
+- Public resources explicitly allow the method via `allowRead()` or `allowCreate()` or similara returning `true`.
+- Protected handlers perform checks up-front using the current session user (and, for privileged actions, a helper like `ensureSuperUser`).
 
-export class MyResource extends Resource {
-	async post(target: RequestTargetOrId, record: any) {
-		const user = this.getCurrentUser();
+## Creating a session (sign in)
+
+Pattern from `resources/signIn.ts`:
+
+```ts
+import { type Context, type RequestTargetOrId, Resource } from 'harperdb';
+
+export interface LoginBody {
+	username?: string;
+	password?: string;
+}
+
+export class SignIn extends Resource {
+	static loadAsInstance = false;
 
-		// Check if the user has the 'super_user' role
-		if (user?.role?.role !== 'super_user') {
-			throw {
-				message: 'Only super users are allowed to make changes',
-				statusCode: 403,
-			};
+	allowCreate() {
+		return true; // public endpoint
+	}
+
+	async post(_target: RequestTargetOrId, data: LoginBody) {
+		const errors: string[] = [];
+		if (!data.username) { errors.push('username'); }
+		if (!data.password) { errors.push('password'); }
+		if (errors.length) {
+			return new Response(
+				`Please include the ${errors.join(' and ')} in your request.`,
+				{ status: 400 },
+			);
 		}
 
-		return super.post(target, record);
+		const context = this.getContext() as Context as any;
+		try {
+			await context.login(data.username, data.password);
+		} catch {
+			return new Response('Please check your credentials and try again.', {
+				status: 403,
+			});
+		}
+		return new Response('Welcome back!', { status: 200 });
 	}
 }
 ```
 
-## Handling Unauthenticated Requests
+- `context.login(username, password)` creates a session and sets the session cookie on the response.
+- Missing fields → `400 Bad Request`.
+- Invalid credentials → `403 Forbidden` (don’t leak which field was wrong).
+
+## Reading the current user (who am I)
+
+Pattern from `resources/me.ts`:
+
+```ts
+import { Resource } from 'harperdb';
 
-Always ensure you handle cases where `this.getCurrentUser()` returns `null`, especially if your resource is accessible to unauthenticated users.
+export class Me extends Resource {
+	static loadAsInstance = false;
 
-```typescript
-const user = this.getCurrentUser();
-if (!user) {
-	throw {
-		message: 'Authentication required',
-		statusCode: 401,
-	};
+	allowRead() {
+		return true; // public: returns data only if session exists
+	}
+
+	async get() {
+		const user = this.getCurrentUser?.();
+		if (!user?.username) {
+			// Not signed in; return 200 with no body to make polling simple on the client
+			return new Response(null, { status: 200 });
+		}
+		return {
+			active: user.active,
+			role: user.role,
+			username: user.username,
+			created: user.__createdtime__,
+			updated: user.__updatedtime__,
+		};
+	}
 }
 ```
 
-## User Object Structure
+- Use `this.getCurrentUser?.()` to access the session’s user (if any).
+- It may be `undefined` when unauthenticated. Handle that case explicitly.
+
+## Destroying a session (sign out)
+
+Pattern from `resources/signOut.ts`:
+
+```ts
+import { type Context, Resource } from 'harperdb';
+
+export class SignOut extends Resource {
+	static loadAsInstance = false;
+
+	allowCreate() {
+		return true; // public endpoint, but requires a session to actually act
+	}
+
+	async post() {
+		const user = this.getCurrentUser();
+		if (!user?.username) {
+			return new Response('Not signed in.', { status: 401 });
+		}
+
+		const context = this.getContext() as Context as any;
+		await context.session?.delete?.(context.session.id);
+		return new Response('Signed out successfully.', { status: 200 });
+	}
+}
+```
+
+- If the request has no session, return `401 Unauthorized`.
+- Otherwise delete the current session via `context.session.delete(sessionId)`.
+
+## Protecting privileged endpoints
+
+For admin-only or otherwise privileged actions, use the `ensureSuperUser` helper with the current user.
+
+```ts
+import {
+	RequestTarget,
+	type RequestTargetOrId,
+	Resource,
+	tables,
+} from 'harperdb';
+import { ensureSuperUser } from './common/ensureSuperUser.ts';
+
+export class DoSomethingInteresting extends Resource {
+	static loadAsInstance = false;
+
+	async get(target: RequestTargetOrId) {
+		ensureSuperUser(this.getCurrentUser());
+		// … fetch and return the artwork
+	}
+}
+```
+
+`ensureSuperUser` throws a `403` if the user is not a super user:
+
+```ts
+import { type User } from 'harperdb';
+
+export function ensureSuperUser(user: User | undefined) {
+	if (!user?.role?.permission?.super_user) {
+		let error = new Error('You do not have permission to perform this action.');
+		(error as any).statusCode = 403;
+		throw error;
+	}
+}
+```
+
+## Status code conventions used here
+
+- 200: Successful operation. For `GET /me`, a `200` with empty body means “not signed in”.
+- 400: Missing required fields (e.g., username/password on sign-in).
+- 401: No current session for an action that requires one (e.g., sign out when not signed in).
+- 403: Authenticated but not authorized (bad credentials on login attempt, or insufficient privileges).
+
+## Client considerations
+
+- Sessions are cookie-based; the server handles setting and reading the cookie via HarperDB. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
+- If developing locally, double-check the server config still has `authentication.authorizeLocal: false` to avoid accidental superuser bypass.
 
-The object returned by `this.getCurrentUser()` typically includes:
+## Quick checklist
 
-- `username`: The username of the authenticated user.
-- `role`: An object containing role information, including the `role` name itself (e.g., `user.role.role`).
+- [ ] Public endpoints explicitly `allowRead`/`allowCreate` as needed.
+- [ ] Sign-in uses `context.login` and handles 400/403 correctly.
+- [ ] Protected routes call `ensureSuperUser(this.getCurrentUser())` (or another role check) before doing work.
+- [ ] Sign-out verifies a session and deletes it.
+- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in HarperDB config.

package/resources/examplePeople.ts

@@ -1,20 +0,0 @@
-import { type RequestTargetOrId, tables } from 'harperdb';
-
-export interface ExamplePerson {
-	id: string;
-	name: string;
-	tag: string;
-}
-
-export class ExamplePeople extends tables.ExamplePeople<ExamplePerson> {
-	// we can define our own custom POST handler
-	async post(target: RequestTargetOrId, newRecord: Omit<ExamplePerson, 'id'>) {
-		// do something with the incoming content;
-		return super.post(target, newRecord);
-	}
-	// or custom GET handler
-	async get(target: RequestTargetOrId): Promise<ExamplePerson> {
-		// we can modify this resource before returning
-		return super.get(target);
-	}
-}

package/resources/exampleSocket.ts

@@ -1,41 +0,0 @@
-import { type IterableEventQueue, RequestTarget, Resource, tables } from 'harperdb';
-
-interface ExampleSocketRecord {
-	id: string;
-	type?: 'get' | 'put';
-	name: string;
-	tag: string;
-}
-
-export class ExampleSocket extends Resource<ExampleSocketRecord> {
-	static loadAsInstance = false;
-
-	// This customizes handling the socket connections; tables can have this method too!
-	async *connect(
-		target: RequestTarget,
-		incomingMessages: IterableEventQueue<ExampleSocketRecord>,
-	): AsyncIterable<ExampleSocketRecord> {
-		const subscription = await tables.ExamplePeople.subscribe(target);
-		if (!incomingMessages) {
-			// Server sent events, no incoming messages!
-			// Subscribe to changes to the table.
-			return subscription;
-		}
-		for await (let message of incomingMessages) {
-			const { type, id, name, tag } = message;
-			switch (type) {
-				case 'get':
-					const loaded = await tables.ExamplePeople.get(id);
-					yield {
-						type: 'get',
-						id,
-						...(loaded ? loaded : {}),
-					};
-					break;
-				case 'put':
-					await tables.ExamplePeople.put(id, { name, tag });
-					break;
-			}
-		}
-	}
-}

package/resources/greeting.ts

@@ -1,29 +0,0 @@
-import { type RecordObject, type RequestTargetOrId, Resource } from 'harperdb';
-
-interface GreetingRecord {
-	greeting: string;
-}
-
-export class Greeting extends Resource<GreetingRecord> {
-	static loadAsInstance = false;
-
-	async post(target: RequestTargetOrId, newRecord: Partial<GreetingRecord & RecordObject>): Promise<GreetingRecord> {
-		return { greeting: 'Greetings, post!' };
-	}
-
-	async get(target?: RequestTargetOrId): Promise<GreetingRecord> {
-		return { greeting: 'Greetings, get!' };
-	}
-
-	async put(target: RequestTargetOrId, record: GreetingRecord & RecordObject): Promise<GreetingRecord> {
-		return { greeting: 'Greetings, put!' };
-	}
-
-	async patch(target: RequestTargetOrId, record: Partial<GreetingRecord & RecordObject>): Promise<GreetingRecord> {
-		return { greeting: 'Greetings, patch!' };
-	}
-
-	async delete(target: RequestTargetOrId): Promise<boolean> {
-		return true;
-	}
-}

package/schemas/examplePeople.graphql

@@ -1,7 +0,0 @@
-## Here we can define any tables in our database. This example shows how we define a type as a table using
-## the type name as the table name and specifying it is an "export" available in the REST and other external protocols.
-type ExamplePeople @table @export {
-	id: ID @primaryKey # Here we define primary key (must be one)
-	name: String # we can define any other attributes here
-	tag: String @indexed # we can specify any attributes that should be indexed
-}