@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/sharing/grants/grants.controller.js

@@ -0,0 +1,176 @@
+"use strict";
+// =============================================================================
+// The grant routes: /api/grants (issue #729, PP-7.2)
+// =============================================================================
+//
+// Every route declares its permission through the app's access decorators
+// (there is no global guard); the SHARING rule (the `share` action on the
+// record, the grantee removing their own access) is the service's decision,
+// inside the request's org-scoped transaction:
+//
+//   GET    /grants?resourceType&resourceId   sharing:read   `share` on the record, else 404
+//   POST   /grants                           sharing:write  `share` on the record
+//   GET    /grants/shared-with-me            sharing:read
+//   PATCH  /grants/:id                       sharing:write  `share` on the grant's record
+//   DELETE /grants/:id                       sharing:read   self; others need sharing:write + `share`
+//
+// Link grants (#730) get their own routes; these take user and group grantees.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGrantsController = createGrantsController;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const grants_dto_1 = require("../dto/grants.dto");
+const sharing_principal_decorator_1 = require("../groups/sharing-principal.decorator");
+const permissions_1 = require("../permissions");
+const grants_service_1 = require("./grants.service");
+const NOT_FOUND = 'The record does not exist in your organization, or you may not share it (never 403 for a type that hides existence: an id discloses nothing)';
+/**
+ * Creates the `GrantsController` class for one set of module options, its
+ * routes guarded by the app's access decorators. `SharingModule.forRoot()`
+ * calls it.
+ *
+ * @param options - the resolved module options.
+ * @returns the controller class.
+ *
+ * @stability experimental
+ */
+function createGrantsController(options) {
+    const access = options.host.access;
+    const CurrentPrincipal = (0, sharing_principal_decorator_1.createSharingPrincipalDecorator)(options.principal);
+    const READ = access.requirePermissions([permissions_1.SHARING_PERMISSIONS.SHARING_READ]);
+    const WRITE = access.requirePermissions([permissions_1.SHARING_PERMISSIONS.SHARING_WRITE]);
+    let GrantsController = class GrantsController {
+        grants;
+        constructor(grants) {
+            this.grants = grants;
+        }
+        sharedWithMe(principal, query) {
+            return this.grants.sharedWithMe(principal, query);
+        }
+        list(principal, query) {
+            return this.grants.list(principal, query);
+        }
+        create(principal, body) {
+            return this.grants.create(principal, body);
+        }
+        update(principal, id, body) {
+            return this.grants.update(principal, id, body);
+        }
+        async revoke(principal, id) {
+            await this.grants.revoke(principal, id);
+        }
+    };
+    __decorate([
+        (0, common_1.Get)('shared-with-me'),
+        READ,
+        (0, swagger_1.ApiOperation)({
+            summary: 'List what is shared with me',
+            description: 'Records shared with you through an active, unexpired grant to you or to a group of your active ' +
+                'organization, newest first, with their `title` and `path` when the resource type describes its records. ' +
+                'Optionally one `resourceType`. Flat pagination. Requires `sharing:read`.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, type: grants_dto_1.SharedWithMeListResponseDto }),
+        __param(0, CurrentPrincipal()),
+        __param(1, (0, common_1.Query)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, grants_dto_1.SharedWithMeQueryDto]),
+        __metadata("design:returntype", void 0)
+    ], GrantsController.prototype, "sharedWithMe", null);
+    __decorate([
+        (0, common_1.Get)(),
+        READ,
+        (0, swagger_1.ApiOperation)({
+            summary: "List a record's grants",
+            description: 'The active user and group grants of one record, oldest first. You must be allowed to share the record ' +
+                '(its owner, a group admin of its owning group, or a `sharing:admin` holder, unless the resource type says ' +
+                'otherwise); anyone else gets 404. Requires `sharing:read`.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, type: grants_dto_1.GrantListResponseDto }),
+        (0, swagger_1.ApiResponse)({ status: 404, description: NOT_FOUND }),
+        __param(0, CurrentPrincipal()),
+        __param(1, (0, common_1.Query)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, grants_dto_1.GrantListQueryDto]),
+        __metadata("design:returntype", void 0)
+    ], GrantsController.prototype, "list", null);
+    __decorate([
+        (0, common_1.Post)(),
+        WRITE,
+        (0, swagger_1.ApiOperation)({
+            summary: 'Share a record',
+            description: 'With a user (by `userId` or `email`; an active member of the organization, 422 `NOT_AN_ORG_MEMBER` ' +
+                'otherwise) or a group of the organization (422 `GROUP_NOT_IN_ORG`). A grantee that already holds an ' +
+                'active grant on the record gets the new role: one role per grantee. The role must be grantable to that ' +
+                'kind of grantee (422 `ROLE_NOT_GRANTABLE`); sharing with yourself is 400 `SELF_GRANT`; past the ' +
+                "type's limit, 409 `GRANT_LIMIT_REACHED`. Failed lookups by e-mail are throttled per account (429 " +
+                '`LOOKUP_THROTTLED` with `Retry-After`). The user is notified (`sharing.shared_with_you`) when the share is ' +
+                'new or its role changed. Requires `sharing:write`.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 201, type: grants_dto_1.GrantResponseDto }),
+        (0, swagger_1.ApiResponse)({ status: 404, description: NOT_FOUND }),
+        (0, swagger_1.ApiResponse)({ status: 422, description: '`NOT_AN_ORG_MEMBER`, `GROUP_NOT_IN_ORG` or `ROLE_NOT_GRANTABLE`' }),
+        (0, swagger_1.ApiResponse)({ status: 429, description: '`LOOKUP_THROTTLED`' }),
+        __param(0, CurrentPrincipal()),
+        __param(1, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, grants_dto_1.CreateGrantDto]),
+        __metadata("design:returntype", void 0)
+    ], GrantsController.prototype, "create", null);
+    __decorate([
+        (0, common_1.Patch)(':id'),
+        WRITE,
+        (0, swagger_1.ApiParam)({ name: 'id', format: 'uuid' }),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Change a grant',
+            description: "Its role and/or expiry (`null` removes it). You must be allowed to share the grant's record; anyone else " +
+                'gets 404. Requires `sharing:write`.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, type: grants_dto_1.GrantResponseDto }),
+        (0, swagger_1.ApiResponse)({ status: 404, description: 'The grant does not exist, is revoked, or you may not manage it' }),
+        __param(0, CurrentPrincipal()),
+        __param(1, (0, common_1.Param)('id', new common_1.ParseUUIDPipe())),
+        __param(2, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, String, grants_dto_1.UpdateGrantDto]),
+        __metadata("design:returntype", void 0)
+    ], GrantsController.prototype, "update", null);
+    __decorate([
+        (0, common_1.Delete)(':id'),
+        READ,
+        (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+        (0, swagger_1.ApiParam)({ name: 'id', format: 'uuid' }),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Revoke a grant, or remove your own access',
+            description: 'A grant to you: remove your own access (`sharing:read` is enough). Any other grant needs `sharing:write` ' +
+                "and the right to share its record; otherwise 404. The grant is revoked, not deleted (`revokedAt`), and " +
+                'access ends on the next request.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 204, description: 'Revoked' }),
+        (0, swagger_1.ApiResponse)({ status: 404, description: 'The grant does not exist, is revoked, or you may not manage it' }),
+        __param(0, CurrentPrincipal()),
+        __param(1, (0, common_1.Param)('id', new common_1.ParseUUIDPipe())),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, String]),
+        __metadata("design:returntype", Promise)
+    ], GrantsController.prototype, "revoke", null);
+    GrantsController = __decorate([
+        (0, swagger_1.ApiTags)('Grants'),
+        (0, common_1.Controller)('grants'),
+        __metadata("design:paramtypes", [grants_service_1.GrantsService])
+    ], GrantsController);
+    return GrantsController;
+}
+//# sourceMappingURL=grants.controller.js.map

package/dist/sharing/grants/grants.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.controller.js","sourceRoot":"","sources":["../../../src/sharing/grants/grants.controller.ts"],"names":[],"mappings":"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"}

package/dist/sharing/grants/grants.service.d.ts

@@ -0,0 +1,197 @@
+import type { CreateGrantInput, GrantDto, GrantList, GrantListQuery, SharedWithMeList, SharedWithMeQuery, UpdateGrantInput } from '@marinoscar/platform-contract/sharing';
+import type { Principal } from '../../core/index';
+import { AccessPolicy } from '../access/access-policy.service';
+import { type GrantRow } from '../data/sharing-tx';
+import { MemberLookupThrottle } from '../groups/member-lookup-throttle';
+import { SharingEffects } from '../groups/sharing-effects';
+import { type SharingDataPort } from '../ports';
+import { PrincipalGroupsProvider } from '../principal-groups.provider';
+import { type ResolvedSharingModuleOptions } from '../sharing.options';
+/**
+ * Optional injection token of the grants service's clock (ms since epoch).
+ *
+ * @stability experimental
+ */
+export declare const GRANTS_CLOCK: unique symbol;
+/**
+ * A `grants` row with the grantee columns the response shows.
+ *
+ * @stability experimental
+ */
+export type GrantWithGrantee = GrantRow & {
+    /** The user grantee's columns, or `null`. */
+    granteeUser: {
+        /** The e-mail address. */
+        email: string;
+        /** The chosen display name, or `null`. */
+        displayName: string | null;
+        /** The identity provider's display name, or `null`. */
+        providerDisplayName: string | null;
+    } | null;
+    /** The group grantee's columns, or `null`. */
+    granteeGroup: {
+        /** The group's name. */
+        name: string;
+    } | null;
+};
+/**
+ * One user or group grant as the API returns it.
+ *
+ * @param row - the `grants` row with its grantee.
+ * @returns the wire shape.
+ *
+ * @stability experimental
+ */
+export declare function toGrantDto(row: GrantWithGrantee): GrantDto;
+/**
+ * Deletes every grant of the given records, of every grantee kind, revoked
+ * ones included. Call it INSIDE the transaction that deletes the records, so
+ * a deleted record never leaves a dangling grant behind (there is no foreign
+ * key to the record: the resource is polymorphic). The prune job catches what
+ * a forgotten call leaves.
+ *
+ * @param tx - the app's transaction client (org-scoped, or the system bypass).
+ * @param type - the records' resource type.
+ * @param ids - the records being deleted.
+ * @returns how many grants were deleted.
+ *
+ * @stability stable
+ */
+export declare function deleteGrantsForResources(tx: unknown, type: string, ids: readonly string[]): Promise<number>;
+/**
+ * The grants API: list, share (upsert), change, revoke, "shared with me",
+ * and `deleteForResources` for an app's delete transaction.
+ *
+ * @stability stable
+ */
+export declare class GrantsService {
+    private readonly data;
+    private readonly policy;
+    private readonly principalGroups;
+    private readonly throttle;
+    private readonly effects;
+    private readonly now;
+    private readonly options?;
+    constructor(data: SharingDataPort, policy: AccessPolicy, principalGroups: PrincipalGroupsProvider, throttle: MemberLookupThrottle, effects: SharingEffects, now?: () => number, options?: Pick<ResolvedSharingModuleOptions, "links"> | undefined);
+    /** The link lifetime bounds (#730). */
+    private get linkTtl();
+    /**
+     * Deletes every grant of the given records. Call it INSIDE the transaction
+     * that deletes them; see {@link deleteGrantsForResources}.
+     *
+     * @param tx - the app's transaction client.
+     * @param type - the records' resource type.
+     * @param ids - the records being deleted.
+     * @returns how many grants were deleted.
+     *
+     * @example
+     * ```ts
+     * await prisma.runInOrg(orgId, async (tx) => {
+     *   await grants.deleteForResources(tx, 'transcript', [id]);
+     *   await tx.transcript.delete({ where: { id } });
+     * });
+     * ```
+     *
+     * @extensionPoint hook
+     * @stability stable
+     */
+    deleteForResources(tx: unknown, type: string, ids: readonly string[]): Promise<number>;
+    /** A registered type named by the request; an unknown one is a 404 like a missing record. */
+    private registered;
+    /** An expiry from the request: in the future, or `null`. */
+    private expiry;
+    /**
+     * `GET /api/grants?resourceType&resourceId`: the record's active grants of
+     * every kind but links (user, group and app kinds), oldest first. The caller must pass the `share` action.
+     *
+     * @param principal - the caller (`sharing:read`).
+     * @param query - the record and the page.
+     * @returns a page of grants.
+     * @throws NotFoundException 404 (or the type's `denyAs`) when the caller may not share the record.
+     */
+    list(principal: Principal, query: GrantListQuery): Promise<GrantList>;
+    /**
+     * `POST /api/grants`: shares a record with a user (by id or e-mail), a
+     * group of its organization or a grantee of a registered persisted app kind
+     * (`kind: 'custom'`). A grantee that already holds an active grant
+     * gets the new role (one role per grantee). Failed lookups by e-mail count
+     * against the caller's throttle.
+     *
+     * @param principal - the caller (`sharing:write`).
+     * @param input - the record, the grantee, the role and the expiry.
+     * @returns the grant.
+     * @throws NotFoundException 404 when the caller may not share the record (or the type is unknown).
+     * @throws BadRequestException 400 `SELF_GRANT` or `EXPIRY_IN_PAST`.
+     * @throws UnprocessableEntityException 422 `ROLE_NOT_GRANTABLE`, `NOT_AN_ORG_MEMBER` or `GROUP_NOT_IN_ORG`.
+     * @throws ConflictException 409 `GRANT_LIMIT_REACHED`.
+     * @throws HttpException 429 `LOOKUP_THROTTLED`.
+     */
+    create(principal: Principal, input: CreateGrantInput): Promise<GrantDto>;
+    /**
+     * A grantee of an app-registered kind. The registered kind validates it and
+     * returns the normalised reference that is stored (422 `GRANTEE_INVALID` with
+     * its message when it rejects it); a kind nobody registered is 422
+     * `GRANTEE_KIND_UNKNOWN`; a registered kind that is not `persisted` is 422
+     * `GRANTEE_KIND_NOT_PERSISTABLE`. A built-in id is refused here (its own
+     * grantee shape creates those). The stored reference is a plain string of
+     * 1 to `granteeRefMax` characters: the kind is the platform's pin, never the
+     * kind's say-so, so a kind cannot write a row of another kind.
+     */
+    private resolveCustomGrantee;
+    /**
+     * Fills `grantee.display` of the app-kind grants of a page with the kind's own
+     * description. After the transaction (a kind's `describe` has no transaction),
+     * and a kind that throws, or is no longer registered, leaves it `null`.
+     */
+    private describeGrantees;
+    /** `INSERT ... ON CONFLICT` on the partial unique index of the grantee's kind. */
+    private upsert;
+    /**
+     * Loads an active grant of the caller's organization (any kind, links
+     * included, #730) and checks the caller may manage it: `share` on its
+     * record (a link: the type's `share_link` action when it declares one). A
+     * caller who may not gets the same 404 as for a missing grant.
+     */
+    private manageable;
+    /**
+     * `PATCH /api/grants/:id`: changes the role and/or the expiry, and a link
+     * grant's label (#730). The caller must pass the `share` action on the
+     * grant's record (a link: `share_link` when the type declares it). A link's
+     * expiry is capped by `links.maxTtlDays`.
+     *
+     * @param principal - the caller (`sharing:write`).
+     * @param grantId - the grant.
+     * @param input - the new role, expiry and/or (links only) label.
+     * @returns the grant.
+     * @throws NotFoundException 404 for a grant the caller may not manage.
+     * @throws UnprocessableEntityException 422 `NOT_A_LINK_GRANT` for a label on a user or group grant.
+     */
+    update(principal: Principal, grantId: string, input: UpdateGrantInput): Promise<GrantDto>;
+    /**
+     * `DELETE /api/grants/:id`: revokes a grant (soft: `revoked_at`,
+     * `revoked_by_id`). A user grantee may always remove their own access
+     * (`sharing:read` is enough); anyone else needs `sharing:write` and the
+     * `share` action on the record, and gets the same 404 as for a missing
+     * grant otherwise. Access ends on the next request.
+     *
+     * @param principal - the caller.
+     * @param grantId - the grant.
+     * @throws NotFoundException 404 for a grant the caller may not manage.
+     */
+    revoke(principal: Principal, grantId: string): Promise<void>;
+    /**
+     * `GET /api/grants/shared-with-me`: the records shared with the caller
+     * through an active, unexpired grant to them or to one of their groups,
+     * newest first, with the type's `describe()` labels when it has one.
+     *
+     * @param principal - the caller (`sharing:read`).
+     * @param query - optionally one resource type, and the page.
+     * @returns a page of items.
+     */
+    sharedWithMe(principal: Principal, query: SharedWithMeQuery): Promise<SharedWithMeList>;
+    /** Writes one audit row INSIDE the caller's transaction: ids and roles only, never an address. */
+    private audit;
+    /** The `sharing.shared_with_you` data, read inside the transaction (labels and the sharer's name). */
+    private notificationData;
+}
+//# sourceMappingURL=grants.service.d.ts.map

package/dist/sharing/grants/grants.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.service.d.ts","sourceRoot":"","sources":["../../../src/sharing/grants/grants.service.ts"],"names":[],"mappings":"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"}