@siglo/notifications 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jerico de guzman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,479 @@
-# Temporary Holding Version
+# @siglo/notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Security migration: read [approval authorization, POST confirmation, durable recovery and delivery guarantees](../../docs/adapters/notification-hardening.md). GET is read-only; configure `authorize` or explicitly opt into `allowBearerApproval`.
+
+
+Enterprise multi-channel notifications, tamper-proof cryptographic approval tokens, and durable human-in-the-loop callback resumption for Siglo workflows.
+
+[![npm version](https://img.shields.io/npm/v/@siglo/notifications.svg)](https://www.npmjs.com/package/@siglo/notifications)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage: 100%](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](https://github.com/jsoftgem/siglo)
+
+---
+
+## 1. Overview & Architecture
+
+In enterprise backend workflows, human intervention (e.g. invoice approvals, production deployment gates, manual fraud reviews) and notifications across Slack, Email, Discord, and SMS are critical. `@siglo/notifications` integrates these patterns directly into Siglo's 5-phase step lifecycle:
+
+```mermaid
+flowchart TD
+    subgraph Execution["1. Workflow Dispatch & Suspension"]
+        Step["sendInteractiveApprovalStep('managerApproval', ...)"]
+        EgressCheck["Assert Transport Host in ASL Network Policy"]
+        IdempCheck["Claim Idempotency Key (stackId:stepName:recipientHash)"]
+        TokenGen["Generate HMAC-SHA256 Signed Action URLs (KeyRing)"]
+        Dispatch["Dispatch via Provider (Slack Block Kit / HTML Email)"]
+        Wait["waitForEvent('APPROVAL_RESOLVED', { correlationKey, timeout })"]
+        Suspend["Checkpoint to PostgreSQL / Redis (Zero Memory Footprint)"]
+
+        Step --> EgressCheck --> IdempCheck --> TokenGen --> Dispatch --> Wait --> Suspend
+    end
+
+    subgraph Resumption["2. Webhook Callback & Distributed Resumption"]
+        User(["Human Approver clicks 'Approve' or 'Reject'"])
+        Router["Callback Router (@siglo/express, fastify, hono)"]
+        Verify["verifyActionToken() (timingSafeCompare, tolerance window)"]
+        RevokeCheck{"isRevoked(correlationKey)?"}
+        ClaimWait["Atomic Storage Claim: claimWaitRecord(correlationKey)"]
+        ResumeFlow["resumeWorkflow(flow, correlationKey, { approved: true })"]
+        Duplicate["Reject with 409 Conflict (WorkflowAlreadyResumedException)"]
+
+        User --> Router --> Verify --> RevokeCheck
+        RevokeCheck -- Yes (Cancelled) --> Duplicate
+        RevokeCheck -- No --> ClaimWait
+        ClaimWait -- Claim Won (200 OK) --> ResumeFlow
+        ClaimWait -- Already Claimed (409) --> Duplicate
+    end
+
+    subgraph Scheduler["3. Timeout Awakening (Dormant Resumption)"]
+        ExpiredWait["Approval Timeout Elapsed ('2h', '48h')"]
+        Poller["@siglo/scheduler (PostgresWaitPoller / session locks)"]
+        TimeoutResume["resumeWorkflow(..., { event: 'timer:expired', allowExpired: true })"]
+
+        ExpiredWait --> Poller --> TimeoutResume
+    end
+```
+
+---
+
+## 2. Installation & Requirements
+
+Install `@siglo/notifications` alongside `@siglo/core`, `@siglo/crypto`, and `@siglo/http`:
+
+```bash
+npm install @siglo/notifications @siglo/crypto @siglo/http @siglo/core
+```
+
+Peer dependencies:
+- `@siglo/core`: `^1.0.0`
+- `@siglo/crypto`: `^1.0.0`
+- `@siglo/http`: `^1.0.0`
+- `@siglo/scheduler` (optional, for background timeout polling): `^1.0.0`
+- `@siglo/postgres` (optional, for persistent checkpoints and shared revocation): `^1.0.0`
+
+---
+
+## 3. Quick Start: Interactive Human Approval Flow
+
+```typescript
+import express from 'express';
+import { flow, waitForEvent, Step, useStorage } from '@siglo/core';
+import { PostgresStorageAdapter } from '@siglo/postgres';
+import { StaticKeyRing } from '@siglo/crypto';
+import {
+  registerNotificationTransport,
+  SlackTransport,
+  sendInteractiveApprovalStep,
+  createNotificationExpressMiddleware,
+  configureApprovalRevocationStore,
+  PostgresApprovalRevocationStore,
+  PostgresNotificationDispatchStore,
+  configureNotificationDispatchStore
+} from '@siglo/notifications';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const storage = new PostgresStorageAdapter({ client: pool });
+await storage.ensureTables();
+useStorage(storage);
+
+// 1. Shared revocation store across workers
+const revocationStore = new PostgresApprovalRevocationStore(pool);
+await revocationStore.initialize();
+configureApprovalRevocationStore(revocationStore);
+const dispatchStore = new PostgresNotificationDispatchStore(pool);
+await dispatchStore.initialize();
+configureNotificationDispatchStore(dispatchStore);
+
+// 2. Register transports globally (or pass per-step)
+registerNotificationTransport(new SlackTransport({
+  apiKey: process.env.SLACK_BOT_TOKEN!
+}));
+
+// 3. Define KeyRing for HMAC signing and key rotation
+const approvalKeyRing = new StaticKeyRing('primary', {
+  primary: process.env.APPROVAL_SECRET_CURRENT!,
+  previous: process.env.APPROVAL_SECRET_PREVIOUS!
+});
+
+// 4. Define the approval workflow
+export const deploymentWorkflow = flow(
+  // Step 1: Send Slack Block Kit card with signed Approve/Reject buttons
+  sendInteractiveApprovalStep('requestApproval', {
+    channel: 'slack',
+    recipient: (ctx: { leadDevSlackId: string }) => ({ slackUserId: ctx.leadDevSlackId }),
+    title: (ctx: { service: string; version: string }) => `Deploy ${ctx.service}@${ctx.version}?`,
+    description: (ctx: { deploymentId: string }) => `Deployment ID: ${ctx.deploymentId}`,
+    correlationKey: (ctx: { deploymentId: string }) => `deploy:${ctx.deploymentId}`,
+    timeout: '2h',
+    onApproveEvent: 'APPROVAL_RESOLVED',
+    onRejectEvent: 'APPROVAL_RESOLVED',
+    callbackBaseUrl: 'https://orchestrator.acme.com/api/siglo/callback',
+    signingSecret: approvalKeyRing,
+    autoCompensate: true // Updates Slack card to 'Cancelled' on failure or rollback
+  }),
+
+  // Step 2: Suspends workflow into PostgreSQL durable checkpoint with a 2h timer
+  waitForEvent('APPROVAL_RESOLVED', {
+    correlationKey: (ctx: { deploymentId: string }) => `deploy:${ctx.deploymentId}`,
+    timeout: '2h'
+  }),
+
+  // Step 3: Guard on approved decision before executing side effects
+  new Step('verifyDecision', async (ctx: { approved?: boolean; event?: { type: string } }) => {
+    if (ctx.approved !== true || ctx.event?.type === 'timer:expired') {
+      throw new Error('Deployment approval was rejected or expired');
+    }
+    return { verified: true };
+  }),
+
+  deployServiceStep
+);
+
+// 5. Expose callback endpoint in Express
+const app = express();
+app.use(express.urlencoded({ extended: false }));
+app.all(
+  '/api/siglo/callback',
+  createNotificationExpressMiddleware({
+    workflow: deploymentWorkflow,
+    signingSecret: approvalKeyRing,
+    authorize: authorizeApproval, // Application identity and CSRF check; see migration guide.
+    responseFormat: 'html',
+    allowedOrigins: ['https://orchestrator.acme.com', 'https://dashboard.acme.com']
+  })
+);
+app.listen(3000);
+```
+
+---
+
+## 4. Multi-Channel Transports
+
+`@siglo/notifications` ships with built-in adapters that adhere to Siglo's AsyncLocalStorage (ASL) network egress perimeter and require zero third-party SDK dependencies (using native HTTPS with validated socket DNS resolution):
+
+| Transport | Channel | Allowed Hosts | Key Features |
+|---|---|---|---|
+| `SlackTransport` | `slack` | `slack.com` | Block Kit action buttons, message cancellation via `chat.update`, modal forms via `openModal` |
+| `ResendTransport` | `email` | `api.resend.com` | Responsive HTML email action templates |
+| `SendGridTransport` | `email` | `api.sendgrid.com` | HTML email dispatch with `x-message-id` tracking |
+| `PostmarkTransport` | `email` | `api.postmarkapp.com` | HTML + plain-text email with server token auth |
+| `SmtpTransport` | `email` | User-defined host | Injected SMTP client (`sendMail`) without bundled dependencies |
+| `DiscordTransport` | `discord` | `discord.com` | Webhook embeds with clickable action links |
+| `TwilioTransport` | `sms` | `api.twilio.com` | Basic SMS dispatch and two-way signed webhook parsing |
+| `PushWebhookTransport` | `push` | Webhook hostname | Provider-neutral JSON push payloads over HTTPS |
+
+### Transport Configuration Examples
+
+```typescript
+import {
+  SlackTransport, ResendTransport, SendGridTransport, PostmarkTransport,
+  DiscordTransport, TwilioTransport, SmtpTransport, PushWebhookTransport,
+  registerNotificationTransport
+} from '@siglo/notifications';
+
+// Slack
+registerNotificationTransport(new SlackTransport({
+  apiKey: process.env.SLACK_BOT_TOKEN!
+}));
+
+// Resend Email
+registerNotificationTransport(new ResendTransport({
+  apiKey: process.env.RESEND_API_KEY!,
+  from: 'ops@acme.com'
+}));
+
+// SendGrid Email
+registerNotificationTransport(new SendGridTransport({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  from: 'ops@acme.com'
+}));
+
+// Postmark Email
+registerNotificationTransport(new PostmarkTransport({
+  apiKey: process.env.POSTMARK_SERVER_TOKEN!,
+  from: 'ops@acme.com'
+}));
+
+// Discord
+registerNotificationTransport(new DiscordTransport());
+
+// Twilio SMS
+registerNotificationTransport(new TwilioTransport({
+  accountSid: process.env.TWILIO_ACCOUNT_SID!,
+  authToken: process.env.TWILIO_AUTH_TOKEN!,
+  from: '+15551234567'
+}));
+
+// Generic SMTP (e.g. Nodemailer)
+registerNotificationTransport(new SmtpTransport({
+  host: 'smtp.mailgun.org',
+  from: 'no-reply@acme.com',
+  sendMail: async (mail) => nodemailerTransport.sendMail(mail)
+}));
+
+// Generic HTTPS Push Webhook
+registerNotificationTransport(new PushWebhookTransport({
+  url: 'https://push.acme.com/v1/notify',
+  headers: { 'X-Service-Token': process.env.PUSH_SERVICE_TOKEN! }
+}));
+```
+
+---
+
+## 5. Workflow Step API
+
+### `sendNotificationStep(name, options)`
+
+Dispatches one-way alerts (email, chat, SMS, push) with automatic idempotency deduplication and context redaction:
+
+```typescript
+import { sendNotificationStep } from '@siglo/notifications';
+
+const alertOps = sendNotificationStep('alertOps', {
+  channel: 'slack',
+  recipient: { slackChannelId: 'C_OPS_ALERTS' },
+  template: (ctx) => `High latency detected on ${ctx.serviceName}: ${ctx.p99}ms`,
+  deduplicationTtl: 3600 // Suppresses duplicate alerts within 1 hour
+});
+```
+
+### `sendInteractiveApprovalStep(name, options)`
+
+Generates signed action tokens, formats interactive cards/emails, registers compensation rollbacks, and attaches approval metadata:
+
+```typescript
+import { sendInteractiveApprovalStep } from '@siglo/notifications';
+
+const approvalStep = sendInteractiveApprovalStep('legalApproval', {
+  channel: 'email',
+  recipient: (ctx) => ({ email: ctx.legalReviewerEmail }),
+  title: (ctx) => `Contract Review Required: ${ctx.contractTitle}`,
+  description: (ctx) => `Value: $${ctx.contractValue}`,
+  correlationKey: (ctx) => `contract:${ctx.contractId}`,
+  timeout: '72h',
+  onApproveEvent: 'CONTRACT_APPROVED',
+  onRejectEvent: 'CONTRACT_REJECTED',
+  callbackBaseUrl: 'https://api.acme.com/siglo/callback',
+  signingSecret: process.env.APPROVAL_SECRET!,
+  autoCompensate: true
+});
+```
+
+---
+
+## 6. Cryptographic Action Tokens & Secret Rotation
+
+Action tokens embed callback metadata in a compact URL-safe format:
+
+$$\text{Token} = \text{base64url}(\text{Payload}) \,\|\, \text{base64url}(\text{HMAC-SHA256}(\text{Payload}, \text{Secret}))$$
+
+### Features:
+- **No Database Lookup on Verification**: Validates authenticity and expiration instantly before accessing storage.
+- **Constant-Time Verification**: Uses `@siglo/crypto`'s `timingSafeCompare` to defeat timing attacks.
+- **Replay handling**: Durable claims reject completed requests. `toleranceSeconds` checks future issuance only; nonces are not independently consumed.
+- **Key Rotation**: Compatible with `@siglo/crypto`'s `StaticKeyRing` to verify tokens signed with previous keys during rotation windows.
+
+```typescript
+import { StaticKeyRing } from '@siglo/crypto';
+import { signActionToken, verifyActionToken } from '@siglo/notifications';
+
+const keyRing = new StaticKeyRing('v2', {
+  v2: 'current-secret-key-2026',
+  v1: 'legacy-secret-key-2025'
+});
+
+// Verify token
+const payload = await verifyActionToken(tokenString, keyRing, {
+  toleranceSeconds: 60 // Allow 60s future clock skew
+});
+```
+
+---
+
+## 7. Web Framework Resumption Handlers
+
+First-class route handlers are provided for `@siglo/express`, `@siglo/fastify`, and `@siglo/hono` with built-in security headers, CORS preflight handling, and response customization:
+
+### Supported Security Headers
+- `Cache-Control: no-store`
+- `Referrer-Policy: no-referrer`
+- `X-Content-Type-Options: nosniff`
+- `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'`
+
+### Express Example
+
+```typescript
+import express from 'express';
+import { createNotificationExpressMiddleware } from '@siglo/notifications';
+
+const app = express();
+app.use(express.urlencoded({ extended: false }));
+
+app.all(
+  '/api/siglo/callback',
+  createNotificationExpressMiddleware({
+    workflow: orderFlow,
+    signingSecret: process.env.APPROVAL_SECRET!,
+    authorize: authorizeApproval, // Application identity and CSRF check; see migration guide.
+    responseFormat: 'html', // Renders accessible confirmation page
+    allowedOrigins: ['https://orchestrator.acme.com', 'https://dashboard.acme.com'],
+    onSuccessRedirect: 'https://dashboard.acme.com/approvals/success',
+    onExpiredRedirect: 'https://dashboard.acme.com/approvals/expired',
+    onErrorRedirect: 'https://dashboard.acme.com/approvals/error'
+  })
+);
+```
+
+### Fastify Example
+
+```typescript
+import Fastify from 'fastify';
+import { createNotificationFastifyHandler } from '@siglo/notifications';
+
+const fastify = Fastify();
+const handler = createNotificationFastifyHandler({
+  workflow: orderFlow,
+  signingSecret: process.env.APPROVAL_SECRET!,
+  authorize: authorizeApproval // Application authentication and CSRF check.
+});
+fastify.route({ method: ['GET', 'POST'], url: '/api/siglo/callback', handler });
+```
+
+### Hono Example (Node)
+
+```typescript
+import { Hono } from 'hono';
+import { createNotificationHonoHandler } from '@siglo/notifications';
+
+const app = new Hono();
+app.all('/api/siglo/callback', createNotificationHonoHandler({
+  workflow: orderFlow,
+  signingSecret: process.env.APPROVAL_SECRET!,
+  authorize: authorizeApproval
+}));
+```
+
+---
+
+## 8. Inbound Twilio SMS Two-Way Approvals
+
+Parse and cryptographically verify inbound SMS approval webhooks (`APPROVE <ref>` or `REJECT <ref>`) adhering to Twilio's signed form specification:
+
+```typescript
+import { parseTwilioSmsReply } from '@siglo/notifications';
+
+app.post('/api/twilio/sms', express.urlencoded({ extended: false }), async (req, res) => {
+  const reply = parseTwilioSmsReply(req.body, {
+    publicUrl: 'https://api.acme.com/api/twilio/sms',
+    authToken: process.env.TWILIO_AUTH_TOKEN!,
+    signature: req.headers['x-twilio-signature'] as string
+  });
+
+  // reply: { approved: true, reference: 'deploy:123', from: '+15550001', messageId: 'SM...' }
+  // Validate a persisted, unpredictable challenge and expected sender first.
+  // Atomically consume the pending request and deduplicate MessageSid in your
+  // application approval service. See the security migration guide.
+  await approvalService.acceptVerifiedSmsReply(reply);
+
+  res.type('text/xml').send('<Response></Response>');
+});
+```
+
+---
+
+## 9. Saga Compensation & Shared Revocations
+
+When a downstream step fails or a workflow times out, Siglo triggers Named Saga Compensation (`cancelNotification`):
+1. **Chat Channels (Slack)**: Calls `chat.update` to replace interactive buttons with an alert (e.g. `"Workflow Cancelled"`).
+2. **Email & SMS**: Records the `correlationKey` into the revocation store so any future clicks on existing email links return `409 Conflict`.
+
+### Configuring Shared PostgreSQL Revocation Store
+
+```typescript
+import { configureApprovalRevocationStore, PostgresApprovalRevocationStore } from '@siglo/notifications';
+
+const revocationStore = new PostgresApprovalRevocationStore(pgPool);
+await revocationStore.initialize();
+configureApprovalRevocationStore(revocationStore);
+```
+
+---
+
+## 10. Observability & PII Redaction
+
+Standard recipient identifiers, credentials, and tokens are automatically redacted by Siglo core before telemetry dispatch. For fine-grained domain PII masking, attach a `NotificationMonitor`:
+
+```typescript
+import { NotificationMonitor } from '@siglo/notifications';
+
+const monitor = new NotificationMonitor([
+  'outputSummary.customers.*.contact',
+  'order.shippingAddress.phone'
+]);
+
+workflow.execute(input, { monitor });
+```
+
+---
+
+## 11. Testing & Verification
+
+`@siglo/notifications` ships with a zero-network mock transport in `@siglo/notifications/testing`:
+
+```typescript
+import { MockNotificationTransport } from '@siglo/notifications/testing';
+import { sendNotificationStep } from '@siglo/notifications';
+
+const mock = new MockNotificationTransport();
+const step = sendNotificationStep('notify', {
+  channel: 'email',
+  recipient: 'user@example.com',
+  template: 'Hello world',
+  transport: mock
+});
+
+await step.execute({});
+console.log(mock.messages.length); // 1
+console.log(mock.messages[0].to);   // 'user@example.com'
+```
+
+### Running Test Suites
+
+```bash
+# Run unit suite (zero network egress)
+npm test --workspace=@siglo/notifications
+
+# Run 100% coverage verification
+npm run test:coverage --workspace=@siglo/notifications
+
+# Run multi-worker PostgreSQL integration suite
+SIGLO_TEST_POSTGRES_URL=postgres://siglo:siglo_test@localhost:5432/siglo_notifications_test \
+npm run test:postgres --workspace=@siglo/notifications
+```
+
+---
+
+## 12. License
+
+MIT © [Jerico de Guzman](https://github.com/jsoftgem/siglo)

package/dist/approvals.d.ts

@@ -0,0 +1,38 @@
+/** Acceptance and revocation must use the same lock implementation on every worker. */
+export interface ApprovalRevocationStore {
+    revoke(correlationKey: string): Promise<void>;
+    isRevoked(correlationKey: string): Promise<boolean>;
+    withApprovalLock<T>(correlationKey: string, action: () => Promise<T>): Promise<T>;
+}
+export declare class InMemoryApprovalRevocationStore implements ApprovalRevocationStore {
+    private revoked;
+    private locks;
+    private scope;
+    withApprovalLock<T>(key: string, action: () => Promise<T>): Promise<T>;
+    revoke(key: string): Promise<void>;
+    isRevoked(key: string): Promise<boolean>;
+}
+export declare function configureApprovalRevocationStore(value: ApprovalRevocationStore): void;
+export declare function getApprovalRevocationStore(): ApprovalRevocationStore;
+interface Connection {
+    query(sql: string, values?: any[]): Promise<{
+        rows: any[];
+    }>;
+    release?(error?: Error): void;
+}
+interface Client extends Connection {
+    connect?(): Promise<Connection | void>;
+}
+/** Use a Pool in multi-worker deployments; locks hold a dedicated connection until completion. */
+export declare class PostgresApprovalRevocationStore implements ApprovalRevocationStore {
+    private client;
+    private scope;
+    private directClientBusy;
+    constructor(client: Client);
+    initialize(): Promise<void>;
+    withApprovalLock<T>(key: string, action: () => Promise<T>): Promise<T>;
+    revoke(correlationKey: string): Promise<void>;
+    isRevoked(correlationKey: string): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=approvals.d.ts.map

package/dist/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AAEA,uFAAuF;AACvF,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnF;AACD,qBAAa,+BAAgC,YAAW,uBAAuB;IAC7E,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAgD;IACvD,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAQtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAClC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAC/C;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAmB;AACzG,wBAAgB,0BAA0B,IAAI,uBAAuB,CAAkB;AACvF,UAAU,UAAU;IAClB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CAC/B;AACD,UAAU,MAAO,SAAQ,UAAU;IAAG,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;CAAE;AAC9E,kGAAkG;AAClG,qBAAa,+BAAgC,YAAW,uBAAuB;IAGjE,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,KAAK,CAAiF;IAC9F,OAAO,CAAC,gBAAgB,CAAS;gBACb,MAAM,EAAE,MAAM;IAC5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAG3B,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAsBtE,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7C,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI1D"}

package/dist/approvals.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresApprovalRevocationStore = exports.InMemoryApprovalRevocationStore = void 0;
+exports.configureApprovalRevocationStore = configureApprovalRevocationStore;
+exports.getApprovalRevocationStore = getApprovalRevocationStore;
+const node_async_hooks_1 = require("node:async_hooks");
+const core_1 = require("@siglo/core");
+class InMemoryApprovalRevocationStore {
+    revoked = new Set();
+    locks = new Map();
+    scope = new node_async_hooks_1.AsyncLocalStorage();
+    async withApprovalLock(key, action) {
+        if (this.locks.has(key) && this.scope.getStore()?.get(key) === this.locks.get(key))
+            return action();
+        if (this.locks.has(key))
+            throw new core_1.DuplicateEventException(key);
+        const owner = Symbol(key);
+        this.locks.set(key, owner);
+        try {
+            return await this.scope.run(new Map([...(this.scope.getStore() ?? []), [key, owner]]), action);
+        }
+        finally {
+            this.locks.delete(key);
+        }
+    }
+    async revoke(key) { await this.withApprovalLock(key, async () => { this.revoked.add(key); const waiting = core_1.defaultDurableManager.getWaiting(key); if (waiting)
+        waiting.status = 'failed'; }); }
+    async isRevoked(key) { return this.revoked.has(key); }
+}
+exports.InMemoryApprovalRevocationStore = InMemoryApprovalRevocationStore;
+let store = new InMemoryApprovalRevocationStore();
+function configureApprovalRevocationStore(value) { store = value; }
+function getApprovalRevocationStore() { return store; }
+/** Use a Pool in multi-worker deployments; locks hold a dedicated connection until completion. */
+class PostgresApprovalRevocationStore {
+    client;
+    scope = new node_async_hooks_1.AsyncLocalStorage();
+    directClientBusy = false;
+    constructor(client) {
+        this.client = client;
+    }
+    async initialize() {
+        await this.client.query('CREATE TABLE IF NOT EXISTS siglo_approval_revocations (correlation_key TEXT PRIMARY KEY, revoked_at TIMESTAMPTZ NOT NULL DEFAULT NOW())');
+    }
+    async withApprovalLock(key, action) {
+        if (this.scope.getStore()?.active && this.scope.getStore()?.key === key)
+            return action();
+        // pg.Client.connect() is not a pool checkout. Pools expose totalCount.
+        const pooled = 'totalCount' in this.client;
+        if (!pooled && this.directClientBusy)
+            throw new core_1.DuplicateEventException(key);
+        if (!pooled)
+            this.directClientBusy = true;
+        let connection;
+        let locked = false;
+        try {
+            connection = pooled ? await this.client.connect() : this.client;
+            const result = await connection.query('SELECT pg_try_advisory_lock(hashtextextended($1, 0)) AS locked', [`siglo:approval:${key}`]);
+            locked = result.rows[0]?.locked === true;
+            if (!locked)
+                throw new core_1.DuplicateEventException(key);
+            const scope = { key, client: connection, active: true };
+            try {
+                return await this.scope.run(scope, action);
+            }
+            finally {
+                scope.active = false;
+            }
+        }
+        finally {
+            try {
+                if (locked)
+                    await connection.query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [`siglo:approval:${key}`]);
+            }
+            catch (error) {
+                if (pooled) {
+                    connection?.release?.(error);
+                    connection = undefined;
+                }
+                throw error;
+            }
+            finally {
+                if (pooled)
+                    connection?.release?.();
+                else
+                    this.directClientBusy = false;
+            }
+        }
+    }
+    async revoke(correlationKey) {
+        await this.withApprovalLock(correlationKey, async () => {
+            const adapter = (0, core_1.getStorageAdapter)();
+            const record = await adapter?.getWaitRecord?.(correlationKey);
+            const cancel = async () => {
+                // Cancel recovery first: a crash before the revocation INSERT must fail closed.
+                await adapter?.cancelWaitRecord?.(correlationKey);
+                await this.scope.getStore().client.query('INSERT INTO siglo_approval_revocations (correlation_key) VALUES ($1) ON CONFLICT (correlation_key) DO NOTHING', [correlationKey]);
+            };
+            if (record && adapter?.withWorkflowLock)
+                await adapter.withWorkflowLock(record.stackId, cancel);
+            else
+                await cancel();
+        });
+    }
+    async isRevoked(correlationKey) {
+        const result = await (this.scope.getStore()?.active ? this.scope.getStore().client : this.client).query('SELECT correlation_key FROM siglo_approval_revocations WHERE correlation_key = $1', [correlationKey]);
+        return result.rows.length > 0;
+    }
+}
+exports.PostgresApprovalRevocationStore = PostgresApprovalRevocationStore;
+//# sourceMappingURL=approvals.js.map

package/dist/approvals.js.map

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

package/dist/callbacks.d.ts

@@ -0,0 +1,14 @@
+import { CallbackHandlerOptions } from './types';
+export interface NotificationCallbackResponse {
+    status: number;
+    body: {
+        message: string;
+    };
+    redirect?: string;
+}
+export declare function handleNotificationCallback(token: string, options: CallbackHandlerOptions): Promise<NotificationCallbackResponse>;
+export declare function renderApprovalConfirmation(result: NotificationCallbackResponse): string;
+export declare function createNotificationExpressMiddleware(options: CallbackHandlerOptions): (req: any, res: any) => Promise<void>;
+export declare function createNotificationFastifyHandler(options: CallbackHandlerOptions): (req: any, reply: any) => Promise<void>;
+export declare function createNotificationHonoHandler(options: CallbackHandlerOptions): (c: any) => Promise<Response>;
+//# sourceMappingURL=callbacks.d.ts.map