@hotmeshio/long-tail 0.23.2 → 0.24.0

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[]>;

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

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isClientId = exports.REFRESH_REUSE_GRACE_SECONDS = void 0;
+exports.createSecret = createSecret;
+exports.hashSecret = hashSecret;
+exports.pkceChallenge = pkceChallenge;
+exports.registerClient = registerClient;
+exports.getClient = getClient;
+exports.issueAuthorizationCode = issueAuthorizationCode;
+exports.exchangeAuthorizationCode = exchangeAuthorizationCode;
+exports.rotateRefreshToken = rotateRefreshToken;
+exports.getLiveGrant = getLiveGrant;
+exports.revokeByRefreshToken = revokeByRefreshToken;
+exports.revokeGrant = revokeGrant;
+exports.listGrants = listGrants;
+const crypto = __importStar(require("crypto"));
+const db_1 = require("../../../lib/db");
+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. */
+exports.REFRESH_REUSE_GRACE_SECONDS = 10;
+/** A new random secret: 32 bytes, base64url. */
+function createSecret() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+/** SHA-256 of a secret. Codes and refresh tokens are stored only as hashes. */
+function hashSecret(secret) {
+    return crypto.createHash('sha256').update(secret).digest('hex');
+}
+/** The PKCE S256 challenge for a code verifier (RFC 7636). */
+function pkceChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+async function registerClient(input) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.INSERT_CLIENT, [
+        `ltc_${createSecret()}`, input.clientName ?? null, input.redirectUris,
+    ]);
+    return rows[0];
+}
+/** A client id as registerClient issues it; anything else names no client and never reaches SQL. */
+const CLIENT_ID = /^ltc_[A-Za-z0-9_-]{43}$/;
+const isClientId = (value) => CLIENT_ID.test(value);
+exports.isClientId = isClientId;
+async function getClient(clientId) {
+    if (!(0, exports.isClientId)(clientId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_CLIENT, [clientId]);
+    return rows[0] ?? null;
+}
+/** Record the person's consent as a grant and return a one-time code for it. */
+async function issueAuthorizationCode(input) {
+    if (!(0, uuid_1.isUuid)(input.userId))
+        throw new Error('issueAuthorizationCode: userId must be a UUID');
+    const code = createSecret();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.ISSUE_CODE, [
+        input.userId, input.clientId, input.policy, input.scope,
+        hashSecret(code), input.redirectUri, input.codeChallenge, input.resource ?? null, input.ttlSeconds,
+    ]);
+    return { code, grantId: rows[0].grant_id };
+}
+/**
+ * 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.
+ */
+async function exchangeAuthorizationCode(input) {
+    const refreshToken = createSecret();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.EXCHANGE_CODE, [
+        hashSecret(input.code), input.clientId, input.redirectUri, pkceChallenge(input.codeVerifier),
+        hashSecret(refreshToken), input.refreshTtlSeconds,
+    ]);
+    if (!rows[0])
+        return null;
+    const { resource, ...snapshot } = rows[0];
+    return { snapshot, resource, refreshToken };
+}
+/**
+ * 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.
+ */
+async function rotateRefreshToken(input) {
+    const pool = (0, db_1.getPool)();
+    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])
+        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 };
+}
+/** The live grant an access token names; null when it is revoked, its owner inactive, or it is another user's. */
+async function getLiveGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || !(0, uuid_1.isUuid)(userId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_LIVE_GRANT, [grantId, userId]);
+    return rows[0] ?? null;
+}
+/** Revoke the grant behind a refresh token presented by its own client (RFC 7009). */
+async function revokeByRefreshToken(refreshToken, clientId) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_BY_REFRESH_TOKEN, [hashSecret(refreshToken), clientId]);
+    return rows[0] ?? null;
+}
+/** Revoke a grant; with `userId`, only when it belongs to that user. */
+async function revokeGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || (userId !== undefined && !(0, uuid_1.isUuid)(userId)))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_GRANT, [grantId, userId ?? null]);
+    return rows[0] ?? null;
+}
+/** The person's live grants that a client has put to use. */
+async function listGrants(userId) {
+    if (!(0, uuid_1.isUuid)(userId))
+        return [];
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_GRANTS, [userId]);
+    return rows;
+}

package/build/services/auth/sql.d.ts

@@ -3,6 +3,7 @@ export declare const GET_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, key_h
 export declare const GET_ALL_ACTIVE_BOT_KEYS = "\n  SELECT id, name, user_id, key_hash, scopes\n  FROM lt_bot_api_keys\n  WHERE (expires_at IS NULL OR expires_at > NOW())";
 export declare const UPDATE_BOT_KEY_LAST_USED = "\n  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1";
 export declare const DELETE_BOT_KEY = "\n  DELETE FROM lt_bot_api_keys WHERE id = $1";
+export declare const GET_BOT_KEY_OWNER = "\n  SELECT user_id FROM lt_bot_api_keys WHERE id = $1";
 export declare const LIST_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at\n  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at";
 export declare const INSERT_SERVICE_TOKEN = "\n  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)\n  VALUES ($1, $2, $3, $4, $5) RETURNING id";
 export declare const GET_ALL_ACTIVE_SERVICE_TOKENS = "\n  SELECT id, name, token_hash FROM lt_service_tokens\n  WHERE (expires_at IS NULL OR expires_at > NOW())";

package/build/services/auth/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ── Bot API key queries ─────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
+exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.GET_BOT_KEY_OWNER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
 exports.INSERT_BOT_KEY = `
   INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
   VALUES ($1, $2, $3, $4, $5) RETURNING id`;
@@ -18,6 +18,8 @@ exports.UPDATE_BOT_KEY_LAST_USED = `
   UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
 exports.DELETE_BOT_KEY = `
   DELETE FROM lt_bot_api_keys WHERE id = $1`;
+exports.GET_BOT_KEY_OWNER = `
+  SELECT user_id FROM lt_bot_api_keys WHERE id = $1`;
 exports.LIST_BOT_KEYS_BY_USER = `
   SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
   FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;

package/build/services/escalation/queries.js

@@ -278,8 +278,13 @@ async function listDistinctTypes() {
  * and an out-of-scope role yields an empty result, not someone else's rows.
  */
 function narrowRoleWithinScope(role, visibleRoles) {
-    if (!role || !visibleRoles)
-        return { role, roles: visibleRoles, empty: false };
+    if (!visibleRoles)
+        return { role, roles: undefined, empty: false };
+    // An empty scope sees nothing; the SDK would read an empty list as no filter.
+    if (visibleRoles.length === 0)
+        return { empty: true };
+    if (!role)
+        return { roles: visibleRoles, empty: false };
     if (!visibleRoles.includes(role))
         return { empty: true };
     return { role, roles: undefined, empty: false };

package/build/services/export/index.d.ts

@@ -48,6 +48,16 @@ export interface WorkflowEnvelopes {
  * so, making this the natural polling body.
  */
 export declare function getWorkflowEnvelopes(workflowId: string, taskQueue: string, workflowName: string): Promise<WorkflowEnvelopes>;
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+export declare function getWorkflowStartIdentity(workflowId: string): Promise<{
+    userId?: string;
+    initiatedBy?: string;
+} | null>;
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/export/index.js

@@ -4,11 +4,13 @@ exports.exportWorkflow = exportWorkflow;
 exports.getWorkflowStatus = getWorkflowStatus;
 exports.exportWorkflowExecution = exportWorkflowExecution;
 exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
+exports.getWorkflowStartIdentity = getWorkflowStartIdentity;
 exports.getWorkflowState = getWorkflowState;
 exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const client_1 = require("./client");
+const resolve_1 = require("../task/resolve");
 const post_process_1 = require("./post-process");
 const workflow_state_1 = require("../workflow-state");
 /** Error thrown when a workflow job is not found (expired or never existed). */
@@ -123,6 +125,31 @@ async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
     const output = await handle.output().catch(() => null);
     return { workflow_id: workflowId, status: reading.state, input, output: output ?? null };
 }
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+async function getWorkflowStartIdentity(workflowId) {
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveWorkflowHandle)(workflowId);
+    }
+    catch {
+        return null;
+    }
+    const handle = await (0, client_1.getHandle)(resolved.taskQueue, resolved.workflowName, workflowId);
+    const args = await handle.input().catch(() => undefined);
+    const envelope = Array.isArray(args) && args.length >= 1 ? args[0] : null;
+    const lt = (envelope && typeof envelope === 'object' ? envelope.lt : null) ?? null;
+    if (!lt)
+        return {};
+    return {
+        ...(typeof lt.userId === 'string' ? { userId: lt.userId } : {}),
+        ...(typeof lt.initiatedBy === 'string' ? { initiatedBy: lt.initiatedBy } : {}),
+    };
+}
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.