npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sprigr/apps-pending-oauth

v0.2.0

Published

Single-use, TTL'd OAuth handshake state in a per-install D1 table, plus completion markers so a replayed callback reports already_connected.

Readme

@sprigr/apps-pending-oauth

Single-use, TTL'd pending-OAuth CSRF state in a per-install D1 table.

Ten marketplace apps each carried a hand-copied version of this store. The copies had drifted in field sets and stale comments (issue sprigr/sprigr-apps#544). The mechanism now lives here once, parameterised by table name; each app keeps its own table and its own payload shape.

Table shape

Apps own the migration. The store expects exactly these columns:

CREATE TABLE <app>_pending_oauth (
  csrf       TEXT PRIMARY KEY,
  payload    TEXT NOT NULL,
  created_at INTEGER NOT NULL
);

Use

Depend on the published package at an exact version:

{ "dependencies": { "@sprigr/apps-pending-oauth": "0.2.0" } }

Then wire it up in src/lib/pending-oauth.ts, which pins the table name and the payload type and re-exports the three functions the call sites already use:

import type { D1Like } from '@sprigr/apps-app-sdk';
import { makePendingOAuthStore, DEFAULT_PENDING_TTL_MS } from '@sprigr/apps-pending-oauth';

export const PENDING_TTL_MS = DEFAULT_PENDING_TTL_MS;

export interface PendingState {
  csrf: string;
  actorPlatformUserId: string | null;
  actorAgentId: string | null;
  iat: number;
}

const store = (db: D1Like) =>
  makePendingOAuthStore<PendingState>({ db, table: 'myapp_pending_oauth' });

export const storePendingOAuth = (db: D1Like, state: PendingState): Promise<void> =>
  store(db).store(state);
export const consumePendingOAuth = (db: D1Like, csrf: string): Promise<PendingState | null> =>
  store(db).consume(csrf);
export const trimExpiredPending = (db: D1Like): Promise<void> => store(db).trimExpired();

Completion markers (second table, required)

Because consume deletes on read, a second delivery of a callback whose connect already WORKED looks exactly like a forged, unknown or expired state. Users re-open callback URLs and browsers restore tabs, so that benign case is the common one, and a refusal page there makes people believe a working connection is broken (microsoft-365, 2026-09-22). makeOAuthCompletions records sha-256(csrf) when a connect succeeds, so the callback can report already_connected instead.

Every app that uses this package should wire them. The platform's OAuth bouncer shows its "already connected" page only for a callback result with ok: false and reason: 'already_connected'; any other shape keeps the red failure page.

The app adds its own table in a new migration:

CREATE TABLE IF NOT EXISTS myapp_oauth_completions (
  csrf_hash    TEXT PRIMARY KEY,
  completed_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_myapp_oauth_completions_at
  ON myapp_oauth_completions(completed_at);

and wires it in the same src/lib/pending-oauth.ts shim:

import { makeOAuthCompletions } from '@sprigr/apps-pending-oauth';

const completions = (db: D1Like) =>
  makeOAuthCompletions({ db, table: 'myapp_oauth_completions' });

export const recordOAuthCompletion = (db: D1Like, csrf: string): Promise<void> =>
  completions(db).record(csrf);
export const wasRecentlyCompleted = (db: D1Like, csrf: string, windowMs?: number): Promise<boolean> =>
  completions(db).wasRecentlyCompleted(csrf, windowMs);
export const trimExpiredCompletions = (db: D1Like): Promise<void> => completions(db).trimExpired();

In the callback: call recordOAuthCompletion as soon as the tokens are written (not at the end of the handler, which is the part that gets cut off), consult wasRecentlyCompleted ONLY after consumePendingOAuth returned null, and turn a hit into a reported failure (ok: false, already_connected) with no exchange and no write. A miss must fall through to the app's existing refusal unchanged. Trim alongside trimExpiredPending.

Why this cannot weaken the csrf gate: only the hash is stored, so nothing in the table can be presented back as state; a hit never grants anything; and the pending row's lifetime is untouched. Every operation is best-effort and never throws. The answer window is 1 hour (COMPLETION_WINDOW_MS) and markers are swept after 24 hours (COMPLETION_TRIM_MS). The full reasoning is in src/completions.ts.

Refusal markers (third table)

A callback that refuses AFTER consume (an agent bind of someone's own account, an ineligible installation, a failed code exchange) has burned the pending row, so a reload of it used to read as invalid_oauth_state and the refusal's hint was lost. makeOAuthRefusals keeps the refusal result, keyed by sha-256(csrf), so the reload repeats it.

CREATE TABLE IF NOT EXISTS myapp_oauth_refusals (
  csrf_hash  TEXT PRIMARY KEY,
  reason     TEXT NOT NULL,
  refused_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_myapp_oauth_refusals_at
  ON myapp_oauth_refusals(refused_at);

Start the callback with consumeOAuthCallback, which consumes the row or says why it is missing, in this order: completed, refused, unknown.

const outcome = await consumeOAuthCallback({
  csrf,
  consume: (c) => consumePendingOAuth(env.DB, c),
  completions: makeOAuthCompletions({ db: env.DB, table: 'myapp_oauth_completions' }),
  refusals: makeOAuthRefusals<CallbackRefusal>({ db: env.DB, table: 'myapp_oauth_refusals' }),
});
if (outcome.kind === 'already_connected') return { ok: false, reason: 'already_connected' };
if (outcome.kind === 'refused') return outcome.refusal;
if (outcome.kind === 'unknown') return { ok: false, reason: 'invalid_oauth_state' };
const { pending, refuse } = outcome;
// every later refusal, including the catch-all:
return refuse({ ok: false, reason: 'agent_bind_refused: ...' });

refuse exists only once the row was consumed, so a csrf the install never minted cannot write a marker. The whole result object is stored as JSON, so any refusal shape replays exactly. Refusals before the consume need no marker: a reload gets the same answer anyway. Trim with makeOAuthRefusals(...).trimExpired() alongside trimExpiredPending. Same window and sweep as completions.

Two things not to "tidy"

  1. consume deletes the row BEFORE comparing the TTL. A presented csrf is burned even when the row has already expired. Returning early on an expired row without deleting it reopens replay of expired state.
  2. An app with a second, longer consume window must pass trimTtlMs. microsoft-365 consumes admin-consent rows at 7 days; trimming at the 24h default would delete live admin-consent rows out from under the IT admin.