60 lines
4.9 KiB
Markdown
60 lines
4.9 KiB
Markdown
# Tasks — add-api-plugin-auth
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] 1.1 Create `packages/api/api-plugin-auth/` with `src/{plugin,middleware,principal,services,schemas,routes,schema,error-codes,otel,types}/` + `tests/{setup,integration}/`
|
|
- [x] 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`)
|
|
- [x] 1.3 15 subpath exports per the proposal
|
|
- [x] 1.4 tsconfigs + vite + vitest (100/100/100/100, testTimeout 60000 for integration)
|
|
- [x] 1.5 `tests/setup/polyfills.ts`
|
|
|
|
## 2. Implementation
|
|
|
|
- [x] 2.1 `src/error-codes.{ts,test.ts,md,index.ts}` — 10 AUTH.* codes + `AuthError`
|
|
- [x] 2.2 `src/principal/principal.{ts,test.ts,md,index.ts}` — `Principal` interface + `mapBetterAuthUserToPrincipal` default
|
|
- [x] 2.3 `src/schemas/principal.{ts,test.ts,md,index.ts}` — `PrincipalSchema`, `SessionSchema`, `AccountSchema` (Zod)
|
|
- [x] 2.4 `src/schemas/options.{ts,test.ts,md,index.ts}` — `AuthPluginOptionsSchema`
|
|
- [x] 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`
|
|
- [x] 2.6 `src/otel/instruments.{ts,test.ts,md,index.ts}` — counters + histogram
|
|
- [x] 2.7 `src/services/auth-service.{ts,test.ts,md,index.ts}` — `AuthService` interface + impl; `ServiceRegistry` module augmentation
|
|
- [x] 2.8 `src/middleware/require-auth.{ts,test.ts,md,index.ts}` — `requireAuth()` factory
|
|
- [x] 2.9 `src/middleware/require-role.{ts,test.ts,md}` — `requireRole(...)` factory
|
|
- [x] 2.10 `src/middleware/require-email-verified.{ts,test.ts,md}` — `requireEmailVerified()` factory
|
|
- [x] 2.11 `src/middleware/session.{ts,test.ts,md}` — global session-resolver middleware (sets `c.set("user")` + `c.set("session")`; Hono `ContextVariableMap` augmentation)
|
|
- [x] 2.12 `src/routes/build-routes.{ts,test.ts,md,index.ts}` — `buildAuthRoutes(auth)` returning `PluginRouteEntry[]` via `RouteBuilder`
|
|
- [x] 2.13 `src/schema/schema.{ts,md,index.ts}` — re-export `BETTER_AUTH_SURREAL_SCHEMA` + `applyBetterAuthSchema` from `@suaveplan/better-auth-surrealdb`
|
|
- [x] 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
|
|
- [x] 2.15 `src/plugin/on-init.test.ts` — covers each of the 6 onInit steps + error paths
|
|
- [x] 2.16 `src/index.ts` — named re-exports only
|
|
|
|
## 3. Tests
|
|
|
|
- [x] 3.1 Co-located `*.test.ts` per spec scenario
|
|
- [x] 3.2 `src/api-plugin-auth.spec-conformance.test.ts` — every AUTH.* code thrown; `expectTypeOf` on `Principal`, `AuthService`, `ContextVariableMap` augmentation
|
|
- [x] 3.3 `tests/integration/full-boot.test.ts` — real `PluginRegistry` + `MigrationRunner` + `OpenAPIRegistry` + SurrealDB testcontainer. Full sign-up → sign-in → /session → sign-out roundtrip
|
|
- [x] 3.4 `tests/integration/openapi-doc.test.ts` — served `/openapi.json` includes all 9 auth routes with Zod-typed schemas
|
|
- [x] 3.5 `tests/integration/schema-idempotency.test.ts` — restart plugin twice; schema re-apply succeeds without breaking existing rows
|
|
- [x] 3.6 `tests/property.test.ts` — fast-check 200 runs: arbitrary valid Principal payloads round-trip through `PrincipalSchema`
|
|
- [x] 3.7 `tests/dep-graph.test.ts` — deps + 15 subpaths + sibling .md per schemas/routes/*
|
|
- [x] 3.8 All tests via `@suaveplan/testing/runner`, `{ timeout: 5000 }` (60000 for integration)
|
|
|
|
## 4. Documentation
|
|
|
|
- [x] 4.1 Sibling `.md` per impl (≥200 words)
|
|
- [x] 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
|
|
|
|
- [x] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-auth --force`
|
|
- [x] 5.2 Coverage 100/100/100/100
|
|
- [x] 5.3 `bun scripts/openspec-conformance.ts @suaveplan/api-plugin-auth` exit 0
|
|
- [x] 5.4 Build green
|
|
- [x] 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)
|
|
- [x] 5.6 Banned-pattern grep + no `export *` + no direct vitest/bun:test imports
|
|
|
|
## 6. Archive
|
|
|
|
- [x] 6.1 Fold spec → `openspec/specs/api-plugin-auth/spec.md`
|
|
- [x] 6.2 mv change → `openspec/archive/<date>-add-api-plugin-auth/`
|
|
- [x] 6.3 DO NOT refresh MANIFEST or STATUS — orchestrator consolidates after the 4-package batch
|