@xemahq/authorization-internal-api-client 0.4.15 → 0.4.18

package/dist/endpoints/resources/resources.d.ts

@@ -13,6 +13,8 @@ export declare const resourcesControllerRegister: (registerResourceOwnershipDto:
 export declare const getResourcesControllerListVisibleUrl: () => string;
 /**
  * Unions OpenFGA owner/shared-with visibility (usersets expanded transitively) with org-shared instances. Org scope is forced from the caller context. Used by platform BFFs to visibility-filter a list on behalf of the end user they serve.
+ *
+ * Supplying `minLevel` narrows the question from "may this subject SEE it" to "does this subject hold at least this LEVEL on it": the answer becomes owner ∪ shared at or above that rung, and org-shared instances drop out because org-shared is a visibility pattern rather than a rung. That is the question a BFF asks to decide who may MANAGE an instance, and answering it here is what keeps the caller from having to expand identity groups itself — OpenFGA expands `team#member` and `role#assignee` usersets transitively.
  * @summary List the instances of a resource type a subject may see
  */
 export declare const resourcesControllerListVisible: (listVisibleResourcesDto: ListVisibleResourcesDto, options?: RequestInit) => Promise<VisibleResourcesDtoDataEnvelope>;
@@ -34,7 +36,7 @@ export declare const getResourcesControllerGetOwnershipUrl: (type: string, id: s
 export declare const resourcesControllerGetOwnership: (type: string, id: string, options?: RequestInit) => Promise<ResourceOwnershipReadDtoDataEnvelope>;
 export declare const getResourcesControllerReplaceOwnershipUrl: (type: string, id: string) => string;
 /**
- * The whole post-state: after this call the instance’s registered subjects are EXACTLY `owners` ∪ `explicitShares`, and a subject named by neither loses its authority row AND its `shared_with` tuple. This is the ONLY surface that can express a revocation as part of a set write — `resource.register` upserts what it is handed and never touches a subject outside that list, so re-registering with a subject removed reports 200 and leaves both its row and its tuple live. Removals delete the tuple BEFORE the row (a crash between them leaves the subject WITHOUT access); additions write the row before the tuple. Serialised per instance by an advisory lock, so two concurrent replaces cannot interleave into a mixed set. Idempotent. Refuses (409 `RESOURCE_SUBJECT_IS_OWNER`) when a currently-registered OWNER is absent from the new `owners` list — dropping or demoting an owner is `resource.deregister`. Org scope is forced from the caller context.
+ * The whole post-state: after this call the instance’s registered subjects are EXACTLY `owners` ∪ `explicitShares`, and a subject named by neither loses its authority row AND its `shared_with` tuple. This is the ONLY surface that can express a revocation as part of a set write — `resource.register` upserts what it is handed and never touches a subject outside that list, so re-registering with a subject removed reports 200 and leaves both its row and its tuple live. Removals delete the tuple BEFORE the row (a crash between them leaves the subject WITHOUT access); additions write the row before the tuple. Serialised per instance by an advisory lock, so two concurrent replaces cannot interleave into a mixed set. Idempotent. Refuses (409 `RESOURCE_SUBJECT_IS_OWNER`) when a currently-registered OWNER is absent from the new `owners` list — dropping or demoting an owner is `resource.deregister`. Org scope is forced from the caller context. A body naming a `grantor` has every share judged against the level that subject actually holds (read from the tuple store, never from the body); omitting it means the calling service asserts owner authority.
  * @summary REPLACE a resource instance’s ownership set
  */
 export declare const resourcesControllerReplaceOwnership: (type: string, id: string, replaceResourceOwnershipDto: ReplaceResourceOwnershipDto, options?: RequestInit) => Promise<ResourceOwnershipDtoDataEnvelope>;

package/dist/endpoints/resources/resources.js

@@ -25,6 +25,8 @@ const getResourcesControllerListVisibleUrl = () => {
 exports.getResourcesControllerListVisibleUrl = getResourcesControllerListVisibleUrl;
 /**
  * Unions OpenFGA owner/shared-with visibility (usersets expanded transitively) with org-shared instances. Org scope is forced from the caller context. Used by platform BFFs to visibility-filter a list on behalf of the end user they serve.
+ *
+ * Supplying `minLevel` narrows the question from "may this subject SEE it" to "does this subject hold at least this LEVEL on it": the answer becomes owner ∪ shared at or above that rung, and org-shared instances drop out because org-shared is a visibility pattern rather than a rung. That is the question a BFF asks to decide who may MANAGE an instance, and answering it here is what keeps the caller from having to expand identity groups itself — OpenFGA expands `team#member` and `role#assignee` usersets transitively.
  * @summary List the instances of a resource type a subject may see
  */
 const resourcesControllerListVisible = async (listVisibleResourcesDto, options) => {
@@ -77,7 +79,7 @@ const getResourcesControllerReplaceOwnershipUrl = (type, id) => {
 };
 exports.getResourcesControllerReplaceOwnershipUrl = getResourcesControllerReplaceOwnershipUrl;
 /**
- * The whole post-state: after this call the instance’s registered subjects are EXACTLY `owners` ∪ `explicitShares`, and a subject named by neither loses its authority row AND its `shared_with` tuple. This is the ONLY surface that can express a revocation as part of a set write — `resource.register` upserts what it is handed and never touches a subject outside that list, so re-registering with a subject removed reports 200 and leaves both its row and its tuple live. Removals delete the tuple BEFORE the row (a crash between them leaves the subject WITHOUT access); additions write the row before the tuple. Serialised per instance by an advisory lock, so two concurrent replaces cannot interleave into a mixed set. Idempotent. Refuses (409 `RESOURCE_SUBJECT_IS_OWNER`) when a currently-registered OWNER is absent from the new `owners` list — dropping or demoting an owner is `resource.deregister`. Org scope is forced from the caller context.
+ * The whole post-state: after this call the instance’s registered subjects are EXACTLY `owners` ∪ `explicitShares`, and a subject named by neither loses its authority row AND its `shared_with` tuple. This is the ONLY surface that can express a revocation as part of a set write — `resource.register` upserts what it is handed and never touches a subject outside that list, so re-registering with a subject removed reports 200 and leaves both its row and its tuple live. Removals delete the tuple BEFORE the row (a crash between them leaves the subject WITHOUT access); additions write the row before the tuple. Serialised per instance by an advisory lock, so two concurrent replaces cannot interleave into a mixed set. Idempotent. Refuses (409 `RESOURCE_SUBJECT_IS_OWNER`) when a currently-registered OWNER is absent from the new `owners` list — dropping or demoting an owner is `resource.deregister`. Org scope is forced from the caller context. A body naming a `grantor` has every share judged against the level that subject actually holds (read from the tuple store, never from the body); omitting it means the calling service asserts owner authority.
  * @summary REPLACE a resource instance’s ownership set
  */
 const resourcesControllerReplaceOwnership = async (type, id, replaceResourceOwnershipDto, options) => {

package/dist/models/listVisibleResourcesDto.d.ts

@@ -7,6 +7,8 @@ import type { ResourceSubjectRefDto } from './resourceSubjectRefDto.js';
 export interface ListVisibleResourcesDto {
     /** Resource kind/type slug. */
     resourceType: string;
+    /** The resource kind's own name for the MINIMUM level the subject must hold. Omitted = the visibility question (owner ∪ shared at any level ∪ org-shared). Present = the authority question (owner ∪ shared at or above this level); org-shared instances are NOT included, because org-shared is a visibility pattern rather than a rung. */
+    minLevel?: string;
     /** The subject whose visible instances are enumerated. */
     subject: ResourceSubjectRefDto;
 }

package/dist/models/replaceResourceOwnershipDto.d.ts

@@ -23,4 +23,6 @@ export interface ReplaceResourceOwnershipDto {
        * So the exemption is per-SUBJECT and explicit: an owner named here is exempt from that probe and has its `owned_by` tuple dropped in the same call that writes the new owners. Naming a subject that is not a registered owner is a no-op, not an error — the migration is then idempotent on replay. A subject named in BOTH `retiringOwners` and `owners` is refused: that is two contradictory instructions about one subject, and either reading is a guess.
        */
     retiringOwners?: ResourceSubjectRefDto[];
+    /** The subject GRANTING the shares in this body, when it is not the instance owner. Used to apply the two delegation rules — a grantor may never confer more than they hold, and re-sharing is itself a level. The LEVEL is resolved from the tuple store, never taken from the body: a grantor that could name its own level would name the highest one. A named grantor holding neither ownership nor any share level is a 403 `RESOURCE_GRANTOR_HOLDS_NOTHING`. Omitted means the calling SERVICE asserts owner authority, which is what this whole surface already establishes — and is exactly how every replace behaved before this field existed, so omitting it changes nothing. */
+    grantor?: ResourceSubjectRefDto;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/authorization-internal-api-client",
-  "version": "0.4.15",
+  "version": "0.4.18",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [