@twinfinity/twin 6.1.0 → 6.1.2-ci.30738

package/src/types/twin-permissions-api.ts

@@ -1,11 +1,32 @@
 /**
- * Named, customer-scoped capability the caller can exercise against the
- * Twin service. Returned by `GET /twins/permissions/me`. Forward-compatible:
- * unknown strings should be treated as "not granted" and ignored, so adding
- * a new capability on the backend is a non-breaking change for clients
- * compiled against older types.
+ * Named, customer-scoped capability the caller can exercise against the Twin service, granted on
+ * the asset domain — the one thing the service governs that is not bound to a single
+ * twin. Returned by `GET /twins/permissions/me`, listed by `GET /twins/permissions` and accepted by
+ * `PUT /twins/permissions/{principalId}`. Mirrors `Twinfinity.Twin.Model.TwinCapability`.
+ *
+ * Distinct from {@link TwinScopedCapability}, which is held on one twin. The two vocabularies never
+ * share a name, because `GET /twins/{twinId}/permissions/me` answers with one flat array mixing
+ * both and each name is resolved against the vocabulary it came from.
+ *
+ * This is the *write* vocabulary — the capabilities a grant may ask for. Values read back from the
+ * service are {@link TwinCapabilityName}, which also admits capabilities a newer server knows and
+ * this client does not; such a value is "not granted" as far as this client is concerned, and must
+ * be ignored rather than treated as an error.
  */
-export type TwinCapability = 'ViewAssetTypes' | 'EditAssetTypes';
+export type TwinCapability = 'ViewAssets' | 'EditAssets' | 'DeleteAssets' | 'EditAssetTypes' | 'ManageAssetPermissions';
+
+/**
+ * A capability as *read back* from the service: one of {@link TwinCapability}, or a name a newer
+ * server knows and this client does not.
+ *
+ * Deliberately wider than the write vocabulary. A grant may only ask for capabilities that exist,
+ * so {@link TwinCapability} stays closed and a typo is a compile error; a listing, though, is
+ * whatever the server says, and ADR-0008 §5 makes tolerating unknown names a rule for readers. The
+ * `(string & {})` tail keeps autocomplete on the five known values while forcing consumers who
+ * `switch` over a capability to write a default arm — which is where an unknown one must land.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinCapabilityName = TwinCapability | (string & {});
 
 /**
  * Response body for `GET /twins/permissions/me`. The `permissions` array
@@ -16,5 +37,221 @@ export type TwinCapability = 'ViewAssetTypes' | 'EditAssetTypes';
  * etag, an identity echo, expiry — can be added without a shape break.
  */
 export interface MyPermissions {
+    permissions: TwinCapabilityName[];
+}
+
+/**
+ * Named capability a principal can hold on one specific twin, granted through
+ * `/twins/{twinId}/permissions`. Mirrors `Twinfinity.Twin.Model.TwinScopedCapability`.
+ *
+ * Distinct from {@link TwinCapability}, which is customer-scoped and speaks about the
+ * asset domain rather than about one twin.
+ *
+ * This is the *write* vocabulary — the four capabilities a grant may ask for. Values read back
+ * from the service are {@link TwinScopedCapabilityName}, which also admits capabilities a newer
+ * server knows and this client does not; such a value is "not granted" as far as this client is
+ * concerned, and must be ignored rather than treated as an error.
+ */
+export type TwinScopedCapability = 'ReadTwin' | 'WriteTwin' | 'DeleteTwin' | 'ManageTwinPermissions';
+
+/**
+ * A capability as *read back* from the service: one of {@link TwinScopedCapability}, or a name a
+ * newer server knows and this client does not.
+ *
+ * Deliberately wider than the write vocabulary. A grant may only ask for capabilities that exist,
+ * so {@link TwinPermissionsPut} stays closed and a typo is a compile error; a listing, though, is
+ * whatever the server says, and ADR-0008 §5 makes tolerating unknown names a rule for readers. The
+ * `(string & {})` tail keeps autocomplete on the four known values while forcing consumers who
+ * `switch` over a capability to write a default arm — which is where an unknown one must land.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinScopedCapabilityName = TwinScopedCapability | (string & {});
+
+/**
+ * A capability as read back from `GET /twins/{twinId}/permissions/me`. That probe answers with one
+ * flat array mixing both vocabularies: the twin's own {@link TwinScopedCapability} values, plus the
+ * asset-instance capabilities `ViewAssets`, `EditAssets` and `DeleteAssets` from the customer-wide
+ * asset domain, which gate the assets hanging off the twin. `EditAssetTypes` and
+ * `ManageAssetPermissions` are not twin-bound and are absent — ask `GET /twins/permissions/me`.
+ *
+ * Names never collide across the two enums, so `includes('EditAssets')` is unambiguous. As with
+ * {@link TwinScopedCapabilityName}, the `(string & {})` tail admits names a newer server knows.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TwinBoundCapabilityName = TwinScopedCapability | TwinCapability | (string & {});
+
+/**
+ * Response body for `GET /twins/{twinId}/permissions/me`: the capabilities the caller
+ * holds on that twin. The endpoint is open to every authenticated caller — an empty
+ * list is an honest answer, not a refusal — so it is safe to call before rendering.
+ */
+export interface MyTwinPermissions {
+    permissions: TwinBoundCapabilityName[];
+}
+
+/**
+ * One entry of an access-control-list row's `inheritedPermissions`: capabilities the row's principal
+ * holds from a grant made somewhere other than this resource, and where that grant lives.
+ *
+ * `source` is an entity reference. A grant held customer-wide is spelled as the bare domain token
+ * with no trailing separator — `"twin"` for the asset capabilities a twin reports — which is where
+ * an administration UI has to go to change them.
+ */
+export interface InheritedPermissions {
+    source: string;
+    permissions: TwinBoundCapabilityName[];
+}
+
+/**
+ * One principal's permission entry on a twin, as listed by
+ * `GET /twins/{twinId}/permissions` and returned by the mutation endpoints.
+ *
+ * This is where the provenance split lives: {@link permissions} is what an administrator can edit
+ * here, {@link inheritedPermissions} is what confers ability on the twin from elsewhere, and
+ * {@link effectivePermissions} is what this principal can actually do. All three describe *this
+ * row's principal* — a twin's own representation is the one that describes the caller, and it
+ * carries the verdict alone.
+ */
+export interface TwinPrincipalPermissionsGet {
+    /** Global id of the principal (a group; users are not grantable per ADR-0008 §6). */
+    principalId: string;
+    /** The principal's display title. */
+    name: string;
+    /**
+     * What this principal holds from grants made on the twin *itself*, and the only part this
+     * surface writes: `setTwinPermissions` replaces exactly this set.
+     */
+    permissions: TwinScopedCapabilityName[];
+    /**
+     * One entry per place outside this twin that confers ability on it. A twin has one possible
+     * source: the domain, `source: 'twin'`, carrying whichever of `ViewAssets`, `EditAssets` and
+     * `DeleteAssets` this principal holds customer-wide, because `twins/{twinId}/assets` gates on
+     * them. The asset catalog capability and `ManageAssetPermissions` never appear — they are
+     * domain-wide and confer nothing on one twin. Empty when the principal holds none of them.
+     */
+    inheritedPermissions: InheritedPermissions[];
+    /**
+     * The union of {@link permissions} and every {@link inheritedPermissions} entry — what this
+     * principal can actually do on the twin. Calculated by the service on every read and never
+     * accepted on a write. Mixes both capability vocabularies, so it is typed the widened way.
+     */
+    effectivePermissions: TwinBoundCapabilityName[];
+    /**
+     * True exactly when a `PUT` or `DELETE` naming this principal would be refused with
+     * `SystemPrincipalImmutable`: the twin's own default groups and the seeded Twinfinity
+     * system principals. Render the control as disabled rather than discovering the
+     * constraint by attempting a write.
+     */
+    readOnly: boolean;
+    /**
+     * Optimistic concurrency token for this entry, to send back on the next mutation of this
+     * principal. Two entries in one listing may carry different values — edit each with the one its
+     * own row reported. Absent when the service had none to report.
+     */
+    etag?: string;
+}
+
+/** Request body for `PUT /twins/{twinId}/permissions/{principalId}`. */
+export interface TwinPermissionsPut {
+    /**
+     * The capability set replacing whatever this principal held of the four above; bits
+     * outside this vocabulary survive untouched. An empty list revokes all four, which
+     * leaves the principal with no listing entry at all unless it carries such bits.
+     */
+    permissions: TwinScopedCapability[];
+    /**
+     * This principal's etag, from its entry in a prior listing or mutation response. May be omitted only to create
+     * the grants of a principal that holds nothing on the twin yet — the one case with no
+     * entry to read one from. Omitting it on what turns out to be a replacement is refused
+     * with `EtagRequired`, and a stale value with `EtagMismatch`.
+     */
+    etag?: string;
+}
+
+/**
+ * One of the default groups a twin owns — `TwinReaders`, `TwinContributors`,
+ * `TwinAdministrators` — provisioned for it when it is created.
+ *
+ * Address a group by {@link id}: {@link name} is informational and not unique across
+ * twins, since every twin's groups carry the same three names. The groups' own grants
+ * are immutable; confer a preset by changing a group's membership through the
+ * Permission service instead.
+ */
+export interface TwinGroupGet {
+    name: string;
+    id: string;
+    title: string;
+}
+
+/** Response body for `GET /twins/{twinId}/groups`. */
+export interface TwinGroupsGet {
+    groups: TwinGroupGet[];
+}
+
+/**
+ * One principal's permission entry on the asset domain, as listed by `GET /twins/permissions` and
+ * returned by the mutation endpoints.
+ *
+ * The etag is customer-wide rather than per principal, so every entry in a listing carries the same
+ * value and a write by any administrator invalidates the one every other administrator is holding.
+ */
+export interface AssetPrincipalPermissionsGet {
+    /** Global id of the principal (a group; users are not grantable). */
+    id: string;
+    /** The principal's display name. */
+    name: string;
+    /** The capabilities this principal holds on the domain. Empty after a full revoke. */
+    permissions: TwinCapabilityName[];
+    /**
+     * True exactly when a `PUT` or `DELETE` naming this principal would be refused with
+     * `SystemPrincipalImmutable`: the seeded default groups. Render the control as disabled rather
+     * than discovering the constraint by attempting a write. False for everything else, the
+     * all-authenticated principal included, whose capabilities are mutable.
+     */
+    readOnly: boolean;
+    /**
+     * Optimistic concurrency token, to send back on the next mutation. It is customer-wide rather
+     * than per principal, so any administrator's write invalidates the value every other one holds.
+     *
+     * Because it belongs to the domain rather than to the principal, a revocation answers with one
+     * too, even though the revoked principal no longer has a listing entry — so a caller may chain
+     * another write straight after a `deleteAssetPermissions` without re-reading the listing.
+     *
+     * Absent only before the domain has been provisioned for the customer.
+     */
+    etag?: string;
+}
+
+/** Request body for `PUT /twins/permissions/{principalId}`. */
+export interface AssetPermissionsPut {
+    /**
+     * The capability set replacing whatever this principal held; an empty list revokes everything
+     * and leaves the principal with no listing entry at all.
+     */
     permissions: TwinCapability[];
+    /**
+     * The domain's etag. May be omitted only to create the grants of a principal that holds nothing
+     * yet — the one case with no entry to read one from. Omitting it on what turns out to be a
+     * replacement is refused with `EtagRequired`, and a stale value with `EtagMismatch`.
+     */
+    etag?: string;
+}
+
+/**
+ * One of the asset domain's default groups — `AssetsReaders`, `AssetsContributors`,
+ * `AssetsAdministrators` — seeded once per customer.
+ *
+ * Unlike a twin's groups, {@link name} is unique across the customer and is what
+ * {@link ITwinClient.getAssetGroup} addresses. The groups' own grants are immutable; confer a
+ * preset by changing a group's membership through the permission API instead.
+ */
+export interface AssetGroupGet {
+    name: string;
+    id: string;
+    title: string;
+}
+
+/** Response body for `GET /twins/groups`. */
+export interface AssetGroupsGet {
+    groups: AssetGroupGet[];
 }