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

package/src/lib/server/upload-cors-reconcile.d.ts

@@ -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.
+ */
+/**
+ * Keep the media bucket's upload CORS in step with the names the console is
+ * SERVED on (AGL-1452).
+ *
+ * ## Why this is automation rather than a checklist line
+ *
+ * GCS matches the CORS `origin` list as an exact string — no subtree form —
+ * so every serving console name needs its own entry, and a missing one fails
+ * only on files large enough to take the signed direct-to-GCS path, behind a
+ * generic "try again" snackbar. Nothing about the symptom points at bucket
+ * configuration, and nothing at attach time pointed at it either.
+ *
+ * That was already costing us, not merely threatening to. Driving real
+ * preflights against `gs://aglyn-main.appspot.com` on 2026-08-20: of the
+ * console project's seventeen attached names, exactly one —
+ * `https://app.aglyn.com` — was permitted, while five names that serve the
+ * console at 200 (`zgover.aglyn.com`, `test-org.aglyn.com`,
+ * `aglyn-org.aglyn.com`, `sale-test.aglyn.com`, `zachary1748.aglyn.com`) were
+ * refused. AGL-1452 recorded workspace subdomains as latent because none were
+ * attached at the time; they are attached now.
+ *
+ * ## Serving names only
+ *
+ * A name attached as a REDIRECT never becomes a browser origin — the browser
+ * is already at the redirect target before it uploads — so it needs no entry.
+ * Measured: `console.aglyn.com` 308s and `app.aglyn.io` 307s to
+ * `app.aglyn.com`, and neither is in the CORS list, and neither is broken.
+ * `attachProjectDomain` therefore calls this only for a name it attached
+ * WITHOUT a redirect.
+ *
+ * ## When it cannot
+ *
+ * The runtime service account may not hold `storage.buckets.update`. That is
+ * a real and likely outcome, and the one thing this must not do about it is
+ * be quiet: the verdict carries `permitted: false` and the exact ordered
+ * read-modify-write command, so the failure is legible at attach time instead
+ * of arriving days later as a broken upload. It never throws and never blocks
+ * an attach — a domain must not fail to attach over a storage API.
+ */
+import { type CorsRule } from '@aglyn/aglyn/server';
+export interface UploadCorsVerdict {
+    /** The origin a browser at this name will send. */
+    origin: string;
+    /** Can a signed `PUT` from that origin complete, now that we are done? */
+    permitted: boolean;
+    /** Origins this run added to the bucket. Empty when it was already covered. */
+    added: string[];
+    /** What a human must run, when we could not. Null when there is nothing owed. */
+    remedy: string | null;
+    /** Which step failed, for a caller that wants to branch. */
+    detail: string | null;
+}
+/**
+ * The bucket, behind a seam.
+ *
+ * Injectable so the merge and the failure paths are exercised without a
+ * network — the reason AGL-1408 shipped broken is that the only leg nobody
+ * could test cheaply was the only leg that mattered.
+ */
+export interface BucketCorsIO {
+    bucket: string;
+    /** Null when the configuration could not be read at all. */
+    read(): Promise<{
+        rules: CorsRule[];
+        metageneration: string;
+    } | null>;
+    /**
+     * Write the merged configuration back, conditional on the metageneration
+     * that was read — two attaches racing would otherwise clobber each other.
+     */
+    write(rules: CorsRule[], metageneration: string): Promise<void>;
+}
+/** The live bucket, or null when this deployment has no media bucket configured. */
+export declare function liveBucketCorsIO(): BucketCorsIO | null;
+export declare function reconcileUploadCors(host: string, io?: BucketCorsIO | null): Promise<UploadCorsVerdict | null>;
+/** What a detach did, or could not do, about the origin it left behind. */
+export interface UploadCorsRelease {
+    /** The origin the detached name used to send. */
+    origin: string;
+    /** Is that origin gone from the bucket now? */
+    revoked: boolean;
+    /** Why not, for a caller that wants to branch. Null when it is gone. */
+    detail: string | null;
+}
+/**
+ * Take an origin back off the bucket when its name stops serving the console
+ * (AGL-1452).
+ *
+ * The mirror of `reconcileUploadCors`, and the half that was missing: attaching
+ * added an origin and detaching left it. That is a standing permission for a
+ * host we no longer serve — and for a white-label customer domain, a host that
+ * somebody else still controls, on a bucket where the signed URL IS the
+ * authorization.
+ *
+ * Same three properties as the attach side. It never throws, never blocks a
+ * detach, and reports what it could not do rather than going quiet: a domain
+ * must not fail to detach because a storage API was slow, and the operator who
+ * detached a customer must be able to see that the permission outlived them.
+ *
+ * Refuses the platform origin structurally, not by convention.
+ */
+export declare function releaseUploadCors(host: string, io?: BucketCorsIO | null): Promise<UploadCorsRelease | null>;

package/src/lib/server/upload-cors-reconcile.js

@@ -0,0 +1,234 @@
+/**
+ * @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.
+ */ /**
+ * Keep the media bucket's upload CORS in step with the names the console is
+ * SERVED on (AGL-1452).
+ *
+ * ## Why this is automation rather than a checklist line
+ *
+ * GCS matches the CORS `origin` list as an exact string — no subtree form —
+ * so every serving console name needs its own entry, and a missing one fails
+ * only on files large enough to take the signed direct-to-GCS path, behind a
+ * generic "try again" snackbar. Nothing about the symptom points at bucket
+ * configuration, and nothing at attach time pointed at it either.
+ *
+ * That was already costing us, not merely threatening to. Driving real
+ * preflights against `gs://aglyn-main.appspot.com` on 2026-08-20: of the
+ * console project's seventeen attached names, exactly one —
+ * `https://app.aglyn.com` — was permitted, while five names that serve the
+ * console at 200 (`zgover.aglyn.com`, `test-org.aglyn.com`,
+ * `aglyn-org.aglyn.com`, `sale-test.aglyn.com`, `zachary1748.aglyn.com`) were
+ * refused. AGL-1452 recorded workspace subdomains as latent because none were
+ * attached at the time; they are attached now.
+ *
+ * ## Serving names only
+ *
+ * A name attached as a REDIRECT never becomes a browser origin — the browser
+ * is already at the redirect target before it uploads — so it needs no entry.
+ * Measured: `console.aglyn.com` 308s and `app.aglyn.io` 307s to
+ * `app.aglyn.com`, and neither is in the CORS list, and neither is broken.
+ * `attachProjectDomain` therefore calls this only for a name it attached
+ * WITHOUT a redirect.
+ *
+ * ## When it cannot
+ *
+ * The runtime service account may not hold `storage.buckets.update`. That is
+ * a real and likely outcome, and the one thing this must not do about it is
+ * be quiet: the verdict carries `permitted: false` and the exact ordered
+ * read-modify-write command, so the failure is legible at attach time instead
+ * of arriving days later as a broken upload. It never throws and never blocks
+ * an attach — a domain must not fail to attach over a storage API.
+ */ import { mergeUploadOrigins, permitsUploadOrigin, revokeUploadOrigins, uploadCorsRemedy, uploadOriginFor } from "@aglyn/aglyn/server";
+/**
+ * The one origin a release must never take away.
+ *
+ * Configured rather than provisioned, so it will never appear in a detach —
+ * but the guard is here rather than at the call site because the cost of
+ * getting it wrong is every customer's large uploads at once, and a guard that
+ * lives at the call site is a guard the next call site does not have.
+ */ function platformOrigin() {
+    var _process_env_NEXT_PUBLIC_CONSOLE_URL;
+    return uploadOriginFor((_process_env_NEXT_PUBLIC_CONSOLE_URL = process.env['NEXT_PUBLIC_CONSOLE_URL']) != null ? _process_env_NEXT_PUBLIC_CONSOLE_URL : 'app.aglyn.com');
+}
+/** The live bucket, or null when this deployment has no media bucket configured. */ export function liveBucketCorsIO() {
+    var _process_env_NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET;
+    const bucket = String((_process_env_NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET = process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET']) != null ? _process_env_NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET : '').trim();
+    if (!bucket) return null;
+    // Imported lazily, not at module scope. `firebase-admin.ts` builds a
+    // Firebase app on load, and this module is imported by `workspace-domains`,
+    // which had no Firebase dependency at all and must keep none — a domain
+    // attach is an HTTP call to Vercel and nothing more.
+    const handle = async ()=>{
+        const { firebaseAdmin } = await import("./firebase-admin.js");
+        return firebaseAdmin.app().storage().bucket(bucket);
+    };
+    return {
+        bucket,
+        read: async ()=>{
+            var _ref, _ref1;
+            const [metadata] = await (await handle()).getMetadata();
+            return {
+                rules: (_ref = metadata == null ? void 0 : metadata.cors) != null ? _ref : [],
+                metageneration: String((_ref1 = metadata == null ? void 0 : metadata.metageneration) != null ? _ref1 : '')
+            };
+        },
+        write: async (rules, metageneration)=>{
+            await (await handle()).setMetadata({
+                cors: rules
+            }, metageneration ? {
+                ifMetagenerationMatch: metageneration
+            } : {});
+        }
+    };
+}
+export async function reconcileUploadCors(host, io = liveBucketCorsIO()) {
+    const origin = uploadOriginFor(host);
+    if (!origin || !io) return null;
+    const refused = (detail)=>({
+            origin,
+            permitted: false,
+            added: [],
+            remedy: uploadCorsRemedy(io.bucket, [
+                origin
+            ]),
+            detail
+        });
+    let current;
+    try {
+        current = await io.read();
+    } catch (error) {
+        console.error('[upload-cors] could not read bucket CORS', io.bucket, error);
+        return refused('read-failed');
+    }
+    if (!current) return refused('read-failed');
+    if (permitsUploadOrigin(current.rules, origin)) {
+        return {
+            origin,
+            permitted: true,
+            added: [],
+            remedy: null,
+            detail: null
+        };
+    }
+    let merged;
+    try {
+        merged = mergeUploadOrigins(current.rules, [
+            origin
+        ]);
+    } catch (error) {
+        // `mergeUploadOrigins` throws only on a wildcard, which `uploadOriginFor`
+        // has already ruled out — so reaching here means the invariant moved.
+        console.error('[upload-cors] refused to build a policy', origin, error);
+        return refused('merge-refused');
+    }
+    try {
+        await io.write(merged.rules, current.metageneration);
+    } catch (error) {
+        console.error('[upload-cors] could not write bucket CORS — large uploads from', origin, 'will fail until a human runs the command in the verdict', error);
+        return refused('write-failed');
+    }
+    return {
+        origin,
+        permitted: true,
+        added: merged.added,
+        remedy: null,
+        detail: null
+    };
+}
+/**
+ * Take an origin back off the bucket when its name stops serving the console
+ * (AGL-1452).
+ *
+ * The mirror of `reconcileUploadCors`, and the half that was missing: attaching
+ * added an origin and detaching left it. That is a standing permission for a
+ * host we no longer serve — and for a white-label customer domain, a host that
+ * somebody else still controls, on a bucket where the signed URL IS the
+ * authorization.
+ *
+ * Same three properties as the attach side. It never throws, never blocks a
+ * detach, and reports what it could not do rather than going quiet: a domain
+ * must not fail to detach because a storage API was slow, and the operator who
+ * detached a customer must be able to see that the permission outlived them.
+ *
+ * Refuses the platform origin structurally, not by convention.
+ */ export async function releaseUploadCors(host, io = liveBucketCorsIO()) {
+    var _platformOrigin;
+    const origin = uploadOriginFor(host);
+    if (!origin || !io) return null;
+    if (origin === platformOrigin()) {
+        return {
+            origin,
+            revoked: false,
+            detail: 'platform-origin'
+        };
+    }
+    let current;
+    try {
+        current = await io.read();
+    } catch (error) {
+        console.error('[upload-cors] could not read bucket CORS', io.bucket, error);
+        return {
+            origin,
+            revoked: false,
+            detail: 'read-failed'
+        };
+    }
+    if (!current) return {
+        origin,
+        revoked: false,
+        detail: 'read-failed'
+    };
+    // Already gone is the success case, not a no-op to report as a failure: a
+    // detach that runs twice must not read as a permission that would not go.
+    if (!permitsUploadOrigin(current.rules, origin)) {
+        return {
+            origin,
+            revoked: true,
+            detail: null
+        };
+    }
+    const { rules, removed } = revokeUploadOrigins(current.rules, [
+        origin
+    ], {
+        keep: [
+            (_platformOrigin = platformOrigin()) != null ? _platformOrigin : ''
+        ].filter(Boolean)
+    });
+    if (removed.length === 0) {
+        return {
+            origin,
+            revoked: false,
+            detail: 'refused'
+        };
+    }
+    try {
+        await io.write(rules, current.metageneration);
+    } catch (error) {
+        console.error('[upload-cors] could not revoke bucket CORS —', origin, 'keeps a standing permission to complete signed uploads; run', 'npm run check:upload-cors -- --prune', error);
+        return {
+            origin,
+            revoked: false,
+            detail: 'write-failed'
+        };
+    }
+    return {
+        origin,
+        revoked: true,
+        detail: null
+    };
+}
+
+//# sourceMappingURL=upload-cors-reconcile.js.map

package/src/lib/server/upload-cors-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/upload-cors-reconcile.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 * Keep the media bucket's upload CORS in step with the names the console is\n * SERVED on (AGL-1452).\n *\n * ## Why this is automation rather than a checklist line\n *\n * GCS matches the CORS `origin` list as an exact string — no subtree form —\n * so every serving console name needs its own entry, and a missing one fails\n * only on files large enough to take the signed direct-to-GCS path, behind a\n * generic \"try again\" snackbar. Nothing about the symptom points at bucket\n * configuration, and nothing at attach time pointed at it either.\n *\n * That was already costing us, not merely threatening to. Driving real\n * preflights against `gs://aglyn-main.appspot.com` on 2026-08-20: of the\n * console project's seventeen attached names, exactly one —\n * `https://app.aglyn.com` — was permitted, while five names that serve the\n * console at 200 (`zgover.aglyn.com`, `test-org.aglyn.com`,\n * `aglyn-org.aglyn.com`, `sale-test.aglyn.com`, `zachary1748.aglyn.com`) were\n * refused. AGL-1452 recorded workspace subdomains as latent because none were\n * attached at the time; they are attached now.\n *\n * ## Serving names only\n *\n * A name attached as a REDIRECT never becomes a browser origin — the browser\n * is already at the redirect target before it uploads — so it needs no entry.\n * Measured: `console.aglyn.com` 308s and `app.aglyn.io` 307s to\n * `app.aglyn.com`, and neither is in the CORS list, and neither is broken.\n * `attachProjectDomain` therefore calls this only for a name it attached\n * WITHOUT a redirect.\n *\n * ## When it cannot\n *\n * The runtime service account may not hold `storage.buckets.update`. That is\n * a real and likely outcome, and the one thing this must not do about it is\n * be quiet: the verdict carries `permitted: false` and the exact ordered\n * read-modify-write command, so the failure is legible at attach time instead\n * of arriving days later as a broken upload. It never throws and never blocks\n * an attach — a domain must not fail to attach over a storage API.\n */\n\nimport {\n  mergeUploadOrigins,\n  permitsUploadOrigin,\n  revokeUploadOrigins,\n  uploadCorsRemedy,\n  uploadOriginFor,\n  type CorsRule,\n} from '@aglyn/aglyn/server'\n\n/**\n * The one origin a release must never take away.\n *\n * Configured rather than provisioned, so it will never appear in a detach —\n * but the guard is here rather than at the call site because the cost of\n * getting it wrong is every customer's large uploads at once, and a guard that\n * lives at the call site is a guard the next call site does not have.\n */\nfunction platformOrigin(): string | null {\n  return uploadOriginFor(\n    process.env['NEXT_PUBLIC_CONSOLE_URL'] ?? 'app.aglyn.com',\n  )\n}\n\nexport interface UploadCorsVerdict {\n  /** The origin a browser at this name will send. */\n  origin: string\n  /** Can a signed `PUT` from that origin complete, now that we are done? */\n  permitted: boolean\n  /** Origins this run added to the bucket. Empty when it was already covered. */\n  added: string[]\n  /** What a human must run, when we could not. Null when there is nothing owed. */\n  remedy: string | null\n  /** Which step failed, for a caller that wants to branch. */\n  detail: string | null\n}\n\n/**\n * The bucket, behind a seam.\n *\n * Injectable so the merge and the failure paths are exercised without a\n * network — the reason AGL-1408 shipped broken is that the only leg nobody\n * could test cheaply was the only leg that mattered.\n */\nexport interface BucketCorsIO {\n  bucket: string\n  /** Null when the configuration could not be read at all. */\n  read(): Promise<{ rules: CorsRule[]; metageneration: string } | null>\n  /**\n   * Write the merged configuration back, conditional on the metageneration\n   * that was read — two attaches racing would otherwise clobber each other.\n   */\n  write(rules: CorsRule[], metageneration: string): Promise<void>\n}\n\n/** The live bucket, or null when this deployment has no media bucket configured. */\nexport function liveBucketCorsIO(): BucketCorsIO | null {\n  const bucket = String(\n    process.env['NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET'] ?? '',\n  ).trim()\n  if (!bucket) return null\n  // Imported lazily, not at module scope. `firebase-admin.ts` builds a\n  // Firebase app on load, and this module is imported by `workspace-domains`,\n  // which had no Firebase dependency at all and must keep none — a domain\n  // attach is an HTTP call to Vercel and nothing more.\n  const handle = async () => {\n    const { firebaseAdmin } = await import('./firebase-admin')\n    return firebaseAdmin.app().storage().bucket(bucket)\n  }\n  return {\n    bucket,\n    read: async () => {\n      const [metadata] = await (await handle()).getMetadata()\n      return {\n        rules: (metadata?.cors ?? []) as CorsRule[],\n        metageneration: String(metadata?.metageneration ?? ''),\n      }\n    },\n    write: async (rules, metageneration) => {\n      await (await handle()).setMetadata(\n        { cors: rules },\n        metageneration ? { ifMetagenerationMatch: metageneration } : {},\n      )\n    },\n  }\n}\n\nexport async function reconcileUploadCors(\n  host: string,\n  io: BucketCorsIO | null = liveBucketCorsIO(),\n): Promise<UploadCorsVerdict | null> {\n  const origin = uploadOriginFor(host)\n  if (!origin || !io) return null\n\n  const refused = (detail: string): UploadCorsVerdict => ({\n    origin,\n    permitted: false,\n    added: [],\n    remedy: uploadCorsRemedy(io.bucket, [origin]),\n    detail,\n  })\n\n  let current: { rules: CorsRule[]; metageneration: string } | null\n  try {\n    current = await io.read()\n  } catch (error) {\n    console.error('[upload-cors] could not read bucket CORS', io.bucket, error)\n    return refused('read-failed')\n  }\n  if (!current) return refused('read-failed')\n\n  if (permitsUploadOrigin(current.rules, origin)) {\n    return { origin, permitted: true, added: [], remedy: null, detail: null }\n  }\n\n  let merged: { rules: CorsRule[]; added: string[] }\n  try {\n    merged = mergeUploadOrigins(current.rules, [origin])\n  } catch (error) {\n    // `mergeUploadOrigins` throws only on a wildcard, which `uploadOriginFor`\n    // has already ruled out — so reaching here means the invariant moved.\n    console.error('[upload-cors] refused to build a policy', origin, error)\n    return refused('merge-refused')\n  }\n\n  try {\n    await io.write(merged.rules, current.metageneration)\n  } catch (error) {\n    console.error(\n      '[upload-cors] could not write bucket CORS — large uploads from',\n      origin,\n      'will fail until a human runs the command in the verdict',\n      error,\n    )\n    return refused('write-failed')\n  }\n\n  return {\n    origin,\n    permitted: true,\n    added: merged.added,\n    remedy: null,\n    detail: null,\n  }\n}\n\n/** What a detach did, or could not do, about the origin it left behind. */\nexport interface UploadCorsRelease {\n  /** The origin the detached name used to send. */\n  origin: string\n  /** Is that origin gone from the bucket now? */\n  revoked: boolean\n  /** Why not, for a caller that wants to branch. Null when it is gone. */\n  detail: string | null\n}\n\n/**\n * Take an origin back off the bucket when its name stops serving the console\n * (AGL-1452).\n *\n * The mirror of `reconcileUploadCors`, and the half that was missing: attaching\n * added an origin and detaching left it. That is a standing permission for a\n * host we no longer serve — and for a white-label customer domain, a host that\n * somebody else still controls, on a bucket where the signed URL IS the\n * authorization.\n *\n * Same three properties as the attach side. It never throws, never blocks a\n * detach, and reports what it could not do rather than going quiet: a domain\n * must not fail to detach because a storage API was slow, and the operator who\n * detached a customer must be able to see that the permission outlived them.\n *\n * Refuses the platform origin structurally, not by convention.\n */\nexport async function releaseUploadCors(\n  host: string,\n  io: BucketCorsIO | null = liveBucketCorsIO(),\n): Promise<UploadCorsRelease | null> {\n  const origin = uploadOriginFor(host)\n  if (!origin || !io) return null\n  if (origin === platformOrigin()) {\n    return { origin, revoked: false, detail: 'platform-origin' }\n  }\n\n  let current: { rules: CorsRule[]; metageneration: string } | null\n  try {\n    current = await io.read()\n  } catch (error) {\n    console.error('[upload-cors] could not read bucket CORS', io.bucket, error)\n    return { origin, revoked: false, detail: 'read-failed' }\n  }\n  if (!current) return { origin, revoked: false, detail: 'read-failed' }\n\n  // Already gone is the success case, not a no-op to report as a failure: a\n  // detach that runs twice must not read as a permission that would not go.\n  if (!permitsUploadOrigin(current.rules, origin)) {\n    return { origin, revoked: true, detail: null }\n  }\n\n  const { rules, removed } = revokeUploadOrigins(current.rules, [origin], {\n    keep: [platformOrigin() ?? ''].filter(Boolean),\n  })\n  if (removed.length === 0) {\n    return { origin, revoked: false, detail: 'refused' }\n  }\n\n  try {\n    await io.write(rules, current.metageneration)\n  } catch (error) {\n    console.error(\n      '[upload-cors] could not revoke bucket CORS —',\n      origin,\n      'keeps a standing permission to complete signed uploads; run',\n      'npm run check:upload-cors -- --prune',\n      error,\n    )\n    return { origin, revoked: false, detail: 'write-failed' }\n  }\n  return { origin, revoked: true, detail: null }\n}\n"],"names":["mergeUploadOrigins","permitsUploadOrigin","revokeUploadOrigins","uploadCorsRemedy","uploadOriginFor","platformOrigin","process","env","liveBucketCorsIO","bucket","String","trim","handle","firebaseAdmin","app","storage","read","metadata","getMetadata","rules","cors","metageneration","write","setMetadata","ifMetagenerationMatch","reconcileUploadCors","host","io","origin","refused","detail","permitted","added","remedy","current","error","console","merged","releaseUploadCors","revoked","removed","keep","filter","Boolean","length"],"mappings":"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"}

package/src/lib/server/upsert-contact.d.ts

@@ -0,0 +1,262 @@
+/**
+ * @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 ContactFacet, type ContactInteraction, type ContactLifecycleStage, type ContactSource } from '@aglyn/aglyn/server';
+import { type ResolvedCampaignTouch } from './campaign-conversion-attribution';
+import { type MarketingConsentSource } from '@aglyn/aglyn/app-utils/marketing-consent';
+/**
+ * What an upsert did, for the callers that need to know (AGL-2602).
+ *
+ * The capture doors never look: a form submission or an order must succeed
+ * whatever happened to the CRM record, which is why this function swallows
+ * its own errors and why every existing caller `await`s it for its side
+ * effect alone. An IMPORT is the caller that has to know, row by row —
+ * "created" and "merged" are its two headline numbers, and a row the
+ * audience band refused has to be handed back to the operator as a row
+ * rather than becoming one more tick on a counter nobody reconciles against
+ * a file. A verdict is returned rather than thrown so the swallowing stays:
+ * `refused: 'error'` is the same silence the doors have always had, now with
+ * a name.
+ */
+export type UpsertHostContactVerdict = {
+    contactId: string;
+    /** True when this call created the row; false when it merged into one. */
+    created: boolean;
+} | {
+    /**
+     * `erased`: the site holds an erasure row for the address (AGL-2623),
+     * so no record is created — a capture must not quietly rebuild a
+     * person the workspace erased. Only a CREATE is refused; a merge
+     * cannot arise, because the erasure removed the row it would merge
+     * into.
+     */
+    refused: 'invalid-email' | 'band' | 'erased' | 'error';
+};
+/**
+ * The per-holder profile fields a door may write alongside the identity.
+ *
+ * `Pick`ed from the facet rather than typed afresh so the two cannot drift:
+ * a field the facet grows is a field this option may carry the moment the
+ * pick names it, and one it does not name is refused at compile time.
+ */
+export type UpsertHostContactFacet = Partial<Pick<ContactFacet, 'phone' | 'jobTitle' | 'companyId' | 'address' | 'ownerUid' | 'lifecycleStage' | 'custom'>>;
+/**
+ * The profile fields a door may hand this function (AGL-2596): the parts of
+ * a person's record that no capture surface collects — the console's create
+ * drawer and the import do, and the order door adds the stage. `custom` is
+ * the holder's own field values, keyed by `ContactFieldDefinition.key`; the
+ * import maps spreadsheet columns onto them, and the definitions live under
+ * the same group the values are written to.
+ */
+export type ContactProfileInput = UpsertHostContactFacet;
+/**
+ * Contacts ingestion (AGL-197): upserts an org-scoped contact doc (AGL-237)
+ * keyed by normalized email from any capture point (forms, membership,
+ * orders, bookings). Fire-and-forget by design — callers should never
+ * fail their primary write because contact capture had a problem.
+ *
+ * Quota (AGL-890): contacts are audience BANDS, not hard caps. Paid plans
+ * always create — contacts past the included band meter onto the monthly
+ * invoice (report-usage cron). Free hard-bands at the included count:
+ * only there do dropped creations increment `counters/contactsDropped`,
+ * surfaced as a console alert (AGL-891). Interactions on existing
+ * contacts always append regardless of plan.
+ */
+/**
+ * What a capture door learns when its capture made a NEW person.
+ *
+ * Handed to {@link UpsertHostContactOptions.onCreated} once, on the create
+ * branch only. The merge branch is a visit by somebody the org already held,
+ * which is another interaction and not a new contact — the same line
+ * `campaignTouch` draws for attribution. Scalars and one string array, so
+ * the runtime can flatten it into an event payload without inventing keys.
+ */
+export interface HostContactCreated {
+    contactId: string;
+    hostId: string;
+    email: string;
+    name?: string;
+    source: ContactSource;
+    /** The capture surface's campaigns, normalized — `[]` when it had none. */
+    campaignIds: string[];
+    /**
+     * The stage the create wrote onto the capturing facet — the door's
+     * {@link UpsertHostContactOptions.initialLifecycleStage}, or the profile's
+     * own — and absent when the capture named none, so an automation can
+     * filter `lifecycleStage == "lead"` on the day the person appears.
+     */
+    lifecycleStage?: ContactLifecycleStage;
+}
+export interface UpsertHostContactOptions {
+    hostId: string;
+    email: unknown;
+    name?: string;
+    source: ContactSource;
+    interaction: Omit<ContactInteraction, 'type' | 'atMs'> & {
+        atMs?: number;
+    };
+    /**
+     * Explicit marketing opt-in (AGL-301) with a consent timestamp, recorded
+     * against {@link hostId} — the brand whose form carried the checkbox.
+     */
+    marketingConsent?: boolean;
+    /**
+     * An explicit REFUSAL, recorded against {@link hostId} (AGL-3185).
+     *
+     * Its own flag rather than `marketingConsent: false`, because every door
+     * that passes a checkbox's value passes `false` for a box left alone, and
+     * a box left alone records nothing — absence is the third state, and
+     * turning it into a refusal would silently make every unticked visitor
+     * unmailable. A door sets this only for an act of refusal: a switch turned
+     * off, a prompt answered no. Ignored when {@link marketingConsent} is true.
+     */
+    declineMarketingConsent?: boolean;
+    /**
+     * The provenance stored on the consent entry {@link marketingConsent} or
+     * {@link declineMarketingConsent} writes (AGL-3185): who recorded it, which
+     * door, which wording version. The console doors pass the person's own
+     * (`actor: 'person'`); a site's capture surface passes none, which the
+     * reader takes as the person's own act anyway.
+     */
+    marketingConsentSource?: MarketingConsentSource;
+    /**
+     * Order value in cents — rolls into RFM fields (AGL-328).
+     *
+     * WHAT IT COUNTS (AGL-1748). GROSS of the platform fee and GROSS of
+     * refunds — the money the customer handed over, not the money the merchant
+     * kept. Every writer passes the same thing: whatever was actually charged
+     * (`amount_total` for a Stripe path, `totals.totalCents` for POS), never a
+     * figure re-derived from product docs, which is the AGL-1698/AGL-1711
+     * lesson. Gross of the fee because this is a CUSTOMER attribute answering
+     * "what is this person worth to me?", and the fee is a cost of the channel,
+     * not something the buyer failed to spend.
+     *
+     * Refunds are still NOT netted here, and now they are recorded elsewhere
+     * (AGL-1754). `refund.ts` writes `refundedCents`, `refundedOrdersCount` and
+     * `lastRefundAtMs` BESIDE these fields — the shape AGL-1747 chose for the
+     * same question on the orders CSV — rather than decrementing a stored number
+     * whose meaning would then differ between rows written before and after that
+     * commit. So `ltvCents` and `ordersCount` remain gross by definition, and a
+     * READER that wants the net computes `ltvCents - refundedCents`, clamping
+     * only what it ranks on: the difference can be negative for a customer whose
+     * pre-AGL-1748 purchase was never counted and whose refund was, which is a
+     * missing purchase showing itself rather than a corrupt contact. AGL-1753 is
+     * the backfill that reconciles it. See `contact-refund.ts` in the commerce
+     * plugin for the full reasoning and for why a refund never CREATES a contact.
+     *
+     * Passing 0 or omitting it means "no purchase": `ltvCents`, `ordersCount`,
+     * `lastPurchaseAtMs` and `firstPurchaseAtMs` are all left untouched, which
+     * is why a caller that formats the amount into the interaction summary and
+     * forgets this field records a customer who has apparently never bought
+     * anything.
+     */
+    purchaseCents?: number;
+    /**
+     * The currency {@link purchaseCents} is in, lowercase, when the door knows.
+     *
+     * Absent everywhere today, because no order document carries a currency and
+     * every checkout door writes `currency: 'usd'` onto the Stripe line items.
+     * `attributeOrderToEmail` defaults it on that basis and says so. The field
+     * exists so a door that ever charges in something else can pass it, and the
+     * campaign revenue report keeps it in its own bucket rather than adding it
+     * to the dollars.
+     */
+    purchaseCurrency?: string;
+    /**
+     * The campaign this person came from, already resolved by the door.
+     *
+     * ⛔ The ORDER path passes none, and must not start. An order already has
+     * its own join one branch below — `attributeOrderToEmail`, keyed on the
+     * order id — and a second record for the same sale would be the same money
+     * counted twice under two rules. This is the door for the moments an order
+     * does NOT cover: a form submission, a membership sign-up, a booking, a
+     * newsletter capture.
+     *
+     * Resolved rather than raw, for the reason `addHostLead` states: one
+     * visitor action reaches several writers and the touch lookup is paid once.
+     */
+    campaignTouch?: ResolvedCampaignTouch | null;
+    /**
+     * The campaigns the CAPTURE SURFACE is filed under.
+     *
+     * ⚠️ A different fact from {@link campaignTouch} beside it, and the two must
+     * never be folded together. A touch is where the visitor came FROM — an ad,
+     * a link, a browser-supplied label resolved through an allowlist. This is
+     * which campaigns the merchant put the form itself in, which is the
+     * merchant's own act and is true of everybody who fills that form in,
+     * including the visitor who arrived by typing the address.
+     *
+     * ⛔ And it is not consent. Filing a form under a campaign says nothing
+     * about what the person agreed to; `marketingConsent` above is the only
+     * input that records a basis.
+     */
+    campaignIds?: readonly string[];
+    /**
+     * Tags to put on THIS holder's facet (AGL-2602).
+     *
+     * Added to, never replaced, on a merge: a person the merchant tagged by
+     * hand and later imported keeps the hand-written tag beside the file's.
+     */
+    tags?: readonly string[];
+    /**
+     * The profile a door knows about the person — phone, title, company,
+     * address, owner, stage, custom values — written into THIS holder's facet
+     * (AGL-2602). Only the keys present are written, so a door that knows the
+     * phone and nothing else does not blank the title somebody typed.
+     */
+    facet?: UpsertHostContactFacet;
+    /**
+     * The EARLIEST stage that describes what this capture was (AGL-2612).
+     *
+     * Every door names one: a form submission is a `lead`, a newsletter opt-in
+     * or a member sign-up is a `subscriber`, a purchase — an order, a paid
+     * booking — is a `customer`. The rule applied to it is
+     * `advanceContactLifecycleStage`: it fills an empty stage and advances an
+     * earlier one, and never moves anybody back, so a customer who fills in
+     * the contact form is still a customer and a subscriber who then submits
+     * a form becomes a lead. Applied on top of `facet.lifecycleStage` when a
+     * door carries both — the caller's stage is the base and this is its
+     * floor.
+     *
+     * A FLOOR and not a value, which is why it is not the facet field: the
+     * facet's `lifecycleStage` is a SET, the shape the console's create
+     * drawer and the import need — the merchant typed a stage and that is the
+     * stage — and a capture door writing a set would put every returning
+     * customer back to `lead` on their next enquiry. Omitted by the doors
+     * that carry the caller's own stage or none (manual, import, API, a lead
+     * conversion), whose contacts read as "no stage", which is true.
+     */
+    initialLifecycleStage?: ContactLifecycleStage;
+    /**
+     * Told when this capture created a contact (AGL-2605).
+     *
+     * A HOOK rather than an event emitted from here, and the reason is the
+     * dependency direction: the event fan-out lives in `libs/tenant/runtime`,
+     * which imports THIS library for its Firestore handle and its org helpers.
+     * An import back up from here would be a cycle, and the module boundaries
+     * (`scope:data` may depend on data and util only) refuse it besides. So
+     * this module reports the fact and the runtime's `captureHostContact`
+     * turns it into `contactCreated` — every server door goes through that
+     * wrapper, and a door that calls this function directly has chosen to
+     * create contacts nothing can react to.
+     *
+     * Awaited with its own catch, like the order join above: the least
+     * important write on the path, and a failure in it must not cost the
+     * capture that already happened.
+     */
+    onCreated?: (created: HostContactCreated) => void | Promise<void>;
+}
+export declare function upsertHostContact(options: UpsertHostContactOptions): Promise<UpsertHostContactVerdict>;