@protobase/schema 0.61.0 → 0.62.0

package/dist/access/resolve.d.ts

@@ -24,8 +24,8 @@ export type ResolveOptions = {
   roles?: {
     /** The rule allowing a capability, as `defineRoles` makes it. */
     can: (capability: any) => Rule;
-    /** The fields the user's roles list for a capability, or `undefined` for every field. */
-    fields?: (user: AccessUser, capability: string) => readonly string[] | undefined;
+    /** The fields the user's roles list for a capability on the resource, or `undefined` for every field. */
+    fields?: (user: AccessUser, capability: string, model: ResourceModel) => readonly string[] | undefined;
     /** The roles by name, to tell whether the project has an `anonymous` role. */
     definitions?: Record<string, unknown>;
     /** Whether the user's roles grant all of a capability, as `defineRoles` makes it; the gate of API functions. */

package/dist/access/resolve.js

@@ -104,7 +104,7 @@ const resolveAccess = async (source, ctx, options = {}) => {
 		model,
 		operation
 	});
-	const listed = (operation) => options.roles?.fields?.(ctx.user, capabilityOf(model, operation));
+	const listed = (operation) => options.roles?.fields?.(ctx.user, capabilityOf(model, operation), model);
 	const lists = {
 		read: listed("read"),
 		create: listed("create"),

package/dist/access/roles.d.ts

@@ -1,3 +1,4 @@
+import { ResourceModel } from "../model.js";
 import { AccessUser } from "./types.js";
 import { Capability, ExactCapability, Grant } from "./capability.js";
 import { HeldCapability, RoleEntry } from "./role-entry.js";
@@ -51,12 +52,14 @@ export declare const defineRoles: <Name extends string = string>(definitions: Re
   holds: (user: AccessUser, capability: Capability<Name>) => boolean;
   /**
    * The fields the user's roles allow for a capability: the union of their lists, or `undefined` when a role grants
-   * it without a list (every field) or none grants it.
+   * it without a list (every field) or none grants it. With the resource's model, as `can` has it, wildcards over
+   * resources count only where the resource takes them.
    */
-  fields: (user: AccessUser, capability: string) => readonly string[] | undefined;
+  fields: (user: AccessUser, capability: string, model?: ResourceModel) => readonly string[] | undefined;
   /**
    * A rule that allows when the user's roles grant the capability: `true` for an unscoped
-   * grant, a row filter for `.own`, `.team` and a limit's filter, `false` otherwise. Refuses a wildcard.
+   * grant, a row filter for `.own`, `.team` and a limit's filter, `false` otherwise. Refuses a wildcard. On a resource
+   * with `.explicitGrants()`, a role's wildcard over resources such as `*.read` grants nothing.
    */
   can: (capability: ExactCapability<Name>) => Rule;
   /** A rule that allows when the user has any of the roles. */

package/dist/access/roles.js

@@ -4,6 +4,7 @@ import { heldCapabilities } from "./role-entry.js";
 import { rule } from "./rule.js";
 //#region src/access/roles.ts
 const rolesOf = (user) => user.roles ?? [];
+const reaches = (held, model) => !model?.explicitGrants || held.capability === "*" || parseCapability(held.capability).name !== "*";
 /**
 * Defines roles as bundles of capability strings. Pass the resource and area names as the type
 * parameter to reject unknown names at compile time:
@@ -66,22 +67,24 @@ const defineRoles = (definitions, options = {}) => {
 		holds: (user, capability) => heldBy(user).some((held) => !held.fields && !held.filter && holdsAll(held.capability, capability)),
 		/**
 		* The fields the user's roles allow for a capability: the union of their lists, or `undefined` when a role grants
-		* it without a list (every field) or none grants it.
+		* it without a list (every field) or none grants it. With the resource's model, as `can` has it, wildcards over
+		* resources count only where the resource takes them.
 		*/
-		fields: (user, capability) => {
+		fields: (user, capability, model) => {
 			const wanted = parseCapability(capability);
-			const matching = heldBy(user).filter((held) => grantsOf(held.capability, wanted).length > 0);
+			const matching = heldBy(user).filter((held) => reaches(held, model) && grantsOf(held.capability, wanted).length > 0);
 			if (matching.length === 0 || matching.some((held) => !held.fields)) return void 0;
 			return [...new Set(matching.flatMap((held) => held.fields))];
 		},
 		/**
 		* A rule that allows when the user's roles grant the capability: `true` for an unscoped
-		* grant, a row filter for `.own`, `.team` and a limit's filter, `false` otherwise. Refuses a wildcard.
+		* grant, a row filter for `.own`, `.team` and a limit's filter, `false` otherwise. Refuses a wildcard. On a resource
+		* with `.explicitGrants()`, a role's wildcard over resources such as `*.read` grants nothing.
 		*/
 		can: (capability) => {
 			const wanted = parseExactCapability(capability);
 			return rule(async (ctx) => {
-				const matching = heldBy(ctx.user ?? {}).flatMap((held) => grantsOf(held.capability, wanted).map((grant) => ({
+				const matching = heldBy(ctx.user ?? {}).filter((held) => reaches(held, ctx.model)).flatMap((held) => grantsOf(held.capability, wanted).map((grant) => ({
 					grant,
 					filter: held.filter
 				})));

package/dist/model.d.ts

@@ -149,6 +149,8 @@ export type ResourceModel = {
   comments?: true;
   /** Whether open pages refresh as soon as its records change (`.live()`). */
   live?: true;
+  /** Whether role wildcards such as `*.read` leave it out, so only `*` and capabilities naming it grant it (`.explicitGrants()`). */
+  explicitGrants?: true;
   /**
    * The fields of a unique key whose conflict on create answers the record already holding those values, to a caller
    * who may read it (`.openExisting()`).

package/dist/resource-model.d.ts

@@ -24,6 +24,7 @@ export type ResourceState = {
   history?: boolean;
   comments?: boolean;
   live?: boolean;
+  explicitGrants?: boolean;
   openExisting?: string[];
 };
 export declare const parseTable: (table: string) => {

package/dist/resource-model.js

@@ -75,6 +75,7 @@ const assembleModel = (state) => {
 		...state.history && { history: true },
 		...state.comments && { comments: true },
 		...state.live && { live: true },
+		...state.explicitGrants && { explicitGrants: true },
 		...state.position && { position: { ...state.position } },
 		...state.parents && { parents: state.parents.map((parent) => ({ ...parent })) },
 		...state.openExisting && { openExisting: [...state.openExisting] }

package/dist/resource.d.ts

@@ -170,6 +170,12 @@ export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
    * [Live updates](docs/website/src/content/docs/reference/live.mdx).
    */
   live(): ResourceBuilder<F, K>;
+  /**
+   * Leaves it out of role wildcards over resources such as `*.read`: with roles, only `*` itself and capabilities that
+   * name it, such as `webhook_subscriptions.read`, grant it. For resources whose records hold secrets, which a role
+   * written as "read everything" should not reach. See [Resources that need named grants](docs/website/src/content/docs/reference/access.mdx#resources-that-need-named-grants).
+   */
+  explicitGrants(): ResourceBuilder<F, K>;
   /** The code predicates (`match`) of its events, by event name. */
   eventMatches(): Record<string, EventMatch<any>>;
   /**

package/dist/resource.js

@@ -192,6 +192,14 @@ var ResourceBuilder = class ResourceBuilder {
 	live() {
 		return this.next({ live: true });
 	}
+	/**
+	* Leaves it out of role wildcards over resources such as `*.read`: with roles, only `*` itself and capabilities that
+	* name it, such as `webhook_subscriptions.read`, grant it. For resources whose records hold secrets, which a role
+	* written as "read everything" should not reach. See [Resources that need named grants](docs/website/src/content/docs/reference/access.mdx#resources-that-need-named-grants).
+	*/
+	explicitGrants() {
+		return this.next({ explicitGrants: true });
+	}
 	/** The code predicates (`match`) of its events, by event name. */
 	eventMatches() {
 		return eventMatches(this.toModel(), this.state.events ?? []);

package/dist/webhooks/webhook-resources.js

@@ -3,7 +3,10 @@ import { resource } from "../resource.js";
 import { view } from "../view.js";
 import { layout } from "../layout.js";
 //#region src/webhooks/webhook-resources.ts
-/** Webhook subscriptions: a row per subscription someone made in the admin app, scoped to their tenant. */
+/**
+* Webhook subscriptions: a row per subscription someone made in the admin app, scoped to their tenant. Their URLs and
+* secrets let anyone call the receivers, so a role's wildcard such as `*.read` reaches none of the webhook resources.
+*/
 const subscriptionsResource = (schema) => resource("webhook_subscriptions").table(`${schema}.subscriptions`).fields({
 	id: f.uuid().readOnly().dbDefault(),
 	name: f.text().min(1).max(100).filterable().sortable(),
@@ -26,7 +29,7 @@ const subscriptionsResource = (schema) => resource("webhook_subscriptions").tabl
 	rotate_secret: f.boolean().default(false),
 	send_test: f.boolean().default(false),
 	resend_failed: f.boolean().default(false)
-}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).owner((r) => r.owner_id).search((r) => [r.name, r.url]);
+}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).owner((r) => r.owner_id).search((r) => [r.name, r.url]).explicitGrants();
 const subscriptionsView = view("webhook_subscriptions").names({
 	singular: "Webhook subscription",
 	plural: "Webhook subscriptions"
@@ -117,7 +120,7 @@ const deliveriesResource = (schema) => resource("webhook_deliveries").table(`${s
 	last_error: f.text().optional().readOnly(),
 	created_at: f.timestamp().readOnly().sortable(),
 	resend: f.boolean()
-}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).access({
+}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).explicitGrants().access({
 	create: () => false,
 	delete: () => false
 });
@@ -169,7 +172,7 @@ const deliveryLogResource = (schema) => resource("webhook_delivery_log").table(`
 	response: f.text().optional().readOnly(),
 	duration_ms: f.integer().readOnly(),
 	at: f.timestamp().readOnly().filterable().sortable()
-}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).access({
+}).primaryKey((r) => r.id).tenant((r) => r.tenant_id).explicitGrants().access({
 	create: () => false,
 	update: () => false,
 	delete: () => false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/schema",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Resource, field, view and access definitions for Protobase configs.",
   "license": "Apache-2.0",
   "repository": {