@fabrika/app 0.3.3 → 0.4.1

package/src/contract/declaration.ts

@@ -0,0 +1,310 @@
+// A contract as plain data, with each schema of type `S`: a zod schema in the evaluated contract, a `SchemaShape`
+// once described. `buildArtifact` reads only this shape, so a reader that produces it from source (B1) and
+// `compileContract` normalize through the same code.
+
+import type { ChallengeProvider, CspSource, MailTemplate, RpcCaller } from '@fabrika/auth-core'
+
+export interface ContractDeclaration<S> {
+	readonly app: string
+	readonly dimensions: Readonly<Record<string, DimensionDeclaration>>
+	readonly actions: Readonly<Record<string, string>>
+	readonly roles: Readonly<Record<string, RoleDeclaration>>
+	readonly mounts: Readonly<Record<string, MountDeclaration<S>>>
+	readonly files: Readonly<Record<string, FilesDeclaration>>
+	readonly jobs: Readonly<Record<string, CronDeclaration>>
+	readonly exports: Readonly<Record<string, ExportDeclaration<S>>>
+	readonly imports: Readonly<Record<string, ImportDeclaration>>
+	readonly csp: CspDeclaration
+	/** A language IAM speaks; `buildArtifact` refuses another value. */
+	readonly locale?: string
+	readonly displayName?: string
+	/** Message kind → locale → template; `buildArtifact` refuses an unknown kind or locale and a bad template. */
+	readonly mail?: Readonly<Record<string, Readonly<Record<string, MailTemplate>>>>
+	/** The actions that manage and list the application's own people. */
+	readonly members?: { readonly manage: string; readonly list: string }
+	/** `'labels'` only; `buildArtifact` refuses another value, and refuses it without `members`. */
+	readonly directory?: string
+}
+
+/**
+ * The keys of the object `defineContract`'s callback returns that are sections, not mounts. Every other key is a
+ * mount. A reader of source splits the object the same way.
+ */
+export const SURFACE_SECTIONS = ['files', 'jobs', 'exports', 'imports', 'csp'] as const
+
+export type SurfaceSection = (typeof SURFACE_SECTIONS)[number]
+
+/**
+ * The option fields each builder takes, and the fields it sets itself. A builder copies only its option fields and
+ * records every other key of its options in `unknownOptions`, so an option can never replace what the builder set;
+ * `buildArtifact` refuses a non-empty `unknownOptions`. A reader of source fills it the same way.
+ */
+export type Builder = 'procedure' | 'rpc' | 'link' | 'spa' | 'form' | 'webhook' | 'files' | 'cron' | 'export' | 'attachment'
+
+export interface BuilderFields {
+	readonly options: readonly string[]
+	readonly owned: readonly string[]
+}
+
+export const BUILDER_FIELDS: Readonly<Record<Builder, BuilderFields>> = {
+	procedure: { options: ['input', 'output', 'access'], owned: ['~kind', 'type'] },
+	rpc: { options: ['callers'], owned: ['kind', 'prefix', 'procedures'] },
+	link: { options: ['spa', 'dimension', 'grants', 'issuedBy', 'maxDays', 'procedures'], owned: ['kind', 'prefix'] },
+	spa: { options: ['dir', 'access', 'public'], owned: ['kind', 'prefix'] },
+	form: { options: ['input', 'appendTo', 'maxBytes', 'rate', 'honeypot', 'challenge', 'then'], owned: ['kind', 'path'] },
+	webhook: { options: ['scheme', 'boundTo', 'actions', 'input', 'maxBytes'], owned: ['kind', 'path'] },
+	files: { options: ['owner', 'read', 'write', 'delete', 'maxBytes', 'types', 'maxPerOwner', 'link', 'scan'], owned: ['kind'] },
+	cron: { options: ['actions', 'scope', 'timeout', 'retries'], owned: ['kind', 'schedule'] },
+	export: { options: ['version', 'consumers', 'audience', 'procedures'], owned: ['kind'] },
+	attachment: { options: ['format', 'filename', 'row', 'maxBytes', 'maxRows'], owned: [] },
+}
+
+/** The keys of `options` that are not `builder`'s option fields. */
+export function unknownOptions(options: object, builder: Builder): string[] {
+	const declared = BUILDER_FIELDS[builder].options
+	return Object.keys(options).filter((key) => !declared.includes(key))
+}
+
+/**
+ * The off-road fields a site of the staged kit declares beside its builder's options. The kit copies them into
+ * `declared`; `buildArtifact` checks which of them the site may carry.
+ */
+export const DECLARED_FIELDS = ['sql', 'unscoped', 'connect', 'issues'] as const
+
+/** The keys of a kit site's `options` that are neither `builder`'s option fields nor a declared field. */
+export function kitUnknownOptions(options: object, builder: Builder): string[] {
+	return unknownOptions(options, builder).filter((key) => !DECLARED_FIELDS.some((field) => field === key))
+}
+
+/**
+ * The reach a site of the staged kit declares, as written (`sql`, `unscoped`, `connect`, `issues`): only the fields
+ * its options carry. Unchecked here: the static reader copies what the source holds, and `buildArtifact` parses it.
+ */
+export interface DeclaredDeclaration {
+	readonly sql?: unknown
+	readonly unscoped?: unknown
+	readonly connect?: unknown
+	readonly issues?: unknown
+}
+
+/** The declared fields of a kit site's options, each one only when the options carry it. */
+export function declaredOf(options: DeclaredDeclaration): DeclaredDeclaration {
+	return {
+		...(options.sql === undefined ? {} : { sql: options.sql }),
+		...(options.unscoped === undefined ? {} : { unscoped: options.unscoped }),
+		...(options.connect === undefined ? {} : { connect: options.connect }),
+		...(options.issues === undefined ? {} : { issues: options.issues }),
+	}
+}
+
+/** Option keys outside the builder's option fields; `buildArtifact` refuses any. */
+interface OptionsRecord {
+	readonly unknownOptions?: readonly string[]
+}
+
+export interface DimensionDeclaration {
+	readonly in?: string
+	readonly creator?: string
+	readonly members?: { readonly manage: string; readonly list: string }
+	/** `'labels'` only; `buildArtifact` refuses another value. */
+	readonly directory?: string
+}
+
+export interface RoleDeclaration {
+	readonly grants: readonly string[]
+	readonly member?: { readonly scope: string; readonly assignableBy: readonly string[] }
+	/** `true` only; `buildArtifact` refuses another value, and refuses it on a role without `member`. */
+	readonly external?: boolean
+}
+
+export type AccessDeclaration =
+	| { readonly member: true }
+	| { readonly action: string; readonly over: string }
+	| { readonly action: string; readonly in: string; readonly from: string }
+	| { readonly action: string; readonly on: string; readonly from: string }
+	| { readonly action: string; readonly creates: string }
+	| { readonly action: string; readonly app: true }
+
+/**
+ * An export procedure's access: an action in a dimension, never `member`, because the consumer's key holds exactly the
+ * actions, and never `app`, because a v1 export declares one dimension.
+ */
+export type ExportAccessDeclaration = Exclude<AccessDeclaration, { readonly member: true } | { readonly app: true }>
+
+export interface LinkAccessDeclaration {
+	readonly action: string
+}
+
+/** `{ public: true }` serves the SPA to anyone, with no session: an anonymous `public-spa` row. */
+export type SpaAccessDeclaration =
+	| { readonly member: true }
+	| { readonly action: string; readonly over: string }
+	| { readonly action: string; readonly app: true }
+	| { readonly public: true }
+
+export type ProcedureType = 'query' | 'mutation'
+
+export interface ProcedureDeclaration<S, Access = AccessDeclaration> extends OptionsRecord {
+	readonly '~kind': 'procedure'
+	readonly type: ProcedureType
+	/** `null` when the procedure takes no input. */
+	readonly input: S | null
+	readonly output: S
+	readonly access: Access
+	/** What a procedure of the staged kit declares off the paved road; a `defineContract` procedure has none. */
+	readonly declared?: unknown
+	/**
+	 * Set by `describeContract` when the output is an `attachment()`: the procedure answers a file, and its described
+	 * `output` is the array of rows the handler returns.
+	 */
+	readonly attachment?: AttachmentDeclaration
+}
+
+/**
+ * The file an `attachment()` output declares beside its row schema, as written; `buildArtifact` checks each field and
+ * applies the default `maxRows`.
+ */
+export interface AttachmentDeclaration extends OptionsRecord {
+	readonly format: string
+	readonly filename: string
+	readonly maxBytes: number
+	readonly maxRows?: number
+}
+
+/** Procedures by name; a nested object groups them, and the path joins the names with `.`. */
+export interface ProcedureTreeDeclaration<S, Access = AccessDeclaration> {
+	readonly [name: string]: ProcedureDeclaration<S, Access> | ProcedureTreeDeclaration<S, Access>
+}
+
+export type MountDeclaration<S> =
+	| RpcMountDeclaration<S>
+	| LinkMountDeclaration<S>
+	| SpaMountDeclaration
+	| HealthMountDeclaration
+	| FormMountDeclaration<S>
+	| WebhookMountDeclaration<S>
+
+export interface RpcMountDeclaration<S> extends OptionsRecord {
+	readonly kind: 'rpc'
+	readonly prefix: string
+	readonly callers: readonly [RpcCaller, ...RpcCaller[]]
+	readonly procedures: ProcedureTreeDeclaration<S>
+}
+
+export interface LinkMountDeclaration<S> extends OptionsRecord {
+	readonly kind: 'link'
+	readonly prefix: string
+	readonly spa: string
+	readonly dimension: string
+	readonly grants: readonly string[]
+	readonly issuedBy: string
+	readonly maxDays: number
+	readonly procedures: ProcedureTreeDeclaration<S, LinkAccessDeclaration>
+}
+
+export interface SpaMountDeclaration extends OptionsRecord {
+	readonly kind: 'spa'
+	readonly prefix: string
+	readonly dir: string
+	readonly access: SpaAccessDeclaration
+	/** Application variables whose values the mount's pages read from `<prefix>/__fabrika-config.json`. */
+	readonly public?: readonly string[]
+}
+
+export interface HealthMountDeclaration {
+	readonly kind: 'health'
+	readonly path: string
+}
+
+export interface FormMountDeclaration<S> extends OptionsRecord {
+	readonly kind: 'form'
+	readonly path: string
+	readonly input: S
+	readonly appendTo: string
+	readonly maxBytes?: number
+	/** Submissions per minute from one client and accepted in all; `FORM_LIMITS` holds the defaults. */
+	readonly rate?: { readonly perClient?: number; readonly perForm?: number }
+	/** An input field that must stay empty. */
+	readonly honeypot?: string
+	/**
+	 * A challenge verified on the server; `secret` names the application variable that holds the provider's secret,
+	 * `siteKey` the one that holds the widget's public site key.
+	 */
+	readonly challenge?: { readonly provider: ChallengeProvider; readonly secret: string; readonly siteKey?: string }
+	/** The cron job of the contract that each accepted submission kicks. */
+	readonly then?: string
+}
+
+export interface WebhookMountDeclaration<S> extends OptionsRecord {
+	readonly kind: 'webhook'
+	readonly path: string
+	readonly scheme: 'github-sha256'
+	/** A dimension, or `app` for the whole application. */
+	readonly boundTo: string
+	readonly actions: readonly string[]
+	readonly input: S
+	readonly maxBytes?: number
+	/** What a webhook of the staged kit declares off the paved road. */
+	readonly declared?: unknown
+}
+
+export interface FilesDeclaration extends OptionsRecord {
+	readonly kind: 'files'
+	readonly owner: string
+	readonly read: string
+	readonly write: string
+	readonly delete: string
+	readonly maxBytes: number
+	readonly types: readonly string[]
+	readonly maxPerOwner?: number
+	/** `true`: every link mount bound to the owner's dimension serves the files; a list: the named link mounts only. */
+	readonly link?: boolean | readonly string[]
+	/** Every upload waits `quarantined` until the scan pass gives it a clean verdict. */
+	readonly scan?: boolean
+}
+
+export interface CronDeclaration extends OptionsRecord {
+	readonly kind: 'cron'
+	readonly schedule: string
+	readonly actions: readonly string[]
+	/** A dimension, or `app` for the whole application. */
+	readonly scope: string
+	readonly timeout?: string
+	readonly retries?: number
+	/** What a job of the staged kit declares off the paved road. */
+	readonly declared?: unknown
+}
+
+export interface ExportDeclaration<S> extends OptionsRecord {
+	readonly kind: 'export'
+	readonly version: number
+	readonly consumers: readonly string[]
+	readonly audience: string
+	readonly procedures: ProcedureTreeDeclaration<S, ExportAccessDeclaration>
+}
+
+export interface ImportDeclaration {
+	readonly app: string
+	readonly export: string
+	readonly version: number
+	readonly digest: string
+	readonly procedures: readonly string[]
+	readonly usedBy: readonly string[]
+	readonly timeoutMs?: number
+}
+
+export interface CspDeclaration {
+	readonly connectSrc?: readonly CspSource[]
+	readonly imgSrc?: readonly CspSource[]
+	readonly frameAncestors?: readonly CspSource[]
+	readonly scriptSrc?: readonly CspSource[]
+	readonly frameSrc?: readonly CspSource[]
+	readonly styleSrc?: readonly CspSource[]
+	readonly fontSrc?: readonly CspSource[]
+}
+
+export function isProcedure<S, Access>(
+	node: ProcedureDeclaration<S, Access> | ProcedureTreeDeclaration<S, Access>,
+): node is ProcedureDeclaration<S, Access> {
+	return node['~kind'] === 'procedure'
+}

package/src/contract/defaults.ts

@@ -0,0 +1,161 @@
+// Every default and every generated path of the contract, in one place. `buildArtifact` applies them; a reader of
+// source reaches them only through `buildArtifact`, so both producers emit the same artifact.
+
+import type { BodyAdmission, ChallengeProvider } from '@fabrika/auth-core'
+
+export const CONTRACT_DEFAULTS = {
+	/** A failed job run is not retried unless the job asks for it: a retry repeats work. */
+	jobRetries: 0,
+	formMaxBytes: 16 * 1024,
+	webhookMaxBytes: 1024 * 1024,
+	fileMaxPerOwner: null,
+	fileLink: false,
+	importTimeoutMs: null,
+} as const
+
+/**
+ * A form's admission, per minute and shared by every instance of the application: the requests it admits from one
+ * client (`X-Fabrika-Client-Ip`) and the submissions it accepts in all. A form may declare its own `rate`, up to
+ * `maxPerMinute` each.
+ */
+export const FORM_LIMITS = {
+	perClient: 10,
+	perForm: 100,
+	maxPerMinute: 10_000,
+} as const
+
+/** The input field that carries a form's challenge token; a form with a challenge declares it as a string. */
+export const FORM_CHALLENGE_FIELD = 'challengeToken'
+
+/** Each challenge provider's fixed browser origins: its widget's script and its frame. */
+export const CHALLENGE_ORIGINS: Readonly<Record<ChallengeProvider, { readonly scriptSrc: readonly string[]; readonly frameSrc: readonly string[] }>> =
+	{
+		turnstile: { scriptSrc: ['https://challenges.cloudflare.com'], frameSrc: ['https://challenges.cloudflare.com'] },
+	}
+
+/** Generated file endpoints live under this prefix, for signed-in people. */
+export const FILES_PREFIX = '/api'
+
+/**
+ * The bounds of a file collection: the largest file a `scan: true` collection admits (the scanner reads at most this
+ * much of one file, so a larger one could never be given a clean verdict), and the pages of `files.<name>.list`.
+ */
+export const FILE_LIMITS = {
+	maxScannedBytes: 100 * 1024 * 1024,
+	/** Sniffable types a `scan: true` collection refuses: archives other than ZIP, whose contents the framework does not check. */
+	unscannedTypes: ['application/gzip'] as readonly string[],
+	listPageDefault: 50,
+	listPageMax: 100,
+} as const
+
+/**
+ * The bounds of an `attachment()` output. `maxBytes` and `maxRows` are each attachment's own, at most these; a cell holds
+ * at most `maxCellLength` UTF-16 code units, the most a spreadsheet cell keeps.
+ */
+export const ATTACHMENT_LIMITS = {
+	maxBytes: 16 * 1024 * 1024,
+	maxRows: 100_000,
+	defaultMaxRows: 10_000,
+	maxCellLength: 32_767,
+} as const
+
+/** The type each attachment format answers with. */
+export const CSV_CONTENT_TYPE = 'text/csv; charset=utf-8'
+export const XLSX_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
+/** Export procedures are served here, one path per procedure, and each export's description at its own path. */
+export { CONNECT_PREFIX } from '@fabrika/auth-core'
+
+/**
+ * Every connector call has a deadline; it bounds the retries too. Queries are safe to retry. An answer and a
+ * description are read under a byte budget, so another application cannot make the consumer buffer without bound.
+ */
+export const CONNECT_LIMITS = {
+	defaultTimeoutMs: 3000,
+	maxTimeoutMs: 10_000,
+	retries: 2,
+	maxAnswerBytes: 1024 * 1024,
+	maxDescriptionBytes: 256 * 1024,
+} as const
+
+/** `products` version 1 → `products.v1`: the description's endpoint id, and the prefix of each procedure's. */
+export function exportBase(name: string, version: number): string {
+	return `${name}.v${version}`
+}
+
+/** A link mount serves its procedures under `<prefix>/api`; everything else under the prefix is its SPA. */
+export const LINK_API_SEGMENT = 'api'
+
+/** The path segment a webhook appends for the binding a delivery addresses. */
+export const WEBHOOK_BINDING_PARAMETER = 'bindingId'
+
+/** Generated webhook binding endpoints (`webhooks.<name>.bind`, `.unbind`) live under this prefix, for signed-in people. */
+export const WEBHOOKS_PREFIX = '/api'
+
+/** The input field of a binding endpoint that names the scope value the binding reaches. */
+export const WEBHOOK_SCOPE_FIELD = 'scope'
+
+/** A GitHub account a binding accepts: an App installation or a repository, by numeric id. */
+export const WEBHOOK_ACCOUNT_PATTERN = '^(?:installation|repository):[1-9][0-9]{0,19}$'
+
+/**
+ * The share SPA's bootstrap, served by the framework under the link prefix and loaded before any other script: it
+ * takes the key out of the URL fragment and keeps it in a closure behind `SHARE_KEY_GLOBAL`.
+ */
+export const LINK_BOOTSTRAP_FILE = '__fabrika-share.js'
+export const SHARE_KEY_GLOBAL = '__fabrikaShareKey'
+
+/** What every `c.spa` mount serves under its prefix: the browser's Operations DSN and the release, as JSON. */
+export const BROWSER_CONFIG_FILE = '__fabrika-config.json'
+
+/** What every `c.spa` mount serves under its prefix to the person its access admitted: label, mailbox and actions. */
+export const PAGE_CALLER_FILE = '__fabrika-me.json'
+
+/** The row of an SPA mount's bare prefix (`GET /admin`), which redirects to the mount (`/admin/`). */
+export function spaPrefixRowId(mount: string): string {
+	return `${mount}.prefix`
+}
+
+/**
+ * The value a generated endpoint access case sends in an input field that names a member the handler looks up
+ * (`members` of `endpoint-access.fixtures.ts`); the endpoint access kit replaces it with a real member of the directory.
+ */
+export const GENERATED_MEMBER = 'fabrika:member'
+
+/**
+ * The value a generated endpoint access case sends in an input field that names an invitation the handler cancels
+ * (`invitations` of `endpoint-access.fixtures.ts`); the endpoint access kit replaces it with one open in the target's value.
+ */
+export const GENERATED_INVITATION = 'fabrika:invitation'
+
+/**
+ * The value a generated endpoint access case sends in an input field that names a share link the handler revokes
+ * (`links` of `endpoint-access.fixtures.ts`); the endpoint access kit replaces it with one the case's caller issued.
+ */
+export const GENERATED_LINK = 'fabrika:link'
+
+/**
+ * The prefix of the value a generated endpoint access case sends in an input field that names a row lying in its object
+ * (`rows` of `endpoint-access.fixtures.ts`), followed by the row's table: `fabrika:row:note_comments`. The endpoint
+ * access kit seeds one such row in each scope's object and sends that scope's key.
+ */
+export const GENERATED_ROW_PREFIX = 'fabrika:row:'
+
+export const JSON_ADMISSION: BodyAdmission = { contentTypes: ['application/json'], maxBytes: null }
+
+/** `/api` + `notes.list` → `/api/notes.list`; a root prefix does not double the `/`. */
+export function joinPath(prefix: string, rest: string): string {
+	return prefix === '/' ? `/${rest}` : `${prefix}/${rest}`
+}
+
+/**
+ * The paths of the endpoints of collection `name` under `base` (`FILES_PREFIX`, or a link mount's API prefix): the
+ * upload takes `/:owner` after its path for a signed-in caller, and the download `/:fileId`.
+ */
+export function fileCollectionPaths(
+	base: string,
+	name: string,
+): { readonly upload: string; readonly download: string; readonly list: string; readonly remove: string } {
+	const at = joinPath(base, `files.${name}`)
+	return { upload: `${at}.upload`, download: at, list: `${at}.list`, remove: `${at}.remove` }
+}