@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/lockdown.js

@@ -0,0 +1,929 @@
+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.
+ */ /**
+ * Lockdown (AGL-1501): the panic button. ONE state shape and ONE resolver
+ * across four scopes — platform, org, host, user — with precedence
+ * platform > org > host > user.
+ *
+ * This module is deliberately pure: it normalizes the storage carriers into
+ * `LockdownState` and answers "is access locked, and what does the visitor
+ * see". Where the state LIVES differs per scope, because two of the four
+ * scopes already shipped and re-implementing them beside themselves is the
+ * bug class this repo keeps re-learning:
+ *
+ * - **org** — `orgs/{orgId}.suspendedAt` (AGL-202/210), extended here with
+ *   `suspendedReasonCode` / `suspendedMessage` / `suspendedUntilMs`. Every
+ *   existing reader of `suspendedAt` keeps working unchanged.
+ * - **host** — NEW staff-only `suspendedAt` (+ same extensions) on the host
+ *   doc. Deliberately NOT `host.maintenance`: that field is CLIENT-writable
+ *   (the customer's own maintenance switch, AGL-131) and must never double
+ *   as a staff security control the customer could simply switch off.
+ * - **platform** — NEW `lockdowns/platform` doc (Admin-SDK read/write; the
+ *   collection is staff-only in rules).
+ * - **user** — NEW `lockdowns/user--{uid}` doc carrying reason/notice,
+ *   alongside the existing Firebase Auth `disabled` flag + refresh-token
+ *   revocation which do the actual keying-out.
+ *
+ * The un-panic invariant lives in the SERVER verdict helper
+ * (libs/tenant/data/admin lockdown.ts): a verified `staff` claim bypasses
+ * every scope, always — a platform lockdown must never lock out the staff
+ * who can lift it. Nothing in this module may be given a way to override
+ * that.
+ */ // Leaf imports only. `host-naming` imports nothing at all, so the DOMAIN
+// scope's apex check cannot introduce a cycle here.
+import { TENANT_APEX } from "./host-naming.js";
+import { operatorContactLine } from "./operator-identity.js";
+// Also a leaf — `platform-brand` imports nothing — so the same no-cycle
+// argument as `host-naming` above covers it. Staff-surface copy must read
+// the CONFIGURED brand: a self-host operator cannot edit source to rename
+// the product (AGL-2153), and "Aglyn cannot reach the database" is a
+// sentence their operators would be shown about their own install.
+import { PLATFORM_BRAND_NAME } from "./platform-brand.js";
+// The plugin-declared levers (AGL-2940). `plugin-entitlements` reaches only
+// the plugin catalog and the permission registry, neither of which imports
+// anything, so the leaf argument above still holds.
+import { listPluginLockdownFeatures } from "../plugin-manager/plugin-entitlements.js";
+/**
+ * The un-panic invariant, per feature (AGL-1510). At the PLATFORM scope a
+ * verified staff claim bypasses unconditionally — that is unchanged and not
+ * negotiable. A FEATURE lock is narrower, so the bypass is granted only
+ * where it aids incident response, and withheld where a staff action would
+ * be the very thing the lock exists to stop:
+ *
+ * - `uploads: true` — the uploads lock answers a malware report, and the
+ *   staff member responding needs to upload a test asset to verify the fix
+ *   before lifting the lock for everyone.
+ * - `marketplace-installs: true` — same shape: a malicious listing slipped
+ *   review, and reproducing the install is part of investigating it.
+ * - `checkout: false` — a checkout lock answers a billing/Stripe bug, and a
+ *   staff-created checkout session is still a real charge against a real
+ *   card. There is no incident-response step that needs money to move;
+ *   verification belongs in Stripe test mode.
+ * - `signups: false` — an account being created has no staff claim yet, so
+ *   a bypass here could never fire honestly; declaring `false` states that
+ *   rather than leaving a bypass that only a misattributed claim could use.
+ *
+ * A plugin's lever carries its own answer on its declaration.
+ *
+ * Each notice says what is paused AND what still works — a feature lock's
+ * whole point is that everything else keeps serving, and the copy must not
+ * let a narrow pause read as a wider outage. The checkout notice in
+ * particular must NEVER read as a payment failure: "your card was declined"
+ * and "we turned checkout off" are different sentences, and only one of them
+ * sends a customer to their bank.
+ */ const CORE_LOCKDOWN_FEATURES = [
+    {
+        key: 'signups',
+        label: 'New signups',
+        staffBypass: false,
+        notice: {
+            title: 'New signups are paused',
+            body: 'New signups are temporarily paused. Existing accounts can sign in and work as usual.'
+        }
+    },
+    {
+        key: 'uploads',
+        label: 'Media uploads',
+        staffBypass: true,
+        notice: {
+            title: 'Uploads are paused',
+            body: 'Media uploads are temporarily disabled while we address an issue. Your existing media and published sites are unaffected.'
+        }
+    },
+    {
+        key: 'checkout',
+        label: 'Checkout (new subscriptions)',
+        staffBypass: false,
+        notice: {
+            title: 'Checkout is temporarily unavailable',
+            body: 'Checkout is temporarily unavailable — this is not a payment failure, and your account, subscription, and sites are unaffected. Please try again shortly.'
+        },
+        // `marketplace/checkout` creates NEW Stripe checkout sessions exactly
+        // like the billing route (AGL-1545); it is also the front door of a paid
+        // install, so it carries BOTH keys and each keeps its own bypass rule.
+        apiPaths: {
+            exact: [
+                'marketplace/checkout'
+            ]
+        }
+    },
+    {
+        key: 'marketplace-installs',
+        label: 'Marketplace installs',
+        staffBypass: true,
+        notice: {
+            title: 'Marketplace installs are paused',
+            body: 'Installing from the marketplace is temporarily disabled. Everything already installed keeps working.'
+        },
+        // Installs-as-a-class, every artifact kind. `marketplace/update-artifact`
+        // re-copies a publisher's version into the org, which is an install by
+        // another name and the same vector a malicious listing would ride.
+        // Publish/review/report paths map to nothing: a marketplace incident
+        // must not stop publishers reporting or staff reviewing.
+        apiPaths: {
+            exact: [
+                'marketplace/checkout',
+                'marketplace/install',
+                'marketplace/update-artifact'
+            ],
+            prefixes: [
+                'marketplace/install-'
+            ]
+        }
+    }
+];
+/**
+ * Every lever, core first and then the plugin declarations in catalog
+ * order — the list the staff checklist renders and the writer validates
+ * against. Read live rather than snapshotted: plugin declarations arrive
+ * at module scope, which can run after any constant here was evaluated.
+ */ export function listLockdownFeatures() {
+    return [
+        ...CORE_LOCKDOWN_FEATURES,
+        ...listPluginLockdownFeatures()
+    ];
+}
+/** The keys of {@link listLockdownFeatures}, in the same order. */ export function listLockdownFeatureKeys() {
+    return listLockdownFeatures().map((feature)=>feature.key);
+}
+/** One lever's declaration — core or plugin — or `undefined`. */ export function lockdownFeatureDeclaration(key) {
+    if (typeof key !== 'string') return undefined;
+    return listLockdownFeatures().find((feature)=>feature.key === key);
+}
+export function isLockdownFeatureKey(value) {
+    return lockdownFeatureDeclaration(value) !== undefined;
+}
+/** Staff-surface label; the key stays the wire/API identity. */ export function lockdownFeatureLabel(key) {
+    var _ref;
+    var _lockdownFeatureDeclaration;
+    return (_ref = (_lockdownFeatureDeclaration = lockdownFeatureDeclaration(key)) == null ? void 0 : _lockdownFeatureDeclaration.label) != null ? _ref : key;
+}
+/**
+ * Whether a verified staff claim passes this feature's lock. A key nothing
+ * declared answers `false`: an undeclared lever has no bypass argument on
+ * record, and the safe reading of "no argument" is "no bypass".
+ */ export function lockdownFeatureStaffBypass(key) {
+    var _lockdownFeatureDeclaration;
+    return ((_lockdownFeatureDeclaration = lockdownFeatureDeclaration(key)) == null ? void 0 : _lockdownFeatureDeclaration.staffBypass) === true;
+}
+const LOCKDOWN_MODE_KEYS = {
+    full: true,
+    'read-only': true
+};
+export const LOCKDOWN_MODES = Object.keys(LOCKDOWN_MODE_KEYS);
+export function isLockdownMode(value) {
+    return typeof value === 'string' && value in LOCKDOWN_MODE_KEYS;
+}
+/** The mode of a state, with the absent-means-`full` default applied. */ export function lockdownMode(state) {
+    return (state == null ? void 0 : state.mode) === 'read-only' ? 'read-only' : 'full';
+}
+export function isReadOnlyLockdown(state) {
+    return lockdownMode(state) === 'read-only';
+}
+const LOCKDOWN_ENFORCEMENT_KEYS = {
+    standard: true,
+    takedown: true
+};
+export const LOCKDOWN_ENFORCEMENTS = Object.keys(LOCKDOWN_ENFORCEMENT_KEYS);
+export function isLockdownEnforcement(value) {
+    return typeof value === 'string' && value in LOCKDOWN_ENFORCEMENT_KEYS;
+}
+/** Staff-surface labels; the key stays the wire/API identity. */ export const LOCKDOWN_ENFORCEMENT_LABELS = {
+    standard: `Standard — releases if ${PLATFORM_BRAND_NAME} cannot reach the database`,
+    takedown: `Takedown — keeps holding if ${PLATFORM_BRAND_NAME} cannot reach the database`
+};
+/**
+ * The enforcement class of a state, with the absent-means-`standard`
+ * default applied. Read through this, never bare — an unrecognised value
+ * must land on the fail-open default rather than on a truthiness test that
+ * would make any junk string fail closed.
+ */ export function lockdownEnforcement(state) {
+    return (state == null ? void 0 : state.enforcement) === 'takedown' ? 'takedown' : 'standard';
+}
+/**
+ * Is this the class that must survive an unreadable carrier? The ONE
+ * predicate the fail-closed path reduces to, so "what is a takedown" has a
+ * single definition rather than one per reader.
+ */ export function isTakedownLockdown(state) {
+    return lockdownEnforcement(state) === 'takedown';
+}
+/**
+ * HTTP method → intent. The safe-method set from RFC 9110 minus TRACE (which
+ * nothing here serves): a method not on this list mutates until proven
+ * otherwise.
+ *
+ * A route whose POST is really a query (`where-used`, `plugin-impact`,
+ * validators) states `intent: 'read'` explicitly rather than being guessed at
+ * from a path.
+ */ export function lockdownIntentForMethod(method) {
+    const normalized = typeof method === 'string' ? method.toUpperCase() : '';
+    return normalized === 'GET' || normalized === 'HEAD' || normalized === 'OPTIONS' ? 'read' : 'write';
+}
+/**
+ * Does this state refuse a request of this intent? The ONE predicate every
+ * chokepoint's discrimination reduces to — a full lock refuses everything, a
+ * read-only lock refuses writes only.
+ *
+ * Note what is NOT here: the staff bypass. That lives above every read in the
+ * server verdict helper and must not acquire a second, mode-shaped copy
+ * — "staff bypass unless…" is how an un-panic invariant stops being one.
+ */ export function lockdownBlocks(state, intent) {
+    if (!state) return false;
+    return lockdownMode(state) === 'full' || intent === 'write';
+}
+const LOCKDOWN_REASON_CODE_KEYS = {
+    security: true,
+    billing: true,
+    maintenance: true,
+    manual: true
+};
+export const LOCKDOWN_REASON_CODES = Object.keys(LOCKDOWN_REASON_CODE_KEYS);
+export function isLockdownReasonCode(value) {
+    return typeof value === 'string' && value in LOCKDOWN_REASON_CODE_KEYS;
+}
+/**
+ * `lockdowns/{id}` — the carrier for the two scopes that had none.
+ * Doc ids are scope-encoded so a lookup is a single `get`:
+ * `platform` and `user--{uid}`. Plain-number timestamps on purpose: the
+ * collection is Admin-SDK-only and converter-free, so a partial write can
+ * never run a converter that "defaults" a sibling field away (the
+ * withConverter-on-partial-writes bug class).
+ */ export const LOCKDOWNS_COLLECTION = 'lockdowns';
+export const PLATFORM_LOCKDOWN_DOC_ID = 'platform';
+export const userLockdownDocId = (uid)=>`user--${uid}`;
+/** `feature--{key}` — same collection, same rules, same audited writer. */ export const featureLockdownDocId = (feature)=>`feature--${feature}`;
+/**
+ * `feature--{key}--org--{orgId}` — the same capability switched off for ONE
+ * workspace (AGL-2927). The carrier the staff org page's AI pause writes:
+ * a spend stop that touches neither the org's entitlements nor its plan, so
+ * lifting it restores exactly what the customer bought. Read only by the
+ * doors that carry that feature key and name the org, and never implied by
+ * the platform-wide document's absence.
+ */ export const orgFeatureLockdownDocId = (feature, orgId)=>`feature--${feature}--org--${orgId}`;
+/**
+ * `domain--{hostname}` — the DOMAIN scope's carrier (AGL-1513).
+ *
+ * ## Keyed on the hostname, deliberately not on the host id
+ *
+ * Every other narrow scope keys on the thing it locks: a user by uid, a host
+ * by host id. A domain lock cannot, because the incidents it exists for are
+ * exactly the ones where the domain moves. A hijacked or disputed domain gets
+ * detached and re-attached — to another site, or to another org — and a lock
+ * keyed on `hosts/{id}` would be left guarding whichever site the name has
+ * since left. Keying on the NAME means the lock follows the name, survives
+ * detach/re-attach, and can be placed on a domain that is not currently
+ * attached to anything at all, which is the state a dispute is usually
+ * resolved in.
+ *
+ * The hostname is lowercased and used verbatim; the caller is responsible for
+ * having validated it as a hostname, and the writer does. Firestore document
+ * ids may contain dots, so `example.com` needs no escaping — and the `domain--`
+ * prefix keeps the key space disjoint from `user--`/`feature--` in the shared
+ * collection.
+ */ export const domainLockdownDocId = (hostname)=>`domain--${hostname.trim().toLowerCase()}`;
+/** A bare hostname: labels of a-z0-9/dash, at least two of them. */ const LOCKABLE_DOMAIN_PATTERN = /^(?!-)[a-z0-9-]{1,63}(\.(?!-)[a-z0-9-]{1,63})+$/;
+/** The DNS limit; also what keeps the document id bounded. */ export const LOCKABLE_DOMAIN_MAX = 253;
+/**
+ * Whether `value` is a name the DOMAIN scope will accept (AGL-1513).
+ *
+ * Shared by the writer and anything that builds the doc id, so "what is a
+ * lockable name" has one definition. Two refusals matter:
+ *
+ *  - **Not hostname-shaped.** The id is derived from this string, and it
+ *    arrives from a staff form; `isDocumentId`-style discipline starts by
+ *    not minting a document for junk in the first place.
+ *  - **Inside the platform apex.** `{sub}.aglyn.app` is OUR name, and the
+ *    tenant resolves that space by `subdomain` and never consults the domain
+ *    scope for it — so a lock placed there would write a document that no
+ *    reader ever looks at. Refusing is the difference between "you cannot do
+ *    that" and a control that silently does nothing, which is the worse of
+ *    the two by a distance. Taking a platform subdomain down is the HOST
+ *    scope's job.
+ */ export function isLockableDomain(value) {
+    if (typeof value !== 'string') return false;
+    const domain = value.trim().toLowerCase();
+    if (!domain || domain.length > LOCKABLE_DOMAIN_MAX) return false;
+    if (!LOCKABLE_DOMAIN_PATTERN.test(domain)) return false;
+    return domain !== TENANT_APEX && !domain.endsWith(`.${TENANT_APEX}`);
+}
+/** Staff-typed notice text is user-facing; keep it bounded and plain. */ export const LOCKDOWN_MESSAGE_MAX = 500;
+/**
+ * Tolerant epoch-ms reader: Firestore `Timestamp`, `{ seconds }` JSON, a
+ * number of ms, or an ISO string — the org carrier's `suspendedAt` arrives
+ * in all of these shapes depending on which cache serialized it.
+ */ export function toEpochMs(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    if (typeof value === 'object') {
+        var _record_seconds;
+        const record = value;
+        if (typeof record.toMillis === 'function') {
+            try {
+                return record.toMillis();
+            } catch (unused) {
+                return undefined;
+            }
+        }
+        const seconds = (_record_seconds = record.seconds) != null ? _record_seconds : record._seconds;
+        if (typeof seconds === 'number' && Number.isFinite(seconds)) {
+            return seconds * 1000;
+        }
+    }
+    return undefined;
+}
+/**
+ * Active now? Expiry passing deactivates without any write.
+ *
+ * Typed on the only field it reads rather than on `LockdownState`, so the
+ * sibling levers built on the same field family — asset quarantine
+ * (AGL-1512) — share this definition of "expired" instead of restating it.
+ * A second copy is how two panic levers end up disagreeing about whether a
+ * window that closed one millisecond ago is still in force.
+ */ export function isLockdownActive(state, nowMs) {
+    if (!state) return false;
+    if (typeof state.untilMs === 'number' && state.untilMs <= nowMs) return false;
+    return true;
+}
+/**
+ * How long the blocking function waits on the lock read before deciding
+ * without it.
+ *
+ * Blocking functions sit on the account-creation critical path and Identity
+ * Platform gives them a bounded window, so an unbounded `get()` would hand
+ * the decision to the platform's own timeout — which refuses, after burning
+ * the whole budget and with no log saying why. Bounding it keeps the verdict
+ * here, where it can be reasoned about and recorded.
+ */ export const SIGNUPS_CREATION_LOCK_READ_TIMEOUT_MS = 2500;
+/**
+ * What the last COMPLETED read saw, for the life of this instance.
+ * `undefined` means no read has completed here yet — the state a cold
+ * instance starts in, and the only one that cannot hold a lock.
+ *
+ * Not a cache: it is never consulted in place of a read, only in place of
+ * one that failed, so it can never make this gate slower to notice a lift
+ * than the lift's own write.
+ */ let lastReadSignupsLock;
+/**
+ * Forget it. Not part of any panic path — this exists for process
+ * boundaries and for tests, where one case's lock would otherwise become the
+ * next case's refusal.
+ */ export function resetSignupsLockMemory() {
+    lastReadSignupsLock = undefined;
+}
+/**
+ * Is this state an engaged lock at `nowMs`?
+ *
+ * Deliberately stricter than `normalizeLockdownDoc`, which refuses to
+ * interpret a malformed doc and so reports NOT LOCKED. Here the document's
+ * existence is the lever: the only writer is the audited staff route, so a
+ * doc that exists at all means someone pulled it, and a field this build
+ * cannot parse must never un-pull it. An expiry that has passed deactivates
+ * with no write, matching `isLockdownActive` exactly (the sibling test pins
+ * that equivalence).
+ */ function signupsLockEngaged(state, nowMs) {
+    if (state === null || state === undefined) return false;
+    return !(typeof state.untilMs === 'number' && state.untilMs <= nowMs);
+}
+/**
+ * Refuse this account creation?
+ *
+ * `readLock` returns the `lockdowns/feature--signups` document, or null when
+ * it does not exist. It is injected rather than imported so this decision —
+ * including its fail-open and timeout behavior — is testable without a
+ * Firestore, and so the same characters run in the function and in the test.
+ *
+ * NOT parameterized by provider, by email, or by tenant. Email/password,
+ * Google and SSO all reach Firebase Auth account creation, and a lock that
+ * discriminated between them would be a lock on one gate of three. The
+ * caller passes no identity at all, so no future edit can quietly add a
+ * carve-out here.
+ */ export async function signupsCreationVerdict(readLock, nowMs, timeoutMs = SIGNUPS_CREATION_LOCK_READ_TIMEOUT_MS) {
+    let timer;
+    let state;
+    try {
+        state = await Promise.race([
+            readLock(),
+            new Promise((_resolve, reject)=>{
+                timer = setTimeout(()=>reject(new Error('signups lock read timed out')), timeoutMs);
+            })
+        ]);
+    } catch (unused) {
+        // Nothing was learned, so the only thing that can refuse now is what an
+        // earlier read established. A remembered lock whose window has closed is
+        // dropped here rather than re-examined on every later failure.
+        if (signupsLockEngaged(lastReadSignupsLock, nowMs)) {
+            return {
+                refused: true,
+                cause: 'held'
+            };
+        }
+        lastReadSignupsLock = undefined;
+        return {
+            refused: false,
+            unreadable: true
+        };
+    } finally{
+        if (timer !== undefined) clearTimeout(timer);
+    }
+    // A completed read is the whole truth, "no document" included: it decides
+    // this account AND replaces whatever was remembered, which is how a lift
+    // takes effect.
+    lastReadSignupsLock = state != null ? state : null;
+    return signupsLockEngaged(state, nowMs) ? {
+        refused: true,
+        cause: 'locked'
+    } : {
+        refused: false
+    };
+}
+// #endregion signups-creation-lock
+/**
+ * Precedence: platform > org > host > domain > user. The widest active scope wins so
+ * the notice a visitor sees names the real cause (a platform maintenance
+ * window should not read as "this account is suspended").
+ *
+ * STRICTNESS OUTRANKS WIDTH (AGL-1511). Once locks have a mode, "widest
+ * wins" alone is a security hole: a platform-wide read-only maintenance
+ * window would outrank — and therefore SOFTEN — a full security takedown on
+ * one org, quietly readmitting every visitor to the site staff just took
+ * down. So an active `full` lock is chosen first (in scope order among the
+ * full ones), and the widest read-only lock only wins when no full lock is
+ * active at all. A lock can never be relaxed by a wider, gentler one.
+ */ export function resolveLockdown(states, nowMs) {
+    var _ref, _active_find;
+    const active = [
+        states.platform,
+        states.org,
+        states.host,
+        states.domain,
+        states.user
+    ].filter((state)=>Boolean(state) && isLockdownActive(state, nowMs));
+    return (_ref = (_active_find = active.find((state)=>lockdownMode(state) === 'full')) != null ? _active_find : active[0]) != null ? _ref : null;
+}
+/**
+ * Org carrier → state. `suspendedAt` alone (every pre-lockdown suspension)
+ * normalizes to `manual` with no public message — the legacy free-text
+ * `suspendedReason` was written for staff eyes and must not leak into the
+ * visitor notice.
+ */ export function normalizeOrgLockdown(org) {
+    if (!org || org.suspendedAt == null) return null;
+    return _extends({
+        scope: 'org'
+    }, org.suspendedMode === 'read-only' ? {
+        mode: 'read-only'
+    } : {}, org.suspendedEnforcement === 'takedown' ? {
+        enforcement: 'takedown'
+    } : {}, {
+        reason: isLockdownReasonCode(org.suspendedReasonCode) ? org.suspendedReasonCode : 'manual',
+        message: typeof org.suspendedMessage === 'string' && org.suspendedMessage ? org.suspendedMessage.slice(0, LOCKDOWN_MESSAGE_MAX) : undefined,
+        atMs: toEpochMs(org.suspendedAt),
+        untilMs: typeof org.suspendedUntilMs === 'number' && Number.isFinite(org.suspendedUntilMs) ? org.suspendedUntilMs : undefined
+    });
+}
+/**
+ * Host carrier → state. Same field family as the org, on the host doc.
+ * `host.maintenance` is NOT consulted here — that is the customer's own
+ * switch and keeps its shipped AGL-131 path.
+ */ export function normalizeHostLockdown(host) {
+    if (!host || host.suspendedAt == null) return null;
+    return _extends({
+        scope: 'host'
+    }, host.suspendedMode === 'read-only' ? {
+        mode: 'read-only'
+    } : {}, host.suspendedEnforcement === 'takedown' ? {
+        enforcement: 'takedown'
+    } : {}, {
+        reason: isLockdownReasonCode(host.suspendedReasonCode) ? host.suspendedReasonCode : 'manual',
+        message: typeof host.suspendedMessage === 'string' && host.suspendedMessage ? host.suspendedMessage.slice(0, LOCKDOWN_MESSAGE_MAX) : undefined,
+        atMs: toEpochMs(host.suspendedAt),
+        untilMs: typeof host.suspendedUntilMs === 'number' && Number.isFinite(host.suspendedUntilMs) ? host.suspendedUntilMs : undefined
+    });
+}
+/** `lockdowns/{id}` doc → state; refuses malformed docs rather than guess. */ export function normalizeLockdownDoc(doc, scope) {
+    if (!doc) return null;
+    if (!isLockdownReasonCode(doc.reason)) return null;
+    // A feature doc whose key is not (or no longer) in the enum is refused
+    // whole, matching the malformed-reason posture: the panic path does not
+    // guess, and an unknown key has no chokepoint to enforce it anyway.
+    if (scope === 'feature' && !isLockdownFeatureKey(doc.feature)) return null;
+    return _extends({
+        scope
+    }, scope === 'feature' && isLockdownFeatureKey(doc.feature) ? {
+        feature: doc.feature
+    } : {}, scope === 'feature' && typeof doc.orgId === 'string' && doc.orgId ? {
+        orgId: doc.orgId
+    } : {}, doc.mode === 'read-only' ? {
+        mode: 'read-only'
+    } : {}, doc.enforcement === 'takedown' ? {
+        enforcement: 'takedown'
+    } : {}, {
+        reason: doc.reason,
+        message: typeof doc.message === 'string' && doc.message ? doc.message.slice(0, LOCKDOWN_MESSAGE_MAX) : undefined,
+        atMs: typeof doc.atMs === 'number' ? doc.atMs : undefined,
+        untilMs: typeof doc.untilMs === 'number' && Number.isFinite(doc.untilMs) ? doc.untilMs : undefined,
+        actorUid: typeof doc.actorUid === 'string' ? doc.actorUid : undefined
+    });
+}
+/**
+ * `Retry-After` seconds for a 503, when the lockdown has a known end.
+ * Clamped to at least 60 so a window expiring mid-request cannot emit 0.
+ */ export function lockdownRetryAfterSeconds(state, nowMs) {
+    if (typeof state.untilMs !== 'number') return undefined;
+    return Math.max(60, Math.ceil((state.untilMs - nowMs) / 1000));
+}
+/**
+ * The address on the visitor-facing 503, from operator configuration
+ * (AGL-2016).
+ *
+ * Was a `'support@aglyn.com'` literal read by eleven call sites below. A
+ * self-hosted site that went into lockdown therefore told *its* visitors to
+ * write to **Aglyn** about an account Aglyn has no record of and cannot
+ * restore. Unlike the abuse form this is not a legal misroute, but it is the
+ * same class of wrong answer: the only party who can lift the lock is the
+ * operator who set it.
+ *
+ * Returns `null` when unconfigured, which the notice treats as "no contact
+ * line" — the same shape `maintenance` already uses. A lockdown notice with a
+ * dangling "contact " and nothing after it would be worse than one that
+ * simply does not offer a channel the deployment does not have.
+ */ export function lockdownSupportEmail() {
+    return operatorContactLine('support').address;
+}
+/**
+ * Per-reason visitor copy — plain and non-alarming. A staff-typed `message`
+ * replaces the body; the title and contact line stay per-reason so staff
+ * cannot accidentally strip the "how do I get out of this" affordance.
+ */ export function lockdownNotice(state) {
+    const custom = typeof state.message === 'string' && state.message.trim() ? state.message.trim() : undefined;
+    // Feature locks carry feature-specific, honest copy (AGL-1510): what is
+    // off, and — just as important — what is NOT affected. Same convention as
+    // the per-reason copy below: a staff message replaces the body only.
+    if (state.scope === 'feature' && state.feature) {
+        return featureLockdownNotice(state.feature, custom, state.untilMs);
+    }
+    // A read-only lock refused a WRITE, and the full-lock copy would lie about
+    // it: "Access is temporarily disabled" is false on a site the reader is
+    // currently looking at (AGL-1511).
+    if (isReadOnlyLockdown(state)) {
+        return readOnlyLockdownNotice(state, custom);
+    }
+    // DOMAIN scope (AGL-1513). The site is fine and is still serving on its
+    // other addresses; this NAME is the thing that is not, and the copy says
+    // that much and no more.
+    if (state.scope === 'domain') {
+        return domainLockdownNotice(state, custom);
+    }
+    switch(state.reason){
+        case 'maintenance':
+            {
+                const until = typeof state.untilMs === 'number' ? new Date(state.untilMs).toUTCString() : undefined;
+                return {
+                    title: 'Down for maintenance',
+                    body: custom != null ? custom : until ? `Scheduled maintenance is in progress. Expected back by ${until}.` : 'Scheduled maintenance is in progress. Please check back shortly.'
+                };
+            }
+        case 'billing':
+            var _lockdownSupportEmail;
+            return {
+                title: 'Account on hold',
+                body: custom != null ? custom : 'This account is on hold over an unresolved billing issue. ' + 'Updating the payment method in workspace billing settings ' + 'restores access.',
+                contact: (_lockdownSupportEmail = lockdownSupportEmail()) != null ? _lockdownSupportEmail : undefined
+            };
+        case 'security':
+            var _lockdownSupportEmail1;
+            return {
+                title: 'Temporarily unavailable',
+                body: custom != null ? custom : 'Access is temporarily disabled while we investigate a security ' + 'concern.',
+                contact: (_lockdownSupportEmail1 = lockdownSupportEmail()) != null ? _lockdownSupportEmail1 : undefined
+            };
+        case 'manual':
+        default:
+            var _lockdownSupportEmail2;
+            return {
+                title: 'Temporarily unavailable',
+                body: custom != null ? custom : 'Access to this account is currently disabled.',
+                contact: (_lockdownSupportEmail2 = lockdownSupportEmail()) != null ? _lockdownSupportEmail2 : undefined
+            };
+    }
+}
+/**
+ * DOMAIN copy (AGL-1513), for a visitor who typed one particular name.
+ *
+ * ## It must never name the address that still works
+ *
+ * Every other scope's copy can afford to be helpful, because the thing being
+ * withheld is the thing the reader is entitled to. This scope exists for
+ * ownership disputes and hijacked or expired domains now pointing at us — so
+ * the person reading this notice may be precisely the party the site is being
+ * withheld from, and "try acme.aglyn.app instead" would lift the lock in one
+ * sentence. None of these bodies names the platform subdomain, and none
+ * should acquire one; the `*.aglyn.app` address is deliberately absent rather
+ * than accidentally missing.
+ *
+ * ## It also does not say whose the name is
+ *
+ * A dispute is exactly the case where we do not know, and a notice is a
+ * publication. "Not currently serving" is the whole of what we can assert
+ * without taking a side in something a registrar or a court settles.
+ */ function domainLockdownNotice(state, custom) {
+    var _lockdownSupportEmail;
+    const title = 'This address is unavailable';
+    const contact = (_lockdownSupportEmail = lockdownSupportEmail()) != null ? _lockdownSupportEmail : undefined;
+    switch(state.reason){
+        case 'maintenance':
+            return {
+                title,
+                body: custom != null ? custom : 'This web address is temporarily not serving while maintenance ' + 'is in progress.',
+                contact
+            };
+        case 'billing':
+            return {
+                title,
+                body: custom != null ? custom : 'This web address is not currently serving over an unresolved ' + 'billing issue.',
+                contact
+            };
+        case 'security':
+            return {
+                title,
+                body: custom != null ? custom : 'This web address is not currently serving while we investigate ' + 'a report about it.',
+                contact
+            };
+        case 'manual':
+        default:
+            return {
+                title,
+                body: custom != null ? custom : 'This web address is not currently serving.',
+                contact
+            };
+    }
+}
+/**
+ * READ-ONLY copy (AGL-1511), for the account holder whose save just refused.
+ *
+ * The whole point of this mode is that the reader is still looking at their
+ * work while being told they cannot change it, so every sentence has to hold
+ * both halves at once: nothing is down, nothing is lost, one verb is paused.
+ * The full-lock titles ("Temporarily unavailable", "Account on hold") are
+ * flatly untrue here and would send someone to support over a fifteen-minute
+ * migration.
+ *
+ * The `until` sentence is built with the SAME `lockdownUntilSuffix` helper
+ * the feature copy uses, so `parseLockdownRefusal` strips and re-renders it
+ * in the reader's local time here too rather than showing a UTC stamp.
+ */ function readOnlyLockdownNotice(state, custom) {
+    const window = typeof state.untilMs === 'number' ? ` ${lockdownUntilSuffix(state.untilMs)}` : '';
+    const title = 'Changes are temporarily paused';
+    switch(state.reason){
+        case 'maintenance':
+            return {
+                title,
+                body: custom != null ? custom : `Saving changes is paused while we complete scheduled maintenance. ` + `Your sites keep serving and nothing you have created is ` + `affected — changes will save again shortly.${window}`
+            };
+        case 'billing':
+            var _lockdownSupportEmail;
+            return {
+                title,
+                body: custom != null ? custom : `Saving changes is paused over an unresolved billing issue. Your ` + `sites keep serving and nothing has been deleted — updating the ` + `payment method in workspace billing settings restores ` + `editing.${window}`,
+                contact: (_lockdownSupportEmail = lockdownSupportEmail()) != null ? _lockdownSupportEmail : undefined
+            };
+        case 'security':
+        case 'manual':
+        default:
+            var _lockdownSupportEmail1;
+            return {
+                title,
+                body: custom != null ? custom : `Saving changes is paused while we work on something. Your sites ` + `keep serving and nothing you have created is affected — ` + `changes will save again shortly.${window}`,
+                contact: (_lockdownSupportEmail1 = lockdownSupportEmail()) != null ? _lockdownSupportEmail1 : undefined
+            };
+    }
+}
+/**
+ * VISITOR copy for a read-only refusal on a tenant site (AGL-1511).
+ *
+ * The issue's central product call: a customer's site staying up and earning
+ * is the entire reason this mode exists instead of full lockdown, so a
+ * visitor-facing write gets a polite inline pause, never a page-level 503.
+ * That decision only pays off if the words match it — a visitor shown
+ * "Temporarily unavailable" on a page that plainly loaded concludes the shop
+ * is broken and leaves, which costs the customer the sale the mode was
+ * protecting.
+ *
+ * So: no mention of maintenance windows, workspaces or accounts (none of
+ * which are the visitor's), no support address (support is the SITE
+ * owner's, not ours, and pointing a stranger at aglyn.com is worse than
+ * silent), an explicit "nothing you typed is lost", and — for checkout — the
+ * same hard rule the feature copy carries: this must never read as a
+ * declined card. A staff-typed `message` is deliberately NOT honoured here;
+ * it is written for the account holder and would land in front of strangers.
+ */ export function lockdownPausedNotice(surface) {
+    switch(surface){
+        case 'form':
+            return {
+                title: 'Temporarily paused',
+                body: 'This form is not accepting submissions for a few minutes. ' + 'Nothing you typed has been lost — please try again shortly.'
+            };
+        case 'checkout':
+            return {
+                title: 'Checkout is temporarily paused',
+                body: 'Checkout is paused for a few minutes — this is not a payment ' + 'problem and you have not been charged. Your basket is safe; ' + 'please try again shortly.'
+            };
+        case 'cart':
+            return {
+                title: 'Temporarily paused',
+                body: 'Basket changes are paused for a few minutes. Browsing works as ' + 'normal — please try again shortly.'
+            };
+        case 'generic':
+        default:
+            return {
+                title: 'Temporarily paused',
+                body: 'This action is paused for a few minutes. Browsing works as ' + 'normal — please try again shortly.'
+            };
+    }
+}
+/**
+ * Per-feature visitor copy (AGL-1510), read off the lever's declaration —
+ * core or plugin — so a plugin's lever explains itself in its own words. A
+ * key nothing declared (a document written before its plugin was removed)
+ * gets the generic pause: the lock is still honored, it just cannot name
+ * what it pauses.
+ */ function featureLockdownNotice(feature, custom, untilMs) {
+    var _ref, _ref1, _lockdownSupportEmail;
+    const window = typeof untilMs === 'number' ? ` Expected back by ${new Date(untilMs).toUTCString()}.` : '';
+    const declared = lockdownFeatureDeclaration(feature);
+    return {
+        title: (_ref = declared == null ? void 0 : declared.notice.title) != null ? _ref : 'Temporarily paused',
+        body: custom != null ? custom : `${(_ref1 = declared == null ? void 0 : declared.notice.body) != null ? _ref1 : 'This action is paused for a few minutes. Browsing works as normal — please try again shortly.'}${window}`,
+        contact: (_lockdownSupportEmail = lockdownSupportEmail()) != null ? _lockdownSupportEmail : undefined
+    };
+}
+/**
+ * The generic-but-honest fallback: what a client says when the server said
+ * Locked but the body told it nothing else. It must still be TRUE — "this is
+ * paused", never "something went wrong" (the failure this whole affordance
+ * exists to stop), and never the word `undefined`.
+ */ export const LOCKDOWN_REFUSAL_FALLBACK_TITLE = 'Temporarily unavailable';
+export const LOCKDOWN_REFUSAL_FALLBACK_MESSAGE = 'This is temporarily paused while we work on something. Nothing you have ' + 'created is affected — please try again shortly.';
+/**
+ * The exact sentence the notice builders append to a DEFAULT body when a
+ * lock has an expiry. Built here so the client parser can strip it by exact
+ * match (same `untilMs`, same string) instead of sniffing a regex.
+ */ function lockdownUntilSuffix(untilMs) {
+    return `Expected back by ${new Date(untilMs).toUTCString()}.`;
+}
+/**
+ * The expiry as a client-side, LOCAL-time line (AGL-1532). A UTC string is
+ * correct and unreadable; a customer wants to know when to come back on
+ * their own clock.
+ */ export function formatLockdownUntil(untilMs) {
+    if (!Number.isFinite(untilMs)) return undefined;
+    const when = new Date(untilMs);
+    if (Number.isNaN(when.getTime())) return undefined;
+    const stamp = when.toLocaleString(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short'
+    });
+    return `Expected back around ${stamp}.`;
+}
+/**
+ * Parse a fetch response's status + parsed JSON body into a renderable
+ * lockdown notice, or `null` when this was not a lockdown refusal
+ * (AGL-1532).
+ *
+ * ONE parser, used by every client call site a feature lock can refuse —
+ * billing checkout, marketplace installs and purchases, the AI-assist
+ * drawer. Three copies of this parsing is the second-implementation shape
+ * that lets one surface drift back to "checkout failed" while the others
+ * stay honest.
+ *
+ * Three rules, each of which a spec pins:
+ *
+ *  1. **Only 423.** A 500 — a real, unexplained failure — returns `null` so
+ *     the caller keeps its generic error toast. Dressing a genuine fault as
+ *     a deliberate pause is a worse lie than the one being fixed.
+ *  2. **A 423 always yields a notice.** The server said Locked; that is the
+ *     honest thing to render even if the body is malformed, truncated by a
+ *     proxy, or from an older deploy. Missing fields degrade to the shared
+ *     per-feature copy when the body names a known feature, and to the
+ *     generic-but-honest fallback otherwise.
+ *  3. **No duplicated expiry.** The default server copy already ends with a
+ *     UTC "Expected back by …" sentence; that exact suffix is stripped and
+ *     restated as `until` in the reader's local time. A staff-typed custom
+ *     message never carries the suffix, so nothing is stripped from it.
+ */ export function parseLockdownRefusal(status, body) {
+    var _ref, _ref1;
+    if (status !== 423) return null;
+    const payload = body && typeof body === 'object' ? body : {};
+    const feature = isLockdownFeatureKey(payload.feature) ? payload.feature : undefined;
+    const untilMs = typeof payload.untilMs === 'number' && Number.isFinite(payload.untilMs) ? payload.untilMs : undefined;
+    // A body that named a feature but lost its copy still gets the RIGHT
+    // words — the same ones the server would have sent — because that copy
+    // lives here too. Only a body naming nothing falls all the way back.
+    const derived = feature ? featureLockdownNotice(feature, undefined, untilMs) : undefined;
+    const title = typeof payload.title === 'string' && payload.title.trim() ? payload.title.trim() : (_ref = derived == null ? void 0 : derived.title) != null ? _ref : LOCKDOWN_REFUSAL_FALLBACK_TITLE;
+    let message = typeof payload.message === 'string' && payload.message.trim() ? payload.message.trim() : (_ref1 = derived == null ? void 0 : derived.body) != null ? _ref1 : LOCKDOWN_REFUSAL_FALLBACK_MESSAGE;
+    if (typeof untilMs === 'number') {
+        const suffix = lockdownUntilSuffix(untilMs);
+        if (message.endsWith(suffix)) {
+            message = message.slice(0, -suffix.length).trim();
+        }
+    }
+    const contact = typeof payload.contact === 'string' && payload.contact.trim() ? payload.contact.trim() : undefined;
+    const until = typeof untilMs === 'number' ? formatLockdownUntil(untilMs) : undefined;
+    return _extends({
+        title,
+        message
+    }, contact ? {
+        contact
+    } : {}, typeof payload.scope === 'string' ? {
+        scope: payload.scope
+    } : {}, feature ? {
+        feature
+    } : {}, isLockdownMode(payload.mode) ? {
+        mode: payload.mode
+    } : {}, typeof untilMs === 'number' ? {
+        untilMs
+    } : {}, until ? {
+        until
+    } : {});
+}
+/**
+ * The notice as ONE line, for surfaces whose only affordance is a snackbar
+ * (AGL-1532). The title is prefixed only when the message does not already
+ * open with it — the checkout copy leads with its own title, and "Checkout
+ * is temporarily unavailable — Checkout is temporarily unavailable — this is
+ * not a payment failure" helps nobody.
+ */ export function lockdownRefusalText(notice) {
+    const lower = notice.message.toLowerCase();
+    const led = lower.startsWith(notice.title.toLowerCase());
+    const head = led ? notice.message : `${notice.title} — ${notice.message}`;
+    return notice.until ? `${head} ${notice.until}` : head;
+}
+/**
+ * Which VISITOR surface a tenant plugin-API path belongs to, for read-only
+ * pause copy (AGL-1511).
+ *
+ * The tenant dispatcher refuses every mutating method under a read-only lock
+ * regardless of path — this only chooses the WORDS, and it exists because
+ * the checkout sentence has a requirement no generic copy can carry: it must
+ * never read as a declined card. Anything unrecognised gets the neutral
+ * generic pause rather than a guess; being vague at a stranger is cheap,
+ * being wrong about their money is not.
+ */ export function lockdownPausedSurfaceForPluginApiPath(path) {
+    if (path === 'commerce/checkout' || path === 'commerce/cart-checkout' || path === 'commerce/pos-order' || path === 'commerce/draft-order') {
+        return 'checkout';
+    }
+    if (path === 'commerce/cart' || path.startsWith('commerce/cart/')) return 'cart';
+    return 'generic';
+}
+/**
+ * Which feature keys gate a plugin-API dispatcher path (AGL-1510, plural
+ * since AGL-1545). Lives here (pure, beside the catalog) so the dispatcher's
+ * wiring is one call and the mapping is unit-testable without a route
+ * harness.
+ *
+ * Every lever declares the paths it gates: exact paths, and prefixes matched
+ * on a SEGMENT boundary, so `ai/generate` gates `ai/generate/section` and
+ * never `ai/generated-report`. A path several levers name is gated by all
+ * of them, each keeping its own staff-bypass rule when composed —
+ * `marketplace/checkout` carries both `checkout` and `marketplace-installs`
+ * (AGL-1545): it creates NEW Stripe checkout sessions exactly like the
+ * billing route, and it is also the front door of a paid install, so a
+ * malicious-listing incident must stop buyers PAYING for the artifact under
+ * investigation, not merely refuse the install after the money moved.
+ *
+ * A plugin's lever gates its paths by existing (AGL-2903): a door
+ * registered under a declared prefix is gated before anyone remembers to
+ * wire it, which is the reason the mapping is declared beside the lever
+ * rather than beside the route.
+ */ export function lockdownFeaturesForPluginApiPath(path) {
+    const keys = [];
+    for (const feature of listLockdownFeatures()){
+        var _ref, _ref1;
+        var _feature_apiPaths, _feature_apiPaths1;
+        const exact = (_ref = (_feature_apiPaths = feature.apiPaths) == null ? void 0 : _feature_apiPaths.exact) != null ? _ref : [];
+        const prefixes = (_ref1 = (_feature_apiPaths1 = feature.apiPaths) == null ? void 0 : _feature_apiPaths1.prefixes) != null ? _ref1 : [];
+        const hit = exact.includes(path) || prefixes.some((prefix)=>path === prefix || path.startsWith(prefix.endsWith('/') || prefix.endsWith('-') ? prefix : `${prefix}/`));
+        if (hit && !keys.includes(feature.key)) keys.push(feature.key);
+    }
+    return keys;
+}
+
+//# sourceMappingURL=lockdown.js.map