flowstate-auth-server Package Skill

Package: @epicdm/flowstate-auth-server Repository: epic-flowstate-community Path: packages/flowstate-auth-server Version: 1.0.0

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState Auth Server Auth Middleware

Status: Active Purpose: Guide authentication and authorization middleware changes. Scope: src/middleware/requireAuth.ts, requireScope.ts, and validation middleware. Trigger: Need to protect routes, debug 401/403 responses, or change request auth data. Input: Authorization header, token manager, storage adapter, domain id, required scopes/roles. Output: Correct req.authData and scope/role authorization behavior.

Authentication

createRequireAuth(tokenManager, storage, domainId) expects:

Authorization: Bearer <token>

Supported token forms:

• JWT access token beginning with eyJ.
• Service JWT verified through verifyServiceToken.
• API token beginning with epic_, validated against stored bcrypt hashes.

On success, middleware attaches authData to the request.

Org Fallback

If token auth data has no orgId, middleware checks x-org-id and fills it. This supports multi-org mode where JWTs may not carry a single org id.

Authorization

createRequireScope(...required) permits access when:

• A required flat scope is in authData.scopes.
• A required role specifier exactly matches a role claim.
• A required role specifier prefixes a role claim, such as role:owner matching role:owner:org:org_1.

Failures return 403 with required specifiers.

Change Checklist

1. Keep missing/malformed auth responses consistent with the 401 shape.
2. Preserve JWT and epic_ API token support unless a breaking change is approved.
3. Preserve x-org-id fallback unless multi-org model changes.
4. Update middleware tests:
   • middleware.test.ts
   • validate-middleware.test.ts
   • scopes.test.ts
5. Check protected route tests for status-code impact.

Verification

yarn workspace @epicdm/flowstate-auth-server test --runInBand src/__tests__/middleware.test.ts src/__tests__/validate-middleware.test.ts src/__tests__/scopes.test.ts
yarn workspace @epicdm/flowstate-auth-server typecheck

Composition Notes

• Use flowstate-auth-server-rbac-admin for protected route behavior.
• Use flowstate-auth-core package skills when changing token manager/storage contracts.

Created: 2026-06-29

Package Skill Inventory

@epicdm/flowstate-auth-server Skill Inventory

Repository: epic-flowstate-community Package path: packages/flowstate-auth-server Package: @epicdm/flowstate-auth-server Inventory date: 2026-06-29

Skill Map

Composition

Start with flowstate-auth-server. Then use focused skills based on route family or operational concern.

Avoid one skill per route file. The agent task is usually flow-level: OAuth, passwordless login, RBAC/admin, middleware, or runtime wiring.

Review Gate

@epicdm/flowstate-auth-server Skills Review

Review date: 2026-06-29 Verdict: Pending verification; local skill coverage is complete for reviewed package behavior.

Coverage Check

• Package purpose and route family map are covered in flowstate-auth-server.
• Runtime config, boot, storage, mail, and observability are covered in flowstate-auth-server-runtime-config.
• OAuth PKCE, DCR, well-known metadata, token exchange, introspection, and revocation are covered in flowstate-auth-server-oauth-pkce.
• Email-code login and refresh are covered in flowstate-auth-server-email-auth.
• RBAC/admin routes are covered in flowstate-auth-server-rbac-admin.
• Authentication and authorization middleware are covered in flowstate-auth-server-auth-middleware.
• Downstream package impact is covered in flowstate-auth-server-consumer-integration.
• Docs, schemas, feature matrix, Dojo, and verification upkeep are covered in flowstate-auth-server-maintenance.

Quality Notes

• Skills group 160 detected features into operational workflows.
• Skills call out route order and test-mode wiring as high-risk source details.
• Skills identify generated Dojo files as prototypes rather than publishable training content.
• Skills/review clarify package exports versus source-level helpers.
• Skills/review document curated feature matrix versus generated Dojo coverage.

Verification

Skill-file checks run:

find packages/flowstate-auth-server/.flowstate/skills -name 'SKILL.md' -print
rg '^---$|^name:|^description: Use when' packages/flowstate-auth-server/.flowstate/skills
LC_ALL=C rg -n '[^\x00-\x7F]' packages/flowstate-auth-server/.flowstate/skills

Results:

• Eight SKILL.md files found.
• Frontmatter pattern present for all skills.
• ASCII scan passed.

Package verification run:

yarn workspace @epicdm/flowstate-auth-server test --runInBand --no-cache
yarn workspace @epicdm/flowstate-auth-server typecheck
yarn workspace @epicdm/flowstate-auth-server build
yarn workspace @epicdm/flowstate-auth-server lint
yarn nx build @epicdm/flowstate-auth-server

Results:

• test --runInBand --no-cache passed: 44 suites, 589 tests, with expected structured logger console output.
• typecheck passed.
• build passed and emitted CJS, ESM, and DTS outputs. DTS output is a tiny export artifact because the built entry is src/index.ts.
• lint failed with 2 existing no-extra-semi errors and 193 warnings. Errors were in src/__tests__/service-accounts.test.ts:50 and src/routes/oauth-providers.routes.ts:185.
• nx build passed for auth-server and 10 dependency tasks; Nx Cloud reported the existing unconnected-workspace 401.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-auth-server/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.