@crowdsource.you/core 1.2.0 → 1.3.0

package/README.md

@@ -14,12 +14,13 @@ transactional outbox and the test sandbox are entry points of the same package.
 | `@crowdsource.you/core/outbox/postgres` | The PostgreSQL store behind `/outbox`: table definitions and the store itself. | as above |
 | `@crowdsource.you/core/testing` | Fixtures, a webhook simulator and an in-process sandbox. | nothing beyond contracts |
 
-**Importing the root pulls in none of `express`, `drizzle-orm`, `postgres` or
-`@oxy.so/db`.** They are OPTIONAL peer dependencies, reached only through
-`/express` and `/outbox`, so an application that files reports and nothing else
-installs a client and a contracts package and stops there. That is the whole
-reason the receiver and the outbox are subpaths rather than a second package:
-there is no version of this package that can disagree with itself.
+**Importing the root pulls in none of `express`, `drizzle-orm`, `postgres`,
+`@oxy.so/db` or `@oxy.so/core`.** They are OPTIONAL peer dependencies, reached
+only through `/express`, `/outbox` and — for `@oxy.so/core` — a lazy require
+inside `crowdSourceForOxyService()`, so an application that files reports and
+nothing else installs a client and a contracts package and stops there. That is
+the whole reason the receiver and the outbox are subpaths rather than a second
+package: there is no version of this package that can disagree with itself.
 
 `@crowdsource.you/contracts` stays a package of its own, and is a **peer
 dependency** here, so you declare it and own its version. That is deliberate:
@@ -107,6 +108,7 @@ Anything in that table can be overridden per report. Nothing in it has to be.
 | --- | --- |
 | `CROWDSOURCE_SERVICE_KEY` | Required for a third party. The one value an integration configures. An Oxy service sets `oxyToken` instead and configures nothing — see "Oxy's own services" below. |
 | `CROWDSOURCE_BASE_URL` | Optional. Overrides the service host — set it only to point at a local backend. `http://` is accepted for `localhost` and refused for anything else, because a service credential sent in clear is a credential you have to rotate. |
+| `OXY_SERVICE_API_KEY` / `OXY_SERVICE_API_SECRET` | Read only by `crowdSourceForOxyService()`, and only where the workload cannot attest. An Oxy service already sets them for the rest of its Oxy calls. Both or neither — one alone, or either left blank, reads as no credential. |
 
 There is **no** `CROWDSOURCE_APP_ID` and there never will be. The application a
 report belongs to is read off the credential; see "The service key" below.
@@ -135,14 +137,38 @@ report belongs to is read off the credential; see "The service key" below.
 
 Mention, Alia, Homiio and the rest hold no service key. They present the Oxy
 service token their own infrastructure already issues, and CrowdSource resolves
-the tenant from the Oxy application it names:
+the tenant from the Oxy application it names — so there is one call and nothing
+to configure:
 
 ```ts
-const crowdsource = new CrowdSource({
-  oxyToken: () => oxyServices.getServiceToken(),
-});
+import { crowdSourceForOxyService } from '@crowdsource.you/core';
+
+const crowdsource = crowdSourceForOxyService();   // undefined where it cannot authenticate
 ```
 
+Three applications each carried their own copy of this: build the client once,
+hand back `undefined` where it cannot be used. None of that was theirs to decide,
+so it lives here now.
+
+- **Built once per process.** Later calls return the same client whatever they
+  ask for; a second one would re-resolve the same tenant and be told the same
+  thing.
+- **`undefined`, never a throw**, where the process can neither attest a workload
+  identity (ADR 0026) nor present an `OXY_SERVICE_API_KEY`/`OXY_SERVICE_API_SECRET`
+  pair. That is a local checkout, and a report filed there must still be stored —
+  the durable row is never gated, and what to do about a missing client is the
+  caller's decision.
+- **`oxyToken` defaults to `@oxy.so/core`'s `getServiceToken()`**, which is an
+  **optional** peer dependency required lazily on this path only. A third party
+  never installs it, and the root import works in a tree without it. Pass your
+  own provider and it is used in place of the default.
+- **`baseUrl` and `logger` are the only other options.** Timeouts, retries, the
+  idempotency key and the envelope are the client's and are not re-asked here.
+  With a logger, the tenant is resolved once in the background and reported, so a
+  token minted for an Oxy application nobody bound is visible at boot rather than
+  on the first report. Nothing waits on it.
+- **`resetCrowdSourceForOxyService()`** is the test hook.
+
 `oxyToken` is asked once per request attempt, so a cached token refreshed on
 expiry is the expected shape — which is what `getServiceToken()` returns. With it
 set, `CROWDSOURCE_SERVICE_KEY` is neither needed nor read, and there is nothing

package/dist/esm/index.js

@@ -34,6 +34,12 @@
  * `Decision` or a `TaxonomyCode` has exactly one definition.
  */
 export { CrowdSource, SERVICE_KEY_ENV_VAR, BASE_URL_ENV_VAR } from './client.js';
+/**
+ * The first-party shortcut. `@oxy.so/core` is an OPTIONAL peer and is required
+ * lazily inside the factory, so this export costs a consumer that never calls it
+ * nothing — the root entry point still loads in a tree that has no Oxy SDK.
+ */
+export { crowdSourceForOxyService, resetCrowdSourceForOxyService } from './oxyService.js';
 export { formatServiceKey, parseServiceKey } from './credential.js';
 export { COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS, DEFAULT_BASE_URL, DEFAULT_POLICY, DEFAULT_RETENTION_DAYS, } from './defaults.js';
 export { canonicalJson, resourceDigest, sha256Digest } from './digest.js';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGjF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EACL,sCAAsC,EACtC,gBAAgB,EAChB,cAAc,EACd,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG1E;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAWnF,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAUzD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGjF;;;;GAIG;AACH,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAG1F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EACL,sCAAsC,EACtC,gBAAgB,EAChB,cAAc,EACd,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG1E;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAWnF,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAUzD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/esm/oxySdk.js

@@ -0,0 +1,134 @@
+/**
+ * The two things this package borrows from `@oxy.so/core`, loaded only when a
+ * first-party Oxy service asks for them.
+ *
+ * `@oxy.so/core` is an OPTIONAL peer dependency. A third party integrating with
+ * CrowdSource holds a service key and must never be made to install Oxy's SDK to
+ * get one, so nothing here is imported at module load: the root entry point has
+ * to stay loadable in a tree where `@oxy.so/core` is simply absent, and a static
+ * import would make `import '@crowdsource.you/core'` throw there — for everyone,
+ * over a path almost nobody takes.
+ *
+ * ## Why `createRequire` and not `import()`
+ *
+ * `crowdSourceForOxyService()` answers synchronously, because it is called where
+ * a module-level `const` is assigned; an application that had to await its
+ * client would have to await every module that holds one. A dynamic `import()`
+ * is a promise in the ESM half of this build, so the load has to be a require.
+ *
+ * Resolution is anchored on the APPLICATION's directory rather than on this
+ * file. One anchor that works in both halves of a dual build is the reason:
+ * `__filename` does not exist in the ESM emit and `import.meta.url` does not
+ * compile in the CommonJS one, whereas `process.cwd()` is the same in both. An
+ * optional peer belongs to the application anyway — it is the application that
+ * declared and installed it.
+ *
+ * A specifier that does not resolve is not an error here. It is the honest
+ * answer to "is this an Oxy service": a process without Oxy's SDK cannot mint an
+ * Oxy service token, which is the same answer a local checkout gets.
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+/** The api key half of an Oxy service credential. */
+export const OXY_SERVICE_API_KEY_ENV_VAR = 'OXY_SERVICE_API_KEY';
+/** Its secret half. Both or neither: one alone authenticates nothing. */
+export const OXY_SERVICE_API_SECRET_ENV_VAR = 'OXY_SERVICE_API_SECRET';
+/**
+ * Where to resolve the optional peer FROM, in the order worth trying.
+ *
+ * The application's directory first: an optional peer belongs to the
+ * application, which is what declared and installed it. Then this file, when the
+ * running half of the dual build has a `__filename` — the CommonJS one does, the
+ * ESM one does not, and `typeof` is what makes asking safe in both. That second
+ * anchor is not decoration: a process whose working directory is not its package
+ * root resolves nothing from the first, and the answer would be a silent
+ * "cannot attest" — a moderation client that is `undefined` for a reason nobody
+ * can see, which is precisely the failure this module is supposed to prevent.
+ */
+function resolutionAnchors() {
+    const anchors = [join(process.cwd(), 'package.json')];
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof __filename === 'string')
+        anchors.push(__filename);
+    return anchors;
+}
+/** Why the last load failed, for a caller that has somewhere to report it. */
+let lastResolutionError = null;
+/**
+ * The loader itself, for the one test that has to prove a successful resolution
+ * clears the recorded reason. Exported rather than re-implemented in the suite:
+ * a test that reimplemented it would pass while this one rotted.
+ */
+export function loadOptionalModuleForTest(specifier) {
+    return loadOxyModule(specifier);
+}
+/** The reason `@oxy.so/core` could not be loaded, or `null` if it was. */
+export function oxySdkResolutionError() {
+    return lastResolutionError;
+}
+function loadOxyModule(specifier) {
+    let failure;
+    for (const anchor of resolutionAnchors()) {
+        try {
+            const loaded = createRequire(anchor)(specifier);
+            lastResolutionError = null;
+            return loaded;
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    lastResolutionError = `${specifier}: ${failure instanceof Error ? failure.message : String(failure)}`;
+    return null;
+}
+/**
+ * Whether this process can prove what it is to Oxy without a secret.
+ *
+ * In ECS the task role attests — a signed `GetCallerIdentity` that Oxy replays
+ * to AWS, with nothing stored anywhere (oxy ADR 0026). A local checkout has no
+ * attestation to offer and must fall back to a credential.
+ */
+export function canAttestWorkloadIdentity() {
+    const server = loadOxyModule('@oxy.so/core/server');
+    return server?.canAttestWorkloadIdentity?.() === true;
+}
+/**
+ * The service credential pair this process was given, or `null`.
+ *
+ * Blank is absent. A task definition that declares the variable and leaves it
+ * empty is the shape this actually arrives in, and a pair of empty strings
+ * treated as present builds a client whose every request fails at the token
+ * call — the failure this whole module exists to answer before it happens.
+ */
+export function oxyServiceCredentials() {
+    const apiKey = process.env[OXY_SERVICE_API_KEY_ENV_VAR]?.trim();
+    const apiSecret = process.env[OXY_SERVICE_API_SECRET_ENV_VAR]?.trim();
+    if (!apiKey || !apiSecret)
+        return null;
+    return { apiKey, apiSecret };
+}
+/**
+ * A current Oxy service token, minted the way `@oxy.so/core` mints one.
+ *
+ * The credential pair is passed rather than installed with
+ * `configureServiceAuth()`, so this never mutates the SDK's shared client out
+ * from under an application that configured it for itself. With no pair,
+ * `getServiceToken()` attests instead — the same order the SDK chose
+ * deliberately, so that a deployment still holding a credential keeps using it
+ * and dropping the two variables is the whole migration.
+ *
+ * The token is cached and re-minted on expiry INSIDE the SDK, which is why this
+ * can be asked once per request attempt.
+ */
+export function oxyServiceToken() {
+    const core = loadOxyModule('@oxy.so/core');
+    const oxyClient = core?.oxyClient;
+    if (oxyClient === undefined) {
+        return Promise.reject(new Error("@oxy.so/core is not installed, so this process cannot mint an Oxy service token. Install it, or pass an 'oxyToken' provider of your own."));
+    }
+    const credentials = oxyServiceCredentials();
+    return credentials === null
+        ? oxyClient.getServiceToken()
+        : oxyClient.getServiceToken(credentials.apiKey, credentials.apiSecret);
+}
+//# sourceMappingURL=oxySdk.js.map

package/dist/esm/oxySdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxySdk.js","sourceRoot":"","sources":["../../src/oxySdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,qDAAqD;AACrD,MAAM,CAAC,MAAM,2BAA2B,GAAG,qBAAqB,CAAC;AAEjE,yEAAyE;AACzE,MAAM,CAAC,MAAM,8BAA8B,GAAG,wBAAwB,CAAC;AA0BvE;;;;;;;;;;;GAWG;AACH,SAAS,iBAAiB;IACxB,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,uEAAuE;IACvE,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,IAAI,mBAAmB,GAAkB,IAAI,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,OAAO,aAAa,CAAU,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB;IACnC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,SAAS,aAAa,CAAI,SAAiB;IACzC,IAAI,OAAgB,CAAC;IACrB,KAAK,MAAM,MAAM,IAAI,iBAAiB,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,SAAS,CAAM,CAAC;YACrD,mBAAmB,GAAG,IAAI,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IACD,mBAAmB,GAAG,GAAG,SAAS,KAAK,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IACtG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,MAAM,GAAG,aAAa,CAAkB,qBAAqB,CAAC,CAAC;IACrE,OAAO,MAAM,EAAE,yBAAyB,EAAE,EAAE,KAAK,IAAI,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,EAAE,IAAI,EAAE,CAAC;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,EAAE,IAAI,EAAE,CAAC;IACtE,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,IAAI,GAAG,aAAa,CAAgB,cAAc,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,CAAC;IAClC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,KAAK,CACP,0IAA0I,CAC3I,CACF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,EAAE,CAAC;IAC5C,OAAO,WAAW,KAAK,IAAI;QACzB,CAAC,CAAC,SAAS,CAAC,eAAe,EAAE;QAC7B,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;AAC3E,CAAC"}

package/dist/esm/oxyService.js

@@ -0,0 +1,123 @@
+/**
+ * The client a first-party Oxy service gets, with nothing to configure.
+ *
+ * Three Oxy applications each carried their own copy of this file — Mention at
+ * 110 lines, Homiio at 70, Allo at 69, the second being the first with the name
+ * swapped. All three answered the same two questions, in the same order, with
+ * the same doc comments: build the client once, and hand back `undefined`
+ * where it cannot be used. None of that is an application's decision, so none of
+ * it belongs in an application.
+ *
+ * What this deliberately does NOT do is re-answer anything the client already
+ * answers. The base URL, the per-attempt deadline, the bounded retries, the
+ * idempotency key, the envelope and the error classification are the client's,
+ * and a factory that re-exposed them would be a second answer to a question that
+ * has one. `baseUrl` is here because a developer pointing at a local backend has
+ * nowhere else to say so; everything else is reached by constructing
+ * {@link CrowdSource} yourself.
+ *
+ * A third party does not use this. It holds a CrowdSource service key — it runs
+ * where Oxy cannot vouch for it — and `new CrowdSource()` reads that key from
+ * the environment.
+ */
+import { CrowdSource } from './client.js';
+import { canAttestWorkloadIdentity, oxySdkResolutionError, oxyServiceCredentials, oxyServiceToken, } from './oxySdk.js';
+let client = null;
+let unavailable = null;
+/**
+ * Whether this process can act as its Oxy application at all.
+ *
+ * Two ways, and a deployment has one of them without anybody configuring it: in
+ * ECS the task role attests (there is no secret), and elsewhere a service api
+ * key pair does. A local checkout has neither, which is the honest answer to "is
+ * the integration on here" — and the reason this is not a `CROWDSOURCE_ENABLED`
+ * flag. A flag says what somebody typed; this says what the process can do.
+ *
+ * Asked up front rather than discovered on the first report, and asked even when
+ * the caller brought its own `oxyToken`: that provider mints from the same two
+ * identities, so a process with neither would hand out a client whose every
+ * request fails at the token call.
+ */
+function canAuthenticateAsOxyService() {
+    return canAttestWorkloadIdentity() || oxyServiceCredentials() !== null;
+}
+/**
+ * The client, or `undefined` where this process cannot authenticate as its Oxy
+ * application.
+ *
+ * `undefined` rather than a throw, and this is the property the three copies
+ * were written for: a local checkout has no workload identity and no credential
+ * pair, and a report filed there must still be STORED. What to do about a
+ * missing client is the caller's decision — the outbox row is durable either
+ * way, and the delivery worker is what notices there is nowhere to send it.
+ *
+ * Built once per process, and every later call returns that same instance
+ * whatever options it passes. A second client would ask CrowdSource which tenant
+ * this token names all over again and be told the same thing.
+ *
+ * The reason for `undefined` is logged once, not per call, because the
+ * alternative is a line per delivery attempt per report — which buries the cause
+ * it is meant to reveal.
+ */
+export function crowdSourceForOxyService(options = {}) {
+    if (client)
+        return client;
+    if (unavailable !== null)
+        return undefined;
+    if (!canAuthenticateAsOxyService()) {
+        unavailable = 'this process cannot obtain an Oxy service token';
+        /**
+         * Say WHY when the reason is that Oxy's SDK could not be loaded at all.
+         *
+         * "Cannot obtain a token" is the right answer for a local checkout and the
+         * wrong-looking one for a deployment that has `@oxy.so/core` installed and
+         * a task role to attest with: there the cause is a resolution that failed,
+         * and without this line an application reads a switched-off integration as
+         * intended behaviour.
+         */
+        const resolution = oxySdkResolutionError();
+        options.logger?.info('[CrowdSource] client not built', {
+            reason: unavailable,
+            ...(resolution === null ? {} : { oxySdk: resolution }),
+        });
+        return undefined;
+    }
+    client = new CrowdSource({
+        oxyToken: options.oxyToken ?? oxyServiceToken,
+        ...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
+    });
+    if (options.logger !== undefined)
+        reportTenant(client, options.logger);
+    return client;
+}
+/**
+ * Resolve the tenant once, in the background, so a missing BINDING is visible at
+ * boot rather than on the first report.
+ *
+ * A token this deployment can mint for an Oxy application nobody bound to a
+ * CrowdSource tenant authenticates nothing, and that failure is otherwise
+ * indistinguishable from "no reports yet". Nothing waits on it: the client is
+ * returned already usable, the client resolves the same promise for its own
+ * calls, and a rejection here is a log line rather than a broken boot — which is
+ * why the rejection handler is attached in the same expression rather than left
+ * to an unhandled-rejection handler somebody else owns.
+ *
+ * Only with a logger. The resolution exists to be REPORTED; with nowhere to
+ * report it, it would be a request at boot whose answer nobody reads, and the
+ * client asks the same question on first use anyway.
+ */
+function reportTenant(built, logger) {
+    void Promise.resolve(built.applicationId).then((applicationId) => {
+        logger.info('[CrowdSource] client ready', { applicationId });
+    }, (error) => {
+        logger.error('[CrowdSource] client built but the tenant did not resolve', {
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    });
+}
+/** Test hook. Production builds the client once and keeps it for the process. */
+export function resetCrowdSourceForOxyService() {
+    client = null;
+    unavailable = null;
+}
+//# sourceMappingURL=oxyService.js.map

package/dist/esm/oxyService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxyService.js","sourceRoot":"","sources":["../../src/oxyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAC;AA+BrB,IAAI,MAAM,GAAuB,IAAI,CAAC;AACtC,IAAI,WAAW,GAAkB,IAAI,CAAC;AAEtC;;;;;;;;;;;;;GAaG;AACH,SAAS,2BAA2B;IAClC,OAAO,yBAAyB,EAAE,IAAI,qBAAqB,EAAE,KAAK,IAAI,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAmC,EAAE;IAErC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAE3C,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC;QACnC,WAAW,GAAG,iDAAiD,CAAC;QAChE;;;;;;;;WAQG;QACH,MAAM,UAAU,GAAG,qBAAqB,EAAE,CAAC;QAC3C,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,gCAAgC,EAAE;YACrD,MAAM,EAAE,WAAW;YACnB,GAAG,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;SACvD,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,GAAG,IAAI,WAAW,CAAC;QACvB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,eAAe;QAC7C,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;KACvE,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,YAAY,CAAC,KAAkB,EAAE,MAA8B;IACtE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAC5C,CAAC,aAAa,EAAE,EAAE;QAChB,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAC/D,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;QACjB,MAAM,CAAC,KAAK,CAAC,2DAA2D,EAAE;YACxE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC/D,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,6BAA6B;IAC3C,MAAM,GAAG,IAAI,CAAC;IACd,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -35,6 +35,13 @@
  */
 export { CrowdSource, SERVICE_KEY_ENV_VAR, BASE_URL_ENV_VAR } from './client.js';
 export type { CrowdSourceOptions } from './client.js';
+/**
+ * The first-party shortcut. `@oxy.so/core` is an OPTIONAL peer and is required
+ * lazily inside the factory, so this export costs a consumer that never calls it
+ * nothing — the root entry point still loads in a tree that has no Oxy SDK.
+ */
+export { crowdSourceForOxyService, resetCrowdSourceForOxyService } from './oxyService.js';
+export type { OxyServiceClientLogger, OxyServiceClientOptions } from './oxyService.js';
 export { formatServiceKey, parseServiceKey } from './credential.js';
 export type { ServiceCredential } from './credential.js';
 export { COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS, DEFAULT_BASE_URL, DEFAULT_POLICY, DEFAULT_RETENTION_DAYS, } from './defaults.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EACL,sCAAsC,EACtC,gBAAgB,EAChB,cAAc,EACd,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnF,YAAY,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,6BAA6B,EAC7B,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;GAIG;AACH,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAC1F,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EACL,sCAAsC,EACtC,gBAAgB,EAChB,cAAc,EACd,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnF,YAAY,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,6BAA6B,EAC7B,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -35,11 +35,19 @@
  * `Decision` or a `TaxonomyCode` has exactly one definition.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.WebhookEndpoints = exports.CommunityNotes = exports.Decisions = exports.Cases = exports.Reports = exports.isCrowdSourceError = exports.isCrowdSourceApiErrorCode = exports.isCrowdSourceApiError = exports.CrowdSourceTransportError = exports.CrowdSourceError = exports.CrowdSourceConfigurationError = exports.CrowdSourceApiError = exports.CROWDSOURCE_API_ERROR_CODES = exports.defaultIdempotencyKey = exports.CrowdSourceReportInputError = exports.sha256Digest = exports.resourceDigest = exports.canonicalJson = exports.DEFAULT_RETENTION_DAYS = exports.DEFAULT_POLICY = exports.DEFAULT_BASE_URL = exports.COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS = exports.parseServiceKey = exports.formatServiceKey = exports.BASE_URL_ENV_VAR = exports.SERVICE_KEY_ENV_VAR = exports.CrowdSource = void 0;
+exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.WebhookEndpoints = exports.CommunityNotes = exports.Decisions = exports.Cases = exports.Reports = exports.isCrowdSourceError = exports.isCrowdSourceApiErrorCode = exports.isCrowdSourceApiError = exports.CrowdSourceTransportError = exports.CrowdSourceError = exports.CrowdSourceConfigurationError = exports.CrowdSourceApiError = exports.CROWDSOURCE_API_ERROR_CODES = exports.defaultIdempotencyKey = exports.CrowdSourceReportInputError = exports.sha256Digest = exports.resourceDigest = exports.canonicalJson = exports.DEFAULT_RETENTION_DAYS = exports.DEFAULT_POLICY = exports.DEFAULT_BASE_URL = exports.COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS = exports.parseServiceKey = exports.formatServiceKey = exports.resetCrowdSourceForOxyService = exports.crowdSourceForOxyService = exports.BASE_URL_ENV_VAR = exports.SERVICE_KEY_ENV_VAR = exports.CrowdSource = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "CrowdSource", { enumerable: true, get: function () { return client_js_1.CrowdSource; } });
 Object.defineProperty(exports, "SERVICE_KEY_ENV_VAR", { enumerable: true, get: function () { return client_js_1.SERVICE_KEY_ENV_VAR; } });
 Object.defineProperty(exports, "BASE_URL_ENV_VAR", { enumerable: true, get: function () { return client_js_1.BASE_URL_ENV_VAR; } });
+/**
+ * The first-party shortcut. `@oxy.so/core` is an OPTIONAL peer and is required
+ * lazily inside the factory, so this export costs a consumer that never calls it
+ * nothing — the root entry point still loads in a tree that has no Oxy SDK.
+ */
+var oxyService_js_1 = require("./oxyService.js");
+Object.defineProperty(exports, "crowdSourceForOxyService", { enumerable: true, get: function () { return oxyService_js_1.crowdSourceForOxyService; } });
+Object.defineProperty(exports, "resetCrowdSourceForOxyService", { enumerable: true, get: function () { return oxyService_js_1.resetCrowdSourceForOxyService; } });
 var credential_js_1 = require("./credential.js");
 Object.defineProperty(exports, "formatServiceKey", { enumerable: true, get: function () { return credential_js_1.formatServiceKey; } });
 Object.defineProperty(exports, "parseServiceKey", { enumerable: true, get: function () { return credential_js_1.parseServiceKey; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,yCAAiF;AAAxE,wGAAA,WAAW,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAG3D,iDAAoE;AAA3D,iHAAA,gBAAgB,OAAA;AAAE,gHAAA,eAAe,OAAA;AAG1C,6CAKuB;AAJrB,qIAAA,sCAAsC,OAAA;AACtC,+GAAA,gBAAgB,OAAA;AAChB,6GAAA,cAAc,OAAA;AACd,qHAAA,sBAAsB,OAAA;AAGxB,yCAA0E;AAAjE,0GAAA,aAAa,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,yGAAA,YAAY,OAAA;AAGpD;;;;;;;;;GASG;AACH,6CAAmF;AAA1E,0HAAA,2BAA2B,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AAW3D,yCASqB;AARnB,wHAAA,2BAA2B,OAAA;AAC3B,gHAAA,mBAAmB,OAAA;AACnB,0HAAA,6BAA6B,OAAA;AAC7B,6GAAA,gBAAgB,OAAA;AAChB,sHAAA,yBAAyB,OAAA;AACzB,kHAAA,qBAAqB,OAAA;AACrB,sHAAA,yBAAyB,OAAA;AACzB,+GAAA,kBAAkB,OAAA;AAIpB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAGhB,uCAA8C;AAArC,iGAAA,KAAK,OAAA;AAAE,qGAAA,SAAS,OAAA;AAIzB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AAGvB,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAUzB,+CAA0E;AAAjE,oHAAA,oBAAoB,OAAA;AAAE,kHAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,yCAAiF;AAAxE,wGAAA,WAAW,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAG3D;;;;GAIG;AACH,iDAA0F;AAAjF,yHAAA,wBAAwB,OAAA;AAAE,8HAAA,6BAA6B,OAAA;AAGhE,iDAAoE;AAA3D,iHAAA,gBAAgB,OAAA;AAAE,gHAAA,eAAe,OAAA;AAG1C,6CAKuB;AAJrB,qIAAA,sCAAsC,OAAA;AACtC,+GAAA,gBAAgB,OAAA;AAChB,6GAAA,cAAc,OAAA;AACd,qHAAA,sBAAsB,OAAA;AAGxB,yCAA0E;AAAjE,0GAAA,aAAa,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,yGAAA,YAAY,OAAA;AAGpD;;;;;;;;;GASG;AACH,6CAAmF;AAA1E,0HAAA,2BAA2B,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AAW3D,yCASqB;AARnB,wHAAA,2BAA2B,OAAA;AAC3B,gHAAA,mBAAmB,OAAA;AACnB,0HAAA,6BAA6B,OAAA;AAC7B,6GAAA,gBAAgB,OAAA;AAChB,sHAAA,yBAAyB,OAAA;AACzB,kHAAA,qBAAqB,OAAA;AACrB,sHAAA,yBAAyB,OAAA;AACzB,+GAAA,kBAAkB,OAAA;AAIpB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAGhB,uCAA8C;AAArC,iGAAA,KAAK,OAAA;AAAE,qGAAA,SAAS,OAAA;AAIzB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AAGvB,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AAUzB,+CAA0E;AAAjE,oHAAA,oBAAoB,OAAA;AAAE,kHAAA,kBAAkB,OAAA"}

package/dist/oxySdk.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The two things this package borrows from `@oxy.so/core`, loaded only when a
+ * first-party Oxy service asks for them.
+ *
+ * `@oxy.so/core` is an OPTIONAL peer dependency. A third party integrating with
+ * CrowdSource holds a service key and must never be made to install Oxy's SDK to
+ * get one, so nothing here is imported at module load: the root entry point has
+ * to stay loadable in a tree where `@oxy.so/core` is simply absent, and a static
+ * import would make `import '@crowdsource.you/core'` throw there — for everyone,
+ * over a path almost nobody takes.
+ *
+ * ## Why `createRequire` and not `import()`
+ *
+ * `crowdSourceForOxyService()` answers synchronously, because it is called where
+ * a module-level `const` is assigned; an application that had to await its
+ * client would have to await every module that holds one. A dynamic `import()`
+ * is a promise in the ESM half of this build, so the load has to be a require.
+ *
+ * Resolution is anchored on the APPLICATION's directory rather than on this
+ * file. One anchor that works in both halves of a dual build is the reason:
+ * `__filename` does not exist in the ESM emit and `import.meta.url` does not
+ * compile in the CommonJS one, whereas `process.cwd()` is the same in both. An
+ * optional peer belongs to the application anyway — it is the application that
+ * declared and installed it.
+ *
+ * A specifier that does not resolve is not an error here. It is the honest
+ * answer to "is this an Oxy service": a process without Oxy's SDK cannot mint an
+ * Oxy service token, which is the same answer a local checkout gets.
+ */
+/** The api key half of an Oxy service credential. */
+export declare const OXY_SERVICE_API_KEY_ENV_VAR = "OXY_SERVICE_API_KEY";
+/** Its secret half. Both or neither: one alone authenticates nothing. */
+export declare const OXY_SERVICE_API_SECRET_ENV_VAR = "OXY_SERVICE_API_SECRET";
+/**
+ * The loader itself, for the one test that has to prove a successful resolution
+ * clears the recorded reason. Exported rather than re-implemented in the suite:
+ * a test that reimplemented it would pass while this one rotted.
+ */
+export declare function loadOptionalModuleForTest(specifier: string): unknown;
+/** The reason `@oxy.so/core` could not be loaded, or `null` if it was. */
+export declare function oxySdkResolutionError(): string | null;
+/**
+ * Whether this process can prove what it is to Oxy without a secret.
+ *
+ * In ECS the task role attests — a signed `GetCallerIdentity` that Oxy replays
+ * to AWS, with nothing stored anywhere (oxy ADR 0026). A local checkout has no
+ * attestation to offer and must fall back to a credential.
+ */
+export declare function canAttestWorkloadIdentity(): boolean;
+/**
+ * The service credential pair this process was given, or `null`.
+ *
+ * Blank is absent. A task definition that declares the variable and leaves it
+ * empty is the shape this actually arrives in, and a pair of empty strings
+ * treated as present builds a client whose every request fails at the token
+ * call — the failure this whole module exists to answer before it happens.
+ */
+export declare function oxyServiceCredentials(): {
+    apiKey: string;
+    apiSecret: string;
+} | null;
+/**
+ * A current Oxy service token, minted the way `@oxy.so/core` mints one.
+ *
+ * The credential pair is passed rather than installed with
+ * `configureServiceAuth()`, so this never mutates the SDK's shared client out
+ * from under an application that configured it for itself. With no pair,
+ * `getServiceToken()` attests instead — the same order the SDK chose
+ * deliberately, so that a deployment still holding a credential keeps using it
+ * and dropping the two variables is the whole migration.
+ *
+ * The token is cached and re-minted on expiry INSIDE the SDK, which is why this
+ * can be asked once per request attempt.
+ */
+export declare function oxyServiceToken(): Promise<string>;
+//# sourceMappingURL=oxySdk.d.ts.map

package/dist/oxySdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxySdk.d.ts","sourceRoot":"","sources":["../src/oxySdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,qDAAqD;AACrD,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,8BAA8B,2BAA2B,CAAC;AAgDvE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAiBD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAGnD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAejD"}

package/dist/oxySdk.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * The two things this package borrows from `@oxy.so/core`, loaded only when a
+ * first-party Oxy service asks for them.
+ *
+ * `@oxy.so/core` is an OPTIONAL peer dependency. A third party integrating with
+ * CrowdSource holds a service key and must never be made to install Oxy's SDK to
+ * get one, so nothing here is imported at module load: the root entry point has
+ * to stay loadable in a tree where `@oxy.so/core` is simply absent, and a static
+ * import would make `import '@crowdsource.you/core'` throw there — for everyone,
+ * over a path almost nobody takes.
+ *
+ * ## Why `createRequire` and not `import()`
+ *
+ * `crowdSourceForOxyService()` answers synchronously, because it is called where
+ * a module-level `const` is assigned; an application that had to await its
+ * client would have to await every module that holds one. A dynamic `import()`
+ * is a promise in the ESM half of this build, so the load has to be a require.
+ *
+ * Resolution is anchored on the APPLICATION's directory rather than on this
+ * file. One anchor that works in both halves of a dual build is the reason:
+ * `__filename` does not exist in the ESM emit and `import.meta.url` does not
+ * compile in the CommonJS one, whereas `process.cwd()` is the same in both. An
+ * optional peer belongs to the application anyway — it is the application that
+ * declared and installed it.
+ *
+ * A specifier that does not resolve is not an error here. It is the honest
+ * answer to "is this an Oxy service": a process without Oxy's SDK cannot mint an
+ * Oxy service token, which is the same answer a local checkout gets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_SERVICE_API_SECRET_ENV_VAR = exports.OXY_SERVICE_API_KEY_ENV_VAR = void 0;
+exports.loadOptionalModuleForTest = loadOptionalModuleForTest;
+exports.oxySdkResolutionError = oxySdkResolutionError;
+exports.canAttestWorkloadIdentity = canAttestWorkloadIdentity;
+exports.oxyServiceCredentials = oxyServiceCredentials;
+exports.oxyServiceToken = oxyServiceToken;
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+/** The api key half of an Oxy service credential. */
+exports.OXY_SERVICE_API_KEY_ENV_VAR = 'OXY_SERVICE_API_KEY';
+/** Its secret half. Both or neither: one alone authenticates nothing. */
+exports.OXY_SERVICE_API_SECRET_ENV_VAR = 'OXY_SERVICE_API_SECRET';
+/**
+ * Where to resolve the optional peer FROM, in the order worth trying.
+ *
+ * The application's directory first: an optional peer belongs to the
+ * application, which is what declared and installed it. Then this file, when the
+ * running half of the dual build has a `__filename` — the CommonJS one does, the
+ * ESM one does not, and `typeof` is what makes asking safe in both. That second
+ * anchor is not decoration: a process whose working directory is not its package
+ * root resolves nothing from the first, and the answer would be a silent
+ * "cannot attest" — a moderation client that is `undefined` for a reason nobody
+ * can see, which is precisely the failure this module is supposed to prevent.
+ */
+function resolutionAnchors() {
+    const anchors = [(0, node_path_1.join)(process.cwd(), 'package.json')];
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof __filename === 'string')
+        anchors.push(__filename);
+    return anchors;
+}
+/** Why the last load failed, for a caller that has somewhere to report it. */
+let lastResolutionError = null;
+/**
+ * The loader itself, for the one test that has to prove a successful resolution
+ * clears the recorded reason. Exported rather than re-implemented in the suite:
+ * a test that reimplemented it would pass while this one rotted.
+ */
+function loadOptionalModuleForTest(specifier) {
+    return loadOxyModule(specifier);
+}
+/** The reason `@oxy.so/core` could not be loaded, or `null` if it was. */
+function oxySdkResolutionError() {
+    return lastResolutionError;
+}
+function loadOxyModule(specifier) {
+    let failure;
+    for (const anchor of resolutionAnchors()) {
+        try {
+            const loaded = (0, node_module_1.createRequire)(anchor)(specifier);
+            lastResolutionError = null;
+            return loaded;
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    lastResolutionError = `${specifier}: ${failure instanceof Error ? failure.message : String(failure)}`;
+    return null;
+}
+/**
+ * Whether this process can prove what it is to Oxy without a secret.
+ *
+ * In ECS the task role attests — a signed `GetCallerIdentity` that Oxy replays
+ * to AWS, with nothing stored anywhere (oxy ADR 0026). A local checkout has no
+ * attestation to offer and must fall back to a credential.
+ */
+function canAttestWorkloadIdentity() {
+    const server = loadOxyModule('@oxy.so/core/server');
+    return server?.canAttestWorkloadIdentity?.() === true;
+}
+/**
+ * The service credential pair this process was given, or `null`.
+ *
+ * Blank is absent. A task definition that declares the variable and leaves it
+ * empty is the shape this actually arrives in, and a pair of empty strings
+ * treated as present builds a client whose every request fails at the token
+ * call — the failure this whole module exists to answer before it happens.
+ */
+function oxyServiceCredentials() {
+    const apiKey = process.env[exports.OXY_SERVICE_API_KEY_ENV_VAR]?.trim();
+    const apiSecret = process.env[exports.OXY_SERVICE_API_SECRET_ENV_VAR]?.trim();
+    if (!apiKey || !apiSecret)
+        return null;
+    return { apiKey, apiSecret };
+}
+/**
+ * A current Oxy service token, minted the way `@oxy.so/core` mints one.
+ *
+ * The credential pair is passed rather than installed with
+ * `configureServiceAuth()`, so this never mutates the SDK's shared client out
+ * from under an application that configured it for itself. With no pair,
+ * `getServiceToken()` attests instead — the same order the SDK chose
+ * deliberately, so that a deployment still holding a credential keeps using it
+ * and dropping the two variables is the whole migration.
+ *
+ * The token is cached and re-minted on expiry INSIDE the SDK, which is why this
+ * can be asked once per request attempt.
+ */
+function oxyServiceToken() {
+    const core = loadOxyModule('@oxy.so/core');
+    const oxyClient = core?.oxyClient;
+    if (oxyClient === undefined) {
+        return Promise.reject(new Error("@oxy.so/core is not installed, so this process cannot mint an Oxy service token. Install it, or pass an 'oxyToken' provider of your own."));
+    }
+    const credentials = oxyServiceCredentials();
+    return credentials === null
+        ? oxyClient.getServiceToken()
+        : oxyClient.getServiceToken(credentials.apiKey, credentials.apiSecret);
+}
+//# sourceMappingURL=oxySdk.js.map

package/dist/oxySdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxySdk.js","sourceRoot":"","sources":["../src/oxySdk.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AA8DH,8DAEC;AAGD,sDAEC;AAwBD,8DAGC;AAUD,sDAKC;AAeD,0CAeC;AA3ID,6CAA4C;AAC5C,yCAAiC;AAEjC,qDAAqD;AACxC,QAAA,2BAA2B,GAAG,qBAAqB,CAAC;AAEjE,yEAAyE;AAC5D,QAAA,8BAA8B,GAAG,wBAAwB,CAAC;AA0BvE;;;;;;;;;;;GAWG;AACH,SAAS,iBAAiB;IACxB,MAAM,OAAO,GAAG,CAAC,IAAA,gBAAI,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,uEAAuE;IACvE,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,IAAI,mBAAmB,GAAkB,IAAI,CAAC;AAE9C;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,SAAiB;IACzD,OAAO,aAAa,CAAU,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,0EAA0E;AAC1E,SAAgB,qBAAqB;IACnC,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,SAAS,aAAa,CAAI,SAAiB;IACzC,IAAI,OAAgB,CAAC;IACrB,KAAK,MAAM,MAAM,IAAI,iBAAiB,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAA,2BAAa,EAAC,MAAM,CAAC,CAAC,SAAS,CAAM,CAAC;YACrD,mBAAmB,GAAG,IAAI,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IACD,mBAAmB,GAAG,GAAG,SAAS,KAAK,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IACtG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,yBAAyB;IACvC,MAAM,MAAM,GAAG,aAAa,CAAkB,qBAAqB,CAAC,CAAC;IACrE,OAAO,MAAM,EAAE,yBAAyB,EAAE,EAAE,KAAK,IAAI,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,mCAA2B,CAAC,EAAE,IAAI,EAAE,CAAC;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,sCAA8B,CAAC,EAAE,IAAI,EAAE,CAAC;IACtE,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe;IAC7B,MAAM,IAAI,GAAG,aAAa,CAAgB,cAAc,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,CAAC;IAClC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,KAAK,CACP,0IAA0I,CAC3I,CACF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,EAAE,CAAC;IAC5C,OAAO,WAAW,KAAK,IAAI;QACzB,CAAC,CAAC,SAAS,CAAC,eAAe,EAAE;QAC7B,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;AAC3E,CAAC"}

package/dist/oxyService.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The client a first-party Oxy service gets, with nothing to configure.
+ *
+ * Three Oxy applications each carried their own copy of this file — Mention at
+ * 110 lines, Homiio at 70, Allo at 69, the second being the first with the name
+ * swapped. All three answered the same two questions, in the same order, with
+ * the same doc comments: build the client once, and hand back `undefined`
+ * where it cannot be used. None of that is an application's decision, so none of
+ * it belongs in an application.
+ *
+ * What this deliberately does NOT do is re-answer anything the client already
+ * answers. The base URL, the per-attempt deadline, the bounded retries, the
+ * idempotency key, the envelope and the error classification are the client's,
+ * and a factory that re-exposed them would be a second answer to a question that
+ * has one. `baseUrl` is here because a developer pointing at a local backend has
+ * nowhere else to say so; everything else is reached by constructing
+ * {@link CrowdSource} yourself.
+ *
+ * A third party does not use this. It holds a CrowdSource service key — it runs
+ * where Oxy cannot vouch for it — and `new CrowdSource()` reads that key from
+ * the environment.
+ */
+import { CrowdSource } from './client.js';
+/**
+ * Where this factory reports what it did.
+ *
+ * Structurally what every Oxy backend's logger already is, so an application
+ * passes the one it has. There is no default and no fallback to `console`: a
+ * library that writes to stdout on its own is a library that appears in
+ * somebody's logs without ever being asked.
+ */
+export interface OxyServiceClientLogger {
+    info(message: string, context: Record<string, unknown>): void;
+    error(message: string, context: Record<string, unknown>): void;
+}
+export interface OxyServiceClientOptions {
+    /**
+     * A current Oxy service token, asked for once per request attempt.
+     *
+     * Defaults to `@oxy.so/core`'s `getServiceToken()`, which is what an Oxy
+     * service would pass anyway. Set it when the token comes from somewhere else —
+     * an SDK instance configured against a non-default Oxy host, say — and it is
+     * used in place of the default, never alongside it.
+     */
+    readonly oxyToken?: () => string | Promise<string>;
+    /** Defaults to the client's own. Set it only to point at a local backend. */
+    readonly baseUrl?: string;
+    /** Defaults to none, which is silence rather than `console`. */
+    readonly logger?: OxyServiceClientLogger;
+}
+/**
+ * The client, or `undefined` where this process cannot authenticate as its Oxy
+ * application.
+ *
+ * `undefined` rather than a throw, and this is the property the three copies
+ * were written for: a local checkout has no workload identity and no credential
+ * pair, and a report filed there must still be STORED. What to do about a
+ * missing client is the caller's decision — the outbox row is durable either
+ * way, and the delivery worker is what notices there is nowhere to send it.
+ *
+ * Built once per process, and every later call returns that same instance
+ * whatever options it passes. A second client would ask CrowdSource which tenant
+ * this token names all over again and be told the same thing.
+ *
+ * The reason for `undefined` is logged once, not per call, because the
+ * alternative is a line per delivery attempt per report — which buries the cause
+ * it is meant to reveal.
+ */
+export declare function crowdSourceForOxyService(options?: OxyServiceClientOptions): CrowdSource | undefined;
+/** Test hook. Production builds the client once and keeps it for the process. */
+export declare function resetCrowdSourceForOxyService(): void;
+//# sourceMappingURL=oxyService.d.ts.map

package/dist/oxyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxyService.d.ts","sourceRoot":"","sources":["../src/oxyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ1C;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChE;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAC1C;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,uBAA4B,GACpC,WAAW,GAAG,SAAS,CA+BzB;AA+BD,iFAAiF;AACjF,wBAAgB,6BAA6B,IAAI,IAAI,CAGpD"}

package/dist/oxyService.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * The client a first-party Oxy service gets, with nothing to configure.
+ *
+ * Three Oxy applications each carried their own copy of this file — Mention at
+ * 110 lines, Homiio at 70, Allo at 69, the second being the first with the name
+ * swapped. All three answered the same two questions, in the same order, with
+ * the same doc comments: build the client once, and hand back `undefined`
+ * where it cannot be used. None of that is an application's decision, so none of
+ * it belongs in an application.
+ *
+ * What this deliberately does NOT do is re-answer anything the client already
+ * answers. The base URL, the per-attempt deadline, the bounded retries, the
+ * idempotency key, the envelope and the error classification are the client's,
+ * and a factory that re-exposed them would be a second answer to a question that
+ * has one. `baseUrl` is here because a developer pointing at a local backend has
+ * nowhere else to say so; everything else is reached by constructing
+ * {@link CrowdSource} yourself.
+ *
+ * A third party does not use this. It holds a CrowdSource service key — it runs
+ * where Oxy cannot vouch for it — and `new CrowdSource()` reads that key from
+ * the environment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crowdSourceForOxyService = crowdSourceForOxyService;
+exports.resetCrowdSourceForOxyService = resetCrowdSourceForOxyService;
+const client_js_1 = require("./client.js");
+const oxySdk_js_1 = require("./oxySdk.js");
+let client = null;
+let unavailable = null;
+/**
+ * Whether this process can act as its Oxy application at all.
+ *
+ * Two ways, and a deployment has one of them without anybody configuring it: in
+ * ECS the task role attests (there is no secret), and elsewhere a service api
+ * key pair does. A local checkout has neither, which is the honest answer to "is
+ * the integration on here" — and the reason this is not a `CROWDSOURCE_ENABLED`
+ * flag. A flag says what somebody typed; this says what the process can do.
+ *
+ * Asked up front rather than discovered on the first report, and asked even when
+ * the caller brought its own `oxyToken`: that provider mints from the same two
+ * identities, so a process with neither would hand out a client whose every
+ * request fails at the token call.
+ */
+function canAuthenticateAsOxyService() {
+    return (0, oxySdk_js_1.canAttestWorkloadIdentity)() || (0, oxySdk_js_1.oxyServiceCredentials)() !== null;
+}
+/**
+ * The client, or `undefined` where this process cannot authenticate as its Oxy
+ * application.
+ *
+ * `undefined` rather than a throw, and this is the property the three copies
+ * were written for: a local checkout has no workload identity and no credential
+ * pair, and a report filed there must still be STORED. What to do about a
+ * missing client is the caller's decision — the outbox row is durable either
+ * way, and the delivery worker is what notices there is nowhere to send it.
+ *
+ * Built once per process, and every later call returns that same instance
+ * whatever options it passes. A second client would ask CrowdSource which tenant
+ * this token names all over again and be told the same thing.
+ *
+ * The reason for `undefined` is logged once, not per call, because the
+ * alternative is a line per delivery attempt per report — which buries the cause
+ * it is meant to reveal.
+ */
+function crowdSourceForOxyService(options = {}) {
+    if (client)
+        return client;
+    if (unavailable !== null)
+        return undefined;
+    if (!canAuthenticateAsOxyService()) {
+        unavailable = 'this process cannot obtain an Oxy service token';
+        /**
+         * Say WHY when the reason is that Oxy's SDK could not be loaded at all.
+         *
+         * "Cannot obtain a token" is the right answer for a local checkout and the
+         * wrong-looking one for a deployment that has `@oxy.so/core` installed and
+         * a task role to attest with: there the cause is a resolution that failed,
+         * and without this line an application reads a switched-off integration as
+         * intended behaviour.
+         */
+        const resolution = (0, oxySdk_js_1.oxySdkResolutionError)();
+        options.logger?.info('[CrowdSource] client not built', {
+            reason: unavailable,
+            ...(resolution === null ? {} : { oxySdk: resolution }),
+        });
+        return undefined;
+    }
+    client = new client_js_1.CrowdSource({
+        oxyToken: options.oxyToken ?? oxySdk_js_1.oxyServiceToken,
+        ...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
+    });
+    if (options.logger !== undefined)
+        reportTenant(client, options.logger);
+    return client;
+}
+/**
+ * Resolve the tenant once, in the background, so a missing BINDING is visible at
+ * boot rather than on the first report.
+ *
+ * A token this deployment can mint for an Oxy application nobody bound to a
+ * CrowdSource tenant authenticates nothing, and that failure is otherwise
+ * indistinguishable from "no reports yet". Nothing waits on it: the client is
+ * returned already usable, the client resolves the same promise for its own
+ * calls, and a rejection here is a log line rather than a broken boot — which is
+ * why the rejection handler is attached in the same expression rather than left
+ * to an unhandled-rejection handler somebody else owns.
+ *
+ * Only with a logger. The resolution exists to be REPORTED; with nowhere to
+ * report it, it would be a request at boot whose answer nobody reads, and the
+ * client asks the same question on first use anyway.
+ */
+function reportTenant(built, logger) {
+    void Promise.resolve(built.applicationId).then((applicationId) => {
+        logger.info('[CrowdSource] client ready', { applicationId });
+    }, (error) => {
+        logger.error('[CrowdSource] client built but the tenant did not resolve', {
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    });
+}
+/** Test hook. Production builds the client once and keeps it for the process. */
+function resetCrowdSourceForOxyService() {
+    client = null;
+    unavailable = null;
+}
+//# sourceMappingURL=oxyService.js.map

package/dist/oxyService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oxyService.js","sourceRoot":"","sources":["../src/oxyService.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AA8EH,4DAiCC;AAgCD,sEAGC;AAhJD,2CAA0C;AAC1C,2CAKqB;AA+BrB,IAAI,MAAM,GAAuB,IAAI,CAAC;AACtC,IAAI,WAAW,GAAkB,IAAI,CAAC;AAEtC;;;;;;;;;;;;;GAaG;AACH,SAAS,2BAA2B;IAClC,OAAO,IAAA,qCAAyB,GAAE,IAAI,IAAA,iCAAqB,GAAE,KAAK,IAAI,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,wBAAwB,CACtC,UAAmC,EAAE;IAErC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAE3C,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC;QACnC,WAAW,GAAG,iDAAiD,CAAC;QAChE;;;;;;;;WAQG;QACH,MAAM,UAAU,GAAG,IAAA,iCAAqB,GAAE,CAAC;QAC3C,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,gCAAgC,EAAE;YACrD,MAAM,EAAE,WAAW;YACnB,GAAG,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;SACvD,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,GAAG,IAAI,uBAAW,CAAC;QACvB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,2BAAe;QAC7C,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;KACvE,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,YAAY,CAAC,KAAkB,EAAE,MAA8B;IACtE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAC5C,CAAC,aAAa,EAAE,EAAE;QAChB,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAC/D,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;QACjB,MAAM,CAAC,KAAK,CAAC,2DAA2D,EAAE;YACxE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC/D,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAgB,6BAA6B;IAC3C,MAAM,GAAG,IAAI,CAAC;IACd,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdsource.you/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "The CrowdSource integration: the API client at the root, and the Express webhook receiver, the transactional outbox and the test sandbox behind subpaths",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -105,12 +105,16 @@
   ],
   "peerDependencies": {
     "@crowdsource.you/contracts": "^1.1.0",
+    "@oxy.so/core": "^1.6.0",
     "@oxy.so/db": "^1.0.0",
     "drizzle-orm": "^0.45.2",
     "express": ">=4.18.0 <6",
     "postgres": "^3.4.9"
   },
   "peerDependenciesMeta": {
+    "@oxy.so/core": {
+      "optional": true
+    },
     "@oxy.so/db": {
       "optional": true
     },

package/src/index.ts

@@ -37,6 +37,14 @@
 export { CrowdSource, SERVICE_KEY_ENV_VAR, BASE_URL_ENV_VAR } from './client.js';
 export type { CrowdSourceOptions } from './client.js';
 
+/**
+ * The first-party shortcut. `@oxy.so/core` is an OPTIONAL peer and is required
+ * lazily inside the factory, so this export costs a consumer that never calls it
+ * nothing — the root entry point still loads in a tree that has no Oxy SDK.
+ */
+export { crowdSourceForOxyService, resetCrowdSourceForOxyService } from './oxyService.js';
+export type { OxyServiceClientLogger, OxyServiceClientOptions } from './oxyService.js';
+
 export { formatServiceKey, parseServiceKey } from './credential.js';
 export type { ServiceCredential } from './credential.js';
 

package/src/oxySdk.ts

@@ -0,0 +1,170 @@
+/**
+ * The two things this package borrows from `@oxy.so/core`, loaded only when a
+ * first-party Oxy service asks for them.
+ *
+ * `@oxy.so/core` is an OPTIONAL peer dependency. A third party integrating with
+ * CrowdSource holds a service key and must never be made to install Oxy's SDK to
+ * get one, so nothing here is imported at module load: the root entry point has
+ * to stay loadable in a tree where `@oxy.so/core` is simply absent, and a static
+ * import would make `import '@crowdsource.you/core'` throw there — for everyone,
+ * over a path almost nobody takes.
+ *
+ * ## Why `createRequire` and not `import()`
+ *
+ * `crowdSourceForOxyService()` answers synchronously, because it is called where
+ * a module-level `const` is assigned; an application that had to await its
+ * client would have to await every module that holds one. A dynamic `import()`
+ * is a promise in the ESM half of this build, so the load has to be a require.
+ *
+ * Resolution is anchored on the APPLICATION's directory rather than on this
+ * file. One anchor that works in both halves of a dual build is the reason:
+ * `__filename` does not exist in the ESM emit and `import.meta.url` does not
+ * compile in the CommonJS one, whereas `process.cwd()` is the same in both. An
+ * optional peer belongs to the application anyway — it is the application that
+ * declared and installed it.
+ *
+ * A specifier that does not resolve is not an error here. It is the honest
+ * answer to "is this an Oxy service": a process without Oxy's SDK cannot mint an
+ * Oxy service token, which is the same answer a local checkout gets.
+ */
+
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+/** The api key half of an Oxy service credential. */
+export const OXY_SERVICE_API_KEY_ENV_VAR = 'OXY_SERVICE_API_KEY';
+
+/** Its secret half. Both or neither: one alone authenticates nothing. */
+export const OXY_SERVICE_API_SECRET_ENV_VAR = 'OXY_SERVICE_API_SECRET';
+
+/**
+ * `@oxy.so/core/server`, narrowed to the one function this package calls.
+ *
+ * Declared rather than imported as a type. `import type` from an optional peer
+ * compiles only where that peer is installed, so typing this from the package
+ * would make `@crowdsource.you/core` fail to build in a tree that deliberately
+ * does not have it — including this one.
+ *
+ * The member is optional because a peer RANGE is advice, not enforcement:
+ * `^1.6.0` is what this package asks for, and a tree that resolved an older
+ * copy — one with no attestation path at all — has to read as "cannot attest"
+ * rather than as a `TypeError` thrown from inside a moderation client.
+ */
+interface OxyServerModule {
+  readonly canAttestWorkloadIdentity?: () => boolean;
+}
+
+/** `@oxy.so/core`, narrowed to the one object this package calls. */
+interface OxyCoreModule {
+  readonly oxyClient?: {
+    getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+  };
+}
+
+/**
+ * Where to resolve the optional peer FROM, in the order worth trying.
+ *
+ * The application's directory first: an optional peer belongs to the
+ * application, which is what declared and installed it. Then this file, when the
+ * running half of the dual build has a `__filename` — the CommonJS one does, the
+ * ESM one does not, and `typeof` is what makes asking safe in both. That second
+ * anchor is not decoration: a process whose working directory is not its package
+ * root resolves nothing from the first, and the answer would be a silent
+ * "cannot attest" — a moderation client that is `undefined` for a reason nobody
+ * can see, which is precisely the failure this module is supposed to prevent.
+ */
+function resolutionAnchors(): string[] {
+  const anchors = [join(process.cwd(), 'package.json')];
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (typeof __filename === 'string') anchors.push(__filename);
+  return anchors;
+}
+
+/** Why the last load failed, for a caller that has somewhere to report it. */
+let lastResolutionError: string | null = null;
+
+/**
+ * The loader itself, for the one test that has to prove a successful resolution
+ * clears the recorded reason. Exported rather than re-implemented in the suite:
+ * a test that reimplemented it would pass while this one rotted.
+ */
+export function loadOptionalModuleForTest(specifier: string): unknown {
+  return loadOxyModule<unknown>(specifier);
+}
+
+/** The reason `@oxy.so/core` could not be loaded, or `null` if it was. */
+export function oxySdkResolutionError(): string | null {
+  return lastResolutionError;
+}
+
+function loadOxyModule<T>(specifier: string): T | null {
+  let failure: unknown;
+  for (const anchor of resolutionAnchors()) {
+    try {
+      const loaded = createRequire(anchor)(specifier) as T;
+      lastResolutionError = null;
+      return loaded;
+    } catch (error: unknown) {
+      failure = error;
+    }
+  }
+  lastResolutionError = `${specifier}: ${failure instanceof Error ? failure.message : String(failure)}`;
+  return null;
+}
+
+/**
+ * Whether this process can prove what it is to Oxy without a secret.
+ *
+ * In ECS the task role attests — a signed `GetCallerIdentity` that Oxy replays
+ * to AWS, with nothing stored anywhere (oxy ADR 0026). A local checkout has no
+ * attestation to offer and must fall back to a credential.
+ */
+export function canAttestWorkloadIdentity(): boolean {
+  const server = loadOxyModule<OxyServerModule>('@oxy.so/core/server');
+  return server?.canAttestWorkloadIdentity?.() === true;
+}
+
+/**
+ * The service credential pair this process was given, or `null`.
+ *
+ * Blank is absent. A task definition that declares the variable and leaves it
+ * empty is the shape this actually arrives in, and a pair of empty strings
+ * treated as present builds a client whose every request fails at the token
+ * call — the failure this whole module exists to answer before it happens.
+ */
+export function oxyServiceCredentials(): { apiKey: string; apiSecret: string } | null {
+  const apiKey = process.env[OXY_SERVICE_API_KEY_ENV_VAR]?.trim();
+  const apiSecret = process.env[OXY_SERVICE_API_SECRET_ENV_VAR]?.trim();
+  if (!apiKey || !apiSecret) return null;
+  return { apiKey, apiSecret };
+}
+
+/**
+ * A current Oxy service token, minted the way `@oxy.so/core` mints one.
+ *
+ * The credential pair is passed rather than installed with
+ * `configureServiceAuth()`, so this never mutates the SDK's shared client out
+ * from under an application that configured it for itself. With no pair,
+ * `getServiceToken()` attests instead — the same order the SDK chose
+ * deliberately, so that a deployment still holding a credential keeps using it
+ * and dropping the two variables is the whole migration.
+ *
+ * The token is cached and re-minted on expiry INSIDE the SDK, which is why this
+ * can be asked once per request attempt.
+ */
+export function oxyServiceToken(): Promise<string> {
+  const core = loadOxyModule<OxyCoreModule>('@oxy.so/core');
+  const oxyClient = core?.oxyClient;
+  if (oxyClient === undefined) {
+    return Promise.reject(
+      new Error(
+        "@oxy.so/core is not installed, so this process cannot mint an Oxy service token. Install it, or pass an 'oxyToken' provider of your own.",
+      ),
+    );
+  }
+
+  const credentials = oxyServiceCredentials();
+  return credentials === null
+    ? oxyClient.getServiceToken()
+    : oxyClient.getServiceToken(credentials.apiKey, credentials.apiSecret);
+}

package/src/oxyService.ts

@@ -0,0 +1,168 @@
+/**
+ * The client a first-party Oxy service gets, with nothing to configure.
+ *
+ * Three Oxy applications each carried their own copy of this file — Mention at
+ * 110 lines, Homiio at 70, Allo at 69, the second being the first with the name
+ * swapped. All three answered the same two questions, in the same order, with
+ * the same doc comments: build the client once, and hand back `undefined`
+ * where it cannot be used. None of that is an application's decision, so none of
+ * it belongs in an application.
+ *
+ * What this deliberately does NOT do is re-answer anything the client already
+ * answers. The base URL, the per-attempt deadline, the bounded retries, the
+ * idempotency key, the envelope and the error classification are the client's,
+ * and a factory that re-exposed them would be a second answer to a question that
+ * has one. `baseUrl` is here because a developer pointing at a local backend has
+ * nowhere else to say so; everything else is reached by constructing
+ * {@link CrowdSource} yourself.
+ *
+ * A third party does not use this. It holds a CrowdSource service key — it runs
+ * where Oxy cannot vouch for it — and `new CrowdSource()` reads that key from
+ * the environment.
+ */
+
+import { CrowdSource } from './client.js';
+import {
+  canAttestWorkloadIdentity,
+  oxySdkResolutionError,
+  oxyServiceCredentials,
+  oxyServiceToken,
+} from './oxySdk.js';
+
+/**
+ * Where this factory reports what it did.
+ *
+ * Structurally what every Oxy backend's logger already is, so an application
+ * passes the one it has. There is no default and no fallback to `console`: a
+ * library that writes to stdout on its own is a library that appears in
+ * somebody's logs without ever being asked.
+ */
+export interface OxyServiceClientLogger {
+  info(message: string, context: Record<string, unknown>): void;
+  error(message: string, context: Record<string, unknown>): void;
+}
+
+export interface OxyServiceClientOptions {
+  /**
+   * A current Oxy service token, asked for once per request attempt.
+   *
+   * Defaults to `@oxy.so/core`'s `getServiceToken()`, which is what an Oxy
+   * service would pass anyway. Set it when the token comes from somewhere else —
+   * an SDK instance configured against a non-default Oxy host, say — and it is
+   * used in place of the default, never alongside it.
+   */
+  readonly oxyToken?: () => string | Promise<string>;
+  /** Defaults to the client's own. Set it only to point at a local backend. */
+  readonly baseUrl?: string;
+  /** Defaults to none, which is silence rather than `console`. */
+  readonly logger?: OxyServiceClientLogger;
+}
+
+let client: CrowdSource | null = null;
+let unavailable: string | null = null;
+
+/**
+ * Whether this process can act as its Oxy application at all.
+ *
+ * Two ways, and a deployment has one of them without anybody configuring it: in
+ * ECS the task role attests (there is no secret), and elsewhere a service api
+ * key pair does. A local checkout has neither, which is the honest answer to "is
+ * the integration on here" — and the reason this is not a `CROWDSOURCE_ENABLED`
+ * flag. A flag says what somebody typed; this says what the process can do.
+ *
+ * Asked up front rather than discovered on the first report, and asked even when
+ * the caller brought its own `oxyToken`: that provider mints from the same two
+ * identities, so a process with neither would hand out a client whose every
+ * request fails at the token call.
+ */
+function canAuthenticateAsOxyService(): boolean {
+  return canAttestWorkloadIdentity() || oxyServiceCredentials() !== null;
+}
+
+/**
+ * The client, or `undefined` where this process cannot authenticate as its Oxy
+ * application.
+ *
+ * `undefined` rather than a throw, and this is the property the three copies
+ * were written for: a local checkout has no workload identity and no credential
+ * pair, and a report filed there must still be STORED. What to do about a
+ * missing client is the caller's decision — the outbox row is durable either
+ * way, and the delivery worker is what notices there is nowhere to send it.
+ *
+ * Built once per process, and every later call returns that same instance
+ * whatever options it passes. A second client would ask CrowdSource which tenant
+ * this token names all over again and be told the same thing.
+ *
+ * The reason for `undefined` is logged once, not per call, because the
+ * alternative is a line per delivery attempt per report — which buries the cause
+ * it is meant to reveal.
+ */
+export function crowdSourceForOxyService(
+  options: OxyServiceClientOptions = {},
+): CrowdSource | undefined {
+  if (client) return client;
+  if (unavailable !== null) return undefined;
+
+  if (!canAuthenticateAsOxyService()) {
+    unavailable = 'this process cannot obtain an Oxy service token';
+    /**
+     * Say WHY when the reason is that Oxy's SDK could not be loaded at all.
+     *
+     * "Cannot obtain a token" is the right answer for a local checkout and the
+     * wrong-looking one for a deployment that has `@oxy.so/core` installed and
+     * a task role to attest with: there the cause is a resolution that failed,
+     * and without this line an application reads a switched-off integration as
+     * intended behaviour.
+     */
+    const resolution = oxySdkResolutionError();
+    options.logger?.info('[CrowdSource] client not built', {
+      reason: unavailable,
+      ...(resolution === null ? {} : { oxySdk: resolution }),
+    });
+    return undefined;
+  }
+
+  client = new CrowdSource({
+    oxyToken: options.oxyToken ?? oxyServiceToken,
+    ...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
+  });
+
+  if (options.logger !== undefined) reportTenant(client, options.logger);
+
+  return client;
+}
+
+/**
+ * Resolve the tenant once, in the background, so a missing BINDING is visible at
+ * boot rather than on the first report.
+ *
+ * A token this deployment can mint for an Oxy application nobody bound to a
+ * CrowdSource tenant authenticates nothing, and that failure is otherwise
+ * indistinguishable from "no reports yet". Nothing waits on it: the client is
+ * returned already usable, the client resolves the same promise for its own
+ * calls, and a rejection here is a log line rather than a broken boot — which is
+ * why the rejection handler is attached in the same expression rather than left
+ * to an unhandled-rejection handler somebody else owns.
+ *
+ * Only with a logger. The resolution exists to be REPORTED; with nowhere to
+ * report it, it would be a request at boot whose answer nobody reads, and the
+ * client asks the same question on first use anyway.
+ */
+function reportTenant(built: CrowdSource, logger: OxyServiceClientLogger): void {
+  void Promise.resolve(built.applicationId).then(
+    (applicationId) => {
+      logger.info('[CrowdSource] client ready', { applicationId });
+    },
+    (error: unknown) => {
+      logger.error('[CrowdSource] client built but the tenant did not resolve', {
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    },
+  );
+}
+
+/** Test hook. Production builds the client once and keeps it for the process. */
+export function resetCrowdSourceForOxyService(): void {
+  client = null;
+  unavailable = null;
+}