@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/organizations.d.ts

@@ -0,0 +1,837 @@
+/**
+ * @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.
+ */
+/**
+ * Server-side organization operations (AGL-233/234). Everything here is
+ * Admin-SDK-only by design: org creation, slug reservation, membership
+ * and the projections the security rules authorize against are never
+ * client-writable (docs/MULTI_TENANT_FIRESTORE.md §8).
+ */
+import { type ConsentGroup, type AglynOrganization, type AglynOrgBilling, type AglynOrgMember, type HostAccessRole, type OrgPermission, type OrgRole } from '@aglyn/aglyn/server';
+import type { PluginActivityTargetType } from '@aglyn/aglyn/plugin-manager/plugin-activity-actions';
+import type { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter';
+export declare class OrgSlugTakenError extends Error {
+    constructor(slug: string);
+}
+/**
+ * ⛔ NOTHING WRITES A NEW `reservedUntil` ANY MORE — AND THE RULES THAT READ
+ * ONE STAY (AGL-2590).
+ *
+ * AGL-2585 gave a workspace created by an UNVERIFIED owner a held address
+ * rather than a granted one, because a signup could create a workspace before
+ * anything proved the email belonged to the person typing it. That is no
+ * longer possible: `/api/orgs/create` refuses an unverified caller outright,
+ * the sign-up form holds its typed name against the account instead, and the
+ * workspace is created on the first verified session. There is no path left
+ * that can produce an unproven address, so `createOrganization` writes the
+ * plain grant this collection has always held and the twenty-one-day
+ * reservation window is gone with the code that set it.
+ *
+ * The READ side below is deliberately kept, and it is not dead weight:
+ * production holds `orgSlugs` documents that WERE written with an expiry,
+ * before this. Deleting the lapse rules would silently promote every one of
+ * those squats to a permanent grant — the exact outcome AGL-2585 existed to
+ * end. They stay until `reap-unverified-orgs` has erased or promoted the last
+ * of them.
+ *
+ * Has a PENDING address reservation run out?
+ *
+ * A reservation with no `reservedUntil` is a GRANT and never lapses, which is
+ * what keeps every workspace made by a verified owner — and every one that
+ * predates the field — untouchable by this rule.
+ *
+ * A `reservedUntil` that is not a finite number never lapses either: a
+ * corrupt or half-written expiry is a reason to leave an address alone, not a
+ * reason to hand it to the next caller.
+ */
+export declare function isSlugReservationLapsed(reservation: {
+    orgId?: unknown;
+    movedTo?: unknown;
+    reservedUntil?: unknown;
+} | undefined, now?: number): boolean;
+/**
+ * Whether an `orgSlugs/{slug}` reservation may be (re)claimed (AGL-585):
+ * free when the doc is missing, when the claimant already owns it, or when
+ * it is a tombstone (`movedTo` set) — a renamed-away slug keeps redirecting
+ * old URLs only until someone wants it, it is never reserved forever.
+ * Claiming writes a full-replace `{ orgId }`, which ends the redirect —
+ * links to a reclaimed slug resolve to the new owner from then on.
+ *
+ * A LAPSED PENDING RESERVATION is claimable too (AGL-2585). The reservation
+ * an unverified signup takes is a hold, not a grant, and a hold that never
+ * expires is the squat this rule exists to end.
+ *
+ * ⚠️ Claimable here is NOT the whole answer for a lapsed reservation — see
+ * {@link lapsedReservationIsStillHeld}, which both call sites consult before
+ * they act on a `true` that came from the lapse branch. This function is pure
+ * and cannot ask whether the owner has verified since; treating its answer as
+ * final would let a customer who verified on day one lose their address on
+ * day twenty-one because a sweep was down.
+ */
+export declare function isSlugReservationClaimable(reservation: {
+    orgId?: unknown;
+    movedTo?: unknown;
+    reservedUntil?: unknown;
+} | undefined, claimingOrgId: string | null, now?: number): boolean;
+export interface CreateOrganizationOptions {
+    name: string;
+    slug: string;
+    ownerUid: string;
+    ownerEmail?: string | null;
+    ownerDisplayName?: string | null;
+    /**
+     * Skip the AGL-2265 free-workspace ceiling.
+     *
+     * For staff provisioning on a customer's behalf and for the migration and
+     * backfill scripts — a ceiling that stops support from fixing a workspace
+     * is a ceiling that produces the ticket it was meant to prevent. Never set
+     * from a self-serve path; `/api/orgs/create` passes the staff claim and
+     * nothing else.
+     */
+    bypassFreeWorkspaceCap?: boolean;
+}
+/**
+ * Creates an org in one transaction: slug reservation (uniqueness), org
+ * doc, owner membership, and the owner's reverse-index entry. Throws
+ * `OrgSlugTakenError` when the slug is reserved; slug validity is the
+ * caller's job (API routes return 400 with policy copy).
+ */
+export declare function createOrganization(options: CreateOrganizationOptions): Promise<string>;
+export interface OrgMembershipResolution {
+    orgId: string;
+    member: AglynOrgMember;
+    /**
+     * True only when THIS call provisioned the org, so a caller can report the
+     * activation (AGL-2587). `ensureOrgForUser` is the third org-creation door
+     * and the only server-side one, and it looked identical from outside to a
+     * resolution of an org that already existed — which is why `org_created`
+     * counted none of the workspaces it makes. Absent on `resolveOrgMembership`,
+     * which never creates anything.
+     */
+    created?: boolean;
+}
+/**
+ * The signed-in user's membership in one org, or null. When `orgId` is
+ * omitted, resolves the user's first org from the reverse index (the
+ * single-org case every pre-org account lands in after backfill).
+ */
+export declare function resolveOrgMembership(uid: string, orgId?: string | null): Promise<OrgMembershipResolution | null>;
+/**
+ * The user's org, creating a personal one on first need (signup flows and
+ * pre-backfill accounts): name from the display name or email local part,
+ * slug generated with numeric-suffix retries on collision.
+ */
+export declare function ensureOrgForUser(uid: string, profile?: {
+    email?: string | null;
+    displayName?: string | null;
+}): Promise<OrgMembershipResolution>;
+/**
+ * Changes an org's workspace slug (AGL-236): reserves the new slug and
+ * updates the org doc in one transaction, leaving the old reservation as
+ * a tombstone (`movedTo`) so existing workspace URLs keep resolving —
+ * the middleware redirects them. Reverse-index slugs fan out after.
+ * Throws `OrgSlugTakenError` only when another org ACTIVELY holds the new
+ * slug — tombstones are claimable (AGL-585). Slug validity/authorization
+ * are the API route's job.
+ */
+export declare function changeOrgSlug(orgId: string, newSlug: string): Promise<{
+    previousSlug: string | null;
+}>;
+/**
+ * Host → org resolution via the server-written `hostIndex` mirror.
+ *
+ * `React.cache`-deduped PER REQUEST (AGL-1302): one tenant render resolved
+ * this hop up to five times — org billing, datasets, plugin installs, realm
+ * installs and the publish-schedule executor each re-read the same
+ * `hostIndex/{hostId}` doc. Per-request memoization is zero-staleness by
+ * construction; outside a React render (route handlers, jest) `cache` is a
+ * pass-through, so nothing changes for the console's authz paths.
+ */
+export declare const resolveOrgIdForHost: (hostId: string) => Promise<string | null>;
+/**
+ * The org doc itself — billing, plan, entitlements and suspension (the
+ * shape the legacy tenants/{uid} doc carried; orgs are the only billing
+ * source since AGL-238). Null when the doc is missing.
+ */
+/**
+ * `React.cache`-deduped per request like {@link resolveOrgIdForHost}
+ * (AGL-1302). NOTE: within one render every caller receives the SAME object
+ * — treat it as read-only, as every current caller already does.
+ */
+export declare const getOrgDoc: (orgId: string) => Promise<Partial<AglynOrganization> | null>;
+/**
+ * Billing/entitlement source for a host (AGL-238): the owning org's doc
+ * via the hostIndex mirror. Null for unindexed hosts — callers treat that
+ * as the pre-billing fail-open (every feature on), the same contract the
+ * legacy tenants/{uid} read had.
+ */
+export declare function getOrgForHost(hostId: string): Promise<{
+    orgId: string;
+    org: Partial<AglynOrganization>;
+} | null>;
+/**
+ * The raw host doc, `React.cache`-deduped per request like
+ * {@link resolveOrgIdForHost}. Null when missing. Added for AGL-1506 so a
+ * dispatcher that already pays this read for the plugin deny-list can also
+ * feed the host's `suspendedAt` family to the lockdown verdict without a
+ * second get. Same read-only contract as {@link getOrgDoc}.
+ */
+export declare const getHostDocAdmin: (hostId: string) => Promise<Record<string, unknown> | null>;
+/**
+ * The host's per-site plugin deny-list (AGL-1014), for API dispatch and any
+ * other server consumer of `resolveHostEnabledPlugins`. Rides
+ * {@link getHostDocAdmin}'s request-cached read. Fail-open to [] — an absent
+ * host doc or field means "nothing disabled here", never a lockout.
+ */
+export declare const getHostDisabledPlugins: (hostId: string) => Promise<string[]>;
+/**
+ * Billing/entitlement source for a user without host context (account-
+ * level APIs): the explicit workspace org when given, else the first org
+ * from the reverse index. Null for accounts with no org yet.
+ */
+export declare function getOrgForUser(uid: string, orgId?: string | null): Promise<{
+    orgId: string;
+    org: Partial<AglynOrganization>;
+    member: AglynOrgMember;
+} | null>;
+/**
+ * Org-scoped data collection for a host (AGL-237): datasets, contacts and
+ * contactSegments live on the org so every host shares them.
+ *
+ * The pre-migration fallback to `hosts/{hostId}/{name}` is GONE (AGL-1050).
+ * The AGL-1040 backfill counted the docs still on it in production and
+ * found zero, so it was dead code rather than a migration — and a second
+ * storage path that can still be WRITTEN is a second boundary to enforce
+ * forever, which undoes the premise of scoped sharing: one home per
+ * resource plus an explicit scope.
+ *
+ * A host with no org is now an error rather than a silent write into a
+ * collection nothing reads. Every host has an org; `hostIndex` is written
+ * by `registerOrgHost` at creation.
+ */
+/**
+ * The org-owned collections a host reads in its own context. Every one of
+ * these carries `visibleTo` (AGL-1037) and so must go through
+ * `scopedToHost` on any Admin-SDK path — `media` and `mediaFolders` were
+ * added for the export route (AGL-1046), which had been reading the
+ * legacy host path and exporting nothing at all.
+ */
+export type OrgDataCollection = 'datasets' | 'contacts' | 'contactSegments' | 'crmViews' | 'lists' | 'media' | 'mediaFolders';
+export declare function orgDataCollectionForHost(hostId: string, name: OrgDataCollection): Promise<FirebaseFirestore.CollectionReference>;
+/**
+ * Narrows an org-scoped collection to what ONE host may see (AGL-1039).
+ *
+ * The Admin SDK does not evaluate Firestore rules, so AGL-1041's
+ * `visibleTo.hasAny(...)` protects the console and nothing else — every
+ * server read has to filter for itself or a client site can render another
+ * client's data. Use this instead of the bare collection ref anywhere a
+ * request is being served in the context of a single host.
+ *
+ * Only the ORG path is filtered — but no longer because of the legacy
+ * `hosts/{hostId}/…` fallback, which AGL-1050 removed on both the server
+ * (above) and the client. What survives it is the reason stated at the
+ * check itself: callers may hand this helper a ref they built themselves,
+ * and a host-library ref must never be filtered, since its docs carry no
+ * `visibleTo` and the filter would match nothing and blank the site.
+ */
+export declare function scopedToHost(ref: FirebaseFirestore.CollectionReference, hostId: string): FirebaseFirestore.Query;
+/**
+ * `orgDataCollectionForHost` + `scopedToHost` in one call — the form every
+ * host-context read should use. Returns the collection ref too, for the
+ * writes and `doc()` lookups a Query cannot express.
+ */
+export declare function orgDataQueryForHost(hostId: string, name: OrgDataCollection): Promise<{
+    ref: FirebaseFirestore.CollectionReference;
+    query: FirebaseFirestore.Query;
+}>;
+/**
+ * Server-side permission check (AGL-243): the member's org-role defaults
+ * refined by their custom role doc (one read, only when assigned). API
+ * routes call this before privileged mutations.
+ */
+/**
+ * The member's FULL granular permission set, custom role and per-member
+ * overrides applied (AGL-2350).
+ *
+ * `memberHasOrgPermission` below is the single-permission form and now
+ * delegates here, so the two cannot answer differently. Split out because
+ * `resolveOrgPermissions` in `libs/tenant/runtime` needs the whole set to
+ * project onto the legacy flag map that the marketplace install and publish
+ * gates read — it previously derived those flags from the built-in role tier
+ * alone, which silently ignored both refinements.
+ *
+ * One conditional read, only when a custom role is actually assigned. A
+ * dangling `roleId` resolves to `null` and falls back to the role defaults
+ * rather than denying, matching what the console hook does with the same
+ * dangling id — a deleted role must not lock a member out of surfaces their
+ * base role allows.
+ */
+export declare function resolveMemberOrgPermissions(orgId: string, member: Partial<AglynOrgMember> | null | undefined): Promise<Record<OrgPermission, boolean>>;
+export declare function memberHasOrgPermission(orgId: string, member: Partial<AglynOrgMember> | null | undefined, permission: OrgPermission): Promise<boolean>;
+/**
+ * May this member hold a catalog permission on this site (AGL-2927,
+ * AGL-2984)?
+ *
+ * The one resolver a door calls for a key a plugin declared with host-role
+ * defaults, so the two membership axes cannot be answered differently by two
+ * routes. An org-wide member is decided by the org catalog through
+ * `resolveMemberOrgPermissions` — custom role and overrides applied, one
+ * conditional read. A site collaborator is decided by the host role they hold
+ * on the site the request NAMES, refined by the per-site toggle on their
+ * member document; a collaborator whose request names no site is refused,
+ * because there is no host role to read a default from and omitting the site
+ * must not be a way around the toggle.
+ *
+ * `hostId` is whatever the body carried, trimmed by the caller or not — an
+ * empty string and `undefined` both mean "no site named".
+ */
+export declare function memberHasPermissionOnHost(orgId: string, hostId: string | null | undefined, member: Partial<AglynOrgMember> | null | undefined, permission: OrgPermission): Promise<boolean>;
+/**
+ * The 403 a door sends when `memberHasPermissionOnHost` says no: the same
+ * customer-safe shape the doors' other refusals use — one sentence, a
+ * `reason` a client can branch on — naming the permission by its catalog
+ * label so the reader can find it on the Team page, and who to ask.
+ */
+export declare function permissionRefusal(permission: OrgPermission): Response;
+/**
+ * An org-wide member's verdict for every key PLUGINS declared into the
+ * catalog, read fresh (AGL-2929, AGL-2984): what `memberHasPermissionOnHost`
+ * answers for them with no site named, as a whole map. `null` for a uid with
+ * no member document and for a site collaborator, whose per-site keys are
+ * decided per site by `setHostPermissions` and have no org-level verdict to
+ * compare. Read on either side of a membership write, it is how the members
+ * route tells which declared keys the write moved.
+ */
+export declare function resolveMemberPluginPermissionsOnOrg(orgId: string, uid: string): Promise<Record<string, boolean> | null>;
+/** A collaborator's per-site verdict on either side of a toggle write. */
+export interface HostPermissionsWrite {
+    /** The verdict before the write; `null` when the member had no access to the site. */
+    before: Record<string, boolean> | null;
+    after: Record<string, boolean>;
+}
+/**
+ * Set a collaborator's per-site toggles (AGL-2927, AGL-2984) and re-project.
+ *
+ * A merge on the nested map, so the member's other sites and every other
+ * field stay untouched; keys no plugin declared as per-site are dropped
+ * rather than stored, and a non-boolean is ignored rather than coerced.
+ * Re-projection is scoped to the one host whose `memberPermissions` changed.
+ *
+ * The verdict before the write comes back beside the one after it, because
+ * the caller records one activity row per key that moved (AGL-2929) and a
+ * toggle set to the value it already had is not a change.
+ */
+export declare function setHostPermissions(options: {
+    orgId: string;
+    uid: string;
+    hostId: string;
+    permissions: Partial<Record<string, unknown>>;
+}): Promise<HostPermissionsWrite>;
+export declare function listOrgMembers(orgId: string): Promise<AglynOrgMember[]>;
+/**
+ * Recomputes the denormalized authorization projections after a membership
+ * change: `memberRoles` and `memberPermissions` on every host the org owns
+ * (or one host when given), and `scopeTokens` + `resolvedPermissions` on
+ * every member doc.
+ *
+ * The rules resolve a request from these reads — the host doc for host
+ * content (docs/MULTI_TENANT_FIRESTORE.md §5), the member doc for scoped
+ * org resources (AGL-1038) — so this is what makes a membership effective.
+ * They live here, in one writer called by every mutation below, because a
+ * grant path that updates one projection and forgets another silently over-
+ * or under-grants.
+ *
+ * Everything is recomputed for the whole roster rather than the changed
+ * member: the roster is already loaded for `memberRoles`, and a full pass
+ * self-heals rows that an earlier partial failure left stale.
+ *
+ * ## `resolvedPermissions`, and why the rules need it denormalized
+ *
+ * Security rules cannot resolve a custom role. `member.roleId` points at
+ * `orgs/{orgId}/roles/{roleId}`, and reproducing the three-layer precedence
+ * (per-member beats custom role beats role default) in CEL takes a second
+ * cross-document get() plus a correct handling of a dangling id — where a
+ * naive version over-denies and locks out paying customers. So the rules read
+ * the ANSWER instead of the inputs, which is the same trade `scopeTokens`
+ * already makes for a reason the rules language shares: it has no `.map()`
+ * either.
+ *
+ * The map is `projectMemberResolvedPermissions`: `resolveOrgPermissions`'
+ * own catalog verdict, plus the plugin-declared keys a custom role or an
+ * override set explicitly (AGL-2974), so the rules and every
+ * server route are reading one resolver's verdict rather than two
+ * implementations of it.
+ *
+ * ONE READ PER DISTINCT ROLE, not per member: an org assigns a handful of
+ * custom roles across a roster that can run to hundreds, and resolving each
+ * member independently would re-read the same few documents once each.
+ */
+export declare function syncOrgAuthProjections(orgId: string, hostId?: string): Promise<void>;
+/**
+ * @deprecated Renamed to `syncOrgAuthProjections` (AGL-1038) now that it
+ * also writes member `scopeTokens`. Kept as an alias for out-of-tree
+ * callers; delete once none remain.
+ */
+export declare const syncHostMemberRoles: typeof syncOrgAuthProjections;
+/** What an org activity entry points at; `id` lets detail views filter. */
+export interface OrgActivityTarget {
+    /**
+     * `host` and `subscription` are the two facts about a workspace that no
+     * host feed can hold (AGL-118).
+     *
+     * A site's own log lives at `hosts/{hostId}/activity` and is destroyed with
+     * the site — `eraseHost` recursive-deletes the whole tree — so "this site
+     * was deleted" written there is an entry with no reader by construction.
+     * A subscription belongs to no single site at all. Both are org-level
+     * events, and this is the only feed that outlives them.
+     */
+    type: 'org' | 'member' | 'invite' | 'host' | 'subscription' | 'contact' | 'company' | 'deal' | 'lead' | 'task' | 'aiJob' | 'role' | 'screen' | 'layout' | 'component' | 'template' | 'workflow' | 'content' | 'theme' | PluginActivityTargetType;
+    id?: string;
+    name?: string;
+    /** Present on a generated screen output so the deep link can hit the exact version. */
+    versionId?: string;
+}
+/**
+ * Org-level counterpart to the host activity log (AGL-118): fire-and-
+ * forget append to `orgs/{orgId}/activity` from the org API routes. Never
+ * throws — an audit miss must not break the mutation that triggered it.
+ * Admin-SDK-only, like the rest of this file; the rules deny client writes.
+ */
+export declare function logOrgActivity(orgId: string, 
+/**
+ * `uid` is nullable because some org events HAVE no actor (AGL-118). Stripe
+ * cancels a subscription after a month of failed retries with nobody
+ * present, and the honest record of that says so. Naming the last person
+ * who touched billing instead would put a real name on an act nobody
+ * performed — and `actorId` is a filterable field, so the invented
+ * attribution would then show up under that person when somebody asks what
+ * they have done.
+ */
+actor: {
+    uid: string | null;
+    email?: string | null;
+}, action: string, target: OrgActivityTarget): Promise<void>;
+/** What a host activity entry points at. Mirrors `HostActivityTarget`. */
+export interface HostActivityTarget {
+    type: 'host' | 'screen' | 'layout' | 'theme' | 'media' | 'content' | 'variable' | 'function' | 'workflow' | 'member' | 'component' | 'template' | 'contact' | 'company' | 'deal' | 'lead';
+    id?: string;
+    name?: string;
+    versionId?: string;
+}
+/**
+ * Append to `hosts/{hostId}/activity` with the ADMIN SDK (AGL-118).
+ *
+ * The host log's twin of {@link logOrgActivity}, and the beginning of the
+ * migration off the browser. Every entry in this collection has been written
+ * by the client since the log existed, which makes it an audit trail its
+ * subject can decline to write: three template surfaces created screens,
+ * layouts and components while calling no logger at all, and nothing noticed
+ * for months because a log that is missing an entry looks exactly like a
+ * person who did nothing.
+ *
+ * A route that already authenticated the caller has the two things the client
+ * cannot be trusted for — a VERIFIED uid, and the certainty that the write it
+ * is recording actually happened, because it performed it. So an entry from
+ * here is worth more than the one it replaces, not merely more reliable.
+ *
+ * Never throws, for the reason the client logger never throws: an audit miss
+ * must not turn a successful create into a failed request. It is `await`ed
+ * rather than floated because a serverless response ending cancels in-flight
+ * work, which would make the drop the common case rather than the rare one.
+ */
+export declare function logHostActivity(hostId: string, actor: HostActivityActor, action: string, target: HostActivityTarget): Promise<void>;
+/**
+ * A collaborator seat refusal, raised from INSIDE the grant transaction
+ * (AGL-2068).
+ *
+ * An exception rather than a return value because it has to travel out of
+ * `upsertOrgMember` / `grantHostAccess`, whose contract is "make it so" and
+ * which four routes already call as a bare `await`. Returning a verdict would
+ * have let every existing call site ignore it silently, which is the shape of
+ * the bug being fixed.
+ */
+export declare class CollaboratorSeatLimitError extends Error {
+    readonly hostId: string;
+    readonly limit: number;
+    readonly upgradeRequired: boolean;
+    readonly addonPriceUsd: number | null;
+    /**
+     * Seats this site holds ABOVE `limit` (AGL-2439). Non-zero means the site
+     * is GRANDFATHERED: those collaborators keep their access, and the refusal
+     * is only of the NEXT one. Carried on the error so the refusal copy can say
+     * that rather than letting the admin read a 403 as "somebody was removed".
+     */
+    readonly retainedOverCap: number;
+    constructor(hostId: string, quota: {
+        limit: number;
+        upgradeRequired: boolean;
+        addonPriceUsd: number | null;
+        retainedOverCap?: number;
+    });
+}
+/**
+ * Turn a seat refusal into the 403 the four admitting routes return, or null
+ * when the error is something else and must keep propagating to the 500.
+ *
+ * Lives here beside `emailUnverifiedResponse` and `lockdownRefusal` so a
+ * route's catch block is one line and cannot accidentally mask a real fault.
+ */
+export declare function collaboratorSeatRefusalResponse(error: unknown): Response | null;
+/**
+ * The same cap, asked BEFORE anything is written (AGL-2068).
+ *
+ * Not the enforcement — the transaction inside the grant is. This exists so
+ * the two doors that only ever create an INVITE (`/api/hosts/members` for an
+ * address with no account yet, and `/api/orgs/invites` create) refuse at the
+ * point the admin is looking at, rather than mailing someone a link that will
+ * be refused when they click it. A race here over-reserves invites; it cannot
+ * over-grant access, because access is only ever granted through the
+ * transactional path.
+ */
+export declare function collaboratorSeatRefusal(options: {
+    orgId: string;
+    org: Partial<AglynOrgBilling>;
+    hostIds: string[];
+    self?: {
+        uid?: string | null;
+        email?: string | null;
+    };
+}): Promise<Response | null>;
+/**
+ * A manager seat refused, thrown rather than returned, for the reason
+ * {@link CollaboratorSeatLimitError} is thrown: it has to travel out of
+ * `upsertOrgMember`, whose contract is "make it so" and which three routes
+ * already call as a bare `await`. A verdict would be silently discarded by
+ * every one of them, which is the shape of the bug being fixed.
+ */
+export declare class ManagerSeatLimitError extends Error {
+    readonly limit: number;
+    readonly upgradeRequired: boolean;
+    readonly addonPriceUsd: number | null;
+    /**
+     * Seats the org holds ABOVE `limit`. Non-zero means it is GRANDFATHERED:
+     * those managers keep their access and only the NEXT one is refused, so the
+     * console can say that instead of letting an admin read a 403 as "somebody
+     * was removed".
+     */
+    readonly retainedOverCap: number;
+    constructor(quota: {
+        limit: number;
+        upgradeRequired: boolean;
+        addonPriceUsd: number | null;
+        retainedOverCap?: number;
+    });
+}
+/**
+ * Turn a manager-seat refusal into the 403 the admitting routes return, or
+ * null when the error is something else and must keep propagating to the 500.
+ *
+ * Sits beside `collaboratorSeatRefusalResponse` and stacks with it in a
+ * route's catch block, each returning null for a non-match.
+ */
+export declare function managerSeatRefusalResponse(error: unknown): Response | null;
+/**
+ * The same cap, asked BEFORE anything is written.
+ *
+ * Not the enforcement — the transaction inside `upsertOrgMember` is. This
+ * exists for the one door that never calls it: `/api/orgs/invites` create
+ * writes an invite document directly, so it refuses at the point the admin is
+ * looking at rather than mailing someone a link that will be refused when
+ * they click it. A race here over-reserves invites; it cannot over-grant
+ * access, because access is only ever granted through the transactional path.
+ */
+export declare function managerSeatRefusal(options: {
+    orgId: string;
+    org: Partial<AglynOrgBilling>;
+    becomesManager: boolean;
+    self?: {
+        uid?: string | null;
+        email?: string | null;
+    };
+}): Promise<Response | null>;
+export interface UpsertOrgMemberOptions {
+    orgId: string;
+    uid: string;
+    role: OrgRole;
+    allHosts?: boolean;
+    /** Per-site grants. `author` (AGL-2334) rides the shared union. */
+    hostAccess?: Record<string, HostAccessRole>;
+    /**
+     * Further CONFIRMED addresses on the joining account (AGL-2486), so a
+     * pending invite addressed to a secondary is recognised as this same
+     * person and does not bill them a second collaborator seat. Must contain
+     * only addresses proven to belong to `uid`.
+     */
+    seatAliasEmails?: readonly (string | null | undefined)[] | null;
+    /** Custom role reference (AGL-243); null clears it. */
+    roleId?: string | null;
+    email?: string | null;
+    displayName?: string | null;
+    /**
+     * The member's provider photo, mirrored onto the roster (AGL-1126).
+     *
+     * Every member surface reads the roster; none of them can read Firebase
+     * Auth for an SSO member, whose record lives in a per-org tenant pool
+     * (AGL-1122). Without this the console falls back to drawn initials for
+     * everyone — fine, but it means a member who HAS a picture still never
+     * shows it. This is the ONLY source of a real face now that the Gravatar
+     * fallback is gone (AGL-1683), so keeping it populated matters more than
+     * it did. Display data only: never an identity or authorization source.
+     */
+    photoURL?: string | null;
+    /** Job title shown on the roster/member page (AGL-364). */
+    title?: string | null;
+    invitedBy?: string | null;
+}
+/**
+ * The owner seat is not writable through the membership door (AGL-1888).
+ *
+ * An exception, and modelled on {@link CollaboratorSeatLimitError}, for the
+ * same reason: it has to travel out of a function whose contract is "make it
+ * so" and which three routes call as a bare `await`. A returned verdict would
+ * be ignorable at every one of them, which is the shape of the bug.
+ */
+export declare class OrgOwnerSeatError extends Error {
+    /** Which invariant refused, for the log and the tests. */
+    readonly reason: 'grant' | 'demote';
+    constructor(reason: 'grant' | 'demote');
+}
+/**
+ * Turn an owner-seat refusal into a 409, or null when the error is something
+ * else and must keep propagating to the 500.
+ *
+ * Beside {@link collaboratorSeatRefusalResponse} so a route's catch block
+ * stays one line and cannot accidentally mask a real fault.
+ */
+export declare function orgOwnerSeatRefusalResponse(error: unknown): Response | null;
+/**
+ * Creates or updates a member transactionally with its reverse-index
+ * entry, then re-syncs host projections.
+ *
+ * ## The owner seat is refused here, not only in the routes (AGL-1888)
+ *
+ * It used to say "owner-role guards live in the API routes — this is the
+ * mechanism", and that was the defect. Both halves of the org-owner invariant
+ * were enforced only at the doors an admin clicks, and invite ACCEPTANCE is a
+ * door that re-validates neither:
+ *
+ *  - **Granting.** `/api/orgs/members` and `/api/orgs/invites` create both
+ *    refuse `role === 'owner'` outright, but acceptance passes the invite
+ *    doc's STORED role straight through (`/api/orgs/invites` accept, and
+ *    `/api/auth/sso-jit`). That is safe today only because every writer of an
+ *    invite doc refuses `owner` and the collection is `allow write: if false`
+ *    — a latent escalation the moment a fourth invite-writer forgets, and the
+ *    invariant that an org has exactly ONE owner is what the whole SSO
+ *    break-glass guarantee rests on ({@link transferOrgOwnership} MOVES the
+ *    seat; nothing else may create one).
+ *  - **Demoting**, which was reachable, self-serve, and irreversible. Invite
+ *    creation never checked that the address is already a member, and
+ *    acceptance accommodates an existing member re-accepting. So any admin
+ *    could invite the OWNER'S own verified address as `viewer`; the owner
+ *    clicks a normal-looking invitation to their own organization; this
+ *    function merge-writes `role: 'viewer'`, `allHosts: false` onto the owner's
+ *    member doc. `orgs/{orgId}.ownerUid` still names them, but every
+ *    authorization read goes through the member doc — so `canManageOrg` is
+ *    now false, `transfer-ownership` checks `membership.member.role ===
+ *    'owner'` and refuses them, `/api/orgs/members` refuses to edit the owner's
+ *    membership at all, and `findBreakGlassOrgOwners` (`where role == owner`)
+ *    finds nobody. The org loses its owner permanently, recoverable only by
+ *    staff. It is the AGL-1375 one-way door rebuilt out of the invite path,
+ *    and it needs no SSO to reach.
+ *
+ * Both checks live HERE because this is the single transaction every door
+ * funnels through, and the org doc and the existing member doc are already in
+ * its read set — so it costs nothing and cannot be forgotten by a fifth
+ * caller. The route-level refusals stay: they are better error messages at
+ * the point the admin is looking, not the control.
+ *
+ * The demotion guard asks BOTH `org.ownerUid` and the stored role, rather
+ * than trusting either to stand for the other. They are supposed to agree;
+ * an org where they have already diverged is exactly the one that most needs
+ * the write refused.
+ *
+ * {@link createOrganization} and {@link transferOrgOwnership} are unaffected —
+ * both write `role: 'owner'` with their own `tx.set`, and remain the only two
+ * producers of an owner in the product.
+ */
+export declare function upsertOrgMember(options: UpsertOrgMemberOptions): Promise<void>;
+/**
+ * Fill in a roster row's display identity from an identity provider, writing
+ * ONLY the fields that are currently blank (AGL-1131).
+ *
+ * Separate from `upsertOrgMember` because the caller is the SSO sign-in path
+ * on its already-a-member branch, where the member's role, host access and
+ * invite state are settled and must not be touched. `upsertOrgMember`
+ * requires a `role` and re-asserts it, so reusing it here would let an SSO
+ * sign-in quietly reset an admin to the org's `sso.defaultRole`.
+ *
+ * Absent-only, so it is safe on every sign-in: it backfills the rows that
+ * predate the IdP mapping and then never writes again, and it can never
+ * overwrite a name or photo a person chose.
+ *
+ * @returns the field names it wrote, for logging and tests.
+ */
+export declare function backfillMemberIdentity(orgId: string, uid: string, identity: {
+    displayName?: string | null;
+    photoURL?: string | null;
+}, db?: FirebaseFirestore.Firestore): Promise<string[]>;
+/**
+ * The same absent-only backfill, across every roster row that names `uid`.
+ *
+ * ## The hole this closes
+ *
+ * `orgs/{orgId}/members/{uid}.photoURL` is the ONLY avatar a member surface
+ * can read — a colleague's auth record is unreadable from another member's
+ * session, and an SSO member's lives in a pool the project cannot see at all
+ * (AGL-1122). Three writers filled it, and between them they missed the
+ * commonest account there is:
+ *
+ * - `upsertOrgMember` — someone ADDED you, so the adder's lookup had a record
+ *   to copy from.
+ * - `backfillMemberIdentity` via the SSO sign-in (AGL-1131) — enterprise only.
+ * - `propagateMemberPhoto` via Manage Account → Profile image (AGL-1976) — a
+ *   photo the person typed or browsed to.
+ *
+ * Nobody adds the person who CREATES a workspace, `createOrganization` writes
+ * their row with a name and an email and no photo, and a Google sign-in never
+ * visits the other two. So the owner of a workspace saw their own face in the
+ * app bar, which reads the live auth record, and a grey initial in their own
+ * Team list — measured on both rows of `test-org`, each with `photoURL` absent
+ * while the auth record and `users/{uid}.photoUrl` carried the picture.
+ *
+ * ## Absent-only, like the function it fans out
+ *
+ * It runs on EVERY sign-in, so the reasoning in `backfillMemberIdentity`
+ * applies unchanged and is the reason this is a fan-out of that function
+ * rather than a second writer: an overwriting version would replace a photo
+ * the person chose in Manage Account with their provider thumbnail on their
+ * next sign-in, silently, forever. `propagateMemberPhoto` is the overwriting
+ * direction and stays the only one, because its input is a choice the person
+ * made rather than an assertion a directory made about them.
+ *
+ * Memberships come from `users/{uid}/orgs`, the reverse index — never a
+ * collection-group query over `members`, which would read every workspace's
+ * roster in the estate to find one person's rows.
+ *
+ * @returns the org ids whose row was written, for logging and tests.
+ */
+export declare function backfillMemberIdentityEverywhere(uid: string, identity: {
+    displayName?: string | null;
+    photoURL?: string | null;
+}, db?: FirebaseFirestore.Firestore): Promise<string[]>;
+/**
+ * Transfers org ownership (AGL-232): the target must already be on the
+ * roster; the previous owner steps down to admin. One transaction across
+ * the org doc, both member docs and both reverse-index entries, then the
+ * host projections re-sync.
+ *
+ * **It moves `ownerUid` and must never touch `createdByUid`** (AGL-2265).
+ * That field is the creator attribution the free-workspace ceiling counts
+ * against, and it is what stops a transfer from being a way to launder the
+ * count: hand a workspace to an alt account, create a fourth, take it back.
+ * Nothing here writes it, and `free-workspace-cap.spec.ts` runs exactly that
+ * sequence to keep it that way.
+ */
+export declare function transferOrgOwnership(orgId: string, fromUid: string, toUid: string): Promise<void>;
+/**
+ * Grants (or updates) per-host access for a uid without disturbing an
+ * existing membership's org role or allHosts flag (AGL-238: the host user
+ * manager rides org membership). Creates a viewer membership scoped to
+ * just this host when the uid is not on the roster yet.
+ */
+export declare function grantHostAccess(options: {
+    orgId: string;
+    uid: string;
+    hostId: string;
+    /** `author` (AGL-2334) edits content and cannot publish. */
+    role: HostAccessRole;
+    email?: string | null;
+    displayName?: string | null;
+    invitedBy?: string;
+}): Promise<void>;
+/**
+ * Drops one host from a member's hostAccess map, then re-projects.
+ *
+ * `updateExisting`, not a merge-set (AGL-1766). A merge-set whose entire
+ * payload is a delete sentinel still CREATES the document when it is absent,
+ * and the row it minted here is not merely untidy — it is a MEMBERSHIP, and
+ * one that reads as org-wide. `isOrgWideMember` treats "no `role`, no
+ * `allHosts`, empty `hostAccess`" as the pre-`allHosts` LEGACY shape and
+ * answers true (deliberately: reading it as "scoped, with access to nothing"
+ * would lock real members out). A genuine site collaborator never looks like
+ * that — `grantHostAccess` always writes `allHosts: false` — but a document
+ * conjured from this patch alone does, exactly.
+ *
+ * So the consequences land away from here, which is what made it hard to see:
+ * `resolveOrgMembership` finds the doc and returns a membership for someone
+ * who was removed from the org; `syncOrgAuthProjections` on the next line
+ * stamps it `scopeTokens: ['org']`, the read set the rules and every
+ * Admin-SDK `memberCanSee` resolve from; and `countManagerSeats` bills it as
+ * a manager seat. (It does NOT reach `hosts/*.memberRoles`, as AGL-1763
+ * supposed — `hostRoleFor` requires an `isOrgRole(role)` and the phantom has
+ * none.)
+ *
+ * Reachable without any race: `removeOrgMember` deletes the org member doc
+ * but leaves the `hosts/{hostId}/members` roster row, which is what this is
+ * called from. Deleting that leftover row re-created the membership it was
+ * meant to finish removing. (AGL-1766's "stale double-submit" is NOT a route:
+ * the caller 404s on the missing roster row before reaching here.)
+ *
+ * DOTTED FIELD PATH, not the nested map: `update()` accepts a delete sentinel
+ * only at the top level of its patch (`@google-cloud/firestore` serializer,
+ * `allowDeletes: 'root'`), so the nested form would throw INVALID_ARGUMENT.
+ * The dotted path is top-level and clears the one key while leaving the rest
+ * of `hostAccess` alone — the same field-by-field semantics the merge had.
+ * Safe as a string path because host ids are `createResourceUid()` nanoids
+ * (`A-Za-z0-9_-`), so none can contain the `.` the SDK splits on.
+ *
+ * REFUSE, and ignore the answer: revoking a grant that is not there is a
+ * no-op and discards nothing (AGL-1760). The projections still run — they are
+ * recomputed from the roster, so a pass that finds no member doc is exactly
+ * the self-heal a stale row needs.
+ */
+export declare function revokeHostAccess(orgId: string, uid: string, hostId: string): Promise<void>;
+/**
+ * Removes a member + reverse index entry, then re-syncs projections.
+ *
+ * The addresses the member added in this workspace (AGL-2975) go in the
+ * same batch. They sit beside the roster row rather than under it, so no
+ * delete of the row reaches them, and an erasure of the person runs through
+ * here once per workspace.
+ */
+export declare function removeOrgMember(orgId: string, uid: string): Promise<void>;
+/**
+ * Registers a host under its org: org directory entry, hostIndex mirror,
+ * and the initial memberRoles projection on the host doc.
+ */
+export declare function registerOrgHost(orgId: string, hostId: string, subdomain?: string): Promise<void>;
+/**
+ * The consent group a site belongs to, read off its owning org.
+ *
+ * The ONE server-side door to pooling. Every capture surface and every send
+ * path resolves a group through this rather than reading
+ * `CONSENT_GROUPS_FIELD` itself, so there is one place that decides what a
+ * site's consent covers and one place a mistake could live.
+ *
+ * FAILS TO THE GROUP OF ONE. An org that cannot be resolved, or a read that
+ * throws, answers "this site alone" — which withholds mail from an org that
+ * had legitimately pooled and never sends mail on a pooling nobody could
+ * confirm. That is the only direction a failure here may fall.
+ *
+ * The org read is `React.cache`-deduped per request by {@link getOrgForHost},
+ * so a send that already resolved the org for its policy pays nothing extra.
+ */
+export declare function consentGroupForSite(hostId: string, org?: Record<string, unknown> | null): Promise<ConsentGroup>;