@shiprev/server-sdk-node 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# @shiprev/server-sdk-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Server SDK you install inside your own Node.js or NestJS service to connect it to a ShipRev instance. It verifies the access tokens ShipRev issues to your users, rules on capabilities locally from a mirror of the application's entitlements, reports metered usage in batches, and makes two-phase reservations for expensive work.
+
+It runs on your request path. What it does when it cannot reach the instance (a dropped connection, a cold start) is specified below and is part of the contract, not an implementation detail.
+
+> **Beta.** Versions `0.1.x` are published under the `beta` dist-tag. The interface may still change before `1.0`; pin an exact version.
+
+## Requirements
+
+- Node.js 20 or later.
+- A running ShipRev instance reachable from your service, and an **SDK-scoped API key** for your application (created in the operator console, or with `POST /mgt/v1/credentials` and `scope: "SDK"`).
+- For the NestJS bindings only: `@nestjs/common` and `@nestjs/core` (9, 10 or 11) and `reflect-metadata`. They are optional peer dependencies; a plain Node.js service does not need them, because the main entry point never loads NestJS.
+
+## Install
+
+```bash
+npm install @shiprev/server-sdk-node@beta
+# or
+pnpm add @shiprev/server-sdk-node@beta
+```
+
+## Quick start (plain Node.js)
+
+```ts
+import { createClient } from '@shiprev/server-sdk-node';
+
+const shiprev = createClient({
+  base_url: process.env.SHIPREV_BASE_URL!, // e.g. https://shiprev.example.com
+  api_key: process.env.SHIPREV_API_KEY!, // SDK-scoped key of your application
+});
+
+// Fetches the signing keys, exchanges the API key for a service token, opens the push stream,
+// and loads the entitlement snapshot of every buyer organization of the application.
+const { state } = await shiprev.start();
+if (state !== 'LIVE') {
+  // start() never throws: the client keeps reconnecting in the background (see "Connection").
+}
+
+// Who is calling: verify the session token your user got from the ShipRev portal.
+const claims = await shiprev.verifyToken(bearerToken);
+
+// May they do it: a local ruling, no network I/O.
+const ruling = shiprev.adjudicate({
+  organization_id: claims.organization_id,
+  capability_key: 'report_exports',
+  quantity: 1,
+  operation: 'write',
+});
+
+if (ruling.allowed) {
+  // ... do the work, then report what was consumed.
+  await shiprev.reportUsage({
+    usage_event_id: crypto.randomUUID(),
+    organization_id: claims.organization_id,
+    capability_key: 'report_exports',
+    quantity: 1,
+    occurred_at: new Date().toISOString(),
+  });
+}
+
+// On shutdown: flush buffered usage.
+await shiprev.stop();
+```
+
+A runnable version of this flow is the `examples/server-sdk-quickstart` example in the ShipRev repository.
+
+## Configuration
+
+`createClient(options)` and `new ShipRevClient(options)` take the same `ShipRevClientOptions`:
+
+| Option                       | Default    | Meaning                                                                                                                                  |
+| :--------------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `base_url`                   | (required) | Base URL of the instance's core service; may include a path prefix. Trailing slashes are ignored                                         |
+| `api_key`                    | (required) | SDK-scoped API key of the application                                                                                                    |
+| `presets.cold_start`         | `'deny'`   | Ruling for **reads** when the mirror is empty and the instance is unreachable: `'allow'` or `'deny'`                                     |
+| `presets.connect_timeout_ms` | `5000`     | Timeout of every request to the instance                                                                                                 |
+| `presets.reservation_ttl_s`  | (service)  | Default time-to-live of a reservation when `reserve()` does not pass one                                                                 |
+| `buffer.batch_size`          | `100`      | Usage events sent per request; reaching it triggers a flush                                                                              |
+| `buffer.flush_interval_ms`   | `5000`     | Background flush interval. `0` disables the timer; the timer never keeps the process alive                                               |
+| `backlog`                    | memory     | Where usage waits while it cannot be delivered; see [Persistence modes](#persistence-modes)                                              |
+| `on_flush_failure`           |            | `(events, error) => void`, called when a batch could not be delivered (the events go to the backlog)                                     |
+| `on_rejected`                |            | `(rejected) => void`, called with the events the service refused, each with a `reason`                                                   |
+| `on_level_change`            |            | `(organization_id, level) => void`, called when an organization's effective level changes; see [Degradation levels](#degradation-levels) |
+
+## NestJS
+
+The NestJS bindings live in the `@shiprev/server-sdk-node/nest` subpath. `ShipRevModule` is a global module that provides one started client and two guards.
+
+```ts
+import { Module } from '@nestjs/common';
+import { ShipRevModule } from '@shiprev/server-sdk-node/nest';
+
+@Module({
+  imports: [
+    ShipRevModule.forRoot({
+      base_url: process.env.SHIPREV_BASE_URL!,
+      api_key: process.env.SHIPREV_API_KEY!,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot` and `forRootAsync` start the client in the background, so the host boots even when the instance is unreachable. `forRootAsync({ imports, inject, useFactory })` builds the options from other providers: `imports` lists the modules that export them, `inject` the providers passed to `useFactory`, in order:
+
+```ts
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ShipRevModule } from '@shiprev/server-sdk-node/nest';
+
+ShipRevModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    base_url: config.getOrThrow<string>('SHIPREV_BASE_URL'),
+    api_key: config.getOrThrow<string>('SHIPREV_API_KEY'),
+  }),
+});
+```
+
+The subpath also resolves under `"moduleResolution": "node"`, the default of new NestJS projects.
+
+Protect routes with the guards, in this order:
+
+```ts
+import { Controller, Post, UseGuards } from '@nestjs/common';
+import { ShipRevClient } from '@shiprev/server-sdk-node';
+import {
+  InjectShipRevClient,
+  RequireCapability,
+  ShipRevAuthGuard,
+  ShipRevCapabilityGuard,
+} from '@shiprev/server-sdk-node/nest';
+
+@Controller('reports')
+@UseGuards(ShipRevAuthGuard, ShipRevCapabilityGuard)
+export class ReportsController {
+  constructor(@InjectShipRevClient() private readonly shiprev: ShipRevClient) {}
+
+  @Post('export')
+  @RequireCapability('report_exports', 'write', 1)
+  async export() {
+    // ...
+  }
+}
+```
+
+- `ShipRevAuthGuard` reads `Authorization: Bearer <token>`, verifies it with `verifyToken()`, and sets the claims on `request.authClaims` and `request.user`. A missing, malformed, badly signed, expired or rejected token (see [Token verification](#token-verification)) is a `401`.
+- `ShipRevCapabilityGuard` reads `@RequireCapability(capabilityKey, operation = 'read', quantity = 1)` from the handler or the controller and rules with `adjudicateAsync()`. The organization comes only from the verified claims (`organization_id` on `request.authClaims`, or on `request.user`); a header, route parameter or body field is never read, because the caller controls those. Claims without an organization are a `403` with reason `missing_organization`, before any ruling. A refusal is a `403`; the ruling is set on `request.ruling`. Routes without `@RequireCapability` pass.
+- `@InjectShipRevClient()` injects the client (token `SHIPREV_CLIENT`).
+
+## Token verification
+
+`verifyToken(token)` accepts only the session tokens the ShipRev portal issues to the buyer end users of **your** application on **your** instance. After the format, the RS256 signature against the instance's keys and the expiry, it checks, in this order:
+
+| Check                                                      | Refused with `TokenRejectedError`, `reason` |
+| :--------------------------------------------------------- | :------------------------------------------ |
+| `exp` is present and numeric                               | `missing_expiry`                            |
+| no `purpose` claim (email verification and the like)       | `not_a_session_token`                       |
+| the client knows what to expect                            | `not_ready`                                 |
+| `aud` and `scope` are both `public`                        | `audience_mismatch`                         |
+| `iss` equals the issuer of the client's service token      | `issuer_mismatch`                           |
+| `pid` equals the application of the client's service token | `project_mismatch`                          |
+
+The expected issuer and application come from the service token the client obtains in `start()`; there is nothing to configure. Until the client has obtained one (never reached the instance), every token is refused with `not_ready`. Once known, the expectations are kept while the client is disconnected, and verification keeps working offline for every signing key already fetched. `TokenRejectedError` is exported from the main entry; its message never contains the token.
+
+A token whose `kid` is not among the cached signing keys triggers one refetch of the instance's keys, but not within 30 seconds of the last successful fetch: inside that window it is refused (`Unknown key ID`) without any request, so forged tokens with random key IDs cannot multiply your traffic into requests to the instance. A failed fetch does not start the window. After the instance rotates its signing key, tokens signed with the new key may therefore be refused for up to 30 seconds after the previous fetch.
+
+## Rulings and `operation`
+
+Every ruling names its `operation`: `'read'` or `'write'`. It is required, because the two fail in opposite directions when the instance is unreachable: reads keep working from the last known entitlements, writes stop. Anything that consumes quota, changes state or costs money is a `write`. A missing or unknown `operation`, or a negative or non-finite `quantity`, is refused with `reason: 'invalid_request'`.
+
+`adjudicate(options)` is synchronous and does no I/O. `adjudicateAsync(options)` returns the same ruling, except that when the client is online and the mirror does not know the organization or capability, it asks the instance (`POST /sdk/v1/adjudicate`) and, on an allow, loads that organization into the mirror.
+
+A `Ruling` is `{ allowed, source, reason?, remaining?, limit?, adjudicated_at }`. `source` says where it came from:
+
+| `source`         | When                                                                                             |
+| :--------------- | :----------------------------------------------------------------------------------------------- |
+| `realtime`       | Online, ruled from the mirror                                                                    |
+| `authoritative`  | Online, the mirror did not know the organization or capability; the instance ruled               |
+| `degraded`       | Offline, ruled from the last snapshot                                                            |
+| `client_default` | No basis for a ruling: invalid request, cold start offline, or online with nothing in the mirror |
+
+Online rulings from the mirror compare `quantity` exactly against the remaining allowance, which the snapshot carries as fixed-point decimal strings. Beyond the remaining allowance nothing is allowed locally, whatever the overage policy: whether credits (and, for `ALLOW_AND_BILL`, the wallet's overdraft limit) cover the write is state of the instance, so the local answer is a refusal with `reason: 'quota_exhausted'`, which `adjudicateAsync()` turns into a question to the instance and returns its ruling. When no ruling can be had the write stays refused. A capability the mirror does not hold is refused with `reason: 'capability_not_granted'` (which `adjudicateAsync()` turns into a question to the instance).
+
+`guardWrite(options, action)` runs `action` only when a `write` ruling allows it, and otherwise throws `DisconnectedWriteError`.
+
+## Usage reporting
+
+`reportUsage(event)` appends to an in-memory buffer; the buffer is sent to `POST /sdk/v1/usage-events` when it reaches `buffer.batch_size`, on the flush timer, on `flush()`, and on `stop()`. Each event is:
+
+| Field             | Meaning                                                                                 |
+| :---------------- | :-------------------------------------------------------------------------------------- |
+| `usage_event_id`  | Your unique ID for the event. The service drops repeats, so a retried event counts once |
+| `organization_id` | Buyer organization that consumed                                                        |
+| `capability_key`  | Metered capability                                                                      |
+| `quantity`        | A finite number; anything else throws `RangeError` at `reportUsage()`                   |
+| `occurred_at`     | ISO 8601 timestamp of the consumption                                                   |
+| `idempotency_key` | Optional                                                                                |
+| `properties`      | Optional, `Record<string, unknown>`                                                     |
+
+Before sending the buffer, each flush first drains what is waiting in the backlog. Events the service refuses are reported to `on_rejected` and are not retried.
+
+`await flush()` (and `await stop()`) resolves only when every event reported before the call has been accepted, refused (`on_rejected`), or moved to the backlog because it could not be delivered (offline, no service token, or a failed request; `on_flush_failure` is called for a failed buffer batch). If another flush is in flight, for example the one that follows a reconnection, the call waits for it and then makes its own pass. A flush started by `flush()` sends the whole backlog, batch by batch, stopping at the first failed batch; a timer tick skips while a flush is in flight and sends at most one backlog batch.
+
+For work whose cost is only known afterwards, reserve first and settle later: `reserve({ organization_id, capability_key, amount, ttl_seconds? })`, then `confirm(reservationId, actualAmount?)` (without an amount, the reserved amount is confirmed) or `release(reservationId)`. Reservations need a service token, which `start()` obtains; without one they throw.
+
+## Connection
+
+From `start()` to `stop()` the client keeps itself connected; the host calls nothing in between.
+
+- **Push stream.** The client holds `GET /sdk/v1/events` open. When the instance announces that an organization's entitlements changed (a plan change, a top-up, an operator's rule change), the client refreshes that organization in the mirror without a restart; when the instance asks for a full resynchronization, it reloads the whole snapshot. The mirror is never refreshed on a timer.
+- **Service token.** Renewed at 80 % of its lifetime; the new token takes over the push stream without a gap. A `401` on any request renews the token once (one renewal shared by concurrent requests) and retries that request once. If the instance refuses the API key itself (revoked or expired), the client retries every 30 seconds.
+- **Online signal.** The push stream is the only signal: the client is `LIVE` while the stream is open and not silent for three heartbeat intervals (45 seconds with the instance's default), and the mirror was loaded after the stream opened. A single failed request does not change the state. A stream that ends or fails is reopened at once; if that fails the client is `DISCONNECTED` and retries after 1, 2, 4, 8, 16 and then every 30 seconds (each ±20 %). A stopped service process is noticed at once; a silent network outage within the heartbeat window.
+- **Recovery.** Back online, the client reloads the whole snapshot, returns to `LIVE`, and delivers the usage backlog before new events. A client that started `COLD_OFFLINE` recovers the same way, without a new `start()`.
+
+Every timer is unref'd: the client never keeps your process alive, and `stop()` closes the stream and clears every timer.
+
+## Disconnected semantics
+
+`start()` moves the client to `LIVE` when it has the signing keys, a service token, a ready push stream and the snapshot. When only the push stream is unavailable it ends in `DISCONNECTED` with the snapshot loaded; when no snapshot could be loaded, in `COLD_OFFLINE`. It does not throw. `state()` reports `{ state, snapshot_revision, last_sync_at }`.
+
+| State          | Meaning                     | Reads                              | Writes                                |
+| :------------- | :-------------------------- | :--------------------------------- | :------------------------------------ |
+| `LIVE`         | Online, mirror loaded       | Ruled from the mirror              | Ruled from the mirror                 |
+| `DISCONNECTED` | Offline, last snapshot kept | **Fail open**: allowed, `degraded` | **Fail closed**: `disconnected_write` |
+| `COLD_OFFLINE` | Offline, nothing loaded     | `presets.cold_start` decides       | **Fail closed**: `disconnected_write` |
+| `COLD`         | Not started, or stopped     |                                    |                                       |
+
+Writes are refused whenever the push stream is down, even if other requests to the instance still succeed: without the stream the mirror may be stale, and a stale mirror must not approve consumption. While offline, usage events are not lost: flushes move them into the backlog, and the first flush back online delivers the backlog before new events.
+
+`setOnline(false)` closes the push stream and suspends reconnection until `setOnline(true)`, which sets `LIVE` at once and resumes; on a started client the next connection attempt then corrects the state. Both are for fault injection and tests. `loadSnapshot(snapshot)` seeds the mirror without the network (a `COLD_OFFLINE` client becomes `DISCONNECTED`).
+
+## Degradation levels
+
+Every organization entry of the snapshot carries two fields the instance computes: `degradation_level`, one of `NONE`, `RESTRICT_NEW`, `RESTRICT_USAGE`, `RESTRICT_READ` and `SUSPENDED` (strictly increasing), and `valid_until`, the time until which the entry may be used without a newer answer. An instance sets the level from its own rules (for example a buyer's unpaid invoices); at `SUSPENDED` the entry's `items` is empty, so nothing is granted. Instances that predate the fields leave them out.
+
+`effectiveLevel(organizationId)` combines them with the connection, synchronously and without I/O, into `{ level, source, expired }` (`undefined` when the mirror does not hold the organization):
+
+| The client observes                                    | `level`                                                | `source`     | `expired` |
+| :----------------------------------------------------- | :----------------------------------------------------- | :----------- | :-------- |
+| `LIVE` (the instance answers)                          | The entry's level                                      | `'answer'`   | `false`   |
+| Not `LIVE`, before the entry's `valid_until`           | The entry's level                                      | `'degraded'` | `false`   |
+| Not `LIVE`, at or after `valid_until` (or none usable) | The entry's level, raised to `RESTRICT_USAGE` at least | `'degraded'` | `true`    |
+
+A level the client does not know (another string, or not a string) reads as `RESTRICT_USAGE`, never looser. The level does not change `adjudicate()`, `adjudicateAsync()` or `guardWrite()`: a disconnected write is refused whatever the level; what a level blocks in your service is your decision.
+
+While `LIVE`, once half of an entry's validity has passed without a newer entry, the client pulls that organization once to renew it (never more than once per entry, never on a fixed period).
+
+`refresh(organizationId, { timeout_ms? })` pulls one organization now, sharing a pull already in flight for it, and resolves with the answer's level (`source: 'answer'`); when the pull fails or does not finish within `timeout_ms` (default `presets.connect_timeout_ms`) it resolves with `effectiveLevel()` as it stands. Use it before refusing an action on a level, so that a change at the instance applies within the action.
+
+`sendUsage(events)` sends one batch at once, outside the buffer and the backlog, and resolves with `{ accepted_count, duplicates_dropped, rejected }`. Quantities may be decimal strings, sent unchanged. It throws `UsageDeliveryError` when the batch did not get through (network error, timeout, `5xx`); any other refusal throws as it came. Sending the same batch again is safe, as events are deduplicated by `usage_event_id`. It is for callers that keep their own durable queue; everyone else uses `reportUsage()`.
+
+## Persistence modes
+
+`backlog.mode` chooses where undeliverable usage waits:
+
+| Mode           | Survives a restart | Notes                                                                                                                                                    |
+| :------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`       | No                 | Default. Events waiting in the backlog are lost if the process exits                                                                                     |
+| `journal`      | Yes                | Append-only file at `backlog.journal_path` (default `.shiprev-usage-journal.log` in the working directory), replayed on start; corrupt lines are skipped |
+| `host_adapter` | Your choice        | Pass `backlog.adapter`, any `BacklogAdapter` (`enqueue`, `peek`, `ack`, `nack`, `size`) backed by your own store, e.g. Redis or your database            |
+
+## Development
+
+```bash
+pnpm --filter @shiprev/server-sdk-node build
+pnpm --filter @shiprev/server-sdk-node test
+pnpm --filter @shiprev/server-sdk-node lint
+pnpm --filter @shiprev/server-sdk-node test:nest9   # Nest specs and type check against NestJS 9; needs the npm registry
+```
+
+Packages are named by product line plus language suffix, `@shiprev/server-sdk-<lang>`; other languages will be added under the same prefix.
+
+## License
+
+[Apache-2.0](./LICENSE).

package/dist/auth/token-verifier.d.ts

@@ -0,0 +1,56 @@
+import { HttpTransport } from '../transport/http.transport';
+import { JwksKey, TokenClaims } from '../types';
+/**
+ * What a buyer session token must carry to be accepted, learned from this client's own machine
+ * token: the instance that issued it and the application it belongs to.
+ */
+export interface TokenExpectations {
+    issuer: string;
+    projectId: string;
+}
+export declare function jwkToPem(jwk: JwksKey): string;
+/**
+ * After a successful JWKS fetch, a token with an unknown `kid` does not trigger another fetch for
+ * this long; it is refused instead. Without it, an anonymous caller could turn every forged token
+ * carrying a random `kid` into one request to the instance. A key rotated in during this window is
+ * accepted at most this long after the previous fetch.
+ */
+export declare const JWKS_REFRESH_COOLDOWN_MS = 30000;
+export declare class TokenVerifier {
+    private readonly transport;
+    private readonly publicKeyCache;
+    /** `Date.now()` of the last successful JWKS fetch; failed fetches do not set it. */
+    private lastRefreshAt;
+    private inFlightRefresh;
+    constructor(transport: HttpTransport);
+    /**
+     * Refreshes the local in-memory public key cache from the JWKS endpoint. Always fetches (no
+     * cooldown); concurrent calls share one request. A success starts the unknown-`kid` cooldown.
+     */
+    refreshKeys(): Promise<void>;
+    private fetchKeys;
+    private inRefreshCooldown;
+    /**
+     * Directly caches a key in memory (e.g. for testing or preloading)
+     */
+    setPublicKey(kid: string, pem: string): void;
+    /**
+     * Verifies an RS256 JWT token locally, extracting the subject and isolation keys.
+     * If the kid is unknown in cache, it triggers a single JWKS refresh, unless the last successful
+     * refresh is less than `JWKS_REFRESH_COOLDOWN_MS` old, in which case the token is refused at once.
+     *
+     * With `expectations` (or `null`, meaning they are not known yet), the token must also be a buyer
+     * session token of that issuer and application; the checks run after the signature, in the order
+     * exp · purpose · aud/scope · iss · pid, and refusals are `TokenRejectedError`. Without the
+     * argument only the signature and, when present, the expiry are checked.
+     */
+    verifyToken(token: string, expectations?: TokenExpectations | null): Promise<TokenClaims>;
+}
+/**
+ * Reads the expectations from a machine token's payload without verifying it (the client obtained
+ * it from the instance itself). Returns `null` when the value is not a decodable JWT or lacks `iss`
+ * or `pid`.
+ */
+export declare function expectationsFromMachineToken(token: string): TokenExpectations | null;
+/** The `exp` of a JWT in milliseconds, or `undefined` when it cannot be read. */
+export declare function expiryOfToken(token: string): number | undefined;