@everystack/auth 0.1.0 → 0.2.1

package/src/plugin.ts

@@ -0,0 +1,264 @@
+/**
+ * @everystack/auth/plugin — Auth routes + layered security as a composable plugin.
+ *
+ * Registers signup, signin, refresh, and signout routes.
+ * Optionally decorates verifyToken with audience, client, device, and custom checks.
+ * Optionally contributes client management CLI actions.
+ *
+ * Note: Types are inlined to avoid circular dependency with @everystack/server.
+ */
+
+// ─── Inlined Server Types (avoid circular dep) ──────────────────────────────
+
+/** Minimal plugin context (compatible with @everystack/server/plugin PluginContext) */
+interface PluginContext {
+  db: any;
+  schema: Record<string, any>;
+  verifyToken: (token: string) => Promise<Record<string, unknown> | null>;
+  environment: string;
+  publishJob: (type: string, payload: unknown) => Promise<string>;
+  [key: string]: unknown;
+}
+
+/** Minimal route type (compatible with @everystack/server Route) */
+interface Route {
+  path: string;
+  method?: string;
+  exact?: boolean;
+  handler: (req: Request) => Promise<Response>;
+}
+
+type ActionHandler = (payload: unknown, ctx: PluginContext) => Promise<unknown>;
+
+interface PluginContribution {
+  routes?: Route[];
+  actions?: Record<string, ActionHandler>;
+}
+
+type Plugin = (ctx: PluginContext) => Promise<PluginContribution>;
+
+// ─── Auth Plugin Types ───────────────────────────────────────────────────────
+
+export type EnrichClaimsFn = (
+  baseClaims: Record<string, unknown>,
+  request: Request,
+) => Promise<Record<string, unknown>>;
+
+export interface ClientCallbacks {
+  resolve: (clientId: string) => Promise<{
+    id: string;
+    name: string;
+    active: boolean;
+    audience?: string;
+    [k: string]: unknown;
+  } | null>;
+  register?: (name: string) => Promise<{ clientId: string; secret: string }>;
+  rotate?: (clientId: string) => Promise<{ secret: string }>;
+  revoke?: (clientId: string) => Promise<void>;
+  list?: () => Promise<Array<{
+    id: string;
+    name: string;
+    clientId: string;
+    active: boolean;
+    createdAt: Date;
+  }>>;
+}
+
+export interface DeviceCallbacks {
+  verify: (attestation: unknown, claims: Record<string, unknown>) => Promise<boolean>;
+  require?: 'always' | 'write' | 'never';
+}
+
+export interface AuthPluginOptions {
+  /** Base path for auth routes (default: '/api/auth') */
+  basePath?: string;
+  /** Expected audience claim — rejects tokens with wrong/missing aud */
+  audience?: string;
+  /** Client resolution and management callbacks */
+  clients?: (ctx: PluginContext) => ClientCallbacks;
+  /** Device attestation verification */
+  device?: DeviceCallbacks;
+  /** Custom claims validation — return false to reject */
+  verifyClaims?: (claims: Record<string, unknown>) => Promise<boolean>;
+}
+
+// ─── enrichClaims Forward Reference ──────────────────────────────────────────
+
+/**
+ * Creates a mutable ref + stable function for enrichClaims.
+ *
+ * The context factory creates auth handlers before plugins init. The plugin
+ * needs to inject enrichClaims behavior after init. This forward reference
+ * pattern bridges that gap.
+ *
+ * Usage in app context factory:
+ *   const enrichClaims = createEnrichRef();
+ *   const auth = createAuthHandlers(db, schema, jwtSecret, {
+ *     enrichClaims: enrichClaims.fn,
+ *   });
+ *   return { ..., enrichClaimsRef: enrichClaims.ref };
+ */
+export function createEnrichRef(): {
+  ref: { current: EnrichClaimsFn | null };
+  fn: EnrichClaimsFn;
+} {
+  const ref: { current: EnrichClaimsFn | null } = { current: null };
+  const fn: EnrichClaimsFn = async (claims, request) => {
+    return ref.current ? ref.current(claims, request) : {};
+  };
+  return { ref, fn };
+}
+
+// ─── Auth Context Extension ──────────────────────────────────────────────────
+
+interface AuthContext extends PluginContext {
+  auth: {
+    signup: (req: Request) => Promise<Response>;
+    signin: (req: Request) => Promise<Response>;
+    refresh: (req: Request) => Promise<Response>;
+    signout: (req: Request) => Promise<Response>;
+  };
+  enrichClaimsRef?: { current: EnrichClaimsFn | null };
+}
+
+// ─── Plugin Implementation ───────────────────────────────────────────────────
+
+export function authPlugin(options: AuthPluginOptions = {}): Plugin {
+  const basePath = options.basePath ?? '/api/auth';
+
+  return async (ctx) => {
+    const { auth } = ctx as AuthContext;
+    const clientCallbacks = options.clients?.(ctx);
+
+    // --- Decorate verifyToken with layered security ---
+    if (options.audience || clientCallbacks || options.device || options.verifyClaims) {
+      const originalVerifyToken = ctx.verifyToken;
+      const deviceRequire = options.device?.require ?? 'never';
+
+      ctx.verifyToken = async (token: string): Promise<Record<string, unknown> | null> => {
+        const claims = await originalVerifyToken(token);
+        if (!claims) return null;
+
+        // Layer 1: Audience check — when configured, all tokens must carry a
+        // matching aud claim. Client-authenticated tokens get aud via enrichClaims.
+        if (options.audience) {
+          if (claims.aud !== options.audience) return null;
+        }
+
+        // Layer 2: Client resolution
+        if (clientCallbacks && claims.client_id) {
+          const client = await clientCallbacks.resolve(claims.client_id as string);
+          if (!client || !client.active) return null;
+        }
+
+        // Layer 3: Device attestation
+        if (options.device && deviceRequire === 'always') {
+          const passed = await options.device.verify(
+            claims.device_attestation ?? null,
+            claims,
+          );
+          if (!passed) return null;
+        }
+
+        // Layer 4: Custom claims validation
+        if (options.verifyClaims) {
+          const valid = await options.verifyClaims(claims);
+          if (!valid) return null;
+        }
+
+        return claims;
+      };
+    }
+
+    // --- Wire enrichClaims ref ---
+    const authCtx = ctx as AuthContext;
+    if (authCtx.enrichClaimsRef && clientCallbacks) {
+      authCtx.enrichClaimsRef.current = async (
+        baseClaims: Record<string, unknown>,
+        request: Request,
+      ): Promise<Record<string, unknown>> => {
+        // Check baseClaims first (refresh path — client_id from session data)
+        let clientId = baseClaims.client_id as string | undefined;
+
+        // Fall back to request body (signin/signup path)
+        if (!clientId) {
+          try {
+            const body = await request.clone().json();
+            clientId = body?.client_id;
+          } catch {
+            // No JSON body or no client_id
+          }
+        }
+
+        if (!clientId) return {};
+
+        const client = await clientCallbacks.resolve(clientId);
+        if (!client || !client.active) return {};
+
+        return {
+          client_id: clientId,
+          aud: client.audience ?? options.audience,
+        };
+      };
+    }
+
+    // --- Build contribution ---
+    const contribution: PluginContribution = {
+      routes: [
+        { path: `${basePath}/signup`, method: 'POST', exact: true, handler: auth.signup },
+        { path: `${basePath}/signin`, method: 'POST', exact: true, handler: auth.signin },
+        { path: `${basePath}/refresh`, method: 'POST', exact: true, handler: auth.refresh },
+        { path: `${basePath}/signout`, method: 'POST', exact: true, handler: auth.signout },
+      ],
+    };
+
+    // --- Client management actions ---
+    if (clientCallbacks) {
+      const hasManagement = clientCallbacks.register ||
+        clientCallbacks.rotate ||
+        clientCallbacks.revoke ||
+        clientCallbacks.list;
+
+      if (hasManagement) {
+        const actions: Record<string, ActionHandler> = {};
+
+        if (clientCallbacks.register) {
+          const registerFn = clientCallbacks.register;
+          actions['clients:register'] = async (payload) => {
+            const { name } = payload as { name: string };
+            return await registerFn(name);
+          };
+        }
+
+        if (clientCallbacks.rotate) {
+          const rotateFn = clientCallbacks.rotate;
+          actions['clients:rotate'] = async (payload) => {
+            const { clientId } = payload as { clientId: string };
+            return await rotateFn(clientId);
+          };
+        }
+
+        if (clientCallbacks.revoke) {
+          const revokeFn = clientCallbacks.revoke;
+          actions['clients:revoke'] = async (payload) => {
+            const { clientId } = payload as { clientId: string };
+            await revokeFn(clientId);
+            return { revoked: true };
+          };
+        }
+
+        if (clientCallbacks.list) {
+          const listFn = clientCallbacks.list;
+          actions['clients:list'] = async () => {
+            const clients = await listFn();
+            return { clients };
+          };
+        }
+
+        contribution.actions = actions;
+      }
+    }
+
+    return contribution;
+  };
+}