@antasphere/chassis-server 1.0.0

package/src/identity/oauth-jwt.ts

@@ -0,0 +1,128 @@
+import { createLocalJWKSet, jwtVerify, type JWK, type JWTVerifyOptions } from 'jose';
+import { type Db } from '@antasphere/chassis-db';
+import type { Principal } from '@antasphere/chassis-contract';
+import { mcpResourceUrl, type Auth } from './better-auth.js';
+import { isWorkspaceSelector, resolveMembership, type OnWorkspaceMiss } from './resolve-membership.js';
+
+/**
+ * OAuth Bearer-JWT resolution — the third credential path in auth-context.
+ *
+ * Access tokens are RS256 JWTs this instance minted itself (Better Auth jwt +
+ * oauthProvider plugins), so verification is fully local: JWKS straight from
+ * the jwt plugin (DB-backed, no HTTP), hard issuer / audience / algorithm /
+ * expiry pinning. On top of the signature, every request re-resolves the
+ * workspace membership LIVE — deactivating a member cuts token access on
+ * their next request, not at token expiry. Scope enforcement stays in the
+ * fail-closed allowlist gate (middleware/scopes.ts), identical to API keys.
+ *
+ * User-scoped credential model: a token identifies its USER ("act as you")
+ * and carries NO workspace authority — claims are never an authorization
+ * input. The request's target workspace comes from the X-Workspace-Id
+ * selector through the shared resolveMembership rule (explicit → fail-closed
+ * membership check; absent → the user's default, else oldest active), the
+ * same rule sessions and API keys use.
+ */
+const JWKS_TTL_MS = 10 * 60 * 1000;
+
+export class OauthJwtVerifier {
+  private readonly issuer: string;
+  private readonly audience: string;
+  // Per-instance cache: the process verifies its OWN tokens, keys rotate
+  // rarely; on an unknown-signature failure we refetch once and retry.
+  private jwksCache: { keySet: ReturnType<typeof createLocalJWKSet>; fetchedAt: number } | null = null;
+
+  constructor(
+    private readonly auth: Auth,
+    private readonly db: Db,
+    publicBaseUrl: string,
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    private readonly onWorkspaceMiss?: OnWorkspaceMiss | undefined
+  ) {
+    this.issuer = publicBaseUrl;
+    this.audience = mcpResourceUrl(publicBaseUrl);
+  }
+
+  private async keySet(forceRefresh = false) {
+    if (!forceRefresh && this.jwksCache && Date.now() - this.jwksCache.fetchedAt < JWKS_TTL_MS) {
+      return this.jwksCache.keySet;
+    }
+    const jwks = (await this.auth.api.getJwks()) as { keys: JWK[] };
+    this.jwksCache = { keySet: createLocalJWKSet(jwks), fetchedAt: Date.now() };
+    return this.jwksCache.keySet;
+  }
+
+  private async verify(token: string) {
+    const options: JWTVerifyOptions = {
+      issuer: this.issuer,
+      audience: this.audience,
+      algorithms: ['RS256'], // hard allowlist — implicitly rejects none/HS256
+      clockTolerance: 5,
+      requiredClaims: ['sub']
+    };
+    try {
+      return await jwtVerify(token, await this.keySet(), options);
+    } catch (err) {
+      // One retry with fresh keys covers signing-key rotation mid-cache —
+      // both directions: a token signed by a key the cache no longer trusts
+      // (JWSSignatureVerificationFailed) and a token signed by a key MINTED
+      // after the cache was warmed (JWKSNoMatchingKey — the rotate-signing-key
+      // drill would otherwise answer 401 for up to JWKS_TTL_MS, ADR 023).
+      if (
+        err instanceof Error &&
+        (err.name === 'JWSSignatureVerificationFailed' || err.name === 'JWKSNoMatchingKey')
+      ) {
+        return await jwtVerify(token, await this.keySet(true), options);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Resolve a Bearer JWT to its principal, or null when the token fails
+   * verification or no live membership answers the selection — the same
+   * fail-closed semantics as the session and API-key paths.
+   *
+   * `requested` is the request's X-Workspace-Id (or null). Resolution is
+   * verify → sub → resolveMembership(sub, requested): the LIVE membership
+   * lookup is the instant-revocation point AND the whole workspace
+   * authorization. A legacy `workspace_id` claim (minted before the
+   * user-scoped model) is deliberately ignored — claims stopped being an
+   * authorization input entirely.
+   */
+  async resolve(token: string, requested: string | null): Promise<Principal | null> {
+    let payload: Record<string, unknown>;
+    try {
+      ({ payload } = await this.verify(token));
+    } catch {
+      return null;
+    }
+    const sub = typeof payload.sub === 'string' ? payload.sub : null;
+    if (!sub) return null;
+
+    let member = await resolveMembership(this.db, sub, requested);
+    if (!member && requested && this.onWorkspaceMiss && isWorkspaceSelector(requested)) {
+      // Unknown-workspace retry (cloud): the JWT verified above — the miss
+      // may be a hub org granted since the last reconcile pass. One cached
+      // reconcile, one re-run of the SAME lookup — no recursion.
+      await this.onWorkspaceMiss(sub, requested);
+      member = await resolveMembership(this.db, sub, requested);
+    }
+    if (!member) return null;
+
+    return {
+      userId: sub,
+      email: member.email,
+      name: member.name,
+      workspaceId: member.workspaceId,
+      role: member.role,
+      origin: member.origin,
+      via: 'oauth',
+      scopes: new Set(
+        String(typeof payload.scope === 'string' ? payload.scope : '')
+          .split(' ')
+          .filter(Boolean)
+      ),
+      ...(member.accountRef ? { accountRef: member.accountRef } : {})
+    };
+  }
+}

package/src/identity/resolve-membership.ts

@@ -0,0 +1,104 @@
+import { and, asc, desc, eq, or, sql } from 'drizzle-orm';
+import { user as userTable, workspaceMembers, workspaces, type Db } from '@antasphere/chassis-db';
+
+/**
+ * The ONE membership-selection rule of the user-scoped credential model
+ * (ADR 014 as amended): every credential — session, API key, OAuth bearer —
+ * identifies a USER, and each request resolves exactly ONE target workspace
+ * for that user:
+ *
+ *  - `requested` non-null (the X-Workspace-Id header, or an API key's pin):
+ *    an ACTIVE membership of that workspace is required, else null — fail
+ *    closed, so an unknown workspace and a workspace the user does not
+ *    belong to are indistinguishable (no oracle). The selector is the
+ *    workspace's LOCAL id, or (PRDCT-2947) the id of the hub organization
+ *    it projects (`workspaces.central_account_id`): a person names the
+ *    organization the hub's way (`--org <hub org id>`) and the tool maps
+ *    it here, in the one rule, so no credential path can fork on it. On
+ *    self-hosted the column is always empty and the second arm is inert.
+ *  - `requested` null: the user's DEFAULT membership (`is_default`, at most
+ *    one per user), else the deterministic fallback — the OLDEST active
+ *    membership (created_at, then id). While no row carries `is_default`
+ *    (nothing sets it on oss; the cloud reconcile materializes the hub-level
+ *    default), the ordering is inert and selection is byte-identical to the
+ *    pre-default behavior.
+ *
+ * All three resolvers share THIS query so the selection rule can never fork
+ * per credential path.
+ */
+
+/** Strict UUID shape — a malformed selector must never reach Postgres' uuid cast. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Well-formed-selector check, shared with the cloud miss-retry hook: only a
+ * plausibly-real workspace id ever triggers a hub reconcile — a garbage
+ * header can never buy a hub round-trip (the reconciler's TTL/throttle
+ * bounds even well-formed ones).
+ */
+export function isWorkspaceSelector(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/**
+ * The cloud edition's unknown-workspace retry hook (internal/federation.md):
+ * a verified credential naming a workspace the local join cannot see MAY be
+ * a hub org granted since the last reconcile pass — "invited at the hub,
+ * clicks a deep link". Boot wires ONE cached reconcile; the resolver then
+ * re-runs the SAME lookup once, no recursion. undefined on oss.
+ */
+export type OnWorkspaceMiss = (userId: string, requested: string) => Promise<void>;
+
+export interface ResolvedMembership {
+  workspaceId: string;
+  role: 'owner' | 'admin' | 'member';
+  origin: 'local' | 'hub' | 'guest';
+  /** The workspace's centralAccountId — null outside hub projections. */
+  accountRef: string | null;
+  /** Live user row fields, for the machine paths that carry no session. */
+  email: string;
+  name: string;
+}
+
+export async function resolveMembership(
+  db: Db,
+  userId: string,
+  requested: string | null
+): Promise<ResolvedMembership | null> {
+  if (requested !== null && !UUID_RE.test(requested)) return null; // fail closed, no uuid-cast 500
+
+  const [row] = await db
+    .select({
+      workspaceId: workspaceMembers.workspaceId,
+      role: workspaceMembers.role,
+      origin: workspaceMembers.origin,
+      accountRef: workspaces.centralAccountId,
+      email: userTable.email,
+      name: userTable.name
+    })
+    .from(workspaceMembers)
+    .innerJoin(workspaces, eq(workspaceMembers.workspaceId, workspaces.id))
+    .innerJoin(userTable, eq(workspaceMembers.userId, userTable.id))
+    .where(
+      and(
+        eq(workspaceMembers.userId, userId),
+        eq(workspaceMembers.isActive, true),
+        ...(requested
+          ? [
+              or(
+                eq(workspaceMembers.workspaceId, requested),
+                // Case-blind like the uuid arm and the pin check (verifier
+                // round 1, F6): the column is text, the selector a uuid.
+                sql`lower(${workspaces.centralAccountId}) = lower(${requested})`
+              )
+            ]
+          : [])
+      )
+    )
+    // Selector-less default: the default membership first, then the
+    // deterministic oldest. With a selector the filter pins a single row and
+    // the order is inert.
+    .orderBy(desc(workspaceMembers.isDefault), asc(workspaceMembers.createdAt), asc(workspaceMembers.id))
+    .limit(1);
+  return row ?? null;
+}

package/src/identity/signing-key.ts

@@ -0,0 +1,164 @@
+import { desc, eq } from 'drizzle-orm';
+import { exportJWK, generateKeyPair } from 'jose';
+import { generateRandomString, symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto';
+import { jwks, type Db } from '@antasphere/chassis-db';
+
+/**
+ * OAuth signing-key durability across AUTH_SECRET rotation (ADR 023).
+ *
+ * The jwt plugin stores its RS256 private key in the `jwks` table encrypted
+ * under the auth secret (bare xchacha20 ciphertext — createAuth passes a
+ * plain string `secret`, so no versioned envelope). Signing decrypts the
+ * NEWEST row on every mint; with no `rotationInterval` the row never
+ * expires, so a rotated AUTH_SECRET turns every token mint into a 500 —
+ * forever. The three exports here close that:
+ *
+ *  - `preflightSigningKey` mirrors the plugin's signing path (newest
+ *    non-expired row → decrypt) at boot and reports failure BEFORE the
+ *    instance serves an authorize endpoint it cannot follow with a token.
+ *  - `rotateSigningKey` mints a fresh RS256 key under the CURRENT secret —
+ *    the same row shape the plugin's own createJwk writes, so the plugin
+ *    signs with it immediately (newest createdAt wins). Retired rows stay in
+ *    the table, and /jwks publishes every row without an expiresAt, so
+ *    already-issued tokens keep verifying for as long as the old row stays —
+ *    the publish-overlap window.
+ *  - `retireSigningKey` deletes ONE named retired row after the overlap
+ *    window; the newest (active signer) is refused.
+ *
+ * Everything here mirrors the pinned better-auth 1.6.15 jwt plugin
+ * (plugins/jwt/{sign,utils,adapter}.mjs) — re-verify the row shape, the
+ * newest-key selection, and the /jwks publish filter on ANY bump.
+ */
+
+/** The alg the chassis pins in `jwks.keyPairConfig` (identity/better-auth.ts). */
+const SIGNING_ALG = 'RS256';
+
+export type SigningKeyPreflight =
+  { ok: true; kid: string | null } | { ok: false; kid: string; reason: string };
+
+/**
+ * The operator-facing diagnostic — names the cause and BOTH safe remedies.
+ * Kept in one place so boot's fatal log and the tests pin the same message.
+ */
+export function signingKeyPreflightMessage(kid: string): string {
+  return (
+    `OAuth signing-key preflight failed: the stored JWKS private key (kid ${kid}) ` +
+    'cannot be decrypted with the current AUTH_SECRET. This happens when AUTH_SECRET ' +
+    'was rotated without re-keying token signing; booting anyway would serve an ' +
+    'authorize endpoint whose every token mint (POST /oauth2/token) answers 500. ' +
+    'Remedies: restore the previous AUTH_SECRET, or mint a fresh signing key under ' +
+    'the current secret with `node dist/index.js rotate-signing-key` — the retired ' +
+    'key stays published on /jwks so already-issued tokens keep verifying ' +
+    '(internal/security-runbooks.md).'
+  );
+}
+
+/**
+ * Boot preflight: attempt one decrypt of the key the jwt plugin would sign
+ * with. Exactly the plugin's selection rule (sign.mjs): newest by createdAt;
+ * a missing table-or-row and an EXPIRED newest row are both fine — the next
+ * mint creates a fresh key under the current secret.
+ */
+export async function preflightSigningKey(db: Db, authSecret: string): Promise<SigningKeyPreflight> {
+  const [latest] = await db
+    .select({ id: jwks.id, privateKey: jwks.privateKey, expiresAt: jwks.expiresAt })
+    .from(jwks)
+    .orderBy(desc(jwks.createdAt))
+    .limit(1);
+  if (!latest) return { ok: true, kid: null };
+  if (latest.expiresAt && latest.expiresAt < new Date()) return { ok: true, kid: null };
+  try {
+    // The plugin stores JSON.stringify(symmetricEncrypt(...)) — decrypt takes
+    // the JSON.parse'd string (sign.mjs).
+    await symmetricDecrypt({ key: authSecret, data: JSON.parse(latest.privateKey) as string });
+    return { ok: true, kid: latest.id };
+  } catch {
+    return { ok: false, kid: latest.id, reason: signingKeyPreflightMessage(latest.id) };
+  }
+}
+
+/**
+ * Mint a new signing key under the given secret — the manual rotation step
+ * (a compromise drill, or re-keying after an AUTH_SECRET change). Mirrors
+ * the plugin's createJwk (utils.mjs): extractable RS256 pair, JWK-exported,
+ * private half encrypted exactly as the plugin decrypts it. The new row's
+ * createdAt makes it the active signer; every older row stays published on
+ * /jwks (the overlap) until explicitly retired.
+ */
+export async function rotateSigningKey(db: Db, authSecret: string): Promise<{ kid: string }> {
+  const { publicKey, privateKey } = await generateKeyPair(SIGNING_ALG, { extractable: true });
+  const publicWebKey = await exportJWK(publicKey);
+  const privateWebKey = await exportJWK(privateKey);
+  const kid = generateRandomString(32, 'a-z', 'A-Z', '0-9');
+  await db.insert(jwks).values({
+    id: kid,
+    publicKey: JSON.stringify(publicWebKey),
+    privateKey: JSON.stringify(
+      await symmetricEncrypt({ key: authSecret, data: JSON.stringify(privateWebKey) })
+    ),
+    createdAt: new Date(),
+    expiresAt: null
+  });
+  return { kid };
+}
+
+/**
+ * Delete ONE retired key by kid, after the overlap window. Refuses the
+ * newest row: deleting the active signer would silently re-key the instance
+ * on the next mint with zero coordination — the exact failure the preflight
+ * exists to prevent.
+ */
+export async function retireSigningKey(db: Db, kid: string): Promise<void> {
+  const [latest] = await db.select({ id: jwks.id }).from(jwks).orderBy(desc(jwks.createdAt)).limit(1);
+  if (!latest) throw new Error('no signing keys exist');
+  if (latest.id === kid) {
+    throw new Error(
+      `refusing to retire ${kid}: it is the ACTIVE signing key (newest row). ` +
+        'Mint a replacement first with rotate-signing-key, wait out the overlap window, then retire.'
+    );
+  }
+  const deleted = await db.delete(jwks).where(eq(jwks.id, kid)).returning({ id: jwks.id });
+  if (deleted.length === 0) throw new Error(`no signing key with kid ${kid}`);
+}
+
+/**
+ * `node dist/index.js rotate-signing-key [--retire <kid>]` — the operator
+ * entry point (index.ts). Runs against the container's own env (DATABASE_URL
+ * + AUTH_SECRET/DATA_DIR), so `docker compose run --rm app …` works while
+ * the server is down — the state the preflight refusal leaves you in.
+ * Output goes to stdout on purpose: this is an interactive operator command,
+ * not the service log.
+ */
+export async function runSigningKeyCli(
+  db: Db,
+  authSecret: string,
+  args: readonly string[],
+  out: (line: string) => void
+): Promise<number> {
+  const retireAt = args.indexOf('--retire');
+  if (retireAt !== -1) {
+    const kid = args[retireAt + 1];
+    if (!kid) {
+      out('usage: rotate-signing-key --retire <kid>');
+      return 1;
+    }
+    await retireSigningKey(db, kid);
+    out(`retired signing key ${kid} — it is no longer published on /jwks; tokens it signed no longer verify`);
+    return 0;
+  }
+
+  const before = await db.select({ id: jwks.id }).from(jwks).orderBy(desc(jwks.createdAt));
+  const { kid } = await rotateSigningKey(db, authSecret);
+  out(`minted new signing key ${kid} under the current AUTH_SECRET — it signs from the next mint on`);
+  if (before.length > 0) {
+    out(
+      `retired key(s) still published for the overlap window (already-issued tokens keep verifying): ` +
+        before.map((k) => k.id).join(', ')
+    );
+    out(
+      'after the overlap window (outstanding access tokens live 15 min; allow for external JWKS caches), ' +
+        'retire each with: rotate-signing-key --retire <kid>'
+    );
+  }
+  return 0;
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+import type { z } from 'zod';
+import { bootPlatform } from './boot.js';
+import type { BootOverrides, BootResult, ToolDefinition } from './tool-definition.js';
+
+export { type AppDeps, createApp, postgresErrorCode } from './app.js';
+export type { ExportEntriesFn, ExportEntry } from './api/export.js';
+export {
+  EMPTY_TOOL_ENTITLEMENTS,
+  HUB_USAGE_SCOPE,
+  HubCreditCheck,
+  HubMachineToken,
+  HubUsagePoster,
+  EntitlementProfiles,
+  assertToolEntitlements,
+  type ToolEntitlementDeclaration
+} from './entitlements/index.js';
+export type {
+  ApiContext,
+  ApiRateLimitContext,
+  ApiRoutesContext,
+  BodyCap,
+  BodyLimitVerdict,
+  BootOverrides,
+  BootResult,
+  FilePolicy,
+  JobsContext,
+  PlatformCore,
+  ServiceCore,
+  ToolApiSlots,
+  ToolAppSlots,
+  ToolBuckets,
+  ToolCopy,
+  ToolDefinition,
+  ToolRateLimiters
+} from './tool-definition.js';
+
+/** A platform: one tool definition bound to the chassis' locked composition. */
+export interface Platform<TEnvShape extends z.ZodRawShape, TDomain, TEvents, TToolOverrides> {
+  /**
+   * The boot sequence, in its locked order: env → logger → db probe → secret →
+   * migrations under advisory lock → app assembly → ready.
+   */
+  boot: (
+    source?: NodeJS.ProcessEnv,
+    overrides?: BootOverrides<TToolOverrides>
+  ) => Promise<BootResult<TEnvShape, TDomain, TEvents>>;
+}
+
+/**
+ * THE composition entry. A tool fills the named slots of `ToolDefinition`;
+ * the chassis owns every ordering (boot.ts, api/create-api.ts, app.ts).
+ */
+export function createPlatform<
+  TEnvShape extends z.ZodRawShape,
+  TDomain,
+  TBuckets extends string = never,
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  TEvents = {},
+  TToolOverrides = never
+>(
+  tool: ToolDefinition<TEnvShape, TDomain, TBuckets, TEvents, TToolOverrides>
+): Platform<TEnvShape, TDomain, TEvents, TToolOverrides> {
+  return { boot: (source, overrides) => bootPlatform(tool, source, overrides) };
+}
+export type { MembershipRemovalHook, RemovedMembership, RemovalCounts } from './members/removal.js';

package/src/invitations/index.ts

@@ -0,0 +1 @@
+export { InvitationError, InvitationService } from './service.js';

package/src/invitations/service.ts

@@ -0,0 +1,171 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { and, eq, isNull, or, sql } from 'drizzle-orm';
+import {
+  invitations,
+  workspaceMembers,
+  user as userTable,
+  type Db,
+  type Invitation
+} from '@antasphere/chassis-db';
+
+/**
+ * Token-bearing invitations; the database holds only sha256 hashes.
+ * Acceptance works with zero SMTP — the copyable link is the primary path,
+ * mail is a bonus.
+ *
+ * Each invitation carries TWO independent tokens for one row (ADR 009):
+ * `token` is the copyable link handed to the inviter (always in the create
+ * response), `emailToken` appears ONLY inside the invitation email. Both
+ * redeem the same invitation, but which one was presented tells the accept
+ * flow whether the accepter demonstrably controls the invited mailbox — the
+ * admin-visible link never proves that, the emailed token does.
+ */
+const INVITATION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+/** A live invitation plus which of its two tokens the caller presented. */
+export interface InvitationMatch {
+  invitation: Invitation;
+  /** True when the presented token is the one that ONLY the email carried. */
+  viaEmailToken: boolean;
+}
+
+export class InvitationService {
+  constructor(private readonly db: Db) {}
+
+  async create(opts: {
+    workspaceId: string;
+    email: string;
+    role: 'owner' | 'admin' | 'member';
+    invitedBy: string;
+  }): Promise<{ invitation: Invitation; token: string; emailToken: string }> {
+    const email = opts.email.toLowerCase().trim();
+
+    // Refuse duplicates: an active member or an open invitation.
+    const [existingMember] = await this.db
+      .select({ id: workspaceMembers.id })
+      .from(workspaceMembers)
+      .innerJoin(userTable, eq(workspaceMembers.userId, userTable.id))
+      .where(
+        and(
+          eq(userTable.email, email),
+          eq(workspaceMembers.workspaceId, opts.workspaceId),
+          eq(workspaceMembers.isActive, true)
+        )
+      )
+      .limit(1);
+    if (existingMember) throw new InvitationError('already_member', 'This email is already an active member');
+
+    const [open] = await this.db
+      .select({ id: invitations.id })
+      .from(invitations)
+      .where(
+        and(
+          eq(invitations.email, email),
+          eq(invitations.workspaceId, opts.workspaceId),
+          isNull(invitations.acceptedAt),
+          isNull(invitations.revokedAt),
+          sql`${invitations.expiresAt} > now()`
+        )
+      )
+      .limit(1);
+    if (open)
+      throw new InvitationError('already_invited', 'An open invitation for this email already exists');
+
+    const token = randomBytes(32).toString('base64url');
+    const emailToken = randomBytes(32).toString('base64url');
+    const [invitation] = await this.db
+      .insert(invitations)
+      .values({
+        workspaceId: opts.workspaceId,
+        email,
+        role: opts.role,
+        tokenHash: hashToken(token),
+        emailTokenHash: hashToken(emailToken),
+        invitedBy: opts.invitedBy,
+        expiresAt: new Date(Date.now() + INVITATION_TTL_MS)
+      })
+      .returning();
+    if (!invitation) throw new Error('invitation insert failed');
+    return { invitation, token, emailToken };
+  }
+
+  /**
+   * Find a live (unaccepted, unrevoked, unexpired) invitation by raw token —
+   * either the copyable-link token or the emailed one — and report which.
+   */
+  async findLiveByToken(token: string): Promise<InvitationMatch | null> {
+    const hash = hashToken(token);
+    const [row] = await this.db
+      .select()
+      .from(invitations)
+      .where(
+        and(
+          or(eq(invitations.tokenHash, hash), eq(invitations.emailTokenHash, hash)),
+          isNull(invitations.acceptedAt),
+          isNull(invitations.revokedAt)
+        )
+      )
+      .limit(1);
+    if (!row) return null;
+    if (row.expiresAt.getTime() < Date.now()) return null;
+    return { invitation: row, viaEmailToken: row.emailTokenHash === hash };
+  }
+
+  /**
+   * Join: create the membership and stamp acceptance atomically enough that
+   * a token cannot be redeemed twice (the accepted_at guard is the gate).
+   */
+  async accept(invitation: Invitation, userId: string): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      const updated = await tx
+        .update(invitations)
+        .set({ acceptedAt: sql`now()` })
+        .where(
+          and(
+            eq(invitations.id, invitation.id),
+            isNull(invitations.acceptedAt),
+            isNull(invitations.revokedAt),
+            sql`${invitations.expiresAt} > now()`
+          )
+        )
+        .returning({ id: invitations.id });
+      if (updated.length === 0) return false; // redeemed, revoked, or expired meanwhile
+
+      // Rejoin after deactivation reactivates the existing row.
+      const [existing] = await tx
+        .select({ id: workspaceMembers.id })
+        .from(workspaceMembers)
+        .where(
+          and(eq(workspaceMembers.workspaceId, invitation.workspaceId), eq(workspaceMembers.userId, userId))
+        )
+        .limit(1);
+      if (existing) {
+        await tx
+          .update(workspaceMembers)
+          .set({ isActive: true, role: invitation.role, invitedBy: invitation.invitedBy })
+          .where(eq(workspaceMembers.id, existing.id));
+      } else {
+        await tx.insert(workspaceMembers).values({
+          workspaceId: invitation.workspaceId,
+          userId,
+          role: invitation.role,
+          invitedBy: invitation.invitedBy
+        });
+      }
+      return true;
+    });
+  }
+}
+
+export class InvitationError extends Error {
+  constructor(
+    public readonly code: 'already_member' | 'already_invited',
+    message: string
+  ) {
+    super(message);
+  }
+}

package/src/jobs/index.ts

@@ -0,0 +1,25 @@
+export {
+  type JobDeclaration,
+  type Jobs,
+  type UsageRetry,
+  DEFAULT_USAGE_RETRY,
+  USAGE_HELD_QUEUE,
+  USAGE_QUEUE,
+  PgBossUsageSink,
+  createJobs,
+  usageSendOptions
+} from './pgboss.js';
+export {
+  type TimerJob,
+  type TimerOptions,
+  type TimerRef,
+  type TimerRetry,
+  type TimerWhen,
+  type Timers,
+  MAX_IN_SECONDS,
+  PGBOSS_SCHEMA,
+  PgBossTimers,
+  TIMER_KEY_LOCK_CLASS,
+  TimerError,
+  startAfterOf
+} from './timers.js';