feat: initial boilerplate

spec/modules/README.md

@@ -0,0 +1 @@
+# Modules

spec/modules/auth/errors.ts

@@ -0,0 +1,7 @@
+import { BadRequestError } from "@spec/relay";
+
+export class AuthenticationStrategyPayloadError extends BadRequestError {
+  constructor() {
+    super("Provided authentication payload is not recognized.");
+  }
+}

spec/modules/auth/mod.ts

@@ -0,0 +1,8 @@
+import { authenticate } from "./routes/authenticate.ts";
+
+export * from "./errors.ts";
+export * from "./strategies.ts";
+
+export const routes = {
+  authenticate,
+};

spec/modules/auth/routes/authenticate.ts

@@ -0,0 +1,9 @@
+import { route } from "@spec/relay";
+
+import { AuthenticationStrategyPayloadError } from "../errors.ts";
+import { StrategyPayloadSchema } from "../strategies.ts";
+
+export const authenticate = route
+  .post("/api/v1/authenticate")
+  .body(StrategyPayloadSchema)
+  .errors([AuthenticationStrategyPayloadError]);

spec/modules/auth/strategies.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+export const PasskeyStrategySchema = z.object({
+  type: z.literal("passkey").describe("Authentication strategy type for WebAuthn/Passkey"),
+  payload: z
+    .object({
+      id: z.string().describe("Base64URL encoded credential ID"),
+      rawId: z.string().describe("Raw credential ID as base64URL encoded string"),
+      response: z
+        .object({
+          clientDataJSON: z.string().describe("Base64URL encoded client data JSON"),
+          authenticatorData: z.string().describe("Base64URL encoded authenticator data"),
+          signature: z.string().optional().describe("Signature for authentication responses"),
+          userHandle: z.string().optional().describe("Optional user handle identifier"),
+          attestationObject: z.string().optional().describe("Attestation object for registration responses"),
+        })
+        .describe("WebAuthn response data"),
+      clientExtensionResults: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("Results from WebAuthn extension inputs"),
+      authenticatorAttachment: z
+        .enum(["platform", "cross-platform"])
+        .optional()
+        .describe("Type of authenticator used (platform or cross-platform)"),
+    })
+    .describe("WebAuthn credential payload"),
+});
+
+export const EmailStrategySchema = z.object({
+  type: z.literal("email").describe("Authentication strategy type for email"),
+  payload: z
+    .object({
+      email: z.email().describe("User's email address for authentication"),
+    })
+    .describe("Email authentication payload"),
+});
+
+export const PasswordStrategySchema = z.object({
+  type: z.literal("password").describe("Authentication strategy type for password"),
+  payload: z
+    .object({
+      identifier: z.string().describe("User identifier (username or email)"),
+      password: z.string().describe("User's password"),
+    })
+    .describe("Password authentication payload"),
+});
+
+export const StrategyPayloadSchema = z
+  .union([PasskeyStrategySchema, EmailStrategySchema, PasswordStrategySchema])
+  .describe("Union of all available authentication strategy schemas");

spec/modules/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@spec/modules",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@spec/relay": "workspace:*",
+    "@spec/shared": "workspace:*",
+    "zod": "4"
+  }
+}