more updates etc

- start scaffolding out api v2
- more docs
- some extensions
- etc

Author: MichaelFedora

.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "request": "launch",
+            "name": "Run STD Example",
+            "type": "pwa-node",
+            "program": "${workspaceFolder}/examples/std.ts",
+            "cwd": "${workspaceFolder}",
+            "runtimeExecutable": "deno",
+            "runtimeArgs": [
+                "run",
+                "--inspect",
+                "--allow-all"
+            ],
+            "attachSimplePort": 9229
+        }
+    ]
+}

.vscode/settings.json

@@ -2,8 +2,5 @@
     "deno.enable": true,
     "deno.lint": true,
     "deno.unstable": false,
-    "cSpell.words": [
-        "GraphiQL"
-    ],
     // "deno.importMap": "./import_map.json"
 }

API.md

@@ -13,19 +13,20 @@ All URLs land under the `/auth` parent route, e.x.:
 - `POST /auth/login`
 - `GET /auth/handshake/start`
 
-- POST `/login`
-- POST `/register`
-- POST `/change-pass`
-- GET `/sessions`
-- DELETE `/session/:id?`
-- POST `/logout`
-- GET `/refresh`
-- GET `/handshake/start`
-- POST `/handshake/complete`
-- GET `/handshake/:id/(approve|cancel)?`
-- GET | POST `/master-key`
-- PUT | DELETE `/master-key/:id`
-- POST `/master-key/:id/generate-session`
+- POST `/login` - Post with a body of `{ username: string; password: string }` and either get a 403 or a session
+- POST `/register` - Post with a body of `{ username: string; password: string }` and get a 401 or a 204.
+- POST `/change-pass` - Post with a body of `{ username: string; password: string; newpass: string }`
+  and either get a 403 or a 204.
+- GET `/sessions` - Receives a list of active sessions
+- DELETE `/session/:id?` - Revoke all or one session via ID)
+- POST `/logout` - Logout of the currently authorized session
+- GET `/refresh` - Refresh the current session - revokes the old session and returns a new ID
+- GET `/handshake/start` - Start a handshake by redirecting to this route
+- POST `/handshake/complete` - Finish a handshake by posting data to this route and getting a session back
+- GET `/handshake/:id/(approve|cancel)?` - Approve or cancel a handshake - this is for a Tiny node UI to use
+- GET | POST `/master-key` - Get all or add a master-key to the Tiny node with an optional `name` query param
+- PUT | DELETE `/master-key/:id` - Update (the name) or remove a master-key
+- POST `/master-key/:id/generate-session` - Use a master-key to generate a session
 
 ## Scoped Features
 

api/router.ts

@@ -1,13 +1,13 @@
-import { RequestStub, RouteHandler } from './types.ts';
+import { SlimRequestStub, RequestStub, RouteHandler } from './types.ts';
 
 /**
  * A step on the path of the router
  */
 interface RouteStep<Req extends RequestStub = RequestStub> {
-  /** The route */
+  /** The route (pathname) */
   route: string;
   /** What request method to limit to; empty for USE, as we do not limit for that */
-  type?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  type?: 'HEAD' | 'OPTIONS' | 'GET' | 'POST' | 'PUT' | 'DELETE';
   /** The route handler (or router) */
   handler: Router<Req> | RouteHandler<Req>;
 }
@@ -75,7 +75,7 @@ export class Router<Req extends RequestStub = RequestStub> {
    * @param {string} type The route method (GET/POST/PUT/DELETE)
    * @param {Array<RouteHandler>} handlers The handlers to add to our #step array (condensed)
    */
-  #add<R extends Req = Req>(route: string, type: 'GET' | 'POST' | 'PUT' | 'DELETE', handlers: RouteHandler<R>[]): void {
+  #add<R extends Req = Req>(route: string, type: 'HEAD' | 'OPTIONS' | 'GET' | 'POST' | 'PUT' | 'DELETE', handlers: RouteHandler<R>[]): void {
 
     // enforce `/{route}` with no trailing `/`'s
     route = '/' + route.replace(/^\/+|\/+$/g, '');
@@ -87,6 +87,32 @@ export class Router<Req extends RequestStub = RequestStub> {
     });
   }
 
+  /**
+   * Add handlers to a HEAD {route} call
+   * @param {string} route The route
+   * @param {Router | RouteHandler} handler A router or route handler
+   * @param {Array<Router | RouteHandler>} handlers Any other route handlers to chain
+   * @returns {this} this
+   */
+  head<R extends Req = Req>(route: string, handler: RouteHandler<R>, ...handlers: RouteHandler<R>[]): this {
+    handlers.unshift(handler);
+    this.#add(route, 'HEAD', handlers);
+    return this;
+  }
+
+  /**
+   * Add handlers to a OPTIONS {route} call
+   * @param {string} route The route
+   * @param {Router | RouteHandler} handler A router or route handler
+   * @param {Array<Router | RouteHandler>} handlers Any other route handlers to chain
+   * @returns {this} this
+   */
+  options<R extends Req = Req>(route: string, handler: RouteHandler<R>, ...handlers: RouteHandler<R>[]): this {
+    handlers.unshift(handler);
+    this.#add(route, 'OPTIONS', handlers);
+    return this;
+  }
+
   /**
    * Add handlers to a GET {route} call
    * @param {string} route The route
@@ -146,11 +172,11 @@ export class Router<Req extends RequestStub = RequestStub> {
    * @param {string?} type The route type -- if undefined (for USE), it also matches any sub-routes
    * @returns {boolean} Whether or not it matches
    */
-  #matchRoute(url: string, route: string, type?: string): boolean {
+  #matchRoute(url: string, route: string, matchExtra?: boolean): boolean {
     let pattern = new URLPattern({ pathname: route });
     let test = pattern.test(url);
 
-    if(type || test)
+    if(!matchExtra || test)
       return test;
 
     pattern = new URLPattern({ pathname: route + '(.*)' });
@@ -165,35 +191,37 @@ export class Router<Req extends RequestStub = RequestStub> {
    * @param {string?} base The base url to append to the routes we are matching; used for sub-routers
    * @returns {Array<RouteHandler>} The path through the step list -- should be iterated through to process
    */
-  #pathfind<R extends Req = Req>(req: R, base = ''): RouteHandler<R>[] {
+  #pathfind<R extends Req = Req>(req: Partial<R> & SlimRequestStub, options?: { base?: string; matchType?: boolean }): { type: RouteStep['type'], handler: RouteHandler<R> }[] {
+    let base = options?.base ?? '';
+    const matchType = options?.matchType !== false;
 
     // enforce `/{route}` with no trailing `/`'s
     if(base)
       base = '/' + base.replace(/^\/+|\/+$/g, '');
 
-    const path: RouteHandler<R>[] = [];
+    const path: { type: RouteStep['type'], handler: RouteHandler<R> }[] = [];
 
     for(const step of this.#steps) {
       // append the base to the route and remove any trailing `/`'s for the proper route to match against
       const route = (base + step.route).replace(/\/+$/g, '');
 
-      if( (step.type && req.method !== step.type) ||
-          !this.#matchRoute(req.url, route, step.type) )
+      if( (matchType && step.type && req.method !== step.type) ||
+          !this.#matchRoute(req.url, route, !step.type) )
         continue;
 
       // move the handler into a variable in case it changes while it is being processed
       const handler = step.handler;
 
       if(handler instanceof Router)
-        path.push(...(handler as Router<R>).#pathfind(req, route));
+        path.push(...(handler as Router<R>).#pathfind(req, { base: route }));
       else {
-        path.push((req, next) => {
+        path.push({ type: step.type, handler: (req, next) => {
           // match the route params for utility reasons
-          req.params = (new URLPattern({ pathname: route + '/:else(.*)?' })).exec(req.url)?.pathname?.groups;
-          delete req.params!.else;
+          req.params = (new URLPattern({ pathname: route + '/:else(.*)?' })).exec(req.url)?.pathname?.groups ?? { };
+          delete req.params.else;
 
           return handler(req, next);
-        });
+        } });
       }
     }
 
@@ -211,9 +239,9 @@ export class Router<Req extends RequestStub = RequestStub> {
    * @returns {Promise<Response | undefined>} The response generated from the given routes,
    * or undefined if nothing was returned
    */
-  async process<R extends Req = Req>(req: R, base = ''): Promise<Response | undefined> {
+  async process<R extends Req = Req>(req: Partial<R> & SlimRequestStub, base = ''): Promise<Response | undefined> {
 
-    const path = this.#pathfind(req, base);
+    const path = this.#pathfind(req, { base });
 
     if(!path.length)
       return undefined;
@@ -222,27 +250,43 @@ export class Router<Req extends RequestStub = RequestStub> {
 
     const query = req.query;
     const params = req.params;
+    const context = req.context;
 
     // generate the query object for utility reasons
-    req.query = req.url.includes('?')
+    req.query = (req.url.includes('?')
       ? Object.fromEntries((new URLSearchParams(req.url.slice(req.url.indexOf('?')))).entries())
-      : undefined;
+      : undefined) ?? { };
+
+    req.context = { };
 
     // used to check if the chain never finished and we got "ghosted"
     const nextResponse = new Response();
 
-    const res = await this.#condense(path)(req, () => nextResponse);
+    const res = await this.#condense(path.map(p => p.handler))(req as R, () => nextResponse);
 
     // cleanup
 
     req.query = query;
     req.params = params;
+    req.context = context;
 
     if(!res || res === nextResponse)
       return undefined;
 
     return res;
   }
+
+  parseOptions<R extends Req = Req>(req: Partial<R> & SlimRequestStub, base = ''): { methods: string } {
+    const path = this.#pathfind(req, { base, matchType: false });
+
+    const methods = new Set<string>();
+
+    for(const p of path)
+      if(p.type)
+        methods.add(p.type);
+
+    return { methods: Array.from(methods.values()).join(', ') };
+  }
 }
 
 export default Router;

api/types.ts

@@ -2,23 +2,38 @@
  * A request stub which this library uses. You can either set the two required fields yourself or
  * just pass something that is compatible (like the standard `Request` object).
  */
-export interface RequestStub {
+export interface SlimRequestStub {
 
   // CORE (std)
 
   /** The (full) url */
   readonly url: string;
   /** The method (GET | PUT | POST | DELETE) */
   readonly method: string;
+}
+
+/**
+ * A request stub which this library uses. You can either set the two required fields yourself or
+ * just pass something that is compatible (like the standard `Request` object).
+ */
+export interface RequestStub<Context = Record<string, unknown>> extends SlimRequestStub {
 
   // GENERATED
 
   /** Generated via URLPattern */
-  params?: Record<string, string | undefined>;
+  params: Record<string, string | undefined>;
   /** Generated via URLSearchParams */
-  query?: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+
+  // UTILITY
+
+  /** Used for utility */
+  context: Context;
 }
 
 /** A route handler or middleware. Can `await` or just return `next` to continue along the chain, but should otherwise return a Response. */
 export type RouteHandler<Req extends RequestStub = RequestStub> = (req: Req, next: () => Promise<Response> | Response) => Promise<Response> | Response;
 
+/** A route handler or middleware. Can `await` or just return `next` to continue along the chain, but should otherwise return a Response. */
+export type SlimRouteHandler<Req extends { readonly url: string; readonly method: string; }> = (req: Req, next: () => Promise<Response> | Response) => Promise<Response> | Response;
+

api/util.ts

@@ -1,5 +1,5 @@
 /**
- * Create a text response
+ * Create a text response.
  * @param {string} body The body of the response
  * @param {ResponseInit} init Response options
  * @returns {Response} The response
@@ -22,7 +22,7 @@ export function text(body = '', init: ResponseInit = { }): Response {
 }
 
 /**
- * Create a JSON response
+ * Create a JSON response.
  * @param {any} body The body of the response
  * @param {ResponseInit} init Response options
  * @returns {Response} The response
@@ -54,11 +54,31 @@ export function noContent(init: ResponseInit = { }): Response {
 }
 
 /**
- * Create a redirect response.
+ * Create a 307 redirect response.
  * @param {string} url The redirect url
  * @param {ResponseInit} init Response options
  * @returns {Response} The response
  */
 export function redirect(url: string, init: ResponseInit = { }): Response {
-  return new Response(undefined, { status: 302, ...init, headers: { ...init.headers, location: url } });
+  return new Response(undefined, { status: 307, ...init, headers: { ...init.headers, location: url } });
+}
+
+/**
+ * Create a 412 precondition failed response.
+ * @param {BodyInit | undefined | null} body The body of the response
+ * @param {ResponseInit} init Response options
+ * @returns {Response} The response
+ */
+export function preconditionFailed(body?: BodyInit | undefined | null, init?: ResponseInit): Response {
+  return new Response(body, { status: 412, statusText: 'Precondition Failed', ...init })
+}
+
+/**
+ * Create a 409 conflict response.
+ * @param {BodyInit | undefined | null} body The body of the response
+ * @param {ResponseInit} init Response options
+ * @returns {Response} The response
+ */
+export function conflict(body?: BodyInit | undefined | null, init?: ResponseInit): Response {
+  return new Response(body, { status: 409, statusText: 'Conflict', ...init });
 }

auth/auth-api.ts

@@ -283,7 +283,7 @@ export class AuthApi extends Api {
     router.get('/sessions', async req => json(await this.sessions(req.user)));
 
     router.delete('/sessions/:id', async req => {
-      await this.deleteSession(req.params!.id!, req.user);
+      await this.deleteSession(req.params.id!, req.user);
 
       return noContent();
     });
@@ -336,7 +336,7 @@ export class AuthApi extends Api {
 
         console.log(req.params, req.query);
 
-        req.handshake = await this.testHandshake(req.params!.id!, req.session!);
+        req.handshake = await this.testHandshake(req.params.id!, req.session!);
         return next();
       });
 
@@ -368,10 +368,10 @@ export class AuthApi extends Api {
       masterKeyRouter.use(handleError('auth-master-key'));
 
       masterKeyRouter.post('/:id/generate-session', async req => {
-        if(!req.query?.scopes)
+        if(!req.query.scopes)
           throw new MalformedError('?scopes=[..] required!');
 
-        return json(await this.generateSessionFromMasterKey(req.params!.id!, this.#validateScopes(req.query.scopes)));
+        return json(await this.generateSessionFromMasterKey(req.params.id!, this.#validateScopes(req.query.scopes)));
       });
 
       masterKeyRouter.use(requireUserSession, (req, next) => {
@@ -382,12 +382,12 @@ export class AuthApi extends Api {
       });
 
       masterKeyRouter.get('/', async req => json(await this.getMasterKeys(req.user!.id!)));
-      masterKeyRouter.post('/', async req => text(await this.addMasterKey(req.user!.id!, req.query?.name)));
+      masterKeyRouter.post('/', async req => text(await this.addMasterKey(req.user!.id!, req.query.name)));
 
       masterKeyRouter.use('/:id', async (req, next) => {
-        const key = await this.getMasterKey(req.params!.id!, req.user!.id!);
+        const key = await this.getMasterKey(req.params.id!, req.user!.id!);
         if(!key)
-          throw new NotFoundError('Key not found with id "' + req.params!.id! + '"!');
+          throw new NotFoundError('Key not found with id "' + req.params.id! + '"!');
 
         req.masterKey = key;
 

auth/auth-db.ts

@@ -45,6 +45,13 @@ export abstract class AuthDb {
   abstract delUser(id: string): Promise<void>;
   abstract getUserFromUsername(username: string): Promise<AuthUser | null>;
 
+  // user preferences
+
+  /* abstract putUserPref(id: string, key: string, value: string);
+  abstract getUserPref(id: string, key: string);
+  abstract findUserPref(id: string, value: string);
+  abstract findUserFromPref(key: string, value: string); */
+
   // handshakes
 
   abstract addHandshake(hs: Handshake): Promise<string>;