@digimuza/saas-core 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digimuza
+
+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

@@ -0,0 +1,234 @@
+# @digimuza/saas-core
+
+A reusable, strongly typed SaaS foundation. One npm package, subpath exports,
+PostgreSQL + Drizzle.
+
+It answers the questions every SaaS application has to answer — who is this user,
+what workspace are they in, what can they do, what have they paid for, what is
+happening, and how do we run the slow parts — so that individual products only
+contain product logic.
+
+Architecture rules and the full roadmap: [CLAUDE.md](./CLAUDE.md).
+
+Two layers of documentation, neither repeating the other:
+
+- **[`src/README.md`](./src/README.md)** — a short README beside each module's code:
+  what it is for, what you actually do with it, the gotchas. Start here.
+- **[`docs/`](./docs/README.md)** — the reference: every exported function, its
+  signature, and why it behaves the way it does.
+
+**Status: Phases 1–12 complete.**
+
+---
+
+## Bootstrap
+
+```bash
+npm install @digimuza/saas-core
+npx sc init
+# Project name (my-app):
+npx sc start
+```
+
+`sc init` creates a project-owned `docker-compose.yml` containing PostgreSQL.
+`sc start` launches it and waits until the database is ready.
+
+See [docs/cli.md](./docs/cli.md).
+
+## Install
+
+```bash
+npm install @digimuza/saas-core drizzle-orm zod
+npm install @trigger.dev/sdk        # only if you use background jobs
+npm install rxjs                    # only if you use reactive streams
+```
+
+`drizzle-orm`, `zod`, `@trigger.dev/sdk` and `rxjs` are **peer** dependencies. Your
+application references exported table objects, defines Trigger.dev tasks against
+the same SDK instance the core triggers through, and pipes the core's Observables
+with its own operators; two copies of any of them would not interoperate.
+
+Configuration comes from **Infisical**, not `.env` files:
+
+```bash
+infisical run -- npm run dev
+```
+
+---
+
+## Modules
+
+| Module | Import from | Guide |
+| --- | --- | --- |
+| Configuration | `/config`, `/config/client` | [docs/config.md](./docs/config.md) |
+| Database & schema | `/db`, `/db/schema` | [docs/db.md](./docs/db.md) |
+| Authentication | `/auth` | [docs/auth.md](./docs/auth.md) |
+| Users & profiles | `/users` | [docs/users.md](./docs/users.md) |
+| Workspaces & members | `/workspaces` | [docs/workspaces.md](./docs/workspaces.md) |
+| Roles & permissions | `/authorization` | [docs/authorization.md](./docs/authorization.md) |
+| Billing | `/billing` | [docs/billing.md](./docs/billing.md) |
+| Entitlements | `/entitlements` | [docs/entitlements.md](./docs/entitlements.md) |
+| Events | `/events` | [docs/events.md](./docs/events.md) |
+| Background jobs | `/jobs` | [docs/jobs.md](./docs/jobs.md) |
+| Realtime | `/realtime` | [docs/realtime.md](./docs/realtime.md) |
+| Streams (RxJS) | `/streams`, `/streams/client` | [docs/streams.md](./docs/streams.md) |
+| Email | `/email` | [docs/email.md](./docs/email.md) |
+| Notifications | `/notifications` | [docs/notifications.md](./docs/notifications.md) |
+| Audit | `/audit` | [docs/audit.md](./docs/audit.md) |
+| API keys | `/api-keys` | [docs/api-keys.md](./docs/api-keys.md) |
+| Webhooks | `/webhooks` | [docs/webhooks.md](./docs/webhooks.md) |
+| Feature flags | `/feature-flags` | [docs/feature-flags.md](./docs/feature-flags.md) |
+| Storage | `/storage` | [docs/storage.md](./docs/storage.md) |
+| Files | `/files` | [docs/files.md](./docs/files.md) |
+| Logger | `/logger` | [docs/logger.md](./docs/logger.md) |
+| CLI | `saas-core` binary | [docs/cli.md](./docs/cli.md) |
+| Publishing | release workflow | [docs/publishing.md](./docs/publishing.md) |
+| Errors | root or `/errors` | [docs/errors.md](./docs/errors.md) |
+
+Every phase in [CLAUDE.md](./CLAUDE.md) now has an implementation. Observability
+beyond the logger — tracing, metrics — is the remaining gap.
+
+---
+
+## The shape of a request
+
+```ts
+import { auth } from "@/lib/auth";
+import { workspaces } from "@digimuza/saas-core/workspaces";
+import { authorization } from "@digimuza/saas-core/authorization";
+import { entitlements } from "@digimuza/saas-core/entitlements";
+import { jobs } from "@digimuza/saas-core/jobs";
+
+// 1. Who is this?
+const user = await auth.requireUser();
+
+// 2. Which workspace — verified, not taken on trust from the URL.
+const context = await workspaces.requireContext({
+  userId: user.id,
+  workspaceId: params.workspaceId,
+});
+
+// 3. May they? 4. Has the workspace paid for it?
+await authorization.require(context, "projects.create");
+await entitlements.require(context, "ai_generation");
+
+// 5. Do the slow part durably.
+await jobs.trigger("generate-project", { name }, {
+  workspaceId: context.workspaceId,
+  actorId: user.id,
+});
+```
+
+Steps 3 and 4 are separate on purpose. Authorization asks whether the *user* is
+permitted; entitlements ask whether the *workspace* has paid. A client renders an
+access error for one and an upsell for the other.
+
+---
+
+## Design principles you will notice in the code
+
+**Tenant isolation is enforced by PostgreSQL, not by application code.**
+`workspace_member_roles` stores `workspace_id` beside `user_id` and `role_id` so
+two composite foreign keys share it — granting a member of workspace A a role from
+workspace B is rejected by the database, and switching `workspace_id` to satisfy
+one key breaks the other. Application code that forgets a check cannot bypass it.
+
+**A `workspaceId` from a request cannot reach a query.** Tenant-scoped operations
+take a `WorkspaceContext`, which only a verified membership lookup produces.
+
+**Non-members get 404, not 403.** A 403 confirms a workspace exists and enables
+tenant enumeration.
+
+**Provider details stay behind adapters.** WorkOS is confined to `/auth`, Revolut
+to one file in `/billing`, Trigger.dev to `/jobs`. Tests enforce each boundary, so
+application code never imports a vendor SDK — and swapping one means writing an
+adapter, not editing services.
+
+**Only the config module reads `process.env`.** Enforced by a test across the whole
+package.
+
+**Idempotency and state changes are one transaction.** Webhook ingestion claims an
+event with a unique-constraint insert rather than a check-then-act; domain events
+are written in the same transaction as the change they describe and dispatched only
+after it commits.
+
+**Limits fail closed.** An entitlement the plan does not mention is zero, never
+unlimited.
+
+**Realtime channels are verified server-side, and there is no wildcard.** A client
+names the channels it wants, so every name is parsed and then checked against
+membership. Browsers never touch `LISTEN`/`NOTIFY` — the server mediates.
+
+**The logger redacts by key and by value.** Credentials never reach a log line,
+whether they arrive under a suspicious field name or as a suspicious-looking value
+under an innocent one.
+
+**Object keys are validated before they are prefixed, not after.** A `../` in a
+storage key is a cross-tenant read with no database involved; the scoped API takes
+paths rather than keys so the tenant prefix cannot be bypassed.
+
+**Secrets are hashed and revealed once.** API keys and invitation tokens store
+only a digest; a database leak does not let an attacker use them. Comparisons are
+constant-time.
+
+**The audit trail is immutable in the database, not by convention.** A trigger
+rejects `UPDATE` and `DELETE` on `audit_logs`, so a migration or a stray `psql`
+session cannot quietly rewrite history.
+
+---
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run db:generate                    # after editing src/db/schema
+infisical run -- npm run db:migrate
+```
+
+Tests run against **real PostgreSQL** — `@electric-sql/pglite`, a devDependency —
+with the real migrations applied. The guarantees under test *are* database
+constraints (composite foreign keys, partial unique indexes, cascades), and a mock
+would happily accept the cross-tenant writes the schema exists to reject.
+
+---
+
+## Known gaps
+
+- **No live-service verification.** PGlite is real PostgreSQL, so the schema and
+  constraints are genuinely exercised — but postgres.js against a server has never
+  been run, and neither has any Revolut HTTP call or Trigger.dev enqueue.
+- **The publish workflow has never run on GitHub Actions.** Every gate was
+  executed locally, the YAML parses, and `npm publish --dry-run` succeeds — but no
+  Actions run and no real publish has happened, and `NPM_TOKEN` is not yet set.
+- **The CLI has never started a real container.** Template generation, Docker
+  preflight, compose argument construction and every error path are tested with an
+  injected runner, and the generated compose file passes `docker compose config` —
+  but no Docker daemon was available to bring the stack up end to end.
+- **Revolut's `createCustomer` and `createCheckout` are unverified** against live
+  credentials. Signature verification is implemented and unit-tested; the HTTP
+  calls are written to the documented endpoints and nothing more.
+- **Revolut has no hosted portal and no server-side subscription object,** so
+  `getPortal()` returns `{ url: undefined }` and cancellation is recorded locally.
+  See [docs/billing.md](./docs/billing.md#revoluts-capability-boundaries).
+- **Sending email is not transactional with the database.** A retried request can
+  send twice; `idempotencyKey` is the only defence, and a provider that ignores it
+  will deliver twice regardless.
+- **Resend's HTTP call is unverified** against live credentials, like Revolut's.
+- **Outgoing webhook URL checking is a first pass, not a complete SSRF defence.**
+  Loopback, RFC1918 and link-local hosts are refused, but DNS can still resolve a
+  public name to a private address at connect time; production should also route
+  egress through a proxy. See
+  [docs/webhooks.md](./docs/webhooks.md#url-safety).
+- **`entitlements.consume()` is not transactional** across its check and insert, so
+  concurrent callers can overshoot a quota by their in-flight quantity. Deliberate;
+  see [docs/entitlements.md](./docs/entitlements.md#it-is-not-transactional-on-purpose).
+- **Server-only enforcement is a runtime guard,** not build-time. The
+  `server-only` package cannot be used here because it breaks plain-Node consumers;
+  see [docs/config.md](./docs/config.md#why-not-the-server-only-package).
+- **The default realtime transport fans out to every server** (one PostgreSQL
+  notification channel, filtered per subscriber), and SSE holds a long-lived
+  request that serverless platforms will cut at their duration cap. Both are
+  documented trade-offs with a transport seam to replace;
+  see [docs/realtime.md](./docs/realtime.md#the-default-transport-postgresql-listennotify).

package/dist/api-keys/index.d.ts

@@ -0,0 +1,9 @@
+import { type ApiKeysService } from "./service.ts";
+export { DEFAULT_KEY_PREFIX, generateApiKey, hashApiKeySecret, maskApiKey, parseApiKey, secretMatchesHash, type GeneratedApiKey, type ParsedApiKey, } from "./keys.ts";
+export { createApiKeysService, unsafeContextFromPrincipal, type ApiKeyPrincipal, type ApiKeysService, type ApiKeysServiceDeps, type ApiKeySummary, type CreateApiKeyInput, type CreatedApiKey, } from "./service.ts";
+/**
+ * Default service, wired to membership verification — so `resolveContext` can
+ * refuse a key whose creator has left the workspace.
+ */
+export declare const apiKeys: ApiKeysService;
+//# sourceMappingURL=index.d.ts.map

package/dist/api-keys/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api-keys/index.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,cAKpB,CAAC"}

package/dist/api-keys/index.js

@@ -0,0 +1,37 @@
+/**
+ * Public API keys surface: `@digimuza/saas-core/api-keys`. Server-only.
+ *
+ * Workspace-scoped machine credentials. A key is not a user: it holds *scopes*,
+ * not roles, and authorization for a key is a scope check.
+ *
+ * ```ts
+ * import { apiKeys } from "@digimuza/saas-core/api-keys";
+ *
+ * const { key, token } = await apiKeys.create(context, {
+ *   name: "CI deploy",
+ *   scopes: ["projects.read", "projects.deploy"],
+ *   expiresAt: new Date(Date.now() + 90 * 86_400_000),
+ * });
+ * // `token` exists exactly once. Only its hash is stored.
+ *
+ * // On an incoming request:
+ * const principal = await apiKeys.validate(request.headers.get("authorization")!);
+ * apiKeys.requireScope(principal, "projects.deploy");
+ * ```
+ */
+import { getDatabase } from "../db/client.js";
+import { workspaces } from "../workspaces/index.js";
+import { createApiKeysService } from "./service.js";
+export { DEFAULT_KEY_PREFIX, generateApiKey, hashApiKeySecret, maskApiKey, parseApiKey, secretMatchesHash, } from "./keys.js";
+export { createApiKeysService, unsafeContextFromPrincipal, } from "./service.js";
+/**
+ * Default service, wired to membership verification — so `resolveContext` can
+ * refuse a key whose creator has left the workspace.
+ */
+export const apiKeys = createApiKeysService({
+    get db() {
+        return getDatabase();
+    },
+    workspaces,
+});
+//# sourceMappingURL=index.js.map

package/dist/api-keys/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api-keys/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAuB,MAAM,cAAc,CAAC;AAEzE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,iBAAiB,GAGlB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAO3B,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAmB,oBAAoB,CAAC;IAC1D,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,UAAU;CACX,CAAC,CAAC"}

package/dist/api-keys/keys.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Key format: `<prefix>_<keyId>_<secret>`.
+ *
+ * Three parts, each earning its place:
+ *
+ * - **prefix** identifies the key as ours at a glance, so a leaked string is
+ *   recognisable in a paste or a log and secret scanners can match on it.
+ * - **keyId** is stored in the clear and indexed, so validation is one lookup
+ *   rather than a scan over every hash.
+ * - **secret** is the only part that is hashed, and the only part never stored.
+ *
+ * Both random parts are **hex**, not base64url. base64url includes `_`, which
+ * would collide with the `_` delimiter and make the token ambiguous to split —
+ * a bug that only shows up for the fraction of keys whose random bytes happen to
+ * encode one. Hex costs a few extra characters and removes the failure mode.
+ */
+export declare const DEFAULT_KEY_PREFIX = "dgk";
+export interface ParsedApiKey {
+    readonly prefix: string;
+    readonly keyId: string;
+    readonly secret: string;
+}
+export interface GeneratedApiKey extends ParsedApiKey {
+    /** The full key. Shown once, never stored. */
+    readonly token: string;
+    readonly keyHash: string;
+}
+/**
+ * Hash the secret half of a key.
+ *
+ * SHA-256, not bcrypt or Argon2. Those exist to make *low-entropy* human
+ * passwords expensive to guess; the secret here is 256 bits of CSPRNG output, so
+ * there is no dictionary to attack. A slow KDF would add tens of milliseconds to
+ * every authenticated request and buy nothing.
+ */
+export declare function hashApiKeySecret(secret: string): string;
+export declare function generateApiKey(prefix?: string): GeneratedApiKey;
+/**
+ * Parse a presented key.
+ *
+ * Returns `undefined` rather than throwing, and never explains *why* — a caller
+ * presenting a malformed key learns only that it was rejected. Distinguishing
+ * "wrong shape" from "unknown key" from "revoked" would let an attacker probe.
+ */
+export declare function parseApiKey(token: string): ParsedApiKey | undefined;
+/**
+ * Compare a presented secret against a stored hash in constant time.
+ *
+ * A plain `===` on hex digests leaks, through timing, how many leading characters
+ * matched — which is enough to reconstruct a digest one character at a time.
+ */
+export declare function secretMatchesHash(secret: string, keyHash: string): boolean;
+/** The displayable form of a key: enough to recognise, not enough to use. */
+export declare function maskApiKey(prefix: string, keyId: string): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/api-keys/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/api-keys/keys.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAOxC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAA2B,GAAG,eAAe,CAiBnF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAuBnE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAS1E;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/api-keys/keys.js

@@ -0,0 +1,92 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { InvalidInputError } from "../errors.js";
+/**
+ * Key format: `<prefix>_<keyId>_<secret>`.
+ *
+ * Three parts, each earning its place:
+ *
+ * - **prefix** identifies the key as ours at a glance, so a leaked string is
+ *   recognisable in a paste or a log and secret scanners can match on it.
+ * - **keyId** is stored in the clear and indexed, so validation is one lookup
+ *   rather than a scan over every hash.
+ * - **secret** is the only part that is hashed, and the only part never stored.
+ *
+ * Both random parts are **hex**, not base64url. base64url includes `_`, which
+ * would collide with the `_` delimiter and make the token ambiguous to split —
+ * a bug that only shows up for the fraction of keys whose random bytes happen to
+ * encode one. Hex costs a few extra characters and removes the failure mode.
+ */
+export const DEFAULT_KEY_PREFIX = "dgk";
+/** 128 bits — enough to identify, and it is not a secret. */
+const KEY_ID_BYTES = 16;
+/** 256 bits. What makes a fast hash sufficient. */
+const SECRET_BYTES = 32;
+/**
+ * Hash the secret half of a key.
+ *
+ * SHA-256, not bcrypt or Argon2. Those exist to make *low-entropy* human
+ * passwords expensive to guess; the secret here is 256 bits of CSPRNG output, so
+ * there is no dictionary to attack. A slow KDF would add tens of milliseconds to
+ * every authenticated request and buy nothing.
+ */
+export function hashApiKeySecret(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}
+export function generateApiKey(prefix = DEFAULT_KEY_PREFIX) {
+    if (!/^[a-z][a-z0-9]{1,15}$/.test(prefix)) {
+        throw new InvalidInputError("An API key prefix must be 2-16 lowercase alphanumerics starting with a letter.");
+    }
+    const keyId = randomBytes(KEY_ID_BYTES).toString("hex");
+    const secret = randomBytes(SECRET_BYTES).toString("hex");
+    return {
+        prefix,
+        keyId,
+        secret,
+        token: `${prefix}_${keyId}_${secret}`,
+        keyHash: hashApiKeySecret(secret),
+    };
+}
+/**
+ * Parse a presented key.
+ *
+ * Returns `undefined` rather than throwing, and never explains *why* — a caller
+ * presenting a malformed key learns only that it was rejected. Distinguishing
+ * "wrong shape" from "unknown key" from "revoked" would let an attacker probe.
+ */
+export function parseApiKey(token) {
+    // Bounded before any work, so an oversized string costs nothing.
+    if (typeof token !== "string" || token.length < 16 || token.length > 256) {
+        return undefined;
+    }
+    const parts = token.split("_");
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const [prefix, keyId, secret] = parts;
+    // Exact hex lengths; anything else is not a key we issued.
+    if (!/^[a-z][a-z0-9]{1,15}$/.test(prefix) ||
+        !new RegExp(`^[0-9a-f]{${KEY_ID_BYTES * 2}}$`).test(keyId) ||
+        !new RegExp(`^[0-9a-f]{${SECRET_BYTES * 2}}$`).test(secret)) {
+        return undefined;
+    }
+    return { prefix, keyId, secret };
+}
+/**
+ * Compare a presented secret against a stored hash in constant time.
+ *
+ * A plain `===` on hex digests leaks, through timing, how many leading characters
+ * matched — which is enough to reconstruct a digest one character at a time.
+ */
+export function secretMatchesHash(secret, keyHash) {
+    const presented = Buffer.from(hashApiKeySecret(secret), "utf8");
+    const stored = Buffer.from(keyHash, "utf8");
+    if (presented.length !== stored.length) {
+        return false;
+    }
+    return timingSafeEqual(presented, stored);
+}
+/** The displayable form of a key: enough to recognise, not enough to use. */
+export function maskApiKey(prefix, keyId) {
+    return `${prefix}_${keyId.slice(0, 6)}…`;
+}
+//# sourceMappingURL=keys.js.map

package/dist/api-keys/keys.js.map

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

package/dist/api-keys/service.d.ts

@@ -0,0 +1,111 @@
+import type { CoreDatabase } from "../db/types.ts";
+import { type WorkspaceContext } from "../workspaces/context.ts";
+import type { WorkspacesService } from "../workspaces/service.ts";
+/**
+ * A validated key, as a principal.
+ *
+ * Note what is absent: there is no user. An API key is a workspace-scoped
+ * machine principal holding *scopes*, not a person holding roles. Authorization
+ * for a key is a scope check, which is why this is not a `WorkspaceContext`.
+ */
+export interface ApiKeyPrincipal {
+    readonly apiKeyId: string;
+    readonly keyId: string;
+    readonly workspaceId: string;
+    readonly name: string;
+    readonly scopes: readonly string[];
+    /** Who created it, if that user still exists. */
+    readonly createdByUserId: string | null;
+}
+/** A key as shown in a list: never the secret, and never the hash. */
+export interface ApiKeySummary {
+    readonly id: string;
+    readonly name: string;
+    /** `dgk_a1b2c3…` — enough to match a log line to a row. */
+    readonly masked: string;
+    readonly scopes: readonly string[];
+    readonly createdByUserId: string | null;
+    readonly createdAt: Date;
+    readonly lastUsedAt: Date | null;
+    readonly expiresAt: Date | null;
+    readonly revokedAt: Date | null;
+}
+export interface CreateApiKeyInput {
+    readonly name: string;
+    readonly scopes?: readonly string[];
+    /** Null or omitted for a key that never expires. */
+    readonly expiresAt?: Date | null;
+    /** Overrides the default `dgk`. 2-16 lowercase alphanumerics. */
+    readonly prefix?: string;
+}
+export interface CreatedApiKey {
+    readonly key: ApiKeySummary;
+    /**
+     * The full key, shown once.
+     *
+     * Only its hash is stored, so this is the one and only time it exists. Losing
+     * it means revoking and issuing a new one.
+     */
+    readonly token: string;
+}
+export interface ApiKeysService {
+    /** Issue a key for the caller's workspace. */
+    create(context: WorkspaceContext, input: CreateApiKeyInput): Promise<CreatedApiKey>;
+    /** The workspace's keys, newest first. Never includes secrets. */
+    list(context: WorkspaceContext, options?: {
+        includeRevoked?: boolean;
+    }): Promise<ApiKeySummary[]>;
+    /**
+     * Validate a presented key.
+     *
+     * @throws UnauthorizedError for anything invalid — unknown, malformed, revoked
+     * or expired all produce the same error, so a caller cannot probe.
+     */
+    validate(token: string): Promise<ApiKeyPrincipal>;
+    /** As {@link validate}, but returns undefined instead of throwing. */
+    tryValidate(token: string): Promise<ApiKeyPrincipal | undefined>;
+    /**
+     * Validate, then confirm the key's creator is *still* a member of the
+     * workspace, and return 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.
+     */
+    resolveContext(token: string): Promise<{
+        context: WorkspaceContext;
+        principal: ApiKeyPrincipal;
+    }>;
+    /** Revoke immediately. Idempotent. */
+    revoke(context: WorkspaceContext, apiKeyId: string): Promise<void>;
+    /** Assert a scope, or throw {@link ForbiddenError}. */
+    requireScope(principal: ApiKeyPrincipal, scope: string): void;
+    /** Whether the principal holds every listed scope. */
+    hasScopes(principal: ApiKeyPrincipal, scopes: readonly string[]): boolean;
+}
+export interface ApiKeysServiceDeps {
+    readonly db: CoreDatabase;
+    /** Used by {@link ApiKeysService.resolveContext} to re-check membership. */
+    readonly workspaces?: Pick<WorkspacesService, "resolveContext">;
+    readonly now?: () => Date;
+    /**
+     * How stale `last_used_at` may get before it is rewritten.
+     *
+     * Updating on every request would turn validation into a write. A minute is
+     * enough to answer "is this key still in use?".
+     */
+    readonly lastUsedThrottleMs?: number;
+}
+export declare function createApiKeysService(deps: ApiKeysServiceDeps): ApiKeysService;
+/**
+ * Build a context from a principal without re-checking membership.
+ *
+ * Internal escape hatch, exported because a machine-to-machine integration may
+ * legitimately have no user behind it at all — in which case there is no
+ * membership to verify and the key itself is the authority. Prefer
+ * `resolveContext`, which does verify.
+ *
+ * @internal
+ */
+export declare function unsafeContextFromPrincipal(principal: ApiKeyPrincipal): WorkspaceContext;
+//# sourceMappingURL=service.d.ts.map

package/dist/api-keys/service.d.ts.map

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