@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/server/site-icon-render.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type SiteIconSpec } from '@aglyn/aglyn/app-utils/site-icon-set';
+import type { Sharp, SharpOptions } from 'sharp';
+/**
+ * Draws one icon of a site's derived set (AGL-3484) — the pixels behind
+ * `?icon=` on the media CDN. The grammar of the set (which sizes, which
+ * plates, how each is addressed) is `site-icon-set.ts` in `@aglyn/aglyn`;
+ * this module only turns a source file and a spec into bytes.
+ *
+ * Every plate starts from the same step: the mark CENTER-FIT on a square,
+ * never stretched. A wordmark uploaded as an icon comes out letterboxed — the
+ * same artwork, smaller — rather than squashed into a square it never was.
+ */
+type SharpFactory = (input?: Buffer | SharpOptions, options?: SharpOptions) => Sharp;
+export interface RenderedSiteIcon {
+    body: Buffer;
+    contentType: string;
+}
+/**
+ * Packs PNG images into one ICO container (PNG-in-ICO, which every browser
+ * since Windows Vista's era reads).
+ *
+ * The format is a 6-byte header, a 16-byte directory entry per image and the
+ * images themselves. A width or height of 256 is written as 0, per the format;
+ * nothing in {@link FAVICON_ICO_SIZES} reaches it, but a caller might.
+ */
+export declare function encodeIco(images: ReadonlyArray<{
+    size: number;
+    png: Buffer;
+}>): Buffer;
+/**
+ * One derived icon of `source`.
+ *
+ *  - `transparent` — center-fit on a transparent square.
+ *  - `flat` — center-fit, then flattened onto `background`: iOS renders a
+ *    touch icon's transparency black, so a transparent mark would sit in a
+ *    black tile on every home screen.
+ *  - `maskable` — fitted inside the safe zone ({@link maskableMarkSize}) on a
+ *    `background` plate, so a launcher's circle or squircle mask crops plate
+ *    and never mark.
+ *  - `ico` — the {@link FAVICON_ICO_SIZES} transparent PNGs in one ICO.
+ *
+ * `background` is anything {@link normalizeSiteIconBackground} reads, and
+ * white when it reads nothing. `sharp` is injectable for the module-shape
+ * reasons `loadSharp` documents; it is loaded when omitted.
+ */
+export declare function renderSiteIcon(options: {
+    source: Buffer;
+    spec: SiteIconSpec;
+    background?: string | null;
+    sharp?: SharpFactory;
+}): Promise<RenderedSiteIcon>;
+export {};

package/src/lib/server/site-icon-render.js

@@ -0,0 +1,157 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { DEFAULT_SITE_ICON_BACKGROUND, FAVICON_ICO_SIZES, maskableMarkSize, normalizeSiteIconBackground, siteIconContentType } from "@aglyn/aglyn/app-utils/site-icon-set";
+import { loadSharp } from "./media-variants.js";
+/** A source whose decoded pixels exceed this is refused rather than decoded. */ const SITE_ICON_MAX_INPUT_PIXELS = 50000000;
+/** `sharp`'s supported SVG density range, kept well inside its upper bound. */ const SVG_DENSITY_RANGE = [
+    1,
+    4800
+];
+const TRANSPARENT = {
+    r: 0,
+    g: 0,
+    b: 0,
+    alpha: 0
+};
+/**
+ * The input options that decode `source` sharply at `target` pixels.
+ *
+ * A raster decodes as it is. An SVG has no pixels until it is rasterized, and
+ * `sharp` does that at 72 dpi — a 24-unit icon would come out 24px and be
+ * UPSCALED to 512, which is the blur deriving was meant to avoid. So the
+ * density is raised until the longer side renders at least `target` pixels.
+ */ async function decodeOptions(sharp, source, target) {
+    var _meta_width, _meta_height;
+    const base = {
+        limitInputPixels: SITE_ICON_MAX_INPUT_PIXELS
+    };
+    const meta = await sharp(source, base).metadata();
+    if (meta.format !== 'svg') return base;
+    const longest = Math.max((_meta_width = meta.width) != null ? _meta_width : 0, (_meta_height = meta.height) != null ? _meta_height : 0);
+    if (!longest) return base;
+    const density = Math.min(SVG_DENSITY_RANGE[1], Math.max(SVG_DENSITY_RANGE[0], Math.ceil(72 * target / longest)));
+    return _extends({}, base, {
+        density
+    });
+}
+/** The mark center-fit on a transparent `size` square, as PNG. */ async function containedMark(sharp, source, size) {
+    const options = await decodeOptions(sharp, source, size);
+    return sharp(source, options).resize(size, size, {
+        fit: 'contain',
+        background: TRANSPARENT
+    }).png().toBuffer();
+}
+/** `mark` (already `markSize` square) centered on an opaque `size` plate. */ async function onPlate(sharp, mark, size, background) {
+    const composed = await sharp({
+        create: {
+            width: size,
+            height: size,
+            channels: 4,
+            background: `#${background}`
+        }
+    }).composite([
+        {
+            input: mark,
+            gravity: 'center'
+        }
+    ]).png().toBuffer();
+    // A second pass, because `sharp` flattens BEFORE it composites within one
+    // pipeline. The plate is opaque, and saying so in the file — no alpha
+    // channel at all — is what keeps iOS from painting anything black.
+    return sharp(composed).flatten({
+        background: `#${background}`
+    }).png().toBuffer();
+}
+/**
+ * Packs PNG images into one ICO container (PNG-in-ICO, which every browser
+ * since Windows Vista's era reads).
+ *
+ * The format is a 6-byte header, a 16-byte directory entry per image and the
+ * images themselves. A width or height of 256 is written as 0, per the format;
+ * nothing in {@link FAVICON_ICO_SIZES} reaches it, but a caller might.
+ */ export function encodeIco(images) {
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(0, 0); // reserved
+    header.writeUInt16LE(1, 2); // type: icon
+    header.writeUInt16LE(images.length, 4);
+    const directory = Buffer.alloc(16 * images.length);
+    let offset = header.length + directory.length;
+    images.forEach(({ size, png }, index)=>{
+        const at = index * 16;
+        const edge = size >= 256 ? 0 : size;
+        directory.writeUInt8(edge, at); // width
+        directory.writeUInt8(edge, at + 1); // height
+        directory.writeUInt8(0, at + 2); // palette size
+        directory.writeUInt8(0, at + 3); // reserved
+        directory.writeUInt16LE(1, at + 4); // color planes
+        directory.writeUInt16LE(32, at + 6); // bits per pixel
+        directory.writeUInt32LE(png.length, at + 8);
+        directory.writeUInt32LE(offset, at + 12);
+        offset += png.length;
+    });
+    return Buffer.concat([
+        header,
+        directory,
+        ...images.map(({ png })=>png)
+    ]);
+}
+/**
+ * One derived icon of `source`.
+ *
+ *  - `transparent` — center-fit on a transparent square.
+ *  - `flat` — center-fit, then flattened onto `background`: iOS renders a
+ *    touch icon's transparency black, so a transparent mark would sit in a
+ *    black tile on every home screen.
+ *  - `maskable` — fitted inside the safe zone ({@link maskableMarkSize}) on a
+ *    `background` plate, so a launcher's circle or squircle mask crops plate
+ *    and never mark.
+ *  - `ico` — the {@link FAVICON_ICO_SIZES} transparent PNGs in one ICO.
+ *
+ * `background` is anything {@link normalizeSiteIconBackground} reads, and
+ * white when it reads nothing. `sharp` is injectable for the module-shape
+ * reasons `loadSharp` documents; it is loaded when omitted.
+ */ export async function renderSiteIcon(options) {
+    var _options_sharp, _normalizeSiteIconBackground;
+    const { source, spec } = options;
+    const sharp = (_options_sharp = options.sharp) != null ? _options_sharp : await loadSharp();
+    const background = (_normalizeSiteIconBackground = normalizeSiteIconBackground(options.background)) != null ? _normalizeSiteIconBackground : DEFAULT_SITE_ICON_BACKGROUND;
+    const contentType = siteIconContentType(spec);
+    if (spec.plate === 'ico') {
+        const images = await Promise.all(FAVICON_ICO_SIZES.map(async (size)=>({
+                size,
+                png: await containedMark(sharp, source, size)
+            })));
+        return {
+            body: encodeIco(images),
+            contentType
+        };
+    }
+    if (spec.plate === 'transparent') {
+        return {
+            body: await containedMark(sharp, source, spec.size),
+            contentType
+        };
+    }
+    const markSize = spec.plate === 'maskable' ? maskableMarkSize(spec.size) : spec.size;
+    const mark = await containedMark(sharp, source, markSize);
+    return {
+        body: await onPlate(sharp, mark, spec.size, background),
+        contentType
+    };
+}
+
+//# sourceMappingURL=site-icon-render.js.map

package/src/lib/server/site-icon-render.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/site-icon-render.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DEFAULT_SITE_ICON_BACKGROUND,\n  FAVICON_ICO_SIZES,\n  maskableMarkSize,\n  normalizeSiteIconBackground,\n  siteIconContentType,\n  type SiteIconSpec,\n} from '@aglyn/aglyn/app-utils/site-icon-set'\nimport type { Sharp, SharpOptions } from 'sharp'\n\nimport { loadSharp } from './media-variants'\n\n/**\n * Draws one icon of a site's derived set (AGL-3484) — the pixels behind\n * `?icon=` on the media CDN. The grammar of the set (which sizes, which\n * plates, how each is addressed) is `site-icon-set.ts` in `@aglyn/aglyn`;\n * this module only turns a source file and a spec into bytes.\n *\n * Every plate starts from the same step: the mark CENTER-FIT on a square,\n * never stretched. A wordmark uploaded as an icon comes out letterboxed — the\n * same artwork, smaller — rather than squashed into a square it never was.\n */\n\ntype SharpFactory = (input?: Buffer | SharpOptions, options?: SharpOptions) => Sharp\n\n/** A source whose decoded pixels exceed this is refused rather than decoded. */\nconst SITE_ICON_MAX_INPUT_PIXELS = 50_000_000\n\n/** `sharp`'s supported SVG density range, kept well inside its upper bound. */\nconst SVG_DENSITY_RANGE = [1, 4800] as const\n\nconst TRANSPARENT = { r: 0, g: 0, b: 0, alpha: 0 }\n\nexport interface RenderedSiteIcon {\n  body: Buffer\n  contentType: string\n}\n\n/**\n * The input options that decode `source` sharply at `target` pixels.\n *\n * A raster decodes as it is. An SVG has no pixels until it is rasterized, and\n * `sharp` does that at 72 dpi — a 24-unit icon would come out 24px and be\n * UPSCALED to 512, which is the blur deriving was meant to avoid. So the\n * density is raised until the longer side renders at least `target` pixels.\n */\nasync function decodeOptions(\n  sharp: SharpFactory,\n  source: Buffer,\n  target: number,\n): Promise<SharpOptions> {\n  const base: SharpOptions = { limitInputPixels: SITE_ICON_MAX_INPUT_PIXELS }\n  const meta = await sharp(source, base).metadata()\n  if (meta.format !== 'svg') return base\n  const longest = Math.max(meta.width ?? 0, meta.height ?? 0)\n  if (!longest) return base\n  const density = Math.min(\n    SVG_DENSITY_RANGE[1],\n    Math.max(SVG_DENSITY_RANGE[0], Math.ceil((72 * target) / longest)),\n  )\n  return { ...base, density }\n}\n\n/** The mark center-fit on a transparent `size` square, as PNG. */\nasync function containedMark(\n  sharp: SharpFactory,\n  source: Buffer,\n  size: number,\n): Promise<Buffer> {\n  const options = await decodeOptions(sharp, source, size)\n  return sharp(source, options)\n    .resize(size, size, { fit: 'contain', background: TRANSPARENT })\n    .png()\n    .toBuffer()\n}\n\n/** `mark` (already `markSize` square) centered on an opaque `size` plate. */\nasync function onPlate(\n  sharp: SharpFactory,\n  mark: Buffer,\n  size: number,\n  background: string,\n): Promise<Buffer> {\n  const composed = await sharp({\n    create: {\n      width: size,\n      height: size,\n      channels: 4,\n      background: `#${background}`,\n    },\n  })\n    .composite([{ input: mark, gravity: 'center' }])\n    .png()\n    .toBuffer()\n  // A second pass, because `sharp` flattens BEFORE it composites within one\n  // pipeline. The plate is opaque, and saying so in the file — no alpha\n  // channel at all — is what keeps iOS from painting anything black.\n  return sharp(composed)\n    .flatten({ background: `#${background}` })\n    .png()\n    .toBuffer()\n}\n\n/**\n * Packs PNG images into one ICO container (PNG-in-ICO, which every browser\n * since Windows Vista's era reads).\n *\n * The format is a 6-byte header, a 16-byte directory entry per image and the\n * images themselves. A width or height of 256 is written as 0, per the format;\n * nothing in {@link FAVICON_ICO_SIZES} reaches it, but a caller might.\n */\nexport function encodeIco(\n  images: ReadonlyArray<{ size: number; png: Buffer }>,\n): Buffer {\n  const header = Buffer.alloc(6)\n  header.writeUInt16LE(0, 0) // reserved\n  header.writeUInt16LE(1, 2) // type: icon\n  header.writeUInt16LE(images.length, 4)\n  const directory = Buffer.alloc(16 * images.length)\n  let offset = header.length + directory.length\n  images.forEach(({ size, png }, index) => {\n    const at = index * 16\n    const edge = size >= 256 ? 0 : size\n    directory.writeUInt8(edge, at) // width\n    directory.writeUInt8(edge, at + 1) // height\n    directory.writeUInt8(0, at + 2) // palette size\n    directory.writeUInt8(0, at + 3) // reserved\n    directory.writeUInt16LE(1, at + 4) // color planes\n    directory.writeUInt16LE(32, at + 6) // bits per pixel\n    directory.writeUInt32LE(png.length, at + 8)\n    directory.writeUInt32LE(offset, at + 12)\n    offset += png.length\n  })\n  return Buffer.concat([header, directory, ...images.map(({ png }) => png)])\n}\n\n/**\n * One derived icon of `source`.\n *\n *  - `transparent` — center-fit on a transparent square.\n *  - `flat` — center-fit, then flattened onto `background`: iOS renders a\n *    touch icon's transparency black, so a transparent mark would sit in a\n *    black tile on every home screen.\n *  - `maskable` — fitted inside the safe zone ({@link maskableMarkSize}) on a\n *    `background` plate, so a launcher's circle or squircle mask crops plate\n *    and never mark.\n *  - `ico` — the {@link FAVICON_ICO_SIZES} transparent PNGs in one ICO.\n *\n * `background` is anything {@link normalizeSiteIconBackground} reads, and\n * white when it reads nothing. `sharp` is injectable for the module-shape\n * reasons `loadSharp` documents; it is loaded when omitted.\n */\nexport async function renderSiteIcon(options: {\n  source: Buffer\n  spec: SiteIconSpec\n  background?: string | null\n  sharp?: SharpFactory\n}): Promise<RenderedSiteIcon> {\n  const { source, spec } = options\n  const sharp =\n    options.sharp ?? ((await loadSharp()) as unknown as SharpFactory)\n  const background =\n    normalizeSiteIconBackground(options.background) ??\n    DEFAULT_SITE_ICON_BACKGROUND\n  const contentType = siteIconContentType(spec)\n\n  if (spec.plate === 'ico') {\n    const images = await Promise.all(\n      FAVICON_ICO_SIZES.map(async (size) => ({\n        size,\n        png: await containedMark(sharp, source, size),\n      })),\n    )\n    return { body: encodeIco(images), contentType }\n  }\n  if (spec.plate === 'transparent') {\n    return { body: await containedMark(sharp, source, spec.size), contentType }\n  }\n  const markSize =\n    spec.plate === 'maskable' ? maskableMarkSize(spec.size) : spec.size\n  const mark = await containedMark(sharp, source, markSize)\n  return {\n    body: await onPlate(sharp, mark, spec.size, background),\n    contentType,\n  }\n}\n"],"names":["DEFAULT_SITE_ICON_BACKGROUND","FAVICON_ICO_SIZES","maskableMarkSize","normalizeSiteIconBackground","siteIconContentType","loadSharp","SITE_ICON_MAX_INPUT_PIXELS","SVG_DENSITY_RANGE","TRANSPARENT","r","g","b","alpha","decodeOptions","sharp","source","target","meta","base","limitInputPixels","metadata","format","longest","Math","max","width","height","density","min","ceil","containedMark","size","options","resize","fit","background","png","toBuffer","onPlate","mark","composed","create","channels","composite","input","gravity","flatten","encodeIco","images","header","Buffer","alloc","writeUInt16LE","length","directory","offset","forEach","index","at","edge","writeUInt8","writeUInt32LE","concat","map","renderSiteIcon","spec","contentType","plate","Promise","all","body","markSize"],"mappings":"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"}

package/src/lib/server/staff-seat.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Whether an auth record's claims carry `staff: true`. */
+export declare function claimsHoldStaff(record: {
+    customClaims?: Record<string, unknown> | null;
+} | null | undefined): boolean;
+/** Whether the account `uid` holds the `staff` claim right now. */
+export declare function isStaffAccount(uid: string): Promise<boolean>;
+/**
+ * Whether the account holding `email` holds the `staff` claim right now.
+ *
+ * Used when an INVITE is sent, before anyone has accepted it, so the invite
+ * reserves no seat. It is not trusted at acceptance: the account that accepts
+ * is checked again by uid, so stamping an invite to a staff address can never
+ * become a free seat for whoever else ends up accepting it.
+ */
+export declare function isStaffAddress(email: string): Promise<boolean>;
+/**
+ * Take the staff stamp off every row and pending invite an account holds,
+ * for when its `staff` claim is revoked.
+ *
+ * The rows come from the `users/{uid}/orgs` reverse index, never a
+ * collection-group scan of every workspace's roster. Invites are found by
+ * address, because they have no uid until accepted.
+ *
+ * It frees no access and adds no check: a former staff member who stays on
+ * a roster now takes a seat like anyone else, and a workspace that is over
+ * its cap because of it keeps everyone it has. Seat caps bind admission,
+ * never access.
+ *
+ * @returns how many rows and invites were unstamped, for the audit row.
+ */
+export declare function clearStaffSeatStamps(uid: string, email?: string | null, db?: FirebaseFirestore.Firestore): Promise<{
+    members: number;
+    invites: number;
+}>;

package/src/lib/server/staff-seat.js

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Platform staff take none of a customer's seats (AGL-3466).
+ *
+ * A roster row or invite for an account holding the `staff` claim is stamped
+ * `staffSeat: true` when the server writes it, and every seat counter skips a
+ * stamped entry (`usesCustomerSeat`). This module answers the two questions
+ * the writers ask — is this account staff, is this address staff's — and
+ * takes the stamp off again when the claim is revoked.
+ *
+ * Every lookup FAILS TOWARDS A SEAT. An auth lookup that throws, or an
+ * account that cannot be found, answers "not staff", so the row it decides
+ * takes a seat like any other. The opposite failure would hand a free seat to
+ * whoever the lookup could not see.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { findUserByEmailAcrossPools, findUserByUidAcrossPools } from "./auth-pools.js";
+import firebaseAdmin from "./firebase-admin.js";
+/** Firestore's hard cap on writes in one batched commit. */ const FIRESTORE_BATCH_LIMIT = 500;
+/** Whether an auth record's claims carry `staff: true`. */ export function claimsHoldStaff(record) {
+    var _record_customClaims;
+    return (record == null ? void 0 : (_record_customClaims = record.customClaims) == null ? void 0 : _record_customClaims['staff']) === true;
+}
+/** Whether the account `uid` holds the `staff` claim right now. */ export async function isStaffAccount(uid) {
+    if (!uid) return false;
+    try {
+        const found = await findUserByUidAcrossPools(uid);
+        return claimsHoldStaff(found == null ? void 0 : found.record);
+    } catch (error) {
+        console.error('[staff-seat] staff lookup by uid failed', error);
+        return false;
+    }
+}
+/**
+ * Whether the account holding `email` holds the `staff` claim right now.
+ *
+ * Used when an INVITE is sent, before anyone has accepted it, so the invite
+ * reserves no seat. It is not trusted at acceptance: the account that accepts
+ * is checked again by uid, so stamping an invite to a staff address can never
+ * become a free seat for whoever else ends up accepting it.
+ */ export async function isStaffAddress(email) {
+    const address = typeof email === 'string' ? email.trim().toLowerCase() : '';
+    if (!address) return false;
+    try {
+        const found = await findUserByEmailAcrossPools(address);
+        return claimsHoldStaff(found == null ? void 0 : found.record);
+    } catch (error) {
+        console.error('[staff-seat] staff lookup by email failed', error);
+        return false;
+    }
+}
+/**
+ * Take the staff stamp off every row and pending invite an account holds,
+ * for when its `staff` claim is revoked.
+ *
+ * The rows come from the `users/{uid}/orgs` reverse index, never a
+ * collection-group scan of every workspace's roster. Invites are found by
+ * address, because they have no uid until accepted.
+ *
+ * It frees no access and adds no check: a former staff member who stays on
+ * a roster now takes a seat like anyone else, and a workspace that is over
+ * its cap because of it keeps everyone it has. Seat caps bind admission,
+ * never access.
+ *
+ * @returns how many rows and invites were unstamped, for the audit row.
+ */ export async function clearStaffSeatStamps(uid, email, db = firebaseAdmin.app().firestore()) {
+    const refs = [];
+    let members = 0;
+    let invites = 0;
+    if (uid) {
+        const memberships = await db.collection('users').doc(uid).collection('orgs').get();
+        const rows = await Promise.all(memberships.docs.map((membership)=>db.collection('orgs').doc(membership.id).collection('members').doc(uid).get()));
+        for (const row of rows){
+            if (row.exists && row.get('staffSeat') !== undefined) {
+                refs.push(row.ref);
+                members += 1;
+            }
+        }
+    }
+    const address = typeof email === 'string' ? email.trim().toLowerCase() : '';
+    if (address) {
+        const pending = await db.collectionGroup('invites').where('email', '==', address).where('acceptedAt', '==', null).get();
+        for (const invite of pending.docs){
+            if (invite.get('staffSeat') !== undefined) {
+                refs.push(invite.ref);
+                invites += 1;
+            }
+        }
+    }
+    for(let i = 0; i < refs.length; i += FIRESTORE_BATCH_LIMIT){
+        const batch = db.batch();
+        for (const ref of refs.slice(i, i + FIRESTORE_BATCH_LIMIT)){
+            batch.update(ref, {
+                staffSeat: FieldValue.delete()
+            });
+        }
+        await batch.commit();
+    }
+    return {
+        members,
+        invites
+    };
+}
+
+//# sourceMappingURL=staff-seat.js.map

package/src/lib/server/staff-seat.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/staff-seat.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Platform staff take none of a customer's seats (AGL-3466).\n *\n * A roster row or invite for an account holding the `staff` claim is stamped\n * `staffSeat: true` when the server writes it, and every seat counter skips a\n * stamped entry (`usesCustomerSeat`). This module answers the two questions\n * the writers ask — is this account staff, is this address staff's — and\n * takes the stamp off again when the claim is revoked.\n *\n * Every lookup FAILS TOWARDS A SEAT. An auth lookup that throws, or an\n * account that cannot be found, answers \"not staff\", so the row it decides\n * takes a seat like any other. The opposite failure would hand a free seat to\n * whoever the lookup could not see.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  findUserByEmailAcrossPools,\n  findUserByUidAcrossPools,\n} from './auth-pools'\nimport firebaseAdmin from './firebase-admin'\n\n/** Firestore's hard cap on writes in one batched commit. */\nconst FIRESTORE_BATCH_LIMIT = 500\n\n/** Whether an auth record's claims carry `staff: true`. */\nexport function claimsHoldStaff(\n  record: { customClaims?: Record<string, unknown> | null } | null | undefined,\n): boolean {\n  return record?.customClaims?.['staff'] === true\n}\n\n/** Whether the account `uid` holds the `staff` claim right now. */\nexport async function isStaffAccount(uid: string): Promise<boolean> {\n  if (!uid) return false\n  try {\n    const found = await findUserByUidAcrossPools(uid)\n    return claimsHoldStaff(found?.record)\n  } catch (error) {\n    console.error('[staff-seat] staff lookup by uid failed', error)\n    return false\n  }\n}\n\n/**\n * Whether the account holding `email` holds the `staff` claim right now.\n *\n * Used when an INVITE is sent, before anyone has accepted it, so the invite\n * reserves no seat. It is not trusted at acceptance: the account that accepts\n * is checked again by uid, so stamping an invite to a staff address can never\n * become a free seat for whoever else ends up accepting it.\n */\nexport async function isStaffAddress(email: string): Promise<boolean> {\n  const address = typeof email === 'string' ? email.trim().toLowerCase() : ''\n  if (!address) return false\n  try {\n    const found = await findUserByEmailAcrossPools(address)\n    return claimsHoldStaff(found?.record)\n  } catch (error) {\n    console.error('[staff-seat] staff lookup by email failed', error)\n    return false\n  }\n}\n\n/**\n * Take the staff stamp off every row and pending invite an account holds,\n * for when its `staff` claim is revoked.\n *\n * The rows come from the `users/{uid}/orgs` reverse index, never a\n * collection-group scan of every workspace's roster. Invites are found by\n * address, because they have no uid until accepted.\n *\n * It frees no access and adds no check: a former staff member who stays on\n * a roster now takes a seat like anyone else, and a workspace that is over\n * its cap because of it keeps everyone it has. Seat caps bind admission,\n * never access.\n *\n * @returns how many rows and invites were unstamped, for the audit row.\n */\nexport async function clearStaffSeatStamps(\n  uid: string,\n  email?: string | null,\n  db: FirebaseFirestore.Firestore = firebaseAdmin.app().firestore(),\n): Promise<{ members: number; invites: number }> {\n  const refs: FirebaseFirestore.DocumentReference[] = []\n  let members = 0\n  let invites = 0\n  if (uid) {\n    const memberships = await db.collection('users').doc(uid).collection('orgs').get()\n    const rows = await Promise.all(\n      memberships.docs.map((membership) =>\n        db.collection('orgs').doc(membership.id).collection('members').doc(uid).get(),\n      ),\n    )\n    for (const row of rows) {\n      if (row.exists && row.get('staffSeat') !== undefined) {\n        refs.push(row.ref)\n        members += 1\n      }\n    }\n  }\n  const address = typeof email === 'string' ? email.trim().toLowerCase() : ''\n  if (address) {\n    const pending = await db\n      .collectionGroup('invites')\n      .where('email', '==', address)\n      .where('acceptedAt', '==', null)\n      .get()\n    for (const invite of pending.docs) {\n      if (invite.get('staffSeat') !== undefined) {\n        refs.push(invite.ref)\n        invites += 1\n      }\n    }\n  }\n  for (let i = 0; i < refs.length; i += FIRESTORE_BATCH_LIMIT) {\n    const batch = db.batch()\n    for (const ref of refs.slice(i, i + FIRESTORE_BATCH_LIMIT)) {\n      batch.update(ref, { staffSeat: FieldValue.delete() })\n    }\n    await batch.commit()\n  }\n  return { members, invites }\n}\n"],"names":["FieldValue","findUserByEmailAcrossPools","findUserByUidAcrossPools","firebaseAdmin","FIRESTORE_BATCH_LIMIT","claimsHoldStaff","record","customClaims","isStaffAccount","uid","found","error","console","isStaffAddress","email","address","trim","toLowerCase","clearStaffSeatStamps","db","app","firestore","refs","members","invites","memberships","collection","doc","get","rows","Promise","all","docs","map","membership","id","row","exists","undefined","push","ref","pending","collectionGroup","where","invite","i","length","batch","slice","update","staffSeat","delete","commit"],"mappings":"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"}

package/src/lib/server/transfer-export.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type TransferExportChoice, type TransferPrefs } from '@aglyn/aglyn/data-transfer';
+import { type TransferEngineDeps } from './transfer-jobs';
+export interface TransferExportInput extends TransferExportChoice {
+    orgId: string;
+    actorUid: string;
+    hostId?: string | null;
+    /** A scoped collaborator's tokens; absent for a reader who sees the whole workspace. */
+    scopeTokens?: readonly string[];
+}
+export interface TransferExportFile {
+    stream: ReadableStream<Uint8Array>;
+    /** The rows the file holds, when they could be counted before the first byte. */
+    rows: number | null;
+    fileName: string;
+    contentType: string;
+    /** The fields written, in order. */
+    fieldIds: string[];
+    /** The resource's name, for the audit and the file. */
+    label: string;
+}
+/**
+ * The export, ready to stream (see the block header): the resource
+ * resolved, the fields checked against its catalog in the person's order,
+ * the rows counted when they can be, and a stream that reads the rest page
+ * by page. A field the catalog no longer has, a format the resource does not
+ * write, or an empty selection is refused before a byte is sent.
+ */
+export declare function streamTransferExport(deps: Pick<TransferEngineDeps, 'resolveResource' | 'now'>, input: TransferExportInput): Promise<TransferExportFile>;
+/** A person's remembered choices for one resource, as far as they can be trusted. */
+export declare function readTransferPrefs(firestore: FirebaseFirestore.Firestore, uid: string, resource: string): Promise<TransferPrefs>;