@crewhaus/tool-notify 0.7.0 → 0.8.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -14,7 +14,7 @@ is a different and more dangerous act.
 ```yaml
 tools:
   - all-notify          # every tool below
-  - -SmsSend            # ...except this one
+  - -smsSend            # ...except this one (a tools: list takes the camelCase key)
 ```
 
 | Tool | What it does |
@@ -44,7 +44,13 @@ The tools worth reaching for first are the ones that send nothing.
 about the same broken host. `QuietHours` is the reason an overnight alert waits
 until 09:00 when it will read identically. `RateLimitGate` is the reason a loop
 does not re-report the same thing on every iteration. All three are pure, take
-`now` as an argument, and compose:
+`now` as an argument, and compose. `now` (and an email's `date`) must name
+its zone. Write it as ISO-8601 (`2026-09-17T03:14:00Z` or `…+09:00`) or
+as an email Date header (`Thu, 17 Sep 2026 03:14:00 +0000`). JavaScript's
+`Date#toString()` form and the US zones an email header may use (`EST`,
+`PDT`, …) are read too. A time without a zone is refused, because it would
+mean the host's local time and differ between machines. So is an abbreviation
+such as `CET` or `IST`, which names different zones in different places:
 
 ```
 NotifyDigest → QuietHours → RateLimitGate → MessageTemplate → ChatPost
@@ -74,7 +80,11 @@ re-deriving it — a second outbound surface with a weaker gate is the same hole
 twice. In summary:
 
 - **Empty allow-list denies everything.** Separately for origins, for SMTP
-  hosts, and for email recipients. There is no "allow all" value.
+  hosts, for email recipients, for SMS numbers (`allowed_sms_recipients`, in
+  E.164 form or a prefix such as `+44*`) and for push targets
+  (`allowed_push_targets`, exact or a `prefix*`). There is no "allow all"
+  value. A provider that pins the number in `staticFields` and maps no `to`
+  never sends the call's value, so it needs no list.
 - **SSRF refusal is numeric, not textual.** Loopback, link-local (including
   the cloud metadata address), RFC1918, CGNAT, multicast and mDNS are refused
   as an IP literal in any of its encodings — octal, hex, integer, every IPv6
@@ -83,6 +93,11 @@ twice. In summary:
 - **The vetted IP is pinned** for the connection, so a rebinding resolver
   cannot swap in a private address between the check and the socket. The SMTP
   client pins the same way, and still presents and verifies the hostname.
+- **An id names an item; it never moves the request.** A Discord channel,
+  message id or emoji, and `DeliveryCheck`'s message id, are written into a
+  URL path. `.` and `..` survive percent-encoding and the URL parser resolves
+  them, so they are refused, and the path actually requested must be the path
+  built with the value written in.
 - **A send never follows a redirect.** Replaying a body at a new origin, or
   downgrading to a GET that delivers nothing, are both worse than stopping.
   Only `DeliveryCheck` follows, re-running the whole gate on every hop.
@@ -92,7 +107,7 @@ twice. In summary:
 ## Credentials
 
 No tool accepts a secret. Every credential is the **NAME** of an environment
-variable, read at call time:
+variable, read at call time, and only a name you list:
 
 ```yaml
 tool_config:
@@ -101,12 +116,28 @@ tool_config:
     allowed_recipients: ["ops@example.com", "*@team.example.com"]
     allowed_smtp_hosts: ["smtp.example.com"]
     allowed_sender_domains: ["example.com"]
+    allowed_secret_envs: [SLACK_OPS_WEBHOOK, SLACK_BOT_TOKEN]
+    allowed_sms_recipients: ["+15550001111", "+4420*"]
+    allowed_push_targets: ["topic:ops-*"]
 ```
 
+`allowed_secret_envs` covers every name a call supplies: `webhookUrlEnv` and
+`tokenEnv` for the chat tools, `WebhookPost`'s `urlEnv`, `auth.envVar` and
+`signing.secretEnv`, and `EmailSend`'s `usernameEnv` and `passwordEnv`. A call
+may choose among the listed names and can never add one, so it cannot send
+another process secret (your LLM provider key, say) to an allowed origin.
+With no list, every such name is refused. A provider's own `auth.envVar`
+(under `providers`) is yours already and needs no listing, but it is read
+only for that provider's calls.
+
 ```jsonc
 { "platform": "slack", "webhookUrlEnv": "SLACK_OPS_WEBHOOK", "text": "…" }
 ```
 
+In API mode (`apiBaseUrl` plus `tokenEnv`) the variable holds a bot token.
+Discord receives it as `Authorization: Bot <token>` and Slack as
+`Authorization: Bearer <token>`, which is what each platform expects of a bot.
+
 A Slack incoming-webhook URL (`/services/T…/B…/…`) and a Discord one
 (`/api/webhooks/<id>/<token>`) carry their whole authority in the **path**, so
 the URL is itself a credential: it is named rather than passed, and no error
@@ -117,6 +148,25 @@ because a tool result is a transcript, a trace and usually an eval report. Every
 result — success or failure — passes through a redactor built from the resolved
 secret, in its literal, URL-encoded and base64 forms.
 
+## What a permission rule reads
+
+- **Chat.** `ChatPost` and `ChatUpdate` read the channel; `ChatDelete` and `ChatReact` read
+  `channel/messageId`. An API-mode call always names `apiBaseUrl`, so the value is matched with
+  that URL's origin in front: `alwaysAllow ChatPost(https://slack.com/C0123)`, or
+  `ChatPost(https://*/C0123)` for that channel on any API. A deny on an API fires on every
+  API-mode call to it: `alwaysDeny ChatPost(https://discord.com/**)`.
+- **Incoming webhooks.** A webhook posts to the channel it was created for, and `ChatPost` ignores
+  a `channel` in that call. So the rule reads `webhookUrlEnv`, the variable that names the webhook:
+  `alwaysAllow ChatPost(SLACK_OPS_WEBHOOK)` covers a webhook post, with or without a `channel`. An
+  allow on a channel does not cover one, and a deny on a channel still fires on it. The webhook's
+  URL is a credential, so no rule reads it, its host included: a deny on an API does not stop a
+  webhook post to that host. Deny the variable instead: `alwaysDeny ChatPost(DISCORD_WEBHOOK)`.
+- **`WebhookPost`** reads `url`, or `urlEnv` when the URL is kept in a variable:
+  `alwaysAllow WebhookPost(DEPLOY_HOOK_URL)`.
+- **Not read:** the SMTP relay in `EmailSend`'s `host` (bounded by `allowed_smtp_hosts`), the
+  provider an SMS or push goes through (each one is yours, in `providers`), and the bot token a
+  Chat call names, which picks the workspace. A rule names who receives the message.
+
 ## Injection is the thing this package is most careful about
 
 A notification is almost always assembled from data the harness did not write:
@@ -238,7 +288,10 @@ Stated rather than papered over:
 - **Implicit TLS (port 465) is untested** for the same reason.
 - **The idempotency ledger is per-process.** A retry after a restart will send
   again. The ledger is the second line of defence; the key is also passed to
-  the provider, which is the first.
+  the provider, which is the first. A key names one message: the same key
+  with a different destination or content is refused and sends nothing,
+  while a retry that changes only its timeout, byte cap, retry pacing or
+  clock reading (`date`, a signature timestamp) returns the first result.
 - **`ChatUpdate` does not return the previous text,** because the platform
   does not give it back.
 - **`EmailSendPreflight` does not fold provider-specific aliases.** Two