suaveplan/openspec/archive/2026-05-18-add-api-plugin-auth/tasks.md

Tasks — add-api-plugin-auth

1. Scaffold

• 1.1 Create packages/api/api-plugin-auth/ with src/{plugin,middleware,principal,services,schemas,routes,schema,error-codes,otel,types}/ + tests/{setup,integration}/
• 1.2 package.json v0.1.0. Deps: @suaveplan/api-plugin @suaveplan/api-openapi @suaveplan/api-migrations @suaveplan/better-auth-surrealdb @suaveplan/surrealdb @suaveplan/error @suaveplan/types tslib, hono @hono/zod-openapi (catalog:server), zod (catalog:forms), @opentelemetry/api, better-auth (catalog:auth)
• 1.3 15 subpath exports per the proposal
• 1.4 tsconfigs + vite + vitest (100/100/100/100, testTimeout 60000 for integration)
• 1.5 tests/setup/polyfills.ts

2. Implementation

• 2.1 src/error-codes.{ts,test.ts,md,index.ts} — 10 AUTH.* codes + AuthError
• 2.2 src/principal/principal.{ts,test.ts,md,index.ts} — Principal interface + mapBetterAuthUserToPrincipal default
• 2.3 src/schemas/principal.{ts,test.ts,md,index.ts} — PrincipalSchema, SessionSchema, AccountSchema (Zod)
• 2.4 src/schemas/options.{ts,test.ts,md,index.ts} — AuthPluginOptionsSchema
• 2.5 src/schemas/routes/<name>.{ts,test.ts,md} — per-route request/response Zod schemas (sign-up, sign-in, sign-out, session, forgot-password, reset-password, verify-email, oauth-start, oauth-callback) + schemas/routes/index.ts
• 2.6 src/otel/instruments.{ts,test.ts,md,index.ts} — counters + histogram
• 2.7 src/services/auth-service.{ts,test.ts,md,index.ts} — AuthService interface + impl; ServiceRegistry module augmentation
• 2.8 src/middleware/require-auth.{ts,test.ts,md,index.ts} — requireAuth() factory
• 2.9 src/middleware/require-role.{ts,test.ts,md} — requireRole(...) factory
• 2.10 src/middleware/require-email-verified.{ts,test.ts,md} — requireEmailVerified() factory
• 2.11 src/middleware/session.{ts,test.ts,md} — global session-resolver middleware (sets c.set("user") + c.set("session"); Hono ContextVariableMap augmentation)
• 2.12 src/routes/build-routes.{ts,test.ts,md,index.ts} — buildAuthRoutes(auth) returning PluginRouteEntry[] via RouteBuilder
• 2.13 src/schema/schema.{ts,md,index.ts} — re-export BETTER_AUTH_SURREAL_SCHEMA + applyBetterAuthSchema from @suaveplan/better-auth-surrealdb
• 2.14 src/plugin/plugin.{ts,test.ts,md,index.ts} — createAuthPlugin(options) factory; 6-step onInit lifecycle (resolve services → apply schema → construct Better-Auth → register service → register routes → install session middleware); onClose releases DB
• 2.15 src/plugin/on-init.test.ts — covers each of the 6 onInit steps + error paths
• 2.16 src/index.ts — named re-exports only

3. Tests

• 3.1 Co-located *.test.ts per spec scenario
• 3.2 src/api-plugin-auth.spec-conformance.test.ts — every AUTH.* code thrown; expectTypeOf on Principal, AuthService, ContextVariableMap augmentation
• 3.3 tests/integration/full-boot.test.ts — real PluginRegistry + MigrationRunner + OpenAPIRegistry + SurrealDB testcontainer. Full sign-up → sign-in → /session → sign-out roundtrip
• 3.4 tests/integration/openapi-doc.test.ts — served /openapi.json includes all 9 auth routes with Zod-typed schemas
• 3.5 tests/integration/schema-idempotency.test.ts — restart plugin twice; schema re-apply succeeds without breaking existing rows
• 3.6 tests/property.test.ts — fast-check 200 runs: arbitrary valid Principal payloads round-trip through PrincipalSchema
• 3.7 tests/dep-graph.test.ts — deps + 15 subpaths + sibling .md per schemas/routes/*
• 3.8 All tests via @suaveplan/testing/runner, { timeout: 5000 } (60000 for integration)

4. Documentation

• 4.1 Sibling .md per impl (≥200 words)
• 4.2 README.md — quick-start using defineApp().use(createAuthPlugin({ betterAuth: { … } })); the 3-way plug-and-play contract explained with the auth plugin as the canonical example; requireAuth/requireRole recipes; OAuth provider config; schema apply / migrations integration notes

5. Gates

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-auth --force
• 5.2 Coverage 100/100/100/100
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-auth exit 0
• 5.4 Build green
• 5.5 bunx turbo test --filter=...@suaveplan/api-plugin-auth --force — dependent sweep (relevant once api-plugin-user + api-plugin-vault exist; harmless until then)
• 5.6 Banned-pattern grep + no export * + no direct vitest/bun:test imports

6. Archive

• 6.1 Fold spec → openspec/specs/api-plugin-auth/spec.md
• 6.2 mv change → openspec/archive/<date>-add-api-plugin-auth/
• 6.3 DO NOT refresh MANIFEST or STATUS — orchestrator consolidates after the 4-package batch