primitive-admin 1.1.0-alpha.74 → 1.1.0-alpha.76

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

@@ -578,6 +578,346 @@ export interface RetiredConfigKey {
 export declare const RETIRED_CONFIG_KEYS: Record<string, Record<string, RetiredConfigKey>>;
 /** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
 export declare function retiredConfigKey(prefix: string, key: string): RetiredConfigKey | null;
+/**
+ * The capability grammar for server functions — #3182 phase 1, rewritten by
+ * #3279 (project `server-functions` phase 3).
+ *
+ * A function declares in its own TOML what it may CONFIGURE:
+ *
+ *   capabilities = ["integration:stripe", "secret:STRIPE_KEY", "databases:delete"]
+ *
+ * ── Why the grammar is this small ────────────────────────────────────────
+ *
+ * The intent's decision (2026-09-09, "Authorization inside a function?"):
+ * function code acts as the system. The invocation gate is the authorization,
+ * and inside a function every platform call carries the app's own authority in
+ * every family. A capability is therefore never a statement about DATA — a
+ * model, a prompt, a channel, a member — because the function may reach all of
+ * it. It is declared only where it configures something:
+ *
+ *   `integration:<key>`   the egress allowlist — which upstream hosts the
+ *                         function's outbound calls may reach;
+ *   `secret:<NAME>`       credential least privilege — which secret VALUES may
+ *                         cross into the sandbox at all;
+ *   the high-blast list   {@link HIGH_BLAST_CAPABILITIES} — the operations
+ *                         whose blast radius the intent keeps opt-in.
+ *
+ * Every other string a function used to declare is RETIRED, and the grammar
+ * says so by name: an author who still writes `database:orders/Order:read`
+ * is told the model changed and what stays, not "unknown family", which would
+ * send them to check their spelling.
+ *
+ * ── Why the components have a charset ────────────────────────────────────
+ *
+ * A keyed grant's key must match `[A-Za-z0-9_-]+`, so neither `:` nor `/` can
+ * enter a component and the string is INJECTIVE — one string, one object. An
+ * integration or secret whose key carries a delimiter is simply unreachable
+ * from functions, with an error that says why (D3182-001's argument, kept).
+ *
+ * ── Why this module is pure ──────────────────────────────────────────────
+ *
+ * Capabilities are validated twice — by `config push`'s preflight, so an
+ * author sees the error against their own file, and by the server, which is
+ * authoritative because the raw admin API exists. Two enforcement points must
+ * not be two grammars, so the grammar lives here, in the dependency-free
+ * `src/config-surface/` tree the CLI vendors at build time
+ * (`cli/scripts/gen-config-surfaces.mjs`). The server imports this module; the
+ * CLI imports the generated copy; the drift guard fails if they differ.
+ */
+/** Every component of a grant. Injectivity depends on this. */
+export declare const GRANT_COMPONENT_PATTERN: RegExp;
+/** `ServerFunctionConfig.capabilities` is a StringSet with these bounds. */
+export declare const MAX_CAPABILITY_ENTRIES = 100;
+export declare const MAX_CAPABILITY_ENTRY_LENGTH = 200;
+/**
+ * The two keyed families the intent keeps: one component under
+ * {@link GRANT_COMPONENT_PATTERN}, naming a single object. Every key format the
+ * platform issues fits: an integration key is `^[a-z0-9][a-z0-9-_]{2,}$` and a
+ * secret name is `^[A-Z][A-Z0-9_]{0,63}$`.
+ */
+export declare const KEYED_GRANT_FAMILIES: readonly ["integration", "secret"];
+/**
+ * The high-blast-radius opt-ins — #3279, criterion 5 (CR3279-001, D3279-003).
+ *
+ * Since function code acts as the system, admission to a family is no longer
+ * an authority statement: everything the gateway lets through runs with the
+ * app's own authority. Most operations are fine that way — that is the whole
+ * decision. A short list is not, and the intent names its categories: delete a
+ * database, app or user; role changes; secret changes; resource provisioning.
+ * Those stay opt-in, so a function that can do them says so in a reviewable
+ * line of its TOML.
+ *
+ * The strings are EXACT and 1:1 with the operation id, so there is nothing to
+ * look up: `users.setRole` needs `users:setRole`. They parse with the verb as
+ * their KEY, because two exact capabilities in one family must not cover each
+ * other — `databases:create` is not permission to delete a database.
+ *
+ * The database ROLE mutations are here because they hand out persistent
+ * authority: a group grant assigns the manager role (D3279-003). App deletion
+ * and secret writes have no app-API route today; they are recorded, not gated,
+ * and the profile generator refuses to admit a future such route without a row
+ * here (`HIGH_BLAST_WATCH` in `scripts/lib/function-profile.mjs`).
+ */
+export declare const HIGH_BLAST_CAPABILITIES: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
+/** The exact strings, which since #3279 are exactly the high-blast list. */
+export declare const EXACT_GRANT_STRINGS: readonly ["databases:create", "databases:delete", "databases:transferOwnership", "databases:addManager", "databases:revokePermission", "databases:grantGroupPermission", "databases:revokeGroupPermission", "users:remove", "users:setRole", "blobBuckets:createBucket", "blobBuckets:deleteBucket"];
+export type GrantFamily = (typeof KEYED_GRANT_FAMILIES)[number] | "databases" | "users" | "blobBuckets";
+/**
+ * The retired FAMILIES (#3279), each with the reason it is gone.
+ *
+ * The value is what the family used to authorize, phrased as what a function
+ * now reaches without it. A refusal names the authored string, says it is
+ * retired, gives this reason, tells the author to delete the entry, and lists
+ * what stays.
+ */
+export declare const RETIRED_GRANT_FAMILIES: Record<string, string>;
+/** The retired EXACT strings (#3279), on the same terms. */
+export declare const RETIRED_GRANT_STRINGS: Record<string, string>;
+/**
+ * The retirement sentence for one authored string, or null when the string is
+ * not a retired one.
+ *
+ * Exported so the enforcement-time reader (`loadConfigGrants`) can tell a
+ * retired string on a pre-change row — tolerated, logged — from a string that
+ * was never a grant at all, which still authorizes nothing.
+ */
+export declare function retiredGrantRefusal(raw: string): string | null;
+/**
+ * Any grant, in one flat shape.
+ *
+ * Flat rather than a discriminated union because this module is vendored into
+ * the CLI, which compiles with `strict: false`: a caller reads `family` and
+ * then `key`, and the fields another family would have used are simply absent.
+ */
+export interface FunctionGrant {
+    family: GrantFamily;
+    /**
+     * The single component of a keyed family — the integration key or the
+     * secret name — or the VERB of a high-blast string (`delete` for
+     * `databases:delete`), so that no two exact capabilities in one family read
+     * as the same grant.
+     */
+    key: string;
+    /** The authored string, so an error or a log line can quote it. */
+    raw: string;
+}
+export interface ParsedFunctionGrant {
+    grant?: FunctionGrant;
+    error?: string;
+}
+/**
+ * A channel name's ceiling, and the reason it has one.
+ *
+ * The name rides in a `ConnectionMapping` row's document-id slot as
+ * `ch:<appId>:<channel>` and in every grant token's claims, so an unbounded
+ * name would be an unbounded key and an unbounded credential. 200 characters
+ * is {@link MAX_CAPABILITY_ENTRY_LENGTH}, kept for continuity with the rows
+ * #3184 already wrote.
+ */
+export declare const MAX_CHANNEL_NAME_LENGTH = 200;
+export interface ParsedChannelName {
+    /** The segment before the first `:`. Absent when the name is refused. */
+    namespace?: string;
+    error?: string;
+}
+/**
+ * A channel NAME, and its namespace.
+ *
+ * The grammar is the grant component charset applied per segment: one or more
+ * `[A-Za-z0-9_-]+` segments joined by `:`. The `channel:<namespace>` GRANT
+ * that used to cover a name is retired (#3279); the name grammar stays because
+ * the authorize and publish routes answer 400 about a name outside it before
+ * anything else, and the connection worker keys membership by it.
+ *
+ * Refusals name the segment that failed, because "channel name is invalid" on
+ * a name like `orders:a::b` tells an author nothing they cannot already see.
+ */
+export declare function parseChannelName(value: unknown): ParsedChannelName;
+/**
+ * One capability entry as a grant, or the reason it is not one.
+ *
+ * The single entry point the enforcement path and both preflights use: a
+ * caller holds one authored string and asks what it grants, without having to
+ * know which of the shapes to try. Every diagnosis is specific — a retired
+ * string gets the retirement and what stays; a near miss in a kept family gets
+ * the family's own strings; a keyed family gets its charset rule.
+ */
+export declare function parseFunctionGrant(entry: unknown): ParsedFunctionGrant;
+/**
+ * One shape rather than a discriminated union: this module is vendored into
+ * the CLI, which compiles with `strict: false`, where narrowing on a boolean
+ * literal discriminant does not hold. Both callers read `ok` and then the
+ * field they want, and the unused half is empty rather than absent.
+ */
+export interface ParsedCapabilities {
+    ok: boolean;
+    /** Deduped, in authored order — what the config row stores. Empty when refused. */
+    capabilities: string[];
+    /** Every grant, in authored order. */
+    allGrants: FunctionGrant[];
+    /**
+     * The retired strings that were SKIPPED, in authored order — populated only
+     * under `tolerateRetired` (see {@link parseCapabilities}); a strict parse
+     * refuses them instead and leaves this empty.
+     */
+    retired: string[];
+    /** Empty when accepted. */
+    errors: string[];
+}
+export interface ParseCapabilitiesOptions {
+    /**
+     * Skip retired strings instead of refusing them — #3279 edge 25.
+     *
+     * The PUSH path is strict: a file that still declares a retired grant is
+     * refused with the retirement, because a line that is accepted and ignored
+     * is a line the author believes means something. The ENFORCEMENT path is
+     * tolerant: a config version pushed before #3279 carries retired strings in
+     * a row that can never be re-pushed to fix (its envelope is immutable), and
+     * refusing it there would break every function pushed before the change.
+     * Such a row authorizes exactly what it keeps, and the skipped strings are
+     * reported in `retired` so the caller can log them.
+     */
+    tolerateRetired?: boolean;
+}
+/**
+ * A whole `capabilities` list: shape, bounds, grammar, duplicates.
+ *
+ * The model's own caps are checked HERE rather than left to the StringSet
+ * field, so an over-long entry is a named push error instead of a late model
+ * throw after the R2 object has already been written (principle 6).
+ */
+export declare function parseCapabilities(value: unknown, options?: ParseCapabilitiesOptions): ParsedCapabilities;
+/**
+ * The config-tree objects an `integration:` grant may name.
+ *
+ * Only the one family whose target is CONFIG-TREE state. `secret:` is absent
+ * on purpose (D3183-002): its values are provisioned per environment, out of
+ * band, and are not part of the reviewed tree at all, so the ordinary order of
+ * work is to push the function and then provision the value. Refusing an
+ * unprovisioned name at push would break that; a missing value at CALL time is
+ * a structured runtime error instead. The high-blast strings name no object.
+ *
+ * `null` means "this enforcement point could not find out". The CLI reads the
+ * tree and, when it can, a live listing; when neither is available it defers
+ * rather than guessing, because a preflight that refused a valid tree for
+ * being offline would be worse than one that lets the server have the last
+ * word. The server never passes null — it can always read its own rows.
+ */
+export interface KnownGrantTargets {
+    /** Non-archived integration keys, or null when unknown. */
+    integrations: ReadonlySet<string> | null;
+}
+/**
+ * Grants naming an integration the app does not have.
+ *
+ * One message per offending grant, quoting the whole authored string AND the
+ * key on its own, so an operator reading the line knows both what to fix in
+ * the file and what to create in the app.
+ *
+ * The rule is here, beside the grammar, for the reason the whole module
+ * exists: `config push`'s preflight and the authoritative server check read
+ * different sources for the same facts — a `.toml` in the tree versus a row
+ * in DynamoDB — and it is the RULE that must not differ between them.
+ */
+export declare function validateKeyedGrantsAgainstTargets(grants: readonly FunctionGrant[], known: KnownGrantTargets): string[];
+/**
+ * The query manifest's grammar, and the read rule it unlocks — #3187, project
+ * `server-functions` phase 5.
+ *
+ * A pushed config version may carry a MANIFEST: the queries and mutations the
+ * tree registered at module scope, collected by the CLI (`function-collect.ts`)
+ * by running the tree with `primitive-functions` aliased to a recording stub.
+ *
+ * ── What the manifest is for ─────────────────────────────────────────────
+ *
+ * Observability, and nothing else. `primitive functions get` and the admin
+ * get list what a version registered, so an operator can see it without
+ * reading the bundle (principle 8). The read rule it used to be decided from
+ * (#3187's `$caller` relaxation of `unscopedReads`) is retired by #3279:
+ * function code acts as the system, so there is no per-model grant for a
+ * binding to waive. The intent says so in as many words — "the models a
+ * function touches are collected at push as a reviewable manifest, not an
+ * authorization".
+ *
+ * It is HONEST-CODE evidence and the design doc says so: a hostile bundle can
+ * register whatever it likes, because the collector runs the tenant's own
+ * code. Nothing security-relevant at runtime reads it — parameter injection
+ * and cache verification happen in the platform-owned SDK inside the isolate,
+ * and the invocation gate remains the adversarial boundary.
+ *
+ * ── Why the grammar is here ──────────────────────────────────────────────
+ *
+ * Same reason as `function-grants.ts`: the CLI validates at push preflight so
+ * an author sees the error against their own tree, and the server validates
+ * authoritatively because the raw admin API exists. Two enforcement points,
+ * one rule, in the dependency-free tree the CLI vendors.
+ */
+/**
+ * The manifest encoding, versioned with the envelope that carries it.
+ *
+ * Version 2 (#3279 behavior 10) adds what a function TOUCHES beside what it
+ * registers: the deduplicated `models` its code names and the `families` of
+ * `ctx.api` and the ctx helpers it reaches, collected by a static scan of the
+ * built bundle, plus a `dynamicModels` marker for a model name the scan
+ * could not resolve — distinct from an empty list, which means "names none".
+ * A version-1 manifest still parses: it records registrations only.
+ */
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSION = 2;
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSIONS: readonly [1, 2];
+/** Bounds, so a manifest cannot be a way to store an unbounded blob. */
+export declare const MAX_MANIFEST_QUERIES = 200;
+export declare const MAX_MANIFEST_NAME_LENGTH = 120;
+export declare const MAX_MANIFEST_MODELS = 200;
+export declare const MAX_MANIFEST_FAMILIES = 40;
+export interface ManifestParam {
+    type?: string;
+    caller?: boolean;
+    optional?: boolean;
+    default?: unknown;
+}
+export interface ManifestQuery {
+    name: string;
+    kind: "query" | "mutation";
+    models: string[];
+    params: Record<string, ManifestParam>;
+    cache: {
+        ttlMs: number;
+    } | null;
+    /** True when a `$caller` binding scopes this registration. */
+    callerScoped: boolean;
+}
+export interface FunctionManifest {
+    schemaVersion: number;
+    queries: ManifestQuery[];
+    /**
+     * Every model name the bundle names, deduplicated and sorted: registration
+     * declarations, literal `.model("…")` calls, and literal `modelName`/`model`
+     * arguments of the direct records and documents calls (#3279). Empty for a
+     * version-1 manifest, and for a function that names none.
+     */
+    models: string[];
+    /** Every `ctx.api.<family>` and ctx-helper family the bundle reaches. */
+    families: string[];
+    /**
+     * The scan met a model name it could not resolve — a computed
+     * `modelName`, a `.model(variable)`. Says "and possibly more", which an
+     * empty `models` list does not.
+     */
+    dynamicModels: boolean;
+}
+export interface ParsedManifest {
+    ok: boolean;
+    manifest: FunctionManifest | null;
+    errors: string[];
+}
+/**
+ * Validate a manifest's grammar and normalize it.
+ *
+ * Deliberately strict about SHAPE and silent about meaning: whether the models
+ * exist, whether the queries are the ones the sandbox will really register,
+ * and whether the author meant any of it are questions this cannot answer.
+ */
+export declare function parseFunctionManifest(value: unknown): ParsedManifest;
 export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;