@objectstack/service-sms 17.0.0-rc.2 → 17.0.0-rc.4

package/CHANGELOG.md

@@ -1,5 +1,261 @@
 # @objectstack/service-sms
 
+## 17.0.0-rc.4
+
+### Minor Changes
+
+- de770bf: fix(cli,service-sms)!: `OS_SMS_PROVIDER=twilo` now fails the boot instead of silently becoming the log transport (#5713)
+
+  **BREAKING for one configuration: a provider tag no SMS transport can build.**
+  `os serve` used to hand `OS_SMS_PROVIDER` (or `config.sms.provider`) straight to
+  `SmsServicePlugin` with nothing to compare it against. The plugin then caught the
+  `makeSmsTransport: unknown provider 'twilo'` throw, substituted `LogSmsTransport`,
+  and booted normally — measured, not inferred:
+
+  ```
+  new SmsServicePlugin({ provider: 'twilo' }).init(ctx)
+    booted_without_throw: true            transport_class: 'LogSmsTransport'
+    isConfigured():       false           logger.warn × 1, logger.error × 0
+    service.send(…)    →  { status: 'sent', messageId: 'dev-sms-…' }
+  ```
+
+  So a phone-OTP sign-in answered "code sent", the user waited for an SMS that was
+  never dispatched, and the one `warn` line scrolled past in the boot log. That is
+  the declared-but-not-delivered shape of Prime Directive #10, and the same one
+  #5132 closed for **mail** in the neighbouring arm of the very same capability
+  loop.
+
+  Three gates already guard the `sms` provider value and none of them could see
+  this path: the `sms` settings namespace declares `provider` as a `select` with an
+  options table, #5131 enforces that table on the write path, and #5204 closed the
+  `SettingsService` env-override branch. All three live behind `SettingsService` —
+  this read happens while the kernel is being assembled, _before_ a settings
+  service exists.
+
+  **`resolveSmsCapabilityArg` now refuses a provider tag outside
+  `log` / `aliyun` / `twilio`**, the way its neighbouring `resolveEmailCapabilityArg`
+  already did, and the capability loop turns that into the loud failure it should
+  be — a hard boot error when the app declared `requires: ['sms']`, otherwise a
+  `console.error` and no SMS service.
+
+  **What it deliberately does NOT do:** demand credentials. Unlike mail, SMS
+  provider credentials are not a boot-time input — the `sms` settings namespace
+  binds them at `kernel:ready`, and that is their documented home. A bare
+  `OS_SMS_PROVIDER=twilio` on a host whose Twilio keys live in Settings is a
+  complete configuration and passes through untouched. `SmsServicePlugin`'s own
+  fallback is likewise untouched: for a _known_ provider with incomplete
+  constructor credentials it is correct (the settings bind can still swap in a
+  working transport), and it remains the last line of defence for hosts that
+  construct the plugin themselves. `os serve` simply stops feeding it input it can
+  never use.
+
+  **Who is affected:** deployments that set `OS_SMS_PROVIDER` (or
+  `config.sms.provider`) to a value outside the supported three — in practice a
+  typo, or a provider that was never implemented — and relied on the fallback to
+  boot. An unset `OS_SMS_PROVIDER` still defaults to `log`; every supported tag
+  still boots with or without credentials.
+
+  **Migration — one line, either direction:**
+
+  - the environment is _not_ meant to send SMS → `OS_SMS_PROVIDER=log` (that
+    explicit value is the supported way to say so, and why refusing the others is
+    fair);
+  - the environment _is_ meant to send SMS → fix the tag to `aliyun` or `twilio`
+    and put the credentials in Settings → SMS Delivery (or
+    `config.sms.providerOptions`).
+
+  The error names the consequence and both fixes, per AGENTS.md's
+  degradation-log-level rule.
+
+  `@objectstack/service-sms` gains the vocabulary the CLI reads instead of
+  restating: `SMS_TRANSPORT_PROVIDERS` and `isSmsTransportProvider()`, with
+  `SmsProviderTag` now derived from the array rather than declared beside it. One
+  vocabulary, two consumers — a second literal list in the CLI is how the mail
+  settings dropdown and the mail transports drifted apart in the first place
+  (#5094).
+
+- 9c90ea0: feat(sms): 短信全局日发送配额 —— 成本总量闸 (#2814)
+
+  #2780 给 OTP 端点落了**按号码**的防滥用（60s 冷却 + 每号码 5 条/小时）。那挡住的是「一个号码花多少钱」，挡不住「这套部署一天花多少钱」：攻击者轮换上万个不同号码时，每个号码都稳稳待在自己的预算里，而日累计账单没有任何上限——这正是 SMS pumping / toll fraud 的典型打法。更要紧的是，按号码那道闸住在 better-auth 的 `hooks.before` 里，只看得见 auth 端点：`notify(channels:['sms'])` 与邀请短信从旁边直接走过去，一条都不计数。
+
+  本次新增一道**总量**闸，扣减点放在所有出站短信本来就必经的那一处 —— `SmsService.send()`。OTP、邀请、messaging `sms` channel 三条路无论从哪扇门进来，都记在同一本账上。
+
+  ## 新增设置项
+
+  `sms` 命名空间新增 `daily_quota`（Daily send limit，number，默认 `0` = 不限）：这套部署每个 **UTC 自然日**允许发出的短信总条数。超出后拒发，直到 00:00 UTC。env 覆盖沿用既有的每键机制，无需额外接线：`OS_SMS_DAILY_QUOTA=2500`。
+
+  `0` 是出厂姿态，所以升级本身不改变任何现有部署的发送行为——闸门要由运营者显式配置才会闭合。
+
+  ## Observable behaviour change
+
+  **配置配额后，发送可能被拒**，两条路径的表现分别是：
+
+  - OTP / 邀请路径 —— `SendSmsResult.status='failed'`，`error` 为 `TOO_MANY_REQUESTS: daily SMS quota exhausted`。刻意与按号码闸抛出的 `TOO_MANY_REQUESTS` 用同一个码，且**不带任何剩余额度细节**：从外面看，两道墙必须长得一样，攻击者不该能试探出自己撞的是哪一道。
+    ⚠️ 但这个码**目前到不了 HTTP 调用方**：`AuthManager.deliverPhoneOtp` 把它重抛成普通 `Error`，而 better-call 对非 `APIError` 一律回 500（实测，见 #6039）。也就是说 OTP 端点上，按号码闸回 429、总量闸回 500。补齐要动 plugin-auth，已单独立案。
+  - messaging `sms` channel —— `SendResult.ok=false`，且 `classifyError` 返回 `'rate_limited'`（此前一律 `'retryable'`）。投递落进 outbox 走退避重试 / 死信，不会被静默丢弃；`rate_limited` 与 `retryable` 走同一条重试阶梯，但把「额度用尽」与「网关抖动」在投递记录上区分开。
+
+  ## 计数落在哪里
+
+  复用仓内唯一那份定窗计数（`incrementFixedWindow`）与它的惰性存储解析（`createLazyCounterStore`，#4772/#4790），不写第三份：
+
+  - 有 kernel `cache` 服务时计在共享 cache（集群共享与否取决于 cache 本身）；
+  - 解析不到时降级为有界的进程内计数，并由解析器**点名**打一条 warn，说明降级的代价（N 节点部署最多可花 N× 配额）；
+  - 解析在**计数被消费时**发生，而非插件 init —— 后注册的 cache 也能在下一次发送时被接上（#4772 的坑）。
+
+  窗口是 UTC 自然日，且由两个机制同时保证：计数键带 UTC 日期（`sms-daily-sends:2026-08-06`），窗口开启时的 TTL 恰为距下一个 UTC 午夜的秒数。任一机制单独也能翻窗，合起来则不可能互相矛盾。
+
+  ## 两条刻意的姿态
+
+  - **fail-open**：计数存储读不到时，闸门**放行**并打一次 warn。短信成本闸不能把登录拖下水（#2814 诉求 4）。
+  - **配额值的钳制在消费侧**：manifest 上的 `min: 0` 今天并不被 `validatePatch` 执行（#5932），所以负值 / `NaN` / `Infinity` / 非数字都会原样抵达读取方。这些一律降级为 `0`（不限）并**点名**打 warn，而不是拒发、也不是替运营者编一个别的默认值——一个设置表单里的手误不该变成手机登录的全站故障，而编一个没人声明过的上限只会把手误藏进看似合理的行为里。
+
+  ## 不在本次范围
+
+  诉求中的**每租户日配额**（`daily_quota_per_tenant`）未实现：`SendSmsInput`（`@objectstack/spec/contracts`）不携带任何租户标识，而在 service 侧另造一个只此一家的拼法就是 Prime Directive #12 明令禁止的影子契约。租户维度要么落在 spec 契约上，要么不落——详见 #2814 上的讨论。
+
+### Patch Changes
+
+- Updated dependencies [9fe9c1d]
+- Updated dependencies [d4e0809]
+- Updated dependencies [f724f69]
+- Updated dependencies [28ad90e]
+- Updated dependencies [f8644c7]
+- Updated dependencies [306ca50]
+- Updated dependencies [978fed2]
+- Updated dependencies [cfc293f]
+- Updated dependencies [de70b42]
+- Updated dependencies [fb3d99b]
+- Updated dependencies [cdfbee2]
+- Updated dependencies [29c6c9d]
+- Updated dependencies [d21c001]
+- Updated dependencies [f1cc3a3]
+- Updated dependencies [ddc2527]
+- Updated dependencies [553a47f]
+- Updated dependencies [7a40b7a]
+- Updated dependencies [7cf1531]
+- Updated dependencies [586d6f7]
+- Updated dependencies [2d14b35]
+- Updated dependencies [a3a884d]
+- Updated dependencies [cfed092]
+- Updated dependencies [93929c2]
+- Updated dependencies [2e284b2]
+- Updated dependencies [1b49eaf]
+- Updated dependencies [0161c7f]
+- Updated dependencies [e900015]
+- Updated dependencies [b5bdf48]
+- Updated dependencies [a019e52]
+- Updated dependencies [64fc6d5]
+- Updated dependencies [b746aa0]
+- Updated dependencies [947d4f9]
+- Updated dependencies [eaaf03c]
+- Updated dependencies [d17df80]
+- Updated dependencies [7d0e7b5]
+- Updated dependencies [6513c17]
+- Updated dependencies [c142ced]
+- Updated dependencies [eda599e]
+- Updated dependencies [c001422]
+- Updated dependencies [77022a9]
+- Updated dependencies [52760bf]
+- Updated dependencies [5543020]
+- Updated dependencies [880d343]
+- Updated dependencies [6e82972]
+- Updated dependencies [4615a18]
+- Updated dependencies [7f62706]
+- Updated dependencies [667fa44]
+- Updated dependencies [37e38d1]
+- Updated dependencies [1eb13a0]
+- Updated dependencies [c52e608]
+- Updated dependencies [4dfd002]
+- Updated dependencies [77be690]
+- Updated dependencies [811c30c]
+- Updated dependencies [b49ccfd]
+- Updated dependencies [85d95e7]
+- Updated dependencies [168f60f]
+- Updated dependencies [244ca86]
+- Updated dependencies [546ab3c]
+- Updated dependencies [0b51bb6]
+- Updated dependencies [08f93bc]
+- Updated dependencies [d9971d3]
+- Updated dependencies [eb3e650]
+- Updated dependencies [abeb375]
+- Updated dependencies [ef4efa8]
+- Updated dependencies [cbb6a5c]
+- Updated dependencies [795b6e1]
+- Updated dependencies [175d789]
+- Updated dependencies [55dbbba]
+- Updated dependencies [72c3c86]
+- Updated dependencies [7f1a635]
+- Updated dependencies [9fa6bab]
+- Updated dependencies [0f2fdcd]
+- Updated dependencies [8ffa8b9]
+- Updated dependencies [674ac99]
+- Updated dependencies [61dc08e]
+- Updated dependencies [8dcf607]
+- Updated dependencies [b691ba9]
+- Updated dependencies [502564d]
+- Updated dependencies [471839d]
+- Updated dependencies [46365ab]
+- Updated dependencies [b508244]
+- Updated dependencies [594508e]
+- Updated dependencies [1c625ca]
+- Updated dependencies [71f205d]
+- Updated dependencies [414395b]
+- Updated dependencies [c5adfe1]
+- Updated dependencies [26e1029]
+- Updated dependencies [4addd9d]
+- Updated dependencies [108ba8d]
+- Updated dependencies [b4ad984]
+- Updated dependencies [a9f32df]
+- Updated dependencies [aeb9b27]
+- Updated dependencies [7d27da0]
+- Updated dependencies [de113a4]
+- Updated dependencies [db8c285]
+- Updated dependencies [089767f]
+- Updated dependencies [e4c8b6c]
+- Updated dependencies [acb10f6]
+- Updated dependencies [1c3da1f]
+- Updated dependencies [a34fd2e]
+- Updated dependencies [889ae47]
+- Updated dependencies [4f4c3fb]
+- Updated dependencies [7adc841]
+- Updated dependencies [4845f85]
+- Updated dependencies [7b005b4]
+- Updated dependencies [94f7b6a]
+- Updated dependencies [5c94f83]
+- Updated dependencies [73e576f]
+- Updated dependencies [c5a5996]
+- Updated dependencies [b40f81c]
+- Updated dependencies [ae490ef]
+- Updated dependencies [f61c8cf]
+- Updated dependencies [e3ef52b]
+- Updated dependencies [07f1822]
+- Updated dependencies [04fab5e]
+- Updated dependencies [ef8b1ff]
+- Updated dependencies [efedd28]
+- Updated dependencies [5278e11]
+- Updated dependencies [23dba62]
+- Updated dependencies [ba98e26]
+- Updated dependencies [fc5f536]
+- Updated dependencies [f8cfbb4]
+- Updated dependencies [c89d18c]
+- Updated dependencies [aac90a5]
+- Updated dependencies [1e6ab15]
+- Updated dependencies [c87ef70]
+- Updated dependencies [3cb0618]
+- Updated dependencies [32a0874]
+- Updated dependencies [7055c22]
+- Updated dependencies [785a748]
+- Updated dependencies [3af0354]
+- Updated dependencies [866ff16]
+- Updated dependencies [5a85e67]
+- Updated dependencies [c183a12]
+- Updated dependencies [8064b07]
+- Updated dependencies [4a56dbd]
+- Updated dependencies [06df4fa]
+  - @objectstack/spec@17.0.0-rc.4
+  - @objectstack/core@17.0.0-rc.4
+  - @objectstack/plugin-auth@17.0.0-rc.4
+
 ## 17.0.0-rc.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,6 +1,213 @@
 import { ISmsTransport, NormalizedSmsMessage, SmsTransportSendResult, ISmsService, SendSmsInput, SendSmsResult } from '@objectstack/spec/contracts';
+import { CounterStore } from '@objectstack/plugin-auth';
 import { Plugin, PluginContext } from '@objectstack/core';
 
+/**
+ * Global daily SMS send quota — the COST TOTAL gate (#2814).
+ *
+ * ## What this adds that the per-number guard cannot
+ *
+ * #2780 gave the OTP endpoints a per-NUMBER budget (60s cooldown + 5 sends per
+ * number per hour, `plugin-auth/src/otp-send-guard.ts`). That bounds what one
+ * phone number costs. It does not bound what the DEPLOYMENT costs: an attacker
+ * rotating through ten thousand distinct numbers keeps every one of them inside
+ * its own budget while the daily bill has no ceiling at all — classic SMS
+ * pumping / toll fraud. And the per-number guard sits in better-auth's
+ * `hooks.before`, so it only ever sees the auth endpoints: `notify(channels:
+ * ['sms'])` and the invitation path walk straight past it.
+ *
+ * This gate is therefore counted at the ONE place every outbound message
+ * already funnels through — `SmsService.send()` — so OTP, invitations and the
+ * messaging `sms` channel are all charged against the same budget, whatever
+ * door they came in by.
+ *
+ * ## Where it counts (#4790's answer, reused verbatim)
+ *
+ * A budget is only worth what its store is worth: counted per process, a
+ * declared "2000 per day" is really 2000×N across N nodes, and nothing says so
+ * (ADR-0049 — declared ≠ enforced). So this counts through the SAME resolution
+ * the auth counters use — `createLazyCounterStore` over the kernel `cache`
+ * service, resolved at COUNTING time (not at plugin init, the #4772 trap),
+ * with a bounded per-process fallback that announces itself. The counting
+ * algorithm is `incrementFixedWindow`, imported rather than re-implemented:
+ * this repo has exactly one fixed-window counter and #4790 said plainly that a
+ * third copy is not wanted.
+ *
+ * ## The window is a UTC calendar day, twice over
+ *
+ * "Daily quota" means the calendar day, not "24h from the first send", so the
+ * counter key carries the UTC date (`sms-daily-sends:2026-08-06`) AND the
+ * window is opened with exactly the seconds remaining until the next UTC
+ * midnight. Either mechanism alone would roll the budget over; together they
+ * cannot disagree — a clock skew that mis-sizes the TTL still lands on a fresh
+ * key at 00:00Z, and a store that ignores TTLs still starts a new key.
+ *
+ * ## Admission-time counting, and fail-open
+ *
+ * A unit is consumed when a send is ADMITTED, before the transport runs —
+ * exactly like `OtpSendGuard.checkAndRecord` and
+ * `createLazyCacheRateLimitStorage.consume`, both of which take the
+ * post-increment count and compare it to the cap. Two consequences, stated
+ * rather than discovered later: a transport failure still spends a unit (the
+ * conservative direction for a COST ceiling, and the alternative is a second
+ * store round-trip on every send), and attempts refused by this gate keep
+ * incrementing the day's counter, so the number in the log line is "attempts
+ * today", not "messages delivered today".
+ *
+ * Every store interaction is fail-OPEN: a cache outage must not take phone
+ * sign-in down with it (#2814 requirement 4). A degraded gate is announced once
+ * and then admits.
+ *
+ * ## What is NOT here
+ *
+ * The per-tenant dimension (`daily_quota_per_tenant`, keyed by
+ * `organizationId`) is deliberately absent: `SendSmsInput`
+ * (`@objectstack/spec/contracts/sms-service.ts`) carries no tenant identifier,
+ * and inventing a second, service-local spelling of one would be exactly the
+ * shadow contract AGENTS.md Prime Directive #12 forbids. See the issue thread
+ * on #2814 — the tenant identifier belongs on the spec contract or nowhere.
+ */
+
+/**
+ * The error code a quota-refused send answers with, as the `CODE: message`
+ * prefix `SmsService` already uses for `VALIDATION_FAILED`.
+ *
+ * Deliberately the same code the per-number guard raises in `plugin-auth`
+ * (`APIError('TOO_MANY_REQUESTS')`), because #2814 asks the two walls to be
+ * indistinguishable from outside: an attacker must not be able to tell which
+ * budget they hit, and a legitimate caller needs no more than "not now".
+ * The message carries NO remaining-quota detail for the same reason.
+ */
+declare const SMS_QUOTA_EXCEEDED_CODE = "TOO_MANY_REQUESTS";
+/** The refusal text handed back on `SendSmsResult.error`. Contains no counts. */
+declare const SMS_QUOTA_EXCEEDED_ERROR = "TOO_MANY_REQUESTS: daily SMS quota exhausted";
+type LoggerLike = {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+};
+interface SmsDailyQuotaOptions {
+    /**
+     * Resolve the store the day counter lives in — called on EVERY check, so a
+     * shared cache registered after this gate was constructed is picked up on the
+     * next send rather than never (#4772/#4790). `SmsServicePlugin` supplies
+     * `createLazyCounterStore(...)`; omitted ⇒ a per-process store, silently
+     * (the gate constructed standalone, e.g. in tests).
+     */
+    resolveStore?: () => Promise<CounterStore>;
+    /** Diagnostics sink. NEVER receives a message body or a recipient. */
+    logger?: LoggerLike;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/** Outcome of one admission check. */
+interface SmsDailyQuotaDecision {
+    /** Whether the send may proceed. */
+    ok: boolean;
+    /**
+     * Attempts counted for the current UTC day AFTER this one, when the counter
+     * was actually consulted. Absent when the gate is off or degraded.
+     */
+    count?: number;
+    /** The enforced ceiling this decision was measured against (`0` ⇒ off). */
+    quota?: number;
+}
+/** `YYYY-MM-DD` in UTC — the day the counter key is scoped to. */
+declare function utcDayStamp(now: number): string;
+/**
+ * Seconds from `now` to the next UTC midnight, at least 1. This is the window
+ * `incrementFixedWindow` opens on the day's first send, so the counter expires
+ * with the day it belongs to instead of 24h after whenever it started.
+ */
+declare function secondsUntilNextUtcMidnight(now: number): number;
+/**
+ * Result of reading an authored quota value: the ceiling actually enforced,
+ * plus the offending input when one had to be discarded.
+ */
+interface NormalizedDailyQuota {
+    /** Enforced ceiling. `0` means unlimited. Always a non-negative integer. */
+    limit: number;
+    /** Set when the authored value was unusable and `0` was substituted. */
+    rejected?: string;
+}
+/**
+ * Clamp an authored `sms.daily_quota` into the value actually enforced.
+ *
+ * **This lives on the CONSUMER side on purpose (#5932).** `SettingsService`
+ * declares `min`/`max` on a manifest specifier but `validatePatch` does not
+ * enforce them today, so a `min: 0` declaration is inert: negative, fractional
+ * and outright non-numeric values all reach a reader intact. Anything that
+ * depends on the manifest having filtered them is declared-but-unenforced
+ * (ADR-0049), so the clamp is here, where the value becomes behaviour, and is
+ * pinned by tests.
+ *
+ * The rules, and why each is the safe direction for a paid channel:
+ *
+ * - **absent / empty string** → `0` (unlimited), quietly. That is "the operator
+ *   has not configured a ceiling", which is the shipped default, not an error.
+ * - **finite number ≥ 0** → `Math.floor(v)`. A fractional message count is
+ *   rounded DOWN, the stricter direction for a cost ceiling, and is not worth a
+ *   diagnostic — `100.5` unambiguously means "at most 100 messages".
+ * - **negative, NaN, ±Infinity, or a non-numeric type** → `0` (unlimited) plus
+ *   a named rejection the caller logs LOUDLY.
+ *
+ * That last rule is the one worth arguing. Two other readings exist and both
+ * are worse here. Refusing to send at all turns one typo in a settings form
+ * into a total outage of phone sign-in — the precise failure #2814 requirement
+ * 4 rules out ("配额闸不能把登录拖下水"), and the same reasoning `SettingsService`
+ * applies when it ignores a rejected `OS_*` override rather than acting on it.
+ * Substituting some other default invents a ceiling nobody declared and hides
+ * the typo behind plausible behaviour (#5152's lesson, where a typo'd
+ * `invite_only` read as `auto` left an operator believing a wall was up).
+ * Ignoring the value and SAYING SO leaves the deployment exactly where it was
+ * before the bad edit, with a line naming the value to fix.
+ */
+declare function normalizeDailyQuota(raw: unknown): NormalizedDailyQuota;
+/**
+ * The global daily send ceiling, counted once per admitted send.
+ *
+ * Constructed by `SmsServicePlugin` and handed to `SmsService`; `setQuota` is
+ * called on every `sms` settings change so an admin edit takes effect without a
+ * restart (same live-swap contract as the transport).
+ */
+declare class SmsDailyQuota {
+    private limit;
+    private readonly resolveStore;
+    private readonly logger?;
+    private readonly now;
+    /**
+     * Per-process fallback used when no resolver was supplied at all (the gate
+     * constructed standalone). The SAME bounded store the auth counters degrade
+     * to — one fallback implementation across the repo, not a second one that can
+     * drift (#4790).
+     */
+    private readonly fallback;
+    /** The last authored value reported as unusable — deduped, per value. */
+    private reportedRejection?;
+    /** UTC day stamp the approaching-ceiling WARN has already fired for. */
+    private nearLimitWarnedFor?;
+    /** UTC day stamp the ceiling-reached WARN has already fired for. */
+    private exceededWarnedFor?;
+    /** Store-outage WARN is once per process — see `checkAndRecord`. */
+    private degradedWarned;
+    constructor(options?: SmsDailyQuotaOptions);
+    /**
+     * Apply an authored `sms.daily_quota`. Anything unusable degrades to
+     * "unlimited" and is reported once per distinct offending value — see
+     * {@link normalizeDailyQuota} for why that is the safe direction.
+     */
+    setQuota(raw: unknown): void;
+    /** The ceiling actually in force (`0` ⇒ unlimited). @internal test seam */
+    get enforcedQuota(): number;
+    /**
+     * Charge one send against today's budget and answer whether it may proceed.
+     *
+     * Never throws: a store outage fails OPEN (announced once per process), for
+     * the reason in the file header — an SMS cost ceiling that can block sign-in
+     * is a worse problem than the one it solves.
+     */
+    checkAndRecord(): Promise<SmsDailyQuotaDecision>;
+}
+
 /**
  * Normalize + validate a recipient phone number. Accepts E.164 and common
  * human formats (spaces / dashes / dots / parens are stripped). Returns
@@ -50,6 +257,14 @@ interface SmsServiceOptions {
         info: (msg: string, meta?: any) => void;
         warn: (msg: string, meta?: any) => void;
     };
+    /**
+     * The deployment-wide daily send ceiling (#2814). Charged once per admitted
+     * send, HERE rather than at the auth endpoints, so OTP, invitations and the
+     * messaging `sms` channel are all counted against the one budget — see
+     * `sms-daily-quota.ts`. Omitted ⇒ no total-cost gate (the pre-#2814
+     * behaviour).
+     */
+    dailyQuota?: SmsDailyQuota;
 }
 /**
  * Concrete ISmsService implementation.
@@ -129,7 +344,32 @@ declare class TwilioSmsTransport implements ISmsTransport {
     send(message: NormalizedSmsMessage): Promise<SmsTransportSendResult>;
 }
 
-type SmsProviderTag = 'log' | 'aliyun' | 'twilio';
+/**
+ * The provider vocabulary — every tag `makeSmsTransport` below can build, and
+ * nothing else. It is the **one** literal: the `SmsProviderTag` type is derived
+ * from it, the `switch` is exhaustive over it, and callers that have to judge an
+ * operator-supplied provider string (the CLI's `sms` capability arm, #5713) read
+ * it from here rather than restating the list.
+ *
+ * Two literals describing one vocabulary is how the mail settings dropdown and
+ * the mail transports drifted apart (#5094) — `sendgrid`/`ses` were offered with
+ * no transport behind them while `resend` had a working transport nobody could
+ * pick. The SMS boot path had the same shape from the other side: `os serve`
+ * passed `OS_SMS_PROVIDER` straight into `SmsServicePlugin` with nothing to
+ * compare it against, so a typo (`twilo`) reached `makeSmsTransport`, threw
+ * there, was caught, and became `LogSmsTransport` — a server that answers every
+ * OTP send `status: 'sent'` and delivers nothing.
+ */
+declare const SMS_TRANSPORT_PROVIDERS: readonly ["log", "aliyun", "twilio"];
+/** A provider tag `makeSmsTransport` can materialise a transport for. */
+type SmsProviderTag = (typeof SMS_TRANSPORT_PROVIDERS)[number];
+/**
+ * Narrow an unknown value to a buildable provider tag. The counterpart of
+ * `isEmailTransportProvider` in `@objectstack/plugin-email`, and used by the CLI
+ * for the same reason: a provider that cannot deliver must be refused where the
+ * operator declared it, not silently downgraded where it is materialised.
+ */
+declare function isSmsTransportProvider(value: unknown): value is SmsProviderTag;
 interface MakeSmsTransportOptions {
     provider: SmsProviderTag;
     /** Provider-specific credentials/options (see the transport option types). */
@@ -188,7 +428,21 @@ declare class SmsServicePlugin implements Plugin {
     type: "standard";
     private readonly options;
     private service?;
+    private dailyQuota?;
     constructor(options?: SmsServicePluginOptions);
+    /**
+     * Build the daily cost gate (#2814) over the kernel `cache` service.
+     *
+     * `resolveCache` is copied in shape from `AuthPlugin.init()` on purpose, for
+     * the two reasons stated there: the `cache` service is registered ASYNC (so
+     * `getService` throws for it and `getServiceAsync` is the only accessor that
+     * works), and resolution has to happen when a counter is CONSUMED rather than
+     * at init, or a deployment that registers its cache after this plugin freezes
+     * a "no shared store" answer for the life of the process (#4772). The
+     * degraded case is announced by `createLazyCounterStore` itself, named for
+     * this subject.
+     */
+    private buildDailyQuota;
     private resolveInitialTransport;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
@@ -200,4 +454,4 @@ declare class SmsServicePlugin implements Plugin {
     private applySmsSettings;
 }
 
-export { AliyunSmsTransport, type AliyunSmsTransportOptions, LogSmsTransport, type MakeSmsTransportOptions, type SmsProviderTag, SmsService, type SmsServiceOptions, SmsServicePlugin, type SmsServicePluginOptions, TwilioSmsTransport, type TwilioSmsTransportOptions, makeSmsTransport, maskPhoneNumber, normalizeSmsRecipient };
+export { AliyunSmsTransport, type AliyunSmsTransportOptions, LogSmsTransport, type MakeSmsTransportOptions, type NormalizedDailyQuota, SMS_QUOTA_EXCEEDED_CODE, SMS_QUOTA_EXCEEDED_ERROR, SMS_TRANSPORT_PROVIDERS, SmsDailyQuota, type SmsDailyQuotaDecision, type SmsDailyQuotaOptions, type SmsProviderTag, SmsService, type SmsServiceOptions, SmsServicePlugin, type SmsServicePluginOptions, TwilioSmsTransport, type TwilioSmsTransportOptions, isSmsTransportProvider, makeSmsTransport, maskPhoneNumber, normalizeDailyQuota, normalizeSmsRecipient, secondsUntilNextUtcMidnight, utcDayStamp };