@hotmeshio/long-tail 0.24.1 → 0.24.2

package/build/lib/db/schemas/040_oauth_client_consent.sql

@@ -0,0 +1,15 @@
+-- Migration 040: when a person last consented to a grant for an OAuth client
+--
+-- Registration needs no sign-in, so a client that never reaches consent is
+-- deleted after the retention window. A client someone has consented to is
+-- kept, so the app can always reconnect with the client id it holds.
+
+ALTER TABLE lt_oauth_clients ADD COLUMN IF NOT EXISTS last_consent_at TIMESTAMPTZ;
+
+-- Clients consented to before this migration: their newest grant.
+UPDATE lt_oauth_clients c
+SET last_consent_at = g.created_at
+FROM (
+  SELECT client_id, MAX(created_at) AS created_at FROM lt_oauth_grants GROUP BY client_id
+) g
+WHERE c.client_id = g.client_id AND c.last_consent_at IS NULL;

package/build/modules/config.d.ts

@@ -30,6 +30,10 @@ export declare const config: {
     JWT_SECRET: string;
     LT_SEED_SERVICE_KEYS: boolean;
     LT_OAUTH_ISSUER: string;
+    /** Spent, expired and revoked OAuth rows are deleted once older than this many days. */
+    OAUTH_RETENTION_DAYS: number;
+    /** Least time between one process's OAuth sweeps. A sweep runs on an OAuth write. */
+    OAUTH_SWEEP_SECONDS: number;
     HONEYCOMB_API_KEY: string;
     ROLE_ENFORCEMENT_CACHE_TTL_MS: number;
     LT_ANALYTICS_MAX_GROUPS: number;

package/build/modules/config.js

@@ -45,6 +45,10 @@ exports.config = {
     LT_SEED_SERVICE_KEYS: process.env.LT_SEED_SERVICE_KEYS === 'true',
     // Enables the OAuth authorization server for /mcp when start() passes no auth.oauthServer.
     LT_OAUTH_ISSUER: process.env.LT_OAUTH_ISSUER || '',
+    /** Spent, expired and revoked OAuth rows are deleted once older than this many days. */
+    OAUTH_RETENTION_DAYS: positiveInt('OAUTH_RETENTION_DAYS', 7),
+    /** Least time between one process's OAuth sweeps. A sweep runs on an OAuth write. */
+    OAUTH_SWEEP_SECONDS: positiveInt('OAUTH_SWEEP_SECONDS', 600),
     HONEYCOMB_API_KEY: process.env.HONEYCOMB_API_KEY || '',
     // Resolver schema enforcement: TTL for the cached enforcing-role set and
     // latest role form schemas. Bounds cross-container staleness after a role

package/build/modules/maintenance.d.ts

@@ -11,7 +11,7 @@ import type { LTMaintenanceConfig } from '../types/maintenance';
  *    (preserves jdata, udata, jmark, hmark — exports always work)
  * 4. Hard-delete pruned jobs older than 180 days
  * 5. Delete OAuth server rows (expired codes and tokens, unused or revoked
- *    grants, clients with no live grant) older than 7 days
+ *    grants, clients never consented to) older than 7 days
  *
  * Conservative defaults — execution artifacts (activity inputs, stream
  * history) are needed for rich export data. Pruning too early strips

package/build/modules/maintenance.js

@@ -13,7 +13,7 @@ exports.defaultMaintenanceConfig = void 0;
  *    (preserves jdata, udata, jmark, hmark — exports always work)
  * 4. Hard-delete pruned jobs older than 180 days
  * 5. Delete OAuth server rows (expired codes and tokens, unused or revoked
- *    grants, clients with no live grant) older than 7 days
+ *    grants, clients never consented to) older than 7 days
  *
  * Conservative defaults — execution artifacts (activity inputs, stream
  * history) are needed for rich export data. Pruning too early strips

package/build/services/auth/oauth-server/index.d.ts

@@ -1,3 +1,3 @@
-export { REFRESH_REUSE_GRACE_SECONDS, createSecret, hashSecret, pkceChallenge, registerClient, getClient, issueAuthorizationCode, exchangeAuthorizationCode, rotateRefreshToken, getLiveGrant, revokeByRefreshToken, revokeGrant, listGrants, pruneOAuthServer, type RevokedGrant, type OAuthPruneCounts, } from './store';
+export { REFRESH_REUSE_GRACE_SECONDS, createSecret, hashSecret, pkceChallenge, registerClient, getClient, issueAuthorizationCode, exchangeAuthorizationCode, rotateRefreshToken, getLiveGrant, revokeByRefreshToken, revokeGrant, listGrants, pruneOAuthServer, sweepOAuthServer, type RevokedGrant, type OAuthPruneCounts, } from './store';
 export { signAccessToken, verifyAccessToken, accessTokenPrincipal, type AccessTokenTarget, type LTAccessTokenClaims, } from './access-token';
 export { MCP_SCOPES, PRESET_SCOPE, ACCESS_TOKEN_TYPE, OAUTH_PRINCIPAL_TYPE } from './constants';

package/build/services/auth/oauth-server/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAUTH_PRINCIPAL_TYPE = exports.ACCESS_TOKEN_TYPE = exports.PRESET_SCOPE = exports.MCP_SCOPES = exports.accessTokenPrincipal = exports.verifyAccessToken = exports.signAccessToken = exports.pruneOAuthServer = exports.listGrants = exports.revokeGrant = exports.revokeByRefreshToken = exports.getLiveGrant = exports.rotateRefreshToken = exports.exchangeAuthorizationCode = exports.issueAuthorizationCode = exports.getClient = exports.registerClient = exports.pkceChallenge = exports.hashSecret = exports.createSecret = exports.REFRESH_REUSE_GRACE_SECONDS = void 0;
+exports.OAUTH_PRINCIPAL_TYPE = exports.ACCESS_TOKEN_TYPE = exports.PRESET_SCOPE = exports.MCP_SCOPES = exports.accessTokenPrincipal = exports.verifyAccessToken = exports.signAccessToken = exports.sweepOAuthServer = exports.pruneOAuthServer = exports.listGrants = exports.revokeGrant = exports.revokeByRefreshToken = exports.getLiveGrant = exports.rotateRefreshToken = exports.exchangeAuthorizationCode = exports.issueAuthorizationCode = exports.getClient = exports.registerClient = exports.pkceChallenge = exports.hashSecret = exports.createSecret = exports.REFRESH_REUSE_GRACE_SECONDS = void 0;
 var store_1 = require("./store");
 Object.defineProperty(exports, "REFRESH_REUSE_GRACE_SECONDS", { enumerable: true, get: function () { return store_1.REFRESH_REUSE_GRACE_SECONDS; } });
 Object.defineProperty(exports, "createSecret", { enumerable: true, get: function () { return store_1.createSecret; } });
@@ -16,6 +16,7 @@ Object.defineProperty(exports, "revokeByRefreshToken", { enumerable: true, get:
 Object.defineProperty(exports, "revokeGrant", { enumerable: true, get: function () { return store_1.revokeGrant; } });
 Object.defineProperty(exports, "listGrants", { enumerable: true, get: function () { return store_1.listGrants; } });
 Object.defineProperty(exports, "pruneOAuthServer", { enumerable: true, get: function () { return store_1.pruneOAuthServer; } });
+Object.defineProperty(exports, "sweepOAuthServer", { enumerable: true, get: function () { return store_1.sweepOAuthServer; } });
 var access_token_1 = require("./access-token");
 Object.defineProperty(exports, "signAccessToken", { enumerable: true, get: function () { return access_token_1.signAccessToken; } });
 Object.defineProperty(exports, "verifyAccessToken", { enumerable: true, get: function () { return access_token_1.verifyAccessToken; } });

package/build/services/auth/oauth-server/sql.d.ts

@@ -1,7 +1,7 @@
 export declare const INSERT_CLIENT = "\n  INSERT INTO lt_oauth_clients (client_id, client_name, redirect_uris)\n  VALUES ($1, $2, $3)\n  RETURNING client_id, client_name, redirect_uris, created_at";
 export declare const GET_CLIENT = "\n  SELECT client_id, client_name, redirect_uris, created_at\n  FROM lt_oauth_clients WHERE client_id = $1";
-/** Create the grant and its authorization code together. */
-export declare const ISSUE_CODE = "\n  WITH g AS (\n    INSERT INTO lt_oauth_grants (user_id, client_id, policy, scope)\n    VALUES ($1, $2, $3, $4)\n    RETURNING id\n  )\n  INSERT INTO lt_oauth_codes (code_hash, grant_id, redirect_uri, code_challenge, resource, expires_at)\n  SELECT $5, g.id, $6, $7, $8, NOW() + make_interval(secs => $9) FROM g\n  RETURNING grant_id";
+/** Create the grant and its authorization code together, and stamp the client's consent. */
+export declare const ISSUE_CODE = "\n  WITH g AS (\n    INSERT INTO lt_oauth_grants (user_id, client_id, policy, scope)\n    VALUES ($1, $2, $3, $4)\n    RETURNING id\n  ),\n  consented AS (\n    UPDATE lt_oauth_clients SET last_consent_at = NOW() WHERE client_id = $2\n  )\n  INSERT INTO lt_oauth_codes (code_hash, grant_id, redirect_uri, code_challenge, resource, expires_at)\n  SELECT $5, g.id, $6, $7, $8, NOW() + make_interval(secs => $9) FROM g\n  RETURNING grant_id";
 /**
  * Consume a code and issue the first refresh token. The code must be unused,
  * unexpired, for this client and redirect URI, and match the PKCE challenge;
@@ -46,5 +46,8 @@ export declare const PRUNE_CODES = "\n  DELETE FROM lt_oauth_codes WHERE expires
  * left with no refresh token and no code: never exchanged, or long unused.
  */
 export declare const PRUNE_GRANTS = "\n  DELETE FROM lt_oauth_grants g\n  WHERE g.revoked_at < NOW() - $1::interval\n     OR (g.created_at < NOW() - $1::interval\n         AND NOT EXISTS (SELECT 1 FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id)\n         AND NOT EXISTS (SELECT 1 FROM lt_oauth_codes c WHERE c.grant_id = g.id))";
-/** Clients registered longer ago than the window with no live grant. */
-export declare const PRUNE_CLIENTS = "\n  DELETE FROM lt_oauth_clients c\n  WHERE c.created_at < NOW() - $1::interval\n    AND NOT EXISTS (SELECT 1 FROM lt_oauth_grants g WHERE g.client_id = c.client_id AND g.revoked_at IS NULL)";
+/**
+ * Clients registered longer ago than the window that no one ever consented to.
+ * A client with a consent is kept: the app holds its client id to reconnect.
+ */
+export declare const PRUNE_CLIENTS = "\n  DELETE FROM lt_oauth_clients c\n  WHERE c.last_consent_at IS NULL AND c.created_at < NOW() - $1::interval\n    AND NOT EXISTS (SELECT 1 FROM lt_oauth_grants g WHERE g.client_id = c.client_id)";

package/build/services/auth/oauth-server/sql.js

@@ -17,12 +17,15 @@ exports.INSERT_CLIENT = `
 exports.GET_CLIENT = `
   SELECT client_id, client_name, redirect_uris, created_at
   FROM lt_oauth_clients WHERE client_id = $1`;
-/** Create the grant and its authorization code together. */
+/** Create the grant and its authorization code together, and stamp the client's consent. */
 exports.ISSUE_CODE = `
   WITH g AS (
     INSERT INTO lt_oauth_grants (user_id, client_id, policy, scope)
     VALUES ($1, $2, $3, $4)
     RETURNING id
+  ),
+  consented AS (
+    UPDATE lt_oauth_clients SET last_consent_at = NOW() WHERE client_id = $2
   )
   INSERT INTO lt_oauth_codes (code_hash, grant_id, redirect_uri, code_challenge, resource, expires_at)
   SELECT $5, g.id, $6, $7, $8, NOW() + make_interval(secs => $9) FROM g
@@ -149,8 +152,11 @@ exports.PRUNE_GRANTS = `
      OR (g.created_at < NOW() - $1::interval
          AND NOT EXISTS (SELECT 1 FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id)
          AND NOT EXISTS (SELECT 1 FROM lt_oauth_codes c WHERE c.grant_id = g.id))`;
-/** Clients registered longer ago than the window with no live grant. */
+/**
+ * Clients registered longer ago than the window that no one ever consented to.
+ * A client with a consent is kept: the app holds its client id to reconnect.
+ */
 exports.PRUNE_CLIENTS = `
   DELETE FROM lt_oauth_clients c
-  WHERE c.created_at < NOW() - $1::interval
-    AND NOT EXISTS (SELECT 1 FROM lt_oauth_grants g WHERE g.client_id = c.client_id AND g.revoked_at IS NULL)`;
+  WHERE c.last_consent_at IS NULL AND c.created_at < NOW() - $1::interval
+    AND NOT EXISTS (SELECT 1 FROM lt_oauth_grants g WHERE g.client_id = c.client_id)`;

package/build/services/auth/oauth-server/store.d.ts

@@ -82,7 +82,14 @@ export interface OAuthPruneCounts {
 /**
  * Delete what the authorization server no longer needs, older than the
  * window (a Postgres interval): spent and expired refresh tokens and codes,
- * then grants with neither left or revoked, then clients with no live grant.
+ * then grants with neither left or revoked, then clients never consented to.
  * Each step reads what the one before it left.
  */
 export declare function pruneOAuthServer(olderThan: string): Promise<OAuthPruneCounts>;
+/**
+ * Delete what the server no longer needs, older than OAUTH_RETENTION_DAYS.
+ * Each OAuth write calls it, and it runs at most once per OAUTH_SWEEP_SECONDS
+ * in a process, so the tables stay bounded with or without a maintenance
+ * schedule. A failed sweep is logged and never fails the write.
+ */
+export declare function sweepOAuthServer(): Promise<void>;

package/build/services/auth/oauth-server/store.js

@@ -47,8 +47,11 @@ exports.revokeByRefreshToken = revokeByRefreshToken;
 exports.revokeGrant = revokeGrant;
 exports.listGrants = listGrants;
 exports.pruneOAuthServer = pruneOAuthServer;
+exports.sweepOAuthServer = sweepOAuthServer;
 const crypto = __importStar(require("crypto"));
 const db_1 = require("../../../lib/db");
+const logger_1 = require("../../../lib/logger");
+const config_1 = require("../../../modules/config");
 const uuid_1 = require("../../../lib/uuid");
 const sql_1 = require("./sql");
 /** A refresh token reused within this many seconds is treated as a client retry. */
@@ -69,6 +72,7 @@ async function registerClient(input) {
     const { rows } = await (0, db_1.getPool)().query(sql_1.INSERT_CLIENT, [
         `ltc_${createSecret()}`, input.clientName ?? null, input.redirectUris,
     ]);
+    void sweepOAuthServer();
     return rows[0];
 }
 /** A client id as registerClient issues it; anything else names no client and never reaches SQL. */
@@ -90,6 +94,7 @@ async function issueAuthorizationCode(input) {
         input.userId, input.clientId, input.policy, input.scope,
         hashSecret(code), input.redirectUri, input.codeChallenge, input.resource ?? null, input.ttlSeconds,
     ]);
+    void sweepOAuthServer();
     return { code, grantId: rows[0].grant_id };
 }
 /**
@@ -110,6 +115,7 @@ async function exchangeAuthorizationCode(input) {
         await pool.query(sql_1.REVOKE_ON_CODE_REUSE, [codeHash]);
         return null;
     }
+    void sweepOAuthServer();
     const { resource, ...snapshot } = rows[0];
     return { snapshot, resource, refreshToken };
 }
@@ -124,8 +130,10 @@ async function rotateRefreshToken(input) {
     const next = createSecret();
     const oldHash = hashSecret(input.refreshToken);
     const { rows } = await pool.query(sql_1.ROTATE_REFRESH_TOKEN, [oldHash, hashSecret(next), input.refreshTtlSeconds, input.clientId]);
-    if (rows[0])
+    if (rows[0]) {
+        void sweepOAuthServer();
         return { snapshot: rows[0], refreshToken: next };
+    }
     const reuse = await pool.query(sql_1.REVOKE_ON_REFRESH_REUSE, [oldHash, exports.REFRESH_REUSE_GRACE_SECONDS]);
     return { snapshot: null, revoked: reuse.rows[0] ?? null };
 }
@@ -158,7 +166,7 @@ async function listGrants(userId) {
 /**
  * Delete what the authorization server no longer needs, older than the
  * window (a Postgres interval): spent and expired refresh tokens and codes,
- * then grants with neither left or revoked, then clients with no live grant.
+ * then grants with neither left or revoked, then clients never consented to.
  * Each step reads what the one before it left.
  */
 async function pruneOAuthServer(olderThan) {
@@ -169,3 +177,24 @@ async function pruneOAuthServer(olderThan) {
     const clients = (await pool.query(sql_1.PRUNE_CLIENTS, [olderThan])).rowCount ?? 0;
     return { refreshTokens, codes, grants, clients };
 }
+let nextSweepAt = 0;
+/**
+ * Delete what the server no longer needs, older than OAUTH_RETENTION_DAYS.
+ * Each OAuth write calls it, and it runs at most once per OAUTH_SWEEP_SECONDS
+ * in a process, so the tables stay bounded with or without a maintenance
+ * schedule. A failed sweep is logged and never fails the write.
+ */
+async function sweepOAuthServer() {
+    const now = Date.now();
+    if (now < nextSweepAt)
+        return;
+    nextSweepAt = now + config_1.config.OAUTH_SWEEP_SECONDS * 1000;
+    try {
+        const counts = await pruneOAuthServer(`${config_1.config.OAUTH_RETENTION_DAYS} days`);
+        if (Object.values(counts).some(Boolean))
+            logger_1.loggerRegistry.info(`[lt-oauth] swept: ${JSON.stringify(counts)}`);
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[lt-oauth] sweep failed: ${err?.message}`);
+    }
+}

package/build/services/maintenance/index.js

@@ -107,7 +107,7 @@ async function executeRule(appId, rule) {
             break;
         }
         // Drop the authorization server's dead rows: spent or expired tokens and
-        // codes, grants with neither left or long revoked, clients with no live grant.
+        // codes, grants with neither left or long revoked, clients never consented to.
         case rule.target === 'oauth' && rule.action === 'delete': {
             const { pruneOAuthServer } = await Promise.resolve().then(() => __importStar(require('../auth/oauth-server')));
             const counts = await pruneOAuthServer(rule.olderThan);

package/docs/maintenance.md

@@ -62,7 +62,7 @@ Six categories of data are subject to maintenance:
 | **Entity jobs** | Job rows where `entity` is set. These represent actual workflow instances -- the rows that back `Durable.Client.workflow.search()` calls and execution exports. Deleting them removes the workflow record entirely. |
 | **Pruned jobs** | Entity jobs that have already had their execution artifacts stripped (the `pruned_at` column is not `NULL`). These retain core data but no longer carry execution scaffolding. They can be hard-deleted after a longer retention window. |
 | **Terminal escalations** | Escalation rows in a terminal status (`resolved`, `cancelled`, `expired`). Terminal rows are inert audit records -- every engine state transition guards on `status = 'pending'`, so aging them out is safe for live waiters, claims, and signal delivery. The engine-owned prune deletes in atomic batches until the retention horizon is drained. Pending rows are never touched. |
-| **OAuth server rows** | The `/mcp` authorization server's records. Refresh tokens and authorization codes past expiry, or rotated out, longer ago than the window; then grants left with neither, or revoked longer ago than the window; then clients registered longer ago than the window with no live grant. A client still holding a live refresh token keeps its grant and its registration. |
+| **OAuth server rows** | The `/mcp` authorization server's records. Refresh tokens and authorization codes past expiry, or rotated out, longer ago than the window; then grants left with neither, or revoked longer ago than the window; then clients registered longer ago than the window that no one ever consented to. A client still holding a live refresh token keeps its grant, and a client anyone has consented to keeps its registration, so the app can reconnect with the client id it holds. |
 
 ## Prune vs. delete
 
@@ -97,9 +97,9 @@ The default configuration (`modules/maintenance.ts`, enabled with `maintenance:
 | 2. Delete transient jobs older than 30 days | Removes activity-level bookkeeping rows that have no associated workflow entity. |
 | 3. Prune entity jobs older than 30 days | Strips execution artifacts from workflow instances while preserving core data. Exports and search remain functional. |
 | 4. Delete pruned jobs older than 180 days | Hard-deletes workflow instances that were pruned at least 180 days ago. This is the final removal. |
-| 5. Delete OAuth server rows older than 7 days | Removes expired codes and tokens, unused or revoked grants, and clients with no live grant. |
+| 5. Delete OAuth server rows older than 7 days | Removes expired codes and tokens, unused or revoked grants, and clients never consented to. |
 
-A custom `rules` list replaces the defaults, so include the `oauth` rule when the OAuth server is enabled.
+A custom `rules` list replaces the defaults. The `oauth` rule is optional: the OAuth server sweeps its own tables as it is used (see [Connect with OAuth](mcp.md#connect-with-oauth)), and the rule adds a sweep on this schedule with its own window.
 
 Rules execute sequentially. If one fails, the remaining rules still run; failures are logged and do not halt the cycle.
 

package/docs/mcp.md

@@ -207,6 +207,8 @@ Allow as me appears only when it grants more than read-only: when you can write
 
 Access tokens last 5 minutes; the client refreshes them silently with a refresh token that rotates on each use and lasts 30 days. Every request reads the grant: a client acts with your roles as they are now, and a disconnected app, a revoked token or a deactivated account stops working on the next request. Disconnect a client under **Connected apps** in the user menu; the same happens when the client revokes its token.
 
+The server keeps its tables bounded on its own. Each process sweeps them on an OAuth write, at most once every `OAUTH_SWEEP_SECONDS` (default 600), deleting rows dead for longer than `OAUTH_RETENTION_DAYS` (default 7): spent and expired codes and refresh tokens, revoked or unused grants, and clients registered but never consented to. A live grant and its current refresh token are kept, and so is any client someone has consented to.
+
 **Enable it** with `auth.oauthServer` in `start()`, or `LT_OAUTH_ISSUER` in the environment:
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",