@astram/identity 0.1.1 → 0.2.0

package/dist/features/cross-tenant/cross-tenant-grant-read.service.js

@@ -0,0 +1,276 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossTenantGrantReadService = void 0;
+// packages/identity/src/features/cross-tenant/cross-tenant-grant-read.service.ts
+/**
+ * CrossTenantGrantReadService — the read side of the cross-tenant grant UI,
+ * backing the inbox / mine / incoming / offerable-types surfaces the controller
+ * exposes. Built over the shared `authzPool` (a `useValue` provider — the mariadb
+ * Pool is NOT a Nest provider in this app, matching the non-DI adapter pattern the
+ * IdentityFeatureModule already uses for its audit/grant-admin stacks), never
+ * through the RecordEngine pipe (`cross_tenant_grant` is a framework-owned table,
+ * not a registered object type resolved via the engine).
+ *
+ * ⛔ TENANT SCOPING (the list-leak class of bug): `listInbox`/`listMine`/
+ * `listIncoming` all take `tenantId` from the CALLER (the controller passes
+ * `req.principal.tenantId` — never a query/body value) and filter ON it in the SQL
+ * WHERE clause. A tenant-A caller can never see tenant-B's grants through these reads,
+ * regardless of what a client might try to pass.
+ *
+ * ⛔ NO RAW UUIDS: every row is resolved via LEFT JOINs to `companies`/`users`/`roles`
+ * (COALESCE to a `'Deleted …'` fallback for an orphaned reference) — the uuid columns
+ * ride in the row ONLY as API keys (`uuid`, `granteeUuid` are never rendered directly;
+ * the UI shows `*Name`/`*Label` fields). `ctg_allowed_actions` is parsed defensively:
+ * the mariadb driver auto-parses the JSON column to a JS array in production, but a
+ * string is accepted too (the writer/adapter lesson — never a bare `JSON.parse` that
+ * assumes one shape).
+ */
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const AUTHZ = 'shield_authz';
+const APP = 'shield_app';
+/**
+ * Parse `ctg_allowed_actions` to a `string[]`, accepting BOTH an already-parsed array
+ * (production — the mariadb driver auto-parses the JSON column) and a JSON string
+ * (test doubles / a raw driver mode). Anything else/malformed -> `[]` (fail-closed,
+ * never throws on a malformed cell). Mirrors the writer's `parseCeiling` in
+ * `@astram/guard`'s cross-tenant-grant-writer (the ceiling-parse lesson).
+ */
+function parseAllowedActions(raw) {
+    if (Array.isArray(raw)) {
+        return raw.filter((a) => typeof a === 'string');
+    }
+    if (typeof raw === 'string' && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return parsed.filter((a) => typeof a === 'string');
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+/** The grantee's resolved display name: the matching user/role LEFT JOIN, else a fallback. */
+function granteeName(row) {
+    const name = row.ctg_grantee_kind === 'role' ? row.grantee_role_name : row.grantee_user_name;
+    return name ?? 'Deleted grantee';
+}
+function granteeKind(row) {
+    return row.ctg_grantee_kind === 'role' ? 'role' : 'user';
+}
+/**
+ * Epoch-ms comes back from the BIGINT column as a JS `bigint` (the mariadb driver's default
+ * for BIGINT), or occasionally a `string`/`number`. Normalize ALL three to a plain `number` —
+ * crucially a `bigint` must be coerced, or it reaches `JSON.stringify` (in the HTTP response
+ * serializer) and throws `TypeError: Do not know how to serialize a BigInt` (a 500). `Number()`
+ * handles bigint | string | number uniformly; epoch-ms is well within `Number.MAX_SAFE_INTEGER`.
+ */
+function expiresAtMs(raw) {
+    return Number(raw);
+}
+/** The columns + JOINs shared by every list read (only the WHERE differs per method). */
+const SELECT_COLUMNS = `
+  ctg.ctg_uuid,
+  ctg.ctg_owning_tenant_uuid,
+  owner_co.c_name AS owning_tenant_name,
+  ctg.ctg_grantee_tenant_uuid,
+  grantee_co.c_name AS grantee_tenant_name,
+  ctg.ctg_grantee_kind,
+  ctg.ctg_grantee_uuid,
+  gu.u_username AS grantee_user_name,
+  gr.r_name AS grantee_role_name,
+  ctg.ctg_type_key,
+  ctg.ctg_scope,
+  ctg.ctg_allowed_actions,
+  ctg.ctg_status,
+  ctg.ctg_offered_by,
+  offerer.u_username AS offered_by_name,
+  ctg.ctg_expires_at_ms,
+  ctg.ctg_created_at
+`;
+const JOINS = `
+  FROM \`${AUTHZ}\`.\`cross_tenant_grant\` ctg
+  LEFT JOIN \`${APP}\`.\`companies\` owner_co ON owner_co.c_uuid = ctg.ctg_owning_tenant_uuid
+  LEFT JOIN \`${APP}\`.\`companies\` grantee_co ON grantee_co.c_uuid = ctg.ctg_grantee_tenant_uuid
+  LEFT JOIN \`${APP}\`.\`users\` gu ON ctg.ctg_grantee_kind = 'user' AND gu.u_uuid = ctg.ctg_grantee_uuid
+  LEFT JOIN \`${APP}\`.\`roles\` gr ON ctg.ctg_grantee_kind = 'role' AND gr.r_uuid = ctg.ctg_grantee_uuid
+  LEFT JOIN \`${APP}\`.\`users\` offerer ON offerer.u_uuid = ctg.ctg_offered_by
+`;
+let CrossTenantGrantReadService = class CrossTenantGrantReadService {
+    pool;
+    offerableTypeInputs;
+    actionsByType;
+    /**
+     * @param pool the shared resolver pool.
+     * @param offerableTypeInputs the ENGINE registrations to filter to `access.tenantScoped
+     *   === true` types for the offer form's picker (decision 1). Passed in (not imported
+     *   directly) so this service stays a plain constructor-arg class like its siblings —
+     *   the module supplies the same merged `[...identityObjects]` set the share-type
+     *   surface uses, so a future tenantScoped type is picked up the same way it becomes
+     *   shareable.
+     * @param actionsByType per-typeKey action vocabulary for the offerable-types read
+     *   (decision 1: "the actions per type come from the type's own action set"). Callers
+     *   pass `actionsFor`, which defaults every type to the CRUD `IDENTITY_ACTIONS` except
+     *   a type with its own override (e.g. `cross_tenant_grant` -> share/accept/revoke) —
+     *   the single source every action-vocabulary consumer uses, so a per-type set can
+     *   never drift between callers.
+     */
+    constructor(pool, offerableTypeInputs, actionsByType) {
+        this.pool = pool;
+        this.offerableTypeInputs = offerableTypeInputs;
+        this.actionsByType = actionsByType;
+    }
+    /**
+     * Pending offers sitting in the CALLER's tenant inbox: `ctg_grantee_tenant_uuid =
+     * tenantId AND ctg_status = 'offered' AND ctg_expires_at_ms > nowMs` (an expired
+     * offer is dead — never surfaced as actionable, mirroring the writer's own active-
+     * grant filter). Ordered soonest-expiring first (most urgent to act on).
+     */
+    async listInbox(tenantId, nowMs) {
+        if (!tenantId)
+            return [];
+        const rows = (await this.pool.query(`SELECT ${SELECT_COLUMNS}
+       ${JOINS}
+       WHERE ctg.ctg_grantee_tenant_uuid = ?
+         AND ctg.ctg_status = 'offered'
+         AND ctg.ctg_expires_at_ms > ?
+       ORDER BY ctg.ctg_expires_at_ms ASC`, [tenantId, nowMs]));
+        return rows.map((row) => ({
+            uuid: row.ctg_uuid,
+            owningTenantName: row.owning_tenant_name ?? 'Deleted tenant',
+            granteeKind: granteeKind(row),
+            granteeName: granteeName(row),
+            typeKey: row.ctg_type_key,
+            typeLabel: row.ctg_type_key,
+            scope: row.ctg_scope,
+            allowedActions: parseAllowedActions(row.ctg_allowed_actions),
+            offeredByName: row.offered_by_name ?? 'Deleted user',
+            expiresAtMs: expiresAtMs(row.ctg_expires_at_ms),
+        }));
+    }
+    /**
+     * Every grant MY tenant OWNS (`ctg_owning_tenant_uuid = tenantId`), ANY status — the
+     * "outgoing" list (what I've offered, whether still pending, accepted, or revoked).
+     * Ordered most-recently-offered first (`ctg_created_at DESC`) — the natural order
+     * for "what have I done lately" on an owner's own outgoing list.
+     */
+    async listMine(tenantId) {
+        if (!tenantId)
+            return [];
+        const rows = (await this.pool.query(`SELECT ${SELECT_COLUMNS}
+       ${JOINS}
+       WHERE ctg.ctg_owning_tenant_uuid = ?
+       ORDER BY ctg.ctg_created_at DESC`, [tenantId]));
+        return rows.map((row) => ({
+            uuid: row.ctg_uuid,
+            granteeTenantName: row.grantee_tenant_name ?? 'Deleted tenant',
+            granteeKind: granteeKind(row),
+            granteeName: granteeName(row),
+            typeKey: row.ctg_type_key,
+            typeLabel: row.ctg_type_key,
+            scope: row.ctg_scope,
+            allowedActions: parseAllowedActions(row.ctg_allowed_actions),
+            status: row.ctg_status,
+            offeredByName: row.offered_by_name ?? 'Deleted user',
+            expiresAtMs: expiresAtMs(row.ctg_expires_at_ms),
+        }));
+    }
+    /**
+     * Grants ACCEPTED into my tenant (`ctg_grantee_tenant_uuid = tenantId AND ctg_status
+     * = 'accepted'`) — the "incoming" (currently-active reach-in) list, distinct from the
+     * pending inbox. Includes grants whose expiry has since passed (this reports status as
+     * stored — `CrossTenantGrantPort.findActiveGrant` is the ACTUAL enforcement of
+     * liveness; this is a read-model list, not a re-implementation of that check), so the
+     * UI can show "expired" via `expiresAtMs` if desired. Ordered soonest-expiring first.
+     */
+    async listIncoming(tenantId) {
+        if (!tenantId)
+            return [];
+        const rows = (await this.pool.query(`SELECT ${SELECT_COLUMNS}
+       ${JOINS}
+       WHERE ctg.ctg_grantee_tenant_uuid = ?
+         AND ctg.ctg_status = 'accepted'
+       ORDER BY ctg.ctg_expires_at_ms ASC`, [tenantId]));
+        return rows.map((row) => ({
+            uuid: row.ctg_uuid,
+            owningTenantName: row.owning_tenant_name ?? 'Deleted tenant',
+            granteeKind: granteeKind(row),
+            granteeName: granteeName(row),
+            typeKey: row.ctg_type_key,
+            typeLabel: row.ctg_type_key,
+            scope: row.ctg_scope,
+            allowedActions: parseAllowedActions(row.ctg_allowed_actions),
+            offeredByName: row.offered_by_name ?? 'Deleted user',
+            expiresAtMs: expiresAtMs(row.ctg_expires_at_ms),
+        }));
+    }
+    /**
+     * The ONE source of truth for "which typeKeys are offerable across tenants" (decision
+     * 1: `access.tenantScoped === true`). Reflects the SAME engine registrations the
+     * share surface merges (`[...identityObjects]`, passed in by the module) and returns
+     * the set of tenantScoped typeKeys. Both the picker read (`listOfferableTypes`) AND the
+     * offer-endpoint guard (`isOfferableType`) derive from this — so there is no way for
+     * the two to drift (a system type can never be BOTH shown in the picker AND accepted
+     * by the offer endpoint, or neither).
+     */
+    offerableTypeKeys() {
+        const keys = new Set();
+        for (const input of this.offerableTypeInputs) {
+            const reg = typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
+            if (reg.access?.tenantScoped === true)
+                keys.add(reg.typeKey); // decision 1: tenantScoped ONLY
+        }
+        return keys;
+    }
+    /**
+     * Is `typeKey` offerable across tenants (i.e. a registered tenantScoped type)? The
+     * offer controller calls this BEFORE `writer.offer()` so an un-offerable typeKey (any
+     * `system` type — e.g. `company`) is rejected with a 400 before any row is written.
+     *
+     * This closes the H3 defense-in-depth gap: the writer's `assertValidOffer` only checks
+     * `typeKey` is a non-empty string, so without this guard a legit own-tenant admin could
+     * mint a junk `offered` grant row for a `system` type. It's inert at evaluation TODAY
+     * only because no type is both `system` AND `tenantScoped` (system types have no
+     * `trusted:'tenantId'`, so the tenant gate never consults a cross-tenant grant for
+     * them) — but that safety is a coincidence, not an explicit rule. This makes it
+     * explicit, using the SAME tenantScoped filter as the picker (`offerableTypeKeys`).
+     */
+    isOfferableType(typeKey) {
+        return this.offerableTypeKeys().has(typeKey);
+    }
+    /**
+     * The object-type picker source for the offer form (decision 1): the tenantScoped
+     * registered types (from `offerableTypeKeys` — the same source `isOfferableType`
+     * uses) paired with each type's action vocabulary. No DB query — pure in-memory
+     * reflection, wrapped in a resolved promise so the controller's read-surface shape is
+     * uniform. The identity types are all `system` and are excluded by construction —
+     * only a tenantScoped type (e.g. `shared_resource`) qualifies.
+     */
+    async listOfferableTypes() {
+        const out = [];
+        for (const typeKey of this.offerableTypeKeys()) {
+            out.push({
+                typeKey,
+                label: typeKey, // no separate label registry today — mirrors the module-registry `label: r.typeKey`
+                actions: [...this.actionsByType(typeKey)],
+            });
+        }
+        return out;
+    }
+};
+exports.CrossTenantGrantReadService = CrossTenantGrantReadService;
+exports.CrossTenantGrantReadService = CrossTenantGrantReadService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Array, Function])
+], CrossTenantGrantReadService);

package/dist/features/cross-tenant/cross-tenant-grant.controller.d.ts

@@ -0,0 +1,65 @@
+import { CrossTenantGrantWriter } from '@astram/guard';
+import type { Principal } from '@astram/engine';
+import { CrossTenantGrantReadService } from './cross-tenant-grant-read.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal. */
+interface AuthedRequest {
+    principal: Principal;
+}
+/** The offer request body — grantee + type + ceiling + expiry ONLY (never authority fields). */
+interface OfferGrantBodyDto {
+    granteeTenantId?: string;
+    granteeKind?: string;
+    granteeUuid?: string;
+    typeKey?: string;
+    allowedActions?: unknown;
+    expiresAtMs?: unknown;
+}
+export declare class CrossTenantGrantController {
+    private readonly grantWriter;
+    private readonly reads;
+    constructor(grantWriter: CrossTenantGrantWriter, reads: CrossTenantGrantReadService);
+    /**
+     * Offer a cross-tenant grant. `owningTenantId`/`offeredBy` come ONLY from the
+     * authenticated principal; the body supplies the grantee + type + ceiling + expiry.
+     * `scope` is hard-coded 'object_type' (decision 4) — no recordId accepted in v1.
+     */
+    offer(req: AuthedRequest, body: OfferGrantBodyDto): Promise<{
+        success: boolean;
+        uuid: string;
+    }>;
+    /** Accept an offered grant. `acceptedBy` comes ONLY from the authenticated principal. */
+    accept(req: AuthedRequest, uuid: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Revoke a grant. `revokedBy` comes ONLY from the authenticated principal. Either the
+     * owning-tenant admin OR a grantee-tenant member may call this (the writer decides) —
+     * the grantee side calling this on an `offered` grant IS the "Decline" action; no
+     * separate endpoint or status exists for decline.
+     */
+    revoke(req: AuthedRequest, uuid: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * The caller's tenant's pending-offers inbox. Scoped to `req.principal.tenantId` —
+     * NEVER a query param — so a caller only ever sees offers made TO their own tenant.
+     */
+    inbox(req: AuthedRequest): Promise<{
+        rows: import("./cross-tenant-grant-read.service.js").InboxGrantRow[];
+    }>;
+    /**
+     * The caller's tenant's grant book: `mine` (grants my tenant OWNS, any status — the
+     * outgoing list) + `incoming` (grants ACCEPTED into my tenant — distinct from the
+     * pending inbox). Both scoped to `req.principal.tenantId` server-side.
+     */
+    list(req: AuthedRequest): Promise<{
+        rows: import("./cross-tenant-grant-read.service.js").MineGrantRow[];
+        incoming: import("./cross-tenant-grant-read.service.js").IncomingGrantRow[];
+    }>;
+    /** The tenantScoped object types (+ their actions) the offer form's picker may show. */
+    offerableTypes(): Promise<{
+        types: import("./cross-tenant-grant-read.service.js").OfferableTypeRow[];
+    }>;
+}
+export {};
+//# sourceMappingURL=cross-tenant-grant.controller.d.ts.map

package/dist/features/cross-tenant/cross-tenant-grant.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-tenant-grant.controller.d.ts","sourceRoot":"","sources":["../../../src/features/cross-tenant/cross-tenant-grant.controller.ts"],"names":[],"mappings":"AA4CA,OAAO,EAGL,sBAAsB,EAKvB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAEnF,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,gGAAgG;AAChG,UAAU,iBAAiB;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAmDD,qBACa,0BAA0B;IAEO,OAAO,CAAC,QAAQ,CAAC,WAAW;IACtE,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADqC,WAAW,EAAE,sBAAsB,EAC7E,KAAK,EAAE,2BAA2B;IAGrD;;;;OAIG;IAGG,KAAK,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,iBAAiB;;;;IA+BtE,yFAAyF;IAGnF,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM;;;IASnE;;;;;OAKG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM;;;IASnE;;;OAGG;IAGG,KAAK,CAAQ,GAAG,EAAE,aAAa;;;IAKrC;;;;OAIG;IAGG,IAAI,CAAQ,GAAG,EAAE,aAAa;;;;IAQpC,wFAAwF;IAGlF,cAAc;;;CAIrB"}

package/dist/features/cross-tenant/cross-tenant-grant.controller.js

@@ -0,0 +1,250 @@
+"use strict";
+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.CrossTenantGrantController = void 0;
+// packages/identity/src/features/cross-tenant/cross-tenant-grant.controller.ts
+/**
+ * CrossTenantGrantController — the HTTP surface over the framework-owned
+ * `CrossTenantGrantWriter` (ADR-0009, Phase 4) + `CrossTenantGrantReadService` (Phase
+ * C). Mirrors `notes/share.controller.ts`'s shape (principal-derived authority body
+ * fields + a `mapGrantError` twin of `mapShareError`).
+ *
+ * Gated on the dedicated `cross_tenant_grant` object type's own action vocabulary
+ * (`share`/`accept`/`revoke` — `features/authz/actions.ts`'s `CROSS_TENANT_GRANT_ACTIONS`),
+ * NOT the identity CRUD verbs: `@Classified({ typeKey:'cross_tenant_grant', action:'share'|
+ * 'accept'|'revoke' })`. This is the SAME permission key the writer's `authorize` closure
+ * checks via `decide()`, so the route guard and the writer agree on exactly one gate — no
+ * bespoke admin notion (the deleted `DbGrantAuthorityResolver`/`COMPANY_ADMIN_KEYS`)
+ * survives anywhere in this path.
+ *
+ * ⛔ AUTHORITY FIELDS COME ONLY FROM `req.principal` — NEVER a body field:
+ *   - offer:   owningTenantId = req.principal.tenantId, offeredBy = req.principal.id
+ *   - accept:  acceptedBy     = req.principal.id
+ *   - revoke:  revokedBy      = req.principal.id
+ * The writer independently re-verifies the real authority (via `decide()`) server-side
+ * regardless of what the controller passes — but the controller itself must never even
+ * READ an authority field from the body, so a malicious body can't influence which
+ * tenant/actor is being checked.
+ *
+ * ⛔ SCOPE IS HARD-CODED 'object_type' IN V1 (decision 4) — the offer body carries no
+ * `recordId`/`scope` field; the controller always passes `scope: 'object_type'` to the
+ * writer. Record-scoped grants are a writer capability the UI does not expose yet.
+ *
+ * Decline (grantee side) = the grantee tenant calling `revoke` on an `offered` grant —
+ * the writer already permits either side to revoke an offered grant (no new status, no
+ * writer change).
+ */
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const cross_tenant_grant_read_service_js_1 = require("./cross-tenant-grant-read.service.js");
+const VALID_GRANTEE_KINDS = ['user', 'role'];
+/** Validate + narrow the offer body, throwing 400 on any missing/malformed field. */
+function parseOfferBody(body) {
+    const granteeTenantId = body?.granteeTenantId;
+    if (typeof granteeTenantId !== 'string' || granteeTenantId.length === 0) {
+        throw new common_1.BadRequestException('granteeTenantId is required');
+    }
+    const granteeKind = body?.granteeKind;
+    if (!VALID_GRANTEE_KINDS.includes(granteeKind)) {
+        throw new common_1.BadRequestException("granteeKind must be 'user' or 'role'");
+    }
+    const granteeUuid = body?.granteeUuid;
+    if (typeof granteeUuid !== 'string' || granteeUuid.length === 0) {
+        throw new common_1.BadRequestException('granteeUuid is required');
+    }
+    const typeKey = body?.typeKey;
+    if (typeof typeKey !== 'string' || typeKey.length === 0) {
+        throw new common_1.BadRequestException('typeKey is required');
+    }
+    const allowedActions = body?.allowedActions;
+    if (!Array.isArray(allowedActions) ||
+        allowedActions.length === 0 ||
+        !allowedActions.every((a) => typeof a === 'string' && a.length > 0)) {
+        throw new common_1.BadRequestException('allowedActions must be a non-empty array of action keys');
+    }
+    const expiresAtMs = body?.expiresAtMs;
+    if (typeof expiresAtMs !== 'number' || !Number.isFinite(expiresAtMs)) {
+        throw new common_1.BadRequestException('expiresAtMs is required and must be a finite epoch-ms timestamp');
+    }
+    return {
+        granteeTenantId,
+        granteeKind: granteeKind,
+        granteeUuid,
+        typeKey,
+        allowedActions: allowedActions,
+        expiresAtMs,
+    };
+}
+let CrossTenantGrantController = class CrossTenantGrantController {
+    grantWriter;
+    reads;
+    constructor(grantWriter, reads) {
+        this.grantWriter = grantWriter;
+        this.reads = reads;
+    }
+    /**
+     * Offer a cross-tenant grant. `owningTenantId`/`offeredBy` come ONLY from the
+     * authenticated principal; the body supplies the grantee + type + ceiling + expiry.
+     * `scope` is hard-coded 'object_type' (decision 4) — no recordId accepted in v1.
+     */
+    async offer(req, body) {
+        const parsed = parseOfferBody(body);
+        // H3 defense-in-depth: only a tenantScoped ("offerable") type may be granted across
+        // tenants. Reject a `system` typeKey (e.g. 'company') with 400 BEFORE the writer runs,
+        // so no junk 'offered' row is written. Uses the SAME tenantScoped filter the picker
+        // (`listOfferableTypes`) uses — one source of truth, no drift.
+        if (!this.reads.isOfferableType(parsed.typeKey)) {
+            throw new common_1.BadRequestException(`typeKey '${parsed.typeKey}' is not offerable for cross-tenant grants — ` +
+                `only tenant-scoped types can be granted across tenants`);
+        }
+        let uuid;
+        try {
+            uuid = await this.grantWriter.offer({
+                owningTenantId: req.principal.tenantId,
+                granteeTenantId: parsed.granteeTenantId,
+                granteeKind: parsed.granteeKind,
+                granteeUuid: parsed.granteeUuid,
+                typeKey: parsed.typeKey,
+                scope: 'object_type',
+                allowedActions: parsed.allowedActions,
+                expiresAtMs: parsed.expiresAtMs,
+                offeredBy: req.principal.id,
+            });
+        }
+        catch (err) {
+            throw mapGrantError(err);
+        }
+        return { success: true, uuid };
+    }
+    /** Accept an offered grant. `acceptedBy` comes ONLY from the authenticated principal. */
+    async accept(req, uuid) {
+        try {
+            await this.grantWriter.accept({ grantUuid: uuid, acceptedBy: req.principal.id });
+        }
+        catch (err) {
+            throw mapGrantError(err);
+        }
+        return { success: true };
+    }
+    /**
+     * Revoke a grant. `revokedBy` comes ONLY from the authenticated principal. Either the
+     * owning-tenant admin OR a grantee-tenant member may call this (the writer decides) —
+     * the grantee side calling this on an `offered` grant IS the "Decline" action; no
+     * separate endpoint or status exists for decline.
+     */
+    async revoke(req, uuid) {
+        try {
+            await this.grantWriter.revoke({ grantUuid: uuid, revokedBy: req.principal.id });
+        }
+        catch (err) {
+            throw mapGrantError(err);
+        }
+        return { success: true };
+    }
+    /**
+     * The caller's tenant's pending-offers inbox. Scoped to `req.principal.tenantId` —
+     * NEVER a query param — so a caller only ever sees offers made TO their own tenant.
+     */
+    async inbox(req) {
+        const rows = await this.reads.listInbox(req.principal.tenantId, Date.now());
+        return { rows };
+    }
+    /**
+     * The caller's tenant's grant book: `mine` (grants my tenant OWNS, any status — the
+     * outgoing list) + `incoming` (grants ACCEPTED into my tenant — distinct from the
+     * pending inbox). Both scoped to `req.principal.tenantId` server-side.
+     */
+    async list(req) {
+        const [mine, incoming] = await Promise.all([
+            this.reads.listMine(req.principal.tenantId),
+            this.reads.listIncoming(req.principal.tenantId),
+        ]);
+        return { rows: mine, incoming };
+    }
+    /** The tenantScoped object types (+ their actions) the offer form's picker may show. */
+    async offerableTypes() {
+        const types = await this.reads.listOfferableTypes();
+        return { types };
+    }
+};
+exports.CrossTenantGrantController = CrossTenantGrantController;
+__decorate([
+    (0, common_1.Post)('cross-tenant-grants'),
+    (0, guard_1.Classified)({ typeKey: 'cross_tenant_grant', action: 'share' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "offer", null);
+__decorate([
+    (0, common_1.Post)('cross-tenant-grants/:uuid/accept'),
+    (0, guard_1.Classified)({ typeKey: 'cross_tenant_grant', action: 'accept' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "accept", null);
+__decorate([
+    (0, common_1.Post)('cross-tenant-grants/:uuid/revoke'),
+    (0, guard_1.Classified)({ typeKey: 'cross_tenant_grant', action: 'revoke' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "revoke", null);
+__decorate([
+    (0, common_1.Get)('cross-tenant-grants/inbox'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "inbox", null);
+__decorate([
+    (0, common_1.Get)('cross-tenant-grants'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Req)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "list", null);
+__decorate([
+    (0, common_1.Get)('cross-tenant-grants/offerable-types'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], CrossTenantGrantController.prototype, "offerableTypes", null);
+exports.CrossTenantGrantController = CrossTenantGrantController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __param(0, (0, common_1.Inject)(guard_1.SHIELD_CROSS_TENANT_GRANT_WRITER)),
+    __metadata("design:paramtypes", [guard_1.CrossTenantGrantWriter,
+        cross_tenant_grant_read_service_js_1.CrossTenantGrantReadService])
+], CrossTenantGrantController);
+/**
+ * Map the writer's typed errors to HTTP (mirrors `share.controller.ts`'s
+ * `mapShareError`): not-permitted -> 403, invalid input -> 400, store outage -> 503.
+ */
+function mapGrantError(err) {
+    if (err instanceof guard_1.GrantNotPermittedError)
+        return new common_1.ForbiddenException(err.message);
+    if (err instanceof guard_1.InvalidGrantError)
+        return new common_1.BadRequestException(err.message);
+    if (err instanceof guard_1.GrantStoreUnavailableError)
+        return new common_1.ServiceUnavailableException(err.message);
+    return err;
+}

package/dist/features/cross-tenant/grant-authorize.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `makeAuthorizeCrossTenantGrant` — builds the `GrantAuthorizeFn` guard's
+ * `CrossTenantGrantWriter` calls to answer "may this principal perform `action` in
+ * `tenantId`?" for the cross-tenant grant lifecycle (offer -> 'share', accept ->
+ * 'accept', revoke -> 'revoke').
+ *
+ * Extracted out of the module wiring (which eagerly opens a real DB pool at forRoot()
+ * time, making it unsafe to import from a lightweight unit test) so the closure's
+ * LOGIC — build the principal, call `decide()`, return `effect === 'allow'` — is
+ * independently testable with fake `readRoleIds`/`decide` collaborators.
+ *
+ * Cross-tenant sharing is NOT a bespoke authority question; it is the SAME "may this
+ * person do this?" question every other action asks, answered by the SAME `decide()`
+ * over the `cross_tenant_grant` object type (`plane: 'control'`, actions
+ * `share`/`accept`/`revoke`).
+ *
+ * ⚠️ ROOT CORRECTNESS: `cross_tenant_grant` is `plane:'control'`, so root MAY
+ * share/accept/revoke — and the ROUTE guard already ran `decide()` with the caller's
+ * REAL principal (incl. its true `isRoot`) before this closure is ever reached. If
+ * this closure built its principal with `isRoot: false` unconditionally, a root
+ * caller who PASSED the route would then be DENIED here (a route-allows/writer-denies
+ * split for the exact same principal). We avoid it by resolving `isRoot` the SAME way
+ * the framework's Internal identity adapter does — membership in the boot-loaded
+ * `rootIds` allowlist — so this closure's principal is root-correct too.
+ *
+ * FAIL-CLOSED: `readRoleIds`/`decide` throwing propagates un-caught — the writer's
+ * `resolveAuthority` converts a throw to `GrantStoreUnavailableError` (retryable
+ * 503). We must NOT catch and return `false`, which would mask an outage as a deny.
+ */
+import type { DecisionAuthority } from '@astram/core';
+import type { GrantAuthorizeFn } from '@astram/guard';
+export interface MakeAuthorizeCrossTenantGrantDeps {
+    /** The (possibly second, independently-built) DecisionAuthority to call `decide()` on. */
+    readonly authority: Pick<DecisionAuthority, 'decide'>;
+    /** The SAME in-effect membership->posting roleIds read every other gate uses. */
+    readonly readRoleIds: (principalId: string, tenantId: string) => Promise<string[]>;
+    /** True iff `principalId` is in the boot-loaded root allowlist (SAME source `principal.isRoot`
+     *  was set from on the route's own decide() call). */
+    readonly isRoot: (principalId: string) => boolean;
+}
+export declare function makeAuthorizeCrossTenantGrant(deps: MakeAuthorizeCrossTenantGrantDeps): GrantAuthorizeFn;
+//# sourceMappingURL=grant-authorize.d.ts.map

package/dist/features/cross-tenant/grant-authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-authorize.d.ts","sourceRoot":"","sources":["../../../src/features/cross-tenant/grant-authorize.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,iCAAiC;IAChD,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IACtD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACnF;0DACsD;IACtD,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CACnD;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,iCAAiC,GACtC,gBAAgB,CAkBlB"}

package/dist/features/cross-tenant/grant-authorize.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAuthorizeCrossTenantGrant = makeAuthorizeCrossTenantGrant;
+function makeAuthorizeCrossTenantGrant(deps) {
+    return async (principalId, tenantId, action) => {
+        const roleIds = await deps.readRoleIds(principalId, tenantId);
+        const principal = {
+            kind: 'user',
+            id: principalId,
+            tenantId,
+            roleIds,
+            isRoot: deps.isRoot(principalId),
+        };
+        const decision = await deps.authority.decide(principal, { key: action }, { level: 'object_type', typeKey: 'cross_tenant_grant', tenantId }, { isAuthenticated: true });
+        return decision.effect === 'allow';
+    };
+}