@flytedesk/app-kit 0.8.0 → 2.0.0

package/dist/auth/types.d.ts

@@ -29,6 +29,20 @@ export interface RefreshTokenRow {
     idpSessionId: string;
     revokedAt: Date | null;
     expiresAt: Date;
+    /**
+     * AK-14 (gap 3; MP-127): whether some OTHER row's `replacesId` points at this one —
+     * i.e. this token's presentation was, at some point, followed by a successful
+     * rotation, as opposed to being revoked directly (a logout, or reuse detection
+     * itself). Only a rotated token's LATE replay (`revokedAt` already set when
+     * `findRefreshTokenByHash` read this row, outside `refreshReuseGraceMs`) can be a
+     * concurrent-tab race; `../plugin.ts`'s `POST {routePrefix}/refresh` reads this
+     * straight off the row it already fetched — never recomputed on any other code path —
+     * specifically so its answer reflects a fully-committed state, not one still
+     * in-flight in a sibling request (see that route's doc comment for why a same-instant
+     * race is instead decided entirely by `claimRefreshTokenForRotation`'s atomicity,
+     * not by this field).
+     */
+    rotated: boolean;
 }
 export interface CreateRefreshTokenInput {
     id: string;
@@ -41,6 +55,14 @@ export interface CreateRefreshTokenInput {
     idpSessionId: string;
     userAgent: string | null;
     ip: string;
+    /**
+     * The id of the refresh token this one was rotated FROM, or `null` for the first
+     * token of a family (issued at login). AK-14: this is what `RefreshTokenRow.rotated`
+     * (above) answers — see that field's doc comment and `../plugin.ts`'s
+     * `refreshReuseGraceMs` for how a late replay of a rotated token is told apart from
+     * reuse.
+     */
+    replacesId: string | null;
 }
 export interface IdpSessionRow {
     id: string;
@@ -87,17 +109,86 @@ export interface AuthStore {
      * the CALLER can't close this gap no matter how carefully it's written — the
      * atomicity has to live in this one storage operation. Never implement this as a
      * separate read followed by an unconditional write.
+     *
+     * AK-14 (gap 3; MP-127): `../plugin.ts`'s `POST {routePrefix}/refresh` only ever calls
+     * this for a token whose `findRefreshTokenByHash` read, moments earlier in the SAME
+     * request, showed `revokedAt: null` — i.e. as far as this request could tell, the
+     * token still looked live. A `false` result here therefore means a SIBLING request
+     * claimed it in the tiny window since that read: a genuine, same-instant
+     * concurrent-tab race, decided by this method's atomicity alone — unconditionally
+     * treated as a race (401, nothing revoked), with no timing/rotated check needed,
+     * exactly matching media-planner's own `updateMany({revokedAt: null}); if (count !==
+     * 1) return false` shape. A LATE replay of an already (and by now long-since)
+     * rotated-away token is a different code path entirely: it never reaches this method
+     * at all, because `findRefreshTokenByHash`'s OWN `revokedAt`/`rotated` answer (read
+     * before this is ever called) already resolves it — see that field's doc comment.
      */
     claimRefreshTokenForRotation(id: string): Promise<boolean>;
-    /** Reuse-detection path: revoke every row sharing this familyId. */
-    revokeFamily(familyId: string): Promise<void>;
+    /**
+     * Revoke every row sharing this familyId — called for reuse detection, sign-out, and
+     * an authorization rejection on refresh (see `RevokeFamilyReason`, AK-20 gap 2327).
+     * `reason` carries WHY, so a consumer's implementation can write its own audit record
+     * (e.g. media-planner's reuse-detection log) without the plugin knowing anything about
+     * that consumer's audit schema — see `RevokeFamilyReason`'s doc comment for what each
+     * variant carries.
+     */
+    revokeFamily(familyId: string, reason: RevokeFamilyReason): Promise<void>;
     createIdpSession(row: CreateIdpSessionInput): Promise<{
         id: string;
     }>;
     findIdpSession(id: string): Promise<IdpSessionRow | null>;
     updateIdpSession(id: string, patch: UpdateIdpSessionInput): Promise<void>;
     deleteIdpSession(id: string): Promise<void>;
+    /**
+     * Runs `fn` while holding an exclusive, per-session lock (AK-20, gap 2326) — a
+     * Postgres-backed store implements this with an advisory lock scoped to `sessionId`
+     * (e.g. `pg_advisory_xact_lock(hashtext(sessionId))`, taken and released within the
+     * same transaction `fn` runs in), so the lock is held across concurrent requests on
+     * different server instances, not just within one process; an in-memory store (tests,
+     * the hello-world example) can implement it with a simple per-key mutex/queue.
+     *
+     * Fixes a real race in `../plugin.ts`'s `getLiveIdpAccessToken`: flytedesk-id rotates
+     * its own refresh token on every use, so two concurrent requests on the same
+     * near-expiry session could both read "stale" before either write landed, both call
+     * `oidc.refreshIdpTokens` with the SAME (about-to-be-consumed) refresh token, and the
+     * loser's request then presents a refresh token flytedesk-id has already rotated away
+     * — getting that otherwise perfectly legitimate session signed out. Every caller of
+     * `getLiveIdpAccessToken` re-reads the session INSIDE the lock and skips its own
+     * refresh if a sibling request already refreshed it while this one was waiting.
+     */
+    withIdpSessionLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
 }
+/**
+ * Why `AuthStore.revokeFamily` (above) is revoking a family — AK-20, gap 2327. Lets a
+ * consumer's own `AuthStore` implementation write an audit record (e.g.
+ * media-planner's reuse-detection log, which records how long after rotation the reuse
+ * was observed and the requesting IP) without `../plugin.ts` knowing anything about that
+ * consumer's audit schema.
+ */
+export type RevokeFamilyReason = {
+    /** A refresh token already rotated away was presented again — either a genuine
+     *  replay/leak, or a same-cookie-jar tab's request that arrived too late to be
+     *  treated as a race (see `RefreshTokenRow.rotated`'s doc comment and
+     *  `FlytedeskAuthOptions.refreshReuseGraceMs`). */
+    type: "reuse_detected";
+    /** The refresh token row that was replayed, exactly as `findRefreshTokenByHash`
+     *  read it. */
+    replayedToken: RefreshTokenRow;
+    /** Milliseconds between `replayedToken`'s rotation and this replay. */
+    sinceRotatedMs: number;
+    ip: string;
+    userAgent: string | null;
+} | {
+    /** POST {routePrefix}/logout — the family is revoked unconditionally as part of
+     *  ending the session, independent of anything else about the request. */
+    type: "signed_out";
+} | {
+    /** POST {routePrefix}/refresh ran the SAME authorization pipeline
+     *  `loadAuthedUser` runs (live IdP authorization, `onAuthorizeUser`) and it
+     *  rejected this session — e.g. a locally-suspended user, a role flytedesk-id
+     *  since revoked, or the backing IdP session no longer existing at all. */
+    type: "authorization_rejected";
+};
 export interface FlytedeskAuthOptions {
     /** This app's OAuth client_id, as registered with flytedesk-id. */
     clientId: string;
@@ -141,4 +232,64 @@ export interface FlytedeskAuthOptions {
      *  session is issued — the hook for a consumer's own app-specific bookkeeping (e.g.
      *  upserting a local profile row, checking a local suspension flag). */
     onSignIn?: (profile: UserinfoClaims, request: FastifyRequest) => Promise<void> | void;
+    /**
+     * OAuth scopes requested at `{routePrefix}/login`. Default
+     * `["openid", "email", "profile", "offline_access"]` (AK-14, gap 1) — `offline_access`
+     * is what makes flytedesk-id's oidc-provider issue a refresh token at all; without it
+     * every session dies the moment its ~1h IdP-side access token expires (a
+     * previously-shipped production bug — see media-planner's now-superseded
+     * `lib/flytedeskId.ts`). Requesting it by default is a deliberate choice, recorded
+     * here rather than defaulted into silently: a session that dies after an hour is
+     * almost never what a consuming app wants. Override to a narrower list only for a
+     * consumer that genuinely wants access-token-lifetime sessions.
+     */
+    scopes?: string[];
+    /**
+     * Bounds EVERY flytedesk-id call this plugin's OIDC client makes — token, userinfo
+     * (`/me`), authorization (`/apps/{id}/authorization`), `/me/apps`, discovery and
+     * revocation — via `AbortSignal.timeout`, through the one bounded-request helper every
+     * one of those calls goes through (AK-20, gap 1; generalized from AK-14 gap 5, which
+     * only bounded `/token`). Default `DEFAULT_IDP_REQUEST_TIMEOUT_MS` (5s, matching
+     * media-planner's `IDP_TOKEN_TIMEOUT_MS`). A hung flytedesk-id response fails loudly
+     * with the typed `IdpTimeoutError` instead of hanging the caller indefinitely — most
+     * importantly for the authorization call, which `loadAuthedUser` (`../plugin.ts`) runs
+     * on every authenticated request, so a hang there previously hung every signed-in
+     * request across every consumer of this package. No alias or deprecated name is kept
+     * for the old, narrower `tokenRequestTimeoutMs`.
+     */
+    idpRequestTimeoutMs?: number;
+    /**
+     * How long after a refresh token was rotated a second presentation of it is still
+     * treated as a concurrent-tab race rather than reuse (AK-14, gap 3; MP-127; RFC 9700
+     * §4.14.2). Two browser tabs share one cookie jar: the loser of a rotation sends the
+     * now-stale cookie only if it did so before the winner's `Set-Cookie` reached the
+     * browser, so a race's loser can only ever present a token that WAS rotated
+     * (`AuthStore.claimRefreshTokenForRotation`'s `rotated: true`), and only within
+     * roughly two client request round-trips of that rotation. Default
+     * `2 * AUTH_REQUEST_DEADLINE_MS` (`../shared-types.js`) — matching media-planner's
+     * `REFRESH_REUSE_GRACE_MS`, which observed a real race's loser arriving 60ms after the
+     * winner's rotation (MP-112) — comfortably inside this default. A presentation of a
+     * token that was NOT rotated (no successor row references it — e.g. it was revoked
+     * directly, by a logout or by reuse detection itself) is ALWAYS treated as reuse,
+     * regardless of this window: only a rotation can be a race.
+     */
+    refreshReuseGraceMs?: number;
+    /**
+     * Per-request authorization hook (AK-14, gap 4), run inside `loadAuthedUser` after the
+     * user has been resolved from a live IdP session and flytedesk-id's authorization
+     * check, but before it's attached to `request.authUser`. Lets a consumer reject a
+     * well-formed, still-IdP-authorized session (e.g. media-planner's own
+     * `User.suspendedAt` — "a media-planner admin can lock someone out of this app
+     * specifically without touching their flytedesk-id account") or enrich/override the
+     * resolved user (e.g. substituting a locally-editable `name` for the IdP's) — neither
+     * of which is otherwise reachable from outside the plugin, since `onSignIn` only ever
+     * fires once, at `/callback` time.
+     *
+     * Returning `null` rejects the request exactly like an IdP-side authorization failure
+     * (`request.authUser` stays unset; `requireAuth` 401s). Returning a user (the same one
+     * passed in, or a modified copy) is what gets attached. Throwing, or a rejected
+     * promise, is treated as a rejection too (fail loudly, AK-16: logged with context,
+     * never a 500) — a hook error must never be indistinguishable from "authenticated".
+     */
+    onAuthorizeUser?: (user: AuthedUser, request: FastifyRequest) => Promise<AuthedUser | null> | AuthedUser | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flytedesk/app-kit",
-  "version": "0.8.0",
+  "version": "2.0.0",
   "description": "Shared platform kit for flytedesk apps: flytedesk-id auth (BFF/OIDC client) and a Postgres-native trace/audit layer.",
   "type": "module",
   "license": "UNLICENSED",
@@ -38,6 +38,10 @@
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth/index.js"
     },
+    "./auth/plugin": {
+      "types": "./dist/auth/plugin.d.ts",
+      "import": "./dist/auth/plugin.js"
+    },
     "./auth/testing": {
       "types": "./dist/auth/testing/index.d.ts",
       "import": "./dist/auth/testing/index.js"