@trackunit/serverside-utils 0.4.25-alpha-27ad777c16e.0 → 0.4.28

package/index.cjs.js

@@ -1,7 +1,108 @@
 'use strict';
 
-var jwtDecode = require('jwt-decode');
 var zod = require('zod');
+var jwtDecode = require('jwt-decode');
+
+const GraphqlErrorSchema = zod.z.object({
+    message: zod.z.string(),
+});
+const readEnvironmentVariable = (key) => {
+    try {
+        return process.env[key];
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Resolves the public GraphQL base URL for the current SDK environment.
+ *
+ * The environment is read from the `SDK_ENVIRONMENT` variable and defaults to
+ * `PROD` when unset.
+ *
+ * @returns {string} The public GraphQL endpoint for the resolved environment.
+ * @throws {Error} When `SDK_ENVIRONMENT` is set to an unknown value.
+ */
+const getGraphqlUrl = () => {
+    const sdkEnvironment = readEnvironmentVariable("SDK_ENVIRONMENT") ?? "PROD";
+    switch (sdkEnvironment.toUpperCase()) {
+        case "DEV":
+            return "https://dev.iris.trackunit.com/api/graphql";
+        case "STAGE":
+            return "https://stage.iris.trackunit.com/api/graphql";
+        case "PROD":
+            return "https://iris.trackunit.com/api/graphql";
+        default:
+            throw new Error(`Unknown SDK environment: ${sdkEnvironment}`);
+    }
+};
+/**
+ * Appends the operation name to the base URL so each call stays attributable by
+ * its unique operation name when observed in GraphQL Hive.
+ */
+const buildOperationUrl = (baseUrl, operationName) => `${baseUrl}/${operationName}`;
+const getErrorBody = async (response) => {
+    try {
+        const text = await response.text();
+        return text.length > 200 ? `${text.slice(0, 200)}...` : text;
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * Executes a query against the public GraphQL API and returns its validated
+ * `data` payload.
+ *
+ * The operation name is appended to the URL so each call stays attributable by
+ * its unique operation name when observed in GraphQL Hive.
+ *
+ * @template TData The shape of the validated `data` payload.
+ * @param props - The properties of the query execution.
+ * @param props.baseUrl - The base GraphQL URL, e.g. from {@link getGraphqlUrl}.
+ * @param props.userToken - The user token used to authenticate the request.
+ * @param props.operationName - The GraphQL operation name. Must be unique so calls stay traceable.
+ * @param props.query - The GraphQL query document.
+ * @param props.variables - Optional variables passed to the query.
+ * @param props.dataSchema - Zod schema used to validate and type the `data` payload.
+ * @returns {Promise<TData>} The validated `data` payload of the response.
+ * @throws {Error} When the HTTP response is not 2xx.
+ * @throws {Error} When the response body cannot be parsed against the expected shape.
+ * @throws {Error} When the response contains GraphQL `errors`.
+ * @throws {Error} When the response contains no `data`.
+ */
+const executePublicQuery = async ({ baseUrl, userToken, operationName, query, variables, dataSchema, }) => {
+    const url = buildOperationUrl(baseUrl, operationName);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${userToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ operationName, query, variables }),
+    });
+    if (!response.ok) {
+        const errorBody = await getErrorBody(response);
+        throw new Error(`Failed to execute ${operationName} at ${url}: ${response.status} ${response.statusText}${errorBody ? ` - ${errorBody}` : ""}`);
+    }
+    const responseData = await response.json();
+    const parseResult = zod.z
+        .object({
+        data: dataSchema.nullish(),
+        errors: zod.z.array(GraphqlErrorSchema).optional(),
+    })
+        .safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid ${operationName} response from ${url}: ${parseResult.error.message}`);
+    }
+    if (parseResult.data.errors && parseResult.data.errors.length > 0) {
+        throw new Error(`GraphQL error in ${operationName}: ${parseResult.data.errors.map(error => error.message).join(", ")}`);
+    }
+    if (parseResult.data.data === undefined || parseResult.data.data === null) {
+        throw new Error(`No data returned from ${operationName} at ${url}`);
+    }
+    return parseResult.data.data;
+};
 
 /**
  * Header key for the account admin iris app token.
@@ -243,9 +344,171 @@ const getDatabricksAccessToken = async ({ context, databricksHost, databricksCli
     };
 };
 
+/**
+ * Operation names are intentionally verbose and unique so the calls are easy to
+ * trace back to this utility (e.g. when inspecting GraphQL Hive). The
+ * `ServersideUtils` prefix already attributes every call to this utility.
+ */
+const USER_PERMISSIONS_OPERATION_NAME = "ServersideUtilsHasScopesUserPermissions";
+const USER_PERMISSIONS_QUERY = `query ${USER_PERMISSIONS_OPERATION_NAME}($securableIds: [ID!]!) {
+  userCurrent {
+    user {
+      permissions(securableIds: $securableIds) {
+        securableId
+        permissions
+      }
+    }
+  }
+}`;
+const UserPermissionsDataSchema = zod.z.object({
+    userCurrent: zod.z
+        .object({
+        user: zod.z
+            .object({
+            permissions: zod.z
+                .array(zod.z
+                .object({
+                securableId: zod.z.string(),
+                permissions: zod.z.array(zod.z.string().nullable()).nullable(),
+            })
+                .nullable())
+                .nullable(),
+        })
+            .nullable(),
+    })
+        .nullable(),
+});
+/**
+ * The only scope prefix currently supported. Scopes are configured by the
+ * developer in the Iris app manifest and follow the `<securable>.<...>` shape
+ * (e.g. `account.group.manage`). Only account-securable scopes can be checked
+ * against the current account.
+ */
+const SUPPORTED_SCOPE_PREFIX = "account";
+const getScopePrefix = (scope) => scope.split(".")[0] ?? "";
+const getCurrentUserAccountPermissions = async ({ baseUrl, userToken, accountId, }) => {
+    const data = await executePublicQuery({
+        baseUrl,
+        userToken,
+        operationName: USER_PERMISSIONS_OPERATION_NAME,
+        query: USER_PERMISSIONS_QUERY,
+        variables: { securableIds: [accountId] },
+        dataSchema: UserPermissionsDataSchema,
+    });
+    return (data.userCurrent?.user?.permissions ?? [])
+        .flatMap(securablePermission => securablePermission?.permissions ?? [])
+        .filter((permission) => permission !== null);
+};
+/**
+ * Checks whether the current logged-in user has all required scopes on their
+ * current account, using the public GraphQL API.
+ *
+ * The current account id is read from the user token, then the user's scopes
+ * for that account are fetched via `userCurrent.user.permissions`.
+ *
+ * Only scopes with the `account` prefix are supported. A scope with any other
+ * prefix throws, since this utility can only evaluate scopes against the
+ * current account.
+ *
+ * @param props - The properties of the request.
+ * @param props.context - Hono request context.
+ * @param props.scopes - Scopes that the current user must have, as configured in
+ * the Iris app manifest. An empty list requires nothing, so the check resolves to
+ * `true` without a lookup (but a missing user token still throws).
+ * @returns {Promise<boolean>} True when the user has all requested scopes,
+ * or when no scopes were requested.
+ * @throws {Error} When the request has no user token.
+ * @throws {Error} When a scope does not use the `account` prefix.
+ * @throws {Error} When the user token has no account id (via `getAccountId`).
+ * @throws {Error} When the scope lookup cannot be completed: a non-2xx HTTP
+ * response, GraphQL `errors`, or an unparseable/empty response body. These signal
+ * "could not check" rather than "user lacks scope", so callers that gate on
+ * the boolean should treat a thrown error as a failure to verify, not a denial.
+ */
+const hasScopes = async ({ context, scopes }) => {
+    const userToken = getUserToken({ context });
+    if (!userToken) {
+        throw new Error("Missing user token");
+    }
+    if (scopes.length === 0) {
+        return true;
+    }
+    const unsupportedScope = scopes.find(scope => getScopePrefix(scope) !== SUPPORTED_SCOPE_PREFIX);
+    if (unsupportedScope !== undefined) {
+        throw new Error(`Unsupported scope "${unsupportedScope}": only "${SUPPORTED_SCOPE_PREFIX}" scopes are currently supported`);
+    }
+    const { accountId } = getAccountId({ context });
+    const baseUrl = getGraphqlUrl();
+    const grantedScopes = await getCurrentUserAccountPermissions({ baseUrl, userToken, accountId });
+    return scopes.every(scope => grantedScopes.includes(scope));
+};
+
+const toScopeList = (scopes) => typeof scopes === "string" ? [scopes] : scopes;
+/**
+ * Creates a Hono middleware that guards routes by account scopes.
+ *
+ * The current user must hold every scope passed in for the request to
+ * continue. When a scope is missing the middleware short-circuits with a
+ * `403` (or a custom response); when no user token is present it responds with
+ * a `401`. On success it calls `next()` so the matched handler runs.
+ *
+ * Scopes match what the developer configures in the Iris app manifest and must
+ * use the `account` prefix (e.g. `account.group.manage`); other prefixes throw.
+ *
+ * If the scope check itself cannot be completed (the token has no account id,
+ * or the GraphQL lookup fails), the error propagates and Hono responds with a `500`
+ * unless an `onError` handler is provided. In all of these cases the matched handler
+ * does not run, so the guard fails closed.
+ *
+ * @param scopes - A single scope or list of scopes the user must have.
+ * @param options - Optional overrides for the failure responses.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @example
+ * ```typescript
+ * // Guard every route in the extension:
+ * app.use(requireScopes("account.view"));
+ *
+ * // Guard a subset of routes:
+ * app.post("/groups/*", requireScopes("account.group.manage"));
+ *
+ * // Require multiple scopes:
+ * app.use(requireScopes(["account.view", "account.group.manage"]));
+ * ```
+ */
+const requireScopes = (scopes, options = {}) => {
+    const requiredScopes = toScopeList(scopes);
+    return async (context, next) => {
+        const userToken = getUserToken({ context });
+        if (!userToken) {
+            return options.onUnauthorized ? options.onUnauthorized(context) : context.json({ error: "Unauthorized" }, 401);
+        }
+        let granted;
+        try {
+            granted = await hasScopes({
+                context,
+                scopes: requiredScopes,
+            });
+        }
+        catch (error) {
+            if (options.onError) {
+                return options.onError(context, error);
+            }
+            throw error;
+        }
+        if (!granted) {
+            return options.onForbidden ? options.onForbidden(context) : context.json({ error: "Forbidden" }, 403);
+        }
+        await next();
+    };
+};
+
 exports.ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER = ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER;
 exports.FORWARDED_AUTHORIZATION_HEADER = FORWARDED_AUTHORIZATION_HEADER;
+exports.executePublicQuery = executePublicQuery;
 exports.getAccountId = getAccountId;
 exports.getDatabricksAccessToken = getDatabricksAccessToken;
+exports.getGraphqlUrl = getGraphqlUrl;
 exports.getSecret = getSecret;
 exports.getUserToken = getUserToken;
+exports.hasScopes = hasScopes;
+exports.requireScopes = requireScopes;

package/index.esm.js

@@ -1,5 +1,106 @@
-import jwtDecode from 'jwt-decode';
 import { z } from 'zod';
+import jwtDecode from 'jwt-decode';
+
+const GraphqlErrorSchema = z.object({
+    message: z.string(),
+});
+const readEnvironmentVariable = (key) => {
+    try {
+        return process.env[key];
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Resolves the public GraphQL base URL for the current SDK environment.
+ *
+ * The environment is read from the `SDK_ENVIRONMENT` variable and defaults to
+ * `PROD` when unset.
+ *
+ * @returns {string} The public GraphQL endpoint for the resolved environment.
+ * @throws {Error} When `SDK_ENVIRONMENT` is set to an unknown value.
+ */
+const getGraphqlUrl = () => {
+    const sdkEnvironment = readEnvironmentVariable("SDK_ENVIRONMENT") ?? "PROD";
+    switch (sdkEnvironment.toUpperCase()) {
+        case "DEV":
+            return "https://dev.iris.trackunit.com/api/graphql";
+        case "STAGE":
+            return "https://stage.iris.trackunit.com/api/graphql";
+        case "PROD":
+            return "https://iris.trackunit.com/api/graphql";
+        default:
+            throw new Error(`Unknown SDK environment: ${sdkEnvironment}`);
+    }
+};
+/**
+ * Appends the operation name to the base URL so each call stays attributable by
+ * its unique operation name when observed in GraphQL Hive.
+ */
+const buildOperationUrl = (baseUrl, operationName) => `${baseUrl}/${operationName}`;
+const getErrorBody = async (response) => {
+    try {
+        const text = await response.text();
+        return text.length > 200 ? `${text.slice(0, 200)}...` : text;
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * Executes a query against the public GraphQL API and returns its validated
+ * `data` payload.
+ *
+ * The operation name is appended to the URL so each call stays attributable by
+ * its unique operation name when observed in GraphQL Hive.
+ *
+ * @template TData The shape of the validated `data` payload.
+ * @param props - The properties of the query execution.
+ * @param props.baseUrl - The base GraphQL URL, e.g. from {@link getGraphqlUrl}.
+ * @param props.userToken - The user token used to authenticate the request.
+ * @param props.operationName - The GraphQL operation name. Must be unique so calls stay traceable.
+ * @param props.query - The GraphQL query document.
+ * @param props.variables - Optional variables passed to the query.
+ * @param props.dataSchema - Zod schema used to validate and type the `data` payload.
+ * @returns {Promise<TData>} The validated `data` payload of the response.
+ * @throws {Error} When the HTTP response is not 2xx.
+ * @throws {Error} When the response body cannot be parsed against the expected shape.
+ * @throws {Error} When the response contains GraphQL `errors`.
+ * @throws {Error} When the response contains no `data`.
+ */
+const executePublicQuery = async ({ baseUrl, userToken, operationName, query, variables, dataSchema, }) => {
+    const url = buildOperationUrl(baseUrl, operationName);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${userToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ operationName, query, variables }),
+    });
+    if (!response.ok) {
+        const errorBody = await getErrorBody(response);
+        throw new Error(`Failed to execute ${operationName} at ${url}: ${response.status} ${response.statusText}${errorBody ? ` - ${errorBody}` : ""}`);
+    }
+    const responseData = await response.json();
+    const parseResult = z
+        .object({
+        data: dataSchema.nullish(),
+        errors: z.array(GraphqlErrorSchema).optional(),
+    })
+        .safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid ${operationName} response from ${url}: ${parseResult.error.message}`);
+    }
+    if (parseResult.data.errors && parseResult.data.errors.length > 0) {
+        throw new Error(`GraphQL error in ${operationName}: ${parseResult.data.errors.map(error => error.message).join(", ")}`);
+    }
+    if (parseResult.data.data === undefined || parseResult.data.data === null) {
+        throw new Error(`No data returned from ${operationName} at ${url}`);
+    }
+    return parseResult.data.data;
+};
 
 /**
  * Header key for the account admin iris app token.
@@ -241,4 +342,162 @@ const getDatabricksAccessToken = async ({ context, databricksHost, databricksCli
     };
 };
 
-export { ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER, FORWARDED_AUTHORIZATION_HEADER, getAccountId, getDatabricksAccessToken, getSecret, getUserToken };
+/**
+ * Operation names are intentionally verbose and unique so the calls are easy to
+ * trace back to this utility (e.g. when inspecting GraphQL Hive). The
+ * `ServersideUtils` prefix already attributes every call to this utility.
+ */
+const USER_PERMISSIONS_OPERATION_NAME = "ServersideUtilsHasScopesUserPermissions";
+const USER_PERMISSIONS_QUERY = `query ${USER_PERMISSIONS_OPERATION_NAME}($securableIds: [ID!]!) {
+  userCurrent {
+    user {
+      permissions(securableIds: $securableIds) {
+        securableId
+        permissions
+      }
+    }
+  }
+}`;
+const UserPermissionsDataSchema = z.object({
+    userCurrent: z
+        .object({
+        user: z
+            .object({
+            permissions: z
+                .array(z
+                .object({
+                securableId: z.string(),
+                permissions: z.array(z.string().nullable()).nullable(),
+            })
+                .nullable())
+                .nullable(),
+        })
+            .nullable(),
+    })
+        .nullable(),
+});
+/**
+ * The only scope prefix currently supported. Scopes are configured by the
+ * developer in the Iris app manifest and follow the `<securable>.<...>` shape
+ * (e.g. `account.group.manage`). Only account-securable scopes can be checked
+ * against the current account.
+ */
+const SUPPORTED_SCOPE_PREFIX = "account";
+const getScopePrefix = (scope) => scope.split(".")[0] ?? "";
+const getCurrentUserAccountPermissions = async ({ baseUrl, userToken, accountId, }) => {
+    const data = await executePublicQuery({
+        baseUrl,
+        userToken,
+        operationName: USER_PERMISSIONS_OPERATION_NAME,
+        query: USER_PERMISSIONS_QUERY,
+        variables: { securableIds: [accountId] },
+        dataSchema: UserPermissionsDataSchema,
+    });
+    return (data.userCurrent?.user?.permissions ?? [])
+        .flatMap(securablePermission => securablePermission?.permissions ?? [])
+        .filter((permission) => permission !== null);
+};
+/**
+ * Checks whether the current logged-in user has all required scopes on their
+ * current account, using the public GraphQL API.
+ *
+ * The current account id is read from the user token, then the user's scopes
+ * for that account are fetched via `userCurrent.user.permissions`.
+ *
+ * Only scopes with the `account` prefix are supported. A scope with any other
+ * prefix throws, since this utility can only evaluate scopes against the
+ * current account.
+ *
+ * @param props - The properties of the request.
+ * @param props.context - Hono request context.
+ * @param props.scopes - Scopes that the current user must have, as configured in
+ * the Iris app manifest. An empty list requires nothing, so the check resolves to
+ * `true` without a lookup (but a missing user token still throws).
+ * @returns {Promise<boolean>} True when the user has all requested scopes,
+ * or when no scopes were requested.
+ * @throws {Error} When the request has no user token.
+ * @throws {Error} When a scope does not use the `account` prefix.
+ * @throws {Error} When the user token has no account id (via `getAccountId`).
+ * @throws {Error} When the scope lookup cannot be completed: a non-2xx HTTP
+ * response, GraphQL `errors`, or an unparseable/empty response body. These signal
+ * "could not check" rather than "user lacks scope", so callers that gate on
+ * the boolean should treat a thrown error as a failure to verify, not a denial.
+ */
+const hasScopes = async ({ context, scopes }) => {
+    const userToken = getUserToken({ context });
+    if (!userToken) {
+        throw new Error("Missing user token");
+    }
+    if (scopes.length === 0) {
+        return true;
+    }
+    const unsupportedScope = scopes.find(scope => getScopePrefix(scope) !== SUPPORTED_SCOPE_PREFIX);
+    if (unsupportedScope !== undefined) {
+        throw new Error(`Unsupported scope "${unsupportedScope}": only "${SUPPORTED_SCOPE_PREFIX}" scopes are currently supported`);
+    }
+    const { accountId } = getAccountId({ context });
+    const baseUrl = getGraphqlUrl();
+    const grantedScopes = await getCurrentUserAccountPermissions({ baseUrl, userToken, accountId });
+    return scopes.every(scope => grantedScopes.includes(scope));
+};
+
+const toScopeList = (scopes) => typeof scopes === "string" ? [scopes] : scopes;
+/**
+ * Creates a Hono middleware that guards routes by account scopes.
+ *
+ * The current user must hold every scope passed in for the request to
+ * continue. When a scope is missing the middleware short-circuits with a
+ * `403` (or a custom response); when no user token is present it responds with
+ * a `401`. On success it calls `next()` so the matched handler runs.
+ *
+ * Scopes match what the developer configures in the Iris app manifest and must
+ * use the `account` prefix (e.g. `account.group.manage`); other prefixes throw.
+ *
+ * If the scope check itself cannot be completed (the token has no account id,
+ * or the GraphQL lookup fails), the error propagates and Hono responds with a `500`
+ * unless an `onError` handler is provided. In all of these cases the matched handler
+ * does not run, so the guard fails closed.
+ *
+ * @param scopes - A single scope or list of scopes the user must have.
+ * @param options - Optional overrides for the failure responses.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @example
+ * ```typescript
+ * // Guard every route in the extension:
+ * app.use(requireScopes("account.view"));
+ *
+ * // Guard a subset of routes:
+ * app.post("/groups/*", requireScopes("account.group.manage"));
+ *
+ * // Require multiple scopes:
+ * app.use(requireScopes(["account.view", "account.group.manage"]));
+ * ```
+ */
+const requireScopes = (scopes, options = {}) => {
+    const requiredScopes = toScopeList(scopes);
+    return async (context, next) => {
+        const userToken = getUserToken({ context });
+        if (!userToken) {
+            return options.onUnauthorized ? options.onUnauthorized(context) : context.json({ error: "Unauthorized" }, 401);
+        }
+        let granted;
+        try {
+            granted = await hasScopes({
+                context,
+                scopes: requiredScopes,
+            });
+        }
+        catch (error) {
+            if (options.onError) {
+                return options.onError(context, error);
+            }
+            throw error;
+        }
+        if (!granted) {
+            return options.onForbidden ? options.onForbidden(context) : context.json({ error: "Forbidden" }, 403);
+        }
+        await next();
+    };
+};
+
+export { ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER, FORWARDED_AUTHORIZATION_HEADER, executePublicQuery, getAccountId, getDatabricksAccessToken, getGraphqlUrl, getSecret, getUserToken, hasScopes, requireScopes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/serverside-utils",
-  "version": "0.4.25-alpha-27ad777c16e.0",
+  "version": "0.4.28",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/execute-public-query.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * Resolves the public GraphQL base URL for the current SDK environment.
+ *
+ * The environment is read from the `SDK_ENVIRONMENT` variable and defaults to
+ * `PROD` when unset.
+ *
+ * @returns {string} The public GraphQL endpoint for the resolved environment.
+ * @throws {Error} When `SDK_ENVIRONMENT` is set to an unknown value.
+ */
+export declare const getGraphqlUrl: () => string;
+/**
+ * The properties of a public GraphQL query execution.
+ */
+export type ExecutePublicQueryProps<TData> = {
+    /** The base GraphQL URL, e.g. from {@link getGraphqlUrl}. */
+    readonly baseUrl: string;
+    /** The user token used to authenticate the request. */
+    readonly userToken: string;
+    /** The GraphQL operation name. Must be unique so calls stay traceable in GraphQL Hive. */
+    readonly operationName: string;
+    /** The GraphQL query document. */
+    readonly query: string;
+    /** Optional variables passed to the query. */
+    readonly variables?: Record<string, unknown>;
+    /** Zod schema used to validate and type the `data` payload of the response. */
+    readonly dataSchema: z.ZodType<TData>;
+};
+/**
+ * Executes a query against the public GraphQL API and returns its validated
+ * `data` payload.
+ *
+ * The operation name is appended to the URL so each call stays attributable by
+ * its unique operation name when observed in GraphQL Hive.
+ *
+ * @template TData The shape of the validated `data` payload.
+ * @param props - The properties of the query execution.
+ * @param props.baseUrl - The base GraphQL URL, e.g. from {@link getGraphqlUrl}.
+ * @param props.userToken - The user token used to authenticate the request.
+ * @param props.operationName - The GraphQL operation name. Must be unique so calls stay traceable.
+ * @param props.query - The GraphQL query document.
+ * @param props.variables - Optional variables passed to the query.
+ * @param props.dataSchema - Zod schema used to validate and type the `data` payload.
+ * @returns {Promise<TData>} The validated `data` payload of the response.
+ * @throws {Error} When the HTTP response is not 2xx.
+ * @throws {Error} When the response body cannot be parsed against the expected shape.
+ * @throws {Error} When the response contains GraphQL `errors`.
+ * @throws {Error} When the response contains no `data`.
+ */
+export declare const executePublicQuery: <TData>({ baseUrl, userToken, operationName, query, variables, dataSchema, }: ExecutePublicQueryProps<TData>) => Promise<TData>;

package/src/has-scopes.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from "hono";
+export type HasScopesProps = {
+    /** Hono request context */
+    readonly context: Context;
+    /**
+     * Scopes the current user must have on their current account, as configured in
+     * the Iris app manifest (e.g. `account.group.manage`). Every scope must use the
+     * `account` prefix.
+     */
+    readonly scopes: ReadonlyArray<string>;
+};
+/**
+ * Checks whether the current logged-in user has all required scopes on their
+ * current account, using the public GraphQL API.
+ *
+ * The current account id is read from the user token, then the user's scopes
+ * for that account are fetched via `userCurrent.user.permissions`.
+ *
+ * Only scopes with the `account` prefix are supported. A scope with any other
+ * prefix throws, since this utility can only evaluate scopes against the
+ * current account.
+ *
+ * @param props - The properties of the request.
+ * @param props.context - Hono request context.
+ * @param props.scopes - Scopes that the current user must have, as configured in
+ * the Iris app manifest. An empty list requires nothing, so the check resolves to
+ * `true` without a lookup (but a missing user token still throws).
+ * @returns {Promise<boolean>} True when the user has all requested scopes,
+ * or when no scopes were requested.
+ * @throws {Error} When the request has no user token.
+ * @throws {Error} When a scope does not use the `account` prefix.
+ * @throws {Error} When the user token has no account id (via `getAccountId`).
+ * @throws {Error} When the scope lookup cannot be completed: a non-2xx HTTP
+ * response, GraphQL `errors`, or an unparseable/empty response body. These signal
+ * "could not check" rather than "user lacks scope", so callers that gate on
+ * the boolean should treat a thrown error as a failure to verify, not a denial.
+ */
+export declare const hasScopes: ({ context, scopes }: HasScopesProps) => Promise<boolean>;

package/src/index.d.ts

@@ -1,5 +1,8 @@
+export { executePublicQuery, getGraphqlUrl, type ExecutePublicQueryProps } from "./execute-public-query";
 export { getAccountId } from "./get-account-id";
 export { getDatabricksAccessToken, type GetDatabricksAccessTokenProps } from "./get-databricks-access-token";
 export { getSecret } from "./get-secret";
 export { getUserToken } from "./get-user-token";
+export { hasScopes, type HasScopesProps } from "./has-scopes";
 export { ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER, FORWARDED_AUTHORIZATION_HEADER } from "./headers";
+export { requireScopes, type RequireScopesOptions } from "./require-scopes";

package/src/require-scopes.d.ts

@@ -0,0 +1,46 @@
+import type { Context, MiddlewareHandler } from "hono";
+export type RequireScopesOptions = {
+    /** Response returned when no user token is present (defaults to 401) */
+    readonly onUnauthorized?: (context: Context) => Response | Promise<Response>;
+    /** Response returned when the user is missing a required scope (defaults to 403) */
+    readonly onForbidden?: (context: Context) => Response | Promise<Response>;
+    /**
+     * Response returned when the scope check could not be completed (e.g. the
+     * token has no account id, or the GraphQL lookup failed). When omitted the error
+     * propagates and Hono responds with a `500`. Either way the route handler does
+     * not run, so the guard fails closed.
+     */
+    readonly onError?: (context: Context, error: unknown) => Response | Promise<Response>;
+};
+/**
+ * Creates a Hono middleware that guards routes by account scopes.
+ *
+ * The current user must hold every scope passed in for the request to
+ * continue. When a scope is missing the middleware short-circuits with a
+ * `403` (or a custom response); when no user token is present it responds with
+ * a `401`. On success it calls `next()` so the matched handler runs.
+ *
+ * Scopes match what the developer configures in the Iris app manifest and must
+ * use the `account` prefix (e.g. `account.group.manage`); other prefixes throw.
+ *
+ * If the scope check itself cannot be completed (the token has no account id,
+ * or the GraphQL lookup fails), the error propagates and Hono responds with a `500`
+ * unless an `onError` handler is provided. In all of these cases the matched handler
+ * does not run, so the guard fails closed.
+ *
+ * @param scopes - A single scope or list of scopes the user must have.
+ * @param options - Optional overrides for the failure responses.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @example
+ * ```typescript
+ * // Guard every route in the extension:
+ * app.use(requireScopes("account.view"));
+ *
+ * // Guard a subset of routes:
+ * app.post("/groups/*", requireScopes("account.group.manage"));
+ *
+ * // Require multiple scopes:
+ * app.use(requireScopes(["account.view", "account.group.manage"]));
+ * ```
+ */
+export declare const requireScopes: (scopes: string | ReadonlyArray<string>, options?: RequireScopesOptions) => MiddlewareHandler;