@hotmeshio/long-tail 0.23.1 → 0.24.0

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAuthorizationRequest = checkAuthorizationRequest;
+exports.isGrantPreset = isGrantPreset;
+exports.withQuery = withQuery;
+exports.grantablePresets = grantablePresets;
+const registration_1 = require("./registration");
+const store_1 = require("./store");
+const constants_1 = require("./constants");
+const CODE_CHALLENGE = /^[A-Za-z0-9_-]{43,128}$/;
+const PRESETS = new Set(Object.keys(constants_1.PRESET_SCOPE));
+const text = (value) => (typeof value === 'string' && value !== '' && !(0, registration_1.hasControlCharacters)(value) ? value : undefined);
+async function checkAuthorizationRequest(params, settings) {
+    const clientId = text(params.client_id);
+    const redirectUri = text(params.redirect_uri);
+    const client = clientId ? await (0, store_1.getClient)(clientId) : null;
+    if (!client)
+        return { ok: false, redirect: false, error: 'invalid_client', description: 'unknown client_id' };
+    if (!redirectUri || !client.redirect_uris.includes(redirectUri)) {
+        return { ok: false, redirect: false, error: 'invalid_request', description: 'redirect_uri is not registered for this client' };
+    }
+    const state = text(params.state);
+    const fail = (error, description) => ({ ok: false, redirect: true, redirectUri, state, error, description });
+    if (params.response_type !== 'code')
+        return fail('unsupported_response_type', 'response_type must be code');
+    const codeChallenge = text(params.code_challenge);
+    if (!codeChallenge || !CODE_CHALLENGE.test(codeChallenge))
+        return fail('invalid_request', 'a PKCE code_challenge is required');
+    if (params.code_challenge_method !== 'S256')
+        return fail('invalid_request', 'code_challenge_method must be S256');
+    const resource = text(params.resource) ?? settings.resource;
+    if (resource !== settings.resource)
+        return fail('invalid_target', `resource must be ${settings.resource}`);
+    return { ok: true, request: { client, redirectUri, codeChallenge, state, scope: text(params.scope), resource } };
+}
+function isGrantPreset(value) {
+    return typeof value === 'string' && PRESETS.has(value);
+}
+/** `uri` with `params` added to its query, keeping any query it already has. */
+function withQuery(uri, params) {
+    const url = new URL(uri);
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            url.searchParams.set(key, value);
+    return url.toString();
+}
+/**
+ * The presets the person may grant. Read-only always; Just be me only when it
+ * adds something: a membership that can write, or an admin tier.
+ */
+function grantablePresets(roles) {
+    const canWrite = roles.some((r) => r.type === 'admin' || r.type === 'superadmin' || (r.write_scope ?? 'all') !== 'none');
+    return canWrite ? ['read_only', 'just_me'] : ['read_only'];
+}

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

@@ -0,0 +1,11 @@
+import type { LTGrantPreset } from '../../../types/oauth-server';
+export declare const MCP_SCOPES: {
+    readonly READ: "mcp:read";
+    readonly FULL: "mcp:full";
+};
+/** The coarse scope a grant preset is reported as. */
+export declare const PRESET_SCOPE: Record<LTGrantPreset, string>;
+/** JOSE `typ` for access tokens (RFC 9068). */
+export declare const ACCESS_TOKEN_TYPE = "at+jwt";
+/** `principalType` of a request authenticated by an OAuth access token. */
+export declare const OAUTH_PRINCIPAL_TYPE = "oauth";

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAUTH_PRINCIPAL_TYPE = exports.ACCESS_TOKEN_TYPE = exports.PRESET_SCOPE = exports.MCP_SCOPES = void 0;
+exports.MCP_SCOPES = {
+    READ: 'mcp:read',
+    FULL: 'mcp:full',
+};
+/** The coarse scope a grant preset is reported as. */
+exports.PRESET_SCOPE = {
+    read_only: exports.MCP_SCOPES.READ,
+    just_me: exports.MCP_SCOPES.FULL,
+};
+/** JOSE `typ` for access tokens (RFC 9068). */
+exports.ACCESS_TOKEN_TYPE = 'at+jwt';
+/** `principalType` of a request authenticated by an OAuth access token. */
+exports.OAUTH_PRINCIPAL_TYPE = 'oauth';

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

@@ -0,0 +1,3 @@
+export { REFRESH_REUSE_GRACE_SECONDS, createSecret, hashSecret, pkceChallenge, registerClient, getClient, issueAuthorizationCode, exchangeAuthorizationCode, rotateRefreshToken, getLiveGrant, revokeByRefreshToken, revokeGrant, listGrants, type RevokedGrant, } 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

@@ -0,0 +1,26 @@
+"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.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; } });
+Object.defineProperty(exports, "hashSecret", { enumerable: true, get: function () { return store_1.hashSecret; } });
+Object.defineProperty(exports, "pkceChallenge", { enumerable: true, get: function () { return store_1.pkceChallenge; } });
+Object.defineProperty(exports, "registerClient", { enumerable: true, get: function () { return store_1.registerClient; } });
+Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return store_1.getClient; } });
+Object.defineProperty(exports, "issueAuthorizationCode", { enumerable: true, get: function () { return store_1.issueAuthorizationCode; } });
+Object.defineProperty(exports, "exchangeAuthorizationCode", { enumerable: true, get: function () { return store_1.exchangeAuthorizationCode; } });
+Object.defineProperty(exports, "rotateRefreshToken", { enumerable: true, get: function () { return store_1.rotateRefreshToken; } });
+Object.defineProperty(exports, "getLiveGrant", { enumerable: true, get: function () { return store_1.getLiveGrant; } });
+Object.defineProperty(exports, "revokeByRefreshToken", { enumerable: true, get: function () { return store_1.revokeByRefreshToken; } });
+Object.defineProperty(exports, "revokeGrant", { enumerable: true, get: function () { return store_1.revokeGrant; } });
+Object.defineProperty(exports, "listGrants", { enumerable: true, get: function () { return store_1.listGrants; } });
+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; } });
+Object.defineProperty(exports, "accessTokenPrincipal", { enumerable: true, get: function () { return access_token_1.accessTokenPrincipal; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "MCP_SCOPES", { enumerable: true, get: function () { return constants_1.MCP_SCOPES; } });
+Object.defineProperty(exports, "PRESET_SCOPE", { enumerable: true, get: function () { return constants_1.PRESET_SCOPE; } });
+Object.defineProperty(exports, "ACCESS_TOKEN_TYPE", { enumerable: true, get: function () { return constants_1.ACCESS_TOKEN_TYPE; } });
+Object.defineProperty(exports, "OAUTH_PRINCIPAL_TYPE", { enumerable: true, get: function () { return constants_1.OAUTH_PRINCIPAL_TYPE; } });

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

@@ -0,0 +1,21 @@
+import type { OAuthServerSettings } from '../../../modules/oauth-server';
+/** Endpoint paths under the issuer. */
+export declare const OAUTH_ENDPOINT_PATHS: {
+    readonly AUTHORIZE: "/api/oauth/authorize";
+    readonly TOKEN: "/api/oauth/token";
+    readonly REGISTER: "/api/oauth/register";
+    readonly REVOKE: "/api/oauth/revoke";
+};
+/** RFC 8414 authorization server metadata. */
+export declare function authorizationServerMetadata(settings: OAuthServerSettings): Record<string, unknown>;
+/** RFC 9728 protected resource metadata for `/mcp`. */
+export declare function protectedResourceMetadata(settings: OAuthServerSettings): Record<string, unknown>;
+/**
+ * Root-relative paths of the two well-known documents. The issuer's and the
+ * resource's paths are appended after the well-known segment (RFC 8414 §3,
+ * RFC 9728 §3).
+ */
+export declare function wellKnownPaths(settings: OAuthServerSettings): {
+    authorizationServer: string;
+    protectedResource: string;
+};

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAUTH_ENDPOINT_PATHS = void 0;
+exports.authorizationServerMetadata = authorizationServerMetadata;
+exports.protectedResourceMetadata = protectedResourceMetadata;
+exports.wellKnownPaths = wellKnownPaths;
+const constants_1 = require("./constants");
+/** Endpoint paths under the issuer. */
+exports.OAUTH_ENDPOINT_PATHS = {
+    AUTHORIZE: '/api/oauth/authorize',
+    TOKEN: '/api/oauth/token',
+    REGISTER: '/api/oauth/register',
+    REVOKE: '/api/oauth/revoke',
+};
+const SCOPES_SUPPORTED = [constants_1.MCP_SCOPES.READ, constants_1.MCP_SCOPES.FULL];
+/** RFC 8414 authorization server metadata. */
+function authorizationServerMetadata(settings) {
+    const at = (path) => `${settings.issuer}${path}`;
+    return {
+        issuer: settings.issuer,
+        authorization_endpoint: at(exports.OAUTH_ENDPOINT_PATHS.AUTHORIZE),
+        token_endpoint: at(exports.OAUTH_ENDPOINT_PATHS.TOKEN),
+        registration_endpoint: at(exports.OAUTH_ENDPOINT_PATHS.REGISTER),
+        revocation_endpoint: at(exports.OAUTH_ENDPOINT_PATHS.REVOKE),
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['none'],
+        revocation_endpoint_auth_methods_supported: ['none'],
+        scopes_supported: SCOPES_SUPPORTED,
+    };
+}
+/** RFC 9728 protected resource metadata for `/mcp`. */
+function protectedResourceMetadata(settings) {
+    return {
+        resource: settings.resource,
+        authorization_servers: [settings.issuer],
+        bearer_methods_supported: ['header'],
+        scopes_supported: SCOPES_SUPPORTED,
+    };
+}
+/**
+ * Root-relative paths of the two well-known documents. The issuer's and the
+ * resource's paths are appended after the well-known segment (RFC 8414 §3,
+ * RFC 9728 §3).
+ */
+function wellKnownPaths(settings) {
+    const issuerPath = new URL(settings.issuer).pathname.replace(/\/+$/, '');
+    return {
+        authorizationServer: `/.well-known/oauth-authorization-server${issuerPath}`,
+        protectedResource: new URL(settings.resourceMetadataUrl).pathname,
+    };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Dynamic client registration (RFC 7591) for public MCP clients: validation
+ * of the requested client metadata, and a per-address registration limit.
+ */
+/** Whether a value carries a control character. */
+export declare function hasControlCharacters(value: string): boolean;
+/** A client name as the consent page may show it: no controls, no direction overrides, trimmed. */
+export declare function displayableClientName(name: string): string;
+/**
+ * The address a registration counts against: IPv4 as is, IPv6 by its /64,
+ * which one host or network usually holds in full.
+ */
+export declare function registrationAddressKey(address: string): string;
+export declare const REGISTRATION_ERRORS: {
+    readonly INVALID_REDIRECT_URI: "invalid_redirect_uri";
+    readonly INVALID_CLIENT_METADATA: "invalid_client_metadata";
+};
+export type RegistrationResult = {
+    ok: true;
+    clientName?: string;
+    redirectUris: string[];
+} | {
+    ok: false;
+    error: string;
+    description: string;
+};
+/**
+ * Loopback http or https on any port, or an https URI equal, in canonical
+ * form, to one the deployment allows. Matching whole URIs, not hosts, keeps a
+ * code from landing on any other path, query or port of an allowed host.
+ */
+export declare function isAllowedRedirectUri(uri: string, allowedUris: string[]): boolean;
+export declare function validateClientMetadata(body: unknown, allowedUris: string[]): RegistrationResult;
+/** A fixed-window count of registrations per address, in memory, per process. */
+export declare class RegistrationLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private windows;
+    constructor(limit: number, windowMs: number);
+    /** Count one registration from `address`; false when over the limit. */
+    allow(address: string, now?: number): boolean;
+}

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

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Dynamic client registration (RFC 7591) for public MCP clients: validation
+ * of the requested client metadata, and a per-address registration limit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistrationLimiter = exports.REGISTRATION_ERRORS = void 0;
+exports.hasControlCharacters = hasControlCharacters;
+exports.displayableClientName = displayableClientName;
+exports.registrationAddressKey = registrationAddressKey;
+exports.isAllowedRedirectUri = isAllowedRedirectUri;
+exports.validateClientMetadata = validateClientMetadata;
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+/** C0 controls, DEL and C1 controls: never part of a token, an id or a URI. */
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+/** Characters that reorder or hide text: a self-chosen client name must not use them to spoof another. */
+const DISPLAY_SPOOFING = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g;
+/** Whether a value carries a control character. */
+function hasControlCharacters(value) {
+    return CONTROL_CHARACTERS.test(value);
+}
+/** A client name as the consent page may show it: no controls, no direction overrides, trimmed. */
+function displayableClientName(name) {
+    return name.replace(DISPLAY_SPOOFING, '').trim();
+}
+/** An IPv6 address as its eight groups, or null when it is not one. */
+function ipv6Groups(ip) {
+    const halves = ip.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(':') : [];
+    if (halves.length === 1)
+        return head.length === 8 ? head : null;
+    const tail = halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - head.length - tail.length;
+    return missing < 0 ? null : [...head, ...Array(missing).fill('0'), ...tail];
+}
+/**
+ * The address a registration counts against: IPv4 as is, IPv6 by its /64,
+ * which one host or network usually holds in full.
+ */
+function registrationAddressKey(address) {
+    const ip = address.split('%')[0];
+    if (ip.startsWith('::ffff:') && ip.includes('.'))
+        return ip.slice(7);
+    if (!ip.includes(':'))
+        return ip;
+    const groups = ipv6Groups(ip);
+    if (!groups)
+        return ip;
+    return `${groups.slice(0, 4).map((g) => (g.replace(/^0+(?=.)/, '') || '0').toLowerCase()).join(':')}::/64`;
+}
+const MAX_REDIRECT_URIS = 10;
+const MAX_URI_LENGTH = 2048;
+const MAX_NAME_LENGTH = 200;
+const GRANT_TYPES = new Set(['authorization_code', 'refresh_token']);
+const RESPONSE_TYPES = new Set(['code']);
+exports.REGISTRATION_ERRORS = {
+    INVALID_REDIRECT_URI: 'invalid_redirect_uri',
+    INVALID_CLIENT_METADATA: 'invalid_client_metadata',
+};
+function invalid(error, description) {
+    return { ok: false, error, description };
+}
+/**
+ * Loopback http or https on any port, or an https URI equal, in canonical
+ * form, to one the deployment allows. Matching whole URIs, not hosts, keeps a
+ * code from landing on any other path, query or port of an allowed host.
+ */
+function isAllowedRedirectUri(uri, allowedUris) {
+    if (uri.length > MAX_URI_LENGTH || hasControlCharacters(uri) || uri.trim() !== uri)
+        return false;
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    if (url.hash || url.username || url.password)
+        return false;
+    if (url.protocol === 'http:')
+        return LOOPBACK_HOSTS.has(url.hostname);
+    if (url.protocol !== 'https:')
+        return false;
+    if (LOOPBACK_HOSTS.has(url.hostname))
+        return true;
+    return allowedUris.includes(url.href);
+}
+const isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+function validateClientMetadata(body, allowedUris) {
+    const input = (body ?? {});
+    const { redirect_uris, client_name, token_endpoint_auth_method, grant_types, response_types } = input;
+    if (!isStringArray(redirect_uris) || redirect_uris.length === 0 || redirect_uris.length > MAX_REDIRECT_URIS) {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_REDIRECT_URI, `redirect_uris must list 1 to ${MAX_REDIRECT_URIS} URIs`);
+    }
+    const refused = redirect_uris.find((uri) => !isAllowedRedirectUri(uri, allowedUris));
+    if (refused !== undefined) {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_REDIRECT_URI, `redirect URI not allowed: ${refused.slice(0, 200)}`);
+    }
+    if (client_name !== undefined && (typeof client_name !== 'string' || client_name.length > MAX_NAME_LENGTH)) {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_CLIENT_METADATA, `client_name must be a string of at most ${MAX_NAME_LENGTH} characters`);
+    }
+    const shownName = typeof client_name === 'string' ? displayableClientName(client_name) : undefined;
+    if (token_endpoint_auth_method !== undefined && token_endpoint_auth_method !== 'none') {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_CLIENT_METADATA, 'only public clients are supported: token_endpoint_auth_method must be none');
+    }
+    if (grant_types !== undefined && !(isStringArray(grant_types) && grant_types.every((g) => GRANT_TYPES.has(g)))) {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_CLIENT_METADATA, 'grant_types may include only authorization_code and refresh_token');
+    }
+    if (response_types !== undefined && !(isStringArray(response_types) && response_types.every((r) => RESPONSE_TYPES.has(r)))) {
+        return invalid(exports.REGISTRATION_ERRORS.INVALID_CLIENT_METADATA, 'response_types may include only code');
+    }
+    return { ok: true, clientName: shownName || undefined, redirectUris: redirect_uris };
+}
+/** A fixed-window count of registrations per address, in memory, per process. */
+class RegistrationLimiter {
+    constructor(limit, windowMs) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.windows = new Map();
+    }
+    /** Count one registration from `address`; false when over the limit. */
+    allow(address, now = Date.now()) {
+        for (const [key, w] of this.windows)
+            if (now - w.start >= this.windowMs)
+                this.windows.delete(key);
+        const window = this.windows.get(address) ?? { start: now, count: 0 };
+        window.count += 1;
+        this.windows.set(address, window);
+        return window.count <= this.limit;
+    }
+}
+exports.RegistrationLimiter = RegistrationLimiter;

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

@@ -0,0 +1,34 @@
+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";
+/**
+ * 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;
+ * the grant must be live and its owner active.
+ */
+export declare const EXCHANGE_CODE = "\n  WITH c AS (\n    UPDATE lt_oauth_codes c SET used_at = NOW()\n    FROM lt_oauth_grants g\n    WHERE c.code_hash = $1 AND c.used_at IS NULL AND c.expires_at > NOW()\n      AND c.redirect_uri = $3 AND c.code_challenge = $4\n      AND g.id = c.grant_id AND g.client_id = $2 AND g.revoked_at IS NULL\n    RETURNING c.grant_id, c.resource\n  ),\n  g AS (\n    SELECT g.* FROM lt_oauth_grants g\n    JOIN c ON c.grant_id = g.id\n    JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'\n  ),\n  rt AS (\n    INSERT INTO lt_oauth_refresh_tokens (token_hash, grant_id, expires_at)\n    SELECT $5, g.id, NOW() + make_interval(secs => $6) FROM g\n    RETURNING grant_id\n  )\n  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, c.resource, \n  COALESCE((\n    SELECT json_agg(json_build_object(\n      'role', r.role, 'type', r.type, 'read_scope', r.read_scope, 'write_scope', r.write_scope\n    ) ORDER BY r.role)\n    FROM lt_user_roles r WHERE r.user_id = g.user_id\n  ), '[]'::json) AS roles\n  FROM g JOIN rt ON rt.grant_id = g.id JOIN c ON c.grant_id = g.id";
+/**
+ * The grant an access token names, as it stands now: only while the grant is
+ * unrevoked and its owner active, with the owner's current memberships. One
+ * primary-key lookup per /mcp request, so a revocation, a deactivation or a
+ * role change takes effect on the next request in every process.
+ */
+export declare const GET_LIVE_GRANT = "\n  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, \n  COALESCE((\n    SELECT json_agg(json_build_object(\n      'role', r.role, 'type', r.type, 'read_scope', r.read_scope, 'write_scope', r.write_scope\n    ) ORDER BY r.role)\n    FROM lt_user_roles r WHERE r.user_id = g.user_id\n  ), '[]'::json) AS roles\n  FROM lt_oauth_grants g\n  JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'\n  WHERE g.id = $1 AND g.user_id = $2 AND g.revoked_at IS NULL";
+/**
+ * Rotate a refresh token: mark the old one used and issue its successor, only
+ * for the client that holds it and while the grant is live and its owner
+ * active. Returns current roles.
+ */
+export declare const ROTATE_REFRESH_TOKEN = "\n  WITH old AS (\n    UPDATE lt_oauth_refresh_tokens t SET used_at = NOW()\n    FROM lt_oauth_grants og\n    WHERE t.token_hash = $1 AND t.used_at IS NULL AND t.expires_at > NOW()\n      AND og.id = t.grant_id AND og.client_id = $4\n    RETURNING t.grant_id\n  ),\n  g AS (\n    SELECT g.* FROM lt_oauth_grants g\n    JOIN old ON old.grant_id = g.id\n    JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'\n    WHERE g.revoked_at IS NULL\n  ),\n  rt AS (\n    INSERT INTO lt_oauth_refresh_tokens (token_hash, grant_id, expires_at)\n    SELECT $2, g.id, NOW() + make_interval(secs => $3) FROM g\n    RETURNING grant_id\n  )\n  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, \n  COALESCE((\n    SELECT json_agg(json_build_object(\n      'role', r.role, 'type', r.type, 'read_scope', r.read_scope, 'write_scope', r.write_scope\n    ) ORDER BY r.role)\n    FROM lt_user_roles r WHERE r.user_id = g.user_id\n  ), '[]'::json) AS roles\n  FROM g JOIN rt ON rt.grant_id = g.id";
+/**
+ * Revoke the grant of a refresh token presented again after it was used,
+ * outside the retry grace window: the token has leaked.
+ */
+export declare const REVOKE_ON_REFRESH_REUSE = "\n  UPDATE lt_oauth_grants g SET revoked_at = NOW()\n  FROM lt_oauth_refresh_tokens t\n  WHERE t.token_hash = $1 AND t.used_at IS NOT NULL\n    AND t.used_at < NOW() - make_interval(secs => $2)\n    AND g.id = t.grant_id AND g.revoked_at IS NULL\n  RETURNING g.id AS grant_id, g.user_id";
+/** Revoke the grant a refresh token belongs to, for the client presenting it. */
+export declare const REVOKE_BY_REFRESH_TOKEN = "\n  UPDATE lt_oauth_grants g SET revoked_at = NOW()\n  FROM lt_oauth_refresh_tokens t\n  WHERE t.token_hash = $1 AND g.id = t.grant_id AND g.client_id = $2 AND g.revoked_at IS NULL\n  RETURNING g.id AS grant_id, g.user_id";
+/** Revoke a grant by id, optionally only when it belongs to the given user. */
+export declare const REVOKE_GRANT = "\n  UPDATE lt_oauth_grants SET revoked_at = NOW()\n  WHERE id = $1 AND ($2::uuid IS NULL OR user_id = $2) AND revoked_at IS NULL\n  RETURNING id AS grant_id, user_id";
+/** A person's live grants that a client has put to use, newest first. */
+export declare const LIST_GRANTS = "\n  SELECT g.id AS grant_id, g.client_id, c.client_name, g.policy, g.scope, g.created_at,\n         (SELECT MAX(t.created_at) FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id) AS last_used_at\n  FROM lt_oauth_grants g\n  JOIN lt_oauth_clients c ON c.client_id = g.client_id\n  WHERE g.user_id = $1 AND g.revoked_at IS NULL\n    AND EXISTS (SELECT 1 FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id)\n  ORDER BY g.created_at DESC";

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

@@ -0,0 +1,123 @@
+"use strict";
+// ── OAuth authorization server queries ─────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_GRANTS = exports.REVOKE_GRANT = exports.REVOKE_BY_REFRESH_TOKEN = exports.REVOKE_ON_REFRESH_REUSE = exports.ROTATE_REFRESH_TOKEN = exports.GET_LIVE_GRANT = exports.EXCHANGE_CODE = exports.ISSUE_CODE = exports.GET_CLIENT = exports.INSERT_CLIENT = void 0;
+/** The grant owner's current memberships, as a JSON array. Expects alias `g`. */
+const GRANT_ROLES = `
+  COALESCE((
+    SELECT json_agg(json_build_object(
+      'role', r.role, 'type', r.type, 'read_scope', r.read_scope, 'write_scope', r.write_scope
+    ) ORDER BY r.role)
+    FROM lt_user_roles r WHERE r.user_id = g.user_id
+  ), '[]'::json)`;
+exports.INSERT_CLIENT = `
+  INSERT INTO lt_oauth_clients (client_id, client_name, redirect_uris)
+  VALUES ($1, $2, $3)
+  RETURNING client_id, client_name, redirect_uris, created_at`;
+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. */
+exports.ISSUE_CODE = `
+  WITH g AS (
+    INSERT INTO lt_oauth_grants (user_id, client_id, policy, scope)
+    VALUES ($1, $2, $3, $4)
+    RETURNING id
+  )
+  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
+  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;
+ * the grant must be live and its owner active.
+ */
+exports.EXCHANGE_CODE = `
+  WITH c AS (
+    UPDATE lt_oauth_codes c SET used_at = NOW()
+    FROM lt_oauth_grants g
+    WHERE c.code_hash = $1 AND c.used_at IS NULL AND c.expires_at > NOW()
+      AND c.redirect_uri = $3 AND c.code_challenge = $4
+      AND g.id = c.grant_id AND g.client_id = $2 AND g.revoked_at IS NULL
+    RETURNING c.grant_id, c.resource
+  ),
+  g AS (
+    SELECT g.* FROM lt_oauth_grants g
+    JOIN c ON c.grant_id = g.id
+    JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'
+  ),
+  rt AS (
+    INSERT INTO lt_oauth_refresh_tokens (token_hash, grant_id, expires_at)
+    SELECT $5, g.id, NOW() + make_interval(secs => $6) FROM g
+    RETURNING grant_id
+  )
+  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, c.resource, ${GRANT_ROLES} AS roles
+  FROM g JOIN rt ON rt.grant_id = g.id JOIN c ON c.grant_id = g.id`;
+/**
+ * The grant an access token names, as it stands now: only while the grant is
+ * unrevoked and its owner active, with the owner's current memberships. One
+ * primary-key lookup per /mcp request, so a revocation, a deactivation or a
+ * role change takes effect on the next request in every process.
+ */
+exports.GET_LIVE_GRANT = `
+  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, ${GRANT_ROLES} AS roles
+  FROM lt_oauth_grants g
+  JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'
+  WHERE g.id = $1 AND g.user_id = $2 AND g.revoked_at IS NULL`;
+/**
+ * Rotate a refresh token: mark the old one used and issue its successor, only
+ * for the client that holds it and while the grant is live and its owner
+ * active. Returns current roles.
+ */
+exports.ROTATE_REFRESH_TOKEN = `
+  WITH old AS (
+    UPDATE lt_oauth_refresh_tokens t SET used_at = NOW()
+    FROM lt_oauth_grants og
+    WHERE t.token_hash = $1 AND t.used_at IS NULL AND t.expires_at > NOW()
+      AND og.id = t.grant_id AND og.client_id = $4
+    RETURNING t.grant_id
+  ),
+  g AS (
+    SELECT g.* FROM lt_oauth_grants g
+    JOIN old ON old.grant_id = g.id
+    JOIN lt_users u ON u.id = g.user_id AND u.status = 'active'
+    WHERE g.revoked_at IS NULL
+  ),
+  rt AS (
+    INSERT INTO lt_oauth_refresh_tokens (token_hash, grant_id, expires_at)
+    SELECT $2, g.id, NOW() + make_interval(secs => $3) FROM g
+    RETURNING grant_id
+  )
+  SELECT g.id AS grant_id, g.user_id, g.client_id, g.policy, g.scope, ${GRANT_ROLES} AS roles
+  FROM g JOIN rt ON rt.grant_id = g.id`;
+/**
+ * Revoke the grant of a refresh token presented again after it was used,
+ * outside the retry grace window: the token has leaked.
+ */
+exports.REVOKE_ON_REFRESH_REUSE = `
+  UPDATE lt_oauth_grants g SET revoked_at = NOW()
+  FROM lt_oauth_refresh_tokens t
+  WHERE t.token_hash = $1 AND t.used_at IS NOT NULL
+    AND t.used_at < NOW() - make_interval(secs => $2)
+    AND g.id = t.grant_id AND g.revoked_at IS NULL
+  RETURNING g.id AS grant_id, g.user_id`;
+/** Revoke the grant a refresh token belongs to, for the client presenting it. */
+exports.REVOKE_BY_REFRESH_TOKEN = `
+  UPDATE lt_oauth_grants g SET revoked_at = NOW()
+  FROM lt_oauth_refresh_tokens t
+  WHERE t.token_hash = $1 AND g.id = t.grant_id AND g.client_id = $2 AND g.revoked_at IS NULL
+  RETURNING g.id AS grant_id, g.user_id`;
+/** Revoke a grant by id, optionally only when it belongs to the given user. */
+exports.REVOKE_GRANT = `
+  UPDATE lt_oauth_grants SET revoked_at = NOW()
+  WHERE id = $1 AND ($2::uuid IS NULL OR user_id = $2) AND revoked_at IS NULL
+  RETURNING id AS grant_id, user_id`;
+/** A person's live grants that a client has put to use, newest first. */
+exports.LIST_GRANTS = `
+  SELECT g.id AS grant_id, g.client_id, c.client_name, g.policy, g.scope, g.created_at,
+         (SELECT MAX(t.created_at) FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id) AS last_used_at
+  FROM lt_oauth_grants g
+  JOIN lt_oauth_clients c ON c.client_id = g.client_id
+  WHERE g.user_id = $1 AND g.revoked_at IS NULL
+    AND EXISTS (SELECT 1 FROM lt_oauth_refresh_tokens t WHERE t.grant_id = g.id)
+  ORDER BY g.created_at DESC`;

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

@@ -0,0 +1,74 @@
+import type { LTGrantPolicy, LTGrantSnapshot, LTGrantSummary, LTOAuthClient } from '../../../types/oauth-server';
+/** A refresh token reused within this many seconds is treated as a client retry. */
+export declare const REFRESH_REUSE_GRACE_SECONDS = 10;
+export interface RevokedGrant {
+    grant_id: string;
+    user_id: string;
+}
+/** A new random secret: 32 bytes, base64url. */
+export declare function createSecret(): string;
+/** SHA-256 of a secret. Codes and refresh tokens are stored only as hashes. */
+export declare function hashSecret(secret: string): string;
+/** The PKCE S256 challenge for a code verifier (RFC 7636). */
+export declare function pkceChallenge(verifier: string): string;
+export declare function registerClient(input: {
+    clientName?: string;
+    redirectUris: string[];
+}): Promise<LTOAuthClient>;
+export declare const isClientId: (value: string) => boolean;
+export declare function getClient(clientId: string): Promise<LTOAuthClient | null>;
+/** Record the person's consent as a grant and return a one-time code for it. */
+export declare function issueAuthorizationCode(input: {
+    userId: string;
+    clientId: string;
+    policy: LTGrantPolicy;
+    scope: string;
+    redirectUri: string;
+    codeChallenge: string;
+    resource?: string;
+    ttlSeconds: number;
+}): Promise<{
+    code: string;
+    grantId: string;
+}>;
+/**
+ * Exchange a code for the grant and its first refresh token. Null when the
+ * code is unknown, used, expired, for another client or redirect URI, fails
+ * PKCE, or its grant or owner is no longer active.
+ */
+export declare function exchangeAuthorizationCode(input: {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+    refreshTtlSeconds: number;
+}): Promise<{
+    snapshot: LTGrantSnapshot;
+    resource: string | null;
+    refreshToken: string;
+} | null>;
+/**
+ * Rotate a refresh token for the client that holds it. Null when it is
+ * unknown, used, expired, another client's, or its grant or owner is no
+ * longer active. A used token presented again outside the
+ * grace window revokes its grant, and `revoked` reports it.
+ */
+export declare function rotateRefreshToken(input: {
+    refreshToken: string;
+    clientId: string;
+    refreshTtlSeconds: number;
+}): Promise<{
+    snapshot: LTGrantSnapshot;
+    refreshToken: string;
+} | {
+    snapshot: null;
+    revoked: RevokedGrant | null;
+}>;
+/** The live grant an access token names; null when it is revoked, its owner inactive, or it is another user's. */
+export declare function getLiveGrant(grantId: string, userId: string): Promise<LTGrantSnapshot | null>;
+/** Revoke the grant behind a refresh token presented by its own client (RFC 7009). */
+export declare function revokeByRefreshToken(refreshToken: string, clientId: string): Promise<RevokedGrant | null>;
+/** Revoke a grant; with `userId`, only when it belongs to that user. */
+export declare function revokeGrant(grantId: string, userId?: string): Promise<RevokedGrant | null>;
+/** The person's live grants that a client has put to use. */
+export declare function listGrants(userId: string): Promise<LTGrantSummary[]>;