@fabrika/app 0.5.5 → 0.7.0

package/src/contract/redirect.ts

@@ -0,0 +1,49 @@
+// `redirect()`: a procedure output that answers a redirect. The handler returns `{ to }`, and the framework answers
+// 303 after a POST and 302 after a GET, to a path of the application's own origin or a URL of an origin the output
+// lists; any other target fails the invocation, so no procedure is an open redirect. The value is the zod schema of
+// what the handler returns, marked with the origins it lists.
+
+import { z } from 'zod/v4'
+import type { Schema } from './define'
+
+const REDIRECT = Symbol('fabrika.redirect')
+
+/** What `redirect()` adds to the `{ to }` schema: the origins a target may name besides the application's own. */
+export interface RedirectMark {
+	readonly origins: readonly string[]
+}
+
+/** The marks `redirect` made: a property another module set on a schema is no redirect. */
+const marks = new WeakSet<object>()
+
+const Target = z.strictObject({ to: z.string().min(1).max(2048) })
+
+/** A redirect output: the handler returns `{ to }`, and the caller receives a 303 or a 302 there. */
+export type Redirect = typeof Target & RedirectBrand
+
+/** What tells a redirect output from a JSON one in the types. */
+export interface RedirectBrand {
+	readonly [REDIRECT]: RedirectMark
+}
+
+export interface RedirectOptions {
+	/** Exact `https://` origins a target may name, besides the application's own: `['https://shop.example']`. */
+	readonly origins?: readonly string[]
+}
+
+/** The output of a procedure that answers a redirect. `compileContract` and the checker refuse an origin it may not list. */
+export function redirect(options: RedirectOptions = {}): Redirect {
+	const mark: RedirectMark = Object.freeze({ origins: Object.freeze([...(options.origins ?? [])]) })
+	marks.add(mark)
+	return Object.assign(Target.clone(), { [REDIRECT]: mark })
+}
+
+/** The mark of a `redirect()` output, or `null` for any other schema. */
+export function redirectOf(schema: Schema): RedirectMark | null {
+	const mark: unknown = Reflect.get(schema, REDIRECT)
+	return isMark(mark) ? mark : null
+}
+
+function isMark(value: unknown): value is RedirectMark {
+	return typeof value === 'object' && value !== null && marks.has(value)
+}

package/src/contract/schema-from-shape.ts

@@ -4,6 +4,7 @@
 
 import type { SchemaShape, StringShape } from '@fabrika/auth-core'
 import { z } from 'zod/v4'
+import { SIGNED_TOKEN_MAX_LENGTH } from './token'
 
 /** The zod schema that admits what `shape` describes; `describeSchema` reads it back into the same shape. */
 export function schemaFromShape(shape: SchemaShape): z.ZodType {
@@ -55,6 +56,12 @@ export function schemaFromShape(shape: SchemaShape): z.ZodType {
 			return z.nullable(schemaFromShape(shape.inner))
 		case 'union':
 			return z.union(shape.options.map(schemaFromShape))
+		case 'token':
+			// The text of a signed token; the runtime verifies it and hands the handler its claims.
+			return z.string().min(1).max(SIGNED_TOKEN_MAX_LENGTH)
+		case 'file':
+			// No export carries a file: the build refuses one, so a description that holds one admits nothing.
+			return z.never()
 	}
 }
 

package/src/contract/schema-shape.ts

@@ -4,7 +4,9 @@
 import type { ArrayShape, NumberShape, SchemaShape, StringShape } from '@fabrika/auth-core'
 import { z } from 'zod/v4'
 import { attachmentOf } from './attachment'
+import { fileOf } from './file'
 import type { Problems } from './problems'
+import { signedTokenOf } from './token'
 
 const SUBSET = 'allowed: the supported z subset of packages/check/CLAUDE.md'
 
@@ -22,6 +24,14 @@ export function describeSchema(schema: z.core.$ZodType, where: string, problems:
 		problems.add(where, "an attachment() is a procedure's whole output, never part of a schema or an input (allowed: output: attachment({ … }))")
 		return null
 	}
+	const token = signedTokenOf(schema)
+	if (token !== null) {
+		return { type: 'token', purpose: token.purpose }
+	}
+	const file = fileOf(schema)
+	if (file !== null) {
+		return { type: 'file', kind: file.kind }
+	}
 	if (schema instanceof z.core.$ZodString || schema instanceof z.core.$ZodStringFormat) {
 		return describeString(schema, where, problems)
 	}

package/src/contract/snapshot-source.ts

@@ -123,6 +123,11 @@ function schemaSource(shape: SchemaShape, where: string): string {
 			return `z.${shape.type}(${schemaSource(shape.inner, where)})`
 		case 'union':
 			return `z.union([${shape.options.map((option) => schemaSource(option, where)).join(', ')}])`
+		case 'token':
+			// The build refuses a signed token in an export, so no description it vendors holds one.
+			throw new ContractError([`procedure '${where}': a signed token has no zod source in a connector snapshot`])
+		case 'file':
+			throw new ContractError([`procedure '${where}': an export carries no file`])
 	}
 }
 

package/src/contract/token.ts

@@ -0,0 +1,89 @@
+// Signed tokens: a purpose declared once in `defineApp`'s options (`token(Claims, { maxDays })`), a field of a
+// procedure's input or `http.query` that carries one (`signedToken('<purpose>')`), and `ctx.tokens.sign` of a site that
+// declares `signs`. On the wire a token is a string; the framework verifies it as it parses the input and hands the
+// handler the purpose's typed claims. A token is single-purpose and no credential: it opens no mount.
+
+import { z } from 'zod/v4'
+import type { InputSchema, NotLoose, Schema } from './define'
+
+const SIGNED_TOKEN = Symbol('fabrika.signedToken')
+
+/** The longest token a field admits: a purpose's claims, a key id, an expiry and a signature, URL-safe. */
+export const SIGNED_TOKEN_MAX_LENGTH = 4096
+
+/** The most days any purpose may declare: a key stays verifying that long after it stopped signing. */
+export const TOKEN_MAX_DAYS = 3650
+
+/** One token purpose: the claims a token of it carries and the longest lifetime a site may sign one for. */
+export interface TokenPurpose<C extends Schema = Schema> {
+	readonly '~kind': 'token'
+	readonly claims: C
+	readonly maxDays: number
+}
+
+export type TokenPurposes = { readonly [purpose: string]: TokenPurpose }
+
+export interface TokenOptions {
+	/** The longest lifetime, in days, of a token of this purpose. */
+	readonly maxDays: number
+}
+
+/**
+ * A token purpose: `token(Recipient, { maxDays: 400 })` under `defineApp(vocabulary, tables, { tokens })`. `Claims` is a
+ * strict object; `compileContract` and the checker refuse what a token may not carry.
+ */
+export function token<C extends InputSchema>(claims: C & NotLoose<C>, options: TokenOptions): TokenPurpose<C> {
+	return Object.freeze({ '~kind': 'token', claims, maxDays: options.maxDays })
+}
+
+/** What `signedToken()` adds to its schema: the purpose a token of the field must be signed for. */
+export interface SignedTokenMark {
+	readonly purpose: string
+}
+
+type TokenBrand<P extends string> = `fabrika.token:${P}`
+
+/** A field that carries a signed token of purpose `P`: a string on the wire, the purpose's claims in the handler. */
+export type SignedTokenSchema<P extends string> =
+	& (PropertyKey extends TokenBrand<P> ? z.ZodString : z.core.$ZodBranded<z.ZodString, TokenBrand<P>>)
+	& { readonly [SIGNED_TOKEN]: SignedTokenMark }
+
+/** The marks `signedToken` made: a property another module set on a schema is no token field. */
+const marks = new WeakSet<object>()
+
+/**
+ * A field of a procedure's input or `http.query` that carries a token of `purpose`, verified as the input is parsed:
+ * `z.strictObject({ t: signedToken('unsubscribe') })`. Only a top-level field; the handler receives the claims.
+ */
+export function signedToken<const P extends string>(purpose: P): SignedTokenSchema<P> {
+	const mark: SignedTokenMark = Object.freeze({ purpose })
+	marks.add(mark)
+	return Object.assign(z.string().min(1).max(SIGNED_TOKEN_MAX_LENGTH).brand<TokenBrand<P>>(), { [SIGNED_TOKEN]: mark })
+}
+
+/** The mark of a `signedToken()` schema, or `null` for any other schema. */
+export function signedTokenOf(schema: Schema): SignedTokenMark | null {
+	const mark: unknown = Reflect.get(schema, SIGNED_TOKEN)
+	return isMark(mark) ? mark : null
+}
+
+function isMark(value: unknown): value is SignedTokenMark {
+	return typeof value === 'object' && value !== null && marks.has(value)
+}
+
+/** The purpose a field's parsed value names when the field is a signed token; `never` for any other field. */
+export type TokenPurposeOf<V> = V extends { readonly [z.core.$brand]: infer B } ? keyof B extends TokenBrand<infer P> ? P : never : never
+
+/** One field as the handler holds it: a signed token as the claims of its purpose, any other field as it is. */
+type ClaimsField<V, T> = [TokenPurposeOf<NonNullable<V>>] extends [never] ? V
+	:
+		| (TokenPurposeOf<NonNullable<V>> extends keyof T ? T[TokenPurposeOf<NonNullable<V>>] extends TokenPurpose<infer C> ? z.output<C> : never : never)
+		| (undefined extends V ? undefined : never)
+
+/** An input as its handler receives it: each signed token field replaced by the verified claims of its purpose. */
+export type WithClaims<In, T> = [keyof In] extends [never] ? In : { readonly [F in keyof In]: ClaimsField<In[F], T> }
+
+/** `ctx.tokens` of a site that declares `signs`: a token of one of those purposes, valid for `days`. */
+export interface TokenSigning<T extends TokenPurposes, S extends string> {
+	sign<const P extends S & keyof T & string>(purpose: P, claims: z.input<T[P]['claims']>, options: { readonly days: number }): string
+}

package/src/contract/webhook-binding.ts

@@ -0,0 +1,26 @@
+// What a procedure that declares `binds: '<webhook>'` reaches through `ctx.webhooks('<webhook>')`, and what it answers
+// the member who binds: the binding's URL and its secret, shown once, or the provider's secret set afterwards.
+
+import { z } from 'zod/v4'
+import type { AppCapability, Ref } from '../implement/capability'
+
+/** The output of a procedure that binds: the binding's id, the URL the provider posts to, and the secret, once. */
+export const WebhookSecret = z.strictObject({ id: z.uuid(), url: z.string().min(1), secret: z.string().min(1) })
+
+export type WebhookSecret = z.output<typeof WebhookSecret>
+
+/**
+ * The bindings of one webhook. A binding reaches the value the capability names: a `Ref` of the webhook's dimension, or
+ * an `AppCapability` for a webhook bound to `'app'`. Both run in the procedure's transaction.
+ */
+export interface WebhookBindings {
+	/** A new binding that accepts deliveries for `account`; the framework generates its secret. */
+	bind(capability: Ref<string, string> | AppCapability<string>, account: string): Promise<WebhookSecret>
+	/**
+	 * Replaces the secret of the binding `id` of that value with one the provider issued (Stripe, Slack, Twilio): the
+	 * provider shows it only after the binding's URL is registered. `false` when the value has no binding of that id.
+	 */
+	setSecret(capability: Ref<string, string> | AppCapability<string>, id: string, secret: string): Promise<boolean>
+	/** Removes the binding `id` of that value; `false` when it has none of that id. */
+	unbind(capability: Ref<string, string> | AppCapability<string>, id: string): Promise<boolean>
+}

package/src/contract/webhook-scheme.ts

@@ -0,0 +1,32 @@
+// A webhook's verifier as data: `buildArtifact` refuses a scheme this parser refuses, and the artifact's parser reads
+// it with the same schema, so a stored artifact never carries a verifier the runtime cannot run.
+
+import { WEBHOOK_PRESETS, type WebhookScheme } from '@fabrika/auth-core'
+import { z } from 'zod/v4'
+
+/** An HTTP header name (RFC 9110's token). */
+const headerName = z.string().regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/, 'is not a header name')
+
+export const hmacSchemeSchema = z.strictObject({
+	header: headerName,
+	algorithm: z.enum(['sha1', 'sha256', 'sha512']),
+	encoding: z.enum(['hex', 'base64']),
+	prefix: z.string().min(1).max(32).optional(),
+	timestamp: headerName.optional(),
+	signed: z.enum(['body', 'timestamp.body']),
+	id: headerName.optional(),
+}).refine(
+	// An unsigned timestamp proves nothing, and a signed one needs the header it is read from.
+	(scheme) => (scheme.signed === 'timestamp.body') === (scheme.timestamp !== undefined),
+	"signed: 'timestamp.body' names its timestamp header, and only it does",
+)
+
+export const webhookSchemeSchema: z.ZodType<WebhookScheme> = z.union([
+	z.enum(WEBHOOK_PRESETS),
+	z.strictObject({ hmac: hmacSchemeSchema }),
+	z.strictObject({ basic: z.literal(true) }),
+	z.strictObject({ bearer: z.literal(true) }),
+])
+
+export const WEBHOOK_SCHEME_ALLOWED =
+	"scheme: 'github-sha256' | 'slack' | 'standard-webhooks' | 'stripe' | 'twilio' | { hmac: { header, algorithm: 'sha1' | 'sha256' | 'sha512', encoding: 'hex' | 'base64', prefix?, timestamp?, signed: 'body' | 'timestamp.body', id? } } | { basic: true } | { bearer: true }"

package/src/files/handle.ts

@@ -3,6 +3,7 @@
 // collection's actions, so a file reaches what its owner reaches, as through the generated endpoints.
 
 import type { Unavailable } from '@fabrika/db/tables'
+import type { FileRef } from '../contract/file'
 import type { Ref } from '../implement/capability'
 
 /** A held file's state: served when `live`, `409` while `quarantined`, gone when `rejected`. */
@@ -94,3 +95,24 @@ export type FileCollectionReadHandle<Why extends string> = FileCollectionReader
 
 /** `ctx.files(<collection>)`: the handle of one collection of the contract, by its name in `files`. */
 export type FileCollections<H> = (collection: string) => H
+
+/** What `ctx.files.put` writes: bytes in memory, a `Blob`, or a stream a large file comes from. */
+export type StoredFileBody = Uint8Array | ReadableStream<Uint8Array> | Blob
+
+/**
+ * `ctx.files.put` and `ctx.files.open`: the stored files of a site (`c.files` kinds). A put stages a file this request
+ * holds; writing its reference into a file column is what keeps it. `open` reads a live file whose reference this
+ * request holds and may read: an input file, a put, or a file column read under its table's read action.
+ */
+export interface StoredFilesHandle {
+	/** A file of `kind` with these bytes, which must be of `type`; it is pending until a column references it. */
+	put(kind: string, body: StoredFileBody, options: { readonly type: string; readonly name?: string }): Promise<FileRef>
+	/** The bytes of a live file, read whole, at most `maxBytes` (the kind's by default); 409 until it is live. */
+	open(file: FileRef, options?: { readonly maxBytes?: number }): Promise<OpenedFile>
+}
+
+/** A site that only reads (a query): it opens a file and creates none. */
+export interface StoredFilesReadHandle {
+	readonly put: Unavailable<'a query creates no file; put it in a mutation, a job or a webhook'>
+	open(file: FileRef, options?: { readonly maxBytes?: number }): Promise<OpenedFile>
+}