@whooshbang/contracts 1.0.0-rc.13

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable contract changes are recorded here.
+
+## 1.0.0-rc.13
+
+- Publish the unchanged contract schemas and fixtures as the first public npm
+  candidate, with explicit public package metadata and a package-local MIT
+  license. `1.0.0-rc.12` remains immutable.
+- Coordinate the public boundary with SDK `1.0.0-rc.14` and deterministic mock
+  `1.0.0-rc.16`; hosted WhooshBang service code remains proprietary.
+
+## 1.0.0-rc.12
+
+- Reissue the unchanged schema and fixture semantics as the coordinated
+  contract identity for SDK `1.0.0-rc.13` and deterministic mock
+  `1.0.0-rc.15`.
+- The mock now omits already-acknowledged events from polls and re-derives a
+  repeated acknowledgement from durable state, matching the existing C0-03
+  fixtures and semantics model. `1.0.0-rc.11` remains immutable.
+
+## 1.0.0-rc.11
+
+- Add the closed `replay_unavailable` Problem code at HTTP 409. Replay
+  refusals retain the `not_terminal`, `payload_unavailable`, or
+  `rollout_disabled` field error that tells an integrator which state blocked
+  the operation.
+- Allow `interaction.received` machine events to outlive answer content. New
+  retained events publish `answer_retained: true` with `response`; redacted
+  events publish `answer_retained: false` and omit `response`.
+- Accept a retained legacy event with `response` and no retention marker during
+  a rolling deployment. Absence is never a redaction signal; only the published
+  `answer_retained: false` shape is.
+- Breaking: exhaustive `ProblemCode` consumers must handle the new member, and
+  machine-event consumers must tolerate a redacted event without `response`.
+  `1.0.0-rc.10` remains immutable.
+
+## 1.0.0-rc.10
+
+- Add the environment-scoped form of each operation an account-scoped caller
+  needs — subscription-link create and read, message create and read,
+  interaction read, machine-client create, and capabilities — alongside the
+  flat forms, which are untouched and remain credential-only.
+- Add a `bearerGrant` security scheme, and attach it to those operations, to
+  the account and project operations, and to the customer-endpoint operations
+  that already carry project and environment in their paths.
+- Split the scope vocabulary by level. Project-level scopes are the credential
+  vocabulary unchanged and stay mirrored exactly; the account-level scopes
+  `projects:read` and `projects:write` exist only on a grant or a human
+  session, because a credential lives inside a project and can never create or
+  enumerate its siblings.
+- Additive throughout: every existing request and response is unchanged.
+
+## 1.0.0-rc.9
+
+- Add authenticated per-message and per-interaction canonical response
+  inspection with a bounded zero-to-30-second wait that defaults to 30.
+- Preserve first-terminal-writer and retained/redacted answer semantics while
+  making wait expiry a successful current-state response.
+- Reissue the unpublished contract as a new immutable candidate;
+  `1.0.0-rc.8` remains unchanged.
+
+## 1.0.0-rc.8
+
+- Add project/environment customer-endpoint create, signed verification,
+  secret rotation, lifecycle, health, and safe attempt-diagnostic operations.
+- Add one-time secret result, verification challenge, endpoint resource, and
+  diagnostic fixtures while preserving the existing Standard Webhooks and
+  idempotency semantics.
+- Preserve each promised rotation overlap by returning a typed conflict when
+  another rotation is requested before the prior overlap expires.
+- Reissue the unpublished contract as a new immutable candidate;
+  `1.0.0-rc.7` remains unchanged.
+
+## 1.0.0-rc.7
+
+- Preserve the first-terminal-writer `answered` state after normalized answer
+  deletion with explicit `answer_retained` status semantics: retained answers
+  remain typed; redacted summaries keep `answered_at` and omit `answer`.
+- Add retained and redacted golden interaction summaries and regenerate the
+  public types, validators, OpenAPI bundle, SDK, and deterministic mock.
+- Reissue the unpublished contract as a new immutable candidate;
+  `1.0.0-rc.6` remains unchanged.
+
+## 1.0.0-rc.6
+
+- Generate the deployed production API server origin from the canonical
+  Cloudflare resource manifest and move it to `https://api.whooshbang.com`.
+- Keep the existing V1 Problem Details and JSON Schema URI identifiers pinned
+  to their immutable `whooshbang.flowxo.com` identities.
+- Reissue the contract, SDK, mock, generated output, and fixture identities as
+  a new immutable candidate; `1.0.0-rc.5` remains unchanged.
+- No compatibility shim or runtime migration is required because the prior
+  candidate was unpublished and the product has not been deployed.
+
+## 1.0.0-rc.5
+
+- Restore the documented `paused` Telegram binding state to the C0
+  `BindingSummary` candidate alongside `active` and `revoked`.
+- Add schema-valid paused and revoked subscription-link fixtures so consumers
+  prove all subscriber-control states instead of inferring them.
+- Reissue the contract, SDK, mock, generated output, and fixture identities as
+  a new immutable candidate; `1.0.0-rc.4` remains unchanged.
+- No compatibility shim or runtime migration is required because the prior
+  candidate was unpublished and the product has not been deployed.
+
+## 1.0.0-rc.4
+
+- Replace the unused pre-launch product identity with WhooshBang across the
+  package name, OpenAPI and schema identities, Problem Details origin,
+  diagnostic header, event envelope, project and machine credential markers,
+  generated types, validators, fixtures, and consumer examples.
+- Rename the public package to `@whooshbang/contracts`; the prior candidate
+  was never published and has no compatibility or migration requirement.
+
+## 1.0.0-rc.3
+
+- Add the approved N1-03 API credential lifecycle contract: account-owned
+  project/environment administration paths, exact high-entropy bearer syntax,
+  one-time create/rotate reveal, metadata-only listing, a zero-to-24-hour
+  rotation overlap, terminal repeat-safe revocation, and indistinguishable
+  invalid/revoked authentication.
+- Keep published credential examples unmistakably synthetic with low-entropy
+  sentinel values so repository secret scanning remains actionable.
+- Require a distinct newly active replacement, coherent lifecycle timestamps,
+  and an explicit old-credential revocation deadline in rotation responses;
+  extend deployable-artifact scanning to WhooshBang bearer formats.
+- Reissue the contract, SDK, mock, fixtures, and generated artifacts under a
+  new immutable candidate identity; `1.0.0-rc.2` remains unchanged.
+
+## 1.0.0-rc.2
+
+- Add the N1-02 human-administration contract to the reviewed release-candidate
+  line: current account projection, project create/list/read, atomic
+  `test`/`live` environment and default-notifier bootstrap, account-scoped
+  idempotency, slug conflict, and non-enumerating cross-account behavior.
+- Reissue the manifest, schemas, fixtures, OpenAPI bundle, generated types, and
+  validators under a new immutable candidate identity; `1.0.0-rc.1` remains
+  unchanged.
+
+## 1.0.0-rc.1
+
+- Promote the exact reviewed Wave 0/C0 contract from `1.0.0-draft.1` without a
+  public semantic change.
+- Reissue every manifest, schema, fixture identity, OpenAPI document, generated
+  output, and package-consumer assertion at the release-candidate version after
+  the compatibility and adversarial security gates passed.
+- Keep the candidate repository-local and unpublished so downstream consumers
+  can pin and verify the exact artifact before any independent product release.
+
+## 1.0.0-draft.1
+
+- Establish the versioned contract workspace, ownership manifest, and package
+  boundary.
+- Add the canonical WhooshBang OpenAPI 3.1.1 contract for subscription-link
+  creation, inspection, and cancellation and message creation, inspection, and
+  cancellation.
+- Add strict JSON Schema 2020-12 request, resource, delivery-attempt, binding,
+  Problem Details, fixture-index, and semantic-scenario models.
+- Add deterministic generated TypeScript, runtime validators, a bundled OpenAPI
+  document, and golden fixtures covering success, failure, idempotency, state,
+  cancellation, and tenant/environment isolation.
+- Record seven-day idempotency, authenticated scope, safe error, and
+  ambiguous-provider `outcome_unknown` semantics without adding production
+  service, SDK, interaction, webhook, or executable mock behavior.
+- Add the C0-03 tagged confirm, single-select, and input interaction request,
+  lifecycle summary, and authenticated answer-event contracts with bounded
+  prompts/options/input, opaque callback tokens, strict expiry ordering, and
+  deterministic duplicate/stale/expired/mismatched fixtures.
+- Add project-administered machine-client and digest-only credential
+  registration/revocation contracts, exact locally generated
+  `wb_mc1.<credential-id>.<secret>` syntax, Web Crypto generation and
+  constant-time digest verification helpers, and safe metadata responses that
+  contain neither a readable secret nor digest.
+- Add bounded long polling, at-least-seven-day event retention, per-event
+  idempotent acknowledgement, contiguous committed cursors, crash replay,
+  fail-closed foreign/uncommitted cursors, and schema-valid poison-event
+  quarantine.
+- Add provider-neutral capability declarations and an additive unique-provider
+  collection with Telegram acceptance evidence and explicit lack of
+  delivered/read evidence.
+- Add the strict `whooshbang.event.v1` envelope, nine initial per-event
+  schemas, generated types/validators, and safe synthetic event fixtures.
+- Add Standard Webhooks-compatible raw-byte HMAC-SHA256 verification using
+  Worker- and Node-compatible Web Crypto, bounded current/previous key
+  rotation, strict replay/header parsing, and 28 deterministic valid and
+  adversarial vectors.
+- Add an independently implemented Python standard-library verifier over the
+  same byte vectors and include it in the immutable package boundary.
+- Add a caller-owned atomic deduplication consumer example with expected
+  project/event checks and seven-day retention, plus deterministic at-least-
+  once delivery classification for 2xx, redirects, retryable outcomes, safe
+  Retry-After, eight attempts, and a 24-hour window.
+- Keep machine message create/read authorization narrowly bound to the
+  authenticated client destination and owned message IDs; cancellation,
+  administration, Relay continuation/resume, multi-select/ordered sets,
+  endpoint registration/delivery queues, WebSockets, SDK networking, and
+  executable mock behavior remain outside this change.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowXO LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# WhooshBang contract workspace
+
+`@whooshbang/contracts` is the runtime-neutral artifact boundary for
+public contracts owned by WhooshBang. It does not depend on sibling
+repositories or Cloudflare runtime types.
+
+Install the current release candidate from the public npm registry:
+
+```sh
+npm install @whooshbang/contracts@next
+```
+
+## Source ownership
+
+- `contract-manifest.json`, `openapi/`, `schemas/`, `fixtures/`, and
+  `examples/` are canonical, human-edited inputs.
+- `src/generated/` is deterministic output. Never edit it by hand; run
+  `npm run contracts:generate` from the repository root.
+- `dist/` and `artifacts/` are local build outputs and are not committed.
+- Other products retain ownership of their own schemas. Consumer artifacts are
+  pinned and exchanged as tarballs rather than accessed through sibling paths.
+
+The manifest indexes the C0-02 core REST contract, its approved N1-02
+account/project administration and N1-03 credential-lifecycle amendments, the
+C0-03 interaction, machine-client, machine-event, and provider-capability
+contracts, and the C0-04 signed customer-event and delivery contracts. The
+canonical API is `openapi/whooshbang-v1.yaml`; its committed distribution
+bundle, generated TypeScript, validators, and fixture index are checked for
+drift on every contract check.
+
+The contract intentionally stops at serialized behavior. The JavaScript SDK and
+executable Hono mock provide deterministic C0-05 consumer behavior, while no
+production authentication, persistence, queue, Telegram, endpoint registration,
+or provider behavior lives in this package. Its bounded runtime-neutral helpers
+cover local machine credential material, raw-byte webhook verification,
+caller-owned idempotent consumption, and delivery-response classification. They
+perform no networking or persistence.
+
+## N1-03 credential boundary
+
+- Human credential administration is scoped by the verified Clerk account and
+  explicit account-owned project/environment path targets.
+- Project bearer syntax is
+  `wb_pc1.pcred_<16-byte-base64url>.<32-byte-base64url-secret>`. Creation and
+  rotation reveal the complete bearer exactly once and cannot be replayed.
+- Safe metadata exposes a non-secret prefix, label, scopes, opaque
+  WhooshBang creator ID, creation/last-used time, and lifecycle state.
+- Rotation preserves label and scopes, with an explicit overlap bounded at 24
+  hours. Revocation is terminal and repeat-safe.
+- The initial onboarding scope set uses `subscriptions:read` as the minimal
+  resource-read scope alongside `messages:write`, `messages:read`, and
+  `subscriptions:write`.
+
+## C0-03 boundaries
+
+- Message creation accepts an optional tagged `confirm`, single `select`, or
+  `input` interaction. Expiry and first-terminal-answer behavior remain
+  server-authoritative.
+- Provider callback and cursor tokens are opaque references. They carry no
+  answer, identity, command, session, or business authority.
+- Machine credentials have only `machine-messages:write`,
+  `machine-messages:read`, `machine-events:read`, and `machine-events:ack`,
+  each constrained to the authenticated client's bound destination or stream.
+  They cannot cancel messages or administer machine clients.
+- Polling repeats unacknowledged events and accepts only the exact atomically
+  committed cursor. Per-event acknowledgement advances only a contiguous
+  prefix; safe quarantine cannot bypass identity, signature, or schema
+  failures.
+- `GET /v1/capabilities` returns a provider collection whose individual
+  declarations validate against the standalone provider-capability schema.
+- Customer applications and Agent Relay decide what an authenticated answer
+  means. WhooshBang never serializes or issues an executable resume
+  command.
+
+## C0-04 boundaries
+
+- `whooshbang.event.v1` is a strict nine-member customer-event union with
+  stable public resource IDs and no bearer, callback token, raw provider
+  identity, executable command, or original message body.
+- Standard Webhooks V1 verification signs
+  `<webhook-id>.<webhook-timestamp>.<raw-body>` with HMAC-SHA256, accepts at
+  most current and previous `whsec_` keys during rotation, and enforces a
+  five-minute-or-narrower replay window.
+- Customer code checks the expected project and atomically deduplicates event
+  IDs before business side effects, retaining successful claims for at least
+  seven days.
+- Delivery is at least once and unordered. Redirects are not followed; only
+  network failures, 408, 425, 429, and 5xx are retryable, with at most eight
+  attempts during 24 hours.
+- The JavaScript verifier is Web Crypto-only. The packaged independent Python
+  example uses only the standard library and passes the same deterministic
+  byte vectors.
+
+## Public package exports
+
+- Package root: contract manifest, version, generated model types, named
+  validators, machine-credential helpers, webhook verification/idempotent
+  consumption, and delivery classification.
+- `examples/python/verify_webhook.py`: independent standard-library verifier.
+- `openapi/whooshbang-v1.yaml`: canonical OpenAPI 3.1.1 source.
+- `openapi/whooshbang-v1.bundle.json`: deterministic self-contained bundle.
+- `schemas/*`: canonical JSON Schema 2020-12 documents.
+- `fixtures/*`: versioned synthetic golden fixtures and their machine-readable
+  index.
+
+## Stable root commands
+
+```sh
+npm run build
+npm run check
+npm run contracts:generate
+npm run contracts:check
+npm run contracts:pack
+```
+
+`contracts:check` validates the manifest and canonical documents, fixtures,
+generated-file drift, package exports, package boundaries, and runtime
+neutrality. `contracts:pack` repeats those checks, proves reproducible packing,
+audits the tarball, and installs it into isolated npm and pnpm consumers. It
+never publishes to a registry.