@shuffl/api-contracts 0.4.0 → 0.5.1

package/dist/webhooks.js

@@ -0,0 +1,429 @@
+// #643: outgoing webhooks. The catalog of events a workspace endpoint can
+// subscribe to, the envelope every delivery carries and the Standard Webhooks
+// (https://www.standardwebhooks.com/) signature, shared by the server that
+// signs and the SDK that verifies. Payloads are thin on purpose: ids,
+// statuses, counts and revisions, never names, emails, Slack ids, message
+// text or document titles. A receiver reads anything more through the API
+// with a key that holds the event's read scope.
+export const webhookApiVersion = '2026-10-17';
+export const webhookEventGroups = {
+    connections: {
+        description: 'Connections programs, rounds and who takes part',
+        label: 'Connections',
+        scope: 'programs:read',
+    },
+    hr: {
+        description: 'Who answers HR requests',
+        label: 'HR team',
+        scope: 'hr:read',
+    },
+    knowledge: {
+        description: 'Proposals, drafts, published pages and connected sources',
+        label: 'Knowledge',
+        scope: 'knowledge:read',
+    },
+    people: {
+        description: 'People, roles, access, identities and departments',
+        label: 'People',
+        scope: 'users:read',
+    },
+    playbook: {
+        description: 'Playbook enrollments, steps, buddies and check-ins',
+        label: 'Playbooks',
+        scope: 'playbooks:read',
+    },
+    webhooks: {
+        description: 'Test events and endpoints Shuffl turned off',
+        label: 'Webhooks',
+        scope: 'webhooks:read',
+    },
+    workspace: {
+        description: 'The workspace itself and its Slack connection',
+        label: 'Workspace',
+        scope: 'team:read',
+    },
+};
+export const webhookEventGroupIds = Object.keys(webhookEventGroups);
+export const webhookEventCatalog = {
+    'hr.responder.granted': {
+        description: 'Someone joined the HR team that answers requests',
+        fields: ['person_id', 'revision'],
+        group: 'hr',
+    },
+    'hr.responder.revoked': {
+        description: 'Someone left the HR team',
+        fields: ['person_id', 'revision'],
+        group: 'hr',
+    },
+    'hr.team.renamed': {
+        description: 'The HR team’s name changed',
+        fields: ['revision'],
+        group: 'hr',
+    },
+    'knowledge.document.archived': {
+        description: 'A page was archived',
+        fields: ['document_id'],
+        group: 'knowledge',
+    },
+    'knowledge.document.audience_changed': {
+        description: 'Who can read a published page changed',
+        fields: ['document_id', 'version_id', 'audience', 'previous_audience'],
+        group: 'knowledge',
+    },
+    'knowledge.document.published': {
+        description: 'A page was published',
+        fields: ['document_id', 'version_id', 'audience'],
+        group: 'knowledge',
+    },
+    'knowledge.document.restored': {
+        description: 'An archived page was restored',
+        fields: ['document_id'],
+        group: 'knowledge',
+    },
+    'knowledge.document.withdrawn': {
+        description: 'A published page was withdrawn',
+        fields: ['document_id'],
+        group: 'knowledge',
+    },
+    'knowledge.draft.saved': {
+        description: 'A draft of a page was saved',
+        fields: ['document_id', 'version_id'],
+        group: 'knowledge',
+    },
+    'knowledge.proposal.created': {
+        description: 'Mello proposed new or changed Knowledge for review',
+        fields: ['proposal_id', 'revision'],
+        group: 'knowledge',
+    },
+    'knowledge.proposal.published': {
+        description: 'A verifier approved a proposal, as written or edited',
+        fields: ['proposal_id', 'revision', 'document_id', 'edited'],
+        group: 'knowledge',
+    },
+    'knowledge.proposal.rejected': {
+        description: 'A verifier turned a proposal down',
+        fields: ['proposal_id', 'revision'],
+        group: 'knowledge',
+    },
+    'knowledge.section.removed': {
+        description: 'A section was removed from a handbook page',
+        fields: ['document_id'],
+        group: 'knowledge',
+    },
+    'knowledge.source.access_lost': {
+        description: 'Shuffl can no longer read a connected document',
+        fields: ['document_id'],
+        group: 'knowledge',
+    },
+    'knowledge.source.connected': {
+        description: 'A Knowledge source such as Google Drive was connected',
+        fields: ['connection_id'],
+        group: 'knowledge',
+    },
+    'knowledge.source.disconnected': {
+        description: 'A Knowledge source was disconnected',
+        fields: ['connection_id'],
+        group: 'knowledge',
+    },
+    'knowledge.verifier.granted': {
+        description: 'Someone can now verify Knowledge',
+        fields: ['person_id', 'revision'],
+        group: 'knowledge',
+    },
+    'knowledge.verifier.revoked': {
+        description: 'Someone can no longer verify Knowledge',
+        fields: ['person_id', 'revision'],
+        group: 'knowledge',
+    },
+    'participant.opted_in': {
+        description: 'A person joined a Connections program',
+        fields: ['person_id', 'program_id', 'revision'],
+        group: 'connections',
+    },
+    'participant.opted_out': {
+        description: 'A person left a Connections program',
+        fields: ['person_id', 'program_id', 'revision'],
+        group: 'connections',
+    },
+    'participant.profile_updated': {
+        description: 'A person updated their profile',
+        fields: ['person_id'],
+        group: 'connections',
+    },
+    'person.access_changed': {
+        description: 'A person’s app access or employment changed',
+        fields: [
+            'person_id',
+            'status',
+            'previous_status',
+            'employment',
+            'previous_employment',
+            'revision',
+        ],
+        group: 'people',
+    },
+    'person.access_suspended': {
+        description: 'A person’s access was suspended',
+        fields: ['person_id'],
+        group: 'people',
+    },
+    'person.created': {
+        description: 'A person was added to the directory',
+        fields: ['person_id', 'revision'],
+        group: 'people',
+    },
+    'person.identity_linked': {
+        description: 'A Slack or single sign-on identity was linked to a person',
+        fields: ['person_id', 'identity_id', 'provider'],
+        group: 'people',
+    },
+    'person.identity_revoked': {
+        description: 'A linked identity was removed from a person',
+        fields: ['person_id', 'identity_id', 'provider'],
+        group: 'people',
+    },
+    'person.manager_changed': {
+        description: 'A person’s manager changed',
+        fields: ['person_id'],
+        group: 'people',
+    },
+    'person.role_changed': {
+        description: 'A person’s workspace role changed',
+        fields: ['person_id', 'role', 'previous_role'],
+        group: 'people',
+    },
+    'person.updated': {
+        description: 'A person’s directory record changed',
+        fields: ['person_id', 'revision'],
+        group: 'people',
+    },
+    'playbooks.approved': {
+        description: 'HR approved a person’s playbook steps',
+        fields: ['enrollment_id'],
+        group: 'playbook',
+    },
+    'playbooks.buddy.accepted': {
+        description: 'A buddy said yes',
+        fields: ['enrollment_id'],
+        group: 'playbook',
+    },
+    'playbooks.buddy.assigned': {
+        description: 'A buddy was asked to help a new hire',
+        fields: ['enrollment_id', 'buddy_person_id'],
+        group: 'playbook',
+    },
+    'playbooks.buddy.declined': {
+        description: 'A buddy said no',
+        fields: ['enrollment_id'],
+        group: 'playbook',
+    },
+    'playbooks.check_in.answered': {
+        description: 'A new hire answered a check-in: all_good, or need_help when they asked HR for help',
+        fields: ['step_id', 'enrollment_id', 'answer'],
+        group: 'playbook',
+    },
+    'playbooks.enrolled': {
+        description: 'A person started a playbook',
+        fields: ['enrollment_id', 'person_id', 'program_id', 'with_buddy'],
+        group: 'playbook',
+    },
+    'playbooks.enrollment_removed': {
+        description: 'A person was taken off a playbook',
+        fields: ['enrollment_id', 'reason'],
+        group: 'playbook',
+    },
+    'playbooks.schedule_changed': {
+        description: 'A person’s playbook schedule changed',
+        fields: ['enrollment_id'],
+        group: 'playbook',
+    },
+    'playbooks.step.failed': {
+        description: 'A playbook step could not be delivered',
+        fields: ['step_id', 'reason'],
+        group: 'playbook',
+    },
+    'playbooks.step.needs_review': {
+        description: 'A playbook step waits for HR before it sends',
+        fields: ['step_id'],
+        group: 'playbook',
+    },
+    'playbooks.step.sent': {
+        description: 'A playbook step reached its person',
+        fields: ['step_id'],
+        group: 'playbook',
+    },
+    'program.archived': {
+        description: 'A program was archived',
+        fields: ['program_id'],
+        group: 'connections',
+    },
+    'program.created': {
+        description: 'A Connections program or playbook was created',
+        fields: ['program_id', 'kind'],
+        group: 'connections',
+    },
+    'program.paused': {
+        description: 'A program was paused',
+        fields: ['program_id'],
+        group: 'connections',
+    },
+    'program.resumed': {
+        description: 'A program was switched on',
+        fields: ['program_id'],
+        group: 'connections',
+    },
+    'program.updated': {
+        description: 'A program’s settings changed',
+        fields: ['program_id', 'kind'],
+        group: 'connections',
+    },
+    'round.planned': {
+        description: 'Shuffl planned a round of introductions',
+        fields: ['round_id', 'groups', 'unmatched'],
+        group: 'connections',
+    },
+    'round.requested': {
+        description: 'Someone asked for a round of introductions',
+        fields: ['round_id', 'retry'],
+        group: 'connections',
+    },
+    'slack.connected': {
+        description: 'Slack was connected',
+        fields: [],
+        group: 'workspace',
+    },
+    'slack.connection_expired': {
+        description: 'Slack stopped accepting Shuffl’s connection',
+        fields: ['reason'],
+        group: 'workspace',
+    },
+    'slack.uninstalled': {
+        description: 'Shuffl was removed from Slack',
+        fields: ['reason'],
+        group: 'workspace',
+    },
+    'webhook.endpoint.disabled': {
+        description: 'Shuffl turned an endpoint off after it kept failing',
+        fields: ['endpoint_id', 'reason'],
+        group: 'webhooks',
+    },
+    'webhook.test': {
+        description: 'A test event someone sent from Settings or the API',
+        fields: ['endpoint_id'],
+        group: 'webhooks',
+    },
+    'workspace.deletion_requested': {
+        description: 'An owner asked to delete the workspace',
+        fields: ['delete_after'],
+        group: 'workspace',
+    },
+    'workspace.exported': {
+        description: 'Someone exported the workspace’s data',
+        fields: [],
+        group: 'workspace',
+    },
+    'workspace.renamed': {
+        description: 'The workspace was renamed',
+        fields: [],
+        group: 'workspace',
+    },
+    'workspace.restored': {
+        description: 'The workspace was restored',
+        fields: ['deletion_canceled'],
+        group: 'workspace',
+    },
+    'workspace.slack_join_access_changed': {
+        description: 'Who can join from Slack changed',
+        fields: [],
+        group: 'workspace',
+    },
+};
+export const webhookEventTypes = Object.keys(webhookEventCatalog);
+export const isWebhookEventType = (value) => Object.hasOwn(webhookEventCatalog, value);
+/** Keys no payload may ever carry. A test walks the catalog against it. */
+export const webhookNeverSendFields = [
+    'answer_text',
+    'body',
+    'comment',
+    'bio',
+    'email',
+    'feedback',
+    'message',
+    'name',
+    'note',
+    'previous_name',
+    'question',
+    'slack_team_id',
+    'slack_user_id',
+    'subject',
+    'text',
+    'title',
+    'token',
+    'secret',
+];
+export const webhookSecretPrefix = 'whsec_';
+export const webhookToleranceSeconds = 300;
+const base64 = (bytes) => {
+    let text = '';
+    for (const byte of new Uint8Array(bytes))
+        text += String.fromCharCode(byte);
+    return btoa(text);
+};
+const secretBytes = (secret) => {
+    const raw = secret.startsWith(webhookSecretPrefix)
+        ? secret.slice(webhookSecretPrefix.length)
+        : secret;
+    return Uint8Array.from(atob(raw), (char) => char.charCodeAt(0));
+};
+/** The `v1,<signature>` value for one secret: base64 HMAC-SHA256 of
+ * `id.timestamp.body`, as Standard Webhooks specifies. */
+export async function signWebhook(secret, id, timestamp, body) {
+    const key = await crypto.subtle.importKey('raw', secretBytes(secret), { hash: 'SHA-256', name: 'HMAC' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${id}.${timestamp}.${body}`));
+    return `v1,${base64(signature)}`;
+}
+export class WebhookVerificationError extends Error {
+    name = 'WebhookVerificationError';
+}
+const header = (headers, name) => {
+    if (typeof headers.get === 'function')
+        return headers.get(name) ?? undefined;
+    const record = headers;
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+    const value = key ? record[key] : undefined;
+    return Array.isArray(value) ? value[0] : (value ?? undefined);
+};
+const sameText = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let difference = 0;
+    for (let i = 0; i < a.length; i++)
+        difference |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return difference === 0;
+};
+/** Checks a delivery's Standard Webhooks headers against the endpoint's
+ * signing secret (or several while one is rolled) and returns the parsed
+ * event. Pass the raw request body, before any JSON parsing. Throws
+ * WebhookVerificationError for a missing header, a timestamp more than
+ * five minutes away or a signature that matches no secret. */
+export async function verifyWebhook(input) {
+    const id = header(input.headers, 'webhook-id');
+    const timestamp = header(input.headers, 'webhook-timestamp');
+    const signatures = header(input.headers, 'webhook-signature');
+    if (!id || !timestamp || !signatures)
+        throw new WebhookVerificationError('Missing webhook headers');
+    const seconds = Number(timestamp);
+    const now = Math.floor((input.now ?? new Date()).getTime() / 1000);
+    if (!Number.isInteger(seconds) ||
+        Math.abs(now - seconds) >
+            (input.toleranceSeconds ?? webhookToleranceSeconds))
+        throw new WebhookVerificationError('Webhook timestamp is too old or new');
+    const offered = signatures.split(' ').filter(Boolean);
+    const secrets = typeof input.secret === 'string' ? [input.secret] : input.secret;
+    for (const secret of secrets) {
+        const expected = await signWebhook(secret, id, seconds, input.body);
+        if (offered.some((value) => sameText(value, expected)))
+            return JSON.parse(input.body);
+    }
+    throw new WebhookVerificationError('No matching webhook signature');
+}