primitive-admin 1.3.0-alpha.1 → 1.3.0-alpha.3

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.
Files changed (116) hide show
  1. package/README.md +46 -22
  2. package/dist/bin/primitive.js +11 -4
  3. package/dist/bin/primitive.js.map +1 -1
  4. package/dist/src/commands/admins.js +91 -0
  5. package/dist/src/commands/admins.js.map +1 -1
  6. package/dist/src/commands/apps.d.ts +3 -6
  7. package/dist/src/commands/apps.js +7 -22
  8. package/dist/src/commands/apps.js.map +1 -1
  9. package/dist/src/commands/auth-passkeys.d.ts +7 -0
  10. package/dist/src/commands/auth-passkeys.js +99 -0
  11. package/dist/src/commands/auth-passkeys.js.map +1 -0
  12. package/dist/src/commands/auth-sessions.js +7 -28
  13. package/dist/src/commands/auth-sessions.js.map +1 -1
  14. package/dist/src/commands/auth.js +1 -1
  15. package/dist/src/commands/auth.js.map +1 -1
  16. package/dist/src/commands/blob-buckets.d.ts +8 -0
  17. package/dist/src/commands/blob-buckets.js +23 -8
  18. package/dist/src/commands/blob-buckets.js.map +1 -1
  19. package/dist/src/commands/db3.js +6 -0
  20. package/dist/src/commands/db3.js.map +1 -1
  21. package/dist/src/commands/documents.js +3 -0
  22. package/dist/src/commands/documents.js.map +1 -1
  23. package/dist/src/commands/functions.js +13 -4
  24. package/dist/src/commands/functions.js.map +1 -1
  25. package/dist/src/commands/init.js +11 -0
  26. package/dist/src/commands/init.js.map +1 -1
  27. package/dist/src/commands/rule-sets.d.ts +1 -1
  28. package/dist/src/commands/rule-sets.js +0 -1
  29. package/dist/src/commands/rule-sets.js.map +1 -1
  30. package/dist/src/commands/sync-app-settings.d.ts +88 -1
  31. package/dist/src/commands/sync-app-settings.js +224 -8
  32. package/dist/src/commands/sync-app-settings.js.map +1 -1
  33. package/dist/src/commands/sync.d.ts +27 -26
  34. package/dist/src/commands/sync.js +249 -116
  35. package/dist/src/commands/sync.js.map +1 -1
  36. package/dist/src/commands/usage.d.ts +12 -2
  37. package/dist/src/commands/usage.js +115 -5
  38. package/dist/src/commands/usage.js.map +1 -1
  39. package/dist/src/lib/admin-login-tables.d.ts +31 -0
  40. package/dist/src/lib/admin-login-tables.js +75 -0
  41. package/dist/src/lib/admin-login-tables.js.map +1 -0
  42. package/dist/src/lib/api-client.d.ts +156 -5
  43. package/dist/src/lib/api-client.js +90 -9
  44. package/dist/src/lib/api-client.js.map +1 -1
  45. package/dist/src/lib/app-settings-descriptor.d.ts +29 -2
  46. package/dist/src/lib/app-settings-descriptor.js +68 -3
  47. package/dist/src/lib/app-settings-descriptor.js.map +1 -1
  48. package/dist/src/lib/cli-manifest.d.ts +9 -0
  49. package/dist/src/lib/cli-manifest.js +19 -3
  50. package/dist/src/lib/cli-manifest.js.map +1 -1
  51. package/dist/src/lib/config-object-descriptor.js +3 -5
  52. package/dist/src/lib/config-object-descriptor.js.map +1 -1
  53. package/dist/src/lib/db3-export.js +1 -0
  54. package/dist/src/lib/db3-export.js.map +1 -1
  55. package/dist/src/lib/document-ingest.d.ts +7 -1
  56. package/dist/src/lib/document-ingest.js +27 -2
  57. package/dist/src/lib/document-ingest.js.map +1 -1
  58. package/dist/src/lib/function-authorize-check.js +5 -0
  59. package/dist/src/lib/function-authorize-check.js.map +1 -1
  60. package/dist/src/lib/function-authorize-view.js +5 -4
  61. package/dist/src/lib/function-authorize-view.js.map +1 -1
  62. package/dist/src/lib/function-bundle.d.ts +6 -0
  63. package/dist/src/lib/function-bundle.js +14 -0
  64. package/dist/src/lib/function-bundle.js.map +1 -1
  65. package/dist/src/lib/function-collect.d.ts +6 -0
  66. package/dist/src/lib/function-collect.js +10 -2
  67. package/dist/src/lib/function-collect.js.map +1 -1
  68. package/dist/src/lib/function-db-types.d.ts +8 -0
  69. package/dist/src/lib/function-db-types.js +15 -0
  70. package/dist/src/lib/function-db-types.js.map +1 -1
  71. package/dist/src/lib/function-log-lines.js +6 -1
  72. package/dist/src/lib/function-log-lines.js.map +1 -1
  73. package/dist/src/lib/function-log-row.d.ts +8 -0
  74. package/dist/src/lib/function-log-row.js +59 -0
  75. package/dist/src/lib/function-log-row.js.map +1 -1
  76. package/dist/src/lib/function-sync.d.ts +62 -0
  77. package/dist/src/lib/function-sync.js +68 -1
  78. package/dist/src/lib/function-sync.js.map +1 -1
  79. package/dist/src/lib/generated-command-status.js +6 -0
  80. package/dist/src/lib/generated-command-status.js.map +1 -1
  81. package/dist/src/lib/generated-config-surfaces.d.ts +104 -4
  82. package/dist/src/lib/generated-config-surfaces.js +378 -49
  83. package/dist/src/lib/generated-config-surfaces.js.map +1 -1
  84. package/dist/src/lib/generated-sdk-types.d.ts +1 -1
  85. package/dist/src/lib/generated-sdk-types.js +1 -1
  86. package/dist/src/lib/generated-sdk-types.js.map +1 -1
  87. package/dist/src/lib/log-inspection.d.ts +37 -2
  88. package/dist/src/lib/log-inspection.js +15 -3
  89. package/dist/src/lib/log-inspection.js.map +1 -1
  90. package/dist/src/lib/outside-project.d.ts +49 -0
  91. package/dist/src/lib/outside-project.js +133 -0
  92. package/dist/src/lib/outside-project.js.map +1 -0
  93. package/dist/src/lib/primitive-declaration.d.ts +8 -1
  94. package/dist/src/lib/primitive-declaration.js +40 -8
  95. package/dist/src/lib/primitive-declaration.js.map +1 -1
  96. package/dist/src/lib/schema-codegen/compiledSpace.d.ts +16 -0
  97. package/dist/src/lib/schema-codegen/compiledSpace.js +23 -11
  98. package/dist/src/lib/schema-codegen/compiledSpace.js.map +1 -1
  99. package/dist/src/lib/schema-codegen/generated-field-table.js +38 -3
  100. package/dist/src/lib/schema-codegen/generated-field-table.js.map +1 -1
  101. package/dist/src/lib/schema-codegen/generated-schema-refs.js +172 -19
  102. package/dist/src/lib/schema-codegen/generated-schema-refs.js.map +1 -1
  103. package/dist/src/lib/schema-codegen/namedRefs.js +8 -2
  104. package/dist/src/lib/schema-codegen/namedRefs.js.map +1 -1
  105. package/dist/src/lib/schema-codegen/schemaDocs.js +10 -4
  106. package/dist/src/lib/schema-codegen/schemaDocs.js.map +1 -1
  107. package/dist/src/lib/schema-codegen/schemaIR.d.ts +12 -2
  108. package/dist/src/lib/schema-codegen/schemaIR.js +26 -2
  109. package/dist/src/lib/schema-codegen/schemaIR.js.map +1 -1
  110. package/dist/src/lib/schema-codegen/schemaToTs.d.ts +2 -1
  111. package/dist/src/lib/schema-codegen/schemaToTs.js +8 -5
  112. package/dist/src/lib/schema-codegen/schemaToTs.js.map +1 -1
  113. package/dist/src/lib/usage-meters.js +1 -0
  114. package/dist/src/lib/usage-meters.js.map +1 -1
  115. package/dist/src/types/index.d.ts +9 -0
  116. package/package.json +2 -2
@@ -2312,6 +2312,43 @@ export function unknownRequestKeysMessage(keys) {
2312
2312
  `${keys.join(", ")}. This endpoint rejects keys it does not accept rather ` +
2313
2313
  "than ignoring them.");
2314
2314
  }
2315
+ // ── src/config-surface/retired-keys.ts ───────────────────────────────────
2316
+ /**
2317
+ * Keys deliberately RETIRED from a configuration object's write surface.
2318
+ *
2319
+ * A retired key is not an unknown key. The generic hint for an unrecognized
2320
+ * TOML key — "check the spelling, or upgrade the CLI" — is exactly backwards
2321
+ * for one this CLI removed on purpose, and the generic 400 for an unaccepted
2322
+ * request key says only that the key is not allowed, not where the value moved
2323
+ * to. Both surfaces need the same sentence, and neither should invent it.
2324
+ *
2325
+ * So the guidance lives here, next to the definitions, with one entry per
2326
+ * retired key: the TOML wording for `config push` (which can tell the author to
2327
+ * delete a line) and the request wording for the API handlers (which cannot).
2328
+ *
2329
+ * Keyed by the table's TOML path prefix (`integration`, `prompt`, …), because
2330
+ * that is the identifier both consumers already have in hand.
2331
+ *
2332
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity).
2333
+ */
2334
+ /** The four bucket access presets, the only values `preset` takes. */
2335
+ export const BLOB_BUCKET_ACCESS_PRESETS = [
2336
+ "public",
2337
+ "authenticated",
2338
+ "admin-only",
2339
+ "personal-uploads",
2340
+ ];
2341
+ /**
2342
+ * The one refusal for a bucket rule set, whichever door it comes through: a
2343
+ * `ruleSetId` or `ruleSetName` body key or TOML line, preset `custom`, or a
2344
+ * rule set of resource type `blob_bucket`. It names the four presets and the
2345
+ * function pattern that replaces a rule set.
2346
+ */
2347
+ export const BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE = "Blob buckets no longer take a rule set: a bucket's access is one of the " +
2348
+ "presets `public`, `authenticated`, `admin-only` or `personal-uploads`. " +
2349
+ "For access a preset cannot express, make the bucket `admin-only` and " +
2350
+ "decide in a server function's `authorize`, which returns read URLs " +
2351
+ "made by `ctx.api.blobBuckets.getSignedUrls`.";
2315
2352
  // #3997 — the three type configs author their rule-set reference by name
2316
2353
  // (#2644): an id names a row in one app and resolves to nothing in another, so
2317
2354
  // a copied file failed instead of resolving. One sentence serves all three
@@ -2432,25 +2469,29 @@ export const RETIRED_CONFIG_KEYS = {
2432
2469
  "`admin-only` (app admins; `personal-uploads` is the per-uploader " +
2433
2470
  "preset).",
2434
2471
  },
2435
- // #4283 — #4116 made the bucket author its rule set by name and kept the
2436
- // id spelling as a deprecated key. Its own sentence rather than the type
2437
- // configs' shared one, which says a pulled file already spells the name:
2438
- // a bucket file pulled before #4116 does not. The `request` half is never
2439
- // surfaced, for the reason given at `RULE_SET_ID_RETIRED`.
2472
+ // #6243 — rule sets left buckets: a bucket's access is one of the four
2473
+ // presets, and anything a preset cannot express goes through a function.
2474
+ // Both spellings of the reference are refused on the wire and in TOML
2475
+ // with the one sentence the rule-set routes also answer, so the author
2476
+ // meets the presets and the function pattern whichever door they used.
2440
2477
  ruleSetId: {
2441
- toml: "`ruleSetId` is no longer authored in TOML (#4283). A rule-set id " +
2442
- "names a row in one app and resolves to nothing in another, so the " +
2443
- "reference is authored by name: replace this line with " +
2444
- '`ruleSetName = "<name>"`, where the name is the `name` the rule ' +
2445
- "set's own `rule-sets/<key>.toml` declares, and push again, or " +
2446
- "`config pull` rewrites the file.",
2447
- request: "`ruleSetId` is the live request key on this surface; only its TOML " +
2448
- "spelling is retired (#4283). Send the rule set's id.",
2478
+ toml: "`ruleSetId` is no longer a bucket key (#6243). " +
2479
+ BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE +
2480
+ " Replace the line with `preset = \"admin-only\"` (or another " +
2481
+ "preset) and push again.",
2482
+ request: BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE,
2483
+ },
2484
+ ruleSetName: {
2485
+ toml: "`ruleSetName` is no longer a bucket key (#6243). " +
2486
+ BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE +
2487
+ " Replace the line with `preset = \"admin-only\"` (or another " +
2488
+ "preset) and push again.",
2489
+ request: BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE,
2449
2490
  },
2450
2491
  },
2451
2492
  // #3997 — keyed by each table's TOML prefix. Only `database-type-config`
2452
2493
  // uses `[type]`, so that entry cannot reach another surface. The blob
2453
- // bucket's `[bucket] ruleSetId` has its own entry under `bucket` (#4283).
2494
+ // bucket's `[bucket] ruleSetId` has its own entry under `bucket` (#6243).
2454
2495
  //
2455
2496
  // #3189 — server-functions phase 6 retires database operations, and with
2456
2497
  // them the two type-level CEL keys that existed for operations: the access
@@ -4049,6 +4090,41 @@ export function publicOptionsRefusal(input) {
4049
4090
  }
4050
4091
  return null;
4051
4092
  }
4093
+ // ── An `authorize` function with no `input` list (#6170) ──────────────────
4094
+ /**
4095
+ * The two fixes for an `authorize` function that declares no `input` list,
4096
+ * in one sentence: list the keys its handler reads, or say it reads none.
4097
+ */
4098
+ const INPUT_LIST_FIXES = 'Add input: ["<key>", ...] to the defineFunction call listing the input keys the handler reads, ' +
4099
+ "or input: [] when the handler reads no input";
4100
+ /**
4101
+ * Why a push refuses an `authorize` function whose export declares no `input`
4102
+ * list and whose TOML declares no trigger — #6170: every door that could
4103
+ * call it is a caller door, where a version with no list is refused. The CLI
4104
+ * refuses before any request and the server at push, with this sentence.
4105
+ */
4106
+ export function inputListRequiredMessage(functionKey) {
4107
+ return (`Function '${functionKey}' runs authorize but declares no input list, so every call to it would be refused. ` +
4108
+ `${INPUT_LIST_FIXES}, then push again.`);
4109
+ }
4110
+ /**
4111
+ * The warning a push answers for an `authorize` function with no `input`
4112
+ * list that declares a trigger — #6170: its trigger doors still hand it the
4113
+ * whole body, and its caller-door calls are refused with
4114
+ * `FUNCTION_INPUT_LIST_MISSING`.
4115
+ */
4116
+ export function inputListMissingWarning(functionKey) {
4117
+ return (`Function '${functionKey}' runs authorize but declares no input list: its triggers run, but calls over http, ` +
4118
+ `ctx.functions, the system routes and agent tools are refused with FUNCTION_INPUT_LIST_MISSING. ${INPUT_LIST_FIXES}.`);
4119
+ }
4120
+ /**
4121
+ * What a caller-door call to an `authorize` version that recorded no `input`
4122
+ * list is refused with — #6170. Answered only after `authorize` allowed.
4123
+ */
4124
+ export function inputListMissingCallMessage(functionKey) {
4125
+ return (`Function '${functionKey}' runs authorize but its deployed version declares no input list, ` +
4126
+ `so the platform does not run its handler. ${INPUT_LIST_FIXES}, then push the function again.`);
4127
+ }
4052
4128
  // ── src/config-surface/function-retired-keys.ts ──────────────────────────
4053
4129
  /**
4054
4130
  * The runtime keys a `functions/<key>.toml` no longer decides anything with —
@@ -9341,13 +9417,14 @@ export const INTEGRATION_SURFACE = {
9341
9417
  * `blob-buckets/<key>.toml` carries a single `[bucket]` table.
9342
9418
  *
9343
9419
  * `ttlTier` is `writableOn: ["create"]`: the update handler does not read it, so
9344
- * the retention tier is fixed at creation. `preset` and the rule set are the two
9345
- * halves of the access model (#1020), and the only access keys: at most one may
9346
- * change per request, which is the controller's rule and stays there. The rule
9347
- * set is authored by name (`ruleSetName`) and sent as `ruleSetId`, as the type
9348
- * configs do (#4116). The id spelling in TOML (#4283) and the pre-#1020
9349
- * `accessPolicy` spelling (#3996) are retired keys (`retired-keys.ts`).
9350
- */
9420
+ * the retention tier is fixed at creation. `preset` is the bucket's access
9421
+ * (#1020), one of `BLOB_BUCKET_ACCESS_PRESETS`. Rule sets left buckets in
9422
+ * #6243: `ruleSetName` and `ruleSetId` are retired keys (`retired-keys.ts`), as
9423
+ * is the pre-#1020 `accessPolicy` spelling (#3996). Access a preset cannot
9424
+ * express goes through a server function that hands out signed URLs.
9425
+ */
9426
+ // Declared in `retired-keys.ts`, which the CLI's concatenated copy places
9427
+ // first; re-exported here beside the surface they describe.
9351
9428
  const BLOB_BUCKET_HANDLER = "src/app-api/controllers/blob-buckets-controller.ts";
9352
9429
  export const BLOB_BUCKET_SURFACE = {
9353
9430
  label: "blob-bucket",
@@ -9389,22 +9466,10 @@ export const BLOB_BUCKET_SURFACE = {
9389
9466
  type: "string",
9390
9467
  emit: "whenSet",
9391
9468
  writableOn: BOTH,
9392
- // #1020 — the honest access field. A rule-set-backed bucket reports
9393
- // "custom", which is not written back as a preset.
9469
+ // #1020 — the access field, one of the four presets (#6243). A
9470
+ // bucket stored with a rule set reads as `admin-only`.
9394
9471
  validation: handledBy("src/app-api/resource-types/blob-bucket.ts", "resolveBucketPreset", "apply"),
9395
9472
  },
9396
- {
9397
- field: "ruleSetId",
9398
- tomlKey: "ruleSetName",
9399
- type: "string",
9400
- emit: "whenSet",
9401
- writableOn: BOTH,
9402
- // Authored as a name, sent as an id (#4116), so a tree copied into
9403
- // another app binds that app's rule set. Existence-checked against
9404
- // AccessRuleSet; mutually exclusive with a preset change in the same
9405
- // request. The TOML spelling of the id is a retired key (#4283).
9406
- validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController", "apply"),
9407
- },
9408
9473
  ],
9409
9474
  notExposed: {
9410
9475
  bucketId: {
@@ -9433,6 +9498,14 @@ export const BLOB_BUCKET_SURFACE = {
9433
9498
  "can read a pre-#1020 row; no write path accepts it and no " +
9434
9499
  "serializer emits it.",
9435
9500
  },
9501
+ ruleSetId: {
9502
+ kind: "server-owned",
9503
+ note: "RETIRED from the write surface by #6243: a bucket's access is one " +
9504
+ "of the four presets. The attribute stays declared so a bucket " +
9505
+ "stored with a rule set reads as `admin-only` " +
9506
+ "(`resolveBucketPreset`); no write path accepts it, a preset " +
9507
+ "update clears it, and no serializer emits it.",
9508
+ },
9436
9509
  createdBy: {
9437
9510
  kind: "server-owned",
9438
9511
  note: "User who created the bucket; assigned server-side.",
@@ -9453,11 +9526,17 @@ export const BLOB_BUCKET_SURFACE = {
9453
9526
  "the identity from the file name and attaches `bucketKey` itself.",
9454
9527
  },
9455
9528
  },
9456
- responseOnlyKeys: {},
9529
+ responseOnlyKeys: {
9530
+ convertedFromRuleSet: {
9531
+ kind: "server-owned",
9532
+ note: "Read-only mark (#6243): true for a bucket stored with a rule set, " +
9533
+ "which is served as `admin-only` until an update names a preset.",
9534
+ },
9535
+ },
9457
9536
  },
9458
9537
  ],
9459
- // A bucket file is the `[bucket]` table and nothing else: its access model is
9460
- // a preset or a rule-set reference, both scalars inside that table.
9538
+ // A bucket file is the `[bucket]` table and nothing else: its access is a
9539
+ // preset, a scalar inside that table.
9461
9540
  tomlDocumentKeys: {},
9462
9541
  };
9463
9542
  // ── src/config-surface/email-template.ts ─────────────────────────────────
@@ -9952,6 +10031,11 @@ const RULE_SET_HANDLER = "src/app-api/controllers/rule-sets-controller.ts";
9952
10031
  * `lock` — locks are server-function-only, and the calling function's
9953
10032
  * `authorize` decides who may lock which key. A stored row can still be listed
9954
10033
  * and deleted; nothing evaluates it.
10034
+ *
10035
+ * `blob_bucket` (#6243) — a bucket's access is one of four presets. The type
10036
+ * stays registered (the presets evaluate through it), so the rule-set
10037
+ * listings leave it out; a stored row can still be listed, read and deleted,
10038
+ * and a bucket that pointed at one is served as `admin-only`.
9955
10039
  */
9956
10040
  export const RETIRED_RULE_SET_RESOURCE_TYPES = {
9957
10041
  lock: {
@@ -9962,6 +10046,13 @@ export const RETIRED_RULE_SET_RESOURCE_TYPES = {
9962
10046
  "`rule-sets/<name>.toml` and run `primitive config push --prune` to " +
9963
10047
  "remove this rule set.",
9964
10048
  },
10049
+ blob_bucket: {
10050
+ code: "BLOB_BUCKET_RULE_SET_RETIRED",
10051
+ message: "`blob_bucket` is no longer a rule-set resource type. " +
10052
+ BLOB_BUCKET_RULE_SET_RETIRED_MESSAGE +
10053
+ " Delete `rule-sets/<name>.toml` and run `primitive config push " +
10054
+ "--prune` to remove this rule set.",
10055
+ },
9965
10056
  };
9966
10057
  /** The retirement for `resourceType`, or `null` for a live type. */
9967
10058
  export function retiredRuleSetResourceType(resourceType) {
@@ -11013,6 +11104,20 @@ export const TEST_CASE_SURFACE = {
11013
11104
  * list (the registry's rule ids are keyed by a surface's `crossFieldRules`).
11014
11105
  * Every refusal is still built through one constructor, `clientVersionsRefusal`.
11015
11106
  *
11107
+ * A platform's entry may also carry `backendOverrides` (#6183, project
11108
+ * `client-backend-overrides`): a list of `{ from, appId, apiUrl? }` steps
11109
+ * saying that copies of the app from version `from` upward talk to another
11110
+ * app id, and optionally another server. The rules here check each step's
11111
+ * form, refuse a step naming the app's own id when the caller passes it, and
11112
+ * bound the stored size of a policy that carries any step. A step's `apiUrl`
11113
+ * must be written in canonical form (equal to `new URL(value).href`) with
11114
+ * plain characters (#6185), so the server is the only URL parser and every
11115
+ * client reads the same address. They check nothing else about the target.
11116
+ *
11117
+ * A platform's entry may also say `enforce` (#6039): a boolean, legal only
11118
+ * beside a `minRequired`, asking the server to refuse callers that report
11119
+ * that platform and a lower version.
11120
+ *
11016
11121
  * Maps are read with own-property iteration only, so a platform named
11017
11122
  * `constructor` is an entry like any other.
11018
11123
  *
@@ -11024,6 +11129,8 @@ export const CLIENT_VERSION_ENTRY_KEYS = [
11024
11129
  "minRecommended",
11025
11130
  "minRequired",
11026
11131
  "updateUrl",
11132
+ "enforce",
11133
+ "backendOverrides",
11027
11134
  ];
11028
11135
  /** The keys of an entry that hold a version. */
11029
11136
  const CLIENT_VERSION_VALUE_KEYS = ["latest", "minRecommended", "minRequired"];
@@ -11045,6 +11152,23 @@ export const CLIENT_UPDATE_URL_SCHEMES = [
11045
11152
  export const MAX_CLIENT_PLATFORMS = 20;
11046
11153
  /** The longest `updateUrl` accepted, in characters. */
11047
11154
  export const MAX_CLIENT_UPDATE_URL_LENGTH = 2048;
11155
+ /** The keys one backend override may carry, in their stored order. */
11156
+ export const BACKEND_OVERRIDE_KEYS = ["from", "appId", "apiUrl"];
11157
+ /** The most backend overrides one platform may declare. */
11158
+ export const MAX_BACKEND_OVERRIDES = 16;
11159
+ /** The longest override `appId` accepted, in characters. */
11160
+ export const MAX_BACKEND_OVERRIDE_APP_ID_LENGTH = 128;
11161
+ /** The hosts an override `apiUrl` may reach over plain `http:`. */
11162
+ export const BACKEND_OVERRIDE_LOOPBACK_HOSTS = [
11163
+ "localhost",
11164
+ "127.0.0.1",
11165
+ "[::1]",
11166
+ ];
11167
+ /**
11168
+ * The largest stored form, in UTF-8 bytes, of a policy that carries at least
11169
+ * one backend override. A policy with none is not measured.
11170
+ */
11171
+ export const MAX_CLIENT_VERSIONS_BYTES = 65536;
11048
11172
  /** The one place a refusal is built. */
11049
11173
  function clientVersionsRefusal(code, key, sentence) {
11050
11174
  return { code, key, message: `${key} ${sentence}` };
@@ -11093,7 +11217,149 @@ export function compareClientVersions(a, b) {
11093
11217
  return 0;
11094
11218
  }
11095
11219
  const SCHEME_LIST = "https:, itms-apps:, itms-beta:, macappstore: or market:";
11096
- const KEY_LIST = "latest, minRecommended, minRequired or updateUrl";
11220
+ const KEY_LIST = "latest, minRecommended, minRequired, updateUrl, enforce or backendOverrides";
11221
+ const OVERRIDE_KEY_LIST = "from, appId or apiUrl";
11222
+ function versionNumberSentence(value) {
11223
+ return (`must be a quoted string such as "1.10": quote it, because an ` +
11224
+ `unquoted ${String(value)} is read as a number and loses its meaning ` +
11225
+ `(1.10 would read as 1.1)`);
11226
+ }
11227
+ function checkOverrideApiUrl(key, where, value) {
11228
+ const refuse = (sentence) => clientVersionsRefusal("override-api-url", key, `${where} ${sentence}`);
11229
+ if (typeof value !== "string")
11230
+ return refuse("must be a string URL");
11231
+ if (value.length > MAX_CLIENT_UPDATE_URL_LENGTH) {
11232
+ return refuse(`is longer than ${MAX_CLIENT_UPDATE_URL_LENGTH} characters`);
11233
+ }
11234
+ let url;
11235
+ try {
11236
+ url = new URL(value);
11237
+ }
11238
+ catch {
11239
+ return refuse(`is not a URL (got "${value}")`);
11240
+ }
11241
+ if (url.username !== "" || url.password !== "") {
11242
+ return refuse("must not carry a user name or password");
11243
+ }
11244
+ if (value.includes("?") || value.includes("#")) {
11245
+ return refuse(`must not carry a query or a fragment (got "${value}")`);
11246
+ }
11247
+ const schemeAllowed = url.protocol === "https:" ||
11248
+ (url.protocol === "http:" && BACKEND_OVERRIDE_LOOPBACK_HOSTS.includes(url.hostname));
11249
+ if (!schemeAllowed) {
11250
+ return refuse(`must use https:, or http: on localhost, 127.0.0.1 or [::1] (got ${url.protocol}//${url.host})`);
11251
+ }
11252
+ if (url.href !== value) {
11253
+ return refuse(`must be written in its canonical form "${url.href}" (got "${value}")`);
11254
+ }
11255
+ const plain = firstNonPlainCharacter(url);
11256
+ if (plain !== null) {
11257
+ return refuse(`must use only plain characters: "${plain}" is not allowed (got "${value}"); a host ` +
11258
+ `takes lower-case letters, digits, - . and _, and a path takes letters, digits, ` +
11259
+ `- . _ ~ ! $ & ' ( ) * + , ; = : @ / and %XX escapes`);
11260
+ }
11261
+ return null;
11262
+ }
11263
+ /** A host of the plain set: lower-case ASCII letters, digits, `-`, `.` and `_`. */
11264
+ const PLAIN_HOST_CHARACTER = /[a-z0-9._-]/;
11265
+ /** A bracketed IPv6 address as the URL parser serializes it. */
11266
+ const PLAIN_IPV6_HOST = /^\[[0-9a-f:]+\]$/;
11267
+ /** A path character RFC 3986 allows raw; `%` is checked as an escape. */
11268
+ const PLAIN_PATH_CHARACTER = /[A-Za-z0-9\-._~!$&'()*+,;=:@/]/;
11269
+ /**
11270
+ * The first character of a canonical override URL's host or path outside the
11271
+ * plain set both clients read the same way, or null. Every such URL is then
11272
+ * read the same way by the WHATWG parser and by Foundation.
11273
+ */
11274
+ function firstNonPlainCharacter(url) {
11275
+ const host = url.hostname;
11276
+ if (!PLAIN_IPV6_HOST.test(host)) {
11277
+ for (const ch of host) {
11278
+ if (!PLAIN_HOST_CHARACTER.test(ch))
11279
+ return ch;
11280
+ }
11281
+ }
11282
+ const path = url.pathname;
11283
+ for (let i = 0; i < path.length; i++) {
11284
+ const ch = path[i];
11285
+ if (ch === "%") {
11286
+ if (/^[0-9A-Fa-f]{2}$/.test(path.slice(i + 1, i + 3))) {
11287
+ i += 2;
11288
+ continue;
11289
+ }
11290
+ return ch;
11291
+ }
11292
+ if (!PLAIN_PATH_CHARACTER.test(ch))
11293
+ return ch;
11294
+ }
11295
+ return null;
11296
+ }
11297
+ function checkBackendOverrides(platform, list, ownAppId) {
11298
+ const listKey = `[clients.${platform}].backendOverrides`;
11299
+ const entryKey = `[[clients.${platform}.backendOverrides]]`;
11300
+ if (!Array.isArray(list)) {
11301
+ return clientVersionsRefusal("overrides-not-a-list", listKey, `must be a list of [[clients.${platform}.backendOverrides]] tables`);
11302
+ }
11303
+ if (list.length === 0) {
11304
+ return clientVersionsRefusal("overrides-empty", listKey, "is empty: add an override or remove the key");
11305
+ }
11306
+ if (list.length > MAX_BACKEND_OVERRIDES) {
11307
+ return clientVersionsRefusal("too-many-overrides", listKey, `has ${list.length} overrides: a platform may declare at most ${MAX_BACKEND_OVERRIDES}`);
11308
+ }
11309
+ for (let i = 0; i < list.length; i++) {
11310
+ const where = `in entry ${i + 1}`;
11311
+ const override = list[i];
11312
+ if (!isPlainMap(override)) {
11313
+ return clientVersionsRefusal("override-not-a-table", entryKey, `${where} must be a table of ${OVERRIDE_KEY_LIST}`);
11314
+ }
11315
+ for (const key of Object.keys(override)) {
11316
+ if (BACKEND_OVERRIDE_KEYS.includes(key))
11317
+ continue;
11318
+ return clientVersionsRefusal("override-unknown-key", `${entryKey}.${key}`, `${where} is not a recognized key: use ${OVERRIDE_KEY_LIST}`);
11319
+ }
11320
+ const fromKey = `${entryKey}.from`;
11321
+ if (!hasOwn(override, "from")) {
11322
+ return clientVersionsRefusal("override-from", fromKey, `${where} is missing: set the first version the override applies to, such as "2.0"`);
11323
+ }
11324
+ const from = override.from;
11325
+ if (typeof from === "number" || typeof from === "bigint") {
11326
+ return clientVersionsRefusal("override-from", fromKey, `${where} ${versionNumberSentence(from)}`);
11327
+ }
11328
+ if (parseClientVersion(from) === null) {
11329
+ return clientVersionsRefusal("override-from", fromKey, `${where} is not a version (got ${JSON.stringify(from)}): use one to three ` +
11330
+ `dot-separated numbers of at most six digits each, such as "2.1.0"`);
11331
+ }
11332
+ const appIdKey = `${entryKey}.appId`;
11333
+ const appId = override.appId;
11334
+ if (typeof appId !== "string" || appId === "") {
11335
+ return clientVersionsRefusal("override-app-id", appIdKey, hasOwn(override, "appId")
11336
+ ? `${where} must be a non-empty string app id`
11337
+ : `${where} is missing: set the app id copies from this version use`);
11338
+ }
11339
+ if (appId.length > MAX_BACKEND_OVERRIDE_APP_ID_LENGTH) {
11340
+ return clientVersionsRefusal("override-app-id", appIdKey, `${where} is longer than ${MAX_BACKEND_OVERRIDE_APP_ID_LENGTH} characters`);
11341
+ }
11342
+ if (ownAppId !== undefined && appId === ownAppId) {
11343
+ return clientVersionsRefusal("override-own-app", appIdKey, `${where} is this app's own id: an override must point at another app`);
11344
+ }
11345
+ if (hasOwn(override, "apiUrl")) {
11346
+ const refused = checkOverrideApiUrl(`${entryKey}.apiUrl`, where, override.apiUrl);
11347
+ if (refused)
11348
+ return refused;
11349
+ }
11350
+ }
11351
+ for (let i = 1; i < list.length; i++) {
11352
+ for (let j = 0; j < i; j++) {
11353
+ const later = list[i].from;
11354
+ const earlier = list[j].from;
11355
+ if (compareClientVersions(later, earlier) === 0) {
11356
+ return clientVersionsRefusal("override-duplicate-from", `${entryKey}.from`, `in entry ${i + 1} (${later}) is the same version as in entry ${j + 1} ` +
11357
+ `(${earlier}): each override on a platform needs a different from`);
11358
+ }
11359
+ }
11360
+ }
11361
+ return null;
11362
+ }
11097
11363
  function checkUpdateUrl(key, value) {
11098
11364
  if (typeof value !== "string") {
11099
11365
  return clientVersionsRefusal("update-url", key, "must be a string URL");
@@ -11113,7 +11379,7 @@ function checkUpdateUrl(key, value) {
11113
11379
  }
11114
11380
  return null;
11115
11381
  }
11116
- function checkEntry(platform, entry) {
11382
+ function checkEntry(platform, entry, options) {
11117
11383
  const table = `[clients.${platform}]`;
11118
11384
  if (!isPlainMap(entry)) {
11119
11385
  return clientVersionsRefusal("entry-not-a-table", table, `must be a table of ${KEY_LIST}`);
@@ -11125,9 +11391,6 @@ function checkEntry(platform, entry) {
11125
11391
  for (const key of keys) {
11126
11392
  if (CLIENT_VERSION_ENTRY_KEYS.includes(key))
11127
11393
  continue;
11128
- if (key === "enforce") {
11129
- return clientVersionsRefusal("enforce-not-accepted", `${table}.enforce`, "is not accepted: this server does not enforce a minimum version");
11130
- }
11131
11394
  return clientVersionsRefusal("unknown-key", `${table}.${key}`, `is not a recognized key: use ${KEY_LIST}`);
11132
11395
  }
11133
11396
  for (const key of CLIENT_VERSION_VALUE_KEYS) {
@@ -11135,9 +11398,7 @@ function checkEntry(platform, entry) {
11135
11398
  continue;
11136
11399
  const value = entry[key];
11137
11400
  if (typeof value === "number" || typeof value === "bigint") {
11138
- return clientVersionsRefusal("version-not-a-string", `${table}.${key}`, `must be a quoted string such as "1.10": quote it, because an ` +
11139
- `unquoted ${String(value)} is read as a number and loses its meaning ` +
11140
- `(1.10 would read as 1.1)`);
11401
+ return clientVersionsRefusal("version-not-a-string", `${table}.${key}`, versionNumberSentence(value));
11141
11402
  }
11142
11403
  if (parseClientVersion(value) === null) {
11143
11404
  return clientVersionsRefusal("version-format", `${table}.${key}`, `is not a version (got ${JSON.stringify(value)}): use one to three ` +
@@ -11149,6 +11410,14 @@ function checkEntry(platform, entry) {
11149
11410
  if (refused)
11150
11411
  return refused;
11151
11412
  }
11413
+ if (hasOwn(entry, "enforce")) {
11414
+ if (typeof entry.enforce !== "boolean") {
11415
+ return clientVersionsRefusal("enforce-not-boolean", `${table}.enforce`, "must be true or false, unquoted");
11416
+ }
11417
+ if (!hasOwn(entry, "minRequired")) {
11418
+ return clientVersionsRefusal("enforce-without-minimum", `${table}.enforce`, "is set but the table sets no minRequired: set minRequired, or remove enforce");
11419
+ }
11420
+ }
11152
11421
  const pairs = [
11153
11422
  ["minRequired", "minRecommended"],
11154
11423
  ["minRequired", "latest"],
@@ -11163,13 +11432,19 @@ function checkEntry(platform, entry) {
11163
11432
  return clientVersionsRefusal("order", `${table}.${lower}`, `(${low}) is above ${upper} (${high})`);
11164
11433
  }
11165
11434
  }
11435
+ if (hasOwn(entry, "backendOverrides")) {
11436
+ const refused = checkBackendOverrides(platform, entry.backendOverrides, options.appId);
11437
+ if (refused)
11438
+ return refused;
11439
+ }
11166
11440
  return null;
11167
11441
  }
11168
11442
  /**
11169
11443
  * The first refusal of a client version policy, or null when it may be
11170
- * stored. `null` and an empty map are legal: they clear the policy.
11444
+ * stored. `null` and an empty map are legal: they clear the policy. Pass the
11445
+ * app's own id as `options.appId` to refuse an override that names it.
11171
11446
  */
11172
- export function checkClientVersions(value) {
11447
+ export function checkClientVersions(value, options = {}) {
11173
11448
  if (value === null || value === undefined)
11174
11449
  return null;
11175
11450
  if (!isPlainMap(value)) {
@@ -11185,10 +11460,23 @@ export function checkClientVersions(value) {
11185
11460
  return clientVersionsRefusal("platform-name", `[clients.${platform}]`, "is not a platform name: use lowercase letters, digits and hyphens, " +
11186
11461
  "starting with a letter, at most 32 characters");
11187
11462
  }
11188
- const refused = checkEntry(platform, value[platform]);
11463
+ const refused = checkEntry(platform, value[platform], options);
11189
11464
  if (refused)
11190
11465
  return refused;
11191
11466
  }
11467
+ const carriesOverrides = platforms.some((platform) => {
11468
+ const entry = value[platform];
11469
+ return isPlainMap(entry) && hasOwn(entry, "backendOverrides");
11470
+ });
11471
+ if (carriesOverrides) {
11472
+ // Every value is a checked string by now, so this is the byte length of
11473
+ // the stored form (key order does not change it).
11474
+ const size = new TextEncoder().encode(JSON.stringify(value)).length;
11475
+ if (size > MAX_CLIENT_VERSIONS_BYTES) {
11476
+ return clientVersionsRefusal("policy-too-large", "[clients]", `is ${size} bytes as stored: a policy with backend overrides may be at ` +
11477
+ `most ${MAX_CLIENT_VERSIONS_BYTES} bytes; remove overrides or shorten their apiUrl`);
11478
+ }
11479
+ }
11192
11480
  return null;
11193
11481
  }
11194
11482
  /**
@@ -11229,6 +11517,47 @@ export function loweredClientMinimums(stored, next) {
11229
11517
  }
11230
11518
  return lowered;
11231
11519
  }
11520
+ /**
11521
+ * Every backend override in `next` whose `from` is at or below its platform's
11522
+ * legal `latest` — what `config push` asks the developer to confirm, because
11523
+ * copies already released would switch backend. Platforms in name order,
11524
+ * overrides in file order; anything unreadable is skipped.
11525
+ */
11526
+ export function releasedBackendOverrides(next) {
11527
+ if (!isPlainMap(next))
11528
+ return [];
11529
+ const released = [];
11530
+ for (const platform of Object.keys(next).sort()) {
11531
+ const entry = next[platform];
11532
+ if (!isPlainMap(entry))
11533
+ continue;
11534
+ const latest = entry.latest;
11535
+ if (parseClientVersion(latest) === null)
11536
+ continue;
11537
+ const list = entry.backendOverrides;
11538
+ if (!Array.isArray(list))
11539
+ continue;
11540
+ for (const override of list) {
11541
+ if (!isPlainMap(override))
11542
+ continue;
11543
+ const { from, appId, apiUrl } = override;
11544
+ if (parseClientVersion(from) === null || typeof appId !== "string")
11545
+ continue;
11546
+ if (compareClientVersions(from, latest) > 0)
11547
+ continue;
11548
+ const item = {
11549
+ platform,
11550
+ from: from,
11551
+ latest: latest,
11552
+ appId,
11553
+ };
11554
+ if (typeof apiUrl === "string")
11555
+ item.apiUrl = apiUrl;
11556
+ released.push(item);
11557
+ }
11558
+ }
11559
+ return released;
11560
+ }
11232
11561
  // ── src/config-surface/app-settings.ts ───────────────────────────────────
11233
11562
  /**
11234
11563
  * The `app-settings` configuration object's definition (issue #2644, phase 3).