@digimuza/saas-core 0.0.2

package/docs/README.md

@@ -0,0 +1,71 @@
+# @digimuza/saas-core — module reference
+
+Per-module guides. Each covers what the module is for, every exported function
+with its signature, and the reasoning behind the design decisions that are not
+obvious from the types.
+
+The [root README](../README.md) is the architectural overview; start there if you
+have not read it. Each module also carries a shorter, task-oriented README beside
+its code — see [`src/README.md`](../src/README.md) for that index. The split is
+deliberate: the colocated README orients you, these guides are the reference, and
+neither repeats the other.
+
+## Modules
+
+| Module | Import from | Guide |
+| --- | --- | --- |
+| Configuration | `@digimuza/saas-core/config` | [config.md](./config.md) |
+| Database & schema | `@digimuza/saas-core/db`, `/db/schema` | [db.md](./db.md) |
+| Authentication | `@digimuza/saas-core/auth` | [auth.md](./auth.md) |
+| Users & profiles | `@digimuza/saas-core/users` | [users.md](./users.md) |
+| Workspaces & members | `@digimuza/saas-core/workspaces` | [workspaces.md](./workspaces.md) |
+| Roles & permissions | `@digimuza/saas-core/authorization` | [authorization.md](./authorization.md) |
+| Billing | `@digimuza/saas-core/billing` | [billing.md](./billing.md) |
+| Entitlements | `@digimuza/saas-core/entitlements` | [entitlements.md](./entitlements.md) |
+| Events | `@digimuza/saas-core/events` | [events.md](./events.md) |
+| Background jobs | `@digimuza/saas-core/jobs` | [jobs.md](./jobs.md) |
+| Realtime | `@digimuza/saas-core/realtime` | [realtime.md](./realtime.md) |
+| Streams (RxJS) | `@digimuza/saas-core/streams` | [streams.md](./streams.md) |
+| Email | `@digimuza/saas-core/email` | [email.md](./email.md) |
+| Notifications | `@digimuza/saas-core/notifications` | [notifications.md](./notifications.md) |
+| Audit | `@digimuza/saas-core/audit` | [audit.md](./audit.md) |
+| API keys | `@digimuza/saas-core/api-keys` | [api-keys.md](./api-keys.md) |
+| Webhooks | `@digimuza/saas-core/webhooks` | [webhooks.md](./webhooks.md) |
+| Feature flags | `@digimuza/saas-core/feature-flags` | [feature-flags.md](./feature-flags.md) |
+| Storage | `@digimuza/saas-core/storage` | [storage.md](./storage.md) |
+| Files | `@digimuza/saas-core/files` | [files.md](./files.md) |
+| Logger | `@digimuza/saas-core/logger` | [logger.md](./logger.md) |
+| CLI | the `saas-core` binary | [cli.md](./cli.md) |
+| Publishing | release workflow | [publishing.md](./publishing.md) |
+| Errors | `@digimuza/saas-core` or `/errors` | [errors.md](./errors.md) |
+
+## Two conventions that apply everywhere
+
+**Every module exports both a factory and a default instance.**
+`createWorkspacesService({ db, events })` builds one explicitly — use it in tests
+and when you need different dependencies. The default (`workspaces`) is wired to
+the configuration-driven database handle and the core event registry, and its
+dependencies resolve on *first use*, not at import. So importing a module never
+requires configuration you have not set up.
+
+**Tenant-scoped operations take a `WorkspaceContext`, never a raw id.**
+A context can only come from a verified membership lookup
+(`workspaces.requireContext`). Passing a `workspaceId` from a request body where a
+context is expected will not type-check. See
+[workspaces.md](./workspaces.md#workspacecontext).
+
+## Reading order for a new application
+
+1. [config.md](./config.md) — get configuration flowing from Infisical
+2. [db.md](./db.md) — run the core migrations, reference core tables from yours
+3. [auth.md](./auth.md) — sign-in, callback, session
+4. [workspaces.md](./workspaces.md) — tenancy, and how a request becomes a context
+5. [authorization.md](./authorization.md) — register permissions, gate actions
+6. [billing.md](./billing.md) + [entitlements.md](./entitlements.md) — charge, then gate on what was paid for
+7. [events.md](./events.md) — declare your own events
+8. [jobs.md](./jobs.md) — move slow work off the request
+9. [realtime.md](./realtime.md) — push what happened to the browser
+10. [streams.md](./streams.md) — react to it, in the server or the browser
+11. [notifications.md](./notifications.md) + [email.md](./email.md) — tell the user
+12. [audit.md](./audit.md) — keep an immutable record of what mattered
+13. [api-keys.md](./api-keys.md) + [webhooks.md](./webhooks.md) — let other systems in and out

package/docs/api-keys.md

@@ -0,0 +1,184 @@
+# API keys
+
+```ts
+import { apiKeys, generateApiKey, parseApiKey } from "@digimuza/saas-core/api-keys";
+```
+
+> Orientation and recipes: [`src/api-keys/README.md`](../src/api-keys/README.md).
+
+Workspace-scoped machine credentials. A key is **not a user**: it holds *scopes*,
+not roles, so authorization for a key is a scope check rather than a permission
+check.
+
+---
+
+## The key format
+
+```
+dgk_<32 hex>_<64 hex>
+ │        │        └── secret — 256 bits, SHA-256 hashed, never stored
+ │        └─────────── keyId  — 128 bits, stored plaintext and indexed
+ └──────────────────── prefix — identifies the key as ours
+```
+
+**Why the split.** Hashing the whole key would mean either scanning every row's
+hash on every request, or storing a searchable copy — the first is O(n) per API
+call, the second defeats the point of hashing. A plaintext, indexed `keyId` makes
+validation one lookup.
+
+**Why hex and not base64url.** base64url includes `_`, which collides with the `_`
+delimiter and makes the token ambiguous to split. That fails only for the fraction
+of keys whose random bytes happen to encode one — the worst kind of bug. A test
+generates 200 keys and asserts three parts every time.
+
+**Why SHA-256 and not bcrypt.** The secret is 256 bits of CSPRNG output, so there
+is no dictionary to attack. bcrypt and Argon2 exist to make *low-entropy human
+passwords* expensive to guess; applying one here would add tens of milliseconds to
+every authenticated request and buy nothing.
+
+---
+
+## `apiKeys.create(context, input)`
+
+```ts
+function create(context: WorkspaceContext, input: {
+  name: string;                     // max 120 chars
+  scopes?: readonly string[];       // deduplicated, max 64
+  expiresAt?: Date | null;          // null never expires
+  prefix?: string;                  // 2-16 lowercase alphanumerics
+}): Promise<{ key: ApiKeySummary; token: string }>
+```
+
+```ts
+const { key, token } = await apiKeys.create(context, {
+  name: "CI deploy",
+  scopes: ["projects.read", "projects.deploy"],
+});
+showOnce(token);
+```
+
+**`token` exists exactly once.** Only the hash of its secret half is stored, so
+there is no way to recover it. Losing it means revoking and issuing a new one.
+
+`ApiKeySummary` never contains a secret or a hash. `masked` is `dgk_a1b2c3…` —
+enough to match a log line to a row.
+
+## `apiKeys.validate(token)` / `tryValidate(token)`
+
+```ts
+function validate(token: string): Promise<ApiKeyPrincipal>
+function tryValidate(token: string): Promise<ApiKeyPrincipal | undefined>
+
+interface ApiKeyPrincipal {
+  apiKeyId: string;
+  keyId: string;
+  workspaceId: string;
+  name: string;
+  scopes: readonly string[];
+  createdByUserId: string | null;
+}
+```
+
+Note what is absent: there is no user. The workspace comes from the key's own row,
+never from the request.
+
+**Every failure produces the same error.** Malformed, unknown, revoked and expired
+all raise `UnauthorizedError("Invalid API key.")`, so a caller cannot probe. There
+is a test asserting all three yield one distinct message.
+
+Comparison is constant-time — a `===` on hex digests leaks, through timing, how
+many leading characters matched.
+
+### `last_used_at`
+
+Recorded after the key is known good, and only when the stored value is at least a
+minute stale. Updating on every request would turn validation into a write path;
+the update is also guarded so two concurrent requests do not both write.
+
+Configure with `lastUsedThrottleMs`.
+
+## `apiKeys.resolveContext(token)`
+
+```ts
+function resolveContext(token: string): Promise<{
+  context: WorkspaceContext;
+  principal: ApiKeyPrincipal;
+}>
+```
+
+Validates, then confirms the key's creator is **still a member** of the workspace,
+and returns a context usable with the rest of the core.
+
+The membership re-check is the point. Without it a key would keep working after the
+person who created it lost access — the classic way a machine credential outlives
+the authority it was granted under.
+
+```ts
+// After the creator is removed from the workspace:
+await apiKeys.validate(token);        // still fine — scopes still apply
+await apiKeys.resolveContext(token);  // UnauthorizedError
+```
+
+So a scope-only integration keeps working, and only the `WorkspaceContext` is
+refused. Re-issue the key under a current member.
+
+For a machine-to-machine integration with genuinely no user behind it, there is no
+membership to verify — `unsafeContextFromPrincipal(principal)` is the deliberate
+escape hatch, named so it cannot be used by accident.
+
+## `apiKeys.list(context, options?)`
+
+```ts
+function list(context: WorkspaceContext, options?: { includeRevoked?: boolean }):
+  Promise<ApiKeySummary[]>
+```
+
+Revoked keys are hidden by default.
+
+## `apiKeys.revoke(context, apiKeyId)`
+
+Immediate and idempotent. Scoped to the caller's workspace, so another tenant's key
+id raises `NotFoundError` rather than being revocable.
+
+## Scopes
+
+```ts
+function requireScope(principal: ApiKeyPrincipal, scope: string): void   // throws ForbiddenError
+function hasScopes(principal: ApiKeyPrincipal, scopes: readonly string[]): boolean
+```
+
+`ForbiddenError.permission` carries the missing scope.
+
+**Scopes are not permissions.** Permissions belong to users through roles; scopes
+belong to keys. See [authorization.md](./authorization.md) for the user side — and
+note that both may apply to a request, depending on how you authenticate it.
+
+---
+
+## Low-level helpers
+
+```ts
+generateApiKey(prefix?): GeneratedApiKey        // { token, prefix, keyId, secret, keyHash }
+parseApiKey(token): ParsedApiKey | undefined    // undefined, never an explanation
+hashApiKeySecret(secret): string
+secretMatchesHash(secret, keyHash): boolean     // constant-time
+maskApiKey(prefix, keyId): string
+```
+
+`parseApiKey` returns `undefined` rather than throwing, and never says why —
+distinguishing "wrong shape" from "unknown key" from "revoked" would let an
+attacker probe. It also bounds the input length before doing any work, so an
+oversized string costs nothing.
+
+---
+
+## Testing
+
+```ts
+createApiKeysService({
+  db,
+  workspaces,                    // omit and resolveContext throws an explanation
+  now: () => fixedClock,
+  lastUsedThrottleMs: 60_000,
+});
+```

package/docs/audit.md

@@ -0,0 +1,198 @@
+# Audit
+
+```ts
+import { audit, auditFromEvent, createAuditService } from "@digimuza/saas-core/audit";
+```
+
+> Orientation and recipes: [`src/audit/README.md`](../src/audit/README.md).
+
+A durable, immutable record of consequential actions — who did what, to what, when.
+For a human reading it after the fact.
+
+---
+
+## Audit is not events
+
+| | [events](./events.md) | audit |
+| --- | --- | --- |
+| Audience | the application | a person, later |
+| Volume | everything | consequential actions only |
+| Immutability | by convention | by **database trigger** |
+| Delivery | may fan out to handlers | synchronous write, never queued |
+
+Recording every event would bury what matters among the routine.
+
+---
+
+## `audit.log(input, tx?)`
+
+```ts
+function log(input: {
+  action: string;                       // "member.role.updated" — past tense, dotted
+  actorId?: string | null;              // null for the system
+  workspaceId?: string | null;          // null for platform-level
+  targetType?: string;
+  targetId?: string;
+  metadata?: Record<string, unknown>;
+  request?: { requestId?: string; ipAddress?: string; userAgent?: string };
+  occurredAt?: Date;
+}, tx?: CoreDatabase): Promise<AuditLogEntry>
+```
+
+Durable the moment it returns — written straight to PostgreSQL, never through
+realtime, an in-process handler, or a queue.
+
+```ts
+await audit.log({
+  action: "member.role.updated",
+  actorId: user.id,
+  workspaceId: context.workspaceId,
+  targetType: "user",
+  targetId: member.id,
+  metadata: { from: "member", to: "admin" },
+  request: { requestId, ipAddress, userAgent },
+});
+```
+
+Pass `tx` to make the entry and the change it describes commit together:
+
+```ts
+await db.transaction(async (tx) => {
+  await assignRole(tx, member.id, roleId);
+  await audit.log({ action: "member.role.updated", /* ... */ }, tx);
+});
+```
+
+Both directions are tested: the entry commits with the change, and rolls back with
+a failure.
+
+`action` is capped at 120 characters so one oversized string cannot make a page of
+the trail unreadable.
+
+## `audit.logMany(inputs, tx?)`
+
+```ts
+function logMany(inputs: readonly AuditEntryInput[], tx?: CoreDatabase): Promise<AuditLogEntry[]>
+```
+
+One statement for several entries.
+
+## `audit.list(context, options?)`
+
+```ts
+function list(context: WorkspaceContext, options?: {
+  actions?: readonly string[];
+  actorId?: string;
+  targetType?: string;
+  targetId?: string;
+  since?: Date;
+  before?: Date;    // keyset pagination
+  limit?: number;   // default 50, capped at 500
+}): Promise<AuditLogEntry[]>
+```
+
+Requires a verified `WorkspaceContext` — a trail is tenant data. Newest first,
+tie-broken on id so keyset pagination cannot loop on equal timestamps.
+
+## `audit.listPlatform(options?)`
+
+Entries with no workspace: account-level actions, and anything belonging to a
+workspace that has since been deleted.
+
+**Not tenant-scoped.** Gate it on an operator-level permission of your own — the
+core cannot know who is allowed to read it.
+
+---
+
+## Immutability, enforced by PostgreSQL
+
+There is no update or delete API, and a trigger rejects both operations:
+
+```sql
+CREATE TRIGGER audit_logs_no_update
+  BEFORE UPDATE ON "audit_logs"
+  FOR EACH ROW EXECUTE FUNCTION saas_core_audit_logs_immutable();
+```
+
+So a migration, a data repair, or a stray `psql` session cannot quietly rewrite
+history either. Amending an entry means deliberately dropping the trigger — which
+is itself an auditable act.
+
+```ts
+await expectDatabaseError(
+  db.update(auditLogs).set({ action: "nothing.happened" }).where(eq(auditLogs.id, id)),
+  /append-only/,
+);
+```
+
+Both operations are tested against real PostgreSQL.
+
+---
+
+## Why `audit_logs` has no foreign keys
+
+`actor_user_id` and `workspace_id` are plain `uuid` columns. Two reasons, and they
+reinforce each other:
+
+1. **An entry must outlive what it describes.** `ON DELETE CASCADE` would erase the
+   trail exactly when it matters most. `SET NULL` would keep the row and destroy
+   its value.
+2. **`SET NULL` is an `UPDATE`,** which the immutability trigger rejects — so a
+   referencing audit row would make its own subject *undeletable*. That is a real
+   conflict, found by a test: deleting a user with audit entries failed outright.
+
+They are historical identifiers, not live references. Join explicitly when
+displaying a trail, and expect misses:
+
+```ts
+const rows = await db
+  .select({ entry: auditLogs, actor: userProfiles })
+  .from(auditLogs)
+  .leftJoin(userProfiles, eq(userProfiles.userId, auditLogs.actorUserId))
+  .where(eq(auditLogs.workspaceId, context.workspaceId));
+```
+
+There is deliberately no Drizzle `relations()` for `audit_logs` — declaring one
+would imply the actor is always resolvable.
+
+---
+
+## `auditFromEvent(event, mapping)`
+
+```ts
+function auditFromEvent(
+  event: SaasEvent,
+  mapping: Record<string, (event: never) => Omit<AuditEntryInput, "actorId" | "workspaceId">>,
+): AuditEntryInput | undefined
+```
+
+Translate selected events into audit entries. Returns `undefined` for anything
+unmapped, so the mapping is explicit about what is worth keeping.
+
+```ts
+events.onAny(async (event) => {
+  const entry = auditFromEvent(event, {
+    "workspace.member.removed": (e) => ({
+      action: "member.removed",
+      targetType: "user",
+      targetId: e.data.userId,
+    }),
+  });
+  if (entry !== undefined) await audit.log(entry);
+});
+```
+
+`actorId`, `workspaceId` and `occurredAt` come from the event.
+
+**But note the shape.** This writes audit from a *handler*, and a handler is not
+durable — a crash between the commit and the handler loses the entry. Convenient
+for the routine cases; for anything that must never be missed, call `audit.log` in
+the same transaction as the change.
+
+---
+
+## Custom construction
+
+```ts
+createAuditService({ db, now: () => fixedClock });
+```

package/docs/auth.md

@@ -0,0 +1,196 @@
+# Authentication
+
+```ts
+import {
+  createConfiguredAuthService,
+  createCookieStore,
+} from "@digimuza/saas-core/auth";
+```
+
+> Orientation and recipes: [`src/auth/README.md`](../src/auth/README.md).
+
+
+WorkOS owns identity — OAuth, SAML, OIDC, passkeys, MFA and session sealing. The
+core keeps its details behind a small API so application code never imports the
+WorkOS SDK; a test enforces that.
+
+---
+
+## Setup
+
+```ts
+// lib/auth.ts
+import { cookies } from "next/headers";
+import { createConfiguredAuthService, createCookieStore } from "@digimuza/saas-core/auth";
+
+export const auth = createConfiguredAuthService(createCookieStore(cookies));
+```
+
+Pass the accessor `cookies`, **not** `cookies()`. Next resolves the jar per
+request, so calling it once at module scope would bind every request to the first
+one.
+
+### Why you have to wire this yourself
+
+The core does not import `next/headers`. Next has no `exports` map, so that
+specifier only resolves through a bundler — importing it would make the package
+unloadable in plain Node, where migration scripts, Trigger.dev tasks and Vitest
+run. Three lines in your app keeps the core framework-agnostic.
+
+For any other runtime, implement `CookieStore` (three methods) or use
+`createMemoryCookieStore()`.
+
+---
+
+## `auth.getAuthorizationUrl(options?)`
+
+```ts
+function getAuthorizationUrl(options?: {
+  redirectUri?: string;
+  state?: string;
+  screenHint?: "sign-up" | "sign-in";
+  loginHint?: string;
+  organizationId?: string;
+  connectionId?: string;
+  invitationToken?: string;
+}): Promise<{ url: string; state: string }>
+```
+
+Builds the WorkOS AuthKit URL **and stores a single-use CSRF state cookie** —
+which is why it is async.
+
+```ts
+// app/login/route.ts
+const { url } = await auth.getAuthorizationUrl({ screenHint: "sign-in" });
+redirect(url);
+```
+
+`provider: "authkit"` is sent only when neither `organizationId` nor
+`connectionId` is given: WorkOS expects exactly one selector, and sending both
+conflicts with the more specific choice.
+
+## `auth.handleCallback(input)`
+
+```ts
+function handleCallback(input: { code: string; state?: string }): Promise<CallbackResult>
+```
+
+```ts
+// app/callback/route.ts
+const { session } = await auth.handleCallback({
+  code: searchParams.get("code")!,
+  state: searchParams.get("state")!,
+});
+```
+
+In order: verifies `state` against the cookie in constant time, consumes the
+cookie, exchanges the code, seals the session into an httpOnly cookie, and syncs
+the identity into `users` / `user_profiles`.
+
+**The state check is not optional ceremony.** Without it an attacker can feed a
+victim's browser a callback URL bearing the attacker's `code` and sign them into
+the attacker's account. The code is not exchanged unless the state matches —
+tested.
+
+Throws `UnauthorizedError` for a missing, unknown or mismatched state.
+
+## `auth.getSession()`
+
+```ts
+function getSession(): Promise<AuthSession | undefined>
+```
+
+```ts
+interface AuthSession {
+  userId: string;        // local id — key off this
+  workosUserId: string;  // identity-provider id
+  sessionId: string;
+  email: string;
+  organizationId?: string;
+  impersonatorEmail?: string;
+}
+```
+
+Reads the cookie, unseals, and validates. An expired access token is refreshed
+transparently — that is the normal case, not an error, since the sealed session
+carries a refresh token. Any other failure reason (tampered or absent cookie) is
+treated as unauthenticated, and no refresh is attempted.
+
+Also provisions the local user if this database has not seen the WorkOS identity
+before — true after a restore, or on the first sign-in following a deploy.
+
+### Refresh and Server Components
+
+Next.js Server Components cannot write cookies, and attempting it throws. The
+refresh already succeeded at WorkOS, so the request *is* authenticated — the write
+failure is tolerated and the session returned. If you want the rotated token to
+persist, refresh in middleware, where writing cookies is allowed.
+
+## `auth.requireSession()` / `auth.requireUser()`
+
+```ts
+function requireSession(): Promise<AuthSession>
+function requireUser(): Promise<UserWithProfile>
+```
+
+Throw `UnauthorizedError` when unauthenticated. Use these in route handlers and
+Server Actions; use the `get*` variants when unauthenticated is a valid state.
+
+## `auth.getCurrentUser()`
+
+```ts
+function getCurrentUser(): Promise<UserWithProfile | undefined>
+```
+
+The session's user, with their profile. See [users.md](./users.md).
+
+## `auth.signOut(options?)`
+
+```ts
+function signOut(options?: { returnTo?: string }): Promise<{ logoutUrl: string | undefined }>
+```
+
+```ts
+const { logoutUrl } = await auth.signOut();
+redirect(logoutUrl ?? "/");
+```
+
+Clears the cookie **before** contacting WorkOS, so a provider outage cannot leave
+a user signed in locally. You must redirect to `logoutUrl` — clearing the cookie
+alone leaves the WorkOS session alive, so the next sign-in would silently succeed
+without re-authenticating.
+
+Returns `undefined` when there was no session, or when the sealed session could
+not be read (nothing left to log out).
+
+---
+
+## Cookie attributes
+
+`httpOnly`, `Secure` outside development, `SameSite=Lax`, `path=/`, 30-day
+lifetime.
+
+`Lax` and not `Strict`: the identity provider returns the user via a top-level GET
+navigation, and `Strict` would withhold the cookie on that request and break every
+sign-in. `Secure` follows `APP_ENV` — requiring it in local development over plain
+HTTP would also break sign-in.
+
+---
+
+## Custom construction
+
+```ts
+import { createAuthService } from "@digimuza/saas-core/auth";
+
+const auth = createAuthService({
+  workos, cookies, users,
+  clientId, cookiePassword, redirectUri,
+  secureCookies: true,
+  sessionCookieName: "my_session",   // default "dg_session"
+  stateCookieName: "my_state",       // default "dg_oauth_state"
+  sessionMaxAgeSeconds: 60 * 60 * 24 * 7,
+});
+```
+
+`getWorkos()` returns the configured, `globalThis`-cached WorkOS client if you need
+a capability the core does not wrap.