@usehercules/convex 0.0.0

package/dist/client/index.js

@@ -0,0 +1,654 @@
+import { ConvexError } from "convex/values";
+// Hard cap on resource-hierarchy depth: a request authorizes against the
+// resource plus at most this many ancestors. Generous for real nesting
+// (folder/file, project/task/comment) while bounding the per-call check count.
+const MAX_AUTHORIZE_CHAIN = 10;
+/**
+ * Wires Hercules managed Access Control into a Convex app. Call once in
+ * `convex/hercules.ts`, passing the generated `query`/`mutation`/`action`
+ * builders and `components`, then re-export the returned builders.
+ *
+ * Returned builders:
+ * - `publicQuery`/`publicMutation`/`publicAction`: no auth.
+ * - `authenticatedQuery`/`...Mutation`/`...Action`: require sign-in only.
+ * - `accessQuery`/`accessMutation`/`accessAction`: enforce a permission in a
+ *   scope. Pass `{ permission, scope }`; resolve `scope` with `scopeFromArg`
+ *   or `scopeFromResource`. Use these for all org-owned reads and writes.
+ * - `hasPermission`/`requirePermission`/`requireAnyPermission`/
+ *   `getEffectivePermissions`: in-handler checks. `getEffectivePermissions`
+ *   and `hasPermission` accept an optional `{ resource }` ref for per-resource
+ *   (e.g. per-project) checks.
+ * - `getCurrentHerculesAuthUserId`: the verified OIDC subject for linking
+ *   app-owned domain rows. Do not parse `tokenIdentifier`.
+ * - `listMyMemberships`/`listMyRoles`: the caller's own scopes/roles.
+ * - `listScopeMembers`/`listScopeRoles`/`listScopePermissions`: complete
+ *   mirrored admin reads for an in-app management screen. Each self-gates on
+ *   the matching `system.*:read` permission and returns `[]` when the caller
+ *   lacks it. Use `createAccessUserActions().listGrantableRoles` instead when
+ *   choosing a role for a write at an exact target.
+ *
+ * Reads resolve against the app's local Access Control mirror, which lags the
+ * control plane by a short projection-sync window after any change.
+ */
+export function createAccessControl(options) {
+    const component = resolveComponent(options);
+    return {
+        publicQuery: options.query,
+        publicMutation: options.mutation,
+        publicAction: options.action,
+        authenticatedQuery: makeAuthenticatedBuilder(options.query, component),
+        authenticatedMutation: makeAuthenticatedBuilder(options.mutation, component),
+        authenticatedAction: makeAuthenticatedBuilder(options.action, component),
+        accessQuery: makeAccessBuilder(options.query, component),
+        accessMutation: makeAccessBuilder(options.mutation, component),
+        accessAction: makeAccessBuilder(options.action, component),
+        hasPermission: makeHasPermission(component),
+        requirePermission: makeRequirePermission(component),
+        requireAnyPermission: makeRequireAnyPermission(component),
+        getEffectivePermissions: makeGetEffectivePermissions(component),
+        checkPermissions: makeCheckPermissions(component),
+        getCurrentHerculesAuthUserId,
+        getDeploymentEntryStatus: makeGetDeploymentEntryStatus(component),
+        filterAuthorizedResources: makeFilterAuthorizedResources(component),
+        listMyMemberships: makeListMyMemberships(component),
+        listMyRoles: makeListMyRoles(component),
+        listScopeMembers: makeListScopeMembers(component),
+        listScopeMemberDirectory: makeListScopeMemberDirectory(component),
+        getScopeMemberDirectoryEntry: makeGetScopeMemberDirectoryEntry(component),
+        listScopeRoles: makeListScopeRoles(component),
+        listScopePermissions: makeListScopePermissions(component),
+        listDirectSubjectsForResource: makeListDirectSubjectsForResource(component),
+    };
+}
+// Single-tenant apps that don't pass a scope arg: every check resolves to
+// the app's default scope. The component query looks up the default scope
+// row from the mirror, so this helper just returns a sentinel string and
+// authorize resolves it. The sentinel is treated as "use the default scope"
+// inside the authorize implementation (component reads the unique row with
+// kind="default").
+export const DEFAULT_SCOPE_SENTINEL = "__hercules_default_scope__";
+export const defaultScope = () => DEFAULT_SCOPE_SENTINEL;
+// The resourceType `scopeFromResource` emits. An extractor only sees the table
+// row, not the permission catalog, so it cannot know the canonical resource
+// type the checked permission uses (e.g. `app.project` for
+// `app.project:archive`). It emits this sentinel instead, and the component's
+// authorize query substitutes the requested permission's canonical catalog
+// resourceType (resolved by catalog lookup). Resource grants are pinned to that
+// same canonical type on the control plane, so the two match by construction.
+// Mirrored in component/checks.ts (like DEFAULT_SCOPE_SENTINEL above).
+export const PERMISSION_RESOURCE_TYPE_SENTINEL = "__hercules_permission_resource_type__";
+/**
+ * Resolves the scope for an `access*` builder from a string arg the caller
+ * passes (e.g. the active org id). Use for list/create handlers where the
+ * frontend already knows the scope. Throws if the arg is missing or empty.
+ *
+ * Do not use this for an operation that receives an org-owned row id (read,
+ * update, delete): a caller could pair their own scope id with another org's
+ * row. Use `scopeFromResource` there so the scope is read from the row.
+ */
+export function scopeFromArg(argKey) {
+    return (_ctx, args) => {
+        const value = args?.[argKey];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `scopeFromArg("${argKey}"): expected non-empty string on args.${argKey}`,
+            });
+        }
+        return value;
+    };
+}
+/**
+ * Resolves the scope from a referenced row for an `access*` builder. Reads
+ * the row named by `argKey`, returns the row's scope plus the resource id,
+ * and lets `authorize` apply resource-level grants on top of the scope check.
+ * Use for any read/update/delete that receives an org-owned row id.
+ *
+ * Params:
+ * - `tableName`: the row's table (used in error messages only).
+ * - `argKey`: the field on `args` holding the row id.
+ * - `options.scopeField`: column carrying the org scope id (default
+ *   `"orgScopeId"`).
+ *
+ * Resource type: the emitted `resourceType` defers to the checked permission's
+ * canonical catalog resource type (e.g. `app.project` for
+ * `app.project:archive`), which is also the type resource grants are pinned
+ * to, so grants on the row always match the guarded permission.
+ *
+ * Hierarchy: pass `options.authorizeAgainst` to declare ordered parent
+ * resources. The target and ancestors are evaluated atomically with the same
+ * requested permission, so any applicable deny wins. The app owns these
+ * relationships; the chain is bounded to ten ancestors.
+ */
+export function scopeFromResource(tableName, argKey, options = {}) {
+    const scopeField = options.scopeField ?? "orgScopeId";
+    return async (ctx, args) => {
+        const id = args?.[argKey];
+        if (id == null) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `scopeFromResource("${tableName}", "${argKey}"): args.${argKey} is missing`,
+            });
+        }
+        const row = await ctx.db.get(id);
+        if (!row || typeof row !== "object") {
+            throw new ConvexError({
+                code: "RESOURCE_NOT_FOUND",
+                message: `scopeFromResource("${tableName}", "${argKey}"): resource not found`,
+            });
+        }
+        const scopeId = row[scopeField];
+        if (typeof scopeId !== "string" || scopeId.length === 0) {
+            throw new ConvexError({
+                code: "INVALID_RESOURCE_SCOPE",
+                message: `scopeFromResource("${tableName}", "${argKey}"): resource is missing "${scopeField}"`,
+            });
+        }
+        const ancestors = normalizeAncestors(options.authorizeAgainst?.(row), `scopeFromResource("${tableName}", "${argKey}")`);
+        return {
+            scopeId,
+            resourceType: PERMISSION_RESOURCE_TYPE_SENTINEL,
+            resourceId: String(id),
+            ...(ancestors ? { ancestors } : {}),
+        };
+    };
+}
+/**
+ * Resolves a specific resource in the default app scope without requiring a
+ * scope id column on the row. Use this for single-scope apps that still need
+ * resource grants, denies, or per-resource UI checks.
+ *
+ * The row is loaded from `args[argKey]`, so authorization and mutation stay
+ * bound to the same resource. Pass `authorizeAgainst` for trusted parent
+ * resources exactly as with {@link scopeFromResource}.
+ */
+export function scopeFromDefaultResource(tableName, argKey, options = {}) {
+    return async (ctx, args) => {
+        const id = args?.[argKey];
+        if (id == null) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `scopeFromDefaultResource("${tableName}", "${argKey}"): args.${argKey} is missing`,
+            });
+        }
+        const row = await ctx.db.get(id);
+        if (!row || typeof row !== "object") {
+            throw new ConvexError({
+                code: "RESOURCE_NOT_FOUND",
+                message: `scopeFromDefaultResource("${tableName}", "${argKey}"): resource not found`,
+            });
+        }
+        const ancestors = normalizeAncestors(options.authorizeAgainst?.(row), `scopeFromDefaultResource("${tableName}", "${argKey}")`);
+        return {
+            scopeId: DEFAULT_SCOPE_SENTINEL,
+            resourceType: PERMISSION_RESOURCE_TYPE_SENTINEL,
+            resourceId: String(id),
+            ...(ancestors ? { ancestors } : {}),
+        };
+    };
+}
+/**
+ * Resolves child-creation authorization from an existing parent row. The
+ * requested child permission stays unchanged; the parent is supplied as an
+ * explicit ancestor and only descendant-enabled bindings apply through it.
+ */
+export function scopeFromParentResource(tableName, argKey, options) {
+    const scopeField = options.scopeField ?? "orgScopeId";
+    return async (ctx, args) => {
+        const id = args?.[argKey];
+        if (id == null) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `scopeFromParentResource("${tableName}", "${argKey}"): args.${argKey} is missing`,
+            });
+        }
+        const row = await ctx.db.get(id);
+        if (!row || typeof row !== "object") {
+            throw new ConvexError({
+                code: "RESOURCE_NOT_FOUND",
+                message: `scopeFromParentResource("${tableName}", "${argKey}"): resource not found`,
+            });
+        }
+        const scopeId = row[scopeField];
+        if (typeof scopeId !== "string" || scopeId.length === 0) {
+            throw new ConvexError({
+                code: "INVALID_RESOURCE_SCOPE",
+                message: `scopeFromParentResource("${tableName}", "${argKey}"): resource is missing "${scopeField}"`,
+            });
+        }
+        const ancestors = normalizeAncestors([
+            { type: options.parentResourceType, id: String(id) },
+            ...(options.authorizeAgainst?.(row) ?? []),
+        ], `scopeFromParentResource("${tableName}", "${argKey}")`);
+        return {
+            scopeId,
+            resourceType: PERMISSION_RESOURCE_TYPE_SENTINEL,
+            ancestors: ancestors,
+        };
+    };
+}
+/**
+ * Resolves child creation against a parent resource in the default app scope.
+ * The parent row is loaded from `args[argKey]`; no scope id field is required
+ * on the parent or child tables.
+ */
+export function scopeFromDefaultParentResource(tableName, argKey, options) {
+    return async (ctx, args) => {
+        const id = args?.[argKey];
+        if (id == null) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `scopeFromDefaultParentResource("${tableName}", "${argKey}"): args.${argKey} is missing`,
+            });
+        }
+        const row = await ctx.db.get(id);
+        if (!row || typeof row !== "object") {
+            throw new ConvexError({
+                code: "RESOURCE_NOT_FOUND",
+                message: `scopeFromDefaultParentResource("${tableName}", "${argKey}"): resource not found`,
+            });
+        }
+        const ancestors = normalizeAncestors([
+            { type: options.parentResourceType, id: String(id) },
+            ...(options.authorizeAgainst?.(row) ?? []),
+        ], `scopeFromDefaultParentResource("${tableName}", "${argKey}")`);
+        return {
+            scopeId: DEFAULT_SCOPE_SENTINEL,
+            resourceType: PERMISSION_RESOURCE_TYPE_SENTINEL,
+            ancestors: ancestors,
+        };
+    };
+}
+function resolveComponent(options) {
+    if (options.component) {
+        return options.component;
+    }
+    const componentName = options.componentName ?? "hercules";
+    const component = options.components?.[componentName];
+    if (!component) {
+        throw new Error("Missing Hercules Access Control component. Install @usehercules/convex in convex/convex.config.ts.");
+    }
+    return component;
+}
+function makeAuthenticatedBuilder(builder, component) {
+    return ((definition) => {
+        return builder(wrapDefinition(definition, component, "authenticated"));
+    });
+}
+function makeAccessBuilder(builder, component) {
+    return ((definition) => {
+        if (typeof definition !== "object" || definition === null || !("handler" in definition)) {
+            throw new Error("access* builders require an object definition with a permission.");
+        }
+        const accessDefinition = definition;
+        if (typeof accessDefinition.permission !== "string" ||
+            accessDefinition.permission.length === 0) {
+            throw new Error("access* builders require a non-empty permission.");
+        }
+        if (accessDefinition.scope !== undefined && typeof accessDefinition.scope !== "function") {
+            throw new Error("access* builders require scope to be a function.");
+        }
+        const { permission, scope, ...convexDefinition } = accessDefinition;
+        const scopeExtractor = (scope ?? defaultScope);
+        return builder(wrapDefinition(convexDefinition, component, "permission", {
+            permission,
+            scope: scopeExtractor,
+        }));
+    });
+}
+function wrapDefinition(definition, component, mode, access) {
+    if (typeof definition === "function") {
+        return async (ctx, ...args) => {
+            await ensureAuthorized(ctx, component, mode, access, args[0]);
+            return definition(ctx, ...args);
+        };
+    }
+    const objectDefinition = definition;
+    return {
+        ...objectDefinition,
+        handler: async (ctx, ...args) => {
+            await ensureAuthorized(ctx, component, mode, access, args[0]);
+            return objectDefinition.handler(ctx, ...args);
+        },
+    };
+}
+function resourceArgs(resource) {
+    return { resourceType: resource?.type, resourceId: resource?.id };
+}
+function ancestorArgs(ancestors) {
+    return ancestors ? { ancestors } : {};
+}
+function normalizeAncestors(ancestors, source = "authorization check") {
+    if (!ancestors || ancestors.length === 0)
+        return undefined;
+    if (ancestors.length > MAX_AUTHORIZE_CHAIN) {
+        throw new ConvexError({
+            code: "INVALID_SCOPE_ARG",
+            message: `${source}: expected at most ${MAX_AUTHORIZE_CHAIN} ancestors`,
+        });
+    }
+    return ancestors.map((ancestor) => {
+        if (!ancestor.type || !ancestor.id) {
+            throw new ConvexError({
+                code: "INVALID_SCOPE_ARG",
+                message: `${source}: ancestors require non-empty type and id`,
+            });
+        }
+        return { resourceType: ancestor.type, resourceId: ancestor.id };
+    });
+}
+async function getTokenIdentifier(ctx) {
+    return (await ctx.auth.getUserIdentity())?.tokenIdentifier ?? undefined;
+}
+async function getCurrentHerculesAuthUserId(ctx) {
+    return (await ctx.auth.getUserIdentity())?.subject ?? undefined;
+}
+function normalizePermissionCheckArgs(args) {
+    if (typeof args === "string") {
+        return {
+            scopeId: DEFAULT_SCOPE_SENTINEL,
+            permission: args,
+            resource: undefined,
+            ancestors: undefined,
+        };
+    }
+    return {
+        scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        permission: args.permission,
+        resource: args.resource,
+        ancestors: normalizeAncestors(args.ancestors),
+    };
+}
+function normalizeAnyPermissionCheckArgs(args) {
+    if (Array.isArray(args)) {
+        return {
+            scopeId: DEFAULT_SCOPE_SENTINEL,
+            permissions: args,
+            resource: undefined,
+            ancestors: undefined,
+        };
+    }
+    return {
+        scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        permissions: args.permissions,
+        resource: args.resource,
+        ancestors: args.ancestors,
+    };
+}
+function normalizeEffectivePermissionsArgs(args) {
+    return {
+        scopeId: args?.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        resource: args?.resource,
+        ancestors: normalizeAncestors(args?.ancestors),
+    };
+}
+function makeHasPermission(component) {
+    return async (ctx, args) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return false;
+        const normalized = normalizePermissionCheckArgs(args);
+        const decision = await ctx.runQuery(component.checks.authorize, {
+            tokenIdentifier,
+            scopeId: normalized.scopeId,
+            permission: normalized.permission,
+            ...resourceArgs(normalized.resource),
+            ...ancestorArgs(normalized.ancestors),
+        });
+        return decision.allowed;
+    };
+}
+function makeRequirePermission(component) {
+    const hasPermission = makeHasPermission(component);
+    return async (ctx, args) => {
+        if (await hasPermission(ctx, args))
+            return;
+        throw new ConvexError({ code: "ACCESS_DENIED", message: "Access denied" });
+    };
+}
+function makeRequireAnyPermission(component) {
+    const hasPermission = makeHasPermission(component);
+    return async (ctx, args) => {
+        const normalized = normalizeAnyPermissionCheckArgs(args);
+        for (const permission of normalized.permissions) {
+            if (await hasPermission(ctx, { ...normalized, permission }))
+                return;
+        }
+        throw new ConvexError({ code: "ACCESS_DENIED", message: "Access denied" });
+    };
+}
+function makeGetEffectivePermissions(component) {
+    return async (ctx, args) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        const normalized = normalizeEffectivePermissionsArgs(args);
+        const result = await ctx.runQuery(component.queries.getEffectivePermissions, {
+            tokenIdentifier,
+            scopeId: normalized.scopeId,
+            ...resourceArgs(normalized.resource),
+            ...ancestorArgs(normalized.ancestors),
+        });
+        return result.permissions;
+    };
+}
+function makeCheckPermissions(component) {
+    return async (ctx, checks) => {
+        if (checks.length > 50) {
+            throw new ConvexError({
+                code: "INVALID_PERMISSION_CHECKS",
+                message: "checkPermissions accepts at most 50 checks",
+            });
+        }
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier) {
+            return checks.map(() => ({
+                allowed: false,
+                reasonCode: "missing_identity",
+                effectiveRoleIds: [],
+            }));
+        }
+        return await ctx.runQuery(component.checks.authorizeMany, {
+            tokenIdentifier,
+            checks: checks.map((check) => {
+                const normalized = normalizePermissionCheckArgs(check);
+                return {
+                    scopeId: normalized.scopeId,
+                    permission: normalized.permission,
+                    ...resourceArgs(normalized.resource),
+                    ...ancestorArgs(normalized.ancestors),
+                };
+            }),
+        });
+    };
+}
+function makeFilterAuthorizedResources(component) {
+    return async (ctx, args) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        const scopeId = args.scopeId ?? DEFAULT_SCOPE_SENTINEL;
+        const allowed = [];
+        for (const item of args.resources) {
+            const ref = args.resource(item);
+            const ancestors = normalizeAncestors(args.ancestors?.(item), "filterAuthorizedResources");
+            const decision = await ctx.runQuery(component.checks.authorize, {
+                tokenIdentifier,
+                scopeId,
+                permission: args.permission,
+                resourceType: ref.type,
+                resourceId: ref.id,
+                ...ancestorArgs(ancestors),
+            });
+            if (decision.allowed)
+                allowed.push(item);
+        }
+        return allowed;
+    };
+}
+function makeListMyMemberships(component) {
+    return async (ctx) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listMyMemberships, {
+            tokenIdentifier,
+        });
+    };
+}
+function makeGetDeploymentEntryStatus(component) {
+    return async (ctx) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier) {
+            return { kind: "fallback", reason: "identity_missing" };
+        }
+        return await ctx.runQuery(component.queries.getDeploymentEntryStatus, {
+            tokenIdentifier,
+        });
+    };
+}
+function makeListMyRoles(component) {
+    return async (ctx, args = {}) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listMyRoles, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        });
+    };
+}
+function makeListScopeMembers(component) {
+    return async (ctx, args = {}) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listScopeMembers, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        });
+    };
+}
+function makeListScopeMemberDirectory(component) {
+    return async (ctx, args = {}) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return { members: [] };
+        const result = await ctx.runQuery(component.queries.listScopeMemberDirectory, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+            cursor: args.cursor,
+            limit: args.limit,
+        });
+        return {
+            members: result.members,
+            ...(result.cursor ? { nextCursor: result.cursor } : {}),
+        };
+    };
+}
+function makeGetScopeMemberDirectoryEntry(component) {
+    return async (ctx, args) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return null;
+        return await ctx.runQuery(component.queries.getScopeMemberDirectoryEntry, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+            principalId: args.principalId,
+            herculesAuthUserId: args.herculesAuthUserId,
+        });
+    };
+}
+function makeListScopeRoles(component) {
+    return async (ctx, args = {}) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listScopeRoles, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        });
+    };
+}
+function makeListScopePermissions(component) {
+    return async (ctx, args = {}) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listScopePermissions, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+        });
+    };
+}
+function makeListDirectSubjectsForResource(component) {
+    return async (ctx, args) => {
+        const tokenIdentifier = await getTokenIdentifier(ctx);
+        if (!tokenIdentifier)
+            return [];
+        return await ctx.runQuery(component.queries.listDirectSubjectsForResource, {
+            tokenIdentifier,
+            scopeId: args.scopeId ?? DEFAULT_SCOPE_SENTINEL,
+            resourceType: args.resourceType,
+            resourceId: args.resourceId,
+            permission: args.permission,
+        });
+    };
+}
+async function ensureAuthorized(ctx, component, mode, access, callerArgs) {
+    const identity = await ctx.auth.getUserIdentity();
+    // MED-01: short-circuit on missing identity before scope extraction so that
+    // unauthenticated callers cannot probe resource existence by observing
+    // INVALID_SCOPE_ARG vs RESOURCE_NOT_FOUND vs INVALID_RESOURCE_SCOPE.
+    if (!identity?.tokenIdentifier) {
+        throw new ConvexError({
+            code: mode === "permission" ? "ACCESS_DENIED" : "UNAUTHENTICATED",
+            message: mode === "permission" ? "Access denied" : "Authentication required",
+            reasonCode: "missing_identity",
+        });
+    }
+    let scopeId;
+    let resourceType;
+    let resourceId;
+    let ancestors;
+    if (mode === "permission") {
+        try {
+            const extracted = await (access?.scope ?? defaultScope)(ctx, callerArgs);
+            if (typeof extracted === "string") {
+                scopeId = extracted;
+            }
+            else {
+                scopeId = extracted.scopeId;
+                resourceType = extracted.resourceType;
+                resourceId = extracted.resourceId;
+                ancestors = extracted.ancestors;
+            }
+        }
+        catch (error) {
+            if (error instanceof ConvexError)
+                throw error;
+            throw new ConvexError({
+                code: "ACCESS_DENIED",
+                message: "scope extraction failed",
+                reasonCode: "scope_extract_failed",
+            });
+        }
+    }
+    const decision = await ctx.runQuery(component.checks.authorize, {
+        tokenIdentifier: identity.tokenIdentifier,
+        scopeId,
+        permission: mode === "permission" ? access?.permission : undefined,
+        resourceType,
+        resourceId,
+        ...ancestorArgs(ancestors),
+    });
+    if (!decision.allowed) {
+        throw new ConvexError({
+            code: mode === "permission" ? "ACCESS_DENIED" : "UNAUTHENTICATED",
+            message: mode === "permission" ? "Access denied" : "Authentication required",
+            reasonCode: decision.reasonCode,
+            sourceVersion: decision.sourceVersion,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map