@xano/cli 1.3.4 → 1.3.5-beta.0

package/dist/utils/policy/template.js

@@ -0,0 +1,152 @@
+import { POLICY_KEY_PATTERN } from '../document-parser.js';
+/**
+ * The refusal of a recipe id given to `--template`: recipes have no create action, so it names the
+ * recipe's templates in the order to create them and, when it has rules no template covers, where
+ * they are shown.
+ */
+export function recipeRefusal(recipe) {
+    const templates = Array.isArray(recipe.templates) ? recipe.templates : [];
+    const rules = Array.isArray(recipe.rules) ? recipe.rules.length : 0;
+    const steps = templates.length > 0
+        ? ` Create its templates in order with --template, one policy each: ${templates.join(', ')}.`
+        : '';
+    const own = rules > 0 ? ` ${rules === 1 ? 'The rule' : `The ${rules} rules`} no template covers ${rules === 1 ? 'goes' : 'go'} in a policy of your own (\`xano policy publish\`).` : '';
+    return `"${recipe.id}" is a recipe (${recipe.title}), not a template, and a recipe has no create action.${steps}${own} Run \`xano policy catalogue --recipe ${recipe.id}\` for what to set up first and the rules.`;
+}
+/**
+ * The policy document for a template: its sparse settings with the `--param` assignments applied, every
+ * `needs` path filled (at least one of a rule's when it says `needs_any`), and a key no policy on the
+ * branch holds (compared case-insensitively). A taken template key gets a free numeric suffix; a taken or
+ * malformed `--key` is refused.
+ */
+export function policyFromTemplate(template, takenKeys, options = {}) {
+    const { checks = [], key, keyRule, overrides = [] } = options;
+    const taken = new Set(takenKeys.map(value => value.toLowerCase()));
+    let chosen = key ?? template.key;
+    if (!keyPattern(keyRule).test(chosen))
+        throw new Error(keyRefusal(keyRule, chosen));
+    if (key !== undefined && taken.has(chosen.toLowerCase()))
+        throw new Error(`Policy ${chosen} already exists. Choose a new --key or use policy publish to update it.`);
+    for (let suffix = 2; taken.has(chosen.toLowerCase()); suffix++)
+        chosen = `${template.key.slice(0, 63 - String(suffix).length)}-${suffix}`;
+    const rules = template.rules.map(rule => ({ check: rule.check, params: Array.isArray(rule.params) ? {} : structuredClone(rule.params), title: rule.title }));
+    for (const assignment of overrides)
+        applyOverride(rules, assignment);
+    const missing = template.rules.flatMap((rule, index) => missingNeeds(rule, rules[index].params, index));
+    if (missing.length > 0)
+        throw new Error(`Fill the template's required settings with --param 'N.path=JSON': ${missing.join(', ')}.${exampleHint(template, checks, missing)}`);
+    return { key: chosen, rules, severity: template.severity, statement: template.summary, title: template.title };
+}
+/**
+ * An example for the first unfilled need that has one, as a `--param` to copy
+ * (` For example: --param '1.names=["audit_log"]'.`), or '' when none has: the template's own example
+ * for the path, else the example its check's catalogue entry gives for that param, as Studio shows it.
+ * The rule number is left off for a single-rule template, as `--param` takes it.
+ */
+function exampleHint(template, checks, missing) {
+    const examples = template.examples && typeof template.examples === 'object' && !Array.isArray(template.examples) ? template.examples : {};
+    for (const entry of missing.flatMap(item => item.split(' or '))) {
+        const dot = entry.indexOf('.');
+        const path = entry.slice(dot + 1);
+        const rule = template.rules[Number(entry.slice(0, dot)) - 1];
+        const example = Object.hasOwn(examples, path) ? examples[path] : checkExample(checks.find(check => check.id === rule?.check), path);
+        if (example === undefined)
+            continue;
+        const name = template.rules.length === 1 ? path : entry;
+        return ` For example: --param '${name}=${JSON.stringify(example)}'.`;
+    }
+    return '';
+}
+/** The catalogue's `example` for a param path of a check (`table_selector.has_field` reads a part's), or undefined. */
+function checkExample(check, path) {
+    let schemas = check?.params;
+    let schema;
+    for (const part of path.split('.')) {
+        if (!schemas || typeof schemas !== 'object' || !Object.hasOwn(schemas, part))
+            return undefined;
+        schema = schemas[part];
+        schemas = schema?.properties;
+    }
+    return schema?.example;
+}
+/** The catalogue's key pattern, or the offline copy when the catalogue serves none (or one that does not compile). */
+function keyPattern(rule) {
+    if (typeof rule?.pattern !== 'string' || rule.pattern === '')
+        return POLICY_KEY_PATTERN;
+    try {
+        return new RegExp(rule.pattern);
+    }
+    catch {
+        return POLICY_KEY_PATTERN;
+    }
+}
+/** The catalogue's refusal for a malformed key, naming it, or the offline sentence. */
+function keyRefusal(rule, key) {
+    return typeof rule?.message === 'string' && rule.message.trim()
+        ? rule.message.replaceAll('%s', key)
+        : 'A policy key must be 1–64 letters, digits, dots, underscores or hyphens, starting with a letter or digit.';
+}
+/**
+ * A rule's unfilled `needs`, each as `N.path`: every unfilled one, or, for a `needs_any` rule with none
+ * filled, one entry naming the alternatives (`1.hosts or 1.providers`).
+ */
+function missingNeeds(rule, params, index) {
+    const needs = (rule.needs ?? []).map(path => ({ filled: filled(readPath(params, path)), name: `${index + 1}.${path}` }));
+    if (rule.needs_any === true && needs.length > 1)
+        return needs.some(need => need.filled) ? [] : [needs.map(need => need.name).join(' or ')];
+    return needs.filter(need => !need.filled).map(need => need.name);
+}
+/** The value at a dotted path of a rule's params, or undefined when any step is missing. */
+function readPath(params, path) {
+    let value = params;
+    for (const part of path.split('.')) {
+        if (!value || typeof value !== 'object' || !Object.hasOwn(value, part))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+/** Whether a `needs` value is set: not empty, null or blank; `false` and `0` count as set. */
+function filled(value) {
+    if (Array.isArray(value))
+        return value.some(item => filled(item));
+    if (value && typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return value !== undefined && value !== null && (typeof value !== 'string' || value.trim() !== '');
+}
+/** Apply one `--param [N.]path=JSON` assignment to its rule's params, refusing unsafe paths and non-JSON values. */
+function applyOverride(rules, assignment) {
+    const equals = assignment.indexOf('=');
+    if (equals < 1)
+        throw new Error('Use --param path=JSON or --param N.path=JSON (rule numbers start at 1).');
+    const parts = assignment.slice(0, equals).split('.');
+    let index = 0;
+    if (/^\d+$/.test(parts[0]))
+        index = Number(parts.shift()) - 1;
+    else if (rules.length !== 1)
+        throw new Error('Include the rule number in --param N.path=JSON for a template with multiple rules.');
+    if (!Number.isSafeInteger(index) || !rules[index])
+        throw new Error(`Rule ${index + 1} does not exist in this template.`);
+    if (parts.length === 0 || parts.some(part => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part) || ['__proto__', 'constructor', 'prototype'].includes(part)))
+        throw new Error('Invalid parameter path. Use parameter names separated by dots.');
+    let value;
+    try {
+        value = JSON.parse(assignment.slice(equals + 1), (_key, parsed) => {
+            if (typeof parsed === 'number' && !Number.isFinite(parsed))
+                throw new Error('Numbers must be finite.');
+            return parsed;
+        });
+    }
+    catch {
+        throw new Error(`The value for ${assignment.slice(0, equals)} must be JSON: a quoted string, finite number, boolean, array or object.`);
+    }
+    let target = rules[index].params;
+    for (const part of parts.slice(0, -1)) {
+        if (target[part] === undefined)
+            target[part] = {};
+        if (!target[part] || typeof target[part] !== 'object' || Array.isArray(target[part]))
+            throw new Error(`Cannot set a nested parameter inside ${part}.`);
+        target = target[part];
+    }
+    target[parts.at(-1)] = value;
+}

package/dist/utils/policy/types.d.ts

@@ -0,0 +1,295 @@
+/** The shapes the policy routes answer with. Policy grammar belongs to the platform. */
+export interface PolicyCatalogueEntry {
+    description?: string;
+    fix_hint?: string;
+    id: string;
+    /** The check's human name. */
+    label: string;
+    object_kinds?: string[];
+    params?: Record<string, PolicyParamSchema>;
+    /** Params of which a rule must set at least one. */
+    requires_one_of?: string[];
+    /** Goals in a customer's words, each with the complete params (scope params included) that achieve it. */
+    uses?: PolicyCheckUse[];
+}
+/** One of a check's `uses`: a goal and a rule's params its check accepts as written. */
+export interface PolicyCheckUse {
+    goal: string;
+    /** What to know before using it, when the goal alone could mislead. */
+    note?: string;
+    /** PHP sends an empty map as `[]`. */
+    params: Record<string, unknown> | unknown[];
+}
+/** One param as the catalogue describes it: a nested object's parts are its `properties`. */
+export interface PolicyParamSchema {
+    /** A value that fits the param, shown as a hint; never filled in. */
+    example?: unknown;
+    properties?: Record<string, PolicyParamSchema>;
+    required?: boolean;
+    type?: string;
+}
+/** One rule as a run snapshot records it: the settings the check ran with, plus the check's label. */
+export interface PolicySnapshotRule {
+    check?: string;
+    id?: string;
+    label?: string;
+    /** The resolved settings; PHP sends an empty map as `[]`. */
+    params?: unknown;
+    title?: string;
+}
+/** One policy as a run snapshot records it, including the description it carried at run time. */
+export interface PolicySnapshotPolicy {
+    key?: string;
+    rules?: PolicySnapshotRule[];
+    /** The policy description as written at run time. */
+    statement?: string;
+    title?: string;
+    /** The Version History index this run evaluated. */
+    version?: number;
+}
+export interface PolicyRuleResult {
+    check_id?: string;
+    checked?: number;
+    message?: string;
+    policy_key?: string;
+    status?: string;
+    warnings?: string[];
+}
+export interface PolicyFinding {
+    /** Stable finding id, used to tell a blocking finding from an advisory one. */
+    id?: string;
+    message?: string;
+    object?: {
+        id?: number;
+        name?: string;
+        type?: string;
+    };
+    policy_key?: string;
+    policy_title?: string;
+    rule_id?: string;
+    rule_title?: string;
+    severity?: string;
+}
+/**
+ * A finding as the platform trims it for a caller without `workspace:policy` read (`access:
+ * "coverage"`): no rule id, severity, params or `allow`, but the check's label, first description
+ * sentence and fix hint, and whether it blocks.
+ */
+export interface CoverageFinding extends PolicyFinding {
+    blocking?: boolean;
+    /** `null` when the rule can no longer be resolved (a deleted policy, a rule removed since the run). */
+    check?: null | {
+        description?: string;
+        fix_hint?: string;
+        label?: string;
+    };
+    /** Coverage only: the run evaluated a policy the branch no longer holds. */
+    deleted?: boolean;
+}
+/** The verdict every `policy_check` carries. */
+export interface PolicyVerdict {
+    /** True when an active, blocking policy failed; it decides the exit code whatever the status. */
+    blocking?: boolean;
+    /** The platform's verdict, including the names of rules that checked no objects. */
+    message?: string;
+    run_id?: number;
+    /**
+     * `pass`, `fail` or `error` (a check could not run) for an evaluation; `disabled`,
+     * `not_applicable` or `unavailable` when nothing was evaluated. An older platform answers
+     * `forbidden` to a caller without `workspace:policy` read, which is reported like any other
+     * status it has no headline for.
+     */
+    status?: string;
+}
+/** A run's finding counts: every finding, the blocking ones, and the rules that could not run. */
+export interface PolicyCounts {
+    /** The findings that do not block; the run summary serves it, a push's feedback does not. */
+    advisory?: number;
+    blocking: number;
+    errors: number;
+    findings: number;
+}
+/**
+ * A push's `policy_check`: the verdict with its findings and results, since a push answers no run.
+ * The lists hold the first 100 each, in the platform's order; the stored run (`run_id`) has them all.
+ */
+export interface PushPolicyCheck extends PolicyVerdict {
+    /**
+     * `coverage` for a caller without `workspace:policy` read: the findings are only those on the
+     * objects the push carried that the caller may read (the workspace too, for a push that carried
+     * the workspace document and a caller with `workspace:settings` read), trimmed (`CoverageFinding`),
+     * with `run_id` 0, `results` empty and a `note`. `counts` are about those findings, except
+     * `counts.errors` (the branch's); `blocking` is what a reader's push of the same change says, so
+     * the exit code is the same whoever pushed.
+     */
+    access?: string;
+    /** The first blocking findings. */
+    blocking_findings?: PolicyFinding[];
+    /** What the lists are out of. */
+    counts?: PolicyCounts;
+    /**
+     * A trimmed answer's count of the findings on the objects the push does not list (never named).
+     * `basis` `introduced`: those the push introduced (not in the push gate's evaluation of the branch
+     * before it on the live branch; elsewhere not in the newest run that still described the branch);
+     * `all`: no baseline was known, so every finding there. An older platform sends no `basis`.
+     */
+    elsewhere?: {
+        basis?: string;
+        blocking?: number;
+        total?: number;
+    };
+    /** The first findings, blocking first. */
+    findings?: PolicyFinding[];
+    /** The platform's sentence on what a trimmed answer leaves out (`access: "coverage"`). */
+    note?: string;
+    results?: PolicyRuleResult[];
+    /** `pushed_objects` beside `access: "coverage"`: the findings are about the pushed objects only. */
+    scope?: string;
+    /** Every finding, listed or not. */
+    total?: number;
+    /** Whether either list was cut. */
+    truncated?: boolean;
+}
+/** One policy that applies to an object, as the coverage route serves it. */
+export interface ObjectCoveragePolicy {
+    blocking?: boolean;
+    /** `blocking` or `advisory`. */
+    enforcement?: string;
+    key?: string;
+    /** Why it applies here, one plain sentence per rule. */
+    reasons?: string[];
+    /**
+     * `failing` (a finding of it here), `not_checked` (no run, or the run did not evaluate it as it now
+     * stands), `could_not_check` (the run could not check it: a rule of it could not run, or the run
+     * stopped on an error before it) or `passing`, which a run that errored on another policy still gives.
+     */
+    status?: string;
+    title?: string;
+}
+/**
+ * `GET policy/object/coverage`: which active policies apply to one object, and its findings in the
+ * branch's newest run, trimmed for anyone who may read the object (`workspace:policy` read is not
+ * needed). The same trimmed shape for every caller.
+ */
+export interface ObjectCoverage {
+    access?: string;
+    findings?: CoverageFinding[];
+    note?: string;
+    object?: {
+        app_id?: number;
+        id?: number;
+        name?: string;
+        type?: string;
+    };
+    policies?: ObjectCoveragePolicy[];
+    /** The branch's newest ended run, `null` before the first. */
+    run?: null | {
+        started_at?: string;
+        status?: string;
+    };
+    summary?: {
+        advisory?: number;
+        applies?: number;
+        blocking?: number;
+        /** The policies that apply whose status is `could_not_check`; an older platform does not send it. */
+        could_not_check?: number;
+        not_checked?: number;
+        passing?: number;
+        /**
+         * `none_apply`, `findings`, `not_checked`, `check_failed` (only when a policy that applies here
+         * could not be checked) or `pass`.
+         */
+        state?: string;
+    };
+}
+/** A policy's place in its branch's newest run, as the platform serves it on every policy. */
+export interface PolicyCoverage {
+    enforcement: null | string;
+    /** Whether the newest run evaluated this policy at all. */
+    included: boolean;
+    /** 0 when the branch has no run. */
+    run_id: number;
+    /** True only when the newest run evaluated a different version of this policy. */
+    stale: boolean;
+    version: null | number;
+}
+export interface Policy {
+    active: boolean;
+    enforcement: string;
+    id: number;
+    key: string;
+    latest_run?: PolicyCoverage;
+    rules?: Array<{
+        id: string;
+    }>;
+    title?: string;
+    /** When the policy was last written, as served; sent back as `last_updated_at` to refuse acting on a stale read. */
+    updated_at?: number | string;
+    /** The index of the policy's newest Version History entry; it moves only when the definition changes. */
+    version: number;
+}
+/** One stored run as the run list serves it: the verdict and counts, without findings or results. */
+export interface PolicyRunSummary {
+    counts: {
+        blocking: number;
+        errors: number;
+        findings: number;
+    };
+    finished_at?: string;
+    id: number;
+    objects_checked: number;
+    started_at?: string;
+    status: string;
+    trigger?: string;
+}
+/** One run in full, as `GET run/{id}` serves it. */
+export interface PolicyRun {
+    findings?: PolicyFinding[];
+    finished_at?: number | string;
+    /** 0 for an evaluation that was not stored. */
+    id?: number;
+    /** How many workspace objects the run inspected. */
+    objects_checked?: number;
+    /** The snapshot of the policies as they were when the run went out. */
+    policies?: PolicySnapshotPolicy[];
+    results?: PolicyRuleResult[];
+    started_at?: number | string;
+    status?: string;
+    trigger?: string;
+}
+/**
+ * What `policy evaluate` answers: the run as `GET run/{id}` serves it, whether it was stored, and the verdict.
+ * With no active policy on the branch it is no run at all: `id` 0, `status` `not_applicable`, nothing evaluated.
+ */
+export interface PolicyEvaluation extends PolicyRun {
+    /** The summary answer's counts (`--summary`). */
+    counts?: PolicyCounts;
+    /** `blocking_total`: every blocking finding, beside the summary answer's listed ones. */
+    policy_check?: PolicyVerdict & {
+        blocking_finding_ids?: string[];
+        blocking_total?: number;
+    };
+    stored?: boolean;
+    /** The summary answer: every finding, and whether `findings` lists only the first. */
+    total?: number;
+    truncated?: boolean;
+}
+/** One run without its findings, as `GET run/{id}/summary` serves it. */
+export interface PolicyRunHead extends PolicyRun {
+    counts?: PolicyCounts;
+    /** The snapshot, each policy with its verdict in this run. */
+    policies?: Array<PolicySnapshotPolicy & {
+        blocking?: boolean;
+        findings?: number;
+        objects_checked?: number;
+        status?: string;
+    }>;
+}
+/** One page of a run's findings, as `GET run/{id}/findings` serves it. */
+export interface PolicyFindingsPage {
+    items: PolicyFinding[];
+    limit: number;
+    offset: number;
+    /** The findings that match the filters, listed or not. */
+    total: number;
+}

package/dist/utils/policy/types.js

@@ -0,0 +1 @@
+export {};