@plitzi/sdk-server 0.33.1 → 0.34.0

package/dist/modules/mysql/schema.js

@@ -0,0 +1,340 @@
+import { execute, selectOne, selectRows } from "./query.js";
+import { tableNames } from "./config.js";
+//#region src/modules/mysql/schema.ts
+/**
+* The tables, as SQL.
+*
+* Two decisions in here are worth stating, because getting either wrong fails much later and looks like something
+* else entirely:
+*
+* **Tokens are `TEXT`, not `VARCHAR`.** A session credential is a JWT, and a JWT's length is set by its `aud` claim
+* — one host per environment. A stack with seven audiences mints a 549-character refresh token, so a `VARCHAR(512)`
+* kills every login with "value too long" on the deployment that has the most environments and nowhere else. They
+* are indexed by prefix instead; the comparison is still exact, MySQL rechecks the full value against the row.
+*
+* **Unix seconds are `BIGINT`, not `INT`.** A signed `INT` runs out on 19 January 2038, and the credential this
+* schema stores that is allowed to live forever is exactly the one that would be written with a far-future date.
+*/
+var CHARSET = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci";
+var step1 = (t) => [
+	`CREATE TABLE IF NOT EXISTS ${t.account} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    username VARCHAR(191) NOT NULL,
+    email VARCHAR(191) NOT NULL,
+    password_hash VARCHAR(255) NULL,
+    status ENUM('active','inactive','blocked') NOT NULL DEFAULT 'active',
+    verified TINYINT(1) NOT NULL DEFAULT 0,
+    reset_token VARCHAR(191) NULL,
+    validation_token VARCHAR(191) NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    UNIQUE KEY account_username (username),
+    UNIQUE KEY account_email (email),
+    KEY account_reset_token (reset_token),
+    KEY account_validation_token (validation_token)
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.session} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    account_id INT UNSIGNED NOT NULL,
+    token TEXT NOT NULL,
+    expires_at BIGINT NOT NULL,
+    refresh_token TEXT NULL,
+    refresh_expires_at BIGINT NULL,
+    user_agent VARCHAR(255) NULL,
+    ip VARCHAR(45) NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    KEY session_account (account_id),
+    KEY session_token (token(191)),
+    KEY session_refresh_token (refresh_token(191)),
+    KEY session_expires_at (expires_at),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.role} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    name VARCHAR(64) NOT NULL,
+    description VARCHAR(255) NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY role_name (name)
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.permission} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    name VARCHAR(64) NOT NULL,
+    description VARCHAR(255) NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY permission_name (name)
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.rolePermission} (
+    role_id INT UNSIGNED NOT NULL,
+    permission_id INT UNSIGNED NOT NULL,
+    PRIMARY KEY (role_id, permission_id),
+    KEY role_permission_permission (permission_id),
+    FOREIGN KEY (role_id) REFERENCES ${t.role} (id) ON DELETE CASCADE,
+    FOREIGN KEY (permission_id) REFERENCES ${t.permission} (id) ON DELETE CASCADE
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.accountRole} (
+    account_id INT UNSIGNED NOT NULL,
+    role_id INT UNSIGNED NOT NULL,
+    PRIMARY KEY (account_id, role_id),
+    KEY account_role_role (role_id),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE,
+    FOREIGN KEY (role_id) REFERENCES ${t.role} (id) ON DELETE CASCADE
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.spaceMember} (
+    space_id BIGINT UNSIGNED NOT NULL,
+    account_id INT UNSIGNED NOT NULL,
+    role_id INT UNSIGNED NOT NULL,
+    is_owner TINYINT(1) NOT NULL DEFAULT 0,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (space_id, account_id),
+    KEY space_member_account (account_id),
+    KEY space_member_role (role_id),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE,
+    FOREIGN KEY (role_id) REFERENCES ${t.role} (id)
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.spaceToken} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    space_id BIGINT UNSIGNED NOT NULL,
+    token TEXT NOT NULL,
+    scope ENUM('render','agent') NOT NULL DEFAULT 'render',
+    is_default TINYINT(1) NOT NULL DEFAULT 0,
+    origins TEXT NULL,
+    expires_at BIGINT NULL,
+    account_id INT UNSIGNED NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    KEY space_token_space (space_id),
+    KEY space_token_token (token(191)),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE
+  ) ${CHARSET}`
+];
+/**
+* Everything an account can be besides a password: an identity at another provider, a second factor, and a
+* one-time code. Added as step 2 rather than folded into step 1 — step 1 is released.
+*/
+var step2 = (t) => [
+	`CREATE TABLE IF NOT EXISTS ${t.identity} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    account_id INT UNSIGNED NOT NULL,
+    provider VARCHAR(64) NOT NULL,
+    subject VARCHAR(191) NOT NULL,
+    email VARCHAR(191) NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    UNIQUE KEY identity_provider_subject (provider, subject),
+    KEY identity_account (account_id),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.mfa} (
+    account_id INT UNSIGNED NOT NULL,
+    secret VARCHAR(191) NOT NULL,
+    confirmed_at BIGINT NULL,
+    recovery_codes TEXT NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (account_id),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE
+  ) ${CHARSET}`,
+	`CREATE TABLE IF NOT EXISTS ${t.otp} (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    account_id INT UNSIGNED NULL,
+    purpose VARCHAR(32) NOT NULL,
+    identifier VARCHAR(191) NOT NULL,
+    code_hash VARCHAR(191) NOT NULL,
+    expires_at BIGINT NOT NULL,
+    attempts INT UNSIGNED NOT NULL DEFAULT 0,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    KEY otp_lookup (purpose, identifier),
+    KEY otp_expires_at (expires_at),
+    FOREIGN KEY (account_id) REFERENCES ${t.account} (id) ON DELETE CASCADE
+  ) ${CHARSET}`
+];
+/**
+* DDL that can be run twice.
+*
+* MySQL has `CREATE TABLE IF NOT EXISTS` and nothing else: `ADD COLUMN IF NOT EXISTS` is MariaDB's, and a plain
+* `ADD COLUMN` on a second run is an error. That matters because MySQL cannot roll back DDL — a step that fails
+* halfway has already applied some of its statements, and the retry has to survive meeting them again.
+*
+* So a conditional is built out of what MySQL does have: look in `information_schema`, and prepare either the real
+* statement or a no-op. Emitted as separate statements because the driver sends one at a time.
+*
+* Every step after the first should be written with these. `schemaStatements()` still returns plain SQL, so a
+* deployment migrating with its own tool gets the same guards.
+*/
+var QUOTE = String.fromCharCode(39);
+/** A SQL string literal. The statement being embedded is DDL, so it routinely contains quotes of its own. */
+var literal = (value) => `${QUOTE}${value.replace(/\\/g, "\\\\").replace(/'/g, "''")}${QUOTE}`;
+var conditional = (test, statement) => [
+	`SET @plitzi_ddl := (SELECT IF(${test}, ${literal(statement)}, 'DO 0'))`,
+	"PREPARE plitzi_ddl_stmt FROM @plitzi_ddl",
+	"EXECUTE plitzi_ddl_stmt",
+	"DEALLOCATE PREPARE plitzi_ddl_stmt"
+];
+var columnExists = (table, column) => `SELECT COUNT(*) FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = '${table}' AND COLUMN_NAME = '${column}'`;
+var indexExists = (table, index) => `SELECT COUNT(*) FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = '${table}' AND INDEX_NAME = '${index}'`;
+/** Adds a column unless it is already there. `definition` is everything after the column name. */
+var addColumn = (table, column, definition) => conditional(`(${columnExists(table, column)}) = 0`, `ALTER TABLE \`${table}\` ADD COLUMN \`${column}\` ${definition}`);
+/** Adds an index unless one of that name exists. `definition` is the parenthesised column list. */
+var addIndex = (table, index, definition) => conditional(`(${indexExists(table, index)}) = 0`, `ALTER TABLE \`${table}\` ADD INDEX \`${index}\` ${definition}`);
+/** The bare name, for the `information_schema` lookups above — they compare against a string, not an identifier. */
+var unquote = (name) => name.replace(/`/g, "");
+/**
+* An address the account asked to move to, and the token that will confirm it.
+*
+* Parked in two columns rather than applied, so the account keeps a working sign-in identifier until the new one
+* answers a confirmation — see `confirmEmailChange`. Written with the idempotent helpers, being a step after the
+* first: this is the migration path every later change to these tables takes.
+*/
+var step3 = (t) => {
+	const account = unquote(t.account);
+	return [
+		...addColumn(account, "pending_email", "VARCHAR(191) NULL AFTER email"),
+		...addColumn(account, "pending_email_token", "VARCHAR(191) NULL AFTER pending_email"),
+		...addIndex(account, "account_pending_email_token", "(pending_email_token)")
+	];
+};
+/** Append only. A released version is never edited — the deployments that already ran it would never see the change. */
+var STEPS = [
+	{
+		version: 1,
+		statements: step1
+	},
+	{
+		version: 2,
+		statements: step2
+	},
+	{
+		version: 3,
+		statements: step3
+	}
+];
+var SCHEMA_VERSION = STEPS[STEPS.length - 1].version;
+/**
+* Every statement this schema is made of, in order — for a deployment that runs `autoMigrate: false` and applies
+* DDL through its own migration tool, which is the normal arrangement anywhere the application's database user is
+* not allowed to alter tables.
+*/
+var schemaStatements = (tables, fromVersion = 0) => STEPS.filter((step) => step.version > fromVersion).flatMap((step) => step.statements(tables));
+/**
+* The order tables must be dropped in, children first. Foreign keys make the wrong order an error rather than a
+* silent mess, but the error names a constraint and not what to do about it.
+*/
+var DROP_ORDER = [
+	"otp",
+	"mfa",
+	"identity",
+	"spaceToken",
+	"spaceMember",
+	"accountRole",
+	"rolePermission",
+	"session",
+	"account",
+	"role",
+	"permission",
+	"schemaVersion"
+];
+/** Which of OUR tables the database already has. Asked of `information_schema`, scoped to this database. */
+var existingTables = async (pool, prefix) => {
+	const wanted = Object.values(tableNames(prefix));
+	const placeholders = wanted.map(() => "?").join(", ");
+	return (await selectRows(pool, `SELECT TABLE_NAME AS name FROM information_schema.TABLES
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${placeholders})`, wanted)).map((row) => row.name);
+};
+var readVersion = async (pool, tables) => {
+	return (await selectOne(pool, `SELECT version FROM ${tables.schemaVersion} WHERE component = 'sdk-server-auth'`))?.version ?? 0;
+};
+/**
+* Brings the schema up to date, once.
+*
+* The advisory lock is not decoration: an all-in-one deployment starts several roles against one database at the
+* same moment, and without it they race to create the same tables and to bump the same version row. `IF NOT EXISTS`
+* makes the statements survive that; the version bump would not.
+*/
+var migrate = async (pool, tables, options) => {
+	const { prefix, adoptExisting = false, log } = options;
+	/**
+	* A database this schema has never been migrated into, that already has tables with these names, is almost
+	* certainly somebody else's — `role`, `permission` and `session` are among the most ordinary names there are, and
+	* this module is explicitly meant to be pointed at a database with unrelated tables in it.
+	*
+	* `CREATE TABLE IF NOT EXISTS` would quietly ADOPT them, and the failure would surface much later as a query
+	* against columns that are not there. Refused instead, naming the fix.
+	*/
+	if (!adoptExisting) {
+		const present = await existingTables(pool, prefix);
+		const migrated = present.includes(tableNames(prefix).schemaVersion) && await readVersion(pool, tables) > 0;
+		if (present.length > 0 && !migrated) throw new Error(`@plitzi/sdk-server/mysql: this database already has tables named ${present.join(", ")}, and they were not created by this schema. Point it at another database, set \`tablePrefix\` so the names cannot collide, or pass \`adoptExisting: true\` if they really are this schema’s and you are re-attaching.`);
+	}
+	await execute(pool, `CREATE TABLE IF NOT EXISTS ${tables.schemaVersion} (
+      component VARCHAR(64) NOT NULL,
+      version INT UNSIGNED NOT NULL,
+      updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      PRIMARY KEY (component)
+    ) ${CHARSET}`);
+	const connection = await pool.getConnection();
+	const lockName = `${tables.schemaVersion.replace(/`/g, "")}_sdk_server`.slice(0, 64);
+	try {
+		if ((await selectOne(connection, "SELECT GET_LOCK(?, 30) AS acquired", [lockName]))?.acquired !== 1) throw new Error(`@plitzi/sdk-server/mysql: timed out waiting for the schema lock "${lockName}". Another process is migrating this database, or one died holding the lock.`);
+		try {
+			const current = await readVersion(pool, tables);
+			/**
+			* The database is ahead of the code. That means an older process has been started against a schema a newer
+			* one migrated, and letting it run is worse than refusing: it would read and write rows shaped by rules it
+			* does not have. The usual cause is a rollback that rolled back the code and not the database.
+			*/
+			if (current > SCHEMA_VERSION) throw new Error(`@plitzi/sdk-server/mysql: this database is at auth schema version ${current} and this build only knows ${SCHEMA_VERSION}. Upgrade @plitzi/sdk-server, or point this process at a database it understands.`);
+			if (current === SCHEMA_VERSION) return current;
+			/**
+			* One step at a time, with the version written after EACH.
+			*
+			* MySQL cannot roll back DDL, so a step that fails halfway leaves the database between two versions. Bumping
+			* once at the end would make the next run start over from `current` and re-apply the statements that had
+			* already succeeded — which is exactly when a non-idempotent `ADD COLUMN` turns a recoverable failure into a
+			* stuck deployment. Recording each step means a retry resumes at the one that failed.
+			*/
+			for (const step of STEPS.filter((candidate) => candidate.version > current)) {
+				for (const statement of step.statements(tables)) await execute(connection, statement);
+				await execute(connection, `INSERT INTO ${tables.schemaVersion} (component, version) VALUES ('sdk-server-auth', ?)
+           ON DUPLICATE KEY UPDATE version = VALUES(version)`, [step.version]);
+				log?.(`[mysql] auth schema migrated to version ${step.version}`);
+			}
+			return SCHEMA_VERSION;
+		} finally {
+			await connection.query("SELECT RELEASE_LOCK(?)", [lockName]);
+		}
+	} finally {
+		connection.release();
+	}
+};
+/**
+* Removes this schema and nothing else.
+*
+* For a deployment that pointed the store at a database it shares with other things and has now stopped using
+* `@plitzi/sdk-server` — dropping the database would take the rest of their application with it, and working out
+* which nine tables were ours is not something anybody should have to do by hand at that moment.
+*
+* It drops **only** the names this schema owns, children first so the foreign keys allow it, and it refuses to
+* touch a database it was never migrated into: without that check, a typo in `tablePrefix` turns this into a tool
+* that deletes somebody else's `role` table.
+*/
+var dropSchema = async (pool, tables, options) => {
+	const { prefix, force = false, log } = options;
+	const present = await existingTables(pool, prefix);
+	if (present.length === 0) return [];
+	if (!force && !present.includes(tableNames(prefix).schemaVersion)) throw new Error(`@plitzi/sdk-server/mysql: refusing to drop ${present.join(", ")} — there is no ${tableNames(prefix).schemaVersion} table, so this schema was never migrated into this database and those tables are somebody else’s. Check \`tablePrefix\`, or pass \`force: true\` if you are certain.`);
+	const dropped = [];
+	for (const key of DROP_ORDER) {
+		const name = tableNames(prefix)[key];
+		if (present.includes(name)) {
+			await execute(pool, `DROP TABLE IF EXISTS ${tables[key]}`);
+			dropped.push(name);
+		}
+	}
+	log?.(`[mysql] dropped ${dropped.length} auth tables: ${dropped.join(", ")}`);
+	return dropped;
+};
+//#endregion
+export { SCHEMA_VERSION, addColumn, addIndex, dropSchema, migrate, schemaStatements };

package/dist/modules/mysql/schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/mysql/sessions.d.ts

@@ -0,0 +1,33 @@
+import { Tables } from './config';
+import { Queryable } from './query';
+/** One signed-in device, as somebody looking at their own account should see it. Never the credential itself. */
+export interface SessionSummary {
+    id: number;
+    userAgent?: string;
+    ip?: string;
+    /** Unix seconds. */
+    createdAt: number;
+    expiresAt: number;
+    /** This is the session asking. A device list without it invites someone to revoke the one they are using. */
+    current: boolean;
+}
+/**
+ * The sessions of one account, as a thing that can be looked at and taken away one at a time.
+ *
+ * This is what a `session` table buys over a token pair on the account row, and it is the whole reason to pay for
+ * it: somebody who left themselves signed in on a machine they no longer have can end that session and keep the
+ * ones they are using. Revoking everything is `clearSession({ userId })` and is a blunter instrument.
+ */
+export declare const createSessionStore: (db: Queryable, t: Tables) => {
+    list: (accountId: number, currentToken?: string) => Promise<SessionSummary[]>;
+    /** Scoped by account as well as id, or one account could end another's session by guessing a number. */
+    revoke: (accountId: number, sessionId: number) => Promise<boolean>;
+    /** "Sign out everywhere else" — the one thing to do from a device you still trust after losing one you do not. */
+    revokeOthers: (accountId: number, currentToken: string) => Promise<number>;
+    /**
+     * Delete what has aged out. Nothing depends on this for correctness — an expired session is refused by its
+     * expiry, not by its absence — so it is housekeeping a deployment schedules, not a step in any request.
+     */
+    purgeExpired: () => Promise<number>;
+};
+export type SessionStore = ReturnType<typeof createSessionStore>;

package/dist/modules/mysql/sessions.js

@@ -0,0 +1,46 @@
+import { execute, selectRows } from "./query.js";
+//#region src/modules/mysql/sessions.ts
+/**
+* The sessions of one account, as a thing that can be looked at and taken away one at a time.
+*
+* This is what a `session` table buys over a token pair on the account row, and it is the whole reason to pay for
+* it: somebody who left themselves signed in on a machine they no longer have can end that session and keep the
+* ones they are using. Revoking everything is `clearSession({ userId })` and is a blunter instrument.
+*/
+var createSessionStore = (db, t) => {
+	const list = async (accountId, currentToken) => {
+		return (await selectRows(db, `SELECT id, token, user_agent, ip, created_at, expires_at
+         FROM ${t.session}
+        WHERE account_id = ?
+        ORDER BY created_at DESC`, [accountId])).map((row) => ({
+			id: row.id,
+			...row.user_agent ? { userAgent: row.user_agent } : {},
+			...row.ip ? { ip: row.ip } : {},
+			createdAt: Math.floor(row.created_at.getTime() / 1e3),
+			expiresAt: row.expires_at,
+			current: currentToken !== void 0 && row.token === currentToken
+		}));
+	};
+	return {
+		list,
+		/** Scoped by account as well as id, or one account could end another's session by guessing a number. */
+		revoke: async (accountId, sessionId) => {
+			return (await execute(db, `DELETE FROM ${t.session} WHERE id = ? AND account_id = ?`, [sessionId, accountId])).affectedRows > 0;
+		},
+		/** "Sign out everywhere else" — the one thing to do from a device you still trust after losing one you do not. */
+		revokeOthers: async (accountId, currentToken) => {
+			return (await execute(db, `DELETE FROM ${t.session} WHERE account_id = ? AND token <> ?`, [accountId, currentToken])).affectedRows;
+		},
+		/**
+		* Delete what has aged out. Nothing depends on this for correctness — an expired session is refused by its
+		* expiry, not by its absence — so it is housekeeping a deployment schedules, not a step in any request.
+		*/
+		purgeExpired: async () => {
+			const now = Math.floor(Date.now() / 1e3);
+			return (await execute(db, `DELETE FROM ${t.session}
+          WHERE expires_at < ? AND (refresh_expires_at IS NULL OR refresh_expires_at < ?)`, [now, now])).affectedRows;
+		}
+	};
+};
+//#endregion
+export { createSessionStore };

package/dist/modules/mysql/spaceTokens.d.ts

@@ -0,0 +1,11 @@
+import { Tables } from './config';
+import { Queryable } from './query';
+import { SpaceTokenAdapters } from '../../core/auth/spaceTokens';
+/**
+ * The stored half of a space credential.
+ *
+ * Note what is NOT here: nothing creates a row. The space-token API rotates, re-scopes and revokes credentials for
+ * a space that already has one, and issuing a space's first credential happens when the space itself is created —
+ * which is the deployment's event, not auth's. `createSpaceToken` on the store's `admin` surface does it.
+ */
+export declare const createSpaceTokenStore: (db: Queryable, t: Tables) => SpaceTokenAdapters;

package/dist/modules/mysql/spaceTokens.js

@@ -0,0 +1,59 @@
+import { execute, selectOne, selectRows } from "./query.js";
+//#region src/modules/mysql/spaceTokens.ts
+var COLUMNS = "id, token, scope, is_default, origins, expires_at, account_id, created_at, updated_at";
+var seconds = (value) => Math.floor(value.getTime() / 1e3);
+var toRecord = (row) => ({
+	id: row.id,
+	token: row.token,
+	scope: row.scope,
+	isDefault: row.is_default === 1,
+	origins: (row.origins ?? "").split(",").map((entry) => entry.trim()).filter(Boolean),
+	expiresAt: row.expires_at,
+	userId: row.account_id,
+	createdAt: seconds(row.created_at),
+	updatedAt: seconds(row.updated_at)
+});
+/**
+* The stored half of a space credential.
+*
+* Note what is NOT here: nothing creates a row. The space-token API rotates, re-scopes and revokes credentials for
+* a space that already has one, and issuing a space's first credential happens when the space itself is created —
+* which is the deployment's event, not auth's. `createSpaceToken` on the store's `admin` surface does it.
+*/
+var createSpaceTokenStore = (db, t) => ({
+	loadDefault: async (spaceId) => {
+		const row = await selectOne(db, `SELECT ${COLUMNS} FROM ${t.spaceToken} WHERE space_id = ? AND is_default = 1 LIMIT 1`, [spaceId]);
+		return row ? toRecord(row) : void 0;
+	},
+	/** Scoped by space as well as id: a token id from another space must not resolve, or it is an IDOR. */
+	find: async (spaceId, tokenId) => {
+		const row = await selectOne(db, `SELECT ${COLUMNS} FROM ${t.spaceToken} WHERE space_id = ? AND id = ? LIMIT 1`, [spaceId, tokenId]);
+		return row ? toRecord(row) : void 0;
+	},
+	list: async (spaceId) => {
+		return (await selectRows(db, `SELECT ${COLUMNS} FROM ${t.spaceToken} WHERE space_id = ? ORDER BY is_default DESC, id ASC`, [spaceId])).map(toRecord);
+	},
+	/**
+	* Only the fields the caller named. `origins` and `expiresAt` are each meaningful as "unchanged" and as "cleared",
+	* and a blanket UPDATE cannot tell those apart — it would wipe a domain list on every plain rotation.
+	*/
+	save: async (id, values) => {
+		const columns = ["token = ?"];
+		const params = [values.token];
+		if (values.origins !== void 0) {
+			columns.push("origins = ?");
+			params.push(values.origins.join(","));
+		}
+		if (values.expiresAt !== void 0) {
+			columns.push("expires_at = ?");
+			params.push(values.expiresAt);
+		}
+		params.push(id);
+		await execute(db, `UPDATE ${t.spaceToken} SET ${columns.join(", ")} WHERE id = ?`, params);
+	},
+	remove: async (id) => {
+		await execute(db, `DELETE FROM ${t.spaceToken} WHERE id = ?`, [id]);
+	}
+});
+//#endregion
+export { createSpaceTokenStore };

package/dist/modules/mysql/store.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/rsc/connectorRscData.d.ts

@@ -0,0 +1,25 @@
+import { ActionsModule } from '../actions';
+import { ActionLookups } from '../actions/types';
+import { ConnectorLookups } from '../connectors/resolver';
+import { SSRAdapters } from '@plitzi/sdk-shared';
+/**
+ * `getRscData`, built from the producers the server was already given — connectors, actions, or both.
+ *
+ * Every deployment that served server-driven elements wrote this same adapter: await the render payload, check the
+ * schema opted into RSC, then hand `resolveRscData` a resolver over the lookups — all of which are this package's
+ * own exports, assembled by the consumer only because nothing assembled them here. That made the lookups a thing
+ * you passed twice, once as config and once folded into an adapter, and put a copy of the enabled check in every
+ * deployment.
+ *
+ * Either half may be absent: a space whose server elements all name actions configures no connectors, and an
+ * element naming a producer this deployment does not have resolves to nothing rather than to an error — the same
+ * answer it gets for a connector the space never created.
+ *
+ * A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
+ */
+export declare const connectorRscData: (lookups?: ConnectorLookups, actions?: {
+    lookups: ActionLookups;
+    module: ActionsModule;
+}, 
+/** The deployment's per-element ceiling, when it set one. `resolveRscData` decides the default. */
+elementTimeoutMs?: number) => NonNullable<SSRAdapters["getRscData"]>;

package/dist/modules/rsc/connectorRscData.js

@@ -0,0 +1,51 @@
+import { createActionResolver } from "../actions/runtime/renderResolver.js";
+import { createConnectorResolver } from "../connectors/resolver.js";
+import { resolveRscData } from "./resolveRscData.js";
+//#region src/modules/rsc/connectorRscData.ts
+/**
+* `getRscData`, built from the producers the server was already given — connectors, actions, or both.
+*
+* Every deployment that served server-driven elements wrote this same adapter: await the render payload, check the
+* schema opted into RSC, then hand `resolveRscData` a resolver over the lookups — all of which are this package's
+* own exports, assembled by the consumer only because nothing assembled them here. That made the lookups a thing
+* you passed twice, once as config and once folded into an adapter, and put a copy of the enabled check in every
+* deployment.
+*
+* Either half may be absent: a space whose server elements all name actions configures no connectors, and an
+* element naming a producer this deployment does not have resolves to nothing rather than to an error — the same
+* answer it gets for a connector the space never created.
+*
+* A deployment that resolves server elements some other way still supplies its own `getRscData`, and that one wins.
+*/
+var connectorRscData = (lookups, actions, elementTimeoutMs) => {
+	const resolveConnector = lookups ? createConnectorResolver(lookups) : void 0;
+	const resolveAction = actions ? createActionResolver(actions.lookups, actions.module) : void 0;
+	/**
+	* An element names ONE producer, and which one decides how its data is fetched.
+	*
+	* A connector is the declarative read and stays the default; an action is the read a manifest cannot express.
+	* Checked in that order so an element carrying both — a connector element an author later pointed at an action —
+	* keeps resolving the way its page already renders, instead of silently changing under them.
+	*/
+	const resolveElement = async (context) => {
+		const attributes = context.element.attributes;
+		if (attributes.connector) return resolveConnector ? resolveConnector(context) : void 0;
+		return attributes.action && resolveAction ? resolveAction(context) : void 0;
+	};
+	return async ({ req, spaceId, environment, user, ids, loadOfflineData }) => {
+		const offlineData = await loadOfflineData();
+		if (!offlineData?.schema.rsc?.enabled) return {};
+		return resolveRscData({
+			schema: offlineData.schema,
+			req,
+			spaceId,
+			environment,
+			user,
+			ids,
+			resolveElement,
+			...elementTimeoutMs === void 0 ? {} : { timeoutMs: elementTimeoutMs }
+		});
+	};
+};
+//#endregion
+export { connectorRscData };

package/dist/modules/rsc/connectorRscData.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/rsc/handler.js

@@ -1,5 +1,6 @@
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildRscCacheKey } from "../../helpers/cache/keys.js";
+import { readDraftToken } from "../../core/previewToken.js";
 import { createOfflineDataLoader } from "../../helpers/offlineDataLoader.js";
 //#region src/modules/rsc/handler.ts
 /** Bounds the reflected location: it only ever selects one of this space's own pages, but it is still input. */
@@ -72,12 +73,24 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 	const ids = idsRaw ? idsRaw.split(",").filter(Boolean).slice(0, 50).map((id) => id.slice(0, 128)) : void 0;
 	const idsParam = ids?.join(",");
 	const pageRequest = withPageLocation(req);
+	/**
+	* Whether this refresh belongs to somebody looking at a draft.
+	*
+	* The page render already refuses to meter or cache a draft, and before draft SESSIONS existed that was the whole
+	* story: a one-shot token was spent by the render, so no refresh could ever carry one. A reusable token can, and a
+	* page left open in a preview asks for data on its own — so without this, iterating on unsaved work would be
+	* billed as live traffic and would show up on the live view as visitors nobody has.
+	*
+	* The token is not resolved here: whether the draft is still in the store decides what the PAGE renders, and a
+	* refresh that arrives a second after it expired is still part of the same preview.
+	*/
+	const previewing = readDraftToken(req) !== void 0;
 	const ttlMs = config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc;
 	const isAuthenticated = !!req.ctx.user;
-	const cacheControl = environment === "main" ? "no-store" : isAuthenticated ? `private, max-age=${Math.floor(ttlMs / 1e3)}` : `public, max-age=${Math.floor(ttlMs / 1e3)}`;
-	const cacheKey = environment !== "main" ? buildRscCacheKey(spaceId, environment, revision, req.ctx.user?.id, idsParam, req) : void 0;
+	const cacheControl = environment === "main" || previewing ? "no-store" : isAuthenticated ? `private, max-age=${Math.floor(ttlMs / 1e3)}` : `public, max-age=${Math.floor(ttlMs / 1e3)}`;
+	const cacheKey = environment !== "main" && !previewing ? buildRscCacheKey(spaceId, environment, revision, req.ctx.user?.id, idsParam, req) : void 0;
 	const cached = cacheKey ? cache?.get(cacheKey) : void 0;
-	await meterRsc(req, config, spaceId, environment, revision, !!cached);
+	if (!previewing) await meterRsc(req, config, spaceId, environment, revision, !!cached);
 	if (cached) {
 		res.setHeader("Content-Type", "application/json; charset=utf-8");
 		res.setHeader("Cache-Control", cacheControl);

package/dist/modules/rsc/matchRscPage.d.ts

@@ -0,0 +1,14 @@
+import { Schema, SSRUser } from '@plitzi/sdk-shared';
+export type RscPageMatch = {
+    pageId: string;
+    routeParams: Record<string, string | undefined>;
+};
+/**
+ * Which page of the schema a URL addresses, matched with the same matcher the client router uses — so the element
+ * set and the route params a read resolves against are the ones the browser will see.
+ *
+ * Its own function because two callers need the answer: the read itself, and the page render deciding beforehand
+ * whether there is anything on this page worth asking an adapter for. `undefined` when the URL matches no page,
+ * which is also nothing to resolve.
+ */
+export declare const matchRscPage: (schema: Schema, path: string, user: SSRUser | undefined) => RscPageMatch | undefined;

package/dist/modules/rsc/matchRscPage.js

@@ -0,0 +1,26 @@
+import { getPaths, matchRoutePath } from "@plitzi/sdk-shared/navigation";
+//#region src/modules/rsc/matchRscPage.ts
+/**
+* Which page of the schema a URL addresses, matched with the same matcher the client router uses — so the element
+* set and the route params a read resolves against are the ones the browser will see.
+*
+* Its own function because two callers need the answer: the read itself, and the page render deciding beforehand
+* whether there is anything on this page worth asking an adapter for. `undefined` when the URL matches no page,
+* which is also nothing to resolve.
+*/
+var matchRscPage = (schema, path, user) => {
+	const pages = schema.pages.reduce((acum, pageId) => {
+		const page = schema.flat[pageId];
+		if (page) acum[pageId] = page;
+		return acum;
+	}, {});
+	const paths = getPaths(pages, schema.pageFolders, !!user);
+	const { pageId, pathMatch } = matchRoutePath(paths, path, !!user);
+	if (!pageId) return;
+	return {
+		pageId,
+		routeParams: pathMatch?.params ?? {}
+	};
+};
+//#endregion
+export { matchRscPage };