@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/lockdown.d.ts

@@ -0,0 +1,698 @@
+/**
+ * @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 PluginLockdownFeatureDeclaration } from '../plugin-manager/plugin-entitlements';
+export type LockdownScope = 'platform' | 'org' | 'host' | 'domain' | 'user' | 'feature';
+/**
+ * FEATURE scope (AGL-1510): kill one capability platform-wide while
+ * everything else keeps serving. The launch set maps one-to-one onto the
+ * incident shapes the issue names — bot wave → `signups`, malware report →
+ * `uploads`, billing bug → `checkout`, malicious listing →
+ * `marketplace-installs`. A plugin that can be switched off in an incident
+ * declares its own lever through `registerPluginEntitlements` (AGL-2940):
+ * the label, the staff-bypass rule, the visitor notice and the API paths it
+ * gates all arrive with the declaration, and the staff checklist, the
+ * writer and the dispatcher read the two sets as one.
+ *
+ * Precedence COMPOSES rather than ranks: a platform lock implies every
+ * feature (the feature verdict helpers check platform first), while a
+ * feature lock implies nothing about the platform/org/host/user scopes —
+ * feature states never enter `resolveLockdown`.
+ */
+export type CoreLockdownFeatureKey = 'signups' | 'uploads' | 'checkout' | 'marketplace-installs';
+/**
+ * A lever's wire identity: one of the core four, or a key a plugin
+ * declared. A string rather than a union because the set is only complete
+ * once every declaring plugin has registered, which no type can know.
+ */
+export type LockdownFeatureKey = CoreLockdownFeatureKey | (string & {});
+/**
+ * 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 declare function listLockdownFeatures(): PluginLockdownFeatureDeclaration[];
+/** The keys of {@link listLockdownFeatures}, in the same order. */
+export declare function listLockdownFeatureKeys(): LockdownFeatureKey[];
+/** One lever's declaration — core or plugin — or `undefined`. */
+export declare function lockdownFeatureDeclaration(key: unknown): PluginLockdownFeatureDeclaration | undefined;
+export declare function isLockdownFeatureKey(value: unknown): value is LockdownFeatureKey;
+/** Staff-surface label; the key stays the wire/API identity. */
+export declare function lockdownFeatureLabel(key: LockdownFeatureKey): string;
+/**
+ * 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 declare function lockdownFeatureStaffBypass(key: LockdownFeatureKey): boolean;
+/**
+ * HOW HARD the lock bites (AGL-1511).
+ *
+ * - `full` — the shipped AGL-1501 behaviour: nothing serves. Sites 503,
+ *   sessions refuse, every API call gets the 423.
+ * - `read-only` — reads keep serving, WRITES refuse. The right shape for the
+ *   most common maintenance need (a schema migration, a data repair, a
+ *   suspected-corruption investigation): the customer's site stays up and
+ *   earning, visitors browse normally, and nothing races the repair.
+ *
+ * ABSENT MEANS `full`. Every lockdown written before this field existed is a
+ * full lock, and a lock whose strictness cannot be read must be treated as
+ * the stricter one — so `full` is both the default and the fail-safe. The
+ * writer stores `mode` only for read-only locks, which keeps every existing
+ * carrier document byte-identical and needs no migration.
+ */
+export type LockdownMode = 'full' | 'read-only';
+export declare const LOCKDOWN_MODES: LockdownMode[];
+export declare function isLockdownMode(value: unknown): value is LockdownMode;
+/** The mode of a state, with the absent-means-`full` default applied. */
+export declare function lockdownMode(state: {
+    mode?: LockdownMode;
+} | null | undefined): LockdownMode;
+export declare function isReadOnlyLockdown(state: {
+    mode?: LockdownMode;
+} | null | undefined): boolean;
+/**
+ * WHAT HAPPENS WHEN WE CANNOT READ THE LOCK (AGL-1621).
+ *
+ * Lockdown fails OPEN: if the carrier read throws, the verdict is "not
+ * locked". That is the right posture for availability — a Firestore blip
+ * must not weld every customer site shut — and the wrong one for a legal or
+ * abuse takedown, where the whole point is that the content stops being
+ * served and STAYS stopped. A DMCA notice is not satisfied by "we served it
+ * because our database was down".
+ *
+ * So the two needs are split on their own axis rather than either one being
+ * bent to fit the other:
+ *
+ * - `standard` — today's behaviour, unchanged. An unreadable lock is not
+ *   enforced. Maintenance windows, billing suspensions, precautionary
+ *   holds, incident response: everything whose cost of over-refusing is
+ *   higher than its cost of under-refusing.
+ * - `takedown` — holds through an infrastructure failure. Legal orders,
+ *   abuse/CSAM removals, domain hijack disputes: the cost of serving is
+ *   higher than the cost of an outage on that one subject.
+ *
+ * ## Why this is its own field and not read off `scope` or `reason`
+ *
+ * NOT `scope`: every one of the six scopes carries both classes. A `host`
+ * lock is a maintenance window on Tuesday and a court-ordered removal on
+ * Wednesday; the scope says WHAT is locked, never why it must hold.
+ *
+ * NOT `reason`: `reason` is already spoken for as the VISITOR-FACING
+ * classifier — it selects the notice copy in `lockdownNotice`. Deriving
+ * fail-closed from `reason === 'security'` would both couple what the
+ * public is told to how the system behaves under failure, and be exactly
+ * the inference this field exists to avoid: most `security` locks are
+ * precautionary holds during an investigation, and those must keep failing
+ * open. A lock that becomes fail-closed because of a heuristic is a lock
+ * that takes a site down for an unrelated reason.
+ *
+ * ABSENT MEANS `standard`, and that direction is the safety property. Every
+ * lock written before this field existed, every lock an operator did not
+ * classify, and every doc whose value this build cannot interpret is
+ * fail-OPEN — the behaviour shipped today. Getting this backwards during a
+ * Firestore incident is the platform-wide outage the split exists to
+ * prevent, so only the exact string `takedown` opts in. Same posture and
+ * same storage discipline as `mode` above: the writer stores the field only
+ * for takedowns, so every existing carrier document stays byte-identical
+ * and no migration is needed.
+ */
+export type LockdownEnforcement = 'standard' | 'takedown';
+export declare const LOCKDOWN_ENFORCEMENTS: LockdownEnforcement[];
+export declare function isLockdownEnforcement(value: unknown): value is LockdownEnforcement;
+/** Staff-surface labels; the key stays the wire/API identity. */
+export declare const LOCKDOWN_ENFORCEMENT_LABELS: Record<LockdownEnforcement, string>;
+/**
+ * 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 declare function lockdownEnforcement(state: {
+    enforcement?: LockdownEnforcement;
+} | null | undefined): LockdownEnforcement;
+/**
+ * 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 declare function isTakedownLockdown(state: {
+    enforcement?: LockdownEnforcement;
+} | null | undefined): boolean;
+/**
+ * What a request is trying to DO, which is the only thing a read-only lock
+ * discriminates on.
+ *
+ * `write` is the default everywhere it is not stated, and that direction is
+ * deliberate: an enforcement point that forgot to declare its intent refuses
+ * during a migration rather than letting an unaudited write through. The
+ * cost of the safe default is an over-refused read; the cost of the unsafe
+ * one is the corruption the whole mode exists to prevent.
+ */
+export type LockdownIntent = 'read' | 'write';
+/**
+ * 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 declare function lockdownIntentForMethod(method: string | null | undefined): LockdownIntent;
+/**
+ * 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 declare function lockdownBlocks(state: {
+    mode?: LockdownMode;
+} | null | undefined, intent: LockdownIntent): boolean;
+export type LockdownReasonCode = 'security' | 'billing' | 'maintenance' | 'manual';
+export declare const LOCKDOWN_REASON_CODES: LockdownReasonCode[];
+export declare function isLockdownReasonCode(value: unknown): value is LockdownReasonCode;
+/** The one shape every enforcement point consumes. */
+export interface LockdownState {
+    scope: LockdownScope;
+    /** Set only when `scope === 'feature'` — which capability is locked. */
+    feature?: LockdownFeatureKey;
+    /**
+     * Set only on a feature lock placed for ONE workspace (AGL-2927): the
+     * org it pauses the capability for. Absent on the platform-wide feature
+     * lock, which implies every workspace.
+     */
+    orgId?: string;
+    /** Absent = `full` (AGL-1511). Read through `lockdownMode`, never bare. */
+    mode?: LockdownMode;
+    /**
+     * Absent = `standard`, i.e. fail-open (AGL-1621). Read through
+     * `lockdownEnforcement`/`isTakedownLockdown`, never bare.
+     */
+    enforcement?: LockdownEnforcement;
+    reason: LockdownReasonCode;
+    /**
+     * Visitor/user-facing notice text (bounded at write time). Anything staff
+     * types here is SHOWN to locked-out users — internal rationale belongs in
+     * the audit row, not this field.
+     */
+    message?: string;
+    atMs?: number;
+    /**
+     * Optional expiry (maintenance windows end). Once `untilMs` passes the
+     * lockdown is simply inactive — access restores with NO staff action and
+     * no write.
+     */
+    untilMs?: number;
+    actorUid?: string;
+}
+/**
+ * `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 declare const LOCKDOWNS_COLLECTION = "lockdowns";
+export declare const PLATFORM_LOCKDOWN_DOC_ID = "platform";
+export declare const userLockdownDocId: (uid: string) => string;
+/** `feature--{key}` — same collection, same rules, same audited writer. */
+export declare const featureLockdownDocId: (feature: LockdownFeatureKey) => string;
+/**
+ * `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 declare const orgFeatureLockdownDocId: (feature: LockdownFeatureKey, orgId: string) => string;
+/**
+ * `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 declare const domainLockdownDocId: (hostname: string) => string;
+/** The DNS limit; also what keeps the document id bounded. */
+export declare 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 declare function isLockableDomain(value: unknown): value is string;
+export interface LockdownDoc {
+    scope: LockdownScope;
+    /** Present on `feature--{key}` docs only. */
+    feature?: LockdownFeatureKey;
+    /** Present on `feature--{key}--org--{orgId}` docs only (AGL-2927). */
+    orgId?: string;
+    /** Written only for read-only locks; absent = `full`. */
+    mode?: LockdownMode;
+    /** Written only for takedowns; absent = `standard` (fail open). */
+    enforcement?: LockdownEnforcement;
+    reason: LockdownReasonCode;
+    message?: string;
+    atMs?: number;
+    untilMs?: number;
+    actorUid?: string;
+}
+/** Staff-typed notice text is user-facing; keep it bounded and plain. */
+export declare 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 declare function toEpochMs(value: unknown): number | 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 declare function isLockdownActive(state: {
+    untilMs?: number;
+} | null | undefined, nowMs: number): boolean;
+/**
+ * ACCOUNT CREATION ITSELF (AGL-1531) — the decision a Firebase Auth
+ * `beforeUserCreated` blocking function makes.
+ *
+ * The signups feature lock already refuses the SESSION (the mint in
+ * /api/auth/session), the acceptance recorder and the signup-page doors, so
+ * a wave's accounts are unusable. They are still CREATED: account creation
+ * is client -> Firebase Auth and no Aglyn server sits in front of it. The
+ * only thing that does is a blocking function, which is why this decision
+ * exists as its own function rather than as another `isLockdownActive` call
+ * at a route.
+ *
+ * ==== EVERYTHING BELOW, TO THE #endregion MARKER, IS COPIED VERBATIM INTO
+ * ==== cloud/functions/src/signups-lock.ts.
+ *
+ * `cloud/functions` is a plain npm package outside the nx workspace — it can
+ * import firebase-admin and firebase-functions and nothing else, so it
+ * cannot import this library. The copy is therefore byte-for-byte and
+ * apps/console/specs/signups-creation-lock-wiring.spec.ts fails if the two
+ * regions ever differ by a character. That makes the tests below tests of
+ * the code that actually deploys, rather than of a lookalike.
+ *
+ * The region imports nothing, for that reason.
+ */
+/**
+ * FAIL OPEN WHEN THE LOCK CANNOT BE READ; KEEP HOLDING ONE ALREADY SEEN.
+ *
+ * This repo's postures are deliberately not uniform — rate limiting fails
+ * soft, CSRF fails closed, and `getFeatureLockdown` fails OPEN because an
+ * unreachable Firestore is an outage rather than a feature lockdown. This
+ * gate sits with the last of those, and the split below is what makes that
+ * safe rather than merely convenient.
+ *
+ * ## Not knowing is answered by admitting
+ *
+ * An unreadable lock means the platform does not KNOW whether staff pulled
+ * the lever. Refusing on "do not know" is not a cautious answer here, it is
+ * a total one: this is the only thing standing in front of Firebase Auth
+ * account creation, so one refusal turns away every stranger at once, with a
+ * generic error they cannot act on and no reason to come back. And the
+ * condition that produces it is ordinary rather than exceptional — where
+ * signup traffic is light the instance is cold for nearly every attempt, so
+ * "the first Firestore read costs more than the budget" is the common case,
+ * not the rare one.
+ *
+ * The error in the other direction is bounded. An account created while
+ * Firestore is unreadable cannot finish signing up anyway — the profile, the
+ * legal-acceptance record and the workspace all live in Firestore — so
+ * admitting costs some orphan Auth records for the length of the read
+ * outage, and those are enumerable and removable afterwards. One side's
+ * mistake is a handful of empty records; the other side's is the whole
+ * funnel, silently, for as long as reads are slow.
+ *
+ * ## A lever actually seen is a fact, and it survives
+ *
+ * Every read that COMPLETES is recorded below, and a read that then fails is
+ * answered from that record instead of from nothing. So the objection
+ * fail-open usually earns — a bot wave makes reads fail and thereby releases
+ * the brake aimed at the wave — needs the wave to land on an instance that
+ * has never once read the lock; every instance that has keeps refusing for
+ * the whole outage. Lifting the lever is itself a Firestore write, so
+ * nothing can lift it during that outage either, and a lock's own `untilMs`
+ * is still honored against the clock, so a dead-man expiry cannot become
+ * un-liftable by being remembered.
+ *
+ * This is STRICTER than the tenant takedown ledger (AGL-1621), which
+ * remembers only locks classified `takedown` and lets a `standard` one
+ * release during an outage. That trade is right where it sits, because
+ * holding a remembered lock there keeps every visitor off a customer's whole
+ * site. Holding one here refuses new signups, which is the cheap direction,
+ * so no `enforcement` field is consulted at all and any active lock is
+ * remembered.
+ *
+ * ## What it does not do, stated rather than implied
+ *
+ * An instance that has never completed a read has nothing to remember, so a
+ * lever pulled DURING a total Firestore outage does not reach a cold one.
+ * Closing that gap needs a carrier more available than Firestore, which is a
+ * different and much larger change; pretending otherwise here would be worse
+ * than naming it. The escape hatch that needs no deploy is unchanged:
+ * unregister the `beforeCreate` trigger in Identity Platform, which the
+ * staff lockdown page reports the state of.
+ */
+export type SignupsCreationVerdict = 
+/**
+ * `unreadable` marks an admission made BLIND: the read did not complete
+ * and nothing this instance remembers said the lever was pulled. Carried
+ * so the caller can log it — the two admissions are the same outcome for
+ * the person signing up and a very different one for an operator.
+ */
+{
+    refused: false;
+    unreadable?: true;
+}
+/**
+ * `locked` = a read completed and found the lever pulled. `held` = a read
+ * failed and an earlier one had found it pulled.
+ */
+ | {
+    refused: true;
+    cause: 'locked' | 'held';
+};
+/**
+ * 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 declare const SIGNUPS_CREATION_LOCK_READ_TIMEOUT_MS = 2500;
+/**
+ * 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 declare function resetSignupsLockMemory(): void;
+/**
+ * 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 declare function signupsCreationVerdict(readLock: () => Promise<{
+    untilMs?: number;
+} | null | undefined>, nowMs: number, timeoutMs?: number): Promise<SignupsCreationVerdict>;
+/**
+ * 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 declare function resolveLockdown(states: {
+    platform?: LockdownState | null;
+    org?: LockdownState | null;
+    host?: LockdownState | null;
+    /**
+     * AGL-1513. Narrower than `host`: it locks ONE attached name while the
+     * same site keeps serving on its other addresses, so it must never
+     * outrank a host takedown. It sits above `user` for the same reason
+     * `host` does — it is a property of the site being addressed, not of
+     * whoever is looking at it.
+     */
+    domain?: LockdownState | null;
+    user?: LockdownState | null;
+}, nowMs: number): LockdownState | 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 declare function normalizeOrgLockdown(org: {
+    suspendedAt?: unknown;
+    suspendedReasonCode?: unknown;
+    suspendedMessage?: unknown;
+    suspendedUntilMs?: unknown;
+    suspendedMode?: unknown;
+    suspendedEnforcement?: unknown;
+} | null | undefined): LockdownState | null;
+/**
+ * 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 declare function normalizeHostLockdown(host: {
+    suspendedAt?: unknown;
+    suspendedReasonCode?: unknown;
+    suspendedMessage?: unknown;
+    suspendedUntilMs?: unknown;
+    suspendedMode?: unknown;
+    suspendedEnforcement?: unknown;
+} | null | undefined): LockdownState | null;
+/** `lockdowns/{id}` doc → state; refuses malformed docs rather than guess. */
+export declare function normalizeLockdownDoc(doc: Partial<LockdownDoc> | null | undefined, scope: LockdownScope): LockdownState | null;
+/**
+ * `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 declare function lockdownRetryAfterSeconds(state: LockdownState, nowMs: number): number | undefined;
+export interface LockdownNotice {
+    title: string;
+    body: string;
+    /** Shown as the action line; undefined = no contact line (maintenance). */
+    contact?: string;
+}
+/**
+ * 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 declare function lockdownSupportEmail(): string | null;
+/**
+ * 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 declare function lockdownNotice(state: LockdownState): LockdownNotice;
+/**
+ * The surfaces on a customer's LIVE SITE that a read-only lock refuses
+ * (AGL-1511). These are the ones whose reader is a visitor, not our
+ * customer — someone who has never heard of a workspace, a lockdown or a
+ * maintenance window and is simply trying to buy something or send a
+ * message.
+ */
+export type LockdownPausedSurface = 'form' | 'checkout' | 'cart' | 'generic';
+/**
+ * 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 declare function lockdownPausedNotice(surface: LockdownPausedSurface): LockdownNotice;
+/**
+ * The wire shape of the 423 refusal body (`lockdownJsonResponse`). Declared
+ * here, beside the copy that fills it, so the client parser below and the
+ * server writer agree by construction rather than by comment.
+ */
+export interface LockdownRefusalBody {
+    error?: unknown;
+    scope?: unknown;
+    feature?: unknown;
+    mode?: unknown;
+    reason?: unknown;
+    title?: unknown;
+    message?: unknown;
+    contact?: unknown;
+    untilMs?: unknown;
+}
+/** A 423 body, parsed into something a client surface can render. */
+export interface LockdownRefusalNotice {
+    title: string;
+    message: string;
+    contact?: string;
+    scope?: LockdownScope;
+    feature?: LockdownFeatureKey;
+    /**
+     * `read-only` when the server refused a WRITE but is still serving reads
+     * (AGL-1511). Absent on every refusal from a full lock, and on any older
+     * deploy — a client must treat absence as "no claim", never as "full".
+     */
+    mode?: LockdownMode;
+    untilMs?: number;
+    /**
+     * The expiry as a human, LOCAL-time line — `undefined` when the lock has
+     * no expiry, which is most of them. Never a raw epoch number.
+     */
+    until?: string;
+}
+/**
+ * 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 declare const LOCKDOWN_REFUSAL_FALLBACK_TITLE = "Temporarily unavailable";
+export declare const LOCKDOWN_REFUSAL_FALLBACK_MESSAGE: string;
+/**
+ * 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 declare function formatLockdownUntil(untilMs: number): string | undefined;
+/**
+ * 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 declare function parseLockdownRefusal(status: number, body: unknown): LockdownRefusalNotice | null;
+/**
+ * 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 declare function lockdownRefusalText(notice: LockdownRefusalNotice): string;
+/**
+ * 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 declare function lockdownPausedSurfaceForPluginApiPath(path: string): LockdownPausedSurface;
+/**
+ * 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 declare function lockdownFeaturesForPluginApiPath(path: string): LockdownFeatureKey[];