@digimuza/saas-core 0.0.2

package/docs/authorization.md

@@ -0,0 +1,225 @@
+# Roles, permissions & authorization
+
+```ts
+import { authorization, definePermissions } from "@digimuza/saas-core/authorization";
+```
+
+> Orientation and recipes: [`src/authorization/README.md`](../src/authorization/README.md).
+
+
+Authorization always requires workspace context. A user's effective permissions are
+the **union** of the permissions carried by every role they hold in that workspace.
+
+Permissions are application-defined; the core stores the vocabulary you register
+rather than shipping its own.
+
+---
+
+## Setup
+
+```ts
+// lib/permissions.ts
+import { definePermissions } from "@digimuza/saas-core/authorization";
+
+export const PERMISSIONS = definePermissions([
+  "projects.read",
+  "projects.create",
+  "projects.delete",
+  "members.invite",
+  "billing.read",
+] as const);
+
+export type AppPermission = (typeof PERMISSIONS)[number];
+```
+
+```ts
+// once at startup, or from a migration step
+await authorization.registerPermissions(PERMISSIONS.map((key) => ({ key })));
+```
+
+### `definePermissions(keys)`
+
+```ts
+function definePermissions<const T extends readonly string[]>(keys: T): T
+```
+
+Purely a typing helper — no I/O. The `const` type parameter preserves the literal
+keys so you get a union type and autocompletion.
+
+### `registerPermissions(definitions)`
+
+```ts
+function registerPermissions(definitions: readonly { key: string; description?: string }[]): Promise<void>
+```
+
+Idempotent, so it is safe on every boot. Permissions must exist before a role can
+be granted them.
+
+---
+
+## Checking
+
+### `authorization.can(context, permission)`
+
+```ts
+function can(context: WorkspaceContext, permission: string): Promise<boolean>
+```
+
+```ts
+if (await authorization.can(context, "projects.delete")) {
+  // show the delete button
+}
+```
+
+### `authorization.require(context, permission)`
+
+```ts
+function require(context: WorkspaceContext, permission: string): Promise<void>
+```
+
+Throws `ForbiddenError` with `.permission` set to the missing key.
+
+### `canAll` / `canAny`
+
+```ts
+function canAll(context: WorkspaceContext, required: readonly string[]): Promise<boolean>
+function canAny(context: WorkspaceContext, required: readonly string[]): Promise<boolean>
+```
+
+Empty lists are handled explicitly and differently: `canAll([])` is `true`
+(vacuously satisfied), `canAny([])` is `false` (nothing to satisfy). Both are
+tested so neither is accidental.
+
+### `authorization.getEffectivePermissions(context)`
+
+```ts
+function getEffectivePermissions(context: WorkspaceContext): Promise<Set<string>>
+```
+
+The union across all the user's roles, resolved in **one** query — a `SELECT
+DISTINCT` over member grants joined through roles to permissions. Holding more
+roles simply widens the set.
+
+Both halves of the join to `roles` are constrained by workspace, so a stale grant
+could not contribute another tenant's permissions.
+
+### `authorization.hasRole(context, roleKey)`
+
+```ts
+function hasRole(context: WorkspaceContext, roleKey: string): Promise<boolean>
+```
+
+**Prefer permissions.** Role checks couple application logic to the role structure,
+so restructuring roles silently changes behaviour. This exists for the rare check
+that genuinely is about role identity.
+
+Matches on `key`, the stable machine identifier, never on `name`, which is
+user-editable and localisable — renaming a role must not change who can do what.
+
+### `authorization.getRoles(context)`
+
+```ts
+function getRoles(context: WorkspaceContext): Promise<Role[]>
+```
+
+---
+
+## Role administration
+
+```ts
+authorization.roles.list(context): Promise<Role[]>
+
+authorization.roles.create(context, {
+  key: string;
+  name: string;
+  description?: string;
+  isDefault?: boolean;
+  permissions?: readonly string[];
+}): Promise<Role>
+
+authorization.roles.setPermissions(context, roleId, keys): Promise<void>
+authorization.roles.delete(context, roleId): Promise<void>
+authorization.roles.assign(context, { userId, roleId }): Promise<void>
+authorization.roles.unassign(context, { userId, roleId }): Promise<void>
+```
+
+- `setPermissions` **replaces** the set; pass `[]` to clear it.
+- `delete` throws `ForbiddenError` for system roles. Deleting `admin` would leave
+  nobody able to administer the workspace.
+- `assign` is idempotent and emits nothing when the role was already held —
+  re-announcing an unchanged grant would make event consumers act twice.
+- `unassign` throws `NotFoundError` if the user does not hold the role.
+- Every one of these verifies the role belongs to the caller's workspace first, so
+  a role id from another tenant cannot be probed or modified.
+
+---
+
+## Cross-workspace isolation is a database constraint
+
+`workspace_member_roles` stores `workspace_id` beside `user_id` and `role_id` so
+that two composite foreign keys can share it:
+
+```
+(workspace_id, user_id)  →  workspace_members(workspace_id, user_id)
+(role_id, workspace_id)  →  roles(id, workspace_id)
+```
+
+Both read the **same** `workspace_id` column, so granting a member of workspace A
+a role belonging to workspace B is rejected by PostgreSQL — not by application code
+that could be forgotten or bypassed. Switching `workspace_id` to satisfy one key
+breaks the other. There are tests for both directions, plus the bypass attempt.
+
+`workspace_invitations` carries the same guard on its optional `role_id`.
+
+When the constraint fires, `roles.assign` translates it to `NotFoundError` — a
+foreign-key violation is the database enforcing tenancy, not an unexpected fault.
+
+---
+
+## Roles table
+
+| Column | Notes |
+| --- | --- |
+| `key` | Stable machine identifier. Unique per workspace. |
+| `name` | Human label. Editable; never used in authorization logic. |
+| `is_system` | Created with the workspace; protected from deletion. |
+| `is_default` | Granted to new members. At most one per workspace. |
+
+`key` and the two flags are additions beyond the original spec's column list.
+`key` exists so authorization never depends on a renameable string; the flags
+implement the spec's "system roles, default roles, custom roles" requirement.
+
+---
+
+## `findRolesWithPermission(db, workspaceId, permission)`
+
+```ts
+function findRolesWithPermission(
+  db: CoreDatabase, workspaceId: string, permission: string,
+): Promise<Role[]>
+```
+
+"Which roles here can do X?" — for building a permissions matrix UI.
+
+---
+
+## Authorization vs entitlements
+
+They answer different questions and **both** must pass:
+
+```ts
+await authorization.require(context, "projects.create");  // may this user?
+await entitlements.require(context, "ai_generation");     // has this workspace paid?
+```
+
+See [entitlements.md](./entitlements.md).
+
+---
+
+## Custom construction
+
+```ts
+import { createAuthorizationService } from "@digimuza/saas-core/authorization";
+
+const authorization = createAuthorizationService({ db, events });   // events optional
+```

package/docs/billing.md

@@ -0,0 +1,293 @@
+# Billing
+
+```ts
+import { billing, InvalidWebhookSignatureError } from "@digimuza/saas-core/billing";
+```
+
+> Orientation and recipes: [`src/billing/README.md`](../src/billing/README.md).
+
+
+Everything above the `BillingProvider` interface is provider-independent, so
+adopting a second payment provider means writing an adapter — a test enforces that
+nothing outside the adapter mentions Revolut.
+
+The core does not implement payment processing.
+
+---
+
+## Plans
+
+### `billing.plans.upsert(input)`
+
+```ts
+function upsert(input: {
+  key: string;                 // stable internal identifier
+  name: string;
+  description?: string;
+  providerPriceId?: string;    // for providers with a price catalogue
+  amountCents?: number;        // minor units, to avoid floating-point money
+  currency?: string;           // ISO 4217, uppercased for you
+  interval?: "month" | "year" | "one_time";
+  isActive?: boolean;
+  sortOrder?: number;
+  entitlements?: readonly EntitlementDefinition[];
+}): Promise<Plan>
+```
+
+Idempotent — run it on every boot to sync the catalogue from code.
+
+```ts
+await billing.plans.upsert({
+  key: "pro",
+  name: "Pro",
+  amountCents: 2900,
+  entitlements: [
+    { key: "ai_generation",  kind: "feature" },
+    { key: "ai_generations", kind: "limit", limitValue: 100 },
+    { key: "team_members",   kind: "limit", limitValue: null },  // unlimited
+  ],
+});
+```
+
+Omit `entitlements` and the existing set is left alone; pass it and the set is
+**replaced**. A `limitValue` on a `feature` is discarded — storing one would make
+`getLimit()` on a feature look meaningful.
+
+Throws `InvalidInputError` for duplicate keys or a negative limit.
+
+### `billing.plans.list` / `getByKey` / `setEntitlements`
+
+```ts
+function list(options?: { includeInactive?: boolean }): Promise<Plan[]>
+function getByKey(key: string): Promise<Plan | undefined>
+function setEntitlements(planKey: string, definitions: readonly EntitlementDefinition[]): Promise<void>
+```
+
+`list()` hides inactive plans by default: `isActive: false` retires a plan from the
+pricing page while still honouring it for existing customers.
+
+Plans use `ON DELETE RESTRICT` from `subscriptions`. Deleting a plan customers are
+paying for would silently strip their entitlements — retire it instead. There is a
+test asserting the delete fails.
+
+---
+
+## Customers
+
+```ts
+function getCustomer(context: WorkspaceContext): Promise<BillingCustomer | undefined>
+function ensureCustomer(context: WorkspaceContext, options?: { email?: string }): Promise<BillingCustomer>
+```
+
+Billing is workspace-scoped: the tenant pays, and members come and go.
+
+`ensureCustomer` is safe to call concurrently — a race on the workspace constraint
+adopts the winner's row. It matches on
+`billing_customers_workspace_id_unique` specifically; a violation of
+`billing_customers_provider_customer_unique` means the provider handed back an id
+already bound to a *different* workspace, which is a genuine fault that must
+surface.
+
+---
+
+## Checkout
+
+```ts
+function createCheckout(context: WorkspaceContext, options: {
+  planKey: string;
+  successUrl: string;
+  cancelUrl: string;
+  quantity?: number;
+  metadata?: Record<string, string>;
+}): Promise<{ url: string; providerCheckoutId?: string }>
+```
+
+```ts
+const { url } = await billing.createCheckout(context, {
+  planKey: "pro",
+  successUrl: "https://app.example.com/billing/done",
+  cancelUrl: "https://app.example.com/billing",
+});
+redirect(url);
+```
+
+Creates the provider customer lazily if needed. Throws `NotFoundError` for an
+unknown plan, `ConflictError` for a retired one.
+
+**Do not grant access when the user returns to `successUrl`.** That redirect is
+attacker-controllable and proves nothing about payment. Access follows from the
+webhook.
+
+---
+
+## Webhooks are the only source of truth
+
+### `billing.webhooks.handle(request)`
+
+```ts
+function handle(request: {
+  rawBody: string;      // exactly as received, before any parsing
+  signature: string;
+  timestamp?: string;
+}): Promise<WebhookOutcome>
+
+type WebhookOutcome =
+  | { status: "processed"; eventId: string; type: string }
+  | { status: "duplicate"; type: string }
+  | { status: "ignored";   eventId: string; type: string };
+```
+
+```ts
+// app/api/billing/webhook/route.ts
+export async function POST(request: Request) {
+  const rawBody = await request.text();   // text, not json
+
+  try {
+    const outcome = await billing.webhooks.handle({
+      rawBody,
+      signature: request.headers.get("revolut-signature") ?? "",
+      timestamp: request.headers.get("revolut-request-timestamp") ?? undefined,
+    });
+    return Response.json(outcome);
+  } catch (error) {
+    if (error instanceof InvalidWebhookSignatureError) {
+      return new Response("invalid signature", { status: 401 });
+    }
+    throw error;   // 5xx makes the provider retry
+  }
+}
+```
+
+**Read the body as text.** Parsing and re-serialising JSON changes key order and
+whitespace, which invalidates the signature.
+
+Verification happens before the parser, and before anything touches the database.
+`InvalidWebhookSignatureError`'s message is deliberately uninformative — a caller
+who cannot produce a valid signature gets no hint about which part failed.
+
+### Idempotency is a database constraint
+
+`(provider, provider_event_id)` is unique and **the insert is the claim**. So
+at-least-once delivery and concurrent redeliveries are handled by PostgreSQL, not
+by a check-then-act two requests could pass together. There is a test firing three
+identical deliveries concurrently: one processes, two dedupe, one subscription row
+results.
+
+The claim is a conditional upsert with `setWhere: status = 'failed'`, so a retry
+re-claims an event whose previous attempt **failed** but never one already
+`processed` or currently `pending`. Genuine failures are replayable without
+risking a double application. The raw payload is retained so replay needs no help
+from the provider.
+
+### `processed` vs `ignored` vs `duplicate`
+
+`ignored` means verified and stored but not actionable — an unknown customer or an
+unresolvable plan. Routine when several environments share one provider account;
+conflating it with `failed` would bury real failures.
+
+### Tenancy comes from our own records
+
+The workspace is resolved from our `billing_customers` row, matched on the provider
+customer id — **never** from the webhook payload. So even a leaked signing secret
+could not redirect a subscription to another tenant.
+
+### Upgrades retire the previous subscription
+
+`subscriptions_one_live_per_workspace_idx` allows exactly one live subscription per
+workspace, which keeps "what plan is this workspace on?" unambiguous rather than
+row-order dependent. An upgrade arrives as a *new* subscription, so applying it
+cancels the old one.
+
+---
+
+## Subscription lifecycle
+
+```ts
+function getSubscription(context: WorkspaceContext): Promise<{ subscription: Subscription; plan: Plan } | undefined>
+function cancelSubscription(context: WorkspaceContext, options?: { atPeriodEnd?: boolean }): Promise<Subscription>
+function getPortal(context: WorkspaceContext, options: { returnUrl: string }): Promise<{ url: string | undefined }>
+```
+
+`cancelSubscription` defaults to `atPeriodEnd: true`, which keeps the subscription
+live — and therefore entitling — until the paid period expires. `false` ends
+entitlements immediately.
+
+**`getPortal` can return `undefined`.** Handle it; do not assume a URL.
+
+---
+
+## Revolut's capability boundaries
+
+Revolut Merchant is an order-and-payment API, not a subscription platform. It has
+no hosted customer portal and no server-side subscription object. So
+`cancelSubscription` and `getPortalUrl` are **optional** on `BillingProvider` and
+absent from the Revolut adapter rather than stubbed to silently do nothing:
+
+- `getPortal()` returns `{ url: undefined }` — build your own billing screen.
+- `cancelSubscription()` records the local state change, and calls the provider
+  only when the adapter supports it.
+
+Recurring charges on Revolut are merchant-initiated: the core owns subscription
+state and drives the charges.
+
+### Verification status
+
+Signature verification implements Revolut's documented scheme and is unit-tested:
+HMAC-SHA256 over `v1.{timestamp}.{body}`, a freshness window for replay protection
+(rejecting both stale timestamps and clocks skewed forward), constant-time
+comparison, and the comma-separated signatures sent during secret rotation.
+
+**The HTTP calls — `createCustomer` and `createCheckout` — have not been run
+against live Revolut credentials.** Treat them as unverified.
+
+```ts
+import { verifyRevolutSignature } from "@digimuza/saas-core/billing";
+
+// Exported separately, so a route handler can verify without constructing
+// API credentials it does not need.
+verifyRevolutSignature({ rawBody, signature, timestamp, secret });
+```
+
+---
+
+## Writing another provider
+
+```ts
+interface BillingProvider {
+  readonly name: string;
+  createCustomer(input): Promise<{ providerCustomerId: string }>;
+  createCheckout(input): Promise<{ url: string; providerCheckoutId?: string }>;
+  cancelSubscription?(input): Promise<void>;   // optional
+  getPortalUrl?(input): Promise<string>;       // optional
+  verifyWebhook(input): boolean;
+  parseWebhookEvent(rawBody: string): ProviderWebhookEvent;
+}
+```
+
+Two obligations the types cannot express:
+
+1. **Map the provider's statuses onto `SubscriptionStatus`.** Fail closed — an
+   unrecognised state must not become `active`, or you grant entitlements the
+   customer may not have.
+2. **Convert dates to `Date` instances.** Providers send ISO strings; passing one
+   through fails deep inside the database driver with an error naming neither the
+   field nor the adapter.
+
+Resolve the plan by `providerPriceId` if the provider has a price catalogue, or by
+`planKey` if the plan travels in a reference you set at checkout.
+
+```ts
+import { createBillingService } from "@digimuza/saas-core/billing";
+
+const billing = createBillingService({ db, provider: myProvider, events });
+```
+
+---
+
+## Diagnostics
+
+```ts
+import { countFailedBillingEvents } from "@digimuza/saas-core/billing";
+
+const backlog = await countFailedBillingEvents(db);   // awaiting replay
+```