@c9up/station 0.1.14 → 0.1.16

package/src/columns.ts

@@ -0,0 +1,136 @@
+/**
+ * Which columns each admin view shows and which ones a write may touch.
+ *
+ * Two rules keep secrets out of the admin by default:
+ *  - a column the model hides from serialization (`serializeAs: null`, the
+ *    marker `toJSON` honours) or whose name says it holds a secret is neither
+ *    rendered nor writable unless the resource names it explicitly;
+ *  - the writable set is an allow-list: `editable` when the resource declares
+ *    one, otherwise every non-secret, non-framework column the form shows.
+ */
+
+import type { ColumnMetadata } from "@c9up/atlas";
+import type { Resource } from "./types.js";
+
+/** Column names that hold credentials — hidden, never flashed, never echoed. */
+export const SENSITIVE_KEY_RE = /password|passwd|secret|token|apikey/i;
+
+const TIMESTAMP_PROPERTY_KEYS: ReadonlySet<string> = new Set([
+	"createdAt",
+	"updatedAt",
+	"deletedAt",
+]);
+const TIMESTAMP_COLUMN_NAMES: ReadonlySet<string> = new Set([
+	"created_at",
+	"updated_at",
+	"deleted_at",
+]);
+
+export function isSecretColumn(c: ColumnMetadata): boolean {
+	return c.serializeAs === null || SENSITIVE_KEY_RE.test(c.propertyKey);
+}
+
+/**
+ * Columns the framework owns: the primary key, managed timestamps (flagged
+ * `autoCreate`/`autoUpdate` or named by convention), relations and the
+ * soft-delete column. Never writable from a request body.
+ */
+export function isFrameworkManaged(
+	c: ColumnMetadata,
+	pkColumn: string,
+	autoManaged: ReadonlySet<string>,
+	excludedProps: ReadonlySet<string>,
+): boolean {
+	if (c.propertyKey === pkColumn) return true;
+	if (autoManaged.has(c.propertyKey)) return true;
+	if (TIMESTAMP_PROPERTY_KEYS.has(c.propertyKey)) return true;
+	const snake = c.propertyKey.replace(/([A-Z])/g, "_$1").toLowerCase();
+	if (TIMESTAMP_COLUMN_NAMES.has(snake)) return true;
+	return excludedProps.has(c.propertyKey);
+}
+
+function byName(
+	columns: ReadonlyArray<ColumnMetadata>,
+	names: ReadonlyArray<string>,
+	resource: Resource,
+	option: string,
+): ColumnMetadata[] {
+	return names.map((name) => {
+		const column = columns.find((c) => c.propertyKey === name);
+		if (column === undefined) {
+			throw new Error(
+				`[station] defineResource '${resource.name}': ${option} names '${name}', which is not a column of ${resource.entity.name}.`,
+			);
+		}
+		return column;
+	});
+}
+
+/**
+ * The columns a list or show view renders: the declared allow-list in its
+ * order, or every non-secret column.
+ */
+export function viewColumns(
+	columns: ReadonlyArray<ColumnMetadata>,
+	allow: ReadonlyArray<string> | undefined,
+	resource: Resource,
+	option: string,
+): ReadonlyArray<ColumnMetadata> {
+	if (allow !== undefined) return byName(columns, allow, resource, option);
+	return columns.filter((c) => !isSecretColumn(c));
+}
+
+/**
+ * The columns a create/edit body may set, which are also the form's fields.
+ * An explicit `editable` naming a framework-owned or form-hidden column is a
+ * contradiction and fails at mount rather than being silently trimmed.
+ */
+export function editableColumns(
+	columns: ReadonlyArray<ColumnMetadata>,
+	resource: Resource,
+	pkColumn: string,
+	autoManaged: ReadonlySet<string>,
+	excludedProps: ReadonlySet<string>,
+): ReadonlyArray<ColumnMetadata> {
+	if (resource.editable !== undefined) {
+		const picked = byName(columns, resource.editable, resource, "editable");
+		for (const c of picked) {
+			if (isFrameworkManaged(c, pkColumn, autoManaged, excludedProps)) {
+				throw new Error(
+					`[station] defineResource '${resource.name}': editable names '${c.propertyKey}', which the framework manages (primary key, timestamp, relation or soft-delete column).`,
+				);
+			}
+			if (resource.formFields[c.propertyKey]?.hidden === true) {
+				throw new Error(
+					`[station] defineResource '${resource.name}': editable names '${c.propertyKey}', which formFields hides.`,
+				);
+			}
+		}
+		return picked;
+	}
+	return columns.filter(
+		(c) =>
+			!isFrameworkManaged(c, pkColumn, autoManaged, excludedProps) &&
+			!isSecretColumn(c) &&
+			resource.formFields[c.propertyKey]?.hidden !== true,
+	);
+}
+
+/**
+ * Editable columns whose stored value is never sent back to the browser: the
+ * form renders them empty and an empty submission leaves them unchanged.
+ */
+export function writeOnlyKeys(
+	editable: ReadonlyArray<ColumnMetadata>,
+	resource: Resource,
+): ReadonlySet<string> {
+	return new Set(
+		editable
+			.filter(
+				(c) =>
+					isSecretColumn(c) ||
+					resource.formFields[c.propertyKey]?.inputType === "password",
+			)
+			.map((c) => c.propertyKey),
+	);
+}

package/src/defineResource.ts

@@ -17,6 +17,26 @@ function isResourceAction(value: unknown): value is ResourceAction {
 	return typeof value === "string" && ACTION_LOOKUP.has(value);
 }
 
+/**
+ * Shape-check a column allow-list. Whether each name is a real column is
+ * checked at mount, where the entity metadata is known.
+ */
+function columnList(
+	value: ReadonlyArray<string> | undefined,
+	option: string,
+): ReadonlyArray<string> | undefined {
+	if (value === undefined) return undefined;
+	if (
+		!Array.isArray(value) ||
+		!value.every((v) => typeof v === "string" && v.length > 0)
+	) {
+		throw new TypeError(
+			`[station] defineResource: '${option}' must be an array of column names`,
+		);
+	}
+	return Object.freeze([...value]);
+}
+
 /**
  * Build a frozen `Resource` from a developer's declaration.
  *
@@ -89,6 +109,14 @@ export function defineResource<T>(options: ResourceOptions<T>): Resource<T> {
 		formFields[field] = override;
 	}
 
+	const list = Object.freeze({
+		columns: columnList(options.list?.columns, "list.columns"),
+	});
+	const show = Object.freeze({
+		columns: columnList(options.show?.columns, "show.columns"),
+	});
+	const editable = columnList(options.editable, "editable");
+
 	// 54.6: audit sink shape-check — if provided, must be callable. No
 	// extra validation; the sink is exercised lazily on first write.
 	let audit: AuditSink | undefined;
@@ -118,8 +146,12 @@ export function defineResource<T>(options: ResourceOptions<T>): Resource<T> {
 		label,
 		actions: orderedActions,
 		audit,
+		auditSecrets: options.auditSecrets === true,
 		onAuditError,
 		formFields: Object.freeze(formFields),
+		list,
+		show,
+		editable,
 	};
 
 	return Object.freeze(resource);

package/src/index.ts

@@ -2,6 +2,10 @@ import "./augmentations.js";
 
 export { kebabCase, pluralise, titleCase } from "./casing.js";
 export { defineResource } from "./defineResource.js";
+export type {
+	StationLoginLimiter,
+	StationLoginRateLimitConfig,
+} from "./loginLimiter.js";
 export { ResourceRegistry } from "./ResourceRegistry.js";
 export type { StationAppContext, StationConfig } from "./StationProvider.js";
 export { default as StationProvider } from "./StationProvider.js";
@@ -23,4 +27,7 @@ export {
 	type Resource,
 	type ResourceAction,
 	type ResourceOptions,
+	type SecurityAuditAction,
+	type SecurityAuditEvent,
+	type SecurityAuditSink,
 } from "./types.js";

package/src/loginLimiter.ts

@@ -0,0 +1,110 @@
+/**
+ * Brute-force throttle for `POST /admin/login`.
+ *
+ * The contract is the one `@c9up/warden`'s `AuthRateLimiter` exposes, so an
+ * application passes its own instance (a Redis-backed one in a cluster) as
+ * `station.loginRateLimit.limiter`. Station cannot construct warden's class —
+ * it never imports `@c9up/warden` — so the default is this in-process copy of
+ * the same semantics: one atomic count per key BEFORE the credential check,
+ * keys `ip:<ip>` and `id:<identifier>`, a bounded store that refuses new keys
+ * rather than forgiving live windows when it is full.
+ */
+
+export interface StationLoginDecision {
+	allowed: boolean;
+	retryAfterSeconds: number;
+}
+
+/** Structural slice of warden's `AuthRateLimiter`. */
+export interface StationLoginLimiter {
+	attempt(...keys: string[]): Promise<StationLoginDecision>;
+	clear(...keys: string[]): Promise<void>;
+}
+
+export interface StationLoginRateLimitConfig {
+	/** Attempts allowed per window, per key. Default 5. */
+	maxAttempts?: number;
+	/** Window length in seconds. Default 900 (15 min). */
+	windowSeconds?: number;
+	/**
+	 * The limiter to use instead of the in-process default — e.g. warden's
+	 * `AuthRateLimiter` over a `RedisAttemptStore`, so a lockout holds on every
+	 * instance. `maxAttempts`/`windowSeconds` then belong to that limiter.
+	 */
+	limiter?: StationLoginLimiter;
+}
+
+/** Same keys as warden's `AuthRateLimiter.loginKeys`, so a shared limiter shares budgets. */
+export function loginKeys(ip: string, identifier: string): string[] {
+	return [`ip:${ip.trim()}`, `id:${identifier.trim().toLowerCase()}`];
+}
+
+const MAX_KEYS = 100_000;
+
+export class MemoryLoginLimiter implements StationLoginLimiter {
+	readonly #maxAttempts: number;
+	readonly #windowMs: number;
+	readonly #entries = new Map<string, { count: number; resetAt: number }>();
+
+	constructor(maxAttempts = 5, windowSeconds = 900) {
+		this.#maxAttempts = positiveInteger("maxAttempts", maxAttempts);
+		this.#windowMs = positiveInteger("windowSeconds", windowSeconds) * 1000;
+	}
+
+	async attempt(...keys: string[]): Promise<StationLoginDecision> {
+		const now = Date.now();
+		let highest = 0;
+		let retryMs = 0;
+		for (const key of keys) {
+			const counted = this.#increment(key, now);
+			if (counted.count > highest) {
+				highest = counted.count;
+				retryMs = counted.resetAt - now;
+			}
+		}
+		return {
+			allowed: highest <= this.#maxAttempts,
+			retryAfterSeconds: Math.max(1, Math.ceil(retryMs / 1000)),
+		};
+	}
+
+	async clear(...keys: string[]): Promise<void> {
+		for (const key of keys) this.#entries.delete(key);
+	}
+
+	#increment(key: string, now: number): { count: number; resetAt: number } {
+		let entry = this.#entries.get(key);
+		if (entry === undefined || entry.resetAt <= now) {
+			this.#entries.delete(key);
+			const earliest = this.#makeRoom(now);
+			// Full of live windows: the keys are attacker-chosen, so evicting
+			// one would forgive a victim's lockout. Refuse the new key instead.
+			if (earliest !== undefined) {
+				return { count: Number.POSITIVE_INFINITY, resetAt: earliest };
+			}
+			entry = { count: 0, resetAt: now + this.#windowMs };
+			this.#entries.set(key, entry);
+		}
+		entry.count++;
+		return entry;
+	}
+
+	#makeRoom(now: number): number | undefined {
+		if (this.#entries.size < MAX_KEYS) return undefined;
+		let earliest = Number.POSITIVE_INFINITY;
+		for (const [key, entry] of this.#entries) {
+			if (entry.resetAt <= now) this.#entries.delete(key);
+			else earliest = Math.min(earliest, entry.resetAt);
+		}
+		return this.#entries.size < MAX_KEYS ? undefined : earliest;
+	}
+}
+
+function positiveInteger(field: string, value: number): number {
+	if (!Number.isSafeInteger(value) || value <= 0) {
+		throw new Error(
+			`[station] station.loginRateLimit.${field} must be a positive whole number, got ${String(value)}`,
+		);
+	}
+	return value;
+}

package/src/types.ts

@@ -21,11 +21,57 @@ export interface AuditEvent {
 	readonly userId?: unknown;
 	readonly before?: Readonly<Record<string, unknown>>;
 	readonly after?: Readonly<Record<string, unknown>>;
+	/**
+	 * On an edit, the secret columns whose value changed. Their values are
+	 * replaced with `"[redacted]"` in `before`/`after` (unless the resource
+	 * sets `auditSecrets`), so this is how a password change stays visible.
+	 */
+	readonly redactedChanges?: ReadonlyArray<string>;
+	/** Client IP of the request that made the change. */
+	readonly ip?: string;
+	readonly userAgent?: string;
+	/** `X-Request-Id` of that request, when the proxy or client set one. */
+	readonly requestId?: string;
 	readonly at: Date;
 }
 
 export type AuditSink = (event: AuditEvent) => void | Promise<void>;
 
+/** What a {@link SecurityAuditEvent} records. */
+export type SecurityAuditAction =
+	| "login"
+	| "login_failed"
+	| "login_throttled"
+	| "logout"
+	| "denied"
+	| "csrf_denied";
+
+/**
+ * A sign-in, sign-out or refusal on the admin surface, sent to the
+ * `station.audit` sink so brute force and probing show up in the trail.
+ */
+export interface SecurityAuditEvent {
+	readonly action: SecurityAuditAction;
+	/** The authenticated user, when one is known. */
+	readonly userId?: unknown;
+	/** The email a sign-in attempt submitted. */
+	readonly identifier?: string;
+	/** For `denied` on a resource action: its slug, action and permission. */
+	readonly resource?: string;
+	readonly resourceAction?: ResourceAction;
+	/** For `denied`: the permission or role that was missing. */
+	readonly permission?: string;
+	readonly path?: string;
+	readonly ip?: string;
+	readonly userAgent?: string;
+	readonly requestId?: string;
+	readonly at: Date;
+}
+
+export type SecurityAuditSink = (
+	event: SecurityAuditEvent,
+) => void | Promise<void>;
+
 /**
  * Per-field override for the auto-generated form (Story 54.5). Station
  * infers the form from the entity's `@Column` metadata; consumers can
@@ -33,7 +79,10 @@ export type AuditSink = (event: AuditEvent) => void | Promise<void>;
  * others.
  */
 export interface FormFieldOverride {
-	/** Hide the field from the form entirely (still rendered on show). */
+	/**
+	 * Hide the field from the form. A hidden field is not writable either: a
+	 * body carrying it is ignored and a hidden boolean keeps its stored value.
+	 */
 	hidden?: boolean;
 	/** Override the rendered `<input type>`. */
 	inputType?:
@@ -53,6 +102,15 @@ export interface FormFieldOverride {
 	required?: boolean;
 }
 
+/** Per-view options for the list and show pages. */
+export interface ResourceViewOptions {
+	/**
+	 * The columns the view renders, in this order. When omitted, every column
+	 * except secrets (`serializeAs: null` or a credential-like name) is shown.
+	 */
+	columns?: ReadonlyArray<string>;
+}
+
 export interface ResourceOptions<TEntity> {
 	/** Entity class (Atlas `@Entity()`-decorated constructor). */
 	entity: new (
@@ -70,6 +128,13 @@ export interface ResourceOptions<TEntity> {
 	 * so apps don't silently lose audit visibility.
 	 */
 	audit?: AuditSink;
+	/**
+	 * Hand secret column values (`serializeAs: null` or a credential-like
+	 * name) to the audit sink as they are. Off by default: they are replaced
+	 * with `"[redacted]"`, because audit logs usually land in a less protected
+	 * store than the table they describe.
+	 */
+	auditSecrets?: boolean;
 	/**
 	 * Invoked when the audit sink throws (Story 54.6 hardening, retro
 	 * 2026-06-01). The mutation has already committed, so this is a
@@ -86,6 +151,18 @@ export interface ResourceOptions<TEntity> {
 	 * the inferred defaults.
 	 */
 	formFields?: Readonly<Record<string, FormFieldOverride>>;
+	/** Columns of the list page. */
+	list?: ResourceViewOptions;
+	/** Columns of the show page. */
+	show?: ResourceViewOptions;
+	/**
+	 * The columns a create/edit may set, and the fields the form shows. When
+	 * omitted: every column except the framework-managed ones, secrets
+	 * (`serializeAs: null` or a credential-like name) and `formFields` marked
+	 * `hidden`. A secret listed here is write-only: the form renders it empty
+	 * and an empty submission keeps the stored value.
+	 */
+	editable?: ReadonlyArray<string>;
 }
 
 export interface Resource<TEntity = unknown> {
@@ -101,8 +178,16 @@ export interface Resource<TEntity = unknown> {
 	readonly actions: ReadonlyArray<ResourceAction>;
 	/** Optional audit sink (Story 54.6). */
 	readonly audit?: AuditSink;
+	/** Whether audit snapshots keep secret column values. */
+	readonly auditSecrets: boolean;
 	/** Optional audit-failure observability hook (Story 54.6 hardening). */
 	readonly onAuditError?: (event: AuditEvent, error: unknown) => void;
 	/** Frozen per-field overrides for the inferred form (Story 54.5). */
 	readonly formFields: Readonly<Record<string, FormFieldOverride>>;
+	/** Frozen list-page options. */
+	readonly list: Readonly<ResourceViewOptions>;
+	/** Frozen show-page options. */
+	readonly show: Readonly<ResourceViewOptions>;
+	/** Frozen editable allow-list; undefined means the default set. */
+	readonly editable?: ReadonlyArray<string>;
 }

package/src/views/form.ts

@@ -48,6 +48,12 @@ export interface FormPageInput {
 	values?: Readonly<Record<string, unknown>>;
 	/** Validation errors keyed by column propertyKey. */
 	errors?: Readonly<Record<string, string>>;
+	/**
+	 * Fields rendered empty whatever their stored or submitted value (secrets).
+	 * A `password` input is always treated this way: a credential, even a hash,
+	 * is never shipped back inside the page.
+	 */
+	writeOnly?: ReadonlySet<string>;
 	/**
 	 * Whether the host has a CSRF token in the per-request store. When true the
 	 * template emits `{{ csrfField() }}`; the handler derives it from
@@ -87,8 +93,16 @@ export type FormViewModel = {
 };
 
 export function buildFormViewModel(input: FormPageInput): FormViewModel {
-	const { resource, columns, pkColumn, row, values, errors, csrfEnabled } =
-		input;
+	const {
+		resource,
+		columns,
+		pkColumn,
+		row,
+		values,
+		errors,
+		csrfEnabled,
+		writeOnly,
+	} = input;
 	const isEdit = row !== undefined;
 	const slug = encodeURIComponent(resource.name);
 	const id = isEdit ? String(row[pkColumn] ?? "") : "";
@@ -108,7 +122,13 @@ export function buildFormViewModel(input: FormPageInput): FormViewModel {
 			(c) => !shouldSkipColumn(c, pkColumn, resource.formFields[c.propertyKey]),
 		)
 		.map((c) =>
-			buildField(c, values ?? row, errors, resource.formFields[c.propertyKey]),
+			buildField(
+				c,
+				values ?? row,
+				errors,
+				resource.formFields[c.propertyKey],
+				writeOnly?.has(c.propertyKey) === true,
+			),
 		);
 
 	return {
@@ -128,10 +148,12 @@ function buildField(
 	source: Readonly<Record<string, unknown>> | undefined,
 	errors: Readonly<Record<string, string>> | undefined,
 	override: FormFieldOverride | undefined,
+	writeOnly: boolean,
 ): FormField {
 	const inputType = override?.inputType ?? inferInputType(c);
 	const name = c.propertyKey;
-	const rawValue = source?.[name];
+	const rawValue =
+		writeOnly || inputType === "password" ? undefined : source?.[name];
 	const isCheckbox = inputType === "checkbox";
 	const value =
 		rawValue === undefined || rawValue === null ? "" : String(rawValue);

package/src/views/login.ts

@@ -7,8 +7,8 @@
  *
  * Pure `(input) => LoginViewModel` builder (Story 57.3): every value reaches
  * HTML through `templates/login.inker`'s `{{ }}` auto-escape (the retired
- * `escape.ts` no longer runs here), so a tampered `?error=…` query parameter
- * cannot smuggle markup into the page. The CSRF hidden input is emitted by
+ * `escape.ts` no longer runs here). `error` only ever carries a message
+ * Station produced; the handler never reads it from the URL. The CSRF hidden input is emitted by
  * inker's canonical `{{ csrfField() }}` helper, guarded by the precomputed
  * `csrfEnabled` boolean.
  */