@relyio/sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @relyio/sdk
 
+## 0.19.0
+
+### Minor Changes
+
+- 0c154b3: **Declare who may read and write each type.** A Record type takes an Owner field, `fields.owner()`, which RelyIO sets from the signed-in End user's token, and `endUsers` names its Policies — `read`, `create`, `update` (with the `fields` an End user may set) and `delete`, each `'owner'`, `'signedIn'`, `'anyone'` (for a read) or a condition built with `conditionRoot('record' | 'claims')`, `and`, `or` and `not`. `perUser.writesPerMinute` caps one End user's writes, and `onOwnerDeleted: 'delete' | 'keep'` says what becomes of their Records when their identity provider deletes them. A content type's `endUsers.read: { when, otherwise }` Gates it: an entry `when` holds of is served whole, any other as its `otherwise` fields with `_gated: true`. The rule types are exported from `@relyio/sdk/schema` as `PolicyRule`, `NamedPolicyRule`, `WriteRule`, `FieldsWriteRule`, `RecordWriteRule`, `RecordTypeEndUsers` and `OwnerDeletedAction`.
+
+  **Private fields.** `private: true` on a field keeps it from every publishable-key read and every End user's, whatever key they come with; your server and your Functions still read it.
+
+  **Clerk's users.** With Clerk in `relyio/extensions.ts`, `clerk.userRef()` declares a reference to a `clerkUser` — the Record RelyIO keeps for each of your Clerk users — and a signed-in End user reads their own `clerkUser`, by its list, by its id, or through an Owner field's include.
+
+  **Refusals you can catch.** A refused End user token is `EndUserTokenInvalidError`, with `reason` (`expired`, `wrong-audience`, `missing`, …). `PublishableKeyRefusedError` now says how to fix it: send the End user's token, declare `endUsers` on the Function, or call from your server. A unique value an End user's write collides with names no `recordId`: it may be a Record they cannot read.
+
+- 6acd363: **Every request carries the signed-in End user's token.** Hand the client your identity provider's token function once — `createClient({ apiKey, getToken })`, Clerk's `getToken` or your own — and each request asks it then: a token is sent as `X-RelyIO-End-User` beside the key, and `null` (or a blank string) sends nothing, so the request is the key's alone. It is asked once per call, so every retry sends the token the first attempt sent; a function that throws rejects the call with nothing sent. It works with a publishable key in a browser and a secret key on a server. `client.with({ getToken })` makes a client that asks its own function in place of its parent's, and `updateConfig({ getToken: null })` stops sending one. A token the API cannot verify is refused `END_USER_TOKEN_INVALID` (401).
+
+  **Claims are typed from `relyio/extensions.ts`.** `ClaimsOf<typeof extensions>` (`@relyio/sdk/extensions`) is an object with one optional key per Claim the identity Extension's `claims` setting names — `oidc: { claims: 'plan, role' }` is `{ plan?: unknown; role?: unknown }` — so `conditionRoot<ClaimsOf<typeof extensions>>('claims').plan.eq('paid')` compiles and a misspelt Claim does not. A setting is text, so a Claim's value is `unknown`.
+
+- 10d761f: **A browser may call a Function that says so.** `defineFunction({ endUsers: 'required', … })` lets a publishable key call it through `relyio.functions.<name>(input)` for a signed-in End user — the call carries their token (`getToken`), and without one it is refused `END_USER_TOKEN_INVALID` (401, reason `missing`); `endUsers: 'optional'` lets it call with or without one. A Function that declares neither is still refused to a publishable key (`PUBLISHABLE_KEY_REFUSED`). The run is bound by the Function's own reach either way — a checkout takes stock the shopper could never write — and the plan names a new or widened `endUsers`.
+
+  **`run.endUser` names who called.** Any call carrying a verified token — with any key, or to a Public route sent one — hands the run `run.endUser`: `{ subject, claims }`, the subject an Owner field stores, and the Claims your `relyio/extensions.ts` declares. Type them by registering it: `declare module '@relyio/sdk' { interface Register { extensions: typeof extensions } }`. A Record the run creates with no owner named is that End user's; name one to set it yourself.
+
 ## 0.18.0
 
 ### Minor Changes

package/dist/automations/index.cjs

@@ -1,70 +1,71 @@
 'use strict';
 
-var chunkLSI26ZN2_cjs = require('../chunk-LSI26ZN2.cjs');
-var chunkZAMAR3X2_cjs = require('../chunk-ZAMAR3X2.cjs');
+var chunkDBYMG6MQ_cjs = require('../chunk-DBYMG6MQ.cjs');
+var chunk5F3YYPLZ_cjs = require('../chunk-5F3YYPLZ.cjs');
+require('../chunk-NN45CSPZ.cjs');
 require('../chunk-L6DXCKVQ.cjs');
 
 
 
 Object.defineProperty(exports, "and", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.and; }
+  get: function () { return chunkDBYMG6MQ_cjs.and; }
 });
 Object.defineProperty(exports, "anyEntry", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.anyEntry; }
+  get: function () { return chunkDBYMG6MQ_cjs.anyEntry; }
 });
 Object.defineProperty(exports, "automations", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.automations; }
+  get: function () { return chunkDBYMG6MQ_cjs.automations; }
 });
 Object.defineProperty(exports, "defineAutomation", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.defineAutomation; }
+  get: function () { return chunkDBYMG6MQ_cjs.defineAutomation; }
 });
 Object.defineProperty(exports, "entries", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.entries; }
+  get: function () { return chunkDBYMG6MQ_cjs.entries; }
 });
 Object.defineProperty(exports, "extensionTrigger", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.extensionTrigger; }
+  get: function () { return chunkDBYMG6MQ_cjs.extensionTrigger; }
 });
 Object.defineProperty(exports, "isAutomationFile", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.isAutomationFile; }
+  get: function () { return chunkDBYMG6MQ_cjs.isAutomationFile; }
 });
 Object.defineProperty(exports, "not", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.not; }
+  get: function () { return chunkDBYMG6MQ_cjs.not; }
 });
 Object.defineProperty(exports, "on", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.on; }
+  get: function () { return chunkDBYMG6MQ_cjs.on; }
 });
 Object.defineProperty(exports, "or", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.or; }
+  get: function () { return chunkDBYMG6MQ_cjs.or; }
 });
 Object.defineProperty(exports, "records", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.records; }
+  get: function () { return chunkDBYMG6MQ_cjs.records; }
 });
 Object.defineProperty(exports, "resolveAutomation", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.resolveAutomation; }
+  get: function () { return chunkDBYMG6MQ_cjs.resolveAutomation; }
 });
 Object.defineProperty(exports, "schedule", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.schedule; }
+  get: function () { return chunkDBYMG6MQ_cjs.schedule; }
 });
 Object.defineProperty(exports, "tpl", {
   enumerable: true,
-  get: function () { return chunkLSI26ZN2_cjs.tpl; }
+  get: function () { return chunkDBYMG6MQ_cjs.tpl; }
 });
 Object.defineProperty(exports, "fields", {
   enumerable: true,
-  get: function () { return chunkZAMAR3X2_cjs.fields; }
+  get: function () { return chunk5F3YYPLZ_cjs.fields; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/automations/index.d.cts

@@ -1,8 +1,7 @@
-import { ConditionScalar, ConditionTest, ConditionTree, ConditionTests } from '../schema/index.cjs';
+import { cH as ConditionScalar, cI as ConditionTest, cK as ConditionTree, cJ as ConditionTests, r as KeyedMembers, an as FieldValues, ao as DeclaredFields, s as KeyedMembersOf, cM as ExtensionSurfaces, cN as ExtensionSettingField, cO as ExtensionSurface, cP as ActionField, cQ as ExtensionValueField, y as ReferenceConfig, o as KeyedFieldOptions, n as KeyedField, cx as FileUpload } from '../define-content-type-BZ6X8GvL.cjs';
+import { A as AnySchemaDefinition, R as RegisteredSchema, B as BaseRecord, a as RecordBatchTarget, b as RecordBatchResult, c as Register, d as RecordConditionValue } from '../register-DeMsaurp.cjs';
+import { i as SchemaRecordTypeNames, I as InferRecordType, b as SchemaContentTypeNames, j as SchemaEntry, f as SchemaLocaleCodes, r as RecordWriteFieldsOf, q as RecordUpdateFieldsOf } from '../define-schema-BPlZl4a2.cjs';
 export { fields } from '../schema/index.cjs';
-import { A as AnySchemaDefinition, R as RegisteredSchema, B as BaseRecord, a as RecordBatchTarget, b as RecordBatchResult, c as RecordConditionValue } from '../register-BYCs0FpF.cjs';
-import { S as SchemaRecordTypeNames, I as InferRecordType, a as SchemaContentTypeNames, b as SchemaEntry, c as SchemaLocaleCodes, R as RecordWriteFieldsOf, d as RecordUpdateFieldsOf } from '../define-schema-DZhtvLiK.cjs';
-import { K as KeyedMembers, F as FieldValues, D as DeclaredFields, a as KeyedMembersOf, b as FileUpload } from '../define-content-type-NEQDrvdq.cjs';
 import '../rich-text.d-BWc-5gX1.cjs';
 
 /**
@@ -600,7 +599,7 @@ interface StepWithOutput<O> extends StepHandle {
     readonly output: Ref<O>;
 }
 /** A Field set's values, as a Function's and an Agent step's output Fields declare them. */
-type ValuesOf$1<F extends KeyedMembers> = FieldValues<DeclaredFields<{
+type ValuesOf$2<F extends KeyedMembers> = FieldValues<DeclaredFields<{
     readonly fields: readonly KeyedMembersOf<F>[];
 }>>;
 /** What `step.agent` takes. */
@@ -770,9 +769,9 @@ interface StepBuilder {
      * Ask an agent to read, answer the declared Fields and propose one change to the types `propose`
      * names. Nothing it proposes is written until an Ask approves it (`step.ask(…, { approve })`).
      */
-    agent<const O extends KeyedMembers>(name: string, config: ProposingAgentStepConfig<O>): StepWithOutput<ProposingOutput<ValuesOf$1<O>>>;
+    agent<const O extends KeyedMembers>(name: string, config: ProposingAgentStepConfig<O>): StepWithOutput<ProposingOutput<ValuesOf$2<O>>>;
     /** Ask an agent to read and answer the declared Fields. It reads; it never writes or sends. */
-    agent<const O extends KeyedMembers>(name: string, config: AgentStepConfig<O>): StepWithOutput<ValuesOf$1<O>>;
+    agent<const O extends KeyedMembers>(name: string, config: AgentStepConfig<O>): StepWithOutput<ValuesOf$2<O>>;
     /** Send through an Extension's Action, from the events worker; Recorded in a Preview without its Connection. */
     action<I, O>(name: string, action: AutomationAction<I, O>, input: StepInput<I>): StepWithOutput<O>;
     /**
@@ -863,6 +862,249 @@ declare function isAutomationFile(value: unknown): value is AutomationFile;
  */
 declare function resolveAutomation(file: AutomationFile, nameOf: (fn: FunctionDefinition) => string | undefined): AutomationDefinition;
 
+/**
+ * `@relyio/sdk/extensions` — the Extensions a Project uses (spec 3, REL-3846; ADR 0019).
+ *
+ * One file, `relyio/extensions.ts`, names each Extension the Project uses and its settings — set once
+ * for the Project, never per Environment — and hands out a typed handle for each. An Automation
+ * imports the handle: its Triggers start an Automation (`on: vercel.deploymentSucceeded()`), and its
+ * Actions are what `step.action` sends through, their input and output typed by the Extension.
+ *
+ * @example
+ * // relyio/extensions.ts
+ * import { defineExtensions } from '@relyio/sdk/extensions'
+ *
+ * const extensions = defineExtensions({
+ *   slack: { defaultChannel: '#orders' },
+ *   vercel: {},
+ * })
+ * export const { slack, vercel } = extensions
+ * export default extensions
+ *
+ * **Never a secret here.** A Connection — an API key, a signing secret, a webhook URL — is made in
+ * the Dashboard, once per Environment, and sealed. A setting is text anyone reading the repository
+ * may see. Declaring an Extension connects nothing: `relyio plan` says which still need connecting
+ * in Production, and which Automations will deploy paused there until they are. Preview never pauses:
+ * an Action with no Preview Connection is Recorded with its sample result.
+ *
+ * **Typed.** Each Extension's settings, Actions and Triggers are RelyIO's own declaration of it
+ * (`@relyio/api-contract`'s `EXTENSION_SURFACES`, which the Extension catalog delivers): an Extension
+ * RelyIO does not have, a setting it does not declare, or a value its setting does not take — a
+ * Slack channel without its `#` — is a type error, and the plan refuses it again for a Manifest read
+ * as data.
+ */
+
+/** One Extension a Project uses: its settings, by key. */
+interface ExtensionUse {
+    readonly settings: Readonly<Record<string, string>>;
+}
+/** What `relyio/extensions.ts` declares, as data: every Extension the Project uses, by slug. */
+type ExtensionsDeclaration = Readonly<Record<string, ExtensionUse>>;
+/** Every Extension a Project may declare, and what its code may name of each. */
+type Surfaces = ExtensionSurfaces;
+/** The value one setting takes: one of its options, text starting with its prefix, or text. */
+type SettingValue<F extends ExtensionSettingField> = F extends {
+    readonly type: 'select';
+    readonly options: ReadonlyArray<infer Option>;
+} ? Option : F extends {
+    readonly type: 'text';
+    readonly prefix: infer Prefix extends string;
+} ? `${Prefix}${string}` : string;
+type Flatten<T> = {
+    readonly [K in keyof T]: T[K];
+};
+/** The settings an Extension takes: its required ones required, the rest optional, nothing else. */
+type SettingsFrom<F extends ExtensionSettingField> = Flatten<{
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? Field['key'] : never]: SettingValue<Field>;
+} & {
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? never : Field['key']]?: SettingValue<Field>;
+}>;
+/**
+ * The settings `defineExtensions` takes for Extension `S`. An Extension with none takes `{}` and
+ * nothing in it.
+ */
+type ExtensionSettings<S extends keyof Surfaces> = [
+    Surfaces[S]['settings'][number]
+] extends [never] ? Readonly<Record<string, never>> : SettingsFrom<Surfaces[S]['settings'][number]>;
+/** What `defineExtensions` takes: each Extension the Project uses, by slug, with its settings. */
+type ExtensionsConfig = {
+    readonly [S in keyof Surfaces]?: ExtensionSettings<S>;
+};
+/** A value field's JSON type, as TypeScript reads it. */
+type JsonOf<T extends ExtensionValueField['type']> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? readonly unknown[] : Readonly<Record<string, unknown>>;
+/** A dot-separated path's first segment. */
+type Head<P extends string> = P extends `${infer First}.${string}` ? First : P;
+/** The fields whose path starts with segment `K`. */
+type Under<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? Head<F['path']> extends K ? F : never : never;
+/** The fields under `K`, their paths with `K.` taken off; never for the field at `K` itself. */
+type Rebased<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? F['path'] extends `${K}.${infer Rest}` ? Omit<F, 'path'> & {
+    readonly path: Rest;
+} : never : never;
+/** A field's value: its JSON type, and an object of strings for one declaring string values. */
+type FieldValueOf<F extends ExtensionValueField> = F extends {
+    readonly values: 'string';
+} ? Readonly<Record<string, string>> : JsonOf<F['type']>;
+/** The value at `K`: the field there, or an object of the fields under it. */
+type ValueAt<F extends ExtensionValueField, K extends string> = [
+    Extract<F, {
+        readonly path: K;
+    }>
+] extends [never] ? ValuesOf$1<Rebased<F, K>> : FieldValueOf<Extract<F, {
+    readonly path: K;
+}>>;
+/**
+ * Value fields as an object: `payload.data.object.id` a `string` at `payload.data.object.id`. A
+ * segment is required when a field under it is.
+ */
+type ValuesOf$1<F extends ExtensionValueField> = Flatten<{
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? K : never]: ValueAt<F, K>;
+} & {
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? never : K]?: ValueAt<F, K>;
+}>;
+/** A Trigger's payload, as an object; one that declares nothing, `{}`. */
+type ValuesOfList<L extends readonly ExtensionValueField[]> = [L[number]] extends [never] ? Record<string, never> : ValuesOf$1<L[number]>;
+/** An action field's value, as TypeScript reads it (`@relyio/api-contract`'s `ACTION_FIELD_TYPES`). */
+type ActionValueOf<T extends ActionField['type']> = T extends 'text' | 'url' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'headers' ? Readonly<Record<string, string>> : AutomationJson;
+/** An Action's input or output fields as an object: required ones required, the rest optional. */
+type ActionValuesOf<L extends readonly ActionField[]> = Flatten<{
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? F['key'] : never]: ActionValueOf<F['type']>;
+} & {
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? never : F['key']]?: ActionValueOf<F['type']>;
+}>;
+/** A Trigger's handle: call it for the Automation's `on`, with a `where` over its event if needed. */
+type ExtensionTriggerHandle<P> = (options?: {
+    readonly where?: (event: Ref<ExtensionTriggerEvent<P>>) => ConditionTree;
+}) => AutomationTriggerHandle<ExtensionTriggerEvent<P>>;
+/**
+ * The handle an Extension's declaration gives: each of its Actions and Triggers, by the name it gives
+ * them, typed by their fields.
+ */
+type HandleOf<X extends ExtensionSurface, S extends string = string> = {
+    readonly [A in keyof X['actions']]: X['actions'][A] extends {
+        readonly action: infer N extends string;
+        readonly step: {
+            readonly input: infer I extends readonly ActionField[];
+            readonly output: infer O extends readonly ActionField[];
+        };
+    } ? AutomationAction<ActionValuesOf<I>, ActionValuesOf<O>, S, N> : never;
+} & {
+    readonly [T in keyof X['triggers']]: X['triggers'][T] extends {
+        readonly payload: infer P extends readonly ExtensionValueField[];
+    } ? ExtensionTriggerHandle<ValuesOfList<P>> : never;
+};
+/**
+ * A contributed field kind's options (spec 4, REL-3894): its base reference's, without `to`, which
+ * the kind names, and never `localized` — a user is no translation.
+ */
+type ContributedFieldOptions<TTo extends string, TMulti extends boolean, TRequired extends boolean> = Omit<ReferenceConfig<TTo, TMulti>, 'to'> & {
+    readonly required?: TRequired;
+    readonly to?: never;
+} & KeyedFieldOptions<never>;
+/**
+ * A contributed field kind's builder — `clerk.userRef()`: a reference to the Extension's Managed
+ * Record type, typed exactly as `fields.reference` types a reference to it, which the Studio picks through
+ * the kind's picker. The schema, reads, writes and Policies treat it as that reference.
+ */
+type ContributedFieldKindBuilder<TTo extends string> = <TMulti extends boolean = false, TRequired extends boolean = false>(options?: ContributedFieldOptions<TTo, TMulti, TRequired>) => KeyedField<'reference', ReferenceConfig<TTo, TMulti> & {
+    required?: TRequired;
+}>;
+/** An Extension's contributed field kinds, by the name its declaration gives them. */
+type FieldKindsOf<X extends ExtensionSurface> = {
+    readonly [K in keyof X['fieldKinds']]: X['fieldKinds'][K] extends {
+        readonly base: {
+            readonly to: infer To extends string;
+        };
+    } ? ContributedFieldKindBuilder<To> : never;
+};
+/** An Extension's Managed Record types, by the name its declaration gives them (REL-3863). */
+type RecordTypesOf<X extends ExtensionSurface> = {
+    readonly [K in keyof X['recordTypes']]: X['recordTypes'][K];
+};
+/** Extension `S`'s handle. */
+type ExtensionHandle<S extends keyof Surfaces> = HandleOf<Surfaces[S], S & string> & FieldKindsOf<Surfaces[S]> & RecordTypesOf<Surfaces[S]>;
+/** Where the declaration rides on what `defineExtensions` returns. */
+declare const DECLARED = "declared";
+/**
+ * Where an {@link ExtensionsFile}'s type keeps the settings it was declared with, for
+ * {@link ClaimsOf} to read. Type-level only: no value carries it.
+ */
+declare const DECLARED_SETTINGS: unique symbol;
+/**
+ * What `relyio/extensions.ts` default-exports: the declaration the CLI reads into the Manifest, and
+ * a handle for each Extension it declares.
+ */
+type ExtensionsFile<C> = ExtensionsFileData & {
+    readonly [S in keyof C & keyof Surfaces]: ExtensionHandle<S>;
+} & {
+    readonly [DECLARED_SETTINGS]?: C;
+};
+/** The setting an identity Extension declares its Claims in (`@relyio/api-contract`'s `IDENTITY_CLAIMS_SETTING`). */
+type ClaimsSetting = 'claims';
+/** `S` without the whitespace `String.prototype.trim` takes off either end. */
+type Trimmed<S extends string> = S extends `${' ' | '\n' | '\t' | '\r'}${infer Rest}` ? Trimmed<Rest> : S extends `${infer Rest}${' ' | '\n' | '\t' | '\r'}` ? Trimmed<Rest> : S;
+/**
+ * The Claim names a `claims` setting declares, read as `claimNamesOf` reads it at deploy: split on
+ * commas, each trimmed, empty ones dropped. Text TypeScript does not know (`string`) may name any.
+ */
+type ClaimNames<S extends string> = string extends S ? string : S extends `${infer First},${infer Rest}` ? ClaimNames<First> | ClaimNames<Rest> : Trimmed<S> extends '' ? never : Trimmed<S>;
+/** Every Claim name the Extensions in `C` declare: an identity Extension's `claims` setting. */
+type DeclaredClaimNames<C> = {
+    readonly [S in keyof C]: C[S] extends {
+        readonly [K in ClaimsSetting]: infer T extends string;
+    } ? ClaimNames<T> : never;
+}[keyof C];
+/**
+ * The Claims a Project relies on, typed from its `relyio/extensions.ts`: `ClaimsOf<typeof
+ * extensions>` is an object with one optional key per Claim its identity Extension's `claims`
+ * setting names — `claims: 'plan, role'` is `{ plan?: unknown; role?: unknown }`. A Claim named and
+ * missing from a token is absent, and a setting is text, so each value is `unknown`: what a Claim may
+ * hold is for the Policy that tests it to say.
+ *
+ * Type a Policy's `claims` root with it, so a misspelt Claim is a compile error:
+ *
+ * @example
+ * import type { ClaimsOf } from '@relyio/sdk/extensions'
+ * import { conditionRoot } from '@relyio/sdk/schema'
+ * import extensions from './extensions'
+ *
+ * const claims = conditionRoot<ClaimsOf<typeof extensions>>('claims')
+ * claims.plan.eq('paid') // ✓
+ * claims.plna.eq('paid') // ✗ `plna` is no Claim the Project declares
+ */
+type ClaimsOf<F> = F extends {
+    readonly [DECLARED_SETTINGS]?: infer C;
+} ? {
+    readonly [N in DeclaredClaimNames<C>]?: unknown;
+} : never;
+/** `C`, refusing a key no Extension declares — at the top and in each Extension's settings. */
+type Exactly<C> = {
+    readonly [S in keyof C]: S extends keyof Surfaces ? C[S] & {
+        readonly [K in Exclude<keyof C[S], keyof ExtensionSettings<S>>]: never;
+    } : never;
+};
+/**
+ * Declare the Extensions the Project uses, with their settings, and take a typed handle for each.
+ * The file is `relyio/extensions.ts`; `relyio deploy` reads its default export into the Manifest.
+ */
+declare function defineExtensions<const C extends ExtensionsConfig>(config: C & Exactly<C>): ExtensionsFile<C>;
+/** What the CLI reads of `relyio/extensions.ts`' default export, whatever it declares. */
+interface ExtensionsFileData {
+    readonly _tag: 'extensions';
+    readonly [DECLARED]: ExtensionsDeclaration;
+}
+/** Whether `value` is what `defineExtensions` returns: how the CLI reads `relyio/extensions.ts`. */
+declare function isExtensionsFile(value: unknown): value is ExtensionsFileData;
+/** The declaration as the Manifest carries it. */
+declare function extensionsDeclarationOf(file: ExtensionsFileData): ExtensionsDeclaration;
+
 /**
  * `@relyio/sdk/functions` — a Function, declared (spec 2, REL-3819; ADR 0021).
  *
@@ -979,6 +1221,8 @@ interface FunctionDeclaration {
     readonly secrets: Readonly<Record<string, FunctionSecretDeclaration>>;
     /** The Actions it may send (REL-3856); absent when it declares none. */
     readonly actions?: readonly FunctionActionReach[];
+    /** Who besides a secret key may call its SDK Way in (spec 4, REL-3892); absent when undeclared. */
+    readonly endUsers?: FunctionEndUsers;
     readonly route?: FunctionRoute;
     readonly tool?: FunctionTool;
     readonly schedule?: FunctionSchedule;
@@ -1124,6 +1368,31 @@ type FunctionRecords<R extends string, W extends string> = {
  * the person's own Preview branch.
  */
 type FunctionWayIn = 'sdk' | 'route' | 'tool' | 'schedule' | 'automation' | 'editor';
+/**
+ * Whether a publishable key may call a Function from a browser (spec 4, REL-3892): `'required'` for
+ * a signed-in End user only — the call carries their token — or `'optional'` with or without one.
+ */
+type FunctionEndUsers = 'required' | 'optional';
+/**
+ * The Claims a run's End user carries: those the registered `relyio/extensions.ts` declares
+ * (`ClaimsOf`), once `Register` names it — `declare module '@relyio/sdk' { interface Register {
+ * extensions: typeof extensions } }` — else any name, each `unknown`.
+ */
+type FunctionEndUserClaims = Register extends {
+    extensions: infer F;
+} ? ClaimsOf<F> : {
+    readonly [claim: string]: unknown;
+};
+/**
+ * The End user a run's call carried a verified token for (spec 4, REL-3892): their subject — the
+ * `sub` an Owner field stores — and the Claims the Project declares, as the token carries them. A
+ * Record the run creates naming no owner is theirs; what the run may touch is still its reach, never
+ * their Policies.
+ */
+interface FunctionEndUser {
+    readonly subject: string;
+    readonly claims: FunctionEndUserClaims;
+}
 /** What a run knows of itself: its id survives every retry. */
 interface FunctionRunInfo {
     readonly id: string;
@@ -1146,6 +1415,11 @@ interface FunctionRunInfo {
      * Absent from a run an SDK call, a route or a tool started.
      */
     readonly event?: Readonly<Record<string, unknown>>;
+    /**
+     * The End user whose token the call carried, verified (spec 4, REL-3892) — with any key on the SDK
+     * Way in or a keyed route, and on a Public route that was sent one. Absent otherwise.
+     */
+    readonly endUser?: FunctionEndUser;
 }
 /** Published content, read through the read core: present when the reach declares `content: 'published'`. */
 interface FunctionContent {
@@ -1272,6 +1546,13 @@ interface FunctionConfig<I extends KeyedMembers, O extends KeyedMembers, R exten
      * type error, and refused at run time.
      */
     actions?: readonly A[];
+    /**
+     * Who besides a secret key may call it through `relyio.functions.<name>(input)` (spec 4,
+     * REL-3892): `'required'` lets a publishable key call it for a signed-in End user, whose token it
+     * carries; `'optional'` lets a publishable key call it with or without one. Left out, a secret key
+     * alone. Either way the run is bound by its reach, and `run.endUser` names who called.
+     */
+    endUsers?: FunctionEndUsers;
     route?: FunctionRoute;
     tool?: FunctionTool;
     schedule?: FunctionSchedule;
@@ -1306,4 +1587,4 @@ declare function defineFunction<const I extends KeyedMembers = Record<never, nev
 /** Whether `value` is what `defineFunction` returns: how the CLI reads a Function file's default export. */
 declare function isFunctionDefinition(value: unknown): value is FunctionDefinition;
 
-export { type FunctionActionRefused as A, type Accepts, type AgentStepConfig, type AnyEntryEvent, type AnyEntryTriggers, type ApproveCounts, type ApproveOutput, type ApproveStepConfig, type AskOutput, type AskStepConfig, type AutomationAction, type AutomationBecomesTest, type AutomationConfig, type AutomationDefinition, type AutomationDuration, type AutomationEntryAction, type AutomationFile, type AutomationInput, type AutomationItemHandle, type AutomationItemRef, type AutomationJson, type AutomationLookupState, type AutomationProposal, type AutomationProposeTarget, type AutomationRecordAction, type AutomationRef, type AutomationStep, type AutomationStepDraft, type AutomationTemplate, type AutomationTrigger, type AutomationTriggerHandle, type AutomationValue, type AutomationWhere, isActionRefused as B, type FunctionCapabilities as C, type FunctionResponse as D, respond as E, type EntryEvent, type EntryTriggers, type ExtensionTriggerEvent, type FunctionRuntime as F, type FunctionConfig as G, type FunctionDefinition as H, type FunctionInputOf as I, type FunctionOutputOf as J, defineFunction as K, isFunctionDefinition as L, type LookedUp, type LookedUpEntry, type LookedUpEntryItem, type LookedUpRecord, type LookupOptions, type ProposingAgentStepConfig, type ProposingOutput, type RecordEvent, type RecordTriggers, type Ref, type RunFailedEvent, type RunFailedWhere, type StepBuilder, type StepHandle, type StepInput, type StepWithOutput, type TriggerWhere, type UidRef, type FunctionContainerSize as a, and, anyEntry, automations, type FunctionDuration as b, type FunctionRouteMethod as c, type FunctionNetworkHost as d, defineAutomation, type FunctionActionReach as e, entries, extensionTrigger, type FunctionActionHandle as f, type FunctionSecretDeclaration as g, type FunctionRoute as h, type FunctionTool as i, isAutomationFile, type FunctionSchedule as j, type FunctionFieldDeclaration as k, type FunctionDeclaration as l, type FunctionRecordTypeName as m, type FunctionFile as n, not, type FunctionCounterMove as o, on, or, type FunctionRecordReader as p, type FunctionRecordWriter as q, type FunctionRecordBatch as r, records, resolveAutomation, type FunctionBatchResult as s, schedule, type FunctionBatchRefused as t, tpl, isBatchRefused as u, type FunctionRecords as v, type FunctionWayIn as w, type FunctionRunInfo as x, type FunctionContent as y, type FunctionActions as z };
+export { type FunctionOutputOf as $, type FunctionCounterMove as A, type Accepts, type AgentStepConfig, type AnyEntryEvent, type AnyEntryTriggers, type ApproveCounts, type ApproveOutput, type ApproveStepConfig, type AskOutput, type AskStepConfig, type AutomationAction, type AutomationBecomesTest, type AutomationConfig, type AutomationDefinition, type AutomationDuration, type AutomationEntryAction, type AutomationFile, type AutomationInput, type AutomationItemHandle, type AutomationItemRef, type AutomationJson, type AutomationLookupState, type AutomationProposal, type AutomationProposeTarget, type AutomationRecordAction, type AutomationRef, type AutomationStep, type AutomationStepDraft, type AutomationTemplate, type AutomationTrigger, type AutomationTriggerHandle, type AutomationValue, type AutomationWhere, type FunctionRecordReader as B, type ContributedFieldOptions as C, type FunctionRecordWriter as D, type ExtensionUse as E, type EntryEvent, type EntryTriggers, type ExtensionTriggerEvent, type FunctionRuntime as F, type FunctionRecordBatch as G, type HandleOf as H, type FunctionBatchResult as I, type FunctionBatchRefused as J, isBatchRefused as K, type FunctionRecords as L, type LookedUp, type LookedUpEntry, type LookedUpEntryItem, type LookedUpRecord, type LookupOptions, type FunctionWayIn as M, type FunctionEndUsers as N, type FunctionEndUserClaims as O, type FunctionEndUser as P, type ProposingAgentStepConfig, type ProposingOutput, type FunctionRunInfo as Q, type FunctionContent as R, type RecordEvent, type RecordTriggers, type Ref, type RunFailedEvent, type RunFailedWhere, type FunctionActions as S, type StepBuilder, type StepHandle, type StepInput, type StepWithOutput, type FunctionActionRefused as T, type TriggerWhere, isActionRefused as U, type UidRef, type FunctionCapabilities as V, type FunctionResponse as W, respond as X, type FunctionConfig as Y, type FunctionDefinition as Z, type FunctionInputOf as _, type ExtensionsDeclaration as a, defineFunction as a0, isFunctionDefinition as a1, and, anyEntry, automations, type ExtensionSettings as b, type ExtensionsConfig as c, type ExtensionTriggerHandle as d, defineAutomation, type ContributedFieldKindBuilder as e, entries, extensionTrigger, type ExtensionHandle as f, type ExtensionsFile as g, type ClaimsOf as h, defineExtensions as i, isAutomationFile, type ExtensionsFileData as j, isExtensionsFile as k, extensionsDeclarationOf as l, type FunctionContainerSize as m, type FunctionDuration as n, not, type FunctionRouteMethod as o, on, or, type FunctionNetworkHost as p, type FunctionActionReach as q, type FunctionActionHandle as r, records, resolveAutomation, type FunctionSecretDeclaration as s, schedule, type FunctionRoute as t, tpl, type FunctionTool as u, type FunctionSchedule as v, type FunctionFieldDeclaration as w, type FunctionDeclaration as x, type FunctionRecordTypeName as y, type FunctionFile as z };