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

package/dist/sharing/grants/grants.service.js

@@ -0,0 +1,736 @@
+"use strict";
+// =============================================================================
+// GrantsService: the grants API and the dangling-grant hygiene (issue #729)
+// =============================================================================
+//
+// Share one record with a user or a group of its organization, change or
+// revoke the share (any kind: link grants, minted by `LinkGrantsService`
+// (#730), are changed and revoked here too), and list what is shared with
+// the caller. Every query runs in ONE transaction scoped to the caller's ACTIVE
+// organization, so row-level security confines it there whatever id the
+// request names; the `share` decision is `AccessPolicy`'s, inside the same
+// transaction.
+//
+// ONE ROLE PER GRANTEE. Granting a user or group that already holds an ACTIVE
+// grant on the record replaces its role: the write is an `INSERT ... ON
+// CONFLICT` on the partial unique indexes `grants_active_user_uniq_idx` /
+// `grants_active_group_uniq_idx` (raw SQL, intentional drift), never a
+// `findFirst` pre-check, so two concurrent grants still leave one active row.
+//
+// SOFT REVOKE. `DELETE /api/grants/:id` sets `revoked_at` and
+// `revoked_by_id`; the `sharing.grants.prune` job deletes the row after the
+// retention period.
+//
+// AFTER COMMIT, outside the transaction: the `sharing.grant.*` events (ids
+// only) and, for a USER grant that was created or whose ROLE changed, the
+// `sharing.shared_with_you` notification (kvox's `changed` rule: never for an
+// unchanged re-grant, never for a group grant).
+// =============================================================================
+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.GrantsService = exports.GRANTS_CLOCK = void 0;
+exports.toGrantDto = toGrantDto;
+exports.deleteGrantsForResources = deleteGrantsForResources;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../otel-core/index");
+const access_policy_service_1 = require("../access/access-policy.service");
+const grantee_kinds_1 = require("../access/grantee-kinds");
+const resource_types_1 = require("../access/resource-types");
+const sharing_tx_1 = require("../data/sharing-tx");
+const errors_1 = require("../errors");
+const events_1 = require("../events");
+const group_common_1 = require("../groups/group-common");
+const member_lookup_throttle_1 = require("../groups/member-lookup-throttle");
+const sharing_effects_1 = require("../groups/sharing-effects");
+const permissions_1 = require("../permissions");
+const link_grants_service_1 = require("../links/link-grants.service");
+const ports_1 = require("../ports");
+const principal_groups_provider_1 = require("../principal-groups.provider");
+const sharing_1 = require("@marinoscar/platform-contract/sharing");
+const sharing_options_1 = require("../sharing.options");
+/**
+ * Optional injection token of the grants service's clock (ms since epoch).
+ *
+ * @stability experimental
+ */
+exports.GRANTS_CLOCK = Symbol.for('@marinoscar/platform/sharing/GRANTS_CLOCK');
+/** Most ids one `deleteMany` of `deleteForResources` names. */
+const DELETE_CHUNK = 1000;
+const GRANTEE_COLUMNS = {
+    granteeUser: { select: { email: true, displayName: true, providerDisplayName: true } },
+    granteeGroup: { select: { name: true } },
+};
+/**
+ * One user or group grant as the API returns it.
+ *
+ * @param row - the `grants` row with its grantee.
+ * @returns the wire shape.
+ *
+ * @stability experimental
+ */
+function toGrantDto(row) {
+    return {
+        id: row.id,
+        orgId: row.orgId,
+        resourceType: row.resourceType,
+        resourceId: row.resourceId,
+        grantee: {
+            kind: row.granteeKind,
+            userId: row.granteeUserId,
+            email: row.granteeUser?.email ?? null,
+            displayName: row.granteeUser ? (row.granteeUser.displayName ?? row.granteeUser.providerDisplayName ?? null) : null,
+            groupId: row.granteeGroupId,
+            groupName: row.granteeGroup?.name ?? null,
+            ref: row.granteeRef ?? null,
+            // Filled by the service for an app kind (its `describe` is asynchronous).
+            display: null,
+        },
+        role: row.role,
+        expiresAt: (0, group_common_1.iso)(row.expiresAt),
+        revokedAt: (0, group_common_1.iso)(row.revokedAt),
+        grantedById: row.grantedById,
+        createdAt: (0, group_common_1.iso)(row.createdAt),
+        updatedAt: (0, group_common_1.iso)(row.updatedAt),
+    };
+}
+/**
+ * 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
+ */
+async function deleteGrantsForResources(tx, type, ids) {
+    const unique = [...new Set(ids)];
+    let deleted = 0;
+    for (let i = 0; i < unique.length; i += DELETE_CHUNK) {
+        const { count } = await (0, sharing_tx_1.asSharingTx)(tx).grant.deleteMany({
+            where: { resourceType: type, resourceId: { in: unique.slice(i, i + DELETE_CHUNK) } },
+        });
+        deleted += count;
+    }
+    return deleted;
+}
+/**
+ * The grants API: list, share (upsert), change, revoke, "shared with me",
+ * and `deleteForResources` for an app's delete transaction.
+ *
+ * @stability stable
+ */
+let GrantsService = class GrantsService {
+    data;
+    policy;
+    principalGroups;
+    throttle;
+    effects;
+    now;
+    options;
+    constructor(data, policy, principalGroups, throttle, effects, now = Date.now, options) {
+        this.data = data;
+        this.policy = policy;
+        this.principalGroups = principalGroups;
+        this.throttle = throttle;
+        this.effects = effects;
+        this.now = now;
+        this.options = options;
+    }
+    /** The link lifetime bounds (#730). */
+    get linkTtl() {
+        return this.options?.links ?? sharing_options_1.SHARING_LINK_DEFAULTS;
+    }
+    /**
+     * 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, type, ids) {
+        return deleteGrantsForResources(tx, type, ids);
+    }
+    /** A registered type named by the request; an unknown one is a 404 like a missing record. */
+    registered(type) {
+        const rt = (0, resource_types_1.findResourceType)(type);
+        if (!rt)
+            throw (0, errors_1.resourceNotFound)();
+        return rt;
+    }
+    /** An expiry from the request: in the future, or `null`. */
+    expiry(value) {
+        if (value === undefined || value === null)
+            return null;
+        const at = new Date(value);
+        if (!(at.getTime() > this.now()))
+            throw (0, errors_1.expiryInPast)();
+        return at;
+    }
+    /**
+     * `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.
+     */
+    async list(principal, query) {
+        const orgId = (0, group_common_1.requireActiveOrg)(principal);
+        const rt = this.registered(query.resourceType);
+        return this.data.runInOrg({ orgId, userId: principal.userId }, async (raw) => {
+            const tx = (0, sharing_tx_1.asSharingTx)(raw);
+            await this.policy.requireIn(raw, principal, 'share', { type: rt.type, id: query.resourceId });
+            const where = { orgId, resourceType: rt.type, resourceId: query.resourceId, revokedAt: null, granteeKind: { not: 'link' } };
+            const total = await tx.grant.count({ where });
+            const rows = await tx.grant.findMany({
+                where,
+                include: GRANTEE_COLUMNS,
+                orderBy: [{ createdAt: 'asc' }, { id: 'asc' }],
+                skip: (query.page - 1) * query.pageSize,
+                take: query.pageSize,
+            });
+            return (0, group_common_1.paged)(rows.map(toGrantDto), total, query.page, query.pageSize);
+        }).then((page) => this.describeGrantees(page));
+    }
+    /**
+     * `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`.
+     */
+    async create(principal, input) {
+        const orgId = (0, group_common_1.requireActiveOrg)(principal);
+        const rt = this.registered(input.resourceType);
+        const grantee = input.grantee;
+        const byEmail = grantee.kind === 'user' && grantee.email !== undefined;
+        if (byEmail) {
+            const wait = this.throttle.retryAfterMs(principal.userId);
+            if (wait > 0)
+                throw (0, errors_1.lookupThrottled)(wait);
+        }
+        const expiresAt = this.expiry(input.expiresAt);
+        const ref = { type: rt.type, id: input.resourceId };
+        let missed = false;
+        let outcome;
+        try {
+            outcome = await this.data.runInOrg({ orgId, userId: principal.userId }, async (raw) => {
+                const tx = (0, sharing_tx_1.asSharingTx)(raw);
+                await this.policy.requireIn(raw, principal, 'share', ref);
+                // Only a caller who may share the record learns what a kind says about a grantee.
+                const custom = grantee.kind === 'custom' ? await this.resolveCustomGrantee(grantee.granteeKind, grantee.ref) : null;
+                const kind = custom ? custom.def.kind : grantee.kind;
+                const grantable = rt.grantable(kind);
+                if (!grantable.includes(input.role))
+                    throw (0, errors_1.roleNotGrantable)(input.role, kind, grantable);
+                // The grantee: an active member of the record's organization, one of its groups, or the
+                // reference an app kind validated (the kind scopes it; the row is confined to this organization).
+                let granteeId;
+                if (custom) {
+                    granteeId = custom.ref;
+                }
+                else if (grantee.kind === 'user') {
+                    const select = { id: true, isActive: true };
+                    const target = byEmail
+                        ? await tx.user.findFirst({ where: { email: { equals: grantee.email, mode: 'insensitive' } }, select })
+                        : await tx.user.findUnique({ where: { id: grantee.userId }, select });
+                    if (target && target.id === principal.userId)
+                        throw (0, errors_1.selfGrant)();
+                    const inOrg = target && target.isActive
+                        ? await tx.membership.findFirst({ where: { orgId, userId: target.id, status: 'active' }, select: { userId: true } })
+                        : null;
+                    if (!target || !inOrg) {
+                        missed = byEmail;
+                        throw (0, errors_1.notAnOrgMember)();
+                    }
+                    granteeId = target.id;
+                }
+                else if (grantee.kind === 'group') {
+                    const group = await tx.group.findFirst({ where: { id: grantee.groupId, orgId }, select: { id: true } });
+                    if (!group)
+                        throw (0, errors_1.groupNotInOrg)();
+                    granteeId = group.id;
+                }
+                else {
+                    throw (0, errors_1.granteeKindUnknown)(String(grantee.kind));
+                }
+                // The cap counts the record's active grants; replacing a grantee's role never hits it.
+                const active = await tx.grant.count({ where: { resourceType: rt.type, resourceId: ref.id, revokedAt: null } });
+                if (active >= rt.maxGrantsPerResource) {
+                    const mine = await tx.grant.count({
+                        where: {
+                            resourceType: rt.type,
+                            resourceId: ref.id,
+                            revokedAt: null,
+                            ...(custom
+                                ? { granteeKind: kind, granteeRef: granteeId }
+                                : grantee.kind === 'user'
+                                    ? { granteeKind: 'user', granteeUserId: granteeId }
+                                    : { granteeKind: 'group', granteeGroupId: granteeId }),
+                        },
+                    });
+                    if (mine === 0)
+                        throw (0, errors_1.conflict)(errors_1.SHARING_ERROR_REASONS.GRANT_LIMIT_REACHED, 'This record has reached its share limit');
+                }
+                const [result] = await this.upsert(tx, { orgId, type: rt.type, resourceId: ref.id, kind, granteeId, role: input.role, expiresAt, actorUserId: principal.userId });
+                const row = (await tx.grant.findUnique({ where: { id: result.id }, include: GRANTEE_COLUMNS }));
+                const previousRole = result.inserted ? null : result.previous_role;
+                // A concurrent first grant of the same grantee: the row was not in our snapshot. Treat as a change.
+                const concurrent = !result.inserted && result.previous_role === null;
+                const roleChanged = result.inserted || concurrent || previousRole !== input.role;
+                const expiryChanged = !result.inserted && !concurrent && (result.previous_expires_at?.getTime() ?? null) !== (expiresAt?.getTime() ?? null);
+                const changed = roleChanged || expiryChanged;
+                if (changed) {
+                    await this.audit(tx, {
+                        orgId,
+                        actorUserId: principal.userId,
+                        action: result.inserted ? 'grant:create' : 'grant:update',
+                        row,
+                        previousRole,
+                    });
+                }
+                const notify = grantee.kind === 'user' && roleChanged ? await this.notificationData(raw, rt, row, previousRole, principal.userId) : null;
+                return { row, inserted: result.inserted, previousRole, changed, notify };
+            });
+        }
+        catch (error) {
+            if (missed)
+                this.throttle.recordMiss(principal.userId);
+            throw error;
+        }
+        if (outcome.changed) {
+            this.effects.grantCommitted([
+                { name: outcome.inserted ? events_1.SHARING_EVENTS.GRANT_CREATED : events_1.SHARING_EVENTS.GRANT_UPDATED, payload: eventPayload(outcome.row, outcome.previousRole, principal.userId) },
+            ]);
+        }
+        if (outcome.notify)
+            this.effects.notifySharedWithYou(outcome.row.granteeUserId, outcome.notify, outcome.row.id);
+        return (await this.describeGrantees({ items: [toGrantDto(outcome.row)] })).items[0];
+    }
+    /**
+     * 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.
+     */
+    async resolveCustomGrantee(kind, input) {
+        const def = (0, grantee_kinds_1.findGranteeKind)(kind);
+        if (!def)
+            throw (0, errors_1.granteeKindUnknown)(kind);
+        if (grantee_kinds_1.BUILTIN_GRANTEE_KIND_IDS.includes(def.kind))
+            throw (0, errors_1.granteeInvalid)(kind, 'Use the grantee shape of the built-in kind');
+        let ref;
+        try {
+            ref = (await def.validateGrantee(input)).id;
+        }
+        catch (error) {
+            // Only a message the kind wrote for people is shown; any other error is the app's internals.
+            throw (0, errors_1.granteeInvalid)(kind, error instanceof grantee_kinds_1.GranteeInputError && error.message ? error.message : 'That grantee is not valid');
+        }
+        if (def.persisted !== true)
+            throw (0, errors_1.granteeKindNotPersistable)(kind);
+        if (typeof ref !== 'string' || ref.length === 0 || ref.length > sharing_1.SHARING_LIMITS.granteeRefMax || ref.includes('\u0000')) {
+            throw (0, errors_1.granteeInvalid)(kind, 'That grantee is not valid');
+        }
+        return { def, ref };
+    }
+    /**
+     * 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`.
+     */
+    async describeGrantees(page) {
+        const items = await Promise.all(page.items.map(async (item) => {
+            const { kind, ref } = item.grantee;
+            if (ref === null || grantee_kinds_1.BUILTIN_GRANTEE_KIND_IDS.includes(kind))
+                return item;
+            const def = (0, grantee_kinds_1.findGranteeKind)(kind);
+            if (!def)
+                return item;
+            try {
+                const display = (await def.describe({ kind, id: ref })).display;
+                return typeof display === 'string' ? { ...item, grantee: { ...item.grantee, display: display.slice(0, sharing_1.SHARING_LIMITS.granteeRefMax) } } : item;
+            }
+            catch {
+                return item;
+            }
+        }));
+        return { ...page, items };
+    }
+    /** `INSERT ... ON CONFLICT` on the partial unique index of the grantee's kind. */
+    upsert(tx, g) {
+        // The RETURNING sub-selects read the statement's snapshot: the row as it
+        // was BEFORE this statement updated it (NULL for a row a concurrent
+        // transaction inserted after our snapshot).
+        if (g.kind === 'user') {
+            return tx.$queryRaw `
+        INSERT INTO grants (id, org_id, resource_type, resource_id, grantee_kind, grantee_user_id, role, expires_at, granted_by_id, created_at, updated_at)
+        VALUES (gen_random_uuid(), ${g.orgId}::uuid, ${g.type}, ${g.resourceId}::uuid, 'user', ${g.granteeId}::uuid, ${g.role}, ${g.expiresAt}::timestamptz, ${g.actorUserId}::uuid, now(), now())
+        ON CONFLICT (resource_type, resource_id, grantee_user_id) WHERE grantee_kind = 'user' AND revoked_at IS NULL
+        DO UPDATE SET role = EXCLUDED.role, expires_at = EXCLUDED.expires_at, updated_at = now()
+        RETURNING id::text AS id, (xmax = 0) AS inserted,
+          (SELECT p.role FROM grants p WHERE p.id = grants.id) AS previous_role,
+          (SELECT p.expires_at FROM grants p WHERE p.id = grants.id) AS previous_expires_at`;
+        }
+        if (g.kind !== 'group') {
+            // An app kind: the kind and the reference are bind parameters, the org is the caller's, and the CHECK
+            // `grants_grantee_consistency_check` refuses a built-in kind id here (it needs its own columns).
+            return tx.$queryRaw `
+        INSERT INTO grants (id, org_id, resource_type, resource_id, grantee_kind, grantee_ref, role, expires_at, granted_by_id, created_at, updated_at)
+        VALUES (gen_random_uuid(), ${g.orgId}::uuid, ${g.type}, ${g.resourceId}::uuid, ${g.kind}, ${g.granteeId}, ${g.role}, ${g.expiresAt}::timestamptz, ${g.actorUserId}::uuid, now(), now())
+        ON CONFLICT (resource_type, resource_id, grantee_kind, grantee_ref) WHERE grantee_kind NOT IN ('user', 'group', 'link') AND revoked_at IS NULL
+        DO UPDATE SET role = EXCLUDED.role, expires_at = EXCLUDED.expires_at, updated_at = now()
+        RETURNING id::text AS id, (xmax = 0) AS inserted,
+          (SELECT p.role FROM grants p WHERE p.id = grants.id) AS previous_role,
+          (SELECT p.expires_at FROM grants p WHERE p.id = grants.id) AS previous_expires_at`;
+        }
+        return tx.$queryRaw `
+      INSERT INTO grants (id, org_id, resource_type, resource_id, grantee_kind, grantee_group_id, role, expires_at, granted_by_id, created_at, updated_at)
+      VALUES (gen_random_uuid(), ${g.orgId}::uuid, ${g.type}, ${g.resourceId}::uuid, 'group', ${g.granteeId}::uuid, ${g.role}, ${g.expiresAt}::timestamptz, ${g.actorUserId}::uuid, now(), now())
+      ON CONFLICT (resource_type, resource_id, grantee_group_id) WHERE grantee_kind = 'group' AND revoked_at IS NULL
+      DO UPDATE SET role = EXCLUDED.role, expires_at = EXCLUDED.expires_at, updated_at = now()
+      RETURNING id::text AS id, (xmax = 0) AS inserted,
+        (SELECT p.role FROM grants p WHERE p.id = grants.id) AS previous_role,
+        (SELECT p.expires_at FROM grants p WHERE p.id = grants.id) AS previous_expires_at`;
+    }
+    /**
+     * 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.
+     */
+    async manageable(raw, principal, orgId, grantId, self) {
+        const tx = (0, sharing_tx_1.asSharingTx)(raw);
+        const row = await tx.grant.findFirst({
+            where: { id: grantId, orgId, revokedAt: null },
+            include: GRANTEE_COLUMNS,
+        });
+        if (!row)
+            throw (0, errors_1.grantNotFound)();
+        const rt = (0, resource_types_1.findResourceType)(row.resourceType);
+        if (!rt)
+            throw (0, errors_1.grantNotFound)();
+        if (!self(row)) {
+            const action = row.granteeKind === 'link' ? (0, link_grants_service_1.linkShareAction)(rt) : 'share';
+            try {
+                await this.policy.requireIn(raw, principal, action, { type: rt.type, id: row.resourceId });
+            }
+            catch (error) {
+                if (error instanceof common_1.NotFoundException)
+                    throw (0, errors_1.grantNotFound)();
+                throw error;
+            }
+        }
+        return { tx, row, rt };
+    }
+    /**
+     * `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.
+     */
+    async update(principal, grantId, input) {
+        const orgId = (0, group_common_1.requireActiveOrg)(principal);
+        const now = this.now();
+        // Validated before the transaction: an expiry in the past is a 400 for every kind.
+        const expiresAt = input.expiresAt === undefined ? undefined : this.expiry(input.expiresAt);
+        const outcome = await this.data.runInOrg({ orgId, userId: principal.userId }, async (raw) => {
+            const { tx, row, rt } = await this.manageable(raw, principal, orgId, grantId, () => false);
+            const isLink = row.granteeKind === 'link';
+            if (input.label !== undefined && !isLink)
+                throw (0, errors_1.notALinkGrant)();
+            if (input.role !== undefined) {
+                const grantable = rt.grantable(row.granteeKind);
+                if (!grantable.includes(input.role))
+                    throw (0, errors_1.roleNotGrantable)(input.role, row.granteeKind, grantable);
+            }
+            const data = {};
+            if (input.role !== undefined)
+                data.role = input.role;
+            // A link's expiry is capped by the deployment's maximum link lifetime (#730).
+            if (expiresAt !== undefined)
+                data.expiresAt = isLink ? (0, link_grants_service_1.resolveLinkExpiry)(input.expiresAt, this.linkTtl, now, 'update') : expiresAt;
+            if (input.label !== undefined)
+                data.linkLabel = input.label;
+            const updated = await tx.grant.update({ where: { id: row.id }, data, include: GRANTEE_COLUMNS });
+            const roleChanged = updated.role !== row.role;
+            const changed = roleChanged ||
+                (updated.expiresAt?.getTime() ?? null) !== (row.expiresAt?.getTime() ?? null) ||
+                (isLink && updated.linkLabel !== row.linkLabel);
+            if (changed && isLink) {
+                await (0, link_grants_service_1.writeLinkAudit)(tx, { orgId, actorUserId: principal.userId, action: 'grant:link:update', row: updated, previousRole: row.role });
+            }
+            else if (changed) {
+                await this.audit(tx, { orgId, actorUserId: principal.userId, action: 'grant:update', row: updated, previousRole: row.role });
+            }
+            const notify = updated.granteeKind === 'user' && roleChanged ? await this.notificationData(raw, rt, updated, row.role, principal.userId) : null;
+            return { row: updated, previousRole: row.role, changed, notify };
+        });
+        if (outcome.changed) {
+            const payload = outcome.row.granteeKind === 'link'
+                ? (0, link_grants_service_1.linkEventPayload)(outcome.row, outcome.previousRole, principal.userId)
+                : eventPayload(outcome.row, outcome.previousRole, principal.userId);
+            this.effects.grantCommitted([{ name: events_1.SHARING_EVENTS.GRANT_UPDATED, payload }]);
+        }
+        if (outcome.notify)
+            this.effects.notifySharedWithYou(outcome.row.granteeUserId, outcome.notify, outcome.row.id);
+        return (await this.describeGrantees({ items: [toGrantDto(outcome.row)] })).items[0];
+    }
+    /**
+     * `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.
+     */
+    async revoke(principal, grantId) {
+        const orgId = (0, group_common_1.requireActiveOrg)(principal);
+        const isSelf = (row) => row.granteeKind === 'user' && row.granteeUserId === principal.userId;
+        const canWrite = (0, group_common_1.holds)(principal, permissions_1.SHARING_PERMISSIONS.SHARING_WRITE);
+        const revoked = await this.data.runInOrg({ orgId, userId: principal.userId }, async (raw) => {
+            const { tx, row } = await this.manageable(raw, principal, orgId, grantId, (candidate) => {
+                if (isSelf(candidate))
+                    return true;
+                // Without sharing:write nobody else's grant is manageable: the same 404 as a missing one.
+                if (!canWrite)
+                    throw (0, errors_1.grantNotFound)();
+                return false;
+            });
+            const updated = await tx.grant.update({
+                where: { id: row.id },
+                data: { revokedAt: new Date(this.now()), revokedById: principal.userId },
+                include: GRANTEE_COLUMNS,
+            });
+            if (updated.granteeKind === 'link') {
+                await (0, link_grants_service_1.writeLinkAudit)(tx, { orgId, actorUserId: principal.userId, action: 'grant:link:revoke', row: updated, previousRole: row.role });
+            }
+            else {
+                await this.audit(tx, { orgId, actorUserId: principal.userId, action: 'grant:revoke', row: updated, previousRole: row.role });
+            }
+            return updated;
+        });
+        this.effects.grantCommitted([{ name: events_1.SHARING_EVENTS.GRANT_REVOKED, payload: eventPayload(revoked, revoked.role, principal.userId) }]);
+    }
+    /**
+     * `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.
+     */
+    async sharedWithMe(principal, query) {
+        const orgId = (0, group_common_1.requireActiveOrg)(principal);
+        const types = query.resourceType ? ((0, resource_types_1.findResourceType)(query.resourceType) ? [query.resourceType] : []) : resource_types_1.resourceTypeRegistry.ids();
+        if (types.length === 0)
+            return (0, group_common_1.paged)([], 0, query.page, query.pageSize);
+        // Who the caller is, by every persisted kind: the built-ins and any app kind (each pinned to its own kind).
+        const subject = (0, grantee_kinds_1.withGroups)(principal, await this.principalGroups.groupsFor(principal));
+        const grantees = (0, grantee_kinds_1.persistedGranteeKinds)().flatMap((def) => {
+            const named = (0, grantee_kinds_1.granteeWhereFor)(def, subject);
+            return named === null ? [] : [named];
+        });
+        const where = {
+            orgId,
+            resourceType: { in: types },
+            revokedAt: null,
+            AND: [
+                { OR: [{ expiresAt: null }, { expiresAt: { gt: new Date(this.now()) } }] },
+                { OR: grantees },
+            ],
+        };
+        return this.data.runInOrg({ orgId, userId: principal.userId }, async (raw) => {
+            const tx = (0, sharing_tx_1.asSharingTx)(raw);
+            const total = await tx.grant.count({ where });
+            const rows = await tx.grant.findMany({
+                where,
+                orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+                skip: (query.page - 1) * query.pageSize,
+                take: query.pageSize,
+            });
+            const labels = new Map();
+            for (const type of new Set(rows.map((row) => row.resourceType))) {
+                const rt = (0, resource_types_1.findResourceType)(type);
+                if (!rt?.def.describe)
+                    continue;
+                const ids = [...new Set(rows.filter((row) => row.resourceType === type).map((row) => row.resourceId))];
+                for (const [id, label] of await rt.def.describe(ids, raw))
+                    labels.set(`${type}:${id}`, label);
+            }
+            const items = rows.map((row) => {
+                const label = labels.get(`${row.resourceType}:${row.resourceId}`);
+                return {
+                    grantId: row.id,
+                    resourceType: row.resourceType,
+                    resourceId: row.resourceId,
+                    role: row.role,
+                    via: viaOf(row.granteeKind),
+                    groupId: row.granteeGroupId,
+                    title: label?.title ?? null,
+                    path: label?.path ?? null,
+                    grantedById: row.grantedById,
+                    expiresAt: (0, group_common_1.iso)(row.expiresAt),
+                    createdAt: (0, group_common_1.iso)(row.createdAt),
+                };
+            });
+            return (0, group_common_1.paged)(items, total, query.page, query.pageSize);
+        });
+    }
+    /** Writes one audit row INSIDE the caller's transaction: ids and roles only, never an address. */
+    async audit(tx, input) {
+        const { row } = input;
+        await tx.auditEvent.create({
+            data: {
+                actorUserId: input.actorUserId,
+                action: input.action,
+                targetType: 'grant',
+                targetId: row.id,
+                orgId: input.orgId,
+                meta: {
+                    resourceType: row.resourceType,
+                    resourceId: row.resourceId,
+                    granteeKind: row.granteeKind,
+                    granteeId: row.granteeUserId ?? row.granteeGroupId ?? row.granteeRef ?? null,
+                    role: row.role,
+                    previousRole: input.previousRole,
+                },
+            },
+        });
+    }
+    /** The `sharing.shared_with_you` data, read inside the transaction (labels and the sharer's name). */
+    async notificationData(raw, rt, row, previousRole, actorUserId) {
+        const tx = (0, sharing_tx_1.asSharingTx)(raw);
+        const label = rt.def.describe ? (await rt.def.describe([row.resourceId], raw)).get(row.resourceId) : undefined;
+        const actor = await tx.user.findUnique({
+            where: { id: actorUserId },
+            select: { email: true, displayName: true, providerDisplayName: true },
+        });
+        return {
+            resourceType: row.resourceType,
+            resourceId: row.resourceId,
+            role: row.role,
+            ...(previousRole !== null ? { previousRole } : {}),
+            ...(label ? { title: label.title, ...(label.path ? { path: label.path } : {}) } : {}),
+            ...(actor ? { sharedBy: actor.displayName ?? actor.providerDisplayName ?? actor.email } : {}),
+            ...(row.expiresAt ? { expiresAt: row.expiresAt.toISOString() } : {}),
+        };
+    }
+};
+exports.GrantsService = GrantsService;
+__decorate([
+    (0, index_1.Trace)('sharing.grant.list'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], GrantsService.prototype, "list", null);
+__decorate([
+    (0, index_1.Trace)('sharing.grant.create'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], GrantsService.prototype, "create", null);
+__decorate([
+    (0, index_1.Trace)('sharing.grant.update'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], GrantsService.prototype, "update", null);
+__decorate([
+    (0, index_1.Trace)('sharing.grant.revoke'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], GrantsService.prototype, "revoke", null);
+__decorate([
+    (0, index_1.Trace)('sharing.grant.shared_with_me'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], GrantsService.prototype, "sharedWithMe", null);
+exports.GrantsService = GrantsService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(ports_1.SHARING_DATA)),
+    __param(5, (0, common_1.Optional)()),
+    __param(5, (0, common_1.Inject)(exports.GRANTS_CLOCK)),
+    __param(6, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Inject)(sharing_options_1.SHARING_OPTIONS)),
+    __metadata("design:paramtypes", [Object, access_policy_service_1.AccessPolicy,
+        principal_groups_provider_1.PrincipalGroupsProvider,
+        member_lookup_throttle_1.MemberLookupThrottle,
+        sharing_effects_1.SharingEffects, Function, Object])
+], GrantsService);
+/** What a "shared with me" item reports as `via`: the registered kind's own, `<kind>_grant` for a kind that left the registry. */
+function viaOf(kind) {
+    const def = (0, grantee_kinds_1.findGranteeKind)(kind);
+    return def ? (0, grantee_kinds_1.granteeKindVia)(def) : `${kind.replace(/-/g, '_')}_grant`;
+}
+/** The event payload of a grant: ids and roles only. */
+function eventPayload(row, previousRole, actorUserId) {
+    return {
+        orgId: row.orgId,
+        grantId: row.id,
+        resourceType: row.resourceType,
+        resourceId: row.resourceId,
+        granteeKind: row.granteeKind,
+        granteeId: row.granteeUserId ?? row.granteeGroupId ?? row.granteeRef ?? null,
+        role: row.role,
+        previousRole,
+        actorUserId,
+    };
+}
+//# sourceMappingURL=grants.service.js.map