feat: added FPApiToken decode without verify

[mabels]

Summary by CodeRabbit

• New Features
  • Added token decoding to extract and return structured claims for dashboard API tokens, including support for both clerk and device-id token types.
• Chores
  • Updated development CLI to point to the dev dashboard API endpoint.
• Tests
  • Expanded test coverage for token decoding and related authentication flows.

[coderabbitai]

Walkthrough

Adds a new async decode(token: string) API to token protocol interfaces and implementations, parsing token structure (via jose's decode utilities), validating parsed claims with ClerkClaimSchema where applicable, and returning a VerifiedClaimsResult without performing full signature verification. Tests and mocks updated accordingly.

Changes

Cohort / File(s)	Summary
Token Types core/types/protocols/dashboard/token.ts	Adds decode(token: string): Promise<Result<VerifiedClaimsResult>> to the FPApiToken interface alongside verify.
Token Implementations core/protocols/dashboard/token.ts	Implements decode on ClerkApiToken and DeviceIdApiToken. Uses decodeJwt / decodeProtectedHeader (jose) to parse token structure, then validates claims with ClerkClaimSchema (Clerk token) or validates embedded creatingUser.claims (Device ID).
Tests — auth handler mocks dashboard/backend/tests/auth-handler.test.ts	Adds decode method to mocked clerk in test setup to return Result<VerifiedClaimsResult>, mirroring existing verify behavior.
Tests — token decoding core/tests/protocols/dashboard/clerk-dash-api.test.ts	Adds tests for ClerkApiToken.decode and DeviceIdApiToken.decode, plus related imports and test harness adjustments (ensureSuperThis, DeviceIdCA, clockTolerance).
CLI config cloud/3rd-party/cli-fp.ts	Updates dashboard API URL to https://dev.connect.fireproof.direct/api (commented localhost alternative remains).
Manifest package.json	Minor manifest changes referenced by tests (small edit).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• refactor: reorganize type definitions and enhance authentication fram… #1515: Introduced/extracted ClerkClaimSchema and related dashboard/device-id token refactors; strongly related to the token decode and claim-validation changes in this PR.

Suggested reviewers

• jchris

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a decode method to the FPApiToken interface and implementations that performs token decoding without requiring the verify step.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch mabels/added-decode-jwt

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@core/protocols/dashboard/token.ts`:
- Around line 128-136: The decode method in token.ts calls decodeJwt which can
throw on malformed tokens; wrap the decodeJwt call with exception2Result so that
exceptions are converted into a Result.Err instead of an unhandled rejection.
Update the async decode(token: string) in the token.ts file to use
exception2Result(() => decodeJwt(token)) (or equivalent) and handle the Result
to return Result.Ok({...}) on success or propagate/return Result.Err on failure;
reference the decode function and decodeJwt and use the same exception2Result
helper pattern used in ClerkApiToken.decode.
- Around line 50-61: In decode, wrap the call to decodeJwt in the same
exception-to-Result pattern used by verify (use exception2Result or equivalent)
so malformed tokens return Result.Err instead of throwing, and adjust the value
passed to FPClerkClaimSchema.safeParse to match the schema shape (wrap the
decoded payload as { payload: decodedPayload } and include protectedHeader if
required); if the header is needed, obtain it with decodeProtectedHeader or use
jwtDecode(..., { complete: true }) before parsing — mirror how
verify/verifyToken constructs and parses the object so
FPClerkClaimSchema.safeParse succeeds.

🧹 Nitpick comments (1)

dashboard/backend/tests/auth-handler.test.ts (1)

51-58: No test exercises the new decode path.

The mock is added to satisfy the interface, but there's no test case that actually calls decode. Consider adding a test to verify the decode-without-verify behavior, especially since it's the feature being introduced.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@core/tests/protocols/dashboard/clerk-dash-api.test.ts`:
- Around line 129-158: The test uses a hardcoded real JWT with PII; replace it
with a synthetic token constructed at test runtime (not committed) that has fake
claims so ClerkApiToken.decode(clerkToken) still parses structure: create a
minimal unsigned/signed JWT via jose.SignJWT or by base64url-encoding a fake
header and payload (claims like email: "test@example.com", name: "Test User",
userId: "test_user", image_url: "https://example.com/img.png") and a dummy
signature, assign it to the clerkToken variable, then run the same assertions
against the synthetic claims so the test verifies decode() behavior without
exposing real PII.

🧹 Nitpick comments (2)

core/tests/protocols/dashboard/clerk-dash-api.test.ts (2)

163-166: Casting {} as DeviceIdCA is acceptable here since decode never touches it.

This works for the decode-only test path, but consider adding a brief comment (e.g., // unused by decode()) so future readers don't wonder if this is a bug.

---

126-127: ensureSuperThis() called at describe-block scope — works but is unconventional.

Typically test scaffolding is set up inside beforeAll/beforeEach. Since ensureSuperThis() is synchronous, this works fine here. Just noting for awareness — if it ever becomes async or has side effects that need teardown, this would need to move.