@usehercules/convex 0.0.0

package/dist/component/effective.d.ts

@@ -0,0 +1,82 @@
+import type { DataModelFromSchemaDefinition, GenericQueryCtx } from "convex/server";
+import { type ApplicableEntry, type WildcardMode } from "./authz";
+import schema from "./schema";
+type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+export type AuthorizationAncestor = {
+    resourceType: string;
+    resourceId: string;
+};
+export declare function normalizeAuthorizationAncestors(ancestors: AuthorizationAncestor[] | undefined): AuthorizationAncestor[] | null;
+type PermissionSummary = {
+    permissionId: string;
+    key: string;
+    resourceType: string;
+    action: string;
+    classification: "delegable" | "owner_only";
+};
+type CatalogPermission = {
+    permissionId: string;
+    key: string;
+    resourceType: string;
+    action: string;
+    classification: "delegable" | "owner_only";
+};
+type RuntimeEntry = ApplicableEntry & {
+    permissionId?: string;
+};
+export type EffectiveAccessEvaluation = {
+    allowed: boolean;
+    reasonCode: string;
+    sourceVersion?: number;
+    scopeId?: string;
+    principalId?: string;
+    effectiveRoleIds: string[];
+    catalogPermissions: CatalogPermission[];
+    wildcard: WildcardMode;
+    entries: RuntimeEntry[];
+};
+export declare function evaluateEffectiveAccess(ctx: GenericQueryCtx<DataModel>, args: {
+    tokenIdentifier?: string;
+    scopeId?: string;
+    resourceType?: string;
+    resourceId?: string;
+    ancestors?: AuthorizationAncestor[];
+}): Promise<EffectiveAccessEvaluation>;
+/**
+ * Grant-side superset action tokens (`manage`, `*`) are never runtime-
+ * checkable: can() requests carry concrete verbs only, so the authorize gate
+ * (checks.ts evaluatePermissionDecision) rejects a request whose resolved
+ * catalog action is a superset token with `invalid_request` — even for an
+ * Owner. Shared by that gate and {@link enumeratePermissions} so the two stay
+ * consistent by construction.
+ */
+export declare function isSupersetAction(action: string): boolean;
+/**
+ * Enumerate the catalog permissions this principal can exercise, by set-
+ * membership over the assembled entries — matching the canonical platform query
+ * (selectEffectivePermissionsByPrincipalIds). A catalog permission is reported
+ * when:
+ *   - Owner (immutable) → always (the whole catalog).
+ *   - Admin (default)   → unless it is an Owner-only lever or is denied by a
+ *     matching deny entry (a narrowing role-permission deny or a direct/resource
+ *     deny).
+ *   - else / additionally → there is a matching allow entry whose action
+ *     covers the catalog permission, and no matching deny entry overrides it.
+ *
+ * Superset-action catalog keys (`:manage`, `:*`) are control-plane management
+ * gates, not runtime-checkable permissions: the authorize gate rejects them
+ * with `invalid_request` ({@link isSupersetAction}), so they are excluded here
+ * for every wildcard mode — getEffectivePermissions must never advertise a key
+ * the runtime will then deny. The capability such a grant confers is still
+ * fully reported: a `manage`/`*` allow entry expands onto the concrete-verb
+ * catalog keys it covers via actionMatches.
+ */
+export declare function enumeratePermissions(catalogPermissions: CatalogPermission[], wildcard: WildcardMode, entries: RuntimeEntry[], args: {
+    resourceId?: string;
+}): PermissionSummary[];
+export declare function collectPrincipalIds(ctx: GenericQueryCtx<DataModel>, args: {
+    principalId: string;
+    scopeId: string;
+}): Promise<string[]>;
+export {};
+//# sourceMappingURL=effective.d.ts.map

package/dist/component/effective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective.d.ts","sourceRoot":"","sources":["../../src/component/effective.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,MAAM,MAAM,UAAU,CAAC;AAE9B,KAAK,SAAS,GAAG,6BAA6B,CAAC,OAAO,MAAM,CAAC,CAAC;AAK9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,qBAAqB,EAAE,GAAG,SAAS,GAC7C,qBAAqB,EAAE,GAAG,IAAI,CAgBhC;AAED,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,WAAW,GAAG,YAAY,CAAC;CAC5C,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,WAAW,GAAG,YAAY,CAAC;CAC5C,CAAC;AAUF,KAAK,YAAY,GAAG,eAAe,GAAG;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAM3B,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IAIxC,QAAQ,EAAE,YAAY,CAAC;IAKvB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB,CAAC;AAEF,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,EAC/B,IAAI,EAAE;IACJ,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACrC,GACA,OAAO,CAAC,yBAAyB,CAAC,CA+LpC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,kBAAkB,EAAE,iBAAiB,EAAE,EACvC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,YAAY,EAAE,EACvB,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,iBAAiB,EAAE,CA0CrB;AAKD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,EAC/B,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,qBA6B/C"}