@digimuza/saas-core 0.0.2

package/docs/realtime.md

@@ -0,0 +1,360 @@
+# Realtime
+
+```ts
+import { realtime, createEventStream, workspaceChannel } from "@digimuza/saas-core/realtime";
+```
+
+> Orientation and recipes: [`src/realtime/README.md`](../src/realtime/README.md).
+
+
+Realtime **delivers** events to connected clients. It is not the source of truth —
+the durable record is the `events` table, and a client that missed a message
+re-reads from it:
+
+```
+PostgreSQL  →  application events  →  realtime transport  →  browser
+```
+
+That ordering is the whole design, and it is why a failed delivery never fails the
+operation that published it.
+
+---
+
+## Wiring
+
+```ts
+// once at startup
+import { events } from "@digimuza/saas-core/events";
+import { realtime } from "@digimuza/saas-core/realtime";
+
+realtime.attach(events);
+```
+
+`attach` uses the events service's existing `onAny` hook, so realtime is an
+optional *consumer* of events and never a dependency of publishing. It returns an
+unsubscribe function.
+
+## Serving a stream
+
+```ts
+// app/api/realtime/route.ts
+import { createEventStream } from "@digimuza/saas-core/realtime";
+import { realtime } from "@digimuza/saas-core/realtime";
+import { auth } from "@/lib/auth";
+
+export async function GET(request: Request) {
+  const user = await auth.requireUser();
+
+  const stream = await createEventStream(realtime, {
+    userId: user.id,                                       // from the session
+    channels: new URL(request.url).searchParams.getAll("channel"),  // untrusted
+    signal: request.signal,
+  });
+
+  return new Response(stream.body, { headers: stream.headers });
+}
+```
+
+## Consuming it
+
+```ts
+const source = new EventSource(
+  `/api/realtime?channel=workspace:${workspaceId}`,
+);
+
+source.addEventListener("project.created", (message) => {
+  const { eventId, data, truncated } = JSON.parse(message.data);
+  if (truncated) {
+    // Payload was too large for the transport; re-read it by id.
+    return refetchEvent(eventId);
+  }
+  applyUpdate(data);
+});
+```
+
+---
+
+## Channels
+
+Two kinds, both scoped to something the server can verify:
+
+| Channel | Granted when |
+| --- | --- |
+| `workspace:<uuid>` | the caller is a member of that workspace |
+| `user:<uuid>` | the uuid is the caller's own id |
+
+**There is no global channel and no wildcard.** A client that could subscribe to
+`*` would receive every tenant's traffic, and no amount of downstream filtering
+makes that safe.
+
+```ts
+workspaceChannel(workspaceId);   // "workspace:<uuid>"
+userChannel(userId);             // "user:<uuid>"
+parseChannel(value);             // Channel | undefined
+requireChannel(value);           // throws InvalidInputError
+```
+
+### Channel names are untrusted input
+
+A client names the channels it wants, so every one is parsed before it is checked.
+`parseChannel` rejects wildcards, path traversal, wrong-case prefixes, surrounding
+whitespace, embedded newlines, the nil UUID, and anything longer than a
+well-formed channel. There are 21 tests on that function alone.
+
+It returns `undefined` rather than throwing: a subscriber sending a batch should
+have the bad ones denied, not the whole request rejected — a client on a stale
+deploy would otherwise be unable to connect at all.
+
+---
+
+## `realtime.authorizeChannels(input)`
+
+```ts
+function authorizeChannels(input: {
+  userId: string;                    // from the session
+  channels: readonly string[];       // from the client
+}): Promise<{ granted: readonly string[]; denied: readonly string[] }>
+```
+
+The **one** place channel access is decided. Transports do not filter — a test
+enforces that they cannot even reach `resolveContext` — so there is exactly one
+rule to audit.
+
+Workspace channels are checked against `workspace_members`; user channels against
+the session's own id. Revoking a membership stops granting immediately, which is
+tested.
+
+`denied` deliberately does not say *why*. "Not a member" and "no such workspace"
+are the same answer, or a client could enumerate tenants by probing channels.
+
+At most 32 channels per subscription, de-duplicated, so a client cannot multiply
+the membership lookups a single request triggers.
+
+## `realtime.subscribe(input)`
+
+```ts
+function subscribe(input: {
+  userId: string;
+  channels: readonly string[];
+  onMessage: (message: RealtimeMessage) => void;
+}): Promise<RealtimeSubscription & { granted: readonly string[] }>
+```
+
+Authorizes, then subscribes. Returns a subscription even when nothing was granted —
+so a caller has one cleanup path — and in that case opens nothing against the
+transport at all.
+
+## `realtime.publish(event, options?)`
+
+```ts
+function publish(event: SaasEvent, options?: { channels?: readonly string[] }): Promise<void>
+```
+
+Projects an event onto its channels. By default that is the workspace channel
+derived from `event.workspaceId`; pass `channels` to add more — a user channel for
+something addressed to one person, for instance.
+
+### What gets broadcast
+
+The default filter is **workspace-scoped events only**. Platform-wide events
+(`user.created`, with a null workspace) have no tenant channel to go to, and
+broadcasting them would mean choosing an audience the event does not describe.
+
+Narrow or widen it explicitly:
+
+```ts
+createRealtimeService({
+  transport, workspaces,
+  broadcast: (event) => event.type.startsWith("job."),
+});
+```
+
+Worth doing deliberately. Event payloads carry identifiers rather than snapshots
+(see [events.md](./events.md#payload-conventions)), so they are usually safe — but
+your own event types are yours to audit.
+
+---
+
+## `RealtimeMessage`
+
+```ts
+interface RealtimeMessage {
+  channel: string;
+  eventId: string;      // the events.id this projects
+  type: string;
+  occurredAt: string;   // ISO 8601
+  data?: unknown;       // absent when truncated
+  truncated?: boolean;
+}
+```
+
+`eventId` is what makes realtime recoverable: a client that missed or received a
+truncated message re-reads the event rather than guessing.
+
+---
+
+## The default transport: PostgreSQL LISTEN/NOTIFY
+
+Chosen because it adds **no infrastructure** — the database is already there, and
+the spec is explicit about preferring PostgreSQL where PostgreSQL is enough. No
+Redis, no broker, no extra service to operate.
+
+**Browsers never touch `LISTEN`/`NOTIFY`.** The server holds the listening
+connection and re-emits only what a given subscriber was granted. PostgreSQL is
+used *internally* as part of the pipeline, which is what the architecture allows.
+
+### Design details worth knowing
+
+**One PG channel, not one per workspace.** `LISTEN` is per-connection and
+per-name, so a channel-per-workspace design would mean thousands of `LISTEN`
+statements and constant `LISTEN`/`UNLISTEN` churn as clients come and go. Instead
+every server sees every message and filters to the channels it has authorized
+subscribers for.
+
+The trade-off is real: fan-out is O(servers), so at large scale every node decodes
+traffic it discards. That is the point at which to swap in a broker — which is why
+`RealtimeTransport` exists.
+
+**One database listener shared across all local subscribers.** A `LISTEN` per HTTP
+connection would exhaust the pool at a few hundred concurrent clients.
+
+**Oversized payloads are truncated, not dropped.** `pg_notify` rejects payloads
+over 8000 bytes. Rather than failing the notification, `data` is removed and
+`truncated: true` set, so the client still learns *that* something happened and can
+re-read it.
+
+**Notifications are validated, not cast.** The payload arrives through the
+database, so anything with `NOTIFY` privileges could have written it. A malformed
+or hostile notification is discarded rather than reaching subscribers as if it were
+a real event.
+
+**Delivery failures are swallowed and reported.** The event is already committed;
+a failed notification costs a client its live update, not the record — and must not
+fail the operation that published it.
+
+### Constructing it explicitly
+
+```ts
+import {
+  createPostgresTransport,
+  postgresJsNotifyClient,
+  PG_NOTIFY_CHANNEL,
+} from "@digimuza/saas-core/realtime";
+import { getDatabaseHandle } from "@digimuza/saas-core/db";
+
+const transport = createPostgresTransport({
+  client: postgresJsNotifyClient(getDatabaseHandle().client),
+  // Separate environments sharing one database, so a staging event cannot
+  // surface in a production browser.
+  notifyChannel: `${PG_NOTIFY_CHANNEL}_staging`,
+  onError: (error) => logger.error({ error }, "realtime transport"),
+});
+```
+
+`NotifyCapableClient` is a three-method interface (`listen`, `unlisten`, `notify`),
+so any driver that can do those works — the core's tests drive it with PGlite.
+
+`encodeMessage` and `decodeMessage` are exported too, if you are writing a
+transport that needs the same size-limit and validation behaviour.
+
+---
+
+## Server-sent events, not WebSockets
+
+`createEventStream` returns bytes plus headers, deliberately **not** a `Response`:
+
+```ts
+interface EventStream {
+  body: ReadableStream<Uint8Array>;
+  headers: Record<string, string>;
+  granted: readonly string[];
+  close(): Promise<void>;
+}
+```
+
+Returning a `Response` would tie the module to the fetch types and to one
+framework; a stream and a header map compose with anything, including plain
+`node:http`.
+
+SSE because it is one-directional — server to browser — which is exactly what
+event delivery needs. It reconnects automatically, survives proxies, and needs no
+protocol upgrade. If you need client-to-server messaging, that is an HTTP request,
+not a realtime concern.
+
+Details the implementation handles:
+
+- **`retry:` hint** on open, so the browser knows how long to wait before
+  reconnecting.
+- **An immediate `: connected` comment**, which flushes headers so the connection
+  opens now rather than on the first real event.
+- **Heartbeat comments every 25s** by default — under the 30-second idle timeout
+  most proxies and load balancers impose.
+- **`X-Accel-Buffering: no`**, without which nginx buffers the response and SSE
+  never arrives at all.
+- **Abort handling.** Pass `request.signal`; without it a dropped connection leaks
+  a subscription and a listener slot for the process's lifetime.
+- **Messages arriving during setup are buffered.** `subscribe` must run before the
+  stream is constructed (`granted` is part of the result), and anything delivered
+  in that window would otherwise be silently dropped.
+
+### Serverless caveat
+
+An SSE connection is a long-lived request. Platforms that cap function duration
+will cut it — on Vercel that is the function `maxDuration`. The browser reconnects
+automatically, so it degrades to polling at the cap rather than breaking, but a
+long-lived host (a container, a persistent Node process) is where this transport
+belongs.
+
+---
+
+## Replacing the transport
+
+```ts
+interface RealtimeTransport {
+  readonly name: string;
+  publish(messages: readonly RealtimeMessage[]): Promise<void>;
+  subscribe(
+    channels: readonly string[],
+    onMessage: (message: RealtimeMessage) => void,
+  ): Promise<RealtimeSubscription>;
+  close?(): Promise<void>;
+}
+```
+
+Two obligations:
+
+1. **Do not authorize.** `channels` is already authorized; deliver to nothing
+   outside the set. Access is decided in the service, and a transport that also
+   filtered would create a second place for the rule to drift.
+2. **Do not throw for an unknown channel.** Publishing is best-effort.
+
+```ts
+import { createRealtimeService, setDefaultRealtimeTransport } from "@digimuza/saas-core/realtime";
+
+// Either build your own service...
+const realtime = createRealtimeService({ transport: myTransport, workspaces });
+
+// ...or replace what the default export uses, before first use.
+setDefaultRealtimeTransport(myTransport);
+```
+
+`REALTIME_URL` and `REALTIME_API_KEY` exist in the `realtime` config section for
+exactly this — a deployment that outgrows LISTEN/NOTIFY and points at Centrifugo,
+Soketi or a hosted service. The PostgreSQL transport ignores them;
+`hasExternalRealtimeConfig()` reports whether they are set.
+
+---
+
+## Testing
+
+The core's own tests run the full pipeline against real PostgreSQL — PGlite
+supports `LISTEN`/`NOTIFY` — so cross-tenant isolation is verified through actual
+notification delivery, not a stand-in that would deliver anything asked of it.
+
+```ts
+const aliceSaw: RealtimeMessage[] = [];
+const bobSaw: RealtimeMessage[] = [];
+// ...subscribe both, publish to each workspace...
+expect(aliceSaw.map((m) => m.channel)).toEqual([workspaceChannel(acme.id)]);
+expect(bobSaw.map((m) => m.channel)).toEqual([workspaceChannel(globex.id)]);
+```

package/docs/storage.md

@@ -0,0 +1,279 @@
+# Storage
+
+```ts
+import { storage, createStorageService, createMemoryStorageProvider } from "@digimuza/saas-core/storage";
+```
+
+> Orientation and recipes: [`src/storage/README.md`](../src/storage/README.md).
+
+Object storage behind an adapter, with tenant scoping that cannot be bypassed.
+
+---
+
+## No database table
+
+An object is referenced by key from whichever product table owns it. A core `files`
+table would have to guess at metadata, ownership and lifecycle only the product
+knows — and the spec's core-owned table list does not include one. Storage adds no
+migration.
+
+---
+
+## `storage.forWorkspace(context)`
+
+```ts
+function forWorkspace(context: WorkspaceContext): ScopedStorage
+```
+
+The only way to address an object. Takes a verified
+[`WorkspaceContext`](./workspaces.md#workspacecontext), and the returned API takes
+**paths** rather than keys — so `workspaces/<id>/` is applied in exactly one place.
+
+```ts
+interface ScopedStorage {
+  readonly workspaceId: string;
+
+  keyFor(path: string): string;
+
+  upload(input: UploadInput): Promise<StoredObject>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+
+  getUrl(path: string, options?: UrlOptions): Promise<string>;
+  createUploadUrl(path: string, options?: UploadUrlOptions): Promise<string>;
+
+  urlForKey(key: string, options?: UrlOptions): Promise<string>;
+  deleteKey(key: string): Promise<void>;
+}
+```
+
+### `upload(input)`
+
+```ts
+await files.upload({
+  path: "avatars/me.png",
+  body,                          // Uint8Array | string
+  contentType: "image/png",
+  cacheControl: "public, max-age=31536000, immutable",
+  metadata: { uploadedBy: user.id },
+  maxBytes: 5 * 1024 * 1024,     // overrides the service default
+});
+```
+
+Size is checked **before** the provider call, so an oversized body is never sent,
+and measured in **bytes** rather than characters. Default limit 25 MB.
+
+Never put a secret in `metadata` — it is stored alongside the object and returned
+by a `HEAD`.
+
+### `keyFor(path)` / `urlForKey(key)` / `deleteKey(key)`
+
+Store `keyFor(path)` in your own table, and pass it back through `urlForKey` or
+`deleteKey`. Both **re-assert ownership**:
+
+```ts
+await files.urlForKey(row.storageKey);   // InvalidInputError if not this workspace
+```
+
+That check matters because a key coming back out of your own database is untrusted
+input — it may have been written before a bug was fixed, or by a different tenant.
+The error deliberately does not distinguish "wrong tenant" from "not a scoped key".
+
+---
+
+## Object keys are the attack surface
+
+A caller who can put `../` in a key reads out of its own prefix and into another
+tenant's: a cross-tenant read with no database involved and nothing in an audit
+log.
+
+So keys are validated **before** being concatenated with a prefix, and validation
+**rejects rather than sanitises** — silently rewriting `../secret` to `secret` would
+store the object somewhere the caller did not ask for.
+
+| Rejected | Why |
+| --- | --- |
+| `..`, `.` segments | Traversal out of the tenant prefix |
+| Leading `/` | Absolute key defeats prefixing entirely |
+| `\` | A separator on some receivers, data on others |
+| Control chars, incl. NUL | A NUL can truncate a key in a C-based backend, so `a<NUL>../b` may be stored as `a` — traversal past a naive check |
+| `a//b`, trailing `/` | Empty segment |
+| ` a.png`, `a.png ` | Legal in S3, invisible in every UI |
+| over 1024 bytes | S3's key limit |
+
+```ts
+workspaceObjectKey(workspaceId, path): string      // validates both, then prefixes
+parseWorkspaceObjectKey(key): { workspaceId, path } | undefined
+assertKeyBelongsTo(workspaceId, key): void
+assertObjectPath(path): void                        // throws with a reason
+isValidObjectPath(path): boolean
+```
+
+`workspaceObjectKey` validates the **workspace id as a UUID** too — it is the only
+thing separating one tenant's objects from another's, and a malformed one could
+create a colliding prefix.
+
+---
+
+## URLs
+
+### `getUrl(path, options?)`
+
+```ts
+interface UrlOptions {
+  expiresInSeconds?: number;    // default 900, max 604800 (7 days)
+  downloadFilename?: string;
+}
+```
+
+Returns the **public URL** when the store has one (`STORAGE_PUBLIC_URL`), otherwise
+a time-limited signed URL. Only a deployment with a public CDN origin can answer
+that; a private bucket is the correct default for user uploads.
+
+**Pass `downloadFilename` for anything a user uploaded.** It forces
+`Content-Disposition: attachment`, which stops a browser rendering an uploaded HTML
+or SVG file in your origin — that is stored XSS.
+
+Requesting it also forces a *signed* URL even when a public one exists, because
+handing back a bare CDN link would silently drop the protection the caller asked
+for.
+
+Quotes and backslashes are stripped from the filename, so it cannot break out of
+the header value.
+
+### `createUploadUrl(path, options?)`
+
+```ts
+const url = await files.createUploadUrl("imports/data.csv", {
+  contentType: "text/csv",
+  expiresInSeconds: 600,
+});
+```
+
+A URL the browser can `PUT` to directly. The reason the interface has this shape:
+proxying uploads through the application means a request that holds a server for
+the whole transfer, and a body limit on every platform in the path.
+
+`contentType` is **signed into the URL**, so the client must send exactly that type
+or be rejected. Without it, a client uploads anything and declares it anything.
+
+### The 7-day cap
+
+`MAX_SIGNED_URL_SECONDS` is S3's own hard limit for a SigV4 presigned URL — beyond
+it the signature is invalid. The service throws rather than clamping, because
+clamping would hand back a URL that expires sooner than the caller was told.
+
+---
+
+## Providers
+
+```ts
+interface StorageProvider {
+  readonly name: string;
+  put(input: PutObjectInput): Promise<StoredObject>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  publicUrl(key: string): string | undefined;
+  signedDownloadUrl(input: SignedDownloadInput): Promise<string>;
+  signedUploadUrl(input: SignedUploadInput): Promise<string>;
+}
+```
+
+Implementations do **no** key validation or tenant scoping. Both happen once, in
+the service; a provider that also checked would give the rule two homes and one
+would drift.
+
+| Provider | Use |
+| --- | --- |
+| `createS3Provider(options)` | AWS S3, Cloudflare R2, MinIO, Backblaze, Supabase |
+| `createMemoryStorageProvider(options?)` | Tests, and a local loop with no credentials |
+
+`createConfiguredStorageProvider()` builds the S3 one from the `storage` config
+section. The default `storage` export uses it, resolving configuration on first use.
+
+### Path style vs virtual-hosted
+
+`forcePathStyle` defaults to **true when an endpoint is given**, false for AWS.
+MinIO and most self-hosted stores cannot do wildcard subdomains, so
+`https://minio.internal:9000/my-bucket/key` is required rather than
+`https://my-bucket.minio.internal:9000/key`.
+
+### Errors never include the response body
+
+S3 error documents echo the key and can echo request parameters, and the message
+may reach a log.
+
+A `404` on delete is treated as success — deleting something already gone is not an
+error. A `403` on `HEAD` is treated as "not found", because that is what S3 returns
+for a missing key on a bucket without `ListBucket`.
+
+---
+
+## SigV4, implemented rather than imported
+
+```ts
+presign(input: PresignInput): PresignResult
+signingKey(input): Buffer
+uriEncode(value): string
+encodeObjectPath(key): string
+```
+
+**Verified against AWS's published worked example** — the test asserts both the
+signature `aeeed9bb…` and the exact canonical request. So unlike the Revolut and
+Resend adapters, this signing is known correct rather than plausible.
+
+Why not `@aws-sdk/client-s3` plus the presigner: it is a large dependency tree for
+a package many applications install, and a deployment on R2 or MinIO has no reason
+to carry the AWS SDK. SigV4 is fully specified, which is precisely what makes
+implementing it defensible — there are vectors to check against.
+
+`PresignResult` exposes `canonicalRequest` and `stringToSign`, which is what makes
+a signature mismatch debuggable rather than a shrug.
+
+### `objectDigest(body)`
+
+```ts
+function objectDigest(body: ObjectBody): string   // sha256 hex
+```
+
+Content hash, for naming an object by its bytes — which gives you deduplication and
+immutable caching for free:
+
+```ts
+const digest = objectDigest(body);
+await files.upload({
+  path: `uploads/${digest}${extension}`,
+  body,
+  cacheControl: "public, max-age=31536000, immutable",
+});
+```
+
+Re-uploading identical bytes then overwrites the same key rather than growing the
+bucket, and the URL can be cached forever because the content cannot change.
+
+Details that are easy to get wrong and are covered:
+
+- `uriEncode` escapes `!'()*`, which `encodeURIComponent` leaves alone.
+- `encodeObjectPath` preserves `/` — separators in a key, not data.
+- The canonical query string is encoded **then** sorted. Sorting first gives a
+  different order for some inputs and the signature will not match.
+- The signing key is four chained HMACs, each narrowing scope, so a leaked one is
+  good for one date, region and service rather than the account.
+
+---
+
+## Testing
+
+```ts
+const provider = createMemoryStorageProvider();
+const storage = createStorageService({ provider });
+
+await storage.forWorkspace(context).upload({ path: "a.png", body: "bytes" });
+
+expect(provider.keysUnder("workspaces/")).toEqual([`workspaces/${context.workspaceId}/a.png`]);
+expect(provider.text(`workspaces/${context.workspaceId}/a.png`)).toBe("bytes");
+```
+
+`keysUnder` exists specifically for asserting tenant scoping. Signed URLs from the
+memory provider are **synthesised** — they carry an expiry and a signature-shaped
+token so a test can assert on them, but nothing verifies them. It is not a store.