@digimuza/saas-core 0.0.2

package/dist/webhooks/outgoing.js

@@ -0,0 +1,375 @@
+import { and, asc, eq, inArray, lte, or, sql } from "drizzle-orm";
+import { webhookDeliveries, webhookEndpoints } from "../db/schema/index.js";
+import { ConflictError, InvalidInputError, NotFoundError } from "../errors.js";
+import { isUniqueViolation } from "../db/errors.js";
+import { generateWebhookSecret, signWebhookPayload, SIGNATURE_HEADER, TIMESTAMP_HEADER, } from "./signature.js";
+const DEFAULT_MAX_ATTEMPTS = 6;
+const DEFAULT_INITIAL_RETRY_MS = 30_000;
+const DEFAULT_MAX_RETRY_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_FAILURE_THRESHOLD = 20;
+const DEFAULT_CLAIM_LIMIT = 50;
+const MAX_CLAIM_LIMIT = 500;
+const MAX_ERROR_LENGTH = 1000;
+/** Reject URLs a tenant should not be able to make the server call. */
+function assertDeliverableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new InvalidInputError("A webhook URL must be absolute.");
+    }
+    if (parsed.protocol !== "https:") {
+        /**
+         * HTTPS only. A signed payload over plain HTTP still exposes its contents,
+         * and the signature does not stop an interceptor reading it.
+         */
+        throw new InvalidInputError("A webhook URL must use https.");
+    }
+    const host = parsed.hostname.toLowerCase();
+    /**
+     * First-pass SSRF guard. A tenant registering `http://169.254.169.254/` would
+     * otherwise have the server fetch its own cloud metadata and post the result
+     * back. DNS can still resolve a public name to a private address, so a
+     * production deployment should also route egress through a proxy that enforces
+     * this at connect time — which is why {@link WebhookSender} is injectable.
+     */
+    const blocked = host === "localhost" ||
+        host === "0.0.0.0" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".internal") ||
+        host.endsWith(".local") ||
+        /^127\./.test(host) ||
+        /^10\./.test(host) ||
+        /^192\.168\./.test(host) ||
+        /^169\.254\./.test(host) ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+        host === "[::1]" ||
+        host === "::1";
+    if (blocked) {
+        throw new InvalidInputError("A webhook URL may not point at a private or loopback address.");
+    }
+}
+function truncate(message) {
+    return message.length > MAX_ERROR_LENGTH
+        ? `${message.slice(0, MAX_ERROR_LENGTH - 1)}…`
+        : message;
+}
+export function createOutgoingWebhooksService(deps) {
+    const now = deps.now ?? (() => new Date());
+    const maxAttempts = deps.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const initialRetryMs = deps.initialRetryDelayMs ?? DEFAULT_INITIAL_RETRY_MS;
+    const maxRetryMs = deps.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_MS;
+    const failureThreshold = deps.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+    /** Doubling backoff, capped. Attempt 1 has already happened when this runs. */
+    function retryDelayMs(attemptCount) {
+        return Math.min(initialRetryMs * 2 ** (attemptCount - 1), maxRetryMs);
+    }
+    async function requireOwnEndpoint(context, endpointId) {
+        const rows = await deps.db
+            .select()
+            .from(webhookEndpoints)
+            .where(and(eq(webhookEndpoints.id, endpointId), 
+        // Scoped, so another tenant's endpoint id is simply not found.
+        eq(webhookEndpoints.workspaceId, context.workspaceId)))
+            .limit(1);
+        const endpoint = rows[0];
+        if (endpoint === undefined) {
+            throw new NotFoundError("Webhook endpoint not found.");
+        }
+        return endpoint;
+    }
+    const endpoints = {
+        async create(context, input) {
+            assertDeliverableUrl(input.url);
+            const secret = generateWebhookSecret();
+            try {
+                const [endpoint] = await deps.db
+                    .insert(webhookEndpoints)
+                    .values({
+                    workspaceId: context.workspaceId,
+                    url: input.url,
+                    description: input.description ?? null,
+                    secret,
+                    eventTypes: [...new Set(input.eventTypes ?? [])],
+                })
+                    .returning();
+                return { endpoint: endpoint, secret };
+            }
+            catch (error) {
+                if (isUniqueViolation(error, "webhook_endpoints_workspace_url_unique")) {
+                    throw new ConflictError("That URL is already registered for this workspace.", {
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        },
+        async list(context) {
+            return deps.db
+                .select()
+                .from(webhookEndpoints)
+                .where(eq(webhookEndpoints.workspaceId, context.workspaceId))
+                .orderBy(asc(webhookEndpoints.createdAt));
+        },
+        async get(context, endpointId) {
+            const endpoint = await requireOwnEndpoint(context, endpointId);
+            return { endpoint, secret: endpoint.secret };
+        },
+        async update(context, endpointId, patch) {
+            await requireOwnEndpoint(context, endpointId);
+            if (patch.url !== undefined) {
+                assertDeliverableUrl(patch.url);
+            }
+            const [updated] = await deps.db
+                .update(webhookEndpoints)
+                .set({
+                ...(patch.url !== undefined ? { url: patch.url } : {}),
+                ...(patch.description !== undefined ? { description: patch.description } : {}),
+                ...(patch.eventTypes !== undefined
+                    ? { eventTypes: [...new Set(patch.eventTypes)] }
+                    : {}),
+                ...(patch.isActive !== undefined
+                    ? {
+                        isActive: patch.isActive,
+                        // Re-enabling clears the failure state, or it would disable again
+                        // on the next failure regardless of what changed.
+                        ...(patch.isActive
+                            ? { consecutiveFailures: 0, disabledAt: null }
+                            : { disabledAt: now() }),
+                    }
+                    : {}),
+                updatedAt: now(),
+            })
+                .where(eq(webhookEndpoints.id, endpointId))
+                .returning();
+            return updated;
+        },
+        async rotateSecret(context, endpointId) {
+            await requireOwnEndpoint(context, endpointId);
+            const secret = generateWebhookSecret();
+            const [updated] = await deps.db
+                .update(webhookEndpoints)
+                .set({ secret, updatedAt: now() })
+                .where(eq(webhookEndpoints.id, endpointId))
+                .returning();
+            return { endpoint: updated, secret };
+        },
+        async remove(context, endpointId) {
+            await requireOwnEndpoint(context, endpointId);
+            // Deliveries cascade; a removed endpoint has no history worth retrying.
+            await deps.db.delete(webhookEndpoints).where(eq(webhookEndpoints.id, endpointId));
+        },
+    };
+    return {
+        endpoints,
+        async dispatch(event, tx) {
+            if (event.workspaceId === null) {
+                /**
+                 * Outgoing webhooks are a tenant feature. A platform-wide event has no
+                 * workspace whose endpoints should receive it, and picking one would leak
+                 * across tenants.
+                 */
+                return [];
+            }
+            const db = tx ?? deps.db;
+            const subscribed = await db
+                .select()
+                .from(webhookEndpoints)
+                .where(and(eq(webhookEndpoints.workspaceId, event.workspaceId), eq(webhookEndpoints.isActive, true), 
+            // Empty `event_types` means "everything".
+            or(sql `cardinality(${webhookEndpoints.eventTypes}) = 0`, sql `${event.type} = any(${webhookEndpoints.eventTypes})`)));
+            if (subscribed.length === 0) {
+                return [];
+            }
+            const payload = {
+                id: event.id,
+                type: event.type,
+                workspaceId: event.workspaceId,
+                occurredAt: event.occurredAt.toISOString(),
+                data: event.data,
+            };
+            /**
+             * `onConflictDoNothing` on (endpoint, event) is the idempotency guarantee:
+             * dispatching the same event twice — a retried job, a replayed event —
+             * cannot produce a second delivery.
+             */
+            return db
+                .insert(webhookDeliveries)
+                .values(subscribed.map((endpoint) => ({
+                endpointId: endpoint.id,
+                eventId: event.id,
+                eventType: event.type,
+                payload: payload,
+                status: "pending",
+                nextAttemptAt: now(),
+            })))
+                .onConflictDoNothing({
+                target: [webhookDeliveries.endpointId, webhookDeliveries.eventId],
+            })
+                .returning();
+        },
+        async claimDue(options = {}) {
+            const at = now();
+            return deps.db
+                .select()
+                .from(webhookDeliveries)
+                .where(and(inArray(webhookDeliveries.status, ["pending", "failed"]), lte(webhookDeliveries.nextAttemptAt, at)))
+                .orderBy(asc(webhookDeliveries.nextAttemptAt))
+                .limit(Math.min(options.limit ?? DEFAULT_CLAIM_LIMIT, MAX_CLAIM_LIMIT));
+        },
+        async attempt(delivery) {
+            const endpointRows = await deps.db
+                .select()
+                .from(webhookEndpoints)
+                .where(eq(webhookEndpoints.id, delivery.endpointId))
+                .limit(1);
+            const endpoint = endpointRows[0];
+            if (endpoint === undefined) {
+                throw new NotFoundError("Webhook endpoint not found.");
+            }
+            const at = now();
+            const body = JSON.stringify(delivery.payload);
+            const signature = signWebhookPayload({
+                rawBody: body,
+                secret: endpoint.secret,
+                timestampMs: at.getTime(),
+            });
+            let result;
+            try {
+                result = await deps.sender.send({
+                    url: endpoint.url,
+                    body,
+                    headers: {
+                        "Content-Type": "application/json",
+                        [SIGNATURE_HEADER]: signature,
+                        [TIMESTAMP_HEADER]: String(at.getTime()),
+                        "X-Saas-Core-Event-Id": delivery.eventId,
+                        "X-Saas-Core-Event-Type": delivery.eventType,
+                        "X-Saas-Core-Delivery-Id": delivery.id,
+                        "X-Saas-Core-Attempt": String(delivery.attemptCount + 1),
+                    },
+                });
+            }
+            catch (error) {
+                // A sender that throws is a failed attempt, not a crashed worker.
+                result = {
+                    delivered: false,
+                    error: truncate(error instanceof Error ? error.message : "Unknown error"),
+                };
+            }
+            const attemptCount = delivery.attemptCount + 1;
+            if (result.delivered) {
+                await deps.db.transaction(async (tx) => {
+                    await tx
+                        .update(webhookDeliveries)
+                        .set({
+                        status: "succeeded",
+                        attemptCount,
+                        lastAttemptedAt: at,
+                        nextAttemptAt: null,
+                        responseStatus: result.responseStatus ?? null,
+                        error: null,
+                        updatedAt: at,
+                    })
+                        .where(eq(webhookDeliveries.id, delivery.id));
+                    // Any success clears the failure streak.
+                    await tx
+                        .update(webhookEndpoints)
+                        .set({ consecutiveFailures: 0, updatedAt: at })
+                        .where(eq(webhookEndpoints.id, endpoint.id));
+                });
+                return result;
+            }
+            const exhausted = attemptCount >= maxAttempts;
+            await deps.db.transaction(async (tx) => {
+                await tx
+                    .update(webhookDeliveries)
+                    .set({
+                    status: exhausted ? "exhausted" : "failed",
+                    attemptCount,
+                    lastAttemptedAt: at,
+                    // Null once terminal, so an exhausted delivery is never re-claimed.
+                    nextAttemptAt: exhausted ? null : new Date(at.getTime() + retryDelayMs(attemptCount)),
+                    responseStatus: result.responseStatus ?? null,
+                    error: result.error ?? "Delivery failed.",
+                    updatedAt: at,
+                })
+                    .where(eq(webhookDeliveries.id, delivery.id));
+                const failures = endpoint.consecutiveFailures + 1;
+                await tx
+                    .update(webhookEndpoints)
+                    .set({
+                    consecutiveFailures: failures,
+                    /**
+                     * An endpoint broken for a long time should stop consuming retry
+                     * budget. Disabling it is recoverable — an operator re-enables it,
+                     * which clears the streak.
+                     */
+                    ...(failures >= failureThreshold
+                        ? { isActive: false, disabledAt: at }
+                        : {}),
+                    updatedAt: at,
+                })
+                    .where(eq(webhookEndpoints.id, endpoint.id));
+            });
+            return result;
+        },
+        async listDeliveries(context, options = {}) {
+            const own = await deps.db
+                .select({ id: webhookEndpoints.id })
+                .from(webhookEndpoints)
+                .where(eq(webhookEndpoints.workspaceId, context.workspaceId));
+            const endpointIds = own.map((row) => row.id);
+            if (endpointIds.length === 0) {
+                return [];
+            }
+            if (options.endpointId !== undefined && !endpointIds.includes(options.endpointId)) {
+                // Another tenant's endpoint id: return nothing rather than confirming it.
+                return [];
+            }
+            return deps.db
+                .select()
+                .from(webhookDeliveries)
+                .where(options.endpointId !== undefined
+                ? eq(webhookDeliveries.endpointId, options.endpointId)
+                : inArray(webhookDeliveries.endpointId, endpointIds))
+                .orderBy(sql `${webhookDeliveries.createdAt} desc`)
+                .limit(Math.min(options.limit ?? DEFAULT_CLAIM_LIMIT, MAX_CLAIM_LIMIT));
+        },
+    };
+}
+/** A {@link WebhookSender} over `fetch`, with a timeout. */
+export function createFetchWebhookSender(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    return {
+        async send({ url, body, headers }) {
+            // Without a timeout, one slow receiver holds a worker slot indefinitely.
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetchImpl(url, {
+                    method: "POST",
+                    headers,
+                    body,
+                    signal: controller.signal,
+                    // Never follow a redirect: it could land somewhere the URL check
+                    // rejected.
+                    redirect: "manual",
+                });
+                return {
+                    delivered: response.status >= 200 && response.status < 300,
+                    responseStatus: response.status,
+                    ...(response.status >= 300
+                        ? { error: `Receiver responded with ${response.status}.` }
+                        : {}),
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+//# sourceMappingURL=outgoing.js.map

package/dist/webhooks/outgoing.js.map

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

package/dist/webhooks/signature.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Webhook signing, shared by both directions.
+ *
+ * The same scheme the core already *verifies* from Revolut: HMAC-SHA256 over
+ * `v1.{timestamp}.{body}`, presented as `v1=<hex>`. Using one scheme for outgoing
+ * signatures too means there is a single implementation to audit, and receivers
+ * can follow the same instructions Stripe and Revolut users already know.
+ */
+export declare const SIGNATURE_VERSION = "v1";
+export declare const SIGNATURE_HEADER = "x-saas-core-signature";
+export declare const TIMESTAMP_HEADER = "x-saas-core-timestamp";
+/** 256 bits, base64url. Long enough that brute force is not a concern. */
+export declare function generateWebhookSecret(): string;
+/** The exact string that gets signed. Both sides must agree on it byte for byte. */
+export declare function signingPayload(timestampMs: number, rawBody: string): string;
+export declare function signWebhookPayload(input: {
+    rawBody: string;
+    secret: string;
+    timestampMs: number;
+}): string;
+/**
+ * Verify a signature over a raw body.
+ *
+ * Must be given the body **exactly as received**. Parsing and re-serialising JSON
+ * changes key order and whitespace, which invalidates the signature — so a route
+ * handler has to read it as text before touching it.
+ *
+ * Accepts several comma-separated signatures, because that is how a sender
+ * presents both the old and new secret while rotating.
+ */
+export declare function verifyWebhookSignature(input: {
+    rawBody: string;
+    signature: string;
+    timestamp: string | number;
+    /** One secret, or several during rotation. */
+    secret: string | readonly string[];
+    toleranceSeconds?: number;
+    now?: () => number;
+}): boolean;
+//# sourceMappingURL=signature.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/webhooks/signature.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AACxD,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAKxD,0EAA0E;AAC1E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAMT;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,GAAG,OAAO,CA+CV"}

package/dist/webhooks/signature.js

@@ -0,0 +1,77 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Webhook signing, shared by both directions.
+ *
+ * The same scheme the core already *verifies* from Revolut: HMAC-SHA256 over
+ * `v1.{timestamp}.{body}`, presented as `v1=<hex>`. Using one scheme for outgoing
+ * signatures too means there is a single implementation to audit, and receivers
+ * can follow the same instructions Stripe and Revolut users already know.
+ */
+export const SIGNATURE_VERSION = "v1";
+export const SIGNATURE_HEADER = "x-saas-core-signature";
+export const TIMESTAMP_HEADER = "x-saas-core-timestamp";
+/** Default freshness window. A signature is valid forever without one. */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/** 256 bits, base64url. Long enough that brute force is not a concern. */
+export function generateWebhookSecret() {
+    return `whsec_${randomBytes(32).toString("base64url")}`;
+}
+/** The exact string that gets signed. Both sides must agree on it byte for byte. */
+export function signingPayload(timestampMs, rawBody) {
+    return `${SIGNATURE_VERSION}.${timestampMs}.${rawBody}`;
+}
+export function signWebhookPayload(input) {
+    const digest = createHmac("sha256", input.secret)
+        .update(signingPayload(input.timestampMs, input.rawBody))
+        .digest("hex");
+    return `${SIGNATURE_VERSION}=${digest}`;
+}
+/**
+ * Verify a signature over a raw body.
+ *
+ * Must be given the body **exactly as received**. Parsing and re-serialising JSON
+ * changes key order and whitespace, which invalidates the signature — so a route
+ * handler has to read it as text before touching it.
+ *
+ * Accepts several comma-separated signatures, because that is how a sender
+ * presents both the old and new secret while rotating.
+ */
+export function verifyWebhookSignature(input) {
+    const timestampMs = typeof input.timestamp === "number" ? input.timestamp : Number(input.timestamp);
+    if (!Number.isFinite(timestampMs)) {
+        return false;
+    }
+    const tolerance = (input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS) * 1000;
+    const at = (input.now ?? Date.now)();
+    /**
+     * Stale *and* future timestamps are rejected. A signature stays valid forever,
+     * so without a window a captured request could be replayed indefinitely — and a
+     * clock skewed forward would widen that window rather than narrow it.
+     */
+    if (Math.abs(at - timestampMs) > tolerance) {
+        return false;
+    }
+    const secrets = typeof input.secret === "string" ? [input.secret] : input.secret;
+    const presented = input.signature
+        .split(",")
+        .map((part) => part.trim())
+        .map((part) => (part.startsWith(`${SIGNATURE_VERSION}=`) ? part.slice(3) : part))
+        .filter((part) => part.length > 0);
+    if (presented.length === 0) {
+        return false;
+    }
+    return secrets.some((secret) => {
+        const expected = Buffer.from(createHmac("sha256", secret)
+            .update(signingPayload(timestampMs, input.rawBody))
+            .digest("hex"), "utf8");
+        return presented.some((candidate) => {
+            const candidateBuffer = Buffer.from(candidate, "utf8");
+            if (candidateBuffer.length !== expected.length) {
+                return false;
+            }
+            // Constant-time: a hex comparison leaks how many leading digits matched.
+            return timingSafeEqual(candidateBuffer, expected);
+        });
+    });
+}
+//# sourceMappingURL=signature.js.map

package/dist/webhooks/signature.js.map

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

package/dist/workspaces/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A caller's identity within one workspace, proven to correspond to a real
+ * membership.
+ *
+ * Every tenant-scoped operation takes one of these. The `membershipVerified`
+ * marker exists so that a `workspaceId` taken straight from a request body,
+ * query string or path parameter cannot be passed where a verified context is
+ * required — the type will not accept it. Obtain one from
+ * `workspaces.resolveContext()` or `workspaces.requireContext()`, which check
+ * `workspace_members` first.
+ *
+ * The marker is a convention, not a cryptographic guarantee: it is greppable and
+ * makes bypassing the check a deliberate, visible act rather than an oversight.
+ */
+export interface WorkspaceContext {
+    readonly userId: string;
+    readonly workspaceId: string;
+    /** @internal Set only by a verified membership lookup. Do not construct by hand. */
+    readonly membershipVerified: true;
+}
+/**
+ * Construct a verified context.
+ *
+ * Internal to the core. Callers outside it must go through
+ * `workspaces.resolveContext()`, which performs the membership check.
+ *
+ * @internal
+ */
+export declare function unsafeWorkspaceContext(userId: string, workspaceId: string): WorkspaceContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/workspaces/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/workspaces/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,EAAE,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAE5F"}

package/dist/workspaces/context.js

@@ -0,0 +1,12 @@
+/**
+ * Construct a verified context.
+ *
+ * Internal to the core. Callers outside it must go through
+ * `workspaces.resolveContext()`, which performs the membership check.
+ *
+ * @internal
+ */
+export function unsafeWorkspaceContext(userId, workspaceId) {
+    return { userId, workspaceId, membershipVerified: true };
+}
+//# sourceMappingURL=context.js.map

package/dist/workspaces/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/workspaces/context.ts"],"names":[],"mappings":"AAqBA;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,WAAmB;IACxE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC;AAC3D,CAAC"}

package/dist/workspaces/index.d.ts

@@ -0,0 +1,5 @@
+export { type WorkspaceContext } from "./context.ts";
+export { createWorkspacesService, DEFAULT_SYSTEM_ROLES, slugify, type AcceptInvitationInput, type CreateWorkspaceInput, type InvitationWithToken, type InviteMemberInput, type SystemRoleDefinition, type WorkspaceMemberSummary, type WorkspacesService, type WorkspacesServiceDeps, } from "./service.ts";
+/** Default service, bound to the configuration-driven database handle. */
+export declare const workspaces: import("./service.ts").WorkspacesService;
+//# sourceMappingURL=index.d.ts.map

package/dist/workspaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workspaces/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,OAAO,EACP,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,eAAO,MAAM,UAAU,0CAKrB,CAAC"}

package/dist/workspaces/index.js

@@ -0,0 +1,21 @@
+/**
+ * Public workspaces surface: `@digimuza/saas-core/workspaces`. Server-only.
+ *
+ * A workspace is the tenancy boundary. Every operation here takes a
+ * {@link WorkspaceContext}, which can only be produced by a verified membership
+ * lookup — so a `workspaceId` supplied by a client cannot reach a query without
+ * passing through `resolveContext()` first.
+ */
+import { getDatabase } from "../db/client.js";
+import { events as coreEventsService } from "../events/index.js";
+import { createWorkspacesService } from "./service.js";
+export {} from "./context.js";
+export { createWorkspacesService, DEFAULT_SYSTEM_ROLES, slugify, } from "./service.js";
+/** Default service, bound to the configuration-driven database handle. */
+export const workspaces = createWorkspacesService({
+    get db() {
+        return getDatabase();
+    },
+    events: coreEventsService,
+});
+//# sourceMappingURL=index.js.map

package/dist/workspaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workspaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,MAAM,IAAI,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAyB,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,OAAO,GASR,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,MAAM,CAAC,MAAM,UAAU,GAAG,uBAAuB,CAAC;IAChD,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,EAAE,iBAAiB;CAC1B,CAAC,CAAC"}