@iveri/contracts 0.2.0 → 0.3.0

package/README.md

@@ -8,10 +8,20 @@ pnpm add @iveri/contracts
 ```
 
 ```ts
-import { ApiResponse, CursorPage, ErrorCode, Maybe, Paginated, UUID } from '@iveri/contracts';
+// Cross-service primitives.
+import { CursorPage, ErrorCode, Maybe, Paginated, UUID, UserPermission } from '@iveri/contracts';
+
+// One service's wire surface.
+import type { CaptureSummary, Endpoint } from '@iveri/contracts/conduit';
+import type { AuthSession, Principal } from '@iveri/contracts/identity';
 ```
 
-Import from the root barrel only — never `@iveri/contracts/dist/...`.
+Three entry points, and no others — never `@iveri/contracts/dist/...`.
+
+The per-service surfaces are **not** re-exported from the root, deliberately. Conduit owns a
+`Provider` and an `Endpoint`; Unibox will want both names for entirely different things. Keeping
+each service behind its own entry point means that collision never has to be resolved by
+renaming a type in a shipped API.
 
 ## Zero runtime dependencies — the rule that defines this package
 
@@ -31,13 +41,14 @@ Anything needing a dependency belongs in `@iveri/nest-sdk` (backend) or `@iveri/
 
 ### `type/`
 
-| Type                                                                          | Use                                                                                           |
-| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `Nil`, `Maybe<T>`, `Nullable<T>`                                              | absent values. `Nullable` for anything crossing the wire — `JSON.stringify` drops `undefined` |
-| `UUID`                                                                        | template-literal shape hint; validation stays at the edge with `@IsUUID()`                    |
-| `Paginated<T>`                                                                | offset paging, where the client needs a total or arbitrary page jumps                         |
-| `CursorPage<T>`                                                               | cursor paging — the default for lists that grow while being read                              |
-| `ApiSuccessResponse<T>`, `ApiErrorResponse`, `ApiErrorBody`, `ApiResponse<T>` | the response envelope                                                                         |
+| Type                               | Use                                                                                           |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| `Nil`, `Maybe<T>`, `Nullable<T>`   | absent values. `Nullable` for anything crossing the wire — `JSON.stringify` drops `undefined` |
+| `UUID`                             | template-literal shape hint; validation stays at the edge with `@IsUUID()`                    |
+| `Paginated<T>`                     | offset paging, where the client needs a total or arbitrary page jumps                         |
+| `CursorPage<T>`                    | cursor paging — the default for lists that grow while being read                              |
+| `IsoDateTime`                      | a timestamp as it appears on the wire. JSON has no date type — this is a `string`             |
+| `ApiErrorResponse`, `ApiErrorBody` | the error envelope. **Only errors are enveloped**; a success is the bare payload              |
 
 ### `enum/`
 
@@ -55,11 +66,38 @@ Values are `<resource>:<action>`, or `<service>:<resource>:<action>` where a res
 would otherwise collide — identity's members are unprefixed because they predate the shared
 catalogue and are already embedded in issued tokens and stored role rows.
 
+### `api/identity/` → `@iveri/contracts/identity`
+
+`iveri-identity-api`'s authentication surface: `SignupBody`, `LoginBody`, `RefreshTokenBody`,
+`AcceptInvitationBody`, `AuthTokens`, `Principal`, `AuthSession`, plus `TenantStatus` and
+`MembershipStatus`.
+
+Auth only. Identity also exposes tenant, user, membership, role and API-key routes; those have
+one consumer each and stay in the service until a second one appears.
+
+### `api/conduit/` → `@iveri/contracts/conduit`
+
+`conduit-api`'s full admin surface: `Endpoint`, `CaptureSummary`/`CaptureDetail`, `Provider`
+with its `SignatureManifest`/`HandshakeManifest`, `Replay`, `SignatureDiagnostic`, the request
+bodies for each, and the five enums they are built from — `SignatureVerdict`,
+`SignatureAlgorithm`, `SignatureEncoding`, `SignatureHeaderScheme`, `HandshakeKind`.
+
+### Why the wire shapes moved here
+
+`conduit-admin-web` hand-transcribed all of it, carefully and with comments. It still drifted:
+`TenantStatus` was written `'active' | 'suspended' | 'cancelled'` where identity sends
+`'ACTIVE' | 'SUSPENDED' | 'PENDING_DELETION'` — wrong casing, and a member that has never
+existed — and `bodySha256` was missing from two shapes. Nothing caught any of it, because a
+hand-written mirror is checked by nobody.
+
+Both sides now compile against these types: each service's response DTO `implements` the
+interface it fulfils, so a field renamed in `conduit-api` fails `tsc` in `conduit-api` rather
+than surfacing as `undefined` in a panel weeks later.
+
 ## What is deliberately **not** here yet
 
-`event/` (domain event envelope, topics) and `api/` (per-service request/response shapes) are
-in the plan but unwritten: no service defines them yet. They get added when a real consumer
-needs them, per the second-consumer rule — not in anticipation.
+`event/` — the domain event envelope and topic map. No service publishes one yet; it lands with
+Conduit's outbox.
 
 ## Adding to the contract
 
@@ -67,9 +105,17 @@ needs them, per the second-consumer rule — not in anticipation.
   existing member means, or removing one, is **major** — clients branch on these, and a
   removed permission silently downgrades every live session whose token still carries it.
 - Widening a type is minor; narrowing it is major.
+- Under `api/`, the contract follows the service: add the field to the service's DTO and to the
+  interface in the same release, and let `implements` prove they agree.
 - Breaking changes get a migration note in `CHANGELOG.md`. Services upgrade deliberately.
 
 ## Build output
 
 Dual ESM + CJS (`dist/esm`, `dist/cjs`) behind an `exports` map, so NestJS `require`s it and
 Vite tree-shakes it. `sideEffects: false`.
+
+The subpath entry points also need a `typesVersions` block, because **TypeScript only reads
+`exports` under `moduleResolution` `node16`/`nodenext`/`bundler`** and every Nest service in the
+fleet compiles with `"node"`. Without it `@iveri/contracts/conduit` resolves at runtime and is
+untyped at compile time — in one repo but not another, which is a confusing thing to debug.
+`scripts/verify-entry-points.mjs` runs in `build` and fails if either half is missing.

package/dist/cjs/api/conduit/capture.type.d.ts

@@ -0,0 +1,70 @@
+import type { CursorPage } from '../../type/cursor-page.type.js';
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { SignatureVerdict } from './signature-verdict.enum.js';
+/** A capture without its body — one row of the list. */
+export interface CaptureSummary {
+    id: UUID;
+    endpointId: UUID;
+    method: string;
+    /** Path after the ingress token. */
+    path: string;
+    /** Raw query string, without the `?`. */
+    queryString: string;
+    contentType: Nullable<string>;
+    /** Body size in bytes, as received. */
+    bodySize: number;
+    /** Hex SHA-256 of the body. Compare this against what the provider says it sent. */
+    bodySha256: string;
+    /** From `x-forwarded-for`. Advisory — a client controls it. */
+    sourceIp: Nullable<string>;
+    /**
+     * Verdict recorded **when the request arrived**. A snapshot: fixing the endpoint's secret
+     * does not rewrite it. Re-run the signature route to check against current configuration.
+     */
+    signatureVerdict: Nullable<SignatureVerdict>;
+    /** A provider's URL-verification challenge rather than a real event. */
+    isHandshake: boolean;
+    receivedAt: IsoDateTime;
+}
+/** A capture with its headers and body. `GET /api/v1/capture/:id`. */
+export interface CaptureDetail extends CaptureSummary {
+    /** Every request header, lowercase keys — including the signature headers. */
+    headers: Record<string, string | string[]>;
+    /**
+     * The body as UTF-8 when it decodes cleanly, otherwise `null`.
+     *
+     * A convenience only. `toString('utf8')` never fails — it substitutes U+FFFD for every
+     * invalid sequence — so a gzip or protobuf body would come back as convincing-looking
+     * mojibake that no longer hashes to `bodySha256`. Conduit round-trips the decode and sends
+     * `null` when it does not survive, which is the honest answer.
+     */
+    body: Nullable<string>;
+    /**
+     * The body as base64. **This is the authoritative field.** A webhook body is arbitrary
+     * bytes; base64 is the only representation that survives JSON without alteration, and the
+     * signed payload is those exact bytes.
+     */
+    bodyBase64: string;
+    /** The body was too large to inline and was read back from a spill file. */
+    isSpilled: boolean;
+}
+/** `GET /api/v1/capture`. */
+export type CapturesPage = CursorPage<CaptureSummary>;
+/**
+ * Query for `GET /api/v1/capture`.
+ *
+ * Cursor-paginated, unlike endpoints and providers: captures are appended to while they are
+ * being read — every inbound webhook lands at the top of the list, including while an operator
+ * pages through it — and offset paging drops or repeats rows under that.
+ */
+export interface GetCapturesQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    after?: Nullable<string>;
+    endpointId?: Nullable<UUID>;
+    method?: Nullable<string>;
+    signatureVerdict?: Nullable<SignatureVerdict>;
+}
+//# sourceMappingURL=capture.type.d.ts.map

package/dist/cjs/api/conduit/capture.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/capture.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,IAAI,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IAEnB,+DAA+D;IAC/D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IAErB,UAAU,EAAE,WAAW,CAAC;CAC3B;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAE3C;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEvB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,6BAA6B;AAC7B,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzB,UAAU,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,gBAAgB,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACjD"}

package/dist/cjs/api/conduit/capture.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=capture.type.js.map

package/dist/cjs/api/conduit/capture.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/capture.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/conduit/endpoint.type.d.ts

@@ -0,0 +1,66 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * One endpoint on the wire.
+ *
+ * Carries `hasSigningSecret`, never the secret. Not a masked value, not a last-four hint — the
+ * field simply does not exist, so no future change can accidentally start populating it.
+ */
+export interface Endpoint {
+    id: UUID;
+    name: string;
+    description: Nullable<string>;
+    /** The path segment providers post to. */
+    ingressToken: string;
+    /**
+     * Path to register with the provider. Relative on purpose — the public origin is a tunnel or
+     * a load balancer this service cannot see, so the caller prepends its own.
+     */
+    ingressPath: string;
+    providerKey: Nullable<string>;
+    /** Whether a signing secret is configured. The secret itself is never returned. */
+    hasSigningSecret: boolean;
+    /** Whether a handshake verify token is configured. */
+    hasVerifyToken: boolean;
+    /** Inactive endpoints answer 410 Gone. */
+    isActive: boolean;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/**
+ * `GET /api/v1/endpoint`. Offset-paginated, unlike captures: endpoints are a small, slow-moving
+ * collection a customer renders as numbered pages.
+ */
+export type EndpointsPage = Paginated<Endpoint>;
+/** `POST /api/v1/endpoint`. */
+export interface CreateEndpointBody {
+    name: string;
+    description?: Nullable<string>;
+    providerKey?: Nullable<string>;
+    signingSecret?: Nullable<string>;
+    verifyToken?: Nullable<string>;
+}
+/**
+ * `PATCH /api/v1/endpoint/:id`.
+ *
+ * **Secret fields have three states, not two.** Omitting one leaves the stored secret untouched;
+ * sending `null` deletes it. A form must therefore never send `''` or `null` where the user
+ * meant "I did not change this" — that silently wipes a working signing secret, and the next
+ * webhook verifies as `MISSING_SECRET` with nothing to say why.
+ */
+export interface UpdateEndpointBody {
+    name?: string;
+    description?: Nullable<string>;
+    providerKey?: Nullable<string>;
+    signingSecret?: Nullable<string>;
+    verifyToken?: Nullable<string>;
+    isActive?: boolean;
+}
+/** Query for `GET /api/v1/endpoint`. */
+export interface GetEndpointsQuery {
+    limit?: number;
+    offset?: number;
+}
+//# sourceMappingURL=endpoint.type.d.ts.map

package/dist/cjs/api/conduit/endpoint.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/endpoint.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,mFAAmF;IACnF,gBAAgB,EAAE,OAAO,CAAC;IAE1B,sDAAsD;IACtD,cAAc,EAAE,OAAO,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAElB,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEhD,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cjs/api/conduit/endpoint.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=endpoint.type.js.map

package/dist/cjs/api/conduit/endpoint.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/endpoint.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/conduit/handshake-kind.enum.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How a provider proves the endpoint is really ours before it will send anything.
+ *
+ * **Handshakes work in inspect mode, deliberately.** Meta will not save a callback URL that
+ * does not echo `hub.challenge`, and Slack will not save one that does not echo `challenge` —
+ * so without this, the local developer tool could never be registered with the provider at all,
+ * and there would be nothing to capture. It is the one piece of ingress behaviour that is not
+ * "store and acknowledge".
+ */
+export declare enum HandshakeKind {
+    /**
+     * Provider sends `GET ?mode=subscribe&verify_token=…&challenge=…` and expects the challenge
+     * echoed back as the plain-text body. Meta (WhatsApp, Messenger, Instagram).
+     */
+    QUERY_ECHO = "query-echo",
+    /**
+     * Provider sends a JSON body carrying a trigger field and a challenge, and expects the
+     * challenge echoed in a JSON response. Slack (`type: url_verification`).
+     */
+    JSON_ECHO = "json-echo"
+}
+//# sourceMappingURL=handshake-kind.enum.d.ts.map

package/dist/cjs/api/conduit/handshake-kind.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-kind.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/handshake-kind.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,oBAAY,aAAa;IACrB;;;OAGG;IACH,UAAU,eAAe;IAEzB;;;OAGG;IACH,SAAS,cAAc;CAC1B"}

package/dist/cjs/api/conduit/handshake-kind.enum.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandshakeKind = void 0;
+/**
+ * How a provider proves the endpoint is really ours before it will send anything.
+ *
+ * **Handshakes work in inspect mode, deliberately.** Meta will not save a callback URL that
+ * does not echo `hub.challenge`, and Slack will not save one that does not echo `challenge` —
+ * so without this, the local developer tool could never be registered with the provider at all,
+ * and there would be nothing to capture. It is the one piece of ingress behaviour that is not
+ * "store and acknowledge".
+ */
+var HandshakeKind;
+(function (HandshakeKind) {
+    /**
+     * Provider sends `GET ?mode=subscribe&verify_token=…&challenge=…` and expects the challenge
+     * echoed back as the plain-text body. Meta (WhatsApp, Messenger, Instagram).
+     */
+    HandshakeKind["QUERY_ECHO"] = "query-echo";
+    /**
+     * Provider sends a JSON body carrying a trigger field and a challenge, and expects the
+     * challenge echoed in a JSON response. Slack (`type: url_verification`).
+     */
+    HandshakeKind["JSON_ECHO"] = "json-echo";
+})(HandshakeKind || (exports.HandshakeKind = HandshakeKind = {}));
+//# sourceMappingURL=handshake-kind.enum.js.map

package/dist/cjs/api/conduit/handshake-kind.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-kind.enum.js","sourceRoot":"","sources":["../../../../src/api/conduit/handshake-kind.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAY,aAYX;AAZD,WAAY,aAAa;IACrB;;;OAGG;IACH,0CAAyB,CAAA;IAEzB;;;OAGG;IACH,wCAAuB,CAAA;AAC3B,CAAC,EAZW,aAAa,6BAAb,aAAa,QAYxB"}

package/dist/cjs/api/conduit/index.d.ts

@@ -0,0 +1,11 @@
+export * from './capture.type.js';
+export * from './endpoint.type.js';
+export * from './handshake-kind.enum.js';
+export * from './provider.type.js';
+export * from './replay.type.js';
+export * from './signature-algorithm.enum.js';
+export * from './signature-encoding.enum.js';
+export * from './signature-header-scheme.enum.js';
+export * from './signature-verdict.enum.js';
+export * from './signature.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/api/conduit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC"}

package/dist/cjs/api/conduit/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./capture.type.js"), exports);
+__exportStar(require("./endpoint.type.js"), exports);
+__exportStar(require("./handshake-kind.enum.js"), exports);
+__exportStar(require("./provider.type.js"), exports);
+__exportStar(require("./replay.type.js"), exports);
+__exportStar(require("./signature-algorithm.enum.js"), exports);
+__exportStar(require("./signature-encoding.enum.js"), exports);
+__exportStar(require("./signature-header-scheme.enum.js"), exports);
+__exportStar(require("./signature-verdict.enum.js"), exports);
+__exportStar(require("./signature.type.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/api/conduit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/conduit/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,qDAAmC;AACnC,2DAAyC;AACzC,qDAAmC;AACnC,mDAAiC;AACjC,gEAA8C;AAC9C,+DAA6C;AAC7C,oEAAkD;AAClD,8DAA4C;AAC5C,sDAAoC"}

package/dist/cjs/api/conduit/provider.type.d.ts

@@ -0,0 +1,138 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { HandshakeKind } from './handshake-kind.enum.js';
+import type { SignatureAlgorithm } from './signature-algorithm.enum.js';
+import type { SignatureEncoding } from './signature-encoding.enum.js';
+import type { SignatureHeaderScheme } from './signature-header-scheme.enum.js';
+/** Required in `signedPayloadTemplate`; substituted with the raw request bytes. */
+export declare const SIGNED_PAYLOAD_BODY_TOKEN = "{body}";
+/** Optional in `signedPayloadTemplate`; substituted with the timestamp exactly as received. */
+export declare const SIGNED_PAYLOAD_TIMESTAMP_TOKEN = "{timestamp}";
+/**
+ * How to verify one provider's HMAC.
+ *
+ * A manifest holds **no secret**. It describes where a signature lives and how it is computed,
+ * never the key it is computed with — which is why it is returned in full to anyone with
+ * `conduit:provider:read` while the signing secret it is used against is returned to nobody.
+ *
+ * This is the response shape: every key is present, absent ones are `null`. The request shape
+ * is {@link SignatureManifestInput}, where they may be omitted.
+ */
+export interface SignatureManifest {
+    algorithm: SignatureAlgorithm;
+    encoding: SignatureEncoding;
+    /** Lowercase header the signature arrives in, e.g. `x-hub-signature-256`. */
+    headerName: string;
+    headerScheme: SignatureHeaderScheme;
+    /** Literal prefix stripped before comparison, e.g. `sha256=`. `DIRECT` scheme only. */
+    headerPrefix: Nullable<string>;
+    /** Key naming the signature inside a `KEY_VALUE_LIST` header, e.g. `v1`. */
+    signatureKey: Nullable<string>;
+    /** Separate header carrying the signed timestamp, when it is not in the signature header. */
+    timestampHeaderName: Nullable<string>;
+    /** Key naming the timestamp inside a `KEY_VALUE_LIST` header, e.g. `t`. */
+    timestampKey: Nullable<string>;
+    /** Replay window. Null disables the age check entirely. */
+    timestampToleranceSeconds: Nullable<number>;
+    /**
+     * What gets hashed. {@link SIGNED_PAYLOAD_BODY_TOKEN} is required;
+     * {@link SIGNED_PAYLOAD_TIMESTAMP_TOKEN} is optional — Slack's is `v0:{timestamp}:{body}`,
+     * Meta's is just `{body}`.
+     */
+    signedPayloadTemplate: string;
+}
+/** {@link SignatureManifest} as sent on create/update: nullable fields may simply be omitted. */
+export interface SignatureManifestInput {
+    algorithm: SignatureAlgorithm;
+    encoding: SignatureEncoding;
+    headerName: string;
+    headerScheme: SignatureHeaderScheme;
+    headerPrefix?: Nullable<string>;
+    signatureKey?: Nullable<string>;
+    timestampHeaderName?: Nullable<string>;
+    timestampKey?: Nullable<string>;
+    timestampToleranceSeconds?: Nullable<number>;
+    signedPayloadTemplate: string;
+}
+/**
+ * How to answer one provider's URL-verification challenge.
+ *
+ * The fields split by {@link HandshakeKind} — a `QUERY_ECHO` manifest populates the four query
+ * parameter names and nulls the rest, a `JSON_ECHO` manifest does the opposite.
+ */
+export interface HandshakeManifest {
+    kind: HandshakeKind;
+    /** Query parameter holding the value to echo back, e.g. `hub.challenge`. */
+    challengeParam: Nullable<string>;
+    /** Query parameter holding the token to compare against the endpoint's, e.g. `hub.verify_token`. */
+    verifyTokenParam: Nullable<string>;
+    /** Query parameter naming the operation, e.g. `hub.mode`. */
+    modeParam: Nullable<string>;
+    /** Value `modeParam` must hold for this to be a handshake, e.g. `subscribe`. */
+    expectedMode: Nullable<string>;
+    /** Top-level body field identifying a handshake, e.g. `type`. */
+    triggerField: Nullable<string>;
+    /** Value `triggerField` must hold, e.g. `url_verification`. */
+    triggerValue: Nullable<string>;
+    /** Body field holding the value to echo back, e.g. `challenge`. */
+    challengeField: Nullable<string>;
+}
+/** {@link HandshakeManifest} as sent on create/update: nullable fields may simply be omitted. */
+export interface HandshakeManifestInput {
+    kind: HandshakeKind;
+    challengeParam?: Nullable<string>;
+    verifyTokenParam?: Nullable<string>;
+    modeParam?: Nullable<string>;
+    expectedMode?: Nullable<string>;
+    triggerField?: Nullable<string>;
+    triggerValue?: Nullable<string>;
+    challengeField?: Nullable<string>;
+}
+/** One provider on the wire. `GET /api/v1/provider`. */
+export interface Provider {
+    /** Null for a built-in — it is not a row and cannot be edited or deleted. */
+    id: Nullable<UUID>;
+    key: string;
+    name: string;
+    description: Nullable<string>;
+    /** Null when this provider signs nothing. */
+    signature: Nullable<SignatureManifest>;
+    /** Null when this provider has no URL challenge. */
+    handshake: Nullable<HandshakeManifest>;
+    /**
+     * Ships with Conduit, in code rather than as a seeded row. Override it by creating your own
+     * under the same key — resolution checks a tenant's rows first.
+     */
+    isBuiltIn: boolean;
+    /** Null for a built-in. */
+    createdAt: Nullable<IsoDateTime>;
+    /** Null for a built-in. */
+    updatedAt: Nullable<IsoDateTime>;
+}
+/**
+ * Not paginated: the list is the built-ins plus whatever one customer has defined by hand.
+ * Wrapped in an object rather than returned as a bare array so a `total` or a cursor can be
+ * added later without breaking every client.
+ */
+export interface ProvidersList {
+    items: Provider[];
+}
+/** `POST /api/v1/provider`. */
+export interface CreateProviderBody {
+    key: string;
+    name: string;
+    description?: Nullable<string>;
+    signature?: Nullable<SignatureManifestInput>;
+    handshake?: Nullable<HandshakeManifestInput>;
+}
+/** `PATCH /api/v1/provider/:id`. */
+export interface UpdateProviderBody {
+    name?: string;
+    description?: Nullable<string>;
+    /** Send `null` to stop verifying this provider's signatures. */
+    signature?: Nullable<SignatureManifestInput>;
+    /** Send `null` to stop answering this provider's challenge. */
+    handshake?: Nullable<HandshakeManifestInput>;
+}
+//# sourceMappingURL=provider.type.d.ts.map

package/dist/cjs/api/conduit/provider.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/provider.type.ts"],"names":[],"mappings":"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"}

package/dist/cjs/api/conduit/provider.type.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNED_PAYLOAD_TIMESTAMP_TOKEN = exports.SIGNED_PAYLOAD_BODY_TOKEN = void 0;
+/** Required in `signedPayloadTemplate`; substituted with the raw request bytes. */
+exports.SIGNED_PAYLOAD_BODY_TOKEN = '{body}';
+/** Optional in `signedPayloadTemplate`; substituted with the timestamp exactly as received. */
+exports.SIGNED_PAYLOAD_TIMESTAMP_TOKEN = '{timestamp}';
+//# sourceMappingURL=provider.type.js.map

package/dist/cjs/api/conduit/provider.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/provider.type.ts"],"names":[],"mappings":";;;AASA,mFAAmF;AACtE,QAAA,yBAAyB,GAAG,QAAQ,CAAC;AAElD,+FAA+F;AAClF,QAAA,8BAA8B,GAAG,aAAa,CAAC"}

package/dist/cjs/api/conduit/replay.type.d.ts

@@ -0,0 +1,48 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/** One replay attempt and whatever came back. */
+export interface Replay {
+    id: UUID;
+    captureId: UUID;
+    targetUrl: string;
+    method: string;
+    /** The body differed from the capture's, so the original signature no longer verifies. */
+    isEdited: boolean;
+    /** Null when no response arrived — a timeout, a refused connection. See `errorMessage`. */
+    responseStatus: Nullable<number>;
+    responseHeaders: Nullable<Record<string, string | string[]>>;
+    /** First 64 KB of the response body. */
+    responseBodyPreview: Nullable<string>;
+    responseBodyTruncated: boolean;
+    /**
+     * Why it failed. **A failed replay is still a 200 from the replay endpoint** — the target
+     * being down is the answer you asked for, not an error on Conduit's side.
+     */
+    errorMessage: Nullable<string>;
+    durationMs: number;
+    executedByUserId: Nullable<UUID>;
+    createdAt: IsoDateTime;
+}
+/**
+ * Unpaginated: one capture accrues a handful of replays while someone fixes a receiver, not
+ * thousands.
+ */
+export interface ReplaysList {
+    items: Replay[];
+}
+/** `POST /api/v1/capture/:id/replay`. */
+export interface ExecuteReplayBody {
+    targetUrl: string;
+    /** Defaults to the capture's method. */
+    method?: Nullable<string>;
+    /** Merged over the captured headers. Signature headers are forwarded deliberately. */
+    headers?: Nullable<Record<string, string>>;
+    /**
+     * Replacement body, base64. Omitting it resends the captured bytes exactly, which is the
+     * only way the original signature still verifies — editing necessarily invalidates it, and
+     * the resulting replay is flagged `isEdited`.
+     */
+    bodyBase64?: Nullable<string>;
+}
+//# sourceMappingURL=replay.type.d.ts.map

package/dist/cjs/api/conduit/replay.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.type.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/replay.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,iDAAiD;AACjD,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IAEf,0FAA0F;IAC1F,QAAQ,EAAE,OAAO,CAAC;IAElB,2FAA2F;IAC3F,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEjC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IAE7D,wCAAwC;IACxC,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEtC,qBAAqB,EAAE,OAAO,CAAC;IAE/B;;;OAGG;IACH,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE/B,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjC,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAC9B,SAAS,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1B,sFAAsF;IACtF,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE3C;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC"}

package/dist/cjs/api/conduit/replay.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=replay.type.js.map

package/dist/cjs/api/conduit/replay.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.type.js","sourceRoot":"","sources":["../../../../src/api/conduit/replay.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/conduit/signature-algorithm.enum.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hash backing a provider's HMAC.
+ *
+ * `SHA1` is here because Meta still sends `x-hub-signature` alongside the SHA-256 header and
+ * some older integrations only have that one. It is **not** a recommendation — a manifest using
+ * it is verifying what the provider actually sends, which is the only useful thing a diagnostic
+ * can do. Nothing in Conduit ever *chooses* SHA-1.
+ *
+ * Values are the strings `node:crypto` expects, so no lookup table stands between the manifest
+ * and `createHmac` — one fewer place for a typo to become "signature mismatch".
+ */
+export declare enum SignatureAlgorithm {
+    SHA1 = "sha1",
+    SHA256 = "sha256",
+    SHA512 = "sha512"
+}
+//# sourceMappingURL=signature-algorithm.enum.d.ts.map

package/dist/cjs/api/conduit/signature-algorithm.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-algorithm.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/conduit/signature-algorithm.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,kBAAkB;IAC1B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,MAAM,WAAW;CACpB"}