@maroonedsoftware/slack 1.8.2 → 1.9.0

package/dist/slack.signature.d.ts

@@ -26,7 +26,7 @@ export type VerifySlackSignatureInput = {
     maxAgeSeconds?: number;
     /**
      * Override for the current Unix time in seconds. Mostly useful for tests;
-     * defaults to `Math.floor(Date.now() / 1000)`.
+     * defaults to `Math.floor(DateTime.now().toSeconds())`.
      */
     now?: number;
 };

package/dist/slack.signature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slack.signature.d.ts","sourceRoot":"","sources":["../src/slack.signature.ts"],"names":[],"mappings":"AAGA,gGAAgG;AAChG,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GACnC,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,yBAAyB,KAAG,IAkDvE,CAAC"}
+{"version":3,"file":"slack.signature.d.ts","sourceRoot":"","sources":["../src/slack.signature.ts"],"names":[],"mappings":"AAIA,gGAAgG;AAChG,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GACnC,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,yBAAyB,KAAG,IAkDvE,CAAC"}

package/dist/slack.signature.policy.d.ts

@@ -0,0 +1,71 @@
+import { BinaryLike } from 'node:crypto';
+import { Policy, PolicyEnvelope, PolicyResult } from '@maroonedsoftware/policies';
+import { SlackConfig } from './slack.config.js';
+/**
+ * Policy name under which {@link SlackSignaturePolicy} is registered. Use as the
+ * key when wiring your `PolicyRegistryMap`, and pass to `PolicyService.check`.
+ */
+export declare const SLACK_SIGNATURE_POLICY: "slack.signature.valid";
+/** Header carrying the request timestamp Slack signs into the HMAC. */
+export declare const SLACK_REQUEST_TIMESTAMP_HEADER = "X-Slack-Request-Timestamp";
+/** Header carrying the `v0=`-prefixed request signature. */
+export declare const SLACK_SIGNATURE_HEADER = "X-Slack-Signature";
+/**
+ * Configuration the {@link SlackSignaturePolicy} reads. A structural subset of
+ * {@link SlackConfig}, so a `SlackConfig` value satisfies it directly — e.g.
+ * `requireSignature<SlackSignatureOptions>('slack')` with the Slack config
+ * stored under that `AppConfig` key.
+ */
+export type SlackSignatureOptions = Pick<SlackConfig, 'signingSecret' | 'signatureMaxAgeSeconds'>;
+/**
+ * Context for {@link SlackSignaturePolicy}: the raw request bytes, a
+ * case-insensitive header accessor, and the {@link SlackSignatureOptions}.
+ *
+ * Structurally compatible with `@maroonedsoftware/koa`'s
+ * `SignaturePolicyContext<SlackSignatureOptions>`, so the koa `requireSignature`
+ * middleware can drive this policy without the slack package depending on koa —
+ * register `SlackSignaturePolicy` under the signature policy name and point the
+ * middleware at the `AppConfig` key holding the Slack config.
+ */
+export interface SlackSignaturePolicyContext {
+    /** Raw, unparsed request body — exactly as Slack sent it (from `ctx.rawBody`). */
+    rawBody: BinaryLike;
+    /**
+     * Case-insensitive request header accessor (Koa's `ctx.get`); returns `''`
+     * when the header is absent.
+     */
+    getHeader: (name: string) => string;
+    /** Slack signing configuration. */
+    options: SlackSignatureOptions;
+}
+/**
+ * Policy form of {@link verifySlackSignature}: verifies a Slack request against
+ * the app signing secret using Slack's v0 scheme (HMAC over
+ * `v0:{timestamp}:{rawBody}`, `v0=`-prefixed, with timestamp replay
+ * protection).
+ *
+ * Delegates to {@link verifySlackSignature} so the crypto/timestamp logic has a
+ * single source of truth, but answers as a {@link PolicyResult} rather than
+ * throwing: allows on success, denies on failure with the helper's
+ * {@link SlackSignatureFailureReason} as the denial `reason` and its diagnostics
+ * (timestamps, window) on `internalDetails` — never the signing secret, never
+ * on the wire. The replay window is anchored to `envelope.now` so all policies
+ * in an evaluation share one clock.
+ *
+ * Registered by default under {@link SLACK_SIGNATURE_POLICY}.
+ *
+ * @example
+ * ```ts
+ * // Direct evaluation in a route handler:
+ * const result = await policyService.check(SLACK_SIGNATURE_POLICY, {
+ *   rawBody: ctx.rawBody,
+ *   getHeader: name => ctx.get(name),
+ *   options: ctx.container.get(SlackConfig),
+ * });
+ * if (isPolicyResultDenied(result)) throw httpError(401);
+ * ```
+ */
+export declare class SlackSignaturePolicy extends Policy<SlackSignaturePolicyContext> {
+    evaluate(context: SlackSignaturePolicyContext, envelope: PolicyEnvelope): Promise<PolicyResult>;
+}
+//# sourceMappingURL=slack.signature.policy.d.ts.map

package/dist/slack.signature.policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.signature.policy.d.ts","sourceRoot":"","sources":["../src/slack.signature.policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAG,uBAAgC,CAAC;AAEvE,uEAAuE;AACvE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,wBAAwB,CAAC,CAAC;AAElG;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,OAAO,EAAE,UAAU,CAAC;IACpB;;;OAGG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,mCAAmC;IACnC,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,oBAAqB,SAAQ,MAAM,CAAC,2BAA2B,CAAC;IACrE,QAAQ,CAAC,OAAO,EAAE,2BAA2B,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;CAwBtG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maroonedsoftware/slack",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Slack utilities for ServerKit.",
   "author": {
     "name": "Marooned Software",
@@ -31,11 +31,14 @@
   ],
   "dependencies": {
     "@slack/web-api": "^7.16.0",
-    "injectkit": "^1.4.1",
+    "injectkit": "^1.4.2",
     "@maroonedsoftware/errors": "1.7.0",
+    "@maroonedsoftware/policies": "0.5.0",
     "@maroonedsoftware/logger": "1.1.1"
   },
   "devDependencies": {
+    "@types/luxon": "^3.7.1",
+    "luxon": "^3.7.2",
     "@repo/config-eslint": "0.2.1",
     "@repo/config-typescript": "0.1.0"
   },