auth-client Package Skill

Package: @epicdm/auth-client Repository: flowstate-platform Path: packages/shared/auth-client Version: 0.1.0

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

Primary Package Workflow

Auth Client OIDC PKCE Workflow

Status: Active Purpose: Keep FlowState app login flows consistent with the shared OIDC client. Scope: packages/shared/auth-client Trigger: An app login/callback flow or shared auth-client behavior needs to change. Input: Issuer URL, client ID, redirect URI, optional scopes, optional client secret, callback code, nonce, and code verifier. Output: Correct authorization URL, token exchange, and verified ID token claims.

Workflow

Create the client with createAuthClient({ issuerUrl, clientId, redirectUri, scopes, clientSecret }).
On login, call buildAuthorizationUrl() and persist state, nonce, and codeVerifier in the app's secure callback storage before redirecting.
On callback, validate returned state in the consuming app, then call exchangeCode(code, codeVerifier).
Verify the returned ID token with verifyIdToken(idToken, nonce, kv?). This fetches JWKS, requires RS256, verifies signature, and checks issuer, audience, expiration, and nonce.
Use fetchJWKS(kv?) only when a caller explicitly needs key material; prefer verifyIdToken for login.
Before changing the API, check consumers with rg "createAuthClient" packages --glob '!**/node_modules/**'.

Verification

yarn workspace @epicdm/auth-client test
yarn workspace @epicdm/auth-client typecheck
yarn workspace @epicdm/auth-client lint

Red Flags

Red flag	Required action
State, nonce, or code verifier not persisted	Fix the consuming app flow before callback exchange.
Non-RS256 ID token accepted	Preserve the algorithm check in `verifyIdToken`.
Issuer or audience skipped	Keep both checks strict.
JWKS fetched on every request despite KV availability	Pass KV where the runtime supports it.

Composition

Use flowstate-identity-oidc-auth-workflow when changing the issuer-side OIDC routes.
Use app-local skills for session cookie or profile persistence after ID token verification.

Package Skill Inventory

Skill Inventory: @epicdm/auth-client

Created Skills

Skill	Type	Trigger
`auth-client-oidc-pkce-workflow`	Workflow	Use when integrating or changing shared OIDC/PKCE auth-client behavior.

Candidate Future Skills

Candidate	Reason to Split Later
`auth-client-jwks-verification`	JWKS caching and RS256 verification may need deeper troubleshooting if key rotation changes.
`auth-client-app-callbacks`	Consumer app callback/session storage can become a cross-app implementation pattern.

Source Evidence

src/index.ts implements client creation, PKCE URL generation, token exchange, JWKS fetch, and ID token verification.
src/__tests__/auth-client.test.ts verifies authorization URL and scope behavior.
Downstream src/lib/oidc/client.ts files import createAuthClient.

Review Gate

Review: @epicdm/auth-client Skills

Result: Pass for source-backed package-local workflow guidance.

Checks

The skill teaches the exact OIDC/PKCE state machine and verification invariants.
It cites source, tests, and downstream app consumers.
Verification commands are package-local and lightweight.
Generated .flowstate/dojo files were not modified.

Residual Risk

Callback/session persistence differs by app and may need app-local skills rather than expansion here.

flowstate-flowstate-platform-epicdm-auth-client

Tags

Publisher

Versions

Skill