primitive-admin 1.1.0-alpha.78 → 1.1.0-alpha.79

package/dist/src/lib/generated-config-surfaces.d.ts

@@ -871,10 +871,38 @@ export declare const MAX_MANIFEST_MODELS = 200;
 export declare const MAX_MANIFEST_FAMILIES = 40;
 export interface ManifestParam {
     type?: string;
+    /** `type: "array"` — the element type, when declared (#3281). */
+    items?: {
+        type: string;
+    };
     caller?: boolean;
     optional?: boolean;
     default?: unknown;
 }
+/** The scalar parameter types a registration may declare, and an array's element types. */
+export declare const QUERY_PARAM_SCALAR_TYPES: readonly ["string", "number", "boolean", "any"];
+/**
+ * Coerce one value to a declared parameter type the way the SDK coerces a
+ * SUPPLIED value: a digit string becomes a number, `"true"`/`"false"` a
+ * boolean, an array's elements each by the `items` type. Applied to a
+ * declared `default` at registration (D3281-SO-005) so what `run` receives is
+ * what the declaration promises — here at push (the collect stub and this
+ * grammar) and in the SDK at the first load. ONE rule, spelled in the SDK's
+ * source a second time because that module is baked text; the tests hold the
+ * two together.
+ */
+export declare function coerceParamDefault(spec: {
+    type?: string;
+    items?: {
+        type?: string;
+    };
+}, value: unknown): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
 export interface ManifestQuery {
     name: string;
     kind: "query" | "mutation";
@@ -918,6 +946,400 @@ export interface ParsedManifest {
  * and whether the author meant any of it are questions this cannot answer.
  */
 export declare function parseFunctionManifest(value: unknown): ParsedManifest;
+/**
+ * The function MODE vocabulary, and the one place its two spellings meet —
+ * #3281, project `server-functions` phase 4.
+ *
+ * `mode = "request" | "task"` is what an author writes (the intent, "Mode
+ * vocabulary?", sponsor decision 2026-09-09): a request function runs inside
+ * the call and returns its result; a task function returns a run id and
+ * survives restarts. `durable = true | false` is the key the first releases
+ * taught, and it stays ACCEPTED as an alias through the transition — a tree
+ * pushed with it keeps pushing, and pulls back byte for byte — while `durable`
+ * stays the adjective for the property itself.
+ *
+ * ── Why one module ───────────────────────────────────────────────────────
+ *
+ * Two spellings for one fact is a place two readers can disagree. So the
+ * resolution is written once, here, in the dependency-free tree the CLI
+ * vendors (`cli/scripts/gen-config-surfaces.mjs`), and every door reads it:
+ * the CLI preflight and diff entity, the server's trigger derivation, the
+ * admin config-version route (payload `mode` beside payload `durable`), the
+ * invoke branch and the trigger fires. A file — or a payload — that carries
+ * both keys has to have them AGREE, or it is refused naming both; a silent
+ * winner would be the one thing worse than two spellings.
+ *
+ * The stored column is still `ServerFunctionConfig.durable` (no `models.yaml`
+ * change before phase 7's rename sweep), which is why `configMode` exists:
+ * reading the row is the other half of the same translation.
+ */
+export type FunctionMode = "request" | "task";
+export declare const FUNCTION_MODES: readonly FunctionMode[];
+/** What a declaration resolved to, or why it could not. */
+export type DeclaredModeResolution = {
+    ok: true;
+    mode: FunctionMode;
+    /**
+     * Whether the declaration SAID anything — false when neither key was
+     * present and the default applied. The admin route's divergence check
+     * reads this: an omitted mode is no claim, so it cannot diverge.
+     */
+    declared: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve `mode` and its alias `durable` to one mode.
+ *
+ * Absent both → `request`. `mode` must be exactly `"request"` or `"task"`;
+ * `durable` must be a boolean. Both present and disagreeing is refused naming
+ * both keys, so an author who half-migrated a file hears which line to fix.
+ */
+export declare function resolveDeclaredMode(input: {
+    mode?: unknown;
+    durable?: unknown;
+}): DeclaredModeResolution;
+/**
+ * The mode a stored config-version row runs in.
+ *
+ * The column is `durable`; a row written before #3281 carries only that, and a
+ * row written after it carries the same thing, so there is exactly one reading.
+ */
+export declare function configMode(row: {
+    durable?: unknown;
+} | null | undefined): FunctionMode;
+/** Is this mode the durable one? The adjective, for the paths that branch on it. */
+export declare function isDurableMode(mode: FunctionMode): boolean;
+/**
+ * The trigger blocks a function declares, derived from its authored TOML
+ * (#3181, project `server-functions`, criterion 4).
+ *
+ * ── The declaration is derived, never supplied ────────────────────────────
+ *
+ * A config-version push carries the authored `functions/<key>.toml` bytes
+ * inside its envelope, and `envelopeHash` covers them. If the push ALSO
+ * carried a parsed `triggers` payload, the two could disagree: a direct API
+ * caller could ship a public webhook trigger the authored file does not
+ * declare, and two pushes with identical envelopes but different trigger
+ * payloads would collapse to one version. So the server parses the envelope's
+ * own bytes here (D3181-005) and there is no payload field to disagree with —
+ * trigger behavior is bound to the version's identity by construction.
+ *
+ * ── Shape only ────────────────────────────────────────────────────────────
+ *
+ * This module decides what the file SAYS: the accepted key set, the required
+ * values, and the rules that need nothing but the document (scheme `none`,
+ * a nameless or duplicated cron entry, an entry count past the per-function
+ * cap, a webhook or database block on a task version). Everything that needs the
+ * app's state — whether a referenced secret exists, whether the
+ * scheme-specific config is valid, whether the app is at its webhook or cron
+ * cap, whether a standalone webhook holds the key — belongs to the push
+ * boundary, which runs the SAME validators the standalone create runs
+ * (D3181-006).
+ *
+ * ── One implementation, two readers (#3320) ───────────────────────────────
+ *
+ * The CLI checks the same rules against the author's own file before a request
+ * is made. It used to do that from a hand-written restatement
+ * (`cli/src/lib/function-triggers.ts`), kept in step only by a paired-fixture
+ * test — so a rule added here with no fixture drifted silently. The rules
+ * therefore live in `src/config-surface/`, which `cli/scripts/
+ * gen-config-surfaces.mjs` vendors verbatim into the committed artifact
+ * `cli/src/lib/generated-config-surfaces.ts`. There is one implementation, and
+ * a change here that is not regenerated fails `--check` (a build failure)
+ * rather than a fixture list that happens not to cover it.
+ *
+ * Reading the authored BYTES is the one thing that stayed server-side:
+ * `deriveTriggerDeclaration` in `src/server-functions/trigger-declaration.ts`
+ * parses them and calls `normalizeTriggerDeclaration` here. This directory
+ * imports nothing but itself (asserted by `config-surface-drift-guard.test.ts`),
+ * and the CLI has already parsed its own file by the time it asks.
+ */
+/**
+ * The resolved mode the declaration is checked against (#3281).
+ *
+ * The rule is per KIND, and permanent (the intent, "Sync functions write a run
+ * row?": *Webhook and database-change triggers require request mode; HTTP and
+ * cron allow both*). A webhook delivery and a database write are both waiting
+ * inside a request for the function to answer; a cron fire is waiting for
+ * nothing, so it starts a task run when the version is a task (#3334).
+ *
+ * The caller resolves `mode`/`durable` once, through `resolveDeclaredMode`,
+ * and hands the answer here — this module never reads the alias itself.
+ */
+export interface TriggerModeOptions {
+    mode?: FunctionMode;
+}
+/**
+ * Why a webhook cannot drive a task function, and what to do instead (#3334).
+ *
+ * The first clause is verbatim what it has always been, so sibling pins on the
+ * request-mode prefix (#3281's) keep holding; everything after the dash is the
+ * half that was missing — an author who meets this at the push door could not
+ * previously tell whether it was a limitation or a design, nor what to write.
+ */
+export declare const WEBHOOK_ON_TASK_REFUSAL: string;
+/** A function's single webhook trigger, normalized. */
+export interface WebhookTriggerDeclaration {
+    verificationScheme: string;
+    signingSecret?: string;
+    toleranceSeconds?: number;
+    deduplicationEnabled?: boolean;
+    deduplicationWindowMs?: number;
+    maxBodyBytes?: number;
+    secretGracePeriodMs?: number;
+    /** `[function.triggers.webhook.verification]` — the row's `config`. */
+    verification?: Record<string, unknown>;
+}
+/** One `[[function.triggers.cron]]` entry, normalized. */
+export interface CronTriggerDeclaration {
+    name: string;
+    cron: string;
+    timezone?: string;
+    overlapPolicy?: string;
+    rootInput?: unknown;
+}
+/** One `[[function.triggers.database]]` entry, normalized (#3184). */
+export interface DatabaseTriggerDeclaration {
+    /** The database type key whose writes fire this function. */
+    type: string;
+}
+export interface TriggerDeclaration {
+    webhook: WebhookTriggerDeclaration | null;
+    cron: CronTriggerDeclaration[];
+    databases: DatabaseTriggerDeclaration[];
+}
+export declare const EMPTY_TRIGGER_DECLARATION: TriggerDeclaration;
+/**
+ * The most cron entries one function may declare.
+ *
+ * The per-app cap (50) is a resource ceiling; this is a per-OBJECT one, so a
+ * single function cannot take most of an app's budget by itself. Ten is the
+ * same order as the schedules a real function needs and leaves the app's
+ * remaining slots for the other 40+ objects the cap is sized for.
+ */
+export declare const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
+/**
+ * The most database types one function may watch (#3184, D-07).
+ *
+ * Per-OBJECT, like the cron cap above: a function watching more than a handful
+ * of types is describing a fan-in the platform cannot bound per write, and
+ * every extra type is another discovery read on somebody's write path.
+ */
+export declare const MAX_DATABASE_TRIGGERS_PER_FUNCTION = 5;
+export declare class TriggerDeclarationError extends Error {
+}
+/** Is anything at all declared? Used to skip work on the common case. */
+export declare function hasDeclaredTriggers(declaration: TriggerDeclaration): boolean;
+/**
+ * Normalize the `triggers` table of an already-parsed `[function]` table.
+ * Throws `TriggerDeclarationError` naming the rule that was broken.
+ *
+ * Split out from the parse (`deriveTriggerDeclaration`, which owns the bytes)
+ * so the CLI's preflight can check the document it has already read, and so the
+ * push boundary can normalize a declaration it read from a stored row without
+ * re-parsing bytes.
+ */
+export declare function normalizeTriggerDeclaration(functionTable: any, options?: TriggerModeOptions): TriggerDeclaration;
+/** The stored JSON for `ServerFunctionConfig.triggers`, or null when empty. */
+export declare function serializeTriggerDeclaration(declaration: TriggerDeclaration): string | null;
+/** Read a stored `ServerFunctionConfig.triggers` value back. */
+export declare function parseStoredTriggerDeclaration(stored: unknown): TriggerDeclaration;
+/** The `CronTrigger.triggerKey` an entry owns. */
+export declare function cronTriggerKeyFor(functionKey: string, name: string): string;
+/** The entry name a `<functionKey>:<name>` trigger key carries. */
+export declare function cronTriggerNameFrom(functionKey: string, triggerKey: string): string;
+/**
+ * The `{{secrets.KEY}}` reference SHAPE, decided from the value alone.
+ *
+ * Split out of `src/services/secret-templates.ts` by #3320 so the one rule that
+ * says whether a stored value IS a whole secret reference has one
+ * implementation on both sides of a `config push`. The CLI preflight refuses a
+ * webhook trigger whose `signingSecret` is a literal before anything is applied,
+ * and the server refuses the same value at the write boundary, because both run
+ * this code — the CLI through the artifact `cli/scripts/gen-config-surfaces.mjs`
+ * renders, the server by importing this module. A shape-only restatement in the
+ * CLI would have been subtly different: a reference spoiled by an invisible
+ * character (#2297) survives `String.trim()` and would have passed a preflight
+ * the server then failed.
+ *
+ * Pure by construction, which is what lets it live here: no secret store is
+ * consulted, because whether a value is a REFERENCE never depends on which keys
+ * exist. Whether the referenced key exists is the server's question, and stays
+ * in `secret-templates.ts` beside the rest of resolution.
+ *
+ * `secret-templates.ts` re-exports everything here, so every existing caller
+ * keeps its import and the two can never be different functions.
+ */
+export declare const SECRETS_TEMPLATE_RE: RegExp;
+/** True when the value carries at least one `{{secrets.KEY}}` reference. */
+export declare function isSecretTemplate(value: string | null | undefined): boolean;
+/**
+ * The value with every well-formed `{{secrets.KEY}}` reference removed — the
+ * text that was NOT part of a reference the grammar accepts.
+ *
+ * This is the string the leftover-syntax rule below has to judge, and it is
+ * always derived from the ORIGINAL stored value, never from a substituted
+ * result. Resolution is a single `String.replace` pass that never re-scans
+ * replacement text (`resolveMultiNamespaceTemplate`), so a brace or a
+ * `secrets.` token coming out of a SECRET'S VALUE is inert — it is credential
+ * material the operator stored, not config text, and testing the substituted
+ * output would reject it (a Stripe key suffix stored as `}v2{` in an otherwise
+ * valid `sk_live_{{secrets.SUFFIX}}` value).
+ */
+export declare function withoutSecretReferences(value: string): string;
+/**
+ * True when the value holds a well-formed `{{secrets.KEY}}` reference and the
+ * text beside it is not credential material — a reference SPOILED by an
+ * invisible character, rather than a legacy literal that happens to contain one
+ * (#2297, consolidating #2386).
+ *
+ * Such a value is a reference spoiled by an authoring mistake — pasted out of
+ * an editor or a document that carried a zero-width character along with it —
+ * and it must fail closed rather than resolve. Before this rule a value spelled
+ * `<U+200B>{{secrets.KEY}}` was not a whole reference (neither `\s` nor
+ * `String.trim()` matches U+200B), carried no leftover reference SYNTAX once
+ * the template was removed, and so classified as a working legacy literal that
+ * resolved to U+200B followed by the secret: an HMAC key silently one byte
+ * wrong, and a read surface pointing the operator at the wrong remediation.
+ *
+ * The rule judges the REMAINDER — the value with its well-formed references
+ * taken out — against an allowlist, which is what makes the class closed:
+ *
+ * - Remainder empty, or ordinary whitespace only: the value is the reference it
+ *   plainly is, padding and all, and keeps resolving (#2191).
+ * - Remainder carries at least one credential character: a genuine mixed
+ *   literal-plus-reference value (`sk_live_{{secrets.SUFFIX}}`), which predates
+ *   reference-only and keeps resolving as shipped (#2332) — including when the
+ *   operator's own bytes contain an invisible character, because that is
+ *   credential material rather than a spoiled pointer.
+ * - Anything else: text that is present but that we cannot recognize as
+ *   credential material. Fail closed.
+ *
+ * Failing closed rather than stripping the character is the deliberate choice
+ * (sponsor decision on #2297): stripping hides the mistake, where a
+ * `malformed-reference` names it at the moment the value is written.
+ *
+ * A value with NO well-formed reference is not this rule's business, and needs
+ * no separate handling: a pure literal is credential material the platform has
+ * no standing to judge (`whsec_<U+200B>raw`), and a MISTYPED reference —
+ * including one spoiled inside the braces, `{{secrets.<U+200B>KEY}}` — leaves
+ * its syntax in the remainder and is already caught by
+ * `carriesMalformedReferenceSyntax` in `secret-templates.ts`.
+ *
+ * Scoped to the reference-only credential boundary, not to
+ * `resolveSecretTemplate`: an integration proxy header is a template by design
+ * (`Authorization: Bearer {{secrets.TOKEN}}`), so it keeps resolving exactly
+ * what the operator wrote.
+ */
+export declare function isSpoiledSecretReference(value: string | null | undefined): boolean;
+/**
+ * Matches a value that is EXACTLY one `{{secrets.KEY}}` reference and nothing
+ * else. Anchored, and deliberately not global — `SECRETS_TEMPLATE_RE` carries
+ * `lastIndex` state between calls.
+ */
+export declare const WHOLE_SECRET_REFERENCE_RE: RegExp;
+/**
+ * True when the whole (trimmed) value is a single `{{secrets.KEY}}` reference.
+ *
+ * The stricter sibling of `isSecretTemplate`, for the callers that use "is a
+ * reference" to mean "carries no secret material of its own". `isSecretTemplate`
+ * is a *contains* test, so `"sk_live_abcd{{secrets.SUFFIX}}"` satisfies it —
+ * which is fine where a value is a template to be resolved (an
+ * `Authorization: Bearer {{secrets.TOKEN}}` header is exactly that), and wrong
+ * where the value is a credential that must live entirely in the encrypted
+ * secret store. Used by the webhook `config` credential rule and by the
+ * redaction that backs it: a mixed value would otherwise pass the write rule
+ * AND skip redaction, storing and echoing most of a working credential in
+ * cleartext.
+ *
+ * Trimmed, so `" {{secrets.KEY}} "` is accepted as the reference it plainly is;
+ * two references, or a reference with any literal text beside it, are not.
+ *
+ * Invisible text beside the reference disqualifies the value before the trim
+ * (#2297): U+FEFF is stripped by `String.trim()` and matched by `\s`, so
+ * without the check a byte-order mark beside the braces would be silently
+ * accepted while its zero-width siblings were not. Rejecting here is what makes
+ * the write gates built on this predicate (`validateWholeSecretReference`, the
+ * webhook `config` credential rule) refuse such a value at configuration time
+ * rather than storing a row that can only fail at use time.
+ */
+export declare function isWholeSecretReference(value: string | null | undefined): boolean;
+/**
+ * The `signingSecret` rule a webhook's verification scheme carries, decided
+ * from the declaration alone (#3320).
+ *
+ * `signingSecret` is reference-only (#2254): a whole `{{secrets.KEY}}`
+ * reference naming an app secret, and nothing else. Which schemes need one,
+ * whether one was supplied, and whether the supplied value is a reference are
+ * all answerable from the file — so they belong in the `config push` preflight,
+ * which aborts before anything is applied, rather than in the apply loop where
+ * a refusal lands after sibling entities are already written.
+ *
+ * That is the whole reason this module exists here rather than beside the rest
+ * of the webhook write pipeline: `src/config-surface/` is vendored verbatim
+ * into `cli/src/lib/generated-config-surfaces.ts`, so the CLI runs the server's
+ * rule instead of a restatement of it, and a change that is not regenerated
+ * fails `gen-config-surfaces.mjs --check`.
+ *
+ * ── What is deliberately NOT here ─────────────────────────────────────────
+ *
+ * Everything that needs the app's state: whether the referenced secret exists,
+ * whether the scheme's `config` is valid under this environment's JWKS policy,
+ * the per-app row cap, a key a standalone webhook already holds. Those stay in
+ * `src/app-api/services/webhook-settings-validation.ts`, which has `Env`. A
+ * local copy of them would be a preflight that gives a false all-clear — and
+ * the residue is then app-state-dependent by construction rather than by
+ * accident of where a rule happened to live.
+ */
+/**
+ * Schemes that don't carry an HMAC `signingSecret`. These either store no key
+ * material at all (`none`) or store it under `AppWebhook.config` instead:
+ * `discord` puts the application public key in `config.publicKey`, `jwt` puts
+ * a JWKS in `config.jwt.jwks`, and `plaid` fetches keys from Plaid using the
+ * API credentials referenced in `config.plaid`.
+ */
+export declare const SCHEMES_WITHOUT_SIGNING_SECRET: readonly string[];
+export declare function requiresSigningSecret(scheme: unknown): boolean;
+/** The coded refusals, so a client can branch without matching prose. */
+export declare const SIGNING_SECRET_MUST_BE_SECRET_REF = "SIGNING_SECRET_MUST_BE_SECRET_REF";
+export declare const SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME = "SIGNING_SECRET_NOT_SUPPORTED_FOR_SCHEME";
+/**
+ * A refusal from this rule. `plain` marks the ones the admin webhook create
+ * answered as a bare text body rather than coded JSON — an observable
+ * distinction, so it travels with the error rather than being flattened.
+ */
+export interface SigningSecretRuleError {
+    message: string;
+    code?: string;
+    plain?: boolean;
+}
+/** The reference-only message, shared by every field that carries one. */
+export declare function wholeSecretReferenceMessage(label: string): string;
+/**
+ * Is this value a whole `{{secrets.KEY}}` reference? Returns the refusal a
+ * caller renders, or null.
+ *
+ * `isWholeSecretReference`, never `isSecretTemplate`: a *contains* test admits
+ * `sk_live_abcd{{secrets.SUFFIX}}`, which stores most of a working credential
+ * in cleartext.
+ */
+export declare function validateWholeSecretReference(label: string, value: unknown, code: string): SigningSecretRuleError | null;
+/**
+ * The whole file-decidable `signingSecret` rule, in the order the standalone
+ * webhook create ran it: a required secret must be present, a present one must
+ * be a whole reference, and a scheme that carries no secret must not be given
+ * one.
+ *
+ * Returns null when the declaration is acceptable — which does NOT mean the
+ * write will succeed: the referenced key still has to exist, and that is the
+ * server's question.
+ */
+export declare function validateSigningSecretDeclaration(input: {
+    verificationScheme: string;
+    signingSecret?: unknown;
+}): SigningSecretRuleError | null;
 export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;