@antasphere/chassis-server 1.0.0

package/src/entitlements/hub-machine-token.ts

@@ -0,0 +1,205 @@
+import { USAGE_WRITE_SCOPE } from '@antasphere/chassis-contract';
+import type { Logger } from '../logger.js';
+
+/**
+ * The tool → hub MACHINE identity (the billing rail spec, §6): a
+ * `client_credentials` token minted on the instance's own registry client
+ * (`HUB_CLIENT_ID` / `HUB_CLIENT_SECRET`) with the single scope
+ * `usage:write`. It carries a client and no subject; the hub refuses every
+ * route but `/usage/*` to it, so the only trust it carries is "this tool
+ * says this account did this" — it cannot read an organization, a user or a
+ * grant, which is what keeps ADR 014's "no service key" stance intact.
+ *
+ * Cached until shortly before expiry and minted single-flight: concurrent
+ * batches share one mint, and a 401 from the hub invalidates the cache so
+ * the next call mints again (`invalidate()`).
+ */
+export const HUB_USAGE_SCOPE = USAGE_WRITE_SCOPE;
+
+/** How long a TRANSIENT mint failure is held before the hub is asked again: one attempt per instance per window during an outage. */
+export const DEFAULT_FAILURE_HOLD_MS = 5_000;
+/**
+ * How long a mint the hub refused as a CONFIGURATION error (`invalid_client`
+ * and its kin) is held (PRDCT-2637). It heals only by an operator's change,
+ * so asking again in five seconds buys nothing and costs the hub's per-IP
+ * token wall, the one bucket people's sign-ins from this instance's
+ * address share: a few replicas with a stale secret would start answering
+ * 429 to a person signing in. Five minutes bounds a fleet to a handful of
+ * mints an hour; `invalidate()` (a 401 from the hub on a live token) still
+ * clears the hold, since the hub then changed its mind.
+ */
+export const DEFAULT_INVALID_CLIENT_HOLD_MS = 5 * 60_000;
+
+export interface HubMachineTokenOptions {
+  issuerUrl: string;
+  clientId: string;
+  clientSecret: string;
+  /** RFC 8707 `resource`: the hub's own API resource (`<hub>/mcp`), the aud the hub mints for its `/usage/*`. */
+  resource: string;
+  logger: Logger;
+  /** Token-endpoint budget per mint. */
+  timeoutMs?: number | undefined;
+  /** Re-mint this many ms before the hub's `expires_in` runs out. */
+  refreshSkewMs?: number | undefined;
+  /** How long a transient mint failure is held before the hub is asked again (the negative cache). */
+  failureHoldMs?: number | undefined;
+  /** How long an `invalid_client`-kind refusal is held (the configuration-error hold, PRDCT-2637). */
+  invalidClientHoldMs?: number | undefined;
+  fetchImpl?: typeof fetch | undefined;
+  now?: (() => number) | undefined;
+}
+
+export class HubMachineTokenError extends Error {
+  constructor(
+    message: string,
+    /** `invalid_client` = the credentials are wrong (never retried into a loop); `transient` = try again later. */
+    public readonly kind: 'invalid_client' | 'transient'
+  ) {
+    super(message);
+    this.name = 'HubMachineTokenError';
+  }
+}
+
+export class HubMachineToken {
+  private readonly tokenUrl: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly now: () => number;
+  private readonly timeoutMs: number;
+  private readonly refreshSkewMs: number;
+  private readonly failureHoldMs: number;
+  private readonly invalidClientHoldMs: number;
+  private cached: { token: string; expiresAtMs: number } | null = null;
+  private inflight: Promise<string> | null = null;
+  /**
+   * The negative cache: after a mint fails, `get()` throws at once until this
+   * moment instead of re-asking the hub. During an outage the first metered
+   * request of every account per TTL would otherwise pay the token timeout
+   * again; with it, one attempt per `failureHoldMs` for the whole instance,
+   * and one per `invalidClientHoldMs` when the hub refused the client itself.
+   */
+  private failedUntilMs = 0;
+  private lastFailure: HubMachineTokenError | null = null;
+  /** How many mints reached the hub — a test seam (single-flight, refresh). */
+  mints = 0;
+
+  constructor(private readonly opts: HubMachineTokenOptions) {
+    this.tokenUrl = opts.issuerUrl.replace(/\/+$/, '') + '/api/v1/auth/oauth2/token';
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.now = opts.now ?? Date.now;
+    this.timeoutMs = opts.timeoutMs ?? 10_000;
+    this.refreshSkewMs = opts.refreshSkewMs ?? 60_000;
+    this.failureHoldMs = opts.failureHoldMs ?? DEFAULT_FAILURE_HOLD_MS;
+    this.invalidClientHoldMs = opts.invalidClientHoldMs ?? DEFAULT_INVALID_CLIENT_HOLD_MS;
+  }
+
+  /** The current token, minted or refreshed as needed. Throws `HubMachineTokenError`. */
+  async get(): Promise<string> {
+    if (this.cached && this.cached.expiresAtMs - this.refreshSkewMs > this.now()) return this.cached.token;
+    // Inside the skew window the token is still live at the hub: a refresh
+    // that fails serves it rather than the failure, until it really expires.
+    const stillLive = this.cached && this.cached.expiresAtMs > this.now() ? this.cached.token : null;
+    if (this.lastFailure && this.failedUntilMs > this.now()) {
+      if (stillLive) return stillLive;
+      throw this.lastFailure;
+    }
+    if (!this.inflight) {
+      this.inflight = this.mint()
+        .then((token) => {
+          this.lastFailure = null;
+          return token;
+        })
+        .catch((cause: unknown) => {
+          const failure =
+            cause instanceof HubMachineTokenError
+              ? cause
+              : new HubMachineTokenError(String(cause), 'transient');
+          this.lastFailure = failure;
+          // A configuration error is held minutes, a transient one seconds
+          // (PRDCT-2637): the former never heals by asking again.
+          this.failedUntilMs =
+            this.now() + (failure.kind === 'invalid_client' ? this.invalidClientHoldMs : this.failureHoldMs);
+          throw failure;
+        })
+        .finally(() => {
+          this.inflight = null;
+        });
+    }
+    if (!stillLive) return this.inflight;
+    return this.inflight.catch(() => stillLive);
+  }
+
+  /** Forget the cached token (the hub answered 401 to it) and the held failure. */
+  invalidate(): void {
+    this.cached = null;
+    this.lastFailure = null;
+    this.failedUntilMs = 0;
+  }
+
+  private async mint(): Promise<string> {
+    this.mints += 1;
+    const body = new URLSearchParams({
+      grant_type: 'client_credentials',
+      scope: HUB_USAGE_SCOPE,
+      resource: this.opts.resource
+    });
+    const basic = Buffer.from(`${this.opts.clientId}:${this.opts.clientSecret}`).toString('base64');
+    let res: Response;
+    try {
+      res = await this.fetchImpl(this.tokenUrl, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/x-www-form-urlencoded',
+          accept: 'application/json',
+          authorization: `Basic ${basic}`
+        },
+        body: body.toString(),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      this.opts.logger.warn({ err }, 'hub machine token: token endpoint unreachable');
+      throw new HubMachineTokenError('hub token endpoint unreachable', 'transient');
+    }
+    let payload: unknown = null;
+    try {
+      payload = await res.json();
+    } catch {
+      // classified by status below
+    }
+    if (res.ok) {
+      const p = (payload ?? {}) as { access_token?: unknown; expires_in?: unknown };
+      if (typeof p.access_token !== 'string' || !p.access_token) {
+        this.opts.logger.warn('hub machine token: token endpoint 200 without an access_token — malformed');
+        throw new HubMachineTokenError('malformed token answer', 'transient');
+      }
+      const expiresInS =
+        typeof p.expires_in === 'number' && Number.isFinite(p.expires_in) && p.expires_in > 0
+          ? p.expires_in
+          : 300;
+      this.cached = { token: p.access_token, expiresAtMs: this.now() + expiresInS * 1000 };
+      return p.access_token;
+    }
+    const error = (payload as { error?: unknown } | null)?.error;
+    // The hub's config-shaped refusals (PRDCT-2625): a wrong secret, a client
+    // outside the registry, a scope that is not exactly usage:write, a
+    // resource that is not the hub's. None heals by retrying; every one is
+    // an operator's error, logged at error level.
+    if (
+      (res.status === 400 || res.status === 401) &&
+      (error === 'invalid_client' ||
+        error === 'unauthorized_client' ||
+        error === 'invalid_scope' ||
+        error === 'invalid_target')
+    ) {
+      this.opts.logger.error(
+        { error },
+        'hub machine token: the hub refuses this client — check HUB_CLIENT_ID/HUB_CLIENT_SECRET, the client\u2019s registry entry and its client_credentials grant'
+      );
+      throw new HubMachineTokenError(String(error), 'invalid_client');
+    }
+    this.opts.logger.warn(
+      { status: res.status, error },
+      'hub machine token: token endpoint answered non-2xx'
+    );
+    throw new HubMachineTokenError(`token endpoint answered ${res.status}`, 'transient');
+  }
+}

package/src/entitlements/hub-subject.ts

@@ -0,0 +1,77 @@
+import { and, eq } from 'drizzle-orm';
+import { account, type Db } from '@antasphere/chassis-db';
+import { HUB_SSO_PROVIDER_ID } from '../identity/hub-sso.js';
+
+/** How many users the cache may hold before a miss sweeps the expired entries. */
+const SWEEP_ABOVE = 5_000;
+
+/** The cache behind `hubSubjectResolver`, exported so its bound can be tested without a database. */
+export interface HubSubjectCache {
+  resolve(userId: string): Promise<string | null>;
+  readonly size: number;
+  clear(): void;
+}
+
+/**
+ * A per-user TTL cache over a hub-subject lookup. A miss (a user with no hub
+ * link) is cached too. The map used to be unbounded: on a long-lived replica
+ * serving many API-key principals it held one entry per distinct user that
+ * ever performed a metered action, for the life of the process (PRDCT-2654).
+ * It is now swept the way `profiles.ts` sweeps its plan cache: whenever it
+ * holds more than `sweepAbove` entries at the moment a miss is about to be
+ * written, every expired entry (`until <= now`) is deleted first.
+ */
+export function hubSubjectCache(
+  lookup: (userId: string) => Promise<string | null>,
+  opts: { ttlMs?: number; sweepAbove?: number; now?: () => number } = {}
+): HubSubjectCache {
+  const ttlMs = opts.ttlMs ?? 5 * 60_000;
+  const sweepAbove = opts.sweepAbove ?? SWEEP_ABOVE;
+  const now = opts.now ?? Date.now;
+  const cache = new Map<string, { sub: string | null; until: number }>();
+  const sweep = (at: number): void => {
+    if (cache.size <= sweepAbove) return;
+    for (const [key, entry] of cache) {
+      if (entry.until <= at) cache.delete(key);
+    }
+  };
+  return {
+    async resolve(userId) {
+      const hit = cache.get(userId);
+      if (hit && hit.until > now()) return hit.sub;
+      const sub = await lookup(userId);
+      const at = now();
+      sweep(at);
+      cache.set(userId, { sub, until: at + ttlMs });
+      return sub;
+    },
+    get size() {
+      return cache.size;
+    },
+    clear() {
+      cache.clear();
+    }
+  };
+}
+
+/**
+ * The hub user behind a local user (the billing rail, PRDCT-2625): a usage
+ * event reports the hub's `sub`, which the SSO link stores as the account
+ * row's `accountId` under the `antasphere` provider. A user with no hub link
+ * (the cloud operator, a local invitee) reports null — the hub would refuse
+ * a local id as `unknown_user`. Cached per user for `ttlMs` through
+ * `hubSubjectCache` (bounded by its sweep); a miss is cached too (the
+ * operator uploads as much as anyone).
+ */
+export function hubSubjectResolver(db: Db, ttlMs = 5 * 60_000): (userId: string) => Promise<string | null> {
+  const dbLookup = async (userId: string): Promise<string | null> => {
+    const [row] = await db
+      .select({ sub: account.accountId })
+      .from(account)
+      .where(and(eq(account.userId, userId), eq(account.providerId, HUB_SSO_PROVIDER_ID)))
+      .limit(1);
+    return row?.sub ?? null;
+  };
+  const cache = hubSubjectCache(dbLookup, { ttlMs });
+  return (userId) => cache.resolve(userId);
+}

package/src/entitlements/index.ts

@@ -0,0 +1,37 @@
+export { describeHubClockSkew, hubClockSkewMs } from './clock-skew.js';
+export {
+  DEFAULT_CREDIT_CHECK_DIALS,
+  HubCreditCheck,
+  type CreditCheck,
+  type CreditCheckDials,
+  type CreditCheckRequest,
+  type CreditVerdict,
+  type HubCreditCheckOptions
+} from './check.js';
+export {
+  entitlementGate,
+  honoPath,
+  isDeferringGate,
+  registerEntitlementGate,
+  type EntitlementCloud,
+  type EntitlementGateDeps
+} from './gate.js';
+export {
+  DEFAULT_FAILURE_HOLD_MS,
+  DEFAULT_INVALID_CLIENT_HOLD_MS,
+  HUB_USAGE_SCOPE,
+  HubMachineToken,
+  HubMachineTokenError,
+  type HubMachineTokenOptions
+} from './hub-machine-token.js';
+export { hubSubjectResolver } from './hub-subject.js';
+export { HubUsagePoster, HubUsagePostError, type HubUsagePosterOptions } from './poster.js';
+export {
+  DEFAULT_PROFILE_DIALS,
+  EntitlementProfiles,
+  defaultProfile,
+  type EntitlementProfileDials,
+  type EntitlementProfilesOptions,
+  type ResolvedProfile
+} from './profiles.js';
+export { assertToolEntitlements, EMPTY_TOOL_ENTITLEMENTS, type ToolEntitlementDeclaration } from './slot.js';

package/src/entitlements/poster.ts

@@ -0,0 +1,265 @@
+import { Counter } from 'prom-client';
+import {
+  usageEventOccurrenceIssue,
+  usageIngestResultSchema,
+  type UsageBatchOutcome,
+  type UsageDownstream,
+  type UsageEvent
+} from '@antasphere/chassis-contract';
+import type { Logger } from '../logger.js';
+import { HubMachineTokenError, type HubMachineToken } from './hub-machine-token.js';
+
+/**
+ * The cloud edition's usage downstream (the billing rail spec, §6): the
+ * batches the durable queue drains are posted to the hub's
+ * `POST /api/v1/usage/events` with the machine token. At-least-once stays
+ * the posture — the hub dedupes by ULID and answers per event
+ * (`accepted | duplicate | rejected`); anything that is not an answer is a
+ * throw, which fails the batch back to the queue for its retry.
+ *
+ * What is retried and what is not:
+ *  - unreachable, timeout, 404 (an older hub that has no ingest yet), 408,
+ *    429, 5xx: an OUTAGE — thrown, retried by the queue, never data loss;
+ *  - 401: the token is dead — invalidated and minted again ONCE, then an
+ *    outage;
+ *  - 400/422: the batch is malformed — a bug, never healed by a retry:
+ *    logged at error level and dropped, per the events' ids;
+ *  - 403 (a client without the scope): logged at error level and treated as
+ *    an outage, so the events wait for the operator rather than vanish;
+ *  - a 2xx whose body is not the hub's answer: an OUTAGE too (PRDCT-2629) —
+ *    a proxy page or a hub regression must never read as delivery;
+ *  - a `rejected` event in a 2xx answer: logged with the hub's reason and
+ *    dropped (the hub judged it).
+ *
+ * The queue's retry budget never ends in a loss: a batch it gives up on is
+ * held and re-driven hourly (jobs/pgboss.ts, PRDCT-2635). What the poster
+ * saw is counted on /metrics (`usage_poster_events_total` per event
+ * outcome, `usage_poster_batches_total` per batch outcome), so a rail that
+ * rejects everything is one scrape away, not one log line nobody reads.
+ *
+ * The date window (PRDCT-2644): the hub refuses an event whose `occurredAt`
+ * is more than seven days before, or more than five minutes after, the
+ * moment it receives it (`usageEventOccurrenceIssue`, the hub's rule
+ * mirrored in the contract), as `rejected(invalid_event)` and never clamped.
+ * So the poster runs the same comparison against its own clock BEFORE
+ * posting: an event outside the window is never posted, it is HELD, named in
+ * the batch outcome (`{ held: [{ id, reason: 'occurred_at_window' }] }`),
+ * logged at warn and counted (`outcome="held"`). The usage worker re-sends
+ * each held event to the held queue (jobs/pgboss.ts), which re-drives it
+ * after the hold, forever: a future-dated event is posted once its time has
+ * come, a stale one stays held until an operator acts. An event the hub
+ * would refuse on its date is handled where it was made, never counted as a
+ * rejection at the hub.
+ */
+export interface HubUsagePosterOptions {
+  issuerUrl: string;
+  token: HubMachineToken;
+  logger: Logger;
+  timeoutMs?: number | undefined;
+  fetchImpl?: typeof fetch | undefined;
+  /** The clock the date window is judged against (a test seam; `Date.now` by default). */
+  now?: (() => number) | undefined;
+}
+
+/** The reason a held event carries when its `occurredAt` falls outside the hub's window. */
+export const OCCURRED_AT_WINDOW = 'occurred_at_window';
+
+export class HubUsagePostError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HubUsagePostError';
+  }
+}
+
+interface EventResult {
+  /** null when the element did not parse at all (`invalid_event`). */
+  id: string | null;
+  status: 'accepted' | 'duplicate' | 'rejected';
+  reason?: string | undefined;
+  details?: unknown;
+}
+
+/** The sentinel `results()` answers for a batch the hub refused as malformed: dropped whole, never retried. */
+const DROPPED: EventResult[] = [];
+
+export class HubUsagePoster implements UsageDownstream {
+  private readonly url: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+  private readonly now: () => number;
+  /** How many POSTs reached the hub — a test seam. */
+  posts = 0;
+  /** Per-event outcomes as the hub answered them (or as the poster dropped or held them). */
+  readonly events: Counter<'outcome'>;
+  /** Per-batch outcomes: delivered (a hub answer read), retried (an outage), dropped (malformed). */
+  readonly batches: Counter<'outcome'>;
+  /** The counters boot registers on the app's /metrics registry (cloud only: oss never builds a poster). */
+  readonly promMetrics: Counter<string>[];
+
+  constructor(private readonly opts: HubUsagePosterOptions) {
+    this.url = opts.issuerUrl.replace(/\/+$/, '') + '/api/v1/usage/events';
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = opts.timeoutMs ?? 15_000;
+    this.now = opts.now ?? Date.now;
+    // registers: [] — boot attaches these to the app registry; a test builds
+    // a poster without one.
+    this.events = new Counter({
+      name: 'usage_poster_events_total',
+      help: 'Usage events by outcome: accepted, duplicate, rejected (the hub judged it), dropped (malformed batch), held (outside the hub’s occurredAt window, never posted)',
+      labelNames: ['outcome'] as const,
+      registers: []
+    });
+    this.batches = new Counter({
+      name: 'usage_poster_batches_total',
+      help: 'Usage batches by outcome: delivered, retried (an outage, the queue retries), dropped (malformed)',
+      labelNames: ['outcome'] as const,
+      registers: []
+    });
+    this.promMetrics = [this.events, this.batches];
+  }
+
+  async emit(event: UsageEvent): Promise<void> {
+    await this.emitBatch([event]);
+  }
+
+  async emitBatch(all: readonly UsageEvent[]): Promise<UsageBatchOutcome> {
+    const held: Array<{ id: string; reason: string }> = [];
+    const events: UsageEvent[] = [];
+    const receivedAt = new Date(this.now());
+    for (const e of all) {
+      const issue = usageEventOccurrenceIssue(new Date(e.occurredAt), receivedAt);
+      if (issue === null) {
+        events.push(e);
+        continue;
+      }
+      held.push({ id: e.id, reason: OCCURRED_AT_WINDOW });
+      this.opts.logger.warn(
+        { id: e.id, occurredAt: e.occurredAt, issue: issue.message },
+        'usage poster: the event’s occurredAt is outside the hub’s window — held, never posted (counted on usage_poster_events_total{outcome="held"})'
+      );
+    }
+    // Counted once the batch is settled: a post that throws fails the whole
+    // batch (the held events' jobs included) back to the queue, whose retry
+    // judges them again, and would count them twice if the count came first.
+    const outcome = (): UsageBatchOutcome => {
+      if (held.length > 0) this.events.inc({ outcome: 'held' }, held.length);
+      return { held };
+    };
+    if (events.length === 0) return outcome();
+    let results: EventResult[];
+    try {
+      const res = await this.post(events, true);
+      results = await this.results(res, events);
+    } catch (err) {
+      this.batches.inc({ outcome: 'retried' });
+      throw err;
+    }
+    if (results === DROPPED) {
+      this.batches.inc({ outcome: 'dropped' });
+      this.events.inc({ outcome: 'dropped' }, events.length);
+      return outcome();
+    }
+    this.batches.inc({ outcome: 'delivered' });
+    for (const r of results) {
+      this.events.inc({ outcome: r.status });
+      if (r.status === 'rejected') {
+        this.opts.logger.error(
+          { id: r.id, reason: r.reason, details: r.details },
+          'usage poster: the hub rejected an event — dropped (the hub judged it; counted on usage_poster_events_total{outcome="rejected"})'
+        );
+      }
+    }
+    return outcome();
+  }
+
+  private async post(events: readonly UsageEvent[], retryOn401: boolean): Promise<Response> {
+    let token: string;
+    try {
+      token = await this.opts.token.get();
+    } catch (err) {
+      if (err instanceof HubMachineTokenError && err.kind === 'invalid_client') {
+        this.opts.logger.error(
+          'usage poster: the hub refuses this instance’s client — events wait in the queue'
+        );
+      }
+      throw new HubUsagePostError('no machine token');
+    }
+    this.posts += 1;
+    let res: Response;
+    try {
+      res = await this.fetchImpl(this.url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({ events }),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      this.opts.logger.warn(
+        { err, count: events.length },
+        'usage poster: hub unreachable — the batch is retried'
+      );
+      throw new HubUsagePostError('hub unreachable');
+    }
+    if (res.status === 401 && retryOn401) {
+      this.opts.token.invalidate();
+      return this.post(events, false);
+    }
+    return res;
+  }
+
+  private async results(res: Response, events: readonly UsageEvent[]): Promise<EventResult[]> {
+    if (res.ok) {
+      const parsed = usageIngestResultSchema.safeParse(await res.json().catch(() => null));
+      if (!parsed.success) {
+        // Not the hub's answer (a proxy page, a hub regression): an outage,
+        // never a delivery — the batch is retried (PRDCT-2629).
+        this.opts.logger.warn(
+          { status: res.status },
+          'usage poster: the hub answered 2xx without readable results — the batch is retried'
+        );
+        throw new HubUsagePostError('hub answered 2xx without readable results');
+      }
+      // One answer per posted element, in the batch's order (the hub's
+      // contract): a shorter or longer answer is not the hub's, and a tail
+      // it does not name would otherwise be neither counted nor retried.
+      if (parsed.data.results.length !== events.length) {
+        this.opts.logger.warn(
+          { answered: parsed.data.results.length, posted: events.length },
+          'usage poster: the hub answered for a different number of events than posted — the batch is retried'
+        );
+        throw new HubUsagePostError('hub answered a different number of events than posted');
+      }
+      return parsed.data.results;
+    }
+    if (res.status === 400 || res.status === 422) {
+      const body = await res.text().catch(() => '');
+      this.opts.logger.error(
+        { status: res.status, ids: events.map((e) => e.id), body: body.slice(0, 500) },
+        'usage poster: the hub refused the batch as malformed — dropped (a bug, never healed by a retry; counted on usage_poster_events_total{outcome="dropped"})'
+      );
+      return DROPPED;
+    }
+    if (res.status === 403) {
+      this.opts.logger.error(
+        { status: res.status },
+        'usage poster: the hub refuses this client (403) — check the client’s usage:write scope; the batch is retried'
+      );
+      throw new HubUsagePostError('hub answered 403');
+    }
+    if (res.status === 404) {
+      this.opts.logger.warn(
+        'usage poster: the hub has no usage ingest yet (404) — the batch is retried; the hub deploys first'
+      );
+      throw new HubUsagePostError('hub answered 404');
+    }
+    this.opts.logger.warn(
+      { status: res.status },
+      'usage poster: the hub answered non-2xx — the batch is retried'
+    );
+    throw new HubUsagePostError(`hub answered ${res.status}`);
+  }
+}