@antasphere/chassis-contract 1.0.2 → 1.2.0

package/dist/schemas/webhooks.d.ts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+/**
+ * Outbound webhooks (PRDCT-3482): a URL a workspace registers to be told, by a
+ * signed POST, when something happens to the tool's own subjects. The tool
+ * declares the event types and the subjects they carry (the catalog); the
+ * chassis stores the endpoints, matches the events against them, signs and
+ * delivers, and keeps each delivery's history. Owners and admins manage them.
+ *
+ * The signing secret is NEVER part of an endpoint's shape: it is shown once,
+ * at creation and at each rotation, and stored sealed.
+ */
+/**
+ * What an endpoint subscribes to: an exact event type (`thing.created`), a
+ * family (`thing.*`) or everything (`*`).
+ */
+export declare const webhookEventPatternSchema: z.ZodString;
+/** A subject key of the catalog (`thing`, `project`): lowercase, digits and underscores. */
+export declare const webhookSubjectKeySchema: z.ZodString;
+/**
+ * Narrows a subscription by subject: a subject key mapped to the ids it
+ * accepts. AND across keys, OR within a key; an event that does not carry a
+ * filtered subject does not match. An empty object filters nothing.
+ */
+export declare const webhookFiltersSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+export type WebhookFilters = z.infer<typeof webhookFiltersSchema>;
+/**
+ * Where the deliveries go: an http or https URL without credentials. Whitespace
+ * and control characters are refused outright, because the URL parser silently
+ * strips tabs and newlines, so the stored string would not be the address
+ * delivered to. The address rules (ports, private networks, https on the cloud
+ * edition) are the server's, answered `url_refused`.
+ */
+export declare const webhookUrlSchema: z.ZodString;
+export declare const webhookDeliveryStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    delivered: "delivered";
+    failed: "failed";
+    held: "held";
+}>;
+export type WebhookDeliveryStatus = z.infer<typeof webhookDeliveryStatusSchema>;
+export declare const webhookEndpointSchema: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    description: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    filters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    enabled: z.ZodBoolean;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    disabledAt: z.ZodNullable<z.ZodString>;
+    disabledReason: z.ZodNullable<z.ZodString>;
+    consecutiveFailures: z.ZodNumber;
+    lastDeliveryAt: z.ZodNullable<z.ZodString>;
+    lastDeliveryStatus: z.ZodNullable<z.ZodEnum<{
+        delivered: "delivered";
+        failed: "failed";
+    }>>;
+    previousSecretExpiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WebhookEndpoint = z.infer<typeof webhookEndpointSchema>;
+/** The endpoint as created, with its signing secret (`whsec_…`), shown ONCE. */
+export declare const webhookEndpointCreatedSchema: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    description: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    filters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    enabled: z.ZodBoolean;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    disabledAt: z.ZodNullable<z.ZodString>;
+    disabledReason: z.ZodNullable<z.ZodString>;
+    consecutiveFailures: z.ZodNumber;
+    lastDeliveryAt: z.ZodNullable<z.ZodString>;
+    lastDeliveryStatus: z.ZodNullable<z.ZodEnum<{
+        delivered: "delivered";
+        failed: "failed";
+    }>>;
+    previousSecretExpiresAt: z.ZodNullable<z.ZodString>;
+    secret: z.ZodString;
+}, z.core.$strip>;
+export type WebhookEndpointCreated = z.infer<typeof webhookEndpointCreatedSchema>;
+/**
+ * The endpoint after a rotation, with its new secret, shown ONCE; the previous
+ * secret keeps signing until `previousSecretExpiresAt`.
+ */
+export declare const webhookSecretRotatedSchema: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    description: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    filters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    enabled: z.ZodBoolean;
+    createdBy: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    disabledAt: z.ZodNullable<z.ZodString>;
+    disabledReason: z.ZodNullable<z.ZodString>;
+    consecutiveFailures: z.ZodNumber;
+    lastDeliveryAt: z.ZodNullable<z.ZodString>;
+    lastDeliveryStatus: z.ZodNullable<z.ZodEnum<{
+        delivered: "delivered";
+        failed: "failed";
+    }>>;
+    secret: z.ZodString;
+    previousSecretExpiresAt: z.ZodString;
+}, z.core.$strip>;
+export type WebhookSecretRotated = z.infer<typeof webhookSecretRotatedSchema>;
+export declare const webhookEndpointCreateSchema: z.ZodObject<{
+    url: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    events: z.ZodArray<z.ZodString>;
+    filters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** The INPUT shape: `description`, `filters` and `enabled` may be left out. */
+export type WebhookEndpointCreate = z.input<typeof webhookEndpointCreateSchema>;
+/** Every field optional, none defaulted (a PATCH never resets what it does not name). */
+export declare const webhookEndpointUpdateSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    events: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WebhookEndpointUpdate = z.infer<typeof webhookEndpointUpdateSchema>;
+export declare const webhooksListSchema: z.ZodObject<{
+    webhooks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        url: z.ZodString;
+        description: z.ZodString;
+        events: z.ZodArray<z.ZodString>;
+        filters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+        enabled: z.ZodBoolean;
+        createdBy: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        disabledAt: z.ZodNullable<z.ZodString>;
+        disabledReason: z.ZodNullable<z.ZodString>;
+        consecutiveFailures: z.ZodNumber;
+        lastDeliveryAt: z.ZodNullable<z.ZodString>;
+        lastDeliveryStatus: z.ZodNullable<z.ZodEnum<{
+            delivered: "delivered";
+            failed: "failed";
+        }>>;
+        previousSecretExpiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WebhooksList = z.infer<typeof webhooksListSchema>;
+export declare const webhooksListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * One event sent to one endpoint, with its attempts. `eventId` is the
+ * receiver's dedupe key, the same on every attempt and on a redelivery;
+ * `lastStatusCode` and `lastError` describe the latest attempt only;
+ * `payload` is the envelope as sent.
+ */
+export declare const webhookDeliverySchema: z.ZodObject<{
+    id: z.ZodString;
+    endpointId: z.ZodString;
+    eventId: z.ZodString;
+    eventType: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        delivered: "delivered";
+        failed: "failed";
+        held: "held";
+    }>;
+    attempt: z.ZodNumber;
+    lastStatusCode: z.ZodNullable<z.ZodNumber>;
+    lastError: z.ZodNullable<z.ZodString>;
+    nextAttemptAt: z.ZodNullable<z.ZodString>;
+    deliveredAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;
+export declare const webhookDeliveriesListSchema: z.ZodObject<{
+    deliveries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        endpointId: z.ZodString;
+        eventId: z.ZodString;
+        eventType: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            delivered: "delivered";
+            failed: "failed";
+            held: "held";
+        }>;
+        attempt: z.ZodNumber;
+        lastStatusCode: z.ZodNullable<z.ZodNumber>;
+        lastError: z.ZodNullable<z.ZodString>;
+        nextAttemptAt: z.ZodNullable<z.ZodString>;
+        deliveredAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WebhookDeliveriesList = z.infer<typeof webhookDeliveriesListSchema>;
+export declare const webhookDeliveriesListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        delivered: "delivered";
+        failed: "failed";
+        held: "held";
+    }>>;
+}, z.core.$strip>;
+/** The `webhook.ping` attempted inline: its outcome is on the delivery row. */
+export declare const webhookTestResultSchema: z.ZodObject<{
+    delivery: z.ZodObject<{
+        id: z.ZodString;
+        endpointId: z.ZodString;
+        eventId: z.ZodString;
+        eventType: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            delivered: "delivered";
+            failed: "failed";
+            held: "held";
+        }>;
+        attempt: z.ZodNumber;
+        lastStatusCode: z.ZodNullable<z.ZodNumber>;
+        lastError: z.ZodNullable<z.ZodString>;
+        nextAttemptAt: z.ZodNullable<z.ZodString>;
+        deliveredAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WebhookTestResult = z.infer<typeof webhookTestResultSchema>;
+/** A subject events can carry and endpoints can filter on: its key (what a filter names), the field of the envelope's `subjects` its value is written under (one id or a list of ids). */
+export declare const webhookCatalogSubjectSchema: z.ZodObject<{
+    key: z.ZodString;
+    field: z.ZodString;
+    description: z.ZodString;
+    list: z.ZodBoolean;
+}, z.core.$strip>;
+export type WebhookCatalogSubject = z.infer<typeof webhookCatalogSubjectSchema>;
+export declare const webhookCatalogEventSchema: z.ZodObject<{
+    type: z.ZodString;
+    description: z.ZodString;
+    subjects: z.ZodArray<z.ZodString>;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type WebhookCatalogEvent = z.infer<typeof webhookCatalogEventSchema>;
+export declare const webhookCatalogSchema: z.ZodObject<{
+    subjects: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        field: z.ZodString;
+        description: z.ZodString;
+        list: z.ZodBoolean;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        description: z.ZodString;
+        subjects: z.ZodArray<z.ZodString>;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WebhookCatalog = z.infer<typeof webhookCatalogSchema>;
+/** `{id}` the endpoint (a uuid, as every `{id}` path param). */
+export declare const webhookParamsSchema: z.ZodObject<{
+    id: z.ZodUUID;
+}, z.core.$strip>;
+/** `{id}` the endpoint, `{deliveryId}` one of its deliveries: both uuids. */
+export declare const webhookDeliveryParamsSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    deliveryId: z.ZodUUID;
+}, z.core.$strip>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/schemas/webhooks.d.ts.map

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

package/dist/schemas/webhooks.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, hasControlChars, plainText } from './common.js';
+/**
+ * Outbound webhooks (PRDCT-3482): a URL a workspace registers to be told, by a
+ * signed POST, when something happens to the tool's own subjects. The tool
+ * declares the event types and the subjects they carry (the catalog); the
+ * chassis stores the endpoints, matches the events against them, signs and
+ * delivers, and keeps each delivery's history. Owners and admins manage them.
+ *
+ * The signing secret is NEVER part of an endpoint's shape: it is shown once,
+ * at creation and at each rotation, and stored sealed.
+ */
+/**
+ * What an endpoint subscribes to: an exact event type (`thing.created`), a
+ * family (`thing.*`) or everything (`*`).
+ */
+export const webhookEventPatternSchema = z
+    .string()
+    .max(80)
+    .regex(/^(\*|[a-z][a-z0-9_]*\.(\*|[a-z][a-z0-9_]*))$/, 'an event type (thing.created), a family (thing.*) or everything (*)');
+/** A subject key of the catalog (`thing`, `project`): lowercase, digits and underscores. */
+export const webhookSubjectKeySchema = z
+    .string()
+    .max(40)
+    .regex(/^[a-z][a-z0-9_]*$/, 'lowercase letters, digits and underscores, starting with a letter');
+/**
+ * Narrows a subscription by subject: a subject key mapped to the ids it
+ * accepts. AND across keys, OR within a key; an event that does not carry a
+ * filtered subject does not match. An empty object filters nothing.
+ */
+export const webhookFiltersSchema = z
+    .record(webhookSubjectKeySchema, z.array(plainText(1, 200)).min(1).max(100))
+    .refine((v) => Object.keys(v).length <= 10, { error: 'at most 10 subject keys' })
+    .describe('Subject key → ids; AND across keys, OR within a key; an event that does not carry a filtered subject does not match');
+const UrlParser = globalThis.URL;
+function isHttpUrlWithoutCredentials(value) {
+    let parsed;
+    try {
+        parsed = new UrlParser(value);
+    }
+    catch {
+        return false;
+    }
+    return ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+        parsed.username === '' &&
+        parsed.password === '');
+}
+/**
+ * Where the deliveries go: an http or https URL without credentials. Whitespace
+ * and control characters are refused outright, because the URL parser silently
+ * strips tabs and newlines, so the stored string would not be the address
+ * delivered to. The address rules (ports, private networks, https on the cloud
+ * edition) are the server's, answered `url_refused`.
+ */
+export const webhookUrlSchema = z
+    .string()
+    .max(2048)
+    .refine((v) => !/\s/.test(v) && !hasControlChars(v), {
+    error: 'must not contain whitespace or control characters',
+    abort: true
+})
+    .refine(isHttpUrlWithoutCredentials, { error: 'an http or https URL without credentials' });
+export const webhookDeliveryStatusSchema = z.enum(['pending', 'delivered', 'failed', 'held']);
+export const webhookEndpointSchema = z.object({
+    id: z.string(),
+    url: z.string(),
+    description: z.string(),
+    events: z.array(z.string()),
+    filters: z.record(z.string(), z.array(z.string())),
+    enabled: z.boolean(),
+    createdBy: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    /** Set with `disabledReason` when the endpoint was switched off after failing too long. */
+    disabledAt: z.string().nullable(),
+    disabledReason: z.string().nullable(),
+    consecutiveFailures: z.number().int(),
+    lastDeliveryAt: z.string().nullable(),
+    lastDeliveryStatus: z.enum(['delivered', 'failed']).nullable(),
+    /** During a rotation, the previous secret keeps signing until this date. */
+    previousSecretExpiresAt: z.string().nullable()
+});
+/** The endpoint as created, with its signing secret (`whsec_…`), shown ONCE. */
+export const webhookEndpointCreatedSchema = webhookEndpointSchema.extend({
+    secret: z.string()
+});
+/**
+ * The endpoint after a rotation, with its new secret, shown ONCE; the previous
+ * secret keeps signing until `previousSecretExpiresAt`.
+ */
+export const webhookSecretRotatedSchema = webhookEndpointSchema.extend({
+    secret: z.string(),
+    previousSecretExpiresAt: z.string()
+});
+const webhookDescriptionSchema = plainText(0, 200);
+const webhookEventsSchema = z.array(webhookEventPatternSchema).min(1).max(50);
+export const webhookEndpointCreateSchema = z.object({
+    url: webhookUrlSchema,
+    description: webhookDescriptionSchema.default(''),
+    events: webhookEventsSchema,
+    filters: webhookFiltersSchema.default({}),
+    enabled: z.boolean().default(true)
+});
+/** Every field optional, none defaulted (a PATCH never resets what it does not name). */
+export const webhookEndpointUpdateSchema = z
+    .object({
+    url: webhookUrlSchema.optional(),
+    description: webhookDescriptionSchema.optional(),
+    events: webhookEventsSchema.optional(),
+    filters: webhookFiltersSchema.optional(),
+    enabled: z.boolean().optional()
+})
+    .refine((b) => Object.values(b).some((v) => v !== undefined), { error: 'nothing to change' });
+export const webhooksListSchema = z.object({
+    webhooks: z.array(webhookEndpointSchema),
+    nextCursor: z.string().nullable()
+});
+export const webhooksListQuerySchema = cursorPageQuerySchema;
+/**
+ * One event sent to one endpoint, with its attempts. `eventId` is the
+ * receiver's dedupe key, the same on every attempt and on a redelivery;
+ * `lastStatusCode` and `lastError` describe the latest attempt only;
+ * `payload` is the envelope as sent.
+ */
+export const webhookDeliverySchema = z.object({
+    id: z.string(),
+    endpointId: z.string(),
+    eventId: z.string(),
+    eventType: z.string(),
+    status: webhookDeliveryStatusSchema,
+    attempt: z.number().int(),
+    lastStatusCode: z.number().int().nullable(),
+    lastError: z.string().nullable(),
+    nextAttemptAt: z.string().nullable(),
+    deliveredAt: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    payload: z.record(z.string(), z.unknown())
+});
+export const webhookDeliveriesListSchema = z.object({
+    deliveries: z.array(webhookDeliverySchema),
+    nextCursor: z.string().nullable()
+});
+export const webhookDeliveriesListQuerySchema = cursorPageQuerySchema.extend({
+    status: webhookDeliveryStatusSchema.optional()
+});
+/** The `webhook.ping` attempted inline: its outcome is on the delivery row. */
+export const webhookTestResultSchema = z.object({
+    delivery: webhookDeliverySchema
+});
+/** A subject events can carry and endpoints can filter on: its key (what a filter names), the field of the envelope's `subjects` its value is written under (one id or a list of ids). */
+export const webhookCatalogSubjectSchema = z.object({
+    key: z.string(),
+    field: z.string(),
+    description: z.string(),
+    /** The value under `field` is always a list of ids (`projectIds`); else always one id. */
+    list: z.boolean()
+});
+export const webhookCatalogEventSchema = z.object({
+    type: z.string(),
+    description: z.string(),
+    /** The subject keys this event carries (what a filter can match it on). */
+    subjects: z.array(z.string()),
+    /** The JSON Schema of the event's `data`. */
+    schema: z.record(z.string(), z.unknown())
+});
+export const webhookCatalogSchema = z.object({
+    subjects: z.array(webhookCatalogSubjectSchema),
+    events: z.array(webhookCatalogEventSchema)
+});
+/** `{id}` the endpoint (a uuid, as every `{id}` path param). */
+export const webhookParamsSchema = z.object({ id: z.uuid() });
+/** `{id}` the endpoint, `{deliveryId}` one of its deliveries: both uuids. */
+export const webhookDeliveryParamsSchema = webhookParamsSchema.extend({ deliveryId: z.uuid() });
+//# sourceMappingURL=webhooks.js.map

package/dist/schemas/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/schemas/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC;KACvC,MAAM,EAAE;KACR,GAAG,CAAC,EAAE,CAAC;KACP,KAAK,CACJ,8CAA8C,EAC9C,qEAAqE,CACtE,CAAC;AAEJ,4FAA4F;AAC5F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,EAAE;KACR,GAAG,CAAC,EAAE,CAAC;KACP,KAAK,CAAC,mBAAmB,EAAE,mEAAmE,CAAC,CAAC;AAEnG;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC,uBAAuB,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;KAC3E,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;KAChF,QAAQ,CACP,qHAAqH,CACtH,CAAC;AASJ,MAAM,SAAS,GAAI,UAAkE,CAAC,GAAG,CAAC;AAE1F,SAAS,2BAA2B,CAAC,KAAa;IAChD,IAAI,MAAgB,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CACL,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;QAC7D,MAAM,CAAC,QAAQ,KAAK,EAAE;QACtB,MAAM,CAAC,QAAQ,KAAK,EAAE,CACvB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,GAAG,CAAC,IAAI,CAAC;KACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE;IACnD,KAAK,EAAE,mDAAmD;IAC1D,KAAK,EAAE,IAAI;CACZ,CAAC;KACD,MAAM,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,0CAA0C,EAAE,CAAC,CAAC;AAE9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAG9F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,2FAA2F;IAC3F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,kBAAkB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC9D,4EAA4E;IAC5E,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAGH,gFAAgF;AAChF,MAAM,CAAC,MAAM,4BAA4B,GAAG,qBAAqB,CAAC,MAAM,CAAC;IACvE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,qBAAqB,CAAC,MAAM,CAAC;IACrE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE;CACpC,CAAC,CAAC;AAGH,MAAM,wBAAwB,GAAG,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACnD,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAE9E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,GAAG,EAAE,gBAAgB;IACrB,WAAW,EAAE,wBAAwB,CAAC,OAAO,CAAC,EAAE,CAAC;IACjD,MAAM,EAAE,mBAAmB;IAC3B,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACnC,CAAC,CAAC;AAIH,yFAAyF;AACzF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,GAAG,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IAChC,WAAW,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAChD,MAAM,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,oBAAoB,CAAC,QAAQ,EAAE;IACxC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;AAGhG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,2BAA2B;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC3C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;CAC3C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,gCAAgC,GAAG,qBAAqB,CAAC,MAAM,CAAC;IAC3E,MAAM,EAAE,2BAA2B,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,QAAQ,EAAE,qBAAqB;CAChC,CAAC,CAAC;AAGH,0LAA0L;AAC1L,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,0FAA0F;IAC1F,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;CAClB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;CAC1C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;CAC3C,CAAC,CAAC;AAGH,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antasphere/chassis-contract",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",

package/src/identity.ts

@@ -16,8 +16,13 @@ export interface ToolIdentity<TScope extends string = string> {
   displayName: string;
   /** API key prefix, without the underscore (`acm` mints `acm_<keyId>_<secret>`). Never change it once keys exist. */
   apiKeyPrefix: string;
-  /** The scope vocabulary, by the part each scope plays. `dataExport` is the opt-in full-workspace export. */
-  scopes: { read: TScope; write: TScope; dataExport: TScope };
+  /**
+   * The scope vocabulary, by the part each scope plays. `dataExport` is the
+   * opt-in full-workspace export; `webhooks` the opt-in management of the
+   * workspace's webhook endpoints (PRDCT-3482), absent on a tool that opens
+   * them to no machine.
+   */
+  scopes: { read: TScope; write: TScope; dataExport: TScope; webhooks?: TScope };
   /** How the OpenAPI document names the CLI key's grant (`things:read+write`). A literal: a contraction, not a join. */
   cliKeyScopesLabel: string;
   /**

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   type CliAuthRevoked
 } from './schemas/cli-auth.js';
 export * from './schemas/sso-connect.js';
+export * from './schemas/cli-package.js';
 export * from './schemas/sso-logout.js';
 export * from './schemas/invitations.js';
 export * from './schemas/audit.js';
@@ -30,6 +31,7 @@ export * from './schemas/break-glass.js';
 export * from './schemas/files.js';
 export * from './schemas/projects.js';
 export * from './schemas/teams.js';
+export * from './schemas/webhooks.js';
 export * from './schemas/demo-passes.js';
 export * from './seams.js';
 export * from './entitlements.js';