@selvajs/supabase-provider 0.14.3 → 0.14.4-beta.0

package/dist/data/rowStamp.d.ts

@@ -0,0 +1,38 @@
+import type { RequestContext } from '@selvajs/platform';
+/**
+ * Row-level (snake_case) audit-stamp helpers for Supabase stores.
+ *
+ * Platform's `auditUpdate` / `auditSoftDelete` emit camelCase *domain* fields
+ * (`updatedAt` / `updatedBy`), but Postgres rows are snake_case, so every store
+ * hand-translated them. These helpers own that translation once. Row-column
+ * naming is a provider concern, so they live here rather than in platform.
+ *
+ * Two deliberate rules, matched to how the engine's stores already write rows:
+ *  - `updated_by` is written ONLY when `ctx.userId` is set. On system contexts
+ *    it's the empty string, and the column FKs `auth.users(id)` with
+ *    `ON DELETE SET NULL` — writing `''` would violate the FK, so it's omitted
+ *    and the existing value is left untouched.
+ *  - Plain updates DON'T stamp `updated_at`: a per-table `updated_at` trigger
+ *    already sets it. Only the soft-delete stamp writes `updated_at` explicitly,
+ *    so it matches `deleted_at` (a single timestamp for the deletion event).
+ */
+/**
+ * Stamp for a plain UPDATE: `{ updated_by }` when the context carries a user,
+ * `{}` otherwise (the DB trigger handles `updated_at`). Spread into the row:
+ * `const row = { ...patch, ...stampUpdate(ctx) }`.
+ */
+export declare function stampUpdate(ctx: RequestContext): {
+    updated_by?: string;
+};
+/**
+ * Stamp for a soft-delete: `{ deleted_at, updated_at, updated_by? }`. `updated_at`
+ * is set explicitly to equal `deleted_at`; `updated_by` follows the same
+ * omit-when-empty rule as {@link stampUpdate}. `fallbackActor` defaults to
+ * `ctx.userId` (matching the engine stores' `auditSoftDelete(ctx, ctx.userId)`).
+ */
+export declare function stampSoftDelete(ctx: RequestContext, fallbackActor?: string | null | undefined): {
+    deleted_at: string;
+    updated_at: string;
+    updated_by?: string;
+};
+//# sourceMappingURL=rowStamp.d.ts.map

package/dist/data/rowStamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowStamp.d.ts","sourceRoot":"","sources":["../../src/data/rowStamp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,cAAc,EACnB,aAAa,GAAE,MAAM,GAAG,IAAI,GAAG,SAAsB,GACnD;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAQjE"}

package/dist/data/rowStamp.js

@@ -0,0 +1,43 @@
+import { auditSoftDelete } from '@selvajs/platform';
+/**
+ * Row-level (snake_case) audit-stamp helpers for Supabase stores.
+ *
+ * Platform's `auditUpdate` / `auditSoftDelete` emit camelCase *domain* fields
+ * (`updatedAt` / `updatedBy`), but Postgres rows are snake_case, so every store
+ * hand-translated them. These helpers own that translation once. Row-column
+ * naming is a provider concern, so they live here rather than in platform.
+ *
+ * Two deliberate rules, matched to how the engine's stores already write rows:
+ *  - `updated_by` is written ONLY when `ctx.userId` is set. On system contexts
+ *    it's the empty string, and the column FKs `auth.users(id)` with
+ *    `ON DELETE SET NULL` — writing `''` would violate the FK, so it's omitted
+ *    and the existing value is left untouched.
+ *  - Plain updates DON'T stamp `updated_at`: a per-table `updated_at` trigger
+ *    already sets it. Only the soft-delete stamp writes `updated_at` explicitly,
+ *    so it matches `deleted_at` (a single timestamp for the deletion event).
+ */
+/**
+ * Stamp for a plain UPDATE: `{ updated_by }` when the context carries a user,
+ * `{}` otherwise (the DB trigger handles `updated_at`). Spread into the row:
+ * `const row = { ...patch, ...stampUpdate(ctx) }`.
+ */
+export function stampUpdate(ctx) {
+    return ctx.userId ? { updated_by: ctx.userId } : {};
+}
+/**
+ * Stamp for a soft-delete: `{ deleted_at, updated_at, updated_by? }`. `updated_at`
+ * is set explicitly to equal `deleted_at`; `updated_by` follows the same
+ * omit-when-empty rule as {@link stampUpdate}. `fallbackActor` defaults to
+ * `ctx.userId` (matching the engine stores' `auditSoftDelete(ctx, ctx.userId)`).
+ */
+export function stampSoftDelete(ctx, fallbackActor = ctx.userId) {
+    const stamp = auditSoftDelete(ctx, fallbackActor);
+    const row = {
+        deleted_at: stamp.deletedAt,
+        updated_at: stamp.updatedAt
+    };
+    if (stamp.updatedBy)
+        row.updated_by = stamp.updatedBy;
+    return row;
+}
+//# sourceMappingURL=rowStamp.js.map

package/dist/data/rowStamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowStamp.js","sourceRoot":"","sources":["../../src/data/rowStamp.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAmB;IAC9C,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,GAAmB,EACnB,gBAA2C,GAAG,CAAC,MAAM;IAErD,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAClD,MAAM,GAAG,GAAoE;QAC5E,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,UAAU,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC;IACF,IAAI,KAAK,CAAC,SAAS;QAAE,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC;IACtD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { SupabaseStorageProvider } from './storage/SupabaseStorageProvider.js';
 export type { SupabaseStorageProviderConfig } from './storage/SupabaseStorageProvider.js';
-export { SupabaseOrgStore, SupabaseProjectStore, SupabaseDefinitionStore, SupabaseInviteStore, SupabaseComputeServerStore, SupabaseShareLinkStore, SupabaseDataProvider, SupabaseEventSink, SupabaseSolveMetricSink, SupabaseAuditQuery, buildClientBundle } from './data/index.js';
-export type { ClientBundle, BuildClientOptions } from './data/index.js';
+export { SupabaseOrgStore, SupabaseProjectStore, SupabaseDefinitionStore, SupabaseInviteStore, SupabaseComputeServerStore, SupabaseShareLinkStore, SupabaseDataProvider, SupabaseEventSink, SupabaseSolveMetricSink, SupabaseAuditQuery, buildClientBundle, clientBundleFromEnv, DEFAULT_SCHEMA, mapPostgrestError, stampUpdate, stampSoftDelete, notDeleted, toRange, orderColumn, nextCursorFromRange, encodeCursor, decodeCursor } from './data/index.js';
+export type { ClientBundle, BuildClientOptions, ForRequestOptions, SchemaClient, SelvaSchemaClient, RangeSpec } from './data/index.js';
 export { SupabaseUserProfileProvider } from './userProfile/index.js';
 export { SupabaseAuthProvider } from './auth/index.js';
 export type { SupabaseAuthProviderConfig } from './auth/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,YAAY,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAE1F,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAExE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,YAAY,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAE1F,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,UAAU,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 export { SupabaseStorageProvider } from './storage/SupabaseStorageProvider.js';
-export { SupabaseOrgStore, SupabaseProjectStore, SupabaseDefinitionStore, SupabaseInviteStore, SupabaseComputeServerStore, SupabaseShareLinkStore, SupabaseDataProvider, SupabaseEventSink, SupabaseSolveMetricSink, SupabaseAuditQuery, buildClientBundle } from './data/index.js';
+export { SupabaseOrgStore, SupabaseProjectStore, SupabaseDefinitionStore, SupabaseInviteStore, SupabaseComputeServerStore, SupabaseShareLinkStore, SupabaseDataProvider, SupabaseEventSink, SupabaseSolveMetricSink, SupabaseAuditQuery, buildClientBundle, clientBundleFromEnv, DEFAULT_SCHEMA, mapPostgrestError, stampUpdate, stampSoftDelete, notDeleted, toRange, orderColumn, nextCursorFromRange, encodeCursor, decodeCursor } from './data/index.js';
 export { SupabaseUserProfileProvider } from './userProfile/index.js';
 export { SupabaseAuthProvider } from './auth/index.js';
 export { SupabasePlatformPermissionStore } from './permissions/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAG/E,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAG/E,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,UAAU,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,MAAM,iBAAiB,CAAC;AAUzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/supabase-provider",
-  "version": "0.14.3",
+  "version": "0.14.4-beta.0",
   "description": "Supabase (Auth + Postgres + Storage) implementations of @selvajs/platform interfaces",
   "license": "MIT",
   "publishConfig": {
@@ -57,7 +57,7 @@
   "dependencies": {
     "@supabase/supabase-js": "^2.104.1",
     "sharp": "^0.34.5",
-    "@selvajs/platform": "0.14.2"
+    "@selvajs/platform": "0.14.3-beta.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",

package/src/auth/SupabaseAuthProvider.ts

@@ -49,6 +49,34 @@ export interface SupabaseAuthProviderConfig {
 	 * `{ ok: false, reason: 'signup_disabled' }`.
 	 */
 	allowEmailLinkSignup?: boolean;
+	/**
+	 * How `verifyToken` validates session JWTs (see the method for the full
+	 * rationale):
+	 *  - `'hybrid'` (default): verify the JWT LOCALLY via `getClaims()` on every
+	 *    request (no network call when the project uses asymmetric signing keys —
+	 *    the modern default), and additionally re-check against GoTrue at most
+	 *    once per `revalidateMs` per session to catch server-side sign-outs and
+	 *    `disabled` flips. Bounds revocation latency to `revalidateMs`.
+	 *  - `'strict'`: call `getUser()` on every request (the pre-1b behavior).
+	 *    Instant revocation, one network round-trip per request. For operators
+	 *    who don't accept any revocation lag.
+	 */
+	tokenVerification?: 'hybrid' | 'strict';
+	/**
+	 * Recheck window for `'hybrid'` verification, in ms. A verified session is
+	 * re-validated against GoTrue at most once per this interval. Default 60s.
+	 */
+	revalidateMs?: number;
+}
+
+/** Default hybrid recheck window — see `revalidateMs`. */
+const DEFAULT_REVALIDATE_MS = 60_000;
+
+/** Parse a positive integer env var, or undefined if unset/invalid. */
+function parsePositiveInt(raw: string | undefined): number | undefined {
+	if (!raw) return undefined;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 
 export class SupabaseAuthProvider implements IAuthProvider {
@@ -61,10 +89,23 @@ export class SupabaseAuthProvider implements IAuthProvider {
 	private readonly anon: SupabaseClient;
 	private readonly anonKey: string;
 	private readonly supabaseUrl: string;
+	private readonly tokenVerification: 'hybrid' | 'strict';
+	private readonly revalidateMs: number;
+
+	/**
+	 * Last time a given session was re-validated against GoTrue (epoch ms),
+	 * keyed by the JWT `session_id`. Bounds the hybrid recheck to once per
+	 * `revalidateMs` per session. Swept lazily (see `verifyToken`) so a burst of
+	 * distinct sessions can't leak memory. Per-process; multi-instance drift is
+	 * harmless (each instance rechecks on its own schedule).
+	 */
+	private readonly lastRevalidatedAt = new Map<string, number>();
 
 	constructor(config: SupabaseAuthProviderConfig) {
 		this.supabaseUrl = config.supabaseUrl;
 		this.anonKey = config.anonKey;
+		this.tokenVerification = config.tokenVerification ?? 'hybrid';
+		this.revalidateMs = config.revalidateMs ?? DEFAULT_REVALIDATE_MS;
 		this.admin = createClient(config.supabaseUrl, config.serviceRoleKey, {
 			auth: { persistSession: false, autoRefreshToken: false }
 		});
@@ -101,6 +142,11 @@ export class SupabaseAuthProvider implements IAuthProvider {
 			.split(',')
 			.map((p) => p.trim().toLowerCase())
 			.filter((p) => p.length > 0);
+		// Local JWT verification is the default (fast; requires asymmetric signing
+		// keys to skip the network — the Supabase default since 2025). Set
+		// SUPABASE_TOKEN_VERIFICATION=strict to force a getUser() per request.
+		const tokenVerification = env.SUPABASE_TOKEN_VERIFICATION === 'strict' ? 'strict' : 'hybrid';
+		const revalidateMs = parsePositiveInt(env.SUPABASE_REVALIDATE_MS);
 		return new SupabaseAuthProvider({
 			supabaseUrl,
 			anonKey,
@@ -109,21 +155,111 @@ export class SupabaseAuthProvider implements IAuthProvider {
 			oauthProviders,
 			// Default true; set SUPABASE_ALLOW_EMAIL_LINK_SIGNUP=false to lock down
 			// to invite-only and reject magic-link signups for new addresses.
-			allowEmailLinkSignup: env.SUPABASE_ALLOW_EMAIL_LINK_SIGNUP !== 'false'
+			allowEmailLinkSignup: env.SUPABASE_ALLOW_EMAIL_LINK_SIGNUP !== 'false',
+			tokenVerification,
+			...(revalidateMs !== undefined ? { revalidateMs } : {})
 		});
 	}
 
+	/**
+	 * Verify a session JWT and return the user, or null if invalid/disabled.
+	 * Runs on EVERY authenticated request, so the fast path avoids a network
+	 * round-trip.
+	 *
+	 * `'hybrid'` (default):
+	 *  1. `getClaims(token)` verifies the JWT. With asymmetric signing keys (the
+	 *     modern Supabase default) this is LOCAL — the SDK verifies against the
+	 *     cached JWKS via Web Crypto, no call to GoTrue. With a legacy symmetric
+	 *     HS256 secret the SDK transparently falls back to a network verify, so
+	 *     this is correct for both project types without us detecting the scheme
+	 *     or hand-rolling JWKS handling (which the Supabase docs warn against —
+	 *     it breaks under key rotation).
+	 *  2. Local verification can't see a server-side sign-out or a `disabled`
+	 *     flip that happened AFTER the token was issued (the claims are a
+	 *     snapshot). So we additionally re-check against GoTrue via `getUser`,
+	 *     but at most once per `revalidateMs` per session — bounding revocation
+	 *     latency to that window while eliminating ~all per-request network
+	 *     calls under steady load.
+	 *
+	 * `'strict'`: `getUser` on every request — instant revocation, one round
+	 * trip per request. The pre-1b behavior, for operators who accept no lag.
+	 */
 	async verifyToken(token: string): Promise<AuthUser | null> {
 		if (!token) return null;
-		// Per-request anon client with the JWT attached. `getUser(token)` also
-		// works, but routing through a scoped client keeps future sub-calls
-		// (profile fetch, etc.) RLS-aware if we ever move them here.
+
+		if (this.tokenVerification === 'strict') {
+			return this.verifyViaGetUser(token);
+		}
+
+		// --- hybrid: local verify first ---
+		const claims = await this.getClaimsOrNull(token);
+		if (!claims) return null;
+		// `disabled` as of token issue. A flip AFTER issue is caught by the
+		// periodic recheck below.
+		if ((claims.user_metadata as { disabled?: boolean } | undefined)?.disabled === true) {
+			return null;
+		}
+
+		// Periodic recheck: catch sign-out / disabled since the token was issued.
+		const sessionId = typeof claims.session_id === 'string' ? claims.session_id : claims.sub;
+		if (this.shouldRevalidate(sessionId)) {
+			const fresh = await this.verifyViaGetUser(token);
+			// getUser rejected it (signed out, disabled, revoked) → deny now.
+			if (!fresh) {
+				this.lastRevalidatedAt.delete(sessionId);
+				return null;
+			}
+			this.markRevalidated(sessionId);
+			return fresh;
+		}
+
+		// Build the user from claims — no network call on this path.
+		return {
+			id: claims.sub,
+			email: typeof claims.email === 'string' ? claims.email : undefined,
+			disabled: false,
+			metadata: claims.user_metadata
+		};
+	}
+
+	/** Full network verify against GoTrue. Also the `'strict'`-mode path. */
+	private async verifyViaGetUser(token: string): Promise<AuthUser | null> {
 		const { data, error } = await this.anon.auth.getUser(token);
 		if (error || !data.user) return null;
 		if (data.user.user_metadata?.disabled === true) return null;
 		return this.hydrate(data.user);
 	}
 
+	/** Local JWT verification. Returns the claims, or null if invalid/expired. */
+	private async getClaimsOrNull(token: string) {
+		try {
+			const { data, error } = await this.anon.auth.getClaims(token);
+			if (error || !data) return null;
+			return data.claims;
+		} catch {
+			return null;
+		}
+	}
+
+	private shouldRevalidate(sessionId: string): boolean {
+		const last = this.lastRevalidatedAt.get(sessionId);
+		return last === undefined || Date.now() - last >= this.revalidateMs;
+	}
+
+	private markRevalidated(sessionId: string): void {
+		const now = Date.now();
+		this.lastRevalidatedAt.set(sessionId, now);
+		// Lazy sweep so a churn of distinct sessions can't grow the map without
+		// bound. Anything older than two windows is definitely stale (it would
+		// revalidate on next use anyway). Cheap: only runs when the map is large.
+		if (this.lastRevalidatedAt.size > 10_000) {
+			const cutoff = now - this.revalidateMs * 2;
+			for (const [id, ts] of this.lastRevalidatedAt) {
+				if (ts < cutoff) this.lastRevalidatedAt.delete(id);
+			}
+		}
+	}
+
 	async getUser(id: string): Promise<AuthUser | null> {
 		const { data, error } = await this.admin.auth.admin.getUserById(id);
 		if (error || !data.user) return null;

package/src/auth/__tests__/token-verification.test.ts

@@ -0,0 +1,158 @@
+/**
+ * CI-runnable (no live stack) tests for §1b hybrid token verification. Stubs
+ * the internal anon client's `getClaims` (local JWT verify) and `getUser`
+ * (network GoTrue verify) so we can assert the network-call behavior directly.
+ *
+ * Contract:
+ *  - hybrid (default): verify locally via getClaims on every request; hit
+ *    getUser at most once per `revalidateMs` per session; a getUser rejection
+ *    during that recheck (sign-out / disabled) denies immediately.
+ *  - strict: getUser on every request.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SupabaseAuthProvider } from '../SupabaseAuthProvider.js';
+
+const URL = 'https://example.supabase.co';
+const ANON = 'anon-key';
+const SERVICE = 'service-key';
+
+interface AuthStub {
+	getClaims: ReturnType<typeof vi.fn>;
+	getUser: ReturnType<typeof vi.fn>;
+}
+
+/** Reach into the provider's private anon client and replace its auth surface. */
+function stubAnonAuth(provider: SupabaseAuthProvider): AuthStub {
+	const stub: AuthStub = { getClaims: vi.fn(), getUser: vi.fn() };
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	(provider as any).anon.auth.getClaims = stub.getClaims;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	(provider as any).anon.auth.getUser = stub.getUser;
+	return stub;
+}
+
+function okClaims(overrides: Record<string, unknown> = {}) {
+	return {
+		data: {
+			claims: {
+				sub: 'user-1',
+				session_id: 'sess-1',
+				email: 'u@example.com',
+				exp: Math.floor(Date.now() / 1000) + 3600,
+				...overrides
+			},
+			header: {},
+			signature: new Uint8Array()
+		},
+		error: null
+	};
+}
+
+function okUser() {
+	return {
+		data: { user: { id: 'user-1', email: 'u@example.com', user_metadata: {} } },
+		error: null
+	};
+}
+
+describe('SupabaseAuthProvider — hybrid token verification', () => {
+	beforeEach(() => vi.restoreAllMocks());
+
+	it('verifies locally via getClaims and rechecks getUser once per window', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE,
+			revalidateMs: 60_000
+		});
+		const stub = stubAnonAuth(provider);
+		stub.getClaims.mockResolvedValue(okClaims());
+		stub.getUser.mockResolvedValue(okUser());
+
+		// First call: local verify + one recheck (never seen this session).
+		const a = await provider.verifyToken('tok');
+		expect(a?.id).toBe('user-1');
+		expect(stub.getClaims).toHaveBeenCalledTimes(1);
+		expect(stub.getUser).toHaveBeenCalledTimes(1);
+
+		// Subsequent calls within the window: local only, NO more getUser.
+		await provider.verifyToken('tok');
+		await provider.verifyToken('tok');
+		expect(stub.getClaims).toHaveBeenCalledTimes(3);
+		expect(stub.getUser).toHaveBeenCalledTimes(1); // still just the first
+	});
+
+	it('denies immediately when the periodic getUser recheck rejects (signed out / revoked)', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE
+		});
+		const stub = stubAnonAuth(provider);
+		stub.getClaims.mockResolvedValue(okClaims());
+		stub.getUser.mockResolvedValue({ data: { user: null }, error: { message: 'signed out' } });
+
+		const result = await provider.verifyToken('tok');
+		expect(result).toBeNull();
+	});
+
+	it('denies when the claims already mark the user disabled (no getUser needed)', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE
+		});
+		const stub = stubAnonAuth(provider);
+		stub.getClaims.mockResolvedValue(okClaims({ user_metadata: { disabled: true } }));
+
+		const result = await provider.verifyToken('tok');
+		expect(result).toBeNull();
+		expect(stub.getUser).not.toHaveBeenCalled();
+	});
+
+	it('denies when getClaims fails (bad signature / expired)', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE
+		});
+		const stub = stubAnonAuth(provider);
+		stub.getClaims.mockResolvedValue({ data: null, error: { message: 'invalid JWT' } });
+
+		expect(await provider.verifyToken('tok')).toBeNull();
+		expect(stub.getUser).not.toHaveBeenCalled();
+	});
+
+	it('returns null for an empty token without any network call', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE
+		});
+		const stub = stubAnonAuth(provider);
+		expect(await provider.verifyToken('')).toBeNull();
+		expect(stub.getClaims).not.toHaveBeenCalled();
+		expect(stub.getUser).not.toHaveBeenCalled();
+	});
+});
+
+describe('SupabaseAuthProvider — strict token verification', () => {
+	beforeEach(() => vi.restoreAllMocks());
+
+	it('calls getUser on every request and never getClaims', async () => {
+		const provider = new SupabaseAuthProvider({
+			supabaseUrl: URL,
+			anonKey: ANON,
+			serviceRoleKey: SERVICE,
+			tokenVerification: 'strict'
+		});
+		const stub = stubAnonAuth(provider);
+		stub.getUser.mockResolvedValue(okUser());
+
+		await provider.verifyToken('tok');
+		await provider.verifyToken('tok');
+		expect(stub.getUser).toHaveBeenCalledTimes(2);
+		expect(stub.getClaims).not.toHaveBeenCalled();
+	});
+});