feat(auth): revocation-aware token introspection — POST /api/v1/auth/introspect (TODO item 4) by lopugit · Pull Request #116 · lopugit/thingtime

lopugit · 2026-07-21T04:28:10Z

Implements TODO.md item 4: external platforms can already verify Thingtime JWTs offline via /api/v1/auth/jwks, but offline verification cannot see server-side revocation. This adds the live-status check.

What changed

POST /api/v1/auth/introspect (new route, RFC 7662 shape): accepts the token in the JSON body ({ "token": "…" }) or as an Authorization: Bearer header. Verifies the signature via the existing verifyJwt, then checks the Mongo session (getLiveSession): exists, not revoked, not expired, userId matches sub, and the user still exists / service-account auth still allowed.
introspectToken in api/utils/auth/getCurrentUser.ts — the logic lives in the utils layer beside resolveTokenUser (FUNDAMENTALS: data access through the utils layer). Deliberate difference from resolveSessionUser: it also reports purpose: 'app' sessions, because external "Login with Thingtime" platforms are the primary caller and introspection only reports status — it never grants the credential any capability.
No oracle: inactive tokens return a bare { active: false } with no reason. Active tokens return sub, jti, purpose, iat/exp (epoch seconds; exp: null = non-expiring), iss. Cache-Control: no-store on all responses.
Authorization model: possession of the token — you can only ask about tokens you already hold (consistent with the SSO default-open origins decision in PR Thingtime SSO: default-open origins — any URL (incl. preview deploys) can use Login with Thingtime #87). Per-IP rate limit via the shared limiter (auth.introspect: 120/min, admin-tunable like every other key).
Registered in the Nitro dispatcher, documented on /docs/api (auto-serves /api/v1/auth/introspect-docs), and covered in apiTests.ts (missing token → 400; unverifiable token → bare { active: false }).

Verified live (worktree dev stack, 127.0.0.1:13930)

Missing token → 400 with guidance; garbage token → { active: false } (body and Bearer variants).
Registered a throwaway user via the real POST /api/v1/auth/register (per FUNDAMENTALS seeding rule) → introspect returned active: true with correct sub/jti/purpose: "browser"/iat/exp/iss.
Revocation: POST /api/v1/auth/logout → the same token now introspects { active: false }.
/tests page: both new tests pass in the Auth group run. Two unrelated failures in that run are parallel-session environment artifacts (another session's cookie on the shared 127.0.0.1 cookie jar breaks the "anonymous" expectation, and the shared per-IP resend-verification window was already exhausted → 429).
/docs/api renders the new "Token introspection" entry.

🤖 Generated with Claude Code

gitguardian · 2026-07-21T04:28:15Z

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
35008687	Triggered	Generic High Entropy Secret	`c98e2ff`	remix/app/docs/apiDocs.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

Understand the implications of revoking this secret by investigating where it is used in your code.
Replace and store your secret safely. Learn here the best practices.
Revoke and rotate this secret.
If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

following these best practices for managing and storing secrets including API keys and other credentials
install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

vercel · 2026-07-21T04:28:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
thingtime	Ready	Preview	Aug 23, 2026 9:07am
thingtime (develop)	Ready	Preview	Aug 23, 2026 9:07am

lopugit · 2026-07-30T12:02:42Z

Consolidation note: this is now the single TODO-4 PR. Chosen over #114/#117/#120 because its introspectToken deliberately reports purpose:'app' sessions — external Login-with-Thingtime platforms are introspection's primary caller, and the resolveTokenUser/resolveSessionUser paths the other PRs reuse default-deny purpose-scoped sessions (they would report active:false for exactly the tokens that matter). Also returns purpose + iss with the RFC 7662 bare {active:false} no-oracle shape. #114, #117, #120 closed as duplicates.

github-actions · 2026-07-30T13:26:27Z

🤝 Merged main into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

Conflicted files:

remix/app/api/utils/rateLimit/config.ts

Please review the merge commit before relying on it.

github-actions · 2026-08-07T06:08:22Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

Conflicted files:

remix/app/api/utils/rateLimit/config.ts

Please review the merge commit before relying on it.

github-actions · 2026-08-08T01:34:12Z

🧬 Rebased claude/auth-token-introspection-s6 onto develop with the AI PR/stack rebase workflow.

Previous head: f7173077c38e80ce5387a38cc6c8c7197cac29e0
Rewritten head: 16f7644d6b2af9367f0e654144b60617ec4fb3d3
graphify: refreshed and committed (semantic mode: none)
Direct stacked children dispatched: 0

The branch was published once with an exact force-with-lease. Please review the rewritten commits before relying on them.

github-actions · 2026-08-09T08:38:47Z

🤖 Auto-resolve running — the conflict resolver started working on this PR at 14:30 UTC.

Expected to finish around 14:38 UTC (resolutions typically land in 3-8 minutes; the job times out at 30). On success a merge commit resolving the conflicts is pushed to this branch and a result comment follows — no manual action is needed meanwhile.

Live status

github-actions · 2026-08-09T08:47:08Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

Conflicted files:

graphify-out/GRAPH_REPORT.md
graphify-out/graph.json
graphify-out/manifest.json
remix/app/api/utils/rateLimit/config.ts

Please review the merge commit before relying on it.

github-actions · 2026-08-09T08:55:27Z

🤖 Auto-rebase running — the stack rebase started working on this PR at 12:34 UTC.

Expected to finish around 12:49 UTC (most rebases still land in 5-15 minutes; the hosted-runner ceiling is 360). On success this branch is force-pushed onto its new base and a result comment follows — no manual action is needed meanwhile.

Live status

github-actions · 2026-08-09T08:59:56Z

🧬 Rebased claude/auth-token-introspection-s6 onto develop with the AI PR/stack rebase workflow.

Previous head: 246c948591900c7fe6bebbea0e7b005d06706548
Rewritten head: d7a7c6e84b26697d4c687da2b62183a46f7b0142
graphify: refreshed and committed (semantic mode: none)
Direct stacked children dispatched: 0

The branch was published once with an exact force-with-lease. Please review the rewritten commits before relying on them.

github-actions · 2026-08-09T11:47:38Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

github-actions · 2026-08-21T04:45:40Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/cache/semantic/66a986879eae83885e86f6094b6b9c67714e4c2f256edd157db885d9b5fa3772.json # graphify-out/cache/semantic/9472c3b491d798863284f2ee76417b9e548102934fab1c26c939c174263aece7.json # graphify-out/cache/semantic/9d941bc0e7934417a20121e81239551aeb78e32a69110b1c863c1d39ae6315fd.json # graphify-out/cache/semantic/a7bb429ccfa80a835eaada037544d54c6b485760f4a81f9425bd0a2c55f9abf5.json # graphify-out/cache/semantic/bad9f54f0b45f717512b05260481bacd21cb0c3fa0c31eab8a26993349b4261b.json # graphify-out/cache/semantic/f1a8d1b8925dafdff51f3774815b93fa71d531dc21b2eb632f9ecc2d46c245e1.json # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32448001629

github-actions · 2026-08-21T05:11:24Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

… — POST /api/v1/auth/introspect (TODO item 4)

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32449178062

github-actions · 2026-08-21T06:00:51Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32452631143

github-actions · 2026-08-21T07:06:33Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/cache/semantic/03d4bef600057c8f0d44c78d9048b84998a642fe21cc953224d6cdde139c62b8.json # graphify-out/cache/semantic/0658eddb308e398d6cef9abc1f7274e397f032dd5abbf8c87ddff06b0586fa83.json # graphify-out/cache/semantic/384333055645511b027a58e7515a6c9852c1a50fcd245e590590ce28e20e8ee7.json # graphify-out/cache/semantic/d4a698266a3959f926c076a5dba885ee86ccb7906d6d9d29f3a490562135fe20.json # graphify-out/graph.json # graphify-out/manifest.json

AST/text-only `graphify update` (graphify 0.9.4, no semantic extraction); run graphify locally with an LLM backend if semantic data is needed. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32457149963

github-actions · 2026-08-21T08:07:22Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32461677790

github-actions · 2026-08-21T09:08:29Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32466414690

github-actions · 2026-08-21T09:49:39Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

No AI resolution was needed by merge time; the branch was updated with a plain merge commit.

Please review the merge commit before relying on it.

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32469692868

github-actions · 2026-08-23T08:40:47Z

🤝 Merged develop into claude/auth-token-introspection-s6 — conflicts auto-resolved by the resolve-pr-conflicts workflow.

Conflicted files:

graphify-out/GRAPH_REPORT.md
graphify-out/graph.json
graphify-out/manifest.json
remix/server/routes/api/[...].ts

Please review the merge commit before relying on it.

…nflicts) Conflicted paths: graphify-out/GRAPH_REPORT.md, graphify-out/graph.json, graphify-out/manifest.json, remix/server/routes/api/[...].ts Resolved by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32628861456 Co-Authored-By: Claude <noreply@anthropic.com>

`graphify extract` with LLM semantic extraction (graphify 0.9.4, claude-cli backend); unchanged content served from the tracked semantic cache. Refreshed by the resolve-pr-conflicts workflow: https://github.com/lopugit/thingtime/actions/runs/32628861456

lopugit mentioned this pull request Jul 21, 2026

feat: Vercel deployment webhook replaces steady-state status polling (TODO 5) #118

Closed

vercel Bot deployed to Preview July 21, 2026 04:41 View deployment

vercel Bot deployed to Preview July 21, 2026 06:06 View deployment

vercel Bot deployed to Preview July 26, 2026 12:39 View deployment

This was referenced Jul 30, 2026

feat(auth): revocation-aware token introspection endpoint (TODO #4) #114

Closed

feat(auth): revocation-aware token introspection endpoint (TODO 4) #117

Closed

feat: revocation-aware token introspection endpoint (TODO #4) #120

Closed

vercel Bot deployed to Preview July 30, 2026 13:27 View deployment

lopugit changed the base branch from main to develop August 6, 2026 06:53

vercel Bot deployed to Preview August 7, 2026 06:11 View deployment

github-actions Bot added the ai-rebase-in-progress AI stack rebase currently owns this PR branch label Aug 8, 2026

lopugit force-pushed the develop branch from 972c5ee to 4d2defc Compare August 8, 2026 01:27

github-actions Bot removed the ai-rebase-in-progress AI stack rebase currently owns this PR branch label Aug 8, 2026

lopugit force-pushed the claude/auth-token-introspection-s6 branch from f717307 to 16f7644 Compare August 8, 2026 01:34

vercel Bot deployed to Preview August 8, 2026 01:51 View deployment

github-actions Bot added the ai-rebase-in-progress AI stack rebase currently owns this PR branch label Aug 9, 2026

github-actions Bot removed the ai-rebase-in-progress AI stack rebase currently owns this PR branch label Aug 9, 2026

lopugit force-pushed the claude/auth-token-introspection-s6 branch from 246c948 to d7a7c6e Compare August 9, 2026 08:59

vercel Bot deployed to Preview August 9, 2026 09:15 View deployment

github-actions Bot added 2 commits August 21, 2026 04:47

vercel Bot deployed to Preview August 21, 2026 04:56 View deployment

github-actions Bot temporarily deployed to develop-pr-116 August 21, 2026 04:59 Destroyed

github-actions Bot added a commit that referenced this pull request Aug 21, 2026

all: merge PR #116 — feat(auth): revocation-aware token introspection…

170d593

… — POST /api/v1/auth/introspect (TODO item 4)

Merge branch 'develop' into claude/auth-token-introspection-s6

b19910e

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

vercel Bot deployed to develop August 21, 2026 05:15 View deployment

github-actions Bot temporarily deployed to develop-pr-116 August 21, 2026 05:22 Destroyed

vercel Bot deployed to Preview August 21, 2026 05:34 View deployment

github-actions Bot added 2 commits August 21, 2026 06:03

Merge branch 'develop' into claude/auth-token-introspection-s6

0044730

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

github-actions Bot added 2 commits August 21, 2026 07:08

github-actions Bot added 2 commits August 21, 2026 08:09

Merge branch 'develop' into claude/auth-token-introspection-s6

aad5147

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

github-actions Bot added 2 commits August 21, 2026 09:10

Merge branch 'develop' into claude/auth-token-introspection-s6

cbfe384

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

github-actions Bot added 2 commits August 21, 2026 09:51

Merge branch 'develop' into claude/auth-token-introspection-s6

e722234

# Conflicts: # graphify-out/GRAPH_REPORT.md # graphify-out/graph.json # graphify-out/manifest.json

github-actions Bot and others added 2 commits August 23, 2026 08:44

Conversation

lopugit commented Jul 21, 2026

What changed

Verified live (worktree dev stack, 127.0.0.1:13930)

Uh oh!

gitguardian Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Uh oh!

vercel Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lopugit commented Jul 30, 2026

Uh oh!

github-actions Bot commented Jul 30, 2026

Uh oh!

github-actions Bot commented Aug 7, 2026

Uh oh!

github-actions Bot commented Aug 8, 2026

Uh oh!

github-actions Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

github-actions Bot commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

github-actions Bot commented Aug 9, 2026

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gitguardian Bot commented Jul 21, 2026 •

edited

Loading

vercel Bot commented Jul 21, 2026 •

edited

Loading

github-actions Bot commented Aug 9, 2026 •

edited

Loading

github-actions Bot commented Aug 9, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 21, 2026 •

edited

Loading

github-actions Bot commented Aug 23, 2026 •

edited

Loading