@norskvideo/ctl-product-template-schema 0.1.87 → 0.1.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { type JsonParamSchema } from "./params.js";
2
3
  import { LISTENER_KINDS } from "./port-bindings.js";
3
4
  export declare const ProductTemplateTargetSchema: z.ZodEnum<{
4
5
  "docker-compose": "docker-compose";
@@ -498,6 +499,7 @@ export declare const STANDARD_ADVANCED_OVERRIDES: {
498
499
  readonly containerUser: {};
499
500
  readonly publicHost: {};
500
501
  };
502
+ export declare const JsonParamSchemaSchema: z.ZodType<JsonParamSchema>;
501
503
  export declare const ProductTemplateParameterSchema: z.ZodObject<{
502
504
  name: z.ZodString;
503
505
  purpose: z.ZodString;
@@ -507,6 +509,7 @@ export declare const ProductTemplateParameterSchema: z.ZodObject<{
507
509
  boolean: "boolean";
508
510
  int: "int";
509
511
  enum: "enum";
512
+ json: "json";
510
513
  }>>;
511
514
  default: z.ZodOptional<z.ZodString>;
512
515
  secret: z.ZodOptional<z.ZodBoolean>;
@@ -518,6 +521,7 @@ export declare const ProductTemplateParameterSchema: z.ZodObject<{
518
521
  min: z.ZodOptional<z.ZodNumber>;
519
522
  max: z.ZodOptional<z.ZodNumber>;
520
523
  values: z.ZodOptional<z.ZodArray<z.ZodString>>;
524
+ schema: z.ZodOptional<z.ZodType<JsonParamSchema, unknown, z.core.$ZodTypeInternals<JsonParamSchema, unknown>>>;
521
525
  label: z.ZodOptional<z.ZodString>;
522
526
  group: z.ZodOptional<z.ZodString>;
523
527
  }, z.core.$strip>;
@@ -532,6 +536,7 @@ export declare const ParametersFileSchema: z.ZodObject<{
532
536
  boolean: "boolean";
533
537
  int: "int";
534
538
  enum: "enum";
539
+ json: "json";
535
540
  }>>;
536
541
  default: z.ZodOptional<z.ZodString>;
537
542
  secret: z.ZodOptional<z.ZodBoolean>;
@@ -543,6 +548,7 @@ export declare const ParametersFileSchema: z.ZodObject<{
543
548
  min: z.ZodOptional<z.ZodNumber>;
544
549
  max: z.ZodOptional<z.ZodNumber>;
545
550
  values: z.ZodOptional<z.ZodArray<z.ZodString>>;
551
+ schema: z.ZodOptional<z.ZodType<JsonParamSchema, unknown, z.core.$ZodTypeInternals<JsonParamSchema, unknown>>>;
546
552
  label: z.ZodOptional<z.ZodString>;
547
553
  group: z.ZodOptional<z.ZodString>;
548
554
  }, z.core.$strip>>>;
@@ -818,6 +824,7 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
818
824
  boolean: "boolean";
819
825
  int: "int";
820
826
  enum: "enum";
827
+ json: "json";
821
828
  }>>;
822
829
  default: z.ZodOptional<z.ZodString>;
823
830
  secret: z.ZodOptional<z.ZodBoolean>;
@@ -829,6 +836,7 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
829
836
  min: z.ZodOptional<z.ZodNumber>;
830
837
  max: z.ZodOptional<z.ZodNumber>;
831
838
  values: z.ZodOptional<z.ZodArray<z.ZodString>>;
839
+ schema: z.ZodOptional<z.ZodType<JsonParamSchema, unknown, z.core.$ZodTypeInternals<JsonParamSchema, unknown>>>;
832
840
  label: z.ZodOptional<z.ZodString>;
833
841
  group: z.ZodOptional<z.ZodString>;
834
842
  }, z.core.$strip>>>;
package/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { ProductTemplateInterfaceSchema } from "./interfaces.js";
3
3
  import { ProductTemplateLogsSchema } from "./logs.js";
4
+ import { validateParamValue } from "./params.js";
4
5
  import { LISTENER_ID_PATTERN, LISTENER_KINDS } from "./port-bindings.js";
5
6
  // ProductTemplate format v1. A product template is a tar file at the wire; the schemas
6
7
  // below describe its parts before packing and how the runner validates
@@ -602,11 +603,67 @@ export const STANDARD_ADVANCED_OVERRIDES = {
602
603
  containerUser: {},
603
604
  publicHost: {},
604
605
  };
606
+ // The shape of a `json` parameter's value: a small subset of JSON Schema
607
+ // (params.ts `JsonParamSchema`, which every form and the runner validate
608
+ // against). `secret` on a string is ours: the field is masked in reads,
609
+ // rendered as a password input, and may hold a `secretref:`.
610
+ const jsonNodeBase = {
611
+ title: z.string().min(1).optional().meta({ description: "A form's label for the field" }),
612
+ description: z.string().optional().meta({ description: "A form's help text for the field" }),
613
+ };
614
+ export const JsonParamSchemaSchema = z
615
+ .lazy(() => z.discriminatedUnion("type", [
616
+ z
617
+ .object({
618
+ ...jsonNodeBase,
619
+ type: z.literal("object"),
620
+ properties: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), JsonParamSchemaSchema),
621
+ required: z.array(z.string()).optional(),
622
+ })
623
+ .strict()
624
+ .superRefine((o, ctx) => {
625
+ for (const name of o.required ?? []) {
626
+ if (!(name in o.properties))
627
+ ctx.addIssue({
628
+ code: "custom",
629
+ path: ["required"],
630
+ message: `required names ${name}, which is not a property`,
631
+ });
632
+ }
633
+ }),
634
+ z
635
+ .object({
636
+ ...jsonNodeBase,
637
+ type: z.literal("array"),
638
+ items: JsonParamSchemaSchema,
639
+ minItems: z.number().int().min(0).optional(),
640
+ maxItems: z.number().int().min(0).optional(),
641
+ })
642
+ .strict(),
643
+ z
644
+ .object({
645
+ ...jsonNodeBase,
646
+ type: z.literal("string"),
647
+ enum: z.array(z.string()).min(1).optional(),
648
+ secret: z.boolean().optional(),
649
+ })
650
+ .strict(),
651
+ z
652
+ .object({
653
+ ...jsonNodeBase,
654
+ type: z.enum(["number", "integer"]),
655
+ minimum: z.number().optional(),
656
+ maximum: z.number().optional(),
657
+ })
658
+ .strict(),
659
+ z.object({ ...jsonNodeBase, type: z.literal("boolean") }).strict(),
660
+ ]))
661
+ .meta({ id: "JsonParamSchema", outputId: "JsonParamSchema" });
605
662
  export const ProductTemplateParameterSchema = z
606
663
  .object({
607
664
  name: z.string().regex(/^[A-Z][A-Z0-9_]*$/, "env var name; uppercase, digits, underscores"),
608
665
  purpose: z.string(),
609
- type: z.enum(["string", "int", "number", "boolean", "enum"]).default("string"),
666
+ type: z.enum(["string", "int", "number", "boolean", "enum", "json"]).default("string"),
610
667
  default: z.string().optional().meta({ description: "Stringified default (even for numeric/boolean/enum types)" }),
611
668
  secret: z.boolean().optional(),
612
669
  deliver: z.enum(["value", "reference"]).optional().meta({
@@ -620,6 +677,9 @@ export const ProductTemplateParameterSchema = z
620
677
  max: z.number().optional(),
621
678
  /** Allowed values for `enum` parameters (rendered as a dropdown). */
622
679
  values: z.array(z.string()).optional(),
680
+ schema: JsonParamSchemaSchema.optional().meta({
681
+ description: "The shape of a `json` parameter's value (a JSON Schema subset), which a form renders and every surface validates. The value is still one environment variable holding the JSON text.",
682
+ }),
623
683
  // Display metadata for a form built from the template. Declaration order is
624
684
  // display order, so there is no `order` field to disagree with it.
625
685
  label: z.string().min(1).optional().meta({
@@ -649,6 +709,24 @@ export const ProductTemplateParameterSchema = z
649
709
  if ((p.min !== undefined || p.max !== undefined) && p.type !== "int" && p.type !== "number") {
650
710
  ctx.addIssue({ code: "custom", path: ["min"], message: "`min`/`max` are only valid for int/number parameters" });
651
711
  }
712
+ if (p.type === "json") {
713
+ if (!p.schema)
714
+ ctx.addIssue({ code: "custom", path: ["schema"], message: "json parameters require a `schema`" });
715
+ if (p.secret === true)
716
+ ctx.addIssue({
717
+ code: "custom",
718
+ path: ["secret"],
719
+ message: "a json parameter is not secret as a whole: mark its secret fields `secret` in its schema",
720
+ });
721
+ if (p.schema && p.default !== undefined && p.default !== "") {
722
+ const err = validateParamValue(p, p.default);
723
+ if (err)
724
+ ctx.addIssue({ code: "custom", path: ["default"], message: `default: ${err}` });
725
+ }
726
+ }
727
+ else if (p.schema !== undefined) {
728
+ ctx.addIssue({ code: "custom", path: ["schema"], message: "`schema` is only valid for json parameters" });
729
+ }
652
730
  })
653
731
  .meta({ id: "ProductTemplateParameter", outputId: "ProductTemplateParameter" });
654
732
  // Wire shape of the optional parameters.yaml file inside a product-template tar.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-product-template-schema",
3
- "version": "0.1.87",
3
+ "version": "0.1.89",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/params.d.ts CHANGED
@@ -9,7 +9,37 @@ export type ParamSpec = {
9
9
  min?: number;
10
10
  max?: number;
11
11
  values?: string[];
12
+ /** The value's shape, for a `json` parameter. */
13
+ schema?: JsonParamSchema;
12
14
  };
15
+ /** The shape of a `json` parameter's value: a small subset of JSON Schema.
16
+ * `secret` (on a string) is ours: the field is masked in reads, rendered as
17
+ * a password input, and may hold a `secretref:`. Every node may carry a
18
+ * `title` (a form's label) and a `description` (its help text). */
19
+ export type JsonParamSchema = (JsonParamNodeBase & {
20
+ type: "object";
21
+ properties: Record<string, JsonParamSchema>;
22
+ required?: string[];
23
+ }) | (JsonParamNodeBase & {
24
+ type: "array";
25
+ items: JsonParamSchema;
26
+ minItems?: number;
27
+ maxItems?: number;
28
+ }) | (JsonParamNodeBase & {
29
+ type: "string";
30
+ enum?: string[];
31
+ secret?: boolean;
32
+ }) | (JsonParamNodeBase & {
33
+ type: "number" | "integer";
34
+ minimum?: number;
35
+ maximum?: number;
36
+ }) | (JsonParamNodeBase & {
37
+ type: "boolean";
38
+ });
39
+ interface JsonParamNodeBase {
40
+ title?: string;
41
+ description?: string;
42
+ }
13
43
  /** A required parameter only blocks launch when it has no `default` to fall
14
44
  * back on — supplying a default is itself a way of satisfying it. */
15
45
  export declare function isParamRequired(p: Pick<ProductTemplateParameter, "required" | "default">): boolean;
@@ -18,3 +48,26 @@ export declare function isParamRequired(p: Pick<ProductTemplateParameter, "requi
18
48
  * empty value for a non-required parameter (the default / runner fills it).
19
49
  * Boolean/number/enum values arrive as strings from form inputs. */
20
50
  export declare function validateParamValue(p: ParamSpec, raw: string): string | undefined;
51
+ /** A `json` parameter's text as a value, or why it is not JSON. */
52
+ export declare function parseJsonParam(raw: string): {
53
+ ok: true;
54
+ value: unknown;
55
+ } | {
56
+ ok: false;
57
+ error: string;
58
+ };
59
+ /** Check a value against a `json` parameter's schema. Answers the first
60
+ * problem, naming where it is (`servers[1].url is required`), or undefined.
61
+ * A `secret` string field may hold a `secretref:`; any string does. */
62
+ export declare function validateJsonParamValue(schema: JsonParamSchema, value: unknown, path?: string): string | undefined;
63
+ /** Rewrite every string the schema marks `secret` (`fn` answers the new
64
+ * string), leaving the rest of the value as it is. A value that does not
65
+ * fit the schema is walked as far as it does. */
66
+ export declare function mapSecretFields(schema: JsonParamSchema, value: unknown, fn: (v: string, path: string) => string, path?: string): unknown;
67
+ /** Whether the schema marks any field `secret`. */
68
+ export declare function hasSecretFields(schema: JsonParamSchema): boolean;
69
+ /** Every string anywhere in a JSON value, rewritten by `fn` (the runner uses
70
+ * it to resolve the `secretref:`s inside a `json` parameter, which are
71
+ * resolved wherever they sit, as a whole value that is one is). */
72
+ export declare function mapJsonStrings(value: unknown, fn: (v: string) => string): unknown;
73
+ export {};
package/params.js CHANGED
@@ -29,10 +29,143 @@ export function validateParamValue(p, raw) {
29
29
  return /^(true|false)$/i.test(v) ? undefined : "must be true or false";
30
30
  case "enum":
31
31
  return p.values && !p.values.includes(v) ? `must be one of: ${p.values.join(", ")}` : undefined;
32
+ case "json": {
33
+ const parsed = parseJsonParam(v);
34
+ if (!parsed.ok)
35
+ return parsed.error;
36
+ return p.schema ? validateJsonParamValue(p.schema, parsed.value) : undefined;
37
+ }
32
38
  default:
33
39
  return undefined; // string — anything goes
34
40
  }
35
41
  }
42
+ /** A `json` parameter's text as a value, or why it is not JSON. */
43
+ export function parseJsonParam(raw) {
44
+ try {
45
+ return { ok: true, value: JSON.parse(raw) };
46
+ }
47
+ catch (e) {
48
+ return { ok: false, error: `must be JSON: ${e instanceof Error ? e.message : String(e)}` };
49
+ }
50
+ }
51
+ /** Where in a value a problem is: `servers[1].url`; the root is `value`. */
52
+ function at(path) {
53
+ return path === "" ? "value" : path;
54
+ }
55
+ /** Check a value against a `json` parameter's schema. Answers the first
56
+ * problem, naming where it is (`servers[1].url is required`), or undefined.
57
+ * A `secret` string field may hold a `secretref:`; any string does. */
58
+ export function validateJsonParamValue(schema, value, path = "") {
59
+ switch (schema.type) {
60
+ case "object": {
61
+ if (typeof value !== "object" || value === null || Array.isArray(value))
62
+ return `${at(path)} must be an object`;
63
+ const obj = value;
64
+ for (const name of schema.required ?? []) {
65
+ const v = obj[name];
66
+ if (v === undefined || v === null || v === "")
67
+ return `${join(path, name)} is required`;
68
+ }
69
+ for (const [name, v] of Object.entries(obj)) {
70
+ const prop = schema.properties[name];
71
+ if (!prop)
72
+ return `${join(path, name)} is not a field this parameter takes`;
73
+ if (v === undefined || v === null)
74
+ continue;
75
+ const err = validateJsonParamValue(prop, v, join(path, name));
76
+ if (err)
77
+ return err;
78
+ }
79
+ return undefined;
80
+ }
81
+ case "array": {
82
+ if (!Array.isArray(value))
83
+ return `${at(path)} must be a list`;
84
+ if (schema.minItems !== undefined && value.length < schema.minItems)
85
+ return `${at(path)} needs at least ${schema.minItems} item${schema.minItems === 1 ? "" : "s"}`;
86
+ if (schema.maxItems !== undefined && value.length > schema.maxItems)
87
+ return `${at(path)} takes at most ${schema.maxItems} item${schema.maxItems === 1 ? "" : "s"}`;
88
+ for (const [i, item] of value.entries()) {
89
+ const err = validateJsonParamValue(schema.items, item, `${path}[${i}]`);
90
+ if (err)
91
+ return err;
92
+ }
93
+ return undefined;
94
+ }
95
+ case "string":
96
+ if (typeof value !== "string")
97
+ return `${at(path)} must be text`;
98
+ if (schema.enum && !schema.enum.includes(value))
99
+ return `${at(path)} must be one of: ${schema.enum.join(", ")}`;
100
+ return undefined;
101
+ case "integer":
102
+ case "number": {
103
+ if (typeof value !== "number" || !Number.isFinite(value))
104
+ return `${at(path)} must be a number`;
105
+ if (schema.type === "integer" && !Number.isInteger(value))
106
+ return `${at(path)} must be a whole number`;
107
+ if (schema.minimum !== undefined && value < schema.minimum)
108
+ return `${at(path)} must be >= ${schema.minimum}`;
109
+ if (schema.maximum !== undefined && value > schema.maximum)
110
+ return `${at(path)} must be <= ${schema.maximum}`;
111
+ return undefined;
112
+ }
113
+ case "boolean":
114
+ return typeof value === "boolean" ? undefined : `${at(path)} must be true or false`;
115
+ }
116
+ }
117
+ function join(path, name) {
118
+ return path === "" ? name : `${path}.${name}`;
119
+ }
120
+ /** Rewrite every string the schema marks `secret` (`fn` answers the new
121
+ * string), leaving the rest of the value as it is. A value that does not
122
+ * fit the schema is walked as far as it does. */
123
+ export function mapSecretFields(schema, value, fn, path = "") {
124
+ switch (schema.type) {
125
+ case "object": {
126
+ if (typeof value !== "object" || value === null || Array.isArray(value))
127
+ return value;
128
+ const out = {};
129
+ for (const [name, v] of Object.entries(value)) {
130
+ const prop = schema.properties[name];
131
+ out[name] = prop ? mapSecretFields(prop, v, fn, join(path, name)) : v;
132
+ }
133
+ return out;
134
+ }
135
+ case "array":
136
+ return Array.isArray(value) ? value.map((v, i) => mapSecretFields(schema.items, v, fn, `${path}[${i}]`)) : value;
137
+ case "string":
138
+ return schema.secret === true && typeof value === "string" ? fn(value, path) : value;
139
+ default:
140
+ return value;
141
+ }
142
+ }
143
+ /** Whether the schema marks any field `secret`. */
144
+ export function hasSecretFields(schema) {
145
+ switch (schema.type) {
146
+ case "object":
147
+ return Object.values(schema.properties).some(hasSecretFields);
148
+ case "array":
149
+ return hasSecretFields(schema.items);
150
+ case "string":
151
+ return schema.secret === true;
152
+ default:
153
+ return false;
154
+ }
155
+ }
156
+ /** Every string anywhere in a JSON value, rewritten by `fn` (the runner uses
157
+ * it to resolve the `secretref:`s inside a `json` parameter, which are
158
+ * resolved wherever they sit, as a whole value that is one is). */
159
+ export function mapJsonStrings(value, fn) {
160
+ if (typeof value === "string")
161
+ return fn(value);
162
+ if (Array.isArray(value))
163
+ return value.map((v) => mapJsonStrings(v, fn));
164
+ if (typeof value === "object" && value !== null) {
165
+ return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, mapJsonStrings(v, fn)]));
166
+ }
167
+ return value;
168
+ }
36
169
  function rangeError(p, n) {
37
170
  if (p.min !== undefined && n < p.min)
38
171
  return `must be >= ${p.min}`;
@@ -1,4 +1,5 @@
1
1
  import { type Result } from "@norskvideo/ctl-foundation/browser";
2
+ import { type JsonParamSchema } from "./params.js";
2
3
  export declare const SECRET_REFERENCE_PREFIX = "secretref:";
3
4
  /** The NodeInventory capability a worker advertises when it resolves secret
4
5
  * references, so placement can keep a job whose parameters hold one off an
@@ -21,11 +22,27 @@ export interface SecretReference {
21
22
  export declare function isSecretReference(value: string): boolean;
22
23
  export declare function parseSecretReference(value: string): Result<SecretReference, string>;
23
24
  export declare function secretReference(provider: string, key: string): string;
25
+ /** The slice of a parameter declaration masking reads. */
26
+ export interface DeclaredSecrecy {
27
+ name: string;
28
+ secret?: boolean;
29
+ type?: string;
30
+ schema?: JsonParamSchema;
31
+ }
24
32
  /** Launch parameters as they may be shown: a parameter the template declares
25
33
  * `secret` has its literal value masked. A reference is shown as it is — it
26
34
  * is the point of a reference that it reveals nothing — and an empty value
27
- * stays visibly empty. */
28
- export declare function redactSecretParams(params: Record<string, string>, declared: readonly {
29
- name: string;
30
- secret?: boolean;
31
- }[]): Record<string, string>;
35
+ * stays visibly empty. In a `json` parameter, each field its schema marks
36
+ * `secret` is masked by the same rule; one that is not JSON, and has secret
37
+ * fields, is masked whole. */
38
+ export declare function redactSecretParams(params: Record<string, string>, declared: readonly DeclaredSecrecy[]): Record<string, string>;
39
+ /** A `json` parameter's text with its secret fields masked. */
40
+ export declare function redactJsonSecrets(schema: JsonParamSchema, text: string): string;
41
+ /** A `json` parameter's text as an editor sent it back, with each secret field
42
+ * that holds the placeholder given the value it stands for in `stored` (the
43
+ * same field of the value held now). Answers the text, or the paths whose
44
+ * placeholder has nothing behind it. */
45
+ export declare function restoreJsonSecrets(schema: JsonParamSchema, incoming: string, stored: string | undefined): Result<string, string[]>;
46
+ /** Every `secretref:` a parameter's value holds: itself, when it is one, or
47
+ * each one inside it, when it is JSON (a `json` parameter's fields). */
48
+ export declare function secretReferencesIn(value: string): string[];
@@ -11,6 +11,7 @@
11
11
  // The browser entry: the API contract reaches this module (the resolve
12
12
  // endpoint's wire schemas), and the contract is loaded by the web UIs.
13
13
  import { err, ok } from "@norskvideo/ctl-foundation/browser";
14
+ import { hasSecretFields, mapJsonStrings, mapSecretFields } from "./params.js";
14
15
  export const SECRET_REFERENCE_PREFIX = "secretref:";
15
16
  /** The NodeInventory capability a worker advertises when it resolves secret
16
17
  * references, so placement can keep a job whose parameters hold one off an
@@ -49,14 +50,102 @@ export function parseSecretReference(value) {
49
50
  export function secretReference(provider, key) {
50
51
  return `${SECRET_REFERENCE_PREFIX}${provider}:${key}`;
51
52
  }
53
+ const maskOne = (v) => (v !== "" && !isSecretReference(v) ? SECRET_PLACEHOLDER : v);
52
54
  /** Launch parameters as they may be shown: a parameter the template declares
53
55
  * `secret` has its literal value masked. A reference is shown as it is — it
54
56
  * is the point of a reference that it reveals nothing — and an empty value
55
- * stays visibly empty. */
57
+ * stays visibly empty. In a `json` parameter, each field its schema marks
58
+ * `secret` is masked by the same rule; one that is not JSON, and has secret
59
+ * fields, is masked whole. */
56
60
  export function redactSecretParams(params, declared) {
57
- const secret = new Set(declared.filter((p) => p.secret === true).map((p) => p.name));
58
- return Object.fromEntries(Object.entries(params).map(([k, v]) => [
59
- k,
60
- secret.has(k) && v !== "" && !isSecretReference(v) ? SECRET_PLACEHOLDER : v,
61
- ]));
61
+ const byName = new Map(declared.map((p) => [p.name, p]));
62
+ return Object.fromEntries(Object.entries(params).map(([k, v]) => {
63
+ const p = byName.get(k);
64
+ if (p?.secret === true)
65
+ return [k, maskOne(v)];
66
+ if (p?.type === "json" && p.schema && hasSecretFields(p.schema))
67
+ return [k, redactJsonSecrets(p.schema, v)];
68
+ return [k, v];
69
+ }));
70
+ }
71
+ /** A `json` parameter's text with its secret fields masked. */
72
+ export function redactJsonSecrets(schema, text) {
73
+ if (text.trim() === "")
74
+ return text;
75
+ let value;
76
+ try {
77
+ value = JSON.parse(text);
78
+ }
79
+ catch {
80
+ return SECRET_PLACEHOLDER;
81
+ }
82
+ return JSON.stringify(mapSecretFields(schema, value, maskOne));
83
+ }
84
+ /** A `json` parameter's text as an editor sent it back, with each secret field
85
+ * that holds the placeholder given the value it stands for in `stored` (the
86
+ * same field of the value held now). Answers the text, or the paths whose
87
+ * placeholder has nothing behind it. */
88
+ export function restoreJsonSecrets(schema, incoming, stored) {
89
+ if (!incoming.includes(SECRET_PLACEHOLDER))
90
+ return ok(incoming);
91
+ let value;
92
+ try {
93
+ value = JSON.parse(incoming);
94
+ }
95
+ catch {
96
+ // Not JSON: a whole-value placeholder (redactJsonSecrets of a value that
97
+ // was not JSON) keeps what is stored, verbatim.
98
+ return incoming.trim() === SECRET_PLACEHOLDER && stored !== undefined ? ok(stored) : err(["value"]);
99
+ }
100
+ let old;
101
+ try {
102
+ old = stored === undefined ? undefined : JSON.parse(stored);
103
+ }
104
+ catch {
105
+ old = undefined;
106
+ }
107
+ const missing = [];
108
+ const restored = mapSecretFields(schema, value, (v, path) => {
109
+ if (v !== SECRET_PLACEHOLDER)
110
+ return v;
111
+ const was = valueAt(old, path);
112
+ if (typeof was === "string" && was !== SECRET_PLACEHOLDER)
113
+ return was;
114
+ missing.push(path === "" ? "value" : path);
115
+ return v;
116
+ });
117
+ return missing.length > 0 ? err(missing) : ok(JSON.stringify(restored));
118
+ }
119
+ /** The value at a path like `servers[1].credential`. */
120
+ function valueAt(value, path) {
121
+ let cur = value;
122
+ for (const part of path.match(/[^.[\]]+/g) ?? []) {
123
+ if (cur === null || typeof cur !== "object")
124
+ return undefined;
125
+ cur = Array.isArray(cur) ? cur[Number(part)] : cur[part];
126
+ }
127
+ return cur;
128
+ }
129
+ /** Every `secretref:` a parameter's value holds: itself, when it is one, or
130
+ * each one inside it, when it is JSON (a `json` parameter's fields). */
131
+ export function secretReferencesIn(value) {
132
+ if (isSecretReference(value))
133
+ return [value];
134
+ const t = value.trimStart();
135
+ if (!t.startsWith("{") && !t.startsWith("["))
136
+ return [];
137
+ let parsed;
138
+ try {
139
+ parsed = JSON.parse(value);
140
+ }
141
+ catch {
142
+ return [];
143
+ }
144
+ const found = [];
145
+ mapJsonStrings(parsed, (s) => {
146
+ if (isSecretReference(s))
147
+ found.push(s);
148
+ return s;
149
+ });
150
+ return found;
62
151
  }